@unbrained/pm-cli 2026.9.7 → 2026.9.8

package/dist/core/lock/lock.js

@@ -1,591 +1,4 @@
-/**
- * @module core/lock/lock
- *
- * Coordinates tracker lock ownership and cleanup for Lock.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b21a63b8-9da9-5c7c-b288-3a2dae342bef")}catch(e){}}();
-import { isFileMissingError } from "../fs/fs-utils.js";
-import { constants as fsConstants } from "node:fs";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { randomUUID } from "node:crypto";
-import { runActiveOnReadHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
-import { EXIT_CODE } from "../shared/constants.js";
-import { PmCliError } from "../shared/errors.js";
-import { toErrorMessage } from "../shared/primitives.js";
-import { getLockPath } from "../store/paths.js";
-import { nowIso } from "../shared/time.js";
-function parseLockInfo(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return {
-            info: null,
-            warnings: ["lock_info_invalid_json"],
-        };
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return {
-            info: null,
-            warnings: ["lock_info_invalid_shape"],
-        };
-    }
-    const candidate = parsed;
-    const id = candidate.id;
-    const pid = candidate.pid;
-    const owner = candidate.owner;
-    const token = candidate.token;
-    const createdAt = candidate.created_at;
-    const ttlSeconds = candidate.ttl_seconds;
-    if (typeof id !== "string" ||
-        typeof pid !== "number" ||
-        !Number.isFinite(pid) ||
-        typeof owner !== "string" ||
-        (token !== undefined &&
-            (typeof token !== "string" || token.trim().length === 0)) ||
-        typeof createdAt !== "string" ||
-        typeof ttlSeconds !== "number" ||
-        !Number.isFinite(ttlSeconds)) {
-        return {
-            info: null,
-            warnings: ["lock_info_invalid_shape"],
-        };
-    }
-    return {
-        info: {
-            id,
-            pid,
-            owner,
-            ...(typeof token === "string" ? { token } : {}),
-            created_at: createdAt,
-            ttl_seconds: ttlSeconds,
-        },
-        warnings: [],
-    };
-}
-async function readLockInfo(lockPath, emitReadHook = true) {
-    try {
-        const raw = await fs.readFile(lockPath, "utf8");
-        if (emitReadHook) {
-            await runActiveOnReadHooks({
-                path: lockPath,
-                scope: "project",
-            });
-        }
-        return parseLockInfo(raw);
-    }
-    catch (error) {
-        if (isFileMissingError(error)) {
-            return {
-                info: null,
-                warnings: [],
-            };
-        }
-        return {
-            info: null,
-            warnings: ["lock_info_read_failed"],
-        };
-    }
-}
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
-/**
- * Classify exclusive-create failures that prove another lock lifecycle is in
- * flight. Windows can report `EPERM`, `EACCES`, or `EBUSY` while a just-unlinked
- * lock is still delete-pending; treating those as fatal makes bounded lock
- * waiting fail nondeterministically. Existing paths are contention on every
- * host. A missing or temporarily unstatable Windows path is contention only
- * when its parent remains writable, preserving genuine permission failures.
- */
-async function isLockCreateContention(error, lockPath, platform = process.platform) {
-    if (isErrno(error, "EEXIST"))
-        return true;
-    if (!isErrno(error, "EPERM") &&
-        !isErrno(error, "EACCES") &&
-        !isErrno(error, "EBUSY")) {
-        return false;
-    }
-    try {
-        await fs.lstat(lockPath);
-        return true;
-    }
-    catch (probeError) {
-        if (platform !== "win32" ||
-            (!isFileMissingError(probeError) &&
-                !isErrno(probeError, "EPERM") &&
-                !isErrno(probeError, "EACCES") &&
-                !isErrno(probeError, "EBUSY"))) {
-            return false;
-        }
-    }
-    try {
-        await fs.access(path.dirname(lockPath), fsConstants.W_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function emitLockWriteHook(lockPath, op) {
-    await runActiveOnWriteHooks({
-        path: lockPath,
-        scope: "project",
-        op,
-    });
-}
-function buildLockPayload(id, owner, ttlSeconds, token = randomUUID()) {
-    return {
-        id,
-        pid: process.pid,
-        owner,
-        token,
-        created_at: nowIso(),
-        ttl_seconds: ttlSeconds,
-    };
-}
-async function createLockFile(lockPath, id, owner, ttlSeconds, token) {
-    await fs.mkdir(path.dirname(lockPath), { recursive: true });
-    const handle = await fs.open(lockPath, "wx");
-    try {
-        await handle.writeFile(`${JSON.stringify(buildLockPayload(id, owner, ttlSeconds, token), null, 2)}\n`, "utf8");
-    }
-    finally {
-        await handle.close();
-    }
-    await emitLockWriteHook(lockPath, "lock:create");
-}
-async function unlinkLockWithHook(lockPath, op) {
-    try {
-        await fs.unlink(lockPath);
-        await emitLockWriteHook(lockPath, op);
-        return true;
-    }
-    catch {
-        // Lock cleanup is best-effort.
-        return false;
-    }
-}
-async function releaseOwnedLock(lockPath, id, owner, token) {
-    const startedAtMs = Date.now();
-    let backoffMs = LOCK_WAIT_INITIAL_DELAY_MS;
-    for (;;) {
-        const releaseCleanupGate = await acquireStaleCleanupGate(lockPath, id);
-        if (releaseCleanupGate !== null) {
-            try {
-                const current = await readLockInfo(lockPath, false);
-                if (isOwnedLock(current.info, id, owner, token)) {
-                    await unlinkLockWithHook(lockPath, "lock:release");
-                }
-            }
-            finally {
-                await releaseCleanupGate();
-            }
-            return;
-        }
-        const current = await readLockInfo(lockPath, false);
-        if (!isOwnedLock(current.info, id, owner, token)) {
-            return;
-        }
-        const elapsedMs = Date.now() - startedAtMs;
-        if (elapsedMs >= LOCK_RELEASE_GATE_WAIT_MS) {
-            return;
-        }
-        await sleepWithJitter(Math.min(backoffMs, LOCK_RELEASE_GATE_WAIT_MS - elapsedMs));
-        backoffMs = Math.min(backoffMs * 2, LOCK_WAIT_MAX_DELAY_MS);
-    }
-}
-function isOwnedLock(info, id, owner, token) {
-    return (info?.id === id &&
-        info.pid === process.pid &&
-        info.owner === owner &&
-        info.token === token);
-}
-function isStaleLock(info, ttlSeconds) {
-    const createdAtMs = info?.created_at
-        ? Date.parse(info.created_at)
-        : Number.NaN;
-    const ageMs = Number.isFinite(createdAtMs)
-        ? Date.now() - createdAtMs
-        : Number.POSITIVE_INFINITY;
-    return ageMs > ttlSeconds * 1000;
-}
-function lockOwnerSuffix(info) {
-    return info?.owner ? ` (owner ${info.owner})` : "";
-}
-const LOCK_WAIT_INITIAL_DELAY_MS = 25;
-const LOCK_WAIT_MAX_DELAY_MS = 200;
-const LOCK_CONFLICT_RETRY_HINT_MS = 250;
-const MAX_STALE_LOCK_REMOVALS = 3;
-const STALE_CLEANUP_GATE_SUFFIX = ".stale-cleanup";
-const STALE_CLEANUP_GATE_OWNER_FILE = "owner.json";
-const STALE_CLEANUP_GATE_STALE_MS = 10_000;
-const LOCK_RELEASE_GATE_WAIT_MS = STALE_CLEANUP_GATE_STALE_MS + LOCK_WAIT_MAX_DELAY_MS;
-const STALE_CLEANUP_GATE_MAX_UNVERIFIED_MS = 60 * 60_000;
-function parseNonNegativeIntegerWaitMs(value) {
-    if (typeof value === "string") {
-        const trimmed = value.trim();
-        if (!/^\d+$/.test(trimmed)) {
-            return undefined;
-        }
-        const parsed = Number(trimmed);
-        return Number.isSafeInteger(parsed) ? parsed : undefined;
-    }
-    if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
-        return Math.trunc(value);
-    }
-    return undefined;
-}
-/** Resolves the effective bounded wait budget for a contended lock: the PM_LOCK_WAIT_MS environment override wins when it parses as a non-negative integer, then the caller-provided budget (settings `locks.wait_ms`), then 0 (fail-fast, the pre-wait behavior). */
-function resolveLockWaitMs(waitMs) {
-    const envRaw = process.env.PM_LOCK_WAIT_MS;
-    const envParsed = parseNonNegativeIntegerWaitMs(envRaw);
-    if (envParsed !== undefined) {
-        return envParsed;
-    }
-    const callerParsed = parseNonNegativeIntegerWaitMs(waitMs);
-    if (callerParsed !== undefined) {
-        return callerParsed;
-    }
-    return 0;
-}
-function sleepWithJitter(baseDelayMs) {
-    const jitteredMs = Math.max(1, Math.round(baseDelayMs * (0.5 + Math.random())));
-    return new Promise((resolve) => setTimeout(resolve, jitteredMs));
-}
-function buildLockConflictError(id, info, waitedMs) {
-    const waitedSuffix = waitedMs > 0 ? ` after waiting ${waitedMs}ms` : "";
-    return new PmCliError(`Item ${id} is locked${lockOwnerSuffix(info)}${waitedSuffix}`, EXIT_CODE.CONFLICT, {
-        code: "lock_conflict",
-        recovery: {
-            retry_after_ms: LOCK_CONFLICT_RETRY_HINT_MS,
-        },
-    });
-}
-function resolveLockOverrideRelease(result) {
-    if (typeof result === "function") {
-        return result;
-    }
-    if (typeof result === "object" && result !== null && "release" in result) {
-        const release = result.release;
-        return typeof release === "function"
-            ? release
-            : null;
-    }
-    return null;
-}
-function throwIfStaleLockNeedsForce(id, lockInfo, force, forceRequired) {
-    if (!force && forceRequired) {
-        const warningSuffix = lockInfo.warnings.length > 0 ? ` (${lockInfo.warnings.join(",")})` : "";
-        throw new PmCliError(`Item ${id} lock is stale${warningSuffix}; rerun with --force when supported for this command`, EXIT_CODE.CONFLICT);
-    }
-}
-function parseStaleCleanupGateOwner(raw) {
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return null;
-    }
-    const candidate = parsed;
-    const pid = candidate.pid;
-    const token = candidate.token;
-    const processStartIdentity = candidate.process_start_identity;
-    if (typeof pid !== "number" ||
-        !Number.isInteger(pid) ||
-        pid <= 0 ||
-        typeof token !== "string" ||
-        token.length === 0 ||
-        (processStartIdentity !== undefined &&
-            (typeof processStartIdentity !== "string" ||
-                !/^\d+$/u.test(processStartIdentity)))) {
-        return null;
-    }
-    return {
-        pid,
-        token,
-        ...(typeof processStartIdentity === "string"
-            ? { process_start_identity: processStartIdentity }
-            : {}),
-    };
-}
-async function readStaleCleanupGateOwner(gatePath) {
-    try {
-        return parseStaleCleanupGateOwner(await fs.readFile(path.join(gatePath, STALE_CLEANUP_GATE_OWNER_FILE), "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
-function isProcessAlive(pid) {
-    if (!Number.isSafeInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        if (isErrno(error, "ESRCH")) {
-            return false;
-        }
-        return true;
-    }
-}
-function parseLinuxProcessStartIdentity(raw) {
-    const closeParenIndex = raw.lastIndexOf(")");
-    if (closeParenIndex < 0)
-        return null;
-    const startTime = raw
-        .slice(closeParenIndex + 2)
-        .trim()
-        .split(/\s+/u)[19];
-    return startTime !== undefined && /^\d+$/u.test(startTime) ? startTime : null;
-}
-/** Read the host process-start coordinate used to distinguish PID reuse. */
-export async function readProcessStartIdentity(pid) {
-    try {
-        return parseLinuxProcessStartIdentity(await fs.readFile(`/proc/${pid}/stat`, "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
-/** Capture the current PID plus a host process-start coordinate when available. */
-export async function captureProcessIdentity(pid = process.pid) {
-    const processStartIdentity = await readProcessStartIdentity(pid);
-    return {
-        pid,
-        ...(processStartIdentity === null
-            ? {}
-            : { process_start_identity: processStartIdentity }),
-    };
-}
-/**
- * Verify that a captured process owner still exists, with a bounded grace
- * period when the host cannot expose a reusable-PID-safe start coordinate.
- */
-export async function isProcessIdentityAlive(identity, unverifiedAgeMs, maxUnverifiedAgeMs) {
-    if (!isProcessAlive(identity.pid))
-        return false;
-    const currentStartIdentity = await readProcessStartIdentity(identity.pid);
-    if (identity.process_start_identity !== undefined &&
-        currentStartIdentity !== null) {
-        return currentStartIdentity === identity.process_start_identity;
-    }
-    return unverifiedAgeMs <= maxUnverifiedAgeMs;
-}
-async function removeStaleCleanupGateDirectory(gatePath) {
-    try {
-        await fs.rm(gatePath, { recursive: true, force: true });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-async function releaseStaleCleanupGate(gatePath, token) {
-    const owner = await readStaleCleanupGateOwner(gatePath);
-    if (owner === null || owner.token !== token) {
-        return;
-    }
-    await removeStaleCleanupGateDirectory(gatePath);
-}
-async function tryCreateStaleCleanupGate(gatePath) {
-    try {
-        await fs.mkdir(gatePath);
-    }
-    catch (error) {
-        if (isErrno(error, "EEXIST")) {
-            return null;
-        }
-        return null;
-    }
-    const owner = {
-        ...(await captureProcessIdentity()),
-        token: randomUUID(),
-    };
-    try {
-        await fs.writeFile(path.join(gatePath, STALE_CLEANUP_GATE_OWNER_FILE), `${JSON.stringify(owner)}\n`, "utf8");
-    }
-    catch {
-        await removeStaleCleanupGateDirectory(gatePath);
-        return null;
-    }
-    return owner;
-}
-async function removeExpiredStaleCleanupGate(gatePath) {
-    let gateAgeMs;
-    try {
-        const stats = await fs.stat(gatePath);
-        gateAgeMs = Date.now() - stats.mtimeMs;
-        if (gateAgeMs <= STALE_CLEANUP_GATE_STALE_MS) {
-            return false;
-        }
-    }
-    catch (error) {
-        return isFileMissingError(error);
-    }
-    const owner = await readStaleCleanupGateOwner(gatePath);
-    if (owner !== null &&
-        (await isProcessIdentityAlive(owner, gateAgeMs, STALE_CLEANUP_GATE_MAX_UNVERIFIED_MS))) {
-        return false;
-    }
-    return removeStaleCleanupGateDirectory(gatePath);
-}
-async function acquireStaleCleanupGate(lockPath, _id) {
-    const gatePath = `${lockPath}${STALE_CLEANUP_GATE_SUFFIX}`;
-    const owner = await tryCreateStaleCleanupGate(gatePath);
-    if (owner !== null) {
-        return async () => releaseStaleCleanupGate(gatePath, owner.token);
-    }
-    if (!(await removeExpiredStaleCleanupGate(gatePath))) {
-        return null;
-    }
-    const recoveredOwner = await tryCreateStaleCleanupGate(gatePath);
-    if (recoveredOwner === null) {
-        return null;
-    }
-    return async () => releaseStaleCleanupGate(gatePath, recoveredOwner.token);
-}
-async function removeConfirmedStaleLock(params) {
-    const releaseCleanupGate = await acquireStaleCleanupGate(params.lockPath, params.id);
-    if (releaseCleanupGate === null) {
-        return {
-            lockInfo: params.fallbackLockInfo,
-            shouldRetryCreate: false,
-            staleRemovalCounted: false,
-        };
-    }
-    try {
-        const currentLockInfo = await readLockInfo(params.lockPath);
-        if (currentLockInfo.info === null &&
-            currentLockInfo.warnings.length === 0) {
-            return {
-                lockInfo: currentLockInfo,
-                shouldRetryCreate: true,
-                staleRemovalCounted: false,
-            };
-        }
-        if (!isStaleLock(currentLockInfo.info, params.ttlSeconds)) {
-            return {
-                lockInfo: currentLockInfo,
-                shouldRetryCreate: false,
-                staleRemovalCounted: false,
-            };
-        }
-        throwIfStaleLockNeedsForce(params.id, currentLockInfo, params.force, params.forceRequiredForStaleLock);
-        if (params.staleRemovals >= MAX_STALE_LOCK_REMOVALS) {
-            throw buildLockConflictError(params.id, currentLockInfo.info, Date.now() - params.startedAtMs);
-        }
-        return {
-            lockInfo: currentLockInfo,
-            shouldRetryCreate: await unlinkLockWithHook(params.lockPath, "lock:stale_remove"),
-            staleRemovalCounted: true,
-        };
-    }
-    finally {
-        await releaseCleanupGate();
-    }
-}
-/** Public contract for test only, shared by SDK and presentation-layer consumers. */
-export const _testOnly = {
-    parseLockInfo,
-    readLockInfo,
-    isErrno,
-    isLockCreateContention,
-    buildLockPayload,
-    isStaleLock,
-    lockOwnerSuffix,
-    resolveLockWaitMs,
-    parseLinuxProcessStartIdentity,
-    readProcessStartIdentity,
-    acquireStaleCleanupGate,
-    removeConfirmedStaleLock,
-};
-/** Implements acquire lock for the public runtime surface of this module. */
-export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false, forceRequiredForStaleLock = true, waitMs) {
-    const lockOverride = await runActiveServiceOverride("lock_acquire", {
-        pm_root: pmRoot,
-        id,
-        ttl_seconds: ttlSeconds,
-        owner,
-        force,
-        force_required_for_stale_lock: forceRequiredForStaleLock,
-    });
-    if (lockOverride.handled) {
-        const release = resolveLockOverrideRelease(lockOverride.result);
-        if (release) {
-            return async () => {
-                await Promise.resolve(release());
-                await runActiveServiceOverride("lock_release", {
-                    pm_root: pmRoot,
-                    id,
-                    owner,
-                });
-            };
-        }
-    }
-    const lockPath = getLockPath(pmRoot, id);
-    const waitBudgetMs = resolveLockWaitMs(waitMs);
-    const startedAtMs = Date.now();
-    let staleRemovals = 0;
-    let backoffMs = LOCK_WAIT_INITIAL_DELAY_MS;
-    const token = randomUUID();
-    for (;;) {
-        try {
-            await createLockFile(lockPath, id, owner, ttlSeconds, token);
-            return async () => {
-                await releaseOwnedLock(lockPath, id, owner, token);
-                await runActiveServiceOverride("lock_release", {
-                    pm_root: pmRoot,
-                    id,
-                    owner,
-                });
-            };
-        }
-        catch (error) {
-            if (!(await isLockCreateContention(error, lockPath))) {
-                throw new PmCliError(`Failed to acquire lock for ${id}: ${toErrorMessage(error)}`, EXIT_CODE.GENERIC_FAILURE);
-            }
-            let lockInfo = await readLockInfo(lockPath);
-            if (isStaleLock(lockInfo.info, ttlSeconds)) {
-                const staleRemoval = await removeConfirmedStaleLock({
-                    lockPath,
-                    id,
-                    ttlSeconds,
-                    force,
-                    forceRequiredForStaleLock,
-                    staleRemovals,
-                    waitBudgetMs,
-                    startedAtMs,
-                    fallbackLockInfo: lockInfo,
-                });
-                lockInfo = staleRemoval.lockInfo;
-                if (staleRemoval.staleRemovalCounted) {
-                    staleRemovals += 1;
-                }
-                if (staleRemoval.shouldRetryCreate) {
-                    continue;
-                }
-            }
-            const elapsedMs = Date.now() - startedAtMs;
-            if (waitBudgetMs === 0 || elapsedMs >= waitBudgetMs) {
-                throw buildLockConflictError(id, lockInfo.info, waitBudgetMs === 0 ? 0 : elapsedMs);
-            }
-            await sleepWithJitter(Math.min(backoffMs, waitBudgetMs - elapsedMs));
-            backoffMs = Math.min(backoffMs * 2, LOCK_WAIT_MAX_DELAY_MS);
-        }
-    }
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="962659bb-37dc-52fa-9d07-6216d34c0d53")}catch(e2){}})();import{isFileMissingError}from"../fs/fs-utils.js";import{constants as fsConstants}from"node:fs";import fs from"node:fs/promises";import path from"node:path";import{randomUUID}from"node:crypto";import{runActiveOnReadHooks,runActiveOnWriteHooks,runActiveServiceOverride}from"../extensions/index.js";import{EXIT_CODE}from"../shared/constants.js";import{PmCliError}from"../shared/errors.js";import{toErrorMessage}from"../shared/primitives.js";import{getLockPath}from"../store/paths.js";import{nowIso}from"../shared/time.js";function parseLockInfo(raw){let parsed;try{parsed=JSON.parse(raw)}catch{return{info:null,warnings:["lock_info_invalid_json"]}}if(typeof parsed!=="object"||parsed===null||Array.isArray(parsed)){return{info:null,warnings:["lock_info_invalid_shape"]}}const candidate=parsed;const id=candidate.id;const pid=candidate.pid;const owner=candidate.owner;const token=candidate.token;const createdAt=candidate.created_at;const ttlSeconds=candidate.ttl_seconds;if(typeof id!=="string"||typeof pid!=="number"||!Number.isFinite(pid)||typeof owner!=="string"||token!==void 0&&(typeof token!=="string"||token.trim().length===0)||typeof createdAt!=="string"||typeof ttlSeconds!=="number"||!Number.isFinite(ttlSeconds)){return{info:null,warnings:["lock_info_invalid_shape"]}}return{info:{id,pid,owner,...typeof token==="string"?{token}:{},created_at:createdAt,ttl_seconds:ttlSeconds},warnings:[]}}async function readLockInfo(lockPath,emitReadHook=true){try{const raw=await fs.readFile(lockPath,"utf8");if(emitReadHook){await runActiveOnReadHooks({path:lockPath,scope:"project"})}return parseLockInfo(raw)}catch(error){if(isFileMissingError(error)){return{info:null,warnings:[]}}return{info:null,warnings:["lock_info_read_failed"]}}}function isErrno(error,code){return typeof error==="object"&&error!==null&&"code"in error&&error.code===code}async function isLockCreateContention(error,lockPath,platform=process.platform){if(isErrno(error,"EEXIST"))return true;if(!isErrno(error,"EPERM")&&!isErrno(error,"EACCES")&&!isErrno(error,"EBUSY")){return false}try{await fs.lstat(lockPath);return true}catch(probeError){if(platform!=="win32"||!isFileMissingError(probeError)&&!isErrno(probeError,"EPERM")&&!isErrno(probeError,"EACCES")&&!isErrno(probeError,"EBUSY")){return false}}try{await fs.access(path.dirname(lockPath),fsConstants.W_OK);return true}catch{return false}}async function emitLockWriteHook(lockPath,op){await runActiveOnWriteHooks({path:lockPath,scope:"project",op})}function buildLockPayload(id,owner,ttlSeconds,token=randomUUID()){return{id,pid:process.pid,owner,token,created_at:nowIso(),ttl_seconds:ttlSeconds}}async function createLockFile(lockPath,id,owner,ttlSeconds,token){await fs.mkdir(path.dirname(lockPath),{recursive:true});const handle=await fs.open(lockPath,"wx");try{await handle.writeFile(`${JSON.stringify(buildLockPayload(id,owner,ttlSeconds,token),null,2)}
+`,"utf8")}finally{await handle.close()}await emitLockWriteHook(lockPath,"lock:create")}async function unlinkLockWithHook(lockPath,op){try{await fs.unlink(lockPath);await emitLockWriteHook(lockPath,op);return true}catch{return false}}async function releaseOwnedLock(lockPath,id,owner,token){const startedAtMs=Date.now();let backoffMs=LOCK_WAIT_INITIAL_DELAY_MS;for(;;){const releaseCleanupGate=await acquireStaleCleanupGate(lockPath,id);if(releaseCleanupGate!==null){try{const current2=await readLockInfo(lockPath,false);if(isOwnedLock(current2.info,id,owner,token)){await unlinkLockWithHook(lockPath,"lock:release")}}finally{await releaseCleanupGate()}return}const current=await readLockInfo(lockPath,false);if(!isOwnedLock(current.info,id,owner,token)){return}const elapsedMs=Date.now()-startedAtMs;if(elapsedMs>=LOCK_RELEASE_GATE_WAIT_MS){return}await sleepWithJitter(Math.min(backoffMs,LOCK_RELEASE_GATE_WAIT_MS-elapsedMs));backoffMs=Math.min(backoffMs*2,LOCK_WAIT_MAX_DELAY_MS)}}function isOwnedLock(info,id,owner,token){return info?.id===id&&info.pid===process.pid&&info.owner===owner&&info.token===token}function isStaleLock(info,ttlSeconds){const createdAtMs=info?.created_at?Date.parse(info.created_at):Number.NaN;const ageMs=Number.isFinite(createdAtMs)?Date.now()-createdAtMs:Number.POSITIVE_INFINITY;return ageMs>ttlSeconds*1e3}function lockOwnerSuffix(info){return info?.owner?` (owner ${info.owner})`:""}const LOCK_WAIT_INITIAL_DELAY_MS=25;const LOCK_WAIT_MAX_DELAY_MS=200;const LOCK_CONFLICT_RETRY_HINT_MS=250;const MAX_STALE_LOCK_REMOVALS=3;const STALE_CLEANUP_GATE_SUFFIX=".stale-cleanup";const STALE_CLEANUP_GATE_OWNER_FILE="owner.json";const STALE_CLEANUP_GATE_STALE_MS=1e4;const LOCK_RELEASE_GATE_WAIT_MS=STALE_CLEANUP_GATE_STALE_MS+LOCK_WAIT_MAX_DELAY_MS;const STALE_CLEANUP_GATE_MAX_UNVERIFIED_MS=60*6e4;function parseNonNegativeIntegerWaitMs(value){if(typeof value==="string"){const trimmed=value.trim();if(!/^\d+$/.test(trimmed)){return void 0}const parsed=Number(trimmed);return Number.isSafeInteger(parsed)?parsed:void 0}if(typeof value==="number"&&Number.isFinite(value)&&value>=0){return Math.trunc(value)}return void 0}function resolveLockWaitMs(waitMs){const envRaw=process.env.PM_LOCK_WAIT_MS;const envParsed=parseNonNegativeIntegerWaitMs(envRaw);if(envParsed!==void 0){return envParsed}const callerParsed=parseNonNegativeIntegerWaitMs(waitMs);if(callerParsed!==void 0){return callerParsed}return 0}function sleepWithJitter(baseDelayMs){const jitteredMs=Math.max(1,Math.round(baseDelayMs*(.5+Math.random())));return new Promise(resolve=>setTimeout(resolve,jitteredMs))}function buildLockConflictError(id,info,waitedMs){const waitedSuffix=waitedMs>0?` after waiting ${waitedMs}ms`:"";return new PmCliError(`Item ${id} is locked${lockOwnerSuffix(info)}${waitedSuffix}`,EXIT_CODE.CONFLICT,{code:"lock_conflict",recovery:{retry_after_ms:LOCK_CONFLICT_RETRY_HINT_MS}})}function resolveLockOverrideRelease(result){if(typeof result==="function"){return result}if(typeof result==="object"&&result!==null&&"release"in result){const release=result.release;return typeof release==="function"?release:null}return null}function throwIfStaleLockNeedsForce(id,lockInfo,force,forceRequired){if(!force&&forceRequired){const warningSuffix=lockInfo.warnings.length>0?` (${lockInfo.warnings.join(",")})`:"";throw new PmCliError(`Item ${id} lock is stale${warningSuffix}; rerun with --force when supported for this command`,EXIT_CODE.CONFLICT)}}function parseStaleCleanupGateOwner(raw){let parsed;try{parsed=JSON.parse(raw)}catch{return null}if(typeof parsed!=="object"||parsed===null||Array.isArray(parsed)){return null}const candidate=parsed;const pid=candidate.pid;const token=candidate.token;const processStartIdentity=candidate.process_start_identity;if(typeof pid!=="number"||!Number.isInteger(pid)||pid<=0||typeof token!=="string"||token.length===0||processStartIdentity!==void 0&&(typeof processStartIdentity!=="string"||!/^\d+$/u.test(processStartIdentity))){return null}return{pid,token,...typeof processStartIdentity==="string"?{process_start_identity:processStartIdentity}:{}}}async function readStaleCleanupGateOwner(gatePath){try{return parseStaleCleanupGateOwner(await fs.readFile(path.join(gatePath,STALE_CLEANUP_GATE_OWNER_FILE),"utf8"))}catch{return null}}function isProcessAlive(pid){if(!Number.isSafeInteger(pid)||pid<=0)return false;try{process.kill(pid,0);return true}catch(error){if(isErrno(error,"ESRCH")){return false}return true}}function parseLinuxProcessStartIdentity(raw){const closeParenIndex=raw.lastIndexOf(")");if(closeParenIndex<0)return null;const startTime=raw.slice(closeParenIndex+2).trim().split(/\s+/u)[19];return startTime!==void 0&&/^\d+$/u.test(startTime)?startTime:null}async function readProcessStartIdentity(pid){try{return parseLinuxProcessStartIdentity(await fs.readFile(`/proc/${pid}/stat`,"utf8"))}catch{return null}}async function captureProcessIdentity(pid=process.pid){const processStartIdentity=await readProcessStartIdentity(pid);return{pid,...processStartIdentity===null?{}:{process_start_identity:processStartIdentity}}}async function isProcessIdentityAlive(identity,unverifiedAgeMs,maxUnverifiedAgeMs){if(!isProcessAlive(identity.pid))return false;const currentStartIdentity=await readProcessStartIdentity(identity.pid);if(identity.process_start_identity!==void 0&&currentStartIdentity!==null){return currentStartIdentity===identity.process_start_identity}return unverifiedAgeMs<=maxUnverifiedAgeMs}async function removeStaleCleanupGateDirectory(gatePath){try{await fs.rm(gatePath,{recursive:true,force:true});return true}catch{return false}}async function releaseStaleCleanupGate(gatePath,token){const owner=await readStaleCleanupGateOwner(gatePath);if(owner===null||owner.token!==token){return}await removeStaleCleanupGateDirectory(gatePath)}async function tryCreateStaleCleanupGate(gatePath){try{await fs.mkdir(gatePath)}catch(error){if(isErrno(error,"EEXIST")){return null}return null}const owner={...await captureProcessIdentity(),token:randomUUID()};try{await fs.writeFile(path.join(gatePath,STALE_CLEANUP_GATE_OWNER_FILE),`${JSON.stringify(owner)}
+`,"utf8")}catch{await removeStaleCleanupGateDirectory(gatePath);return null}return owner}async function removeExpiredStaleCleanupGate(gatePath){let gateAgeMs;try{const stats=await fs.stat(gatePath);gateAgeMs=Date.now()-stats.mtimeMs;if(gateAgeMs<=STALE_CLEANUP_GATE_STALE_MS){return false}}catch(error){return isFileMissingError(error)}const owner=await readStaleCleanupGateOwner(gatePath);if(owner!==null&&await isProcessIdentityAlive(owner,gateAgeMs,STALE_CLEANUP_GATE_MAX_UNVERIFIED_MS)){return false}return removeStaleCleanupGateDirectory(gatePath)}async function acquireStaleCleanupGate(lockPath,_id){const gatePath=`${lockPath}${STALE_CLEANUP_GATE_SUFFIX}`;const owner=await tryCreateStaleCleanupGate(gatePath);if(owner!==null){return async()=>releaseStaleCleanupGate(gatePath,owner.token)}if(!await removeExpiredStaleCleanupGate(gatePath)){return null}const recoveredOwner=await tryCreateStaleCleanupGate(gatePath);if(recoveredOwner===null){return null}return async()=>releaseStaleCleanupGate(gatePath,recoveredOwner.token)}async function removeConfirmedStaleLock(params){const releaseCleanupGate=await acquireStaleCleanupGate(params.lockPath,params.id);if(releaseCleanupGate===null){return{lockInfo:params.fallbackLockInfo,shouldRetryCreate:false,staleRemovalCounted:false}}try{const currentLockInfo=await readLockInfo(params.lockPath);if(currentLockInfo.info===null&&currentLockInfo.warnings.length===0){return{lockInfo:currentLockInfo,shouldRetryCreate:true,staleRemovalCounted:false}}if(!isStaleLock(currentLockInfo.info,params.ttlSeconds)){return{lockInfo:currentLockInfo,shouldRetryCreate:false,staleRemovalCounted:false}}throwIfStaleLockNeedsForce(params.id,currentLockInfo,params.force,params.forceRequiredForStaleLock);if(params.staleRemovals>=MAX_STALE_LOCK_REMOVALS){throw buildLockConflictError(params.id,currentLockInfo.info,Date.now()-params.startedAtMs)}return{lockInfo:currentLockInfo,shouldRetryCreate:await unlinkLockWithHook(params.lockPath,"lock:stale_remove"),staleRemovalCounted:true}}finally{await releaseCleanupGate()}}const _testOnly={parseLockInfo,readLockInfo,isErrno,isLockCreateContention,buildLockPayload,isStaleLock,lockOwnerSuffix,resolveLockWaitMs,parseLinuxProcessStartIdentity,readProcessStartIdentity,acquireStaleCleanupGate,removeConfirmedStaleLock};async function acquireLock(pmRoot,id,ttlSeconds,owner,force=false,forceRequiredForStaleLock=true,waitMs){const lockOverride=await runActiveServiceOverride("lock_acquire",{pm_root:pmRoot,id,ttl_seconds:ttlSeconds,owner,force,force_required_for_stale_lock:forceRequiredForStaleLock});if(lockOverride.handled){const release=resolveLockOverrideRelease(lockOverride.result);if(release){return async()=>{await Promise.resolve(release());await runActiveServiceOverride("lock_release",{pm_root:pmRoot,id,owner})}}}const lockPath=getLockPath(pmRoot,id);const waitBudgetMs=resolveLockWaitMs(waitMs);const startedAtMs=Date.now();let staleRemovals=0;let backoffMs=LOCK_WAIT_INITIAL_DELAY_MS;const token=randomUUID();for(;;){try{await createLockFile(lockPath,id,owner,ttlSeconds,token);return async()=>{await releaseOwnedLock(lockPath,id,owner,token);await runActiveServiceOverride("lock_release",{pm_root:pmRoot,id,owner})}}catch(error){if(!await isLockCreateContention(error,lockPath)){throw new PmCliError(`Failed to acquire lock for ${id}: ${toErrorMessage(error)}`,EXIT_CODE.GENERIC_FAILURE)}let lockInfo=await readLockInfo(lockPath);if(isStaleLock(lockInfo.info,ttlSeconds)){const staleRemoval=await removeConfirmedStaleLock({lockPath,id,ttlSeconds,force,forceRequiredForStaleLock,staleRemovals,waitBudgetMs,startedAtMs,fallbackLockInfo:lockInfo});lockInfo=staleRemoval.lockInfo;if(staleRemoval.staleRemovalCounted){staleRemovals+=1}if(staleRemoval.shouldRetryCreate){continue}}const elapsedMs=Date.now()-startedAtMs;if(waitBudgetMs===0||elapsedMs>=waitBudgetMs){throw buildLockConflictError(id,lockInfo.info,waitBudgetMs===0?0:elapsedMs)}await sleepWithJitter(Math.min(backoffMs,waitBudgetMs-elapsedMs));backoffMs=Math.min(backoffMs*2,LOCK_WAIT_MAX_DELAY_MS)}}}export{_testOnly,acquireLock,captureProcessIdentity,isProcessIdentityAlive,readProcessStartIdentity};
 //# sourceMappingURL=lock.js.map
-//# debugId=b21a63b8-9da9-5c7c-b288-3a2dae342bef