ushman-ledger 1.2.2 → 1.3.1

package/dist/storage/filesystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../src/storage/filesystem.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,KAAK,cAAc,EAAwB,MAAM,uBAAuB,CAAC;AAElF,OAAO,EAAE,aAAa,EAAE,CAAC;AACzB,eAAO,MAAM,oBAAoB,6BAA8B,CAAC;AAChE,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,KAAK,mBAAmB,GAAG;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CACpC,CAAC;AAuCF,MAAM,MAAM,WAAW,GAAG;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,4BAA4B,EAAE,MAAM,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,eAAe,MAAM,KAAG,WAkB1D,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,WAAW,CAYxF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,UAAU,MAAM,EAAE,MAAM,mBAAmB,GAAG,IAAI,SAOxF,CAAC;AAoBF,eAAO,MAAM,mBAAmB,GAAU,UAAU,MAAM,EAAE,MAAM,MAAM,kBAiBvE,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,oBAAoB,CA8E/F,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAU,UAAU,MAAM,EAAE,OAAO,OAAO,kBAEzE,CAAC;AAoCF,eAAO,MAAM,YAAY,GAAU,eAAe,MAAM,KAAG,OAAO,CAAC,cAAc,CAmBhF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAU,eAAe,MAAM,EAAE,UAAU,cAAc,kBASjF,CAAC;AAoFF,eAAO,MAAM,qBAAqB,GAAU,eAAe,MAAM,kBAIhE,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAU,eAAe,MAAM,EAAE,OAAO,WAAW,KAAG,OAAO,CAAC,MAAM,EAAE,CAOzG,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,eAAe,MAAM,EAAE,OAAO,WAAW,EAAE,UAAU,MAAM,oBAGnG,CAAC;AAEF,eAAO,MAAM,cAAc,GAAU,eAAe,MAAM,EAAE,OAAO,WAAW,EAAE,UAAU,MAAM,EAAE,OAAO,OAAO,oBAK/G,CAAC"}
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../src/storage/filesystem.ts"],"names":[],"mappings":"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"}

package/dist/storage/filesystem.js

@@ -3,6 +3,7 @@ import { mkdir, open, readdir, readFile, rename, rm, stat } from 'node:fs/promis
 import path from 'node:path';
 import * as v from 'valibot';
 import { stableStringify } from "../json.js";
+import { isProcessAlive } from "../process.js";
 import { readLabManifestMin } from "../lab-min.js";
 import { LEDGER_PHASES } from "../schema/entry.js";
 import { LedgerManifestSchema } from "../schema/manifest.js";
