@llblab/pi-telegram 0.53.1 → 0.54.0

package/docs/multi-instance-bus.md

@@ -54,12 +54,12 @@ The operator experience:
 - Do not couple the first design to Pi sessions if live instance ownership is the better runtime truth.
 - Do not expose arbitrary group participants to prompts, controls, or artifacts.
 - Do not require Threaded Mode for classic private-chat users; classic private-chat mode remains valid and should not receive slot/thread-name guidance.
-- Do not implement leader election through unsafe lock stealing without heartbeats or stale-owner checks.
+- Do not implement leader election through unsafe lock stealing without stale-owner proof (dead PID, or a bus-proven unresponsive owner).
 
 ## Terms
 
 - `Telegram bus`: The singleton local capability to poll Telegram updates and send Telegram API calls for one bot token.
-- `Leader`: The live Pi instance that currently owns the Telegram bus and calls `getUpdates`; this is an ephemeral role transferable after stale heartbeat detection.
+- `Leader`: The live Pi instance that currently owns the Telegram bus and calls `getUpdates`; this is an ephemeral role transferable after its PID dies or the bus proves it unresponsive.
 - `Follower`: A live Pi instance that wants Telegram presence but routes Telegram API access through the leader.
 - `Bus lifecycle`: Transient recovery state only. Stable identity is the bus role (`leader` / `follower`); lifecycle surfaces exceptional handoff states such as `electing`, not duplicate roles with labels like `leader-active`.
 - `Agent instance`: A running Pi process/session with its own extension state, queue, active turn, model, tools, and lifecycle hooks.
