@llblab/pi-telegram 0.45.11 → 0.47.0

package/dist/lib/locks.js

@@ -0,0 +1,1208 @@
+/**
+ * Telegram singleton lock helpers
+ * Zones: telegram ownership, filesystem, transport authority
+ * Owns extension-local owners.json access and Telegram bridge ownership semantics
+ */
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+import { resolveTelegramOwnersPath } from "./paths.js";
+export const TELEGRAM_LOCK_KEY = "default";
+export const TELEGRAM_BUS_LEADER_STALE_HEARTBEAT_MS = 8_000;
+export const TELEGRAM_OWNERSHIP_CHECK_MS = 1_000;
+export const TELEGRAM_OWNERSHIP_REFRESH_MS = 2_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() {
+    const globals = globalThis;
+    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 getOwnersPath() {
+    return resolveTelegramOwnersPath();
+}
+/**
+ * Resolve the extension-local owner slot for the active Telegram profile.
+ * Default profile → default
+ * Named profile → the validated profile name
+ */
+export function resolveTelegramLockKey(activeProfile) {
+    return activeProfile || TELEGRAM_LOCK_KEY;
+}
+export function createTelegramLockKeyResolver(activeProfile) {
+    return function getTelegramLockKey() {
+        return resolveTelegramLockKey(activeProfile.getActiveProfileName());
+    };
+}
+export function readLocks(path = getOwnersPath()) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function readLocksForTransaction(path) {
+    let source;
+    try {
+        source = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return {};
+        throw error;
+    }
+    const value = JSON.parse(source);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Invalid Telegram owner store: ${path}`);
+    }
+    return value;
+}
+function isRetryableLockWriteError(error) {
+    const code = error?.code;
+    return code === "EPERM" || code === "EBUSY" || code === "EACCES";
+}
+function sleepSync(ms) {
+    const buffer = new SharedArrayBuffer(4);
+    Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+}
+/** Rename one Telegram runtime artifact with bounded Windows sharing retries. */
+export function renameTelegramPathWithRetry(sourcePath, destinationPath, options = {}) {
+    const rename = options.rename ?? renameSync;
+    const attempts = Math.max(1, options.attempts ?? TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS);
+    const retryDelayMs = Math.max(0, options.retryDelayMs ?? TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS);
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            rename(sourcePath, destinationPath);
+            return true;
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return false;
+            if (!isRetryableLockWriteError(error) || attempt === attempts - 1) {
+                throw error;
+            }
+            sleepSync(retryDelayMs * (attempt + 1));
+        }
+    }
+    return false;
+}
+const TELEGRAM_TRANSACTION_OWNER_PATTERN = /^owner\.([A-Za-z0-9-]+)\.json$/u;
+function getLockTransactionOwnerFile(generation) {
+    return `owner.${generation}.json`;
+}
+function getLockTransactionOwnerPath(path) {
+    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) {
+    try {
+        const value = JSON.parse(readFileSync(getLockTransactionOwnerPath(path), "utf8"));
+        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) {
+    return Object.assign(new Error(`Telegram lock transaction guard already exists: ${path}`), { code: "EEXIST" });
+}
+function isLockTransactionContentionError(error) {
+    const code = error?.code;
+    return (code === "EEXIST" ||
+        code === "ENOTEMPTY" ||
+        code === "ENOTDIR" ||
+        code === "EISDIR" ||
+        isRetryableLockWriteError(error));
+}
+function removeLockTransactionGuard(path) {
+    rmSync(path, { recursive: true, force: true });
+}
+function createLockTransactionGuard(path, options = {}) {
+    const owner = {
+        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);
+        (options.publishRename ?? renameSync)(stagedPath, path);
+        return owner;
+    }
+    finally {
+        try {
+            removeLockTransactionGuard(stagedPath);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+function releaseLockTransactionGuard(path, owner) {
+    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()}`;
+    if (!renameTelegramPathWithRetry(path, releasedPath))
+        return;
+    try {
+        removeLockTransactionGuard(releasedPath);
+    }
+    catch {
+        /* released debris cannot retain transaction authority */
+    }
+}
+function isAbandonedLockTransaction(path) {
+    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");
+function getActiveTransactionReclaims() {
+    const root = globalThis;
+    return (root[TELEGRAM_ACTIVE_TRANSACTION_RECLAIMS] ??= new Set());
+}
+function reclaimAbandonedDirectoryGuard(path, options = {}) {
+    try {
+        if (!lstatSync(path).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    let entries;
+    try {
+        entries = readdirSync(path);
+    }
+    catch {
+        // Another recovery candidate may remove the observed guard after lstat.
+        return false;
+    }
+    if (entries.length !== 1)
+        return false;
+    const entry = entries[0];
+    let observedPid;
+    let observedReclaimGeneration;
+    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) {
+        const code = error?.code;
+        if (code === "ENOENT")
+            return false;
+        // macOS may report EINVAL instead of ENOENT when another process wins
+        // the same source rename. Only classify it as contention once the
+        // observed source is actually gone; preserve unrelated EINVAL failures.
+        if (code === "EINVAL" && !existsSync(sourcePath))
+            return false;
+        throw error;
+    }
+    const renameWithRetry = (fromPath, toPath) => renameTelegramPathWithRetry(fromPath, toPath, { rename: renameRecovery });
+    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, options = {}) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            return createLockTransactionGuard(path, options);
+        }
+        catch (error) {
+            if (!isLockTransactionContentionError(error))
+                throw error;
+            if (!reclaimAbandonedDirectoryGuard(path, options))
+                return undefined;
+        }
+    }
+    return undefined;
+}
+function removeAbandonedLegacyRecoveryGuard(path, options = {}) {
+    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?.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, options = {}) {
+    let owner = acquireRecoverableDirectoryGuard(path, options);
+    if (owner)
+        return owner;
+    if (!removeAbandonedLegacyRecoveryGuard(path, options))
+        return undefined;
+    owner = acquireRecoverableDirectoryGuard(path, options);
+    return owner;
+}
+function createRecoveredLockTransactionGuard(path, options = {}) {
+    try {
+        return createLockTransactionGuard(path, options);
+    }
+    catch (error) {
+        if (isLockTransactionContentionError(error))
+            return undefined;
+        throw error;
+    }
+}
+function recoverAbandonedLockTransaction(path, options = {}) {
+    if (!isAbandonedLockTransaction(path))
+        return undefined;
+    let isDirectory;
+    try {
+        isDirectory = lstatSync(path).isDirectory();
+    }
+    catch {
+        return undefined;
+    }
+    if (isDirectory) {
+        if (!reclaimAbandonedDirectoryGuard(path, options))
+            return undefined;
+        const recoveredOwner = createRecoveredLockTransactionGuard(path, options);
+        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;
+    try {
+        if (!isAbandonedLockTransaction(path))
+            return undefined;
+        const stalePath = `${path}.stale.${process.pid}.${randomUUID()}`;
+        try {
+            renameSync(path, stalePath);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        try {
+            removeLockTransactionGuard(stalePath);
+        }
+        catch {
+            /* stale debris cannot retain transaction authority */
+        }
+        recoveredOwner = createRecoveredLockTransactionGuard(path, options);
+        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, options = {}) {
+    const attempts = Math.max(1, options.attempts ?? TELEGRAM_LOCK_TRANSACTION_ATTEMPTS);
+    const retryDelayMs = Math.max(0, options.retryDelayMs ?? TELEGRAM_LOCK_TRANSACTION_RETRY_DELAY_MS);
+    mkdirSync(dirname(path), { recursive: true });
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            return createLockTransactionGuard(path, options);
+        }
+        catch (error) {
+            if (!isLockTransactionContentionError(error))
+                throw error;
+            const recoveredOwner = recoverAbandonedLockTransaction(path, options);
+            if (recoveredOwner !== undefined)
+                return recoveredOwner;
+            if (attempt === attempts - 1) {
+                throw new Error(`Timed out acquiring Telegram lock transaction: ${path}`);
+            }
+            sleepSync(retryDelayMs);
+        }
+    }
+    throw new Error(`Failed to acquire Telegram lock transaction: ${path}`);
+}
+export function withTelegramFileTransaction(transactionPath, operation, options = {}) {
+    const owner = acquireLockTransaction(transactionPath, options);
+    try {
+        return operation();
+    }
+    finally {
+        releaseLockTransactionGuard(transactionPath, owner);
+    }
+}
+function withLockTransaction(locksPath, mutate) {
+    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, locks) {
+    mkdirSync(dirname(path), { recursive: true });
+    const payload = `${JSON.stringify(locks, null, 2)}\n`;
+    let lastError;
+    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, {
+                encoding: "utf8",
+                mode: 0o600,
+            });
+            renameSync(tempPath, path);
+            return;
+        }
+        catch (error) {
+            lastError = error;
+            try {
+                unlinkSync(tempPath);
+            }
+            catch {
+                /* best effort */
+            }
+            if (!isRetryableLockWriteError(error) ||
+                attempt === TELEGRAM_LOCK_WRITE_RETRY_ATTEMPTS - 1) {
+                throw error;
+            }
+            sleepSync(TELEGRAM_LOCK_WRITE_RETRY_DELAY_MS * (attempt + 1));
+        }
+    }
+    throw lastError;
+}
+export function parseTelegramLockEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.pid !== "number")
+        return undefined;
+    return {
+        pid: record.pid,
+        cwd: typeof record.cwd === "string" ? record.cwd : undefined,
+        instanceId: typeof record.instanceId === "string" ? record.instanceId : undefined,
+        heartbeatMs: typeof record.heartbeatMs === "number" ? record.heartbeatMs : undefined,
+        leaderEpoch: 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
+            : undefined,
+        busSecret: typeof record.busSecret === "string" ? record.busSecret : undefined,
+    };
+}
+export function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+export function formatTelegramLockEntry(lock) {
+    return lock.cwd ? `pid ${lock.pid}, cwd ${lock.cwd}` : `pid ${lock.pid}`;
+}
+function formatTelegramFollowerRegistrationFailure(message) {
+    if (/\b(?:ENOENT|ECONNREFUSED|ETIMEDOUT)\b/u.test(message)) {
+        return (`live owner / unreachable bus endpoint after bounded retries (${message}); ` +
+            "wait briefly for owner recovery, then retry /telegram-connect. " +
+            "Do not force takeover while the owner remains live");
+    }
+    return message;
+}
+function getLockState(lock, pid, isAlive, options = {}) {
+    if (!lock)
+        return { kind: "inactive" };
+    if (lock.pid === pid)
+        return { kind: "active-here", lock };
+    if (typeof lock.heartbeatMs === "number" &&
+        typeof options.nowMs === "number" &&
+        typeof options.staleHeartbeatMs === "number" &&
+        options.nowMs - lock.heartbeatMs > options.staleHeartbeatMs) {
+        return { kind: "stale", lock };
+    }
+    if (isAlive(lock.pid))
+        return { kind: "active-elsewhere", lock };
+    return { kind: "stale", lock };
+}
+function ownsLockContext(lock, pid, ctx) {
+    if (!lock || lock.pid !== pid)
+        return false;
+    return !lock.cwd || !ctx || lock.cwd === ctx.cwd;
+}
+function hasSameLockOwner(current, expected) {
+    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, pid, ctx, instanceId, runtimeGeneration) {
+    if (current.pid !== pid ||
+        (current.cwd !== undefined && current.cwd !== ctx.cwd) ||
+        !instanceId) {
+        return false;
+    }
+    return (current.runtimeGeneration === undefined ||
+        runtimeGeneration > current.runtimeGeneration);
+}
+function createLockEntry(pid, ctx, options) {
+    const lock = { pid, cwd: ctx.cwd };
+    if (options.instanceId) {
+        const nowMs = options.getNowMs?.();
+        lock.instanceId = options.instanceId;
+        lock.heartbeatMs = nowMs;
+        lock.leaderEpoch = options.mintLeaderEpoch?.() ?? randomUUID();
+        lock.runtimeGeneration = options.runtimeGeneration;
+    }
+    if (options.busSocketPath)
+        lock.busSocketPath = options.busSocketPath;
+    if (options.busSecret)
+        lock.busSecret = options.busSecret;
+    return lock;
+}
+function formatLockState(state) {
+    switch (state.kind) {
+        case "inactive":
+            return "inactive";
+        case "active-here":
+            return "active here";
+        case "active-elsewhere":
+            return `active elsewhere (${formatTelegramLockEntry(state.lock)})`;
+        case "stale":
+            return `stale (${formatTelegramLockEntry(state.lock)})`;
+    }
+}
+export function createTelegramLockRuntime(options = {}) {
+    const key = options.key ?? TELEGRAM_LOCK_KEY;
+    const locksPath = options.locksPath ?? getOwnersPath();
+    const pid = options.pid ?? process.pid;
+    const isAlive = options.isProcessAlive ?? isProcessAlive;
+    const getNowMs = options.getNowMs ?? Date.now;
+    const runtimeGeneration = options.runtimeGeneration ?? allocateTelegramLockRuntimeGeneration();
+    let ownedLockKey;
+    let ownedLock;
+    let deliveryRevoked = false;
+    const stateOptions = () => ({
+        nowMs: getNowMs(),
+        staleHeartbeatMs: options.staleHeartbeatMs,
+    });
+    const resolveEffectiveKey = () => {
+        if (typeof key === "function")
+            return key() || TELEGRAM_LOCK_KEY;
+        return key;
+    };
+    const readLock = () => {
+        const effectiveKey = resolveEffectiveKey();
+        return parseTelegramLockEntry(readLocks(locksPath)[effectiveKey]);
+    };
+    const adoptCompatibleOwnedLock = (effectiveKey, lock, ctx) => {
+        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 = {}) => withLockTransaction(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) &&
+                !deliveryRevoked) {
+                return {
+                    result: {
+                        ok: true,
+                        lock: current,
+                        replacedStale: false,
+                    },
+                    changed: false,
+                };
+            }
+            if (acquireOptions.election && current) {
+                if (state.kind !== "stale" ||
+                    !hasSameLockOwner(current, acquireOptions.expectedOwner)) {
+                    return {
+                        result: { ok: false, lock: current },
+                        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") &&
+                !(deliveryRevoked && hasSameLockOwner(current, expectedOwned)) &&
+                (!acquireOptions.force ||
+                    !expectedReplacementMatches ||
+                    !canReplaceCurrent)) {
+                return {
+                    result: { ok: false, lock: state.lock },
+                    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;
+            deliveryRevoked = false;
+            return {
+                result: {
+                    ok: true,
+                    lock,
+                    replacedStale: state.kind === "stale",
+                },
+                changed: true,
+            };
+        }),
+        release: () => {
+            // Withdraw local send authority even if the durable release fails.
+            deliveryRevoked = true;
+            return 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())),
+        getOwnedLeaderEpoch: () => {
+            if (deliveryRevoked)
+                return undefined;
+            const effectiveKey = resolveEffectiveKey();
+            const lock = parseTelegramLockEntry(readLocks(locksPath)[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]);
+            return hasSameLockOwner(lock, adoptCompatibleOwnedLock(effectiveKey, lock, ctx));
+        },
+        commitIfOwned: (commit) => !deliveryRevoked && 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) => !deliveryRevoked && 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 = {
+                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 };
+        }),
+    };
+}
+export function createTelegramLockOwnershipGuard(lock) {
+    return {
+        ownsContext: (ctx) => lock.owns(ctx),
+    };
+}
+export function createTelegramDirectDeliveryOwnershipChecker(deps) {
+    return () => {
+        const ctx = deps.contextStore.get();
+        return ctx ? deps.lock.owns(ctx) : false;
+    };
+}
+function snapshotLockContext(ctx) {
+    return { cwd: ctx.cwd };
+}
+export function createTelegramLockedPollingRuntime(deps) {
+    let ownershipCheckInterval;
+    let ownershipRefreshInterval;
+    let ownershipStop;
+    let activeContext;
+    let takeoverCandidate;
+    let sessionAutoStartRun;
+    let pollingGeneration = 0;
+    const ownershipCheckMs = deps.ownershipCheckMs ?? TELEGRAM_OWNERSHIP_CHECK_MS;
+    const ownershipRefreshMs = deps.ownershipRefreshMs ?? TELEGRAM_OWNERSHIP_REFRESH_MS;
+    const stopOwnershipWatcher = () => {
+        if (ownershipCheckInterval)
+            clearInterval(ownershipCheckInterval);
+        if (ownershipRefreshInterval)
+            clearInterval(ownershipRefreshInterval);
+        ownershipCheckInterval = undefined;
+        ownershipRefreshInterval = undefined;
+    };
+    const suspendPolling = async () => {
+        pollingGeneration += 1;
+        activeContext = undefined;
+        deps.transportMonitor?.stop();
+        deps.stopFollowerRegistration?.();
+        stopOwnershipWatcher();
+        if (sessionAutoStartRun) {
+            await sessionAutoStartRun;
+            deps.stopFollowerRegistration?.();
+        }
+        if (ownershipStop) {
+            await ownershipStop;
+            return;
+        }
+        await deps.stopPolling();
+    };
+    const stopAfterOwnershipLoss = () => {
+        if (ownershipStop)
+            return;
+        activeContext = undefined;
+        deps.transportMonitor?.stop();
+        stopOwnershipWatcher();
+        deps.onTransportAvailabilityChanged?.();
+        ownershipStop = deps
+            .stopPolling()
+            .catch((error) => deps.recordRuntimeEvent?.("lock", error, { phase: "ownership-loss" }))
+            .finally(() => {
+            ownershipStop = undefined;
+        });
+    };
+    const startOwnershipWatcher = (ctx) => {
+        const owner = snapshotLockContext(ctx);
+        stopOwnershipWatcher();
+        ownershipCheckInterval = setInterval(() => {
+            try {
+                if (deps.lock.owns(owner))
+                    return;
+            }
+            catch (error) {
+                deps.recordRuntimeEvent?.("lock", error, { phase: "check" });
+            }
+            stopAfterOwnershipLoss();
+        }, ownershipCheckMs);
+        ownershipRefreshInterval = setInterval(() => {
+            try {
+                if (deps.lock.refresh(owner))
+                    return;
+            }
+            catch (error) {
+                deps.recordRuntimeEvent?.("lock", error, { phase: "refresh" });
+            }
+            stopAfterOwnershipLoss();
+        }, ownershipRefreshMs);
+        ownershipCheckInterval.unref?.();
+        ownershipRefreshInterval.unref?.();
+    };
+    const runOwnedPollingStart = async (ctx, options, isCurrent) => {
+        if (!isCurrent())
+            return false;
+        activeContext = ctx;
+        startOwnershipWatcher(ctx);
+        try {
+            if (!deps.lock.refresh(snapshotLockContext(ctx))) {
+                stopOwnershipWatcher();
+                return false;
+            }
+            await options.onAcquired?.();
+            if (!isCurrent())
+                return false;
+            await deps.startPolling(ctx, options);
+        }
+        catch (error) {
+            if (!isCurrent())
+                return false;
+            stopOwnershipWatcher();
+            try {
+                await deps.stopPolling();
+            }
+            catch (stopError) {
+                deps.recordRuntimeEvent?.("lock", stopError, {
+                    phase: "startup-rollback",
+                });
+            }
+            if (!isCurrent())
+                return false;
+            deps.lock.release();
+            deps.onTransportAvailabilityChanged?.();
+            throw error;
+        }
+        if (!isCurrent())
+            return false;
+        if (deps.lock.owns(ctx)) {
+            if (activeContext !== ctx)
+                return false;
+            deps.transportMonitor?.start(ctx);
+            return true;
+        }
+        stopOwnershipWatcher();
+        if (ownershipStop)
+            await ownershipStop;
+        if (!isCurrent())
+            return false;
+        await deps.stopPolling();
+        if (!isCurrent())
+            return false;
+        deps.onTransportAvailabilityChanged?.();
+        return false;
+    };
+    const canStartPolling = (ctx) => deps.canStartPolling?.(ctx) ?? true;
+    const formatStartBlockedMessage = (ctx) => deps.formatStartBlockedMessage?.(ctx) ??
+        "Telegram polling is unavailable in this Pi run mode.";
+    return {
+        start: async (ctx, options = {}) => {
+            if (!deps.hasBotToken()) {
+                return {
+                    ok: false,
+                    message: deps.getBotTokenDiagnostic?.() ?? "Telegram bot is not configured.",
+                };
+            }
+            if (!canStartPolling(ctx)) {
+                return { ok: false, message: formatStartBlockedMessage(ctx) };
+            }
+            const cancelled = {
+                ok: false,
+                canTakeover: false,
+                message: "Telegram polling startup was cancelled or superseded.",
+            };
+            if (deps.isContextCurrent?.(ctx) === false)
+                return cancelled;
+            const generation = ++pollingGeneration;
+            const isCurrent = () => generation === pollingGeneration &&
+                (deps.isContextCurrent?.(ctx) ?? true);
+            if (ownershipStop)
+                await ownershipStop;
+            if (!isCurrent())
+                return cancelled;
+            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;
+                    try {
+                        const registered = await deps.registerFollowerWithOwner(ctx, acquired.lock);
+                        if (!isCurrent())
+                            return cancelled;
+                        if (registered) {
+                            deps.updateStatus(ctx);
+                            return { ok: true, canTakeover: false };
+                        }
+                        if (registered === false)
+                            failureMessage = "not registered";
+                    }
+                    catch (error) {
+                        failureMessage =
+                            error instanceof Error ? error.message : String(error);
+                        deps.recordRuntimeEvent?.("bus", error, {
+                            phase: "follower-register",
+                        });
+                    }
+                    if (failureMessage) {
+                        const owner = formatTelegramLockEntry(acquired.lock);
+                        return {
+                            ok: false,
+                            canTakeover: false,
+                            owner,
+                            message: `Telegram bridge is active in another Pi instance (${owner}); follower registration failed: ${formatTelegramFollowerRegistrationFailure(failureMessage)}.`,
+                        };
+                    }
+                }
+                const owner = formatTelegramLockEntry(acquired.lock);
+                return {
+                    ok: false,
+                    canTakeover: true,
+                    owner,
+                    message: `Telegram bridge is active in another Pi instance (${owner}).`,
+                };
+            }
+            takeoverCandidate = undefined;
+            if (!(await runOwnedPollingStart(ctx, options, isCurrent))) {
+                if (!isCurrent())
+                    return cancelled;
+                return {
+                    ok: false,
+                    canTakeover: false,
+                    message: "Telegram leadership changed during polling startup.",
+                };
+            }
+            if (!isCurrent())
+                return cancelled;
+            deps.onTransportAvailabilityChanged?.();
+            deps.updateStatus(ctx);
+            const staleSuffix = acquired.replacedStale ? " Replaced stale lock." : "";
+            return { ok: true, message: `Telegram bridge connected.${staleSuffix}` };
+        },
+        stop: async () => {
+            await suspendPolling();
+            const state = deps.lock.release();
+            deps.onTransportAvailabilityChanged?.();
+            if (state.kind === "active-elsewhere") {
+                return `Telegram bridge is active in another Pi instance (${formatTelegramLockEntry(state.lock)}).`;
+            }
+            if (state.kind === "stale") {
+                return `Removed stale Telegram bridge lock (${formatTelegramLockEntry(state.lock)}).`;
+            }
+            return "Telegram bridge disconnected.";
+        },
+        suspend: suspendPolling,
+        onPersistentConflict: async (ctx, count) => {
+            if (activeContext === undefined || ownershipStop)
+                return;
+            if (!(deps.isContextCurrent?.(ctx) ?? activeContext === ctx))
+                return;
+            activeContext = undefined;
+            pollingGeneration += 1;
+            stopOwnershipWatcher();
+            deps.transportMonitor?.stop();
+            let ownership = "unverifiable";
+            const cleanupErrors = [];
+            try {
+                ownership = deps.lock.owns(snapshotLockContext(ctx)) ? "owned" : "lost";
+            }
+            catch (error) {
+                cleanupErrors.push(String(error));
+            }
+            try {
+                deps.lock.release();
+            }
+            catch (error) {
+                ownership = "unverifiable";
+                cleanupErrors.push(String(error));
+            }
+            ownershipStop = Promise.resolve()
+                .then(() => deps.stopPolling())
+                .catch((error) => { cleanupErrors.push(String(error)); })
+                .finally(() => {
+                ownershipStop = undefined;
+                deps.recordRuntimeEvent?.("polling", ownership === "lost"
+                    ? "Telegram transport stopped: local ownership lost; check for another Pi instance."
+                    : "Telegram transport stopped: competing getUpdates client or ownership mismatch.", {
+                    phase: "persistent-conflict", count, ownership,
+                    ...(cleanupErrors.length ? { cleanupErrors } : {}),
+                });
+                deps.updateStatus(ctx);
+            });
+            deps.onTransportAvailabilityChanged?.();
+            await ownershipStop;
+        },
+        onSessionStart: async (_event, ctx) => {
+            if (!deps.hasBotToken())
+                return;
+            if (!canStartPolling(ctx))
+                return;
+            const ownsCurrentLock = deps.lock.owns(ctx);
+            const state = ownsCurrentLock ? undefined : deps.lock.getState();
+            const canResumeStaleSameCwd = state?.kind === "stale" && state.lock.cwd === ctx.cwd;
+            const canHandoffSameProcess = state?.kind === "active-here" &&
+                (!state.lock.cwd || state.lock.cwd === ctx.cwd);
+            const canRestoreRememberedFollower = state?.kind === "active-elsewhere" &&
+                deps.restoreFollowerWithOwner !== undefined;
+            if (!ownsCurrentLock &&
+                !canResumeStaleSameCwd &&
+                !canHandoffSameProcess &&
+                !canRestoreRememberedFollower) {
+                return;
+            }
+            if (deps.isContextCurrent?.(ctx) === false)
+                return;
+            const generation = ++pollingGeneration;
+            const isCurrent = () => generation === pollingGeneration &&
+                (deps.isContextCurrent?.(ctx) ?? true);
+            const startedAtMs = Date.now();
+            deps.recordRuntimeEvent?.("lock", "Telegram auto-start scheduled", {
+                phase: "auto-start-scheduled",
+                mode: canRestoreRememberedFollower ? "follower-restore" : "leader",
+            });
+            const run = (async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+                if (ownershipStop)
+                    await ownershipStop;
+                if (!isCurrent())
+                    return;
+                if (canRestoreRememberedFollower && state?.kind === "active-elsewhere") {
+                    const restored = await deps.restoreFollowerWithOwner?.(ctx, state.lock);
+                    if (!isCurrent() || !restored)
+                        return;
+                    deps.onTransportAvailabilityChanged?.();
+                    deps.updateStatus(ctx);
+                    deps.recordRuntimeEvent?.("bus", "Telegram follower auto-connect completed", { phase: "follower-auto-connect" });
+                    return;
+                }
+                if (canResumeStaleSameCwd || canHandoffSameProcess) {
+                    const acquired = deps.lock.acquire(ctx, canHandoffSameProcess
+                        ? { force: true, expectedOwner: state?.lock }
+                        : undefined);
+                    if (!acquired.ok)
+                        return;
+                }
+                if (!isCurrent())
+                    return;
+                if (!(await runOwnedPollingStart(ctx, {}, isCurrent)))
+                    return;
+                if (!isCurrent())
+                    return;
+                deps.onTransportAvailabilityChanged?.();
+                deps.updateStatus(ctx);
+                deps.recordRuntimeEvent?.("lock", "Telegram auto-start completed", {
+                    phase: "auto-start-complete",
+                    durationMs: Date.now() - startedAtMs,
+                });
+            })()
+                .catch((error) => {
+                deps.recordRuntimeEvent?.("lock", error, { phase: "auto-start" });
+            })
+                .finally(() => {
+                if (sessionAutoStartRun === run)
+                    sessionAutoStartRun = undefined;
+            });
+            sessionAutoStartRun = run;
+        },
+        registerFollowerWithOwner: deps.registerFollowerWithOwner
+            ? async (ctx, owner) => {
+                const registered = await deps.registerFollowerWithOwner?.(ctx, owner);
+                if (registered)
+                    deps.updateStatus(ctx);
+                return registered === true;
+            }
+            : undefined,
+        restoreFollowerWithOwner: deps.restoreFollowerWithOwner
+            ? async (ctx, owner) => {
+                const restored = await deps.restoreFollowerWithOwner?.(ctx, owner);
+                if (restored)
+                    deps.updateStatus(ctx);
+                return restored === true;
+            }
+            : undefined,
+        stopFollowerRegistration: deps.stopFollowerRegistration,
+    };
+}