@llblab/pi-telegram 0.53.1 → 0.54.0

package/AGENTS.md

@@ -76,7 +76,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - Runtime files live under `<agent-dir>/tmp/pi-telegram` (releases before 0.52.0 used `tmp/telegram`, which a new release never writes, migrates or deletes). The older `owners.json` is read-only evidence: a live fresh owner there blocks acquisition so two release generations never poll one bot, and only its identity is exposed, never its bus endpoint or secret. Only `state.json` and `logs.jsonl` are persistent root files: the per-profile `transport` section of `state.json` is the sole transport-owner authority, `workspace` owns canonical Workspace/Restore evidence and `admission` its leases; the `runtime` section and `logs.jsonl` never grant routing authority. Each section changes only through the shared transaction under its own domain authority (nonleader admission remains process/birth-owned, not transport-owned); Workspace/runtime publication captures exact session authority, and acquisition, refresh, release, takeover, and irreversible leader work fence the exact owner/epoch. Ordinary reads and section mutations still refuse a damaged shared envelope without repair. Only a non-election leader start (`/telegram-connect` or session auto-start) runs the operator-approved optimistic reset: under the shared transaction guard it replaces damaged envelope/transport/Workspace/admission evidence with an empty envelope, accepting loss of every profile's runtime continuity; filesystem access errors still refuse (see [Damaged-State Reset](./docs/architecture.md#damaged-state-reset-operator-approved)). Use the [session journal contract](./docs/multi-instance-bus.md#session-owned-journal-storage) for owners-named polling continuity and the explicitly approved optimistic session-family sweep; that sweep is not Thread deletion or receipt settlement.
 - Threaded Mode has exactly one live leader per bot profile. Followers are real operator-started Pi processes and must authenticate/register over local IPC; Telegram never spawns hidden Pi processes. A live but unreachable owner does not authorize split-brain polling.
 - Local IPC is a trust boundary, not merely a private socket. Unknown, stale, mismatched-generation, or unauthorized requests must not inject prompts, callbacks, API sends, artifacts, liveness, or bindings. Follower registration identity may prepare a binding, but inbound generation authority is published only after successful preparation for the same generation and current context; pending or failed startup cannot append into a retained old journal. Readiness also binds the active Pi context and supplied session generation. Same-session refresh awaits binding preparation without re-registering; a changed session ID cannot publish readiness until its exact leader registration is acknowledged. Reusing a context object cannot carry readiness across a session-generation or ID change. Registration requests capture session authority before asynchronous startup and fence every publication/finalization against the current attempt. Stop or supersession invalidates that attempt; obsolete cleanup cannot erase a newer registration or a refreshed context.
