pi-agent-edit 0.0.0-stage → 0.2.3

package/index.ts

@@ -0,0 +1,335 @@
+/**
+ * pi-agent-edit — an agent-oriented replacement for Pi's built-in `edit` tool.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { applyEdits, decode, encode, EditError, formatReport, whitespaceWarnings, type EditSpec } from "./engine.ts";
+import { atomicWrite, ConcurrentModificationError, sha } from "./writer.ts";
+
+export { atomicWrite } from "./writer.ts";
+
+// ───────────────────────────── schema ─────────────────────────────
+
+const EditItem = Type.Object({
+  oldText: Type.Optional(
+    Type.String({ description: "Text to replace, copied from the file. Small but unique. Locator option 1." }),
+  ),
+  newText: Type.String({ description: "Replacement text (or text to insert). Empty string deletes." }),
+  replaceAll: Type.Optional(Type.Boolean({ description: "With oldText: replace every occurrence." })),
+  nearLine: Type.Optional(
+    Type.Integer({ minimum: 1, description: "With oldText: if it occurs several times, pick the occurrence closest to this line." }),
+  ),
+  startLine: Type.Optional(
+    Type.Integer({ minimum: 1, description: "Locator option 2: first line (1-based) of the range to replace." }),
+  ),
+  endLine: Type.Optional(Type.Integer({ minimum: 1, description: "With startLine: last line of the range (inclusive). Defaults to startLine." })),
+  afterLine: Type.Optional(
+    Type.Integer({ minimum: 0, description: "Locator option 3: insert newText as new line(s) after this line (0 = top of file)." }),
+  ),
+});
+
+const EditParams = Type.Object({
+  path: Type.String({ description: "Path of the file to edit (relative or absolute)." }),
+  edits: Type.Array(EditItem, { minItems: 1, description: "One or more edits, all relative to the file BEFORE this call." }),
+  dryRun: Type.Optional(Type.Boolean({ description: "Preview the diff without writing." })),
+});
+
+const DESCRIPTION = `Edit an existing file with one or more targeted changes, applied atomically (all succeed or nothing is written).
+Each item in edits uses exactly ONE locator:
+- oldText: replace it with newText. Copy oldText from the file; keep it small but unique. Matching tolerates trailing whitespace, indentation (newText is re-indented to fit) and whitespace/quote/fullwidth-punctuation differences, but never rewrites text outside the match. If oldText occurs several times, the error shows context for up to 5 occurrences, unique oldText suggestions when available, and up to 12 matching line numbers you can pass as nearLine right away (unless multiple matches start on the same line); or set replaceAll: true.
+- startLine (+ optional endLine): replace that inclusive line range with newText; empty newText deletes the lines.
+- afterLine: insert newText as new line(s) after that line (0 = top of file).
+Line-number locators only work if you read or wrote the file after its last external change; otherwise use oldText.
+All edits refer to the file as it was BEFORE this call and must not overlap. dryRun: true previews without writing.
+The result shows a numbered diff of the changed lines, so re-reading is usually unnecessary. On failure the error shows the closest matching text with line numbers — fix oldText from it instead of re-reading.
+Use write (not edit) to create new files or fully rewrite small files.`;
+
+// ───────────────────────────── helpers ─────────────────────────────
+
+const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB
+
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/**
+ * Decode strictly. A lenient utf8 read turns every invalid byte (GBK, Latin-1, …) into
+ * U+FFFD and writing that back rewrites the WHOLE file, not just the edited region.
+ */
+function decodeUtf8(buf: Buffer, shown: string): string {
+  if (buf.includes(0)) throw new Error(`${shown} looks like a binary file; refusing to edit it.`);
+  try {
+    return utf8.decode(buf);
+  } catch {
+    throw new Error(
+      `${shown} is not valid UTF-8 (perhaps GBK, Latin-1 or another legacy encoding). Refusing to edit it, ` +
+        `because rewriting it as UTF-8 would corrupt every non-ASCII character in the file. ` +
+        `Convert it first (e.g. iconv -f GBK -t UTF-8) or edit it with a tool that preserves its encoding.`,
+    );
+  }
+}
+
+function resolvePath(cwd: string, p: string): string {
+  let q = p.trim();
+  if (q === "~" || q.startsWith("~/")) q = path.join(os.homedir(), q.slice(1));
+  return path.resolve(cwd, q);
+}
+
+/**
+ * Resolve to a real, existing path. Models often write file mentions as "@src/app.ts";
+ * the literal name is tried first so a file that really starts with "@" still works.
+ */
+async function resolveExisting(cwd: string, p: string): Promise<string> {
+  const q = p.trim();
+  const tries = [q];
+  if (q.startsWith("@") && q.length > 1) tries.push(q.slice(1));
+  let lastErr: unknown;
+  for (const t of tries) {
+    try {
+      return await fs.realpath(resolvePath(cwd, t));
+    } catch (err) {
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+const ITEM_ALIAS_KEYS = [
+  "old_text", "old_str", "old_string",
+  "new_text", "new_str", "new_string",
+  "replace_all", "near_line", "start_line", "end_line", "after_line",
+];
+
+const TOP_ALIAS_KEYS = [
+  "file_path", "filePath", "file", "dry_run",
+  "oldText", "newText", "replaceAll", "nearLine", "startLine", "endLine", "afterLine",
+  ...ITEM_ALIAS_KEYS,
+];
+
+/** Accept legacy / foreign argument shapes before schema validation. */
+function normalizeArgs(raw: any): any {
+  if (!raw || typeof raw !== "object") return raw;
+  const a: any = { ...raw };
+  a.path ??= a.file_path ?? a.filePath ?? a.file;
+  a.dryRun ??= a.dry_run;
+  if (a.dryRun === undefined) delete a.dryRun;
+
+  if (typeof a.edits === "string") {
+    try {
+      a.edits = JSON.parse(a.edits);
+    } catch {
+      /* leave for validation error */
+    }
+  }
+  if (a.edits && !Array.isArray(a.edits) && typeof a.edits === "object") a.edits = [a.edits];
+
+  const oldT = a.oldText ?? a.old_text ?? a.old_str ?? a.old_string;
+  const newT = a.newText ?? a.new_text ?? a.new_str ?? a.new_string;
+  const startL = a.startLine ?? a.start_line;
+  const afterL = a.afterLine ?? a.after_line;
+  if (!a.edits && newT !== undefined && (oldT !== undefined || startL !== undefined || afterL !== undefined)) {
+    a.edits = [{
+      oldText: oldT,
+      newText: newT,
+      replaceAll: a.replaceAll ?? a.replace_all,
+      nearLine: a.nearLine ?? a.near_line,
+      startLine: startL,
+      endLine: a.endLine ?? a.end_line,
+      afterLine: afterL,
+    }];
+  }
+
+  if (Array.isArray(a.edits)) {
+    a.edits = a.edits.map((e: any, i: number) => {
+      if (!e || typeof e !== "object") return e;
+      const o: any = { ...e };
+      o.oldText ??= o.old_text ?? o.old_str ?? o.old_string;
+      o.newText ??= o.new_text ?? o.new_str ?? o.new_string;
+      o.replaceAll ??= o.replace_all;
+      o.nearLine ??= o.near_line;
+      o.startLine ??= o.start_line;
+      o.endLine ??= o.end_line;
+      o.afterLine ??= o.after_line;
+      // Pi's schema conversion truncates Integer values before execute().
+      // Validate normalized locators here, while their original values survive.
+      for (const field of ["startLine", "endLine", "afterLine", "nearLine"] as const) {
+        // null means "not set"; "12" is a common way for models to send a number.
+        if (o[field] === null) o[field] = undefined;
+        if (typeof o[field] === "string" && /^\s*-?\d+\s*$/.test(o[field])) o[field] = Number(o[field]);
+        if (o[field] !== undefined && !Number.isSafeInteger(o[field])) {
+          throw new Error(`Edit #${i + 1}: ${field} must be a safe integer; received ${String(o[field])}. No changes written.`);
+        }
+      }
+      for (const k of ITEM_ALIAS_KEYS) delete o[k];
+      for (const k of ["oldText", "replaceAll", "nearLine", "startLine", "endLine", "afterLine"]) {
+        if (o[k] == null) delete o[k]; // null or undefined: not set
+      }
+      return o;
+    });
+  }
+  for (const k of TOP_ALIAS_KEYS) delete a[k];
+  return a;
+}
+
+function jsonWarning(file: string, before: string, after: string): string | undefined {
+  if (!/\.json$/i.test(file)) return undefined;
+  try {
+    JSON.parse(before.replace(/^\ufeff/, ""));
+  } catch {
+    return undefined;
+  }
+  try {
+    JSON.parse(after.replace(/^\ufeff/, ""));
+    return undefined;
+  } catch (e: any) {
+    return `WARNING: file was valid JSON before this edit and is not anymore (${e?.message ?? e}). Fix it now.`;
+  }
+}
+
+// ───────────────────────────── extension ─────────────────────────────
+
+interface View {
+  hash: string;
+  linesValid: boolean;
+}
+
+export default function (pi: ExtensionAPI) {
+  const views = new Map<string, View>();
+  // Line numbers shown by the last ambiguity error per file, valid only for that content.
+  const offers = new Map<string, { hash: string; lines: Set<number> }>();
+
+  // A "view" is what the model saw in its current context. Anything that swaps or rewrites
+  // that context invalidates it: a new session, switching/forking sessions, jumping in the
+  // session tree, or compaction. Event names differ between Pi versions; registering one a
+  // version does not emit is harmless.
+  for (const event of ["session_start", "session_switch", "session_fork", "session_branch", "session_tree", "session_compact"]) {
+    try {
+      pi.on(event as any, async () => {
+        views.clear();
+        offers.clear();
+      });
+    } catch {
+      /* event not supported by this Pi version */
+    }
+  }
+
+  pi.on("tool_result", async (event: any, ctx: any) => {
+    if ((event?.toolName !== "read" && event?.toolName !== "write") || event?.isError) return;
+    const p = event?.input?.path ?? event?.input?.file_path;
+    if (typeof p !== "string") return;
+    try {
+      const real = await resolveExisting(ctx.cwd, p);
+      const st = await fs.stat(real);
+      if (!st.isFile() || st.size > MAX_FILE_SIZE) return;
+      views.set(real, { hash: sha(await fs.readFile(real)), linesValid: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  pi.registerTool({
+    name: "edit",
+    label: "Edit",
+    description: DESCRIPTION,
+    promptSnippet: "Edit files: oldText replace (tolerant, lossless), line-range replace/delete, insert after line; atomic multi-edit",
+    promptGuidelines: [
+      "Prefer edit over write for changes to existing files; batch all changes to one file into a single edit call.",
+      "If an edit fails, use the closest-candidate text shown in the error to fix oldText instead of re-reading the whole file.",
+    ],
+    parameters: EditParams,
+    prepareArguments: normalizeArgs,
+
+    async execute(_toolCallId: string, params: any, signal: AbortSignal | undefined, _onUpdate: any, ctx: any) {
+      let target: string;
+      try {
+        target = await resolveExisting(ctx.cwd, params.path);
+      } catch {
+        throw new Error(`File not found: ${params.path}. Use the write tool to create a new file.`);
+      }
+      const st = await fs.stat(target);
+      if (st.isDirectory()) throw new Error(`${params.path} is a directory, not a file.`);
+      if (st.size > MAX_FILE_SIZE) throw new Error(`${params.path} is too large (${(st.size / 1024 / 1024).toFixed(1)} MB, limit ${MAX_FILE_SIZE / 1024 / 1024} MB). Refusing to edit.`);
+
+      return withFileMutationQueue(target, async () => {
+        const buf = await fs.readFile(target);
+        const raw = decodeUtf8(buf, params.path);
+        const hashBefore = sha(buf);
+
+        // Can line numbers the model remembers be trusted? Needed for startLine/afterLine,
+        // and for nearLine when it has to pick between several matches.
+        const v = views.get(target);
+        const staleReason = !v
+          ? `you have not read ${params.path} in this session`
+          : v.hash !== hashBefore
+            ? `${params.path} changed on disk since you last read it (by another tool or process)`
+            : !v.linesValid
+              ? `line count changed in part of ${params.path} during a previous edit since you last read it, so line numbers may have shifted`
+              : undefined;
+
+        const edits: EditSpec[] = params.edits;
+        const usesLines = edits.some((e) => e.startLine !== undefined || e.afterLine !== undefined);
+        if (usesLines && staleReason) {
+          const hint = "Re-read the relevant region with the read tool (offset/limit is fine) and retry, or use oldText instead of line numbers.";
+          if (!v) throw new Error(`Line-number edits need a fresh view: ${staleReason}. ${hint}`);
+          throw new Error(`Line-number edits rejected: ${staleReason}. ${hint}`);
+        }
+
+        const decoded = decode(raw);
+        let res;
+        try {
+          const offer = offers.get(target);
+          res = applyEdits(decoded, edits, {
+            lineNumbersTrusted: !staleReason,
+            untrustedReason: staleReason,
+            offeredNearLines: offer?.hash === hashBefore ? offer.lines : undefined,
+          });
+        } catch (err) {
+          if (err instanceof EditError) {
+            if (err.nearLineOffers?.length) offers.set(target, { hash: hashBefore, lines: new Set(err.nearLineOffers) });
+            throw new Error(err.message);
+          }
+          throw err;
+        }
+        const newRaw = encode(decoded, res.text);
+
+        if (!params.dryRun) {
+          if (signal?.aborted) throw new Error("Edit aborted before writing; file unchanged.");
+          try {
+            // Refuses to write if another process changed the file since it was read above.
+            await atomicWrite(target, newRaw, { expectedHash: hashBefore });
+            offers.delete(target);
+          } catch (err) {
+            if (err instanceof ConcurrentModificationError) views.delete(target);
+            throw err;
+          }
+          if (v) {
+            views.set(target, {
+              hash: sha(newRaw),
+              // Per-hunk check: equal totals can still shift every line in between.
+              linesValid: v.linesValid && v.hash === hashBefore && !res.linesShifted,
+            });
+          }
+        }
+
+        let text = formatReport(res, { path: params.path, dryRun: !!params.dryRun });
+        const warnings = [jsonWarning(target, raw, newRaw), ...whitespaceWarnings(target, res).map((w) => "WARNING: " + w)]
+          .filter((w): w is string => !!w);
+        if (warnings.length) text = warnings.join("\n") + "\n\n" + text;
+
+        return {
+          content: [{ type: "text" as const, text }],
+          details: {
+            path: target,
+            dryRun: !!params.dryRun,
+            added: res.added,
+            removed: res.removed,
+            levels: [...new Set(res.ranges.map((r) => r.level))],
+            report: text,
+          },
+        };
+      });
+    },
+  } as any);
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "pi-agent-edit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.3",
+  "description": "An agent-built edit tool for Pi: lossless tolerant matching, actionable ambiguity recovery, stale-read guards, and recoverable file writes.",
+  "type": "module",
+  "keywords": ["pi-package", "pi-extension", "edit", "coding-agent"],
+  "license": "MIT",
+  "author": "bjstan1979",
+  "files": [
+    "index.ts",
+    "engine.ts",
+    "writer.ts",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "scripts": {
+    "test": "tsx --test test/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0"
+  }
+}

package/writer.ts

@@ -0,0 +1,221 @@
+/**
+ * pi-agent-edit — safe file replacement (no Pi dependency, unit-testable).
+ *
+ * Preferred path: write a temp file next to the target, fsync it, re-check that the
+ * target still holds the bytes the edit was computed from, then rename over it.
+ *
+ * Fallback path (hard links, directories we cannot create files in, ownership we cannot
+ * restore): write through the existing inode. That cannot be atomic on POSIX, so it is
+ * made recoverable instead:
+ *   - the content is verified and written through ONE file descriptor;
+ *   - the original bytes are kept in memory and, best effort, in a backup file;
+ *   - new bytes are written over the old ones without O_TRUNC and the file is truncated
+ *     afterwards, so a failure never leaves an empty file;
+ *   - on any error the original is written back; only if that also fails does the error
+ *     point the user at the backup file.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Hash of the file's bytes (a string is hashed as its UTF-8 encoding, i.e. the bytes written). */
+export const sha = (s: string | Buffer) => createHash("sha1").update(s).digest("hex");
+
+/** The target changed between reading it and writing it. Nothing was written. */
+export class ConcurrentModificationError extends Error {}
+
+export interface WriteOptions {
+  /**
+   * sha1 of the bytes the new content was computed from. When set, the write is refused
+   * if the target no longer holds exactly those bytes (another process changed it).
+   */
+  expectedHash?: string;
+}
+
+/**
+ * Errors meaning "a new file cannot be created or swapped in here" (read-only or sticky
+ * directory, bind-mounted file, …). Only for these is an in-place write a safe fallback.
+ * Anything else — ENOSPC, EDQUOT, EIO — fails the whole write with the original untouched.
+ */
+const IN_PLACE_FALLBACK_CODES = new Set(["EACCES", "EPERM", "EROFS", "EXDEV", "EBUSY", "ENOTSUP", "EOPNOTSUPP", "EINVAL", "ENAMETOOLONG"]);
+
+const errCode = (err: unknown) => (err as NodeJS.ErrnoException)?.code ?? "";
+const errMsg = (err: unknown) => (err as Error)?.message ?? String(err);
+
+function concurrentError(target: string): ConcurrentModificationError {
+  return new ConcurrentModificationError(
+    `${target} was changed by another process while this edit was being prepared. Nothing was written. ` +
+      `Re-read the file and redo the edit against its current content.`,
+  );
+}
+
+async function verifyUnchanged(target: string, expectedHash: string | undefined): Promise<void> {
+  if (expectedHash === undefined) return;
+  let current: Buffer;
+  try {
+    current = await fs.readFile(target);
+  } catch (err) {
+    if (errCode(err) === "ENOENT") throw concurrentError(target);
+    throw err;
+  }
+  if (sha(current) !== expectedHash) throw concurrentError(target);
+}
+
+async function writeAll(h: FileHandle, buf: Buffer): Promise<void> {
+  let off = 0;
+  while (off < buf.length) {
+    const { bytesWritten } = await h.write(buf, off, buf.length - off, off);
+    if (bytesWritten <= 0) throw Object.assign(new Error("short write"), { code: "EIO" });
+    off += bytesWritten;
+  }
+}
+
+async function readAll(h: FileHandle): Promise<Buffer> {
+  const { size } = await h.stat();
+  const chunks: Buffer[] = [];
+  let pos = 0;
+  for (;;) {
+    const buf = Buffer.alloc(Math.max(size - pos, 64 * 1024));
+    const { bytesRead } = await h.read(buf, 0, buf.length, pos);
+    if (bytesRead === 0) break;
+    chunks.push(buf.subarray(0, bytesRead));
+    pos += bytesRead;
+  }
+  return Buffer.concat(chunks);
+}
+
+/** Best-effort: persist the rename itself. Some file systems refuse to fsync directories. */
+async function syncDir(dir: string): Promise<void> {
+  let h: FileHandle | undefined;
+  try {
+    h = await fs.open(dir, "r");
+    await h.sync();
+  } catch {
+    /* not supported here; the data itself was already fsynced */
+  } finally {
+    await h?.close().catch(() => {});
+  }
+}
+
+async function writeBackup(target: string, original: Buffer): Promise<string | undefined> {
+  const name = `pi-agent-edit-backup-${path.basename(target)}-${Date.now()}-${randomBytes(3).toString("hex")}`;
+  const file = path.join(os.tmpdir(), name);
+  try {
+    await fs.writeFile(file, original, { mode: 0o600, flag: "wx" });
+    return file;
+  } catch {
+    return undefined; // the in-memory copy is still used for rollback
+  }
+}
+
+/**
+ * Write through the existing inode, recoverably (see the file header). Exported for tests.
+ */
+export async function writeInPlace(target: string, content: string, opts: WriteOptions = {}): Promise<void> {
+  const next = Buffer.from(content, "utf8");
+  const h = await fs.open(target, "r+");
+  let backup: string | undefined;
+  try {
+    // Verify and write through the same descriptor: the content checked is the inode written.
+    const original = await readAll(h);
+    if (opts.expectedHash !== undefined && sha(original) !== opts.expectedHash) throw concurrentError(target);
+    backup = await writeBackup(target, original);
+    // Backup I/O can be slow. Recheck even without expectedHash: rollback must
+    // never intentionally use a snapshot already superseded during preparation.
+    if (sha(await readAll(h)) !== sha(original)) throw concurrentError(target);
+    try {
+      await writeAll(h, next);
+      await h.truncate(next.length);
+      await h.sync();
+    } catch (err) {
+      let restored = false;
+      try {
+        // Overwriting already-allocated blocks first, then truncating, needs no new space on
+        // ordinary file systems, so this normally succeeds even after ENOSPC.
+        await writeAll(h, original);
+        await h.truncate(original.length);
+        await h.sync();
+        restored = true;
+      } catch {
+        /* reported below */
+      }
+      if (restored) {
+        throw new Error(`Could not write ${target}: ${errMsg(err)}. The original content was restored; nothing was changed.`);
+      }
+      const keep = backup;
+      backup = undefined; // do not delete it in finally
+      throw new Error(
+        `Could not write ${target}: ${errMsg(err)}, and restoring the original also failed. The file may be partially written. ` +
+          (keep ? `A copy of the original is at ${keep}.` : `No backup copy could be created.`),
+      );
+    }
+  } finally {
+    await h.close().catch(() => {});
+    if (backup) await fs.rm(backup, { force: true }).catch(() => {});
+  }
+}
+
+export async function atomicWrite(target: string, content: string, opts: WriteOptions = {}): Promise<void> {
+  const st = await fs.stat(target);
+  if (st.nlink > 1) {
+    // Replacing the inode would split the hard links; write through it instead.
+    await writeInPlace(target, content, opts);
+    return;
+  }
+  const tmp = path.join(path.dirname(target), `.${path.basename(target)}.pi-edit-${randomBytes(4).toString("hex")}.tmp`);
+  const fallback = async (err: unknown, why: string) => {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    if (err instanceof ConcurrentModificationError) throw err;
+    const code = errCode(err);
+    if (!IN_PLACE_FALLBACK_CODES.has(code)) {
+      throw new Error(`Could not write ${target}: ${errMsg(err)}. The file was left unchanged.`);
+    }
+    console.warn(`[pi-agent-edit] ${why} (${code}); falling back to an in-place write for ${target}`);
+    await writeInPlace(target, content, opts);
+  };
+
+  try {
+    await fs.writeFile(tmp, content, { encoding: "utf8", mode: st.mode & 0o7777, flag: "wx" });
+  } catch (err) {
+    return fallback(err, "could not create a temporary file");
+  }
+  let keepInode = false;
+  try {
+    // Data must be on disk before the rename makes it the file's only copy.
+    const th = await fs.open(tmp, "r+");
+    try {
+      await th.sync();
+    } finally {
+      await th.close().catch(() => {});
+    }
+    const tst = await fs.stat(tmp);
+    if (tst.uid !== st.uid || tst.gid !== st.gid) {
+      // A new inode belongs to whoever runs Pi. Hand it back to the original owner/group;
+      // if that is not permitted, keep the original inode by writing in place.
+      try {
+        await fs.chown(tmp, st.uid, st.gid);
+      } catch (err) {
+        if (!["EPERM", "EACCES"].includes(errCode(err))) throw err;
+        keepInode = true;
+      }
+    }
+    if (!keepInode) {
+      // chown can clear setuid/setgid; restore mode only after ownership.
+      await fs.chmod(tmp, st.mode & 0o7777);
+      // Last check as close to the rename as possible. A writer that slips in between
+      // this read and the rename is the one window left (POSIX has no compare-and-rename).
+      await verifyUnchanged(target, opts.expectedHash);
+      await fs.rename(tmp, target);
+    }
+  } catch (err) {
+    return fallback(err, "atomic rename failed");
+  }
+  if (keepInode) {
+    await fs.rm(tmp, { force: true }).catch(() => {});
+    await writeInPlace(target, content, opts);
+    return;
+  }
+  await syncDir(path.dirname(target));
+}