@llblab/pi-telegram 0.20.0 → 0.20.1

package/AGENTS.md

@@ -126,6 +126,7 @@ The core product loop is mobile continuation: start or supervise work in the ter
 
 - Keep globally reusable rules as independent bullets in the most general applicable section of `AGENTS.md`; do not hide a cross-cutting rule inside one local feature paragraph just because that feature revealed it.
 - Local/domain bullets should state how a general rule applies there, or record domain-specific exceptions; they should not be the only source for a rule that applies to multiple tools, transports, domains, or docs surfaces.
+- Markdown tables use compact source formatting: separator cells are exactly `---`, and headers/body cells have one surrounding space without alignment padding. Keep vendored references unchanged.
 - Pi-facing tool results shown in compact tool rows should start with exactly one leading newline (`\nResult`) so the result is visually separated from the tool-call header by one blank line without excessive vertical spacing.
 - For non-trivial implementation, release, or architecture-audit work, run an `AGENTS.md` compliance pass: reread the durable principles and relevant project docs, map the changed behavior to the rules it touches, validate code/tests/docs against those rules, and explicitly surface any rule conflict, obsolete rule, or evidence-backed improvement. When the rules themselves drift from the product reality, update `AGENTS.md` or document a deliberate exception in the same pass instead of silently working around it.
 - Treat Windows Telegram runtime error reports as high-signal evidence even when Linux is the primary development environment. Windows uses different filesystem/IPC behavior and is more likely to reveal lock, heartbeat, named-pipe, atomic-rename, and Threaded Mode edge cases; minimize each report into a regression or a documented platform caveat instead of dismissing it as environment noise.

package/BACKLOG.md

@@ -1,28 +1,16 @@
 # Project Backlog
 
-_This backlog tracks only open release-relevant work: 0.20.0 profile isolation, evidence-gated Telegram client/runtime follow-ups, and upstream Pi API blockers. Completed validation evidence belongs in `CHANGELOG.md`, not in this queue._
+_This backlog tracks only open release-relevant work: live promoted-follower verification, evidence-gated Telegram client/runtime follow-ups, and upstream Pi API blockers. Completed validation evidence belongs in `CHANGELOG.md`, not in this queue._
 
-## P0 — Profile Reality Isolation Audit
+## P1 — Promoted Follower Reload Evidence
 
-Context: 0.20.0 profiles are parallel bot/runtime realities, not just alternate credentials. Any persistent or observable runtime surface that cannot safely mix bot identities must be explicitly global or profile-scoped. Logs and Threaded Mode state are now profile-aware; the remaining audit lens should check surfaces beyond the validated setup/connect smoke path: bus endpoints, temp artifacts, in-memory registries, queues, ownership caches, and status diagnostics.
+Context: deterministic coverage protects promoted follower thread preservation, and the latest live Linux smoke closed reload routing, follower Active, and reroute/restore regressions. The exact promoted-leader reload path is deliberately outside the 0.20.1 profile IPC hotfix because it is unrelated to profile transport isolation; keep it as an evidence-gated follow-up rather than blocking that release.
 
 Open work:
 
-- [ ] Audit remaining non-setup filesystem/runtime observability surfaces and classify each as global shared config, session-local memory, or profile-scoped reality.
-- [ ] Profile-scope bus leader/follower IPC endpoints if parallel named profiles can run in the same agent dir concurrently.
-- [ ] Add regression coverage for any newly profile-scoped surface, preserving default-profile legacy paths where applicable.
+- [ ] Capture live evidence that leader → follower promotes → `/reload` preserves the promoted leader's Telegram thread identity.
 
-Done when: parallel named-profile runtimes have no shared logs/state/IPC/diagnostic surfaces except intentionally top-level shared bridge configuration.
-
-## P0 — Promoted Follower Reload Smoke
-
-Context: deterministic coverage protects promoted follower thread preservation, and the latest live Linux smoke closed the reload routing, follower Active, and reroute/restore regressions. Keep one explicit live check for promoted-follower reload identity unless that exact path is covered in the release smoke pass.
-
-Open work:
-
-- [ ] Close leader → follower promotes → `/reload` promoted leader preserves the same Telegram thread identity.
-
-Done when: promoted-follower reload identity has live Telegram evidence or is deliberately deferred out of the hotfix scope.
+Done when: promoted-follower reload identity has direct live Telegram evidence.
 
 ## P1 — Native Windows Threaded Mode Follow-Ups
 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.20.1: Profile IPC Isolation Hotfix
+
+- `[Runtime Isolation]` Profile-scoped Threaded Mode leader and follower IPC endpoints on Unix and Windows while preserving the default profile's legacy socket and named-pipe paths. Impact: parallel named-profile runtimes no longer contend for, unlink, or connect to another bot profile's local bus transport.
+- `[Profile Switching]` Resolved leader and follower endpoints from the active profile when servers start, follower calls are sent, diagnostics render, and follower registration publishes its receiver address. Impact: changing profiles after process start cannot retain stale IPC identity from the previously active profile.
+- `[Validation]` Added Unix and Windows endpoint-isolation regressions plus runtime restart coverage, and documented global, profile-scoped, and session-local runtime surfaces. Impact: profile reality boundaries are explicit and deterministic without making scratch attachments or extension registries routing authority.
+
 ## 0.20.0: Pi-Compatible Multi-Profile Runtime
 
 - `[Profiles]` Added named Telegram bot/session profiles under `telegram.json` `profiles` while preserving the top-level default profile and legacy default paths. Profile activation is session-local, bot/session fields are profile-scoped, shared bridge settings remain global, and setup/connect accept explicit profile names. Impact: separate bots can run from the same agent directory without `telegram-bots.json`, persisted active-profile drift, or default-profile migration risk.

package/README.md

