pi-session-mcp 0.11.9 → 0.12.0

package/.pi-session-mcp-cli/doctor.js

@@ -6,6 +6,7 @@ import { createProcessRunner } from "./setup-process.js";
 import { podmanInfo, isSafeRefName } from "./writer-boundary.js";
 import { containedBuiltinSkills, containedProfileRefused } from "./writer-lifecycle.js";
 import { readWriterState, writerAcceptanceCurrent, writerName, writerPaths } from "./writer-state.js";
+import { LEASE_DIRECTORY } from "./writer-lease.js";
 import { loadConfig } from "./config.js";
 import { containerRuntimeUsable } from "./container-runtime.js";
 import { PiExtensionError } from "./extension-spec.js";
@@ -31,7 +32,7 @@ async function readPrefix(path, maxBytes) {
     }
 }
 const defaultFileSystem = { readFile, stat, access };
-const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "workspace_gitfile", "workspace_mode_unset", "workspace_host_writes_accepted", "container_runtime_unavailable", "container_profile_refused", "writer_not_ready", "writer_dirty", "writer_uncollected_bundle", "extension_missing", "extension_version_mismatch", "extension_unpinned", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated", "event_spool_root"];
+const CHECK_ORDER = ["node_version_unsupported", "package_metadata_unreadable", "build_missing", "build_stale", "version_mismatch", "config_missing", "config_unreadable", "config_invalid", "workspace_missing", "workspace_not_directory", "workspace_unreadable", "workspace_not_writable", "workspace_gitfile", "workspace_mode_unset", "workspace_base_unset", "workspace_host_writes_accepted", "container_runtime_unavailable", "container_profile_refused", "writer_lease_directory", "writer_not_ready", "writer_not_migrated", "writer_off_default_base", "writer_dirty", "writer_git_identity_missing", "writer_uncollected_bundle", "extension_missing", "extension_version_mismatch", "extension_unpinned", "skill_missing", "skill_unreadable", "skill_duplicate", "skill_override_outdated", "event_spool_root"];
 function failure(id, subject, remediation) { return Object.freeze({ id, severity: "error", subject, remediation }); }
 function warning(id, subject, remediation) { return Object.freeze({ id, severity: "warning", subject, remediation }); }
 function ok(id, subject) { return Object.freeze({ id, severity: "ok", subject }); }
@@ -147,7 +148,7 @@ async function hasGitfilePointer(fs, workspace) {
         return false;
     }
 }
