@hassangameryt/freeflow 0.7.3 → 0.9.0

package/pi-extension/dist/task-memory/tool.js

@@ -0,0 +1,233 @@
+import { autoApproveGroup } from "./config.js";
+import { renderTaskCall, renderTaskResult } from "./render.js";
+import { confirmWithUser } from "../ask-user/ask.js";
+export const TASK_MEMORY_TOOL = "task_memory";
+const DESCRIPTION =
+  "Task memory: the Working Records (Track Work) this session works on, and their projects. Read the task-memory skill before your first proposal; Track Work decides what records say. Reading needs no permission: projects lists every project; list lists this repository's records, or a project's tasks; view reads a record's resume view or one entry by task ID; search finds lines in the focused task, its tree, or its project. Attention: focus switches to an attached record; detach stops working on one. Proposals, each confirmed by the user in a dialog before anything happens: attach a record; create a task in this repository's project and attach it; child or fanout (a child with its own Git worktree) of the focused task for a parallel session; project_new or project_link for this repository; import a repository record into a project; confirm a held record; env to change a task's directories; remove a task with its children, or project_remove a whole project, which moves their records to the trash. Only the user empties the trash, with /freeflow trash empty: when asked to, tell the user to run it. A decline is the user's answer: do not retry it or work around it.";
+const ACTIONS = [
+  "projects",
+  "list",
+  "view",
+  "search",
+  "attach",
+  "focus",
+  "detach",
+  "create",
+  "child",
+  "fanout",
+  "project_new",
+  "project_link",
+  "import",
+  "confirm",
+  "env",
+  "remove",
+  "project_remove",
+];
+// Actions that change which records this session holds; the Runtime State follows them.
+const CHANGES_STATE = new Set(["attach", "focus", "detach", "create", "import", "confirm", "remove", "project_remove"]);
+/** Actions any profile may take: they only read. `env` reads too, unless it changes a directory. */
+const READS = new Set(["projects", "list", "view", "search"]);
+const reads = (params) =>
+  READS.has(params?.action) ||
+  (params?.action === "env" &&
+    !params?.primary?.trim?.() &&
+    !params?.add_dir?.trim?.() &&
+    !params?.remove_dir?.trim?.());
+/** Registered once, declared only while task memory is effective (see applyTaskMemoryTools). */
+export function registerTaskMemoryTool(pi, host) {
+  pi.registerTool({
+    name: TASK_MEMORY_TOOL,
+    label: "Task memory",
+    description: DESCRIPTION,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { type: "string", enum: ACTIONS },
+        record: {
+          type: "string",
+          description: "A task ID such as my-project/task-003, or a record.md path; remove takes a task ID",
+        },
+        project: { type: "string", description: "list: a project's name; import: the project to move the record into" },
+        name: { type: "string", description: "project_new, project_link, project_remove: the project's name" },
+        worktrees: { type: "string", description: "project_new, project_link: where children's worktrees go" },
+        title: { type: "string", description: "create, child, fanout: the new task's title" },
+        goal: {
+          type: "string",
+          description:
+            "create, child, fanout: its goal, one line; omitted, the title is the goal (the dialog shows it)",
+        },
+        entry: { type: "string", description: "view: one entry ID such as S-004" },
+        query: { type: "string", description: "search: text to find" },
+        scope: { type: "string", enum: ["task", "tree", "project"], description: "search: where to look" },
+        primary: { type: "string", description: "env: the task's new primary directory" },
+        add_dir: { type: "string", description: "env: a directory to add" },
+        remove_dir: { type: "string", description: "env: a directory to remove" },
+      },
+      required: ["action"],
+    },
+    // It asks the user, so scripts must not call it (Pi's guidance for such tools); called directly, its own
+    // transcript views apply, which a codemode script's nested call would bypass.
+    exposure: "model-only",
+    defaultActive: false,
+    executionMode: "sequential",
+    renderCall: (args, theme) => renderTaskCall(args, theme),
+    renderResult: (result, options, theme, context) => renderTaskResult(result, options, theme, context),
+    async execute(_id, params, _signal, _update, ctx) {
+      const refused = reads(params) ? undefined : host.refusal?.();
+      const group = reads(params) ? undefined : autoApproveGroup(params?.action);
+      const approved = group !== undefined && host.autoApproved?.(group) === true;
+      const result = refused ? { ok: false, text: refused } : await run(host, params, ctx, approved);
+      if (approved && result.ok)
+        result.text = `Auto-approved by the user's taskMemory.autoApprove setting (${group}); no dialog was shown.\n\n${result.text}`;
+      if (result.ok && CHANGES_STATE.has(params?.action)) host.changed(ctx);
+      let next;
+      if (result.ok && result.snapshot) {
+        const brief = await host.memory.brief(result.snapshot);
+        result.headline ??= `${params.action === "focus" ? "Focus on" : "Attached"} ${brief.label} · ${brief.state}`;
+        next = brief.next || undefined;
+      }
+      return {
+        content: [{ type: "text", text: result.text }],
+        details: {
+          action: params?.action,
+          ...(result.snapshot ? { snapshot: result.snapshot } : {}),
+          ...(result.headline ? { headline: result.headline } : {}),
+          ...(next ? { next } : {}),
+          ...(result.command ? { command: result.command } : {}),
+          ...(result.id ? { id: result.id } : {}),
+        },
+        ...(result.ok ? {} : { isError: true }),
+      };
+    },
+  });
+}
+/** Ask the user before an action taken on their authority; without a UI the proposal cannot be confirmed. */
+async function confirmProposal(ctx, title, message) {
+  if (!ctx.hasUI) return { ok: false, text: `${title} needs the user's confirmation, and no UI is available.` };
+  if (await confirmWithUser(ctx, title, message)) return undefined;
+  return { ok: false, headline: "Declined by the user", text: "The user declined. Do not retry or work around it." };
+}
+const show = (value) => (typeof value === "string" ? value.trim() : "");
+async function run(host, params, ctx, approved = false) {
+  const { memory } = host;
+  // An action the user's auto-approve setting covers runs without asking.
+  const ask = (context, title, message) =>
+    approved ? Promise.resolve(undefined) : confirmProposal(context, title, message);
+  const cwd = ctx.cwd;
+  switch (params?.action) {
+    case "projects":
+      return memory.projects(cwd);
+    case "list":
+      return { ok: true, text: await memory.list(cwd, params.project) };
+    case "view":
+      return memory.view(params.record, params.entry, cwd);
+    case "search":
+      return memory.search(params.query, params.scope, cwd);
+    case "focus":
+      return memory.focus(params.record, cwd);
+    case "detach":
+      return memory.detach(params.record, cwd);
+    case "attach":
+      return (
+        (await ask(
+          ctx,
+          "Attach task record?",
+          `The agent proposes working on ${show(params.record)} in this session.`,
+        )) ?? memory.attach(params.record, cwd)
+      );
+    case "create": {
+      const declined = await ask(
+        ctx,
+        "Create task?",
+        `Create "${show(params.title)}" in this repository's project and attach it to this session? Goal: ${show(params.goal) || show(params.title)}`,
+      );
+      if (declined) return declined;
+      const created = await memory.create(params.title, params.goal, cwd);
+      if (!created.ok || !created.id) return created;
+      const attached = await memory.attach(created.id, cwd);
+      return attached.ok
+        ? {
+            ...attached,
+            headline: `Created and attached ${created.id} — ${show(params.title)}`,
+            text: `Created ${created.id} and attached it to this session.\n\n${attached.text}`,
+          }
+        : { ...attached, text: `Created ${created.id}, but it was not attached: ${attached.text}` };
+    }
+    case "child":
+      return (
+        (await ask(
+          ctx,
+          "Create child task?",
+          `Create "${show(params.title)}" as a child of the focused task, for a parallel session you start?`,
+        )) ?? memory.child(params.title, params.goal)
+      );
+    case "fanout":
+      return (
+        (await ask(
+          ctx,
+          "Fan out a child task?",
+          `Create child "${show(params.title)}" of the focused task with its own Git worktree and branch? You start its session in a new terminal.`,
+        )) ?? memory.fanout(params.title, params.goal)
+      );
+    case "project_new":
+    case "project_link": {
+      const operation = params.action === "project_new" ? "new" : "link";
+      const declined = await ask(
+        ctx,
+        operation === "new" ? "Create project?" : "Link repository?",
+        operation === "new"
+          ? `Create project "${show(params.name)}" and link this repository (${cwd}) to it?${show(params.worktrees) ? ` Child worktrees go in ${show(params.worktrees)}.` : ""}`
+          : `Link this repository (${cwd}) to project "${show(params.name)}"?`,
+      );
+      return declined ?? memory.project(operation, params.name, params.worktrees, cwd);
+    }
+    case "import":
+      return (
+        (await ask(
+          ctx,
+          "Import record?",
+          `Move ${show(params.record)} into the ${show(params.project)} project's store, with a task ID?`,
+        )) ?? memory.importRecord(params.record, params.project, cwd)
+      );
+    case "confirm":
+      return (
+        (await ask(
+          ctx,
+          "Make held record writable?",
+          `Let this session write ${show(params.record) || "its held records"}, taking ownership where another session owns one?`,
+        )) ?? memory.confirm(params.record, cwd)
+      );
+    case "env": {
+      const change = { primary: show(params.primary), add: show(params.add_dir), remove: show(params.remove_dir) };
+      if (change.primary || change.add || change.remove) {
+        const declined = await ask(
+          ctx,
+          "Change task directories?",
+          `For ${show(params.record)}: ${[change.primary && `primary ${change.primary}`, change.add && `add ${change.add}`, change.remove && `remove ${change.remove}`].filter(Boolean).join(", ")}?`,
+        );
+        if (declined) return declined;
+      }
+      return memory.environment(params.record, change, cwd);
+    }
+    case "remove":
+    case "project_remove": {
+      // Removal always asks: no auto-approve setting covers it (Task 006).
+      const target = params.action === "remove" ? { task: params.record } : { project: params.name };
+      const { question, error } = await memory.removalQuestion(target);
+      if (!question) return { ok: false, text: error ?? "Nothing to remove." };
+      const title = params.action === "remove" ? "Remove task?" : "Remove project?";
+      return (await confirmProposal(ctx, title, question)) ?? memory.remove(target);
+    }
+    default:
+      return { ok: false, text: `action must be one of ${ACTIONS.join(", ")}.` };
+  }
+}
+/** Declare or withdraw task_memory when task memory's effective state changes, keeping other tools in place. */
+export function applyTaskMemoryTools(pi, effective) {
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const current = pi.getActiveTools();
+  const present = current.includes(TASK_MEMORY_TOOL);
+  if (effective && !present) pi.setActiveTools([...current, TASK_MEMORY_TOOL]);
+  if (!effective && present) pi.setActiveTools(current.filter((name) => name !== TASK_MEMORY_TOOL));
+}

