@llblab/pi-kit 0.36.1 → 0.36.2

package/node_modules/@llblab/pi-telegram/docs/multi-instance-bus.md

@@ -222,10 +222,10 @@ Production retirement requires a durable profile-scoped reader/writer ledger own
 - The unreachable legacy `directories` projector remains only for decoding old internal snapshots; effective configuration falls back to Letters. The `directory-snake` and `directory-title` modes derive suffix visibility exclusively from the leader's current authenticated live-owner snapshot: one live binding for a normalized exact cwd has no suffix; two or more live bindings for that cwd all expose their globally assigned slots; dormant retained bindings never affect the count. `showSlotSuffix` remains readable for legacy presentation but is ignored by both new projectors and is never written merely because live concurrency changed. The leader captures exact profile, epoch, binding target, and follower registration generation before projection; a provisioning candidate counts only after its authenticated exact owner is admitted to the same serialized Workspace mutation, while an owner losing authority is excluded before reconciliation. Registration/provision completion, authenticated disconnect or confirmed-dead prune, target replacement, and promotion schedule one serialized reconciliation of every affected live same-cwd binding. A failed or partial Telegram rename retains acknowledged per-binding progress and retries only under a fresh live snapshot; dormant tabs are not renamed until they regain authenticated ownership. Leader startup treats its authenticated follower roster as unsettled for one follower-staleness window: automatic display reconciliations requested by election or incremental re-registration are deferred and coalesced until that boundary. A same-cwd follower returning within the window therefore preserves the already acknowledged suffix without an `unsuffixed → suffixed` Telegram rename; if it stays absent, the settled reconcile removes the suffix once. Explicit mode changes remain immediate, and leader stop/restart invalidates the pending timer. Equal basenames from different paths still require deterministic parent-path qualification independently from same-cwd suffixing. Preserve the existing `threadName` as generated/recovery identity while automatic modes are selected. New manual names live only in `manualThreadName`; do not guess manual provenance from a legacy name or palette membership. Telegram `/name Name` changes the manual override and displayed title only for its exact originating target. Leader and follower requests carry that target through final generation/binding checks, so replacement cannot redirect a stale dialog mutation. Reset uses the same negotiated `workspace-thread-rename-v1` capability and exact follower generation; the leader computes the current automatic projection from the latest live snapshot, edits the exact target, clears only `manualThreadName`, and persists before acknowledging. Follower metadata refresh preserves an acknowledged display title only while target and registration generation stay unchanged. Named-profile setup preserves the latest saved automatic preference even if another instance changes it while the token form is open.
 - Fresh provisioning projects the candidate together with retained bindings and sends the active mode's title in `createForumTopic`. The exact targeted provision retains creation-title evidence until the Workspace commit publishes the binding and consumes that evidence together. Recovery preserves it even when a starting record already exists; an untargeted or unknown creation never authorizes a title commit. Proven deletion removes exact-target pending creation evidence, including when no current record was committed. Older contradictory pending/deleted snapshots settle that evidence durably before replacement; closed targets and pending cleanup block recovery until reconciliation, rather than becoming active again. The same exact-target check protects follower reconnect/carried-target shortcuts and the final Workspace commit, before creation evidence can be consumed. A matching carried pending target resumes through the provisioner that owns its reserved slot and acknowledged title instead of allocating that slot again. The shared provision-commit helper first commits the claim, then applies the acknowledged title with exact-binding comparison, preserving generic stale-title rejection on target replacement. Switching display mode changes projection only: preserve Thread ID, binding identity, slot, queue ownership, and routing. `displayTitle` records a successful Telegram edit independently of `threadName`, survives same-target registration updates, and is cleared on target replacement. The title reconciler captures profile, mode, leader epoch, and exact live-binding authority before each edit, rechecks after ACK and persistence, and skips dormant bindings. Failed persistence retains acknowledged dirty metadata for a later persist without repeating that API edit; a late or unknown ACK never commits a title to a replacement binding. Keep the stable palette/manual name separate from the current display title so switching back does not generate a different name. The leader owns Telegram title edits and acknowledged follower/TUI convergence, with generation/profile fencing and truthful partial-failure recovery. Successful registration ACKs optionally carry the acknowledged `displayTitle` with the exact target and registration generation, making it available before the initial status refresh. Heartbeats carry later title changes; stale generations cannot update display state. Connected notices use acknowledged titles while runtime `threadName` remains the stable restoration identity. Live bot chooser/notice labels, prompt attribution, and cross-instance agent-target name selection use the same acknowledged projection, but candidate liveness and the captured numeric `{chatId, threadId}` remain authoritative. Ambiguous projected names fail closed. Older peers can ignore the optional field, and no separate polling connection or follower snapshot-read loop is needed; do not expose a setting control that merely stores a preference without updating its promised surfaces.
 - Reopening a retained inactive binding restores its slot and name without taking leadership. Explicit connection from the same directory may allocate a second binding. Startup restore remains restore-only: it must not evict another Workspace or allocate a fresh binding merely because all remembered bindings are owned. Explicit connection already skips a live peer's migrated binding instead of attempting to adopt it; that admission rule is independent of the display redesign.