-async function defaultEventSpoolRoot(path) {
+async function defaultRootInfo(path) {
     try {
         const info = await lstat(path);
         return { isDirectory: info.isDirectory(), uid: info.uid, mode: info.mode };
@@ -158,6 +159,30 @@ async function defaultEventSpoolRoot(path) {
         throw error;
     }
 }
+/**
+ * Offline check of the host-only writer lease directory. A missing directory is fine because the
+ * first lease creates it. An existing entry must be a real directory of the current user with mode
+ * 0700: the rule `acquireWriterLease` applies before it opens a lease file. Nothing is created,
+ * repaired or read, and no path or lease file name appears in the report.
+ */
+async function writerLeaseCheck(home, probe, uid) {
+    let info;
+    try {
+        info = await probe(join(home, ...LEASE_DIRECTORY));
+    }
+    catch {
+        return failure("writer_lease_directory", "writer lease", "grant access to the writer lease directory");
+    }
+    if (info === undefined)
+        return undefined;
+    // Lease files must keep their inodes: a moved or recreated directory would let a second holder in.
+    if (!info.isDirectory)
+        return failure("writer_lease_directory", "writer lease", "close every writer session and setup run, then replace the entry with a private directory owned by the current user");
+    if ((uid !== undefined && info.uid !== uid) || (info.mode & 0o7777) !== 0o700) {
+        return failure("writer_lease_directory", "writer lease", "repair the lease directory in place (owner and chmod 700); never move or delete it or its lock files");
+    }
+    return ok("writer_lease_directory", "writer lease");
+}
 /**
  * Offline check of the event spool's runtime directories, run only when event delivery is enabled.
  * Nothing is created or repaired, and no path appears in the report. A missing runtime directory
@@ -208,6 +233,44 @@ async function defaultWriterRuntime() {
             }
         } };
 }
+async function writerGitIdentity(clone) {
+    try {
+        const handle = await open(join(clone, ".git", "config"), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const info = await handle.stat();
+            if (!info.isFile() || info.size > 65_536)
+                return false;
+            const buffer = Buffer.alloc(65_536);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            if ((await handle.stat()).size > 65_536)
+                return false;
+            let user = false, name = false, email = false;
+            for (const line of buffer.subarray(0, bytesRead).toString("utf8").split("\n")) {
+                const section = /^\s*\[([^\]]+)\]/.exec(line);
+                if (section) {
+                    user = section[1].trim().toLowerCase() === "user";
+                    continue;
+                }
+                if (!user)
+                    continue;
+                const key = /^\s*(name|email)\s*=\s*(.*?)\s*$/i.exec(line);
+                if (!key || !key[2] || /^(?:""|[#;])/.test(key[2]))
+                    continue;
+                if (key[1].toLowerCase() === "name")
+                    name = true;
+                else
+                    email = true;
+            }
+            return name && email;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
 async function writerDirty(clone, state) {
     try {
         const git = join(clone, ".git");
@@ -280,6 +343,7 @@ async function writerDirty(clone, state) {
 export async function runDoctor(dependencies = {}) {
     const fs = dependencies.fileSystem ?? defaultFileSystem;
     const root = dependencies.packageRoot ?? process.cwd();
+    const home = dependencies.home ?? homedir();
     const checks = [];
     let metadata;
     try {
@@ -418,9 +482,13 @@ export async function runDoctor(dependencies = {}) {
         let runtime;
         let rawConfig, rawConfigLoaded = false, rawConfigReadable = false;
         let availableBuiltinSkills = new Set();
+        const offDefaultBase = new Map();
         for (const [alias, entry] of config.workspaceModes) {
             if (entry.mode !== "container" || !entry.container)
                 continue;
+            checks.push(entry.container.base === undefined
+                ? warning("workspace_base_unset", alias, `record the workspace default base with pi-session-mcp-setup --repo ${alias} --base <branch> --apply`)
+                : ok("workspace_base_unset", alias));
             if (!rawConfigLoaded) {
                 rawConfigLoaded = true;
                 try {
@@ -445,7 +513,7 @@ export async function runDoctor(dependencies = {}) {
                     checks.push(ok("container_profile_refused", alias));
             }
             for (let index = 1; index <= entry.container.writers; index++) {
-                const name = writerName(alias, index), home = dependencies.home ?? homedir(), paths = writerPaths(home, name);
+                const name = writerName(alias, index), paths = writerPaths(home, name);
                 const remediation = `run pi-session-mcp-setup --repo ${alias} --apply, or --writer ${name} --recreate --apply`;
                 let state, ready = false;
                 try {
@@ -459,6 +527,11 @@ export async function runDoctor(dependencies = {}) {
                 checks.push(ready ? ok("writer_not_ready", name) : failure("writer_not_ready", name, remediation));
                 if (!state)
                     continue;
+                checks.push(state.launch === "relay" ? ok("writer_not_migrated", name)
+                    : warning("writer_not_migrated", name, `run pi-session-mcp-setup --repo ${alias} --apply to migrate the writer to the relay`));
+                if (entry.container.base !== undefined && ready && state.base.ref !== `refs/heads/${entry.container.base}`) {
+                    offDefaultBase.set(alias, (offDefaultBase.get(alias) ?? 0) + 1);
+                }
                 checks.push(await writerDirty(paths.clone, state)
                     ? warning("writer_dirty", name, "collect writer work before resetting or recreating the writer") : ok("writer_dirty", name));
                 let bundles = false;
@@ -471,9 +544,18 @@ export async function runDoctor(dependencies = {}) {
                 catch (error) {
                     bundles = !isMissing(error);
                 }
+                checks.push(await writerGitIdentity(paths.clone) ? ok("writer_git_identity_missing", name)
+                    : warning("writer_git_identity_missing", name, "set user.name and user.email in the operator checkout, then reset the writer"));
                 checks.push(bundles ? warning("writer_uncollected_bundle", name, "collect or review outstanding writer bundles") : ok("writer_uncollected_bundle", name));
             }
         }
+        for (const [alias, entry] of config.workspaceModes) {
+            if (entry.mode !== "container" || !entry.container || entry.container.base === undefined)
+                continue;
+            const count = offDefaultBase.get(alias) ?? 0;
+            checks.push(count === 0 ? ok("writer_off_default_base", alias)
+                : warning("writer_off_default_base", alias, `${count} ${count === 1 ? "writer is" : "writers are"} off the workspace default base; finish each with pi-session-mcp-setup --writer <name> --finish --apply once its work is collected`));
+        }
     }
     if (config) {
         // This advisory check needs positive evidence, like the gitfile check: unreadable or
@@ -546,7 +628,10 @@ export async function runDoctor(dependencies = {}) {
         }
     }
     if (config?.eventDelivery === "spool")
-        checks.push(await eventSpoolCheck(dependencies.env ?? process.env, dependencies.eventSpoolRoot ?? defaultEventSpoolRoot, dependencies.uid ?? process.getuid?.()));
+        checks.push(await eventSpoolCheck(dependencies.env ?? process.env, dependencies.eventSpoolRoot ?? defaultRootInfo, dependencies.uid ?? process.getuid?.()));
+    const lease = await writerLeaseCheck(home, dependencies.writerLeaseRoot ?? defaultRootInfo, dependencies.uid ?? process.getuid?.());
+    if (lease)
+        checks.push(lease);
     if (config)
         checks.push(...await skillOverrideChecks(config.skillOverrideDirectory, shippedSkillsDirectory(dependencies.packageRoot), dependencies.releasedSkillTrees));
     const rank = new Map(CHECK_ORDER.map((id, index) => [id, index]));

package/.pi-session-mcp-cli/execution-modes.js

@@ -3,7 +3,16 @@ import { dirname, join } from "node:path";
 import { z } from "zod";
 import { ConfigError } from "./config.js";
 import { ImmutableMap } from "./execution-profile.js";
+import { isSafeRefName } from "./writer-boundary.js";
 export const EXECUTION_MODES_FILE = "execution-modes.json";
+/** A base is a plain local branch name: safe, not `HEAD`, no ref prefix, no commit ID, at most 200 characters. */
+export function isShortBranchName(value) {
+    return value.length <= 200
+        && isSafeRefName(value)
+        && value !== "HEAD"
+        && !value.startsWith("refs/")
+        && !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(value);
+}
 export function executionModesPath(configPath) {
     return join(dirname(configPath), EXECUTION_MODES_FILE);
 }
@@ -17,7 +26,9 @@ const entrySchema = z.discriminatedUnion("mode", [
         profiles: z.array(z.string()).min(1),
         image: z.union([z.literal("node"), z.string().regex(/^[0-9a-f]{64}$/)]).default("node"),
         network: z.enum(["pasta", "none"]).default("pasta"),
-        cache: z.enum(["none", "go"]).default("none"),
+        cache: z.enum(["none", "go", "uv"]).default("none"),
+        tags: z.enum(["none", "reachable"]).default("none"),
+        base: z.string().refine(isShortBranchName).optional(),
     }).strict(),
 ]);
 export const executionModesSchema = z.object({
@@ -39,9 +50,10 @@ export function resolveExecutionModes(raw, workspaceAliases, profiles) {
                     throw new ConfigError("invalid_execution_modes");
                 }
             }
-            const { mode, ...settings } = entry;
+            const { mode, base, ...settings } = entry;
             entries.set(alias, Object.freeze({ mode, container: Object.freeze({
                     ...settings, profiles: Object.freeze([...settings.profiles]),
+                    ...(base === undefined ? {} : { base }),
                 }) }));
         }
         else {
@@ -66,6 +78,6 @@ export async function loadExecutionModes(configPath, workspaceAliases, profiles)
     }
     return resolveExecutionModes(raw, workspaceAliases, profiles);
 }
