om-memory-system 5.0.0 → 5.2.0

package/dist/services/skill-learning/drafting.d.ts

@@ -50,6 +50,19 @@ export type IdeasResult = {
     ok: true;
     ideas: SkillIdea[];
 } | DraftFailure;
+declare function tool(name: string, description: string, properties: Record<string, unknown>): {
+    type: string;
+    function: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+    };
+};
+export { tool };
 export declare function withFinalNewline(text: string): string;
 export declare function sameText(a: string, b: string): boolean;
 export declare const READ_ONLY: DraftFailure;

package/dist/services/skill-learning/drafting.js

@@ -37,6 +37,7 @@ function tool(name, description, properties) {
         },
     };
 }
+export { tool };
 const evidenceField = {
     type: "array",
     items: { type: "string" },

package/dist/services/skill-learning/failure-explain.d.ts

@@ -0,0 +1,52 @@
+import { type ProfileFailureCode } from "../../core/profile-failure.js";
+import { type SkillModel } from "./drafting.js";
+import { type FailureGroup } from "./failures.js";
+import type { SkillIndex } from "./skill-index.js";
+import type { SkillStore } from "./store.js";
+/** At most this many groups go to the model, most calls first. */
+export declare const MAX_EXPLAIN_GROUPS = 10;
+/** One input excerpt per group, cut to this many characters. */
+export declare const EXPLAIN_EXCERPT_CHARS = 500;
+/** What a cause is blamed on; the panel shows the label as a lead. */
+export type ExplainCauseKind = "skill" | "harness" | "environment" | "unknown";
+export interface ExplainCause {
+    kind: ExplainCauseKind;
+    explanation: string;
+    actions: string[];
+}
+/** The model's reply: a summary and labelled causes. Shown, never saved. */
+export interface FailureExplanation {
+    summary: string;
+    causes: ExplainCause[];
+}
+export type ExplainFailureCode = ProfileFailureCode | "not-found" | "invalid-args";
+export type ExplainResult = {
+    ok: true;
+    explanation: FailureExplanation;
+} | {
+    ok: false;
+    code: ExplainFailureCode;
+    message: string;
+};
+export interface ExplainDeps {
+    store: SkillStore;
+    index: SkillIndex;
+    model: SkillModel;
+}
+/**
+ * Builds the request the test asserts on: the skill name, its `SKILL.md` when
+ * a watched folder holds it, and the top groups. No prompts, no replies.
+ */
+export declare function explainUserPrompt(skill: {
+    name: string;
+    path: string | null;
+}, skillFile: string | null, groups: readonly FailureGroup[]): string;
+/**
+ * Asks the external API model to explain one skill's failure groups (design
+ * §9). The reply is returned, never saved. Reuses the drafting model path and
+ * its failure codes, including `not-configured`.
+ */
+export declare function explainFailures(skill: {
+    name: string;
+    path: string | null;
+}, deps: ExplainDeps): Promise<ExplainResult>;

package/dist/services/skill-learning/failure-explain.js

@@ -0,0 +1,131 @@
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { profileFailureCode, profileResultCode, } from "../../core/profile-failure.js";
+import { log } from "../logger.js";
+import { tool } from "./drafting.js";
+import { skillFailureGroups } from "./failures.js";
+/** At most this many groups go to the model, most calls first. */
+export const MAX_EXPLAIN_GROUPS = 10;
+/** One input excerpt per group, cut to this many characters. */
+export const EXPLAIN_EXCERPT_CHARS = 500;
+const ExplainReply = z.object({
+    summary: z.string(),
+    causes: z
+        .array(z.object({
+        kind: z.enum(["skill", "harness", "environment", "unknown"]),
+        explanation: z.string(),
+        actions: z.array(z.string()).default([]),
+    }))
+        .default([]),
+});
+const EXPLAIN_TOOL = tool("explain_skill_failures", "Explain a skill's failed tool calls", {
+    summary: { type: "string", description: "One or two plain sentences on what fails and why" },
+    causes: {
+        type: "array",
+        items: {
+            type: "object",
+            properties: {
+                kind: {
+                    type: "string",
+                    enum: ["skill", "harness", "environment", "unknown"],
+                    description: "skill: the SKILL.md should change; harness: a host or harness bug; environment: machine, setup or credentials; unknown",
+                },
+                explanation: { type: "string", description: "What the error text shows" },
+                actions: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Suggested actions, as leads from the error text only",
+                },
+            },
+            required: ["kind", "explanation", "actions"],
+        },
+    },
+});
+const EXPLAIN_SYSTEM = [
+    "You explain why a coding agent's tool calls failed while it used one skill (SKILL.md).",
+    "You see the skill file and its failure groups: tool name, first error line, counts, the last time seen and one short input excerpt. You cannot see the host's code.",
+    "Label each cause skill, harness, environment or unknown. Treat your labels and suggested actions as leads from error text only, not conclusions.",
+    "Write plain British English. Call the explain_skill_failures tool.",
+].join(" ");
+const FAILURE_TEXT = {
+    "not-configured": "The external API is not set up. Set it up in the External API card.",
+    "invalid-args": "This skill has no failed tool calls to explain.",
+    "invalid-reply": "The model reply was not valid, so nothing is shown. Try again.",
+    timeout: "The model did not reply in time",
+};
+/** Log one metadata record with the reason code only, and return the failure. */
+function fail(step, code) {
+    log(`Skill ${step} failed`, { host: null, reason: code }, "error");
+    return { ok: false, code, message: FAILURE_TEXT[code] ?? `Explaining failed: ${code}` };
+}
+function groupLine(group) {
+    const parts = [
+        `- Tool: ${group.name}`,
+        `Error: ${group.errorLine ?? "(no error text)"}`,
+        `Calls: ${group.calls} over ${group.turns} turns`,
+        `Last seen: ${new Date(group.lastSeenAt).toISOString()}`,
+    ];
+    const call = group.latest[0];
+    if (call) {
+        parts.push(`Input excerpt: "${call.input.slice(0, EXPLAIN_EXCERPT_CHARS)}"`);
+    }
+    return parts.join("; ");
+}
+/**
+ * Builds the request the test asserts on: the skill name, its `SKILL.md` when
+ * a watched folder holds it, and the top groups. No prompts, no replies.
+ */
+export function explainUserPrompt(skill, skillFile, groups) {
+    const file = skillFile === null ? "(not in a watched folder; no SKILL.md)" : `<<<\n${skillFile}\n>>>`;
+    return [
+        `Skill: ${skill.name}`,
+        `SKILL.md:\n${file}`,
+        `Failure groups, most calls first:`,
+        groups.map(groupLine).join("\n") || "(none)",
+    ].join("\n\n");
+}
+/**
+ * Asks the external API model to explain one skill's failure groups (design
+ * §9). The reply is returned, never saved. Reuses the drafting model path and
+ * its failure codes, including `not-configured`.
+ */
+export async function explainFailures(skill, deps) {
+    if (!deps.model.ready)
+        return fail("explain failures", "not-configured");
+    const groups = (await skillFailureGroups(deps.store, skill, deps.index)).slice(0, MAX_EXPLAIN_GROUPS);
+    if (groups.length === 0)
+        return fail("explain failures", "invalid-args");
+    let skillFile = null;
+    if (skill.path) {
+        try {
+            skillFile = readFileSync(skill.path, "utf8");
+        }
+        catch {
+            skillFile = null;
+        }
+    }
+    const user = explainUserPrompt(skill, skillFile, groups);
+    let result;
+    try {
+        result = await deps.model.callTool(EXPLAIN_SYSTEM, user, EXPLAIN_TOOL);
+    }
+    catch (error) {
+        return fail("explain failures", profileFailureCode(error));
+    }
+    if (!result.success)
+        return fail("explain failures", profileResultCode(result));
+    const parsed = ExplainReply.safeParse(result.data);
+    if (!parsed.success)
+        return fail("explain failures", "invalid-reply");
+    return {
+        ok: true,
+        explanation: {
+            summary: parsed.data.summary.trim(),
+            causes: parsed.data.causes.map((cause) => ({
+                kind: cause.kind,
+                explanation: cause.explanation.trim(),
+                actions: cause.actions.map((action) => action.trim()).filter(Boolean),
+            })),
+        },
+    };
+}