-- Prefer free letters in deterministic order. Only under full slot exhaustion may retirement choose the eligible binding with the oldest proven inactivity start, not necessarily slot `a` after `z`. Time alone never retires a binding. If every slot is protected or its ownership is unverifiable, reject new allocation with a truthful capacity explanation; never evict a live owner or silently expand into `aa`.
+- Prefer free letters in deterministic order. Only under full slot exhaustion may retirement choose the eligible binding with the oldest proven inactivity start, not necessarily slot `a` after `z`. Time alone never retires a binding. If every slot is protected or its ownership is unverifiable, retirement is impossible and allocation falls back to the metadata-only letter reuse described under Demand-Driven Slot Rotation instead of refusing the connection; never delete a live owner's Thread or silently expand into `aa`.
 - Inactivity begins at a verified transition to no live owner; an idle but connected process is active. Exact confirmed Thread deletion also proves that the binding has no active Telegram target: the common Thread store records first inactivity with invalidation, even if an earlier stale observation already removed the live record. Fenced invalidation publishes this metadata only at its durable commit; closure or an unknown API outcome alone supplies no inactivity. With automatic cleanup disabled, confirmed-dead follower pruning instead acquires profile admission and commits non-destructive owner detachment. It requires one exact owner record and one matching Workspace binding with the same letter; final publication rechecks the registered positive PID's absence, prune generation, leader epoch, profile and replacement registrations. It retains the tab, Workspace identity, slot and journals without claiming that Telegram deleted the Thread. For graceful leader quit with cleanup disabled, the [lifecycle boundary](./architecture.md#runtime-ownership) supplies completed quiescence and exact session/epoch/profile authority for the same atomic detachment; reload/new/resume/fork never enter it. A failed pre-commit publication retains the owner record; a lost post-rename acknowledgement leaves the committed fact intact. No-op snapshot equality cannot bypass the fenced transition into memory. Missing/ambiguous legacy identity remains protected. Live-owner, accepted-work and delivery protection still apply independently before retirement. Do not derive inactivity from last user message, heartbeat silence alone, snapshot-write time, file age, or any elapsed-time threshold. Legacy records without sufficient evidence have no `inactiveSinceMs` and remain ineligible rather than inheriting an invented old timestamp. Malformed inactivity values are ignored without dropping the binding. Repeated inactive observations retain the first timestamp for pressure ordering; stale same-target upserts cannot postpone it, while target replacement or successful active provisioning clears it.
 - Eligibility excludes live or unverifiable owners, exact transient claims, accepted pending/active work, unresolved delivery authority, and pending provisioning, handoff, or cleanup operations. The store can capture one candidate snapshot from bindings, live records, process-local exact claims, reservations, and persisted provision/cleanup intents, but requires the caller to supply separate tri-state evidence for external live ownership, accepted work, and delivery authority. Only three explicit `clear` results plus valid continuous inactivity produce `eligible`; any protected or unknown dimension fails closed. Before future deletion, `workspace-retirement` selects the oldest eligible pressure victim only after all slots are occupied or reserved. It captures the profile and leader epoch, rechecks protection, then persists one durable Workspace retirement intent containing the complete expected binding, pressure reason, leader epoch, and request time. The intent itself protects that binding from competing selection; only the exact captured intent may be excluded during a fenced recheck. Duplicate intent ids, bindings, targets, or letters fail closed. Each new Workspace binding durably accumulates the registration/profile keys used to route its historical follower journals and marks that set complete. An existing legacy binding may learn current keys but cannot claim its unknown historical set is complete without separate discovery proof. Accepted-work policy treats an exact local queued/active target or any unsettled entry in a binding-specific follower journal as protected. Shared leader-journal entries protect only a decoded exact target; undecodable relevant entries, unreadable sources, and incomplete source enumeration remain unknown. The read-only evidence capture resolves the shared leader journal and every recorded follower key; missing resolvers, read errors, or an incomplete legacy key set make coverage unknown. A complete readable capture may prune a known empty follower-journal key only when a separate process/writer check is explicitly clear and the exact binding, profile, and leader epoch remain current; nonempty, unreadable, writable, or unknown keys remain. For incomplete legacy metadata, `journal` can discover canonical profile-exact follower snapshot and segment roots. Matching paths with unexpected/unreadable shape make discovery incomplete; successfully read discovered journals are target-scoped evidence because their one-way filename hash cannot recover the historical routing key. Legacy completeness remains unset, so later retirement repeats discovery rather than forgetting that historical domain. Live composition includes decoded process-birth proof, registry liveness, queue/journal state, and delivery-authority discovery.
