@planu/cli 4.13.0 → 4.14.1

package/dist/engine/safety/cross-process-lock.js

@@ -1,28 +1,73 @@
-// src/engine/safety/cross-process-lock.ts — Cross-process spec lockfile (SPEC-719)
-//
-// Lockfiles live at: <projectPath>/data/.locks/planu/<specId>.lock
-// File mode: 0o600 (owner read/write only)
-import { open, unlink, readFile, mkdir, chmod, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
-import { hostname as osHostname } from 'node:os';
+// Transactional cross-process leases with monotonic fencing.
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { randomUUID } from 'node:crypto';
-import { writeJsonSafe } from './atomic-writer.js';
-import { enrichWithStaleness } from './lock-staleness.js';
-import { readValidatedLockFile, scavengeStaleLockArtifacts } from './lock-scavenger.js';
+import { hostname as osHostname } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { hashProjectPath } from '../../storage/base-store.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { computeStaleReason, isPidDead, STALE_THRESHOLD_MS } from './lock-staleness.js';
+import { LockLeaseStore, } from './lock-lease-store.js';
+import { scavengeStaleLockArtifacts } from './lock-scavenger.js';
+import { assertNoObsoleteFileLock, assertSafeLockResourceId, assertSafeLockScopeId, } from './obsolete-lock-guard.js';
 export { getLockScavengeMetrics, resetLockScavengeMetricsForTests, scavengeStaleLockArtifacts, } from './lock-scavenger.js';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const DEFAULT_TTL_MS = 600_000; // 10 minutes
-const MIN_TTL_MS = 60_000; // 1 minute
-const MAX_TTL_MS = 86_400_000; // 24 hours
-const HEARTBEAT_INTERVAL_MS = 30_000; // 30 seconds
+const LOCK_NAMESPACE = 'spec';
+const DEFAULT_TTL_MS = 600_000;
+const MIN_TTL_MS = 60_000;
+const MAX_TTL_MS = 86_400_000;
+const HEARTBEAT_INTERVAL_MS = 30_000;
 export { HEARTBEAT_INTERVAL_MS };
-// ---------------------------------------------------------------------------
-// Errors
-// ---------------------------------------------------------------------------
-/** Thrown by withSpecLock when the lock is held by another live session. */
 export class LockBusyError extends Error {
     code = 'LOCK_BUSY';
     holder;
@@ -32,304 +77,255 @@ export class LockBusyError extends Error {
         this.holder = holder;
     }
 }
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-function locksDir(projectPath) {
-    return join(projectPath, 'data', '.locks', 'planu');
+function projectId(projectPathOrId) {
+    return isAbsolute(projectPathOrId) ? hashProjectPath(projectPathOrId) : projectPathOrId;
 }
-function lockPath(projectPath, specId) {
-    return join(locksDir(projectPath), `${specId}.lock`);
+function leaseKey(projectPathOrId, specId) {
+    return { namespace: LOCK_NAMESPACE, scopeId: projectId(projectPathOrId), resourceId: specId };
 }
-function resolveSessionId(opts) {
-    return opts?.sessionId ?? process.env.PLANU_SESSION_ID ?? randomUUID();
+function resolveSessionId(options) {
+    return options?.sessionId ?? process.env.PLANU_SESSION_ID ?? randomUUID();
 }
 function clampTtl(ttlMs) {
     const ttl = ttlMs ?? DEFAULT_TTL_MS;
     return Math.min(Math.max(ttl, MIN_TTL_MS), MAX_TTL_MS);
 }
-async function readLockFile(path) {
-    try {
-        const raw = await readFile(path, 'utf-8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
+function toMetadata(record) {
+    return {
+        specId: record.resourceId,
+        scopeId: record.scopeId,
+        pid: record.pid,
+        sessionId: record.sessionId,
+        hostname: record.hostname,
+        acquiredAt: new Date(record.acquiredAtMs).toISOString(),
+        lastHeartbeatAt: new Date(record.heartbeatAtMs).toISOString(),
+        ttlMs: record.hardExpiresAtMs - record.acquiredAtMs,
+        lockId: record.lockId,
+        fencingToken: record.fencingToken,
+        ...(record.reason === undefined ? {} : { reason: record.reason }),
+    };
 }
-/** Write a lockfile atomically and set 0o600 mode. */
-async function writeLockFile(path, metadata) {
-    await mkdir(join(path, '..'), { recursive: true });
-    await writeJsonSafe(path, metadata, { verify: true, backupCount: 0 });
-    // Set strict mode: owner read/write only
-    await chmod(path, 0o600);
+function candidate(key, options, nowMs) {
+    const ttlMs = clampTtl(options?.ttlMs);
+    return {
+        ...key,
+        lockId: randomUUID(),
+        sessionId: resolveSessionId(options),
+        pid: process.pid,
+        hostname: osHostname(),
+        nowMs,
+        leaseExpiresAtMs: Math.min(nowMs + STALE_THRESHOLD_MS, nowMs + ttlMs),
+        hardExpiresAtMs: nowMs + ttlMs,
+        ...(options?.reason === undefined ? {} : { reason: options.reason }),
+    };
 }
-/** Try to create a new lockfile exclusively (O_EXCL). Returns true on success. */
-async function tryExclusiveCreate(path, metadata) {
-    await mkdir(join(path, '..'), { recursive: true });
-    let fd = null;
-    try {
-        // 'wx' = O_WRONLY | O_CREAT | O_EXCL — fails if file already exists
-        fd = await open(path, 'wx', 0o600);
-        await fd.writeFile(JSON.stringify(metadata, null, 2), 'utf-8');
-        return true;
-    }
-    catch (err) {
-        if (err instanceof Error && 'code' in err && err.code === 'EEXIST') {
-            return false;
-        }
-        throw err;
-    }
-    finally {
-        await fd?.close().catch(() => {
-            // best-effort close
-        });
-    }
+function isRecordStale(record, nowMs) {
+    return computeStaleReason(toMetadata(record), osHostname(), nowMs) !== undefined;
 }
-// ---------------------------------------------------------------------------
-// LockHandle implementation
-// ---------------------------------------------------------------------------
-function buildHandle(metadata, path) {
-    return {
+function buildHandle(record) {
+    const metadata = toMetadata(record);
+    const key = {
+        namespace: record.namespace,
+        scopeId: record.scopeId,
+        resourceId: record.resourceId,
+    };
+    const handle = {
         metadata,
-        lockPath: path,
-        async heartbeat() {
-            const current = await readLockFile(path);
-            if (current?.sessionId !== metadata.sessionId) {
-                console.warn('[planu:lock] heartbeat_skipped_foreign_holder', {
-                    specId: metadata.specId,
-                    expectedSession: metadata.sessionId,
-                    foundSession: current?.sessionId ?? null,
-                });
-                return false;
-            }
-            const updated = {
-                ...current,
-                lastHeartbeatAt: new Date().toISOString(),
-            };
+        lockPath: resolveStorageLayout().lockDatabase,
+        heartbeat() {
             try {
-                await writeLockFile(path, updated);
-                return true;
+                const env_1 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const store = __addDisposableResource(env_1, new LockLeaseStore(), false);
+                    return Promise.resolve(store.heartbeat({
+                        ...key,
+                        lockId: metadata.lockId,
+                        fencingToken: metadata.fencingToken,
+                        nowMs: Date.now(),
+                        leaseExpiresAtMs: Date.now() + STALE_THRESHOLD_MS,
+                    }));
+                }
+                catch (e_1) {
+                    env_1.error = e_1;
+                    env_1.hasError = true;
+                }
+                finally {
+                    __disposeResources(env_1);
+                }
             }
-            catch (err) {
-                console.warn('[planu:lock] heartbeat_failed', {
-                    specId: metadata.specId,
-                    error: err instanceof Error ? err.message : String(err),
-                });
-                return false;
+            catch (error) {
+                reportClassifiedDegradation('LOCK_HEARTBEAT', error);
+                return Promise.resolve(false);
             }
         },
-        async isStillHeld() {
-            const current = await readLockFile(path);
-            return current?.sessionId === metadata.sessionId;
+        isStillHeld() {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const store = __addDisposableResource(env_2, new LockLeaseStore(), false);
+                const current = store.get(key);
+                const sqliteHeld = current?.lockId === metadata.lockId &&
+                    current.fencingToken === metadata.fencingToken &&
+                    !isRecordStale(current, Date.now());
+                if (!sqliteHeld) {
+                    return Promise.resolve(false);
+                }
+                return Promise.resolve(sqliteHeld);
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                __disposeResources(env_2);
+            }
         },
     };
+    return handle;
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Try to acquire a cross-process lock for `specId`.
- *
- * Returns a LockHandle on success, or null if the lock is held by another live session.
- * Stale locks (PID dead, heartbeat expired, or TTL expired) are reclaimed automatically.
- *
- * @remarks
- * NFS / SMB caveat: O_EXCL is not guaranteed atomic on network filesystems.
- * This implementation is reliable on local POSIX filesystems (APFS, HFS+, ext4, tmpfs).
- */
-export async function acquireLock(projectPath, specId, opts) {
-    await scavengeStaleLockArtifacts(projectPath, specId);
-    const path = lockPath(projectPath, specId);
-    const now = Date.now();
-    const sessionId = resolveSessionId(opts);
-    const ttlMs = clampTtl(opts?.ttlMs);
-    const nowIso = new Date(now).toISOString();
-    const metadata = {
-        specId,
-        pid: process.pid,
-        sessionId,
-        hostname: osHostname(),
-        acquiredAt: nowIso,
-        lastHeartbeatAt: nowIso,
-        ttlMs,
-        ...(opts?.reason !== undefined ? { reason: opts.reason } : {}),
-    };
-    // Attempt exclusive creation first
-    const created = await tryExclusiveCreate(path, metadata);
-    if (created) {
-        return buildHandle(metadata, path);
-    }
-    // File exists — check staleness
-    const existing = await readLockFile(path);
-    if (existing === null) {
-        // Lockfile vanished between EEXIST and read — retry once
-        const retried = await tryExclusiveCreate(path, metadata);
-        if (retried) {
-            return buildHandle(metadata, path);
+export async function acquireLock(projectPath, specId, options) {
+    const env_3 = { stack: [], error: void 0, hasError: false };
+    try {
+        const key = leaseKey(projectPath, specId);
+        assertSafeLockScopeId(key.scopeId);
+        assertSafeLockResourceId(specId);
+        await assertNoObsoleteFileLock(join(resolveStorageLayout().state, 'locks', key.scopeId, `${specId}.lock`), specId);
+        await scavengeStaleLockArtifacts(projectPath, specId);
+        const nowMs = Date.now();
+        const next = candidate(key, options, nowMs);
+        const store = __addDisposableResource(env_3, new LockLeaseStore(), false);
+        let acquired = store.acquire(next);
+        if (acquired === undefined) {
+            const current = store.get(key);
+            if (current !== undefined && isPidDead(toMetadata(current), osHostname())) {
+                acquired = store.reclaim({
+                    ...key,
+                    expectedLockId: current.lockId,
+                    expectedFencingToken: current.fencingToken,
+                    nowMs,
+                    ownerDead: true,
+                    candidate: next,
+                });
+            }
         }
-        return null;
+        return acquired === undefined ? null : buildHandle(acquired);
     }
-    const info = enrichWithStaleness(existing, osHostname(), now);
-    if (!info.stale) {
-        // Lock is held by a live session
-        console.warn('[planu:lock] lock_busy', {
-            specId,
-            holderSession: existing.sessionId,
-            holderPid: existing.pid,
-            holderAcquiredAt: existing.acquiredAt,
-            staleReason: null,
-        });
-        return null;
+    catch (e_3) {
+        env_3.error = e_3;
+        env_3.hasError = true;
+    }
+    finally {
+        __disposeResources(env_3);
     }
-    // Stale lock — reclaim via atomic write
-    console.warn('[planu:lock] lock_reclaimed', {
-        specId,
-        previousSession: existing.sessionId,
-        previousPid: existing.pid,
-        previousAcquiredAt: existing.acquiredAt,
-        staleReason: info.staleReason,
-        newSession: sessionId,
-        newPid: process.pid,
-    });
-    await writeLockFile(path, metadata);
-    return buildHandle(metadata, path);
 }
-/**
- * Release a lock if it is still held by the given handle.
- * Idempotent: calling twice on the same handle is safe.
- * Will NOT unlink a lockfile that is now held by a different session.
- */
-export async function releaseLock(handle) {
-    const path = handle.lockPath;
-    if (!existsSync(path)) {
-        return; // already gone — idempotent
+export function releaseLock(handle) {
+    const env_4 = { stack: [], error: void 0, hasError: false };
+    try {
+        const store = __addDisposableResource(env_4, new LockLeaseStore(), false);
+        store.release({
+            namespace: LOCK_NAMESPACE,
+            scopeId: handle.metadata.scopeId,
+            resourceId: handle.metadata.specId,
+            lockId: handle.metadata.lockId,
+            fencingToken: handle.metadata.fencingToken,
+            nowMs: Date.now(),
+        });
+        return Promise.resolve();
     }
-    const current = await readLockFile(path);
-    if (current === null) {
-        return; // race: file deleted between existsSync and read
+    catch (e_4) {
+        env_4.error = e_4;
+        env_4.hasError = true;
     }
-    if (current.sessionId !== handle.metadata.sessionId) {
-        console.warn('[planu:lock] release_skipped_foreign_holder', {
-            specId: handle.metadata.specId,
-            expectedSession: handle.metadata.sessionId,
-            foundSession: current.sessionId,
-        });
-        return;
+    finally {
+        __disposeResources(env_4);
     }
+}
+export function isLocked(projectPath, specId) {
+    const env_5 = { stack: [], error: void 0, hasError: false };
     try {
-        await unlink(path);
-    }
-    catch (err) {
-        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
-            return; // already unlinked — idempotent
+        const store = __addDisposableResource(env_5, new LockLeaseStore(), false);
+        const record = store.get(leaseKey(projectPath, specId));
+        if (record === undefined) {
+            return Promise.resolve(null);
         }
-        throw err;
+        const metadata = toMetadata(record);
+        const staleReason = computeStaleReason(metadata, osHostname(), Date.now());
+        return Promise.resolve({
+            ...metadata,
+            stale: staleReason !== undefined,
+            ...(staleReason === undefined ? {} : { staleReason }),
+        });
     }
-    const dir = dirname(path);
-    const base = basename(path);
-    const backups = await readdir(dir).catch(() => []);
-    await Promise.all(backups
-        .filter((entry) => entry.startsWith(`${base}.bak.`))
-        .map(async (entry) => {
-        const backupPath = join(dir, entry);
-        const backup = await readValidatedLockFile(backupPath);
-        if (backup?.metadata.sessionId === handle.metadata.sessionId) {
-            await unlink(backupPath).catch(() => undefined);
-        }
-    }));
-}
-/**
- * Read the current lockfile state for a spec.
- * Returns null when no lockfile exists.
- * Enriches the result with computed staleness fields.
- */
-export async function isLocked(projectPath, specId) {
-    const path = lockPath(projectPath, specId);
-    const raw = await readLockFile(path);
-    if (raw === null) {
-        return null;
+    catch (e_5) {
+        env_5.error = e_5;
+        env_5.hasError = true;
+    }
+    finally {
+        __disposeResources(env_5);
     }
-    return enrichWithStaleness(raw, osHostname(), Date.now());
 }
-/**
- * List all cross-process locks for a project, filtering out stale ones.
- * Non-existent `.locks/` directory returns an empty array.
- */
 export async function listActiveCrossProcessLocks(projectPath) {
-    const dir = locksDir(projectPath);
-    if (!existsSync(dir)) {
-        return [];
-    }
-    await scavengeStaleLockArtifacts(projectPath);
-    let entries;
+    const env_6 = { stack: [], error: void 0, hasError: false };
     try {
-        entries = await readdir(dir);
+        await scavengeStaleLockArtifacts(projectPath);
+        const store = __addDisposableResource(env_6, new LockLeaseStore(), false);
+        const nowMs = Date.now();
+        return store
+            .list({ namespace: LOCK_NAMESPACE, scopeId: projectId(projectPath) })
+            .map(toMetadata)
+            .map((metadata) => {
+            const staleReason = computeStaleReason(metadata, osHostname(), nowMs);
+            return {
+                ...metadata,
+                stale: staleReason !== undefined,
+                ...(staleReason === undefined ? {} : { staleReason }),
+            };
+        })
+            .filter((info) => !info.stale);
     }
-    catch {
-        return [];
+    catch (e_6) {
+        env_6.error = e_6;
+        env_6.hasError = true;
+    }
+    finally {
+        __disposeResources(env_6);
     }
-    const now = Date.now();
-    const localHost = osHostname();
-    const results = [];
-    await Promise.all(entries
-        .filter((f) => f.endsWith('.lock'))
-        .map(async (filename) => {
-        const raw = await readLockFile(join(dir, filename));
-        if (raw === null) {
-            return;
-        }
-        const info = enrichWithStaleness(raw, localHost, now);
-        if (!info.stale) {
-            results.push(info);
-        }
-    }));
-    return results;
 }
-/**
- * High-level wrapper: acquire → run fn → release.
- * Automatically sets up a 30s heartbeat and tears it down on completion.
- * Throws LockBusyError if the lock cannot be acquired.
- *
- * @example
- * ```ts
- * await withSpecLock(projectPath, specId, async (_handle) => {
- *   await mutatSpec();
- * }, { reason: 'update_status(approved)' });
- * ```
- */
-export async function withSpecLock(projectPath, specId, fn, opts) {
-    const handle = await acquireLock(projectPath, specId, opts);
+export async function withSpecLock(projectPath, specId, fn, options) {
+    const handle = await acquireLock(projectPath, specId, options);
     if (handle === null) {
-        // Read existing lock to include in error
-        const existing = await readLockFile(lockPath(projectPath, specId));
-        const holder = existing ?? {
+        const holder = await isLocked(projectPath, specId);
+        throw new LockBusyError(holder ?? {
             specId,
-            pid: 0,
+            scopeId: projectId(projectPath),
+            pid: 1,
             sessionId: 'unknown',
             hostname: 'unknown',
             acquiredAt: new Date().toISOString(),
             lastHeartbeatAt: new Date().toISOString(),
             ttlMs: DEFAULT_TTL_MS,
-        };
-        throw new LockBusyError(holder);
+            lockId: 'unknown',
+            fencingToken: 0,
+        });
     }
-    // Set up heartbeat interval
-    const hbTimer = setInterval(() => {
-        void handle.heartbeat().catch(() => {
-            // best-effort — logged inside heartbeat()
+    const heartbeat = setInterval(() => {
+        void handle.heartbeat().catch((error) => {
+            reportClassifiedDegradation('LOCK_HEARTBEAT_TIMER', error);
         });
     }, HEARTBEAT_INTERVAL_MS);
+    heartbeat.unref();
     try {
-        return await fn(handle);
+        const result = await fn(handle);
+        if (!(await handle.isStillHeld())) {
+            const error = new Error(`[Planu] Lease lost before completing ${specId}`);
+            error.code = 'LOCK_LEASE_LOST';
+            throw error;
+        }
+        return result;
     }
     finally {
-        clearInterval(hbTimer);
-        await releaseLock(handle).catch((err) => {
-            console.warn('[planu:lock] release_error_in_finally', {
-                specId,
-                error: err instanceof Error ? err.message : String(err),
-            });
+        clearInterval(heartbeat);
+        await releaseLock(handle).catch((error) => {
+            reportClassifiedDegradation('LOCK_RELEASE_FINALLY', error);
         });
     }
 }

package/dist/engine/safety/file-mutex.d.ts

@@ -1,13 +1,6 @@
 import type { FileMutexLockHandle as LockHandle } from '../../types/safety.js';
-/**
- * Acquires a file-based lock for a named resource.
- * Polls until the lock is available or timeout expires.
- * Stale locks (old timestamp or dead PID) are auto-released.
- */
+/** Acquire a transactional mutex for a named file resource. */
 export declare function acquireLock(resource: string, timeoutMs?: number): Promise<LockHandle>;
-/**
- * Releases a previously acquired lock.
- * No-op if the lock file was already removed.
- */
+/** Release only the exact acquisition represented by this handle. */
 export declare function releaseLock(handle: LockHandle): Promise<void>;
 //# sourceMappingURL=file-mutex.d.ts.map