package/pi-extension/dist/tool-execution/apply-patch/grammar.js

@@ -0,0 +1,23 @@
+// The apply_patch Lark grammar from OpenAI Codex (codex-rs/core/assets/tools/apply_patch.lark at bcd6d9ab),
+// Copyright 2025 OpenAI, licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).
+// GPT models are trained on this exact grammar; keep it byte-identical to upstream.
+export const APPLY_PATCH_LARK_GRAMMAR = `start: begin_patch hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch: "*** End Patch" LF?
+
+hunk: add_hunk | delete_hunk | update_hunk
+add_hunk: "*** Add File: " filename LF add_line+
+delete_hunk: "*** Delete File: " filename LF
+update_hunk: "*** Update File: " filename LF change_move? change?
+
+filename: /(.+)/
+add_line: "+" /(.*)/ LF -> line
+
+change_move: "*** Move to: " filename LF
+change: (change_context | change_line)+ eof_line?
+change_context: ("@@" | "@@ " /(.+)/) LF
+change_line: ("+" | "-" | " ") /(.*)/ LF
+eof_line: "*** End of File" LF
+
+%import common.LF
+`;

package/pi-extension/dist/tool-execution/apply-patch/match.js

@@ -0,0 +1,38 @@
+// Locating a hunk's lines in a file, with the four passes of OpenAI Codex's seek_sequence
+// (codex-rs/apply-patch/src/seek_sequence.rs at bcd6d9ab, Apache-2.0): exact, then ignoring trailing whitespace,
+// then ignoring surrounding whitespace, then after normalizing Unicode punctuation and spaces.
+function normalise(line) {
+  return line
+    .trim()
+    .replace(/[‐‑‒–—―−]/g, "-")
+    .replace(/[‘’‚‛]/g, "'")
+    .replace(/[“”„‟]/g, '"')
+    .replace(/[  -   　]/g, " ");
+}
+const PASSES = [(line) => line, (line) => line.trimEnd(), (line) => line.trim(), normalise];
+function matchesAt(lines, pattern, at, pass) {
+  const compare = PASSES[pass];
+  for (let i = 0; i < pattern.length; i++) if (compare(lines[at + i]) !== compare(pattern[i])) return false;
+  return true;
+}
+/**
+ * The first index at or after `start` where `pattern` matches, and the pass that matched. With `endOfFile`, the
+ * search starts where the pattern would end the file (falling back to `start` when that is earlier than the file).
+ */
+export function seekSequence(lines, pattern, start, endOfFile) {
+  if (pattern.length === 0) return { index: start, pass: 0 };
+  if (pattern.length > lines.length) return undefined;
+  const from = endOfFile ? Math.max(lines.length - pattern.length, start) : start;
+  for (let pass = 0; pass < PASSES.length; pass++)
+    for (let i = from; i <= lines.length - pattern.length; i++)
+      if (matchesAt(lines, pattern, i, pass)) return { index: i, pass };
+  return undefined;
+}
+/** Other places in the whole file where the pattern matches with the same pass: a visible sign of ambiguity. */
+export function otherMatches(lines, pattern, index, pass) {
+  if (pattern.length === 0) return [];
+  const found = [];
+  for (let i = 0; i <= lines.length - pattern.length; i++)
+    if (i !== index && matchesAt(lines, pattern, i, pass)) found.push(i);
+  return found;
+}

