@llblab/pi-telegram 0.23.2 → 0.24.0

package/AGENTS.md

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

package/BACKLOG.md

@@ -10,7 +10,7 @@ Open work:
 
 - [ ] Capture text diagnostics if Windows classic restore/status convergence repeatedly exceeds the intended 5–15 second fallback window.
 - [ ] Add a focused regression or transport/status adjustment only if new Windows evidence shows a repeatable named-pipe, lock, heartbeat, queue, or status-convergence issue.
-- [ ] For every Windows connect/runtime crash report, classify the failing boundary (`locks.json` atomic write, named pipe, heartbeat, polling, queue, or status), ensure `logs.jsonl` captures enough redacted evidence before shutdown, and add a minimized regression when the failure can be simulated deterministically.
+- [ ] For every Windows connect/runtime crash report, classify the failing boundary (`owners.json` atomic write, named pipe, heartbeat, polling, queue, or status), ensure `logs.jsonl` captures enough redacted evidence before shutdown, and add a minimized regression when the failure can be simulated deterministically.
 
 Done when: new Windows-specific runtime issues are either fixed with targeted coverage or left out of the backlog because the native smoke remains green.
 

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+## 0.24.0: Canonical Profiles And Extension-Local Ownership
+
+- `Canonical Default Profile`: Persisted bot/session identity under `profiles.default` and named siblings while keeping shared settings top-level. Legacy root identity migrates atomically when unambiguous and conflicts fail closed; bare and explicit `default` setup/connect commands now behave identically without changing default runtime paths. Live reload preserved token, pairing, offset, ownership, and Telegram delivery.
+- `Extension-Local Transport Ownership`: Replaced shared agent-level `locks.json` ownership with private profile-scoped `tmp/telegram/owners.json`, serialized through `owners.json.transaction`; followers remain outside owner-slot writes. Breaking: `0.24.0` intentionally does not migrate legacy ownership, so upgrading resets the transport owner and may require `/telegram-connect`. Live reload confirmed isolated default ownership while leaving the legacy registry untouched.
+
+## 0.23.3: Thread-Scoped Settings Hotfix
+
+- `Thread-Scoped Settings Rehydration`: Preserved `message_thread_id` when rebuilding full Settings menu state after session reload or TTL expiry. Impact: a stale Settings message in Threaded Mode retains its exact Telegram target when later callbacks reopen menus or cross into model/status controls.
+- `Composition Root Hygiene`: Sorted the local domain imports in `index.ts` and normalized adjacent wrapping without changing runtime composition. Impact: the entrypoint remains easier to scan and review while preserving the existing dependency graph and behavior.
+
 ## 0.23.2: Voice Policy And Turn Delivery Hotfix
 
 - `Settings Persistence Race`: Rebuilt expired Settings callback state from the live model-menu context before applying mutations. Polling now persists only its monotonic `lastUpdateId` into the current config-store snapshot instead of later submitting the detached full config object captured when polling started. Impact: a subsequent Telegram update can no longer erase freshly persisted `voice.replyMode`, `assistant.proactivePush`, or other Settings values and return the menu to stale defaults.

package/README.md

@@ -45,7 +45,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`. 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. Cancelling or failing named-profile token validation leaves the currently active profile and polling runtime unchanged; setup reports the profile as saved and connected only after polling startup succeeds.
+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`. Bot/session identity persists under `profiles.default`; shared handlers and assistant/voice/time settings remain top-level. `/telegram-setup default` and `/telegram-connect default` are exact aliases for the bare commands. Use `/telegram-setup <name>` only when you want an additional bot profile. Cancelling or failing named-profile token validation leaves the currently active profile and polling runtime unchanged; setup reports the profile as saved and connected only after polling startup succeeds.
 
 ### 3. Connect this Pi instance and its active session
 