package/dist/services/skill-learning/failures.d.ts

@@ -0,0 +1,57 @@
+import type { SkillIndex } from "./skill-index.js";
+import type { SkillStore } from "./store.js";
+/** The server sends at most this many characters of one call's input (design §3). */
+export declare const FAILURE_INPUT_CAP = 20000;
+/** A group key is the first line of the error text, cut to this length (design §4). */
+export declare const FAILURE_LINE_CHARS = 200;
+/** How many of a group's latest calls the reply carries. */
+export declare const FAILURE_SAMPLE = 5;
+/** How many groups the reply carries, most calls first. */
+export declare const FAILURE_GROUP_LIMIT = 50;
+/** One failed tool call of a turn, as the dialog shows it. */
+export interface TurnFailure {
+    position: number;
+    name: string;
+    input: string;
+    /** True when the stored input was longer than `FAILURE_INPUT_CAP`. */
+    inputCut: boolean;
+    /** Null when the host reported no error text. */
+    error: string | null;
+}
+/** One failed call of a group: the call fields plus its turn's time and project. */
+export interface FailureGroupCall extends TurnFailure {
+    turnId: number;
+    createdAt: number;
+    projectName: string | null;
+}
+/** The failed calls of one skill that count against it, grouped by tool and first error line. */
+export interface FailureGroup {
+    /** The tool name. */
+    name: string;
+    /** The first line of the error text, cut to `FAILURE_LINE_CHARS`; null when no error text. */
+    errorLine: string | null;
+    /** Calls in the group. */
+    calls: number;
+    /** Turns the calls span. */
+    turns: number;
+    /** When the newest call of the group happened. */
+    lastSeenAt: number;
+    /** The latest `FAILURE_SAMPLE` calls, newest first. */
+    latest: FailureGroupCall[];
+}
+/**
+ * Every failed call of one turn, ordered by position. Null when the turn does
+ * not exist; an empty list when it has no failed call. A missing `skills.db`
+ * gives an empty list and stays missing.
+ */
+export declare function turnFailures(store: SkillStore, turnId: number): Promise<TurnFailure[] | null>;
+/**
+ * The failed calls of one skill that count against it by the ranking rule,
+ * grouped by tool name and the first line of the error text, most calls first.
+ * At most `FAILURE_GROUP_LIMIT` groups come back, each with its latest calls.
+ * A missing `skills.db` gives an empty list and stays missing.
+ */
+export declare function skillFailureGroups(store: SkillStore, skill: {
+    name: string;
+    path: string | null;
+}, index: SkillIndex): Promise<FailureGroup[]>;

