@pentoshi/clai 4.11.2 → 4.11.4

package/dist/tools/fs.js

@@ -1,5 +1,5 @@
 import { createReadStream, lstatSync, readlinkSync, realpathSync } from "node:fs";
-import { open, readdir, readFile, writeFile, appendFile, unlink, rm, rename, mkdir, stat, chmod } from "node:fs/promises";
+import { open, readdir, readFile, appendFile, unlink, rm, rename, mkdir, stat, chmod } from "node:fs/promises";
 import { join, dirname, basename, relative, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { createInterface } from "node:readline";
@@ -20,7 +20,73 @@ import { buildFileChange, formatUnifiedPreview, } from "./file-diff.js";
  *   any failure so a crash cannot leave a stray `.clai-*` file behind.
  */
 let atomicWriteCounter = 0;
-export async function writeFileAtomic(resolved, contents) {
+const fileMutationLanes = new Map();
+const RETRYABLE_FS_CODES = new Set(["EAGAIN", "EBUSY", "EMFILE", "ENFILE", "EPERM"]);
+function mutationKey(path) {
+    return process.platform === "win32" ? path.toLowerCase() : path;
+}
+function mutationTarget(path) {
+    return canonicalizeForContainment(path) ?? path;
+}
+async function withFileMutation(path, operation) {
+    const key = mutationKey(mutationTarget(path));
+    const previous = fileMutationLanes.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    fileMutationLanes.set(key, current);
+    await previous.catch(() => undefined);
+    try {
+        return await operation();
+    }
+    finally {
+        release();
+        if (fileMutationLanes.get(key) === current)
+            fileMutationLanes.delete(key);
+    }
+}
+function appendShrankFailure(path, expected, actual) {
+    return {
+        ok: false,
+        output: `fs.append integrity check failed: expected prior bytes=${expected} but the file is only ${actual}. ` +
+            `It was truncated or this is the wrong path — appending would silently drop the missing content. (${path})`,
+        exitCode: 1,
+    };
+}
+function appendAlreadyApplied(original, content, position) {
+    if (content.length === 0)
+        return false;
+    return position === "start"
+        ? original.startsWith(content)
+        : original.endsWith(content);
+}
+async function fileTailEquals(path, size, content) {
+    const expected = Buffer.from(content, "utf8");
+    if (expected.length === 0 || size < expected.length)
+        return false;
+    let handle;
+    try {
+        handle = await open(path, "r");
+        const buffer = Buffer.alloc(expected.length);
+        await handle.read(buffer, 0, expected.length, size - expected.length);
+        return buffer.equals(expected);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+function retryableFsError(error) {
+    const code = error && typeof error === "object" && "code" in error
+        ? String(error.code ?? "")
+        : "";
+    return RETRYABLE_FS_CODES.has(code);
+}
+async function writeFileAtomicAttempt(path, contents) {
+    const resolved = mutationTarget(path);
     const priorMode = await stat(resolved)
         .then((st) => st.mode & 0o7777)
         .catch(() => undefined);
@@ -36,9 +102,8 @@ export async function writeFileAtomic(resolved, contents) {
         await handle.sync();
         await handle.close();
         handle = undefined;
-        if (priorMode !== undefined) {
+        if (priorMode !== undefined)
             await chmod(tempPath, priorMode);
-        }
         await rename(tempPath, resolved);
     }
     catch (error) {
@@ -48,6 +113,19 @@ export async function writeFileAtomic(resolved, contents) {
         throw error;
     }
 }
+export async function writeFileAtomic(resolved, contents) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await writeFileAtomicAttempt(resolved, contents);
+            return;
+        }
+        catch (error) {
+            if (attempt >= 3 || !retryableFsError(error))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 15 * 2 ** attempt));
+        }
+    }
+}
 /**
  * Threshold above which whole-file mutation is refused or replaced by an
  * in-place strategy. Reading and rewriting a very large file holds 2x its size
@@ -648,34 +726,32 @@ export async function fsRead(path, options = {}) {
 }
 export async function fsWrite(path, content, options = {}) {
     const resolved = ensureWriteAllowed(path, options.confirmed);
-    // Create any missing parent directories so writing "src/index.js" into a
-    // fresh project just works — the agent should not have to chain a separate
-    // mkdir before every file write. This was the most common failure: ENOENT
-    // on a path whose parent dir did not exist yet.
-    let before = "";
-    let existed = false;
-    try {
-        before = await readFile(resolved, "utf8");
-        existed = true;
-    }
-    catch (error) {
-        if (error?.code !== "ENOENT")
-            throw error;
-    }
-    await mkdir(dirname(resolved), { recursive: true });
-    await writeFile(resolved, content, "utf8");
-    const change = buildFileChange({
-        path: resolved,
-        before,
-        after: content,
-        kind: existed ? "overwrite" : "create",
+    return withFileMutation(resolved, async () => {
+        let before = "";
+        let existed = false;
+        try {
+            before = await readFile(resolved, "utf8");
+            existed = true;
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT")
+                throw error;
+        }
+        await mkdir(dirname(resolved), { recursive: true });
+        await writeFileAtomic(resolved, content);
+        const change = buildFileChange({
+            path: resolved,
+            before,
+            after: content,
+            kind: existed ? "overwrite" : "create",
+        });
+        const verb = existed ? "Wrote" : "Created";
+        return {
+            ok: true,
+            output: describeWrite(resolved, content, verb),
+            fileChanges: [change],
+        };
     });
-    const verb = existed ? "Wrote" : "Created";
-    return {
-        ok: true,
-        output: describeWrite(resolved, content, verb),
-        fileChanges: [change],
-    };
 }
 /** Atomically replace an inclusive, 1-indexed line range in an existing file. */
 export async function fsReplaceLines(path, startLine, endLine, content, options = {}) {
@@ -683,36 +759,37 @@ export async function fsReplaceLines(path, startLine, endLine, content, options
     if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1 || endLine < startLine) {
         return { ok: false, output: "fs.replaceLines requires integers with 1 <= startLine <= endLine", exitCode: 1 };
     }
-    const original = await readFile(resolved, "utf8");
-    const newline = original.includes("\r\n") ? "\r\n" : "\n";
-    const hadFinalNewline = original.endsWith("\n");
-    const lines = original.split(/\r?\n/);
-    if (hadFinalNewline)
-        lines.pop();
-    if (endLine > lines.length) {
-        return { ok: false, output: `fs.replaceLines range ${startLine}-${endLine} exceeds ${lines.length} lines`, exitCode: 1 };
-    }
-    const replacement = content === "" ? [] : content.split(/\r?\n/);
-    if (replacement.at(-1) === "")
-        replacement.pop();
-    lines.splice(startLine - 1, endLine - startLine + 1, ...replacement);
-    const next = lines.join(newline) + (hadFinalNewline ? newline : "");
-    await writeFileAtomic(resolved, next);
-    // X10: receipt with line count + hash so the model notices size changes.
-    const verb = content === ""
-        ? `Deleted lines ${startLine}-${endLine} in`
-        : `Replaced lines ${startLine}-${endLine} in`;
-    const change = buildFileChange({
-        path: resolved,
-        before: original,
-        after: next,
-        kind: "edit",
+    return withFileMutation(resolved, async () => {
+        const original = await readFile(resolved, "utf8");
+        const newline = original.includes("\r\n") ? "\r\n" : "\n";
+        const hadFinalNewline = original.endsWith("\n");
+        const lines = original.split(/\r?\n/);
+        if (hadFinalNewline)
+            lines.pop();
+        if (endLine > lines.length) {
+            return { ok: false, output: `fs.replaceLines range ${startLine}-${endLine} exceeds ${lines.length} lines`, exitCode: 1 };
+        }
+        const replacement = content === "" ? [] : content.split(/\r?\n/);
+        if (replacement.at(-1) === "")
+            replacement.pop();
+        lines.splice(startLine - 1, endLine - startLine + 1, ...replacement);
+        const next = lines.join(newline) + (hadFinalNewline ? newline : "");
+        await writeFileAtomic(resolved, next);
+        const verb = content === ""
+            ? `Deleted lines ${startLine}-${endLine} in`
+            : `Replaced lines ${startLine}-${endLine} in`;
+        const change = buildFileChange({
+            path: resolved,
+            before: original,
+            after: next,
+            kind: "edit",
+        });
+        return {
+            ok: true,
+            output: describeWrite(resolved, next, verb),
+            fileChanges: [change],
+        };
     });
-    return {
-        ok: true,
-        output: describeWrite(resolved, next, verb),
-        fileChanges: [change],
-    };
 }
 const WRITE_MANY_MAX_FILES = 50;
 /**
@@ -754,18 +831,21 @@ export async function fsWriteMany(files, options = {}) {
         }
         try {
             const resolved = ensureWriteAllowed(file.path, options.confirmed);
-            let before = "";
-            let existed = false;
-            try {
-                before = await readFile(resolved, "utf8");
-                existed = true;
-            }
-            catch (error) {
-                if (error?.code !== "ENOENT")
-                    throw error;
-            }
-            await mkdir(dirname(resolved), { recursive: true });
-            await writeFile(resolved, file.content, "utf8");
+            const mutation = await withFileMutation(resolved, async () => {
+                let before = "";
+                let existed = false;
+                try {
+                    before = await readFile(resolved, "utf8");
+                    existed = true;
+                }
+                catch (error) {
+                    if (error?.code !== "ENOENT")
+                        throw error;
+                }
+                await mkdir(dirname(resolved), { recursive: true });
+                await writeFileAtomic(resolved, file.content);
+                return { before, existed };
+            });
             const bytes = Buffer.byteLength(file.content, "utf8");
             const nLines = file.content.length === 0 ? 0 : file.content.split(/\r?\n/).length;
             const sha = createHash("sha256")
@@ -775,9 +855,9 @@ export async function fsWriteMany(files, options = {}) {
             written.push(`${resolved} (bytes=${bytes} lines=${nLines} sha256_12=${sha})`);
             changes.push(buildFileChange({
                 path: resolved,
-                before,
+                before: mutation.before,
                 after: file.content,
-                kind: existed ? "overwrite" : "create",
+                kind: mutation.existed ? "overwrite" : "create",
             }));
         }
         catch (error) {
@@ -989,101 +1069,103 @@ export async function fsSearch(pattern, path = safeCwd(), options = {}) {
  */
 export async function fsEdit(path, oldText, newText, expectedReplacements, options = {}) {
     const resolved = ensureWriteAllowed(path, options.confirmed);
-    const priorStat = await stat(resolved).catch(() => undefined);
-    if (priorStat?.isFile() && priorStat.size > LARGE_MUTATION_BYTES) {
-        return {
-            ok: false,
-            output: `fs.edit refuses ${resolved}: ${priorStat.size.toLocaleString()} bytes exceeds the ${Math.round(LARGE_MUTATION_BYTES / (1024 * 1024))}MB whole-file edit limit. ` +
-                `Use fs.replaceLines for a bounded line range, or a streaming tool (sed -i / awk) via shell.exec.`,
-            exitCode: 1,
-        };
-    }
-    const content = await readFile(resolved, "utf8");
-    const expected = expectedReplacements ?? 1;
-    let targetOldText = oldText;
-    let targetNewText = newText;
-    // Count occurrences (exact match first)
-    let count = 0;
-    let searchPos = 0;
-    while (true) {
-        const idx = content.indexOf(targetOldText, searchPos);
-        if (idx === -1)
-            break;
-        count += 1;
-        searchPos = idx + targetOldText.length;
-    }
-    // Fallback: match CRLF / LF line ending differences or trailing whitespace
-    if (count === 0) {
-        const hasCRLF = content.includes("\r\n");
-        const candidateOld = hasCRLF
-            ? oldText.replace(/\r?\n/g, "\r\n")
-            : oldText.replace(/\r\n/g, "\n");
-        const candidateNew = hasCRLF
-            ? newText.replace(/\r?\n/g, "\r\n")
-            : newText.replace(/\r\n/g, "\n");
-        let altCount = 0;
-        let altPos = 0;
+    return withFileMutation(resolved, async () => {
+        const priorStat = await stat(resolved).catch(() => undefined);
+        if (priorStat?.isFile() && priorStat.size > LARGE_MUTATION_BYTES) {
+            return {
+                ok: false,
+                output: `fs.edit refuses ${resolved}: ${priorStat.size.toLocaleString()} bytes exceeds the ${Math.round(LARGE_MUTATION_BYTES / (1024 * 1024))}MB whole-file edit limit. ` +
+                    `Use fs.replaceLines for a bounded line range, or a streaming tool (sed -i / awk) via shell.exec.`,
+                exitCode: 1,
+            };
+        }
+        const content = await readFile(resolved, "utf8");
+        const expected = expectedReplacements ?? 1;
+        let targetOldText = oldText;
+        let targetNewText = newText;
+        // Count occurrences (exact match first)
+        let count = 0;
+        let searchPos = 0;
         while (true) {
-            const idx = content.indexOf(candidateOld, altPos);
+            const idx = content.indexOf(targetOldText, searchPos);
             if (idx === -1)
                 break;
-            altCount += 1;
-            altPos = idx + candidateOld.length;
-        }
-        if (altCount > 0) {
-            targetOldText = candidateOld;
-            targetNewText = candidateNew;
-            count = altCount;
+            count += 1;
+            searchPos = idx + targetOldText.length;
         }
-        else {
-            const trimmedOld = candidateOld.trimEnd();
-            if (trimmedOld.length > 0) {
-                let trimCount = 0;
-                let trimPos = 0;
-                while (true) {
-                    const idx = content.indexOf(trimmedOld, trimPos);
-                    if (idx === -1)
-                        break;
-                    trimCount += 1;
-                    trimPos = idx + trimmedOld.length;
-                }
-                if (trimCount > 0) {
-                    targetOldText = trimmedOld;
-                    targetNewText = candidateNew.trimEnd();
-                    count = trimCount;
+        // Fallback: match CRLF / LF line ending differences or trailing whitespace
+        if (count === 0) {
+            const hasCRLF = content.includes("\r\n");
+            const candidateOld = hasCRLF
+                ? oldText.replace(/\r?\n/g, "\r\n")
+                : oldText.replace(/\r\n/g, "\n");
+            const candidateNew = hasCRLF
+                ? newText.replace(/\r?\n/g, "\r\n")
+                : newText.replace(/\r\n/g, "\n");
+            let altCount = 0;
+            let altPos = 0;
+            while (true) {
+                const idx = content.indexOf(candidateOld, altPos);
+                if (idx === -1)
+                    break;
+                altCount += 1;
+                altPos = idx + candidateOld.length;
+            }
+            if (altCount > 0) {
+                targetOldText = candidateOld;
+                targetNewText = candidateNew;
+                count = altCount;
+            }
+            else {
+                const trimmedOld = candidateOld.trimEnd();
+                if (trimmedOld.length > 0) {
+                    let trimCount = 0;
+                    let trimPos = 0;
+                    while (true) {
+                        const idx = content.indexOf(trimmedOld, trimPos);
+                        if (idx === -1)
+                            break;
+                        trimCount += 1;
+                        trimPos = idx + trimmedOld.length;
+                    }
+                    if (trimCount > 0) {
+                        targetOldText = trimmedOld;
+                        targetNewText = candidateNew.trimEnd();
+                        count = trimCount;
+                    }
                 }
             }
         }
-    }
-    if (count === 0) {
-        return {
-            ok: false,
-            output: `No matches found for the search text in ${resolved}. The text to replace was not found.`,
-            exitCode: 1,
-        };
-    }
-    if (count !== expected) {
+        if (count === 0) {
+            return {
+                ok: false,
+                output: `No matches found for the search text in ${resolved}. The text to replace was not found.`,
+                exitCode: 1,
+            };
+        }
+        if (count !== expected) {
+            return {
+                ok: false,
+                output: `Found ${count} occurrence(s) of the search text, but expected exactly ${expected}. Aborting to avoid unintended changes. Use expectedReplacements=${count} if you want to replace all.`,
+                exitCode: 1,
+            };
+        }
+        const updated = content.replaceAll(targetOldText, targetNewText);
+        // Atomic, mode-preserving, race-safe replacement.
+        await writeFileAtomic(resolved, updated);
+        const change = buildFileChange({
+            path: resolved,
+            before: content,
+            after: updated,
+            kind: "edit",
+        });
+        const preview = formatUnifiedPreview(change, { maxLines: 24 });
         return {
-            ok: false,
-            output: `Found ${count} occurrence(s) of the search text, but expected exactly ${expected}. Aborting to avoid unintended changes. Use expectedReplacements=${count} if you want to replace all.`,
-            exitCode: 1,
+            ok: true,
+            output: `Replaced ${count} occurrence(s) in ${resolved}.\n${preview}`,
+            fileChanges: [change],
         };
-    }
-    const updated = content.replaceAll(targetOldText, targetNewText);
-    // Atomic, mode-preserving, race-safe replacement.
-    await writeFileAtomic(resolved, updated);
-    const change = buildFileChange({
-        path: resolved,
-        before: content,
-        after: updated,
-        kind: "edit",
     });
-    const preview = formatUnifiedPreview(change, { maxLines: 24 });
-    return {
-        ok: true,
-        output: `Replaced ${count} occurrence(s) in ${resolved}.\n${preview}`,
-        fileChanges: [change],
-    };
 }
 /**
  * Delete a file or directory. Requires the path to be inside the
@@ -1091,54 +1173,57 @@ export async function fsEdit(path, oldText, newText, expectedReplacements, optio
  */
 export async function fsDelete(path, recursive, options = {}) {
     const resolved = ensureWriteAllowed(path, options.confirmed);
-    try {
-        // Snapshot text content for diff UI when deleting a single small file.
-        let before = "";
-        let canDiff = false;
-        if (!recursive) {
-            try {
-                const st = await stat(resolved);
-                if (st.isFile() && st.size <= 200_000) {
-                    before = await readFile(resolved, "utf8");
-                    canDiff = true;
+    return withFileMutation(resolved, async () => {
+        try {
+            // Snapshot text content for diff UI when deleting a single small file.
+            let before = "";
+            let canDiff = false;
+            if (!recursive) {
+                try {
+                    const st = await stat(resolved);
+                    if (st.isFile() && st.size <= 200_000) {
+                        before = await readFile(resolved, "utf8");
+                        canDiff = true;
+                    }
+                }
+                catch {
+                    /* ignore — delete may still succeed or fail below */
                 }
             }
-            catch {
-                /* ignore — delete may still succeed or fail below */
+            if (recursive) {
+                await rm(resolved, { recursive: true, force: false });
+                return { ok: true, output: `Deleted (recursive): ${resolved}` };
             }
+            await unlink(resolved);
+            const change = canDiff
+                ? buildFileChange({
+                    path: resolved,
+                    before,
+                    after: "",
+                    kind: "delete",
+                })
+                : buildFileChange({
+                    path: resolved,
+                    before: "",
+                    after: "",
+                    kind: "delete",
+                });
+            return {
+                ok: true,
+                output: `Deleted: ${resolved}`,
+                fileChanges: [change],
+            };
         }
-        if (recursive) {
-            await rm(resolved, { recursive: true, force: false });
-            return { ok: true, output: `Deleted (recursive): ${resolved}` };
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { ok: false, output: `Delete failed: ${msg}`, exitCode: 1 };
         }
-        await unlink(resolved);
-        const change = canDiff
-            ? buildFileChange({
-                path: resolved,
-                before,
-                after: "",
-                kind: "delete",
-            })
-            : buildFileChange({
-                path: resolved,
-                before: "",
-                after: "",
-                kind: "delete",
-            });
-        return {
-            ok: true,
-            output: `Deleted: ${resolved}`,
-            fileChanges: [change],
-        };
-    }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { ok: false, output: `Delete failed: ${msg}`, exitCode: 1 };
-    }
+    });
 }
 export async function fsAppend(path, content, options = {}) {
     const resolved = ensureWriteAllowed(path, options.confirmed);
     const position = options.position ?? "end";
+    const expectedPriorBytes = options.expectedPriorBytes;
     if (position !== "start" && position !== "end") {
         return {
             ok: false,
@@ -1146,94 +1231,100 @@ export async function fsAppend(path, content, options = {}) {
             exitCode: 1,
         };
     }
-    let original = "";
-    // Large-file guard: reading + rewriting a 500 MB log to append a few lines
-    // holds 2x the file in heap. Above the threshold, append in place with
-    // `appendFile` and say the diff was skipped for size.
-    const priorStat = await stat(resolved).catch(() => undefined);
-    if (priorStat?.isFile() &&
-        priorStat.size > LARGE_MUTATION_BYTES &&
-        position === "end") {
-        const priorBytesLarge = priorStat.size;
-        if (typeof options.expectedPriorBytes === "number" &&
-            options.expectedPriorBytes !== priorBytesLarge) {
-            return {
-                ok: false,
-                output: `fs.append integrity check failed for ${resolved}: expected prior bytes=${options.expectedPriorBytes}, actual=${priorBytesLarge}. ` +
-                    `Do NOT append again until you reconcile (read the last ~20 lines or re-write).`,
-                exitCode: 1,
-            };
-        }
-        await appendFile(resolved, content, "utf8");
-        const afterStat = await stat(resolved).catch(() => undefined);
+    if (expectedPriorBytes !== undefined &&
+        (!Number.isSafeInteger(expectedPriorBytes) || expectedPriorBytes < 0)) {
         return {
-            ok: true,
-            output: describeWrite(resolved, content, "Appended (end) to") +
-                `\n  prior_bytes=${priorBytesLarge} after_bytes=${afterStat?.size ?? priorBytesLarge + Buffer.byteLength(content, "utf8")}` +
-                `\n  note: file exceeds ${Math.round(LARGE_MUTATION_BYTES / (1024 * 1024))}MB — appended in place and skipped the diff/receipt hash of the whole file.`,
+            ok: false,
+            output: "fs.append expectedPriorBytes must be a non-negative safe integer.",
+            exitCode: 1,
         };
     }
-    try {
-        original = await readFile(resolved, "utf8");
-    }
-    catch (error) {
-        if (error?.code !== "ENOENT") {
-            throw error;
+    return withFileMutation(resolved, async () => {
+        const priorStat = await stat(resolved).catch(() => undefined);
+        if (priorStat?.isFile() &&
+            priorStat.size > LARGE_MUTATION_BYTES &&
+            position === "end") {
+            const priorBytes = priorStat.size;
+            if (expectedPriorBytes !== undefined && expectedPriorBytes > priorBytes) {
+                return appendShrankFailure(resolved, expectedPriorBytes, priorBytes);
+            }
+            const stale = expectedPriorBytes !== undefined && expectedPriorBytes < priorBytes;
+            if (stale && (await fileTailEquals(resolved, priorBytes, content))) {
+                return {
+                    ok: true,
+                    output: describeWrite(resolved, content, "Append already applied to") +
+                        `\n  prior_bytes=${priorBytes} expected_prior_bytes=${expectedPriorBytes}`,
+                };
+            }
+            await appendFile(resolved, content, "utf8");
+            const afterBytes = (await stat(resolved).catch(() => undefined))?.size ??
+                priorBytes + Buffer.byteLength(content, "utf8");
+            return {
+                ok: true,
+                output: describeWrite(resolved, content, "Appended (end) to") +
+                    `\n  prior_bytes=${priorBytes} after_bytes=${afterBytes}` +
+                    (stale ? `\n  note: expectedPriorBytes=${expectedPriorBytes} was stale; appended at ${priorBytes}.` : "") +
+                    `\n  note: file exceeds ${Math.round(LARGE_MUTATION_BYTES / (1024 * 1024))}MB — appended in place and skipped the diff/receipt hash of the whole file.`,
+            };
+        }
+        let original = "";
+        try {
+            original = await readFile(resolved, "utf8");
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT")
+                throw error;
+            if (expectedPriorBytes !== undefined && expectedPriorBytes !== 0) {
+                return {
+                    ok: false,
+                    output: `fs.append integrity check failed: expected prior bytes=${expectedPriorBytes} but file does not exist.`,
+                    exitCode: 1,
+                };
+            }
+            await mkdir(dirname(resolved), { recursive: true });
+            await writeFileAtomic(resolved, content);
+            const change = buildFileChange({
+                path: resolved,
+                before: "",
+                after: content,
+                kind: "create",
+            });
+            return {
+                ok: true,
+                output: describeWrite(resolved, content, "Created"),
+                fileChanges: [change],
+            };
         }
-        if (typeof options.expectedPriorBytes === "number" &&
-            options.expectedPriorBytes !== 0) {
+        const priorBytes = Buffer.byteLength(original, "utf8");
+        if (expectedPriorBytes !== undefined && expectedPriorBytes > priorBytes) {
+            return appendShrankFailure(resolved, expectedPriorBytes, priorBytes);
+        }
+        const stale = expectedPriorBytes !== undefined && expectedPriorBytes < priorBytes;
+        if (stale && appendAlreadyApplied(original, content, position)) {
             return {
-                ok: false,
-                output: `fs.append integrity check failed: expected prior bytes=${options.expectedPriorBytes} but file does not exist.`,
-                exitCode: 1,
+                ok: true,
+                output: describeWrite(resolved, original, "Append already applied to") +
+                    `\n  prior_bytes=${priorBytes} expected_prior_bytes=${expectedPriorBytes}`,
             };
         }
-        // File does not exist: create missing parent directories and write content
-        await mkdir(dirname(resolved), { recursive: true });
-        await writeFile(resolved, content, "utf8");
+        const next = position === "start" ? content + original : original + content;
+        await writeFileAtomic(resolved, next);
+        const afterBytes = Buffer.byteLength(next, "utf8");
         const change = buildFileChange({
             path: resolved,
-            before: "",
-            after: content,
-            kind: "create",
+            before: original,
+            after: next,
+            kind: "append",
         });
         return {
             ok: true,
-            output: describeWrite(resolved, content, "Created"),
+            output: describeWrite(resolved, next, `Appended (${position}) to`) +
+                `\n  prior_bytes=${priorBytes} after_bytes=${afterBytes}` +
+                (stale
+                    ? `\n  note: expectedPriorBytes=${expectedPriorBytes} was stale; appended at ${priorBytes}.`
+                    : ""),
             fileChanges: [change],
         };
-    }
-    const priorBytes = Buffer.byteLength(original, "utf8");
-    if (typeof options.expectedPriorBytes === "number" &&
-        options.expectedPriorBytes !== priorBytes) {
-        return {
-            ok: false,
-            output: `fs.append integrity check failed for ${resolved}: expected prior bytes=${options.expectedPriorBytes}, actual=${priorBytes}. ` +
-                `Do NOT append again until you reconcile (read the last ~20 lines or re-write).`,
-            exitCode: 1,
-        };
-    }
-    let next = "";
-    if (position === "start") {
-        next = content + original;
-    }
-    else {
-        next = original + content;
-    }
-    // Atomic, mode-preserving, race-safe replacement.
-    await writeFileAtomic(resolved, next);
-    const st = await stat(resolved).catch(() => undefined);
-    const change = buildFileChange({
-        path: resolved,
-        before: original,
-        after: next,
-        kind: "append",
     });
-    return {
-        ok: true,
-        output: describeWrite(resolved, next, `Appended (${position}) to`) +
-            `\n  prior_bytes=${priorBytes} after_bytes=${st?.size ?? Buffer.byteLength(next, "utf8")}`,
-        fileChanges: [change],
-    };
 }
 //# sourceMappingURL=fs.js.map