@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.921

package/dist/heart/failure-reports.js

@@ -0,0 +1,336 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOSED_REPORT_RETENTION_MS = exports.REPORTS_PER_ORIGIN_DAY = exports.REPORTS_PER_ORIGIN_HOUR = exports.REPORTS_PER_DAY = exports.REPORTS_PER_HOUR = void 0;
+exports.reportsDir = reportsDir;
+exports.errorClass = errorClass;
+exports.failureFingerprint = failureFingerprint;
+exports.readFailureReport = readFailureReport;
+exports.listFailureReports = listFailureReports;
+exports.reportBody = reportBody;
+exports.pruneClosedReports = pruneClosedReports;
+exports.fileFailureReport = fileFailureReport;
+exports.resolveFailureReport = resolveFailureReport;
+exports.fixLiveNoticeText = fixLiveNoticeText;
+exports.confirmResolvedReports = confirmResolvedReports;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const semver = __importStar(require("semver"));
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const escalation_grants_1 = require("../a2a/escalation-grants");
+const outbox_store_1 = require("../a2a/outbox-store");
+const resolution_proof_1 = require("../a2a/resolution-proof");
+const replay_harness_1 = require("../a2a/replay-harness");
+const runtime_1 = require("../nerves/runtime");
+const file_lock_1 = require("./file-lock");
+exports.REPORTS_PER_HOUR = 5;
+exports.REPORTS_PER_DAY = 20;
+exports.REPORTS_PER_ORIGIN_HOUR = 3;
+exports.REPORTS_PER_ORIGIN_DAY = 10;
+exports.CLOSED_REPORT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+const FIELD_MAX_CHARS = 2_000;
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+const REPORT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+function reportsDir(agentRoot) {
+    return path.join(agentRoot, "state", "reports");
+}
+function reportFile(agentRoot, id) {
+    return path.join(reportsDir(agentRoot), `${id}.json`);
+}
+function cap(value) {
+    return value.trim().slice(0, FIELD_MAX_CHARS);
+}
+/** The same failure reads the same: numbers, ids and paths are blanked so a retry with a new request id folds in. */
+function errorClass(error) {
+    return error.toLowerCase()
+        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gu, "<id>")
+        .replace(/(?:\/[\w.@-]+){2,}/gu, "<path>")
+        .replace(/\d+/gu, "<n>")
+        .replace(/\s+/gu, " ").trim().slice(0, 80);
+}
+function failureFingerprint(failedTool, error) {
+    return (0, node_crypto_1.createHash)("sha256").update(`${(failedTool ?? "").trim().toLowerCase()}\0${errorClass(error)}`).digest("hex").slice(0, 16);
+}
+function readFailureReport(agentRoot, id) {
+    if (!REPORT_ID.test(id))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(reportFile(agentRoot, id), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeReport(agentRoot, record) {
+    fs.mkdirSync(reportsDir(agentRoot), { recursive: true });
+    const file = reportFile(agentRoot, record.id);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+function listFailureReports(agentRoot) {
+    let names;
+    try {
+        names = fs.readdirSync(reportsDir(agentRoot));
+    }
+    catch {
+        return [];
+    }
+    return names.filter((name) => name.endsWith(".json")).flatMap((name) => {
+        const record = readFailureReport(agentRoot, name.slice(0, -5));
+        return record ? [record] : [];
+    });
+}
+function reportBody(record) {
+    const { origin } = record;
+    return [
+        `Failure report ${record.shortId} (${record.severity})${origin.ownerOrigin ? "" : " - UNTRUSTED ORIGIN: not the owner's session"}`,
+        origin.ownerOrigin ? `Ari asked: ${record.ariWords}` : `A session with ${origin.friendName ?? "an unknown friend"} (${origin.trustLevel ?? "unknown trust"}) reported: ${record.ariWords}`,
+        `I tried: ${record.tried}`,
+        `${record.failedTool ? `${record.failedTool} failed` : "I gave up"}: ${record.error}`,
+        `Conversation: ${origin.channel ?? "unknown"}/${origin.key ?? "unknown"}`,
+        `Origin: friend ${origin.friendId ?? "unknown"}, trust ${origin.trustLevel ?? "unknown"}, owner ${origin.ownerOrigin ? "yes" : "no"}`,
+    ].join("\n");
+}
+/** The origin friend, read from the friend store: only an active family friend on the owner profile is the owner. */
+async function resolveOrigin(store, origin) {
+    const friend = origin.friendId ? await store.get(origin.friendId) : null;
+    const ownerOrigin = Boolean(friend && friend.admissionState === "active" && friend.trustLevel === "family" && friend.capabilityProfileId === "sanctuary-owner");
+    return { ...origin, friendName: friend ? friend.name : null, trustLevel: friend ? String(friend.trustLevel) : null, ownerOrigin };
+}
+/** Closed reports are history; they go after a month so the directory does not grow without bound. */
+function pruneClosedReports(agentRoot, now = Date.now()) {
+    let pruned = 0;
+    for (const record of listFailureReports(agentRoot)) {
+        if (record.status === "closed" && record.closedAt && now - Date.parse(record.closedAt) > exports.CLOSED_REPORT_RETENTION_MS) {
+            fs.rmSync(reportFile(agentRoot, record.id), { force: true });
+            pruned += 1;
+        }
+    }
+    return pruned;
+}
+function lockDir(agentRoot) {
+    return path.join(reportsDir(agentRoot), ".locks");
+}
+function overBudget(created, now, perHour, perDay) {
+    return created.filter((at) => now - at < HOUR_MS).length >= perHour || created.filter((at) => now - at < DAY_MS).length >= perDay;
+}
+async function fileFailureReport(agentRoot, store, input, now = Date.now()) {
+    const ariWords = cap(input.ariWords);
+    const tried = cap(input.tried);
+    const error = cap(input.error);
+    if (!ariWords || !tried || !error)
+        return { ok: false, reason: "invalid", detail: "ari_words, tried and error are all required" };
+    const failedTool = input.failedTool?.trim() ? input.failedTool.trim().slice(0, 120) : null;
+    const fingerprint = failureFingerprint(failedTool ?? undefined, error);
+    const origin = await resolveOrigin(store, input.origin);
+    const replay = origin.friendId !== null && (0, replay_harness_1.isReplayWindowOpen)(agentRoot, origin.friendId, now);
+    // A replay identity speaks only inside its window; once the window closes it must not reach a real outbox.
+    if (!replay && origin.friendId !== null && (0, replay_harness_1.isReplayIdentity)(agentRoot, origin.friendId))
+        return { ok: false, reason: "invalid", detail: "a replay identity can file only while its replay window is open" };
+    // One lock around read, rate check and write, so two processes cannot both pass the budget or file the same failure twice.
+    return (0, file_lock_1.withFileLock)(lockDir(agentRoot), "file", async () => {
+        pruneClosedReports(agentRoot, now);
+        const existing = listFailureReports(agentRoot);
+        // A replay conversation never folds: each gate run must leave a fresh report to read back.
+        const open = replay ? undefined : existing.find((record) => !record.replay && record.fingerprint === fingerprint && record.status !== "closed");
+        if (open) {
+            const folded = await foldRepeat(agentRoot, open.id, { error, failedTool, origin }, now);
+            if (folded)
+                return folded;
+        }
+        const holders = (await (0, escalation_grants_1.escalationHolders)(agentRoot, store, now)).filter((holder) => replay ? (0, replay_harness_1.isReplayWindowOpen)(agentRoot, holder.id, now) : !(0, replay_harness_1.isReplayIdentity)(agentRoot, holder.id));
+        if (holders.length === 0)
+            return { ok: false, reason: "no_escalation_peer", detail: replay ? "no replay escalation peer" : "no friend holds the escalation grant" };
+        // Replay identities (the same check that keeps them out of owner policy) have no budget: every gate run files its reports, and the gate acknowledges them.
+        const real = existing.filter((record) => !record.replay);
+        if (!replay && overBudget(real.map((record) => Date.parse(record.createdAt)), now, exports.REPORTS_PER_HOUR, exports.REPORTS_PER_DAY)) {
+            return { ok: false, reason: "rate_limited", detail: `at most ${exports.REPORTS_PER_HOUR} new reports an hour and ${exports.REPORTS_PER_DAY} a day` };
+        }
+        if (!replay && overBudget(real.filter((record) => record.origin.friendId === origin.friendId).map((record) => Date.parse(record.createdAt)), now, exports.REPORTS_PER_ORIGIN_HOUR, exports.REPORTS_PER_ORIGIN_DAY)) {
+            return { ok: false, reason: "rate_limited", detail: `at most ${exports.REPORTS_PER_ORIGIN_HOUR} new reports an hour and ${exports.REPORTS_PER_ORIGIN_DAY} a day from one origin` };
+        }
+        const id = (0, node_crypto_1.randomUUID)();
+        const record = {
+            id, shortId: id.slice(0, 8), fingerprint, createdAt: new Date(now).toISOString(), lastSeenAt: new Date(now).toISOString(), occurrences: 1,
+            severity: input.severity, ariWords, tried, error, failedTool, origin, replay,
+            recipients: holders.map((holder) => holder.id), outboxEntries: {}, status: "open",
+        };
+        const outbox = new outbox_store_1.FileOutboxStore(agentRoot);
+        for (const holder of holders) {
+            record.outboxEntries[holder.id] = outbox.append(holder.id, {
+                kind: "failure_report",
+                body: reportBody(record),
+                meta: {
+                    reportId: id, shortId: record.shortId, severity: record.severity, failedTool, fingerprint, ariWords: record.ariWords, conversation: { channel: origin.channel, key: origin.key },
+                    origin: { friendId: origin.friendId, friendName: origin.friendName, trustLevel: origin.trustLevel, ownerOrigin: origin.ownerOrigin },
+                },
+            }, now).id;
+        }
+        writeReport(agentRoot, record);
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.failure_report_filed", message: "filed a failure report", meta: { reportId: id, severity: record.severity, recipients: holders.length, replay, ownerOrigin: origin.ownerOrigin } });
+        return { ok: true, id, shortId: record.shortId, duplicate: false, recipients: holders.length };
+    });
+}
+/** Counts a repeat on the open report (re-read under the report's own lock) and tells the recipients, at most once a day per report. */
+async function foldRepeat(agentRoot, id, repeat, now) {
+    return (0, file_lock_1.withFileLock)(lockDir(agentRoot), `report-${id}`, () => {
+        const fresh = readFailureReport(agentRoot, id);
+        if (!fresh || fresh.status === "closed")
+            return null;
+        const occurrences = fresh.occurrences + 1;
+        const notify = fresh.lastRepeatNoticeAt === undefined || now - Date.parse(fresh.lastRepeatNoticeAt) >= DAY_MS;
+        if (notify) {
+            const outbox = new outbox_store_1.FileOutboxStore(agentRoot);
+            for (const recipient of fresh.recipients) {
+                outbox.append(recipient, {
+                    kind: "report_repeat",
+                    body: `Failure report ${fresh.shortId} happened again (${occurrences} times so far)${repeat.origin.ownerOrigin ? "" : " - UNTRUSTED ORIGIN: not the owner's session"}. ${repeat.failedTool ? `${repeat.failedTool} failed` : "I gave up"}: ${repeat.error}`,
+                    meta: { reportId: fresh.id, shortId: fresh.shortId, occurrences, status: fresh.status, origin: { friendId: repeat.origin.friendId, friendName: repeat.origin.friendName, trustLevel: repeat.origin.trustLevel, ownerOrigin: repeat.origin.ownerOrigin } },
+                }, now);
+            }
+        }
+        writeReport(agentRoot, { ...fresh, occurrences, lastSeenAt: new Date(now).toISOString(), ...(notify ? { lastRepeatNoticeAt: new Date(now).toISOString() } : {}) });
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.failure_report_folded", message: "folded a repeat failure into an open report", meta: { reportId: fresh.id, occurrences, notified: notify } });
+        return { ok: true, id: fresh.id, shortId: fresh.shortId, duplicate: true, recipients: fresh.recipients.length };
+    });
+}
+/** Records the fix a recipient says is live from `version`; the owner is told only once the running version reaches it. */
+async function resolveFailureReport(agentRoot, input, now = Date.now()) {
+    if (!readFailureReport(agentRoot, input.id))
+        return { ok: false, reason: "unknown_report" };
+    return (0, file_lock_1.withFileLock)(lockDir(agentRoot), `report-${input.id}`, () => resolveLocked(agentRoot, input, now));
+}
+function resolveLocked(agentRoot, input, now) {
+    const record = readFailureReport(agentRoot, input.id);
+    /* v8 ignore next -- only a report pruned between the check above and taking its lock can be missing here @preserve */
+    if (!record)
+        return { ok: false, reason: "unknown_report" };
+    if (!record.recipients.includes(input.byFriendId))
+        return { ok: false, reason: "not_recipient" };
+    if (record.status === "closed")
+        return { ok: false, reason: "already_closed" };
+    const version = semver.valid(input.version);
+    if (!version || version !== input.version)
+        return { ok: false, reason: "bad_version" };
+    const note = cap(input.note);
+    if (!note)
+        return { ok: false, reason: "bad_note" };
+    writeReport(agentRoot, { ...record, status: "resolved", resolution: { version, note, by: input.byFriendId, at: new Date(now).toISOString(), resolvedAt: input.resolvedAt, signedNote: input.note, proof: input.proof } });
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.failure_report_resolved", message: "an escalation peer resolved a failure report", meta: { reportId: record.id, version } });
+    return { ok: true, id: record.id, status: "resolved" };
+}
+function fixLiveNoticeText(record) {
+    const resolution = record.resolution;
+    if (!record.origin.ownerOrigin) {
+        return `The fix for something I couldn't do earlier for ${record.origin.friendName ?? "a connected friend"} (report ${record.shortId}) is live now, in version ${resolution.version}. ${resolution.note}`;
+    }
+    return `The fix for what I couldn't do for you earlier (report ${record.shortId}) is live now, in version ${resolution.version}. ${resolution.note}\n\nYou asked: ${record.ariWords}`;
+}
+// Reports are rate limited and pruned, so this set stays small.
+const warnedSkips = new Set();
+/** The owner hears "fixed" only if the escalation holder signed it and still holds escalation; a file the Butler's own uid can write proves nothing. */
+async function resolutionIsSigned(agentRoot, deps, record, now) {
+    const resolution = record.resolution;
+    const skip = (reason) => {
+        // The confirm tick runs every few minutes, so each report warns once per process, not once per tick.
+        const key = `${record.id}:${reason}`;
+        if (warnedSkips.has(key))
+            return false;
+        warnedSkips.add(key);
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.failure_report_resolution_unverified", message: "skipped a resolved report that the holder's signature does not vouch for", meta: { reportId: record.id, by: resolution.by, reason } });
+        return false;
+    };
+    // A report that was ever closed already told the owner; a resolved status on it is a forgery or a replay.
+    if (record.closedAt !== undefined)
+        return skip("report was closed before");
+    // The owner is told exactly what was signed: the stored note must be the signed note, and the version its canonical form.
+    if (typeof resolution.signedNote !== "string" || resolution.note !== cap(resolution.signedNote))
+        return skip("note is not the signed note");
+    if (semver.valid(resolution.version) !== resolution.version)
+        return skip("version is not canonical");
+    const friend = deps.friends ? await deps.friends.get(resolution.by) : null;
+    if (!friend || !(0, escalation_grants_1.holdsEscalation)(agentRoot, friend, now))
+        return skip("holder no longer holds escalation");
+    // The key comes from the root-owned grant. The friend record is writable by the Butler's own uid and is never consulted for it.
+    const checked = (0, resolution_proof_1.verifyResolution)({
+        sodium: await (0, a2a_client_1.ready)(),
+        claim: { reportId: record.id, version: resolution.version, note: resolution.signedNote, resolvedAt: resolution.resolvedAt ?? "" },
+        proof: resolution.proof,
+        holderDid: (0, escalation_grants_1.pinnedHolderDid)(agentRoot, resolution.by, now),
+    });
+    return checked.ok;
+}
+/** Tells the owner about each resolved report whose fix has reached the running version, then closes it. */
+async function confirmResolvedReports(agentRoot, deps, now = Date.now()) {
+    const result = { closed: [], waiting: [], failed: [] };
+    for (const listed of listFailureReports(agentRoot)) {
+        if (listed.status !== "resolved" || !listed.resolution)
+            continue;
+        if (!semver.valid(deps.runningVersion) || !semver.gte(deps.runningVersion, listed.resolution.version)) {
+            result.waiting.push(listed.id);
+            continue;
+        }
+        try {
+            // The report is read again under its lock: a resolution or repeat may have landed since the listing.
+            const outcome = await (0, file_lock_1.withFileLock)(lockDir(agentRoot), `report-${listed.id}`, async () => {
+                const record = readFailureReport(agentRoot, listed.id);
+                if (!record || record.status !== "resolved" || !record.resolution)
+                    return "skipped";
+                if (!semver.gte(deps.runningVersion, record.resolution.version))
+                    return "waiting";
+                if (!(await resolutionIsSigned(agentRoot, deps, record, now)))
+                    return "skipped";
+                if (!record.replay)
+                    await deps.notifyOwner({ noticeId: `failure-fixed:${record.id}`, text: fixLiveNoticeText(record) });
+                writeReport(agentRoot, { ...record, status: "closed", closedAt: new Date(now).toISOString() });
+                (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.failure_report_closed", message: "closed a failure report after its fix went live", meta: { reportId: record.id, version: record.resolution.version } });
+                return "closed";
+            });
+            if (outcome === "closed")
+                result.closed.push(listed.id);
+            else if (outcome === "waiting")
+                result.waiting.push(listed.id);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.failure_report_notice_failed", message: "could not tell the owner a fix is live; will retry", meta: { reportId: listed.id, error: error instanceof Error ? error.message : String(error) } });
+            result.failed.push(listed.id);
+        }
+    }
+    pruneClosedReports(agentRoot, now);
+    return result;
+}

package/dist/heart/file-lock.js

@@ -0,0 +1,109 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFileLock = withFileLock;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const DEFAULT_STALE_MS = 120_000;
+const DEFAULT_WAIT_MS = 45_000;
+const DEFAULT_POLL_MS = 25;
+/**
+ * Breaks a stale lock by renaming it to a name only this caller knows, then removing that. Two waiters both seeing the
+ * same stale lock cannot both break it: only one rename succeeds, and the loser never touches a lock a third process
+ * has since taken under the original name.
+ */
+function breakStaleLock(lock) {
+    const broken = `${lock}.broken-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    try {
+        fs.renameSync(lock, broken);
+    }
+    catch {
+        /* v8 ignore next -- the loser of a break race finds the lock already renamed away, and simply retries @preserve */
+        return false;
+    }
+    removeLock(broken);
+    return true;
+}
+/** The lock directory is always empty, so removing it never recurses; another process may already have broken it as stale. */
+function removeLock(lock) {
+    try {
+        fs.rmdirSync(lock);
+    }
+    catch {
+        /* v8 ignore next -- a lock broken as stale by another process is already gone @preserve */
+        return;
+    }
+}
+/**
+ * Runs `fn` while holding a named lock in `dir`. The lock is a directory, because creating one is atomic across
+ * processes, which matters here: the Butler's senses (Telegram, A2A, the private runtime) are separate processes that
+ * share one bundle on disk.
+ */
+async function withFileLock(dir, name, fn, options = {}) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const waitMs = options.waitMs ?? DEFAULT_WAIT_MS;
+    const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+    fs.mkdirSync(dir, { recursive: true });
+    const lock = path.join(dir, `${name}.lock`);
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        try {
+            fs.mkdirSync(lock);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            /* v8 ignore next -- a holder releasing between the failed mkdir and this stat reads as an old lock, which is then simply retried @preserve */
+            const heldSince = fs.statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? 0;
+            if (Date.now() - heldSince > staleMs) {
+                /* v8 ignore next -- only the waiter whose rename won reports the break @preserve */
+                if (breakStaleLock(lock))
+                    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "heart", event: "heart.file_lock_broken", message: "broke a lock whose holder never released it", meta: { name, heldMs: Date.now() - heldSince } });
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`timed out waiting for the ${name} lock`);
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        removeLock(lock);
+    }
+}