-- Reclamation deletes the exact inactive Telegram Thread and therefore removes its history; this is distinct from dropping a local label. The leader owns a durable, exact-binding-and-epoch-fenced retirement intent. The store validates and persists this contract, and preparation resumes an exact current-epoch intent after persistence failure or reload. The isolated executor requires both the caller-owned exclusive gate and durable admission ledger. It acquires or exactly adopts the matching fence, rechecks protection after admissions close, persists `deletion-issued`, and invokes an executor-only `deleteForumTopic` port with the sole non-retried permit. Unknown results keep the binding, intent, slot, and issued fence; retries and successors cannot issue again and require exact already-absence proof. Exact parsed Telegram rejection instead follows the cancellation protocol below, retaining the binding and letter. Success or confirmed absence advances to `commit-ready`, then a store-owned commit hides the free slot while persistence is in flight, restores in-memory authority on known failure, and removes binding+intent before exact fence completion. One failure-resilient Workspace operation runtime owns the shared gate for topic lifecycle, reroute restore/reclaim, leader/follower provisioning, delayed post-provision reconciliation, disconnect and confirmed-dead cleanup, rename, and display reconciliation; registration cannot enter the live registry until its gated provisioning completes. Timer-owned mutation never inherits expired registration authority: it reacquires profile admission before cleanup and remains blocked without store/API effects behind either retained fence phase. The executor consumes that runtime's exposed gate rather than nesting another lock. A successor leader cannot execute the old epoch directly. It may durably adopt exactly one intent into its current epoch only when the profile, complete binding snapshot, and fresh protection recheck still match; known persistence failure restores the old intent and request time. Leader composition now exposes external protection from exact live registry targets, active/queued local targets, shared and historical follower journals, and profile-exact discovery for incomplete legacy history. An accepted item without an exact target for the candidate chat remains unknown. Exact JSON and multipart Bot API operations are counted at the shared direct-client boundary through final settlement; a message-scoped edit/delete without thread identity conservatively protects all bindings in its chat. Historical follower owner keys are decoded before process-birth liveness checks. Exact durable intents block matching claims, activation, title/journal commits, and binding upserts, preventing normal mutation from making their snapshots stale. Closed-but-existing topics do not count as confirmed absence. The former process-local TOCTOU is closed in the isolated ledger/executor and production journal/API/mutation/allocation composition, including delayed post-provision cleanup. Fresh leader/follower allocation now retries once after a confirmed pressure retirement. Allocation requests serialize before taking ordinary leases; failure releases those leases before retirement enters the shared mutation gate and acquires its destructive fence. Restore-only follower startup never enters this path. Protected or unverifiable capacity still fails closed. Reuse changes only the letter assignment: routing remains exact numeric target authority, so traffic for the retired target cannot reach the replacement. Recheck eligibility before Telegram mutation and serialize against re-registration. Release the letter only after confirmed deletion or exact already-absent evidence and a successful durable retirement commit. The current confirmed cleanup path records inactivity only after its exact deletion/already-absent result; an unconfirmed API outcome records no inactivity. Unknown API outcomes, failed persistence, owner replacement, and interrupted cleanup retain the reservation and recovery evidence, preventing reassignment or deletion of a replacement target.
+- Reclamation deletes the exact inactive Telegram Thread and therefore removes its history; this is distinct from dropping a local label. The leader owns a durable, exact-binding-and-epoch-fenced retirement intent. The store validates and persists this contract, and preparation resumes an exact current-epoch intent after persistence failure or reload. The isolated executor requires both the caller-owned exclusive gate and durable admission ledger. It acquires or exactly adopts the matching fence, rechecks protection after admissions close, persists `deletion-issued`, and invokes an executor-only `deleteForumTopic` port with the sole non-retried permit. Unknown results keep the binding, intent, slot, and issued fence; retries and successors cannot issue again and require exact already-absence proof. Exact parsed Telegram rejection instead follows the cancellation protocol below, retaining the binding and letter. Success or confirmed absence advances to `commit-ready`, then a store-owned commit hides the free slot while persistence is in flight, restores in-memory authority on known failure, and removes binding+intent before exact fence completion. One failure-resilient Workspace operation runtime owns the shared gate for topic lifecycle, reroute restore/reclaim, leader/follower provisioning, delayed post-provision reconciliation, disconnect and confirmed-dead cleanup, rename, and display reconciliation; registration cannot enter the live registry until its gated provisioning completes. Timer-owned mutation never inherits expired registration authority: it reacquires profile admission before cleanup and remains blocked without store/API effects behind either retained fence phase. The executor consumes that runtime's exposed gate rather than nesting another lock. A successor leader cannot execute the old epoch directly. It may durably adopt exactly one intent into its current epoch only when the profile, complete binding snapshot, and fresh protection recheck still match; known persistence failure restores the old intent and request time. Leader composition now exposes external protection from exact live registry targets, active/queued local targets, shared and historical follower journals, and profile-exact discovery for incomplete legacy history. An accepted item without an exact target for the candidate chat remains unknown. Exact JSON and multipart Bot API operations are counted at the shared direct-client boundary through final settlement; a message-scoped edit/delete without thread identity conservatively protects all bindings in its chat. Historical follower owner keys are decoded before process-birth liveness checks. Exact durable intents block matching claims, activation, title/journal commits, and binding upserts, preventing normal mutation from making their snapshots stale. Closed-but-existing topics do not count as confirmed absence. The former process-local TOCTOU is closed in the isolated ledger/executor and production journal/API/mutation/allocation composition, including delayed post-provision cleanup. Fresh leader/follower allocation now retries once after a confirmed pressure retirement. Allocation requests serialize before taking ordinary leases; failure releases those leases before retirement enters the shared mutation gate and acquires its destructive fence. Restore-only follower startup never enters this path. Protected or unverifiable capacity deletes nothing and falls back to metadata-only letter reuse. Reuse changes only the letter assignment: routing remains exact numeric target authority, so traffic for the retired target cannot reach the replacement. Recheck eligibility before Telegram mutation and serialize against re-registration. Release the letter only after confirmed deletion or exact already-absent evidence and a successful durable retirement commit. The current confirmed cleanup path records inactivity only after its exact deletion/already-absent result; an unconfirmed API outcome records no inactivity. Unknown API outcomes, failed persistence, owner replacement, and interrupted cleanup retain the reservation and recovery evidence, preventing reassignment or deletion of a replacement target.
 - A retired binding no longer promises its former name/letter on reopen; the Workspace may be provisioned anew. Retained message ownership and journal evidence must never route old work through a recycled letter: full binding generation and target remain mandatory independently of display labels.
 - Implement and validate using isolated stores and mocked Telegram APIs. Do not delete live Threads, migrate live journals/locks manually, publish, or restart operator instances as part of local preparation. Operator smoke on disposable Threads is a separate gate.
 
@@ -235,6 +235,12 @@ A fresh leader allocation or authenticated explicit follower registration first
 
 The executor validates exact bot/profile, leader epoch, fence owner, binding, target, slot, operation and issuance time immediately before `deleteForumTopic`. This executor-only transport uses the existing client without ordinary target admission, which its own fence intentionally blocks; both API retries and network-family fallback are disabled. Only `true` or a definite HTTP 400 absent-Thread response confirms deletion. A parsed Telegram `ok: false` response with matching HTTP/error codes in `400 | 401 | 403 | 404 | 429`, the exact `deleteForumTopic` method and target, and no confirmed-absence evidence instead proves rejection. The executor durably records `deletion-rejected`, withdraws only the matching retirement intent, persists that withdrawal while retaining the binding, then releases the exact fence. Reconstruction finishes cancellation even after intent removal or lost publication acknowledgements; it does not require deletion eligibility or issue another delete. Every fresh attempt uses a new operation identity, even within the same clock tick. A runtime that does not understand the retained rejection phase cannot recover it; use a supporting build, not manual ledger edits. Transport failures, HTTP 5xx, malformed/mismatched responses and forged status fields remain unknown: they retain the binding and fence without reissuing or assigning the letter. No background timer or elapsed-age threshold performs rotation.
 