@@ -41,7 +41,7 @@ Run this inside Pi:
 /telegram-setup
 ```
 
-Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved token, setup offers it as the default. If no saved token exists, setup can prefill from `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, or `TELEGRAM_KEY`.
+Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved token, setup offers it as the default. If no saved token exists, setup can prefill from `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, or `TELEGRAM_KEY`. Named profiles are optional; the ordinary `/telegram-setup` and `/telegram-connect` flow keeps using the default profile. Use `/telegram-setup <name>` only when you want an additional bot profile.
 
 ### 3. Connect this Pi session
 
@@ -49,7 +49,7 @@ Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved tok
 /telegram-connect
 ```
 
-The connected Pi instance owns Telegram polling. In classic mode this is a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the leader and later visible Pi instances register as followers.
+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 unnamed default profile keeps legacy 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.
 
 ### 4. Pair your Telegram account
 
@@ -69,44 +69,45 @@ The first Telegram user to message the bot becomes the allowed owner. Other user
 - Send voice, images, files, replies, edits, or media groups; the bridge turns them into Pi context.
 - Ask for an artifact; `telegram_attach` returns it through the active reply or direct Telegram delivery.
 - In Threaded Mode, run multiple visible Pi instances through one bot, each with its own Telegram thread.
+- Configure named profiles to run independent Telegram bots from the same Pi agent directory without sharing transport or routing state.
 
 ## Product Model
 
-| Lens                    | What `pi-telegram` owns                                                                            |
-| ----------------------- | -------------------------------------------------------------------------------------------------- |
-| Operator companion      | A phone-width control surface for a live Pi session                                                |
-| Runtime adapter         | Telegram turns mapped into Pi lifecycle, queueing, previews, final replies, and artifacts          |
-| Telegram UI harness     | Menus, settings, callbacks, Rich Markdown, drafts, active status, buttons, voice, and files        |
-| Multi-instance organism | One leader plus explicit visible followers routed through Telegram private-chat threads            |
-| Extension platform      | Commands, sections, status rows, update handlers, inbound/outbound handlers, and voice providers   |
-| Safety boundary         | No hidden Pi processes, no fake terminal, no PTY tricks, no arbitrary TUI slash-command forwarding |
+| Lens | What `pi-telegram` owns |
+| --- | --- |
+| Operator companion | A phone-width control surface for a live Pi session |
+| Runtime adapter | Telegram turns mapped into Pi lifecycle, queueing, previews, final replies, and artifacts |
+| Telegram UI harness | Menus, settings, callbacks, Rich Markdown, drafts, active status, buttons, voice, and files |
+| Multi-instance organism | One leader plus explicit visible followers routed through Telegram private-chat threads |
+| Extension platform | Commands, sections, status rows, update handlers, inbound/outbound handlers, and voice providers |
+| Safety boundary | No hidden Pi processes, no fake terminal, no PTY tricks, no arbitrary TUI slash-command forwarding |
 
 ## Feature Showcase
 
 `pi-telegram` is intentionally broad: it is a Telegram-shaped runtime surface, not only a message relay. This catalogue keeps the practical feature surface visible while detailed contracts stay in `/docs`.
 
