dsh-hashline-edit 0.1.0 → 0.2.0

package/src/fs-lifecycle.ts

@@ -0,0 +1,201 @@
+import { lstat, mkdir, realpath, rename, rm, rmdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { DomainError } from "./domain-errors.js";
+import { reportDiagnostic } from "./diagnostics.js";
+import { resolveTarget } from "./fs-write.js";
+import { errCode } from "./utils.js";
+
+/**
+ * Filesystem primitives for apply_patch's file lifecycle: classify, create directories, delete a
+ * regular file and rename one. Every entry point resolves through {@link resolveTarget}, the same
+ * symlink-resolving boundary every read/write uses, so a lifecycle action can never escape it.
+ *
+ * These are primitives, not a second write engine: file CONTENTS still go through writeAtomic;
+ * this module only owns namespace operations that writeAtomic deliberately does not express.
+ *
+ * @module dsh-hashline-edit/fs-lifecycle
+ */
+
+/** The physical kind of a path as the file layer sees it (symlinks resolved first). */
+export type PathKind = "file" | "directory" | "other" | "absent";
+
+/** Classify one path through the file layer's symlink-resolving boundary. */
+export async function pathKind(path: string): Promise<PathKind> {
+  const targetPath = await resolveTarget(path);
+  try {
+    const info = await lstat(targetPath);
+    if (info.isSymbolicLink()) return "other";
+    if (info.isFile()) return "file";
+    if (info.isDirectory()) return "directory";
+    return "other";
+  } catch (error: unknown) {
+    if (errCode(error) === "ENOENT") return "absent";
+    throw error;
+  }
+}
+
+/**
+ * True when `path` resolves inside `root` once every existing symlink/junction component is
+ * followed. A missing tail is checked against its nearest existing ancestor: an Add File under a
+ * junction ancestor therefore fails before mkdir can create anything outside the workspace.
+ */
+export async function isPathWithinWorkspace(root: string, path: string): Promise<boolean> {
+  const absolutePath = resolve(path);
+  const { root: fsRoot } = parse(absolutePath);
+  let cursor = fsRoot;
+  for (const part of absolutePath
+    .slice(fsRoot.length)
+    .split(sep)
+    .filter((value) => value.length > 0)) {
+    cursor = join(cursor, part);
+    try {
+      const info = await lstat(cursor);
+      if (info.isSymbolicLink()) return false;
+      // WHY: Windows junctions are reparse points that some Node builds do not classify as
+      // WHY: symlinks; a realpath that differs from the lexical path proves a link component.
+      if ((await realpath(cursor)) !== cursor) return false;
+    } catch (error: unknown) {
+      if (errCode(error) === "ENOENT") break;
+      throw error;
+    }
+  }
+  const rootReal = await realpath(resolve(root));
+  let ancestor = absolutePath;
+  for (;;) {
+    try {
+      const real = await realpath(ancestor);
+      const rel = relative(rootReal, real);
+      return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+    } catch (error: unknown) {
+      if (errCode(error) !== "ENOENT") throw error;
+      const parent = dirname(ancestor);
+      if (parent === ancestor) return false;
+      ancestor = parent;
+    }
+  }
+}
+
+/** Throw the E_PATCH_SYNTAX boundary refusal for one escaping lifecycle path. */
+export async function assertPathWithinWorkspace(root: string, path: string): Promise<void> {
+  if (!(await isPathWithinWorkspace(root, path))) {
+    throw new DomainError("E_PATCH_SYNTAX", {
+      message: `path escapes the workspace through a symlink or junction: ${path}`,
+      path,
+    });
+  }
+}
+
+/** Create one directory (and missing parents), through the symlink-resolving boundary. */
+export async function mkdirp(path: string, workspaceRoot?: string): Promise<void> {
+  if (path.includes("\0")) {
+    throw new DomainError("E_INTERNAL_INVARIANT", { message: "Path contains null byte." });
+  }
+  if (workspaceRoot !== undefined) await assertPathWithinWorkspace(workspaceRoot, path);
+  const targetPath = await resolveTarget(path);
+  await mkdir(targetPath, { recursive: true });
+  if (workspaceRoot !== undefined) await assertPathWithinWorkspace(workspaceRoot, path);
+}
+
+/**
+ * Delete one regular file. Deliberately NOT recursive: a lifecycle delete targets a file, and a
+ * directory at the same path is a caller bug that must surface, never be removed wholesale.
+ */
+export async function removeFile(path: string, signal?: AbortSignal): Promise<void> {
+  signal?.throwIfAborted();
+  const targetPath = await resolveTarget(path);
+  const kind = await pathKind(targetPath);
+  if (kind === "absent") {
+    const error = new Error(
+      "ENOENT: no such file or directory, unlink '" + targetPath + "'",
+    ) as NodeJS.ErrnoException;
+    error.code = "ENOENT";
+    throw error;
+  }
+  if (kind !== "file") {
+    throw new DomainError("E_INTERNAL_INVARIANT", {
+      message: "Refusing to delete a non-file lifecycle target: " + path,
+    });
+  }
+  await rm(targetPath, { force: false });
+}
+
+/**
+ * Rename one regular file, creating the destination parent first. The destination must not exist:
+ * a move never clobbers another file (spec §6: target-exists is a rejection, not an overwrite).
+ */
+export async function renameFile(
+  from: string,
+  to: string,
+  signal?: AbortSignal,
+  workspaceRoot?: string,
+): Promise<void> {
+  signal?.throwIfAborted();
+  if (workspaceRoot !== undefined) {
+    await assertPathWithinWorkspace(workspaceRoot, from);
+    await assertPathWithinWorkspace(workspaceRoot, to);
+  }
+  const fromPath = await resolveTarget(from);
+  const toPath = await resolveTarget(to);
+  const destinationKind = await pathKind(toPath);
+  if (destinationKind !== "absent") {
+    const error = new Error(
+      "EEXIST: file already exists, rename '" + fromPath + "' -> '" + toPath + "'",
+    ) as NodeJS.ErrnoException;
+    error.code = "EEXIST";
+    throw error;
+  }
+  await mkdirp(dirname(toPath), workspaceRoot);
+  if (workspaceRoot !== undefined) await assertPathWithinWorkspace(workspaceRoot, to);
+  await rename(fromPath, toPath);
+}
+
+/**
+ * The directories on the way to `path` that do not exist yet, OUTERMOST FIRST. Captured before a
+ * lifecycle add writes, so an undo removes exactly the directories the add created and no others.
+ */
+export async function missingAncestorDirs(path: string): Promise<string[]> {
+  const targetPath = await resolveTarget(path);
+  const missing: string[] = [];
+  let cursor = dirname(targetPath);
+  const { root } = parse(cursor);
+  while (cursor !== root) {
+    try {
+      const info = await lstat(cursor);
+      if (info.isDirectory()) break;
+      break;
+    } catch (error: unknown) {
+      if (errCode(error) !== "ENOENT") throw error;
+      missing.unshift(cursor);
+      cursor = dirname(cursor);
+    }
+  }
+  return missing;
+}
+
+/**
+ * Best-effort removal of directories a lifecycle add created, deepest first. Returns the removed
+ * paths. A directory that is no longer empty (an outside writer put something there) is kept.
+ */
+export async function pruneEmptyDirs(dirs: readonly string[]): Promise<string[]> {
+  const removed: string[] = [];
+  for (const dir of [...dirs].sort((a, b) => b.length - a.length)) {
+    try {
+      await rmdir(dir);
+      removed.push(dir);
+    } catch (error: unknown) {
+      const code = errCode(error);
+      if (
+        code === "ENOENT" ||
+        code === "ENOTEMPTY" ||
+        code === "EEXIST" ||
+        code === "EPERM" ||
+        code === "EISDIR" ||
+        code === "ENOTDIR"
+      ) {
+        continue;
+      }
+      reportDiagnostic("fs-lifecycle", "failed to prune a lifecycle-created directory:", error);
+    }
+  }
+  return removed;
+}

package/src/hash-store.ts

@@ -156,7 +156,16 @@ function openDb(storePath: string, budget?: BusyBudget): OpenedDb {
 const MIGRATION_COLUMNS = {
   cut_intent: { direction: "TEXT" },
   file_snapshots: { stat_key: "TEXT" },
-  file_undo: { snapshot_hash: "TEXT", transaction_id: "TEXT", raw_pre: "TEXT" },
+  file_undo: {
+    snapshot_hash: "TEXT",
+    transaction_id: "TEXT",
+    raw_pre: "TEXT",
+    lifecycle: "TEXT",
+    from_path: "TEXT",
+    to_path: "TEXT",
+    raw_post: "TEXT",
+    created_dirs: "TEXT",
+  },
   served: { retired: "TEXT", canons: "TEXT", snapshotId: "TEXT" },
   undo: { result_content: "TEXT NOT NULL DEFAULT ''" },
 } as const;
@@ -625,6 +634,14 @@ export function ensureFileUndoSchema(db: DatabaseSync): void {
   addColumnIfMissing(db, "file_undo", "snapshot_hash");
   addColumnIfMissing(db, "file_undo", "transaction_id");
   addColumnIfMissing(db, "file_undo", "raw_pre");
+  // WHY: apply_patch lifecycle rows are still edit-shaped rows: one file_undo row per member,
+  // WHY: one shared transaction id. These columns only widen what a row can describe — an
+  // WHY: existing row (all NULL) stays an ordinary edit, so the addition is back-compatible.
+  addColumnIfMissing(db, "file_undo", "lifecycle");
+  addColumnIfMissing(db, "file_undo", "from_path");
+  addColumnIfMissing(db, "file_undo", "to_path");
+  addColumnIfMissing(db, "file_undo", "raw_post");
+  addColumnIfMissing(db, "file_undo", "created_dirs");
   // WHY: versions the persisted anchor set — existing rows keep 0 (never current),
   // WHY: so a pre-bump store is refused, not migrated, on first open after upgrade.
   // WHY: `canon_version` (pre-rename builds) is renamed in place, preserving stamped values.

package/src/hashline/lease-resolve.ts

@@ -85,6 +85,14 @@ function resolvedAt(edit: HEdit, fileHashes: string[], fromLine: number, toLine:
     ...(edit.placement !== undefined ? { placement: edit.placement } : {}),
   };
 }
+/**
+ * SAFETY: one copy of each refused anchor, in submission order. A single-line edit names the same
+ * anchor in both bounds; collapsing the pair keeps the refusal's count and quoted list honest (one
+ * anchor, not two).
+ */
+function distinctAnchors(anchors: readonly string[]): string[] {
+  return [...new Set(anchors)];
+}
 
 /**
  * Refuses anchors the lease seam cannot place: the session holds no lease for them in this file.
@@ -103,14 +111,12 @@ function throwUnknownOrForeign(args: {
 }): never {
   const { edit, snapshot, source } = args;
   const path = snapshot.filePath ?? "this file";
-  const refused = [
-    ...new Set(
-      [
-        args.refusedFrom ? edit.hash_bounds[0].hash : undefined,
-        args.refusedTo ? edit.hash_bounds[1].hash : undefined,
-      ].filter((hash): hash is string => hash !== undefined),
-    ),
-  ];
+  const refused = distinctAnchors(
+    [
+      args.refusedFrom ? edit.hash_bounds[0].hash : undefined,
+      args.refusedTo ? edit.hash_bounds[1].hash : undefined,
+    ].filter((hash): hash is string => hash !== undefined),
+  );
   const homes = [
     ...new Set(refused.flatMap((anchor) => source.anchorHomes?.(anchor) ?? [])),
   ].sort();

package/src/hashline/resolve.ts

@@ -1,4 +1,4 @@
-import { abortIf, rejectUnknownFields, clipLine } from "../utils.js";
+import { abortIf, rejectUnknownFields } from "../utils.js";
 import { DomainError, formatWarning } from "../domain-errors.js";
 import { HASH_CLASS, HASH_LEN } from "./hash-identity.js";
 import { parseHashRef, parseText, type Anchor } from "./parse.js";
@@ -239,51 +239,54 @@ function _fmtMismatch(mismatches: HMismatch[], snapshot: FileSnapshotContext): s
   return fmtMismatchWithServes(mismatches, snapshot).message;
 }
 
+/**
+ * SAFETY: one copy per distinct anchor hash, in submission order. A single-line edit names its one
+ * anchor in both bounds, so the size of this array — never the raw mismatch count — owns the label
+ * and the count in the rendered refusal.
+ */
+function distinctByHash<T extends { ref: { hash: string } }>(items: readonly T[]): T[] {
+  return [...new Map(items.map((item) => [item.ref.hash, item])).values()];
+}
+
+/**
+ * SAFETY: the summary names which anchors failed and how many distinct anchors they are. Row
+ * evidence is collected through `pushRow` for the rejection's single `servedBlock`; echoing the rows
+ * here as a second context block is the duplicate this function no longer produces.
+ */
 function formatNotFound(
   notFound: HMismatch[],
   fileLines: string[],
-  fileHashes: string[],
   filePath: string | undefined,
   pushRow: (ln: number) => void,
   out: string[],
 ): void {
   if (notFound.length === 0) return;
-  const distinct = [...new Map(notFound.map((m) => [m.ref.hash, m])).values()];
+  const distinct = distinctByHash(notFound);
   const refList = distinct.map((m) => `"${m.ref.hash}"`).join(", ");
   // WHY: the body carries no code tag — the registry owns the `[MODEL] [E_*]`
   // WHY: header when the caller wraps this in a `DomainError`.
   out.push(
-    `${distinct.length} stale anchor${distinct.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. Re-read the full file and copy the fresh ${HASH_LEN}-char anchors (the ${HASH_LEN} chars before │, e.g. "wUpX").`,
+    `${distinct.length} stale anchor${distinct.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}.`,
   );
   for (const m of distinct) {
     const ctx = m.context;
     if (!ctx) continue;
     const from = Math.max(1, ctx.line - 1);
     const to = Math.min(fileLines.length, ctx.line + 1);
-    const rows: string[] = [];
-    for (let ln = from; ln <= to; ln++) {
-      rows.push(`    ${ln}: ${fileHashes[ln - 1]}│${clipLine(fileLines[ln - 1] ?? "")}`);
-      pushRow(ln);
-    }
-    out.push("");
-    out.push(
-      `  Current context around resolved anchor "${ctx.hash}" (line ${ctx.line}):\n${rows.join("\n")}`,
-    );
+    for (let ln = from; ln <= to; ln++) pushRow(ln);
   }
 }
 function formatAmbiguous(
   ambiguous: HMismatch[],
-  fileLines: string[],
-  fileHashes: string[],
   filePath: string | undefined,
   pushRow: (ln: number) => void,
   out: string[],
 ): void {
   if (ambiguous.length === 0) return;
   if (out.length > 0) out.push("");
-  const distinctAmbiguous = [...new Map(ambiguous.map((m) => [m.ref.hash, m])).values()];
+  const distinctAmbiguous = distinctByHash(ambiguous);
   out.push(
-    `${distinctAmbiguous.length} ambiguous anchor${distinctAmbiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Re-read the full file and copy the fresh ${HASH_LEN}-char anchors (the ${HASH_LEN} chars before │, e.g. "wUpX").`,
+    `${distinctAmbiguous.length} ambiguous anchor${distinctAmbiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}.`,
   );
   for (const m of distinctAmbiguous) {
     const sample = (m.candidates ?? []).slice(0, 5);
@@ -291,14 +294,8 @@ function formatAmbiguous(
       (m.candidates?.length ?? 0) > sample.length
         ? `, ... (+${(m.candidates?.length ?? 0) - sample.length} more)`
         : "";
-    const lines = sample
-      .map((line) => {
-        const content = clipLine(fileLines[line - 1] ?? "");
-        pushRow(line);
-        return `    ${line}: ${fileHashes[line - 1]}│${content}`;
-      })
-      .join("\n");
-    out.push(`  Hash "${m.ref.hash}" matches lines ${sample.join(", ")}${more}.\n${lines}`);
+    for (const line of sample) pushRow(line);
+    out.push(`  Hash "${m.ref.hash}" matches lines ${sample.join(", ")}${more}.`);
   }
 }
 function buildHashIndex(fileHashes: string[]): Map<string, number[]> {
@@ -311,6 +308,12 @@ function buildHashIndex(fileHashes: string[]): Map<string, number[]> {
   }
   return hashIndex;
 }
+/**
+ * SAFETY: the rejection summary plus the rows to serve. The message is facts-only: it names the
+ * distinct failing anchors and, for ambiguous ones, the candidate line numbers. Row content travels
+ * only in `servedRows` so a caller renders one evidence block; a message that also echoes the rows
+ * would make the retry read the same lines twice.
+ */
 export function fmtMismatchWithServes(
   mismatches: HMismatch[],
   snapshot: FileSnapshotContext,
@@ -330,8 +333,8 @@ export function fmtMismatchWithServes(
   };
   const notFound = mismatches.filter((m) => m.kind === "not_found");
   const ambiguous = mismatches.filter((m) => m.kind === "ambiguous");
-  formatNotFound(notFound, fileLines, fileHashes, filePath, pushRow, out);
-  formatAmbiguous(ambiguous, fileLines, fileHashes, filePath, pushRow, out);
+  formatNotFound(notFound, fileLines, filePath, pushRow, out);
+  formatAmbiguous(ambiguous, filePath, pushRow, out);
 
   return { message: out.join("\n"), servedRows };
 }

package/src/host-utils.ts

@@ -0,0 +1,224 @@
+/**
+ * Host-neutral utilities the hashline core needs from the historical pi runtime.
+ *
+ * WHY: the dsh plugin ships without the pi agent package. Three core modules used
+ * to import small utility functions from `@earendil-works/pi-coding-agent`:
+ * `src/file-content/preview.ts` and `src/file-content/served-header.ts` use
+ * `formatSize` / `truncateHead` / `DEFAULT_MAX_LINES` / `DEFAULT_MAX_BYTES`
+ * to render read pages, and `src/mutation-queue.ts` uses
+ * `withFileMutationQueue` to serialize same-file mutations for the cut
+ * transaction and its correlated undo. This module owns that surface as plain
+ * host-neutral code; `dsh/host-compat.ts` re-exports it for the dsh bundle.
+ *
+ * @module dsh-hashline-edit/host-utils
+ */
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+
+/** Retained line budget, matching pi's `DEFAULT_MAX_LINES`. */
+export const DEFAULT_MAX_LINES = 2000;
+
+/** Retained byte budget, matching pi's `DEFAULT_MAX_BYTES` (50KB). */
+export const DEFAULT_MAX_BYTES = 50 * 1024;
+
+/** The truncation report the core's read page renders. */
+export interface TruncationResult {
+  /** The truncated content. */
+  content: string;
+  /** Whether truncation occurred. */
+  truncated: boolean;
+  /** Which limit was hit: `"lines"`, `"bytes"`, or `null` when nothing was cut. */
+  truncatedBy: "lines" | "bytes" | null;
+  /** Total number of lines in the original content. */
+  totalLines: number;
+  /** Total number of bytes in the original content. */
+  totalBytes: number;
+  /** Number of complete lines in the truncated output. */
+  outputLines: number;
+  /** Number of bytes in the truncated output. */
+  outputBytes: number;
+  /** Whether the last line was partially truncated (tail truncation only). */
+  lastLinePartial: boolean;
+  /** Whether the first line exceeded the byte limit (head truncation only). */
+  firstLineExceedsLimit: boolean;
+  /** The line limit that was applied. */
+  maxLines: number;
+  /** The byte limit that was applied. */
+  maxBytes: number;
+}
+
+/** The two independent limits a truncation call applies. */
+export interface TruncationOptions {
+  /** Maximum number of lines; defaults to {@link DEFAULT_MAX_LINES}. */
+  maxLines?: number;
+  /** Maximum number of bytes; defaults to {@link DEFAULT_MAX_BYTES}. */
+  maxBytes?: number;
+}
+
+/** Split content into lines for counting, dropping the empty tail of a trailing newline. */
+function splitLinesForCounting(content: string): string[] {
+  if (content.length === 0) return [];
+  const lines = content.split("\n");
+  if (content.endsWith("\n")) lines.pop();
+  return lines;
+}
+
+/**
+ * Format bytes as a human-readable size (`512B`, `1.5KB`, `2.0MB`).
+ * @param bytes - the byte count to render.
+ * @returns the pi-compatible size label.
+ */
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/**
+ * Truncate content from the head (keep the first N lines / bytes).
+ *
+ * WHY: the read page's oversize and truncation warnings must agree with the pi
+ * implementation the rest of the contract was written against, so this is a
+ * faithful port including its two edge rules: complete lines only, and an
+ * over-long first line yields empty content with `firstLineExceedsLimit`.
+ * @param content - the text to truncate.
+ * @param options - the line and byte limits.
+ * @returns the truncation report.
+ */
+export function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {
+  const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  const totalBytes = Buffer.byteLength(content, "utf-8");
+  const lines = splitLinesForCounting(content);
+  const totalLines = lines.length;
+
+  if (totalLines <= maxLines && totalBytes <= maxBytes) {
+    return {
+      content,
+      truncated: false,
+      truncatedBy: null,
+      totalLines,
+      totalBytes,
+      outputLines: totalLines,
+      outputBytes: totalBytes,
+      lastLinePartial: false,
+      firstLineExceedsLimit: false,
+      maxLines,
+      maxBytes,
+    };
+  }
+
+  const firstLineBytes = Buffer.byteLength(lines[0] ?? "", "utf-8");
+  if (firstLineBytes > maxBytes) {
+    return {
+      content: "",
+      truncated: true,
+      truncatedBy: "bytes",
+      totalLines,
+      totalBytes,
+      outputLines: 0,
+      outputBytes: 0,
+      lastLinePartial: false,
+      firstLineExceedsLimit: true,
+      maxLines,
+      maxBytes,
+    };
+  }
+
+  const outputLinesArr: string[] = [];
+  let outputBytesCount = 0;
+  let truncatedBy: "lines" | "bytes" = "lines";
+  for (let index = 0; index < lines.length && index < maxLines; index += 1) {
+    const line = lines[index] ?? "";
+    const lineBytes = Buffer.byteLength(line, "utf-8") + (index > 0 ? 1 : 0);
+    if (outputBytesCount + lineBytes > maxBytes) {
+      truncatedBy = "bytes";
+      break;
+    }
+    outputLinesArr.push(line);
+    outputBytesCount += lineBytes;
+  }
+  if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+    truncatedBy = "lines";
+  }
+
+  const outputContent = outputLinesArr.join("\n");
+  return {
+    content: outputContent,
+    truncated: true,
+    truncatedBy,
+    totalLines,
+    totalBytes,
+    outputLines: outputLinesArr.length,
+    outputBytes: Buffer.byteLength(outputContent, "utf-8"),
+    lastLinePartial: false,
+    firstLineExceedsLimit: false,
+    maxLines,
+    maxBytes,
+  };
+}
+
+/** The per-path queue tails; an entry exists only while a mutation holds or awaits it. */
+const fileMutationQueues = new Map<string, Promise<void>>();
+
+/** WHY: queue registration itself must be serialized so two callers cannot adopt the same tail. */
+let registrationQueue: Promise<void> = Promise.resolve();
+
+/** Whether a realpath failure means "no such path" (the queue then keys by the resolved path). */
+function isMissingPathError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}
+
+/** Key a mutation by the canonical path, falling back to the resolved path for missing files. */
+async function getMutationQueueKey(filePath: string): Promise<string> {
+  const resolvedPath = resolve(filePath);
+  try {
+    return await realpath(resolvedPath);
+  } catch (error) {
+    if (isMissingPathError(error)) return resolvedPath;
+    throw error;
+  }
+}
+
+/**
+ * Serialize file mutation operations that target the same file; different files still run
+ * in parallel. A faithful port of pi's queue so the core's cut transaction keeps its
+ * lock ordering guarantees under the dsh host.
+ * @param filePath - the file the mutation targets.
+ * @param run - the critical section to run once the path is free.
+ * @returns the critical section's result.
+ */
+export async function withFileMutationQueue<T>(
+  filePath: string,
+  run: () => Promise<T>,
+): Promise<T> {
+  const registration = registrationQueue.then(async () => {
+    const key = await getMutationQueueKey(filePath);
+    const currentQueue = fileMutationQueues.get(key) ?? Promise.resolve();
+    let releaseNext: () => void = () => {};
+    const nextQueue = new Promise<void>((resolveQueue) => {
+      releaseNext = resolveQueue;
+    });
+    const chainedQueue = currentQueue.then(() => nextQueue);
+    fileMutationQueues.set(key, chainedQueue);
+    return { key, currentQueue, chainedQueue, releaseNext };
+  });
+  registrationQueue = registration.then(
+    () => undefined,
+    () => undefined,
+  );
+
+  const { key, currentQueue, chainedQueue, releaseNext } = await registration;
+  await currentQueue;
+  try {
+    return await run();
+  } finally {
+    releaseNext();
+    if (fileMutationQueues.get(key) === chainedQueue) fileMutationQueues.delete(key);
+  }
+}

package/src/mutation-engine/batch-span-gate.ts

@@ -101,6 +101,12 @@ export interface BaselineSpanContext {
   sessionKey: string;
   absolutePath: string;
   isPreview: boolean;
+  /**
+   * WHY: the CALLER's own item numbers, parallel to `edits` — a per-file plan keeps its items'
+   * WHY: global positions, so an aggregated refusal names the item the model sent instead of this
+   * WHY: plan's local index. Absent means `edits` IS the whole call, so local index = caller number.
+   */
+  itemNumbers?: readonly number[];
   path: string;
   originalHashes: string[];
   originalNormalized: string;
@@ -224,14 +230,21 @@ export async function assertBatchSpansDisjoint(
       failures.push({ error, index });
     }
   }
+  const numberOf = (local: number): number => ctx.itemNumbers?.[local] ?? local;
   // WHY: anchor failures mask overlap reporting — without valid anchors there are no coordinates
   // WHY: to compare, so validation rejections throw before the overlap scan below.
   if (failures.length === 1) {
     const only = failures[0]!;
-    throw batchAbortFor({ error: only.error, index: only.index, path: ctx.path });
+    throw batchAbortFor({ error: only.error, index: numberOf(only.index), path: ctx.path });
   }
   if (failures.length > 1) {
-    throw batchAbortForMany({ failures, path: ctx.path });
+    throw batchAbortForMany({
+      failures: failures.map((failure) => ({
+        error: failure.error,
+        index: numberOf(failure.index),
+      })),
+      path: ctx.path,
+    });
   }
   for (let i = 0; i < spans.length; i++) {
     for (let j = i + 1; j < spans.length; j++) {
@@ -250,8 +263,8 @@ export async function assertBatchSpansDisjoint(
         const originalLines = splitLines(ctx.originalNormalized);
         const rows = serveRowsForEdit(edits[b.index]!, ctx.originalHashes);
         throw new DomainError("E_BATCH_ABORT", {
-          earlierIndex: a.index,
-          laterIndex: b.index,
+          earlierIndex: numberOf(a.index),
+          laterIndex: numberOf(b.index),
           earlierStart: a.startLine,
           earlierEnd: a.endLine,
           laterStart: b.startLine,