@llblab/pi-telegram 0.24.4 → 0.24.6

package/AGENTS.md

@@ -78,7 +78,8 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - The bridge is session-local, paired to one allowed Telegram user, and owns a local queue aligned with Pi lifecycle hooks
 - The Telegram lock owns external Telegram transport, not local Pi execution. Local extension state and queue runtime are per Pi instance: losing exact `/telegram-connect` ownership must not clear accepted queue state or stop local Pi dispatch, but preview, final delivery, attachments, menus, and other Bot API mutations fail closed once another runtime owns transport. A replacement owner must never receive stale direct mutations merely to preserve old-runtime Telegram output. Bus leader lock entries carry a stable `leaderEpoch` minted on acquisition and preserved across heartbeat refreshes; leader-owned Thread Reconciler cleanup/provisioning actions stamp that epoch and skip destructive side effects if current leadership differs.
 - Telegram transport ownership lives only in the extension-local `tmp/telegram/owners.json` store under `default` or named profile slots. Every mutation must serialize the complete cross-process read/check/write transaction through `owners.json.transaction` and fail closed on contention; atomic payload replacement alone does not make ownership linearizable. Refresh, release, takeover, and irreversible leader work additionally fence against the exact acquired owner and leader epoch. In classic/private-chat mode, transport ownership is the whole bridge ownership and `/telegram-connect` from another live Pi offers classic takeover confirmation. In Threaded Mode, transport ownership is the bus leader role and another live Pi registers as follower instead of offering takeover while the leader is live. If follower registration is unavailable, fall back to classic takeover.
-- Polling checks exact `owners.json` ownership every second but refreshes the durable owner heartbeat only every two seconds; an eight-second stale threshold preserves bounded recovery headroom without turning every ownership check into an atomic disk rewrite. Ownership transactions publish a fully initialized private guard directory containing one exact generation-specific `owner.<generation>.json` through same-parent atomic rename. The owner filename and payload generation must match so stale observation cannot rename replacement metadata. Release verifies the owner and atomically renames the stable guard away before cleanup. Directory recovery first claims owner metadata inside the still-occupied guard so a crashed recoverer can itself be replaced without exposing the stable path; transient guard moves and rollback both retry, while inactive process-global claim generations remain recoverable after failed restoration. If secondary recovery cleanup fails after publishing a replacement main guard, release that exact replacement before propagating the failure. Guards must not depend on hard links, direct file rename-overwrite, incomplete create-then-write state, or age-only recovery; malformed or unsupported guards fail closed.
+- Polling checks exact `owners.json` ownership every second but refreshes the durable owner heartbeat only every two seconds; an eight-second stale threshold preserves bounded recovery headroom without turning every ownership check into an atomic disk rewrite. Ownership transactions publish a fully initialized private guard directory containing one exact generation-specific `owner.<generation>.json` through same-parent atomic rename. The owner filename and payload generation must match so stale observation cannot rename replacement metadata. Release verifies the owner and atomically renames the stable guard away before cleanup. Directory recovery first claims owner metadata inside the still-occupied guard so a crashed recoverer can itself be replaced without exposing the stable path; transient guard moves and rollback both retry, while inactive process-global claim generations remain recoverable after failed restoration. If secondary recovery cleanup fails after publishing a replacement main guard, release that exact replacement before propagating the failure. Guards must not depend on hard links, direct file rename-overwrite, incomplete create-then-write state, or age-only recovery; malformed or unsupported guards fail closed during ordinary mutation.
+- `/telegram-connect` is the bounded liveness-recovery boundary for unclean-shutdown corruption in disposable `tmp/telegram` state. It may quarantine only classifier-approved malformed `owners.json`, active-profile `state*.json`, and `owners.json.transaction` after serializing recoverers and revalidating under ownership fencing; it must preserve `telegram.json`, diagnostics, unrelated artifacts, and every verifiable live owner/transaction holder. Stale heartbeats older than eight seconds do not gain protection through PID reuse. Require confirmed local polling suspension before quarantine mutation; a suspension failure blocks recovery, while an ownership-release failure may continue only into final guarded live-owner revalidation. Use the established bounded Windows sharing-violation rename retries. Retry polling exactly once after recovery, preserve unrelated startup errors, and replace blocked/repeated recovery failure with one explicit restart instruction rather than broad `tmp/` deletion or an automatic loop.
 - Telegram profiles are parallel bot/runtime realities, not merely alternate credentials. Persist every bot/session field (`botToken`, `botUsername`, `botId`, `allowedUserId`, `lastUpdateId`) under `telegram.json` `profiles.<name>`, including `profiles.default`; keep shared handlers and assistant/voice/time/thread-lifecycle settings top-level. Bare and explicit `default` setup/connect commands address the same profile. Legacy root identity may normalize atomically only when unambiguous; conflicts fail closed without mutation. Any owner slot, IPC endpoint, state snapshot, diagnostics log, thread/bus binding, runtime cache, ownership map, or operator-visible status surface that could mix bot identities must be deliberately classified as global, session-local, or profile-scoped. Use the `default` owner slot for the default profile and validated profile names for named slots; give named profiles isolated observable surfaces unless there is an explicit top-level shared-config reason not to.
 - Telegram private-chat Threaded Mode is the public switch for the local multi-instance bus. There is no separate public `telegram.json` bus switch: classic/private-chat singleton DM behavior is the base product mode, and when Telegram reports Threaded Mode available for the bot the bridge enables leader/follower bus behavior. If Telegram reports Threaded Mode unavailable or thread operations prove it unavailable, the bridge returns to classic singleton behavior as a first-class mode. During a live Threaded Mode downgrade, the current transport leader keeps the singleton classic polling role and followers disconnect instead of taking over or offering takeover while active thread bindings prove this is a downgrade from a live bus organism. Do not inject slot/thread rename guidance in classic mode. Blocked instances should not silently register as followers unless the effective runtime mode is Threaded Mode.
 - In Threaded Mode, exactly one live leader owns `getUpdates` and direct Telegram Bot API calls for one bot token. `/telegram-connect` means join the local Telegram organism: if no live leader exists the instance becomes leader; if a live leader exists the terminal-visible instance registers as follower; ordinary connect must not offer manual takeover while the leader heartbeat is live. Leadership is an ephemeral transport role, not permanent ownership by the first terminal-visible Pi instance. Heartbeat acknowledgements carry the authenticated live follower-slot roster: on leader loss, the lowest observed live slot attempts the atomic lock first, while higher slots defer for one bounded grace and then re-check so a missing lower follower cannot block recovery indefinitely. Followers must be started by the operator as real Pi processes, register over the local bus, heartbeat, receive only their routed inbound updates, and send outbound replies/previews/files/chat-actions through the leader transport; Telegram must not spawn hidden Pi processes, launch follower subprocesses, or expose a slash command that creates a new local Pi instance. If a leader reloads while followers stay alive, followers must treat rejected/unknown/unauthorized heartbeats as a registration-loss signal and optimistically re-register with the currently active leader before considering promotion; after a short grace window without successful re-registration, a live follower may promote only through an atomic expected-owner transition after the exact observed leader lease becomes stale or inactive. An unreachable IPC endpoint does not authorize replacing a still-live lock owner; remain disconnected/retrying rather than creating split-brain polling. Terminal status must not remain `follower` while the leader registry can no longer route that follower's thread. Heartbeat pruning is liveness bookkeeping, not permission to delete, mark offline, or send a Telegram-visible disconnected notice for a follower's thread; preserve active follower tabs/bindings across transient reload/reconnect incidents and reserve destructive teardown/offline transitions for confirmed manual disconnect, graceful Pi quit, or confirmed reconciliation cases. If the leader dies, a live follower should eventually be able to take over through stale-leader election/recovery so the local multi-instance organism keeps running. Explicit `/telegram-disconnect` retains destructive confirmation; graceful Pi `quit` invokes the same teardown without prompting when top-level `threads.automaticCleanup` is enabled (default), while disabling it and `reload`, `new`, `resume`, or `fork` preserve the binding through safe handoff/suspension. A leader deletes its own bound thread before releasing transport ownership, while a follower sends an authenticated exact-registration-generation disconnect envelope and waits for the leader to delete its assigned thread, mark the durable binding offline, and remove live routing authority before unregistering. Cleanup must be confirmed by successful deletion or explicit already-gone evidence; incomplete cleanup preserves binding/routing state, keeps the session open, and returns actionable retry guidance. A promoted leader authorizes inherited follower-thread cleanup by its current leader epoch rather than the historical owner label. Status is reactive to the effective runtime role and bot capability: classic/non-thread mode shows ordinary `telegram connected`, active bus leadership shows `telegram leader`, and registered followers show `telegram follower`; stable multi-instance truth belongs in the bus role (`leader`/`follower`), while lifecycle is reserved for transient recovery state such as `electing` and must not duplicate stable roles with labels like `leader-active`. When leadership or Threaded Mode availability changes at runtime, the status line and `/telegram-status` must converge promptly instead of preserving a stale role label.

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.24.6: README Positioning Hotfix
+
+- `README Positioning`: Removed duplicated automatic thread-cleanup detail from the opening and defaults summary while retaining the canonical behavior in the lifecycle controls and configuration documentation. Impact: the package entrypoint stays focused on the companion runtime model without changing graceful-quit behavior or its configurable cleanup policy.
+
+## 0.24.5: Unclean-Shutdown Recovery Hotfix
+
+- `Unclean-Shutdown Recovery`: `/telegram-connect` now classifies truncated temporary ownership/routing snapshots and unverifiable ownership transaction debris, quarantines only damaged disposable artifacts when no verifiable live owner protects them, and retries startup exactly once. Recovery serializes cross-process contenders, revalidates under ownership fencing, treats eight-second stale heartbeats as replaceable despite PID reuse, preserves `telegram.json` and diagnostics, and converts blocked or repeated failure into one explicit Pi-restart instruction. Impact: abrupt host shutdown no longer leaves the bridge trapped behind raw JSON/transaction errors or requires deleting the whole agent `tmp/` directory.
+- `Composition Root Cooling`: Moved follower active-auth and transient-election mutable state from `index.ts` into a cohesive `bus-follower` control runtime while leaving direct one-to-one runtime wiring in the composition root. Impact: follower control state now has one testable owner without introducing a wrapper whose only purpose is line-count reduction.
+
 ## 0.24.4: Context And Thread Lifecycle Hotfix
 
 - `Disconnect Context Availability`: Reconciled `telegram_attach`, `telegram_message`, `telegram_help`, their active-tool prompt metadata, and the compact bridge suffix against effective direct-owner or registered-follower authority. Successful disconnect or authority loss removes only pi-telegram surfaces for subsequent requests; reconnect/recovery restores only the operator's previously active pi-telegram subset across same-process reload, while execute-time transport guards remain. Impact: disconnected sessions stop spending context on unavailable Telegram capabilities or inviting calls that must fail.