-- Protocol compatibility is independent from package version. Registration negotiates protocol version, runtime build, and canonical capabilities before target provisioning or live publication. `durable-follower-admission-v1` gates source forwarding; `queue-handoff-v1` independently gates semantic queue transfer for every participant and is advertised only with exact source/recipient journal-binding composition. `follower.register` and capability-gated restore-only `follower.restoreWorkspace` are bootstrap requests; other requests require exact live-registry generation authority, and `bus.ack` is response-only. `thread-display-mode-v1` gates follower display-setting requests; the leader owns their serialized profile preference and title application.
+- Protocol compatibility is independent from package version. Registration negotiates protocol version, runtime build, and canonical capabilities before target provisioning or live publication. `durable-follower-admission-v1` gates source forwarding; `queue-handoff-v1` independently gates semantic queue transfer for every participant and is advertised only with exact source/recipient journal-binding composition. `follower.register`, capability-gated restore-only `follower.restoreWorkspace` and side-effect-free liveness `bus.probe` are bootstrap requests; other requests require exact live-registry generation authority, and `bus.ack` is response-only. `thread-display-mode-v1` gates follower display-setting requests; the leader owns their serialized profile preference and title application.
 - Long-lived timers, pollers, watchers, receivers, heartbeats, background delivery, and deferred dispatch are session-bound. Shutdown cancels/drains diagnostics publications and fences deferred status reads before they can acquire guards or repair files. Replacement stops stale activity and makes late work inert; teardown must recheck the captured session generation even when context identity is reused. Same-process handoff may preserve exact profile/target identity but never stale Pi context or cross-profile authority. Follower heartbeat and leader-to-follower Restore/live-rebind control reply deadlines align with the eight-second leader stale-liveness window rather than the generic one-second local-RPC default; an ordinary multi-second Pi/TUI event-loop stall or a slower Windows named pipe is not registration or recipient loss. Participating source observations must hold a reference for the actual read, including pending-mutation/count queries against a stopped worker's retained source; a scoped observation never restores receipt readiness or execution authority. A donor cancellation resumed after remote handoff awaits must also hold a source reference; only the existing exact journal CAS may cancel, never undo accepted recipient custody. Stable source keys do not certify captured callable lifetimes: snapshot prepared worker capabilities at construction and replace them on source-handle renewal without replaying unsettled input. Aborting a durable update generation does not release that `update_id`: replacement replay waits for its actual handler settlement, and effectful handlers use the shared execution fence immediately before commit and after awaited delegation. Admission also rechecks that fence after the default handler returns, before its outcome can settle custody; a stopped handler's ordinary return is not completion authority. Internal clones explicitly carry the hidden fence; reroute forwarding, thread-store mutation, cleanup, and Bot API boundaries retain the originating generation.
 - Runtime state is event-driven reconciliation of local assumptions against Telegram signals, not a complete bot read-model and not permission to query Telegram on every action. Destructive thread cleanup goes through `thread-reconciler` with current proof and leader fencing. Fresh Workspace Thread creation derives its initial Bot API title from the active display mode before issuance; the stable generated `threadName` remains separate from the acknowledged `displayTitle`.
 

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 ## Unreleased
 