@@ -80,7 +80,7 @@ tmp/pi-telegram/state.json / profiles.<profile>.transport -> polling/control own
 Threaded Mode meaning:
 
 ```text
-tmp/pi-telegram/state.json / profiles.<profile>.transport -> bus leader identity + heartbeat
+tmp/pi-telegram/state.json / profiles.<profile>.transport -> bus leader identity (no periodic 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. Same-session context refresh preserves bus membership; a changed Pi session ID suspends the old receiver/heartbeat and requires acknowledged successor registration before readiness, without an explicit Thread disconnect. A new follower process also attempts a restore-only registration at session startup when the selected profile's local state contains a Workspace binding for the exact `cwd` and session ID. The recent-event log distinguishes missing session bindings, disabled Threaded Mode, leader-side restore refusal, and a restore that returned without connecting; none of these refusals silently provisions a new Thread. 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.
@@ -255,13 +255,13 @@ Routing authority remains the authenticated live owner plus exact numeric Telegr
 
 ## Leader Election
 
-Leader election is heartbeat-gated and lock-backed. The polling owner checks exact lock ownership every second, refreshes its durable lease every two seconds, and becomes stale after eight seconds; the serialized expected-owner transaction remains the final cross-platform election authority.
+Leader election is liveness-proof-gated and lock-backed. Since 0.54 the leader writes no periodic heartbeat: the transport section changes only on acquire, release, takeover or entry migration, and the owner's one- and two-second ownership checks are lock-free reads. A dead PID is stale immediately. A live PID is replaceable only with bus proof: an authenticated side-effect-free `bus.probe` to the leader endpoint that either stays unanswered for the eight-second window, or finds a refusing endpoint twice one window apart (a just-started leader binds well within it). Any reply, including an older leader rejecting the unknown kind, proves it alive; a missing endpoint proves nothing, because a live classic-mode leader has none. Classic mode therefore never takes over a live PID automatically: `/telegram-connect` asks the operator. Entries written by older releases still carry `heartbeatMs` and keep the eight-second stale rule. The serialized expected-owner transaction, binding the proof to the exact owner epoch, remains the final cross-platform election authority.
 
 1. On startup, read the Telegram lock.
 2. If no leader exists, acquire leadership and start polling.
 3. If a live leader exists, restore a remembered profile-scoped exact-`cwd` follower binding automatically; otherwise wait for explicit `/telegram-connect` rather than provisioning a new Thread from startup alone.
-4. If the leader heartbeat is stale, attempt an atomic leadership takeover; ordinary `/telegram-connect` on a follower is not a leadership move while the leader is live.
-5. Heartbeat acknowledgements carry the authenticated live follower-slot roster. If several followers detect stale leadership, the lowest observed live slot attempts promotion immediately; higher slots defer one bounded election grace and re-check the lock. Atomic compare/write acquisition remains the final ownership authority, and a missing lower-slot follower cannot block a higher survivor beyond that grace.
+4. If the leader PID is dead, or its re-registration fails and the bus proves it unresponsive, attempt an atomic leadership takeover; ordinary `/telegram-connect` on a follower is not a leadership move while the leader is live.
+5. Heartbeat acknowledgements carry the authenticated live follower-slot roster. If several followers detect stale or unresponsive leadership, the lowest observed live slot attempts promotion immediately; higher slots defer one bounded election grace and re-check the lock. Atomic compare/write acquisition remains the final ownership authority, and a missing lower-slot follower cannot block a higher survivor beyond that grace.
 
 Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding. Follower Bot API calls already admitted by the active Pi turn wait for that bounded re-registration and capture its new exact generation before entering transport; they do not fail merely because recovery temporarily cleared local registration, and they never replay after an ambiguous transport commit. After the grace window followers promote only when the exact observed leader lease has become stale or inactive; an unavailable IPC endpoint never authorizes replacing a still-live owner. If the exact carried target is absent from persisted bindings, the leader first runs the same synchronous visibility probe: success recovers it instead of creating another Telegram thread, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. An ambiguous absent-target probe persists only non-routable `probe-required` restoration evidence, so targetless retries, successor follower processes with the same exact Workspace claim, and leader reloads probe that exact target again instead of activating it or provisioning a speculative replacement. A carried slot survives only when that slot remains free. Every successful reuse refreshes the binding timestamp. The leader never restores persisted followers into the live registry speculatively. Absent follower records remain durable restart hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; only fresh authenticated registration creates live routing authority. This preserves real thread bindings through reload and process-absence gaps without allowing historical records or competing pollers to masquerade as live state.
 
@@ -269,7 +269,7 @@ Followers first try to re-register after leader reload or unknown-heartbeat resp
 
 ### Protocol identity and compatibility
 
-The session-native local wire contract has protocol version `2`, independent from the npm package version. Follower registration and the leader acknowledgement carry `{ protocolVersion, runtimeBuild, capabilities }`. Capability names are canonical, unique, and sorted. A leader rejects missing or mismatched protocol identity before provisioning a target or publishing the follower into live routing; a strict follower likewise rejects an acknowledgement without compatible leader identity. Different package builds remain compatible when their protocol versions agree. `durable-follower-admission-v1` gates source forwarding, while `queue-handoff-v1` independently gates live semantic queue transfer; every participant in a routed handoff must advertise it. `workspace-follower-auto-connect-v1` gates restore-only startup admission. Session identity is part of protocol v2 rather than an optional capability. Every cwd-scoped v2 registration carries the exact bounded session ID; missing identity is rejected before provisioning or publication. Reconnect, replacement, and promotion preserve it. Protocol-v1 peers are rejected by the base version check, avoiding mixed semantic branches. `thread-display-mode-v1` gates exact-generation follower display-setting requests and Letters/Directories require compatible connected followers; returning to Names allows legacy peers. Registration checks the current display-mode requirement before provisioning and again before live publication. The leader serializes config persistence and title application. `workspace-thread-rename-v1` independently gates follower rename requests whose exact registration generation is checked before the leader mutates Telegram and persists the Workspace binding. `session-replacement-intent-v1` gates Telegram `/new` from a follower Thread: followers never write `state.json`, so `follower.publishSessionReplacement` asks the leader to CAS-publish the durable intent only when the live registration generation, leader epoch, Profile, exact `cwd`, source session, Thread target, and the leader's own Workspace binding slot/name all match, with a bounded unexpired TTL. The intent records the source runtime instance; only a successor registration from that instance or its authenticated same-process handoff (`previousInstanceId`) may re-key the binding, and `follower.settleSessionReplacement` claims it once only after the leader's store shows that successor session bound to the same target. A missing capability, stale generation, or mismatch fails the command closed.
+The session-native local wire contract has protocol version `3`, independent from the npm package version. Version 3 moved journal source serialization from the `telegram.json` transaction to the journal-owned `runtime/journals.transaction`; because v2 peers would not exclude v3 journal writers, the base version check rejects them instead of mixing lock semantics. Follower registration and the leader acknowledgement carry `{ protocolVersion, runtimeBuild, capabilities }`. Capability names are canonical, unique, and sorted. A leader rejects missing or mismatched protocol identity before provisioning a target or publishing the follower into live routing; a strict follower likewise rejects an acknowledgement without compatible leader identity. Different package builds remain compatible when their protocol versions agree. `durable-follower-admission-v1` gates source forwarding, while `queue-handoff-v1` independently gates live semantic queue transfer; every participant in a routed handoff must advertise it. `workspace-follower-auto-connect-v1` gates restore-only startup admission. Session identity has been part of the base protocol since v2 rather than an optional capability. Every cwd-scoped registration carries the exact bounded session ID; missing identity is rejected before provisioning or publication. Reconnect, replacement, and promotion preserve it. Older-protocol peers are rejected by the base version check, avoiding mixed semantic branches. `thread-display-mode-v1` gates exact-generation follower display-setting requests and Letters/Directories require compatible connected followers; returning to Names allows legacy peers. Registration checks the current display-mode requirement before provisioning and again before live publication. The leader serializes config persistence and title application. `workspace-thread-rename-v1` independently gates follower rename requests whose exact registration generation is checked before the leader mutates Telegram and persists the Workspace binding. `session-replacement-intent-v1` gates Telegram `/new` from a follower Thread: followers never write `state.json`, so `follower.publishSessionReplacement` asks the leader to CAS-publish the durable intent only when the live registration generation, leader epoch, Profile, exact `cwd`, source session, Thread target, and the leader's own Workspace binding slot/name all match, with a bounded unexpired TTL. The intent records the source runtime instance; only a successor registration from that instance or its authenticated same-process handoff (`previousInstanceId`) may re-key the binding, and `follower.settleSessionReplacement` claims it once only after the leader's store shows that successor session bound to the same target. A missing capability, stale generation, or mismatch fails the command closed.
 
 The current root advertises `workspace-restore-v1`; all participating peers and potential leader successors must be upgraded before operator-controlled use. The retired `leader.replaceFollowerTarget` envelope is no longer parsed or produced, even with current authentication and registration generation. Its `leader.workspaceRestore` envelope carries only an operation ID, exact recipient registration generation and `apply`/`inspect` mode; the receiver derives binding and destination from the retained intent, not caller-supplied target data. Authentication and an explicitly enabled receiver are mandatory. The controller checks both peers' capability and protocol compatibility, captures live registration/session/slot/endpoint authority, sends once without transport retry, then validates the request, operation, recipient, observed target, slot and boolean readiness against the current registration. A lost response leaves the durable issuance consumed; a separate read-only inspection can prove readiness without applying again. Neither the controller nor receiver settles source input or writes follower-owned canonical state. A successor registration/process may inspect only its actual same-session canonical binding and local target; readiness records the new observer separately without changing the original issuance. An old local target cannot be repaired through inspection, and successor apply is rejected. Interrupted startup, terminal source/cleanup settlement and live behavior were accepted in the operator's 0.52.0 live smoke.
 
@@ -287,7 +287,7 @@ As part of staging, the exact recipient presents the token and atomically receiv
 
 ### Live-Rebind Channel
 
-The 0.53.0 channel preserves protocol v2 and negotiates live rebinding independently from package version. Release 0.53.0 advertises the following capabilities; an instance still running an older build does not acquire them until it is reloaded. Compatible package versions alone cannot supply missing capabilities:
+The 0.53.0 channel preserved protocol v2 and negotiates live rebinding independently from package version; 0.54 moves the base protocol to v3 without changing these capabilities. Release 0.53.0 advertises the following capabilities; an instance still running an older build does not acquire them until it is reloaded. Compatible package versions alone cannot supply missing capabilities:
 
 - `live-thread-rebind-save-v1`, `live-thread-rebind-apply-v1`, `live-thread-rebind-settle-v1`: Exact recipient save/apply/release and source settlement through the shared channel.
 - `live-thread-rebind-command-set-v1`: One `selectedCommand: { name, target }` descriptor and `observe-command` / `command-observed` completion observation, rather than separate status/control wire forms. Retired descriptors and capability names refuse without a compatibility shim.
@@ -513,7 +513,7 @@ Rules:
 
 Current state under the agent dir:
 
-- `tmp/pi-telegram/state.json` `profiles.<profile>.transport`: authoritative transport owner for `default` or a named profile, holding the bus leader identity, capability secret, heartbeat, generation, cleanup fencing epoch and polling-journal pointer. Mutations serialize through `runtime/state.json.transaction`; followers never write it. The local bus endpoint is derived from the agent directory; a `busSocketPath` field is tolerated but not required.
+- `tmp/pi-telegram/state.json` `profiles.<profile>.transport`: authoritative transport owner for `default` or a named profile, holding the bus leader identity, capability secret, generation, cleanup fencing epoch and polling-journal pointer. Mutations serialize through `runtime/state.json.transaction`; followers never write it. The local bus endpoint is derived from the agent directory; a `busSocketPath` field is tolerated but not required.
 - `profiles.<profile>.workspace`: canonical Workspace/thread state; `profiles.<profile>.runtime`: volatile observable/debug projection, never routing authority, with `source: "snapshot"` and `writtenAtMs`. Every process on one profile reads this shared file, but only the active transport owner may publish either section; followers become writers only after promotion. Runtime publication never touches the canonical section, so a stale status writer cannot erase leader records. The `runtime` section mirrors `/telegram-status`-style projections: `runtime` identifies leader/follower role, lifecycle activity, and the exact polling phase/progress snapshot; `liveRoster` mirrors followers/current targets/reservations; `diagnostics` mirrors status/debug signals. The `workspace` section keeps top-level `bot` capability state such as `threadMode: "unknown" | "enabled" | "disabled"`; `threads` stores current routeable bindings; `workspaceBindings` stores dormant exact-`cwd` target/name/slot reuse hints; `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/pi-telegram/runtime/bus.<hash>.sock` (leader) and `runtime/f.<hash>.sock` (follower) symlinks backed by colocated private generation sockets, with bounded private external shortening only for over-long paths; native Windows uses deterministic named pipes under `\\.\pipe\pi-telegram-...`. These are transient IPC endpoints, not durable routing state.
 
@@ -528,13 +528,13 @@ All files containing routing, chat ids, thread ids, or process details use priva
 ### Leader exits cleanly
 
 - Leader stops polling and marks itself offline.
-- Followers detect missing heartbeat.
+- Follower heartbeats go unanswered and the released or dead owner is stale.
 - One follower promotes itself after jitter/tie-break.
 - New leader resumes `getUpdates` from the persisted offset if safe.
 
 ### Leader crashes
 
-- Followers detect stale heartbeat.
+- Followers see a dead PID, or prove a hung leader unresponsive over the bus.
 - One follower promotes itself.
 - Some updates may be delayed or skipped depending on offset persistence; dispatcher design must define this explicitly.
 
@@ -606,7 +606,7 @@ Leader command Restore now binds `updates.bindTelegramUpdateCompletionAcceptance
 
 A source-journal completion hint now also selects a ready leader Restore with retained completed or queued acceptance and unissued cleanup. Fresh admission and strict scoped ACK queries precede executor adoption. A read-only canonical observation requires one exact active binding/session/CWD/slot/target and one current leader owner with matching instance, CWD and profile key; local target equality alone cannot re-key the operation. The existing inspect-only controller preserves the original recipient/grants and observes the same-session current leader without applying identity, invoking a handler or sending follower RPC. After its await, immutable proofs are read again before settling only their proven originals. Live fences remain in storage authority callbacks; canonical observations stay outside the snapshot transaction and are repeated through cleanup awaits and before retirement. An owner change after close retains issued cleanup rather than deleting or retiring. Exact already-retained local readiness needs no republication. Native cold cases cover same-instance/successor continuation, partial/missing/foreign evidence, wrong local session/CWD/target/owner, post-await proof/recipient changes, both canonical publication rename boundaries and unknown/issued cleanup, preserving source bytes throughout. Queued ACK continuation uses the same pre-adoption proof and canonical-owner fences. After recipient inspection it rereads unproven scopes and publishes `queue-completed`, grouping only matching receipts/kinds; admission-only, missing or partial proof cannot release another original. Native single-/multi-receipt cases preserve issued grants and source bytes across canonical publication faults, with or without a prior admission fact. Producer execution, successor startup/ownership and accepted-work clearance are distinct preconditions; these fixtures do not prove actual interrupted Pi startup. Scoped ACKs still never expire, evict or release.
 