package/README.md

@@ -10,8 +10,6 @@ It is a **runtime adapter**, not a remote terminal. Start or supervise work in t
 
 Proactive push is enabled by default. `assistant.proactivePush` projects every completed public assistant text block from local or autonomous work—including visible checkpoints and the final answer—to the authorized Telegram target once and in order; set it explicitly to `false` to disable projection. It never mirrors local prompts, hidden reasoning, tool traffic, token deltas, Telegram-owned turns, or stale-generation work. See [Outbound](docs/outbound.md#proactive-public-output) and the [configuration reference](docs/public-api.md#configuration-api).
 
-Automatic thread cleanup is enabled by default. Graceful Pi quit deletes that instance's Threaded Mode tab; use `🧹 Auto thread cleanup` in Telegram Settings or set `threads.automaticCleanup` to `false` to preserve the tab as a restart hint. This option never changes manual `/telegram-disconnect`, which still asks for confirmation and deletes the tab.
-
 This repository is an actively maintained fork of [`badlogic/pi-telegram`](https://github.com/badlogic/pi-telegram). It started from upstream commit [`cb34008`](https://github.com/badlogic/pi-telegram/commit/cb34008460b6c1ca036d92322f69d87f626be0fc) and has since diverged substantially.
 
 ## Install
@@ -57,6 +55,8 @@ Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved tok
 
 The connected Pi instance owns Telegram polling. Use `/telegram-connect <name>` to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers.
 
+After an unclean computer shutdown, `/telegram-connect` detects truncated or structurally invalid temporary ownership/routing files, quarantines only the damaged files under `tmp/telegram/recovery/`, and retries once. Saved `telegram.json` configuration and runtime diagnostics remain intact. Recovery never replaces a verifiable live owner; if safe automatic recovery cannot complete, the command gives one explicit Pi-restart instruction instead of requiring deletion of the whole `tmp/` directory.
+
 ### 4. Pair your Telegram account
 
 Open the bot DM and send:
@@ -214,7 +214,7 @@ Most controls live in Pi commands or the Telegram menu. Environment variables re
 | Inbound file limit | `PI_TELEGRAM_INBOUND_FILE_MAX_BYTES`, `TELEGRAM_MAX_FILE_SIZE_BYTES` |
 | Outbound attachment limit | `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES`, `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES` |
 
-Defaults are chosen for ordinary private-bot use: saved config in `~/.pi/agent`, inbound temp files in `~/.pi/agent/tmp/telegram`, `assistant: { rendering: "rich", draftPreviews: false }` for assistant answer output, `threads.automaticCleanup: true` for graceful Threaded Mode teardown, and native Telegram active status for long-running turns.
+Defaults are chosen for ordinary private-bot use: saved config in `~/.pi/agent`, inbound temp files in `~/.pi/agent/tmp/telegram`, `assistant: { rendering: "rich", draftPreviews: false }` for assistant answer output, and native Telegram active status for long-running turns.
 
 ## Extension Platform
 

package/docs/architecture.md

@@ -64,7 +64,7 @@ The repository uses a **Flat Domain DAG**:
 - `api`: Bot API helpers, retries, uploads/downloads, temp cleanup, byte limits, chat actions, lazy token clients, and API error recording.
 - `config` / `setup`: `telegram.json`, bot token setup, named bot/session profiles, first-user pairing, authorization, env fallback, atomic persistence, effective config views, and live config accessors.
 - `locks` / `polling`: extension-local transport owner storage, exact-owner epoch exposure, process-global reload generations, owner-aware polling lifecycle/takeover/follower registration, and the cohesive classic-vs-Threaded capability state/monitor/observation/polling orchestration. Polling also owns long-poll controller state, offset admission/persistence, and poll-loop wiring.
-- `bus` / `bus-api` / `bus-leader` / `bus-follower` / `ownership` / `target`: Threaded Mode multi-instance bus contracts, profile-scoped process/endpoint identity, local leader/follower IPC, leader-only orchestration, follower-side manual registration/session runtime, follower-routed Bot API calls, live message ownership, and `{ chatId, threadId? }` target identity. `bus` owns shared protocol, process identity, profile-aware local endpoints, and IPC primitives; `bus-leader` owns leader runtime, leader envelope handling, activation scheduling, and leader polling/server/prune orchestration; `bus-follower` owns process-stable manual-follower keys plus this Pi instance's follower-side registration, heartbeat, one-sequence authenticated client assembly, forwarded-update adaptation/receiving, recovery retry defaults, and routed API caller without any process spawning.
+- `bus` / `bus-api` / `bus-leader` / `bus-follower` / `ownership` / `target`: Threaded Mode multi-instance bus contracts, profile-scoped process/endpoint identity, local leader/follower IPC, leader-only orchestration, follower-side manual registration/session runtime, follower-routed Bot API calls, live message ownership, and `{ chatId, threadId? }` target identity. `bus` owns shared protocol, process identity, profile-aware local endpoints, and IPC primitives; `bus-leader` owns leader runtime, leader envelope handling, activation scheduling, and leader polling/server/prune orchestration; `bus-follower` owns process-stable manual-follower keys plus this Pi instance's follower-side registration, active leader-auth/transient-election control state, heartbeat, one-sequence authenticated client assembly, forwarded-update adaptation/receiving, recovery retry defaults, and routed API caller without any process spawning.
 - `sync`: demand-driven Telegram reconciliation, mutable sync-slice state, nested provisioning activity, and local assumption policy. It does not own a complete Telegram bot read-model; Bot API lacks a complete topic/thread listing surface. It owns sync slices, invalidation triggers, config-persist invalidation sequencing, stale-topic API recovery adaptation, observation intake, status/debug freshness, and reconciliation scheduling across bot identity, pairing assumptions, live target bindings, reservations, and transport health after meaningful observable signals. It should call narrower domain primitives rather than letting `index.ts`, `threads`, or `status` accumulate cross-cutting reconciliation policy.
 - `thread-reconciler`: Threaded Mode control-plane planning for Telegram thread/tab lifecycle. It owns the reconciliation state machine (`stable`, `provisioning`, `sync-required`, `cleanup-required`), pure plans, proof-before-delete rules, pending-provision protection, fresh-creation grace windows, leader-epoch checks, and the single policy authority for destructive thread cleanup actions. It excludes live Telegram API calls, inbound routing, menu rendering, and direct persistence.
 - `threads`: Telegram UI thread/tab binding state mapped to Bot API `message_thread_id` / `ForumTopic` transport. Owns leader and current-instance identity state, profile-bound same-process leader session handoff, status projections, slot allocation from the current extension state, baked compact thread-name selection, current binding persistence, and primitive thread provision helpers. It should not persist stale/offline/failed target history, own destructive cleanup policy, grow into the general Telegram synchronization domain, or expose a rename tool.
@@ -127,6 +127,7 @@ Telegram configuration lives in `~/.pi/agent/telegram.json`. Bot/session identit
 - `owners.json` owns only Telegram transport control. Local extension and accepted queue state remain per Pi instance when ownership moves, but previews, final delivery, dispatch transport mutations, and delayed Bot API work fail closed until exact direct or follower authority becomes valid again.
 - Exact ownership remains checked every second, while the durable owner heartbeat refresh runs every two seconds and becomes stale after eight seconds. This keeps replacement detection responsive while halving steady-state atomic `owners.json` rewrites without changing the cross-platform file-transaction authority. Every acquisition, refresh, release, takeover, and stale recovery serializes through the sibling `owners.json.transaction` guard. The guard publishes one private generation-named owner record atomically, validates filename/payload generation agreement, fences stale recovery and delayed release against replacement-owner ABA, and fails closed on malformed state, unverifiable ownership, contention timeout, or unsupported filesystem behavior. The JSON store publishes through a private same-directory temporary file and atomic rename; atomic payload replacement does not replace transaction serialization.
 - `owners.json` is authoritative and private. `state.json` remains an observable snapshot, `logs.jsonl` remains diagnostics, and followers remain authenticated bus registrations rather than ownership-file writers.
+- Ordinary ownership and state mutations fail closed on malformed files. When `/telegram-connect` itself fails and the recovery classifier finds truncated `owners.json`, truncated profile `state*.json`, or an unverifiable `owners.json.transaction`, it may prioritize runtime liveness: a dedicated recovery transaction serializes contenders, the ownership transaction fences a final reread, and only classifier-approved disposable artifacts move atomically into `tmp/telegram/recovery/<timestamp>-<pid>-<generation>/`. A verifiable live owner or transaction holder blocks mutation. Local polling suspension must complete before any quarantine mutation; failure blocks recovery, while a later ownership-release parse failure may proceed only because final guarded classification still protects any live owner. Quarantine renames use the same bounded `EPERM`/`EBUSY`/`EACCES` sharing retries as ownership publication for native Windows. Stale owner heartbeats older than eight seconds remain replaceable even if the operating system reused their PID. Configuration, logs, and unrelated temporary files never enter the recovery candidate set. The command retries startup once; a second failure becomes one explicit restart instruction rather than another recovery loop.
 
 ### Persistence I/O Baseline
 
@@ -138,7 +139,7 @@ The three runtime files have different authority and write pressure. Preserve th
 
 This baseline counts write-producing code paths rather than filesystem implementation details that vary between ext4, APFS, NTFS, and network-backed home directories. Optimization evidence should compare these deterministic triggers first, then use platform smoke evidence for rename, named-pipe, crash, and cleanup behavior. Recovery-critical `state.json` fields are `bot`, `identities`, `reservations`, `pendingProvisions`, `syncObservations`, and `threads`; `runtime`, `liveRoster`, `diagnostics`, and `writtenAtMs` are observational and may use bounded coalescing when authority checks remain unchanged.
 
-Version `0.24.0` intentionally does not read or migrate the former agent-level `locks.json`; upgrading resets Telegram ownership. Run `/telegram-connect` when a fresh owner is not elected automatically. Delete `~/.pi/agent/tmp/telegram/owners.json` and its stale transaction guard, when no owner process is live, to reset only pi-telegram transport ownership without deleting configuration, diagnostics, or other extensions' state.
+Version `0.24.0` intentionally does not read or migrate the former agent-level `locks.json`; upgrading resets Telegram ownership. Run `/telegram-connect` when a fresh owner is not elected automatically. Current builds automatically quarantine recognized unclean-shutdown corruption when no live owner protects it. Manual removal of `~/.pi/agent/tmp/telegram/owners.json` and its transaction guard is only a last resort after stopping every Pi instance that could own Telegram; never delete the whole agent `tmp/` directory to repair this extension.
 
 ### Threaded Mode Multi-Instance Bus
 

package/docs/multi-instance-bus.md

@@ -355,6 +355,8 @@ Current state under the agent dir:
 - `tmp/telegram/state.json`: volatile extension+bot observable/debug snapshot, not routing authority. It writes `source: "snapshot"` and `writtenAtMs` so consumers do not confuse it with an authoritative database. Every process on one Telegram profile reads this shared path, but only the active transport owner may persist it; followers become writers only after promotion. Status-only persistence refreshes disk-backed bindings before serialization so an already-loaded stale view cannot erase newer leader records. It mirrors `/telegram-status`-style projections: top-level `bot` stores bot-wide capability state such as `threadMode: "unknown" | "enabled" | "disabled"`, `runtime` identifies leader/follower role and process status, `liveRoster` mirrors followers/current targets/reservations, `diagnostics` mirrors status/debug signals, `threads` stores current routeable bindings, `bot.lastSlot` stores the compact slot cursor used when all current threads are gone, and `reservations` records short-lived slot collision guards.
 - Local bus endpoints: Unix-like platforms expose stable `tmp/telegram/bus.sock` and `tmp/telegram/followers/*` symlinks backed by private generation sockets; native Windows uses deterministic named pipes under `\\.\pipe\pi-telegram-...`. These are transient IPC endpoints, not durable routing state.
 
+If an unclean host shutdown truncates `owners.json`, a profile `state*.json`, or the ownership transaction guard, `/telegram-connect` classifies the damage before recovery. With no verifiable live owner, one cross-process recovery winner quarantines only those damaged disposable artifacts and startup retries once; followers or leaders appearing during the final guarded reread stop the reset. `telegram.json`, `logs*.jsonl`, other profiles' valid state, and unrelated extension data remain untouched. A blocked or failed reset reports which Pi must restart instead of emitting repeated raw parse/transaction errors.
+
 The bridge must not keep a separate durable `telegram-targets.json` history. `state.json` retains current stable manual-follower bindings as restart hints, but they never authorize routing without a matching authenticated live registration. Stale/offline/failed observations are not reusable delivery authority. `sync` remains event-driven assumption reconciliation rather than a full Telegram bot-state mirror because Bot API exposes no complete thread listing surface. Non-current routeable thread bindings are pruned during load/persist; old session records must not be retained just to compute the next slot because `bot.lastSlot` is the only durable cursor. Previous-process leader bindings are treated as occupied TTL-bounded reservations until Telegram confirms deletion: reload/startup may close/delete/probe the old thread, known reservations are retried proactively on leader startup, and if Telegram still accepts the old thread id, the new leader should provision the next free slot (`B`, `C`, …) rather than creating a duplicate same-letter tab or blocking startup on Telegram UI convergence. Routing must use live current threads/follower registry, never reservations. The bus leader provisions its own thread during bus startup/connect and provisions follower threads on `follower.register`; registered followers also live in the leader's in-memory registry and communicate over the local bus socket. The live follower registry can resolve a follower by exact `{ chatId, threadId? }`; the leader uses that target ownership to forward message and edited-message updates to followers, and the follower receiver accepts those updates in addition to callbacks and reactions. Terminal status and `[telegram|thread:name]` resolve the matching current-instance identity through the same target-aware path, preferring registered local metadata over stale shared bindings. Media album grouping and split-text coalescing keys include the thread target, queue reaction mutations can scope by chat/thread to avoid cross-target message-id collisions, active-turn target is exposed for lifecycle cleanup and local direct-tool defaults, transport reply dedup is chat/thread-scoped, stored menu state is keyed by chat/message so callback state lookup cannot collide across chats, and generated button turns plus section prompt/open actions preserve the callback thread target. `telegram_message` and immediate `telegram_attach` delivery can also carry an explicit `thread_id` with `chat_id`; when a follower is registered, their default direct-tool target is the assigned thread target and the bus-aware API runtime routes the send through the leader instead of calling Bot API transport locally.
 
 All files containing routing, chat ids, thread ids, or process details use private permissions and represent current state rather than historical target caches.

package/index.ts

@@ -33,6 +33,7 @@ import * as Preview from "./lib/preview.ts";
 import * as Prompts from "./lib/prompts.ts";
 import * as PromptTemplates from "./lib/prompt-templates.ts";
 import * as Queue from "./lib/queue.ts";
+import * as Recovery from "./lib/recovery.ts";
 import * as Replies from "./lib/replies.ts";
 import * as Routing from "./lib/routing.ts";
 import * as Runtime from "./lib/runtime.ts";
@@ -84,10 +85,11 @@ export default function (pi: Pi.ExtensionAPI) {
       manualFollowerOwnerId: telegramManualFollowerOwnerId,
     });
   const telegramBusAuthSecret = Bus.createTelegramBusAuthSecret();
-  let telegramActiveBusAuthSecret: string | undefined;
-  let telegramBusLifecycleOverridePhase:
-    Status.TelegramBridgeBusLifecyclePhase | undefined;
+  const telegramBusFollowerControlState =
+    BusFollower.createTelegramBusFollowerControlState();
   const telegramBusFollowerRegistry = Bus.createTelegramBusFollowerRegistry();
+  // Late-bound composition port breaks the follower-availability callback cycle;
+  // the mutable availability policy itself remains owned by prompts.
   let modelContextAvailabilityRuntime:
     | Prompts.TelegramModelContextAvailabilityRuntime
     | undefined;
@@ -318,9 +320,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getRecentRuntimeEvents: runtimeEvents.getEvents,
     getRuntimeLockState: lockRuntime.getStatusLabel,
     ...threadStatusProjectionRuntime,
-    getBusLifecyclePhase() {
-      return telegramBusLifecycleOverridePhase;
-    },
+    getBusLifecyclePhase: telegramBusFollowerControlState.getLifecyclePhase,
     getBotThreadMode() {
       return threadStore.getBotState();
     },
@@ -363,9 +363,7 @@ export default function (pi: Pi.ExtensionAPI) {
     >({
       socketPath: getTelegramBusSocketPath,
       instanceId: telegramInstanceId,
-      getApiAuthSecret() {
-        return telegramActiveBusAuthSecret;
-      },
+      getApiAuthSecret: telegramBusFollowerControlState.getActiveAuthSecret,
       getForwardingAuthSecret() {
         return telegramBusAuthSecret;
       },
@@ -800,9 +798,7 @@ export default function (pi: Pi.ExtensionAPI) {
         socketPath: getTelegramBusFollowerSocketPath,
         instanceId: telegramInstanceId,
         getContext: telegramSessionContextStore.get,
-        getAuthSecret() {
-          return telegramActiveBusAuthSecret;
-        },
+        getAuthSecret: telegramBusFollowerControlState.getActiveAuthSecret,
         ...forwardedRouteHandlers,
         prepareForwardedMessage: textGroupRuntime.prepareForwardedMessage,
         recordRuntimeEvent,
@@ -821,9 +817,7 @@ export default function (pi: Pi.ExtensionAPI) {
       recovery: {
         registrationState: telegramBusFollowerRegistrationState,
         getLeaderState: lockRuntime.getState,
-        setLifecyclePhase(phase) {
-          telegramBusLifecycleOverridePhase = phase;
-        },
+        setLifecyclePhase: telegramBusFollowerControlState.setLifecyclePhase,
         updateStatus,
         promoteToLeader: promoteTelegramBusFollowerToLeader,
         getActiveContext: telegramSessionContextStore.get,
@@ -839,9 +833,8 @@ export default function (pi: Pi.ExtensionAPI) {
         getLeaderAuthSecret(owner) {
           return owner.busSecret;
         },
-        setActiveAuthSecret(secret) {
-          telegramActiveBusAuthSecret = secret;
-        },
+        setActiveAuthSecret:
+          telegramBusFollowerControlState.setActiveAuthSecret,
         getProfileKey: getTelegramManualFollowerProfileKey,
         recordRuntimeEvent,
       },
@@ -1044,6 +1037,21 @@ export default function (pi: Pi.ExtensionAPI) {
     activeTurnRuntime,
     lockedPollingRuntime,
     stopPolling: disconnectTelegramAndDeleteCurrentThread,
+    recoverPollingStart:
+      Recovery.createTelegramPollingStartRecoveryHandler({
+        getOwnersPath: Paths.resolveTelegramOwnersPath,
+        getStatePaths() {
+          return [
+            Threads.getTelegramTopicTargetsPath(
+              undefined,
+              configStore.getActiveProfileName(),
+            ),
+          ];
+        },
+        suspendPolling: lockedPollingRuntime.suspend,
+        releaseOwnership: lockRuntime.release,
+        recordRuntimeEvent,
+      }),
     getDisconnectThreadName() {
       const record = findCurrentThreadRecord();
       if (!record?.target.threadId) return undefined;

package/lib/bindings.ts

@@ -99,6 +99,7 @@ interface TelegramCommandsAndToolsBindingDeps {
   activeTurnRuntime: Queue.TelegramActiveTurnStore<Queue.PendingTelegramTurn>;
   lockedPollingRuntime: Locks.TelegramLockedPollingRuntime<Pi.ExtensionContext>;
   stopPolling?: () => Promise<void | string>;
+  recoverPollingStart?: Commands.TelegramBridgeCommandRegistrationDeps["recoverPollingStart"];
   getDisconnectThreadName?: () => string | undefined;
   onTransportChanged?: () => Promise<void> | void;
   getStatusLines: (
@@ -127,6 +128,7 @@ export function registerTelegramCommandsAndTools({
   activeTurnRuntime,
   lockedPollingRuntime,
   stopPolling,
+  recoverPollingStart,
   getDisconnectThreadName,
   onTransportChanged,
   getStatusLines,
@@ -234,8 +236,16 @@ export function registerTelegramCommandsAndTools({
     getStatusLines,
     reloadConfig: configStore.load,
     hasBotToken: configStore.hasBotToken,
-    startPolling: lockedPollingRuntime.start,
+    startPolling: async (ctx, options) => {
+      try {
+        return await lockedPollingRuntime.start(ctx, options);
+      } catch (error) {
+        recordRuntimeEvent("recovery", error, { phase: "polling-start" });
+        throw error;
+      }
+    },
     stopPolling: stopPolling ?? lockedPollingRuntime.stop,
+    recoverPollingStart,
     getDisconnectThreadName,
     updateStatus,
     getProfileNames: () =>

package/lib/bus-follower.ts

@@ -138,6 +138,17 @@ export interface TelegramBusFollowerSessionRefreshHookDeps<TContext> {
   ) => void;
 }
 
+export type TelegramBusFollowerControlLifecyclePhase = "electing";
+
+export interface TelegramBusFollowerControlState {
+  getActiveAuthSecret: () => string | undefined;
+  setActiveAuthSecret: (secret: string | undefined) => void;
+  getLifecyclePhase: () => TelegramBusFollowerControlLifecyclePhase | undefined;
+  setLifecyclePhase: (
+    phase: TelegramBusFollowerControlLifecyclePhase | undefined,
+  ) => void;
+}
+
 export interface TelegramBusFollowerRegistrationState {
   isRegistered: () => boolean;
   getTarget: () => TelegramTarget | undefined;
@@ -841,6 +852,21 @@ export function createTelegramBusFollowerSessionRefreshHook<TContext>(
   };
 }
 
+export function createTelegramBusFollowerControlState(): TelegramBusFollowerControlState {
+  let activeAuthSecret: string | undefined;
+  let lifecyclePhase: TelegramBusFollowerControlLifecyclePhase | undefined;
+  return {
+    getActiveAuthSecret: () => activeAuthSecret,
+    setActiveAuthSecret(secret) {
+      activeAuthSecret = secret;
+    },
+    getLifecyclePhase: () => lifecyclePhase,
+    setLifecyclePhase(phase) {
+      lifecyclePhase = phase;
+    },
+  };
+}
+
 export function createTelegramBusFollowerRegistrationState(
   options: { onAvailabilityChanged?: () => void } = {},
 ): TelegramBusFollowerRegistrationState {

package/lib/commands.ts

@@ -297,6 +297,11 @@ export interface TelegramBridgeCommandStartPollingResult {
   owner?: string;
 }
 
+export type TelegramPollingStartRecoveryResult =
+  | { kind: "unhandled" }
+  | { kind: "retry"; message: string }
+  | { kind: "blocked"; message: string };
+
 export interface TelegramBridgeCommandRegistrationDeps {
   promptForConfig: (ctx: ExtensionCommandContext, profileName?: string) => Promise<void>;
   getStatusLines: (options?: TelegramBridgeStatusLineOptions) => string[];
@@ -310,6 +315,9 @@ export interface TelegramBridgeCommandRegistrationDeps {
     | Promise<void | TelegramBridgeCommandStartPollingResult>
     | TelegramBridgeCommandStartPollingResult;
   stopPolling: () => Promise<void | string>;
+  recoverPollingStart?: (
+    error: unknown,
+  ) => Promise<TelegramPollingStartRecoveryResult>;
   getDisconnectThreadName?: () => string | undefined;
   updateStatus: (ctx: ExtensionCommandContext) => void;
   getProfileNames?: () => string[];
@@ -390,7 +398,41 @@ export function registerTelegramBridgeCommands(
         await deps.promptForConfig(ctx, profileName);
         return;
       }
-      let result = await deps.startPolling(ctx, {
+      let recoveryUsed = false;
+      const startWithRecovery = async (
+        options: TelegramBridgeCommandStartPollingOptions,
+      ): Promise<void | TelegramBridgeCommandStartPollingResult> => {
+        try {
+          return await deps.startPolling(ctx, options);
+        } catch (error) {
+          if (!deps.recoverPollingStart || recoveryUsed) throw error;
+          const recovery = await deps.recoverPollingStart(error);
+          if (recovery.kind === "unhandled") throw error;
+          if (recovery.kind === "blocked") {
+            return { ok: false, message: recovery.message };
+          }
+          recoveryUsed = true;
+          try {
+            const retry = await deps.startPolling(ctx, options);
+            if (!retry) {
+              return { ok: true, message: recovery.message };
+            }
+            return {
+              ...retry,
+              message: retry.ok
+                ? `${recovery.message} ${retry.message ?? "Telegram bridge connected."}`
+                : retry.message,
+            };
+          } catch {
+            return {
+              ok: false,
+              message:
+                "Telegram temporary state was recovered, but the bridge could not restart. Restart this Pi instance and run /telegram-connect again.",
+            };
+          }
+        }
+      };
+      let result = await startWithRecovery({
         forceFreshLeaderThread: true,
       });
       if (result && !result.ok && result.canTakeover) {
@@ -403,7 +445,7 @@ export function registerTelegramBridgeCommands(
           deps.updateStatus(ctx);
           return;
         }
-        result = await deps.startPolling(ctx, {
+        result = await startWithRecovery({
           force: true,
           forceFreshLeaderThread: true,
         });

package/lib/locks.ts

@@ -176,6 +176,42 @@ function sleepSync(ms: number): void {
   Atomics.wait(new Int32Array(buffer), 0, 0, ms);
 }
 
+export interface TelegramRenameRetryOptions {
+  rename?: typeof renameSync;
+  attempts?: number;
+  retryDelayMs?: number;
+}
+
+/** Rename one Telegram runtime artifact with bounded Windows sharing retries. */
+export function renameTelegramPathWithRetry(
+  sourcePath: string,
+  destinationPath: string,
+  options: TelegramRenameRetryOptions = {},
+): boolean {
+  const rename = options.rename ?? renameSync;
+  const attempts = Math.max(
+    1,
+    options.attempts ?? TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS,
+  );
+  const retryDelayMs = Math.max(
+    0,
+    options.retryDelayMs ?? TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS,
+  );
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      rename(sourcePath, destinationPath);
+      return true;
+    } catch (error) {
+      if ((error as { code?: unknown })?.code === "ENOENT") return false;
+      if (!isRetryableLockWriteError(error) || attempt === attempts - 1) {
+        throw error;
+      }
+      sleepSync(retryDelayMs * (attempt + 1));
+    }
+  }
+  return false;
+}
+
 interface TelegramLockTransactionOwner {
   pid: number;
   acquiredAtMs: number;
@@ -307,29 +343,11 @@ function releaseLockTransactionGuard(
     );
   }
   const releasedPath = `${path}.released.${randomUUID()}`;
-  for (
-    let attempt = 0;
-    attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS;
-    attempt += 1
-  ) {
-    try {
-      renameSync(path, releasedPath);
-      try {
-        removeLockTransactionGuard(releasedPath);
-      } catch {
-        /* released debris cannot retain transaction authority */
-      }
-      return;
-    } catch (error) {
-      if ((error as { code?: unknown })?.code === "ENOENT") return;
-      if (
-        !isRetryableLockWriteError(error) ||
-        attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1
-      ) {
-        throw error;
-      }
-      sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
-    }
+  if (!renameTelegramPathWithRetry(path, releasedPath)) return;
+  try {
+    removeLockTransactionGuard(releasedPath);
+  } catch {
+    /* released debris cannot retain transaction authority */
   }
 }
 
@@ -411,28 +429,8 @@ function reclaimAbandonedDirectoryGuard(
     throw error;
   }
 
-  const renameWithRetry = (fromPath: string, toPath: string): boolean => {
-    for (
-      let attempt = 0;
-      attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS;
-      attempt += 1
-    ) {
-      try {
-        renameRecovery(fromPath, toPath);
-        return true;
-      } catch (error) {
-        if ((error as { code?: unknown })?.code === "ENOENT") return false;
-        if (
-          !isRetryableLockWriteError(error) ||
-          attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1
-        ) {
-          throw error;
-        }
-        sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
-      }
-    }
-    return false;
-  };
+  const renameWithRetry = (fromPath: string, toPath: string): boolean =>
+    renameTelegramPathWithRetry(fromPath, toPath, { rename: renameRecovery });
 
   activeReclaims.add(reclaimGeneration);
   const stalePath = `${path}.stale.${process.pid}.${randomUUID()}`;

package/lib/recovery.ts

@@ -0,0 +1,464 @@
+/**
+ * Telegram disposable runtime recovery classification
+ * Zones: filesystem diagnostics, unclean-shutdown recovery
+ * Owns fail-safe classification of temporary ownership and routing artifacts
+ */
+
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import {
+  isProcessAlive as defaultIsProcessAlive,
+  parseTelegramLockEntry,
+  renameTelegramPathWithRetry,
+  TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS,
+  withTelegramFileTransaction,
+  type TelegramFileTransactionOptions,
+} from "./locks.ts";
+
+export type TelegramRuntimeArtifactKind = "owners" | "state" | "transaction";
+
+export interface TelegramRuntimeCorruptArtifact {
+  kind: TelegramRuntimeArtifactKind;
+  path: string;
+  reason: string;
+}
+
+export type TelegramRuntimeRecoveryClassification =
+  | { kind: "clean" }
+  | {
+      kind: "recoverable-corruption";
+      artifacts: TelegramRuntimeCorruptArtifact[];
+    }
+  | {
+      kind: "blocked-live-owner";
+      artifacts: TelegramRuntimeCorruptArtifact[];
+      livePids: number[];
+    };
+
+export interface TelegramRuntimeRecoveryClassificationOptions {
+  ownersPath: string;
+  statePaths?: readonly string[];
+  transactionPath?: string;
+  isProcessAlive?: (pid: number) => boolean;
+  nowMs?: number;
+  staleHeartbeatMs?: number;
+  ignoredTransactionPids?: readonly number[];
+}
+
+export type TelegramRuntimeRecoveryResult =
+  | { kind: "not-needed" }
+  | {
+      kind: "blocked-live-owner";
+      livePids: number[];
+      quarantineDir?: string;
+    }
+  | {
+      kind: "recovered";
+      artifacts: TelegramRuntimeCorruptArtifact[];
+      quarantineDir: string;
+    };
+
+export interface TelegramRuntimeRecoveryOptions
+  extends TelegramRuntimeRecoveryClassificationOptions {
+  recoveryTransactionPath?: string;
+  quarantineRoot?: string;
+  pid?: number;
+  getNowMs?: () => number;
+  quarantineRename?: typeof renameSync;
+  quarantineRenameRetryDelayMs?: number;
+  transactionOptions?: TelegramFileTransactionOptions;
+}
+
+export type TelegramPollingStartRecoveryDecision =
+  | { kind: "unhandled" }
+  | { kind: "retry"; message: string }
+  | { kind: "blocked"; message: string };
+
+export interface TelegramPollingStartRecoveryHandlerDeps {
+  getOwnersPath: () => string;
+  getStatePaths: () => readonly string[];
+  suspendPolling: () => Promise<unknown>;
+  releaseOwnership?: () => unknown | Promise<unknown>;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
+interface ArtifactInspection {
+  source: TelegramRuntimeArtifactKind;
+  corrupt?: TelegramRuntimeCorruptArtifact;
+  ownerPids: number[];
+}
+
+const OWNER_FILE_PATTERN = /^owner\.([A-Za-z0-9-]+)\.json$/u;
+const RECLAIM_FILE_PATTERN =
+  /^owner\.reclaim\.(\d+)\.([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.json$/u;
+
+function corruption(
+  kind: TelegramRuntimeArtifactKind,
+  path: string,
+  reason: string,
+): ArtifactInspection {
+  return { source: kind, corrupt: { kind, path, reason }, ownerPids: [] };
+}
+
+function inspectOwners(
+  path: string,
+  nowMs: number,
+  staleHeartbeatMs: number,
+): ArtifactInspection {
+  if (!existsSync(path)) return { source: "owners", ownerPids: [] };
+  let value: unknown;
+  try {
+    value = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return corruption("owners", path, "owners.json is not valid JSON");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return corruption("owners", path, "owners.json is not an object");
+  }
+  const ownerPids = Object.values(value).flatMap((candidate) => {
+    const entry = parseTelegramLockEntry(candidate);
+    if (
+      !entry ||
+      (typeof entry.heartbeatMs === "number" &&
+        nowMs - entry.heartbeatMs > staleHeartbeatMs)
+    ) {
+      return [];
+    }
+    return [entry.pid];
+  });
+  return { source: "owners", ownerPids };
+}
+
+function inspectState(path: string): ArtifactInspection {
+  if (!existsSync(path)) return { source: "state", ownerPids: [] };
+  try {
+    JSON.parse(readFileSync(path, "utf8"));
+    return { source: "state", ownerPids: [] };
+  } catch {
+    return corruption("state", path, `${basename(path)} is not valid JSON`);
+  }
+}
+
+function parseTransactionOwner(path: string): number | undefined {
+  const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const pid = (value as Record<string, unknown>).pid;
+  const acquiredAtMs = (value as Record<string, unknown>).acquiredAtMs;
+  const generation = (value as Record<string, unknown>).generation;
+  return typeof pid === "number" &&
+    typeof acquiredAtMs === "number" &&
+    typeof generation === "string"
+    ? pid
+    : undefined;
+}
+
+function inspectTransaction(path: string): ArtifactInspection {
+  if (!existsSync(path)) return { source: "transaction", ownerPids: [] };
+  try {
+    const stat = lstatSync(path);
+    let ownerPath: string;
+    let expectedOwnerPid: number | undefined;
+    if (stat.isDirectory()) {
+      const entries = readdirSync(path);
+      if (entries.length !== 1) {
+        return corruption(
+          "transaction",
+          path,
+          "transaction guard has an unverifiable directory shape",
+        );
+      }
+      const entry = entries[0];
+      const ownerMatch = OWNER_FILE_PATTERN.exec(entry);
+      const reclaimMatch = RECLAIM_FILE_PATTERN.exec(entry);
+      if (!ownerMatch && !reclaimMatch) {
+        return corruption(
+          "transaction",
+          path,
+          "transaction guard has an unrecognized owner marker",
+        );
+      }
+      ownerPath = join(path, entry);
+      expectedOwnerPid = reclaimMatch ? Number(reclaimMatch[1]) : undefined;
+      const ownerPid = parseTransactionOwner(ownerPath);
+      if (ownerPid === undefined) {
+        return corruption(
+          "transaction",
+          path,
+          "transaction guard owner metadata is invalid",
+        );
+      }
+      if (ownerMatch) {
+        const value = JSON.parse(readFileSync(ownerPath, "utf8")) as Record<
+          string,
+          unknown
+        >;
+        if (value.generation !== ownerMatch[1]) {
+          return corruption(
+            "transaction",
+            path,
+            "transaction guard generation does not match its owner marker",
+          );
+        }
+      }
+      return {
+        source: "transaction",
+        ownerPids: [expectedOwnerPid ?? ownerPid],
+      };
+    }
+    if (!stat.isFile()) {
+      return corruption(
+        "transaction",
+        path,
+        "transaction guard has an unsupported filesystem type",
+      );
+    }
+    ownerPath = path;
+    const ownerPid = parseTransactionOwner(ownerPath);
+    return ownerPid === undefined
+      ? corruption(
+          "transaction",
+          path,
+          "legacy transaction guard owner metadata is invalid",
+        )
+      : { source: "transaction", ownerPids: [ownerPid] };
+  } catch {
+    return corruption(
+      "transaction",
+      path,
+      "transaction guard cannot be inspected",
+    );
+  }
+}
+
+/**
+ * Classify disposable runtime corruption without mutating any artifact.
+ *
+ * Corruption remains recoverable only when neither owners.json nor a
+ * verifiable transaction marker identifies a process that is still alive.
+ */
+export function classifyTelegramRuntimeRecovery(
+  options: TelegramRuntimeRecoveryClassificationOptions,
+): TelegramRuntimeRecoveryClassification {
+  const transactionPath =
+    options.transactionPath ?? `${options.ownersPath}.transaction`;
+  const inspections = [
+    inspectOwners(
+      options.ownersPath,
+      options.nowMs ?? Date.now(),
+      options.staleHeartbeatMs ?? TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS,
+    ),
+    ...(options.statePaths ?? []).map(inspectState),
+    inspectTransaction(transactionPath),
+  ];
+  const artifacts = inspections.flatMap((inspection) =>
+    inspection.corrupt ? [inspection.corrupt] : [],
+  );
+  if (artifacts.length === 0) return { kind: "clean" };
+
+  const processAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  const ignoredTransactionPids = new Set(
+    options.ignoredTransactionPids ?? [],
+  );
+  const livePids = [
+    ...new Set(
+      inspections.flatMap((inspection) =>
+        inspection.ownerPids.filter(
+          (pid) =>
+            !(
+              inspection.source === "transaction" &&
+              ignoredTransactionPids.has(pid)
+            ) && processAlive(pid),
+        ),
+      ),
+    ),
+  ].sort((left, right) => left - right);
+  return livePids.length > 0
+    ? { kind: "blocked-live-owner", artifacts, livePids }
+    : { kind: "recoverable-corruption", artifacts };
+}
+
+/**
+ * Quarantine classifier-approved disposable corruption under two guards.
+ *
+ * A dedicated recovery transaction serializes recoverers. The ownership
+ * transaction then prevents a new Telegram owner from appearing between the
+ * final classification and mutation. Every artifact is renamed within its
+ * filesystem; durable config and diagnostics never enter the candidate set.
+ */
+export function recoverTelegramRuntimeState(
+  options: TelegramRuntimeRecoveryOptions,
+): TelegramRuntimeRecoveryResult {
+  const pid = options.pid ?? process.pid;
+  const transactionPath =
+    options.transactionPath ?? `${options.ownersPath}.transaction`;
+  const recoveryTransactionPath =
+    options.recoveryTransactionPath ??
+    join(dirname(options.ownersPath), "runtime-recovery.transaction");
+  const quarantineRoot =
+    options.quarantineRoot ?? join(dirname(options.ownersPath), "recovery");
+  const classificationOptions = {
+    ownersPath: options.ownersPath,
+    statePaths: options.statePaths,
+    transactionPath,
+    isProcessAlive: options.isProcessAlive,
+    nowMs: options.nowMs ?? options.getNowMs?.(),
+    staleHeartbeatMs: options.staleHeartbeatMs,
+  } satisfies TelegramRuntimeRecoveryClassificationOptions;
+
+  return withTelegramFileTransaction(
+    recoveryTransactionPath,
+    () => {
+      const initial = classifyTelegramRuntimeRecovery(classificationOptions);
+      if (initial.kind === "clean") return { kind: "not-needed" };
+      if (initial.kind === "blocked-live-owner") {
+        return {
+          kind: "blocked-live-owner",
+          livePids: initial.livePids,
+        };
+      }
+
+      let quarantineDir: string | undefined;
+      const recoveredArtifacts: TelegramRuntimeCorruptArtifact[] = [];
+      const ensureQuarantineDir = (): string => {
+        if (quarantineDir) return quarantineDir;
+        quarantineDir = join(
+          quarantineRoot,
+          `${options.getNowMs?.() ?? Date.now()}-${pid}-${randomUUID()}`,
+        );
+        mkdirSync(quarantineDir, { recursive: true, mode: 0o700 });
+        return quarantineDir;
+      };
+      const quarantineArtifact = (
+        artifact: TelegramRuntimeCorruptArtifact,
+      ): void => {
+        if (!existsSync(artifact.path)) return;
+        const destination = join(ensureQuarantineDir(), basename(artifact.path));
+        if (
+          renameTelegramPathWithRetry(artifact.path, destination, {
+            rename: options.quarantineRename,
+            retryDelayMs: options.quarantineRenameRetryDelayMs,
+          })
+        ) {
+          recoveredArtifacts.push(artifact);
+        }
+      };
+
+      for (const artifact of initial.artifacts) {
+        if (artifact.kind === "transaction") quarantineArtifact(artifact);
+      }
+
+      return withTelegramFileTransaction(
+        transactionPath,
+        () => {
+          const current = classifyTelegramRuntimeRecovery({
+            ...classificationOptions,
+            ignoredTransactionPids: [process.pid],
+          });
+          if (current.kind === "blocked-live-owner") {
+            return {
+              kind: "blocked-live-owner",
+              livePids: current.livePids,
+              quarantineDir,
+            };
+          }
+          if (current.kind === "recoverable-corruption") {
+            for (const artifact of current.artifacts) {
+              if (artifact.kind !== "transaction") quarantineArtifact(artifact);
+            }
+          }
+          return recoveredArtifacts.length > 0 && quarantineDir
+            ? {
+                kind: "recovered",
+                artifacts: recoveredArtifacts,
+                quarantineDir,
+              }
+            : { kind: "not-needed" };
+        },
+        options.transactionOptions,
+      );
+    },
+    options.transactionOptions,
+  );
+}
+
+/** Build the `/telegram-connect` recovery boundary around runtime artifacts. */
+export function createTelegramPollingStartRecoveryHandler(
+  deps: TelegramPollingStartRecoveryHandlerDeps,
+): () => Promise<TelegramPollingStartRecoveryDecision> {
+  return async () => {
+    const ownersPath = deps.getOwnersPath();
+    const statePaths = deps.getStatePaths();
+    const classification = classifyTelegramRuntimeRecovery({
+      ownersPath,
+      statePaths,
+    });
+    if (classification.kind === "clean") return { kind: "unhandled" };
+    if (classification.kind === "blocked-live-owner") {
+      return {
+        kind: "blocked",
+        message: `Telegram temporary state is damaged, but owner process ${classification.livePids.join(", ")} is still live. Restart that Pi instance, then run /telegram-connect again.`,
+      };
+    }
+
+    try {
+      await deps.suspendPolling();
+    } catch (error) {
+      deps.recordRuntimeEvent?.("recovery", error, {
+        phase: "suspend-before-reset",
+      });
+      return {
+        kind: "blocked",
+        message:
+          "Telegram polling could not stop safely, so temporary state was not reset. Restart this Pi instance and run /telegram-connect again.",
+      };
+    }
+    try {
+      await deps.releaseOwnership?.();
+    } catch (error) {
+      deps.recordRuntimeEvent?.("recovery", error, {
+        phase: "release-before-reset",
+      });
+    }
+    try {
+      const recovery = recoverTelegramRuntimeState({
+        ownersPath,
+        statePaths,
+      });
+      if (recovery.kind === "blocked-live-owner") {
+        return {
+          kind: "blocked",
+          message: `Telegram temporary state changed during recovery and is now protected by owner process ${recovery.livePids.join(", ")}. Restart that Pi instance, then run /telegram-connect again.`,
+        };
+      }
+      return {
+        kind: "retry",
+        message:
+          recovery.kind === "recovered"
+            ? "Telegram temporary state was damaged after an unclean shutdown and has been reset."
+            : "Telegram temporary state was recovered by another Pi instance.",
+      };
+    } catch (error) {
+      deps.recordRuntimeEvent?.("recovery", error, { phase: "runtime-reset" });
+      return {
+        kind: "blocked",
+        message:
+          "Telegram temporary-state recovery failed. Restart this Pi instance and run /telegram-connect again.",
+      };
+    }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.24.4",
+  "version": "0.24.6",
   "private": false,
   "publishConfig": {
     "access": "public"