-export function codingAllowed(entry) {
-    return entry.mode === "unset" || entry.mode === "host";
+export function codingAllowed(entry, relay) {
+    return entry.mode === "unset" || entry.mode === "host" || (entry.mode === "container" && relay);
 }

package/.pi-session-mcp-cli/override-lock.js

@@ -72,7 +72,7 @@ export async function acquireOverrideLock(overrideDirectory, options = {}) {
         },
     };
 }
-function flockBinary(options) {
+export function flockBinary(options) {
     const trusted = options.isTrustedBinary ?? ((path) => isTrustedSystemBinary(path));
     return (options.flockCandidates ?? FLOCK_CANDIDATES).find((candidate) => trusted(candidate));
 }
@@ -86,7 +86,7 @@ async function openLockFile(lockPath, platform, timeoutMs, signal) {
         throw new OverrideLockError(error.message === "ownership_lock_busy" ? "override_lock_busy" : "override_lock_unavailable");
     }
 }
-function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
+export function lockWithFlock(flockPath, lockFd, timeoutMs, signal, nonBlocking = false) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
             reject(new OverrideLockError("override_lock_unavailable"));
@@ -97,7 +97,7 @@ function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
             // flock parses fractional seconds with the locale's decimal separator, so only whole
             // seconds go on the command line. The exact bound is the timer below, which stops flock.
             const wholeSeconds = String(Math.max(1, Math.ceil(timeoutMs / 1_000)));