-The worker now has a prepared optional `beforeQueueReceiptPublished(receipt, owner, ctx, isCurrent)` barrier. Exact durable queue admission retains the original, but neither cached readiness nor its downstream observer publishes until the asynchronous acceptance publisher succeeds. Publication requires a captured exact receipt-inspection capability before and after the await, with current process/session/context/binding checks. Receipt and owner arguments are detached; grouped reports and concurrent snapshot refresh share one pending publication. Same-process cold receipt reconstruction uses that barrier without running the original handler. Callback failures hold queued work; readiness observers remain diagnostic after successful publication. Ordinary commit failures still release deferred claims synchronously. `waitForDrain` covers in-flight publication. Serialized production journal bindings now compose `inspectQueuedReceipt(expected)` with their existing strict private sibling and derive `isQueueReceiptCurrent` from the exact active recovery key. The read-only v1 observer requires every canonical ordered source ID, receipt/kind, full owner/acquisition and absence of a handoff offer. It returns detached source digests of the retained **queued** originals plus normalized-owner SHA-256; those digests are not pre-queue pending hashes or removal ACKs. Query mismatch yields no proof; malformed, corrupt, foreign or unprepared evidence throws without repair, rebinding or source mutation. Inspection uses lock-only source/config serialization, not writer admission, so observing exact accepted work does not borrow persistence permission. Native fixtures cover whole groups, owner/acquisition mismatch, offers, retained byte continuity, cold/detached proof, post-await completion/corruption and read-only authority. The production worker now wires routing's `beforeQueueReceiptPublished` publisher. It selects only retained operations overlapping that exact active-journal receipt, then reacquires fresh profile Workspace admission; ordinary receipts remain a no-op for Restore policy. A selected operation must be ready with its issued routing, exact current executor/operator and leader recipient. Canonical read-only binding/owner checks and live session/CWD/slot/target establish recipient authority before each `queued` acceptance. Exact receipt/source and owner-hash evidence is retained in the existing operation before readiness. Storage's authority predicate checks only live fences to avoid reacquiring its held snapshot transaction; canonical CAS plus pre/post snapshot reads preserve binding protection. Lost publication reply reconciles only an identical retained request/executor/operator/proof. After publication the publisher re-reads the whole receipt, and after admission returns it rechecks captured recipient guards; changed proof or authority suppresses readiness without rolling back accepted local queue work. No apply, prompt enqueue, deletion or cleanup is repeated by this publisher. Same-process worker reconstruction can republish only acceptance from its still-exact receipt; it is not actual interrupted Pi startup or a foreign-session successor grant.
+The worker now has a prepared optional `beforeQueueReceiptPublished(receipt, owner, ctx, isCurrent)` barrier. Exact durable queue admission retains the original, but neither cached readiness nor its downstream observer publishes until the asynchronous acceptance publisher succeeds. Publication requires a captured exact receipt-inspection capability before and after the await, with current process/session/context/binding checks. Receipt and owner arguments are detached; grouped reports and concurrent snapshot refresh share one pending publication. Same-process cold receipt reconstruction uses that barrier without running the original handler. Callback failures hold queued work; readiness observers remain diagnostic after successful publication. Ordinary commit failures still release deferred claims synchronously. `waitForDrain` covers in-flight publication. Serialized production journal bindings now compose `inspectQueuedReceipt(expected)` with their existing strict private sibling and derive `isQueueReceiptCurrent` from the exact active recovery key. The read-only v1 observer requires every canonical ordered source ID, receipt/kind, full owner/acquisition and absence of a handoff offer. It returns detached source digests of the retained **queued** originals plus normalized-owner SHA-256; those digests are not pre-queue pending hashes or removal ACKs. Query mismatch yields no proof; malformed, corrupt, foreign or unprepared evidence throws without repair, rebinding or source mutation. Inspection uses lock-only journal source serialization, not writer admission, so observing exact accepted work does not borrow persistence permission. Native fixtures cover whole groups, owner/acquisition mismatch, offers, retained byte continuity, cold/detached proof, post-await completion/corruption and read-only authority. The production worker now wires routing's `beforeQueueReceiptPublished` publisher. It selects only retained operations overlapping that exact active-journal receipt, then reacquires fresh profile Workspace admission; ordinary receipts remain a no-op for Restore policy. A selected operation must be ready with its issued routing, exact current executor/operator and leader recipient. Canonical read-only binding/owner checks and live session/CWD/slot/target establish recipient authority before each `queued` acceptance. Exact receipt/source and owner-hash evidence is retained in the existing operation before readiness. Storage's authority predicate checks only live fences to avoid reacquiring its held snapshot transaction; canonical CAS plus pre/post snapshot reads preserve binding protection. Lost publication reply reconciles only an identical retained request/executor/operator/proof. After publication the publisher re-reads the whole receipt, and after admission returns it rechecks captured recipient guards; changed proof or authority suppresses readiness without rolling back accepted local queue work. No apply, prompt enqueue, deletion or cleanup is repeated by this publisher. Same-process worker reconstruction can republish only acceptance from its still-exact receipt; it is not actual interrupted Pi startup or a foreign-session successor grant.
 
 Native full-capacity leader Restore cases exercise positive queued publication, both rename sides, a forged returned intent with no proof, missing/unreadable receipt or a changed source digest on proof reread, authority loss, recipient change before publication/after the proof reread/after admission, and same-process worker reconstruction. Each original stays queued under its durable owner, exactly one prompt is accepted, and uncertain acceptance never publishes readiness or triggers cleanup. A native two-original media-group producer now exercises the same contract through its real unbound-group debounce, shared chooser/Restore selection, journal and worker. At full A–Z capacity, it relocates the same binding/slot and enqueues one combined prompt with one full receipt. A failed or unproven second acceptance retains the first proof but holds the entire receipt; lost post-rename reply reconciles both. A changed second digest on reread or an actual native whole-group handoff offer withholds readiness without undoing accepted work. Same-process worker reconstruction completes partial proof, preserves the first acceptance byte-for-byte, and emits one readiness observation without journal mutation or another enqueue/apply. Duplicate acceptance publication leaves canonical bytes unchanged. These are grouped prompt fixtures, not all remaining control/local outcomes or actual Pi startup acceptance.
 
