@arnilo/prism-tools 0.0.0-stage → 0.13.0

package/coding/src/agent/edit.ts

@@ -0,0 +1,322 @@
+/**
+ * Edit tool: precise text replacement in an existing file via exact matching.
+ *
+ * Behavioral port of pi's core/tools/edit for @arnilo/prism-tools/coding, adapted to Prism's
+ * `ToolDefinition` contract. Faithfully ports the access → read → stripBom → line-ending-normalize →
+ * `applyEditsToNormalizedContent` (exact only, with duplicate/overlap/empty/no-change guards) →
+ * write flow, serialized per-path via `withFileMutationQueue`. Also ports `prepareEditArguments`
+ * (tolerates models that send `edits` as a JSON string or as legacy top-level `oldText`/`newText`).
+ *
+ * Drops pi's TUI (`renderCall`/`renderResult`, live preview cache, theme/syntax-highlight).
+ *
+ * Deviations from pi (documented):
+ *  - Abort + every failure (missing/unreadable file, no-match, duplicate, overlap, empty oldText,
+ *    no-change) return a Prism `error` result (pi throws/rejects). On no-match the file is untouched
+ *    because `applyEditsToNormalizedContent` throws before `writeFile`.
+ *  - pi's per-tool `details: { diff, patch, firstChangedLine }` (TUI-facing) is surfaced as
+ *    `ToolResult.metadata` (host-readable, keeps model context small — the model only sees the short
+ *    `Edited <path>: N block(s).` confirmation plus the changed lines).
+ *  - The post-`writeFile` abort check is dropped (consistent with the write tool): if the write
+ *    completed, the edit is real and is reported as success rather than a misleading "aborted".
+ */
+import { Buffer } from "node:buffer";
+import { constants } from "node:fs";
+import { access as fsAccess, stat as fsStat } from "node:fs/promises";
+import type { JsonObject, ToolDefinition, ToolExecutionContext, ToolResult } from "@arnilo/prism";
+import { atomicWriteUtf8File } from "./atomic-write.js";
+import { readFileBounded } from "./bounded-file.js";
+import {
+  applyEditsToNormalizedContent,
+  detectLineEnding,
+  generateChangedLinePreview,
+  generateDiffString,
+  generateUnifiedPatch,
+  normalizeToLF,
+  restoreLineEndings,
+  stripBom,
+} from "./edit-diff.js";
+import { CODING_LOCAL_EFFECT } from "./effects.js";
+import type { ExecutionPolicy } from "./execution-policy.js";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import type { CodingLifecycleEvent } from "./lifecycle-events.js";
+import {
+  DEFAULT_MAX_EDIT_FILE_BYTES,
+  DEFAULT_MAX_EDIT_INPUT_BYTES,
+  DEFAULT_MAX_EDITS,
+  HARD_MAX_EDIT_FILE_BYTES,
+  HARD_MAX_EDIT_INPUT_BYTES,
+  HARD_MAX_EDITS,
+  validateCodingLimit,
+} from "./limits.js";
+import { resolveToCwd } from "./path-utils.js";
+import { type ReadBeforeWriteOptions, refuseReadBeforeWrite } from "./read-path-set.js";
+
+export interface Edit {
+  oldText: string;
+  newText: string;
+}
+
+/** Display/result details mirrored from pi's `EditToolDetails`, surfaced via `ToolResult.metadata`. */
+export interface EditToolDetails {
+  /** Absolute path written (F7 projection + host navigation). */
+  path: string;
+  /** Display-oriented diff of the changes made. */
+  diff: string;
+  /** Standard unified patch of the changes made. */
+  patch: string;
+  /** Line number of the first change in the new file (for editor navigation). */
+  firstChangedLine?: number;
+}
+
+/**
+ * Pluggable operations for the edit tool. Override to delegate file editing to remote systems
+ * (e.g. SSH) while keeping the tool's matching + per-path serialization behavior.
+ */
+export interface EditOperations {
+  /** Read bounded file contents as a Buffer. */
+  readFile: (absolutePath: string, options: { maxBytes: number; signal?: AbortSignal }) => Promise<Buffer>;
+  /** Write content to a file. */
+  writeFile: (absolutePath: string, content: string, options?: { signal?: AbortSignal }) => Promise<void>;
+  /** Check the file is readable and writable (throw if not). */
+  access: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<void>;
+  /** Return target size before the bounded read. */
+  statFile: (absolutePath: string, options?: { signal?: AbortSignal }) => Promise<{ size: number }>;
+}
+
+export interface EditToolOptions extends ReadBeforeWriteOptions {
+  /** Structured pre-execution policy checked before filesystem writes. */
+  executionPolicy?: ExecutionPolicy;
+  /** Custom operations backend (default: local filesystem). */
+  operations?: EditOperations;
+  /** Maximum target file bytes read for matching (default 8 MiB). */
+  maxFileBytes?: number;
+  /** Maximum aggregate UTF-8 bytes across old/new edit text (default 2 MiB). */
+  maxInputBytes?: number;
+  /** Maximum replacements per call (default 100). */
+  maxEdits?: number;
+  /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+  onEvent?: (event: CodingLifecycleEvent) => void;
+}
+
+const defaultEditOperations: EditOperations = {
+  readFile: (path, options) => readFileBounded(path, options.maxBytes, options.signal),
+  writeFile: (path, content, options) => atomicWriteUtf8File(path, content, { signal: options?.signal }),
+  access: (path) => fsAccess(path, constants.R_OK | constants.W_OK),
+  statFile: async (path) => ({ size: (await fsStat(path)).size }),
+};
+
+function errorResult(toolCallId: string, message: string): ToolResult {
+  return {
+    toolCallId,
+    name: "edit",
+    content: [{ type: "text", text: message }],
+    error: { message },
+  };
+}
+
+/** Port of pi's `prepareEditArguments`: tolerate model quirks (edits as JSON string; legacy fields). */
+function prepareEditArguments(input: JsonObject): { path: string; edits: unknown } {
+  let edits: unknown = input.edits;
+  // Some models send edits as a JSON string instead of an array.
+  if (typeof edits === "string") {
+    try {
+      const parsed = JSON.parse(edits) as unknown;
+      if (Array.isArray(parsed)) edits = parsed;
+    } catch {
+      /* leave as-is; validation will reject */
+    }
+  }
+  const path = typeof input.path === "string" ? input.path : "";
+  // Legacy: top-level oldText/newText instead of edits[].
+  if (typeof input.oldText === "string" && typeof input.newText === "string") {
+    const arr = Array.isArray(edits) ? [...edits] : [];
+    arr.push({ oldText: input.oldText, newText: input.newText });
+    edits = arr;
+  }
+  return { path, edits };
+}
+
+function validateEdits(edits: unknown, maxEdits: number, maxInputBytes: number): Edit[] | string {
+  if (!Array.isArray(edits) || edits.length === 0) {
+    return "edits must contain at least one replacement.";
+  }
+  if (edits.length > maxEdits) return `edits contains ${edits.length} replacements, exceeds ${maxEdits} limit.`;
+  const out: Edit[] = [];
+  let inputBytes = 0;
+  for (let i = 0; i < edits.length; i++) {
+    const e = edits[i] as { oldText?: unknown; newText?: unknown };
+    if (typeof e?.oldText !== "string" || typeof e?.newText !== "string") {
+      return `edits[${i}] must have string oldText and newText.`;
+    }
+    inputBytes += Buffer.byteLength(e.oldText, "utf-8") + Buffer.byteLength(e.newText, "utf-8");
+    if (inputBytes > maxInputBytes) {
+      return `edit input is ${inputBytes} bytes, exceeds ${maxInputBytes} byte limit.`;
+    }
+    out.push({ oldText: e.oldText, newText: e.newText });
+  }
+  return out;
+}
+
+export function createEditTool(cwd: string, options?: EditToolOptions): ToolDefinition {
+  const ops = options?.operations ?? defaultEditOperations;
+  const maxFileBytes = validateCodingLimit("maxFileBytes", options?.maxFileBytes ?? DEFAULT_MAX_EDIT_FILE_BYTES, HARD_MAX_EDIT_FILE_BYTES);
+  const maxInputBytes = validateCodingLimit(
+    "maxInputBytes",
+    options?.maxInputBytes ?? DEFAULT_MAX_EDIT_INPUT_BYTES,
+    HARD_MAX_EDIT_INPUT_BYTES,
+  );
+  const maxEdits = validateCodingLimit("maxEdits", options?.maxEdits ?? DEFAULT_MAX_EDITS, HARD_MAX_EDITS);
+  const guard = options?.requireReadBeforeWrite === true;
+
+  return {
+    name: "edit",
+    kind: "edit",
+    effect: CODING_LOCAL_EFFECT,
+    effects: ["write"],
+    description: `Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file exactly, including whitespace and newlines; copy it from \`read\` output without the line-number prefix. A miss fails with a Nearby hint and leaves the file unchanged. The result shows the changed lines with their new line numbers, so you can check the edit without another \`read\`. Duplicate or overlapping matches fail closed. If two changes affect the same block or nearby lines, merge them into one edit. Do not include large unchanged regions just to connect distant changes.${guard ? " Read the path first or pass force=true to override the host's read-before-write guard." : ""}`,
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to the file to edit (relative or absolute)" },
+        ...(guard
+          ? {
+              force: {
+                type: "boolean",
+                description: "Bypass the read-before-write guard for this call.",
+              },
+            }
+          : {}),
+        edits: {
+          type: "array",
+          description:
+            "One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.",
+          items: {
+            type: "object",
+            properties: {
+              oldText: {
+                type: "string",
+                description:
+                  "Exact text for one targeted replacement. It must be unique in the original file and must not overlap with any other edits[].oldText in the same call.",
+              },
+              newText: { type: "string", description: "Replacement text for this targeted edit." },
+            },
+            required: ["oldText", "newText"],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ["path", "edits"],
+      additionalProperties: false,
+    } as JsonObject,
+    async execute(args, context: ToolExecutionContext): Promise<ToolResult> {
+      const toolCallId = context.toolCallId;
+      if (typeof args.edits === "string" && Buffer.byteLength(args.edits, "utf-8") > maxInputBytes) {
+        return errorResult(toolCallId, `edit input exceeds ${maxInputBytes} byte limit.`);
+      }
+
+      const prepared = prepareEditArguments(args);
+      const force = args.force === true;
+      if (prepared.path.length === 0) {
+        return errorResult(toolCallId, "path is required and must be a non-empty string.");
+      }
+      const editsOrError = validateEdits(prepared.edits, maxEdits, maxInputBytes);
+      if (typeof editsOrError === "string") {
+        return errorResult(toolCallId, editsOrError);
+      }
+      const edits = editsOrError;
+
+      try {
+        const absolutePath = resolveToCwd(prepared.path, cwd);
+
+        const policyCheck = await enforceExecutionPolicy(
+          options?.executionPolicy,
+          {
+            kind: "edit",
+            operation: "edit",
+            paths: [absolutePath],
+            risk: "medium",
+            metadata: { editCount: edits.length, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+          },
+          toolCallId,
+          "edit",
+          (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }),
+        );
+        if (!policyCheck.allowed) return policyCheck.result;
+        const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+
+        const rbwRefusal = refuseReadBeforeWrite("edit", prepared.path, allowedPath, options, force);
+        if (rbwRefusal) return errorResult(toolCallId, rbwRefusal);
+
+        return await withFileMutationQueue(allowedPath, async () => {
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+          // Check the file is readable + writable.
+          try {
+            await ops.access(allowedPath, { signal: context.signal });
+          } catch (error) {
+            if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+            const err = error as NodeJS.ErrnoException;
+            const errorMessage = error instanceof Error && "code" in error ? `Error code: ${err.code}` : String(error);
+            return errorResult(toolCallId, `Could not edit file: ${prepared.path}. ${errorMessage}.`);
+          }
+
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+          const { size } = await ops.statFile(allowedPath, { signal: context.signal });
+          if (size > maxFileBytes) {
+            return errorResult(toolCallId, `Edit target is ${size} bytes, exceeds ${maxFileBytes} byte limit.`);
+          }
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+          const buffer = await ops.readFile(allowedPath, { maxBytes: maxFileBytes, signal: context.signal });
+          if (buffer.length > maxFileBytes) {
+            return errorResult(toolCallId, `Edit target is ${buffer.length} bytes, exceeds ${maxFileBytes} byte limit.`);
+          }
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+          const rawContent = buffer.toString("utf-8");
+          // The model will not include an invisible BOM in oldText.
+          const { bom, text: content } = stripBom(rawContent);
+          const originalEnding = detectLineEnding(content);
+          const normalizedContent = normalizeToLF(content);
+
+          // Apply exact matching. Throws on no-match / duplicate / overlap / empty / no-change.
+          let baseContent: string;
+          let newContent: string;
+          try {
+            ({ baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, prepared.path));
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return errorResult(toolCallId, message);
+          }
+
+          if (context.signal?.aborted) return errorResult(toolCallId, "Operation aborted");
+
+          const finalContent = bom + restoreLineEndings(newContent, originalEnding);
+          await ops.writeFile(allowedPath, finalContent, { signal: context.signal });
+          options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "edit", toolCallId });
+
+          const diffResult = generateDiffString(baseContent, newContent);
+          const patch = generateUnifiedPatch(prepared.path, baseContent, newContent);
+          const preview = generateChangedLinePreview(baseContent, newContent);
+          const moreNote = preview.more > 0 ? `\n(… ${preview.more} more changed lines)` : "";
+          const confirmation = `Edited ${prepared.path}: ${edits.length} block(s).${preview.text ? `\n${preview.text}` : ""}${moreNote}`;
+          return {
+            toolCallId,
+            name: "edit",
+            content: [{ type: "text", text: confirmation }],
+            metadata: {
+              path: allowedPath,
+              diff: diffResult.diff,
+              patch,
+              firstChangedLine: diffResult.firstChangedLine,
+            } satisfies EditToolDetails,
+          };
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return errorResult(toolCallId, message);
+      }
+    },
+  };
+}

package/coding/src/agent/effects.ts

@@ -0,0 +1,102 @@
+import { Buffer } from "node:buffer";
+import { lstat, open } from "node:fs/promises";
+import type { JsonObject, ToolEffectDeclaration, ToolEffectRecord, ToolResult } from "@arnilo/prism";
+import { HARD_MAX_WRITE_BYTES } from "./limits.js";
+import { resolveContainedMutationPath } from "./mutation-path.js";
+
+export const CODING_OBSERVATION_EFFECT = { kind: "none", idempotency: "none" } as const satisfies ToolEffectDeclaration;
+export const CODING_LOCAL_EFFECT = { kind: "local_mutation", idempotency: "optional" } as const satisfies ToolEffectDeclaration;
+export const CODING_UNSUPPORTED_EFFECT = { kind: "external_mutation", idempotency: "unsupported" } as const satisfies ToolEffectDeclaration;
+
+export interface CodingEffectReconciliationInput {
+  readonly cwd: string;
+  readonly record: Pick<ToolEffectRecord, "toolCallId" | "toolName">;
+  readonly args: JsonObject;
+  readonly signal?: AbortSignal;
+}
+
+export type CodingEffectReconciliation = { readonly status: "completed"; readonly result: ToolResult } | { readonly status: "unknown" };
+
+/**
+ * Checks only exact local postconditions. Callers retain the pending call arguments,
+ * then pass a completed result to ToolEffectStore.resolveUnknown() when this returns one.
+ */
+export async function reconcileCodingToolEffect(input: CodingEffectReconciliationInput): Promise<CodingEffectReconciliation> {
+  input.signal?.throwIfAborted();
+  const completed = () => ({
+    status: "completed" as const,
+    result: {
+      toolCallId: input.record.toolCallId,
+      name: input.record.toolName,
+      content: [{ type: "text" as const, text: "Local tool postcondition verified." }],
+      value: { reconciled: true },
+    },
+  });
+
+  try {
+    if (input.record.toolName === "write") {
+      const path = stringArg(input.args, "path");
+      const content = stringArg(input.args, "content");
+      if (path === undefined || content === undefined || Buffer.byteLength(content, "utf8") > HARD_MAX_WRITE_BYTES)
+        return { status: "unknown" };
+      const target = await resolveContainedMutationPath(input.cwd, path);
+      const expected = Buffer.from(content, "utf8");
+      const handle = await open(target, "r");
+      try {
+        const st = await handle.stat();
+        if (!st.isFile() || st.size !== expected.length) return { status: "unknown" };
+        // Verify descriptor still refers to the same inode we resolved (detect swap/symlink).
+        try {
+          const cur = await lstat(target);
+          if (cur.isSymbolicLink() || cur.ino !== st.ino || cur.dev !== st.dev) return { status: "unknown" };
+        } catch {
+          return { status: "unknown" };
+        }
+        const data = await handle.readFile();
+        return data.equals(expected) ? completed() : { status: "unknown" };
+      } finally {
+        await handle.close();
+      }
+    }
+    if (input.record.toolName === "delete") {
+      const path = stringArg(input.args, "path");
+      if (path === undefined) return { status: "unknown" };
+      await resolveContainedMutationPath(input.cwd, path, { allowMissing: true });
+      return (await missing(input.cwd, path)) ? completed() : { status: "unknown" };
+    }
+    if (input.record.toolName === "move") {
+      const from = stringArg(input.args, "from");
+      const to = stringArg(input.args, "to");
+      if (from === undefined || to === undefined) return { status: "unknown" };
+      await Promise.all([
+        resolveContainedMutationPath(input.cwd, from, { allowMissing: true }),
+        resolveContainedMutationPath(input.cwd, to, { allowMissing: true }),
+      ]);
+      if (await missing(input.cwd, from)) {
+        try {
+          await resolveContainedMutationPath(input.cwd, to);
+          return completed();
+        } catch {
+          return { status: "unknown" };
+        }
+      }
+    }
+  } catch {
+    // Containment/read failure is not proof that an effect did not happen.
+  }
+  return { status: "unknown" };
+}
+
+function stringArg(args: JsonObject, name: string): string | undefined {
+  const value = args[name];
+  return typeof value === "string" ? value : undefined;
+}
+
+async function missing(cwd: string, path: string): Promise<boolean> {
+  try {
+    await resolveContainedMutationPath(cwd, path);
+    return false;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR";
+  }
+}

package/coding/src/agent/env.ts

@@ -0,0 +1,28 @@
+/**
+ * Child environment allow-list builder (P1 hardening).
+ *
+ * Fail-closed: nothing from `process.env` reaches a child process unless its
+ * name is explicitly listed in `inherit`. Callers that need host values
+ * (PATH, locale) enumerate them here; provider-approved extras come through
+ * `set`. Never pass `process.env` through to a spawn.
+ */
+
+/** Default vars safe to inherit for agent/process/LSP/PTY children. */
+export const DEFAULT_CHILD_ENV_INHERIT: readonly string[] = ["PATH", "LANG", "LC_ALL", "HOME", "TERM"];
+
+export interface ChildEnvOptions {
+  /** Names copied from `process.env` (absent values are skipped). */
+  readonly inherit?: readonly string[];
+  /** Explicit values added verbatim (overrides an inherited name). */
+  readonly set?: Readonly<Record<string, string>>;
+}
+
+export function buildChildEnv({ inherit = [], set }: ChildEnvOptions = {}): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const name of inherit) {
+    const value = process.env[name];
+    if (value !== undefined) env[name] = value;
+  }
+  if (set) Object.assign(env, set);
+  return env;
+}

