approval-md 0.3.0 → 0.4.0

package/dist/src/core/channel-lease.js

@@ -0,0 +1,663 @@
+/**
+ * One transport per gate, enforced locally (APRV-424, review finding 1).
+ *
+ * `core/channel-owner.ts` answers "does another INSTANCE on this machine hold
+ * this bot", keyed on the instance id, and `getWebhookInfo` answers "what is
+ * the Bot API delivering this bot's updates to". Between those two answers
+ * there was a hole, and it is the one this file closes: two processes started
+ * in the SAME gate, one `approval up` long-polling and one `approval channel
+ * telegram webhook`, pass both checks. The registry compares instance ids and
+ * both processes are the same instance; `getWebhookInfo` is empty when the
+ * poller is the one already running. Each then runs its own dispatch cycle
+ * over its own `DispatchState` against one log, so every pending request
+ * reaches the phone twice under two nonces and only one of the two copies can
+ * resolve a tap.
+ *
+ * ## What the lease is
+ *
+ * A lockfile in the gate's own derived state directory:
+ *
+ * ```
+ * <instance home>/.approval/daemon/telegram-transport.lock
+ * ```
+ *
+ * `daemon/` because that is where this runtime already keeps per-gate runtime
+ * state that a clone must not inherit (`core/live-draw.ts`'s socket lives
+ * beside it, and `.gitignore` holds the whole directory). It carries the
+ * holder's pid, which transport it is running, and when it started, and it is
+ * created with `O_EXCL` so two processes racing cannot both believe they took
+ * it.
+ *
+ * ## Per PROCESS, and validated for liveness
+ *
+ * The holder is a pid, so:
+ *
+ * - **A second process refuses.** It reads the holder, sees a live pid, and is
+ *   told which transport is running and under which pid. The refusal is the
+ *   whole point: a channel that ran both transports would deliver twice.
+ * - **A dead holder is reclaimed.** A crash, a `kill -9`, a laptop that slept
+ *   through a power cycle: the lockfile outlives the process, and refusing
+ *   forever over a file nobody owns would be an outage with no fault behind
+ *   it. `process.kill(pid, 0)` is the probe; `EPERM` counts as alive, because
+ *   a pid that belongs to somebody else is still a pid in use.
+ * - **The same pid is never in conflict with itself.** One process holds one
+ *   transport, and the in-process half of that rule is
+ *   `TelegramChannel.claimTransport`, which refuses a second claim on one
+ *   channel object. A re-take by the holding pid rewrites the record rather
+ *   than refusing, so a supervisor that restarts its own channel part inside
+ *   one process (`approval up`) is not fighting its own lockfile.
+ *
+ * A recycled pid is the acknowledged limit: a long-dead holder whose number
+ * has been reused by an unrelated program reads as alive, and the operator
+ * gets a refusal naming a pid that is not a gate. That is the safe direction
+ * of the error (a refusal an operator can clear by deleting a named file,
+ * rather than two pollers on one log), and it is the same trade
+ * `core/live-draw.ts` makes when it validates the answering daemon's pid.
+ *
+ * ## Why an I/O failure is a refusal
+ *
+ * Every other local record in this runtime is a cache whose absence is the
+ * status quo (`channel-owner.ts` says so at length). This one is not: it is
+ * the only thing standing between a gate and two live transports, so a
+ * directory it cannot create or a file it cannot write is a state in which
+ * exclusion cannot be promised, and the stricter path is to say so and stop.
+ * The refusal names the path, which is a thing an operator can fix.
+ *
+ * Nothing here is evidence. It is never read by an enforcement path, it
+ * widens no permission, and the only thing it can produce is a refusal to
+ * start.
+ */
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { instanceHomeFor } from "./instance.js";
+/** The lockfile's basename inside the gate's `daemon/` directory. */
+export const CHANNEL_LEASE_FILE = "telegram-transport.lock";
+/** The only format version this build writes, and the only one it reads. */
+export const CHANNEL_LEASE_VERSION = 1;
+/** How many times a take retries around a torn or reclaimed lockfile. */
+export const CHANNEL_LEASE_ATTEMPTS = 5;
+/** How long a take waits before re-reading a lockfile it could not parse. */
+export const CHANNEL_LEASE_RETRY_MS = 20;
+/**
+ * The sibling file that serializes TAKE-OVERS of an existing lockfile.
+ *
+ * The lease itself is taken with `O_EXCL`, which settles the ordinary race by
+ * itself: exactly one of two processes creating a file that is not there wins.
+ * Reclaiming a lockfile that IS there cannot be settled that way, and the
+ * first version of this module proved it. Two processes both read the same
+ * dead holder, the first unlinked it and created its own live lease, and the
+ * second, resuming inside its own read-then-unlink, deleted that live lease
+ * and created its own. Both then believed they held the gate, which is the
+ * exact state this file exists to rule out.
+ *
+ * So a take-over happens inside a critical section of its own, entered with
+ * the same `O_EXCL` primitive, and what happens inside it is a re-read: the
+ * record must still be the very one that was judged dead (same pid, same
+ * `started_at`) or the take-over is abandoned. The loser of that race finds a
+ * LIVE record on its next pass and refuses, which is the right answer.
+ */
+export const CHANNEL_LEASE_RECLAIM_SUFFIX = ".reclaim";
+/**
+ * How old a reclaim lock has to be before its age is worth saying out loud.
+ *
+ * It DECIDES NOTHING, and that is the third review's first finding. An earlier
+ * version evicted a reclaim lock on age alone, which handed the section to a
+ * second process while the first was still inside it: the first then renamed
+ * its lease over the second's and deleted the second's lock on its way out.
+ * What decides an eviction now is the same liveness probe a lease holder is
+ * judged by, because "five seconds have passed" says nothing about whether
+ * anybody is still in the room.
+ */
+export const CHANNEL_LEASE_RECLAIM_STALE_MS = 5_000;
+/**
+ * How much later than the lease a process may have started and still be its
+ * holder.
+ *
+ * `started_at` is written just after the holder is running, so the holder's
+ * own start time is at or before it. A pid whose process started AFTER the
+ * lease was written is a pid the operating system handed to somebody else,
+ * which is the case this tolerance exists to detect rather than to forgive.
+ * The slack covers the coarse clock the fallback probe reports (`ps -o
+ * lstart=` has one-second resolution) and small clock adjustments.
+ */
+export const CHANNEL_LEASE_START_TOLERANCE_MS = 2_000;
+/**
+ * Why a lease could not be taken. Frozen, per SPEC.md §11.1 invariant 6.
+ *
+ * Two of the three name the transport that already holds the gate, because
+ * that is what decides the repair: stop the poller, or stop the webhook runner
+ * (which also removes the registration as it exits). The third is the state in
+ * which no promise can be made at all.
+ */
+export const CHANNEL_LEASE_REFUSAL_CODES = [
+    /** A long-poll listener (`approval channel telegram listen`, `approval up`) holds it. */
+    "telegram-poller-running",
+    /** A webhook runner holds it. Same code the Bot API probe uses, same repair. */
+    "webhook-registered",
+    /** The lockfile could not be created, read or written, so exclusion cannot be promised. */
+    "telegram-lease-unavailable",
+];
+/** The gate's `daemon/` directory for `logPath`, derived and never configured. */
+export function channelLeaseDirFor(logPath) {
+    return join(instanceHomeFor(resolve(logPath)), "daemon");
+}
+/** Where the Telegram transport lease for `logPath` lives. */
+export function channelLeasePathFor(logPath) {
+    return join(channelLeaseDirFor(logPath), CHANNEL_LEASE_FILE);
+}
+/**
+ * When the process with this pid started, or `null` when it cannot be learned.
+ *
+ * Two sources, in order of cost. On Linux `/proc/<pid>` is created with the
+ * process and carries its start time, which needs no subprocess. Everywhere
+ * else `ps -o lstart=` answers the same question; it costs one short-lived
+ * child, paid once per lease take (which happens once per process start), and
+ * a `ps` that is missing, slow or unhelpful returns `null` rather than
+ * failing.
+ *
+ * `null` is the fail-CLOSED direction here: a holder whose start time cannot
+ * be compared is judged by its pid alone, exactly as before this probe
+ * existed, and a live pid then still refuses.
+ */
+export function processStartedAt(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    if (process.platform === "linux") {
+        try {
+            return statSync(`/proc/${String(pid)}`).mtime;
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        const run = spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+            encoding: "utf8",
+            timeout: 2_000,
+            windowsHide: true,
+        });
+        if (run.status !== 0)
+            return null;
+        const text = (run.stdout ?? "").trim();
+        if (text.length === 0)
+            return null;
+        const when = new Date(text);
+        return Number.isNaN(when.getTime()) ? null : when;
+    }
+    catch {
+        return null;
+    }
+}
+/** Ask the operating system about one pid. The default {@link ChannelLeaseOptions.probe}. */
+export function probePid(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return { running: false, foreign: false, startedAt: null };
+    }
+    try {
+        process.kill(pid, 0);
+    }
+    catch (cause) {
+        const code = cause.code;
+        if (code === "ESRCH")
+            return { running: false, foreign: false, startedAt: null };
+        if (code === "EPERM")
+            return { running: true, foreign: true, startedAt: processStartedAt(pid) };
+        // Anything else is unexpected, and the stricter reading of an unexpected
+        // answer is that the holder is there.
+        return { running: true, foreign: false, startedAt: processStartedAt(pid) };
+    }
+    return { running: true, foreign: false, startedAt: processStartedAt(pid) };
+}
+/**
+ * Is `pid` a running process?
+ *
+ * Kept for the callers that only want the coarse answer. The lease itself asks
+ * {@link probePid}, because a pid alone cannot tell a holder from a number the
+ * operating system has since handed to somebody else.
+ */
+export function pidIsAlive(pid) {
+    return probePid(pid).running;
+}
+/**
+ * Why a lease stopped being its holder's.
+ *
+ * Three ways, and the operator is told which: the process is gone, the number
+ * now belongs to somebody this process cannot signal, or the number is in use
+ * by a process that started after the lease was written and therefore cannot
+ * be the one that wrote it.
+ */
+export const CHANNEL_LEASE_RECLAIM_REASONS = ["gone", "foreign", "recycled"];
+/** Is this holder still the process that wrote the lease? */
+function judgeHolder(holder, probe) {
+    const found = probe(holder.pid);
+    if (!found.running)
+        return { held: false, reason: "gone" };
+    if (found.foreign)
+        return { held: false, reason: "foreign" };
+    if (found.startedAt !== null) {
+        const wrote = Date.parse(holder.startedAt);
+        if (!Number.isNaN(wrote) &&
+            found.startedAt.getTime() > wrote + CHANNEL_LEASE_START_TOLERANCE_MS) {
+            return { held: false, reason: "recycled" };
+        }
+    }
+    return { held: true };
+}
+/** How a reclaim is reported to the operator. */
+export function reclaimDetail(holder, reason) {
+    const why = reason === "gone"
+        ? "that process is gone"
+        : reason === "foreign"
+            ? "that pid now belongs to a process this one cannot signal, so it is not the holder"
+            : "that pid belongs to a process that started after the lease was written, so the number has been reused";
+    return `the telegram transport lease was held by pid ${String(holder.pid)} in ${holder.mode} mode since ${holder.startedAt}, and ${why}; reclaimed`;
+}
+/** Synchronous sleep with no dependency and no busy-spin. `core/log.ts`'s. */
+function sleepSync(ms) {
+    const buffer = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(buffer, 0, 0, ms);
+}
+function parseHolder(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const record = raw;
+    if (record["version"] !== CHANNEL_LEASE_VERSION)
+        return null;
+    const pid = record["pid"];
+    const mode = record["mode"];
+    const startedAt = record["started_at"];
+    const instanceHome = record["instance_home"];
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return null;
+    if (mode !== "poll" && mode !== "webhook")
+        return null;
+    if (typeof startedAt !== "string" || startedAt.length === 0)
+        return null;
+    if (typeof instanceHome !== "string")
+        return null;
+    return { pid, mode, startedAt, instanceHome };
+}
+function readHolder(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (cause) {
+        return cause.code === "ENOENT" ? { state: "absent" } : { state: "torn" };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { state: "torn" };
+    }
+    const holder = parseHolder(parsed);
+    return holder === null ? { state: "torn" } : { state: "held", holder };
+}
+/**
+ * {@link readHolder}, re-read while it comes back unreadable.
+ *
+ * A record this build cannot parse is either a lockfile a crash tore in half
+ * or one a process is writing right now, and for as long as that write takes
+ * the two look alike. So an unreadable file is re-read before it is judged,
+ * and only one that stays unreadable is reported as torn.
+ */
+function readHolderSettled(path) {
+    let read = readHolder(path);
+    for (let attempt = 1; read.state === "torn" && attempt < CHANNEL_LEASE_ATTEMPTS; attempt += 1) {
+        sleepSync(CHANNEL_LEASE_RETRY_MS);
+        read = readHolder(path);
+    }
+    return read;
+}
+/** What the lockfile for `logPath` currently says, or `null`. Diagnostics only. */
+export function readChannelLease(logPath) {
+    const read = readHolder(channelLeasePathFor(logPath));
+    return read.state === "held" ? read.holder : null;
+}
+/** The code a refusal takes, given which transport holds the gate. */
+function codeFor(mode) {
+    return mode === "webhook" ? "webhook-registered" : "telegram-poller-running";
+}
+function refusalMessage(holder, wanted, path) {
+    const held = holder.mode === "webhook"
+        ? `a webhook runner (\`approval channel telegram webhook\`) is already receiving this gate's telegram updates`
+        : `a long-poll listener (\`approval channel telegram listen\` or \`approval up\`) is already receiving this gate's telegram updates`;
+    const same = holder.mode === wanted;
+    const why = same
+        ? "Two of them on one log both put every pending request on the phone, each under its own nonce, and only the copy whose process holds the delivery can resolve a tap"
+        : "Long polling and a webhook are alternatives per bot: both processes would put every pending request on the phone under their own nonce, only one of the two copies could resolve a tap, and the Bot API refuses getUpdates outright while a webhook is set";
+    return `${held} in ${holder.mode} mode, as pid ${String(holder.pid)}, since ${holder.startedAt}. ${why}. Stop that process (a clean stop removes its lease, and a webhook runner removes its registration as it exits), or give this instance its own bot with \`approval setup channel telegram\`. The lease is ${path}; a lease whose process is gone is reclaimed automatically, so deleting it by hand is only for a pid that no longer names a gate`;
+}
+/**
+ * Take the gate's Telegram transport lease in `mode`, or say who holds it.
+ *
+ * Synchronous, like every other lockfile in this runtime: the take happens
+ * once per process before anything is delivered, and a caller that had to
+ * await it would be a caller that could interleave two takes in one process.
+ */
+export function takeChannelLease(logPath, mode, options = {}) {
+    const pid = options.pid ?? process.pid;
+    const now = options.now ?? (() => new Date());
+    const coarse = options.alive;
+    const probe = options.probe ??
+        (coarse === undefined
+            ? probePid
+            : (candidate) => ({
+                running: coarse(candidate),
+                foreign: false,
+                startedAt: null,
+            }));
+    const path = channelLeasePathFor(logPath);
+    const instanceHome = instanceHomeFor(resolve(logPath));
+    const unavailable = (detail) => ({
+        ok: false,
+        code: "telegram-lease-unavailable",
+        holder: null,
+        message: `the telegram transport lease ${path} could not be taken (${detail}). This lease is the only thing that keeps one gate from running a poller and a webhook at once, so a gate that cannot hold one does not start: make that directory writable, or point --log at the instance this process is meant to serve`,
+    });
+    try {
+        mkdirSync(channelLeaseDirFor(logPath), { recursive: true, mode: 0o700 });
+    }
+    catch (cause) {
+        return unavailable(cause instanceof Error ? cause.message : String(cause));
+    }
+    let reclaimed = null;
+    let reclaimedBecause = null;
+    for (let attempt = 0; attempt < CHANNEL_LEASE_ATTEMPTS; attempt += 1) {
+        const body = `${JSON.stringify({
+            version: CHANNEL_LEASE_VERSION,
+            pid,
+            mode,
+            started_at: now().toISOString(),
+            instance_home: instanceHome,
+        }, null, 2)}\n`;
+        // The ordinary case, and the only one `O_EXCL` can settle on its own:
+        // nothing holds the gate, and exactly one of any number of processes
+        // creating this file wins.
+        const created = createExclusive(path, body);
+        if (created === "created") {
+            return { ok: true, lease: leaseFor(path, mode, pid), reclaimed, reclaimedBecause };
+        }
+        if (created !== "exists")
+            return unavailable(created.detail);
+        const read = readHolderSettled(path);
+        if (read.state === "absent")
+            continue;
+        if (read.state === "held" && read.holder.pid === pid) {
+            // This process already holds the gate. One process runs one transport,
+            // and the in-process guard against two is `claimTransport`; rewriting
+            // the record keeps it true rather than making a supervisor fight its own
+            // lockfile across a restart of its channel part. Written through a temp
+            // and a rename, so a reader never sees half a record.
+            const rewritten = writeAtomic(path, body, pid);
+            if (rewritten !== null)
+                return unavailable(rewritten);
+            return { ok: true, lease: leaseFor(path, mode, pid), reclaimed, reclaimedBecause };
+        }
+        if (read.state === "held") {
+            const verdict = judgeHolder(read.holder, probe);
+            if (verdict.held) {
+                return {
+                    ok: false,
+                    code: codeFor(read.holder.mode),
+                    holder: read.holder,
+                    message: refusalMessage(read.holder, mode, path),
+                };
+            }
+            options.beforeTakeOver?.();
+            const taken = takeOver(path, body, pid, { kind: "holder", holder: read.holder }, probe, {
+                ...(options.note === undefined ? {} : { note: options.note }),
+                ...(options.insideTakeOver === undefined ? {} : { inside: options.insideTakeOver }),
+            });
+            if (taken === "taken") {
+                reclaimed = read.holder;
+                reclaimedBecause = verdict.reason;
+                return { ok: true, lease: leaseFor(path, mode, pid), reclaimed, reclaimedBecause };
+            }
+            if (taken === "changed" || taken === "busy") {
+                sleepSync(CHANNEL_LEASE_RETRY_MS);
+                continue;
+            }
+            return unavailable(taken.detail);
+        }
+        // Unreadable after {@link CHANNEL_LEASE_ATTEMPTS} reads: nobody is
+        // finishing a write, so this is a lockfile a crash tore in half, and
+        // refusing forever over bytes nobody can read would be an outage with no
+        // fault behind it. Replaced rather than deleted-then-created, so the path
+        // is never absent and no third process can slip in through the gap.
+        const replaced = takeOver(path, body, pid, { kind: "torn" }, probe, {
+            ...(options.note === undefined ? {} : { note: options.note }),
+            ...(options.insideTakeOver === undefined ? {} : { inside: options.insideTakeOver }),
+        });
+        if (replaced === "taken") {
+            return { ok: true, lease: leaseFor(path, mode, pid), reclaimed, reclaimedBecause };
+        }
+        if (replaced === "changed" || replaced === "busy") {
+            sleepSync(CHANNEL_LEASE_RETRY_MS);
+            continue;
+        }
+        return unavailable(replaced.detail);
+    }
+    return unavailable(`${String(CHANNEL_LEASE_ATTEMPTS)} attempts raced another process taking it over. Something else is reclaiming this gate's transport lease and has not finished: ${path}${CHANNEL_LEASE_RECLAIM_SUFFIX} is that take-over in progress. This process refuses rather than force it, because forcing a critical section is how two transports end up running at once; if that file has no process behind it and this keeps happening, remove it`);
+}
+/** `O_EXCL` create, the one race the file system settles by itself. */
+function createExclusive(path, body) {
+    try {
+        const handle = openSync(path, "wx", 0o600);
+        try {
+            writeFileSync(handle, body, { encoding: "utf8" });
+        }
+        finally {
+            closeSync(handle);
+        }
+        return "created";
+    }
+    catch (cause) {
+        if (cause.code === "EEXIST")
+            return "exists";
+        return { detail: cause instanceof Error ? cause.message : String(cause) };
+    }
+}
+/**
+ * Write `path` whole, by rename, never leaving it absent or half-written.
+ *
+ * `rename` replaces the destination in one step, so a reader either sees the
+ * old record or the new one. Returns `null` on success and the detail of the
+ * failure otherwise.
+ */
+function writeAtomic(path, body, pid) {
+    temporaryCounter += 1;
+    const temporary = `${path}.${String(pid)}.${String(temporaryCounter)}.${String(Date.now())}.tmp`;
+    try {
+        writeFileSync(temporary, body, { encoding: "utf8", mode: 0o600 });
+        renameSync(temporary, path);
+        return null;
+    }
+    catch (cause) {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            /* the temp may never have been created; its absence is the desired state */
+        }
+        return cause instanceof Error ? cause.message : String(cause);
+    }
+}
+let temporaryCounter = 0;
+function readReclaimLock(lockPath) {
+    let raw;
+    try {
+        raw = readFileSync(lockPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const record = parsed;
+    const pid = record["pid"];
+    const nonce = record["nonce"];
+    const at = record["at"];
+    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
+        return null;
+    if (typeof nonce !== "string" || nonce.length === 0)
+        return null;
+    return { pid, nonce, at: typeof at === "number" ? at : 0 };
+}
+/** Does the lock on disk still name this entry? */
+function holdsSection(lockPath, pid, nonce) {
+    const lock = readReclaimLock(lockPath);
+    return lock !== null && lock.pid === pid && lock.nonce === nonce;
+}
+/**
+ * Replace a lockfile somebody else wrote, inside a critical section.
+ *
+ * The section is the whole of the fix for the interleaving in APRV-424's
+ * second review: two processes that had both read one dead holder used to take
+ * turns deleting each other's live lease. Inside it the record is read AGAIN
+ * and must still be exactly what was judged (the same pid and the same
+ * `started_at`), so the second reclaimer of a pair abandons its take-over,
+ * finds a live record on the next pass, and refuses.
+ *
+ * ## The section is owned, not merely occupied (third review, finding 1)
+ *
+ * Holding the section is not enough; a process has to still be holding it at
+ * the moment it acts. The first version aged a reclaim lock out after five
+ * seconds and unlinked it on the way out unconditionally, which gave the
+ * section away and then took somebody else's:
+ *
+ * A enters, re-reads, and stalls. B ages A's lock out, enters, reclaims, and
+ * renames its own lease in. A resumes and renames over B's live lease, and
+ * A's `finally` deletes B's reclaim lock for good measure. Two holders, again.
+ *
+ * Three changes close it, and all three are about identity:
+ *
+ * - The lock carries this process's pid AND a nonce, so one entry can be told
+ *   from another by the same process.
+ * - The ownership is re-checked immediately before the rename. A process that
+ *   lost the section abandons the take-over (`busy`) and meets the new
+ *   holder's live record on its next pass.
+ * - The `finally` removes the lock only while it still names this entry.
+ *
+ * And the age-out is no longer a decision: a reclaim lock is evicted only when
+ * its own process is GONE, judged by the same probe a lease holder is judged
+ * by. The age is reported and nothing more, because "five seconds have passed"
+ * says nothing about whether anybody is still in the room.
+ *
+ * `busy` means another process holds the section right now: the caller waits
+ * and comes round again rather than forcing it, because forcing a critical
+ * section is the same as not having one.
+ */
+function takeOver(path, body, pid, expect, probe, options = {}) {
+    const lockPath = `${path}${CHANNEL_LEASE_RECLAIM_SUFFIX}`;
+    const nonce = randomBytes(8).toString("hex");
+    const entered = createExclusive(lockPath, `${JSON.stringify({ pid, nonce, at: Date.now() })}\n`);
+    if (entered !== "created") {
+        if (entered !== "exists")
+            return entered;
+        const held = readReclaimLock(lockPath);
+        if (held === null) {
+            // Unreadable or half written: it may be a lock being entered right now,
+            // and it names no process, so there is no liveness question to ask about
+            // it. Age may not answer one either (see the constant above), so waiting
+            // is the only safe answer; the attempt budget bounds it and the refusal
+            // names the file.
+            return "busy";
+        }
+        if (probe(held.pid).running)
+            return "busy";
+        // Its process is gone, so it died inside the section. The age says how
+        // long ago that was and decides nothing: a lock five seconds old whose
+        // process is alive is a slow reclaim, and evicting it is how two holders
+        // happen.
+        const age = Date.now() - held.at;
+        options.note?.(`a telegram transport reclaim lock left by pid ${String(held.pid)} ${String(Math.max(age, 0))}ms ago has no process behind it; evicted`);
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* somebody else cleared it first, which is the same outcome */
+        }
+        return "busy";
+    }
+    try {
+        const fresh = readHolderSettled(path);
+        if (fresh.state === "absent") {
+            // The record went away while this process was entering the section: the
+            // holder released it, or another take-over finished. Create rather than
+            // rename, so a fresh taker that got there first is not overwritten.
+            const created = createExclusive(path, body);
+            if (created === "created")
+                return "taken";
+            return created === "exists" ? "changed" : created;
+        }
+        if (expect.kind === "torn") {
+            if (fresh.state !== "torn")
+                return "changed";
+        }
+        else {
+            if (fresh.state !== "held")
+                return "changed";
+            // Identity is the pid AND the instant it wrote, so a reused pid holding
+            // a fresh lease is not mistaken for the dead holder that was judged.
+            if (fresh.holder.pid !== expect.holder.pid)
+                return "changed";
+            if (fresh.holder.startedAt !== expect.holder.startedAt)
+                return "changed";
+        }
+        options.inside?.();
+        // The last thing before the write: is this entry still the one that holds
+        // the section? A process that stalled long enough to be evicted must not
+        // rename over the lease that replaced it.
+        if (!holdsSection(lockPath, pid, nonce))
+            return "busy";
+        const written = writeAtomic(path, body, pid);
+        return written === null ? "taken" : { detail: written };
+    }
+    finally {
+        // Only ours, and only while it is still ours: unlinking unconditionally is
+        // how a stalled process hands the next holder's section to a third.
+        if (holdsSection(lockPath, pid, nonce)) {
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                /* advisory: a lock whose process is gone is evicted by the next taker */
+            }
+        }
+    }
+}
+function leaseFor(path, mode, pid) {
+    let released = false;
+    return {
+        path,
+        mode,
+        pid,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            const read = readHolder(path);
+            if (read.state !== "held" || read.holder.pid !== pid)
+                return;
+            try {
+                unlinkSync(path);
+            }
+            catch {
+                /* advisory: a lease that could not be removed is reclaimed by the next taker's liveness probe */
+            }
+        },
+    };
+}
+//# sourceMappingURL=channel-lease.js.map