@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/lock.js

@@ -0,0 +1,792 @@
+import { randomUUID } from "node:crypto";
+import { linkSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { setTimeout as sleep } from "node:timers/promises";
+import { buildRegisterDocument, casFailureLine, casWrite, ensureEnvironmentId, fleetRootForLockPath, preflightShared, readSharedExclusion, } from "./exclusion.js";
+import { readRegularPathIfPresent } from "./fleet.js";
+/**
+ * Lease-based session lock (kernel plan v1, M1-P3 step 1; DR-0007; plan
+ * constraint C-2). One orchestrator per fleet: the lock file at
+ * state/orchestrator.lock holds a JSON lease {holderId, hostname,
+ * acquiredAt, expiresAt, durationSeconds, token} where holderId is an
+ * opaque value generated at acquire. Liveness is lease freshness only:
+ * this module never probes any running program in any way (FM-053), and
+ * the death of a holder is deliberately invisible to the lease (an
+ * unexpired lease excludes even when its holder is gone; recovery is the
+ * explicit --take-over after expiry).
+ *
+ * Mutation contract (EXT-F-01, adopted verbatim from the plan):
+ * - Every mutation (acquire, renew, release, takeover) goes through the
+ *   ONE shared atomic mutation primitive, applyLeaseMutation. A mutation
+ *   is decided against an observed lease state and applied only if the
+ *   file still holds exactly that state; the application is confirmed by
+ *   re-reading the unique per-mutation token it wrote. A confirmation
+ *   showing another writer's token means the mutation lost and returns
+ *   failure without retry. Ownership is not valid until the primitive
+ *   completes.
+ * - Renew fails on an expired lease and succeeds only while holderId
+ *   matches and expiresAt is in the future.
+ * - Takeover succeeds only if the observed lease is still the lease being
+ *   replaced (compare-and-swap over the lease file content) and
+ *   serializes with renew, release, and competing takeovers.
+ *
+ * Serialization mechanism: mutations are serialized through a claim file
+ * beside the lock (<lock>.mutex, created O_EXCL; FM-022's
+ * serialize-through-a-claim pattern), and inside that claim the primitive
+ * re-reads the lock, byte-compares it with the observed state, applies
+ * via O_EXCL create (absent lock, PR-006) or write-temp-then-rename, and
+ * confirms by re-reading its own token (FM-022 write-then-verify). No
+ * steal protocol exists on purpose (FM-058): a claim file left behind by
+ * a crashed mutation makes later mutations fail loudly after a bounded
+ * wait, naming the file for manual removal; the critical section is a
+ * few file operations, so this window is tiny.
+ *
+ * What the token confirmation is and is NOT (corrected per D-2; the
+ * previous wording here claimed a second safety net that does not
+ * exist). The confirmation read asserts only "my bytes are in the file
+ * now". That is last-writer-wins: it catches an intruder who applied
+ * AFTER this mutation, and it does NOT catch one who applied before and
+ * merely lost the race to write last. The O_EXCL claim file is
+ * therefore the sole serializer, and it is advisory: no handle is held
+ * on it and nothing checks ownership when it is unlinked. The apply is
+ * preceded by a second read-and-compare (stillMatches) so that a lost
+ * claim degrades to a clean loss instead of a double win, but that
+ * narrows the window rather than closing it. Deleting a live claim file
+ * can still produce two holders; that is why the CLI's remedy text now
+ * says so instead of inviting it.
+ *
+ * Exclusion domain (PR-201, DR-0007 stated honestly): the lease excludes
+ * within one filesystem and one clock, the fleet home the lock file lives
+ * in. Mutations of the lock file made outside this module (manual edits)
+ * are not covered by the contract.
+ *
+ * CROSS-ENVIRONMENT EXCLUSION IS A SECOND LAYER ABOVE THIS ONE (M4-P21),
+ * and it is OFF unless the fleet home declares it. When the fleet's own
+ * `package.json` carries `tiphys.sharedExclusion`, every mutation below
+ * first asks `src/exclusion.ts` for a verdict from the shared register on
+ * the fleet's git remote, and only a won verdict reaches the local lease.
+ * With the field ABSENT, `readSharedExclusion` returns before spawning
+ * anything and every path in this module behaves exactly as it did, which
+ * is the property M4-P21 criterion 1 asserts. The refusal never touches the
+ * lock file, which is what makes the fail-closed behaviour on an
+ * unreachable register observable (criterion 7): no local lease appears.
+ *
+ * Renewal discipline (PR-203): the default lease lasts 900 seconds and
+ * the holder renews at or before half-life (renewByMs). Holdership on
+ * mutating kernel commands (spawn, teardown) is verified against the
+ * lease by M1-P4.
+ */
+export const DEFAULT_LEASE_DURATION_SECONDS = 900;
+/** Bounded wait for the mutation claim file, then fail loudly. */
+const MUTEX_WAIT_TOTAL_MS = 5000;
+const MUTEX_WAIT_POLL_MS = 10;
+function parseLease(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    const candidate = parsed;
+    if (typeof candidate.holderId !== "string" ||
+        candidate.holderId === "" ||
+        typeof candidate.hostname !== "string" ||
+        typeof candidate.acquiredAt !== "string" ||
+        typeof candidate.expiresAt !== "string" ||
+        typeof candidate.durationSeconds !== "number" ||
+        typeof candidate.token !== "string" ||
+        Number.isNaN(Date.parse(candidate.expiresAt))) {
+        return undefined;
+    }
+    return candidate;
+}
+export function renderLease(lease) {
+    return `${JSON.stringify(lease, null, 2)}\n`;
+}
+/**
+ * Read the current lock file state: absent, or present with raw bytes.
+ *
+ * THE ENTRY TYPE IS ESTABLISHED BEFORE THE OPEN (T-008's shape in shipped
+ * code). A bare `readFileSync` here blocked FOREVER with zero output on a
+ * named pipe at the lease path, and took `lock status`, `lock acquire`,
+ * `lock renew` and `lock release` with it, while `tiphys doctor` returned in
+ * the same second against the same FIFO with "is a named pipe, not a regular
+ * file, so it was not opened". Two readers of one path, one of which
+ * established the type; this is now the same reader.
+ *
+ * A refusal THROWS rather than returning a fourth `ObservedLease` variant.
+ * The function already threw on every non-ENOENT error, so the contract its
+ * callers were written against is unchanged, and bin/tiphys.ts turns the
+ * throw into one diagnostic line and a nonzero exit.
+ */
+export function observeLease(lockPath) {
+    const read = readRegularPathIfPresent(lockPath);
+    if (read.kind === "absent") {
+        return { kind: "absent" };
+    }
+    if (read.kind === "refused") {
+        throw new Error(read.reason);
+    }
+    return { kind: "present", raw: read.body, lease: parseLease(read.body) };
+}
+/**
+ * THE ONE EXPIRY COMPARISON IN THE KERNEL (M4-P17 criterion 2).
+ *
+ * `isExpired` below needs a whole `Lease`, and doctor's lock check does not
+ * have one: it reads the lease file defensively and holds only `holderId` and
+ * `expiresAt`, because a lease file that fails `parseLease` must still produce
+ * a diagnosis rather than nothing. Before this phase that forced doctor to
+ * carry its own `Date.parse(...) <= Date.now()`, which is a SECOND comparison
+ * of the same property, free to drift from this one. The boundary is where
+ * that drift shows: `<=` makes expiry INCLUSIVE, so a lease whose `expiresAt`
+ * is exactly the current millisecond is expired, and a second copy written
+ * with `<` disagrees for exactly one millisecond and agrees everywhere else.
+ * A disagreement that narrow is not something a reviewer finds by reading.
+ *
+ * So the comparison lives here once and both callers reach it.
+ */
+export function expiryHasPassed(expiresAt, nowMs) {
+    return Date.parse(expiresAt) <= nowMs;
+}
+export function isExpired(lease, nowMs) {
+    return expiryHasPassed(lease.expiresAt, nowMs);
+}
+/** The renew-by deadline (half-life of the current term), for holders. */
+export function renewByMs(lease) {
+    return Date.parse(lease.expiresAt) - (lease.durationSeconds * 1000) / 2;
+}
+/** The same guarded read as observeLease, for the inside of the claim. */
+function readCurrent(lockPath) {
+    const read = readRegularPathIfPresent(lockPath);
+    if (read.kind === "absent") {
+        return { present: false, raw: "" };
+    }
+    if (read.kind === "refused") {
+        throw new Error(read.reason);
+    }
+    return { present: true, raw: read.body };
+}
+/**
+ * Re-read the lock file and re-compare it against the state a mutation
+ * was decided on. Used immediately before every apply (D-2).
+ */
+function stillMatches(lockPath, observed) {
+    const current = readCurrent(lockPath);
+    if (observed.kind === "absent") {
+        return !current.present;
+    }
+    return current.present && current.raw === observed.raw;
+}
+/**
+ * The single staging path a lease rename goes through (CR-202). One
+ * fixed name is safe because staging only ever happens inside the
+ * mutation claim, and it makes strand cleanup deterministic.
+ */
+export function stagePathFor(lockPath) {
+    return `${lockPath}.stage`;
+}
+/**
+ * The one shared atomic mutation primitive (EXT-F-01). Applies next (new
+ * file content, or null to remove the lock) only if the lock file still
+ * holds exactly the observed state, and confirms the application by
+ * re-reading the mutation's own token. Loses without retry otherwise.
+ */
+export async function applyLeaseMutation(lockPath, observed, next, token) {
+    const mutexPath = `${lockPath}.mutex`;
+    const deadline = Date.now() + MUTEX_WAIT_TOTAL_MS;
+    for (;;) {
+        try {
+            writeFileSync(mutexPath, token, { flag: "wx" });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST") {
+                throw error;
+            }
+            if (Date.now() >= deadline) {
+                // CR-204: name the lease situation first, so an operator is not
+                // nudged toward a takeover when the obstacle is a claim file and
+                // there is no lease at all.
+                // The remedy sentence is deliberately NOT part of this reason:
+                // the CLI appends it from the claimTimeout flag, so the
+                // classification is load-bearing at every layer rather than
+                // carried along as prose (CR-204).
+                // U-6: an expired lease is not a held one. Saying "lock held"
+                // here contradicted lock status in the same fleet, which calls
+                // the same lease expired, and reads as "the holder is alive"
+                // when the truth is the opposite.
+                const holder = observed.kind === "present" && observed.lease !== undefined
+                    ? isExpired(observed.lease, Date.now())
+                        ? `expired lease from ${observed.lease.holderId}`
+                        : `lock held by ${observed.lease.holderId}`
+                    : "no lease, no live holder";
+                return {
+                    won: false,
+                    claimTimeout: true,
+                    reason: `${holder}; stale claim file ${mutexPath} blocking after ` +
+                        `${String(MUTEX_WAIT_TOTAL_MS)}ms`,
+                };
+            }
+            await sleep(MUTEX_WAIT_POLL_MS);
+        }
+    }
+    try {
+        // CR-202: clear any stranded stage left by a mutation that died
+        // between its stage write and its rename. This runs inside the
+        // claim, so it provably cannot race a live mutation (a live one
+        // would hold the claim), which is why no age heuristic is needed
+        // or wanted. It is unconditional because the release path (unlink)
+        // and the absent-lock acquire path (O_EXCL create) never touch the
+        // stage: cleaning only in the rename branch would let a strand
+        // survive a release/acquire-only sequence indefinitely.
+        try {
+            unlinkSync(stagePathFor(lockPath));
+        }
+        catch {
+            // No strand present, which is the normal case.
+        }
+        const current = readCurrent(lockPath);
+        if (observed.kind === "absent") {
+            if (current.present) {
+                return {
+                    won: false,
+                    reason: "lost: a lease appeared after this mutation observed none",
+                };
+            }
+        }
+        else if (!current.present) {
+            return {
+                won: false,
+                reason: "lost: the observed lease is gone",
+            };
+        }
+        else if (current.raw !== observed.raw) {
+            return {
+                won: false,
+                reason: "lost: the lease changed after this mutation observed it",
+            };
+        }
+        // D-2: re-read and re-compare immediately before every apply. The
+        // claim file is the ONLY serializer, and it is advisory: no handle
+        // is held on it, and the operator remedy this CLI prints tells a
+        // human to delete it. If a claim is lost that way, another mutation
+        // can enter this section concurrently; without this second compare
+        // both could apply and both could believe they won. With it, the
+        // loser sees changed bytes and degrades to a clean loss. This
+        // narrows the window to the syscall gap; it does not remove it, and
+        // the module docs say so rather than claiming a guarantee.
+        if (!stillMatches(lockPath, observed)) {
+            return {
+                won: false,
+                reason: "lost: the lease changed while this mutation held the claim",
+            };
+        }
+        if (next === null) {
+            unlinkSync(lockPath);
+            const confirm = readCurrent(lockPath);
+            if (confirm.present) {
+                return { won: false, reason: "lost: removal did not stick" };
+            }
+            return { won: true };
+        }
+        if (observed.kind === "absent") {
+            // D-1: publish the initial lease atomically. writeFileSync with
+            // flag "wx" is openSync(O_EXCL) followed by a SEPARATE writeSync,
+            // so the lock file's NAME becomes visible at length zero before
+            // the lease bytes land. observeLease, leaseStatus and doctor all
+            // read outside the claim, so a reader landing in that window sees
+            // an empty file and reports a healthy fleet as corrupt; it turned
+            // acceptance criterion 3's own witness red on pristine code.
+            //
+            // linkSync gives both properties at once: the stage file already
+            // holds the complete lease, and link fails with EEXIST if the
+            // lock path exists, which is exactly the atomic exclusive-create
+            // test PR-006 asks for. So exclusion is preserved and the name
+            // never exists half-published. renew and takeover were already
+            // immune because they stage then rename; this makes the absent
+            // lock path use the same discipline, which is the asymmetry the
+            // module previously left unjustified.
+            const stagePath = stagePathFor(lockPath);
+            /* THE STAGE IS OPENED FOR WRITING and is NOT guarded here, which is a
+               measurement rather than an oversight. open(2) for writing on a FIFO
+               blocks exactly as reading one does, so this looked like a member of
+               the class this round closed. It is not: the claim-held sweep above
+               (CR-202) unlinks `<lock>.stage` UNCONDITIONALLY before either branch
+               writes it, so a planted FIFO is gone by the time this line runs.
+               Measured at this head with a real mkfifo at
+               `state/orchestrator.lock.stage`: `tiphys lock acquire` exits 0 in
+               under a second and the lease is taken. A guard here would therefore
+               be code no witness can redden. */
+            writeFileSync(stagePath, next);
+            try {
+                linkSync(stagePath, lockPath);
+            }
+            catch (error) {
+                if (error.code === "EEXIST") {
+                    return {
+                        won: false,
+                        reason: "lost: a lease appeared after this mutation observed none",
+                    };
+                }
+                throw error;
+            }
+            finally {
+                try {
+                    unlinkSync(stagePath);
+                }
+                catch {
+                    // The stage sweep at the top of the claim also covers this.
+                }
+            }
+        }
+        else {
+            // The stage is ONE fixed path beside the lock (CR-202). Every
+            // stage write happens inside the claim, so no two stages can ever
+            // coexist and a fixed name needs no uniqueness to be safe; the
+            // claim-held sweep above then makes cleanup of a crash strand
+            // deterministic (exactly one possible strand path, removed
+            // unconditionally) instead of an age-based guess over a family of
+            // unique names. The CAS is untouched by this choice: the
+            // byte-compare against the observed state and the token
+            // confirmation read both still happen inside the claim, and the
+            // rename remains atomic within one directory.
+            const stagePath = stagePathFor(lockPath);
+            /* THE STAGE IS OPENED FOR WRITING and is NOT guarded here, which is a
+               measurement rather than an oversight. open(2) for writing on a FIFO
+               blocks exactly as reading one does, so this looked like a member of
+               the class this round closed. It is not: the claim-held sweep above
+               (CR-202) unlinks `<lock>.stage` UNCONDITIONALLY before either branch
+               writes it, so a planted FIFO is gone by the time this line runs.
+               Measured at this head with a real mkfifo at
+               `state/orchestrator.lock.stage`: `tiphys lock acquire` exits 0 in
+               under a second and the lease is taken. A guard here would therefore
+               be code no witness can redden. */
+            writeFileSync(stagePath, next);
+            try {
+                renameSync(stagePath, lockPath);
+            }
+            catch (error) {
+                try {
+                    unlinkSync(stagePath);
+                }
+                catch {
+                    // Stage cleanup is best effort; the original error surfaces.
+                }
+                if (error.code === "ENOENT") {
+                    // Another mutation swept this stage, which means it entered
+                    // the critical section concurrently, which means this claim
+                    // was lost (D-2). Report it as a loss rather than letting a
+                    // raw ENOENT stack out of the CLI.
+                    return {
+                        won: false,
+                        reason: "lost: the staged lease disappeared before it was published, " +
+                            "which means another mutation held the claim concurrently",
+                    };
+                }
+                throw error;
+            }
+        }
+        const confirm = readCurrent(lockPath);
+        const confirmedLease = confirm.present ? parseLease(confirm.raw) : undefined;
+        if (confirmedLease === undefined || confirmedLease.token !== token) {
+            return {
+                won: false,
+                reason: "lost: confirmation read shows another writer's token",
+            };
+        }
+        return { won: true };
+    }
+    finally {
+        try {
+            unlinkSync(mutexPath);
+        }
+        catch {
+            // Claim file already gone; nothing to release.
+        }
+    }
+}
+/**
+ * Resolve the fleet home's declaration. The ONLY entry into the shared
+ * layer, and the only place a fleet root is derived: a lock path is
+ * `<root>/state/orchestrator.lock` (src/fleet.ts:37), so the root is two
+ * directories up unless a caller names it. A declaration that is present
+ * and unusable is reported rather than treated as absent, because reading a
+ * typo as "off" is the failure that would make this layer green everywhere.
+ */
+function sharedGate(lockPath, fleetRoot) {
+    const root = fleetRoot ?? fleetRootForLockPath(lockPath);
+    const declaration = readSharedExclusion(root);
+    if (declaration.kind === "absent") {
+        return { kind: "off" };
+    }
+    if (declaration.kind === "invalid") {
+        return { kind: "invalid", reason: declaration.reason };
+    }
+    const identity = ensureEnvironmentId(root);
+    return {
+        kind: "on",
+        ctx: { config: declaration.config, envId: identity.envId, fleetRoot: root },
+    };
+}
+function invalidDeclarationOutcome(reason) {
+    return {
+        ok: false,
+        reason: `shared exclusion is declared and unusable, refusing rather than running ` +
+            `local-only: ${reason}`,
+    };
+}
+/** Ask the shared register for a verdict, without touching anything. */
+function sharedPreflight(ctx, intent, takeover, nowMs) {
+    return preflightShared({
+        fleetRoot: ctx.fleetRoot,
+        config: ctx.config,
+        envId: ctx.envId,
+        intent,
+        takeover,
+        nowMs,
+    });
+}
+function sharedNote(ctx, preflight) {
+    return { line: preflight.line, envId: ctx.envId };
+}
+/**
+ * Publish the won verdict to the register. Called only AFTER the local
+ * mutation succeeded, so the two layers agree or the local one is rolled
+ * back by the caller: a register entry with no local lease behind it would
+ * exclude every environment including the one that wrote it.
+ */
+function sharedCommit(ctx, preflight, state, nowMs, durationSeconds) {
+    const document = buildRegisterDocument({
+        state,
+        envId: ctx.envId,
+        counter: preflight.nextCounter,
+        nowMs,
+        durationSeconds,
+        ref: ctx.config.ref,
+        ...(preflight.current !== undefined && state === "held" && !preflight.takingOver
+            ? { acquiredAt: preflight.current.acquiredAt }
+            : {}),
+    });
+    const outcome = casWrite(ctx.fleetRoot, ctx.config, preflight.expectedSha, document);
+    if (outcome.kind === "won") {
+        return { ok: true, sha: outcome.sha };
+    }
+    return { ok: false, reason: casFailureLine(ctx.config.ref, outcome) };
+}
+/**
+ * UNDO A LOCAL LEASE MUTATION WHOSE REGISTER PUBLISH LOST.
+ *
+ * `current` is what the lock file holds NOW (the state this mutation left),
+ * and `restore` is the observation the mutation was decided against, whose
+ * raw bytes are written back verbatim so the restored file is BYTE-IDENTICAL
+ * to the one the command claimed not to have changed.
+ *
+ * The token handed to the primitive is the RESTORED lease's own token, not a
+ * fresh one: the primitive confirms an application by re-reading the token in
+ * the file it just wrote, and a fresh token would fail that confirmation
+ * against bytes that carry the old one.
+ *
+ * Returns the sentence appended to the failure line. A rollback that ITSELF
+ * loses is stated rather than swallowed, because "the local lease was
+ * restored" is a claim a later reader will act on.
+ */
+async function restoreLocal(lockPath, current, restore) {
+    if (restore.lease === undefined) {
+        return "; the local lease could NOT be restored: the observed lease does not parse";
+    }
+    const undone = await applyLeaseMutation(lockPath, current, restore.raw, restore.lease.token);
+    return undone.won
+        ? "; the local lease was restored"
+        : `; the local lease could NOT be restored (${undone.reason}), so ${lockPath} and the register now disagree`;
+}
+function buildLease(nowMs, durationSeconds) {
+    return {
+        holderId: randomUUID(),
+        hostname: hostname(),
+        acquiredAt: new Date(nowMs).toISOString(),
+        expiresAt: new Date(nowMs + durationSeconds * 1000).toISOString(),
+        durationSeconds,
+        token: randomUUID(),
+    };
+}
+/**
+ * Acquire the lease, or take over an expired one when takeover is set.
+ * Refusals (lock held, expired without takeover, unexpired takeover)
+ * never mutate the file; only won mutations do.
+ */
+export async function acquireLease(lockPath, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const durationSeconds = options.durationSeconds ?? DEFAULT_LEASE_DURATION_SECONDS;
+    /* THE SHARED LAYER RUNS FIRST AND MUTATES NOTHING (M4-P21 criteria 1 and
+       7). Off unless declared, so the read below is the whole cost for every
+       fleet that has not opted in. A refusal returns here, before the local
+       lease file can be created, which is the fail-closed property: an
+       unreachable register leaves no local lock behind to be mistaken for
+       exclusion that is not there. */
+    const gate = sharedGate(lockPath, options.fleetRoot);
+    if (gate.kind === "invalid") {
+        return invalidDeclarationOutcome(gate.reason);
+    }
+    let preflight;
+    if (gate.kind === "on") {
+        preflight = sharedPreflight(gate.ctx, "acquire", options.takeover === true, nowMs);
+        if (preflight.kind === "refused") {
+            return {
+                ok: false,
+                reason: preflight.line,
+                shared: sharedNote(gate.ctx, preflight),
+            };
+        }
+    }
+    const observed = options.observed ?? observeLease(lockPath);
+    if (observed.kind === "present") {
+        if (observed.lease === undefined) {
+            return {
+                ok: false,
+                reason: `lease file ${lockPath} is corrupt; inspect it manually`,
+            };
+        }
+        if (!isExpired(observed.lease, nowMs)) {
+            return {
+                ok: false,
+                reason: options.takeover === true
+                    ? `takeover refused: lock held by ${observed.lease.holderId}, unexpired until ${observed.lease.expiresAt}`
+                    : `lock held by ${observed.lease.holderId}, expires ${observed.lease.expiresAt}`,
+            };
+        }
+        if (options.takeover !== true) {
+            return {
+                ok: false,
+                reason: `lease expired (holder ${observed.lease.holderId}, expired ` +
+                    `${observed.lease.expiresAt}); acquire refused, takeover is ` +
+                    `explicit: lock acquire --take-over`,
+            };
+        }
+    }
+    const lease = buildLease(nowMs, durationSeconds);
+    const result = await applyLeaseMutation(lockPath, observed, renderLease(lease), lease.token);
+    if (!result.won) {
+        // CR-204: a claim-file timeout is not a held lease. Its reason
+        // already states the lease situation, so it is never re-prefixed
+        // with "lock held", and the classification travels to the caller.
+        if (result.claimTimeout === true) {
+            return { ok: false, reason: result.reason, claimTimeout: true };
+        }
+        return { ok: false, reason: `lock held (${result.reason})` };
+    }
+    if (gate.kind === "on" && preflight !== undefined && preflight.kind === "proceed") {
+        const published = sharedCommit(gate.ctx, preflight, "held", nowMs, durationSeconds);
+        if (!published.ok) {
+            /* The register refused after the local lease was written, so the local
+               lease is rolled back through the SAME mutation primitive. Leaving it
+               would make this environment believe it holds a fleet another
+               environment holds, which is the exact state this layer exists to
+               prevent. */
+            await applyLeaseMutation(lockPath, { kind: "present", raw: renderLease(lease), lease }, null, randomUUID());
+            const line = `shared exclusion refused acquire: ${published.reason}; the local lease was rolled back`;
+            return {
+                ok: false,
+                reason: line,
+                shared: { line, envId: gate.ctx.envId },
+            };
+        }
+        return {
+            ok: true,
+            lease,
+            shared: {
+                line: `${preflight.line}; register now ${published.sha}`,
+                envId: gate.ctx.envId,
+            },
+        };
+    }
+    return { ok: true, lease };
+}
+/**
+ * Renew the lease held by holderId. Fails on an expired lease even when
+ * holderId matches (EXT-F-01: a paused holder whose lease expired cannot
+ * renew), fails on a holder mismatch, and never mutates the file on any
+ * failure. The new expiry strictly increases (a renew that does not
+ * extend the lease would be useless).
+ */
+export async function renewLease(lockPath, holderId, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const gate = sharedGate(lockPath, options.fleetRoot);
+    if (gate.kind === "invalid") {
+        return invalidDeclarationOutcome(gate.reason);
+    }
+    let preflight;
+    if (gate.kind === "on") {
+        preflight = sharedPreflight(gate.ctx, "renew", false, nowMs);
+        if (preflight.kind === "refused") {
+            return {
+                ok: false,
+                reason: preflight.line,
+                shared: sharedNote(gate.ctx, preflight),
+            };
+        }
+    }
+    const observed = options.observed ?? observeLease(lockPath);
+    if (observed.kind === "absent") {
+        return { ok: false, reason: "renew refused: no lease present" };
+    }
+    if (observed.lease === undefined) {
+        return {
+            ok: false,
+            reason: `lease file ${lockPath} is corrupt; inspect it manually`,
+        };
+    }
+    if (observed.lease.holderId !== holderId) {
+        return {
+            ok: false,
+            reason: `renew refused: lease is held by ${observed.lease.holderId}, not ${holderId}`,
+        };
+    }
+    if (isExpired(observed.lease, nowMs)) {
+        return {
+            ok: false,
+            reason: `renew refused: lease expired ${observed.lease.expiresAt}; an ` +
+                `expired lease cannot be renewed, re-acquire or take over instead`,
+        };
+    }
+    const durationSeconds = options.durationSeconds ?? observed.lease.durationSeconds;
+    const newExpiresMs = Math.max(nowMs + durationSeconds * 1000, Date.parse(observed.lease.expiresAt) + 1);
+    const lease = {
+        ...observed.lease,
+        expiresAt: new Date(newExpiresMs).toISOString(),
+        durationSeconds,
+        token: randomUUID(),
+    };
+    const result = await applyLeaseMutation(lockPath, observed, renderLease(lease), lease.token);
+    if (!result.won) {
+        if (result.claimTimeout === true) {
+            return { ok: false, reason: result.reason, claimTimeout: true };
+        }
+        return { ok: false, reason: `renew ${result.reason}` };
+    }
+    if (gate.kind === "on" && preflight !== undefined && preflight.kind === "proceed") {
+        /* A RENEW ADVANCES THE FENCING COUNTER, and that is the whole of what
+           makes another environment's staleness judgement safe under clock skew
+           (criterion 5). The observer sees an increment, never a timestamp. */
+        const published = sharedCommit(gate.ctx, preflight, "held", nowMs, durationSeconds);
+        if (!published.ok) {
+            /* THE LOCAL LAYER IS ROLLED BACK, exactly as acquire's failure arm
+               does it and through the SAME primitive. src/lock.ts:537 states the
+               invariant: the two layers agree, or the local one is undone by the
+               caller. Until this round `acquireLease` was the only one of the
+               three publishing callers that honoured it, so a failed renew
+               reported failure while the lease file had ALREADY been extended
+               under a new token, and a failed release reported failure while the
+               lease file had already been DELETED. */
+            const line = `shared exclusion refused renew: ${published.reason}${await restoreLocal(lockPath, { kind: "present", raw: renderLease(lease), lease }, observed)}`;
+            return {
+                ok: false,
+                reason: line,
+                shared: { line, envId: gate.ctx.envId },
+            };
+        }
+        return {
+            ok: true,
+            lease,
+            shared: {
+                line: `${preflight.line}; register now ${published.sha}`,
+                envId: gate.ctx.envId,
+            },
+        };
+    }
+    return { ok: true, lease };
+}
+/**
+ * Release the lease held by holderId. Expiry does not block a release
+ * (an expired former holder may clean up its own lease), but a holder
+ * mismatch refuses, so a losing holder can never remove the winner's
+ * lease; and the compare-and-swap in the primitive means a release
+ * staged before a takeover completes loses to it.
+ */
+export async function releaseLease(lockPath, holderId, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const gate = sharedGate(lockPath, options.fleetRoot);
+    if (gate.kind === "invalid") {
+        return invalidDeclarationOutcome(gate.reason);
+    }
+    let preflight;
+    if (gate.kind === "on") {
+        /* CRITERION 8. A release by a non-holder is refused HERE, before any
+           write, so the register sha is byte-identical before and after. The
+           refusal is the register's own comparison, not a local one: a clone
+           whose local lease says it holds the fleet still loses to a register
+           that names another environment. */
+        preflight = sharedPreflight(gate.ctx, "release", false, nowMs);
+        if (preflight.kind === "refused") {
+            return {
+                ok: false,
+                reason: preflight.line,
+                shared: sharedNote(gate.ctx, preflight),
+            };
+        }
+    }
+    const observed = options.observed ?? observeLease(lockPath);
+    if (observed.kind === "absent") {
+        return { ok: false, reason: "release refused: no lease present" };
+    }
+    if (observed.lease === undefined) {
+        return {
+            ok: false,
+            reason: `lease file ${lockPath} is corrupt; inspect it manually`,
+        };
+    }
+    if (observed.lease.holderId !== holderId) {
+        return {
+            ok: false,
+            reason: `release refused: lease is held by ${observed.lease.holderId}, not ${holderId}`,
+        };
+    }
+    const result = await applyLeaseMutation(lockPath, observed, null, randomUUID());
+    if (!result.won) {
+        if (result.claimTimeout === true) {
+            return { ok: false, reason: result.reason, claimTimeout: true };
+        }
+        return { ok: false, reason: `release ${result.reason}` };
+    }
+    if (gate.kind === "on" && preflight !== undefined && preflight.kind === "proceed") {
+        const published = sharedCommit(gate.ctx, preflight, "free", nowMs, observed.lease.durationSeconds);
+        if (!published.ok) {
+            /* See renewLease above: the local lease was REMOVED before this
+               publish was attempted, and the holdership guard keys on that file's
+               PRESENCE, so leaving it removed reopens the dual-writer window
+               M1-P4 criterion 12 closed. */
+            const line = `shared exclusion could not publish the release: ${published.reason}${await restoreLocal(lockPath, { kind: "absent" }, observed)}`;
+            return {
+                ok: false,
+                reason: line,
+                shared: { line, envId: gate.ctx.envId },
+            };
+        }
+        return {
+            ok: true,
+            lease: null,
+            shared: {
+                line: `${preflight.line}; register now ${published.sha}`,
+                envId: gate.ctx.envId,
+            },
+        };
+    }
+    return { ok: true, lease: null };
+}
+/** Report the lock state; reading only, never mutating (always safe). */
+export function leaseStatus(lockPath, nowMs = Date.now()) {
+    const observed = observeLease(lockPath);
+    if (observed.kind === "absent") {
+        return { state: "free" };
+    }
+    if (observed.lease === undefined) {
+        return {
+            state: "corrupt",
+            detail: `lease file ${lockPath} does not parse as a lease`,
+        };
+    }
+    return {
+        state: isExpired(observed.lease, nowMs) ? "expired" : "held",
+        lease: observed.lease,
+    };
+}