@llblab/pi-kit 0.27.6 → 0.28.0

package/node_modules/@llblab/pi-telegram/lib/locks.ts

@@ -1,15 +1,18 @@
 /**
  * Telegram singleton lock helpers
  * Zones: telegram ownership, filesystem, transport authority
- * Owns extension-local owners.json access and Telegram bridge ownership semantics
+ * Owns filesystem authority, atomic runtime-section publication and Telegram bridge ownership semantics
  */
 
 import {
   chmodSync,
+  closeSync,
   existsSync,
+  fstatSync,
   lstatSync,
   mkdirSync,
   mkdtempSync,
+  openSync,
   readFileSync,
   readdirSync,
   renameSync,
@@ -18,8 +21,15 @@ import {
   writeFileSync,
 } from "node:fs";
 import { randomUUID } from "node:crypto";
-import { basename, dirname, join } from "node:path";
-import { resolveTelegramOwnersPath } from "./paths.ts";
+import { isDeepStrictEqual } from "node:util";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { isWireRecord as runtimeStateRecord } from "./wire.ts";
+import {
+  isTelegramSessionPollingJournalPath,
+  resolveTelegramOwnersPath,
+  resolveTelegramSessionPollingJournalPath,
+  resolveTelegramUpdateJournalPathForProfile,
+} from "./paths.ts";
 
 export const TELEGRAM_LOCK_KEY = "default";
 export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 8_000;
@@ -57,7 +67,7 @@ export function resolveTelegramLockKey(activeProfile?: string): string {
   return activeProfile || TELEGRAM_LOCK_KEY;
 }
 
-export interface TelegramActiveProfileGetter {
+interface TelegramActiveProfileGetter {
   getActiveProfileName: () => string | undefined;
 }
 
@@ -69,6 +79,31 @@ export function createTelegramLockKeyResolver(
   };
 }
 
+/** Structural session view; Locks never imports the lifecycle owner. */
+interface TelegramOwnedStateSessionPort<TContext extends TelegramLockContext> {
+  get: () => TContext | undefined;
+  getGeneration: () => number;
+  isCurrent: (ctx: TContext, generation?: number) => boolean;
+}
+
+/**
+ * Captures exact context, session generation and owned leader epoch before awaits.
+ * Session replacement, release or re-election revokes the grant; a successor never renews it.
+ */
+export function createTelegramOwnedStateAuthorityCapture<TContext extends TelegramLockContext>(
+  lock: Pick<TelegramLockRuntime<TContext>, "owns" | "getOwnedLeaderEpoch">,
+  session: TelegramOwnedStateSessionPort<TContext>,
+): () => (() => boolean) | undefined {
+  return () => {
+    const ctx = session.get(), generation = session.getGeneration();
+    if (ctx === undefined || !session.isCurrent(ctx, generation)) return undefined;
+    const epoch = lock.getOwnedLeaderEpoch();
+    if (epoch === undefined) return undefined;
+    const current = (): boolean => session.isCurrent(ctx, generation) && lock.owns(ctx) && lock.getOwnedLeaderEpoch() === epoch;
+    return current() ? current : undefined;
+  };
+}
+
 export interface TelegramLockEntry {
   pid: number;
   cwd?: string;
@@ -78,6 +113,8 @@ export interface TelegramLockEntry {
   runtimeGeneration?: number;
   busSocketPath?: string;
   busSecret?: string;
+  /** Polling journal custody; inherited by every successor and kept after release. */
+  journalPath?: string;
 }
 
 export interface TelegramLockContext {
@@ -90,16 +127,18 @@ export type TelegramLockState =
   | { kind: "active-elsewhere"; lock: TelegramLockEntry }
   | { kind: "stale"; lock: TelegramLockEntry };
 
-export interface TelegramLockAcquireOptions {
+interface TelegramLockAcquireOptions {
   force?: boolean;
   expectedOwner?: TelegramLockEntry;
   election?: boolean;
 }
 
-export type TelegramLockAcquireResult =
+type TelegramLockAcquireResult =
   | { ok: true; lock: TelegramLockEntry; replacedStale: boolean }
   | { ok: false; lock: TelegramLockEntry };
 
+export type TelegramOwnedStatePublicationResult<T> = { committed: false } | { committed: true; result: T };
+
 export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
   acquire: (
     ctx: TContext,
@@ -111,24 +150,37 @@ export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
   getOwnedLeaderEpoch: () => number | string | undefined;
   owns: (ctx?: TelegramLockContext) => boolean;
   commitIfOwned: (commit: () => void) => boolean;
+  /** Consolidated-store publication; domain reducers retain their own exact payload/CAS rules. */
+  publishStateSectionIfOwned?: <T>(
+    section: "workspace" | "runtime",
+    mutate: (current: unknown, observed: Readonly<TelegramRuntimeStateProfile>) => TelegramRuntimeStateMutation<T>,
+    options: TelegramOwnedStatePublicationOptions,
+  ) => TelegramOwnedStatePublicationResult<T>;
   refresh: (ctx?: TelegramLockContext) => boolean;
+  /** The polling journal named by owners.json for this key, owned or not. */
+  getJournalPath: () => string | undefined;
 }
 
-export interface TelegramLockOwnershipGuard<
+interface TelegramLockOwnershipGuard<
   TContext extends TelegramLockContext,
 > {
   ownsContext: (ctx: TContext) => boolean;
 }
 
-export interface TelegramLockContextStore<
+interface TelegramLockContextStore<
   TContext extends TelegramLockContext,
 > {
   get: () => TContext | undefined;
 }
 
-export interface TelegramLockRuntimeOptions {
+interface TelegramLockRuntimeOptions {
   key?: string | (() => string | undefined);
   locksPath?: string;
+  /** Consolidated version-2 state envelope; exclusive with `locksPath`. */
+  statePath?: string;
+  statePublication?: Pick<TelegramRuntimeStatePublicationOptions, "onPublicationBoundary" | "publishRename">;
+  /** Read-only ownership file of releases that used another directory; a live fresh owner there blocks acquisition. */
+  legacyLocksPath?: string;
   pid?: number;
   isProcessAlive?: (pid: number) => boolean;
   instanceId?: string;
@@ -138,6 +190,42 @@ export interface TelegramLockRuntimeOptions {
   mintLeaderEpoch?: () => number | string;
   runtimeGeneration?: number;
   staleHeartbeatMs?: number;
+  /** First leader without an inherited pointer names the polling journal it creates. */
+  createJournalPath?: (ctx: TelegramLockContext) => string | undefined;
+}
+
+/**
+ * Leader polling journal: the path owners.json names, else the session that would host it on acquisition.
+ * Without a session identity, the flat root `inbox` remains the compatibility fallback.
+ */
+export function createTelegramLeaderJournalPathResolver(deps: {
+  getNamedJournalPath: () => string | undefined;
+  getSessionId: () => string | undefined;
+  getProfileName: () => string | undefined;
+}) {
+  // An existing flat root journal keeps its custody; new installations never create one.
+  const createOwn = (profileName = deps.getProfileName()): string | undefined => {
+    const root = resolveTelegramUpdateJournalPathForProfile(profileName);
+    if (existsSync(root)) return root;
+    const sessionId = deps.getSessionId();
+    return sessionId === undefined ? undefined : resolveTelegramSessionPollingJournalPath(sessionId, undefined, profileName);
+  };
+  return {
+    createJournalPath: () => createOwn(),
+    resolve(profileName?: string): string {
+      const named = deps.getNamedJournalPath();
+      if (named && (isTelegramSessionPollingJournalPath(named) ||
+          named === resolveTelegramUpdateJournalPathForProfile(profileName))) return named;
+      return createOwn(profileName) ?? resolveTelegramUpdateJournalPathForProfile(profileName);
+    },
+  };
+}
+
+/** A released key keeps only `{ journalPath }`: no owner, but the successor's polling custody. */
+export function readTelegramLockJournalPath(value: unknown): string | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const path = (value as Record<string, unknown>).journalPath;
+  return typeof path === "string" && path ? path : undefined;
 }
 
 export function readLocks(path = getOwnersPath()): Record<string, unknown> {
@@ -177,7 +265,7 @@ function sleepSync(ms: number): void {
   Atomics.wait(new Int32Array(buffer), 0, 0, ms);
 }
 
-export interface TelegramRenameRetryOptions {
+interface TelegramRenameRetryOptions {
   rename?: typeof renameSync;
   attempts?: number;
   retryDelayMs?: number;
@@ -650,6 +738,188 @@ export function withTelegramFileTransaction<T>(
   }
 }
 
+export type TelegramRuntimeStateSection = "transport" | "workspace" | "admission" | "runtime";
+type TelegramRuntimeStateProfile = Partial<Record<TelegramRuntimeStateSection, unknown>>;
+interface TelegramRuntimeStateFile {
+  version: 2;
+  profiles: Record<string, TelegramRuntimeStateProfile>;
+}
+export class TelegramRuntimeStateError extends Error {
+  readonly code: "invalid" | "authority-changed" | "publication-unknown";
+  constructor(code: TelegramRuntimeStateError["code"], message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "TelegramRuntimeStateError";
+    this.code = code;
+  }
+}
+const TELEGRAM_RUNTIME_STATE_SECTIONS: readonly TelegramRuntimeStateSection[] = ["transport", "workspace", "admission", "runtime"];
+const TELEGRAM_ACTIVE_STATE_TRANSACTIONS = Symbol.for("@llblab/pi-telegram/active-state-transactions");
+type TelegramStateGlobal = typeof globalThis & { [TELEGRAM_ACTIVE_STATE_TRANSACTIONS]?: Set<string> };
+function requireRuntimeStatePath(path: string): void {
+  if (typeof path !== "string" || !isAbsolute(path) || resolve(path) !== path)
+    throw new TelegramRuntimeStateError("invalid", "Telegram runtime state path must be canonical and absolute.");
+}
+function requireRuntimeStateProfile(profile: string): void {
+  if (typeof profile !== "string" || !profile.length || profile.length > 512 || /[\x00-\x1f]/u.test(profile))
+    throw new TelegramRuntimeStateError("invalid", "Telegram runtime state profile is invalid.");
+}
+/** Private single-link regular file read with identity continuity; initial absence only is positive. */
+function readTelegramRuntimeSource(path: string): string | undefined {
+  requireRuntimeStatePath(path);
+  let source: string;
+  let observed = false;
+  try {
+    const stat = lstatSync(path);
+    observed = true;
+    if (!stat.isFile() || stat.nlink !== 1 ||
+        (process.platform !== "win32" && (stat.mode & 0o077) !== 0))
+      throw new TelegramRuntimeStateError("invalid", "Telegram runtime state must be a private regular file.");
+    const fd = openSync(path, "r");
+    try {
+      const opened = fstatSync(fd);
+      if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.nlink !== 1 || !opened.isFile() ||
+          (process.platform !== "win32" && (opened.mode & 0o077) !== 0))
+        throw new TelegramRuntimeStateError("invalid", "Telegram runtime state identity changed before reading.");
+      source = readFileSync(fd).toString("utf8");
+    } finally { closeSync(fd); }
+    const after = lstatSync(path);
+    if (after.dev !== stat.dev || after.ino !== stat.ino || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs)
+      throw new TelegramRuntimeStateError("invalid", "Telegram runtime state changed during observation.");
+  }
+  catch (error) {
+    if (!observed && (error as { code?: unknown }).code === "ENOENT") return undefined;
+    throw error;
+  }
+  return source;
+}
+
+/** Strict, observational envelope read; section owners validate their own payloads. Legacy state is never adopted here. */
+export function readTelegramRuntimeState(path: string): TelegramRuntimeStateFile {
+  const observed = readTelegramRuntimeSource(path);
+  if (observed === undefined) return { version: 2, profiles: {} };
+  let value: unknown;
+  try { value = JSON.parse(observed); }
+  catch (error) { throw new TelegramRuntimeStateError("invalid", "Telegram runtime state is unreadable.", { cause: error }); }
+  if (!runtimeStateRecord(value) || value.version !== 2 || !runtimeStateRecord(value.profiles) ||
+      Object.keys(value).some(key => key !== "version" && key !== "profiles"))
+    throw new TelegramRuntimeStateError("invalid", "Telegram runtime state envelope is unsupported or malformed.");
+  for (const [profile, sections] of Object.entries(value.profiles)) {
+    requireRuntimeStateProfile(profile);
+    if (!runtimeStateRecord(sections) || Object.keys(sections).some(key => !TELEGRAM_RUNTIME_STATE_SECTIONS.includes(key as TelegramRuntimeStateSection)))
+      throw new TelegramRuntimeStateError("invalid", "Telegram runtime state sections are malformed.");
+  }
+  return value as unknown as TelegramRuntimeStateFile;
+}
+/**
+ * Operator-approved optimistic recovery before leader acquisition: when the shared envelope, any transport section or a
+ * caller-validated section is damaged, publish a fresh empty envelope instead of refusing. All profiles lose runtime
+ * continuity. Filesystem access errors are not damage and still throw. Returns whether a reset was published.
+ */
+export function resetDamagedTelegramRuntimeState(path: string,
+  validateProfile?: (profile: string, sections: Readonly<TelegramRuntimeStateProfile>) => void): boolean {
+  requireRuntimeStatePath(path);
+  const runtimeDir = join(dirname(path), "runtime");
+  mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
+  return withTelegramFileTransaction(join(runtimeDir, `${basename(path)}.transaction`), () => {
+    let damaged = false;
+    try {
+      for (const [profile, sections] of Object.entries(readTelegramRuntimeState(path).profiles)) {
+        assertTelegramStateTransport(sections.transport);
+        try { validateProfile?.(profile, sections); } catch { damaged = true; }
+      }
+    } catch (error) {
+      if (!(error instanceof TelegramRuntimeStateError)) throw error;
+      damaged = true;
+    }
+    if (!damaged) return false;
+    const tempPath = join(runtimeDir, `${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(tempPath, `${JSON.stringify({ version: 2, profiles: {} }, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+      if (!renameTelegramPathWithRetry(tempPath, path)) throw new Error("Telegram runtime state reset publication disappeared.");
+    } finally {
+      try { unlinkSync(tempPath); }
+      catch (error) { if ((error as { code?: unknown }).code !== "ENOENT") throw error; }
+    }
+    return true;
+  });
+}
+export interface TelegramRuntimeStateMutation<T> {
+  value: unknown;
+  result: T;
+}
+interface TelegramRuntimeStatePublicationOptions {
+  /** Exact domain authority, recaptured by the caller before invoking this synchronous transaction. */
+  isCurrent: () => boolean;
+  onPublicationBoundary?: (boundary: "before-write" | "after-write-before-rename" | "after-rename") => void;
+  publishRename?: typeof renameSync;
+}
+export interface TelegramOwnedStatePublicationOptions extends TelegramRuntimeStatePublicationOptions {
+  /** Optional caller-bound physical/logical identity; a mismatch cannot redirect an owner grant. */
+  expectedScope?: { path: string; profile: string };
+}
+/**
+ * One physical read/check/write transaction for one named section. The caller supplies domain policy; copies expose
+ * current sibling facts without granting writes to them. No await, nested transaction, repair or legacy import.
+ */
+export function mutateTelegramRuntimeStateSection<T>(
+  path: string, profile: string, section: TelegramRuntimeStateSection,
+  mutate: (current: unknown, observed: Readonly<TelegramRuntimeStateProfile>) => TelegramRuntimeStateMutation<T>,
+  options: TelegramRuntimeStatePublicationOptions,
+): T {
+  requireRuntimeStatePath(path);
+  requireRuntimeStateProfile(profile);
+  if (!TELEGRAM_RUNTIME_STATE_SECTIONS.includes(section))
+    throw new TelegramRuntimeStateError("invalid", "Telegram runtime state section is invalid.");
+  const active = ((globalThis as TelegramStateGlobal)[TELEGRAM_ACTIVE_STATE_TRANSACTIONS] ??= new Set<string>());
+  if (active.has(path)) throw new TelegramRuntimeStateError("invalid", "Nested Telegram runtime state transaction is not allowed.");
+  const assertCurrent = (): void => {
+    if (!options.isCurrent()) throw new TelegramRuntimeStateError("authority-changed", "Telegram runtime state publication authority changed.");
+  };
+  assertCurrent();
+  active.add(path);
+  try {
+    const runtimeDir = join(dirname(path), "runtime");
+    mkdirSync(runtimeDir, { recursive: true, mode: 0o700 });
+    return withTelegramFileTransaction(join(runtimeDir, `${basename(path)}.transaction`), () => {
+      assertCurrent();
+      const file = readTelegramRuntimeState(path);
+      const previous = Object.hasOwn(file.profiles, profile) ? file.profiles[profile]! : {};
+      const outcome = mutate(structuredClone(previous[section]), structuredClone(previous));
+      if (!runtimeStateRecord(outcome) || !Object.hasOwn(outcome, "value") || !Object.hasOwn(outcome, "result") || "then" in outcome)
+        throw new TelegramRuntimeStateError("invalid", "Telegram runtime state mutations must return a synchronous value and result.");
+      // Normalize intentional optional properties to their wire representation before comparison/publication.
+      const next = outcome.value === undefined ? undefined : JSON.parse(JSON.stringify(outcome.value)) as unknown;
+      assertCurrent();
+      if (isDeepStrictEqual(previous[section], next)) return outcome.result;
+      const updated = { ...previous };
+      if (next === undefined) delete updated[section];
+      else updated[section] = next;
+      if (Object.keys(updated).length) Object.defineProperty(file.profiles, profile, { value: updated, enumerable: true, configurable: true, writable: true });
+      else delete file.profiles[profile];
+      const tempPath = join(runtimeDir, `${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+      try {
+        options.onPublicationBoundary?.("before-write");
+        assertCurrent();
+        writeFileSync(tempPath, `${JSON.stringify(file, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        options.onPublicationBoundary?.("after-write-before-rename");
+        assertCurrent();
+        try {
+          if (!renameTelegramPathWithRetry(tempPath, path, { rename: options.publishRename }))
+            throw new Error("Telegram runtime state temporary publication disappeared.");
+          options.onPublicationBoundary?.("after-rename");
+          assertCurrent();
+        } catch (error) {
+          throw new TelegramRuntimeStateError("publication-unknown", "Telegram runtime state publication outcome is unknown.", { cause: error });
+        }
+        return outcome.result;
+      } finally {
+        try { unlinkSync(tempPath); }
+        catch (error) { if ((error as { code?: unknown }).code !== "ENOENT") throw error; }
+      }
+    });
+  } finally { active.delete(path); }
+}
+
 function withLockTransaction<T>(
   locksPath: string,
   mutate: (locks: Record<string, unknown>) => {
@@ -730,6 +1000,7 @@ export function parseTelegramLockEntry(
         : undefined,
     busSecret:
       typeof record.busSecret === "string" ? record.busSecret : undefined,
+    ...(readTelegramLockJournalPath(record) ? { journalPath: readTelegramLockJournalPath(record) } : {}),
   };
 }
 
@@ -744,7 +1015,7 @@ export function isProcessAlive(pid: number): boolean {
   }
 }
 
-export function formatTelegramLockEntry(lock: TelegramLockEntry): string {
+function formatTelegramLockEntry(lock: TelegramLockEntry): string {
   return lock.cwd ? `pid ${lock.pid}, cwd ${lock.cwd}` : `pid ${lock.pid}`;
 }
 
@@ -832,9 +1103,11 @@ function createLockEntry(
     getNowMs?: () => number;
     mintLeaderEpoch?: () => number | string;
     runtimeGeneration?: number;
+    journalPath?: string;
   },
 ): TelegramLockEntry {
   const lock: TelegramLockEntry = { pid, cwd: ctx.cwd };
+  if (options.journalPath) lock.journalPath = options.journalPath;
   if (options.instanceId) {
     const nowMs = options.getNowMs?.();
     lock.instanceId = options.instanceId;
@@ -860,10 +1133,27 @@ function formatLockState(state: TelegramLockState): string {
   }
 }
 
+function assertTelegramStateTransport(value: unknown): void {
+  if (value === undefined) return;
+  if (!runtimeStateRecord(value)) throw new TelegramRuntimeStateError("invalid", "Telegram state transport is malformed.");
+  const keys = ["pid", "cwd", "instanceId", "heartbeatMs", "leaderEpoch", "runtimeGeneration", "busSocketPath", "busSecret", "journalPath"];
+  if (Object.keys(value).some(key => !keys.includes(key)) ||
+      (value.pid === undefined ? Object.keys(value).length !== 1 || !readTelegramLockJournalPath(value) :
+        !Number.isSafeInteger(value.pid) || (value.pid as number) <= 0) ||
+      ["cwd", "instanceId", "busSocketPath", "busSecret", "journalPath"].some(key => value[key] !== undefined && typeof value[key] !== "string") ||
+      ["heartbeatMs", "runtimeGeneration"].some(key => value[key] !== undefined && (!Number.isSafeInteger(value[key]) || (value[key] as number) < 0)) ||
+      (value.journalPath !== undefined && !readTelegramLockJournalPath(value)) ||
+      (value.leaderEpoch !== undefined && (typeof value.leaderEpoch === "string" ? value.leaderEpoch.length === 0 : !Number.isSafeInteger(value.leaderEpoch))))
+    throw new TelegramRuntimeStateError("invalid", "Telegram state transport is malformed.");
+}
+
 export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
   options: TelegramLockRuntimeOptions = {},
 ): TelegramLockRuntime<TContext> {
   const key = options.key ?? TELEGRAM_LOCK_KEY;
+  if (options.statePath && options.locksPath)
+    throw new TelegramRuntimeStateError("invalid", "Telegram transport must select one storage identity.");
+  const statePath = options.statePath;
   const locksPath = options.locksPath ?? getOwnersPath();
   const pid = options.pid ?? process.pid;
   const isAlive = options.isProcessAlive ?? isProcessAlive;
@@ -881,9 +1171,48 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
     if (typeof key === "function") return key() || TELEGRAM_LOCK_KEY;
     return key;
   };
+  const readOwners = (): Record<string, unknown> => {
+    if (!statePath) return readLocks(locksPath);
+    // Read-only ownership queries fail closed (no owner); acquisition/publication still refuse malformed state.
+    try {
+      const transports = Object.fromEntries(Object.entries(readTelegramRuntimeState(statePath).profiles)
+        .filter(([, value]) => Object.hasOwn(value, "transport")).map(([profile, value]) => [profile, value.transport]));
+      assertTelegramStateTransport(transports[resolveEffectiveKey()]);
+      return transports;
+    } catch { return {}; }
+  };
+  const transactOwners = <T>(mutate: (locks: Record<string, unknown>) => { result: T; changed: boolean }): T => {
+    if (!statePath) return withLockTransaction(locksPath, mutate);
+    const profile = resolveEffectiveKey();
+    return mutateTelegramRuntimeStateSection(statePath, profile, "transport", current => {
+      assertTelegramStateTransport(current);
+      const locks = { [profile]: current };
+      const outcome = mutate(locks);
+      const value = outcome.changed ? locks[profile] : current;
+      assertTelegramStateTransport(value);
+      return { value, result: outcome.result };
+    }, { ...options.statePublication, isCurrent: () => resolveEffectiveKey() === profile });
+  };
   const readLock = () => {
     const effectiveKey = resolveEffectiveKey();
-    return parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+    return parseTelegramLockEntry(readOwners()[effectiveKey]);
+  };
+  // A live older-release leader polls the same bot from its own directory. Only identity is exposed: its bus
+  // endpoint, secret and epoch belong to another protocol and must never become a follower target.
+  const readLegacyOwner = (effectiveKey: string): TelegramLockEntry | undefined => {
+    if (!options.legacyLocksPath || options.legacyLocksPath === (statePath ?? locksPath)) return undefined;
+    try {
+      const records = statePath ? readLocksForTransaction(options.legacyLocksPath) : readLocks(options.legacyLocksPath);
+      if (statePath) for (const value of Object.values(records)) assertTelegramStateTransport(value);
+      const raw = records[effectiveKey];
+      const legacy = parseTelegramLockEntry(raw);
+      if (!legacy || getLockState(legacy, -1, isAlive, stateOptions()).kind !== "active-elsewhere") return undefined;
+      return { pid: legacy.pid, ...(legacy.cwd ? { cwd: legacy.cwd } : {}), ...(legacy.instanceId ? { instanceId: legacy.instanceId } : {}),
+        ...(legacy.heartbeatMs !== undefined ? { heartbeatMs: legacy.heartbeatMs } : {}) };
+    } catch (error) {
+      if (statePath) throw error;
+      return undefined;
+    }
   };
   const adoptCompatibleOwnedLock = (
     effectiveKey: string,
@@ -908,8 +1237,10 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
   };
   return {
     acquire: (ctx, acquireOptions = {}) =>
-      withLockTransaction<TelegramLockAcquireResult>(locksPath, (locks) => {
+      transactOwners<TelegramLockAcquireResult>((locks) => {
         const effectiveKey = resolveEffectiveKey();
+        const legacy = readLegacyOwner(effectiveKey);
+        if (legacy) return { result: { ok: false, lock: legacy } as const, changed: false };
         const current = parseTelegramLockEntry(locks[effectiveKey]);
         const state = getLockState(current, pid, isAlive, stateOptions());
         const expectedOwned = adoptCompatibleOwnedLock(
@@ -971,7 +1302,9 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
             changed: false,
           };
         }
+        const journalPath = readTelegramLockJournalPath(locks[effectiveKey]) ?? options.createJournalPath?.(ctx);
         const lock = createLockEntry(pid, ctx, {
+          journalPath,
           instanceId: options.instanceId,
           busSocketPath: options.busSocketPath,
           busSecret: options.busSecret,
@@ -995,7 +1328,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
     release: () => {
       // Withdraw local send authority even if the durable release fails.
       deliveryRevoked = true;
-      return withLockTransaction(locksPath, (locks) => {
+      return transactOwners((locks) => {
         const effectiveKey = resolveEffectiveKey();
         const state = getLockState(
           parseTelegramLockEntry(locks[effectiveKey]),
@@ -1010,7 +1343,9 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
             ownedLock,
           );
         if (changed) {
-          delete locks[effectiveKey];
+          const journalPath = readTelegramLockJournalPath(locks[effectiveKey]);
+          if (journalPath) locks[effectiveKey] = { journalPath };
+          else delete locks[effectiveKey];
           ownedLockKey = undefined;
           ownedLock = undefined;
         }
@@ -1018,26 +1353,27 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
       });
     },
     getState: () => getLockState(readLock(), pid, isAlive, stateOptions()),
+    getJournalPath: () => readTelegramLockJournalPath(readOwners()[resolveEffectiveKey()]),
     getStatusLabel: () =>
       formatLockState(getLockState(readLock(), pid, isAlive, stateOptions())),
     getOwnedLeaderEpoch: () => {
       if (deliveryRevoked) return undefined;
       const effectiveKey = resolveEffectiveKey();
-      const lock = parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+      const lock = parseTelegramLockEntry(readOwners()[effectiveKey]);
       const exactOwner = adoptCompatibleOwnedLock(effectiveKey, lock);
       return hasSameLockOwner(lock, exactOwner) ? lock?.leaderEpoch : undefined;
     },
     owns: (ctx) => {
       if (deliveryRevoked) return false;
       const effectiveKey = resolveEffectiveKey();
-      const lock = parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+      const lock = parseTelegramLockEntry(readOwners()[effectiveKey]);
       return hasSameLockOwner(
         lock,
         adoptCompatibleOwnedLock(effectiveKey, lock, ctx),
       );
     },
     commitIfOwned: (commit) =>
-      !deliveryRevoked && withLockTransaction(locksPath, (locks) => {
+      !deliveryRevoked && transactOwners((locks) => {
         const effectiveKey = resolveEffectiveKey();
         const lock = parseTelegramLockEntry(locks[effectiveKey]);
         const exactOwner =
@@ -1050,10 +1386,36 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
           return { result: false, changed: false };
         }
         commit();
-        return { result: true, changed: false };
+        // External-file commits may retain an independent effect; never acknowledge under a changed unified owner.
+        const current = !statePath || (!deliveryRevoked && hasSameLockOwner(parseTelegramLockEntry(readOwners()[effectiveKey]), ownedLock));
+        return { result: current, changed: false };
       }),
+    publishStateSectionIfOwned<T>(
+      section: "workspace" | "runtime",
+      mutate: (current: unknown, observed: Readonly<TelegramRuntimeStateProfile>) => TelegramRuntimeStateMutation<T>,
+      publication: TelegramOwnedStatePublicationOptions,
+    ): TelegramOwnedStatePublicationResult<T> {
+      if (section !== "workspace" && section !== "runtime")
+        throw new TelegramRuntimeStateError("invalid", "Telegram owner section publication is restricted to Workspace and runtime observations.");
+      if (!statePath) throw new TelegramRuntimeStateError("invalid", "Consolidated transport storage is not selected.");
+      const profile = resolveEffectiveKey(), expected = ownedLock ? { ...ownedLock } : undefined;
+      if (publication.expectedScope && (publication.expectedScope.path !== statePath || publication.expectedScope.profile !== profile))
+        return { committed: false };
+      if (deliveryRevoked || ownedLockKey !== profile || !expected || !publication.isCurrent()) return { committed: false };
+      const isCurrent = (): boolean => !deliveryRevoked && resolveEffectiveKey() === profile && ownedLockKey === profile &&
+        hasSameLockOwner(ownedLock, expected) && publication.isCurrent() &&
+        hasSameLockOwner(parseTelegramLockEntry(readOwners()[profile]), expected);
+      if (!isCurrent()) return { committed: false };
+      return mutateTelegramRuntimeStateSection<TelegramOwnedStatePublicationResult<T>>(statePath, profile, section, (current, observed) => {
+        assertTelegramStateTransport(observed.transport);
+        if (!hasSameLockOwner(parseTelegramLockEntry(observed.transport), expected))
+          return { value: current, result: { committed: false } as const };
+        const outcome = mutate(current, observed);
+        return { value: outcome.value, result: { committed: true, result: outcome.result } as const };
+      }, { ...publication, isCurrent });
+    },
     refresh: (ctx) =>
-      !deliveryRevoked && withLockTransaction(locksPath, (locks) => {
+      !deliveryRevoked && transactOwners((locks) => {
         const effectiveKey = resolveEffectiveKey();
         const lock = parseTelegramLockEntry(locks[effectiveKey]);
         const expectedOwner = adoptCompatibleOwnedLock(effectiveKey, lock, ctx);
@@ -1077,6 +1439,7 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
             ? { busSocketPath: options.busSocketPath }
             : {}),
           busSecret: options.busSecret ?? lock.busSecret,
+          ...(lock.journalPath ? { journalPath: lock.journalPath } : {}),
         };
         locks[effectiveKey] = refreshedLock;
         ownedLockKey = effectiveKey;
@@ -1106,7 +1469,7 @@ export function createTelegramDirectDeliveryOwnershipChecker<
   };
 }
 
-export interface TelegramLockedPollingStartOptions {
+interface TelegramLockedPollingStartOptions {
   force?: boolean;
   forceFreshLeaderThread?: boolean;
   requestedThreadName?: string;
@@ -1114,7 +1477,7 @@ export interface TelegramLockedPollingStartOptions {
   onAcquired?: () => Promise<void> | void;
 }
 
-export type TelegramLockedPollingStartResult =
+type TelegramLockedPollingStartResult =
   | { ok: true; message?: string; canTakeover?: false }
   | { ok: false; message: string; canTakeover?: boolean; owner?: string };
 
@@ -1128,6 +1491,8 @@ export interface TelegramLockedPollingRuntime<
   stop: () => Promise<string>;
   suspend: () => Promise<void>;
   isSuspended: () => boolean;
+  /** Fence one owned polling generation; suspension, restart, conflict or lock loss revokes it. */
+  captureTransportAuthority: (ctx: TContext) => (() => boolean) | undefined;
   onPersistentConflict: (ctx: TContext, count: number) => Promise<void>;
   onSessionStart: (_event: unknown, ctx: TContext) => Promise<void>;
   registerFollowerWithOwner?: (
@@ -1141,10 +1506,12 @@ export interface TelegramLockedPollingRuntime<
   stopFollowerRegistration?: () => void;
 }
 
-export interface TelegramLockedPollingRuntimeDeps<
+interface TelegramLockedPollingRuntimeDeps<
   TContext extends TelegramLockContext,
 > {
   lock: TelegramLockRuntime<TContext>;
+  /** Optimistically replaces a damaged shared runtime state before a non-election acquisition. */
+  resetDamagedState?: () => boolean;
   hasBotToken: () => boolean;
   getBotTokenDiagnostic?: () => string | undefined;
   canStartPolling?: (ctx: TContext) => boolean;
@@ -1343,6 +1710,12 @@ export function createTelegramLockedPollingRuntime<
         (deps.isContextCurrent?.(ctx) ?? true);
       if (ownershipStop) await ownershipStop;
       if (!isCurrent()) return cancelled;
+      if (!options.election && deps.resetDamagedState) {
+        try {
+          if (deps.resetDamagedState()) deps.recordRuntimeEvent?.("lock",
+            new Error("Damaged Telegram runtime state was reset; previous runtime continuity was discarded."), { phase: "state-reset" });
+        } catch (error) { deps.recordRuntimeEvent?.("lock", error, { phase: "state-reset" }); }
+      }
       let acquired = deps.lock.acquire(ctx, {
         force: options.force,
         expectedOwner:
@@ -1438,6 +1811,12 @@ export function createTelegramLockedPollingRuntime<
       return "Telegram bridge disconnected.";
     },
     suspend: suspendPolling,
+    captureTransportAuthority(ctx) {
+      const generation = pollingGeneration;
+      const current = () => generation === pollingGeneration && activeContext === ctx && !ownershipStop &&
+        (deps.isContextCurrent?.(ctx) ?? true) && deps.lock.owns(snapshotLockContext(ctx));
+      return current() ? current : undefined;
+    },
     isSuspended: () => suspendedGeneration === pollingGeneration &&
       suspensionsInFlight === 0 && startupsInFlight === 0 && !sessionAutoStartRun && !ownershipStop,
     onPersistentConflict: async (ctx, count) => {