+#### Metadata-Only Letter Reuse
+
+When pressure retirement finds no eligible binding (every letter protected or unverifiable), the same wrapper reassigns the least recently used letter rather than refusing the connection. Under the shared gate it reloads the store and, if still no letter is free, removes the `slot` from one binding and from its current Thread record, persists once, and retries the claim, which then takes the freed letter. The victim is the binding with the oldest last use: detached bindings by their first-inactivity time, live owners counted as most recent and chosen only when nothing detached remains, ties by letter. The metadata reassignment keeps the Thread, binding, journals, accepted work and generated name; it performs no deletion. Before retrying allocation, the leader awaits one display-only reconciliation of the displaced binding under fresh profile admission. A slotless binding displays its retained generated name in every automatic mode, or keeps its manual override. Routing remains the exact numeric target plus binding key, so old work can never reach the replacement through the recycled letter.
+
+A binding or letter held by a claim, reservation, pending provision, cleanup, retirement intent or an external admission reservation is skipped, as is a letter that a different current Thread record also holds. An unreadable external reservation set, lost leader authority or refused publication restores the previous assignment and reports capacity unavailable. The displaced binding is slotless like a legacy binding: it holds no letter, is not a capacity-retirement candidate, and regains one only through a later allocation-authorized connection. Displaced bindings and their Threads therefore accumulate; nothing deletes them automatically. On the leader, Settings → Thread cleanup → Review inactive tabs can prepare exact inactive slotless bindings with complete clear protection. Back leaves them untouched; the separate Clean action confirms deletion of the reviewed Telegram tabs and their messages. The shared gate reloads and revalidates each exact candidate before and under its manual cleanup fence; changed/protected candidates are skipped, and an unknown issued deletion never repeats. The manual-cleanup path retains explicit `slot: null` through its work-set, fence, permit and exact binding commit; it never uses the letter now held by another binding. Older readers reject these new null-bearing records rather than inferring cleanup permission. Pressure retirement still requires a real letter. Restore-only startup and background heartbeat recovery never reuse a letter, which prevents eviction churn. A rejected or unknown title edit retains the previous acknowledged title and records a diagnostic; it cannot undo or repeat the published reassignment, block the fresh connection, or authorize deletion. Ordinary display reconciliation also includes slotless bindings without live owners, so startup or a later display trigger can repair the title after failure or a crash between reassignment and editing. Title edits retain exact binding/profile/mode/epoch fences and require a positive acknowledgement; this display authority never creates live routing ownership.
+
 Protection reads use the binding's strict non-repairing journal inspector. Corruption, unsupported platforms/schemas, incomplete historical coverage and unresolved named-profile paths remain unknown, never empty-work evidence. Legacy inactivity timestamps are not fabricated. If full pressure is blocked only by queued work, rotation may inspect candidates oldest-first and invoke the journal's existing exact dead-owner recovery—never raw file or queue clearing. The current binding, leader/profile authority, local queue, live owner and delivery authority must all remain clear; source enumeration must be complete; each relevant entry must form a whole unoffered receipt group for the same target and owner; and every grouped PID plus process birth must be freshly proven dead before the first mutation. The journal rechecks the exact receipt, owner/acquisition, source IDs, handoff absence and liveness transactionally. Any live/unverifiable owner, partial/mixed group, mutation refusal, replacement or unknown evidence stops that candidate. A committed prefix may remain discarded after interruption, but it grants no deletion authority: rotation performs a fresh complete protection capture and ordinary retirement eligibility check before preparing the destructive fence. Unrelated journal work is untouched, no payload is replayed, and restore-only startup never enters this path. Deletion removes **the Telegram Thread and all its messages** as documented by [`deleteForumTopic`](../.agents/skills/telegram-bot/api.md#deleteforumtopic); retirement removes that exact local Workspace binding, not Pi session files, project files, State Flow memory, or durable update journals. Reopening a retired session may create a fresh Thread rather than restoring its deleted history.
 
 ### Ambiguous Retirement Recovery Evidence
@@ -667,7 +673,7 @@ This inspection authorizes no reload/restart, live-state mutation, fault injecti
 ## Security Boundaries
 
 - Messages, edits, callbacks, and reactions check user authorization, not only chat/thread membership.
-- Followers authenticate to the local leader IPC with a leader-minted capability secret carried in the active lock entry; registration, heartbeat, forwarded updates, and follower API calls without the secret are rejected. Registration rejections are surfaced verbatim in the follower `/telegram-connect` result, registration waits through leader-side Telegram thread provisioning, and successful registrations send an immediate heartbeat before the interval ticker so the leader does not prune a live follower before its first scheduled heartbeat. The local bus socket is also created under a private `0700` directory with `0600` socket permissions as a first local-only boundary.
+- Followers authenticate to the local leader IPC with a leader-minted capability secret carried in the active lock entry; registration, heartbeat, forwarded updates, and follower API calls without the secret are rejected. Registration rejections are surfaced verbatim in the follower `/telegram-connect` result, registration waits through leader-side Telegram thread provisioning, and successful registrations send an immediate heartbeat before the interval ticker so the leader does not prune a live follower before its first scheduled heartbeat. The local bus socket is also created under a private `0700` directory with `0600` socket permissions as a first local-only boundary. A reply refused because it targets a Thread other than the follower's own surfaces as the typed `TelegramApiFollowerNotAllowedError` carrying only the requested target. A journaled recipient input whose Thread was since re-created re-runs exactly once against the follower's current Thread (reply anchor cleared, diagnostic `recipient-target-recovery`); a second refusal or any other failure keeps the ordinary durable `retry-wait`.
 - Follower Bot API proxying is allowlisted and target-scoped where applicable. Ordinary sends remain confined to the follower's assigned thread; trusted runtime-marked `telegram_message` cross-target sends may address only a different thread inside the same paired chat, and the leader strips the internal marker before calling Telegram. This preserves requested inter-thread delivery without granting arbitrary bot or cross-chat control.
 - Button and section callbacks verify authorized `from.id` and owning target/instance.
 - Generated artifacts stay scoped to the owning thread after leader failover.

package/node_modules/@llblab/pi-telegram/docs/public-api.md

@@ -125,6 +125,8 @@ The file is global across Pi instances and contains configuration only. The per-
 
 Threaded Mode Settings exposes **Thread display** as Letters (default), Names, `directory-snake`, or `directory-title`; retained `directories` is unsupported, resolves to Letters, and is never rewritten automatically. `threads.displayMode` is shared by every profile; absent and invalid values resolve to `letters`. The retired `profiles.<name>.threadDisplayMode` key is ignored, not migrated. Another profile's already-running leader applies a shared change at its next startup or display reconciliation. Settings previews the current binding set through the same projector used for fresh titles and reconciliation. A manual `/name` override appears as `custom`; choosing any automatic Thread display option clears that override for the current Thread and immediately reapplies the selected projection. Names projects the generated dictionary name for the slot; the two directory modes tokenize Unicode path segments deterministically and render snake case or humanized title case, with `_a` or ` A` slot suffixes when required. The leader serializes preference persistence and title reconciliation, while a follower sends an authenticated `follower.setThreadDisplayMode` request gated by `thread-display-mode-v1`, the additional `directory-display-format-v1` capability for either new directory mode, and its exact registration generation. Config writes check the originating authority inside the config transaction; mode changes preserve target IDs, slots, generated recovery names, manual overrides, and queue ownership. `/name` mutations carry their originating target through final binding validation. The caller confirms only after application succeeds. A partial failure may leave the preference saved and some titles updated; Settings reports that state and permits retry. Acknowledged follower titles arrive through heartbeat rather than a new read loop.
 
+Manual cleanup is independent of the graceful-quit toggle. On the leader instance, Settings → Thread cleanup → Review inactive tabs prepares only exact inactive bindings with complete clear protection, including bindings without a letter. Review and Back delete nothing. The separate Clean action confirms deletion of those eligible Telegram tabs and all their messages, not Pi session history or project files. Confirmation reloads and revalidates the exact review under a one-shot manual fence. Changed or protected bindings are skipped; an issued unknown deletion is never retried automatically, and unfinished local commit retains recovery protection. Follower instances do not receive a remote cleanup grant from these controls.
+
 Hidden/default semantics are represented by absence:
 
 - `threads.automaticCleanup` defaults to `true`; graceful Pi quit deletes the instance's bound Threaded Mode tab without prompting but preserves the owner slot as independent restart intent. Set it to `false`, or use `🧹 Thread cleanup` in Telegram Settings, to preserve the tab too. A confirmed `/telegram-disconnect`, unlike quit, clears restart ownership. Settings views and cleanup reload shared config before evaluating this switch, so another live Pi instance's update takes effect without restarting. Confirmed leader/follower teardown persists an exact target/runtime-generation cleanup intent before Telegram deletion; an interrupted attempt remains retryable by the current or successor leader under current authority and clears only after confirmed deletion. A same-profile replacement leader first adopts any still-active binding and cancels its superseded cleanup, so startup never deletes and recreates a reusable thread. If a follower's graceful envelope is missed, the leader may create the same fenced cleanup only after its heartbeat is stale, the OS confirms the exact registered PID no longer exists, cleanup remains enabled, and no replacement registration can overtake deletion. Heartbeat loss alone, live/unknown process liveness, IPC failure, and auth failure remain non-destructive. Invalid-config recovery makes the setting unresolved and therefore skips destructive cleanup. Manual `/telegram-disconnect` keeps its confirmation and teardown behavior regardless of this setting.

package/node_modules/@llblab/pi-telegram/docs/ui-style.md

@@ -240,7 +240,7 @@ A message (or All-tab command) held in an unbound or temporary tab gets one rout
 - Cancel appears only at the root.
 - An input sent from `All` moves into the routing tab opened for it: the tab starts with a silent forward of the input (Telegram shows it as forwarded from the operator), the chooser replies to it, and the original leaves `All` once the copy is confirmed. A restored Thread therefore keeps the prompt it answers.
 - A chooser is one-shot: every final outcome deletes its message. A confirmed Cancel, a Forward or Reroute, and a successful Restore remove the menu; Restore keeps the tab as the Pi's Thread, while a temporary tab with no remaining unresolved input is removed. If Telegram refuses the delete, Cancel and Restore leave an inert bold notice (`⛔️ Routing cancelled.` / `✅ Message routed.`) with an empty keyboard, and Forward asks for one more tap to clear the menu.
-- Old or expired controls answer `⌛ Routing choice expired.`
+- Old or expired controls answer `⌛ Routing choice expired.` A newly committed expiry instead displays the fully bold `⌛ Routing expired; input was not delivered.` only for proven unissued work. Selected/issued or uncertain work displays fully bold `⌛ Routing expired; delivery is unconfirmed.` followed by `Previously accepted work may continue.` If the chooser is gone, or its temporary tab will be removed, send that notice without an old reply anchor to the leader's current owned Thread in the same private chat; never fall back to All. No owned Thread means diagnostics only.
 - 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`.
 

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

@@ -453,7 +453,30 @@ export function createTelegramGenerativeAppBoundButtonActionInvoker<
       | GenerativeApps.GenerativeAppLiveSurface<GenerativeApps.TelegramBindLiveHandle>
       | undefined;
     try {
-      boundAction = GenerativeApps.parseGenerativeAppBoundAction(action.prompt);
+      // Only buttons emitted by a Generative App carry a binding. An unbound button is ordinary model text
+      // (`std::map`, `a::b(c)`): malformed or uninstalled-app prompts fall through to the normal prompt plane.
+      if (!action.binding) {
+        try {
+          boundAction = GenerativeApps.parseGenerativeAppBoundAction(
+            action.prompt,
+          );
+        } catch {
+          return false;
+        }
+        if (
+          boundAction &&
+          !(await GenerativeApps.isGenerativeAppInstalled(
+            deps.agentDir,
+            boundAction.app,
+          ))
+        ) {
+          boundAction = undefined;
+        }
+      } else {
+        boundAction = GenerativeApps.parseGenerativeAppBoundAction(
+          action.prompt,
+        );
+      }
       if (!boundAction) return false;
       deps.assertExecutionCurrent(query);
       const chatId = query.message?.chat?.id;

package/node_modules/@llblab/pi-telegram/lib/bus-follower.ts

@@ -70,6 +70,7 @@ import {
   type TelegramBusSelectedMenuTextEffect,
   type TelegramBusSocketPathSource,
   type TelegramBusWorkspaceRestoreObservation,
+  TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE,
 } from "./bus.ts";
 import type {
   TelegramConfigStore,
@@ -96,6 +97,7 @@ import {
   assertTelegramApiCallAuthority,
   TelegramApiAuthorityError,
   TelegramApiCommitUnknownError,
+  TelegramApiFollowerNotAllowedError,
   TelegramApiStaleTargetError,
   type TelegramApiCallOptions,
 } from "./telegram-api.ts";
@@ -1986,6 +1988,20 @@ export function createTelegramBusFollowerApiCaller(
         new Error(message ?? "Telegram bus API call result is ambiguous."),
       );
     }
+    if (message === TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE) {
+      const body =
+        (method === "call" || method === "callMultipart") && isRecord(args[1])
+          ? args[1]
+          : undefined;
+      const chatId = Number(body?.chat_id);
+      const threadId = Number(body?.message_thread_id);
+      throw new TelegramApiFollowerNotAllowedError(
+        message,
+        Number.isSafeInteger(chatId) && Number.isSafeInteger(threadId)
+          ? { chatId, threadId }
+          : undefined,
+      );
+    }
     throw new Error(message ?? "Telegram bus API call failed.");
   };
   return async (method, args, localOptions) => {

package/node_modules/@llblab/pi-telegram/lib/bus-leader.ts

@@ -40,6 +40,7 @@ import {
   type TelegramBusProtocolIdentity,
   type TelegramBusSelectedMenuDelivery,
   type TelegramBusSocketPathSource,
+  TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE,
 } from "./bus.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
 import type { TelegramAttachmentSource } from "./media.ts";
@@ -464,6 +465,9 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
           store: deps.topicTargetStore,
           getLeaderEpoch: deps.getCurrentLeaderEpoch,
           getExternalProtection: deps.captureWorkspaceExternalProtection,
+          onSlotReused: (bindingKey, isCurrent) => display
+            ? reconcileThreadDisplay(bindingKey, isCurrent).then(() => undefined)
+            : Promise.resolve(),
           recordEvent(message, details) {
             deps.recordRuntimeEvent("bus", message, details);
           },
@@ -513,6 +517,9 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
         getLeaderEpoch: () => deps.getCurrentLeaderEpoch?.(),
         captureLiveBindingKeys,
         captureBindingAuthority(binding) {
+          // Slotless retained bindings need display repair even without a live owner.
+          // The reconciler still fences the exact binding snapshot, profile, mode and epoch.
+          if (binding.slot === undefined) return () => true;
           const matches = (target: TelegramTarget | undefined) =>
             target?.chatId === binding.target.chatId &&
             target?.threadId === binding.target.threadId;
@@ -544,19 +551,22 @@ export function createTelegramBusLeaderRuntimeAssembly<TContext>(
         callApi: deps.callApi,
       })
     : undefined;
-  const reconcileThreadDisplayOperation = async () => {
-    const result = await display!.reconcile();
+  const reconcileThreadDisplayOperation = async (bindingKey?: string) => {
+    const result = await display!.reconcile(bindingKey);
     deps.onThreadDisplayChanged?.();
     return result;
   };
-  const reconcileThreadDisplay = () =>
+  const reconcileThreadDisplay = (bindingKey?: string, isCurrent: () => boolean = () => true) =>
     runWorkspaceOperation(
       {
         operationId: createTelegramWorkspaceAdmissionOperationId(),
         operationKind: "workspace.reconcile-display",
         scopes: [{ kind: "profile" }],
       },
-      reconcileThreadDisplayOperation,
+      () => {
+        if (!isCurrent()) throw new Error("Telegram Thread display update lost allocation authority.");
+        return reconcileThreadDisplayOperation(bindingKey);
+      },
     );
   let startupDisplayTimer: ReturnType<typeof setTimeout> | undefined;
   let startupDisplayGeneration = 0;
@@ -4181,7 +4191,7 @@ async function handleFollowerApiCall(
   ) {
     return rejectTelegramBusRequest(
       envelope.requestId,
-      "Telegram bus API call is not allowed for this follower.",
+      TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE,
     );
   }
   if (!deps.callApi) {

package/node_modules/@llblab/pi-telegram/lib/bus.ts

@@ -2873,6 +2873,9 @@ export function isTelegramBusEnvelopeAuthorized(
 }
 
 /** Negative acknowledgement carrying only a diagnostic message. */
+export const TELEGRAM_BUS_FOLLOWER_API_NOT_ALLOWED_MESSAGE =
+  "Telegram bus API call is not allowed for this follower.";
+
 export function rejectTelegramBusRequest(
   requestId: string,
   message: string,

package/node_modules/@llblab/pi-telegram/lib/extension.ts

@@ -590,18 +590,32 @@ export default function (pi: Pi.ExtensionAPI) {
         );
       },
     });
-  const inactiveThreadCleanupReviewRuntime =
-    ThreadCleanupManager.createTelegramInactiveThreadCleanupReviewRuntime({
-      getProfileName() {
-        return configStore.getActiveProfileName() ?? "default";
+  const inactiveThreadCleanupRuntime =
+    ThreadCleanupManager.createTelegramInactiveThreadCleanupRuntime({
+      store: threadStore,
+      captureAuthority() {
+        const ledger = workspaceAdmissionRuntime.resolve();
+        const leaderEpoch = getCurrentLeaderEpoch();
+        const operator = configStore.getAllowedUserId();
+        if (!ledger || leaderEpoch === undefined || operator === undefined) return undefined;
+        const stamp = telegramTransportStampRuntime.getStamp();
+        const generation = telegramSessionContextStore.getGeneration();
+        return {
+          profileName: configStore.getActiveProfileName() ?? "default",
+          leaderEpoch, ledger,
+          isCurrent() {
+            return getCurrentLeaderEpoch() === leaderEpoch &&
+              telegramTransportStampRuntime.isActive(stamp) &&
+              configStore.getAllowedUserId() === operator &&
+              telegramSessionContextStore.getGeneration() === generation;
+          },
+        };
       },
-      listBindings: threadStore.listWorkspaceBindings,
       getProtection: captureWorkspaceExternalProtection,
-      listReservations: threadStore.listReservations,
-      listPendingProvisions: threadStore.listPendingProvisions,
-      listPendingCleanups: threadStore.listPendingCleanups,
-      getWorkStore() {
-        const profileName = configStore.getActiveProfileName() ?? "default";
+      getProcessLiveness: ProcessIdentity.getTelegramProcessLiveness,
+      runExclusive: telegramWorkspaceOperationRuntime.runExclusive,
+      getWorkStore(authority) {
+        const profileName = authority.profileName;
         const botToken = configStore.getBotToken();
         if (!botToken)
           throw new Error(
@@ -617,9 +631,16 @@ export default function (pi: Pi.ExtensionAPI) {
           tokenSha256: Journal.createTelegramUpdateJournalBotIdentity({
             botToken,
           }).tokenSha256,
+          admissionProfileKey: authority.ledger.getProfileKey(),
         });
       },
       runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,
+      deleteThread(authorize) {
+        return directTelegramApiRuntime.deleteWorkspaceThread(authorize);
+      },
+      onError(error) {
+        recordRuntimeEvent("telegram", error, { phase: "manual-inactive-thread-cleanup" });
+      },
     });
   const updateAdmissionRuntimeBinding =
     Updates.createTelegramUpdateAdmissionRuntimeBinding<Pi.ExtensionContext>({
@@ -1187,7 +1208,8 @@ export default function (pi: Pi.ExtensionAPI) {
       sendInteractiveMessage,
       answerCallbackQuery,
       ...configControls,
-      reviewInactiveThreads: inactiveThreadCleanupReviewRuntime.review,
+      reviewInactiveThreads: inactiveThreadCleanupRuntime.review,
+      cleanInactiveThreads: inactiveThreadCleanupRuntime.clean,
       getThreadDisplayMode() {
         return threadStore.getBotState().threadMode === "enabled"
           ? Config.resolveTelegramThreadDisplayMode(configStore.get())
@@ -1741,6 +1763,16 @@ export default function (pi: Pi.ExtensionAPI) {
           },
         );
       },
+      recoverRejectedRecipientTarget(error) {
+        const rejected =
+          error instanceof TelegramApi.TelegramApiFollowerNotAllowedError
+            ? error.requestTarget
+            : undefined;
+        const current = telegramBusFollowerRegistrationState.getTarget();
+        return rejected && current?.threadId !== undefined
+          ? { rejected, current: { chatId: current.chatId, threadId: current.threadId } }
+          : undefined;
+      },
       prepareUpdateForExecution(update) {
         return BusFollower.prepareTelegramBusFollowerJournaledUpdateForExecution(
           update,

package/node_modules/@llblab/pi-telegram/lib/generative-apps.ts

@@ -288,6 +288,18 @@ export function resolveGenerativeAppDir(agentDir: string, app: string): string {
   return join(getAppsRoot(agentDir), app);
 }
 
+export async function isGenerativeAppInstalled(
+  agentDir: string,
+  app: string,
+): Promise<boolean> {
+  try {
+    await stat(resolveGenerativeAppModulePath(agentDir, app));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function resolveGenerativeAppModulePath(
   agentDir: string,
   app: string,

package/node_modules/@llblab/pi-telegram/lib/lifecycle.ts

@@ -14,6 +14,7 @@ import type {
   AgentStartEvent,
   AssistantMessageEvent,
   BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
   ExtensionAPI,
   ExtensionContext,
   InputEvent,
@@ -61,6 +62,7 @@ type TelegramBeforeAgentStartEvent = Omit<
 
 export interface TelegramBeforeAgentStartResult {
   systemPrompt?: string | string[];
+  message?: BeforeAgentStartEventResult["message"];
 }
 
 type TelegramBeforeAgentStartReturn =

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -207,7 +207,7 @@ export function buildAutomaticThreadCleanupSettingsText(
     "<code>-</code> <code>on</code> (default): delete the bound thread and release Telegram authority on graceful quit.",
     "<code>-</code> <code>off</code>: preserve the tab as a restart hint; manual <code>/telegram-disconnect</code> still confirms and deletes it.",
     "",
-    "Review inactive tabs checks current owner and work evidence. Review never deletes tabs.",
+    "On the leader instance, Review inactive tabs checks current owner and work evidence, including tabs without a letter. Review never deletes tabs.",
   ].join("\n");
 }
 
@@ -217,7 +217,8 @@ function buildInactiveThreadReviewText(count: number): string {
     "",
     `${count} proven inactive tab${count === 1 ? "" : "s"}.`,
     "No tabs were deleted.",
-    "Deletion requires a separate confirmed Clean action.",
+    "Clean inactive tabs deletes these Telegram tabs and all their messages. Pi session history and project files are not removed.",
+    "Clean rechecks owner and work protection; a changed or protected tab is skipped. Choose Back to leave without deleting anything.",
   ].join("\n");
 }
 

package/node_modules/@llblab/pi-telegram/lib/pi.ts

@@ -10,6 +10,7 @@ import {
   type AgentSettledEvent,
   type AgentStartEvent,
   type BeforeAgentStartEvent,
+  type BeforeAgentStartEventResult,
   type ExtensionAPI,
   type ExtensionCommandContext,
   type ExtensionContext,
@@ -33,6 +34,7 @@ export type {
   AgentStartEvent,
   AssistantMessageEvent,
   BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
   ExtensionAPI,
   ExtensionCommandContext,
   ExtensionContext,

package/node_modules/@llblab/pi-telegram/lib/prompts.ts

@@ -1,10 +1,10 @@
 /**
  * Telegram prompt injection helpers
  * Zones: pi agent prompts, telegram guidance
- * Owns Telegram-specific system prompt suffixes injected into pi agent turns
+ * Owns stable Telegram guidance, turn-scoped context, and compatibility fallback hooks
  */
 
-import type { BeforeAgentStartEvent } from "./pi.ts";
+import type { BeforeAgentStartEvent, BeforeAgentStartEventResult } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
 export const TELEGRAM_CONNECTED_CONTEXT_MESSAGE =
@@ -164,18 +164,34 @@ type TelegramBeforeAgentStartResult = {
   systemPrompt: TelegramSystemPrompt;
 };
 
+type TelegramProactiveBeforeAgentStartResult = Omit<BeforeAgentStartEventResult, "systemPrompt"> & {
+  systemPrompt?: TelegramSystemPrompt;
+};
+
 type TelegramBeforeAgentStartHook = (
   event: TelegramBeforeAgentStartEvent,
 ) => TelegramBeforeAgentStartResult;
 
-export function buildTelegramBridgeSystemPrompt(options: {
+// Returning any systemPrompt makes Pi replace its prompt, which defeats prompt
+// caching; return an override only when the computed prompt actually differs.
+function overrideSystemPromptIfChanged(
+  incoming: TelegramSystemPrompt | null | undefined,
+  computed: TelegramSystemPrompt,
+): TelegramBeforeAgentStartResult | undefined {
+  const base = incoming ?? "";
+  const unchanged =
+    Array.isArray(base) && Array.isArray(computed)
+      ? base.length === computed.length &&
+        base.every((block, index) => block === computed[index])
+      : base === computed;
+  return unchanged ? undefined : { systemPrompt: computed };
+}
+
+function buildTelegramTurnSuffix(options: {
   prompt?: string;
-  systemPrompt?: TelegramSystemPrompt | null;
   telegramPrefix?: string;
-  localSystemPromptSuffix: string;
   telegramTurnSystemPromptSuffix: string;
-}): TelegramBeforeAgentStartResult {
-  const basePrompt = options.systemPrompt ?? "";
+}): string {
   const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
   const telegramHead = telegramPrefix.endsWith("]")
     ? telegramPrefix.slice(0, -1)
@@ -184,9 +200,20 @@ export function buildTelegramBridgeSystemPrompt(options: {
   const telegramTurn =
     trimmedPrompt.startsWith(`${telegramHead}]`) ||
     trimmedPrompt.startsWith(`${telegramHead}|`);
-  const telegramSuffix = telegramTurn
+  return telegramTurn
     ? `${options.telegramTurnSystemPromptSuffix}\n- The current user message came from Telegram.`
     : "";
+}
+
+export function buildTelegramBridgeSystemPrompt(options: {
+  prompt?: string;
+  systemPrompt?: TelegramSystemPrompt | null;
+  telegramPrefix?: string;
+  localSystemPromptSuffix: string;
+  telegramTurnSystemPromptSuffix: string;
+}): TelegramBeforeAgentStartResult {
+  const basePrompt = options.systemPrompt ?? "";
+  const telegramSuffix = buildTelegramTurnSuffix(options);
   return {
     systemPrompt: Array.isArray(basePrompt)
       ? [...basePrompt, options.localSystemPromptSuffix + telegramSuffix]
@@ -236,22 +263,58 @@ export interface TelegramProactivePromptHookDeps<TContext> {
   isAvailable: (ctx: TContext) => boolean;
 }
 
+const TELEGRAM_TOOL_NAMES = ["telegram_attach", "telegram_message"];
+
+// Sections cannot modify an opaque prompt owned by an earlier handler.
+// Preserve append/strip compatibility there instead of silently losing guidance.
+function applyTelegramPromptSections(
+  event: TelegramBeforeAgentStartEvent,
+  available: boolean,
+): boolean {
+  const options = event.systemPromptOptions as
+    | Partial<TelegramBeforeAgentStartEvent["systemPromptOptions"]>
+    | undefined;
+  const sections = options?.sections;
+  if (typeof sections !== "object" || sections === null || options?.forceSystemPrompt !== undefined) return false;
+  if (available) {
+    sections.telegram = LOCAL_SYSTEM_PROMPT_SUFFIX.trim();
+    return true;
+  }
+  delete sections.telegram;
+  for (const name of TELEGRAM_TOOL_NAMES) {
+    if (options?.toolSnippets) delete options.toolSnippets[name];
+    if (options?.toolGuidelines) delete options.toolGuidelines[name];
+  }
+  return true;
+}
+
 export function createTelegramProactiveBeforeAgentStartHook<TContext>(
   deps: TelegramProactivePromptHookDeps<TContext>,
 ): (
   event: TelegramBeforeAgentStartEvent,
   ctx: TContext,
-) => Promise<TelegramBeforeAgentStartResult> {
+) => Promise<TelegramProactiveBeforeAgentStartResult | undefined> {
   const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
   return async (event, ctx) => {
     deps.reconcileAvailability?.();
-    if (!deps.isAvailable(ctx)) {
-      return {
-        systemPrompt: stripTelegramToolMetadataFromSystemPrompt(
-          event.systemPrompt,
-        ),
-      };
+    const available = deps.isAvailable(ctx);
+    // A caller-supplied baseHook owns its own prompt text, so it stays on the forced-prompt path.
+    if (!deps.baseHook && applyTelegramPromptSections(event, available)) {
+      const turnSuffix = available ? buildTelegramTurnSuffix({
+        prompt: event.messageType === "custom" ? undefined : event.prompt,
+        telegramTurnSystemPromptSuffix: TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX,
+      }).trim() : "";
+      return turnSuffix ? { message: { customType: "telegram-turn", content: turnSuffix, display: false } } : undefined;
+    }
+    if (!available) {
+      return overrideSystemPromptIfChanged(
+        event.systemPrompt,
+        stripTelegramToolMetadataFromSystemPrompt(event.systemPrompt),
+      );
     }
-    return baseHook(event);
+    return overrideSystemPromptIfChanged(
+      event.systemPrompt,
+      baseHook(event).systemPrompt,
+    );
   };
 }