@@ -53,7 +53,7 @@ Paste the bot token. If `~/.pi/agent/telegram.json` already contains a saved tok
 /telegram-connect
 ```
 
-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.
+The connected Pi instance owns Telegram polling. Use `/telegram-connect <name>` to activate a named profile. Each profile is a parallel bot runtime with isolated polling, diagnostics, Threaded Mode state, and local bus transport; the `default` profile keeps unsuffixed runtime paths. In classic mode each profile uses a singleton lock. When Telegram private-chat Threaded Mode is available, one live instance becomes the profile's leader and later visible Pi instances register as followers.
 
 ### 4. Pair your Telegram account
 
@@ -148,9 +148,9 @@ Run these inside Pi.
 
 | Command | Purpose |
 | --- | --- |
-| `/telegram-setup` | Save or update the default bot token |
+| `/telegram-setup` / `/telegram-setup default` | Save or update `profiles.default` |
 | `/telegram-setup <profile>` | Save or update a named-profile bot token |
-| `/telegram-connect` | Activate the default profile and acquire its transport ownership |
+| `/telegram-connect` / `/telegram-connect default` | Activate `profiles.default` and acquire its transport ownership |
 | `/telegram-connect <profile>` | Activate a named profile and acquire its transport ownership |
 | `/telegram-disconnect` | Stop polling and release ownership; in Threaded Mode, confirm deletion of this instance's current Telegram thread |
 | `/telegram-status` | Inspect connection, mode, queue, transport, and recent diagnostics |
@@ -257,7 +257,6 @@ A Telegram prompt is a normal model turn in the active Pi session and therefore
 - [Extension Sections](./docs/sections.md) — Telegram-native companion UI surfaces.
 - [Updates](./docs/updates.md) — update handler registry and callback interop.
 - [Multi-Instance Bus](./docs/multi-instance-bus.md) — leader/follower routing in Threaded Mode.
-- [Locks](./docs/locks.md) — singleton ownership and shared lock conventions.
 - [UI Style](./docs/ui-style.md) — menu, emoji, labels, dialogs, and inline keyboard standards.
 - [Callback Namespaces](./docs/callback-namespaces.md) — callback ownership and routing.
 - [Command Templates](./docs/command-templates.md) — handler command-template conventions.

package/docs/README.md

@@ -20,5 +20,4 @@ Living index of project documentation in `/docs`.
 - [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
 - [ui-style.md](./ui-style.md) — Inline UI style guide for buttons, toggles, tabs, option lists, cards, and dialogs

package/docs/architecture.md

@@ -63,7 +63,7 @@ The repository uses a **Flat Domain DAG**:
 - `index.ts`: composition root for live ports, session-state ports, transport adapters, and lifecycle registration. It exposes cross-domain wiring but does not own mutable domain state or reusable adapters.
 - `api`: Bot API helpers, retries, uploads/downloads, temp cleanup, byte limits, chat actions, lazy token clients, and API error recording.
 - `config` / `setup`: `telegram.json`, bot token setup, named bot/session profiles, first-user pairing, authorization, env fallback, atomic persistence, effective config views, and live config accessors.
-- `locks` / `polling`: serialized singleton lock storage, exact-owner epoch exposure, process-global reload generations, lock-aware polling lifecycle/takeover/follower registration, and the cohesive classic-vs-Threaded capability state/monitor/observation/polling orchestration. Polling also owns long-poll controller state, offset admission/persistence, and poll-loop wiring.
+- `locks` / `polling`: extension-local transport owner storage, exact-owner epoch exposure, process-global reload generations, owner-aware polling lifecycle/takeover/follower registration, and the cohesive classic-vs-Threaded capability state/monitor/observation/polling orchestration. Polling also owns long-poll controller state, offset admission/persistence, and poll-loop wiring.
 - `bus` / `bus-api` / `bus-leader` / `bus-follower` / `ownership` / `target`: Threaded Mode multi-instance bus contracts, profile-scoped process/endpoint identity, local leader/follower IPC, leader-only orchestration, follower-side manual registration/session runtime, follower-routed Bot API calls, live message ownership, and `{ chatId, threadId? }` target identity. `bus` owns shared protocol, process identity, profile-aware local endpoints, and IPC primitives; `bus-leader` owns leader runtime, leader envelope handling, activation scheduling, and leader polling/server/prune orchestration; `bus-follower` owns process-stable manual-follower keys plus this Pi instance's follower-side registration, heartbeat, one-sequence authenticated client assembly, forwarded-update adaptation/receiving, recovery retry defaults, and routed API caller without any process spawning.
 - `sync`: demand-driven Telegram reconciliation, mutable sync-slice state, nested provisioning activity, and local assumption policy. It does not own a complete Telegram bot read-model; Bot API lacks a complete topic/thread listing surface. It owns sync slices, invalidation triggers, config-persist invalidation sequencing, stale-topic API recovery adaptation, observation intake, status/debug freshness, and reconciliation scheduling across bot identity, pairing assumptions, live target bindings, reservations, and transport health after meaningful observable signals. It should call narrower domain primitives rather than letting `index.ts`, `threads`, or `status` accumulate cross-cutting reconciliation policy.
 - `thread-reconciler`: Threaded Mode control-plane planning for Telegram thread/tab lifecycle. It owns the reconciliation state machine (`stable`, `provisioning`, `sync-required`, `cleanup-required`), pure plans, proof-before-delete rules, pending-provision protection, fresh-creation grace windows, leader-epoch checks, and the single policy authority for destructive thread cleanup actions. It excludes live Telegram API calls, inbound routing, menu rendering, and direct persistence.
@@ -103,7 +103,7 @@ Mirrored domain regressions live in `/tests/*.test.ts`. Shared test fixtures sho
 
 ## Configuration And Ownership
 
-Telegram configuration lives in `~/.pi/agent/telegram.json`. Polling ownership lives separately in `~/.pi/agent/locks.json` under `@llblab/pi-telegram`.
+Telegram configuration lives in `~/.pi/agent/telegram.json`. Bot/session identity (`botToken`, `botUsername`, `botId`, `allowedUserId`, `lastUpdateId`) persists only under `profiles.default` or `profiles.<name>`; shared handlers and assistant/voice/time settings stay top-level. Authoritative transport ownership lives separately in the pi-telegram-private `~/.pi/agent/tmp/telegram/owners.json` store. Its top-level slots are `default` and validated named profile names; unrelated extensions never read or write this file.
 
 ### Setup Flow
 
@@ -113,29 +113,28 @@ Telegram configuration lives in `~/.pi/agent/telegram.json`. Polling ownership l
 2. Otherwise use the first supported Telegram token environment variable.
 3. Otherwise show the example placeholder.
 
-`ctx.ui.input()` only supports placeholder text, so setup uses `ctx.ui.editor()` when a real default must appear already filled in. Persisted config is written through a private temp file plus atomic rename and left with `0600` permissions.
+`ctx.ui.input()` only supports placeholder text, so setup uses `ctx.ui.editor()` when a real default must appear already filled in. Bare and explicit `default` setup/connect commands address the same `profiles.default` entry. Persisted config is written through a private temp file plus atomic rename and left with `0600` permissions. On first load, legacy root identity moves into `profiles.default` in that same serialized atomic transaction when no conflicting canonical value exists; identical duplicates collapse, complementary fields merge, and conflicts reject the load without modifying the file.
 
 ### Runtime Ownership
 
-- `/telegram-connect` acquires or moves singleton polling ownership before polling starts.
-- `/telegram-disconnect` stops polling and releases ownership. In Threaded Mode it first names the current thread in a destructive confirmation, then tears down the disconnecting instance's bound Telegram thread: leaders delete their own thread directly, and followers send an authenticated exact-generation disconnect envelope and wait for confirmed leader cleanup before unregistering. Unconfirmed cleanup keeps binding/routing state available for an explicit retry.
-- Session start schedules Telegram polling resume asynchronously only when the existing lock already points at the current `pid`/`cwd`, or when a stale same-`cwd` lock can be safely replaced after process restart. Startup and `/resume` should not wait on Telegram leader election, Bot API probes, poller handoff, or thread reconciliation before restoring the Pi session.
-- Pi `print`/`json` run modes stay passive: they do not start or resume Telegram polling even if a lock is present. Older Pi runtimes without `ctx.mode` keep the previous compatibility behavior.
-- Inherited child sessions that see the same `telegram.json` but do not own the `pid`/`cwd` lock must not auto-start polling or call `getUpdates` unless the operator force-takes ownership.
-- Session replacement suspends polling/watchers without releasing ownership so the next session-start hook in the same process can resume. A registered follower snapshots its assigned target into a short-lived same-process handoff, stops the old receiver/heartbeat, and automatically re-registers the new session context through the live leader without marking or replacing its Telegram thread.
-- Live polling owners require explicit takeover confirmation.
-- Long-lived polling timers use snapshotted ownership context and stop local polling when the lock no longer points at their own process.
-- `locks.json` owns only external Telegram control/polling. Local extension and accepted queue state remain per Pi instance when ownership moves, but previews, final delivery, dispatch transport mutations, and other delayed work stop until exact direct or follower authority becomes valid again; ownership loss never permits delivery through replacement transport.
+- `/telegram-connect` acquires or moves the active profile's owner slot before polling starts. `/telegram-disconnect` stops polling and releases only that exact slot. In Threaded Mode disconnect first names the current thread in a destructive confirmation, then tears down the disconnecting instance's bound Telegram thread: leaders delete their own thread directly, and followers send an authenticated exact-generation disconnect envelope and wait for confirmed leader cleanup before unregistering. Unconfirmed cleanup keeps binding/routing state available for an explicit retry.
+- Session start schedules polling resume asynchronously only when the owner slot already points at the current `pid`/`cwd`, or when a stale same-`cwd` owner can be safely replaced after process restart. Startup and `/resume` do not wait on leader election, Bot API probes, poller handoff, or thread reconciliation before restoring the Pi session.
+- Pi `print`/`json` run modes stay passive. Inherited child sessions that share `telegram.json` but do not own the exact `pid`/`cwd` slot must not poll or call `getUpdates` unless the operator force-takes ownership.
+- Session replacement suspends polling/watchers without releasing ownership so the next session in the same process can resume. A registered follower snapshots its assigned target into a short-lived same-process handoff, stops the old receiver/heartbeat, and re-registers through the live leader without marking or replacing its Telegram thread.
+- Live external owners require explicit takeover confirmation. Long-lived timers compare against snapshotted owner identity and stop local transport work when the slot no longer matches.
+- `owners.json` owns only Telegram transport control. Local extension and accepted queue state remain per Pi instance when ownership moves, but previews, final delivery, dispatch transport mutations, and delayed Bot API work fail closed until exact direct or follower authority becomes valid again.
+- Every acquisition, refresh, release, takeover, and stale recovery serializes through the sibling `owners.json.transaction` guard. The guard publishes one private generation-named owner record atomically, validates filename/payload generation agreement, fences stale recovery and delayed release against replacement-owner ABA, and fails closed on malformed state, unverifiable ownership, contention timeout, or unsupported filesystem behavior. The JSON store publishes through a private same-directory temporary file and atomic rename; atomic payload replacement does not replace transaction serialization.
+- `owners.json` is authoritative and private. `state.json` remains an observable snapshot, `logs.jsonl` remains diagnostics, and followers remain authenticated bus registrations rather than ownership-file writers.
 
-Deleting `locks.json` resets runtime ownership without deleting Telegram configuration.
+Version `0.24.0` intentionally does not read or migrate the former agent-level `locks.json`; upgrading resets Telegram ownership. Run `/telegram-connect` when a fresh owner is not elected automatically. Delete `~/.pi/agent/tmp/telegram/owners.json` and its stale transaction guard, when no owner process is live, to reset only pi-telegram transport ownership without deleting configuration, diagnostics, or other extensions' state.
 
 ### Threaded Mode Multi-Instance Bus
 
 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, 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`, `tmp/telegram/logs.<profile>._prev.jsonl`, 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.
+Named Telegram profiles are orthogonal to Threaded Mode. The selected profile chooses the bot/session slice (`botToken`, `botId`, `botUsername`, `allowedUserId`, `lastUpdateId`) and scopes the `owners.json` slot, diagnostics logs, state files, thread/bus ownership, 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` slot. A different selected profile is a parallel bot runtime: its owner slot, `tmp/telegram/state.<profile>.json`, `tmp/telegram/logs.<profile>.jsonl`, `tmp/telegram/logs.<profile>._prev.jsonl`, thread bindings, Unix sockets, and Windows named pipes are isolated from the default profile and other named profiles while shared bridge settings remain top-level/global.
 
-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. Config persistence serializes cross-process writers and applies each recursive mutation delta to the latest disk snapshot, so named-profile offsets and unrelated global/profile updates do not stale-replace one another. Polling publishes only its monotonic `lastUpdateId` into the current config-store snapshot; it never persists the detached full config object captured at poll start, which would interpret newer Settings fields as deletions. Runtime profile switching follows stop-old/commit-new ordering: reload keeps the selected identity stable, old polling/lock/bus teardown finishes while all dynamic resolvers still point at the old profile, and only then may activation expose the new token, lock key, state path, target namespace, and IPC endpoint. 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.
+Profile reality follows three explicit storage classes. `telegram.json` shared settings and extension registries are process-global platform configuration; `profiles.default` and `profiles.<name>` bot/session fields plus observable transport/routing authority are profile-scoped; queues, active turns, ownership caches, menu state, and runtime controllers are session-local memory. Config persistence serializes cross-process writers and applies each recursive mutation delta to the latest disk snapshot, so named-profile offsets and unrelated global/profile updates do not stale-replace one another. Polling publishes only its monotonic `lastUpdateId` into the current config-store snapshot; it never persists the detached full config object captured at poll start, which would interpret newer Settings fields as deletions. Runtime profile switching follows stop-old/commit-new ordering: reload keeps the selected identity stable, old polling/lock/bus teardown finishes while all dynamic resolvers still point at the old profile, and only then may activation expose the new token, lock key, state path, target namespace, and IPC endpoint. 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. Absent follower bindings remain durable restoration hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; process absence and heartbeat pruning alone do not remove them. If an authenticated live follower carries an exact target that is absent from current bindings, the leader recovers it only behind a synchronous visibility probe: success activates it, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. 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.
 

package/docs/multi-instance-bus.md

@@ -71,16 +71,16 @@ The operator experience:
 
 In Threaded Mode, the lock means "this instance is the current Telegram bus leader" rather than "this instance is the only usable Telegram extension".
 
-Classic lock meaning:
+Classic ownership meaning:
 
 ```text
-locks.json / @llblab/pi-telegram -> polling/control owner
+tmp/telegram/owners.json / <profile-slot> -> polling/control owner
 ```
 
 Threaded Mode meaning:
 
 ```text
-locks.json / @llblab/pi-telegram -> bus leader identity + heartbeat
+tmp/telegram/owners.json / <profile-slot> -> bus leader identity + heartbeat
 ```
 
 Followers do not poll. They register with the leader and receive routed inbound updates from it. Followers still own their local queue, active-turn state, previews, final delivery planning, model switches, and Pi lifecycle. The leader owns only Telegram transport and update fanout. Pi session replacement (`new`) changes follower agent context, not bus membership: a registered follower preserves its registration and refreshes the live context instead of disconnecting. The Telegram bus belongs to the local set of cooperating visible Pi instances rather than to the first terminal session forever: if the visible terminal leader exits, a live registered follower can take over leadership.
@@ -200,7 +200,7 @@ Current portability audit:
 
 - Local bus transport: adapted. Unix-like platforms use filesystem socket paths; native Windows uses named pipes so no POSIX socket pathname is required.
 - Bus endpoint permissions: Unix sockets/directories use `chmod`; Windows named-pipe endpoints skip POSIX chmod/unlink path handling because the pipe is not a filesystem node.
-- Shared lock/config/state/temp files: path construction uses `path.join`/`path.resolve` under the Pi agent directory. File permission calls remain best-effort private-mode hardening; native Windows may emulate POSIX modes, so broad Windows ACL auditing is outside this extension's current local-bus baseline.
+- Ownership/config/state/temp files: path construction uses `path.join`/`path.resolve` under the Pi agent directory. File permission calls remain best-effort private-mode hardening; native Windows may emulate POSIX modes, so broad Windows ACL auditing is outside this extension's current local-bus baseline.
 - Process liveness: lock ownership uses `process.kill(pid, 0)`, which Node supports on Windows for existence checks. Cross-user permission failures are treated as alive, matching Unix semantics.
 - Shell/provider commands: outbound handler command templates remain operator-configured and platform-dependent; Threaded Mode bus portability does not guarantee every configured STT/TTS/shell provider is Windows-native.
 - Manual follower identity: process ids are used as local liveness/profile hints only, not cross-machine identifiers.
@@ -323,15 +323,21 @@ Target-scoped state requirements:
 
 There is no public `telegram.json` switch for the bus. Telegram private-chat Threaded Mode is the runtime switch: when Telegram exposes threads for the bot, the bridge enables the local bus; when Telegram runs as an ordinary private DM, the bridge uses classic private-chat flow as the base mode.
 
-Typical config remains just bot identity and authorization:
+Typical config remains just bot identity and authorization, stored in the canonical default profile:
 
 ```json
 {
-  "botToken": "...",
-  "allowedUserId": 123456789
+  "profiles": {
+    "default": {
+      "botToken": "...",
+      "allowedUserId": 123456789
+    }
+  }
 }
 ```
 
+Named bots use sibling `profiles.<name>` entries. Shared bridge settings remain top-level.
+
 Rules:
 
 - Classic mode is selected by Telegram capability: when private-chat threads are unavailable or disabled, the polling owner uses ordinary single-DM behavior and blocked instances do not register as followers. During a live downgrade from Threaded Mode, the current bus leader becomes the classic polling owner after two 2.5-second capability-monitor probes and followers disconnect; if classic polling restore fails transiently, later monitor ticks retry the restore instead of allowing a follower takeover. Followers must not turn the downgrade into a takeover while active thread bindings prove the singleton owner was already established by the bus leader.
@@ -345,8 +351,8 @@ 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. 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.
+- `tmp/telegram/owners.json`: authoritative extension-local transport owners keyed by `default` or named profile. Each owner contains the bus leader identity, capability secret, heartbeat, generation, and cleanup fencing epoch. Mutations serialize through `owners.json.transaction`; followers never write owner slots. The local bus endpoint is derived from the agent directory by default; legacy `busSocketPath` entry fields are tolerated inside current owner records 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. Every process on one Telegram profile reads this shared path, but only the active transport owner may persist it; followers become writers only after promotion. Status-only persistence refreshes disk-backed bindings before serialization so an already-loaded stale view cannot erase newer leader records. It mirrors `/telegram-status`-style projections: top-level `bot` stores bot-wide capability state such as `threadMode: "unknown" | "enabled" | "disabled"`, `runtime` identifies leader/follower role and process status, `liveRoster` mirrors followers/current targets/reservations, `diagnostics` mirrors status/debug signals, `threads` stores current routeable bindings, `bot.lastSlot` stores the compact slot cursor used when all current threads are gone, and `reservations` records short-lived slot collision guards.
 - Local bus endpoints: Unix-like platforms expose stable `tmp/telegram/bus.sock` and `tmp/telegram/followers/*` symlinks backed by private generation sockets; native Windows uses deterministic named pipes under `\\.\pipe\pi-telegram-...`. These are transient IPC endpoints, not durable routing state.
 
 The bridge must not keep a separate durable `telegram-targets.json` history. `state.json` retains current stable manual-follower bindings as restart hints, but they never authorize routing without a matching authenticated live registration. Stale/offline/failed observations are not reusable delivery authority. `sync` remains event-driven assumption reconciliation rather than a full Telegram bot-state mirror because Bot API exposes no complete thread listing surface. Non-current routeable thread bindings are pruned during load/persist; old session records must not be retained just to compute the next slot because `bot.lastSlot` is the only durable cursor. Previous-process leader bindings are treated as occupied TTL-bounded reservations until Telegram confirms deletion: reload/startup may close/delete/probe the old thread, known reservations are retried proactively on leader startup, and if Telegram still accepts the old thread id, the new leader should provision the next free slot (`B`, `C`, …) rather than creating a duplicate same-letter tab or blocking startup on Telegram UI convergence. Routing must use live current threads/follower registry, never reservations. The bus leader provisions its own thread during bus startup/connect and provisions follower threads on `follower.register`; registered followers also live in the leader's in-memory registry and communicate over the local bus socket. The live follower registry can resolve a follower by exact `{ chatId, threadId? }`; the leader uses that target ownership to forward message and edited-message updates to followers, and the follower receiver accepts those updates in addition to callbacks and reactions. Terminal status and `[telegram|thread:name]` resolve the matching current-instance identity through the same target-aware path, preferring registered local metadata over stale shared bindings. Media album grouping and split-text coalescing keys include the thread target, queue reaction mutations can scope by chat/thread to avoid cross-target message-id collisions, active-turn target is exposed for lifecycle cleanup and local direct-tool defaults, transport reply dedup is chat/thread-scoped, stored menu state is keyed by chat/message so callback state lookup cannot collide across chats, and generated button turns plus section prompt/open actions preserve the callback thread target. `telegram_message` and immediate `telegram_attach` delivery can also carry an explicit `thread_id` with `chat_id`; when a follower is registered, their default direct-tool target is the assigned thread target and the bus-aware API runtime routes the send through the leader instead of calling Bot API transport locally.

package/docs/public-api.md

@@ -78,12 +78,16 @@ Configuration lives in `~/.pi/agent/telegram.json` unless `PI_CODING_AGENT_DIR`
 Stable config keys:
 
 ```ts
-interface TelegramConfig {
-  botToken?: string;
+interface TelegramBotProfile {
+  botToken: string;
   botUsername?: string; // runtime-managed
   botId?: number; // runtime-managed
   allowedUserId?: number;
   lastUpdateId?: number; // runtime-managed
+}
+
+interface TelegramConfig {
+  profiles?: Record<string, TelegramBotProfile>; // includes `default`
   inboundHandlers?: TelegramInboundHandlerConfig[];
   attachmentHandlers?: TelegramInboundHandlerConfig[]; // compatibility alias
   outboundHandlers?: TelegramOutboundHandlerConfig[];
@@ -103,6 +107,8 @@ interface TelegramConfig {
 }
 ```
 
+Bot/session identity always persists under `profiles.<name>`. The ordinary setup path uses `profiles.default`; `/telegram-setup default` and `/telegram-connect default` are exact aliases for the bare commands. Named profiles use the same shape. Shared handlers plus `assistant`, `voice`, and `time` remain top-level. On the first `0.24.0` load, unambiguous legacy root identity moves atomically into `profiles.default`; identical duplicates collapse, complementary fields merge, and conflicting values fail closed without modifying the file.
+
 Hidden/default semantics are represented by absence:
 
 - `assistant.proactivePush` defaults to `true`; omit it to keep projection enabled, or set it explicitly to `false` to disable it. When enabled, each completed public assistant text block from local or autonomous work is projected to the authorized Telegram target once and in source order. This includes visible intermediate commentary/checkpoints and the final block. It excludes token deltas, hidden reasoning, tool calls/arguments/results, Telegram-owned turns, empty blocks, and stale authority. Projection uses the configured Rich or HTML assistant renderer and binds admitted work to the exact target, profile/token transport generation, direct leader epoch or follower registration generation, and session generation. The old top-level `proactivePush` key is ignored; move the setting manually under `assistant`.

package/docs/sections.md

@@ -436,7 +436,7 @@ Available programmatically via `getTelegramSectionDiagnostics()`. Main-menu/sett
 
 - [Callback Namespaces](./callback-namespaces.md): defines `section:` as pi-telegram-owned prefix. Sections use namespaced callbacks but authors never hand-roll them
 - [Updates](./updates.md): raw update interception for direct Telegram update access. Sections are the structured UI layer above
-- [Extension Locks](../docs/locks.md) (polling): same identity key rules (`package.json/name` → canonical id)
+- [Architecture](./architecture.md#configuration-and-ownership): pi-telegram transport ownership is extension-local and independent from section registration identity
 - [Command Templates](./command-templates.md): sections do not execute command templates by default. UI registration + callback routing, not shell execution
 
 ## 15. Demo Extension

package/docs/updates.md

@@ -136,7 +136,7 @@ This means:
 
 ## Ownership semantics
 
-The handler registry is ownership-agnostic and does not interact with the `locks.json` singleton lock documented in [Locks](./locks.md). When the locked polling runtime stops `pi-telegram`'s `getUpdates` loop, for example after ownership is moved to another pi process, handlers stop receiving updates because no updates are being fetched. They are not unregistered.
+The handler registry is ownership-agnostic and does not interact with the extension-local transport owner slots documented in [Architecture](./architecture.md#configuration-and-ownership). When the polling runtime loses its `owners.json` slot and stops `getUpdates`, handlers stop receiving updates because no updates are being fetched; they are not unregistered.
 
 If a layered extension needs to react to ownership changes, it should observe `pi-telegram` lifecycle events through the standard pi extension hooks rather than through the handler registry.
 

package/index.ts

@@ -7,18 +7,18 @@
 import * as Activity from "./lib/activity.ts";
 import * as Bindings from "./lib/bindings.ts";
 import * as BusApi from "./lib/bus-api.ts";
-import * as Bus from "./lib/bus.ts";
 import * as BusFollower from "./lib/bus-follower.ts";
 import * as BusLeader from "./lib/bus-leader.ts";
 import * as BusTransport from "./lib/bus-transport.ts";
+import * as Bus from "./lib/bus.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Commands from "./lib/commands.ts";
 import * as Config from "./lib/config.ts";
 import * as Delivery from "./lib/delivery.ts";
-import * as Threads from "./lib/threads.ts";
 import * as Inbound from "./lib/inbound.ts";
 import * as Lifecycle from "./lib/lifecycle.ts";
 import * as Locks from "./lib/locks.ts";
+import * as Logs from "./lib/logs.ts";
 import * as Media from "./lib/media.ts";
 import * as MenuQueue from "./lib/menu-queue.ts";
 import * as MenuSettings from "./lib/menu-settings.ts";
@@ -35,13 +35,13 @@ import * as Queue from "./lib/queue.ts";
 import * as Replies from "./lib/replies.ts";
 import * as Routing from "./lib/routing.ts";
 import * as Runtime from "./lib/runtime.ts";
-import * as Logs from "./lib/logs.ts";
 import * as Sections from "./lib/sections.ts";
 import * as Status from "./lib/status.ts";
 import * as Sync from "./lib/sync.ts";
 import * as TelegramApi from "./lib/telegram-api.ts";
 import * as TextGroups from "./lib/text-groups.ts";
 import * as ThreadReconciler from "./lib/thread-reconciler.ts";
+import * as Threads from "./lib/threads.ts";
 import * as TimeInjection from "./lib/time-injection.ts";
 import * as Updates from "./lib/updates.ts";
 import * as Voice from "./lib/voice.ts";
@@ -465,8 +465,7 @@ export default function (pi: Pi.ExtensionAPI) {
         isTransportStampActive: telegramTransportStampRuntime.isActive,
         ownsDirect: lockRuntime.owns,
         getDirectEpoch: lockRuntime.getOwnedLeaderEpoch,
-        isFollowerRegistered:
-          telegramBusFollowerRegistrationState.isRegistered,
+        isFollowerRegistered: telegramBusFollowerRegistrationState.isRegistered,
         getFollowerGeneration:
           telegramBusFollowerRegistrationState.getGeneration,
       },
@@ -776,8 +775,7 @@ export default function (pi: Pi.ExtensionAPI) {
           return telegramActiveBusAuthSecret;
         },
         ...forwardedRouteHandlers,
-        prepareForwardedMessage:
-          textGroupRuntime.prepareForwardedMessage,
+        prepareForwardedMessage: textGroupRuntime.prepareForwardedMessage,
         recordRuntimeEvent,
       },
       targetReplacement: {

package/lib/bindings.ts

@@ -204,15 +204,7 @@ export function registerTelegramCommandsAndTools({
               );
             }
             await configStore.load();
-            const latestConfig = configStore.getStoredConfig();
-            configStore.activateProfile(undefined);
-            configStore.set({
-              ...latestConfig,
-              profiles: {
-                ...(latestConfig.profiles ?? {}),
-                [profileName]: profile,
-              },
-            });
+            configStore.setProfile(profileName, profile);
             configStore.activateProfile(profileName);
             await onTransportChanged?.();
             await persistConfig(configStore.get());

package/lib/commands.ts

@@ -4,7 +4,10 @@
  * Owns Telegram slash-command normalization, bot command metadata, and pi-side command registration behind runtime ports
  */
 