-| Surface              | What you can do                                                                                                                                          | Why it matters                                                                                                             |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Prompt intake        | Send text, replies, edits, images, files, albums, voice notes, and handler output into Pi.                                                               | Telegram becomes a real mobile input surface with file/context references, not just a text tunnel.                         |
-| Queue control        | Inspect waiting turns, delete stale work, promote important prompts, continue, abort, stop, or force the next queued item.                               | Long Pi tasks keep running while new mobile prompts stay visible and controllable instead of interrupting or disappearing. |
-| Operator menu        | Use `/start` for status, prompt templates, model, thinking, settings, queue, extension sections, and diagnostics.                                        | The bot is an operator panel, not a command cheat sheet.                                                                   |
-| Prompt templates     | Run Pi prompt templates as Telegram-safe commands such as `/fix_tests`.                                                                                  | Reusable local workflows become phone-accessible without exposing arbitrary terminal commands.                             |
-| Model and thinking   | Switch model or reasoning level from Telegram through safe continuation flows.                                                                           | Mobile control can adjust execution strategy without tearing down the current session.                                     |
-| Compaction           | Confirm `/compact`, show native active status during compaction, and preserve Telegram-owned turn semantics.                                             | Context maintenance is visible and safe from the phone.                                                                    |
-| Draft previews       | Show native active status by default, or enable Telegram Rich Draft previews while the agent is still working.                                           | The operator can hide/show in-progress text independently from final rendering.                                            |
-| Assistant rendering  | Choose Native Rich Markdown or legacy Markdown-to-HTML for final assistant replies.                                                                      | Renderer compatibility is explicit instead of being conflated with draft previews.                                         |
-| Bridge UI rendering  | Render tool rows, reasoning/technical steps, menus, queue controls, status, settings, diagnostics, and sections through explicit Telegram HTML/plain UI. | Harness-owned surfaces remain operationally predictable and visually distinct from model-authored answers.                 |
-| Inbound files        | Download inbound files to the Pi agent temp directory with size limits.                                                                                  | Screenshots, PDFs, datasets, and artifacts enter Pi as inspectable local files.                                            |
-| Outbound artifacts   | Return generated files through `telegram_attach` during active turns or explicit direct delivery.                                                        | Agents send real artifacts as files, not pasted blobs.                                                                     |
-| Voice input          | Route audio through configured command-template handlers, programmatic handlers, or STT providers.                                                       | Voice notes become usable prompt context.                                                                                  |
-| Voice output         | Use `telegram_voice`, reply modes, configured voice handlers, and TTS providers.                                                                         | Replies can become Telegram voice messages when the workflow calls for it.                                                 |
-| Buttons              | Turn top-level `telegram_button` comments into inline buttons.                                                                                           | Assistant-authored choices become native Telegram interactions.                                                            |
-| Callback routing     | Route known callbacks to the owner extension and unknown callbacks back into Pi.                                                                         | Companion extensions can build UI without polling Telegram themselves.                                                     |
-| Threaded Mode        | Run one leader plus visible follower Pi instances through named private-chat threads.                                                                    | One bot can host a local multi-instance Pi organism without hidden process spawning.                                       |
-| Reroute and restore  | Preserve unknown threads and offer explicit target choices.                                                                                              | Telegram client state can be repaired without silently deleting or hijacking prompts.                                      |
-| Extension sections   | Add menu sections, commands, status rows, settings, callbacks, and delivery helpers from companion extensions.                                           | `pi-telegram` becomes a platform surface for other Pi extensions.                                                          |
-| Runtime diagnostics  | Use `/telegram-status` and recent runtime events for connection, role, queue, transport, and failure evidence.                                           | Debugging lives in the operator surface instead of hidden logs only.                                                       |
-| Safety and ownership | Pair one owner, lock transport, scope targets, and reject fake terminal behavior.                                                                        | Remote access remains explicit, bounded, and understandable.                                                               |
+| Surface | What you can do | Why it matters |
+| --- | --- | --- |
+| Prompt intake | Send text, replies, edits, images, files, albums, voice notes, and handler output into Pi. | Telegram becomes a real mobile input surface with file/context references, not just a text tunnel. |
+| Queue control | Inspect waiting turns, delete stale work, promote important prompts, continue, abort, stop, or force the next queued item. | Long Pi tasks keep running while new mobile prompts stay visible and controllable instead of interrupting or disappearing. |
+| Operator menu | Use `/start` for status, prompt templates, model, thinking, settings, queue, extension sections, and diagnostics. | The bot is an operator panel, not a command cheat sheet. |
+| Prompt templates | Run Pi prompt templates as Telegram-safe commands such as `/fix_tests`. | Reusable local workflows become phone-accessible without exposing arbitrary terminal commands. |
+| Model and thinking | Switch model or reasoning level from Telegram through safe continuation flows. | Mobile control can adjust execution strategy without tearing down the current session. |
+| Compaction | Confirm `/compact`, show native active status during compaction, and preserve Telegram-owned turn semantics. | Context maintenance is visible and safe from the phone. |
+| Draft previews | Show native active status by default, or enable Telegram Rich Draft previews while the agent is still working. | The operator can hide/show in-progress text independently from final rendering. |
+| Assistant rendering | Choose Native Rich Markdown or legacy Markdown-to-HTML for final assistant replies. | Renderer compatibility is explicit instead of being conflated with draft previews. |
+| Bridge UI rendering | Render tool rows, reasoning/technical steps, menus, queue controls, status, settings, diagnostics, and sections through explicit Telegram HTML/plain UI. | Harness-owned surfaces remain operationally predictable and visually distinct from model-authored answers. |
+| Inbound files | Download inbound files to the Pi agent temp directory with size limits. | Screenshots, PDFs, datasets, and artifacts enter Pi as inspectable local files. |
+| Outbound artifacts | Return generated files through `telegram_attach` during active turns or explicit direct delivery. | Agents send real artifacts as files, not pasted blobs. |
+| Voice input | Route audio through configured command-template handlers, programmatic handlers, or STT providers. | Voice notes become usable prompt context. |
+| Voice output | Use `telegram_voice`, reply modes, configured voice handlers, and TTS providers. | Replies can become Telegram voice messages when the workflow calls for it. |
+| Buttons | Turn top-level `telegram_button` comments into inline buttons. | Assistant-authored choices become native Telegram interactions. |
+| Callback routing | Route known callbacks to the owner extension and unknown callbacks back into Pi. | Companion extensions can build UI without polling Telegram themselves. |
+| Threaded Mode | Run one leader plus visible follower Pi instances through named private-chat threads. | One bot can host a local multi-instance Pi organism without hidden process spawning. |
+| Reroute and restore | Preserve unknown threads and offer explicit target choices. | Telegram client state can be repaired without silently deleting or hijacking prompts. |
+| Extension sections | Add menu sections, commands, status rows, settings, callbacks, and delivery helpers from companion extensions. | `pi-telegram` becomes a platform surface for other Pi extensions. |
+| Runtime diagnostics | Use `/telegram-status` and recent runtime events for connection, role, queue, transport, and failure evidence. | Debugging lives in the operator surface instead of hidden logs only. |
+| Safety and ownership | Pair one owner, lock transport, scope targets, and reject fake terminal behavior. | Remote access remains explicit, bounded, and understandable. |
 
 ## Core Loop
 
@@ -126,14 +127,14 @@ The bridge keeps Telegram responsive without stealing Pi's runtime model. Queuei
 
 Use these in the bot DM.
 
-| Command     | Purpose                                                 |
-| ----------- | ------------------------------------------------------- |
-| `/start`    | Pair when needed and open the main operator menu        |
-| `/compact`  | Confirm and run session compaction when safe            |
-| `/next`     | Dispatch the next queued turn, aborting first if needed |
-| `/continue` | Enqueue a priority continuation prompt                  |
-| `/abort`    | Abort the active run while preserving the queue         |
-| `/stop`     | Abort the active run and clear waiting Telegram turns   |
+| Command | Purpose |
+| --- | --- |
+| `/start` | Pair when needed and open the main operator menu |
+| `/compact` | Confirm and run session compaction when safe |
+| `/next` | Dispatch the next queued turn, aborting first if needed |
+| `/continue` | Enqueue a priority continuation prompt |
+| `/abort` | Abort the active run while preserving the queue |
+| `/stop` | Abort the active run and clear waiting Telegram turns |
 
 Hidden compatibility shortcuts: `/help`, `/status`, `/model`, `/thinking`, `/queue`, and `/settings` jump into the same menu system.
 