package/dist/services/skill-learning/failures.js

@@ -0,0 +1,103 @@
+import { skillUsesFor } from "./turn-summaries.js";
+/** The server sends at most this many characters of one call's input (design §3). */
+export const FAILURE_INPUT_CAP = 20_000;
+/** A group key is the first line of the error text, cut to this length (design §4). */
+export const FAILURE_LINE_CHARS = 200;
+/** How many of a group's latest calls the reply carries. */
+export const FAILURE_SAMPLE = 5;
+/** How many groups the reply carries, most calls first. */
+export const FAILURE_GROUP_LIMIT = 50;
+// An empty error text is no error text, as a null one is: both show as
+// "No error text recorded". The first line of the error is the group key; a
+// trailing carriage return from CRLF text is not part of the key.
+const NO_ERROR = "tc.error IS NULL OR tc.error = ''";
+const LINE = `CASE WHEN ${NO_ERROR} THEN NULL
+  ELSE rtrim(substr(substr(tc.error, 1, instr(tc.error || char(10), char(10)) - 1), 1, ${FAILURE_LINE_CHARS}), char(13)) END`;
+const CALL_FIELDS = `
+  tc.position, tc.name,
+  substr(tc.input, 1, ${FAILURE_INPUT_CAP}) AS input,
+  length(tc.input) > ${FAILURE_INPUT_CAP} AS input_cut,
+  CASE WHEN ${NO_ERROR} THEN NULL ELSE tc.error END AS error`;
+function callRow(row) {
+    return {
+        position: Number(row.position),
+        name: String(row.name),
+        input: String(row.input),
+        inputCut: Number(row.input_cut) === 1,
+        error: row.error == null ? null : String(row.error),
+    };
+}
+/**
+ * Every failed call of one turn, ordered by position. Null when the turn does
+ * not exist; an empty list when it has no failed call. A missing `skills.db`
+ * gives an empty list and stays missing.
+ */
+export async function turnFailures(store, turnId) {
+    const db = await store.existingDb();
+    if (!db)
+        return [];
+    const turn = await db.get("SELECT id FROM turns WHERE id = ?", [turnId]);
+    if (!turn)
+        return null;
+    const rows = await db.all(`SELECT ${CALL_FIELDS} FROM tool_calls tc
+     WHERE tc.turn_id = ? AND tc.outcome = 'error' ORDER BY tc.position, tc.id`, [turnId]);
+    return rows.map(callRow);
+}
+/**
+ * The failed calls of one skill that count against it by the ranking rule,
+ * grouped by tool name and the first line of the error text, most calls first.
+ * At most `FAILURE_GROUP_LIMIT` groups come back, each with its latest calls.
+ * A missing `skills.db` gives an empty list and stays missing.
+ */
+export async function skillFailureGroups(store, skill, index) {
+    const db = await store.existingDb();
+    if (!db)
+        return [];
+    const uses = skillUsesFor(skill, index);
+    // The earliest use of this skill only, as the ranking measures it; another
+    // skill used earlier in the same turn does not move the line.
+    const firstUse = `SELECT u.turn_id, MIN(COALESCE(u.position, -1)) AS position
+    FROM (${uses.sql}) u GROUP BY u.turn_id`;
+    const failed = `SELECT tc.id, tc.turn_id, tc.position, tc.name, t.created_at, t.project_name, ${LINE} AS line,
+      substr(tc.input, 1, ${FAILURE_INPUT_CAP}) AS input,
+      length(tc.input) > ${FAILURE_INPUT_CAP} AS input_cut,
+      CASE WHEN ${NO_ERROR} THEN NULL ELSE tc.error END AS error
+    FROM tool_calls tc
+    JOIN turns t ON t.id = tc.turn_id
+    JOIN (${firstUse}) f ON f.turn_id = tc.turn_id
+    WHERE tc.outcome = 'error' AND tc.position > f.position`;
+    const top = `SELECT name, line, COUNT(*) AS calls, COUNT(DISTINCT turn_id) AS turn_count,
+       MAX(created_at) AS last_seen
+     FROM (${failed}) GROUP BY name, line
+     ORDER BY calls DESC, last_seen DESC, name, line LIMIT ${FAILURE_GROUP_LIMIT}`;
+    const groups = await db.all(top, uses.args);
+    if (groups.length === 0)
+        return [];
+    // The latest calls of the returned groups in one query: window functions work in the
+    // store's libSQL (checked for this change), so no JavaScript fallback is needed.
+    const latest = await db.all(`SELECT turn_id, created_at, project_name, position, name, line, input, input_cut, error
+     FROM (SELECT g.*, ROW_NUMBER() OVER (PARTITION BY g.name, g.line ORDER BY g.created_at DESC, g.id DESC) AS rn
+       FROM (${failed}) g
+       JOIN (${top}) k ON k.name = g.name AND k.line IS g.line)
+     WHERE rn <= ${FAILURE_SAMPLE} ORDER BY name, line, rn`, [...uses.args, ...uses.args]);
+    const byGroup = new Map();
+    for (const row of latest) {
+        const key = JSON.stringify([String(row.name), row.line == null ? null : String(row.line)]);
+        const list = byGroup.get(key) ?? [];
+        list.push({
+            ...callRow(row),
+            turnId: Number(row.turn_id),
+            createdAt: Number(row.created_at),
+            projectName: row.project_name == null ? null : String(row.project_name),
+        });
+        byGroup.set(key, list);
+    }
+    return groups.map((group) => ({
+        name: String(group.name),
+        errorLine: group.line == null ? null : String(group.line),
+        calls: Number(group.calls),
+        turns: Number(group.turn_count),
+        lastSeenAt: Number(group.last_seen),
+        latest: byGroup.get(JSON.stringify([String(group.name), group.line == null ? null : String(group.line)])) ?? [],
+    }));
+}