@@ -643,7 +643,7 @@ This inspection authorizes no reload/restart, live-state mutation, fault injecti
 ### Split brain
 
 - Two leaders calling `getUpdates` is the main safety failure.
-- Lock heartbeat/takeover must be atomic enough to prevent this under normal local concurrency.
+- Lock takeover must be atomic enough to prevent this under normal local concurrency.
 - Persistent competing `getUpdates` clients trigger a full transport stand-down even when the local lock still appears owned; the stopped runtime preserves accepted local work and releases only its exact ownership. See [Runtime Ownership](./architecture.md#runtime-ownership) for the threshold, diagnostic, and reconnect contract.
 
 ## Security Boundaries
@@ -657,7 +657,7 @@ This inspection authorizes no reload/restart, live-state mutation, fault injecti
 
 ## Acceptance Criteria
 
-- [x] The lock semantics are redesigned as Telegram bus leadership with heartbeat and stale takeover rules.
+- [x] The lock semantics are redesigned as Telegram bus leadership with liveness proof and stale takeover rules.
 - [x] A first-class `TelegramTarget` can represent classic private chats and thread destinations.
 - [x] The bridge can run in classic mode with unchanged private-chat behavior.
 - [x] A live Pi instance can register as a follower when another live instance is leader.
@@ -676,7 +676,7 @@ Open live client and native Windows evidence gates for future behavior belong in
 - Bus semantics are the feature frame: Telegram threads are one Telegram UI substrate for a local multi-instance bus.
 - `TelegramTarget` and target-key helpers represent classic private chats and thread destinations.
 - Outbound ports, previews, replies, voice, attachments, chat actions, menus, sections, buttons, queue mutations, and direct local delivery carry target metadata where needed.
-- The transport lock distinguishes live bus leadership from ordinary classic ownership through heartbeat, leader epoch, and stale takeover rules.
+- The transport lock distinguishes live bus leadership from ordinary classic ownership through leader epoch, liveness proof, and stale takeover rules.
 - The leader records live follower registration, heartbeat, thread identity, slot, and target mapping; followers do not poll `getUpdates`.
 - Local IPC is the default internal bus. Registered followers receive normalized inbound updates and send allowlisted, target-scoped Bot API calls through the leader.
 - Thread targets are current-state bindings, not historical delivery addresses. Stable restart hints require a fresh authenticated follower registration before they become live routing authority; stale/offline/failed entries remain reconciliation evidence only.

package/lib/bus-follower.ts

@@ -385,6 +385,8 @@ export function createTelegramManualFollowerProfileKeyResolver(input: {
 
 export interface TelegramBusFollowerElection {
   expectedOwner?: TelegramLockEntry;
+  /** The expected owner is bus-proven unresponsive; the lock CAS still requires it to be the current owner. */
+  unresponsive?: boolean;
 }
 
 export type TelegramBusFollowerPromotionHandler<TContext> = (
@@ -568,6 +570,8 @@ export interface TelegramBusFollowerHeartbeatRecoveryHandlerDeps<TContext> {
   scheduleRetry?: (retry: () => void, delayMs: number) => void;
   getActiveContext?: () => TContext | undefined;
   promotionGraceMs?: number;
+  /** Bus liveness proof for a live-PID leader that no longer answers; replaces the retired file heartbeat. */
+  proveLeaderUnresponsive?: (owner: TelegramLockEntry) => Promise<boolean>;
   recordRuntimeEvent: (
     category: string,
     error: unknown,
@@ -2410,6 +2414,13 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler<TContext>(
           ) {
             return;
           }
+          if (await deps.proveLeaderUnresponsive?.(graceState.lock)) {
+            await promoteToLeader(error, ctx, initialBinding, {
+              expectedOwner: graceState.lock,
+              unresponsive: true,
+            });
+            return;
+          }
           deps.setLifecyclePhase(undefined);
           safeUpdateStatus(ctx);
           deps.recordRuntimeEvent(

package/lib/bus-leader.ts

@@ -3371,6 +3371,14 @@ export function createTelegramBusLeaderEnvelopeHandler(
       return createUnauthorizedBusAck(envelope.requestId);
     }
     switch (envelope.kind) {
+      case "bus.probe":
+        // Liveness only: no registry, routing, journal or Bot API effect.
+        return {
+          kind: "bus.ack" as const,
+          requestId: envelope.requestId,
+          ok: true,
+          protocol: deps.protocolIdentity,
+        };
       case "follower.register":
       case "follower.restoreWorkspace": {
         const compatibility = getTelegramBusProtocolCompatibility({

package/lib/bus.ts

@@ -45,7 +45,12 @@ import {
   type TelegramBusTransportRetryPolicy,
 } from "./bus-transport.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
-import { TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS } from "./locks.ts";
+import {
+  isSameTelegramLockOwner,
+  TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS,
+  type TelegramLockEntry,
+  type TelegramLockState,
+} from "./locks.ts";
 import { resolveAgentDir } from "./paths.ts";
 import { getTelegramProcessBirthIdentity } from "./process-identity.ts";
 import {
@@ -131,7 +136,8 @@ export function createTelegramBusAuthSecret(): string {
   return randomBytes(32).toString("base64url");
 }
 
-const TELEGRAM_BUS_PROTOCOL_VERSION = 2 as const;
+// v3: journal source serialization left the config transaction; mixed v2/v3 peers would not exclude each other.
+const TELEGRAM_BUS_PROTOCOL_VERSION = 3 as const;
 export const TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION =
   "durable-follower-admission-v1" as const;
 export const TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF =
@@ -1222,6 +1228,11 @@ export type TelegramBusEnvelope = (
       args: unknown[];
       sentAtMs: number;
     }
+  | {
+      /** Side-effect-free leader liveness probe; any acknowledgement proves a responsive event loop. */
+      kind: "bus.probe";
+      requestId: string;
+    }
   | {
       kind: "bus.ack";
       requestId: string;
@@ -1269,7 +1280,8 @@ export function getTelegramBusEnvelopeTrafficClass(
 ): TelegramBusEnvelopeTrafficClass {
   if (
     envelope.kind === "follower.register" ||
-    envelope.kind === "follower.restoreWorkspace"
+    envelope.kind === "follower.restoreWorkspace" ||
+    envelope.kind === "bus.probe"
   )
     return "bootstrap";
   if (envelope.kind === "bus.ack") return "response";
@@ -1579,6 +1591,9 @@ export function parseTelegramBusEnvelope(
     case "follower.callApi":
       envelope = parseCallApiEnvelope(value, requestId);
       break;
+    case "bus.probe":
+      envelope = { kind, requestId };
+      break;
     case "bus.ack":
       envelope = parseAckEnvelope(value, requestId);
       break;
@@ -1590,6 +1605,112 @@ export function parseTelegramBusEnvelope(
   return envelope;
 }
 
+/**
+ * One leader liveness observation. `silent` (connected or connecting, no answer within the window) and
+ * `unreachable` (an endpoint that refuses connections: nobody listens) can support a takeover. A missing endpoint is
+ * `unknown`: a live classic-mode leader has no socket at all. Any bytes or an orderly close prove the peer's event
+ * loop handled the connection, so even an older leader rejecting the unknown kind is `responsive`.
+ */
+export type TelegramBusLeaderProbeResult =
+  | "responsive"
+  | "silent"
+  | "unreachable"
+  | "unknown";
+
+export function probeTelegramBusLeader(input: {
+  socketPath: TelegramBusSocketPathSource;
+  secret?: string;
+  timeoutMs?: number;
+}): Promise<TelegramBusLeaderProbeResult> {
+  const timeoutMs = input.timeoutMs ?? TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS;
+  return new Promise((resolve) => {
+    let settled = false;
+    let socket: Socket | undefined;
+    const finish = (result: TelegramBusLeaderProbeResult) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket?.destroy();
+      resolve(result);
+    };
+    const timer = setTimeout(() => finish("silent"), timeoutMs);
+    let connected = false;
+    try {
+      socket = createConnection(resolveTelegramBusSocketPath(input.socketPath));
+    } catch {
+      finish("unknown");
+      return;
+    }
+    socket.once("connect", () => {
+      connected = true;
+      socket!.write(
+        encodeTelegramBusEnvelope({
+          kind: "bus.probe",
+          requestId: `probe:${randomBytes(8).toString("hex")}`,
+          ...(input.secret ? { auth: input.secret } : {}),
+        }),
+      );
+    });
+    socket.once("data", () => finish("responsive"));
+    socket.once("end", () => finish("responsive"));
+    socket.once("error", (error) => {
+      const code = (error as NodeJS.ErrnoException).code;
+      finish(
+        !connected && code === "ECONNREFUSED" ? "unreachable" : "unknown",
+      );
+    });
+  });
+}
+
+/**
+ * Takeover evidence replacing the retired file heartbeat: a full silent window, or an unreachable endpoint
+ * confirmed again after one more window (a just-started leader binds its socket well within it). The owner must
+ * stay the same throughout; the lock acquisition then CAS-checks that exact owner.
+ */
+export async function proveTelegramBusLeaderUnresponsive(input: {
+  probe: () => Promise<TelegramBusLeaderProbeResult>;
+  isSameOwner: () => boolean;
+  sleep: (ms: number) => Promise<void>;
+  windowMs?: number;
+}): Promise<boolean> {
+  const first = await input.probe();
+  if (first === "silent") return input.isSameOwner();
+  if (first !== "unreachable") return false;
+  await input.sleep(input.windowMs ?? TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS);
+  if (!input.isSameOwner()) return false;
+  const second = await input.probe();
+  return (second === "silent" || second === "unreachable") && input.isSameOwner();
+}
+
+/** Composition-ready takeover proof for one profile's leader lock and endpoint. */
+export function createTelegramBusLeaderUnresponsivenessProof(deps: {
+  getLeaderState: () => TelegramLockState;
+  getLeaderSocketPath: () => string;
+  probe?: typeof probeTelegramBusLeader;
+  sleep?: (ms: number) => Promise<void>;
+}): (owner: TelegramLockEntry) => Promise<boolean> {
+  const probe = deps.probe ?? probeTelegramBusLeader;
+  const sleep =
+    deps.sleep ??
+    ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  return (owner) =>
+    proveTelegramBusLeaderUnresponsive({
+      probe: () =>
+        probe({
+          socketPath: owner.busSocketPath ?? deps.getLeaderSocketPath(),
+          secret: owner.busSecret,
+        }),
+      isSameOwner: () => {
+        const state = deps.getLeaderState();
+        return (
+          state.kind === "active-elsewhere" &&
+          isSameTelegramLockOwner(state.lock, owner)
+        );
+      },
+      sleep,
+    });
+}
+
 interface TelegramBusLocalServer {
   start: () => Promise<void>;
   stop: () => Promise<void>;

package/lib/config.ts

@@ -289,12 +289,6 @@ export interface TelegramConfigStore {
     assertExecutionCurrent?: () => void,
     commitIfOwned?: (commit: () => void) => boolean,
   ) => Promise<boolean>;
-  /** Lock-only serialization for trusted synchronous source operations, not authorization.
-   * Does not read/adopt config. Acquire required Workspace admission first; never
-   * acquire owners or nest config admission here. Do not pass async callbacks:
-   * returned promises are not protected after their synchronous prefix.
-   */
-  withSourceSerialization: <T>(operation: () => T) => T;
   /** Trusted synchronous publication only; caller acquires Workspace admission before this config transaction. */
   withPairingAdmission: <T>(
     profileName: string,
@@ -779,8 +773,6 @@ export function createTelegramConfigStore(
       nextConfig.allowedUserId = userId;
       setEffectiveConfig(nextConfig);
     },
-    withSourceSerialization: (operation) =>
-      withTelegramFileTransaction(`${configPath}.transaction`, operation),
     withPairingAdmission: (profileName, tokenSha256, publish) =>
       withPersistedPairingProfile(
         profileName,

package/lib/extension.ts

@@ -181,13 +181,15 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       getProfileName: configStore.getActiveProfileName,
     });
+  const withTelegramJournalSourceSerialization =
+    Journal.createTelegramJournalSourceSerialization();
   const telegramJournalBindingRuntime =
     Journal.createTelegramUpdateJournalBindingRuntime({
       base: {
         getProfileName: configStore.getActiveProfileName,
         getBotToken: configStore.getBotToken,
         getBotId: getTelegramBotId,
-        withSourceSerialization: configStore.withSourceSerialization,
+        withSourceSerialization: withTelegramJournalSourceSerialization,
         onRecovery(event) {
           recordRuntimeEvent(
             "recovery",
@@ -259,6 +261,11 @@ export default function (pi: Pi.ExtensionAPI) {
       return telegramLeaderJournalPath.createJournalPath();
     },
   });
+  const proveTelegramLeaderUnresponsive =
+    Bus.createTelegramBusLeaderUnresponsivenessProof({
+      getLeaderState: lockRuntime.getState,
+      getLeaderSocketPath: getTelegramBusSocketPath,
+    });
   const telegramSessionContextStore =
     Lifecycle.createTelegramSessionContextStore<Pi.ExtensionContext>({
       getIdentity(ctx) {
@@ -1368,7 +1375,7 @@ export default function (pi: Pi.ExtensionAPI) {
         botToken,
         botId: getTelegramBotId(),
       });
-      return configStore.withSourceSerialization(function () {
+      return withTelegramJournalSourceSerialization(function () {
         return Journal.isTelegramThreadCleanupJournalNamespaceClear({
           directory: Paths.resolveTelegramTempDir(),
           profile,
@@ -1988,6 +1995,7 @@ export default function (pi: Pi.ExtensionAPI) {
       },
       recovery: {
         getLeaderState: lockRuntime.getState,
+        proveLeaderUnresponsive: proveTelegramLeaderUnresponsive,
         setLifecyclePhase: telegramBusFollowerControlState.setLifecyclePhase,
         updateStatus,
         promoteToLeader: promoteTelegramBusFollowerToLeader,
@@ -2347,6 +2355,7 @@ export default function (pi: Pi.ExtensionAPI) {
   const threadAwarePollingPorts = telegramThreadCapabilityRuntime.pollingPorts;
   const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
     lock: lockRuntime,
+    proveOwnerUnresponsive: proveTelegramLeaderUnresponsive,
     resetDamagedState() {
       return Locks.resetDamagedTelegramRuntimeState(
         Paths.resolveTelegramStatePath(),

package/lib/journal.ts

@@ -46,6 +46,7 @@ import {
 import {
   decodeTelegramSessionDirectoryName,
   getTelegramProfilePathSuffix,
+  resolveTelegramRuntimeDir,
   TELEGRAM_DEFAULT_PROFILE_NAME,
 } from "./paths.ts";
 import {
@@ -4889,6 +4890,21 @@ export function createTelegramUpdateJournalBindingRuntime(deps: {
   return runtime;
 }
 
+/**
+ * Journal-owned cross-family source serializer, lock-only and never authorization. Its guard lives
+ * in the runtime service directory, so journal work never touches `telegram.json` or its
+ * transaction. Acquire Workspace admission and any sender (config) admission first; never acquire
+ * owners inside it. Callbacks must be synchronous: a returned promise is unprotected after its
+ * synchronous prefix.
+ */
+export function createTelegramJournalSourceSerialization(
+  getTransactionPath: () => string = () =>
+    join(resolveTelegramRuntimeDir(), "journals.transaction"),
+): <T>(operation: () => T) => T {
+  return (operation) =>
+    withTelegramFileTransaction(getTransactionPath(), operation);
+}
+
 export function createTelegramUpdateJournalStore(
   options: TelegramUpdateJournalStoreOptions,
 ): TelegramUpdateJournalStore {
@@ -5591,36 +5607,40 @@ function createJournalStoreCore(
     }
   };
 
+  const acquireSource = (): JournalSourceAcquisition | undefined =>
+    sourceAccess
+      ? acquireTelegramUpdateJournalFamily(
+          {
+            ...sourceAccess,
+            path,
+            profile,
+            botIdentity: expectedIdentity,
+          },
+          version,
+        )
+      : undefined;
+  const readAcquiredSource = (
+    source: JournalSourceAcquisition,
+  ): ReadTelegramUpdateJournalResult => {
+    const file =
+      source.evidence.kind === "present" ? source.evidence.file : emptyFile();
+    return {
+      file,
+      exists: source.evidence.kind === "present",
+      serializedBytes: assertCapacity(file),
+      source,
+    };
+  };
+
   const runJournalTransaction = <T>(
     operation: (read: typeof readCurrent) => T,
   ): T => {
     try {
       // Acquire before the transaction helper can create parents or staging names.
       // The config continuation excludes participating writers through consumption.
-      const source = sourceAccess
-        ? acquireTelegramUpdateJournalFamily(
-            {
-              ...sourceAccess,
-              path,
-              profile,
-              botIdentity: expectedIdentity,
-            },
-            version,
-          )
-        : undefined;
-      const readSource = (): ReadTelegramUpdateJournalResult => {
-        if (!source) return readCurrent();
-        const file =
-          source.evidence.kind === "present"
-            ? source.evidence.file
-            : emptyFile();
-        return {
-          file,
-          exists: source.evidence.kind === "present",
-          serializedBytes: assertCapacity(file),
-          source,
-        };
-      };
+      const source = acquireSource();
+      const readSource = (): ReadTelegramUpdateJournalResult =>
+        source ? readAcquiredSource(source) : readCurrent();
       return withTelegramFileTransaction(`${path}.transaction`, () =>
         operation(readSource),
       );
@@ -7024,16 +7044,30 @@ function createJournalStoreCore(
       assertCurrent();
       return { issued, entries: result };
     });
+  const projectRead = (current: ReadTelegramUpdateJournalResult) => ({
+    ...cloneFile(current.file),
+    exists: current.exists,
+    serializedBytes: current.serializedBytes,
+  });
   const journal: TelegramUpdateJournalStore = {
     read() {
-      return runMutation((readCurrent) => {
-        const current = readCurrent();
-        return {
-          ...cloneFile(current.file),
-          exists: current.exists,
-          serializedBytes: current.serializedBytes,
-        };
-      });
+      // Atomic publication makes a repair-free read safe without serialization, so idle
+      // status and polling cursor reads create no guards. Any read that needs reconciliation,
+      // or races a compaction, falls back to the serialized path that owns repair.
+      const attempt = (): ReadTelegramUpdateJournalResult | undefined => {
+        try {
+          const source = acquireSource();
+          return source ? readAcquiredSource(source) : readCurrentStrict(false);
+        } catch {
+          return undefined;
+        }
+      };
+      const current = options.withWriterAdmission
+        ? options.withWriterAdmission(attempt)
+        : attempt();
+      return current
+        ? projectRead(current)
+        : runMutation((readCurrent) => projectRead(readCurrent()));
     },
     appendBatch(updates, requestedAcceptedThroughUpdateId) {
       const canonicalUpdates = updates.map((update) =>
@@ -7199,10 +7233,17 @@ function createJournalStoreCore(
             serializedBytes: published.serializedBytes,
           };
         });
+      // Sender admission is the outer config authority; journal serialization nests inside it.
+      const serializedAppend = (preApprovalExcluded?: boolean) =>
+        withSourceSerialization
+          ? withSourceSerialization(() =>
+              appendWithEvidence(preApprovalExcluded),
+            )
+          : appendWithEvidence(preApprovalExcluded);
       const append = () => {
         if (withPairedAdmission) {
           const result = withPairedAdmission(normalizedUpdates, () =>
-            appendWithEvidence(),
+            serializedAppend(),
           );
           if (!result.admitted)
             throw createJournalError(
@@ -7213,10 +7254,8 @@ function createJournalStoreCore(
           return result.value;
         }
         if (withPairingAdmission)
-          return withPairingAdmission(appendWithEvidence);
-        return withSourceSerialization
-          ? withSourceSerialization(() => appendWithEvidence())
-          : appendWithEvidence();
+          return withPairingAdmission(serializedAppend);
+        return serializedAppend();
       };
       const admittedAppend = () => {
         if (!workspaceAdmission) return append();