@@ -141,12 +142,14 @@ Hidden compatibility shortcuts: `/help`, `/status`, `/model`, `/thinking`, `/que
 
 Run these inside Pi.
 
-| Command                | Purpose                                                            |
-| ---------------------- | ------------------------------------------------------------------ |
-| `/telegram-setup`      | Save or update the bot token                                       |
-| `/telegram-connect`    | Start polling and acquire Telegram transport ownership             |
-| `/telegram-disconnect` | Stop polling and release ownership                                 |
-| `/telegram-status`     | Inspect connection, mode, queue, transport, and recent diagnostics |
+| Command | Purpose |
+| --- | --- |
+| `/telegram-setup` | Save or update the default bot token |
+| `/telegram-setup <profile>` | Save or update a named-profile bot token |
+| `/telegram-connect` | Activate the default profile and acquire its transport ownership |
+| `/telegram-connect <profile>` | Activate a named profile and acquire its transport ownership |
+| `/telegram-disconnect` | Stop polling and release ownership |
+| `/telegram-status` | Inspect connection, mode, queue, transport, and recent diagnostics |
 
 ## Main Surfaces
 
@@ -184,23 +187,23 @@ Classic private DM mode is the base product mode. When Telegram private-chat Thr
 - Unknown threads are preserved and offered explicit reroute/restore choices.
 - Telegram never launches hidden Pi processes.
 
-| Mode          | Best for                                                 | Runtime shape                                                                 |
-| ------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| Classic DM    | One live Pi session controlled from one private bot chat | One polling owner, one queue/runtime surface                                  |
-| Threaded Mode | Several visible Pi terminals sharing one bot             | One leader owns transport; followers route through named private-chat threads |
+| Mode | Best for | Runtime shape |
+| --- | --- | --- |
+| Classic DM | One live Pi session controlled from one private bot chat | One polling owner, one queue/runtime surface |
+| Threaded Mode | Several visible Pi terminals sharing one bot | One leader owns transport; followers route through named private-chat threads |
 
 ## Environment Configuration
 
 Most controls live in Pi commands or the Telegram menu. Environment variables remain for bootstrap and transport boundaries:
 
-| Area                      | Variables                                                                                      |
-| ------------------------- | ---------------------------------------------------------------------------------------------- |
-| Bot token bootstrap       | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, `TELEGRAM_KEY`                     |
-| HTTP proxy                | `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, plus `NODE_USE_ENV_PROXY=1` or Node `--use-env-proxy` |
-| Telegram network family   | `PI_TELEGRAM_NETWORK_FAMILY=auto`, `ipv4`, `ipv6`, or `ipv4-fallback`                          |
-| Agent data root           | `PI_CODING_AGENT_DIR`                                                                          |
-| 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`              |
+| Area | Variables |
+| --- | --- |
+| Bot token bootstrap | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_KEY`, `TELEGRAM_TOKEN`, `TELEGRAM_KEY` |
+| HTTP proxy | `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, plus `NODE_USE_ENV_PROXY=1` or Node `--use-env-proxy` |
+| Telegram network family | `PI_TELEGRAM_NETWORK_FAMILY=auto`, `ipv4`, `ipv6`, or `ipv4-fallback` |
+| Agent data root | `PI_CODING_AGENT_DIR` |
+| 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, and native Telegram active status for long-running turns.
 

package/docs/README.md

@@ -6,7 +6,7 @@ Living index of project documentation in `/docs`.
 
 ## Documents
 
-- [architecture.md](./architecture.md) — Overview of the Telegram bridge runtime, queueing model, native Rich Markdown delivery, UI/compat rendering, and interactive controls
+- [architecture.md](./architecture.md) — Overview of the Telegram bridge runtime, optional profile isolation, queueing model, native Rich Markdown delivery, UI/compat rendering, and interactive controls
 - [public-api.md](./public-api.md) — Stable public API map: package entrypoints, commands, config, assistant markup, extension APIs, smoke examples, and compatibility boundaries
 - [../.agents/skills/telegram-bot/SKILL.md](../.agents/skills/telegram-bot/SKILL.md) — Agent-facing Telegram Bot API lookup skill backed by a local full Bot API reference
 - [../.agents/skills/domain-dag/SKILL.md](../.agents/skills/domain-dag/SKILL.md) — Project-local Domain DAG architecture skill and validator guidance
@@ -15,7 +15,7 @@ Living index of project documentation in `/docs`.
 - [outbound.md](./outbound.md) — Local `pi-telegram` outbound-handler config, text/voice/button behavior, voice synthesis provider fallback priority, artifact outputs, and callback routing
 - [callback-namespaces.md](./callback-namespaces.md) — Shared Telegram `callback_data` namespace standard for layered extensions
 - [updates.md](./updates.md) — Update classification and runtime handler registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection
-- [multi-instance-bus.md](./multi-instance-bus.md) — Optional multi-instance Telegram bus architecture: leader/follower routing, thread targets, instance slots, manual follower registration, and recovery semantics
+- [multi-instance-bus.md](./multi-instance-bus.md) — Optional multi-instance Telegram bus architecture: profile-scoped transport, leader/follower routing, thread targets, instance slots, manual follower registration, and recovery semantics
 - [sections.md](./sections.md) — Telegram Extension Sections Standard: registration contract, context ports, callback routing, navigation hierarchy, and demo reference for pi extensions that want Telegram UI surfaces
 - [voice.md](./voice.md) — Voice integration guide: detection, reply policy, STT/TTS provider registration, provider-owned conversion, and transparent interception
 - [locks.md](./locks.md) — Shared `locks.json` standard for singleton extension ownership

package/docs/architecture.md

@@ -120,7 +120,9 @@ Deleting `locks.json` resets runtime ownership without deleting Telegram configu
 
 Telegram private-chat Threaded Mode is the public switch for multi-instance Telegram operation. Classic single-DM polling is the base mode. When Telegram private-chat threads are available for the bot, the bridge enables the local leader/follower bus automatically; when threads are unavailable or later disabled, the bridge returns to classic single-DM polling as a first-class mode.
 
-Named Telegram profiles are orthogonal to Threaded Mode. The selected profile chooses the bot/session slice (`botToken`, `botId`, `botUsername`, `allowedUserId`, `lastUpdateId`) and scopes singleton locks, diagnostics logs, state files, and thread/bus owner keys; it must not change the Threaded Mode rules. Within one selected profile, leader/follower election, bus transport, thread provisioning, routing, ownership forwarding, cleanup, and runtime diagnostics behave exactly as they do for the default profile. A different selected profile is a parallel bot runtime: its locks, `tmp/telegram/state.<profile>.json`, `tmp/telegram/logs.<profile>.jsonl`, previous log, and thread bindings are isolated from the default profile and from other named profiles while shared bridge settings remain top-level/global. The default profile preserves legacy `state.json`, `logs.jsonl`, and `logs.previous.jsonl` paths for compatibility.
+Named Telegram profiles are orthogonal to Threaded Mode. The selected profile chooses the bot/session slice (`botToken`, `botId`, `botUsername`, `allowedUserId`, `lastUpdateId`) and scopes singleton locks, diagnostics logs, state files, thread/bus owner keys, and leader/follower IPC endpoints; it must not change the Threaded Mode rules. Within one selected profile, leader/follower election, bus transport, thread provisioning, routing, ownership forwarding, cleanup, and runtime diagnostics behave exactly as they do for the default profile. A different selected profile is a parallel bot runtime: its locks, `tmp/telegram/state.<profile>.json`, `tmp/telegram/logs.<profile>.jsonl`, previous log, thread bindings, Unix sockets, and Windows named pipes are isolated from the default profile and from other named profiles while shared bridge settings remain top-level/global. The default profile preserves legacy state, log, socket, and named-pipe paths for compatibility.
+
+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. `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.
 

