@unbrained/pm-cli 2026.9.2 → 2026.9.4

package/dist/core/history/replay.js

@@ -4,13 +4,13 @@
  * Implements append-only history and replay behavior for Replay.
  */
 
-!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]="c9488ed4-8228-5e7c-9717-69dd7a3275c4")}catch(e){}}();
+!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]="ce8dfbdf-8471-5843-8179-5608140330e1")}catch(e){}}();
 import jsonPatch from "fast-json-patch";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
 import { canonicalDocument } from "../item/item-format.js";
 import { toItemRecord } from "../item/item-record.js";
 import { orderObject, sha256Hex, stableStringify, } from "../shared/serialization.js";
-import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentVerificationCandidates, } from "./history.js";
+import { CURRENT_HISTORY_ITEM_HASH_VERSION, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, hashDocumentVerificationCandidates, resealHistoryRewrite, verifyHistoryRecordHash, verifyHistoryRewriteEvidence, } from "./history.js";
 /** Public contract for empty replay document, shared by SDK and presentation-layer consumers. */
 export const EMPTY_REPLAY_DOCUMENT = {
     metadata: {},
@@ -165,6 +165,31 @@ function historyEntryHashCandidates(explicitVersion, authoritativeVersion) {
         ? [...SUPPORTED_HISTORY_ITEM_HASH_VERSIONS]
         : [authoritativeVersion];
 }
+/** Return the first record or retained-rewrite integrity failure for one entry. */
+function historyEntryIntegrityError(entry) {
+    const recordVerification = verifyHistoryRecordHash(entry);
+    if (!recordVerification.ok)
+        return recordVerification.error;
+    const rewriteVerification = verifyHistoryRewriteEvidence(entry);
+    return rewriteVerification.ok ? undefined : rewriteVerification.error;
+}
+/** Validate immutable metadata and apply one patch for chain verification. */
+function verifyHistoryEntryInput(entry, replay) {
+    const integrityError = historyEntryIntegrityError(entry);
+    if (integrityError)
+        return { ok: false, error: integrityError };
+    const applied = tryApplyReplayPatch(replay, entry.patch);
+    return applied.ok
+        ? { ok: true, document: applied.document }
+        : { ok: false, error: "patch_apply_failed" };
+}
+/** Refuse any entry whose current or retained immutable envelope is invalid. */
+function assertHistoryEntryIntegrity(entry, index) {
+    const integrityError = historyEntryIntegrityError(entry);
+    if (integrityError) {
+        throw new TypeError(`${integrityError}:entry_${index + 1}`);
+    }
+}
 /** Deterministically verify a history chain: each entry's before_hash must equal the prior replayed after_hash, the patch must strictly apply, and the recorded after_hash must equal the replayed result. */
 /** Verify a chain and report the explicit or auto-detected item hash epoch. */
 export function verifyHistoryChainWithVersion(entries) {
@@ -179,18 +204,15 @@ export function verifyHistoryChainWithVersion(entries) {
         if (unsupportedVersion) {
             errors.push(`verify_failed:unsupported_item_hash_version:${String(explicitVersion)}:entry_${index + 1}`);
         }
-        const applied = tryApplyReplayPatch(replay, entry.patch);
-        if (!applied.ok) {
+        const input = verifyHistoryEntryInput(entry, replay);
+        if (!input.ok) {
             return {
                 ok: false,
-                errors: [
-                    ...errors,
-                    `verify_failed:patch_apply_failed:entry_${index + 1}`,
-                ],
+                errors: [...errors, `verify_failed:${input.error}:entry_${index + 1}`],
             };
         }
         if (unsupportedVersion) {
-            replay = applied.document;
+            replay = input.document;
             detectedVersion = undefined;
             authoritativeExplicitVersion = undefined;
             continue;
@@ -201,7 +223,7 @@ export function verifyHistoryChainWithVersion(entries) {
         const candidates = historyEntryHashCandidates(explicitVersion, authoritativeExplicitVersion);
         const candidateMatches = candidates.map((version) => ({
             version,
-            match: matchReplayHashCandidates(replay, applied.document, version, entry),
+            match: matchReplayHashCandidates(replay, input.document, version, entry),
         }));
         const matchingVersion = candidateMatches.find(({ match }) => match.pairIndex >= 0);
         if (matchingVersion === undefined) {
@@ -215,7 +237,7 @@ export function verifyHistoryChainWithVersion(entries) {
             };
         }
         const version = matchingVersion.version;
-        replay = applied.document;
+        replay = input.document;
         detectedVersion = version;
         authoritativeExplicitVersion =
             explicitVersion ??
@@ -304,6 +326,27 @@ export function resolveHistoryRepairItemHashVersion(entries) {
     }
     return CURRENT_HISTORY_ITEM_HASH_VERSION;
 }
+/** Apply one patch strictly or return its deterministic lenient repair projection. */
+function applyReanchorPatch(replay, entry) {
+    const strict = tryApplyReplayPatch(replay, entry.patch);
+    if (strict.ok) {
+        return {
+            next: strict.document,
+            patch: entry.patch,
+            repaired: false,
+            converted: 0,
+            skipped: 0,
+        };
+    }
+    const lenient = lenientApplyReplayPatch(replay, entry.patch);
+    return {
+        next: lenient.document,
+        patch: jsonPatch.compare(replay, lenient.document),
+        repaired: true,
+        converted: lenient.convertedReplaceToAdd,
+        skipped: lenient.skippedOps,
+    };
+}
 /** Re-anchor a drifted history chain: replay every entry from empty, recompute the before/after hashes, and only rewrite a patch when the original op set no longer strictly applies (legacy drift). Clean entries keep their patch verbatim so the on-disk diff stays minimal. The returned chain verifies via verifyHistoryChain. */
 export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistoryRepairItemHashVersion(entries), options = {}) {
     const unsupportedIndex = entries.findIndex((entry) => isUnsupportedExplicitHistoryItemHashVersion(entry.item_hash_version));
@@ -322,27 +365,12 @@ export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistory
         entries.some((entry) => entry.item_hash_version !== undefined);
     for (let index = 0; index < entries.length; index += 1) {
         const entry = entries[index];
-        const strict = tryApplyReplayPatch(replay, entry.patch);
-        let next;
-        let outPatch;
-        let patchRepaired = false;
-        let entryConverted = 0;
-        let entrySkipped = 0;
-        if (strict.ok) {
-            next = strict.document;
-            outPatch = entry.patch;
-        }
-        else {
-            const lenient = lenientApplyReplayPatch(replay, entry.patch);
-            next = lenient.document;
-            outPatch = jsonPatch.compare(replay, next);
-            patchRepaired = true;
-            entryConverted = lenient.convertedReplaceToAdd;
-            entrySkipped = lenient.skippedOps;
-            convertedReplaceToAdd += entryConverted;
-            skippedOps += entrySkipped;
-            entriesPatchRepaired += 1;
-        }
+        assertHistoryEntryIntegrity(entry, index);
+        const patchApplication = applyReanchorPatch(replay, entry);
+        const { next, patch: outPatch, repaired: patchRepaired, converted: entryConverted, skipped: entrySkipped, } = patchApplication;
+        convertedReplaceToAdd += entryConverted;
+        skippedOps += entrySkipped;
+        entriesPatchRepaired += Number(patchRepaired);
         const hashMatch = matchReplayHashCandidates(replay, next, itemHashVersion, entry);
         if (semanticIndex === undefined || options.continuousHashSurface !== true) {
             semanticIndex = [
@@ -361,7 +389,7 @@ export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistory
         if (rehashed) {
             entriesRehashed += 1;
         }
-        const rewrittenEntry = {
+        let rewrittenEntry = {
             ...entry,
             patch: outPatch,
             before_hash: beforeHash,
@@ -373,6 +401,12 @@ export function reanchorHistoryEntries(entries, itemHashVersion = resolveHistory
         else {
             delete rewrittenEntry.item_hash_version;
         }
+        const versionChanged = rewrittenEntry.item_hash_version !== entry.item_hash_version;
+        if (rehashed || patchRepaired || versionChanged) {
+            rewrittenEntry = resealHistoryRewrite(entry, rewrittenEntry, {
+                retainOriginalPatch: patchRepaired,
+            });
+        }
         rewritten.push(rewrittenEntry);
         details.push({
             index: index + 1,
@@ -403,4 +437,4 @@ export function historyEntriesToRaw(entries) {
     return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
 }
 //# sourceMappingURL=replay.js.map
-//# debugId=c9488ed4-8228-5e7c-9717-69dd7a3275c4
+//# debugId=ce8dfbdf-8471-5843-8179-5608140330e1

package/dist/core/history/workspace-history.js

@@ -5,7 +5,7 @@
  * HistoryEntry format used by item mutations.
  */
 
-!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]="9027d972-ce29-5511-ba81-27e17d97446e")}catch(e){}}();
+!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]="4df21a17-43c0-5b63-adf3-657699e6a058")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
@@ -13,6 +13,7 @@ import { acquireLock } from "../lock/lock.js";
 import { EMPTY_CANONICAL_DOCUMENT, EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
 import { stableStringify } from "../shared/serialization.js";
+import { nowIso } from "../shared/time.js";
 import { appendHistoryEntry, createHistoryEntry } from "./history.js";
 import { readHistoryEntries } from "./read.js";
 import { cloneEmptyReplayDocument, replayToItemDocument, tryApplyReplayPatch, verifyHistoryChain, } from "./replay.js";
@@ -153,7 +154,7 @@ async function appendWorkspaceHistoryChangeLocked(change) {
     if (idempotentEntry) {
         return { entry: idempotentEntry, historyPath };
     }
-    const timestamp = new Date().toISOString();
+    const timestamp = nowIso();
     const beforeDocument = entries.length === 0
         ? EMPTY_CANONICAL_DOCUMENT
         : replayWorkspaceEntries(entries);
@@ -222,7 +223,7 @@ export async function appendWorkspaceAuditEvent(options) {
             ? EMPTY_CANONICAL_DOCUMENT
             : replayWorkspaceEntries(entries);
         const entry = createHistoryEntry({
-            nowIso: new Date().toISOString(),
+            nowIso: nowIso(),
             author: options.author,
             op: options.op,
             before: beforeDocument,
@@ -340,7 +341,7 @@ export async function reconcileWorkspaceJsonHistory(options) {
         if (stableStringify(priorDocuments[documentPath]) === stableStringify(current)) {
             return { changed: false, historyPath };
         }
-        const timestamp = new Date().toISOString();
+        const timestamp = nowIso();
         const entry = createHistoryEntry({
             nowIso: timestamp,
             author: options.author,
@@ -393,7 +394,7 @@ export async function restoreWorkspaceJsonFromHistory(options) {
                 changed: false,
             };
         const beforeDocument = replayWorkspaceEntries(entries);
-        const timestamp = new Date().toISOString();
+        const timestamp = nowIso();
         const entry = createHistoryEntry({
             nowIso: timestamp,
             author: options.author,
@@ -430,4 +431,4 @@ export async function restoreWorkspaceJsonFromHistory(options) {
     }
 }
 //# sourceMappingURL=workspace-history.js.map
-//# debugId=9027d972-ce29-5511-ba81-27e17d97446e
+//# debugId=4df21a17-43c0-5b63-adf3-657699e6a058

package/dist/core/lock/lock.d.ts

@@ -2,6 +2,7 @@ interface LockInfo {
     id: string;
     pid: number;
     owner: string;
+    token?: string;
     created_at: string;
     ttl_seconds: number;
 }
@@ -14,14 +15,40 @@ interface StaleLockRemovalResult {
     shouldRetryCreate: boolean;
     staleRemovalCounted: boolean;
 }
+/** Stable operating-system identity for a process when the host exposes one. */
+export interface ProcessIdentity {
+    /** Operating-system process identifier captured with the owner record. */
+    pid: number;
+    /** Host process-start coordinate that distinguishes reuse of the same PID. */
+    process_start_identity?: string;
+}
 declare function parseLockInfo(raw: string): LockReadResult;
-declare function readLockInfo(lockPath: string): Promise<LockReadResult>;
+declare function readLockInfo(lockPath: string, emitReadHook?: boolean): Promise<LockReadResult>;
 declare function isErrno(error: unknown, code: string): boolean;
-declare function buildLockPayload(id: string, owner: string, ttlSeconds: number): LockInfo;
+/**
+ * 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.
+ */
+declare function isLockCreateContention(error: unknown, lockPath: string, platform?: NodeJS.Platform): Promise<boolean>;
+declare function buildLockPayload(id: string, owner: string, ttlSeconds: number, token?: string): LockInfo;
 declare function isStaleLock(info: LockInfo | null, ttlSeconds: number): boolean;
 declare function lockOwnerSuffix(info: LockInfo | null): string;
 /** 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). */
 declare function resolveLockWaitMs(waitMs: number | undefined): number;
+declare function parseLinuxProcessStartIdentity(raw: string): string | null;
+/** Read the host process-start coordinate used to distinguish PID reuse. */
+export declare function readProcessStartIdentity(pid: number): Promise<string | null>;
+/** Capture the current PID plus a host process-start coordinate when available. */
+export declare function captureProcessIdentity(pid?: number): Promise<ProcessIdentity>;
+/**
+ * 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 declare function isProcessIdentityAlive(identity: ProcessIdentity, unverifiedAgeMs: number, maxUnverifiedAgeMs: number): Promise<boolean>;
 declare function acquireStaleCleanupGate(lockPath: string, _id: string): Promise<(() => Promise<void>) | null>;
 declare function removeConfirmedStaleLock(params: {
     lockPath: string;
@@ -39,10 +66,13 @@ export declare const _testOnly: {
     parseLockInfo: typeof parseLockInfo;
     readLockInfo: typeof readLockInfo;
     isErrno: typeof isErrno;
+    isLockCreateContention: typeof isLockCreateContention;
     buildLockPayload: typeof buildLockPayload;
     isStaleLock: typeof isStaleLock;
     lockOwnerSuffix: typeof lockOwnerSuffix;
     resolveLockWaitMs: typeof resolveLockWaitMs;
+    parseLinuxProcessStartIdentity: typeof parseLinuxProcessStartIdentity;
+    readProcessStartIdentity: typeof readProcessStartIdentity;
     acquireStaleCleanupGate: typeof acquireStaleCleanupGate;
     removeConfirmedStaleLock: typeof removeConfirmedStaleLock;
 };

package/dist/core/lock/lock.js

@@ -4,8 +4,9 @@
  * 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]="a9ad8a9f-de6e-5bce-8685-844f1129d5fb")}catch(e){}}();
+!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";
@@ -36,12 +37,15 @@ function parseLockInfo(raw) {
     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)) {
@@ -55,19 +59,22 @@ function parseLockInfo(raw) {
             id,
             pid,
             owner,
+            ...(typeof token === "string" ? { token } : {}),
             created_at: createdAt,
             ttl_seconds: ttlSeconds,
         },
         warnings: [],
     };
 }
-async function readLockInfo(lockPath) {
+async function readLockInfo(lockPath, emitReadHook = true) {
     try {
         const raw = await fs.readFile(lockPath, "utf8");
-        await runActiveOnReadHooks({
-            path: lockPath,
-            scope: "project",
-        });
+        if (emitReadHook) {
+            await runActiveOnReadHooks({
+                path: lockPath,
+                scope: "project",
+            });
+        }
         return parseLockInfo(raw);
     }
     catch (error) {
@@ -89,6 +96,43 @@ function isErrno(error, code) {
         "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,
@@ -96,20 +140,21 @@ async function emitLockWriteHook(lockPath, op) {
         op,
     });
 }
-function buildLockPayload(id, owner, ttlSeconds) {
+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) {
+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), null, 2)}\n`, "utf8");
+        await handle.writeFile(`${JSON.stringify(buildLockPayload(id, owner, ttlSeconds, token), null, 2)}\n`, "utf8");
     }
     finally {
         await handle.close();
@@ -127,6 +172,41 @@ async function unlinkLockWithHook(lockPath, op) {
         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)
@@ -146,8 +226,8 @@ 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;
-// Bounds PID-reuse false positives: a live recycled PID can delay cleanup, but not indefinitely.
-const STALE_CLEANUP_GATE_MAX_ACTIVE_MS = 5 * 60_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();
@@ -220,14 +300,24 @@ function parseStaleCleanupGateOwner(raw) {
     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) {
+        token.length === 0 ||
+        (processStartIdentity !== undefined &&
+            (typeof processStartIdentity !== "string" ||
+                !/^\d+$/u.test(processStartIdentity)))) {
         return null;
     }
-    return { pid, token };
+    return {
+        pid,
+        token,
+        ...(typeof processStartIdentity === "string"
+            ? { process_start_identity: processStartIdentity }
+            : {}),
+    };
 }
 async function readStaleCleanupGateOwner(gatePath) {
     try {
@@ -238,6 +328,8 @@ async function readStaleCleanupGateOwner(gatePath) {
     }
 }
 function isProcessAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
     try {
         process.kill(pid, 0);
         return true;
@@ -249,6 +341,49 @@ function isProcessAlive(pid) {
         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 });
@@ -275,7 +410,10 @@ async function tryCreateStaleCleanupGate(gatePath) {
         }
         return null;
     }
-    const owner = { pid: process.pid, token: randomUUID() };
+    const owner = {
+        ...(await captureProcessIdentity()),
+        token: randomUUID(),
+    };
     try {
         await fs.writeFile(path.join(gatePath, STALE_CLEANUP_GATE_OWNER_FILE), `${JSON.stringify(owner)}\n`, "utf8");
     }
@@ -299,8 +437,7 @@ async function removeExpiredStaleCleanupGate(gatePath) {
     }
     const owner = await readStaleCleanupGateOwner(gatePath);
     if (owner !== null &&
-        isProcessAlive(owner.pid) &&
-        gateAgeMs <= STALE_CLEANUP_GATE_MAX_ACTIVE_MS) {
+        (await isProcessIdentityAlive(owner, gateAgeMs, STALE_CLEANUP_GATE_MAX_UNVERIFIED_MS))) {
         return false;
     }
     return removeStaleCleanupGateDirectory(gatePath);
@@ -365,10 +502,13 @@ export const _testOnly = {
     parseLockInfo,
     readLockInfo,
     isErrno,
+    isLockCreateContention,
     buildLockPayload,
     isStaleLock,
     lockOwnerSuffix,
     resolveLockWaitMs,
+    parseLinuxProcessStartIdentity,
+    readProcessStartIdentity,
     acquireStaleCleanupGate,
     removeConfirmedStaleLock,
 };
@@ -400,11 +540,12 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
     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);
+            await createLockFile(lockPath, id, owner, ttlSeconds, token);
             return async () => {
-                await unlinkLockWithHook(lockPath, "lock:release");
+                await releaseOwnedLock(lockPath, id, owner, token);
                 await runActiveServiceOverride("lock_release", {
                     pm_root: pmRoot,
                     id,
@@ -413,7 +554,7 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
             };
         }
         catch (error) {
-            if (!isErrno(error, "EEXIST")) {
+            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);
@@ -447,4 +588,4 @@ export async function acquireLock(pmRoot, id, ttlSeconds, owner, force = false,
     }
 }
 //# sourceMappingURL=lock.js.map
-//# debugId=a9ad8a9f-de6e-5bce-8685-844f1129d5fb
+//# debugId=b21a63b8-9da9-5c7c-b288-3a2dae342bef