-import { pairTelegramUserIfNeeded } from "./config.ts";
+import {
+  pairTelegramUserIfNeeded,
+  TELEGRAM_DEFAULT_PROFILE_NAME,
+} from "./config.ts";
 import type { ExtensionAPI, ExtensionCommandContext } from "./pi.ts";
 import type { TelegramBridgeStatusLineOptions } from "./status.ts";
 import {
@@ -321,7 +324,7 @@ function parseTelegramProfileArg(args: string): string | undefined {
   const word = args.trim().split(/\s+/)[0];
   if (!word || word.length === 0) return undefined;
   if (word.startsWith("-")) return undefined;
-  return word;
+  return word === TELEGRAM_DEFAULT_PROFILE_NAME ? undefined : word;
 }
 
 function formatTelegramTakeoverTitle(ctx: ExtensionCommandContext): string {

package/lib/config.ts

@@ -15,7 +15,12 @@ import {
   writeFileSync,
 } from "node:fs";
 import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
-import { resolveAgentDir, resolveTelegramConfigPath } from "./paths.ts";
+import {
+  resolveAgentDir,
+  resolveTelegramConfigPath,
+  TELEGRAM_DEFAULT_PROFILE_NAME,
+} from "./paths.ts";
+export { TELEGRAM_DEFAULT_PROFILE_NAME } from "./paths.ts";
 
 import type { CommandTemplateObjectConfig } from "./command-templates.ts";
 import type { TelegramInboundHandlerConfig } from "./inbound.ts";
@@ -52,10 +57,15 @@ export interface ResolvedTelegramTimeConfig {
 export type TelegramAssistantRenderingMode = "rich" | "html";
 
 export interface TelegramConfig {
+  /** @deprecated persisted identity belongs in profiles.default; retained for effective/legacy views */
   botToken?: string;
+  /** @deprecated persisted identity belongs in profiles.default; retained for effective/legacy views */
   botUsername?: string;
+  /** @deprecated persisted identity belongs in profiles.default; retained for effective/legacy views */
   botId?: number;
+  /** @deprecated persisted identity belongs in profiles.default; retained for effective/legacy views */
   allowedUserId?: number;
+  /** @deprecated persisted identity belongs in profiles.default; retained for effective/legacy views */
   lastUpdateId?: number;
   inboundHandlers?: TelegramInboundHandlerConfig[];
   attachmentHandlers?: TelegramInboundHandlerConfig[];
@@ -77,7 +87,7 @@ export interface TelegramConfig {
     sendTranscript?: boolean;
   };
   time?: TelegramTimeConfig;
-  /** Named bot/session profiles (e.g. "work", "omp"). */
+  /** Canonical bot/session profiles, including profiles.default. */
   profiles?: Record<string, TelegramBotProfile>;
 }
 
@@ -98,7 +108,6 @@ export interface TelegramBotProfile {
 /** Profile names must contain only lowercase ASCII letters and digits; max 32 chars. */
 const TELEGRAM_PROFILE_NAME_PATTERN = /^[a-z0-9]{1,32}$/;
 const TELEGRAM_RESERVED_PROFILE_NAMES: ReadonlySet<string> = new Set([
-  "default",
   "main",
   "active",
 ]);
@@ -111,10 +120,8 @@ export function isValidTelegramProfileName(name: string): boolean {
 }
 
 /**
- * Resolve the effective config for a named (or default) profile.
- * Returns bot/session fields from the named profile, falling back to
- * top-level fields for the default profile. Shared bridge settings
- * always come from the top level.
+ * Resolve bot/session identity from the canonical default or named profile.
+ * Shared bridge settings always remain top-level.
  */
 export function resolveTelegramActiveProfile(
   config: TelegramConfig,
@@ -126,16 +133,9 @@ export function resolveTelegramActiveProfile(
   allowedUserId?: number;
   lastUpdateId?: number;
 } {
-  if (!profileName || !config.profiles?.[profileName]) {
-    return {
-      botToken: config.botToken,
-      botUsername: config.botUsername,
-      botId: config.botId,
-      allowedUserId: config.allowedUserId,
-      lastUpdateId: config.lastUpdateId,
-    };
-  }
-  const profile = config.profiles[profileName];
+  const effectiveProfileName = profileName ?? TELEGRAM_DEFAULT_PROFILE_NAME;
+  const profile = config.profiles?.[effectiveProfileName];
+  if (!profile) return {};
   return {
     botToken: profile.botToken,
     botUsername: profile.botUsername,
@@ -154,6 +154,7 @@ export interface TelegramConfigStore {
   get: () => TelegramConfig;
   getStoredConfig: () => TelegramConfig;
   set: (config: TelegramConfig) => void;
+  setProfile: (profileName: string, profile: TelegramBotProfile) => void;
   update: (mutate: (config: TelegramConfig) => void) => void;
   activateProfile: (profileName: string | undefined) => boolean;
   getActiveProfileName: () => string | undefined;
@@ -396,10 +397,91 @@ export function getTelegramProfileFields(
   if (!token) return undefined;
   return {
     botToken: token,
-    botUsername: config.botUsername,
-    botId: config.botId,
-    allowedUserId: config.allowedUserId,
-    lastUpdateId: config.lastUpdateId,
+    ...(config.botUsername !== undefined
+      ? { botUsername: config.botUsername }
+      : {}),
+    ...(config.botId !== undefined ? { botId: config.botId } : {}),
+    ...(config.allowedUserId !== undefined
+      ? { allowedUserId: config.allowedUserId }
+      : {}),
+    ...(config.lastUpdateId !== undefined
+      ? { lastUpdateId: config.lastUpdateId }
+      : {}),
+  };
+}
+
+function omitTelegramRootProfileFields(config: TelegramConfig): TelegramConfig {
+  const {
+    botToken: _botToken,
+    botUsername: _botUsername,
+    botId: _botId,
+    allowedUserId: _allowedUserId,
+    lastUpdateId: _lastUpdateId,
+    ...sharedConfig
+  } = config;
+  return sharedConfig;
+}
+
+export function normalizeTelegramDefaultProfileConfig(config: TelegramConfig): {
+  config: TelegramConfig;
+  changed: boolean;
+} {
+  const hasLegacyRootProfile = [
+    "botToken",
+    "botUsername",
+    "botId",
+    "allowedUserId",
+    "lastUpdateId",
+  ].some((field) => Object.hasOwn(config, field));
+  if (!hasLegacyRootProfile) return { config, changed: false };
+  const canonicalProfile = config.profiles?.[TELEGRAM_DEFAULT_PROFILE_NAME];
+  const legacyToken = config.botToken?.trim();
+  if (Object.hasOwn(config, "botToken") && !legacyToken) {
+    throw new Error("Legacy Telegram default profile has no bot token");
+  }
+  const legacyProfile: Partial<TelegramBotProfile> = {
+    ...(legacyToken ? { botToken: legacyToken } : {}),
+    ...(config.botUsername !== undefined
+      ? { botUsername: config.botUsername }
+      : {}),
+    ...(config.botId !== undefined ? { botId: config.botId } : {}),
+    ...(config.allowedUserId !== undefined
+      ? { allowedUserId: config.allowedUserId }
+      : {}),
+    ...(config.lastUpdateId !== undefined
+      ? { lastUpdateId: config.lastUpdateId }
+      : {}),
+  };
+  if (!canonicalProfile && !legacyToken) {
+    throw new Error("Legacy Telegram default profile has no bot token");
+  }
+  const hasConflict = canonicalProfile
+    ? Object.entries(legacyProfile).some(
+        ([field, value]) =>
+          Object.hasOwn(canonicalProfile, field) &&
+          !configValuesEqual(
+            canonicalProfile[field as keyof TelegramBotProfile],
+            value,
+          ),
+      )
+    : false;
+  if (hasConflict) {
+    throw new Error(
+      "Conflicting Telegram default profile identity at root and profiles.default",
+    );
+  }
+  const normalizedProfile: TelegramBotProfile = canonicalProfile
+    ? { ...legacyProfile, ...canonicalProfile }
+    : (legacyProfile as TelegramBotProfile);
+  return {
+    config: {
+      ...omitTelegramRootProfileFields(config),
+      profiles: {
+        ...(config.profiles ?? {}),
+        [TELEGRAM_DEFAULT_PROFILE_NAME]: normalizedProfile,
+      },
+    },
+    changed: true,
   };
 }
 
@@ -407,16 +489,12 @@ function applyTelegramProfile(
   config: TelegramConfig,
   profileName: string | undefined,
 ): TelegramConfig {
-  if (!profileName) return config;
-  const profile = config.profiles?.[profileName];
-  if (!profile) return config;
+  const effectiveProfileName = profileName ?? TELEGRAM_DEFAULT_PROFILE_NAME;
+  const profile = config.profiles?.[effectiveProfileName];
+  if (!profile) return omitTelegramRootProfileFields(config);
   return {
-    ...config,
-    botToken: profile.botToken,
-    botUsername: profile.botUsername,
-    botId: profile.botId,
-    allowedUserId: profile.allowedUserId,
-    lastUpdateId: profile.lastUpdateId,
+    ...omitTelegramRootProfileFields(config),
+    ...profile,
   };
 }
 
@@ -425,18 +503,13 @@ function storeTelegramEffectiveConfig(
   nextConfig: TelegramConfig,
   profileName: string | undefined,
 ): TelegramConfig {
-  if (!profileName) return nextConfig;
+  const effectiveProfileName = profileName ?? TELEGRAM_DEFAULT_PROFILE_NAME;
   const profile = getTelegramProfileFields(nextConfig);
   const profiles = { ...(baseConfig.profiles ?? {}) };
-  if (profile) profiles[profileName] = profile;
-  else delete profiles[profileName];
+  if (profile) profiles[effectiveProfileName] = profile;
+  else delete profiles[effectiveProfileName];
   return {
-    ...nextConfig,
-    botToken: baseConfig.botToken,
-    botUsername: baseConfig.botUsername,
-    botId: baseConfig.botId,
-    allowedUserId: baseConfig.allowedUserId,
-    lastUpdateId: baseConfig.lastUpdateId,
+    ...omitTelegramRootProfileFields(nextConfig),
     profiles: Object.keys(profiles).length > 0 ? profiles : undefined,
   };
 }
@@ -444,7 +517,9 @@ function storeTelegramEffectiveConfig(
 export function createTelegramConfigStore(
   options: TelegramConfigStoreOptions = {},
 ): TelegramConfigStore {
-  let config: TelegramConfig = cloneTelegramConfig(options.initialConfig ?? {});
+  let config: TelegramConfig = normalizeTelegramDefaultProfileConfig(
+    cloneTelegramConfig(options.initialConfig ?? {}),
+  ).config;
   let persistedConfig: TelegramConfig = {};
   let mutationVersion = 0;
   let persistQueue: Promise<void> = Promise.resolve();
@@ -465,14 +540,33 @@ export function createTelegramConfigStore(
     get: getEffectiveConfig,
     getStoredConfig: () => config,
     set: setEffectiveConfig,
+    setProfile: (profileName, profile) => {
+      config = {
+        ...omitTelegramRootProfileFields(config),
+        profiles: {
+          ...(config.profiles ?? {}),
+          [profileName]: cloneTelegramConfig(profile),
+        },
+      };
+      mutationVersion += 1;
+    },
     update: (mutate) => {
       const nextConfig = getEffectiveConfig();
       mutate(nextConfig);
       setEffectiveConfig(nextConfig);
     },
     activateProfile: (profileName) => {
-      if (profileName && !config.profiles?.[profileName]) return false;
-      activeProfileName = profileName;
+      const normalizedProfileName =
+        !profileName || profileName === TELEGRAM_DEFAULT_PROFILE_NAME
+          ? undefined
+          : profileName;
+      if (
+        normalizedProfileName &&
+        !config.profiles?.[normalizedProfileName]
+      ) {
+        return false;
+      }
+      activeProfileName = normalizedProfileName;
       return true;
     },
     getActiveProfileName: () => activeProfileName,
@@ -491,7 +585,7 @@ export function createTelegramConfigStore(
       setEffectiveConfig(nextConfig);
     },
     load: async () => {
-      config = await readTelegramConfig(configPath, {
+      const loadedConfig = await readTelegramConfig(configPath, {
         onInvalidConfig: (recovery) => {
           options.recordRuntimeEvent?.("config", recovery.error, {
             phase: "load",
@@ -500,6 +594,32 @@ export function createTelegramConfigStore(
           });
         },
       });
+      let normalized: ReturnType<typeof normalizeTelegramDefaultProfileConfig>;
+      try {
+        normalized = normalizeTelegramDefaultProfileConfig(loadedConfig);
+      } catch (error) {
+        options.recordRuntimeEvent?.("config", error, {
+          phase: "default-profile-normalize",
+          configPath,
+        });
+        throw error;
+      }
+      config = normalized.changed
+        ? withTelegramFileTransaction(`${configPath}.transaction`, () => {
+            const latestConfig = readTelegramConfigForTransaction(configPath);
+            const latestNormalized = normalizeTelegramDefaultProfileConfig(
+              latestConfig,
+            );
+            if (latestNormalized.changed) {
+              writeTelegramConfigInTransaction(
+                agentDir,
+                configPath,
+                latestNormalized.config,
+              );
+            }
+            return latestNormalized.config;
+          })
+        : normalized.config;
       persistedConfig = cloneTelegramConfig(config);
       mutationVersion += 1;
     },

package/lib/locks.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram singleton lock helpers
- * Zones: shared singleton, filesystem, telegram runtime ownership
- * Owns shared locks.json access and Telegram bridge ownership semantics
+ * Zones: telegram ownership, filesystem, transport authority
+ * Owns extension-local owners.json access and Telegram bridge ownership semantics
  */
 
 import {
@@ -19,9 +19,9 @@ import {
 } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { basename, dirname, join } from "node:path";
-import { resolveTelegramLocksPath } from "./paths.ts";
+import { resolveTelegramOwnersPath } from "./paths.ts";
 
-export const TELEGRAM_LOCK_KEY = "@llblab/pi-telegram";
+export const TELEGRAM_LOCK_KEY = "default";
 export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 5_000;
 const TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS = 5;
 const TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS = 25;
@@ -42,18 +42,17 @@ function allocateTelegramLockRuntimeGeneration(): number {
   return generation;
 }
 
-function getLocksPath(): string {
-  return resolveTelegramLocksPath();
+function getOwnersPath(): string {
+  return resolveTelegramOwnersPath();
 }
 
 /**
- * Resolve the scoped lock key for the active Telegram profile.
- * Default profile → @llblab/pi-telegram
- * Named profile → @llblab/pi-telegram:<name>
+ * Resolve the extension-local owner slot for the active Telegram profile.
+ * Default profile → default
+ * Named profile → the validated profile name
  */
 export function resolveTelegramLockKey(activeProfile?: string): string {
-  if (activeProfile) return `${TELEGRAM_LOCK_KEY}:${activeProfile}`;
-  return TELEGRAM_LOCK_KEY;
+  return activeProfile || TELEGRAM_LOCK_KEY;
 }
 
 export interface TelegramActiveProfileGetter {
@@ -139,7 +138,7 @@ export interface TelegramLockRuntimeOptions {
   staleHeartbeatMs?: number;
 }
 
-export function readLocks(path = getLocksPath()): Record<string, unknown> {
+export function readLocks(path = getOwnersPath()): Record<string, unknown> {
   if (!existsSync(path)) return {};
   try {
     const value = JSON.parse(readFileSync(path, "utf8"));
@@ -161,7 +160,7 @@ function readLocksForTransaction(path: string): Record<string, unknown> {
   }
   const value: unknown = JSON.parse(source);
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(`Invalid Telegram lock registry: ${path}`);
+    throw new Error(`Invalid Telegram owner store: ${path}`);
   }
   return value as Record<string, unknown>;
 }
@@ -856,7 +855,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
   options: TelegramLockRuntimeOptions = {},
 ): TelegramLockRuntime<TContext> {
   const key = options.key ?? TELEGRAM_LOCK_KEY;
-  const locksPath = options.locksPath ?? getLocksPath();
+  const locksPath = options.locksPath ?? getOwnersPath();
   const pid = options.pid ?? process.pid;
   const isAlive = options.isProcessAlive ?? isProcessAlive;
   const getNowMs = options.getNowMs ?? Date.now;

package/lib/menu-settings.ts

@@ -74,7 +74,11 @@ export interface TelegramSettingsMenuRuntime<TContext> {
     query: {
       id: string;
       data?: string;
-      message?: { message_id?: number; chat?: { id?: number } };
+      message?: {
+        message_id?: number;
+        message_thread_id?: number;
+        chat?: { id?: number };
+      };
     },
     ctx: TContext,
   ) => Promise<boolean>;
@@ -98,6 +102,7 @@ export interface TelegramSettingsMenuRuntimeDeps<
   getModelMenuState: (
     chatId: number,
     ctx: TContext,
+    threadId?: number,
   ) => Promise<TelegramModelMenuState<TModel>>;
   getStoredModelMenuState: (
     messageId: number | undefined,
@@ -672,7 +677,11 @@ export function createTelegramSettingsMenuRuntime<
           );
           return true;
         }
-        state = await deps.getModelMenuState(chatId, ctx);
+        state = await deps.getModelMenuState(
+          chatId,
+          ctx,
+          query.message?.message_thread_id,
+        );
         state.messageId = messageId;
         state.mode = "settings";
         deps.storeModelMenuState(state);

package/lib/paths.ts

@@ -10,6 +10,8 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+export const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
+
 export interface TelegramAgentDirResolutionInput {
   env?: Partial<Pick<NodeJS.ProcessEnv, "PI_CODING_AGENT_DIR">>;
   execPath?: string;
@@ -45,18 +47,19 @@ export function resolveTelegramConfigPath(): string {
   return join(resolveAgentDir(), "telegram.json");
 }
 
-/** Telegram singleton lock file (<agentDir>/locks.json). */
-export function resolveTelegramLocksPath(): string {
-  return join(resolveAgentDir(), "locks.json");
-}
-
 /** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
 export function resolveTelegramTempDir(agentDir = resolveAgentDir()): string {
   return join(agentDir, "tmp", "telegram");
 }
 
+/** Telegram transport ownership store (<agentDir>/tmp/telegram/owners.json). */
+export function resolveTelegramOwnersPath(): string {
+  return join(resolveTelegramTempDir(), "owners.json");
+}
+
 export function getTelegramProfilePathSuffix(profileName?: string): string {
-  return profileName ? `.${profileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}` : "";
+  if (!profileName || profileName === TELEGRAM_DEFAULT_PROFILE_NAME) return "";
+  return `.${profileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`;
 }
 
 export function resolveTelegramProfileTempFilePath(

package/lib/status.ts

@@ -4,6 +4,8 @@
  * Builds usage, cost, and context summaries for the interactive Telegram status view
  */
 
+const TELEGRAM_STATUS_DEFAULT_PROFILE_NAME = "default";
+
 export type TelegramStatusQueueLane = "control" | "priority" | "default";
 
 export interface TelegramUsageStats {
@@ -624,7 +626,9 @@ export function createTelegramBridgeStatusRuntime<
     getBridgeStatusLineState: () => {
       const config = deps.getConfig();
       const botThreadMode = deps.getBotThreadMode?.();
-      const activeProfileName = deps.getActiveProfileName?.();
+      const activeProfileName = deps.getActiveProfileName
+        ? (deps.getActiveProfileName() ?? TELEGRAM_STATUS_DEFAULT_PROFILE_NAME)
+        : undefined;
       return {
         hasBotToken: Boolean(config.botToken),
         botUsername: config.botUsername,
@@ -1066,13 +1070,16 @@ function buildTelegramBridgeCompactStatusLines(
     : state.activeSourceMessageIds?.length
       ? "active"
       : "idle";
-  const profileSuffix = state.activeProfileName
-    ? `.${state.activeProfileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`
+  const diagnosticsProfileName =
+    state.activeProfileName === TELEGRAM_STATUS_DEFAULT_PROFILE_NAME
+      ? undefined
+      : state.activeProfileName;
+  const profileSuffix = diagnosticsProfileName
+    ? `.${diagnosticsProfileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`
     : "";
-  const profileSlug = profileSuffix.slice(1);
   const diagnosticsPaths = state.diagnosticPaths ?? {
     state: `~/.pi/agent/tmp/telegram/state${profileSuffix}.json`,
-    logs: `~/.pi/agent/tmp/telegram/logs${profileSlug ? `.${profileSlug}` : ""}.jsonl`,
+    logs: `~/.pi/agent/tmp/telegram/logs${profileSuffix}.jsonl`,
   };
   return [
     "connection:",

package/package.json

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

package/docs/locks.md

@@ -1,156 +0,0 @@
-# Extension Locks Standard
-
-**Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
-
----
-
-`locks.json` is a shared registry for singleton pi extensions.
-
-Path:
-
-```text
-~/.pi/agent/locks.json
-```
-
-## Shape
-
-```json
-{
-  "@scope/pi-singleton": {
-    "pid": 2590864,
-    "cwd": "/home/user/project"
-  }
-}
-```
-
-Top-level keys are extension identities. Values are JSON objects owned by that extension.
-
-## Identity key
-
-Use the most stable available identity:
-
-1. `package.json/name` for npm-style pi packages
-2. Directory name when the extension entrypoint is `index.ts` but there is no package name
-3. File basename when the extension is a single file
-
-For npm-style package extensions, the canonical value is the `package.json` `name`. Implementations may keep that value as a small local constant when it is clearer than runtime package introspection. The fallback rules are only for unpackaged extensions.
-
-Examples:
-
-```text
-extensions/pi-singleton/package.json name=@scope/pi-singleton -> @scope/pi-singleton
-extensions/pi-singleton/index.ts without package.json         -> pi-singleton
-extensions/pi-singleton.ts                                    -> pi-singleton
-```
-
-## Required fields
-
-```json
-{
-  "pid": 2590864
-}
-```
-
-`pid` is the process that currently owns the singleton runtime. `cwd` should be stored when ownership is tied to a pi session directory.
-
-During a user-initiated start/connect event, an extension should:
-
-1. Read its lock entry
-2. If `pid` is stale, replace the entry
-3. If `pid` and `cwd` match the current pi instance, refresh or keep the entry
-4. If a live external owner exists, ask interactively whether to move singleton ownership here
-
-## Acquisition timing
-
-Lock writes must be caused by an explicit user-initiated runtime event, such as a start/connect command or a confirmed takeover prompt.
-
-Extension initialization and session-start hooks may read `locks.json`, update local status, install ownership watchers, and resume local work when the existing lock already points at the current `pid`/`cwd`. After a full process restart, a session-start hook may replace a stale lock from the same `cwd` to restore explicitly requested ownership. They must not create ownership from an inactive lock, take over a live external owner, or replace a stale lock from another directory by themselves. Such locks should stay visible as state until the user runs the start/connect command. Session replacement should suspend local runtime work and ownership watchers without releasing the lock, so the next session in the same `pid`/`cwd` can resume from explicit ownership.
-
-## Optional fields
-
-Extensions may add compact fields when useful:
-
-```json
-{
-  "pid": 2590864,
-  "cwd": "/repo/project",
-  "mode": "connected",
-  "updatedAt": "2026-04-28T00:00:00.000Z"
-}
-```
-
-Do not print optional fields in normal UI unless they help the user act.
-
-## Ownership rules
-
-- One top-level key per singleton extension
-- An extension may only mutate its own key
-- Other keys must be preserved exactly
-- If `cwd` is present, active-here ownership means both `pid` and `cwd` match the current pi instance
-- Human-readable diagnostics should say `active here`, `active elsewhere`, or `stale`
-- Debug data belongs in `locks.json`, not in normal status output
-
-## Runtime status
-
-Singleton extensions with footer/status presence should expose quiet but explicit local state:
-
-- `off` when this pi instance does not own the singleton runtime
-- `on` when this pi instance owns the runtime but has no pending runtime detail to show
-- `[16:32:39]` when the runtime owns scheduled work and can show the next countdown
-
-Extensions may prefix active states with their own compact name, such as `telegram on` or `wakeup [00:10:00]`. Quiet idle states may be hidden when status-line width is more valuable than an explicit off marker.
-
-## Interactive takeover
-
-Start/connect commands should make singleton moves easy:
-
-1. If no live owner exists, take ownership without an extra prompt
-2. If a live external owner exists, ask whether to move singleton ownership to this pi instance
-3. On confirmation, write the current `{ "pid": ..., "cwd": ... }` to this extension's key in `locks.json`
-4. The previous owner must notice that `locks.json` no longer points at its own `pid`/`cwd` and stop local runtime work without deleting the new lock
-
-Takeover prompts should use the extension name as the dialog title, then the question, a blank line, and source/target lines:
-
-```text
-pi-singleton
-move singleton lock here?
-
-from: pid 2590864, cwd /old
-to: /new
-```
-
-Avoid repeating the extension name in the body. Color is encouraged: extension title/name accent, question warning, `from:`/`to:` muted.
-
-The previous owner may use `fs.watch`, mtime polling, or an existing status/timer tick. Long-lived watchers should compare against a snapshotted `pid`/`cwd` identity rather than a live pi context object, because session replacement such as `/new` makes captured contexts stale. The important contract is graceful local shutdown after ownership mismatch.
-
-## Reset
-
-Delete `~/.pi/agent/locks.json` to reset singleton runtime ownership for all participating extensions without deleting their configuration files.
-
-## Atomicity
-
-`locks.json` is one shared registry, so preserving unrelated keys in memory is not sufficient. Every writer must serialize the complete cross-process read/check/write transaction through the same guard. Otherwise two extensions can read the same snapshot, update different keys, and publish snapshots that erase one another.
-
-The canonical guard path is:
-
-```text
-~/.pi/agent/locks.json.transaction
-```
-
-All participating extensions must follow one compatible protocol:
-
-- Acquire the guard before every ownership acquisition, refresh, release, takeover, or other registry mutation.
-- Publish fully initialized private owner metadata atomically. A portable implementation may stage a non-empty directory containing `owner.<generation>.json`, require filename/payload generation agreement, and rename that directory into the stable guard path.
-- Do not depend on hard links or platform-specific advisory locks; the protocol must work on Linux, macOS, native Windows, and Android/Termux filesystems supported by Pi.
-- Read and validate the latest complete registry only after guard acquisition, change only the owned extension key, and preserve every unrelated key from that guarded snapshot.
-- Publish the JSON payload through a same-directory temporary file and atomic rename. Atomic payload replacement prevents torn JSON but does not replace transaction serialization.
-- Release only the exact acquired owner by atomically renaming the stable guard away before cleanup. Stale recovery must prove the observed owner process is dead and must fence delayed recovery against replacement-owner ABA races.
-- Fail closed on malformed owner metadata, malformed registry state, unverifiable generations, contention timeout, or unsupported atomic filesystem behavior.
-
-Lock-free reads remain appropriate for status display when readers tolerate an old-or-new complete snapshot. Any decision that mutates shared ownership must re-read and validate under the transaction.
-
-Cross-writer safety is compositional: every writer targeting the same registry must participate in the protocol. One compliant writer cannot guarantee lost-update safety against another writer that bypasses the shared transaction.
-
-## Migration
-
-Migrations from legacy lock files or legacy keys should be one-off cleanup work. Runtime ownership should read and write only `locks.json` under the canonical identity key.