@llblab/pi-telegram 0.21.1 → 0.22.1

package/lib/locks.ts

@@ -5,20 +5,42 @@
  */
 
 import {
+  chmodSync,
   existsSync,
+  lstatSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
+  readdirSync,
   renameSync,
+  rmSync,
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join } from "node:path";
 import { resolveTelegramLocksPath } from "./paths.ts";
 
 export const TELEGRAM_LOCK_KEY = "@llblab/pi-telegram";
 export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 5_000;
 const TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS = 5;
 const TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS = 25;
+const TELEGRAM_LOCK_TRANSACTION_ATTEMPTS = 80;
+const TELEGRAM_LOCK_TRANSACTION_RETRY_DELAY_MS = 25;
+const TELEGRAM_LOCK_RUNTIME_GENERATION_KEY =
+  "__piTelegramLockRuntimeGeneration__";
+
+function allocateTelegramLockRuntimeGeneration(): number {
+  const globals = globalThis as Record<string, unknown>;
+  const previous = globals[TELEGRAM_LOCK_RUNTIME_GENERATION_KEY];
+  const previousGeneration =
+    typeof previous === "number" && Number.isSafeInteger(previous)
+      ? previous
+      : 0;
+  const generation = Math.max(Date.now(), previousGeneration + 1);
+  globals[TELEGRAM_LOCK_RUNTIME_GENERATION_KEY] = generation;
+  return generation;
+}
 
 function getLocksPath(): string {
   return resolveTelegramLocksPath();
@@ -51,7 +73,8 @@ export interface TelegramLockEntry {
   cwd?: string;
   instanceId?: string;
   heartbeatMs?: number;
-  leaderEpoch?: number;
+  leaderEpoch?: number | string;
+  runtimeGeneration?: number;
   busSocketPath?: string;
   busSecret?: string;
 }
@@ -68,6 +91,8 @@ export type TelegramLockState =
 
 export interface TelegramLockAcquireOptions {
   force?: boolean;
+  expectedOwner?: TelegramLockEntry;
+  election?: boolean;
 }
 
 export type TelegramLockAcquireResult =
@@ -82,7 +107,9 @@ export interface TelegramLockRuntime<TContext extends TelegramLockContext> {
   release: () => TelegramLockState;
   getState: () => TelegramLockState;
   getStatusLabel: () => string;
+  getOwnedLeaderEpoch: () => number | string | undefined;
   owns: (ctx?: TelegramLockContext) => boolean;
+  commitIfOwned: (commit: () => void) => boolean;
   refresh: (ctx?: TelegramLockContext) => boolean;
 }
 
@@ -107,6 +134,8 @@ export interface TelegramLockRuntimeOptions {
   busSocketPath?: string;
   busSecret?: string;
   getNowMs?: () => number;
+  mintLeaderEpoch?: () => number | string;
+  runtimeGeneration?: number;
   staleHeartbeatMs?: number;
 }
 
@@ -122,6 +151,21 @@ export function readLocks(path = getLocksPath()): Record<string, unknown> {
   }
 }
 
