pi-patcher 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bassim Shahidy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,135 @@
+# pi-patcher
+
+Self-healing patches for [pi](https://github.com/earendil-works/pi-coding-agent).
+
+Want to modify `pi` but your changes require a patch? Use `pi-patcher` to keep source patches applied across every `pi update`. When patching fails due to updates to target files, `pi-patcher` uses `pi` to self-heal: the AI updates the patch file for the new code and applies it.
+
+## The idea
+
+Every time pi updates, your local patches break. The old story is: re-derive the patch, re-apply, repeat forever.
+
+pi-patcher flips that. Each patch is a tiny `oldText → newText` spec plus a plain-English `intent.md`. On every `pi update`:
+
+1. If the spec still applies cleanly, it's re-applied. Done.
+2. If it drifted, pi-patcher hands the intent, the old spec, and the new target file to pi and asks it to find the equivalent edit.
+3. The healed edit is diffed back into a fresh spec and saved. Next update, it just works.
+
+Pi patches pi. The patch maintainer is the agent.
+
+## Install
+
+```sh
+npm install -g pi-patcher
+pi-patcher init
+```
+
+`pi-patcher init` applies the bundled `bootstrap-hook` patch, wiring `pi-patcher reconcile` into the end of `pi update` so your patches are re-applied automatically on every future update. Every edit is reversible via `pi-patcher remove` or `pi-patcher uninstall`, and any failed apply or heal is rolled back automatically, leaving the target file untouched.
+
+You write patches in `~/.pi/patches/`; pi-patcher's own bundled patches live separately under `~/.pi/pi-patcher/internal-patches/` and never touch your dir.
+
+## Commands
+
+```sh
+pi-patcher init         # one-time setup: install bundled patches + wire into `pi update`
+pi-patcher reconcile    # apply pending patches; heal drifted ones
+pi-patcher list         # status + most recent heal session per patch
+pi-patcher heal <id>    # force-heal one patch (manual re-anchor)
+pi-patcher remove <id>  # revert a user patch's edits and delete its folder
+pi-patcher uninstall    # revert every patch and `npm uninstall -g pi-patcher`
+```
+
+Running `pi-patcher` with no arguments prints this list.
+
+`init` is what you run once after `npm install`. Re-running it after upgrades is safe.
+
+`reconcile` is the workhorse for steady-state. It runs automatically after every `pi update` (via the hook `init` installs), and you can also run it by hand after authoring or editing a patch.
+
+`remove` reverts a user patch, then deletes its folder. Bundled patches are managed by pi-patcher — use `uninstall` to remove those.
+
+## Writing a patch
+
+A patch is just a folder in `~/.pi/patches/` with a `PATCH.md` file:
+
+````text
+~/.pi/patches/<id>/
+  PATCH.md
+````
+
+`PATCH.md` is freeform markdown plus frontmatter and fenced edit blocks. The prose is fed to the AI when healing; mechanical apply only reads the frontmatter and edit fences:
+
+````md
+---
+id: my-patch
+summary: What this patch does
+version: 0.1.0
+lastUpdated: 2026-06-25
+---
+
+# My patch
+
+Whatever prose helps explain the patch.
+
+```patch file=dist/example.js
+<<<<<<< SEARCH
+old text
+=======
+new text
+>>>>>>> REPLACE
+```
+````
+
+Diff-style hunks are also supported:
+
+````md
+```diff file=dist/example.js
+@@ optional hint @@
+ context line
++added line
+```
+````
+
+Each derived `oldText` must appear exactly once in the target file. `newText` must be non-empty — deletion-only patches aren't supported in this version (replace the line with a comment instead).
+
+A patch can contain multiple fenced edits, across one or more files. Mechanical apply, revert, and AI heal all iterate over every entry; heal runs one AI session per drifted replacement and rewrites only that entry in `PATCH.md`. Legacy `intent.md` + `spec.json` patch folders are still read for backwards compatibility.
+
+JavaScript and JSON targets are syntax-checked after every edit. Any file type (markdown, plain text, etc.) is supported.
+
+## How healing works
+
+When the literal `oldText`/`newText` no longer matches, pi-patcher hands the work to pi:
+
+- the target file is snapshotted first
+- `pi -p --model ${PI_PATCHER_HEAL_MODEL:-openai-codex/gpt-5.5:low} --session-id <id>` is invoked with `prompts/heal.md` on stdin
+- pi uses your normal session storage, so heal sessions remain discoverable anywhere `pi --session <id>` can find them
+- pi-patcher shows a small progress spinner while the headless heal runs, but suppresses raw nested pi output by default
+- the result is syntax-checked (JS / JSON only); the snapshot is restored on failure
+- if pi decides the change is out of scope (feature removed, would require a redesign), it emits `===ABORT===` internally and pi-patcher prints the abort reason once
+- on success, pi-patcher derives a fresh `oldText`/`newText` from the AI's edit and saves it back to `PATCH.md` (or `spec.json` for legacy patches)
+
+Each heal prints the short replay command, e.g. `pi --session 019efc67-5d7d-75f1-b395-62e7ccc0eda0`.
+
+## Uninstalling
+
+```sh
+pi-patcher uninstall
+```
+
+Reverts every patch (yours and the bundled ones), deletes their folders, forgets state, then runs `npm uninstall -g pi-patcher`.
+
+To *temporarily* disable pi-patcher without uninstalling, rename any patch directory to `_<id>`. The loader skips underscore-prefixed entries.
+
+## Model configuration
+
+`PI_PATCHER_HEAL_MODEL` overrides the default heal model (`openai-codex/gpt-5.5:low`).
+
+## Development
+
+```sh
+bun test
+bun run typecheck
+bun run build
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,1090 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import fs4 from "node:fs";
+import path4 from "node:path";
+import { spawnSync } from "node:child_process";
+
+// src/patches.ts
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+var ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+var PATCHES_DIR = path.join(os.homedir(), ".pi", "patches");
+var HOME = path.join(os.homedir(), ".pi", "pi-patcher");
+var STATE = path.join(HOME, "state.json");
+var INTERNAL_PATCHES_DIR = path.join(HOME, "internal-patches");
+var PROMPTS_DIR = path.join(ROOT, "prompts");
+var BUNDLED_PATCHES = process.env.PI_PATCHER_BUNDLED_DIR ?? path.join(ROOT, "patches");
+var HEAL_MODEL = process.env.PI_PATCHER_HEAL_MODEL ?? "openai-codex/gpt-5.5:low";
+function ensureLayout() {
+  for (const dir of [PATCHES_DIR, INTERNAL_PATCHES_DIR])
+    fs.mkdirSync(dir, { recursive: true });
+}
+function syncInternalPatches(baseShas, mode) {
+  ensureLayout();
+  const events = [];
+  if (!fs.existsSync(BUNDLED_PATCHES))
+    return events;
+  for (const entry of fs.readdirSync(BUNDLED_PATCHES, { withFileTypes: true })) {
+    if (!entry.isDirectory())
+      continue;
+    const id = entry.name;
+    const bundledDir = path.join(BUNDLED_PATCHES, id);
+    const bundledFile = patchDefinitionPath(bundledDir);
+    if (!bundledFile)
+      continue;
+    const bundledSha = sha(fs.readFileSync(bundledFile, "utf8"));
+    const workingDir = path.join(INTERNAL_PATCHES_DIR, id);
+    const workingFile = patchDefinitionPath(workingDir);
+    if (!workingFile) {
+      if (mode !== "seed")
+        continue;
+      replaceDir(bundledDir, workingDir);
+      baseShas[id] = bundledSha;
+      events.push({ id, action: "seeded" });
+      continue;
+    }
+    const workingSha = sha(fs.readFileSync(workingFile, "utf8"));
+    const baseSha = baseShas[id];
+    if (workingSha === baseSha && bundledSha !== baseSha) {
+      replaceDir(bundledDir, workingDir);
+      baseShas[id] = bundledSha;
+      events.push({ id, action: "refreshed" });
+    } else if (baseSha === undefined) {
+      baseShas[id] = workingSha;
+    }
+  }
+  return events;
+}
+function isInternalPatch(id) {
+  return patchDefinitionPath(path.join(INTERNAL_PATCHES_DIR, id)) !== undefined;
+}
+function findPiRoot() {
+  let piBin;
+  try {
+    piBin = execFileSync("which", ["pi"], { encoding: "utf8" }).trim();
+  } catch {
+    throw new Error("Could not find `pi` on PATH");
+  }
+  let current = fs.realpathSync(piBin);
+  if (fs.statSync(current).isFile())
+    current = path.dirname(current);
+  while (current !== path.dirname(current)) {
+    const pkg = path.join(current, "package.json");
+    if (fs.existsSync(pkg)) {
+      try {
+        const json = JSON.parse(fs.readFileSync(pkg, "utf8"));
+        if (json.name === "@earendil-works/pi-coding-agent")
+          return current;
+      } catch {}
+    }
+    current = path.dirname(current);
+  }
+  throw new Error("Could not resolve pi package root from `pi` on PATH");
+}
+function resolveTarget(piRoot, target) {
+  return path.isAbsolute(target) ? target : path.join(piRoot, target);
+}
+function allPatches() {
+  ensureLayout();
+  const internal = discoverPatchesIn(INTERNAL_PATCHES_DIR);
+  const user = discoverPatchesIn(PATCHES_DIR);
+  const seen = new Set(internal.map((p) => p.id));
+  return [...internal, ...user.filter((p) => !seen.has(p.id))].sort((a, b) => a.id.localeCompare(b.id));
+}
+function discoverPatchesIn(dir) {
+  if (!fs.existsSync(dir))
+    return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith("_") && patchDefinitionPath(path.join(dir, e.name)) !== undefined).map((e) => loadFromDir(path.join(dir, e.name)));
+}
+function loadPatch(id) {
+  ensureLayout();
+  for (const base of [INTERNAL_PATCHES_DIR, PATCHES_DIR]) {
+    const dir = path.join(base, id);
+    if (patchDefinitionPath(dir))
+      return loadFromDir(dir);
+  }
+  throw new Error(`No patch named ${id}`);
+}
+function saveSpec(patch, spec) {
+  if (patch.source === "markdown") {
+    fs.writeFileSync(path.join(patch.dir, "PATCH.md"), renderPatchMd(patch, spec));
+  } else {
+    fs.writeFileSync(path.join(patch.dir, "spec.json"), `${JSON.stringify(spec, null, 2)}
+`);
+  }
+  patch.spec = spec;
+}
+function removePatchDir(id) {
+  fs.rmSync(path.join(PATCHES_DIR, id), { recursive: true, force: true });
+}
+function loadFromDir(dir) {
+  const id = path.basename(dir);
+  const patchMd = path.join(dir, "PATCH.md");
+  if (fs.existsSync(patchMd)) {
+    const patch = parsePatchMd(dir, fs.readFileSync(patchMd, "utf8"));
+    validateSpec(patch.id, patch.spec);
+    return patch;
+  }
+  const specPath = path.join(dir, "spec.json");
+  const intentPath = path.join(dir, "intent.md");
+  const spec = JSON.parse(fs.readFileSync(specPath, "utf8"));
+  validateSpec(id, spec);
+  return {
+    id,
+    dir,
+    intent: fs.existsSync(intentPath) ? fs.readFileSync(intentPath, "utf8") : "",
+    spec,
+    source: "json"
+  };
+}
+function patchDefinitionPath(dir) {
+  const patchMd = path.join(dir, "PATCH.md");
+  if (fs.existsSync(patchMd))
+    return patchMd;
+  const specJson = path.join(dir, "spec.json");
+  return fs.existsSync(specJson) ? specJson : undefined;
+}
+function parsePatchMd(dir, markdown) {
+  const fallbackId = path.basename(dir);
+  const { attrs, body, bodyOffset } = parseFrontmatter(markdown);
+  const id = stringAttr(attrs.id) ?? fallbackId;
+  if (id !== fallbackId)
+    throw new Error(`${fallbackId}: PATCH.md id must match its directory name`);
+  const title = body.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? id;
+  const parsed = parseMarkdownEdits(id, body, bodyOffset);
+  return {
+    id,
+    dir,
+    intent: markdown.trim(),
+    spec: { version: 1, files: parsed.files },
+    source: "markdown",
+    summary: stringAttr(attrs.summary),
+    title,
+    markdown,
+    markdownBlocks: parsed.blocks
+  };
+}
+function parseFrontmatter(markdown) {
+  if (!markdown.startsWith(`---
+`))
+    return { attrs: {}, body: markdown, bodyOffset: 0 };
+  const end = markdown.indexOf(`
+---`, 4);
+  if (end === -1)
+    return { attrs: {}, body: markdown, bodyOffset: 0 };
+  const raw = markdown.slice(4, end).trim();
+  const attrs = {};
+  for (const line of raw.split(/\r?\n/)) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (match)
+      attrs[match[1]] = match[2].replace(/^['"]|['"]$/g, "");
+  }
+  let bodyOffset = end + 5;
+  if (markdown.slice(bodyOffset).startsWith(`
+`))
+    bodyOffset++;
+  return { attrs, body: markdown.slice(bodyOffset), bodyOffset };
+}
+function stringAttr(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function parseMarkdownEdits(id, body, bodyOffset) {
+  const byTarget = new Map;
+  const targetOrder = [];
+  const blocks = [];
+  for (const fence of markdownFences(body)) {
+    const target = targetFromFenceInfo(fence.info);
+    if (!target)
+      continue;
+    const replacement = parseSearchReplaceBlock(fence.content) ?? parseDiffBlock(fence.content);
+    if (!replacement)
+      throw new Error(`${id}: ${target}: fence is neither a search/replace nor a hunk block`);
+    const anchorHint = noteBefore(body.slice(0, fence.start));
+    if (anchorHint)
+      replacement.anchorHint = anchorHint;
+    if (!byTarget.has(target))
+      targetOrder.push(target);
+    const replacements = byTarget.get(target) ?? [];
+    const fileIndex = targetOrder.indexOf(target);
+    const replacementIndex = replacements.length;
+    replacements.push(replacement);
+    byTarget.set(target, replacements);
+    blocks.push({
+      start: bodyOffset + fence.start,
+      end: bodyOffset + fence.end,
+      fileIndex,
+      replacementIndex,
+      target
+    });
+  }
+  return {
+    files: targetOrder.map((target) => ({
+      target,
+      replacements: byTarget.get(target) ?? []
+    })),
+    blocks
+  };
+}
+function markdownFences(markdown) {
+  const fences = [];
+  let pos = 0;
+  while (pos < markdown.length) {
+    const lineStart = pos;
+    const lineEnd = markdown.indexOf(`
+`, lineStart);
+    const lineStop = lineEnd === -1 ? markdown.length : lineEnd;
+    const line = markdown.slice(lineStart, lineStop);
+    const open = line.match(/^\s{0,3}(`{3,})(.*)$/);
+    pos = lineEnd === -1 ? markdown.length : lineEnd + 1;
+    if (!open)
+      continue;
+    const tickCount = open[1].length;
+    const info = open[2].trim();
+    const contentStart = pos;
+    let closeStart = -1;
+    let closeEnd = -1;
+    while (pos < markdown.length) {
+      const candidateStart = pos;
+      const candidateLineEnd = markdown.indexOf(`
+`, candidateStart);
+      const candidateStop = candidateLineEnd === -1 ? markdown.length : candidateLineEnd;
+      const candidate = markdown.slice(candidateStart, candidateStop);
+      pos = candidateLineEnd === -1 ? markdown.length : candidateLineEnd + 1;
+      if (new RegExp(`^\\s{0,3}\`{${tickCount},}\\s*$`).test(candidate)) {
+        closeStart = candidateStart;
+        closeEnd = candidateStop;
+        break;
+      }
+    }
+    if (closeStart === -1)
+      break;
+    let content = markdown.slice(contentStart, closeStart);
+    if (content.endsWith(`
+`))
+      content = content.slice(0, -1);
+    fences.push({ start: lineStart, end: closeEnd, info, content });
+  }
+  return fences;
+}
+function targetFromFenceInfo(info) {
+  const match = info.match(/(?:^|\s)file=("[^"]+"|'[^']+'|\S+)/);
+  if (!match)
+    return;
+  return match[1].replace(/^['"]|['"]$/g, "").trim() || undefined;
+}
+function noteBefore(prefix) {
+  return prefix.match(/(?:^|\n)>\s*note:\s*([^\n]+)\n\s*$/i)?.[1]?.trim();
+}
+function parseSearchReplaceBlock(block) {
+  const match = block.match(/^<<<<<<< SEARCH\r?\n([\s\S]*?)^=======\r?\n([\s\S]*?)^>>>>>>> REPLACE\s*$/m);
+  return match ? { oldText: match[1], newText: match[2] } : null;
+}
+function parseDiffBlock(block) {
+  const lines = block.split(/\r?\n/);
+  const oldLines = [];
+  const newLines = [];
+  let changed = false;
+  for (const line of lines) {
+    if (/^@@.*@@$/.test(line))
+      continue;
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      newLines.push(line.slice(1));
+      changed = true;
+    } else if (line.startsWith("-") && !line.startsWith("---")) {
+      oldLines.push(line.slice(1));
+      changed = true;
+    } else {
+      oldLines.push(line);
+      newLines.push(line);
+    }
+  }
+  if (!changed)
+    return null;
+  const oldText = oldLines.length ? `${oldLines.join(`
+`)}
+` : "";
+  const newText = newLines.length ? `${newLines.join(`
+`)}
+` : "";
+  return { oldText, newText };
+}
+function renderPatchMd(patch, spec) {
+  if (patch.markdown && patch.markdownBlocks?.length) {
+    let markdown = patch.markdown;
+    for (const block of [...patch.markdownBlocks].sort((a, b) => b.start - a.start)) {
+      const replacement = spec.files[block.fileIndex]?.replacements[block.replacementIndex];
+      if (!replacement)
+        continue;
+      markdown = `${markdown.slice(0, block.start)}${renderSearchReplaceFence(block.target, replacement)}${markdown.slice(block.end)}`;
+    }
+    return markdown.endsWith(`
+`) ? markdown : `${markdown}
+`;
+  }
+  const title = patch.title ?? patch.id;
+  const summary = patch.summary ?? title;
+  const out = [
+    "---",
+    `id: ${patch.id}`,
+    `summary: ${summary}`,
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    patch.intent.trim(),
+    ""
+  ];
+  for (const file of spec.files) {
+    for (const replacement of file.replacements)
+      out.push(renderSearchReplaceFence(file.target, replacement), "");
+  }
+  return `${out.join(`
+`).replace(/\n{3,}/g, `
+
+`).trimEnd()}
+`;
+}
+function renderSearchReplaceFence(target, replacement) {
+  return [
+    `\`\`\`patch file=${target}`,
+    "<<<<<<< SEARCH",
+    replacement.oldText.replace(/\n$/, ""),
+    "=======",
+    replacement.newText.replace(/\n$/, ""),
+    ">>>>>>> REPLACE",
+    "```"
+  ].join(`
+`);
+}
+function validateSpec(id, spec) {
+  if (!Array.isArray(spec.files) || spec.files.length === 0)
+    throw new Error(`${id}: patch must define at least one edit`);
+  for (const file of spec.files) {
+    if (!file.target || !Array.isArray(file.replacements))
+      throw new Error(`${id}: each file needs a target and replacements`);
+    for (const r of file.replacements) {
+      if (typeof r.oldText !== "string" || typeof r.newText !== "string")
+        throw new Error(`${id}: replacements need oldText and newText strings`);
+      if (r.oldText === "")
+        throw new Error(`${id}: empty oldText is not supported`);
+      if (r.newText === "")
+        throw new Error(`${id}: empty newText (deletion patches) is not supported. ` + `Replace the line with a comment or no-op instead.`);
+    }
+  }
+}
+function statusOf(patch, piRoot) {
+  const seen = new Set;
+  for (const file of patch.spec.files) {
+    const target = resolveTarget(piRoot, file.target);
+    if (!fs.existsSync(target)) {
+      seen.add("drift");
+      continue;
+    }
+    const text = fs.readFileSync(target, "utf8");
+    for (const r of file.replacements)
+      seen.add(classify(r, text));
+  }
+  if (seen.has("drift"))
+    return "drift";
+  if (seen.has("pending"))
+    return "pending";
+  return "applied";
+}
+function classify(r, text) {
+  const newCount = count(text, r.newText);
+  if (newCount === 1)
+    return "applied";
+  if (newCount > 1)
+    return "drift";
+  return count(text, r.oldText) === 1 ? "pending" : "drift";
+}
+function applyEdits(patch, piRoot) {
+  return runEdits(patch, piRoot, false);
+}
+function revertEdits(patch, piRoot) {
+  return runEdits(patch, piRoot, true);
+}
+function runEdits(patch, piRoot, reverse) {
+  const originals = new Map;
+  let changed = false;
+  try {
+    for (const file of patch.spec.files) {
+      const target = resolveTarget(piRoot, file.target);
+      const original = fs.readFileSync(target, "utf8");
+      let text = original;
+      for (const r of file.replacements) {
+        const status = classify(r, text);
+        const done = reverse ? "pending" : "applied";
+        const ready = reverse ? "applied" : "pending";
+        if (status === done)
+          continue;
+        if (status === ready) {
+          text = reverse ? text.replace(r.newText, r.oldText) : text.replace(r.oldText, r.newText);
+          continue;
+        }
+        throw new Error(`${patch.id}: ${file.target}: cannot ${reverse ? "revert" : "apply"} a replacement (expected exactly one occurrence of ${reverse ? "newText" : "oldText"})`);
+      }
+      if (text === original)
+        continue;
+      if (!originals.has(target))
+        originals.set(target, original);
+      fs.writeFileSync(target, text);
+      validateTarget(target);
+      changed = true;
+    }
+  } catch (error) {
+    for (const [target, original] of originals)
+      fs.writeFileSync(target, original);
+    throw error;
+  }
+  return changed;
+}
+function validateTarget(target) {
+  const ext = path.extname(target).toLowerCase();
+  if (ext === ".js" || ext === ".mjs" || ext === ".cjs") {
+    execFileSync(process.execPath, ["--check", target], { stdio: "pipe" });
+    return;
+  }
+  if (ext === ".json") {
+    JSON.parse(fs.readFileSync(target, "utf8"));
+  }
+}
+function count(haystack, needle) {
+  if (!needle)
+    return 0;
+  let n = 0;
+  let i = 0;
+  while ((i = haystack.indexOf(needle, i)) !== -1) {
+    n++;
+    i += needle.length;
+  }
+  return n;
+}
+function sha(text) {
+  return crypto.createHash("sha256").update(text).digest("hex");
+}
+function derivePatch(before, after) {
+  if (before === after)
+    return null;
+  let start = 0;
+  while (start < before.length && start < after.length && before[start] === after[start])
+    start++;
+  let endBefore = before.length - 1;
+  let endAfter = after.length - 1;
+  while (endBefore >= start && endAfter >= start && before[endBefore] === after[endAfter]) {
+    endBefore--;
+    endAfter--;
+  }
+  let a = start;
+  while (a > 0 && before[a - 1] !== `
+`)
+    a--;
+  let b = endBefore + 1;
+  while (b < before.length && before[b] !== `
+`)
+    b++;
+  if (b < before.length)
+    b++;
+  let c = start;
+  while (c > 0 && after[c - 1] !== `
+`)
+    c--;
+  let d = endAfter + 1;
+  while (d < after.length && after[d] !== `
+`)
+    d++;
+  if (d < after.length)
+    d++;
+  let oldText = before.slice(a, b);
+  let newText = after.slice(c, d);
+  while ((count(before, oldText) !== 1 || count(after, newText) !== 1) && (a > 0 || b < before.length || c > 0 || d < after.length)) {
+    if (a > 0) {
+      a--;
+      while (a > 0 && before[a - 1] !== `
+`)
+        a--;
+    }
+    if (c > 0) {
+      c--;
+      while (c > 0 && after[c - 1] !== `
+`)
+        c--;
+    }
+    if (b < before.length) {
+      while (b < before.length && before[b] !== `
+`)
+        b++;
+      if (b < before.length)
+        b++;
+    }
+    if (d < after.length) {
+      while (d < after.length && after[d] !== `
+`)
+        d++;
+      if (d < after.length)
+        d++;
+    }
+    oldText = before.slice(a, b);
+    newText = after.slice(c, d);
+  }
+  return { oldText, newText };
+}
+function replaceDir(src, dst) {
+  fs.rmSync(dst, { recursive: true, force: true });
+  copyDir(src, dst, true);
+}
+function copyDir(src, dst, overwrite = false) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dst, entry.name);
+    if (entry.isDirectory())
+      copyDir(s, d, overwrite);
+    else if (overwrite || !fs.existsSync(d))
+      fs.copyFileSync(s, d);
+  }
+}
+
+// src/state.ts
+import fs2 from "node:fs";
+import path2 from "node:path";
+function loadState() {
+  try {
+    return JSON.parse(fs2.readFileSync(STATE, "utf8"));
+  } catch {
+    return { patches: {} };
+  }
+}
+function saveState(state) {
+  fs2.mkdirSync(path2.dirname(STATE), { recursive: true });
+  fs2.writeFileSync(STATE, `${JSON.stringify(state, null, 2)}
+`);
+}
+function recordApplied(state, id) {
+  const entry = entryFor(state, id);
+  entry.lastAppliedAt = new Date().toISOString();
+  delete entry.lastError;
+}
+function recordReverted(state, id) {
+  const entry = entryFor(state, id);
+  entry.lastRevertedAt = new Date().toISOString();
+  delete entry.lastError;
+}
+function recordHealed(state, id) {
+  const entry = entryFor(state, id);
+  entry.lastHealedAt = new Date().toISOString();
+  delete entry.lastError;
+}
+function recordError(state, id, message) {
+  entryFor(state, id).lastError = message;
+}
+function rememberSession(state, id, sessionId) {
+  const entry = entryFor(state, id);
+  entry.lastSessions = [sessionId, ...entry.lastSessions ?? []].slice(0, 10);
+}
+function forgetPatch(state, id) {
+  delete state.patches[id];
+}
+function patchError(state, id) {
+  return state.patches[id]?.lastError;
+}
+function lastSession(state, id) {
+  return state.patches[id]?.lastSessions?.[0];
+}
+function entryFor(state, id) {
+  state.patches[id] ??= {};
+  return state.patches[id];
+}
+
+// src/heal.ts
+import fs3 from "node:fs";
+import path3 from "node:path";
+import crypto2 from "node:crypto";
+import { spawn } from "node:child_process";
+
+// src/ui.ts
+var useColor = Boolean(process.stdout.isTTY && !process.env.NO_COLOR);
+function color(code, text) {
+  return useColor ? `\x1B[${code}m${text}\x1B[0m` : text;
+}
+var ui = {
+  dim: (text) => color(2, text),
+  green: (text) => color(32, text),
+  yellow: (text) => color(33, text),
+  red: (text) => color(31, text),
+  cyan: (text) => color(36, text)
+};
+function logHeader() {
+  console.log("pi-patcher");
+}
+function logApplied(id) {
+  console.log(`  ${ui.green("✓")} ${id} applied`);
+}
+function logSuccess(message) {
+  console.log(`  ${ui.green("✓")} ${message}`);
+}
+function logWarn(message) {
+  console.log(`  ${ui.yellow("⚠")} ${message}`);
+}
+function logFailure(message) {
+  console.log(`  ${ui.red("✗")} ${message}`);
+}
+function logInfo(message) {
+  console.log(`  ${ui.dim("•")} ${message}`);
+}
+function logDetail(message) {
+  console.log(`    ${message}`);
+}
+function logLabeledDetail(label, text) {
+  const firstPrefix = `    ${label}: `;
+  const nextPrefix = " ".repeat(firstPrefix.length);
+  const columns = process.stdout.columns ?? 100;
+  const lines = wrapWords(text, Math.max(20, columns - firstPrefix.length));
+  if (lines.length === 0) {
+    console.log(firstPrefix.trimEnd());
+    return;
+  }
+  console.log(`${firstPrefix}${lines[0]}`);
+  for (const line of wrapWords(lines.slice(1).join(" "), Math.max(20, columns - nextPrefix.length)))
+    console.log(`${nextPrefix}${line}`);
+}
+function wrapWords(text, width) {
+  const words = text.trim().split(/\s+/).filter(Boolean);
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (!line)
+      line = word;
+    else if (line.length + 1 + word.length <= width)
+      line += ` ${word}`;
+    else {
+      lines.push(line);
+      line = word;
+    }
+  }
+  if (line)
+    lines.push(line);
+  return lines;
+}
+
+// src/heal.ts
+async function heal(patch, piRoot, state) {
+  let ok = true;
+  for (let fi = 0;fi < patch.spec.files.length; fi++) {
+    const file = patch.spec.files[fi];
+    for (let ri = 0;ri < file.replacements.length; ri++) {
+      const target = resolveTarget(piRoot, file.target);
+      if (!fs3.existsSync(target)) {
+        ok = false;
+        recordError(state, patch.id, `${file.target}: target file missing`);
+        continue;
+      }
+      const text = fs3.readFileSync(target, "utf8");
+      const replacement = patch.spec.files[fi].replacements[ri];
+      if (classify(replacement, text) !== "drift")
+        continue;
+      if (!await healOne(patch, fi, ri, piRoot, state))
+        ok = false;
+    }
+  }
+  return ok;
+}
+async function healOne(patch, fi, ri, piRoot, state) {
+  const file = patch.spec.files[fi];
+  const replacement = file.replacements[ri];
+  const target = resolveTarget(piRoot, file.target);
+  const before = fs3.readFileSync(target, "utf8");
+  const label = healLabel(patch, fi, ri);
+  logWarn(`${label} drifted`);
+  const sessionId = crypto2.randomUUID();
+  const stopSpinner = startSpinner(`healing ${label} with ${HEAL_MODEL}`);
+  const child = await runPiHeal(["-p", "--model", HEAL_MODEL, "--session-id", sessionId], renderPrompt(patch, file.target, target, replacement));
+  stopSpinner();
+  const output = child.output;
+  const fail = (reason, inspect = true) => {
+    fs3.writeFileSync(target, before);
+    recordError(state, patch.id, reason);
+    if (inspect)
+      rememberSession(state, patch.id, sessionId);
+    logFailure(`${label} not healed`);
+    logLabeledDetail("Reason", reason);
+    if (inspect)
+      logDetail(`Inspect: ${ui.cyan(`pi --session ${sessionId}`)}`);
+    return false;
+  };
+  const abort = output.match(/===ABORT===([\s\S]*?)===END===/);
+  if (abort)
+    return fail(abort[1].trim());
+  if (child.error)
+    return fail(`failed to start pi: ${child.error.message}`, false);
+  if (child.status !== 0)
+    return fail(child.signal ? `pi heal session terminated by signal ${child.signal}` : `pi heal session exited with status ${child.status ?? "unknown"}`);
+  try {
+    validateTarget(target);
+  } catch (error) {
+    return fail(`validation failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const after = fs3.readFileSync(target, "utf8");
+  const derived = derivePatch(before, after);
+  if (!derived || count(before, derived.oldText) !== 1 || count(after, derived.newText) !== 1)
+    return fail("edits did not produce a derivable patch");
+  rewriteReplacement(patch, fi, ri, derived);
+  rememberSession(state, patch.id, sessionId);
+  recordHealed(state, patch.id);
+  logSuccess(`${label} healed`);
+  logDetail(`Inspect: ${ui.cyan(`pi --session ${sessionId}`)}`);
+  return true;
+}
+var MAX_CAPTURED_OUTPUT = 1024 * 1024 * 20;
+function runPiHeal(args, input) {
+  return new Promise((resolve) => {
+    const child = spawn("pi", args, {
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const chunks = [];
+    let captured = 0;
+    let spawnError;
+    const capture = (chunk) => {
+      if (captured >= MAX_CAPTURED_OUTPUT)
+        return;
+      const remaining = MAX_CAPTURED_OUTPUT - captured;
+      const kept = chunk.length > remaining ? chunk.subarray(0, remaining) : chunk;
+      chunks.push(kept);
+      captured += kept.length;
+    };
+    child.stdout.on("data", capture);
+    child.stderr.on("data", capture);
+    child.on("error", (error) => {
+      spawnError = error;
+    });
+    child.on("close", (status, signal) => {
+      resolve({
+        output: Buffer.concat(chunks).toString("utf8"),
+        error: spawnError,
+        status,
+        signal
+      });
+    });
+    child.stdin.on("error", () => {});
+    child.stdin.end(input);
+  });
+}
+function startSpinner(message) {
+  if (!process.stdout.isTTY) {
+    console.log(`  ${ui.dim("…")} ${message}…`);
+    return () => {
+      return;
+    };
+  }
+  const frames = ["◐", "◓", "◑", "◒"].map(ui.yellow);
+  const start = Date.now();
+  let i = 0;
+  const render = () => {
+    const elapsed = Math.floor((Date.now() - start) / 1000);
+    process.stdout.write(`\r  ${frames[i++ % frames.length]} ${message} (${elapsed}s)`);
+  };
+  render();
+  const timer = setInterval(render, 120);
+  return () => {
+    clearInterval(timer);
+    process.stdout.write("\r\x1B[K");
+  };
+}
+function healLabel(patch, fi, ri) {
+  const file = patch.spec.files[fi];
+  if (patch.spec.files.length === 1 && file.replacements.length === 1)
+    return patch.id;
+  return `${patch.id} (${file.target}#${ri})`;
+}
+function renderPrompt(patch, target, targetPath, replacement) {
+  const template = fs3.readFileSync(path3.join(PROMPTS_DIR, "heal.md"), "utf8");
+  return template.replaceAll("{{patch_id}}", patch.id).replaceAll("{{target_path}}", targetPath).replaceAll("{{patch_markdown}}", patchMarkdownContext(patch, target, replacement)).replaceAll("{{validation_hint}}", validationHint(targetPath));
+}
+function patchMarkdownContext(patch, target, replacement) {
+  if (patch.source === "markdown") {
+    const patchMd = path3.join(patch.dir, "PATCH.md");
+    if (fs3.existsSync(patchMd))
+      return fs3.readFileSync(patchMd, "utf8").trim();
+    if (patch.markdown)
+      return patch.markdown.trim();
+  }
+  return [
+    `# ${patch.id}`,
+    "",
+    patch.intent.trim() || "Legacy spec.json patch.",
+    "",
+    `\`\`\`patch file=${target}`,
+    "<<<<<<< SEARCH",
+    replacement.oldText.replace(/\n$/, ""),
+    "=======",
+    replacement.newText.replace(/\n$/, ""),
+    ">>>>>>> REPLACE",
+    "```"
+  ].join(`
+`);
+}
+function validationHint(targetPath) {
+  const ext = path3.extname(targetPath).toLowerCase();
+  if (ext === ".js" || ext === ".mjs" || ext === ".cjs")
+    return `The target file must pass \`node --check ${targetPath}\` after edits.`;
+  if (ext === ".json")
+    return `The target file must remain valid JSON after edits.`;
+  return `The target file must remain syntactically valid for its language; no automatic check is run for this file type.`;
+}
+function rewriteReplacement(patch, fi, ri, derived) {
+  const newSpec = structuredClone(patch.spec);
+  const file = newSpec.files[fi];
+  const old = file.replacements[ri];
+  file.replacements[ri] = { ...old, ...derived };
+  saveSpec(patch, newSpec);
+}
+
+// src/cli.ts
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}, (error) => {
+  console.error(`pi-patcher: ${msg(error)}`);
+  process.exitCode = 1;
+});
+async function main(argv) {
+  if (argv.length === 0) {
+    console.log(helpText());
+    return 0;
+  }
+  const [cmd, ...rest] = argv;
+  switch (cmd) {
+    case "init":
+      return await cmdInit();
+    case "reconcile":
+      return await cmdReconcile();
+    case "list":
+      return await cmdList();
+    case "heal":
+      return await cmdHeal(requireArg(rest[0], "heal <id>"));
+    case "remove":
+      return await cmdRemove(requireArg(rest[0], "remove <id>"));
+    case "uninstall":
+      return await cmdUninstall();
+    case "help":
+    case "--help":
+    case "-h":
+      console.log(helpText());
+      return 0;
+    case "version":
+    case "--version":
+    case "-v":
+      console.log(version());
+      return 0;
+    default:
+      console.error(`pi-patcher: unknown command: ${cmd}`);
+      console.error(`Run \`pi-patcher --help\` for usage.`);
+      return 1;
+  }
+}
+function helpText() {
+  return `pi-patcher ${version()}
+Self-healing patches for pi.
+
+Usage:
+  pi-patcher init             Install bundled patches and wire into \`pi update\`
+  pi-patcher reconcile        Apply pending patches; heal drifted ones
+  pi-patcher list             Show status and most recent heal session
+  pi-patcher heal <id>        Re-anchor a drifted patch via AI
+  pi-patcher remove <id>      Revert edits and delete the patch folder
+  pi-patcher uninstall        Revert every patch and uninstall the npm package
+
+  pi-patcher --help, -h       Show this help
+  pi-patcher --version, -v    Show version
+
+First-run flow: \`npm install -g pi-patcher && pi-patcher init\`.
+Docs: https://github.com/AVGVSTVS96/pi-patcher`;
+}
+function version() {
+  try {
+    const pkg = JSON.parse(fs4.readFileSync(path4.join(ROOT, "package.json"), "utf8"));
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function cmdReconcile() {
+  return await withSession(async (piRoot, state) => {
+    logHeader();
+    state.internalBaseShas ??= {};
+    logSyncEvents(syncInternalPatches(state.internalBaseShas, "refresh-only"));
+    const summary = await applyAll(piRoot, state);
+    logSummary(summary);
+    return summary.failed ? 1 : 0;
+  });
+}
+
+class ReportedPatchFailure extends Error {
+}
+async function applyAll(piRoot, state) {
+  const summary = { applied: 0, healed: 0, current: 0, failed: 0 };
+  for (const patch of allPatches()) {
+    try {
+      summary[await reconcileOne(patch, piRoot, state)]++;
+    } catch (error) {
+      summary.failed++;
+      const message = msg(error);
+      recordError(state, patch.id, message);
+      if (!(error instanceof ReportedPatchFailure))
+        logFailure(`${patch.id} failed: ${message}`);
+    }
+  }
+  return summary;
+}
+async function reconcileOne(patch, piRoot, state) {
+  switch (statusOf(patch, piRoot)) {
+    case "applied":
+      delete state.patches[patch.id]?.lastError;
+      logSuccess(`${patch.id} already current`);
+      return "current";
+    case "pending": {
+      if (applyEdits(patch, piRoot))
+        recordApplied(state, patch.id);
+      logApplied(patch.id);
+      return "applied";
+    }
+    case "drift":
+      if (!await heal(patch, piRoot, state))
+        throw new ReportedPatchFailure(patchError(state, patch.id) ?? "heal failed");
+      return "healed";
+  }
+}
+function logSyncEvents(events) {
+  for (const e of events)
+    logInfo(e.action === "seeded" ? `seeded internal patch ${e.id}` : `refreshed internal patch ${e.id} (shipped update)`);
+}
+function logSummary(s) {
+  const parts = [];
+  if (s.applied)
+    parts.push(`${s.applied} applied`);
+  if (s.healed)
+    parts.push(`${s.healed} healed`);
+  if (s.current)
+    parts.push(`${s.current} already current`);
+  if (s.failed)
+    parts.push(`${s.failed} failed`);
+  console.log(`  ${parts.length ? parts.join(", ") : "no patches to apply"}`);
+}
+async function cmdList() {
+  return await withSession((piRoot, state) => {
+    logHeader();
+    let found = false;
+    for (const patch of allPatches()) {
+      found = true;
+      const status = statusOf(patch, piRoot);
+      if (status === "applied")
+        logSuccess(`${patch.id} applied`);
+      else if (status === "pending")
+        logInfo(`${patch.id} pending`);
+      else
+        logWarn(`${patch.id} drifted`);
+      const session = lastSession(state, patch.id);
+      if (session)
+        logLabeledDetail("Last heal", `pi --session ${sessionArg(session)}`);
+    }
+    if (!found)
+      console.log("  no patches found");
+    return 0;
+  });
+}
+function sessionArg(session) {
+  const base = path4.basename(session).replace(/\.jsonl$/, "");
+  return base.includes("_") ? base.slice(base.lastIndexOf("_") + 1) : base;
+}
+async function cmdHeal(id) {
+  return await withSession(async (piRoot, state) => await heal(loadPatch(id), piRoot, state) ? 0 : 1);
+}
+async function cmdRemove(id) {
+  return await withSession((piRoot, state) => {
+    if (isInternalPatch(id))
+      throw new Error(`${id} is managed by pi-patcher; use \`pi-patcher uninstall\` to remove it`);
+    const patch = loadPatch(id);
+    const status = statusOf(patch, piRoot);
+    if (status === "drift")
+      throw new Error(`${id} has drifted; the original edit isn't where we left it. ` + `Edit the target file by hand to remove the patch's effect, then re-run \`pi-patcher remove ${id}\`. ` + `If you just want the folder gone, \`rm -rf ~/.pi/patches/${id}\`.`);
+    if (status === "applied") {
+      if (revertEdits(patch, piRoot))
+        recordReverted(state, patch.id);
+      console.log(`pi-patcher: reverted ${id}`);
+    }
+    removePatchDir(id);
+    forgetPatch(state, id);
+    console.log(`pi-patcher: removed ${id}`);
+    return 0;
+  });
+}
+async function cmdInit() {
+  return await withSession(async (piRoot, state) => {
+    logHeader();
+    state.internalBaseShas ??= {};
+    logSyncEvents(syncInternalPatches(state.internalBaseShas, "seed"));
+    const summary = await applyAll(piRoot, state);
+    logSummary(summary);
+    if (!summary.failed) {
+      console.log("");
+      console.log("pi-patcher is wired into pi update.");
+      console.log("To remove cleanly later, run: pi-patcher uninstall");
+    }
+    return summary.failed ? 1 : 0;
+  });
+}
+async function cmdUninstall() {
+  const cleanupExit = await withSession((piRoot, state) => {
+    let issues = 0;
+    for (const patch of allPatches()) {
+      try {
+        const status = statusOf(patch, piRoot);
+        if (status === "applied") {
+          revertEdits(patch, piRoot);
+          logSuccess(`${patch.id} reverted`);
+        } else if (status === "drift") {
+          issues++;
+          logWarn(`${patch.id} skipped (drifted; file already modified upstream, left as-is)`);
+        }
+      } catch (error) {
+        issues++;
+        logFailure(`${patch.id} revert failed: ${msg(error)} (continuing)`);
+      }
+      fs4.rmSync(patch.dir, { recursive: true, force: true });
+      delete state.patches[patch.id];
+    }
+    delete state.internalBaseShas;
+    console.log(issues ? `pi-patcher: removed ${issues === 1 ? "1 patch with caveats" : `patches (${issues} with caveats)`}; running \`npm uninstall -g pi-patcher\`…` : `pi-patcher: all patches cleaned up; running \`npm uninstall -g pi-patcher\`…`);
+    return 0;
+  });
+  if (cleanupExit !== 0)
+    return cleanupExit;
+  const result = spawnSync("npm", ["uninstall", "-g", "pi-patcher"], {
+    stdio: "inherit"
+  });
+  return result.status ?? 1;
+}
+async function withSession(fn) {
+  ensureLayout();
+  const piRoot = findPiRoot();
+  const state = loadState();
+  state.piRoot = piRoot;
+  state.lastRunAt = new Date().toISOString();
+  try {
+    return await fn(piRoot, state);
+  } finally {
+    saveState(state);
+  }
+}
+function requireArg(value, hint) {
+  if (value == null)
+    throw new Error(`Usage: pi-patcher ${hint}`);
+  return value;
+}
+function msg(error) {
+  return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-patcher",
+  "version": "1.0.0",
+  "description": "Update-resilient self-healing patches for pi installs.",
+  "author": {
+    "name": "Bassim Shahidy",
+    "email": "bassim@shahidy.com",
+    "url": "https://bassim.sh"
+  },
+  "type": "module",
+  "bin": {
+    "pi-patcher": "dist/cli.js"
+  },
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "changeset": "changeset",
+    "typecheck": "tsc --noEmit",
+    "test": "bun run build && bun test",
+    "build": "tsc --noEmit && bun build src/cli.ts --target=node --outfile=dist/cli.js && chmod +x dist/cli.js",
+    "ci:publish": "bun run build && changeset publish",
+    "prepack": "bun run build"
+  },
+  "files": [
+    "dist",
+    "prompts",
+    "patches",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi",
+    "patch",
+    "patcher",
+    "self-healing",
+    "ai",
+    "agent",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AVGVSTVS96/pi-patcher.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AVGVSTVS96/pi-patcher/issues"
+  },
+  "homepage": "https://github.com/AVGVSTVS96/pi-patcher#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "bun@1.3.9",
+  "devDependencies": {
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^22.0.0",
+    "changesets-changelog-clean": "^1.4.0",
+    "typescript": "^5.5.0"
+  },
+  "license": "MIT"
+}

package/patches/bootstrap-hook/PATCH.md

@@ -0,0 +1,26 @@
+---
+id: bootstrap-hook
+summary: Re-run `pi-patcher reconcile` after pi finishes updating itself.
+version: 0.1.0
+lastUpdated: 2026-06-25
+---
+
+# Bootstrap hook
+
+## Intent
+
+After pi's built-in `pi update` command finishes updating pi itself, automatically run `pi-patcher reconcile` so all installed source patches are re-applied to the freshly updated pi install.
+
+This must be a tiny, safe hook in `dist/package-manager-cli.js` immediately after the existing `console.log(chalk.green(`Updated ${APP_NAME}`));` line in the self-update path. The inserted hook must be valid in pi's compiled ESM output and must not rely on CommonJS-only globals like `require`. It should not change update behavior if `pi-patcher` is missing or fails to launch.
+
+## Patch Edits
+
+### dist/package-manager-cli.js
+
+> note: end of the pi self-update branch, immediately after Updated ${APP_NAME}
+
+```diff file=dist/package-manager-cli.js
+@@ pi self update success branch @@
+                    console.log(chalk.green(`Updated ${APP_NAME}`));
++                    try { (await import("node:child_process")).spawnSync("pi-patcher", ["reconcile"], { stdio: "inherit" }); } catch {}
+```

package/prompts/heal.md

@@ -0,0 +1,37 @@
+You are healing a pi-patcher PATCH.md after upstream changed the target file.
+Use the PATCH.md as the source of truth; re-anchor its intended edit with the smallest equivalent change, not a redesign.
+
+Patch id: {{patch_id}}
+Target file: {{target_path}}
+
+## PATCH.md
+
+````markdown
+{{patch_markdown}}
+````
+
+## Task
+The PATCH.md edit for this target no longer applies cleanly. Use the prose and fenced edit as context, then edit the current target file to restore that same intent.
+
+Before editing, output exactly one planning block:
+
+===PLAN===
+A concise 2-4 sentence summary of what changed upstream and what you will edit.
+===END===
+
+Then perform the edit and exit.
+
+## Abort instead of redesigning
+If the PATCH.md intent no longer maps cleanly to this target file, do not edit. Output:
+
+===ABORT===
+A concise reason you are not proceeding.
+===END===
+
+Then exit.
+
+## Hard constraints
+- Edit only this file: {{target_path}}
+- Keep the edit as small as possible.
+- Do not modify package metadata, settings, logs, backups, or patch specs.
+- {{validation_hint}}