package/dist/services/skill-learning/turn-summaries.d.ts

@@ -12,6 +12,14 @@ export interface SkillTurnSummary {
     promptPreview: string;
     failedToolCalls: number;
 }
+/** The SQL that selects a skill's uses (turn id and position), and its parameters. */
+export declare function skillUsesFor(skill: {
+    name: string;
+    path: string | null;
+}, index: SkillIndex): {
+    sql: string;
+    args: (string | number)[];
+};
 /**
  * Turns that used one skill, newest first, `limit` of them after skipping
  * `offset`. `path` is null for a skill that no watched folder holds. A missing

package/dist/services/skill-learning/turn-summaries.js

@@ -17,16 +17,16 @@ function toSummary(row) {
 // The same use-to-skill rule as the ranking: a recorded path counts while the
 // index lists it; a use with no path belongs to the one watched skill with its name.
 const BY_PATH = `
-SELECT su.turn_id FROM skill_uses su
+SELECT su.turn_id, su.position FROM skill_uses su
 WHERE su.skill_path = ? OR (su.skill_path IS NULL AND su.skill_name = ? AND ? = 1)`;
 const BY_NAME = `
-SELECT su.turn_id FROM skill_uses su
+SELECT su.turn_id, su.position FROM skill_uses su
 WHERE su.skill_name = ? AND (
   (su.skill_path IS NOT NULL AND su.skill_path NOT IN (SELECT value FROM json_each(?)))
   OR (su.skill_path IS NULL AND ? = 0)
 )`;
-/** The SQL that selects a skill's turn ids, and its parameters. */
-function turnIdsFor(skill, index) {
+/** The SQL that selects a skill's uses (turn id and position), and its parameters. */
+export function skillUsesFor(skill, index) {
     const named = index.entries.filter((e) => e.name === skill.name);
     return skill.path
         ? {
@@ -42,6 +42,11 @@ function turnIdsFor(skill, index) {
             ],
         };
 }
+/** The SQL that selects a skill's turn ids, and its parameters. */
+function turnIdsFor(skill, index) {
+    const uses = skillUsesFor(skill, index);
+    return { sql: `SELECT turn_id FROM (${uses.sql})`, args: uses.args };
+}
 /**
  * Turns that used one skill, newest first, `limit` of them after skipping
  * `offset`. `path` is null for a skill that no watched folder holds. A missing

package/dist/services/skill-routes.js

@@ -1,9 +1,12 @@
 import { existsSync } from "node:fs";
+import { CONFIG } from "../config.js";
 import { RECORDING_OFF_TEXT, runSkillOperation, } from "../core/skill-operations.js";
 import { log } from "./logger.js";
 import { skillActivity, skillDaily } from "./skill-learning/activity.js";
 import { parseActivityQuery, topParam } from "./skill-learning/activity-range.js";
 import { undoProposal } from "./skill-learning/apply.js";
+import { turnFailures, skillFailureGroups } from "./skill-learning/failures.js";
+import { explainFailures } from "./skill-learning/failure-explain.js";
 import { skillHistory, withCanUndo } from "./skill-learning/history.js";
 import { skillOperationsDeps } from "./skill-learning/operations-deps.js";
 import { getProposal, setSkillMode, } from "./skill-learning/proposal-store.js";
@@ -11,6 +14,7 @@ import { listProposalSummaries } from "./skill-learning/proposal-summaries.js";
 import { intParam } from "./skill-learning/query-params.js";
 import { SKILL_ORDERS, rankSkills } from "./skill-learning/ranking.js";
 import { skillTurnSettingsFor } from "./skill-learning/settings-for.js";
+import { skillModel } from "./skill-learning/skill-model.js";
 import { getSkillIndex } from "./skill-learning/skill-index.js";
 import { SkillStore, SkillStoreError, skillsDbPath } from "./skill-learning/store.js";
 import { RECENT_TURN_LIMIT, countSkillTurns, recentSkillTurns, skillTurnsByIds, } from "./skill-learning/turn-summaries.js";
@@ -133,6 +137,25 @@ async function dispatch(path, method, url, readBody, ctx) {
         if (path === "/api/skills/skill") {
             return showSkill(url, { store, folders: settings.folders }, index(), now);
         }
+        if (path === "/api/skills/failures") {
+            return showFailureGroups(url, store, index(), now);
+        }
+        const turnFailuresMatch = /^\/api\/skills\/turns\/([^/]+)\/failures$/.exec(path);
+        if (turnFailuresMatch) {
+            let id = "";
+            try {
+                id = decodeURIComponent(turnFailuresMatch[1]);
+            }
+            catch {
+                // A malformed percent sequence is not a number; the check below rejects "".
+            }
+            if (!/^\d+$/.test(id))
+                return fail("invalid-args", "The turn id must be a number");
+            const failures = await turnFailures(store, Number(id));
+            if (failures === null)
+                return fail("not-found", "No such turn");
+            return ok("ok", { failures });
+        }
         if (path === "/api/skills/activity") {
             const query = parseActivityQuery(url, now);
             if ("error" in query)
@@ -179,6 +202,11 @@ async function dispatch(path, method, url, readBody, ctx) {
             return setMode(await readBody(), store, index());
         case "/api/skills/delete-turns":
             return deleteTurns(await readBody(), store);
+        case "/api/skills/explain-failures":
+            // Stored text goes to the external model, so recording must be on.
+            if (!settings.enabled)
+                return fail("recording-off", RECORDING_OFF_TEXT);
+            return explainFailureGroups(await readBody(), store, index(), now);
         case "/api/skills/record-past":
             return recordPast(settings.enabled, ctx);
     }
@@ -205,6 +233,30 @@ async function showSkill(url, deps, index, now) {
             : [],
     });
 }
+async function showFailureGroups(url, store, index, now) {
+    const path = text(url.searchParams.get("path"));
+    const name = text(url.searchParams.get("name"));
+    if (!path && !name)
+        return fail("invalid-args", "Give path or name");
+    const skill = (await rankSkills(store, index, now)).find((s) => path ? s.path === path : s.path === null && s.name === name);
+    if (!skill)
+        return fail("not-found", "No such skill");
+    return ok("ok", { groups: await skillFailureGroups(store, skill, index) });
+}
+/** Explains one skill's failure groups through the drafting model path. The reply is shown, never saved. */
+async function explainFailureGroups(body, store, index, now) {
+    const path = text(body.path);
+    const name = text(body.name);
+    if (!path && !name)
+        return fail("invalid-args", "Give path or name");
+    const skill = (await rankSkills(store, index, now)).find((s) => path ? s.path === path : s.path === null && s.name === name);
+    if (!skill)
+        return fail("not-found", "No such skill");
+    const result = await explainFailures(skill, { store, index, model: skillModel(CONFIG) });
+    if (!result.ok)
+        return fail(result.code, result.message);
+    return ok("explained", { explanation: result.explanation });
+}
 async function proposals(url, store, folders) {
     const state = text(url.searchParams.get("state"));
     const skill = text(url.searchParams.get("skill"));

package/dist/services/web-ensure.d.ts

@@ -70,6 +70,17 @@ export declare const START_LOCK_STALE_MS = 20000;
 export declare function startLockPath(home?: string): string;
 /** Lock files are private to the user (0600 in a 0700 folder), like the token file. */
 export declare const nodeLockFs: LockFs;
+/**
+ * `nodeLockFs.replace`: write the temp file, rename it over the target, and
+ * when the rename reports ENOENT for a temp file that was just written,
+ * rewrite it and try again, up to `rewrites` times.
+ */
+export declare function replaceRetrying(path: string, text: string, deps?: {
+    mkdir?: (dir: string) => void;
+    write?: (path: string, text: string) => void;
+    rename?: (from: string, to: string) => void;
+    rewrites?: number;
+}, rewrites?: number): void;
 /** `renameSync` that retries while Windows reports the target busy. */
 export declare function renameRetrying(from: string, to: string, rename?: (from: string, to: string) => void, platform?: NodeJS.Platform, wait?: (ms: number) => void): void;
 /** Remove the start lock when it names `pid`. A restart copy calls this once it owns the port. */

package/dist/services/web-ensure.js

@@ -70,16 +70,45 @@ export const nodeLockFs = {
         }
     },
     replace(path, text) {
-        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        const temp = `${path}.${process.pid}.tmp`;
-        writeFileSync(temp, text, { mode: 0o600 });
-        renameRetrying(temp, path);
+        replaceRetrying(path, text);
     },
 };
 // Windows can refuse a link or rename while another process has the file open.
 // Bound retries so a permanent permission error still reaches the caller.
 const WINDOWS_FILE_RETRY_WAITS_MS = [1, 2, 5, 10, 20, 50, 100, 200];
 const WINDOWS_FILE_BUSY_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