@@ -46,9 +47,11 @@ export const resolveLedgerPaths = (workspaceRoot) => {
     const root = path.join(workspaceRoot, ...LEDGER_ROOT_SEGMENTS);
     return {
         blobsDir: path.join(root, 'blobs'),
+        externalTempFilesDir: path.join(root, 'external-temp-files'),
         lockFile: (phase) => path.join(root, phase, '.lock'),
         manifestFile: path.join(root, 'manifest.json'),
         manifestLockFile: path.join(root, '.manifest.lock'),
+        pendingCommitQuarantineDir: path.join(root, 'pending-quarantine'),
         pendingArchivesDir: path.join(root, 'pending-archives'),
         pendingCommitsDir: path.join(root, 'pending'),
         phaseDir: (phase) => path.join(root, phase),
@@ -65,7 +68,9 @@ export const ensureLedgerDirectories = async (workspaceRoot) => {
     const paths = resolveLedgerPaths(workspaceRoot);
     await mkdir(paths.root, { recursive: true });
     await mkdir(paths.blobsDir, { recursive: true });
+    await mkdir(paths.externalTempFilesDir, { recursive: true });
     await mkdir(paths.pendingCommitsDir, { recursive: true });
+    await mkdir(paths.pendingCommitQuarantineDir, { recursive: true });
     await mkdir(paths.pendingArchivesDir, { recursive: true });
     await Promise.all(LEDGER_PHASES.map(async (phase) => {
         await mkdir(paths.phaseDir(phase), { recursive: true });
@@ -80,6 +85,36 @@ export const setAtomicWriteTestHook = (filePath, hook) => {
     }
     atomicWriteTestHooks.set(key, hook);
 };
+const withPrimaryErrorPreserved = (error, cleanupError) => {
+    if (error instanceof Error) {
+        const errorWithCause = error;
+        if (errorWithCause.cause === undefined) {
+            Object.defineProperty(errorWithCause, 'cause', {
+                configurable: true,
+                enumerable: false,
+                value: cleanupError,
+                writable: true,
+            });
+        }
+        return error;
+    }
+    return new Error(String(error), { cause: cleanupError });
+};
+const removeTempRegistration = async (tempRegistration) => {
+    if (!tempRegistration) {
+        return;
+    }
+    await tempRegistration.remove();
+};
+const throwWithTempRegistrationCleanup = async ({ error, tempRegistration, }) => {
+    try {
+        await removeTempRegistration(tempRegistration);
+    }
+    catch (cleanupError) {
+        throw withPrimaryErrorPreserved(error, cleanupError);
+    }
+    throw error;
+};
 const createManifest = async (workspaceRoot) => {
     const labManifest = await readLabManifestMin(workspaceRoot);
     const now = new Date().toISOString();
@@ -97,30 +132,73 @@ const createManifest = async (workspaceRoot) => {
         workspaceId: labManifest.workspaceId,
     });
 };
-export const writeAtomicTextFile = async (filePath, text) => {
+export const writeAtomicTextFile = async (filePath, text, options = {}) => {
     await mkdir(path.dirname(filePath), { recursive: true });
     const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`;
-    const handle = await open(tempPath, 'w');
+    const tempRegistration = await options.registerTempFile?.({ finalPath: filePath, tempPath });
+    let handle;
     try {
-        await handle.writeFile(text, 'utf8');
-        await handle.sync();
+        handle = await open(tempPath, 'w');
+    }
+    catch (error) {
+        await throwWithTempRegistrationCleanup({
+            error,
+            tempRegistration,
+        });
+    }
+    const fileHandle = handle;
+    if (!fileHandle) {
+        throw new Error(`Failed to open atomic temp file: ${tempPath}`);
+    }
+    let writeError;
+    try {
+        await fileHandle.writeFile(text, 'utf8');
+        await fileHandle.sync();
+    }
+    catch (error) {
+        writeError = error;
     }
     finally {
-        await handle.close();
+        await fileHandle.close();
+    }
+    if (writeError) {
+        await rm(tempPath, { force: true });
+        await throwWithTempRegistrationCleanup({
+            error: writeError,
+            tempRegistration,
+        });
     }
     await runAtomicWriteTestHook(filePath);
     try {
         await rename(tempPath, filePath);
+        await removeTempRegistration(tempRegistration);
     }
     catch (error) {
         await rm(tempPath, { force: true });
-        throw error;
+        await throwWithTempRegistrationCleanup({
+            error,
+            tempRegistration,
+        });
     }
 };
-export const createAtomicTextFileWriter = async (filePath) => {
+export const createAtomicTextFileWriter = async (filePath, options = {}) => {
     await mkdir(path.dirname(filePath), { recursive: true });
     const tempPath = `${filePath}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`;
-    const handle = await open(tempPath, 'w');
+    const tempRegistration = await options.registerTempFile?.({ finalPath: filePath, tempPath });
+    let handle;
+    try {
+        handle = await open(tempPath, 'w');
+    }
+    catch (error) {
+        await throwWithTempRegistrationCleanup({
+            error,
+            tempRegistration,
+        });
+    }
+    const fileHandle = handle;
+    if (!fileHandle) {
+        throw new Error(`Failed to open atomic temp file: ${tempPath}`);
+    }
     let completed = false;
     let pendingWriteError;
     let writeChain = Promise.resolve();
@@ -149,11 +227,12 @@ export const createAtomicTextFileWriter = async (filePath) => {
             catch (error) {
                 writeError = error;
             }
-            await handle.close();
+            await fileHandle.close();
             await rm(tempPath, { force: true });
-            if (writeError) {
-                throw writeError;
-            }
+            await throwWithTempRegistrationCleanup({
+                error: writeError,
+                tempRegistration,
+            });
         },
         close: async () => {
             if (!(await finalizeHandle())) {
@@ -163,23 +242,30 @@ export const createAtomicTextFileWriter = async (filePath) => {
                 await waitForWrites();
             }
             catch (error) {
-                await handle.close();
+                await fileHandle.close();
                 await rm(tempPath, { force: true });
-                throw error;
+                await throwWithTempRegistrationCleanup({
+                    error,
+                    tempRegistration,
+                });
             }
             try {
-                await handle.sync();
+                await fileHandle.sync();
             }
             finally {
-                await handle.close();
+                await fileHandle.close();
             }
             await runAtomicWriteTestHook(filePath);
             try {
                 await rename(tempPath, filePath);
+                await removeTempRegistration(tempRegistration);
             }
             catch (error) {
                 await rm(tempPath, { force: true });
-                throw error;
+                await throwWithTempRegistrationCleanup({
+                    error,
+                    tempRegistration,
+                });
             }
         },
         write: async (chunk) => {
@@ -188,7 +274,7 @@ export const createAtomicTextFileWriter = async (filePath) => {
                     return;
                 }
                 await runAtomicWriteWriteTestHook(filePath);
-                await handle.writeFile(chunk, 'utf8');
+                await fileHandle.write(chunk, undefined, 'utf8');
             });
             writeChain = nextWrite.catch((error) => {
                 pendingWriteError ??= error;
@@ -200,6 +286,26 @@ export const createAtomicTextFileWriter = async (filePath) => {
 export const writeAtomicJsonFile = async (filePath, value) => {
     await writeAtomicTextFile(filePath, `${stableStringify(value, true)}\n`);
 };
+const EXTERNAL_TEMP_FILE_SCHEMA_VERSION = 'ushman-ledger-external-temp-file/v1';
+const ExternalTempFileRecordSchema = v.object({
+    createdAt: v.pipe(v.string(), v.isoTimestamp()),
+    finalPath: v.pipe(v.string(), v.minLength(1)),
+    schemaVersion: v.literal(EXTERNAL_TEMP_FILE_SCHEMA_VERSION),
+    tempPath: v.pipe(v.string(), v.minLength(1)),
+});
+export const createExternalTempFileRegistrar = (workspaceRoot) => async ({ finalPath, tempPath }) => {
+    const paths = await ensureLedgerDirectories(workspaceRoot);
+    const recordPath = path.join(paths.externalTempFilesDir, `${process.pid}.${Date.now()}.${randomUUID()}.json`);
+    await writeAtomicJsonFile(recordPath, v.parse(ExternalTempFileRecordSchema, {
+        createdAt: new Date().toISOString(),
+        finalPath: path.resolve(finalPath),
+        schemaVersion: EXTERNAL_TEMP_FILE_SCHEMA_VERSION,
+        tempPath: path.resolve(tempPath),
+    }));
+    return {
+        remove: async () => rm(recordPath, { force: true }),
+    };
+};
 const parseManifestText = (filePath, text) => {
     try {
         return v.parse(LedgerManifestSchema, JSON.parse(text));
@@ -268,22 +374,6 @@ const parseTempOwnerPid = (fileName) => {
     }
     return Number.parseInt(match[1], 10);
 };
-const isProcessAlive = (pid) => {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        const code = error.code;
-        if (code === 'EPERM') {
-            return true;
-        }
-        if (code === 'ESRCH') {
-            return false;
-        }
-        throw error;
-    }
-};
 const resolveFinalPathFromTemp = (filePath) => {
     const fileName = path.basename(filePath);
     const tempMarkerIndex = fileName.lastIndexOf('.tmp.');
@@ -304,10 +394,12 @@ const cleanupStaleTempFile = async (fullPath) => {
         throw error;
     }
     const ownerPid = parseTempOwnerPid(path.basename(fullPath));
-    if (Date.now() - fileStat.mtimeMs < LEDGER_STALE_TEMP_MS) {
-        return;
+    if (ownerPid !== null) {
+        if (isProcessAlive(ownerPid)) {
+            return;
+        }
     }
-    if (ownerPid !== null && isProcessAlive(ownerPid)) {
+    else if (Date.now() - fileStat.mtimeMs < LEDGER_STALE_TEMP_MS) {
         return;
     }
     const finalPath = resolveFinalPathFromTemp(fullPath);
@@ -325,6 +417,73 @@ const cleanupStaleTempFile = async (fullPath) => {
     }
     await rm(fullPath, { force: true });
 };
+const readExternalTempFileRecord = async (recordPath) => {
+    try {
+        const text = await readFile(recordPath, 'utf8');
+        return {
+            kind: 'valid',
+            record: v.parse(ExternalTempFileRecordSchema, JSON.parse(text)),
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return {
+                kind: 'missing',
+            };
+        }
+        return {
+            kind: 'invalid',
+        };
+    }
+};
+const pathExists = async (filePath) => {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+};
+const isTrackedAtomicTempRecord = (record) => path.dirname(record.tempPath) === path.dirname(record.finalPath) &&
+    path.basename(record.tempPath).startsWith(`${path.basename(record.finalPath)}.tmp.`);
+const quarantineInvalidExternalTempRecord = async (recordPath) => {
+    const quarantinedPath = `${recordPath}.invalid.${Date.now()}.${randomUUID()}`;
+    try {
+        await rename(recordPath, quarantinedPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
+};
+const cleanupTrackedExternalTempFile = async (recordPath) => {
+    const recordResult = await readExternalTempFileRecord(recordPath);
+    if (recordResult.kind === 'missing') {
+        return;
+    }
+    if (recordResult.kind === 'invalid') {
+        await quarantineInvalidExternalTempRecord(recordPath);
+        return;
+    }
+    if (!isTrackedAtomicTempRecord(recordResult.record)) {
+        await quarantineInvalidExternalTempRecord(recordPath);
+        return;
+    }
+    if (!(await pathExists(recordResult.record.tempPath))) {
+        await rm(recordPath, { force: true });
+        return;
+    }
+    await cleanupStaleTempFile(recordResult.record.tempPath);
+    if (!(await pathExists(recordResult.record.tempPath))) {
+        await rm(recordPath, { force: true });
+    }
+};
 const listLedgerTempFiles = async (root) => {
     const entries = await readdir(root, { withFileTypes: true });
     const tempFiles = [];
@@ -342,8 +501,16 @@ const listLedgerTempFiles = async (root) => {
 };
 export const cleanupStaleTempFiles = async (workspaceRoot) => {
     const paths = await ensureLedgerDirectories(workspaceRoot);
-    const tempFiles = await listLedgerTempFiles(paths.root);
-    await Promise.all(tempFiles.map(async (filePath) => cleanupStaleTempFile(filePath)));
+    const [tempFiles, externalTempRecords] = await Promise.all([
+        listLedgerTempFiles(paths.root),
+        readdir(paths.externalTempFilesDir, { withFileTypes: true }),
+    ]);
+    await Promise.all([
+        ...tempFiles.map(async (filePath) => cleanupStaleTempFile(filePath)),
+        ...externalTempRecords
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+            .map(async (entry) => cleanupTrackedExternalTempFile(path.join(paths.externalTempFilesDir, entry.name))),
+    ]);
 };
 export const readPhaseEntryFileNames = async (workspaceRoot, phase) => {
     const paths = await ensureLedgerDirectories(workspaceRoot);

package/dist/storage/lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAGA,KAAK,WAAW,GAAG;IACf,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE;QACjB,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACtG,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B,CAAC;AAqLF,MAAM,MAAM,UAAU,GAAG;IACrB,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AA+BF,eAAO,MAAM,WAAW,GAAU,UAAU,MAAM,EAAE,UAAS,OAAO,CAAC,WAAW,CAAM,KAAG,OAAO,CAAC,UAAU,CAgD1G,CAAC"}
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAIA,KAAK,WAAW,GAAG;IACf,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE;QACjB,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACtG,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B,CAAC;AAyMF,MAAM,MAAM,UAAU,GAAG;IACrB,QAAQ,CAAC,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACzC,CAAC;AAkCF,eAAO,MAAM,WAAW,GAAU,UAAU,MAAM,EAAE,UAAS,OAAO,CAAC,WAAW,CAAM,KAAG,OAAO,CAAC,UAAU,CAgD1G,CAAC"}

package/dist/storage/lock.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
-import { open, readFile, rename, rm, stat } from 'node:fs/promises';
+import { open, readFile, rename, rm } from 'node:fs/promises';
+import { isProcessAlive } from "../process.js";
 const DEFAULT_LOCK_OPTIONS = {
     // Give writers enough time to detect and reclaim a stale lock before timing out.
     retryDelayMs: 10,
@@ -7,6 +8,12 @@ const DEFAULT_LOCK_OPTIONS = {
     timeoutMs: 35_000,
 };
 const sleep = async (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const parseOwnerPid = (value) => {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        return null;
+    }
+    return value;
+};
 const readLockState = async (lockPath) => {
     try {
         const rawText = await readFile(lockPath, 'utf8');
@@ -14,6 +21,7 @@ const readLockState = async (lockPath) => {
             const parsed = JSON.parse(rawText);
             const startedAt = typeof parsed.startedAt === 'string' ? Date.parse(parsed.startedAt) : Number.NaN;
             return {
+                ownerPid: parseOwnerPid(parsed.pid),
                 rawText,
                 startedAtMs: Number.isNaN(startedAt) ? null : startedAt,
                 token: typeof parsed.token === 'string' && parsed.token.length > 0 ? parsed.token : null,
@@ -21,6 +29,7 @@ const readLockState = async (lockPath) => {
         }
         catch {
             return {
+                ownerPid: null,
                 rawText,
                 startedAtMs: null,
                 token: null,
@@ -35,6 +44,9 @@ const readLockState = async (lockPath) => {
     }
 };
 const isFreshLockState = (lockState, staleMs) => {
+    if (lockState.ownerPid !== null && !isProcessAlive(lockState.ownerPid)) {
+        return false;
+    }
     if (lockState.startedAtMs === null) {
         return false;
     }
@@ -62,17 +74,17 @@ const writeExclusiveTextFile = async (filePath, text) => {
         await handle.close();
     }
 };
-const reclaimMarkerExists = async (lockPath) => {
-    try {
-        await stat(buildReclaimMarkerPath(lockPath));
-        return true;
+const hasActiveReclaimMarker = async (lockPath, staleMs) => {
+    const reclaimMarkerPath = buildReclaimMarkerPath(lockPath);
+    const reclaimMarkerState = await readLockState(reclaimMarkerPath);
+    if (!reclaimMarkerState) {
+        return false;
     }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return false;
-        }
-        throw error;
+    if (isFreshLockState(reclaimMarkerState, staleMs)) {
+        return true;
     }
+    await rm(reclaimMarkerPath, { force: true });
+    return false;
 };
 const acquireReclaimMarker = async (lockPath) => {
     const reclaimMarkerPath = buildReclaimMarkerPath(lockPath);
@@ -126,17 +138,24 @@ const reclaimIfObservedStateMatches = async ({ lockPath, observedState, testHook
             }
             throw error;
         }
+        let shouldRemoveQuarantine = false;
         try {
             const quarantinedState = await readLockState(quarantinePath);
             if (!quarantinedState || quarantinedState.rawText !== observedState.rawText) {
                 await restoreQuarantinedLock(lockPath, quarantinePath);
                 return false;
             }
-            await rm(quarantinePath, { force: true });
+            shouldRemoveQuarantine = true;
             return true;
         }
+        catch (error) {
+            await restoreQuarantinedLock(lockPath, quarantinePath);
+            throw error;
+        }
         finally {
-            await rm(quarantinePath, { force: true });
+            if (shouldRemoveQuarantine) {
+                await rm(quarantinePath, { force: true });
+            }
         }
     }
     finally {
@@ -155,7 +174,10 @@ const reclaimIfStale = async (lockPath, options) => {
     });
 };
 const describeCurrentLockState = async (lockPath) => {
-    const [currentState, reclaiming] = await Promise.all([readLockState(lockPath), reclaimMarkerExists(lockPath)]);
+    const [currentState, reclaiming] = await Promise.all([
+        readLockState(lockPath),
+        hasActiveReclaimMarker(lockPath, DEFAULT_LOCK_OPTIONS.staleMs),
+    ]);
     if (!currentState) {
         return reclaiming ? 'lock missing while stale reclamation marker is present' : 'lock file is missing';
     }
@@ -163,7 +185,7 @@ const describeCurrentLockState = async (lockPath) => {
     return `${ageMs}, token=${currentState.token ?? 'missing'}, reclaiming=${reclaiming ? 'yes' : 'no'}`;
 };
 const assertOwnership = async (lockPath, token) => {
-    if (await reclaimMarkerExists(lockPath)) {
+    if (await hasActiveReclaimMarker(lockPath, DEFAULT_LOCK_OPTIONS.staleMs)) {
         throw new Error(`Lost ledger lock ownership for ${lockPath}: stale reclamation is in progress.`);
     }
     const currentState = await readLockState(lockPath);
@@ -182,7 +204,7 @@ export const acquireLock = async (lockPath, options = {}) => {
     const mergedOptions = { ...DEFAULT_LOCK_OPTIONS, ...options };
     const deadline = Date.now() + mergedOptions.timeoutMs;
     while (Date.now() <= deadline) {
-        if (await reclaimMarkerExists(lockPath)) {
+        if (await hasActiveReclaimMarker(lockPath, mergedOptions.staleMs)) {
             await sleep(mergedOptions.retryDelayMs);
             continue;
         }
@@ -201,7 +223,7 @@ export const acquireLock = async (lockPath, options = {}) => {
             finally {
                 await handle.close();
             }
-            if (await reclaimMarkerExists(lockPath)) {
+            if (await hasActiveReclaimMarker(lockPath, mergedOptions.staleMs)) {
                 await releaseIfOwned(lockPath, token);
                 await sleep(mergedOptions.retryDelayMs);
                 continue;

package/package.json

@@ -12,6 +12,7 @@
     "dependencies": {
         "safe-stable-stringify": "^2.5.0",
         "tar": "^7.5.15",
+        "ushman-lab-types": "^0.2.0",
         "valibot": "^1.4.1"
     },
     "description": "Append-only workspace ledger library and CLI for Ushman v4.",
@@ -70,5 +71,5 @@
     },
     "type": "module",
     "types": "dist/index.d.ts",
-    "version": "1.2.2"
+    "version": "1.3.1"
 }