package/pi-extension/dist/tool-execution/apply-patch/parser.js

@@ -0,0 +1,177 @@
+// A port of OpenAI Codex's apply_patch parser (codex-rs/apply-patch/src/{parser,streaming_parser}.rs at bcd6d9ab,
+// Apache-2.0), including its lenient forms, so patches GPT models write for Codex parse the same way here.
+export class PatchParseError extends Error {
+  line;
+  constructor(message, line) {
+    super(line === undefined ? message : `${message} (patch line ${line})`);
+    this.line = line;
+  }
+}
+const BEGIN = "*** Begin Patch";
+const END = "*** End Patch";
+const ADD = "*** Add File: ";
+const DELETE = "*** Delete File: ";
+const UPDATE = "*** Update File: ";
+const MOVE = "*** Move to: ";
+const EOF_MARKER = "*** End of File";
+const ENVIRONMENT = "*** Environment ID: ";
+const HEADERS = "Valid hunk headers: '*** Add File: {path}', '*** Delete File: {path}', '*** Update File: {path}'";
+const UNEXPECTED = (line) =>
+  `Unexpected line found in update hunk: '${line}'. Every line should start with ' ' (context line), '+' (added line), or '-' (removed line)`;
+function boundaries(lines) {
+  const strict = (candidate) => {
+    const first = candidate[0]?.trim(),
+      last = candidate.at(-1)?.trim();
+    if (first !== BEGIN) throw new PatchParseError(`The first line of the patch must be '${BEGIN}'`);
+    if (last !== END) throw new PatchParseError(`The last line of the patch must be '${END}'`);
+    return candidate;
+  };
+  try {
+    return strict(lines);
+  } catch (error) {
+    // Codex's lenient mode: a heredoc wrapper, as GPT models write for a shell invocation. The optional
+    // `apply_patch` prefix covers the same wrapper copied from a shell command.
+    const first = lines[0]?.replace(/^apply_patch\s+/, "");
+    if (["<<EOF", "<<'EOF'", '<<"EOF"'].includes(first ?? "") && lines.at(-1)?.endsWith("EOF") && lines.length >= 4)
+      return strict(lines.slice(1, -1));
+    throw error;
+  }
+}
+export function parsePatch(text) {
+  const lines = boundaries(text.trim().split(/\r?\n/));
+  const hunks = [];
+  let mode = "started";
+  let updateHeaderLine = 0;
+  let environment = false;
+  const lastUpdate = () => {
+    const hunk = hunks.at(-1);
+    return hunk?.kind === "update" ? hunk : undefined;
+  };
+  const ensureUpdateNotEmpty = (line, number) => {
+    const update = mode === "update" ? lastUpdate() : undefined;
+    if (!update) return;
+    if (update.chunks.length === 0)
+      throw new PatchParseError(`Update file hunk for path '${update.path}' is empty`, updateHeaderLine);
+    const chunk = update.chunks.at(-1);
+    if (chunk.oldLines.length === 0 && chunk.newLines.length === 0)
+      throw new PatchParseError(line === END ? "Update hunk does not contain any lines" : UNEXPECTED(line), number);
+  };
+  const header = (trimmed, number) => {
+    if (mode === "started" && trimmed.startsWith(ENVIRONMENT) && hunks.length === 0) {
+      if (environment) throw new PatchParseError("apply_patch environment_id cannot be specified more than once");
+      if (!trimmed.slice(ENVIRONMENT.length).trim())
+        throw new PatchParseError("apply_patch environment_id cannot be empty");
+      environment = true;
+      return true;
+    }
+    for (const [marker, kind] of [
+      [END, "end"],
+      [ADD, "add"],
+      [DELETE, "delete"],
+      [UPDATE, "update"],
+    ]) {
+      if (kind === "end" ? trimmed !== END : !trimmed.startsWith(marker)) continue;
+      ensureUpdateNotEmpty(trimmed, number);
+      const path = trimmed.slice(marker.length);
+      if (kind === "end") mode = "ended";
+      else if (kind === "add") {
+        hunks.push({ kind: "add", path, contents: "" });
+        mode = "add";
+      } else if (kind === "delete") {
+        hunks.push({ kind: "delete", path });
+        mode = "delete";
+      } else {
+        hunks.push({ kind: "update", path, chunks: [] });
+        mode = "update";
+        updateHeaderLine = number;
+      }
+      return true;
+    }
+    return false;
+  };
+  const chunk = (update) => {
+    if (update.chunks.length === 0) update.chunks.push({ oldLines: [], newLines: [], context: [], endOfFile: false });
+    return update.chunks.at(-1);
+  };
+  lines.slice(1).forEach((line, offset) => {
+    const number = offset + 2;
+    const trimmed = line.trim();
+    if (mode === "ended") {
+      if (trimmed) throw new PatchParseError(`The last line of the patch must be '${END}'`, number);
+      return;
+    }
+    if (mode === "started") {
+      if (!header(trimmed, number))
+        throw new PatchParseError(`'${trimmed}' is not a valid hunk header. ${HEADERS}`, number);
+      return;
+    }
+    if (mode === "add") {
+      if (header(trimmed, number)) return;
+      const add = hunks.at(-1);
+      if (line.startsWith("+") && add?.kind === "add") {
+        add.contents += `${line.slice(1)}\n`;
+        return;
+      }
+      throw new PatchParseError(`'${trimmed}' is not a valid hunk header. ${HEADERS}`, number);
+    }
+    if (mode === "delete") {
+      if (header(trimmed, number)) return;
+      throw new PatchParseError(`'${trimmed}' is not a valid hunk header. ${HEADERS}`, number);
+    }
+    // Update file.
+    const updateLine = line.trimEnd();
+    if (header(updateLine, number)) return;
+    const update = lastUpdate();
+    const current = update.chunks.at(-1);
+    if (current?.endOfFile) {
+      if (!updateLine) return;
+      if (updateLine !== "@@" && !updateLine.startsWith("@@ "))
+        throw new PatchParseError(`Expected update hunk to start with a @@ context marker, got: '${line}'`, number);
+    }
+    if (update.chunks.length === 0 && update.moveTo === undefined && updateLine.startsWith(MOVE)) {
+      update.moveTo = updateLine.slice(MOVE.length);
+      return;
+    }
+    const isAnchor = updateLine === "@@" || updateLine.startsWith("@@ ");
+    if (isAnchor && current && current.oldLines.length === 0 && current.newLines.length === 0)
+      throw new PatchParseError(UNEXPECTED(line), number);
+    if (isAnchor) {
+      update.chunks.push({
+        ...(updateLine === "@@" ? {} : { anchor: updateLine.slice(3) }),
+        oldLines: [],
+        newLines: [],
+        context: [],
+        endOfFile: false,
+      });
+      return;
+    }
+    if (updateLine === EOF_MARKER) {
+      if (!current || (current.oldLines.length === 0 && current.newLines.length === 0))
+        throw new PatchParseError("Update hunk does not contain any lines", number);
+      current.endOfFile = true;
+      return;
+    }
+    if (line === "" || line.startsWith(" ")) {
+      const target = chunk(update);
+      target.context.push([target.oldLines.length, target.newLines.length]);
+      const text = line === "" ? "" : line.slice(1);
+      target.oldLines.push(text);
+      target.newLines.push(text);
+      return;
+    }
+    if (line.startsWith("+")) {
+      chunk(update).newLines.push(line.slice(1));
+      return;
+    }
+    if (line.startsWith("-")) {
+      chunk(update).oldLines.push(line.slice(1));
+      return;
+    }
+    if (current && (current.oldLines.length > 0 || current.newLines.length > 0))
+      throw new PatchParseError(`Expected update hunk to start with a @@ context marker, got: '${line}'`, number);
+    throw new PatchParseError(UNEXPECTED(line), number);
+  });
+  // `mode` changes inside the callback above, which the compiler cannot see.
+  if (mode !== "ended") throw new PatchParseError(`The last line of the patch must be '${END}'`);
+  return hunks;
+}

