agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/state/write/lock.js

@@ -0,0 +1,837 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { assertRealpathBoundary } from "../../registries/artifactRegistry.js";
+import { assertValidatedProjectRoot } from "../projectRoot.js";
+import { reject } from "./errors.js";
+const sleepArray = new Int32Array(new SharedArrayBuffer(4));
+const INITIALIZATION_GRACE_MS = 250;
+const OWNER_NAME = "owner.json";
+const OWNER_PREPARATION_NAME = ".owner.json.tmp";
+const CLAIM_NAME = ".reclaim.json";
+const MAX_OWNER_BYTES = 8 * 1024;
+const MAX_RECOVERY_ENTRIES = 128;
+const DIRECTORY_FLAGS = fs.constants.O_RDONLY
+    | (fs.constants.O_DIRECTORY ?? 0)
+    | (fs.constants.O_NOFOLLOW ?? 0);
+const FILE_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0);
+const PRIVATE_NAME = /^\.writer\.(?:(\d+)\.)?([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})\.tmp$/;
+const LEGACY_CLAIM_NAME = /^\.writer\.[0-9a-f-]{36}\.claim$/;
+function lockRecord(value) {
+    if (value === null
+        || typeof value !== "object"
+        || !Number.isSafeInteger(value.pid)
+        || value.pid <= 0
+        || typeof value.token !== "string"
+        || value.token.length === 0
+        || typeof value.created_at !== "string")
+        return null;
+    return value;
+}
+function identity(fd) {
+    const stat = fs.fstatSync(fd, { bigint: true });
+    return { dev: stat.dev, ino: stat.ino };
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameRecord(left, right) {
+    return left.pid === right.pid
+        && left.token === right.token
+        && left.created_at === right.created_at;
+}
+function fdPath(fd, name) {
+    return name ? `/proc/self/fd/${fd}/${name}` : `/proc/self/fd/${fd}`;
+}
+function pathMatches(pathname, expectedFd, flags) {
+    let observedFd;
+    try {
+        observedFd = fs.openSync(pathname, flags);
+        return sameIdentity(identity(observedFd), identity(expectedFd));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (observedFd !== undefined)
+            fs.closeSync(observedFd);
+    }
+}
+function entryAbsent(directoryFd, name) {
+    try {
+        fs.lstatSync(fdPath(directoryFd, name));
+        return false;
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
+function readRecord(fd) {
+    try {
+        const stat = fs.fstatSync(fd, { bigint: true });
+        if (!stat.isFile() || stat.size > BigInt(MAX_OWNER_BYTES))
+            return null;
+        const size = Number(stat.size);
+        const bytes = Buffer.alloc(size);
+        let offset = 0;
+        while (offset < size) {
+            const read = fs.readSync(fd, bytes, offset, size - offset, offset);
+            if (read === 0)
+                break;
+            offset += read;
+        }
+        if (offset !== size)
+            return null;
+        return lockRecord(JSON.parse(bytes.toString("utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+function inspectRecord(directoryFd, name) {
+    let fd;
+    try {
+        fd = fs.openSync(fdPath(directoryFd, name), FILE_FLAGS);
+        const stat = fs.fstatSync(fd, { bigint: true });
+        const file = stat.isFile();
+        const record = file ? readRecord(fd) : null;
+        return record
+            ? { state: "valid", stale: false, fd, file, record }
+            : {
+                state: "malformed",
+                stale: Date.now() - Number(stat.mtimeMs) >= INITIALIZATION_GRACE_MS,
+                fd,
+                file,
+            };
+    }
+    catch (error) {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+        if (error.code !== "ENOENT") {
+            return { state: "malformed", stale: false, file: false };
+        }
+        const stat = fs.fstatSync(directoryFd, { bigint: true });
+        return {
+            state: "malformed",
+            stale: Date.now() - Number(stat.mtimeMs) >= INITIALIZATION_GRACE_MS,
+            file: false,
+        };
+    }
+}
+function inspectLock(lockPath) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            const fd = fs.openSync(lockPath, DIRECTORY_FLAGS);
+            return { state: "directory", fd, owner: inspectRecord(fd, OWNER_NAME) };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT")
+                return { state: "absent" };
+            if (code !== "ENOTDIR" && code !== "ELOOP")
+                throw error;
+        }
+        let stat;
+        try {
+            stat = fs.lstatSync(lockPath);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { state: "absent" };
+            throw error;
+        }
+        if (stat.isDirectory() && !stat.isSymbolicLink())
+            continue;
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            return { state: "unsupported", kind: stat.isSymbolicLink() ? "symbolic link" : "non-file entry" };
+        }
+        try {
+            const fd = fs.openSync(lockPath, FILE_FLAGS);
+            const opened = fs.fstatSync(fd);
+            if (opened.isFile())
+                return { state: "legacy_file", fd };
+            fs.closeSync(fd);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "EISDIR" || code === "ENOTDIR")
+                continue;
+            throw error;
+        }
+    }
+    return { state: "unsupported", kind: "entry changing during inspection" };
+}
+function closeRecord(inspection) {
+    if (inspection.fd !== undefined)
+        fs.closeSync(inspection.fd);
+}
+function closeInspection(inspection) {
+    if (inspection.state === "directory") {
+        closeRecord(inspection.owner);
+        fs.closeSync(inspection.fd);
+    }
+    else if (inspection.state === "legacy_file") {
+        fs.closeSync(inspection.fd);
+    }
+}
+function pidState(pid) {
+    if (pid === process.pid)
+        return "live";
+    try {
+        process.kill(pid, 0);
+        return "live";
+    }
+    catch (error) {
+        return error.code === "ESRCH" ? "dead" : "indeterminate";
+    }
+}
+function ownerIsDead(record) {
+    return pidState(record.pid) === "dead";
+}
+function syncDirectory(directory) {
+    const fd = typeof directory === "number" ? directory : fs.openSync(directory, DIRECTORY_FLAGS);
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        if (typeof directory !== "number")
+            fs.closeSync(fd);
+    }
+}
+function unlinkPinnedFile(directoryFd, name, expectedFd) {
+    if (!fs.fstatSync(expectedFd).isFile())
+        return false;
+    const target = fdPath(directoryFd, name);
+    if (!pathMatches(target, expectedFd, FILE_FLAGS))
+        return false;
+    try {
+        fs.unlinkSync(target);
+        syncDirectory(directoryFd);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function removePinnedDirectory(parentFd, name, directoryFd) {
+    const target = fdPath(parentFd, name);
+    if (!pathMatches(target, directoryFd, DIRECTORY_FLAGS))
+        return false;
+    try {
+        fs.rmdirSync(target);
+        syncDirectory(parentFd);
+        return true;
+    }
+    catch (error) {
+        if (["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code ?? ""))
+            return false;
+        throw error;
+    }
+}
+function recordCanBeRecovered(inspection, token) {
+    if (!inspection.file || inspection.fd === undefined)
+        return false;
+    if (inspection.state === "malformed")
+        return inspection.stale;
+    return (token === undefined || inspection.record.token === token) && ownerIsDead(inspection.record);
+}
+function recoverPrivateDirectory(parentFd, name, token, pid, transitionedTokens) {
+    // Preparation may pause indefinitely; only positive owner-death evidence permits mutation.
+    const privatePath = fdPath(parentFd, name);
+    let directoryFd;
+    try {
+        directoryFd = fs.openSync(privatePath, DIRECTORY_FLAGS);
+        const transitioned = transitionedTokens.has(token);
+        const namedPidState = pid === undefined ? undefined : pidState(pid);
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const names = fs.readdirSync(fdPath(directoryFd));
+            if (!pathMatches(privatePath, directoryFd, DIRECTORY_FLAGS)) {
+                return entryAbsent(parentFd, name) ? "recovered" : "unknown";
+            }
+            if (names.length === 0) {
+                if (namedPidState === "live")
+                    return "live";
+                if (!transitioned && namedPidState !== "dead")
+                    return "unknown";
+                return removePinnedDirectory(parentFd, name, directoryFd) || entryAbsent(parentFd, name)
+                    ? "recovered"
+                    : "unknown";
+            }
+            if (names.includes(OWNER_PREPARATION_NAME)) {
+                if (names.length !== 1)
+                    return "unknown";
+                const preparation = inspectRecord(directoryFd, OWNER_PREPARATION_NAME);
+                try {
+                    if (!preparation.file || preparation.fd === undefined) {
+                        if (entryAbsent(directoryFd, OWNER_PREPARATION_NAME))
+                            continue;
+                        return "unknown";
+                    }
+                    if (preparation.state === "valid"
+                        && (preparation.record.token !== token || preparation.record.pid !== pid))
+                        return "unknown";
+                    if (namedPidState === "live")
+                        return "live";
+                    if (namedPidState !== "dead")
+                        return "unknown";
+                    unlinkPinnedFile(directoryFd, OWNER_PREPARATION_NAME, preparation.fd);
+                    return removePinnedDirectory(parentFd, name, directoryFd) || entryAbsent(parentFd, name)
+                        ? "recovered"
+                        : "unknown";
+                }
+                finally {
+                    closeRecord(preparation);
+                }
+            }
+            if (names.length > MAX_RECOVERY_ENTRIES
+                || names.some((entry) => entry !== OWNER_NAME && !LEGACY_CLAIM_NAME.test(entry)))
+                return "unknown";
+            const records = names.map((entry) => ({ entry, inspection: inspectRecord(directoryFd, entry) }));
+            try {
+                const missing = records.filter(({ inspection }) => !inspection.file || inspection.fd === undefined);
+                if (missing.length > 0) {
+                    if (missing.every(({ entry }) => entryAbsent(directoryFd, entry)))
+                        continue;
+                    return "unknown";
+                }
+                if (records.some(({ inspection }) => inspection.state === "valid" && inspection.record.token !== token)) {
+                    return "unknown";
+                }
+                if (pid !== undefined
+                    && records.some(({ inspection }) => inspection.state === "valid" && inspection.record.pid !== pid))
+                    return "unknown";
+                const validRecords = records.filter(({ inspection }) => inspection.state === "valid");
+                const recordPidStates = validRecords.map(({ inspection }) => pidState(inspection.record.pid));
+                if (namedPidState === "indeterminate" || recordPidStates.includes("indeterminate"))
+                    return "unknown";
+                const fullyInitializedLivePreparation = pid !== undefined
+                    && namedPidState === "live"
+                    && records.every(({ inspection }) => inspection.state === "valid")
+                    && records.some(({ entry }) => entry === OWNER_NAME)
+                    && recordPidStates.every((state) => state === "live");
+                if (fullyInitializedLivePreparation)
+                    return "live";
+                if (namedPidState === "live" || recordPidStates.includes("live"))
+                    return "unknown";
+                if (!transitioned && (pid === undefined || namedPidState !== "dead"))
+                    return "unknown";
+                for (const { entry, inspection } of records) {
+                    unlinkPinnedFile(directoryFd, entry, inspection.fd);
+                }
+                return removePinnedDirectory(parentFd, name, directoryFd) || entryAbsent(parentFd, name)
+                    ? "recovered"
+                    : "unknown";
+            }
+            finally {
+                for (const { inspection } of records)
+                    closeRecord(inspection);
+            }
+        }
+        return "unknown";
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            return "recovered";
+        if (code === "ENOTDIR" || code === "ELOOP")
+            return "unknown";
+        throw error;
+    }
+    finally {
+        if (directoryFd !== undefined)
+            fs.closeSync(directoryFd);
+    }
+}
+function staleTransitionTokens(parentFd) {
+    const tokens = new Set();
+    let lockFd;
+    try {
+        lockFd = fs.openSync(fdPath(parentFd, ".writer.lock"), DIRECTORY_FLAGS);
+        for (const name of [OWNER_NAME, CLAIM_NAME]) {
+            const record = inspectRecord(lockFd, name);
+            try {
+                if (record.state === "valid" && ownerIsDead(record.record))
+                    tokens.add(record.record.token);
+            }
+            finally {
+                closeRecord(record);
+            }
+        }
+    }
+    catch (error) {
+        if (!["ENOENT", "ENOTDIR", "ELOOP"].includes(error.code ?? ""))
+            throw error;
+    }
+    finally {
+        if (lockFd !== undefined)
+            fs.closeSync(lockFd);
+    }
+    return tokens;
+}
+function recoverPreparedLocks(parentFd, lockPath) {
+    const candidates = fs.readdirSync(fdPath(parentFd), { withFileTypes: true })
+        .map((entry) => ({ entry, match: PRIVATE_NAME.exec(entry.name) }))
+        .filter(({ match }) => match !== null);
+    if (candidates.length > MAX_RECOVERY_ENTRIES) {
+        privateResidue(lockPath, candidates.map(({ entry }) => entry.name));
+    }
+    const transitionedTokens = staleTransitionTokens(parentFd);
+    const live = [];
+    const unresolved = [];
+    for (const { entry, match } of candidates) {
+        if (!entry.isDirectory() || entry.isSymbolicLink()) {
+            unresolved.push(entry.name);
+            continue;
+        }
+        const recovery = recoverPrivateDirectory(parentFd, entry.name, match[2], match[1] === undefined ? undefined : Number(match[1]), transitionedTokens);
+        if (recovery === "live")
+            live.push(entry.name);
+        if (recovery === "unknown")
+            unresolved.push(entry.name);
+    }
+    if (unresolved.length > 0)
+        privateResidue(lockPath, unresolved);
+    return live.length > 0;
+}
+function prepareLock(parentFd) {
+    const record = {
+        pid: process.pid,
+        token: randomUUID(),
+        created_at: new Date().toISOString(),
+    };
+    const name = `.writer.${record.pid}.${record.token}.tmp`;
+    const preparedPath = fdPath(parentFd, name);
+    let dirFd;
+    let ownerFd;
+    let ownerName = OWNER_PREPARATION_NAME;
+    try {
+        fs.mkdirSync(preparedPath, { mode: 0o700 });
+        dirFd = fs.openSync(preparedPath, DIRECTORY_FLAGS);
+        ownerFd = fs.openSync(fdPath(dirFd, ownerName), fs.constants.O_RDWR | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+        fs.writeFileSync(ownerFd, `${JSON.stringify(record)}\n`);
+        fs.fsyncSync(ownerFd);
+        const validated = readRecord(ownerFd);
+        if (validated === null || !sameRecord(validated, record)) {
+            throw new Error("writer owner metadata validation failed before publication");
+        }
+        fs.renameSync(fdPath(dirFd, ownerName), fdPath(dirFd, OWNER_NAME));
+        ownerName = OWNER_NAME;
+        syncDirectory(dirFd);
+        return { path: preparedPath, dirFd, ownerFd, record };
+    }
+    catch (error) {
+        if (dirFd !== undefined && ownerFd !== undefined) {
+            try {
+                unlinkPinnedFile(dirFd, ownerName, ownerFd);
+            }
+            catch {
+                // Preserve the acquisition error.
+            }
+        }
+        if (ownerFd !== undefined)
+            fs.closeSync(ownerFd);
+        if (dirFd !== undefined)
+            fs.closeSync(dirFd);
+        try {
+            fs.rmdirSync(preparedPath);
+            syncDirectory(parentFd);
+        }
+        catch {
+            // Preserve the acquisition error.
+        }
+        throw error;
+    }
+}
+function disposePrepared(prepared, parentFd) {
+    if (prepared.ownerFd >= 0 && prepared.dirFd >= 0) {
+        try {
+            unlinkPinnedFile(prepared.dirFd, OWNER_NAME, prepared.ownerFd);
+        }
+        catch {
+            // The owner was moved or the private directory changed identity.
+        }
+    }
+    if (prepared.ownerFd >= 0) {
+        fs.closeSync(prepared.ownerFd);
+        prepared.ownerFd = -1;
+    }
+    const exactDirectory = prepared.dirFd >= 0
+        && pathMatches(prepared.path, prepared.dirFd, DIRECTORY_FLAGS);
+    if (prepared.dirFd >= 0) {
+        fs.closeSync(prepared.dirFd);
+        prepared.dirFd = -1;
+    }
+    if (exactDirectory) {
+        try {
+            fs.rmdirSync(prepared.path);
+            syncDirectory(parentFd);
+        }
+        catch {
+            // A non-empty replacement is not this attempt's directory.
+        }
+    }
+}
+function verifyCanonicalLock(projectDirectory, parentFd, lockPath, lockFd, ownerFd, expected) {
+    if (!pathMatches(projectDirectory, parentFd, DIRECTORY_FLAGS))
+        return false;
+    let canonicalFd;
+    let canonicalOwnerFd;
+    try {
+        canonicalFd = fs.openSync(lockPath, DIRECTORY_FLAGS);
+        if (!sameIdentity(identity(canonicalFd), identity(lockFd)))
+            return false;
+        canonicalOwnerFd = fs.openSync(fdPath(canonicalFd, OWNER_NAME), FILE_FLAGS);
+        if (!sameIdentity(identity(canonicalOwnerFd), identity(ownerFd)))
+            return false;
+        const observed = readRecord(canonicalOwnerFd);
+        return observed !== null && sameRecord(observed, expected);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (canonicalOwnerFd !== undefined)
+            fs.closeSync(canonicalOwnerFd);
+        if (canonicalFd !== undefined)
+            fs.closeSync(canonicalFd);
+    }
+}
+function removeOwnedDirectory(parentFd, lockName, lockFd, ownerFd) {
+    if (!unlinkPinnedFile(lockFd, OWNER_NAME, ownerFd))
+        return false;
+    return removePinnedDirectory(parentFd, lockName, lockFd);
+}
+function writerLock(projectDirectory, lockPath, lockName, parentFd, lockFd, ownerFd, record, createdDirectory) {
+    let released = false;
+    return {
+        path: lockPath,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                if (verifyCanonicalLock(projectDirectory, parentFd, lockPath, lockFd, ownerFd, record)) {
+                    removeOwnedDirectory(parentFd, lockName, lockFd, ownerFd);
+                }
+            }
+            catch {
+                // A missing or replaced lock is not this owner's to remove.
+            }
+            fs.closeSync(ownerFd);
+            const exactDirectory = pathMatches(projectDirectory, parentFd, DIRECTORY_FLAGS);
+            fs.closeSync(lockFd);
+            fs.closeSync(parentFd);
+            if (createdDirectory && exactDirectory) {
+                try {
+                    fs.rmdirSync(projectDirectory);
+                }
+                catch {
+                    // A published artifact or peer now owns the directory.
+                }
+            }
+        },
+    };
+}
+function publishPrepared(prepared, projectDirectory, parentFd, lockPath, lockName, createdDirectory) {
+    try {
+        fs.renameSync(prepared.path, fdPath(parentFd, lockName));
+    }
+    catch (error) {
+        if (renameConflict(error))
+            return null;
+        throw error;
+    }
+    syncDirectory(parentFd);
+    if (verifyCanonicalLock(projectDirectory, parentFd, lockPath, prepared.dirFd, prepared.ownerFd, prepared.record)) {
+        return writerLock(projectDirectory, lockPath, lockName, parentFd, prepared.dirFd, prepared.ownerFd, prepared.record, createdDirectory);
+    }
+    try {
+        removeOwnedDirectory(parentFd, lockName, prepared.dirFd, prepared.ownerFd);
+    }
+    catch {
+        // Only the exact prepared instance may be cleaned.
+    }
+    fs.closeSync(prepared.ownerFd);
+    prepared.ownerFd = -1;
+    fs.closeSync(prepared.dirFd);
+    prepared.dirFd = -1;
+    return null;
+}
+function inspectedOwnerMatches(inspection) {
+    return inspection.owner.fd === undefined
+        ? entryAbsent(inspection.fd, OWNER_NAME)
+        : pathMatches(fdPath(inspection.fd, OWNER_NAME), inspection.owner.fd, FILE_FLAGS);
+}
+function recoverLegacyClaims(inspection) {
+    const names = fs.readdirSync(fdPath(inspection.fd));
+    if (names.length > MAX_RECOVERY_ENTRIES)
+        return false;
+    for (const name of names.filter((entry) => LEGACY_CLAIM_NAME.test(entry))) {
+        const claim = inspectRecord(inspection.fd, name);
+        try {
+            if (!recordCanBeRecovered(claim))
+                return false;
+            unlinkPinnedFile(inspection.fd, name, claim.fd);
+        }
+        finally {
+            closeRecord(claim);
+        }
+    }
+    return fs.readdirSync(fdPath(inspection.fd)).every((name) => name === OWNER_NAME || name === CLAIM_NAME);
+}
+function removeClaim(inspection, claim) {
+    const removed = unlinkPinnedFile(inspection.fd, CLAIM_NAME, claim.fd);
+    fs.closeSync(claim.fd);
+    claim.fd = -1;
+    return removed;
+}
+function claimInspectedDirectory(inspection, prepared, parentFd, lockName) {
+    const canonicalPath = fdPath(parentFd, lockName);
+    if (!pathMatches(canonicalPath, inspection.fd, DIRECTORY_FLAGS)
+        || !inspectedOwnerMatches(inspection)
+        || !recoverLegacyClaims(inspection))
+        return null;
+    const claimPath = fdPath(inspection.fd, CLAIM_NAME);
+    try {
+        // One fixed O_EXCL entry elects one reclaimer inside the exact directory inspected above.
+        fs.linkSync(fdPath(prepared.dirFd, OWNER_NAME), claimPath);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const existing = inspectRecord(inspection.fd, CLAIM_NAME);
+        try {
+            if (recordCanBeRecovered(existing))
+                unlinkPinnedFile(inspection.fd, CLAIM_NAME, existing.fd);
+        }
+        finally {
+            closeRecord(existing);
+        }
+        return null;
+    }
+    let claimFd;
+    try {
+        claimFd = fs.openSync(claimPath, FILE_FLAGS);
+        if (!sameIdentity(identity(claimFd), identity(prepared.ownerFd))
+            || fs.fstatSync(claimFd, { bigint: true }).nlink !== 2n) {
+            fs.closeSync(claimFd);
+            unlinkPinnedFile(inspection.fd, CLAIM_NAME, prepared.ownerFd);
+            return null;
+        }
+        const claim = { fd: claimFd };
+        syncDirectory(inspection.fd);
+        if (pathMatches(canonicalPath, inspection.fd, DIRECTORY_FLAGS)
+            && pathMatches(claimPath, claimFd, FILE_FLAGS)
+            && inspectedOwnerMatches(inspection))
+            return claim;
+        removeClaim(inspection, claim);
+        return null;
+    }
+    catch (error) {
+        if (claimFd !== undefined)
+            fs.closeSync(claimFd);
+        try {
+            unlinkPinnedFile(inspection.fd, CLAIM_NAME, prepared.ownerFd);
+        }
+        catch {
+            // Preserve the claim-publication error.
+        }
+        throw error;
+    }
+}
+function adoptInspectedDirectory(inspection, prepared, projectDirectory, parentFd, lockPath, lockName, createdDirectory) {
+    const claim = claimInspectedDirectory(inspection, prepared, parentFd, lockName);
+    if (!claim)
+        return null;
+    let transitioned = false;
+    try {
+        if (!inspectedOwnerMatches(inspection)) {
+            removeClaim(inspection, claim);
+            return null;
+        }
+        fs.renameSync(fdPath(prepared.dirFd, OWNER_NAME), fdPath(inspection.fd, OWNER_NAME));
+        transitioned = true;
+        syncDirectory(inspection.fd);
+        syncDirectory(parentFd);
+        if (!verifyCanonicalLock(projectDirectory, parentFd, lockPath, inspection.fd, prepared.ownerFd, prepared.record)) {
+            unlinkPinnedFile(inspection.fd, OWNER_NAME, prepared.ownerFd);
+            removeClaim(inspection, claim);
+            return null;
+        }
+        closeRecord(inspection.owner);
+        inspection.owner.fd = undefined;
+        const exactPrivateDirectory = pathMatches(prepared.path, prepared.dirFd, DIRECTORY_FLAGS);
+        if (!exactPrivateDirectory || !removePinnedDirectory(parentFd, path.basename(prepared.path), prepared.dirFd)) {
+            unlinkPinnedFile(inspection.fd, OWNER_NAME, prepared.ownerFd);
+            removeClaim(inspection, claim);
+            return null;
+        }
+        fs.closeSync(prepared.dirFd);
+        prepared.dirFd = -1;
+        if (!removeClaim(inspection, claim)) {
+            unlinkPinnedFile(inspection.fd, OWNER_NAME, prepared.ownerFd);
+            return null;
+        }
+        if (!verifyCanonicalLock(projectDirectory, parentFd, lockPath, inspection.fd, prepared.ownerFd, prepared.record)) {
+            unlinkPinnedFile(inspection.fd, OWNER_NAME, prepared.ownerFd);
+            return null;
+        }
+        return writerLock(projectDirectory, lockPath, lockName, parentFd, inspection.fd, prepared.ownerFd, prepared.record, createdDirectory);
+    }
+    catch (error) {
+        if (transitioned) {
+            try {
+                unlinkPinnedFile(inspection.fd, OWNER_NAME, prepared.ownerFd);
+            }
+            catch {
+                // The exact transitioned owner is already absent.
+            }
+        }
+        if (claim.fd >= 0) {
+            try {
+                removeClaim(inspection, claim);
+            }
+            catch {
+                if (claim.fd >= 0)
+                    fs.closeSync(claim.fd);
+            }
+        }
+        throw error;
+    }
+}
+function renameConflict(error) {
+    return ["EEXIST", "ENOTEMPTY", "ENOTDIR", "EISDIR"].includes(error.code ?? "");
+}
+function timeout(lockPath) {
+    reject({
+        class: "conflict",
+        message: `writer lock timeout at '${lockPath}'; retry the command after the active writer finishes`,
+        syntax: "agentera state <artifact-id> <verb> ... --format json",
+        example: "retry the same command after the active writer finishes",
+    });
+}
+function waitForContention(lockPath, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        timeout(lockPath);
+    Atomics.wait(sleepArray, 0, 0, Math.min(25, remaining));
+}
+function privateResidue(lockPath, names) {
+    const directory = path.dirname(lockPath);
+    const listed = names.slice(0, 3).map((name) => `'${path.join(directory, name)}'`).join(", ");
+    const omitted = names.length > 3 ? `, and ${names.length - 3} more` : "";
+    reject({
+        class: "conflict",
+        message: `private writer preparation residue at ${listed}${omitted} has unknown or unverifiable ownership and cannot be reclaimed safely; verify no Agentera writer is running, remove the listed residue, and retry`,
+        syntax: "agentera state <artifact-id> <verb> ... --format json",
+        example: `after verifying no Agentera writer is running, remove '${path.join(directory, names[0])}' and retry the same command`,
+    });
+}
+function unsupportedLock(lockPath, kind) {
+    const legacy = kind === "legacy file" ? "legacy writer lock file" : `writer lock ${kind}`;
+    reject({
+        class: "conflict",
+        message: `${legacy} at '${lockPath}' cannot be reclaimed safely; verify no Agentera writer is running, remove the entry, and retry`,
+        syntax: "agentera state <artifact-id> <verb> ... --format json",
+        example: `after verifying no Agentera writer is running, remove '${lockPath}' and retry the same command`,
+    });
+}
+function cleanupCreatedDirectory(projectDirectory, createdDirectory) {
+    if (!createdDirectory)
+        return;
+    try {
+        fs.rmdirSync(projectDirectory);
+    }
+    catch {
+        // A peer or project artifact now owns the directory.
+    }
+}
+function openProjectDirectory(projectRoot, expectedRoot) {
+    if (expectedRoot)
+        assertValidatedProjectRoot(expectedRoot);
+    const projectDirectory = path.join(projectRoot, ".agentera");
+    assertRealpathBoundary(projectRoot, projectDirectory, "writer lock");
+    const createdDirectory = !fs.existsSync(projectDirectory);
+    let parentFd;
+    try {
+        fs.mkdirSync(projectDirectory, { recursive: true });
+        if (expectedRoot)
+            assertValidatedProjectRoot(expectedRoot);
+        parentFd = fs.openSync(projectDirectory, DIRECTORY_FLAGS);
+        if (expectedRoot)
+            assertValidatedProjectRoot(expectedRoot);
+        return { projectDirectory, createdDirectory, parentFd };
+    }
+    catch (error) {
+        if (parentFd !== undefined)
+            fs.closeSync(parentFd);
+        cleanupCreatedDirectory(projectDirectory, createdDirectory);
+        throw error;
+    }
+}
+export function acquireWriterLock(projectRoot, timeoutMs = 2000, expectedRoot) {
+    const { projectDirectory, createdDirectory, parentFd } = openProjectDirectory(projectRoot, expectedRoot);
+    const lockName = ".writer.lock";
+    const lockPath = path.join(projectDirectory, lockName);
+    const anchoredLockPath = fdPath(parentFd, lockName);
+    const deadline = Date.now() + timeoutMs;
+    let prepared;
+    try {
+        let waitedForPreparation = false;
+        while (recoverPreparedLocks(parentFd, lockPath)) {
+            waitedForPreparation = true;
+            waitForContention(lockPath, deadline);
+        }
+        if (waitedForPreparation && Date.now() >= deadline)
+            timeout(lockPath);
+        prepared = prepareLock(parentFd);
+        while (true) {
+            if (expectedRoot)
+                assertValidatedProjectRoot(expectedRoot);
+            const published = publishPrepared(prepared, projectDirectory, parentFd, lockPath, lockName, createdDirectory);
+            if (published) {
+                try {
+                    if (expectedRoot)
+                        assertValidatedProjectRoot(expectedRoot);
+                }
+                catch (error) {
+                    published.release();
+                    prepared = undefined;
+                    throw error;
+                }
+                return published;
+            }
+            if (prepared.dirFd < 0 || prepared.ownerFd < 0) {
+                prepared = prepareLock(parentFd);
+            }
+            const existing = inspectLock(anchoredLockPath);
+            if (existing.state === "legacy_file") {
+                closeInspection(existing);
+                unsupportedLock(lockPath, "legacy file");
+            }
+            if (existing.state === "unsupported")
+                unsupportedLock(lockPath, existing.kind);
+            if (existing.state === "directory") {
+                const reclaimable = existing.owner.state === "valid"
+                    ? ownerIsDead(existing.owner.record)
+                    : existing.owner.stale;
+                if (reclaimable) {
+                    const lock = adoptInspectedDirectory(existing, prepared, projectDirectory, parentFd, lockPath, lockName, createdDirectory);
+                    if (lock)
+                        return lock;
+                }
+            }
+            closeInspection(existing);
+            waitForContention(lockPath, deadline);
+        }
+    }
+    catch (error) {
+        if (prepared !== undefined)
+            disposePrepared(prepared, parentFd);
+        fs.closeSync(parentFd);
+        cleanupCreatedDirectory(projectDirectory, createdDirectory);
+        throw error;
+    }
+}