package/coding/src/agent/execution-policy.ts

@@ -0,0 +1,89 @@
+/**
+ * Package-local execution policy (plan 155 Task 6).
+ *
+ * The kernel `ExecutionPolicy` export is retired: tool policy is a host `tool.call` hook, decided
+ * from declared `effects` and roots. These types stay package-internal because the coding tools
+ * accept an optional host-supplied policy for their sandbox and command-rule checks (plan 154
+ * Task 1 (g)); they are no longer part of `@arnilo/prism`.
+ */
+import type { ToolResult } from "@arnilo/prism";
+
+export type ExecutionRisk = "low" | "medium" | "high";
+
+export interface ExecutionAction {
+  readonly kind: "shell" | "read" | "write" | "edit" | string;
+  readonly operation: string;
+  readonly paths?: readonly string[];
+  readonly command?: string;
+  readonly risk?: ExecutionRisk;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface ExecutionDecision {
+  readonly allowed: boolean;
+  readonly reason?: string;
+  readonly modified?: Partial<ExecutionAction>;
+  /** When true, tool definitions should expose `exclusive: true` for pre-dispatch serialization. */
+  readonly exclusive?: boolean;
+}
+
+export interface ExecutionPolicy {
+  check(action: ExecutionAction): ExecutionDecision | Promise<ExecutionDecision>;
+}
+
+export class ExecutionDeniedError extends Error {
+  readonly code = "ERR_PRISM_EXECUTION_DENIED";
+  constructor(
+    readonly action: ExecutionAction,
+    readonly decision: ExecutionDecision,
+  ) {
+    super(decision.reason ?? `Execution denied for ${action.kind}:${action.operation}`);
+    this.name = "ExecutionDeniedError";
+  }
+}
+
+export async function checkExecution(policy: ExecutionPolicy | undefined, action: ExecutionAction): Promise<ExecutionDecision> {
+  return policy ? await policy.check(action) : { allowed: true };
+}
+
+export function applyExecutionDecision(action: ExecutionAction, decision: ExecutionDecision): ExecutionAction {
+  return decision.modified ? { ...action, ...decision.modified } : action;
+}
+
+export async function assertExecutionAllowed(policy: ExecutionPolicy | undefined, action: ExecutionAction): Promise<ExecutionAction> {
+  const decision = await checkExecution(policy, action);
+  if (!decision.allowed) throw new ExecutionDeniedError(action, decision);
+  return applyExecutionDecision(action, decision);
+}
+
+export async function enforceExecutionPolicy(
+  policy: ExecutionPolicy | undefined,
+  action: ExecutionAction,
+  toolCallId: string,
+  toolName: string,
+  /** Called once on policy denial so one site emits lifecycle permission_denied for every tool. */
+  onDenied?: (input: { readonly toolCallId: string; readonly toolName: string; readonly reason: string }) => void,
+): Promise<{ allowed: true; action: ExecutionAction } | { allowed: false; result: ToolResult }> {
+  if (!policy) return { allowed: true, action };
+  try {
+    const allowedAction = await assertExecutionAllowed(policy, action);
+    return { allowed: true, action: allowedAction };
+  } catch (error) {
+    const message =
+      error instanceof ExecutionDeniedError
+        ? (error.decision.reason ?? error.message)
+        : error instanceof Error
+          ? error.message
+          : String(error);
+    onDenied?.({ toolCallId, toolName, reason: message });
+    return {
+      allowed: false,
+      result: {
+        toolCallId,
+        name: toolName,
+        content: [{ type: "text", text: message }],
+        error: { message },
+      },
+    };
+  }
+}

package/coding/src/agent/file-mutation-queue.ts

@@ -0,0 +1,72 @@
+/**
+ * Serialize file mutation operations targeting the same file.
+ * Operations for different files still run in parallel.
+ *
+ * Behavioral port of pi's core/tools/file-mutation-queue for @arnilo/prism-tools/coding.
+ * stdlib only (node:fs/promises realpath, node:path resolve).
+ *
+ * ponytail: global process-wide Map mutex keyed by realpath. Ceiling: all
+ * mutation queues share one process Map; if a host runs many concurrent
+ * sessions in one process they all share the namespace (intended — same file
+ * must serialize regardless of session). Upgrade path: scope the Map per
+ * ToolRegistry if isolation between registries is ever needed.
+ */
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const fileMutationQueues = new Map<string, Promise<void>>();
+let registrationQueue: Promise<void> = Promise.resolve();
+
+function isMissingPathError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    ((error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR")
+  );
+}
+
+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;
+  }
+}
+
+/**
+ * Run `fn` exclusively for `filePath`: concurrent calls with the same path
+ * (or the same realpath) run one after another; calls for different paths run
+ * in parallel. Resolves/rejects with `fn`'s result and always releases the slot.
+ */
+export async function withFileMutationQueue<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+  const registration = registrationQueue.then(async () => {
+    const key = await getMutationQueueKey(filePath);
+    const currentQueue: Promise<void> = fileMutationQueues.get(key) ?? Promise.resolve();
+    let releaseNext!: () => void;
+    const nextQueue = new Promise<void>((resolveQueue) => {
+      releaseNext = resolveQueue;
+    });
+    const chainedQueue: Promise<void> = 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 fn();
+  } finally {
+    releaseNext();
+    if (fileMutationQueues.get(key) === chainedQueue) {
+      fileMutationQueues.delete(key);
+    }
+  }
+}