+## 0.54.0: No periodic disk writes while idle
+
+- `Journal serialization`: The update journal no longer borrows the `telegram.json` lock. Journal operations serialize on their own `tmp/pi-telegram/runtime/journals.transaction`, so receiving messages and repairing journals never touch the config file or its guard; only config writes and sender admission still take it. Bus protocol moves to v3 so 0.53.x peers, which serialize on the old lock, cannot register alongside 0.54 writers.
+- `Idle status writes`: The persisted runtime status no longer stores poll-cycle timestamps, so an idle connected session stops rewriting `state.json` after every long-poll response.
+- `Leader liveness`: The leader no longer rewrites `state.json` every two seconds. A dead PID is taken over at once; a live but frozen Threaded Mode leader is replaced only after an authenticated `bus.probe` proves it unresponsive, bound to that exact owner. Classic mode never takes over a live PID silently: `/telegram-connect` asks first. An idle connected session now makes no periodic disk writes.
+
+## 0.53.2: Idle runtime without lock churn
+
+- `Idle disk load`: Polling-cursor and status reads of the update journal no longer open config and journal transactions, so a connected idle session stops creating `telegram.json.transaction.staged.*` and `inbox.json.transaction.staged.*` guard folders; only reads that need repair take the serialized path. Unchanged runtime status snapshots are compared before locking and skip their `state.json` transaction.
+
 ## 0.53.1: Text replies without false voice errors
 
 - `Voice artifacts`: A reply plan without voice content no longer reaches outbound voice artifact delivery, so plain text replies stop recording "every voice synthesis provider failed" delivery errors; explicit `telegram_voice` markup and genuine synthesis failures keep their existing fallback behavior (#318).

package/dist/lib/bus-follower.d.ts

@@ -179,6 +179,8 @@ export declare function createTelegramManualFollowerProfileKeyResolver(input: {
 }): () => string;
 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> = (ctx: TContext, binding: TelegramBusFollowerPromotedBinding, election: TelegramBusFollowerElection) => Promise<boolean>;
 type TelegramBusFollowerWorkspaceAdmissionDeps = {
@@ -227,6 +229,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, details?: Record<string, unknown>) => void;
 }
 export interface TelegramBusForwardedUpdateReceiverRuntimeDeps<TContext> {

package/dist/lib/bus-follower.js

@@ -1357,6 +1357,13 @@ export function createTelegramBusFollowerHeartbeatRecoveryHandler(deps) {
                     if (await tryRegisterWithLeader(ctx, graceState.lock, "follower-register-restore-grace", initialBinding)) {
                         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("bus", "Telegram follower promotion blocked by live leader lease", {

package/dist/lib/bus-leader.js

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

package/dist/lib/bus.d.ts

@@ -6,6 +6,7 @@
  */
 import { type TelegramBusEndpointLayout, type TelegramBusTransportEventRecorder, type TelegramBusTransportRetryPolicy } from "./bus-transport.ts";
 import type { TelegramThreadDisplayMode } from "./config.ts";
+import { type TelegramLockEntry, type TelegramLockState } from "./locks.ts";
 import { type TelegramQueueHandoffPayload } from "./queue.ts";
 import { type TelegramTarget } from "./target.ts";
 import { type TelegramSessionReplacementIntent } from "./threads.ts";
@@ -525,6 +526,10 @@ export type TelegramBusEnvelope = ({
     method: string;
     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;
@@ -558,6 +563,36 @@ export declare function createTelegramBusRequestId(input: {
 export declare function createTelegramBusRequestIdFactory(instanceId: string): () => string;
 export declare function encodeTelegramBusEnvelope(envelope: TelegramBusEnvelope): string;
 export declare function parseTelegramBusEnvelope(line: string): TelegramBusEnvelope | undefined;
+/**
+ * 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 declare function probeTelegramBusLeader(input: {
+    socketPath: TelegramBusSocketPathSource;
+    secret?: string;
+    timeoutMs?: number;
+}): Promise<TelegramBusLeaderProbeResult>;
+/**
+ * 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 declare function proveTelegramBusLeaderUnresponsive(input: {
+    probe: () => Promise<TelegramBusLeaderProbeResult>;
+    isSameOwner: () => boolean;
+    sleep: (ms: number) => Promise<void>;
+    windowMs?: number;
+}): Promise<boolean>;
+/** Composition-ready takeover proof for one profile's leader lock and endpoint. */
+export declare function createTelegramBusLeaderUnresponsivenessProof(deps: {
+    getLeaderState: () => TelegramLockState;
+    getLeaderSocketPath: () => string;
+    probe?: typeof probeTelegramBusLeader;
+    sleep?: (ms: number) => Promise<void>;
+}): (owner: TelegramLockEntry) => Promise<boolean>;
 interface TelegramBusLocalServer {
     start: () => Promise<void>;
     stop: () => Promise<void>;

package/dist/lib/bus.js

@@ -12,7 +12,7 @@ import { platform as getPlatform, tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { classifyTelegramBusTransportError, createTelegramBusTransportTimeoutError, delayTelegramBusTransportRetry, getTelegramBusEndpointDiagnostics, getTelegramBusFollowerEndpoint, getTelegramBusLeaderEndpoint, getTelegramBusPipePath, getTelegramBusTransportRetryPolicy, isRetryableTelegramBusTransportError, isTelegramBusPipePath, probeTelegramBusEndpoint, TELEGRAM_BUS_MAX_DIRECT_UNIX_ENDPOINT_BYTES, } from "./bus-transport.js";
-import { TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS } from "./locks.js";
+import { isSameTelegramLockOwner, TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS, } from "./locks.js";
 import { resolveAgentDir } from "./paths.js";
 import { getTelegramProcessBirthIdentity } from "./process-identity.js";
 import { parseTelegramQueueHandoffPayload, TELEGRAM_QUEUE_HANDOFF_PAYLOAD_MAX_BYTES, } from "./queue.js";
@@ -46,7 +46,8 @@ export function createTelegramBusProcessRuntime(input) {
 export function createTelegramBusAuthSecret() {
     return randomBytes(32).toString("base64url");
 }
-const TELEGRAM_BUS_PROTOCOL_VERSION = 2;
+// v3: journal source serialization left the config transaction; mixed v2/v3 peers would not exclude each other.
+const TELEGRAM_BUS_PROTOCOL_VERSION = 3;
 export const TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION = "durable-follower-admission-v1";
 export const TELEGRAM_BUS_CAPABILITY_QUEUE_HANDOFF = "queue-handoff-v1";
 export const TELEGRAM_BUS_CAPABILITY_INPUT_CUSTODY_REFERENCE = "input-custody-reference-v1";
@@ -466,7 +467,8 @@ export function createTelegramBusFollowerSourceReferenceDeliveryIdentity(input)
 }
 export function getTelegramBusEnvelopeTrafficClass(envelope) {
     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";
@@ -718,6 +720,9 @@ export function parseTelegramBusEnvelope(line) {
         case "follower.callApi":
             envelope = parseCallApiEnvelope(value, requestId);
             break;
+        case "bus.probe":
+            envelope = { kind, requestId };
+            break;
         case "bus.ack":
             envelope = parseAckEnvelope(value, requestId);
             break;
@@ -729,6 +734,79 @@ export function parseTelegramBusEnvelope(line) {
         envelope.auth = auth;
     return envelope;
 }
+export function probeTelegramBusLeader(input) {
+    const timeoutMs = input.timeoutMs ?? TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS;
+    return new Promise((resolve) => {
+        let settled = false;
+        let socket;
+        const finish = (result) => {
+            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.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) {
+    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) {
+    const probe = deps.probe ?? probeTelegramBusLeader;
+    const sleep = deps.sleep ??
+        ((ms) => new Promise((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,
+    });
+}
 const TELEGRAM_ACTIVE_LOCAL_SERVERS = Symbol.for("@llblab/pi-telegram/active-local-servers");
 function getActiveTelegramBusLocalServers() {
     const root = globalThis;

package/dist/lib/config.d.ts

@@ -116,12 +116,6 @@ export interface TelegramConfigStore {
     setAllowedUserId: (userId: number) => void;
     /** Publish an unpaired profile owner atomically; true only for the resulting exact owner. */
     persistAllowedUserId: (userId: number, 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, tokenSha256: string, publish: (preApprovalExcluded: boolean) => T) => T;
     /** Observe an existing exact owner and refresh an unpaired cache; never create an owner. Callback must be synchronous. */

package/dist/lib/config.js

@@ -449,7 +449,6 @@ export function createTelegramConfigStore(options = {}) {
             nextConfig.allowedUserId = userId;
             setEffectiveConfig(nextConfig);
         },
-        withSourceSerialization: (operation) => withTelegramFileTransaction(`${configPath}.transaction`, operation),
         withPairingAdmission: (profileName, tokenSha256, publish) => withPersistedPairingProfile(profileName, tokenSha256, (_latest, profile) => publish(profile.allowedUserId === undefined)),
         withPairedUserAdmission: (profileName, tokenSha256, userId, publish, assertExecutionCurrent) => {
             if (!Number.isSafeInteger(userId) || userId <= 0)

package/dist/lib/extension.js

@@ -142,12 +142,13 @@ export default function (pi) {
         },
         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", event.kind === "repaired"
                     ? "Telegram update journal was repaired automatically."
@@ -199,6 +200,10 @@ export default function (pi) {
             return telegramLeaderJournalPath.createJournalPath();
         },
     });
+    const proveTelegramLeaderUnresponsive = Bus.createTelegramBusLeaderUnresponsivenessProof({
+        getLeaderState: lockRuntime.getState,
+        getLeaderSocketPath: getTelegramBusSocketPath,
+    });
     const telegramSessionContextStore = Lifecycle.createTelegramSessionContextStore({
         getIdentity(ctx) {
             return ctx.sessionManager ?? ctx.cwd;
@@ -1069,7 +1074,7 @@ export default function (pi) {
                 botToken,
                 botId: getTelegramBotId(),
             });
-            return configStore.withSourceSerialization(function () {
+            return withTelegramJournalSourceSerialization(function () {
                 return Journal.isTelegramThreadCleanupJournalNamespaceClear({
                     directory: Paths.resolveTelegramTempDir(),
                     profile,
@@ -1554,6 +1559,7 @@ export default function (pi) {
         },
         recovery: {
             getLeaderState: lockRuntime.getState,
+            proveLeaderUnresponsive: proveTelegramLeaderUnresponsive,
             setLifecyclePhase: telegramBusFollowerControlState.setLifecyclePhase,
             updateStatus,
             promoteToLeader: promoteTelegramBusFollowerToLeader,
@@ -1860,6 +1866,7 @@ export default function (pi) {
     const threadAwarePollingPorts = telegramThreadCapabilityRuntime.pollingPorts;
     const lockedPollingRuntime = Locks.createTelegramLockedPollingRuntime({
         lock: lockRuntime,
+        proveOwnerUnresponsive: proveTelegramLeaderUnresponsive,
         resetDamagedState() {
             return Locks.resetDamagedTelegramRuntimeState(Paths.resolveTelegramStatePath(), function (profile, sections) {
                 Threads.parseTelegramWorkspaceStateSection(sections.workspace, profile);

package/dist/lib/journal.d.ts

@@ -860,6 +860,14 @@ export declare function createTelegramUpdateJournalBindingRuntime(deps: {
     getActiveFollowerSessionId?: () => string | undefined;
     isFollowerRegistered: () => boolean;
 }): TelegramUpdateJournalBindingRuntime;
+/**
+ * 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 declare function createTelegramJournalSourceSerialization(getTransactionPath?: () => string): <T>(operation: () => T) => T;
 export declare function createTelegramUpdateJournalStore(options: TelegramUpdateJournalStoreOptions): TelegramUpdateJournalStore;
 /** Opt-in v3 only; does not migrate old files or expose legacy unowned mutation ports. */
 export declare function createTelegramInputJournalStore(options: TelegramInputJournalStoreOptions): TelegramInputJournalStore;

package/dist/lib/journal.js

@@ -10,7 +10,7 @@ import { chmodSync, closeSync, fstatSync, lstatSync, mkdirSync, opendirSync, ope
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { TELEGRAM_STRICT_READ_FLAGS, renameTelegramPathWithRetry, withTelegramFileTransaction, } from "./locks.js";
-import { decodeTelegramSessionDirectoryName, getTelegramProfilePathSuffix, TELEGRAM_DEFAULT_PROFILE_NAME, } from "./paths.js";
+import { decodeTelegramSessionDirectoryName, getTelegramProfilePathSuffix, resolveTelegramRuntimeDir, TELEGRAM_DEFAULT_PROFILE_NAME, } from "./paths.js";
 import { getTelegramProcessLiveness, } from "./process-identity.js";
 import { hasOnlyWireKeys as hasOnlyKeys, isNonEmptyWireString as isNonEmptyString, isWireRecord as isRecord, isNonNegativeWireInteger as isSafeNonNegativeInteger, } from "./wire.js";
 import { getTelegramWorkspaceAdmissionScopeKey, runWithTelegramWorkspaceAdmissions, } from "./workspace-admission.js";
@@ -2735,6 +2735,16 @@ 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 = () => join(resolveTelegramRuntimeDir(), "journals.transaction")) {
+    return (operation) => withTelegramFileTransaction(getTransactionPath(), operation);
+}
 export function createTelegramUpdateJournalStore(options) {
     return createJournalStoreCore(options).journal;
 }
@@ -3221,31 +3231,29 @@ function createJournalStoreCore(options, getInputContext) {
             return { file: reset, exists: true, serializedBytes };
         }
     };
+    const acquireSource = () => sourceAccess
+        ? acquireTelegramUpdateJournalFamily({
+            ...sourceAccess,
+            path,
+            profile,
+            botIdentity: expectedIdentity,
+        }, version)
+        : undefined;
+    const readAcquiredSource = (source) => {
+        const file = source.evidence.kind === "present" ? source.evidence.file : emptyFile();
+        return {
+            file,
+            exists: source.evidence.kind === "present",
+            serializedBytes: assertCapacity(file),
+            source,
+        };
+    };
     const runJournalTransaction = (operation) => {
         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 = () => {
-                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 = () => source ? readAcquiredSource(source) : readCurrent();
             return withTelegramFileTransaction(`${path}.transaction`, () => operation(readSource));
         }
         catch (error) {
@@ -4091,16 +4099,31 @@ function createJournalStoreCore(options, getInputContext) {
         assertCurrent();
         return { issued, entries: result };
     });
+    const projectRead = (current) => ({
+        ...cloneFile(current.file),
+        exists: current.exists,
+        serializedBytes: current.serializedBytes,
+    });
     const journal = {
         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 = () => {
+                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) => normalizeIncomingJournaledUpdate(update, path));
@@ -4206,18 +4229,20 @@ function createJournalStoreCore(options, getInputContext) {
                     serializedBytes: published.serializedBytes,
                 };
             });
+            // Sender admission is the outer config authority; journal serialization nests inside it.
+            const serializedAppend = (preApprovalExcluded) => withSourceSerialization
+                ? withSourceSerialization(() => appendWithEvidence(preApprovalExcluded))
+                : appendWithEvidence(preApprovalExcluded);
             const append = () => {
                 if (withPairedAdmission) {
-                    const result = withPairedAdmission(normalizedUpdates, () => appendWithEvidence());
+                    const result = withPairedAdmission(normalizedUpdates, () => serializedAppend());
                     if (!result.admitted)
                         throw createJournalError("sender-denied", path, "refused paired-only sender admission");
                     return result.value;
                 }
                 if (withPairingAdmission)
-                    return withPairingAdmission(appendWithEvidence);
-                return withSourceSerialization
-                    ? withSourceSerialization(() => appendWithEvidence())
-                    : appendWithEvidence();
+                    return withPairingAdmission(serializedAppend);
+                return serializedAppend();
             };
             const admittedAppend = () => {
                 if (!workspaceAdmission)

package/dist/lib/locks.d.ts

@@ -60,6 +60,8 @@ interface TelegramLockAcquireOptions {
     force?: boolean;
     expectedOwner?: TelegramLockEntry;
     election?: boolean;
+    /** Bus-proven unresponsive owner: treated as stale only while it is still exactly the current owner. */
+    unresponsiveOwner?: TelegramLockEntry;
 }
 type TelegramLockAcquireResult = {
     ok: true;
@@ -213,6 +215,8 @@ export interface TelegramOwnedStatePublicationOptions extends TelegramRuntimeSta
 export declare function mutateTelegramRuntimeStateSection<T>(path: string, profile: string, section: TelegramRuntimeStateSection, mutate: TelegramRuntimeStateSectionReducer<T>, options: TelegramRuntimeStatePublicationOptions): T;
 export declare function writeLocks(path: string, locks: Record<string, unknown>): void;
 export declare function parseTelegramLockEntry(value: unknown): TelegramLockEntry | undefined;
+/** Exact owner identity (pid, cwd, instance, leader epoch, runtime generation); absent entries never match. */
+export declare function isSameTelegramLockOwner(current: TelegramLockEntry | undefined, expected: TelegramLockEntry | undefined): boolean;
 export declare function createTelegramLockRuntime<TContext extends TelegramLockContext>(options?: TelegramLockRuntimeOptions): TelegramLockRuntime<TContext>;
 export declare function createTelegramLockOwnershipGuard<TContext extends TelegramLockContext>(lock: TelegramLockRuntime<TContext>): TelegramLockOwnershipGuard<TContext>;
 export declare function createTelegramDirectDeliveryOwnershipChecker<TContext extends TelegramLockContext>(deps: {
@@ -225,6 +229,7 @@ interface TelegramLockedPollingStartOptions {
     requestedThreadName?: string;
     election?: {
         expectedOwner?: TelegramLockEntry;
+        unresponsive?: boolean;
     };
     onAcquired?: () => Promise<void> | void;
 }
@@ -270,6 +275,8 @@ interface TelegramLockedPollingRuntimeDeps<TContext extends TelegramLockContext>
     registerFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     restoreFollowerWithOwner?: (ctx: TContext, owner: TelegramLockEntry) => boolean | undefined | Promise<boolean | undefined>;
     stopFollowerRegistration?: () => void;
+    /** Threaded Mode takeover evidence after failed follower registration; replaces the retired file heartbeat. */
+    proveOwnerUnresponsive?: (owner: TelegramLockEntry) => Promise<boolean>;
     onTransportAvailabilityChanged?: () => void;
     transportMonitor?: {
         start: (ctx: TContext) => void;