+function readLocksForTransaction(path: string): Record<string, unknown> {
+  let source: string;
+  try {
+    source = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as { code?: unknown })?.code === "ENOENT") return {};
+    throw error;
+  }
+  const value: unknown = JSON.parse(source);
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid Telegram lock registry: ${path}`);
+  }
+  return value as Record<string, unknown>;
+}
+
 function isRetryableLockWriteError(error: unknown): boolean {
   const code = (error as { code?: unknown })?.code;
   return code === "EPERM" || code === "EBUSY" || code === "EACCES";
@@ -132,11 +176,497 @@ function sleepSync(ms: number): void {
   Atomics.wait(new Int32Array(buffer), 0, 0, ms);
 }
 
+interface TelegramLockTransactionOwner {
+  pid: number;
+  acquiredAtMs: number;
+  generation: string;
+}
+
+const TELEGRAM_TRANSACTION_OWNER_PATTERN =
+  /^owner\.([A-Za-z0-9-]+)\.json$/u;
+
+function getLockTransactionOwnerFile(generation: string): string {
+  return `owner.${generation}.json`;
+}
+
+function getLockTransactionOwnerPath(path: string): string {
+  const stat = lstatSync(path);
+  if (stat.isDirectory()) {
+    const entries = readdirSync(path);
+    if (
+      entries.length === 1 &&
+      (TELEGRAM_TRANSACTION_OWNER_PATTERN.test(entries[0]) ||
+        TELEGRAM_TRANSACTION_RECLAIM_PATTERN.test(entries[0]))
+    ) {
+      return join(path, entries[0]);
+    }
+    throw new Error(`Unverifiable Telegram lock transaction guard: ${path}`);
+  }
+  if (stat.isFile()) return path;
+  throw new Error(`Unsupported Telegram lock transaction guard: ${path}`);
+}
+
+function readLockTransactionOwner(
+  path: string,
+): TelegramLockTransactionOwner | undefined {
+  try {
+    const value = JSON.parse(
+      readFileSync(getLockTransactionOwnerPath(path), "utf8"),
+    ) as Record<string, unknown>;
+    if (
+      typeof value.pid !== "number" ||
+      typeof value.acquiredAtMs !== "number" ||
+      typeof value.generation !== "string"
+    ) {
+      return undefined;
+    }
+    const ownerMatch = TELEGRAM_TRANSACTION_OWNER_PATTERN.exec(
+      basename(getLockTransactionOwnerPath(path)),
+    );
+    if (ownerMatch && ownerMatch[1] !== value.generation) return undefined;
+    return {
+      pid: value.pid,
+      acquiredAtMs: value.acquiredAtMs,
+      generation: value.generation,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function createLockTransactionContentionError(path: string): Error {
+  return Object.assign(
+    new Error(`Telegram lock transaction guard already exists: ${path}`),
+    { code: "EEXIST" },
+  );
+}
+
+function isLockTransactionContentionError(
+  error: unknown,
+  path: string,
+): boolean {
+  const code = (error as { code?: unknown })?.code;
+  if (
+    code === "EEXIST" ||
+    code === "ENOTEMPTY" ||
+    code === "ENOTDIR" ||
+    code === "EISDIR"
+  ) {
+    return true;
+  }
+  return existsSync(path) && (code === "EPERM" || code === "EACCES");
+}
+
+function removeLockTransactionGuard(path: string): void {
+  rmSync(path, { recursive: true, force: true });
+}
+
+function createLockTransactionGuard(
+  path: string,
+): TelegramLockTransactionOwner {
+  const owner: TelegramLockTransactionOwner = {
+    pid: process.pid,
+    acquiredAtMs: Date.now(),
+    generation: randomUUID(),
+  };
+  const stagedPath = mkdtempSync(`${path}.staged.`);
+  try {
+    chmodSync(stagedPath, 0o700);
+    writeFileSync(
+      join(stagedPath, getLockTransactionOwnerFile(owner.generation)),
+      `${JSON.stringify(owner)}\n`,
+      { encoding: "utf8", flag: "wx", mode: 0o600 },
+    );
+    if (existsSync(path)) throw createLockTransactionContentionError(path);
+    renameSync(stagedPath, path);
+    return owner;
+  } finally {
+    try {
+      removeLockTransactionGuard(stagedPath);
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+function releaseLockTransactionGuard(
+  path: string,
+  owner: TelegramLockTransactionOwner,
+): void {
+  const current = readLockTransactionOwner(path);
+  if (!current) {
+    if (!existsSync(path)) return;
+    throw new Error(`Cannot verify Telegram lock transaction guard: ${path}`);
+  }
+  if (
+    current.pid !== owner.pid ||
+    current.generation !== owner.generation ||
+    current.acquiredAtMs !== owner.acquiredAtMs
+  ) {
+    throw new Error(
+      `Telegram lock transaction guard changed ownership: ${path}`,
+    );
+  }
+  const releasedPath = `${path}.released.${randomUUID()}`;
+  for (
+    let attempt = 0;
+    attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS;
+    attempt += 1
+  ) {
+    try {
+      renameSync(path, releasedPath);
+      try {
+        removeLockTransactionGuard(releasedPath);
+      } catch {
+        /* released debris cannot retain transaction authority */
+      }
+      return;
+    } catch (error) {
+      if ((error as { code?: unknown })?.code === "ENOENT") return;
+      if (
+        !isRetryableLockWriteError(error) ||
+        attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1
+      ) {
+        throw error;
+      }
+      sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
+    }
+  }
+}
+
+function isAbandonedLockTransaction(path: string): boolean {
+  const owner = readLockTransactionOwner(path);
+  return owner ? !isProcessAlive(owner.pid) : false;
+}
+
+const TELEGRAM_TRANSACTION_RECLAIM_PATTERN =
+  /^owner\.reclaim\.(\d+)\.([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.json$/u;
+const TELEGRAM_ACTIVE_TRANSACTION_RECLAIMS = Symbol.for(
+  "@llblab/pi-telegram/active-transaction-reclaims",
+);
+
+type TelegramTransactionGlobal = typeof globalThis & {
+  [TELEGRAM_ACTIVE_TRANSACTION_RECLAIMS]?: Set<string>;
+};
+
+export interface TelegramFileTransactionOptions {
+  recoveryRename?: typeof renameSync;
+}
+
+function getActiveTransactionReclaims(): Set<string> {
+  const root = globalThis as TelegramTransactionGlobal;
+  return (root[TELEGRAM_ACTIVE_TRANSACTION_RECLAIMS] ??= new Set());
+}
+
+function reclaimAbandonedDirectoryGuard(
+  path: string,
+  options: TelegramFileTransactionOptions = {},
+): boolean {
+  try {
+    if (!lstatSync(path).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  const entries = readdirSync(path);
+  if (entries.length !== 1) return false;
+  const entry = entries[0];
+  let observedPid: number;
+  let observedReclaimGeneration: string | undefined;
+  if (TELEGRAM_TRANSACTION_OWNER_PATTERN.test(entry)) {
+    const owner = readLockTransactionOwner(path);
+    if (!owner) return false;
+    observedPid = owner.pid;
+  } else {
+    const match = TELEGRAM_TRANSACTION_RECLAIM_PATTERN.exec(entry);
+    if (!match) return false;
+    observedPid = Number.parseInt(match[1], 10);
+    observedReclaimGeneration = match[2];
+  }
+  const activeReclaims = getActiveTransactionReclaims();
+  if (
+    observedPid === process.pid &&
+    observedReclaimGeneration !== undefined
+  ) {
+    if (activeReclaims.has(observedReclaimGeneration)) return false;
+  } else if (isProcessAlive(observedPid)) {
+    return false;
+  }
+
+  const renameRecovery = options.recoveryRename ?? renameSync;
+  const sourcePath = join(path, entry);
+  const reclaimGeneration = randomUUID();
+  const reclaimPath = join(
+    path,
+    `owner.reclaim.${process.pid}.${reclaimGeneration}.json`,
+  );
+  try {
+    // Claim inside the still-occupied guard before making its stable path free.
+    renameRecovery(sourcePath, reclaimPath);
+  } catch (error) {
+    if ((error as { code?: unknown })?.code === "ENOENT") return false;
+    throw error;
+  }
+
+  const renameWithRetry = (fromPath: string, toPath: string): boolean => {
+    for (
+      let attempt = 0;
+      attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS;
+      attempt += 1
+    ) {
+      try {
+        renameRecovery(fromPath, toPath);
+        return true;
+      } catch (error) {
+        if ((error as { code?: unknown })?.code === "ENOENT") return false;
+        if (
+          !isRetryableLockWriteError(error) ||
+          attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1
+        ) {
+          throw error;
+        }
+        sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
+      }
+    }
+    return false;
+  };
+
+  activeReclaims.add(reclaimGeneration);
+  const stalePath = `${path}.stale.${process.pid}.${randomUUID()}`;
+  try {
+    try {
+      if (!renameWithRetry(path, stalePath)) return false;
+    } catch (renameError) {
+      try {
+        if (!renameWithRetry(reclaimPath, sourcePath)) throw renameError;
+      } catch (rollbackError) {
+        throw new AggregateError(
+          [renameError, rollbackError],
+          `Failed to reclaim or restore Telegram lock transaction guard: ${path}`,
+        );
+      }
+      throw renameError;
+    }
+  } finally {
+    activeReclaims.delete(reclaimGeneration);
+  }
+  try {
+    removeLockTransactionGuard(stalePath);
+  } catch {
+    /* stale debris cannot retain transaction authority */
+  }
+  return true;
+}
+
+function acquireRecoverableDirectoryGuard(
+  path: string,
+  options: TelegramFileTransactionOptions = {},
+): TelegramLockTransactionOwner | undefined {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return createLockTransactionGuard(path);
+    } catch (error) {
+      if (!isLockTransactionContentionError(error, path)) throw error;
+      if (!reclaimAbandonedDirectoryGuard(path, options)) return undefined;
+    }
+  }
+  return undefined;
+}
+
+function removeAbandonedLegacyRecoveryGuard(
+  path: string,
+  options: TelegramFileTransactionOptions = {},
+): boolean {
+  try {
+    if (!lstatSync(path).isFile() || !isAbandonedLockTransaction(path))
+      return false;
+  } catch {
+    return false;
+  }
+  const migrationGuardPath = `${path}.migration`;
+  const migrationOwner = acquireRecoverableDirectoryGuard(
+    migrationGuardPath,
+    options,
+  );
+  if (!migrationOwner) return false;
+  try {
+    try {
+      if (!lstatSync(path).isFile() || !isAbandonedLockTransaction(path))
+        return false;
+    } catch {
+      return false;
+    }
+    const stalePath = `${path}.stale.${process.pid}.${randomUUID()}`;
+    try {
+      renameSync(path, stalePath);
+    } catch (error) {
+      if ((error as { code?: unknown })?.code === "ENOENT") return false;
+      throw error;
+    }
+    try {
+      removeLockTransactionGuard(stalePath);
+    } catch {
+      /* stale debris cannot retain transaction authority */
+    }
+    return true;
+  } finally {
+    releaseLockTransactionGuard(migrationGuardPath, migrationOwner);
+  }
+}
+
+function acquireLegacyRecoveryGuard(
+  path: string,
+  options: TelegramFileTransactionOptions = {},
+): TelegramLockTransactionOwner | undefined {
+  let owner = acquireRecoverableDirectoryGuard(path, options);
+  if (owner) return owner;
+  if (!removeAbandonedLegacyRecoveryGuard(path, options)) return undefined;
+  owner = acquireRecoverableDirectoryGuard(path, options);
+  return owner;
+}
+
+function createRecoveredLockTransactionGuard(
+  path: string,
+): TelegramLockTransactionOwner | undefined {
+  try {
+    return createLockTransactionGuard(path);
+  } catch (error) {
+    if (isLockTransactionContentionError(error, path)) return undefined;
+    throw error;
+  }
+}
+
+function recoverAbandonedLockTransaction(
+  path: string,
+  options: TelegramFileTransactionOptions = {},
+): TelegramLockTransactionOwner | undefined {
+  if (!isAbandonedLockTransaction(path)) return undefined;
+  let isDirectory: boolean;
+  try {
+    isDirectory = lstatSync(path).isDirectory();
+  } catch {
+    return undefined;
+  }
+  if (isDirectory) {
+    if (!reclaimAbandonedDirectoryGuard(path, options)) return undefined;
+    const recoveredOwner = createRecoveredLockTransactionGuard(path);
+    try {
+      reclaimAbandonedDirectoryGuard(`${path}.recovery`, options);
+      return recoveredOwner;
+    } catch (error) {
+      if (recoveredOwner) {
+        try {
+          releaseLockTransactionGuard(path, recoveredOwner);
+        } catch {
+          /* preserve the recovery cleanup failure */
+        }
+      }
+      throw error;
+    }
+  }
+
+  const recoveryGuardPath = `${path}.recovery`;
+  const recoveryOwner = acquireLegacyRecoveryGuard(
+    recoveryGuardPath,
+    options,
+  );
+  if (!recoveryOwner) return undefined;
+  let recoveredOwner: TelegramLockTransactionOwner | undefined;
+  try {
+    if (!isAbandonedLockTransaction(path)) return undefined;
+    const stalePath = `${path}.stale.${process.pid}.${randomUUID()}`;
+    try {
+      renameSync(path, stalePath);
+    } catch (error) {
+      if ((error as { code?: unknown })?.code === "ENOENT") return undefined;
+      throw error;
+    }
+    try {
+      removeLockTransactionGuard(stalePath);
+    } catch {
+      /* stale debris cannot retain transaction authority */
+    }
+    recoveredOwner = createRecoveredLockTransactionGuard(path);
+    return recoveredOwner;
+  } finally {
+    try {
+      releaseLockTransactionGuard(recoveryGuardPath, recoveryOwner);
+    } catch (error) {
+      if (recoveredOwner) {
+        try {
+          releaseLockTransactionGuard(path, recoveredOwner);
+        } catch {
+          /* preserve the recovery cleanup failure */
+        }
+      }
+      throw error;
+    }
+  }
+}
+
+function acquireLockTransaction(
+  path: string,
+  options: TelegramFileTransactionOptions = {},
+): TelegramLockTransactionOwner {
+  mkdirSync(dirname(path), { recursive: true });
+  for (
+    let attempt = 0;
+    attempt < TELEGRAM_LOCK_TRANSACTION_ATTEMPTS;
+    attempt += 1
+  ) {
+    try {
+      return createLockTransactionGuard(path);
+    } catch (error) {
+      if (!isLockTransactionContentionError(error, path)) throw error;
+      const recoveredOwner = recoverAbandonedLockTransaction(path, options);
+      if (recoveredOwner !== undefined) return recoveredOwner;
+      if (attempt === TELEGRAM_LOCK_TRANSACTION_ATTEMPTS - 1) {
+        throw new Error(
+          `Timed out acquiring Telegram lock transaction: ${path}`,
+        );
+      }
+      sleepSync(TELEGRAM_LOCK_TRANSACTION_RETRY_DELAY_MS);
+    }
+  }
+  throw new Error(`Failed to acquire Telegram lock transaction: ${path}`);
+}
+
+export function withTelegramFileTransaction<T>(
+  transactionPath: string,
+  operation: () => T,
+  options: TelegramFileTransactionOptions = {},
+): T {
+  const owner = acquireLockTransaction(transactionPath, options);
+  try {
+    return operation();
+  } finally {
+    releaseLockTransactionGuard(transactionPath, owner);
+  }
+}
+
+function withLockTransaction<T>(
+  locksPath: string,
+  mutate: (locks: Record<string, unknown>) => {
+    result: T;
+    changed: boolean;
+  },
+): T {
+  return withTelegramFileTransaction(`${locksPath}.transaction`, () => {
+    const locks = readLocksForTransaction(locksPath);
+    const outcome = mutate(locks);
+    if (outcome.changed) writeLocks(locksPath, locks);
+    return outcome.result;
+  });
+}
+
 export function writeLocks(path: string, locks: Record<string, unknown>): void {
   mkdirSync(dirname(path), { recursive: true });
   const payload = `${JSON.stringify(locks, null, 2)}\n`;
   let lastError: unknown;
-  for (let attempt = 0; attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS; attempt += 1) {
+  for (
+    let attempt = 0;
+    attempt < TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS;
+    attempt += 1
+  ) {
     const tempPath = `${path}.${process.pid}.${Date.now()}.${attempt}.tmp`;
     try {
       writeFileSync(tempPath, payload, {
@@ -179,7 +709,14 @@ export function parseTelegramLockEntry(
     heartbeatMs:
       typeof record.heartbeatMs === "number" ? record.heartbeatMs : undefined,
     leaderEpoch:
-      typeof record.leaderEpoch === "number" ? record.leaderEpoch : undefined,
+      typeof record.leaderEpoch === "number" ||
+      typeof record.leaderEpoch === "string"
+        ? record.leaderEpoch
+        : undefined,
+    runtimeGeneration:
+      typeof record.runtimeGeneration === "number"
+        ? record.runtimeGeneration
+        : undefined,
     busSocketPath:
       typeof record.busSocketPath === "string"
         ? record.busSocketPath
@@ -243,6 +780,40 @@ function ownsLockContext(
   return !lock.cwd || !ctx || lock.cwd === ctx.cwd;
 }
 
+function hasSameLockOwner(
+  current: TelegramLockEntry | undefined,
+  expected: TelegramLockEntry | undefined,
+): boolean {
+  if (!current || !expected) return false;
+  return (
+    current.pid === expected.pid &&
+    current.cwd === expected.cwd &&
+    current.instanceId === expected.instanceId &&
+    current.leaderEpoch === expected.leaderEpoch &&
+    current.runtimeGeneration === expected.runtimeGeneration
+  );
+}
+
+function canSupersedeSameProcessOwner(
+  current: TelegramLockEntry,
+  pid: number,
+  ctx: TelegramLockContext,
+  instanceId: string | undefined,
+  runtimeGeneration: number,
+): boolean {
+  if (
+    current.pid !== pid ||
+    (current.cwd !== undefined && current.cwd !== ctx.cwd) ||
+    !instanceId
+  ) {
+    return false;
+  }
+  return (
+    current.runtimeGeneration === undefined ||
+    runtimeGeneration > current.runtimeGeneration
+  );
+}
+
 function createLockEntry(
   pid: number,
   ctx: TelegramLockContext,
@@ -251,6 +822,8 @@ function createLockEntry(
     busSocketPath?: string;
     busSecret?: string;
     getNowMs?: () => number;
+    mintLeaderEpoch?: () => number | string;
+    runtimeGeneration?: number;
   },
 ): TelegramLockEntry {
   const lock: TelegramLockEntry = { pid, cwd: ctx.cwd };
@@ -258,7 +831,8 @@ function createLockEntry(
     const nowMs = options.getNowMs?.();
     lock.instanceId = options.instanceId;
     lock.heartbeatMs = nowMs;
-    lock.leaderEpoch = nowMs;
+    lock.leaderEpoch = options.mintLeaderEpoch?.() ?? randomUUID();
+    lock.runtimeGeneration = options.runtimeGeneration;
   }
   if (options.busSocketPath) lock.busSocketPath = options.busSocketPath;
   if (options.busSecret) lock.busSecret = options.busSecret;
@@ -286,6 +860,10 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
   const pid = options.pid ?? process.pid;
   const isAlive = options.isProcessAlive ?? isProcessAlive;
   const getNowMs = options.getNowMs ?? Date.now;
+  const runtimeGeneration =
+    options.runtimeGeneration ?? allocateTelegramLockRuntimeGeneration();
+  let ownedLockKey: string | undefined;
+  let ownedLock: TelegramLockEntry | undefined;
   const stateOptions = () => ({
     nowMs: getNowMs(),
     staleHeartbeatMs: options.staleHeartbeatMs,
@@ -298,56 +876,196 @@ export function createTelegramLockRuntime<TContext extends TelegramLockContext>(
     const effectiveKey = resolveEffectiveKey();
     return parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
   };
-  const writeLock = (lock: TelegramLockEntry) => {
-    const effectiveKey = resolveEffectiveKey();
-    const locks = readLocks(locksPath);
-    locks[effectiveKey] = lock;
-    writeLocks(locksPath, locks);
+  const adoptCompatibleOwnedLock = (
+    effectiveKey: string,
+    lock: TelegramLockEntry | undefined,
+    ctx?: TelegramLockContext,
+  ): TelegramLockEntry | undefined => {
+    if (ownedLock) {
+      return ownedLockKey === effectiveKey ? ownedLock : undefined;
+    }
+    if (!ownsLockContext(lock, pid, ctx)) return undefined;
+    if (
+      (lock?.instanceId !== undefined &&
+        lock.instanceId !== options.instanceId) ||
+      (lock?.runtimeGeneration !== undefined &&
+        lock.runtimeGeneration !== runtimeGeneration)
+    ) {
+      return undefined;
+    }
+    ownedLockKey = effectiveKey;
+    ownedLock = lock;
+    return ownedLock;
   };
   return {
-    acquire: (ctx, acquireOptions = {}) => {
-      const state = getLockState(readLock(), pid, isAlive, stateOptions());
-      if (state.kind === "active-elsewhere" && !acquireOptions.force)
-        return { ok: false, lock: state.lock };
-      const lock = createLockEntry(pid, ctx, {
-        instanceId: options.instanceId,
-        busSocketPath: options.busSocketPath,
-        busSecret: options.busSecret,
-        getNowMs,
-      });
-      writeLock(lock);
-      return { ok: true, lock, replacedStale: state.kind === "stale" };
-    },
-    release: () => {
-      const state = getLockState(readLock(), pid, isAlive, stateOptions());
-      if (state.kind === "active-here" || state.kind === "stale") {
-        const locks = readLocks(locksPath);
-        delete locks[resolveEffectiveKey()];
-        writeLocks(locksPath, locks);
-      }
-      return state;
-    },
+    acquire: (ctx, acquireOptions = {}) =>
+      withLockTransaction<TelegramLockAcquireResult>(locksPath, (locks) => {
+        const effectiveKey = resolveEffectiveKey();
+        const current = parseTelegramLockEntry(locks[effectiveKey]);
+        const state = getLockState(current, pid, isAlive, stateOptions());
+        const expectedOwned = adoptCompatibleOwnedLock(
+          effectiveKey,
+          current,
+          ctx,
+        );
+        if (
+          state.kind === "active-here" &&
+          hasSameLockOwner(current, expectedOwned)
+        ) {
+          return {
+            result: {
+              ok: true,
+              lock: current!,
+              replacedStale: false,
+            } as const,
+            changed: false,
+          };
+        }
+        if (acquireOptions.election && current) {
+          if (
+            state.kind !== "stale" ||
+            !hasSameLockOwner(current, acquireOptions.expectedOwner)
+          ) {
+            return {
+              result: { ok: false, lock: current } as const,
+              changed: false,
+            };
+          }
+        }
+        const expectedReplacementMatches = hasSameLockOwner(
+          state.kind === "active-here" || state.kind === "active-elsewhere"
+            ? state.lock
+            : undefined,
+          acquireOptions.expectedOwner,
+        );
+        const canReplaceCurrent =
+          state.kind === "active-elsewhere" ||
+          (state.kind === "active-here" &&
+            canSupersedeSameProcessOwner(
+              state.lock,
+              pid,
+              ctx,
+              options.instanceId,
+              runtimeGeneration,
+            ));
+        if (
+          !acquireOptions.election &&
+          (state.kind === "active-here" || state.kind === "active-elsewhere") &&
+          (!acquireOptions.force ||
+            !expectedReplacementMatches ||
+            !canReplaceCurrent)
+        ) {
+          return {
+            result: { ok: false, lock: state.lock } as const,
+            changed: false,
+          };
+        }
+        const lock = createLockEntry(pid, ctx, {
+          instanceId: options.instanceId,
+          busSocketPath: options.busSocketPath,
+          busSecret: options.busSecret,
+          getNowMs,
+          mintLeaderEpoch: options.mintLeaderEpoch,
+          runtimeGeneration,
+        });
+        locks[effectiveKey] = lock;
+        ownedLockKey = effectiveKey;
+        ownedLock = lock;
+        return {
+          result: {
+            ok: true,
+            lock,
+            replacedStale: state.kind === "stale",
+          } as const,
+          changed: true,
+        };
+      }),
+    release: () =>
+      withLockTransaction(locksPath, (locks) => {
+        const effectiveKey = resolveEffectiveKey();
+        const state = getLockState(
+          parseTelegramLockEntry(locks[effectiveKey]),
+          pid,
+          isAlive,
+          stateOptions(),
+        );
+        const changed =
+          ownedLockKey === effectiveKey &&
+          hasSameLockOwner(
+            parseTelegramLockEntry(locks[effectiveKey]),
+            ownedLock,
+          );
+        if (changed) {
+          delete locks[effectiveKey];
+          ownedLockKey = undefined;
+          ownedLock = undefined;
+        }
+        return { result: state, changed };
+      }),
     getState: () => getLockState(readLock(), pid, isAlive, stateOptions()),
     getStatusLabel: () =>
       formatLockState(getLockState(readLock(), pid, isAlive, stateOptions())),
-    owns: (ctx) => ownsLockContext(readLock(), pid, ctx),
-    refresh: (ctx) => {
-      const lock = readLock();
-      if (!lock || !ownsLockContext(lock, pid, ctx)) return false;
-      if (!options.instanceId) return true;
-      writeLock({
-        pid: lock.pid,
-        ...(lock.cwd ? { cwd: lock.cwd } : {}),
-        instanceId: options.instanceId,
-        heartbeatMs: getNowMs(),
-        leaderEpoch: lock.leaderEpoch,
-        ...(options.busSocketPath
-          ? { busSocketPath: options.busSocketPath }
-          : {}),
-        busSecret: options.busSecret ?? lock.busSecret,
-      });
-      return true;
+    getOwnedLeaderEpoch: () => {
+      const effectiveKey = resolveEffectiveKey();
+      const lock = parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+      const exactOwner = adoptCompatibleOwnedLock(effectiveKey, lock);
+      return hasSameLockOwner(lock, exactOwner) ? lock?.leaderEpoch : undefined;
     },
+    owns: (ctx) => {
+      const effectiveKey = resolveEffectiveKey();
+      const lock = parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+      return hasSameLockOwner(
+        lock,
+        adoptCompatibleOwnedLock(effectiveKey, lock, ctx),
+      );
+    },
+    commitIfOwned: (commit) =>
+      withLockTransaction(locksPath, (locks) => {
+        const effectiveKey = resolveEffectiveKey();
+        const lock = parseTelegramLockEntry(locks[effectiveKey]);
+        const exactOwner =
+          ownedLockKey === effectiveKey && hasSameLockOwner(lock, ownedLock);
+        if (!exactOwner) {
+          if (ownedLockKey === effectiveKey) {
+            ownedLockKey = undefined;
+            ownedLock = undefined;
+          }
+          return { result: false, changed: false };
+        }
+        commit();
+        return { result: true, changed: false };
+      }),
+    refresh: (ctx) =>
+      withLockTransaction(locksPath, (locks) => {
+        const effectiveKey = resolveEffectiveKey();
+        const lock = parseTelegramLockEntry(locks[effectiveKey]);
+        const expectedOwner = adoptCompatibleOwnedLock(effectiveKey, lock, ctx);
+        if (!lock || !hasSameLockOwner(lock, expectedOwner)) {
+          if (ownedLockKey === effectiveKey) {
+            ownedLockKey = undefined;
+            ownedLock = undefined;
+          }
+          return { result: false, changed: false };
+        }
+        if (!options.instanceId) return { result: true, changed: false };
+        const refreshedLock: TelegramLockEntry = {
+          pid: lock.pid,
+          ...(lock.cwd ? { cwd: lock.cwd } : {}),
+          instanceId: options.instanceId,
+          heartbeatMs: getNowMs(),
+          leaderEpoch:
+            lock.leaderEpoch ?? options.mintLeaderEpoch?.() ?? randomUUID(),
+          runtimeGeneration: lock.runtimeGeneration ?? runtimeGeneration,
+          ...(options.busSocketPath
+            ? { busSocketPath: options.busSocketPath }
+            : {}),
+          busSecret: options.busSecret ?? lock.busSecret,
+        };
+        locks[effectiveKey] = refreshedLock;
+        ownedLockKey = effectiveKey;
+        ownedLock = refreshedLock;
+        return { result: true, changed: true };
+      }),
   };
 }
 
@@ -374,6 +1092,8 @@ export function createTelegramDirectDeliveryOwnershipChecker<
 export interface TelegramLockedPollingStartOptions {
   force?: boolean;
   forceFreshLeaderThread?: boolean;
+  election?: { expectedOwner?: TelegramLockEntry };
+  onAcquired?: () => Promise<void> | void;
 }
 
 export type TelegramLockedPollingStartResult =
@@ -434,6 +1154,7 @@ export function createTelegramLockedPollingRuntime<
 ): TelegramLockedPollingRuntime<TContext> {
   let ownershipInterval: ReturnType<typeof setInterval> | undefined;
   let ownershipStop: Promise<void> | undefined;
+  let takeoverCandidate: TelegramLockEntry | undefined;
   let sessionAutoStartRun: Promise<void> | undefined;
   let sessionAutoStartGeneration = 0;
   const ownershipCheckMs = deps.ownershipCheckMs ?? 1000;
@@ -480,6 +1201,36 @@ export function createTelegramLockedPollingRuntime<
     }, ownershipCheckMs);
     ownershipInterval.unref?.();
   };
+  const runOwnedPollingStart = async (
+    ctx: TContext,
+    options: TelegramLockedPollingStartOptions,
+  ): Promise<boolean> => {
+    startOwnershipWatcher(ctx);
+    try {
+      if (!deps.lock.refresh(snapshotLockContext(ctx))) {
+        stopOwnershipWatcher();
+        return false;
+      }
+      await options.onAcquired?.();
+      await deps.startPolling(ctx, options);
+    } catch (error) {
+      stopOwnershipWatcher();
+      try {
+        await deps.stopPolling();
+      } catch (stopError) {
+        deps.recordRuntimeEvent?.("lock", stopError, {
+          phase: "startup-rollback",
+        });
+      }
+      deps.lock.release();
+      throw error;
+    }
+    if (deps.lock.owns(ctx)) return true;
+    stopOwnershipWatcher();
+    if (ownershipStop) await ownershipStop;
+    await deps.stopPolling();
+    return false;
+  };
   const canStartPolling = (ctx: TContext): boolean =>
     deps.canStartPolling?.(ctx) ?? true;
   const formatStartBlockedMessage = (ctx: TContext): string =>
@@ -493,8 +1244,35 @@ export function createTelegramLockedPollingRuntime<
       if (!canStartPolling(ctx)) {
         return { ok: false, message: formatStartBlockedMessage(ctx) };
       }
-      const acquired = deps.lock.acquire(ctx, options);
+      let acquired = deps.lock.acquire(ctx, {
+        force: options.force,
+        expectedOwner:
+          options.election?.expectedOwner ??
+          (options.force ? takeoverCandidate : undefined),
+        election: options.election !== undefined,
+      });
+      if (!acquired.ok && !options.election) {
+        const currentState = deps.lock.getState();
+        if (
+          currentState.kind === "active-here" &&
+          hasSameLockOwner(currentState.lock, acquired.lock)
+        ) {
+          acquired = deps.lock.acquire(ctx, {
+            force: true,
+            expectedOwner: acquired.lock,
+          });
+        }
+      }
       if (!acquired.ok) {
+        takeoverCandidate = acquired.lock;
+        if (options.election) {
+          return {
+            ok: false,
+            canTakeover: false,
+            owner: formatTelegramLockEntry(acquired.lock),
+            message: "Telegram leadership election lost to another live owner.",
+          };
+        }
         if (deps.registerFollowerWithOwner) {
           let failureMessage: string | undefined;
           try {
@@ -532,8 +1310,14 @@ export function createTelegramLockedPollingRuntime<
           message: `Telegram bridge is active in another Pi instance (${owner}).`,
         };
       }
-      await deps.startPolling(ctx, options);
-      startOwnershipWatcher(ctx);
+      takeoverCandidate = undefined;
+      if (!(await runOwnedPollingStart(ctx, options))) {
+        return {
+          ok: false,
+          canTakeover: false,
+          message: "Telegram leadership changed during polling startup.",
+        };
+      }
       deps.updateStatus(ctx);
       const staleSuffix = acquired.replacedStale ? " Replaced stale lock." : "";
       return { ok: true, message: `Telegram bridge connected.${staleSuffix}` };
@@ -557,7 +1341,16 @@ export function createTelegramLockedPollingRuntime<
       const state = ownsCurrentLock ? undefined : deps.lock.getState();
       const canResumeStaleSameCwd =
         state?.kind === "stale" && state.lock.cwd === ctx.cwd;
-      if (!ownsCurrentLock && !canResumeStaleSameCwd) return;
+      const canHandoffSameProcess =
+        state?.kind === "active-here" &&
+        (!state.lock.cwd || state.lock.cwd === ctx.cwd);
+      if (
+        !ownsCurrentLock &&
+        !canResumeStaleSameCwd &&
+        !canHandoffSameProcess
+      ) {
+        return;
+      }
       sessionAutoStartGeneration += 1;
       const generation = sessionAutoStartGeneration;
       const startedAtMs = Date.now();
@@ -567,14 +1360,18 @@ export function createTelegramLockedPollingRuntime<
       const run = (async () => {
         await new Promise((resolve) => setTimeout(resolve, 0));
         if (generation !== sessionAutoStartGeneration) return;
-        if (canResumeStaleSameCwd) {
-          const acquired = deps.lock.acquire(ctx);
+        if (canResumeStaleSameCwd || canHandoffSameProcess) {
+          const acquired = deps.lock.acquire(
+            ctx,
+            canHandoffSameProcess
+              ? { force: true, expectedOwner: state?.lock }
+              : undefined,
+          );
           if (!acquired.ok) return;
         }
         if (generation !== sessionAutoStartGeneration) return;
-        await deps.startPolling(ctx);
+        if (!(await runOwnedPollingStart(ctx, {}))) return;
         if (generation !== sessionAutoStartGeneration) return;
-        startOwnershipWatcher(ctx);
         deps.updateStatus(ctx);
         deps.recordRuntimeEvent?.("lock", "Telegram auto-start completed", {
           phase: "auto-start-complete",