package/docs/command-templates.md

@@ -63,13 +63,13 @@ Implementations may expand `~` in command position and may resolve relative comm
 
 Supported forms:
 
-| Form             | Meaning                                          |
-| ---------------- | ------------------------------------------------ |
-| `{name}`         | Required value from runtime values or `defaults` |
-| `{name=default}` | Inline default when no value is provided         |
-| `{items[index]}` | Array item selected by literal or repeat index   |
-| `{value??fallback}` | Fallback when the value is absent or falsy    |
-| `{flag?yes:no}`  | Conditional text selected by flag truthiness     |
+| Form | Meaning |
+| --- | --- |
+| `{name}` | Required value from runtime values or `defaults` |
+| `{name=default}` | Inline default when no value is provided |
+| `{items[index]}` | Array item selected by literal or repeat index |
+| `{value??fallback}` | Fallback when the value is absent or falsy |
+| `{flag?yes:no}` | Conditional text selected by flag truthiness |
 
 Resolution order is runtime values → `defaults` → inline default → error. Default values that are themselves a single placeholder, such as `{prompt}` resolving to `{prompts[index]}`, are resolved recursively with a small depth guard. A repeat node may set `repeat` to `{items.length}` when an array arg should determine fanout width.
 

package/docs/inbound.md

@@ -59,11 +59,11 @@ Handlers match by optional `type`, `mime`, or `match`. `mime` and `type` are ind
 
 Built-in placeholders for text handlers:
 
-| Placeholder | Value        |
-| ----------- | ------------ |
-| `{text}`    | Current text |
-| `{mime}`    | `text/plain` |
-| `{type}`    | `text`       |
+| Placeholder | Value |
+| --- | --- |
+| `{text}` | Current text |
+| `{mime}` | `text/plain` |
+| `{type}` | `text` |
 
 ## Media/File Handlers
 
@@ -71,12 +71,12 @@ Media/file handlers keep the legacy attachment-handler behavior: downloaded file
 
 Built-in placeholders for media/file handlers:
 
-| Placeholder | Value                                          |
-| ----------- | ---------------------------------------------- |
-| `{file}`    | Downloaded file path                           |
-| `{mime}`    | MIME type if known                             |
-| `{type}`    | Kind: `voice`, `audio`, `document`, or `photo` |
-| `{text}`    | Empty string                                   |
+| Placeholder | Value |
+| --- | --- |
+| `{file}` | Downloaded file path |
+| `{mime}` | MIME type if known |
+| `{type}` | Kind: `voice`, `audio`, `document`, or `photo` |
+| `{text}` | Empty string |
 
 If a top-level one-step media handler template has no `{file}` placeholder, the downloaded file path is appended as the last command arg as a one-step handler convenience. Composition steps are plain command templates and do not receive implicit file-path args; include `{file}` explicitly where needed.
 

package/docs/multi-instance-bus.md

@@ -8,6 +8,8 @@ This document uses **thread** as the canonical product term because Telegram cli
 
 This document supersedes the narrower API-topic framing. Telegram threads are a UI/routing substrate, but the deeper design problem is multi-instance coordination: one bot token has one Telegram API update bus, while multiple live Pi agent instances may want to expose their own Telegram workspace through that bus.
 
+Named bot profiles are optional and orthogonal to this design. The ordinary unnamed profile keeps the existing setup, connect, lock, state, log, Unix socket, and Windows named-pipe paths. When operators configure additional profiles, each profile is an independent bot runtime with its own lock key, observable state, thread ownership, and leader/follower IPC endpoints; leader election and follower routing never cross profile boundaries.
+
 ## Problem
 
 Classic `pi-telegram` mode binds one private Telegram DM to one live Pi instance through one bot token and one singleton polling owner. The lock currently answers: "which Pi instance owns Telegram control/polling?"

package/docs/outbound.md