+/**
+ * How many times `replaceRetrying` rewrites its temp file when `rename`
+ * reports ENOENT for a file that was just written. Bun's rename can
+ * intermittently do that (see docs/tdr/030-intermittent-bun-rename-failure.md),
+ * which made tests/web-ensure.test.ts fail at random under load. Rewriting
+ * and retrying heals that without weakening a genuine failure, which keeps
+ * failing past this budget and still reaches the caller.
+ */
+const REPLACE_ENOENT_REWRITES = 3;
+/**
+ * `nodeLockFs.replace`: write the temp file, rename it over the target, and
+ * when the rename reports ENOENT for a temp file that was just written,
+ * rewrite it and try again, up to `rewrites` times.
+ */
+export function replaceRetrying(path, text, deps = {}, rewrites = deps.rewrites ?? REPLACE_ENOENT_REWRITES) {
+    const mkdir = deps.mkdir ?? ((dir) => mkdirSync(dir, { recursive: true, mode: 0o700 }));
+    const write = deps.write ?? ((file, body) => writeFileSync(file, body, { mode: 0o600 }));
+    const rename = deps.rename ?? ((from, to) => renameRetrying(from, to));
+    mkdir(dirname(path));
+    const temp = `${path}.${process.pid}.tmp`;
+    for (let attempt = 0;; attempt++) {
+        write(temp, text);
+        try {
+            rename(temp, path);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT" || attempt >= rewrites)
+                throw error;
+        }
+    }
+}
 /** `renameSync` that retries while Windows reports the target busy. */
 export function renameRetrying(from, to, rename = renameSync, platform = process.platform, wait = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)) {
     for (let attempt = 0;; attempt++) {