@llblab/pi-telegram 0.20.3 → 0.20.4

package/AGENTS.md

@@ -79,12 +79,12 @@ The core product loop is mobile continuation: start or supervise work in the ter
 - 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. 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 itself and force-acquire transport leadership so the organism degrades forward instead of staying split-brain. 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 explicit disconnect 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` is a manual thread teardown: a leader deletes its own bound thread before releasing transport ownership, while a follower asks the leader to delete its assigned thread through scoped bus API before unregistering. 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.
 - Runtime routing binds to a live `instanceId`; current thread identity should use explicit owner records (`leader`, `manual-follower`, `pending-topic`) rather than hiding ownership direction in legacy string keys. Compatibility keys may be derived internally, but stale session records must not be treated as live owners. A live instance owns at most one active bound thread; provisioning a new target for the same `instanceId` must remove older current-state bindings and close duplicate Telegram threads when possible. A reload creates a new runtime `instanceId`; if the previous leader slot is still known/alive, keep it occupied in reservations and assign the new leader the next free slot instead of creating a duplicate same-letter tab or blocking startup on Telegram UI convergence.
 - Follower registration readiness should stay on the smallest critical path that makes the follower routable: create or reuse the Telegram target, persist the active binding, mark target-bindings fresh, and return the target to the follower. Manual follower identity must survive a Pi process reload in the same terminal so reload is not treated as a new follower/thread; do not key durable follower ownership only by the short-lived Pi process id. Telegram-visible connected notices, duplicate/replaced thread cleanup, and other reconciliation work are important but non-critical; run them after registration and record slow/failing background steps as runtime events rather than delaying follower usability.
-- Instance slots are extension-owned ring-order metadata. Allocate fresh slots from the `bot.lastSlot` cursor as `A` → `B` → ... → `Z` → `A`, allowing the cursor to move to lower letters after wraparound. Only current live/recovering bindings plus unexpired pending provisions and explicit reservations occupy slots; historical records must not block allocation indefinitely. Preserve a slot on ordinary current binding/thread reuse without advancing or rewinding the fresh-allocation cursor. Follower bindings may survive through a bounded leader-reload re-registration grace window. Successful target reuse must refresh the binding timestamp, and post-reload compaction must preserve a recently refreshed binding across the brief registry gap caused by follower session replacement; older records without a live owner leave current `state.json` without implying destructive Telegram thread deletion. When post-grace follower compaction removes the binding represented by `bot.lastSlot`, realign the cursor to the newest-created remaining live binding in the same reconciliation pass; preserve a cursor that still belongs to a live binding and continue skipping unexpired pending/reserved slots. Do not reinterpret an otherwise orphaned cursor outside compaction because normal thread deletion may intentionally preserve ring sequence. The alphabet cap is a feature — compact single-letter tabs are scannable.
-- Instance thread names are provisioner-authored identity metadata, not model-authored output. Fresh Threaded Mode threads select one of five curated compact 4-6 letter Latin names for the assigned slot letter using provisioning timestamp entropy, then create the Telegram thread with that thread name immediately. The title is the thread name itself, not `{slot} {threadName}` or `{slot} — {threadName}`. Do not register or reintroduce an agent-facing thread rename tool; removing the extra rename prompt/tool turn is an intentional simplicity constraint. Thread names must mirror into terminal status and live diagnostics from the bound thread record; do not hide a valid baked/custom thread name behind old slot-prefix validation. A follower that later becomes leader keeps its existing name; leadership changes are transport role changes, not identity resets.
+- Instance slots are extension-owned ring-order metadata. Allocate fresh slots from the `bot.lastSlot` cursor as `A` → `B` → ... → `Z` → `A`, allowing the cursor to move to lower letters after wraparound. Only current live/recovering bindings plus unexpired pending provisions and explicit reservations occupy slots; historical records must not block allocation indefinitely. Preserve a slot on ordinary current binding/thread reuse without advancing or rewinding the fresh-allocation cursor. Follower bindings may survive through a bounded leader-reload re-registration grace window. Successful target reuse must refresh the binding timestamp, and post-reload compaction must preserve a recently refreshed binding across the brief registry gap caused by follower session replacement; older records without a live owner leave current `state.json` without implying destructive Telegram thread deletion. An authenticated live follower whose carried exact target is missing from current persisted bindings should recover that target instead of creating another Telegram thread; preserve a carried slot only when it does not collide with another current record. When post-grace follower compaction removes the binding represented by `bot.lastSlot`, realign the cursor to the newest-created remaining live binding in the same reconciliation pass; preserve a cursor that still belongs to a live binding and continue skipping unexpired pending/reserved slots. Do not reinterpret an otherwise orphaned cursor outside compaction because normal thread deletion may intentionally preserve ring sequence. The alphabet cap is a feature — compact single-letter tabs are scannable.
+- Instance thread names are provisioner-authored identity metadata, not model-authored output. Fresh Threaded Mode threads select one of five curated compact 4-6 letter Latin names for the assigned slot letter using provisioning timestamp entropy, then create the Telegram thread with that thread name immediately. The title is the thread name itself, not `{slot} {threadName}` or `{slot} — {threadName}`. Do not register or reintroduce an agent-facing thread rename tool; removing the extra rename prompt/tool turn is an intentional simplicity constraint. Thread names must mirror into terminal status, live diagnostics, and `[telegram|thread:name]` through one target-aware current-instance identity resolver. Registered follower/leader metadata takes precedence over a stale shared record for the same target, with the record used only as fallback; do not hide a valid baked/custom thread name behind old slot-prefix validation. A follower that later becomes leader keeps its existing name; leadership changes are transport role changes, not identity resets.
 - Telegram private-chat Threaded Mode treats `All` as an aggregate/control surface, not a durable `General` thread and not a process launcher. Leader activation creates/reuses a leader thread in the private bot DM (chat = allowedUserId) proactively. If all threads are closed and the owner writes from `All`, a first new unbound thread should be reclaimed by the leader when the leader lacks an active bound thread. Later unknown threads require explicit routing or restore; creating another Pi instance is a manual terminal action followed by `/telegram-connect`.
 - Unbound thread detection: when a message arrives from the owner in an unknown `message_thread_id` while Threaded Mode is active, the default runtime first reclaims it for the leader if the leader has no active bound thread and routes the prompt locally. Later unknown threads are preserved by default and receive an in-thread reroute chooser that can send the captured prompt to a live thread or restore a stale leader/follower binding through explicit restore actions; destructive cleanup happens only after explicit user confirmation and through `thread-reconciler`. If the operator wants another Pi instance, they start Pi in a terminal and run `/telegram-connect`; Telegram-originated hidden auto-spawn and `/thread`-style process launch flows are intentionally absent. If Threaded Mode is unavailable, the message is processed normally through classic routing.
 - Telegram extension work should not hold Pi's core agent lifecycle hostage once Pi has produced the semantic result. For Telegram-originated turns, final Telegram delivery, attachment upload, and transport cleanup are extension-owned side effects; schedule them off the critical `agent_end` path when ordering can still be preserved, record failures as runtime events, and keep dispatch of the next Telegram turn behind the delivery task when needed to avoid interleaving previews/finals.
-- Telegram runtime state should be treated as event-driven reconciliation of extension assumptions against observable Telegram signals, not as a full Telegram bot read-model and not as a reason to query Telegram on every action. Keep a local assumption model for bot identity/capabilities, pairing assumptions, thread support, known thread lifecycle, bound instance targets, reservations, and transport health. Invalidate and reconcile the relevant slice on meaningful events: startup/reload, lifecycle service messages, stale-send/API errors, setup/pairing changes, follower register/prune, explicit status/debug requests, and bounded low-frequency leader health ticks. `lib/sync.ts` owns sync slices, observation intake, invalidation triggers, status/debug freshness, and reconciliation scheduling; it must not promise complete bot-state mirroring because Bot API lacks a complete topic listing surface. `lib/thread-reconciler.ts` owns pure Threaded Mode lifecycle planning and should become the only policy authority for destructive thread cleanup decisions. `threads` owns current Telegram UI thread/tab binding primitives and thread-name helpers mapped to Bot API topic transport, `status` renders projections, and `index.ts` only wires ports. `tmp/telegram/logs.jsonl` is a session-local redacted runtime evidence stream for race debugging and resets on extension start / runtime scope changes; it is diagnostics only, not routing/provisioning authority. `state.json` should be an observable/debug snapshot aligned with `/telegram-status` (extension runtime, bot capabilities including `bot.lastSlot`, runtime role, live roster projection, reservations, diagnostics), not routing/provisioning authority. Live bus/runtime state is authoritative; file reservations and fresh capability observations may be startup hints/collision guards only; stale snapshots must re-probe before suppressing bus/topic behavior. Do not persist stale/offline/failed thread target history as source of truth.
+- Telegram runtime state should be treated as event-driven reconciliation of extension assumptions against observable Telegram signals, not as a full Telegram bot read-model and not as a reason to query Telegram on every action. Keep a local assumption model for bot identity/capabilities, pairing assumptions, thread support, known thread lifecycle, bound instance targets, reservations, and transport health. Invalidate and reconcile the relevant slice on meaningful events: startup/reload, lifecycle service messages, stale-send/API errors, setup/pairing changes, follower register/prune, explicit status/debug requests, and bounded low-frequency leader health ticks. `lib/sync.ts` owns sync slices, observation intake, invalidation triggers, status/debug freshness, and reconciliation scheduling; it must not promise complete bot-state mirroring because Bot API lacks a complete topic listing surface. `lib/thread-reconciler.ts` owns pure Threaded Mode lifecycle planning and should become the only policy authority for destructive thread cleanup decisions. `threads` owns current Telegram UI thread/tab binding primitives and thread-name helpers mapped to Bot API topic transport, `status` renders projections, and `index.ts` only wires ports. `tmp/telegram/logs.jsonl` is a session-local redacted runtime evidence stream for race debugging and resets on extension start / runtime scope changes; it is diagnostics only, not routing/provisioning authority. `state.json` should be an observable/debug snapshot aligned with `/telegram-status` (extension runtime, bot capabilities including `bot.lastSlot`, runtime role, live roster projection, reservations, diagnostics), not routing/provisioning authority. Because every process on one Telegram profile shares this file, only the active transport lock owner may persist it; followers read current state and gain write authority only after promotion. Status-only writes must refresh disk-backed bindings before serialization so a stale loaded snapshot cannot erase newer leader state. Live bus/runtime state is authoritative; file reservations and fresh capability observations may be startup hints/collision guards only; stale snapshots must re-probe before suppressing bus/topic behavior. Do not persist stale/offline/failed thread target history as source of truth.
 - Thread bindings are bidirectional. From the Pi-instance side, an instance knows and preserves its target, slot, thread name, lifecycle state, and direct-delivery defaults. From the Telegram-client/bot side, the bridge observes thread creation/close/reopen/stale-send signals and reconciles them into instance binding state. Lifecycle transitions that affect operator understanding should be Telegram-visible when a live transport remains: every successful follower registration/re-registration gets a compact connected notice in the assigned thread, while heartbeat pruning stays silent because it is only liveness suspicion. These notices should use the instance thread name when known and fall back to the slot letter only while the thread is still unnamed. New unknown threads (owner writing in `All`) are preserved until the user explicitly chooses a reroute/restore/new-instance action that makes cleanup eligible; any destructive cleanup must go through `thread-reconciler`. Unknown `forum_topic_created` service events are observations, not destructive cleanup proof.
 - The multi-instance bus uses private bot DMs with Telegram private-chat Threaded Mode enabled for the bot. No supergroup, group, or forum configuration is needed; the thread chat is always the private chat with the paired owner. Threaded capability checks must use bot/private-chat evidence such as `getMe.has_topics_enabled`, incoming `message_thread_id`, and topic operation success/failure; do not use group chat metadata as the control-plane truth for Telegram private-chat Threaded Mode.
 - Target-scoped behavior must preserve `{ chatId, threadId? }` through inbound messages/edits/callbacks/reactions, thread lifecycle service messages, media and split-text grouping, queue mutations, active-turn cleanup, previews, reply deduplication, menus, sections, generated buttons, voice, attachments, and direct delivery. Threaded Mode replies must keep Telegram's reply affordance to the triggering message just like classic DM mode. In Telegram private-chat Threaded Mode, mobile Telegram has been live-verified to render `sendMessage` replies that include top-level `message_thread_id` plus same-chat `reply_parameters.message_id`; Telegram Desktop may fail to show the visual reply header for the same correct payload, so do not treat Desktop-only absence as bridge failure without mobile/payload evidence.

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.20.4: Thread State Ownership Hotfix
+
+- `[State Ownership]` Made the active transport lock owner the only process allowed to persist the profile-shared `state.json`; followers remain readers and acquire write authority only after promotion. Status-only persistence now refreshes disk-backed bindings before serialization. Impact: a stale follower diagnostics snapshot cannot erase newer leader-owned bindings, produce duplicate slot occupancy, or make a live follower disappear from current thread state.
+- `[Follower Recovery]` Followers now carry target, slot, and thread name during re-registration. When an authenticated live follower carries an exact target missing from persisted bindings, the leader recovers that target without creating another Telegram thread and restores its slot only when unoccupied; a matching previous live-roster observation can recover the name for an older follower runtime. Impact: damaged local state converges around the surviving Telegram tab instead of replacing it or preserving a duplicate letter.
+- `[Thread Identity]` Unified terminal status and `[telegram|thread:name]` behind one target-aware current-instance identity resolver. Registered follower/leader metadata takes precedence over a stale shared record for the same target, with persisted state used only as fallback. Impact: when the prompt tag correctly identifies `Beacon`, terminal status can no longer regress to a previous thread name from stale state.
+- `[Live Linux]` A clean same-directory bootstrap produced one leader and two followers with exact unique bindings `A / Aster / 524667`, `B / Beacon / 524669`, and `C / Cinder / 524671`; the live roster and persisted targets agreed without duplicate slots. Impact: multiple processes launched from the same cwd no longer expose the state-writer collision that originally duplicated slot `E`.
+- `[Validation]` Added deterministic coverage for stale status writers, denied follower writes, promotion-time write authority, carried identity metadata, exact live-target recovery, collision-safe slot recovery, and status/prompt identity convergence. The full release validation passes with one platform-only named-pipe skip. Impact: the original corruption and cross-surface mismatch scenarios are release-gated.
+
 ## 0.20.3: Persistent Threads And Activity
 
 - `[Follower Sessions]` Registered followers now snapshot their target, slot, and thread name before same-process Pi session replacement, stop the old receiver/heartbeat context, and automatically re-register the new session through the live leader. Impact: `/new` and `/reload` no longer intentionally leave a healthy follower disconnected or require another manual `/telegram-connect`.

package/docs/architecture.md

@@ -124,7 +124,7 @@ Named Telegram profiles are orthogonal to Threaded Mode. The selected profile ch
 
 Profile reality follows three explicit storage classes. `telegram.json` shared settings and extension registries are process-global platform configuration; profile bot/session fields and observable transport/routing authority are profile-scoped; queues, active turns, ownership caches, menu state, and runtime controllers are session-local memory. Downloaded attachments use UUID-prefixed names in the shared Telegram scratch directory and are session artifacts rather than identity or routing authority, so cross-profile cleanup is limited to stale scratch files and cannot redirect live traffic.
 
-When Threaded Mode is active, the current polling owner is also the Telegram bus leader. The leader owns the local bus endpoint (Unix-domain socket on Unix-like platforms, named pipe on native Windows), polls `getUpdates`, performs direct Bot API calls, records follower heartbeats, prunes stale followers, and provisions Telegram UI thread targets through live runtime/bus state. Follower liveness is intentionally fast because heartbeat traffic is local IPC: followers heartbeat every `1s`, the leader treats them as stale after `2s`, and the prune loop runs every `1s` so stopped followers are detected promptly while active forwarded updates/API calls still refresh liveness. Heartbeat pruning is silent liveness bookkeeping: it preserves the follower thread binding and does not send a Telegram-visible disconnected notice, because the common cause may be leader reload or IPC handoff rather than a dead follower. Successful follower target reuse refreshes the binding's recovery timestamp; post-leader-reload compaction preserves that recently refreshed binding across a brief follower session-replacement registry gap, while genuinely historical records still leave current state after grace. `tmp/telegram/logs.jsonl` is a session-local redacted runtime evidence stream for race debugging; it resets on extension start and runtime scope changes, and must not become routing/provisioning authority. `tmp/telegram/state.json` is an extension+bot observable/debug snapshot aligned with status diagnostics: `source: "snapshot"` and `writtenAtMs` mark it as observational, not authoritative. Fresh capability observations may skip redundant startup probes, but stale snapshots re-probe before suppressing bus/thread behavior. Top-level `bot` mirrors bot-wide capabilities such as thread mode, `runtime` describes process role/status, `liveRoster` mirrors followers/current targets/reservations, `diagnostics` mirrors recent status/debug signals including the latest thread-reconciler phase/counts, `threads` stores current routeable bindings, TTL-bounded reservations explain short-lived slot collision guards, and TTL-pruned `pendingProvisions` protects in-flight topic creation slots from cleanup/allocation races. Fresh provisioning writes pending state before the Bot API create call, adds the returned target to the pending record, persists a `starting` binding, then promotes it to `active` and clears pending state. If final binding persistence fails after Telegram returns a thread id, the targeted pending provision remains as cleanup/retry evidence. Once targeted pending provisions expire, they are retained for `thread-reconciler` close/delete cleanup and pending scratchpad removal after a successful cleanup apply; untargeted expired pending records can prune without cleanup because no Telegram thread id exists. Runtime events coalesce status-snapshot writes so transient bus/API/update failures remain inspectable even when the operator has not opened `/telegram-status`. The bridge must not keep a durable `telegram-targets.json` target history; stale/offline/failed thread observations are pruned instead of reused. Previous-process leader bindings that still probe alive become reservations/collision guards, not routeable active threads, so a reloaded leader can take the next free slot without duplicating the same visible tab name. The thread chat is always the private bot DM with the paired owner (`allowedUserId`). In Telegram private-chat Threaded Mode, the leader creates/reuses its own thread before polling — it is a real bound instance, not a dispatcher. Followers authenticate bus envelopes with the leader-minted capability secret stored in the active lock entry. Leader lock entries also carry a stable `leaderEpoch` minted on acquisition and preserved across heartbeat refreshes; leader-owned cleanup/provisioning plans stamp that epoch, and Thread Reconciler apply skips destructive work if leadership has moved on before side effects run. Followers own their own Pi session state, queue, active turns, previews, menus, and lifecycle hooks, but route allowlisted, target-scoped Telegram API calls through the leader. When a follower promotes after heartbeat loss, status/state diagnostics expose only the transient `electing` lifecycle phase; stable `leader`/`follower` identity stays in the bus role so diagnostics do not duplicate role state. The TUI status bar and `/telegram-status` report `leader` or `follower` role so a registered follower is not shown as generically disconnected.
+When Threaded Mode is active, the current polling owner is also the Telegram bus leader. The leader owns the local bus endpoint (Unix-domain socket on Unix-like platforms, named pipe on native Windows), polls `getUpdates`, performs direct Bot API calls, records follower heartbeats, prunes stale followers, and provisions Telegram UI thread targets through live runtime/bus state. Follower liveness is intentionally fast because heartbeat traffic is local IPC: followers heartbeat every `1s`, the leader treats them as stale after `2s`, and the prune loop runs every `1s` so stopped followers are detected promptly while active forwarded updates/API calls still refresh liveness. Heartbeat pruning is silent liveness bookkeeping: it preserves the follower thread binding and does not send a Telegram-visible disconnected notice, because the common cause may be leader reload or IPC handoff rather than a dead follower. Successful follower target reuse refreshes the binding's recovery timestamp; post-leader-reload compaction preserves that recently refreshed binding across a brief follower session-replacement registry gap, while genuinely historical records still leave current state after grace. If an authenticated live follower carries an exact target that is absent from current bindings, the leader recovers that target without creating a replacement Telegram thread; a carried slot is restored only when it is not already occupied. `tmp/telegram/logs.jsonl` is a session-local redacted runtime evidence stream for race debugging; it resets on extension start and runtime scope changes, and must not become routing/provisioning authority. `tmp/telegram/state.json` is an extension+bot observable/debug snapshot aligned with status diagnostics: `source: "snapshot"` and `writtenAtMs` mark it as observational, not authoritative. All instances on one Telegram profile read the same snapshot, but only the active transport lock owner persists it; followers become writers only after promotion. Status-only persistence reloads current disk bindings before serialization, preventing a stale follower/status view from erasing newer leader-owned targets. Fresh capability observations may skip redundant startup probes, but stale snapshots re-probe before suppressing bus/thread behavior. Top-level `bot` mirrors bot-wide capabilities such as thread mode, `runtime` describes process role/status, `liveRoster` mirrors followers/current targets/reservations, `diagnostics` mirrors recent status/debug signals including the latest thread-reconciler phase/counts, `threads` stores current routeable bindings, TTL-bounded reservations explain short-lived slot collision guards, and TTL-pruned `pendingProvisions` protects in-flight topic creation slots from cleanup/allocation races. Fresh provisioning writes pending state before the Bot API create call, adds the returned target to the pending record, persists a `starting` binding, then promotes it to `active` and clears pending state. If final binding persistence fails after Telegram returns a thread id, the targeted pending provision remains as cleanup/retry evidence. Once targeted pending provisions expire, they are retained for `thread-reconciler` close/delete cleanup and pending scratchpad removal after a successful cleanup apply; untargeted expired pending records can prune without cleanup because no Telegram thread id exists. Runtime events coalesce status-snapshot writes so transient bus/API/update failures remain inspectable even when the operator has not opened `/telegram-status`. The bridge must not keep a durable `telegram-targets.json` target history; stale/offline/failed thread observations are pruned instead of reused. Previous-process leader bindings that still probe alive become reservations/collision guards, not routeable active threads, so a reloaded leader can take the next free slot without duplicating the same visible tab name. The thread chat is always the private bot DM with the paired owner (`allowedUserId`). In Telegram private-chat Threaded Mode, the leader creates/reuses its own thread before polling — it is a real bound instance, not a dispatcher. Followers authenticate bus envelopes with the leader-minted capability secret stored in the active lock entry. Leader lock entries also carry a stable `leaderEpoch` minted on acquisition and preserved across heartbeat refreshes; leader-owned cleanup/provisioning plans stamp that epoch, and Thread Reconciler apply skips destructive work if leadership has moved on before side effects run. Followers own their own Pi session state, queue, active turns, previews, menus, and lifecycle hooks, but route allowlisted, target-scoped Telegram API calls through the leader. When a follower promotes after heartbeat loss, status/state diagnostics expose only the transient `electing` lifecycle phase; stable `leader`/`follower` identity stays in the bus role so diagnostics do not duplicate role state. The TUI status bar and `/telegram-status` report `leader` or `follower` role so a registered follower is not shown as generically disconnected. Terminal status identity and the `[telegram|thread:name]` prompt label use the same target-aware current-instance resolver: registered local metadata wins over a stale shared binding for the matching target, while the binding remains a fallback for partial metadata.
 
 Follower binding is manual and process-first: the operator starts another Pi process, then runs `/telegram-connect`; only then does that process register as a follower with an instance-scoped internal binding identity and cause the leader to create/reuse a thread for it. Telegram does not expose `/thread`, auto-spawn arbitrary unbound threads, or launch hidden follower subprocesses. In Threaded Mode, `/telegram-connect` does not offer manual takeover while a live leader exists; takeover is reserved for stale-leader election/recovery. Leadership remains an ephemeral transport role that another live follower can take over after stale heartbeat detection.
 

package/docs/multi-instance-bus.md

@@ -155,7 +155,7 @@ Leader election is heartbeat-gated and lock-backed:
 4. If the leader heartbeat is stale, attempt an atomic leadership takeover; ordinary `/telegram-connect` on a follower is not a leadership move while the leader is live.
 5. If several followers detect stale leadership, atomic compare/write lock acquisition ensures only one becomes leader.
 
-Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target so the new leader can reuse the same binding, then promote only after the grace window expires. Every successful reuse refreshes the binding timestamp. The leader does not restore persisted followers into the live registry speculatively: after a bounded re-registration grace window it removes older follower records that still lack a live bus owner from current `state.json`, while preserving a recently refreshed binding across the brief registry gap caused by follower session replacement and never deleting Telegram tabs. This preserves real thread bindings through transient reload gaps without allowing historical records or competing pollers to masquerade as live state.
+Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding, then promote only after the grace window expires. If the exact live target is absent from persisted bindings, the leader recovers it instead of creating another Telegram thread and keeps its carried slot only when that slot is free. Every successful reuse refreshes the binding timestamp. The leader does not restore persisted followers into the live registry speculatively: after a bounded re-registration grace window it removes older follower records that still lack a live bus owner from current `state.json`, while preserving a recently refreshed binding across the brief registry gap caused by follower session replacement and never deleting Telegram tabs. This preserves real thread bindings through transient reload gaps without allowing historical records or competing pollers to masquerade as live state.
 
 ## Leader/Follower Communication
 
@@ -346,10 +346,10 @@ Rules:
 Current state under the agent dir:
 
 - `locks.json`: current bus leader identity, capability secret, heartbeat, and cleanup fencing epoch. The local bus endpoint is derived from the agent directory by default; legacy `busSocketPath` entries are tolerated but are not required.
-- `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. 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.
+- `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 lock 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 use `tmp/telegram/bus.sock` and `tmp/telegram/followers/*`; native Windows uses deterministic named pipes under `\\.\pipe\pi-telegram-...`. These are transient IPC endpoints, not durable routing state.
 
-The bridge must not keep a durable `telegram-targets.json` history. Stale/offline/failed thread entries are reconciliation observations, not reusable source-of-truth state; persisting them increases collision risk. `sync` is event-driven assumption reconciliation, not full Telegram bot-state mirroring, because Bot API does not expose a complete topic/thread listing surface. `state.json` therefore exists for extension+bot observability, diagnostics, startup hints, and explaining reconciliation decisions; live bus/runtime state remains authoritative for routing and provisioning. 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. 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.
+The bridge must not keep a durable `telegram-targets.json` history. Stale/offline/failed thread entries are reconciliation observations, not reusable source-of-truth state; persisting them increases collision risk. `sync` is event-driven assumption reconciliation, not full Telegram bot-state mirroring, because Bot API does not expose a complete topic/thread listing surface. `state.json` therefore exists for extension+bot observability, diagnostics, startup hints, and explaining reconciliation decisions; live bus/runtime state remains authoritative for routing and provisioning. 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

@@ -142,6 +142,9 @@ export default function (pi: Pi.ExtensionAPI) {
   };
   Config.bindGlobalTelegramConfigRuntime(configStore);
   const configControls = Config.createTelegramConfigControls(configStore);
+  let canPersistThreadState = function (): boolean {
+    return false;
+  };
   const threadStore = Threads.createTelegramTopicTargetStore({
     path: function () {
       return Threads.getTelegramTopicTargetsPath(
@@ -149,6 +152,9 @@ export default function (pi: Pi.ExtensionAPI) {
         configStore.getActiveProfileName(),
       );
     },
+    canPersist: function () {
+      return canPersistThreadState();
+    },
   });
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>({
     key: Locks.createTelegramLockKeyResolver(configStore),
@@ -156,6 +162,9 @@ export default function (pi: Pi.ExtensionAPI) {
     busSecret: telegramBusAuthSecret,
     staleHeartbeatMs: Locks.TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS,
   });
+  canPersistThreadState = function (): boolean {
+    return lockRuntime.getState().kind === "active-here";
+  };
   const lockOwnershipGuard =
     Locks.createTelegramLockOwnershipGuard(lockRuntime);
   const getCurrentLeaderEpoch = function (): number | undefined {
@@ -262,6 +271,38 @@ export default function (pi: Pi.ExtensionAPI) {
     }
     return record;
   };
+  const getCurrentInstanceThreadIdentity = function (
+    target?: Queue.TelegramQueueTarget,
+  ): Threads.TelegramInstanceThreadIdentityCandidate {
+    const followerTarget = telegramBusFollowerRegistrationState.getTarget();
+    const record = target
+      ? Threads.findCurrentTelegramInstanceThreadRecord({
+          records: threadStore.list(),
+          instanceId: telegramInstanceId,
+          preferredTarget: target,
+        })
+      : getCurrentThreadRecord();
+    return Threads.resolveTelegramInstanceThreadIdentity({
+      target,
+      follower:
+        telegramBusFollowerRegistrationState.isRegistered() && followerTarget
+          ? {
+              target: followerTarget,
+              slot: telegramBusFollowerRegistrationState.getSlot(),
+              threadName:
+                telegramBusFollowerRegistrationState.getThreadName(),
+            }
+          : undefined,
+      leader: telegramBusLeaderTarget
+        ? {
+            target: telegramBusLeaderTarget,
+            slot: telegramBusLeaderSlot,
+            threadName: telegramBusLeaderThreadName,
+          }
+        : undefined,
+      record,
+    });
+  };
   const statusRuntime = Status.createTelegramBridgeStatusRuntime<
     Pi.ExtensionContext,
     Queue.TelegramQueueItem<Pi.ExtensionContext>
@@ -337,19 +378,11 @@ export default function (pi: Pi.ExtensionAPI) {
     },
     getInstanceSlot() {
       if (threadStore.getBotState().threadMode === "disabled") return undefined;
-      return (
-        getCurrentThreadRecord()?.slot ??
-        telegramBusFollowerRegistrationState.getSlot() ??
-        telegramBusLeaderSlot
-      );
+      return getCurrentInstanceThreadIdentity().slot;
     },
     getInstanceThreadName() {
       if (threadStore.getBotState().threadMode === "disabled") return undefined;
-      return (
-        getCurrentThreadRecord()?.threadName ??
-        telegramBusFollowerRegistrationState.getThreadName() ??
-        telegramBusLeaderThreadName
-      );
+      return getCurrentInstanceThreadIdentity().threadName;
     },
   });
   const { updateStatus: updateStatusLine } = statusRuntime;
@@ -733,19 +766,15 @@ export default function (pi: Pi.ExtensionAPI) {
     },
     getLocalThreadLabelForTarget(target) {
       const followerTarget = telegramBusFollowerRegistrationState.getTarget();
-      if (
+      const isLocalFollowerTarget =
+        telegramBusFollowerRegistrationState.isRegistered() &&
         followerTarget?.chatId === target.chatId &&
-        followerTarget.threadId === target.threadId
-      ) {
-        return telegramBusFollowerRegistrationState.getThreadName();
-      }
-      if (
+        followerTarget.threadId === target.threadId;
+      const isLocalLeaderTarget =
         telegramBusLeaderTarget?.chatId === target.chatId &&
-        telegramBusLeaderTarget.threadId === target.threadId
-      ) {
-        return telegramBusLeaderThreadName;
-      }
-      return undefined;
+        telegramBusLeaderTarget.threadId === target.threadId;
+      if (!isLocalFollowerTarget && !isLocalLeaderTarget) return undefined;
+      return getCurrentInstanceThreadIdentity(target).threadName;
     },
     getCurrentLeaderEpoch,
     getThreadReconciliationMachineState() {

package/lib/bus-follower.ts

@@ -777,6 +777,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
   let activeAuthSecret: string | undefined;
   let activeContext: TContext | undefined;
   let lastKnownTarget: TelegramTarget | undefined;
+  let lastKnownSlot: string | undefined;
+  let lastKnownThreadName: string | undefined;
   const stopHeartbeat = () => {
     if (!heartbeatInterval) return;
     clearInterval(heartbeatInterval);
@@ -788,6 +790,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
     deps.setActiveAuthSecret?.(undefined);
     deps.registrationState?.setRegistered(false);
     lastKnownTarget = undefined;
+    lastKnownSlot = undefined;
+    lastKnownThreadName = undefined;
     activeContext = undefined;
     void deps.stopReceiving?.();
   };
@@ -849,8 +853,13 @@ export function createTelegramBusFollowerRegistrationRuntime<
             deps.getProfileKey?.(ctx) ??
             (ctx.cwd ? `cwd:${ctx.cwd}` : undefined),
           threadName:
+            deps.registrationState?.getThreadName() ??
+            lastKnownThreadName ??
             deps.getThreadName?.(ctx) ??
             (ctx.cwd ? basename(ctx.cwd) : undefined),
+          ...(deps.registrationState?.getSlot() ?? lastKnownSlot
+            ? { slot: deps.registrationState?.getSlot() ?? lastKnownSlot }
+            : {}),
           cwd: ctx.cwd,
           pid: getPid(),
           target:
@@ -912,6 +921,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
           registrationResult,
         );
         lastKnownTarget = registrationResult.target;
+        lastKnownSlot = registrationResult.slot;
+        lastKnownThreadName = registrationResult.threadName;
         activeLeaderSocketPath = leaderSocketPath;
         activeContext = ctx;
         await sendHeartbeat();

package/lib/bus-leader.ts

@@ -477,6 +477,22 @@ export function createTelegramBusFollowerTargetProvisioner(
       : undefined;
     const followerOwner =
       Threads.getTelegramThreadOwnerFromProfileKey(followerProfileKey);
+    const recoverableTarget =
+      !reconnectRecord &&
+      registration.target?.chatId === chatId &&
+      registration.target.threadId !== undefined &&
+      !recordsBeforeProvision.some(
+        (record) =>
+          record.target.chatId === registration.target?.chatId &&
+          record.target.threadId === registration.target.threadId,
+      )
+        ? registration.target
+        : undefined;
+    const recoveryHint = recoverableTarget
+      ? deps.topicTargetStore.getFollowerRecoveryHintByTarget?.(
+          recoverableTarget,
+        )
+      : undefined;
     const registrationKey = followerProfileKey || registration.instanceId;
     const pendingRegistration = pendingRegistrations.get(registrationKey);
     if (pendingRegistration) return pendingRegistration;
@@ -499,12 +515,69 @@ export function createTelegramBusFollowerTargetProvisioner(
         deps.onProvisioningEnd?.();
       }
     };
+    const recoverRequestedTarget = async () => {
+      const nowMs = getNowMs();
+      const requestedThreadName =
+        registration.threadName &&
+        Threads.isTelegramTopicThreadNameValidForSlot(
+          registration.threadName,
+          registration.slot,
+        )
+          ? registration.threadName
+          : recoveryHint?.threadName &&
+              Threads.isTelegramTopicThreadNameValidForSlot(
+                recoveryHint.threadName,
+                recoveryHint.slot,
+              )
+            ? recoveryHint.threadName
+            : undefined;
+      let recoveredRecord = deps.topicTargetStore.upsert({
+        profileKey: followerProfileKey,
+        owner:
+          followerOwner.kind === "manual-follower"
+            ? followerOwner
+            : {
+                kind: "manual-follower",
+                instanceId: registration.instanceId,
+              },
+        target: {
+          chatId: recoverableTarget!.chatId,
+          threadId: recoverableTarget!.threadId!,
+        },
+        status: "active",
+        createdAtMs: registration.connectedAtMs || nowMs,
+        updatedAtMs: nowMs,
+        instanceId: registration.instanceId,
+        ...(requestedThreadName ? { threadName: requestedThreadName } : {}),
+        lastSyncObservedAtMs: nowMs,
+        lastReconcileAction: "follower-live-target-recovery",
+      });
+      const requestedSlot = registration.slot ?? recoveryHint?.slot;
+      const requestedSlotAvailable =
+        !!requestedSlot &&
+        /^[A-Z]$/.test(requestedSlot) &&
+        !recordsBeforeProvision.some((record) => record.slot === requestedSlot);
+      if (requestedSlotAvailable) {
+        recoveredRecord = deps.topicTargetStore.upsert({
+          ...recoveredRecord,
+          slot: requestedSlot,
+        });
+      }
+      await deps.topicTargetStore.persist();
+      return {
+        target: recoveredRecord.target,
+        reused: true,
+        record: recoveredRecord,
+      };
+    };
     const runRegistration = async (): Promise<
       (TelegramTarget & { slot?: string; threadName?: string }) | undefined
     > => {
     let result = reconnectRecord
       ? { target: reconnectRecord.target, reused: true, record: reconnectRecord }
-      : await provisionTarget();
+      : recoverableTarget
+        ? await recoverRequestedTarget()
+        : await provisionTarget();
     if (reconnectRecord) {
       const nowMs = getNowMs();
       const transferredRecord = deps.topicTargetStore.upsert({

package/lib/bus.ts

@@ -98,6 +98,7 @@ export interface TelegramBusInstanceRegistration {
   instanceId: string;
   profileKey?: string;
   threadName?: string;
+  slot?: string;
   cwd?: string;
   pid?: number;
   target?: TelegramTarget;
@@ -1068,6 +1069,9 @@ function parseRegistration(
     registration.profileKey = value.profileKey;
   if (typeof value.threadName === "string")
     registration.threadName = value.threadName;
+  if (typeof value.slot === "string" && /^[A-Z]$/.test(value.slot)) {
+    registration.slot = value.slot;
+  }
   if (typeof value.cwd === "string") registration.cwd = value.cwd;
   if (typeof value.pid === "number") registration.pid = value.pid;
   if (typeof value.busSocketPath === "string") {

package/lib/threads.ts

@@ -183,6 +183,9 @@ export interface TelegramTopicTargetStore {
   load: () => Promise<void>;
   persist: () => Promise<void>;
   list: () => TelegramTopicTargetRecord[];
+  getFollowerRecoveryHintByTarget?: (
+    target: TelegramTarget,
+  ) => { slot?: string; threadName?: string } | undefined;
   listReservations: () => TelegramThreadReservation[];
   listPendingProvisions: () => TelegramThreadPendingProvision[];
   listSyncObservations: () => TelegramTopicSyncObservation[];
@@ -266,6 +269,7 @@ export function reconcileTelegramFreshAllocationCursor(
 export interface TelegramTopicTargetStoreOptions {
   path: string | (() => string);
   getNowMs?: () => number;
+  canPersist?: () => boolean;
 }
 
 export interface TelegramTopicTargetProvisionerDeps {
@@ -869,6 +873,54 @@ function targetMatches(left: TelegramTarget, right: TelegramTarget): boolean {
   return left.chatId === right.chatId && left.threadId === right.threadId;
 }
 
+function getTargetRecoveryHintKey(target: TelegramTarget): string {
+  return `${target.chatId}:${target.threadId ?? "private"}`;
+}
+
+function parseFollowerRecoveryHints(
+  value: unknown,
+): Map<string, { slot?: string; threadName?: string }> {
+  const hints = new Map<string, { slot?: string; threadName?: string }>();
+  if (!value || typeof value !== "object" || Array.isArray(value)) return hints;
+  const liveRoster = (value as Record<string, unknown>).liveRoster;
+  if (!liveRoster || typeof liveRoster !== "object" || Array.isArray(liveRoster))
+    return hints;
+  const followers = (liveRoster as Record<string, unknown>).busFollowers;
+  if (!Array.isArray(followers)) return hints;
+  for (const follower of followers) {
+    if (!follower || typeof follower !== "object" || Array.isArray(follower))
+      continue;
+    const record = follower as Record<string, unknown>;
+    const target = record.target;
+    if (!target || typeof target !== "object" || Array.isArray(target)) continue;
+    const targetRecord = target as Record<string, unknown>;
+    if (typeof targetRecord.chatId !== "number") continue;
+    const normalizedTarget: TelegramTarget = {
+      chatId: targetRecord.chatId,
+      ...(typeof targetRecord.threadId === "number"
+        ? { threadId: targetRecord.threadId }
+        : {}),
+    };
+    const slot =
+      typeof targetRecord.slot === "string" && /^[A-Z]$/.test(targetRecord.slot)
+        ? targetRecord.slot
+        : typeof record.slot === "string" && /^[A-Z]$/.test(record.slot)
+          ? record.slot
+          : undefined;
+    const threadName =
+      typeof targetRecord.threadName === "string"
+        ? targetRecord.threadName
+        : typeof record.threadName === "string"
+          ? record.threadName
+          : undefined;
+    hints.set(getTargetRecoveryHintKey(normalizedTarget), {
+      ...(slot ? { slot } : {}),
+      ...(threadName ? { threadName } : {}),
+    });
+  }
+  return hints;
+}
+
 function getInstanceProcessKey(
   instanceId: string | undefined,
 ): string | undefined {
@@ -905,6 +957,10 @@ export function createTelegramTopicTargetStore(
   let reservations: TelegramThreadReservation[] = [];
   let pendingProvisions: TelegramThreadPendingProvision[] = [];
   let syncObservations: TelegramTopicSyncObservation[] = [];
+  let followerRecoveryHints = new Map<
+    string,
+    { slot?: string; threadName?: string }
+  >();
   let loaded = false;
   let loadedPath: string | undefined;
   let dirty = false;
@@ -939,6 +995,7 @@ export function createTelegramTopicTargetStore(
     reservations = [];
     pendingProvisions = [];
     syncObservations = [];
+    followerRecoveryHints = new Map();
     statusSnapshot = {};
     loaded = false;
     dirty = false;
@@ -955,11 +1012,14 @@ export function createTelegramTopicTargetStore(
       reservations = [];
       pendingProvisions = [];
       syncObservations = [];
+      followerRecoveryHints = new Map();
       loaded = true;
       return;
     }
     const content = await readFile(path, "utf8");
-    const file = parseTopicTargetFile(JSON.parse(content));
+    const rawFile: unknown = JSON.parse(content);
+    const file = parseTopicTargetFile(rawFile);
+    followerRecoveryHints = parseFollowerRecoveryHints(rawFile);
     botState = file.bot;
     records = new Map(
       file.threads.map((record) => [
@@ -993,6 +1053,7 @@ export function createTelegramTopicTargetStore(
       target: { ...observation.target },
     }));
     loaded = true;
+    dirty = false;
   };
 
   return {
@@ -1003,7 +1064,11 @@ export function createTelegramTopicTargetStore(
     async persist() {
       const path = getPath();
       if (loadedPath !== path && !dirty) resetForPath(path);
-      if (!loaded && !dirty) await loadFromDisk();
+      if (options.canPersist && !options.canPersist()) {
+        await loadFromDisk();
+        return;
+      }
+      if (!dirty || !loaded) await loadFromDisk();
       await mkdir(dirname(path), { recursive: true });
       const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
       const nowMs = getNowMs();
@@ -1058,6 +1123,10 @@ export function createTelegramTopicTargetStore(
     list() {
       return Array.from(records.values()).map(cloneRecord);
     },
+    getFollowerRecoveryHintByTarget(target) {
+      const hint = followerRecoveryHints.get(getTargetRecoveryHintKey(target));
+      return hint ? { ...hint } : undefined;
+    },
     listReservations() {
       const nowMs = getNowMs();
       return reservations
@@ -1962,6 +2031,48 @@ export async function provisionOwnBusTopic(
   };
 }
 
+export interface TelegramInstanceThreadIdentityCandidate {
+  target?: TelegramTarget;
+  slot?: string;
+  threadName?: string;
+}
+
+export function resolveTelegramInstanceThreadIdentity(options: {
+  target?: TelegramTarget;
+  follower?: TelegramInstanceThreadIdentityCandidate;
+  leader?: TelegramInstanceThreadIdentityCandidate;
+  record?: TelegramTopicTargetRecord;
+}): TelegramInstanceThreadIdentityCandidate {
+  const targetMatchesCandidate = (
+    candidate: TelegramInstanceThreadIdentityCandidate | undefined,
+  ) => {
+    if (!candidate) return false;
+    if (!options.target) return true;
+    return !!candidate.target && targetMatches(candidate.target, options.target);
+  };
+  const local = targetMatchesCandidate(options.follower)
+    ? options.follower
+    : targetMatchesCandidate(options.leader)
+      ? options.leader
+      : undefined;
+  const record =
+    options.record &&
+    (!options.target || targetMatches(options.record.target, options.target))
+      ? options.record
+      : undefined;
+  return {
+    ...(local?.target ?? record?.target
+      ? { target: local?.target ?? record?.target }
+      : {}),
+    ...(local?.slot ?? record?.slot
+      ? { slot: local?.slot ?? record?.slot }
+      : {}),
+    ...(local?.threadName ?? record?.threadName
+      ? { threadName: local?.threadName ?? record?.threadName }
+      : {}),
+  };
+}
+
 export function findCurrentTelegramInstanceThreadRecord(options: {
   records: readonly TelegramTopicTargetRecord[];
   instanceId: string;

package/package.json

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