Skip to content

The one and only agent harness for complex codebases. Project memory, planning, execution, and verified completion inside Codex.

8.8 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { closeSync, ftruncateSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
import { dirname } from "node:path";
import { UlwLoopError } from "./types.js";
// O_EXCL establishes ownership. Async holders keep the fd open and refresh a
// lease through that fd, never through the pathname: a reclaimed inode is invisible.
// Sync/legacy holders are lease-less and only dead pids retire their records.
// Expiry permits overlapping bodies; immutable revision publication fences them.
// Reclaim's reread/unlink is not atomic. On Windows an open inode may not unlink:
// treat that refusal as a live owner and fail closed. Release checks its token.
export const ULW_LOOP_LOCK_TIMEOUT_CODE = "ULW_LOOP_LOCK_TIMEOUT";
const DEFAULT_TIMEOUT_MS = 10_000;
const DEFAULT_STALE_MS = 60_000;
const DEFAULT_LEASE_MS = 30_000;
const SLEEP_CELL = new Int32Array(new SharedArrayBuffer(4));
const systemClock = {
    now: Date.now,
    schedule(fn, ms) {
        const timer = setTimeout(fn, ms);
        return {
            unref: () => {
                timer.unref();
            },
            cancel: () => clearTimeout(timer),
        };
    },
};
export async function withStateLock(lockPath, fn, options = {}) {
    const holder = await acquireAsync(lockPath, options);
    const clock = options.clock ?? systemClock;
    let timer;
    let heartbeatError;
    const beat = () => {
        try {
            holder.record.leaseUntil = clock.now() + (options.leaseMs ?? DEFAULT_LEASE_MS);
            writeRecord(holder);
            schedule();
        }
        catch (error) {
            heartbeatError = error;
        }
    };
    const schedule = () => {
        if (options.heartbeatMs === 0)
            return;
        timer = clock.schedule(beat, options.heartbeatMs ?? (options.leaseMs ?? DEFAULT_LEASE_MS) / 3);
        timer.unref();
    };
    schedule();
    try {
        const result = await fn(holder.record.token);
        if (heartbeatError !== undefined)
            throw heartbeatError;
        return result;
    }
    finally {
        timer?.cancel();
        closeSync(holder.fd);
        release(lockPath, holder.record.token);
    }
}
export function withStateLockSync(lockPath, fn, options = {}) {
    const holder = acquireSync(lockPath, options);
    try {
        return fn();
    }
    finally {
        closeSync(holder.fd);
        release(lockPath, holder.record.token);
    }
}
export function isStateLockTimeout(error) {
    return error instanceof UlwLoopError && error.code === ULW_LOOP_LOCK_TIMEOUT_CODE;
}
async function acquireAsync(lockPath, options) {
    const clock = options.clock ?? systemClock;
    const deadline = clock.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
    mkdirSync(dirname(lockPath), { recursive: true });
    for (let attempt = 0;;) {
        const outcome = attemptOnce(lockPath, options, clock.now(), options.leaseMs ?? DEFAULT_LEASE_MS);
        if (outcome.kind === "acquired")
            return outcome.holder;
        if (outcome.kind === "retry")
            continue;
        if (clock.now() >= deadline)
            throw lockTimeout(lockPath, options);
        await new Promise((resolve) => clock.schedule(resolve, backoffMs(attempt)));
        attempt += 1;
    }
}
function acquireSync(lockPath, options) {
    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
    mkdirSync(dirname(lockPath), { recursive: true });
    for (let attempt = 0;;) {
        const outcome = attemptOnce(lockPath, options, Date.now());
        if (outcome.kind === "acquired")
            return outcome.holder;
        if (outcome.kind === "retry")
            continue;
        if (Date.now() >= deadline)
            throw lockTimeout(lockPath, options);
        Atomics.wait(SLEEP_CELL, 0, 0, backoffMs(attempt));
        attempt += 1;
    }
}
function attemptOnce(lockPath, options, now, leaseMs) {
    try {
        const holder = tryCreate(lockPath, now, leaseMs);
        if (holder !== null)
            return { kind: "acquired", holder };
        const snapshot = readSnapshot(lockPath, now);
        if (snapshot === null)
            return { kind: "retry" };
        const record = snapshot.record;
        const stale = record === null
            ? snapshot.ageMs > (options.staleMs ?? DEFAULT_STALE_MS)
            : !isProcessAlive(record.pid) || (record.leaseUntil !== undefined && now > record.leaseUntil);
        if (stale && reclaim(lockPath, snapshot.raw))
            return { kind: "retry" };
        return { kind: "wait" };
    }
    catch (error) {
        if (hasCode(error, "EINTR"))
            return { kind: "wait" };
        throw error;
    }
}
function writeRecord(holder) {
    const buf = Buffer.from(JSON.stringify(holder.record));
    ftruncateSync(holder.fd, 0);
    let offset = 0;
    while (offset < buf.length) {
        const written = writeSync(holder.fd, buf, offset, buf.length - offset, offset);
        if (written === 0)
            throw new Error("State lock write made no progress.");
        offset += written;
    }
}
function tryCreate(lockPath, now, leaseMs) {
    let fd;
    try {
        fd = openSync(lockPath, "wx");
    }
    catch (error) {
        if (hasCode(error, "EEXIST"))
            return null;
        throw error;
    }
    const record = {
        pid: process.pid,
        createdAt: new Date(now).toISOString(),
        token: randomUUID(),
        ...(leaseMs === undefined ? {} : { leaseUntil: now + leaseMs }),
    };
    const holder = { fd, record };
    try {
        writeRecord(holder);
    }
    catch (error) {
        closeSync(fd);
        try {
            unlinkSync(lockPath);
        }
        catch (cleanup) {
            if (!hasCode(cleanup, "ENOENT"))
                throw cleanup;
        }
        throw error;
    }
    return holder;
}
function readSnapshot(lockPath, now) {
    try {
        const raw = readFileSync(lockPath, "utf8");
        return { raw, record: parseRecord(raw), ageMs: now - statSync(lockPath).mtimeMs };
    }
    catch (error) {
        if (hasCode(error, "ENOENT"))
            return null;
        throw error;
    }
}
function parseRecord(raw) {
    try {
        const record = JSON.parse(raw);
        if (typeof record !== "object" || record === null)
            return null;
        if (!("pid" in record) || typeof record.pid !== "number" || !Number.isInteger(record.pid) || record.pid <= 0)
            return null;
        if (!("createdAt" in record) || typeof record.createdAt !== "string")
            return null;
        if (!("token" in record) || typeof record.token !== "string" || record.token.length === 0)
            return null;
        return {
            pid: record.pid,
            createdAt: record.createdAt,
            token: record.token,
            ...("leaseUntil" in record && typeof record.leaseUntil === "number" ? { leaseUntil: record.leaseUntil } : {}),
        };
    }
    catch (error) {
        if (error instanceof SyntaxError)
            return null;
        throw error;
    }
}
function isProcessAlive(pid) {
    try {
        process.kill(pid, 0);
        return true;
    }
    catch (error) {
        if (hasCode(error, "ESRCH"))
            return false;
        if (hasCode(error, "EPERM"))
            return true;
        throw error;
    }
}
function reclaim(lockPath, expectedRaw) {
    const current = readSnapshot(lockPath, Date.now());
    if (current === null)
        return true;
    if (current.raw !== expectedRaw)
        return false;
    try {
        unlinkSync(lockPath);
    }
    catch (error) {
        if (hasCode(error, "EPERM") || hasCode(error, "EACCES"))
            return false;
        if (!hasCode(error, "ENOENT"))
            throw error;
    }
    return true;
}
function release(lockPath, token) {
    if (readSnapshot(lockPath, Date.now())?.record?.token !== token)
        return;
    try {
        unlinkSync(lockPath);
    }
    catch (error) {
        if (!hasCode(error, "ENOENT"))
            throw error;
    }
}
function backoffMs(attempt) {
    return Math.min(100, 5 * 2 ** attempt) + Math.random() * 5;
}
function lockTimeout(lockPath, options) {
    const holder = readSnapshot(lockPath, Date.now())?.record;
    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
    const owner = holder == null ? "another process" : `pid ${holder.pid}`;
    return new UlwLoopError(`ulw-loop state lock ${lockPath} is held by ${owner} for more than ${timeoutMs}ms. The lock owner is still alive. If a JS eval kernel was interrupted while writing, wait for its lease to expire (${options.leaseMs ?? DEFAULT_LEASE_MS} ms) or restart the owning senpi process; never delete a lock owned by a live process.`, ULW_LOOP_LOCK_TIMEOUT_CODE, { details: { lockPath, timeoutMs, ...(holder == null ? {} : { holderPid: holder.pid }) } });
}
function hasCode(error, code) {
    return error instanceof Error && "code" in error && error.code === code;
}