@@ -10,11 +10,11 @@ Text handlers use the portable [Command Template Standard](./command-templates.m
 
 An outbound handler is selected by `type`. Text replies and assistant markup map to handler types:
 
-| Source            | Handler                       | Action                  |
-| ----------------- | ----------------------------- | ----------------------- |
-| Final text        | `outboundHandlers[type=text]` | Transform before render |
-| `telegram_voice`  | Voice pipeline                | OGG/Opus `sendVoice`    |
-| `telegram_button` | Built-in                      | Attach inline button    |
+| Source | Handler | Action |
+| --- | --- | --- |
+| Final text | `outboundHandlers[type=text]` | Transform before render |
+| `telegram_voice` | Voice pipeline | OGG/Opus `sendVoice` |
+| `telegram_button` | Built-in | Attach inline button |
 
 The voice pipeline is detailed below: configured `type: "voice"` handlers first, then programmatic handlers, then registered synthesis providers.
 

package/index.ts

@@ -77,9 +77,21 @@ export default function (pi: Pi.ExtensionAPI) {
   let telegramBusLifecycleOverridePhase:
     | Status.TelegramBridgeBusLifecyclePhase
     | undefined;
-  const telegramBusSocketPath = Bus.getTelegramBusSocketPath();
-  const telegramBusFollowerSocketPath =
-    Bus.getTelegramBusFollowerSocketPath(telegramInstanceId);
+  const getTelegramBusSocketPath = function (): string {
+    return Bus.getTelegramBusSocketPath(
+      undefined,
+      undefined,
+      getActiveTelegramThreadProfile(),
+    );
+  };
+  const getTelegramBusFollowerSocketPath = function (): string {
+    return Bus.getTelegramBusFollowerSocketPath(
+      telegramInstanceId,
+      undefined,
+      undefined,
+      getActiveTelegramThreadProfile(),
+    );
+  };
   let telegramBusRequestSequence = 0;
   const telegramBusFollowerRegistry = Bus.createTelegramBusFollowerRegistry();
   const telegramBusFollowerRegistrationState =
@@ -300,12 +312,13 @@ export default function (pi: Pi.ExtensionAPI) {
     },
     getLocalBus() {
       return {
-        leaderSocketPath: telegramBusSocketPath,
-        leaderTransport:
-          BusTransport.getTelegramBusTransportKind(telegramBusSocketPath),
-        followerSocketPath: telegramBusFollowerSocketPath,
+        leaderSocketPath: getTelegramBusSocketPath(),
+        leaderTransport: BusTransport.getTelegramBusTransportKind(
+          getTelegramBusSocketPath(),
+        ),
+        followerSocketPath: getTelegramBusFollowerSocketPath(),
         followerTransport: BusTransport.getTelegramBusTransportKind(
-          telegramBusFollowerSocketPath,
+          getTelegramBusFollowerSocketPath(),
         ),
         followerRegistered: telegramBusFollowerRegistrationState.isRegistered(),
         followerTarget: telegramBusFollowerRegistrationState.getTarget(),
@@ -412,7 +425,7 @@ export default function (pi: Pi.ExtensionAPI) {
     },
     getDefaultTarget: proactivePushTargetGetter,
     callFollowerApi: BusFollower.createTelegramBusFollowerApiCaller({
-      socketPath: telegramBusSocketPath,
+      socketPath: getTelegramBusSocketPath,
       instanceId: telegramInstanceId,
       createRequestId() {
         telegramBusRequestSequence += 1;
@@ -641,7 +654,7 @@ export default function (pi: Pi.ExtensionAPI) {
       Routing.TelegramRoutedCallbackQuery,
       Routing.TelegramRoutedMessage
     >({
-      socketPath: telegramBusSocketPath,
+      socketPath: getTelegramBusSocketPath,
       createRequestId() {
         telegramBusRequestSequence += 1;
         return Bus.createTelegramBusRequestId({
@@ -656,7 +669,7 @@ export default function (pi: Pi.ExtensionAPI) {
     });
   const followerTargetController =
     Bus.createTelegramBusFollowerTargetController({
-      socketPath: telegramBusSocketPath,
+      socketPath: getTelegramBusSocketPath,
       createRequestId() {
         telegramBusRequestSequence += 1;
         return Bus.createTelegramBusRequestId({
@@ -811,7 +824,7 @@ export default function (pi: Pi.ExtensionAPI) {
       Routing.TelegramRoutedCallbackQuery,
       Routing.TelegramRoutedMessage
     >({
-      socketPath: telegramBusFollowerSocketPath,
+      socketPath: getTelegramBusFollowerSocketPath,
       instanceId: telegramInstanceId,
       getContext() {
         return telegramSessionContextStore.get();
@@ -910,7 +923,8 @@ export default function (pi: Pi.ExtensionAPI) {
     BusFollower.createTelegramBusFollowerRegistrationRuntime<Pi.ExtensionContext>(
       {
         instanceId: telegramInstanceId,
-        followerBusSocketPath: telegramBusFollowerSocketPath,
+        getFollowerBusSocketPath: getTelegramBusFollowerSocketPath,
+        getLeaderSocketPath: getTelegramBusSocketPath,
         startReceiving: telegramBusForwardedUpdateReceiver.start,
         stopReceiving: telegramBusForwardedUpdateReceiver.stop,
         registrationState: telegramBusFollowerRegistrationState,
@@ -967,7 +981,7 @@ export default function (pi: Pi.ExtensionAPI) {
     });
   };
   const telegramBusLeaderRuntime = BusLeader.createTelegramBusLeaderRuntime({
-    socketPath: telegramBusSocketPath,
+    socketPath: getTelegramBusSocketPath,
     followerRegistry: telegramBusFollowerRegistry,
     authSecret: telegramBusAuthSecret,
     startPolling: pollingRuntime.start,

package/lib/bus-follower.ts

@@ -16,8 +16,10 @@ import {
   createTelegramBusLocalServer,
   createUnauthorizedBusAck,
   getTelegramBusSocketPath,
+  resolveTelegramBusSocketPath,
   sendTelegramBusLocalEnvelope,
   type TelegramBusEnvelope,
+  type TelegramBusSocketPathSource,
 } from "./bus.ts";
 import {
   getTelegramBusTransportRetryPolicy,
@@ -133,7 +135,7 @@ export interface TelegramBusForwardedUpdateReceiverRuntime {
 }
 
 export interface TelegramBusFollowerApiCallerDeps {
-  socketPath: string;
+  socketPath: TelegramBusSocketPathSource;
   instanceId: string;
   createRequestId: () => string;
   getAuthSecret?: () => string | undefined;
@@ -149,6 +151,7 @@ export interface TelegramBusFollowerRegistrationRuntimeDeps<
   getLeaderAuthSecret?: (leader: { busSecret?: string }) => string | undefined;
   setActiveAuthSecret?: (secret: string | undefined) => void;
   followerBusSocketPath?: string;
+  getFollowerBusSocketPath?: () => string;
   getLeaderSocketPath?: () => string;
   startReceiving?: () => Promise<void>;
   stopReceiving?: () => Promise<void> | void;
@@ -238,7 +241,7 @@ export interface TelegramBusForwardedUpdateReceiverRuntimeDeps<
   TCallbackQuery,
   TMessage = unknown,
 > {
-  socketPath: string;
+  socketPath: TelegramBusSocketPathSource;
   instanceId: string;
   getAuthSecret?: () => string | undefined;
   getContext: () => TContext | undefined;
@@ -354,11 +357,12 @@ export function createTelegramBusFollowerApiCaller(
   const getNowMs = deps.getNowMs ?? Date.now;
   const timeoutMs = deps.timeoutMs ?? 30000;
   return async (method, args) => {
+    const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
     const response = await sendTelegramBusLocalEnvelope({
-      socketPath: deps.socketPath,
+      socketPath,
       timeoutMs,
       retry: getTelegramBusTransportRetryPolicy({
-        endpoint: deps.socketPath,
+        endpoint: socketPath,
         operation: "operation",
       }),
       envelope: {
@@ -725,7 +729,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
             (ctx.cwd ? basename(ctx.cwd) : undefined),
           cwd: ctx.cwd,
           pid: getPid(),
-          busSocketPath: deps.followerBusSocketPath,
+          busSocketPath:
+            deps.getFollowerBusSocketPath?.() ?? deps.followerBusSocketPath,
           connectedAtMs: getNowMs(),
         },
       });

package/lib/bus-leader.ts

@@ -20,6 +20,7 @@ import {
   type TelegramBusFollowerRegistry,
   type TelegramBusFollowerView,
   type TelegramBusInstanceRegistration,
+  type TelegramBusSocketPathSource,
 } from "./bus.ts";
 import { getTelegramBusTransportRetryPolicy } from "./bus-transport.ts";
 
@@ -176,7 +177,7 @@ export type TelegramBusFollowerMessageOwnershipRecorder = (
 ) => void;
 
 export interface TelegramBusLeaderRuntimeDeps<TContext> {
-  socketPath: string;
+  socketPath: TelegramBusSocketPathSource;
   followerRegistry: TelegramBusFollowerRegistry;
   authSecret?: string;
   startPolling: (ctx: TContext) => void | Promise<void>;

package/lib/bus-transport.ts

@@ -99,31 +99,55 @@ export function getTelegramBusTransportRetryPolicy(input: {
   };
 }
 
+function normalizeTelegramBusEndpointScope(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 80);
+}
+
 export function getTelegramBusLeaderEndpoint(input: {
   agentDir: string;
   platform: NodeJS.Platform | string;
+  profileName?: string;
 }): string {
+  const profileScope = input.profileName
+    ? normalizeTelegramBusEndpointScope(input.profileName)
+    : undefined;
   return input.platform === "win32"
-    ? getTelegramBusPipePath({ agentDir: input.agentDir, scope: "bus" })
-    : join(input.agentDir, "tmp", "telegram", "bus.sock");
+    ? getTelegramBusPipePath({
+        agentDir: input.agentDir,
+        scope: profileScope ? `bus-${profileScope}` : "bus",
+      })
+    : join(
+        input.agentDir,
+        "tmp",
+        "telegram",
+        profileScope ? `bus.${profileScope}.sock` : "bus.sock",
+      );
 }
 
 export function getTelegramBusFollowerEndpoint(input: {
   agentDir: string;
   platform: NodeJS.Platform | string;
   instanceId: string;
+  profileName?: string;
 }): string {
+  const instanceScope = normalizeTelegramBusEndpointScope(input.instanceId);
+  const profileScope = input.profileName
+    ? normalizeTelegramBusEndpointScope(input.profileName)
+    : undefined;
   return input.platform === "win32"
     ? getTelegramBusPipePath({
         agentDir: input.agentDir,
-        scope: `follower-${input.instanceId}`,
+        scope: profileScope
+          ? `follower-${profileScope}-${instanceScope}`
+          : `follower-${instanceScope}`,
       })
     : join(
         input.agentDir,
         "tmp",
         "telegram",
         "followers",
-        `${input.instanceId.replace(/[^a-zA-Z0-9_.-]/g, "_")}.sock`,
+        ...(profileScope ? [profileScope] : []),
+        `${instanceScope}.sock`,
       );
 }
 

package/lib/bus.ts

@@ -41,16 +41,23 @@ export function createTelegramBusAuthSecret(): string {
 export function getTelegramBusSocketPath(
   agentDir = resolveAgentDir(),
   platform = getPlatform(),
+  profileName?: string,
 ): string {
-  return getTelegramBusLeaderEndpoint({ agentDir, platform });
+  return getTelegramBusLeaderEndpoint({ agentDir, platform, profileName });
 }
 
 export function getTelegramBusFollowerSocketPath(
   instanceId: string,
   agentDir = resolveAgentDir(),
   platform = getPlatform(),
+  profileName?: string,
 ): string {
-  return getTelegramBusFollowerEndpoint({ agentDir, platform, instanceId });
+  return getTelegramBusFollowerEndpoint({
+    agentDir,
+    platform,
+    instanceId,
+    profileName,
+  });
 }
 
 export interface TelegramBusInstanceRegistration {
@@ -344,8 +351,16 @@ export interface TelegramBusLocalServer {
   stop: () => Promise<void>;
 }
 
+export type TelegramBusSocketPathSource = string | (() => string);
+
+export function resolveTelegramBusSocketPath(
+  source: TelegramBusSocketPathSource,
+): string {
+  return typeof source === "function" ? source() : source;
+}
+
 export interface TelegramBusLocalServerDeps {
-  socketPath: string;
+  socketPath: TelegramBusSocketPathSource;
   handleEnvelope: (
     envelope: TelegramBusEnvelope,
   ) =>
@@ -362,7 +377,7 @@ export interface TelegramBusLocalClientOptions {
 }
 
 export interface TelegramBusForeignOwnedForwarderDeps {
-  socketPath: string;
+  socketPath: TelegramBusSocketPathSource;
   createRequestId: () => string;
   getNowMs?: () => number;
   timeoutMs?: number;
@@ -401,12 +416,13 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
   const getNowMs = deps.getNowMs ?? Date.now;
   const send = async (envelope: TelegramBusEnvelope): Promise<boolean> => {
     if (deps.getAuthSecret) envelope.auth = deps.getAuthSecret();
+    const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
     const response = await sendTelegramBusLocalEnvelope({
-      socketPath: deps.socketPath,
+      socketPath,
       envelope,
       timeoutMs: deps.timeoutMs,
       retry: getTelegramBusTransportRetryPolicy({
-        endpoint: deps.socketPath,
+        endpoint: socketPath,
         operation: "operation",
       }),
     });
@@ -558,6 +574,7 @@ export function createTelegramBusLocalServer(
   deps: TelegramBusLocalServerDeps,
 ): TelegramBusLocalServer {
   let server: Server | undefined;
+  let activeSocketPath: string | undefined;
   const sockets = new Set<Socket>();
   const closeSocket = (socket: Socket) => {
     sockets.delete(socket);
@@ -566,16 +583,18 @@ export function createTelegramBusLocalServer(
   return {
     start: async () => {
       if (server) return;
-      const usesWindowsPipe = isTelegramBusPipePath(deps.socketPath);
+      const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
+      activeSocketPath = socketPath;
+      const usesWindowsPipe = isTelegramBusPipePath(socketPath);
       deps.recordTransportEvent?.(
         "server-start",
-        getTelegramBusEndpointDiagnostics(deps.socketPath),
+        getTelegramBusEndpointDiagnostics(socketPath),
       );
       if (!usesWindowsPipe) {
-        const socketDir = dirname(deps.socketPath);
+        const socketDir = dirname(socketPath);
         mkdirSync(socketDir, { recursive: true, mode: 0o700 });
         chmodSync(socketDir, 0o700);
-        if (existsSync(deps.socketPath)) unlinkSync(deps.socketPath);
+        if (existsSync(socketPath)) unlinkSync(socketPath);
       }
       server = createServer((socket) => {
         sockets.add(socket);
@@ -591,14 +610,14 @@ export function createTelegramBusLocalServer(
               socket,
               deps.handleEnvelope,
               deps.recordTransportEvent,
-              deps.socketPath,
+              socketPath,
             );
           }
         });
         socket.on("close", () => sockets.delete(socket));
         socket.on("error", (error) => {
           deps.recordTransportEvent?.("server-socket-error", {
-            ...getTelegramBusEndpointDiagnostics(deps.socketPath),
+            ...getTelegramBusEndpointDiagnostics(socketPath),
             ...classifyTelegramBusTransportError(error),
           });
           closeSocket(socket);
@@ -607,24 +626,28 @@ export function createTelegramBusLocalServer(
       try {
         await new Promise<void>((resolve, reject) => {
           server?.once("error", reject);
-          server?.listen(deps.socketPath, resolve);
+          server?.listen(socketPath, resolve);
         });
         deps.recordTransportEvent?.(
           "server-started",
-          getTelegramBusEndpointDiagnostics(deps.socketPath),
+          getTelegramBusEndpointDiagnostics(socketPath),
         );
       } catch (error) {
+        server = undefined;
+        activeSocketPath = undefined;
         deps.recordTransportEvent?.("server-start-failed", {
-          ...getTelegramBusEndpointDiagnostics(deps.socketPath),
+          ...getTelegramBusEndpointDiagnostics(socketPath),
           ...classifyTelegramBusTransportError(error),
         });
         throw error;
       }
-      if (!usesWindowsPipe) chmodSync(deps.socketPath, 0o600);
+      if (!usesWindowsPipe) chmodSync(socketPath, 0o600);
     },
     stop: async () => {
       const activeServer = server;
+      const socketPath = activeSocketPath;
       server = undefined;
+      activeSocketPath = undefined;
       for (const socket of sockets) closeSocket(socket);
       if (activeServer) {
         await new Promise<void>((resolve) =>
@@ -632,15 +655,18 @@ export function createTelegramBusLocalServer(
         );
       }
       if (
-        !isTelegramBusPipePath(deps.socketPath) &&
-        existsSync(deps.socketPath)
+        socketPath &&
+        !isTelegramBusPipePath(socketPath) &&
+        existsSync(socketPath)
       ) {
-        unlinkSync(deps.socketPath);
+        unlinkSync(socketPath);
+      }
+      if (socketPath) {
+        deps.recordTransportEvent?.(
+          "server-stopped",
+          getTelegramBusEndpointDiagnostics(socketPath),
+        );
       }
-      deps.recordTransportEvent?.(
-        "server-stopped",
-        getTelegramBusEndpointDiagnostics(deps.socketPath),
-      );
     },
   };
 }

package/package.json

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