@planu/cli 4.13.0 → 5.0.0

package/dist/engine/safety/lock-lease-store.js

@@ -0,0 +1,372 @@
+import { chmodSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+const SCHEMA_VERSION = 1;
+const DEFAULT_BUSY_TIMEOUT_MS = 5_000;
+const BUSY_RETRY_INTERVAL_MS = 10;
+const BUSY_WAIT = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+function requireText(value, label, maxLength = 512) {
+    if (!value.trim() || value.length > maxLength || value.includes('\0')) {
+        throw new Error(`[Planu] Invalid ${label}`);
+    }
+}
+function requireTimestamp(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`[Planu] Invalid ${label}`);
+    }
+}
+function validateKey(key) {
+    requireText(key.namespace, 'lock namespace', 128);
+    requireText(key.scopeId, 'lock scopeId');
+    requireText(key.resourceId, 'lock resourceId');
+}
+function resourceKey(key) {
+    validateKey(key);
+    return JSON.stringify([key.namespace, key.scopeId, key.resourceId]);
+}
+function validateCandidate(candidate) {
+    validateKey(candidate);
+    requireText(candidate.lockId, 'lockId');
+    requireText(candidate.sessionId, 'sessionId');
+    requireText(candidate.hostname, 'lock hostname');
+    requireTimestamp(candidate.nowMs, 'lock nowMs');
+    requireTimestamp(candidate.leaseExpiresAtMs, 'lock leaseExpiresAtMs');
+    requireTimestamp(candidate.hardExpiresAtMs, 'lock hardExpiresAtMs');
+    if (!Number.isSafeInteger(candidate.pid) || candidate.pid < 1) {
+        throw new Error('[Planu] Invalid lock pid');
+    }
+    if (candidate.leaseExpiresAtMs <= candidate.nowMs ||
+        candidate.hardExpiresAtMs < candidate.leaseExpiresAtMs) {
+        throw new Error('[Planu] Lock expiry must be in the future and within the hard expiry');
+    }
+    if (candidate.reason !== undefined) {
+        requireText(candidate.reason, 'lock reason', 2_048);
+    }
+}
+function mapRow(row) {
+    return {
+        namespace: row.namespace,
+        scopeId: row.scope_id,
+        resourceId: row.resource_id,
+        lockId: row.lock_id,
+        sessionId: row.session_id,
+        pid: row.pid,
+        hostname: row.hostname,
+        acquiredAtMs: row.acquired_at_ms,
+        heartbeatAtMs: row.heartbeat_at_ms,
+        leaseExpiresAtMs: row.lease_expires_at_ms,
+        hardExpiresAtMs: row.hard_expires_at_ms,
+        fencingToken: row.fencing_token,
+        ...(row.reason === null ? {} : { reason: row.reason }),
+    };
+}
+function isSqliteBusy(error) {
+    return error instanceof Error && /database is (?:locked|busy)/iu.test(error.message);
+}
+/** Dedicated SQLite authority for cross-process leases and monotonic fencing tokens. */
+export class LockLeaseStore {
+    path;
+    schemaVersion = SCHEMA_VERSION;
+    database;
+    closed = false;
+    constructor(options = {}) {
+        const path = options.path ?? resolveStorageLayout().lockDatabase;
+        const busyTimeoutMs = options.busyTimeoutMs ?? DEFAULT_BUSY_TIMEOUT_MS;
+        if (!path.trim()) {
+            throw new Error('[Planu] Lock database path is required');
+        }
+        if (path !== ':memory:' && !isAbsolute(path)) {
+            throw new Error('[Planu] Lock database path must be absolute');
+        }
+        if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 0 || busyTimeoutMs > 60_000) {
+            throw new Error('[Planu] busyTimeoutMs must be an integer between 0 and 60000');
+        }
+        this.path = path === ':memory:' ? path : resolve(path);
+        if (this.path !== ':memory:') {
+            mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        }
+        this.database = new DatabaseSync(this.path, {
+            timeout: busyTimeoutMs,
+            enableForeignKeyConstraints: true,
+            enableDoubleQuotedStringLiterals: false,
+            allowExtension: false,
+        });
+        try {
+            this.migrate();
+            this.configureJournal(busyTimeoutMs);
+            this.database.exec('PRAGMA synchronous = FULL;');
+            this.protectDatabaseFiles();
+        }
+        catch (error) {
+            this.database.close();
+            throw error;
+        }
+    }
+    configureJournal(busyTimeoutMs) {
+        const deadline = Date.now() + busyTimeoutMs;
+        for (;;) {
+            try {
+                const current = this.database.prepare('PRAGMA journal_mode').get();
+                if (current.journal_mode.toLowerCase() !== 'wal') {
+                    this.database.exec('PRAGMA journal_mode = WAL');
+                }
+                return;
+            }
+            catch (error) {
+                if (!isSqliteBusy(error) || Date.now() >= deadline) {
+                    throw error;
+                }
+                Atomics.wait(BUSY_WAIT, 0, 0, BUSY_RETRY_INTERVAL_MS);
+            }
+        }
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new Error('[Planu] Lock database is closed');
+        }
+    }
+    protectDatabaseFiles() {
+        if (this.path === ':memory:') {
+            return;
+        }
+        for (const path of [this.path, `${this.path}-wal`, `${this.path}-shm`]) {
+            if (existsSync(path)) {
+                chmodSync(path, 0o600);
+            }
+        }
+    }
+    migrate() {
+        this.database.exec('BEGIN IMMEDIATE');
+        try {
+            const row = this.database.prepare('PRAGMA user_version').get();
+            if (row.user_version > SCHEMA_VERSION) {
+                throw new Error(`[Planu] Lock schema ${String(row.user_version)} is newer than supported`);
+            }
+            if (row.user_version === 0) {
+                this.database.exec(`
+        CREATE TABLE lock_tombstones (
+          resource_key TEXT PRIMARY KEY,
+          last_fencing_token INTEGER NOT NULL CHECK (last_fencing_token >= 0),
+          updated_at_ms INTEGER NOT NULL
+        ) STRICT;
+        CREATE TABLE lock_leases (
+          resource_key TEXT PRIMARY KEY,
+          namespace TEXT NOT NULL,
+          scope_id TEXT NOT NULL,
+          resource_id TEXT NOT NULL,
+          lock_id TEXT NOT NULL UNIQUE,
+          session_id TEXT NOT NULL,
+          pid INTEGER NOT NULL CHECK (pid > 0),
+          hostname TEXT NOT NULL,
+          acquired_at_ms INTEGER NOT NULL,
+          heartbeat_at_ms INTEGER NOT NULL,
+          lease_expires_at_ms INTEGER NOT NULL,
+          hard_expires_at_ms INTEGER NOT NULL,
+          fencing_token INTEGER NOT NULL CHECK (fencing_token > 0),
+          reason TEXT
+        ) STRICT;
+        CREATE INDEX lock_leases_expiry_idx
+          ON lock_leases (lease_expires_at_ms, hard_expires_at_ms);
+        PRAGMA user_version = 1;
+        `);
+            }
+            this.database.exec('COMMIT');
+        }
+        catch (error) {
+            this.database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    transaction(operation) {
+        this.assertOpen();
+        this.database.exec('BEGIN IMMEDIATE');
+        try {
+            const result = operation();
+            this.database.exec('COMMIT');
+            this.protectDatabaseFiles();
+            return result;
+        }
+        catch (error) {
+            this.database.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    row(key) {
+        return this.database.prepare('SELECT * FROM lock_leases WHERE resource_key = ?').get(key);
+    }
+    nextFencingToken(key, currentToken = 0) {
+        const tombstone = this.database
+            .prepare('SELECT last_fencing_token FROM lock_tombstones WHERE resource_key = ?')
+            .get(key);
+        const token = Math.max(currentToken, tombstone?.last_fencing_token ?? 0) + 1;
+        if (!Number.isSafeInteger(token)) {
+            throw new Error('[Planu] Lock fencing token exhausted');
+        }
+        return token;
+    }
+    preserveFence(key, token, nowMs) {
+        this.database
+            .prepare(`INSERT INTO lock_tombstones (resource_key, last_fencing_token, updated_at_ms)
+         VALUES (?, ?, ?)
+         ON CONFLICT(resource_key) DO UPDATE SET
+           last_fencing_token = MAX(lock_tombstones.last_fencing_token, excluded.last_fencing_token),
+           updated_at_ms = MAX(lock_tombstones.updated_at_ms, excluded.updated_at_ms)`)
+            .run(key, token, nowMs);
+    }
+    insert(key, candidate, fencingToken) {
+        this.database
+            .prepare(`INSERT INTO lock_leases
+          (resource_key, namespace, scope_id, resource_id, lock_id, session_id, pid, hostname,
+           acquired_at_ms, heartbeat_at_ms, lease_expires_at_ms, hard_expires_at_ms,
+           fencing_token, reason)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(key, candidate.namespace, candidate.scopeId, candidate.resourceId, candidate.lockId, candidate.sessionId, candidate.pid, candidate.hostname, candidate.nowMs, candidate.nowMs, candidate.leaseExpiresAtMs, candidate.hardExpiresAtMs, fencingToken, candidate.reason ?? null);
+        const inserted = this.row(key);
+        if (inserted === undefined) {
+            throw new Error('[Planu] Lock lease insert did not persist');
+        }
+        return mapRow(inserted);
+    }
+    acquire(candidate) {
+        validateCandidate(candidate);
+        const key = resourceKey(candidate);
+        return this.transaction(() => {
+            const current = this.row(key);
+            if (current !== undefined) {
+                return undefined;
+            }
+            const token = this.nextFencingToken(key);
+            this.preserveFence(key, token, candidate.nowMs);
+            return this.insert(key, candidate, token);
+        });
+    }
+    reclaim(input) {
+        validateKey(input);
+        validateCandidate(input.candidate);
+        requireText(input.expectedLockId, 'expectedLockId');
+        requireTimestamp(input.expectedFencingToken, 'expected fencingToken');
+        requireTimestamp(input.nowMs, 'lock nowMs');
+        if (resourceKey(input) !== resourceKey(input.candidate)) {
+            throw new Error('[Planu] Reclaim candidate must target the expected resource');
+        }
+        const key = resourceKey(input);
+        return this.transaction(() => {
+            const current = this.row(key);
+            if (current?.lock_id !== input.expectedLockId ||
+                current.fencing_token !== input.expectedFencingToken ||
+                input.ownerDead !== true) {
+                return undefined;
+            }
+            const token = this.nextFencingToken(key, current.fencing_token);
+            const deleted = this.database
+                .prepare('DELETE FROM lock_leases WHERE resource_key = ? AND lock_id = ? AND fencing_token = ?')
+                .run(key, input.expectedLockId, input.expectedFencingToken);
+            if (deleted.changes !== 1) {
+                return undefined;
+            }
+            this.preserveFence(key, token, input.nowMs);
+            return this.insert(key, input.candidate, token);
+        });
+    }
+    heartbeat(input) {
+        const key = resourceKey(input);
+        requireText(input.lockId, 'lockId');
+        requireTimestamp(input.fencingToken, 'lock fencingToken');
+        requireTimestamp(input.nowMs, 'lock nowMs');
+        requireTimestamp(input.leaseExpiresAtMs, 'lock leaseExpiresAtMs');
+        if (input.leaseExpiresAtMs <= input.nowMs) {
+            throw new Error('[Planu] Heartbeat expiry must be in the future');
+        }
+        this.assertOpen();
+        const updated = this.database
+            .prepare(`UPDATE lock_leases
+         SET heartbeat_at_ms = ?, lease_expires_at_ms = MIN(?, hard_expires_at_ms)
+         WHERE resource_key = ? AND lock_id = ? AND fencing_token = ?
+           AND lease_expires_at_ms > ? AND hard_expires_at_ms > ?`)
+            .run(input.nowMs, input.leaseExpiresAtMs, key, input.lockId, input.fencingToken, input.nowMs, input.nowMs);
+        this.protectDatabaseFiles();
+        return updated.changes === 1;
+    }
+    release(input) {
+        const key = resourceKey(input);
+        requireText(input.lockId, 'lockId');
+        requireTimestamp(input.fencingToken, 'lock fencingToken');
+        requireTimestamp(input.nowMs, 'lock nowMs');
+        return this.transaction(() => {
+            const current = this.row(key);
+            if (current?.lock_id !== input.lockId || current.fencing_token !== input.fencingToken) {
+                return false;
+            }
+            const deleted = this.database
+                .prepare('DELETE FROM lock_leases WHERE resource_key = ? AND lock_id = ? AND fencing_token = ?')
+                .run(key, input.lockId, input.fencingToken);
+            if (deleted.changes !== 1) {
+                return false;
+            }
+            this.preserveFence(key, current.fencing_token, input.nowMs);
+            return true;
+        });
+    }
+    get(keyInput) {
+        this.assertOpen();
+        const row = this.row(resourceKey(keyInput));
+        return row === undefined ? undefined : mapRow(row);
+    }
+    list(input = {}) {
+        this.assertOpen();
+        if (input.namespace !== undefined) {
+            requireText(input.namespace, 'lock namespace', 128);
+        }
+        if (input.scopeId !== undefined) {
+            requireText(input.scopeId, 'lock scopeId');
+        }
+        const conditions = [];
+        const parameters = [];
+        if (input.namespace !== undefined) {
+            conditions.push('namespace = ?');
+            parameters.push(input.namespace);
+        }
+        if (input.scopeId !== undefined) {
+            conditions.push('scope_id = ?');
+            parameters.push(input.scopeId);
+        }
+        const where = conditions.length === 0 ? '' : ` WHERE ${conditions.join(' AND ')}`;
+        const rows = this.database
+            .prepare(`SELECT * FROM lock_leases${where} ORDER BY namespace, scope_id, resource_id`)
+            .all(...parameters);
+        return rows.map(mapRow);
+    }
+    scavengeLease(input) {
+        const key = resourceKey(input);
+        requireText(input.expectedLockId, 'expectedLockId');
+        requireTimestamp(input.expectedFencingToken, 'expected fencingToken');
+        requireTimestamp(input.nowMs, 'lock nowMs');
+        return this.transaction(() => {
+            const current = this.row(key);
+            if (current?.lock_id !== input.expectedLockId ||
+                current.fencing_token !== input.expectedFencingToken ||
+                input.ownerDead !== true) {
+                return false;
+            }
+            const deleted = this.database
+                .prepare('DELETE FROM lock_leases WHERE resource_key = ? AND lock_id = ? AND fencing_token = ?')
+                .run(key, input.expectedLockId, input.expectedFencingToken);
+            if (deleted.changes !== 1) {
+                return false;
+            }
+            this.preserveFence(key, current.fencing_token, input.nowMs);
+            return true;
+        });
+    }
+    close() {
+        if (!this.closed) {
+            this.database.close();
+            this.closed = true;
+        }
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+//# sourceMappingURL=lock-lease-store.js.map

package/dist/engine/safety/lock-scavenger.d.ts

@@ -1,9 +1,6 @@
-import type { CrossProcessLockMetadata, LockScavengeMetrics } from '../../types/spec-lock-v2.js';
+import type { LockScavengeMetrics } from '../../types/spec-lock-v2.js';
 export declare function getLockScavengeMetrics(): Readonly<LockScavengeMetrics>;
 export declare function resetLockScavengeMetricsForTests(): void;
-export declare function readValidatedLockFile(path: string): Promise<{
-    raw: string;
-    metadata: CrossProcessLockMetadata;
-} | null>;
+/** Reclaim stale SQLite leases with CAS and remove obsolete legacy lock artifacts. */
 export declare function scavengeStaleLockArtifacts(projectPath: string, onlySpecId?: string): Promise<LockScavengeMetrics>;
 //# sourceMappingURL=lock-scavenger.d.ts.map

package/dist/engine/safety/lock-scavenger.js

@@ -1,9 +1,65 @@
-import { readFile, readdir, unlink } from 'node:fs/promises';
+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 { readFile, readdir, rm } from 'node:fs/promises';
 import { hostname as osHostname } from 'node:os';
-import { join } from 'node:path';
-import { enrichWithStaleness } from './lock-staleness.js';
-const MIN_TTL_MS = 60_000;
-const MAX_TTL_MS = 86_400_000;
+import { isAbsolute, join } from 'node:path';
+import { hashProjectPath } from '../../storage/base-store.js';
+import { resolveStorageLayout } from '../../storage/storage-layout.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { computeStaleReason, isPidDead } from './lock-staleness.js';
+import { LockLeaseStore } from './lock-lease-store.js';
+import { assertSafeLockScopeId } from './obsolete-lock-guard.js';
+const LOCK_NAMESPACE = 'spec';
 const metrics = {
     scavengedLocks: 0,
     scavengedBackups: 0,
@@ -19,96 +75,122 @@ export function resetLockScavengeMetricsForTests() {
     metrics.preservedLive = 0;
     metrics.preservedCorrupt = 0;
 }
-function locksDir(projectPath) {
-    return join(projectPath, 'data', '.locks', 'planu');
+function projectId(projectPathOrId) {
+    return isAbsolute(projectPathOrId) ? hashProjectPath(projectPathOrId) : projectPathOrId;
 }
-function isValidLockMetadata(value) {
-    if (typeof value !== 'object' || value === null) {
-        return false;
-    }
-    const lock = value;
-    return (typeof lock.specId === 'string' &&
-        lock.specId.trim().length > 0 &&
-        typeof lock.sessionId === 'string' &&
-        lock.sessionId.trim().length > 0 &&
-        typeof lock.hostname === 'string' &&
-        lock.hostname.trim().length > 0 &&
-        typeof lock.pid === 'number' &&
-        Number.isSafeInteger(lock.pid) &&
-        lock.pid > 0 &&
-        typeof lock.ttlMs === 'number' &&
-        Number.isSafeInteger(lock.ttlMs) &&
-        lock.ttlMs >= MIN_TTL_MS &&
-        lock.ttlMs <= MAX_TTL_MS &&
-        typeof lock.acquiredAt === 'string' &&
-        !Number.isNaN(Date.parse(lock.acquiredAt)) &&
-        typeof lock.lastHeartbeatAt === 'string' &&
-        !Number.isNaN(Date.parse(lock.lastHeartbeatAt)));
-}
-export async function readValidatedLockFile(path) {
-    try {
-        const raw = await readFile(path, 'utf-8');
-        const parsed = JSON.parse(raw);
-        return isValidLockMetadata(parsed) ? { raw, metadata: parsed } : null;
-    }
-    catch {
-        return null;
-    }
+function metadata(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 }),
+    };
 }
-export async function scavengeStaleLockArtifacts(projectPath, onlySpecId) {
-    const dir = locksDir(projectPath);
+async function removeObsoleteFileLockArtifacts(scopeId, onlySpecId) {
+    assertSafeLockScopeId(scopeId);
+    const directory = join(resolveStorageLayout().state, 'locks', scopeId);
     let entries;
     try {
-        entries = await readdir(dir);
-    }
-    catch {
-        return { scavengedLocks: 0, scavengedBackups: 0, preservedLive: 0, preservedCorrupt: 0 };
+        entries = await readdir(directory);
     }
-    const delta = {
-        scavengedLocks: 0,
-        scavengedBackups: 0,
-        preservedLive: 0,
-        preservedCorrupt: 0,
-    };
-    const candidates = entries.filter((entry) => {
-        const match = /^(.*\.lock)(?:\.bak\.\d+)?$/.exec(entry);
-        return match !== null && (!onlySpecId || match[1] === `${onlySpecId}.lock`);
-    });
-    for (const entry of candidates) {
-        const path = join(dir, entry);
-        const first = await readValidatedLockFile(path);
-        if (!first) {
-            delta.preservedCorrupt += 1;
-            continue;
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { scavengedBackups: 0, preservedLive: 0, preservedCorrupt: 0 };
         }
-        const info = enrichWithStaleness(first.metadata, osHostname(), Date.now());
-        if (!info.stale) {
-            delta.preservedLive += 1;
+        throw error;
+    }
+    let scavengedBackups = 0;
+    let preservedLive = 0;
+    let preservedCorrupt = 0;
+    for (const entry of entries) {
+        const match = /^(.*)\.lock(?:(?:\.bak\.\d+)|(?:\.(?:pending|sentinel-publish|refresh)\.\d+\.[0-9a-f-]+))?$/.exec(entry);
+        if (match === null || (onlySpecId !== undefined && match[1] !== onlySpecId)) {
             continue;
         }
-        const current = await readValidatedLockFile(path);
-        if (current?.raw !== first.raw) {
-            delta.preservedLive += 1;
+        const primary = entry === `${match[1]}.lock`;
+        if (!primary) {
+            await rm(join(directory, entry), { force: true });
+            scavengedBackups += 1;
             continue;
         }
         try {
-            await unlink(path);
-            if (entry.includes('.lock.bak.')) {
-                delta.scavengedBackups += 1;
+            const parsed = JSON.parse(await readFile(join(directory, entry), 'utf8'));
+            if (Number.isSafeInteger(parsed.pid) && parsed.pid > 0) {
+                preservedLive += 1;
             }
             else {
-                delta.scavengedLocks += 1;
+                preservedCorrupt += 1;
             }
         }
         catch (error) {
-            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
-                throw error;
+            if (error.code === 'ENOENT') {
+                continue;
             }
+            reportClassifiedDegradation('LEGACY_LOCK_SCAVENGE_READ', error);
+            preservedCorrupt += 1;
         }
     }
-    for (const key of Object.keys(delta)) {
-        metrics[key] += delta[key];
+    return { scavengedBackups, preservedLive, preservedCorrupt };
+}
+/** Reclaim stale SQLite leases with CAS and remove obsolete legacy lock artifacts. */
+export async function scavengeStaleLockArtifacts(projectPath, onlySpecId) {
+    const env_1 = { stack: [], error: void 0, hasError: false };
+    try {
+        const scopeId = projectId(projectPath);
+        const nowMs = Date.now();
+        const legacy = await removeObsoleteFileLockArtifacts(scopeId, onlySpecId);
+        const delta = {
+            scavengedLocks: 0,
+            ...legacy,
+        };
+        const store = __addDisposableResource(env_1, new LockLeaseStore(), false);
+        const leases = store
+            .list({ namespace: LOCK_NAMESPACE, scopeId })
+            .filter((lease) => onlySpecId === undefined || lease.resourceId === onlySpecId);
+        for (const lease of leases) {
+            const staleReason = computeStaleReason(metadata(lease), osHostname(), nowMs);
+            if (staleReason === undefined) {
+                delta.preservedLive += 1;
+                continue;
+            }
+            if (!isPidDead(metadata(lease), osHostname())) {
+                delta.preservedLive += 1;
+                continue;
+            }
+            const removed = store.scavengeLease({
+                namespace: lease.namespace,
+                scopeId: lease.scopeId,
+                resourceId: lease.resourceId,
+                expectedLockId: lease.lockId,
+                expectedFencingToken: lease.fencingToken,
+                nowMs,
+                ownerDead: true,
+            });
+            if (removed) {
+                delta.scavengedLocks += 1;
+            }
+            else {
+                delta.preservedLive += 1;
+            }
+        }
+        for (const key of Object.keys(delta)) {
+            metrics[key] += delta[key];
+        }
+        return delta;
+    }
+    catch (e_1) {
+        env_1.error = e_1;
+        env_1.hasError = true;
+    }
+    finally {
+        __disposeResources(env_1);
     }
-    return delta;
 }
 //# sourceMappingURL=lock-scavenger.js.map

package/dist/engine/safety/lock-staleness.js

@@ -39,7 +39,10 @@ export function isPidDead(lock, localHostname) {
             return true;
         }
         // EPERM means the process exists but we lack permission to signal it — treat as alive
-        return false;
+        if (err instanceof Error && 'code' in err && err.code === 'EPERM') {
+            return false;
+        }
+        throw err;
     }
 }
 /**

package/dist/engine/safety/obsolete-lock-guard.d.ts

@@ -0,0 +1,8 @@
+export declare function assertSafeLockScopeId(scopeId: string): void;
+export declare function assertSafeLockResourceId(resourceId: string): void;
+/**
+ * Refuse mixed-version access when an older file-lock authority is present.
+ * The file is never removed here because path-based unlink cannot be made ABA-safe.
+ */
+export declare function assertNoObsoleteFileLock(path: string, resource: string): Promise<void>;
+//# sourceMappingURL=obsolete-lock-guard.d.ts.map