package/pi-extension/dist/tool-execution/apply-patch/plan.js

@@ -0,0 +1,201 @@
+import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { resolveToolPath } from "../file-state.js";
+import { closestMatch } from "../edit-messages.js";
+import { parsePatch } from "./parser.js";
+import { otherMatches, seekSequence } from "./match.js";
+class PlanError extends Error {}
+async function isFile(path) {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+const MAX_SHOWN_LINES = 20;
+function notFound(path, hunk, oldLines, lines) {
+  const subject = `${path} hunk ${hunk}`;
+  const match = closestMatch(lines.join("\n"), oldLines.join("\n"));
+  if (!match)
+    return new PlanError(
+      `${subject}: context not found and no similar lines exist in the current file. Read the region you meant, then retry.`,
+    );
+  return new PlanError(
+    [
+      `${subject}: context not found. Closest match, lines ${match.start}–${match.end} (current file contents):`,
+      ...lines.slice(match.start - 1, Math.min(match.end, match.start - 1 + MAX_SHOWN_LINES)),
+      "If these are the lines you meant, retry with context copied exactly from them. If not, read the region you meant, then retry.",
+    ].join("\n"),
+  );
+}
+/** Split text as it was stored so it can be written back the same way: BOM, line ending, final newline. */
+function splitText(raw) {
+  const bom = raw.startsWith("") ? "" : "";
+  const body = raw.slice(bom.length);
+  const firstLf = body.indexOf("\n");
+  const crlf = firstLf > 0 && body[firstLf - 1] === "\r";
+  const lf = body.replace(/\r\n/g, "\n");
+  const finalNewline = lf === "" || lf.endsWith("\n");
+  const lines = lf === "" ? [] : lf.split("\n");
+  if (lf.endsWith("\n")) lines.pop();
+  return { bom, crlf, finalNewline, lines };
+}
+function joinText(parts, lines) {
+  const text = lines.join("\n") + (parts.finalNewline && lines.length > 0 ? "\n" : "");
+  return parts.bom + (parts.crlf ? text.replace(/\n/g, "\r\n") : text);
+}
+/** Codex's compute_replacements, keeping the file's own bytes on context lines. */
+function updateLines(path, lines, chunks, notes) {
+  const replacements = [];
+  let cursor = 0;
+  chunks.forEach((chunk, index) => {
+    const hunk = index + 1;
+    if (chunk.anchor !== undefined) {
+      const anchor = seekSequence(lines, [chunk.anchor], cursor, false);
+      if (!anchor)
+        throw new PlanError(
+          `${path} hunk ${hunk}: @@ line not found: '${chunk.anchor}'. Use a line that exists in the file after the previous hunk, or leave the @@ line empty.`,
+        );
+      cursor = anchor.index + 1;
+    }
+    if (chunk.oldLines.length === 0) {
+      replacements.push({ start: lines.length, length: 0, lines: [...chunk.newLines] });
+      return;
+    }
+    let pattern = chunk.oldLines;
+    let replacement = chunk.newLines;
+    let found = seekSequence(lines, pattern, cursor, chunk.endOfFile);
+    if (!found && pattern.at(-1) === "") {
+      // A trailing empty line stands for the file's final newline, which the line list does not hold.
+      pattern = pattern.slice(0, -1);
+      if (replacement.at(-1) === "") replacement = replacement.slice(0, -1);
+      found = seekSequence(lines, pattern, cursor, chunk.endOfFile);
+    }
+    if (!found) throw notFound(path, hunk, chunk.oldLines, lines);
+    const resolved = [...replacement];
+    for (const [oldIndex, newIndex] of chunk.context)
+      if (oldIndex < pattern.length && newIndex < resolved.length) resolved[newIndex] = lines[found.index + oldIndex];
+    const others = otherMatches(lines, pattern, found.index, found.pass);
+    if (others.length > 0)
+      notes.push(
+        `${path} hunk ${hunk}: its lines also match at line ${others.map((i) => i + 1).join(", ")}; it was applied at line ${found.index + 1}.`,
+      );
+    replacements.push({ start: found.index, length: pattern.length, lines: resolved });
+    cursor = found.index + pattern.length;
+  });
+  const next = [...lines];
+  for (const { start, length, lines: added } of [...replacements].sort((a, b) => b.start - a.start))
+    next.splice(start, length, ...added);
+  return next;
+}
+async function plan(hunks, cwd, files, notes) {
+  if (hunks.length === 0) throw new PlanError("The patch changes no files. Add at least one file section, then retry.");
+  // Later sections see earlier sections' results, as they would if applied one by one.
+  const virtual = new Map();
+  const current = async (abs) => {
+    if (virtual.has(abs)) return virtual.get(abs);
+    if (!(await isFile(abs))) return null;
+    const bytes = await readFile(abs);
+    const text = bytes.toString("utf8");
+    return Buffer.from(text, "utf8").equals(bytes) ? text : "\u0000not-utf8";
+  };
+  const steps = [];
+  for (const hunk of hunks) {
+    const abs = resolveToolPath(hunk.path, cwd);
+    const existing = await current(abs);
+    if (hunk.kind === "add") {
+      if (existing !== null && !virtual.has(abs) && !files.wasRead(hunk.path, cwd))
+        throw new PlanError(
+          `${hunk.path} exists and has not been read in this session. Read ${hunk.path}, then retry the patch.`,
+        );
+      virtual.set(abs, hunk.contents);
+      steps.push({ path: hunk.path, abs, operation: "add", content: hunk.contents });
+      continue;
+    }
+    if (existing === null)
+      throw new PlanError(
+        hunk.kind === "delete"
+          ? `${hunk.path}: file not found; nothing to delete.`
+          : `${hunk.path}: file not found. Use *** Add File: ${hunk.path} to create it.`,
+      );
+    if (existing === "\u0000not-utf8")
+      throw new PlanError(`${hunk.path}: not UTF-8 text; apply_patch edits text files only.`);
+    if (!virtual.has(abs) && (await files.changedSinceObserved(hunk.path, cwd)))
+      notes.push(`${hunk.path} changed since you read it; the patch applied to the current text.`);
+    if (hunk.kind === "delete") {
+      virtual.set(abs, null);
+      steps.push({ path: hunk.path, abs, operation: "delete" });
+      continue;
+    }
+    const parts = splitText(existing);
+    const content = joinText(parts, updateLines(hunk.path, parts.lines, hunk.chunks, notes));
+    if (hunk.moveTo !== undefined) {
+      const toAbs = resolveToolPath(hunk.moveTo, cwd);
+      if ((await current(toAbs)) !== null)
+        throw new PlanError(`${hunk.moveTo} already exists. Delete or rename it first, or move to another path.`);
+      virtual.set(abs, null);
+      virtual.set(toAbs, content);
+      steps.push({ path: hunk.path, abs, operation: "move", to: hunk.moveTo, toAbs, content });
+      continue;
+    }
+    virtual.set(abs, content);
+    steps.push({ path: hunk.path, abs, operation: "update", content });
+  }
+  return steps;
+}
+async function withLocks(paths, fn) {
+  // Sorted, so two patches touching the same files never wait on each other in opposite order.
+  const [first, ...rest] = [...new Set(paths)].sort();
+  return first === undefined ? fn() : withFileMutationQueue(first, () => withLocks(rest, fn));
+}
+async function write(step) {
+  if (step.operation === "delete") return unlink(step.abs);
+  const target = step.toAbs ?? step.abs;
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, step.content, "utf8");
+  if (step.operation === "move") await unlink(step.abs);
+}
+/** Plan the whole patch against current files, then write it; a planning failure writes nothing. */
+export async function applyPatch(text, cwd, files) {
+  const notes = [];
+  let hunks;
+  try {
+    hunks = parsePatch(text);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { status: "not_applied", files: [], notes, error: `Invalid patch: ${reason}. Fix the patch, then retry.` };
+  }
+  const paths = hunks.flatMap((hunk) => [
+    resolveToolPath(hunk.path, cwd),
+    ...(hunk.kind === "update" && hunk.moveTo !== undefined ? [resolveToolPath(hunk.moveTo, cwd)] : []),
+  ]);
+  return withLocks(paths, async () => {
+    let steps;
+    try {
+      steps = await plan(hunks, cwd, files, notes);
+    } catch (error) {
+      if (!(error instanceof PlanError)) throw error;
+      return { status: "not_applied", files: [], notes, error: error.message };
+    }
+    const changes = steps.map((step) => ({
+      path: step.path,
+      operation: step.operation,
+      ...(step.to === undefined ? {} : { to: step.to }),
+      outcome: "not_written",
+    }));
+    for (const [index, step] of steps.entries()) {
+      try {
+        await write(step);
+        changes[index].outcome = "written";
+      } catch (error) {
+        changes[index].outcome = "failed";
+        changes[index].error = error instanceof Error ? error.message : String(error);
+        // A failed write may already have changed its target, so this is never reported as "not applied".
+        // Nothing after it is attempted.
+        return { status: "partial", files: changes, notes };
+      }
+    }
+    return { status: "applied", files: changes, notes };
+  });
+}