-            locker = spawn(flockPath, ["-E", String(FLOCK_BUSY_EXIT), "-w", wholeSeconds, "3"], { stdio: ["ignore", "ignore", "ignore", lockFd], detached: true });
+            locker = spawn(flockPath, ["-E", String(FLOCK_BUSY_EXIT), ...(nonBlocking ? ["-n"] : ["-w", wholeSeconds]), "3"], { stdio: ["ignore", "ignore", "ignore", lockFd], detached: true });
         }
         catch {
             reject(new OverrideLockError("override_lock_unavailable"));
@@ -111,7 +111,7 @@ function lockWithFlock(flockPath, lockFd, timeoutMs, signal) {
             catch { /* already gone */ }
         } };
         const cleanup = () => { clearTimeout(bound); signal?.removeEventListener("abort", stop); };
-        const bound = setTimeout(() => { expired = true; stop(); }, timeoutMs);
+        const bound = nonBlocking ? undefined : setTimeout(() => { expired = true; stop(); }, timeoutMs);
         signal?.addEventListener("abort", stop, { once: true });
         locker.once("error", () => { cleanup(); reject(new OverrideLockError("override_lock_unavailable")); });
         locker.once("close", (code) => {

package/.pi-session-mcp-cli/setup-process.js

@@ -56,7 +56,7 @@ export function createProcessRunner(options = {}) {
             if (!table)
                 return { exitCode: 126, stdout: "", stderr: "" };
             return new Promise((resolve) => {
-                const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe"], env: runOptions?.env ? { ...(options.env ?? process.env), ...runOptions.env } : options.env, cwd: runOptions?.cwd, detached: process.platform !== "win32" });
+                const child = spawn(command, [...args], { stdio: ["ignore", "pipe", "pipe", ...(runOptions?.inheritFds ?? [])], env: runOptions?.env ? { ...(options.env ?? process.env), ...runOptions.env } : options.env, cwd: runOptions?.cwd, detached: process.platform !== "win32" });
                 let stdout = "";
                 let stderr = "";
                 let overflow = false;
@@ -132,9 +132,9 @@ export function createProcessRunner(options = {}) {
         } };
 }
 /** Generalized bounded stdio transport for a generated writer wrapper. */
-export function createCommandMcpStdioLauncher(command, env) {
+export function createCommandMcpStdioLauncher(command, env, options) {
     return async (signal) => {
-        const child = spawn(command[0], command.slice(1), { stdio: ["pipe", "pipe", "pipe"], env, detached: process.platform !== "win32" });
+        const child = spawn(command[0], command.slice(1), { stdio: ["pipe", "pipe", "pipe", ...(options?.inheritFds ?? [])], env, detached: process.platform !== "win32" });
         let buffer = "", closed = false, overflow = false;
         child.stdout.on("data", (chunk) => { if (!overflow) {
             buffer += chunk.toString("utf8");
@@ -415,7 +415,8 @@ export async function acquireSetupGuardian(lockFd, timeoutMs, signal, validateFe
     } });
     const runner = {
         run(command, args, runSignal, runOptions) {
-            if (runOptions?.env !== undefined || released || unsafe || pending || runSignal?.aborted || !child.connected)
+            // The guardian child cannot pass descriptors through; refuse instead of dropping a caller's lease.
+            if (runOptions?.env !== undefined || runOptions?.inheritFds !== undefined || released || unsafe || pending || runSignal?.aborted || !child.connected)
                 return Promise.resolve({ exitCode: 126, stdout: "", stderr: "" });
             const id = nextId++;
             return new Promise((resolve) => {

package/.pi-session-mcp-cli/writer-boundary.js

@@ -1,8 +1,9 @@
 import { constants } from "node:fs";
 import { chmod, lstat, mkdir, open, opendir, readdir, rmdir, unlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { DEFAULT_COMMAND_TIMEOUT_MS } from "./client-adapters/command.js";
 import { CONTAINER_EVENTS_DIR, EVENTS_DIR_ENV, writerEventsDir } from "./turn-events.js";
+import { writerContainerName, writerLabel } from "./writer-fence.js";
 export const NODE_IMAGE_REF = "docker.io/library/node@sha256:c4d5523090a817b7aa86d2111241fdd4f66d1e27782b44160e6aa63b357ecb2d";
 export const IMAGE_PULL_TIMEOUT_MS = 900_000;
 export const BOUNDARY_GIT = "git -c safe.directory=* -c core.fsmonitor=false -c core.hooksPath=/dev/null";
@@ -15,10 +16,11 @@ export class BoundaryError extends Error {
     }
 }
 /** `eventsDir` is the dedicated host spool directory of this writer; pass it only when event delivery is enabled for the writer. */
-export function serveArgs(paths, state, command, releaseRoot, eventsDir) {
+export function serveArgs(paths, state, command, releaseRoot, eventsDir, options) {
     const args = [
         "run", "-i", "--rm", "--pull=never", "--userns=keep-id", "--read-only",
         "--cap-drop=all", "--security-opt=no-new-privileges", `--network=${state.network}`,
+        "--label", writerLabel(options?.name ?? basename(paths.root)),
         "--tmpfs", "/tmp:rw,nosuid,nodev,size=512m",
         "--tmpfs", "/pi/home:rw,nosuid,nodev,mode=0700,size=64m,U",
         "-v", `${paths.clone}:${paths.clone}:rw`,
@@ -33,10 +35,14 @@ export function serveArgs(paths, state, command, releaseRoot, eventsDir) {
         "-e", "PI_CODING_AGENT_DIR=/pi/agent",
         "-e", "PI_SESSION_MCP_WRITER_GUARD=/pi/config/writer-guard.json",
     ];
+    if (options?.name !== undefined)
+        args.push("--name", writerContainerName(options.name));
     if (eventsDir !== undefined)
         args.push("-v", `${eventsDir}:${CONTAINER_EVENTS_DIR}:rw`, "-e", `${EVENTS_DIR_ENV}=${CONTAINER_EVENTS_DIR}`);
     if (state.cache === "go")
         args.push("-v", `${paths.go}:/pi/go:rw`, "-e", "GOPATH=/pi/go", "-e", "GOCACHE=/pi/go/cache", "-e", "GOTOOLCHAIN=local");
+    if (state.cache === "uv")
+        args.push("-v", `${paths.uv}:/pi/uv:rw`, "-e", "UV_CACHE_DIR=/pi/uv/cache", "-e", "npm_config_cache=/pi/uv/npm");
     return [...args, state.imageId, ...command];
 }
 export class EventsDirectoryError extends Error {
@@ -225,10 +231,10 @@ export async function ensureWriterEventsDirectory(home, name, uid, now = Date.no
     }
     return target;
 }
-export function throwawayArgs(paths, imageId, opts, script, args) {
+export function throwawayArgs(name, paths, imageId, opts, script, args) {
     const result = [
         "run", "--rm", "-i", "--pull=never", "--network=none", "--userns=keep-id", "--read-only",
-        "--cap-drop=all", "--security-opt=no-new-privileges",
+        "--cap-drop=all", "--security-opt=no-new-privileges", "--label", writerLabel(name),
         "--tmpfs", "/tmp:rw,nosuid,nodev,size=1g", "-e", "HOME=/tmp",
         "-v", `${paths.clone}:${paths.clone}:${opts.clone}`,
         "--workdir", paths.clone,

package/.pi-session-mcp-cli/writer-fence.js

@@ -0,0 +1,50 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { BoundaryError } from "./writer-boundary.js";
+export const FENCE_STOP_TIMEOUT_MS = 20_000;
+const containersSchema = z.array(z.object({ Id: z.string().min(1), Names: z.array(z.string()) }));
+export function writerContainerName(name) { return `pi-writer-${name}`; }
+export function writerLabel(name) { return `pi-session-mcp.writer=${name}`; }
+/** The caller holds the lease; no writer data may change until both inventories are empty. */
+export async function ensureWriterAbsent(runner, paths, name, options) {
+    try {
+        const timeoutMs = options.stopTimeoutMs ?? FENCE_STOP_TIMEOUT_MS;
+        if (process.platform !== "linux" || !Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+            throw new BoundaryError("writer_fenced");
+        const deadline = performance.now() + timeoutMs;
+        const remaining = () => {
+            const left = Math.ceil(deadline - performance.now());
+            if (left <= 0)
+                throw new BoundaryError("writer_fenced");
+            return left;
+        };
+        const podman = async (args) => {
+            const result = await runner.run("podman", args, AbortSignal.timeout(remaining()), { inheritFds: [options.leaseFd] });
+            remaining();
+            if (result.exitCode !== 0 || result.stderr === "output_limit")
+                throw new BoundaryError("writer_fenced");
+            return result.stdout;
+        };
+        const list = async (filter) => containersSchema.parse(JSON.parse(await podman(["ps", "-a", "--filter", filter, "--format", "json"])));
+        const removed = new Set();
+        for (;;) {
+            const labelled = await list(`label=${writerLabel(name)}`);
+            // Podman's volume filter matches the mount destination; every writer container, old releases
+            // included, mounts the clone at its own host path, so this also finds unlabelled ones.
+            const mounted = await list(`volume=${paths.clone}`);
+            const ids = new Set([...labelled, ...mounted].map((container) => container.Id));
+            if (ids.size === 0)
+                return;
+            for (const id of ids) {
+                if (removed.has(id))
+                    continue;
+                await podman(["rm", "-f", "-t", String(Math.ceil(remaining() / 1000)), id]);
+                removed.add(id);
+            }
+            await delay(Math.min(100, remaining()));
+        }
+    }
+    catch {
+        throw new BoundaryError("writer_fenced");
+    }
+}

package/.pi-session-mcp-cli/writer-lease.js

@@ -0,0 +1,140 @@
+import { close, constants, fstat } from "node:fs";
+import { chmod, lstat, mkdir, open } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { flockBinary, lockWithFlock, OverrideLockError } from "./override-lock.js";
+import { assertSupportedFilesystem } from "./setup-platform.js";
+import { WRITER_NAME_PATTERN } from "./writer-state.js";
+export const LEASE_DIRECTORY = [".local", "state", "pi-session-mcp", "leases"];
+export class WriterLeaseError extends Error {
+    code;
+    constructor(code) {
+        super("Writer lease is not available");
+        this.code = code;
+        this.name = "WriterLeaseError";
+    }
+}
+export function writerLeasePath(home, name) {
+    if (!WRITER_NAME_PATTERN.test(name))
+        throw new WriterLeaseError("writer_lease_unavailable");
+    return join(home, ...LEASE_DIRECTORY, `${name}.lock`);
+}
+function checkFile(file) {
+    if (!file.isFile() || file.uid !== process.getuid() || (file.mode & 0o7777) !== 0o600) {
+        throw new WriterLeaseError("writer_lease_unavailable");
+    }
+}
+async function checkPath(path, descriptor) {
+    checkFile(descriptor);
+    const linked = await lstat(path);
+    checkFile(linked);
+    if (descriptor.dev !== linked.dev || descriptor.ino !== linked.ino)
+        throw new WriterLeaseError("writer_lease_unavailable");
+}
+async function prepare(home, name, options, create) {
+    if (process.platform !== "linux" || options.signal?.aborted)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    const path = writerLeasePath(home, name);
+    const binary = flockBinary(options);
+    if (!binary)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    const directory = join(home, ...LEASE_DIRECTORY);
+    // The umask may narrow the requested modes; a directory this call created gets its exact mode.
+    if (create && await mkdir(directory, { recursive: true, mode: 0o700 }) !== undefined)
+        await chmod(directory, 0o700);
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.uid !== process.getuid() || (info.mode & 0o7777) !== 0o700)
+        throw new WriterLeaseError("writer_lease_unavailable");
+    await assertSupportedFilesystem(directory, "linux", options.readStatfs);
+    return { path, binary };
+}
+/** Creates the file exclusively and sets its exact mode, or opens the existing one; never follows a link. */
+async function openLeaseFile(path) {
+    try {
+        const created = await open(path, constants.O_NOFOLLOW | constants.O_CREAT | constants.O_EXCL | constants.O_RDWR, 0o600);
+        try {
+            await created.chmod(0o600);
+        }
+        catch (error) {
+            await created.close().catch(() => undefined);
+            throw error;
+        }
+        return created;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return open(path, constants.O_NOFOLLOW | constants.O_RDWR);
+    }
+}
+function lease(fd, closeDescriptor) {
+    let released = false;
+    return {
+        fd,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            // Never unlock explicitly: mutating children can still hold this open file description.
+            await closeDescriptor().catch(() => undefined);
+        },
+    };
+}
+export async function acquireWriterLease(home, name, options) {
+    let handle;
+    try {
+        if (!Number.isFinite(options.waitMs) || options.waitMs < 0)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        const { path, binary } = await prepare(home, name, options, true);
+        handle = await openLeaseFile(path);
+        checkFile(await handle.stat());
+        await lockWithFlock(binary, handle.fd, options.waitMs, options.signal, options.waitMs === 0);
+        await checkPath(path, await handle.stat());
+        const held = handle;
+        return lease(held.fd, () => held.close());
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        throw new WriterLeaseError(error instanceof OverrideLockError && error.code === "override_lock_busy" ? "writer_busy" : "writer_lease_unavailable");
+    }
+}
+/**
+ * Adopts a descriptor a parent passed down while it holds the lease. A fresh open must find the
+ * lock busy before the descriptor is touched; if the holder released in between, the descriptor's
+ * own `flock -n` takes the lock instead, which still leaves exactly one exclusive holder. Adopt the
+ * same descriptor once: `release()` closes that descriptor number.
+ */
+export async function adoptInheritedLease(home, name, fd, options = {}) {
+    let probe;
+    try {
+        if (!Number.isInteger(fd) || fd < 0)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        const { path, binary } = await prepare(home, name, options, false);
+        await checkPath(path, await promisify(fstat)(fd));
+        probe = await open(path, constants.O_NOFOLLOW | constants.O_RDWR);
+        await checkPath(path, await probe.stat());
+        // A fresh open must be excluded BEFORE touching the inherited description; otherwise
+        // flock on an unlocked inherited fd would itself acquire a lock and falsely prove ownership.
+        let busy = false;
+        try {
+            await lockWithFlock(binary, probe.fd, 0, options.signal, true);
+        }
+        catch (error) {
+            if (!(error instanceof OverrideLockError) || error.code !== "override_lock_busy")
+                throw error;
+            busy = true;
+        }
+        if (!busy)
+            throw new WriterLeaseError("writer_lease_unavailable");
+        await lockWithFlock(binary, fd, 0, options.signal, true);
+        await checkPath(path, await promisify(fstat)(fd));
+        return lease(fd, () => promisify(close)(fd));
+    }
+    catch {
+        // Rejection does not take ownership of the caller's descriptor.
+        throw new WriterLeaseError("writer_lease_unavailable");
+    }
+    finally {
+        await probe?.close().catch(() => undefined);
+    }
+}