opencode-hashline 1.2.0 → 1.3.1

package/dist/opencode-hashline.cjs

@@ -37,11 +37,15 @@ __export(hashline_exports, {
   DEFAULT_EXCLUDE_PATTERNS: () => DEFAULT_EXCLUDE_PATTERNS,
   DEFAULT_PREFIX: () => DEFAULT_PREFIX,
   HashlineCache: () => HashlineCache,
+  HashlineError: () => HashlineError,
   applyHashEdit: () => applyHashEdit,
   buildHashMap: () => buildHashMap,
+  computeFileRev: () => computeFileRev,
   computeLineHash: () => computeLineHash,
   createHashline: () => createHashline,
   detectLineEnding: () => detectLineEnding,
+  extractFileRev: () => extractFileRev,
+  findCandidateLines: () => findCandidateLines,
   formatFileWithHashes: () => formatFileWithHashes,
   getAdaptiveHashLength: () => getAdaptiveHashLength,
   getByteLength: () => getByteLength,
@@ -53,6 +57,7 @@ __export(hashline_exports, {
   resolveRange: () => resolveRange,
   shouldExclude: () => shouldExclude,
   stripHashes: () => stripHashes,
+  verifyFileRev: () => verifyFileRev,
   verifyHash: () => verifyHash
 });
 function resolveConfig(config, pluginConfig) {
@@ -69,7 +74,9 @@ function resolveConfig(config, pluginConfig) {
     hashLength: merged.hashLength ?? DEFAULT_CONFIG.hashLength,
     cacheSize: merged.cacheSize ?? DEFAULT_CONFIG.cacheSize,
     prefix: merged.prefix !== void 0 ? merged.prefix : DEFAULT_CONFIG.prefix,
-    debug: merged.debug ?? DEFAULT_CONFIG.debug
+    debug: merged.debug ?? DEFAULT_CONFIG.debug,
+    fileRev: merged.fileRev ?? DEFAULT_CONFIG.fileRev,
+    safeReapply: merged.safeReapply ?? DEFAULT_CONFIG.safeReapply
   };
 }
 function fnv1aHash(str) {
@@ -100,33 +107,90 @@ function computeLineHash(idx, line, hashLen = 3) {
   const hash = raw % modulus;
   return hash.toString(16).padStart(hashLen, "0");
 }
-function formatFileWithHashes(content, hashLen, prefix) {
+function computeFileRev(content) {
+  const normalized = content.includes("\r\n") ? content.replace(/\r\n/g, "\n") : content;
+  const hash = fnv1aHash(normalized);
+  return hash.toString(16).padStart(8, "0");
+}
+function extractFileRev(annotatedContent, prefix) {
+  const effectivePrefix = prefix === void 0 ? DEFAULT_PREFIX : prefix === false ? "" : prefix;
+  const escapedPrefix = effectivePrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pattern = new RegExp(`^${escapedPrefix}REV:([0-9a-f]{8})$`);
+  const firstLine = annotatedContent.split("\n")[0];
+  const match = firstLine.match(pattern);
+  return match ? match[1] : null;
+}
+function verifyFileRev(expectedRev, currentContent) {
+  const actualRev = computeFileRev(currentContent);
+  if (actualRev !== expectedRev) {
+    throw new HashlineError({
+      code: "FILE_REV_MISMATCH",
+      message: `File revision mismatch: expected "${expectedRev}", got "${actualRev}". The file has changed since it was last read.`,
+      expected: expectedRev,
+      actual: actualRev,
+      hint: "Re-read the file to get fresh hash references and a new file revision."
+    });
+  }
+}
+function findCandidateLines(originalLineNumber, expectedHash, lines, hashLen) {
+  const effectiveLen = hashLen && hashLen >= 2 ? hashLen : expectedHash.length;
+  const originalIdx = originalLineNumber - 1;
+  const candidates = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (i === originalIdx) continue;
+    const candidateHash = computeLineHash(originalIdx, lines[i], effectiveLen);
+    if (candidateHash === expectedHash) {
+      candidates.push({
+        lineNumber: i + 1,
+        // 1-based
+        content: lines[i]
+      });
+    }
+  }
+  return candidates;
+}
+function formatFileWithHashes(content, hashLen, prefix, includeFileRev) {
   const normalized = content.includes("\r\n") ? content.replace(/\r\n/g, "\n") : content;
   const lines = normalized.split("\n");
   const effectiveLen = hashLen && hashLen >= 3 ? hashLen : getAdaptiveHashLength(lines.length);
   const effectivePrefix = prefix === void 0 ? DEFAULT_PREFIX : prefix === false ? "" : prefix;
+  const hashLens = new Array(lines.length).fill(effectiveLen);
   const hashes = new Array(lines.length);
-  const seen = /* @__PURE__ */ new Map();
-  const upgraded = /* @__PURE__ */ new Set();
   for (let idx = 0; idx < lines.length; idx++) {
-    const hash = computeLineHash(idx, lines[idx], effectiveLen);
-    if (seen.has(hash)) {
-      const longerLen = Math.min(effectiveLen + 1, 8);
-      const prevIdx = seen.get(hash);
-      if (!upgraded.has(prevIdx)) {
-        hashes[prevIdx] = computeLineHash(prevIdx, lines[prevIdx], longerLen);
-        upgraded.add(prevIdx);
+    hashes[idx] = computeLineHash(idx, lines[idx], effectiveLen);
+  }
+  let hasCollisions = true;
+  while (hasCollisions) {
+    hasCollisions = false;
+    const seen = /* @__PURE__ */ new Map();
+    for (let idx = 0; idx < lines.length; idx++) {
+      const h = hashes[idx];
+      const group = seen.get(h);
+      if (group) {
+        group.push(idx);
+      } else {
+        seen.set(h, [idx]);
+      }
+    }
+    for (const [, group] of seen) {
+      if (group.length < 2) continue;
+      for (const idx of group) {
+        const newLen = Math.min(hashLens[idx] + 1, 8);
+        if (newLen === hashLens[idx]) continue;
+        hashLens[idx] = newLen;
+        hashes[idx] = computeLineHash(idx, lines[idx], newLen);
+        hasCollisions = true;
       }
-      hashes[idx] = computeLineHash(idx, lines[idx], longerLen);
-      upgraded.add(idx);
-    } else {
-      seen.set(hash, idx);
-      hashes[idx] = hash;
     }
   }
-  return lines.map((line, idx) => {
+  const annotatedLines = lines.map((line, idx) => {
     return `${effectivePrefix}${idx + 1}:${hashes[idx]}|${line}`;
-  }).join("\n");
+  });
+  if (includeFileRev) {
+    const rev = computeFileRev(content);
+    annotatedLines.unshift(`${effectivePrefix}REV:${rev}`);
+  }
+  return annotatedLines.join("\n");
 }
 function stripHashes(content, prefix) {
   const effectivePrefix = prefix === void 0 ? DEFAULT_PREFIX : prefix === false ? "" : prefix;
@@ -136,9 +200,10 @@ function stripHashes(content, prefix) {
     hashLinePattern = new RegExp(`^([+ \\-])?${escapedPrefix}\\d+:[0-9a-f]{2,8}\\|`);
     stripRegexCache.set(escapedPrefix, hashLinePattern);
   }
+  const revPattern = new RegExp(`^${escapedPrefix}REV:[0-9a-f]{8}$`);
   const lineEnding = detectLineEnding(content);
   const normalized = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
-  const result = normalized.split("\n").map((line) => {
+  const result = normalized.split("\n").filter((line) => !revPattern.test(line)).map((line) => {
     const match = line.match(hashLinePattern);
     if (match) {
       const patchMarker = match[1] || "";
@@ -152,7 +217,10 @@ function parseHashRef(ref) {
   const match = ref.match(/^(\d+):([0-9a-f]{2,8})$/);
   if (!match) {
     const display = ref.length > 100 ? `${ref.slice(0, 100)}\u2026` : ref;
-    throw new Error(`Invalid hash reference: "${display}". Expected format: "<line>:<2-8 char hex>"`);
+    throw new HashlineError({
+      code: "INVALID_REF",
+      message: `Invalid hash reference: "${display}". Expected format: "<line>:<2-8 char hex>"`
+    });
   }
   return {
     line: parseInt(match[1], 10),
@@ -170,9 +238,10 @@ function normalizeHashRef(ref) {
     return `${parseInt(annotated[1], 10)}:${annotated[2].toLowerCase()}`;
   }
   const display = ref.length > 100 ? `${ref.slice(0, 100)}\u2026` : ref;
-  throw new Error(
-    `Invalid hash reference: "${display}". Expected "<line>:<hash>" or an annotated line like "#HL <line>:<hash>|..."`
-  );
+  throw new HashlineError({
+    code: "INVALID_REF",
+    message: `Invalid hash reference: "${display}". Expected "<line>:<hash>" or an annotated line like "#HL <line>:<hash>|..."`
+  });
 }
 function buildHashMap(content, hashLen) {
   const lines = content.split("\n");
@@ -185,50 +254,97 @@ function buildHashMap(content, hashLen) {
   }
   return map;
 }
-function verifyHash(lineNumber, hash, currentContent, hashLen, lines) {
+function verifyHash(lineNumber, hash, currentContent, hashLen, lines, safeReapply) {
   const contentLines = lines ?? currentContent.split("\n");
   const effectiveLen = hashLen && hashLen >= 2 ? hashLen : hash.length;
   if (lineNumber < 1 || lineNumber > contentLines.length) {
     return {
       valid: false,
+      code: "TARGET_OUT_OF_RANGE",
       message: `Line ${lineNumber} is out of range (file has ${contentLines.length} lines)`
     };
   }
   const idx = lineNumber - 1;
   const actualHash = computeLineHash(idx, contentLines[idx], effectiveLen);
   if (actualHash !== hash) {
+    const candidates = findCandidateLines(lineNumber, hash, contentLines, effectiveLen);
+    if (safeReapply && candidates.length === 1) {
+      return {
+        valid: true,
+        relocatedLine: candidates[0].lineNumber,
+        candidates
+      };
+    }
+    if (safeReapply && candidates.length > 1) {
+      return {
+        valid: false,
+        code: "AMBIGUOUS_REAPPLY",
+        expected: hash,
+        actual: actualHash,
+        candidates,
+        message: `Hash mismatch at line ${lineNumber}: expected "${hash}", got "${actualHash}". Found ${candidates.length} candidate lines \u2014 ambiguous reapply.`
+      };
+    }
     return {
       valid: false,
+      code: "HASH_MISMATCH",
       expected: hash,
       actual: actualHash,
+      candidates,
       message: `Hash mismatch at line ${lineNumber}: expected "${hash}", got "${actualHash}". The file may have changed since it was read.`
     };
   }
   return { valid: true };
 }
-function resolveRange(startRef, endRef, content, hashLen) {
+function resolveRange(startRef, endRef, content, hashLen, safeReapply) {
   const start = parseHashRef(startRef);
   const end = parseHashRef(endRef);
   if (start.line > end.line) {
-    throw new Error(
-      `Invalid range: start line ${start.line} is after end line ${end.line}`
-    );
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid range: start line ${start.line} is after end line ${end.line}`
+    });
   }
   const lineEnding = detectLineEnding(content);
   const normalized = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
   const lines = normalized.split("\n");
-  const startVerify = verifyHash(start.line, start.hash, normalized, hashLen, lines);
+  const startVerify = verifyHash(start.line, start.hash, normalized, hashLen, lines, safeReapply);
   if (!startVerify.valid) {
-    throw new Error(`Start reference invalid: ${startVerify.message}`);
+    throw new HashlineError({
+      code: startVerify.code ?? "HASH_MISMATCH",
+      message: `Start reference invalid: ${startVerify.message}`,
+      expected: startVerify.expected,
+      actual: startVerify.actual,
+      candidates: startVerify.candidates,
+      lineNumber: start.line,
+      hint: startVerify.candidates && startVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${startVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
   }
-  const endVerify = verifyHash(end.line, end.hash, normalized, hashLen, lines);
+  const effectiveStartLine = startVerify.relocatedLine ?? start.line;
+  const endVerify = verifyHash(end.line, end.hash, normalized, hashLen, lines, safeReapply);
   if (!endVerify.valid) {
-    throw new Error(`End reference invalid: ${endVerify.message}`);
+    throw new HashlineError({
+      code: endVerify.code ?? "HASH_MISMATCH",
+      message: `End reference invalid: ${endVerify.message}`,
+      expected: endVerify.expected,
+      actual: endVerify.actual,
+      candidates: endVerify.candidates,
+      lineNumber: end.line,
+      hint: endVerify.candidates && endVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${endVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
   }
-  const rangeLines = lines.slice(start.line - 1, end.line);
+  const effectiveEndLine = endVerify.relocatedLine ?? end.line;
+  if (effectiveStartLine > effectiveEndLine) {
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid effective range after relocation: start line ${effectiveStartLine} is after end line ${effectiveEndLine}`,
+      hint: "The referenced lines may have been reordered. Re-read the file to get fresh references."
+    });
+  }
+  const rangeLines = lines.slice(effectiveStartLine - 1, effectiveEndLine);
   return {
-    startLine: start.line,
-    endLine: end.line,
+    startLine: effectiveStartLine,
+    endLine: effectiveEndLine,
     lines: rangeLines,
     content: rangeLines.join(lineEnding)
   };
@@ -244,22 +360,37 @@ function replaceRange(startRef, endRef, content, replacement, hashLen) {
   const result = [...before, ...replacementLines, ...after].join("\n");
   return lineEnding === "\r\n" ? result.replace(/\n/g, "\r\n") : result;
 }
-function applyHashEdit(input, content, hashLen) {
+function applyHashEdit(input, content, hashLen, safeReapply) {
   const lineEnding = detectLineEnding(content);
   const workContent = lineEnding === "\r\n" ? content.replace(/\r\n/g, "\n") : content;
+  if (input.fileRev) {
+    verifyFileRev(input.fileRev, workContent);
+  }
   const normalizedStart = normalizeHashRef(input.startRef);
   const start = parseHashRef(normalizedStart);
   const lines = workContent.split("\n");
-  const startVerify = verifyHash(start.line, start.hash, workContent, hashLen, lines);
+  const startVerify = verifyHash(start.line, start.hash, workContent, hashLen, lines, safeReapply);
   if (!startVerify.valid) {
-    throw new Error(`Start reference invalid: ${startVerify.message}`);
+    throw new HashlineError({
+      code: startVerify.code ?? "HASH_MISMATCH",
+      message: `Start reference invalid: ${startVerify.message}`,
+      expected: startVerify.expected,
+      actual: startVerify.actual,
+      candidates: startVerify.candidates,
+      lineNumber: start.line,
+      hint: startVerify.candidates && startVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${startVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
   }
+  const effectiveStartLine = startVerify.relocatedLine ?? start.line;
   if (input.operation === "insert_before" || input.operation === "insert_after") {
     if (input.replacement === void 0) {
-      throw new Error(`Operation "${input.operation}" requires "replacement" content`);
+      throw new HashlineError({
+        code: "MISSING_REPLACEMENT",
+        message: `Operation "${input.operation}" requires "replacement" content`
+      });
     }
     const insertionLines = input.replacement.split("\n");
-    const insertIndex = input.operation === "insert_before" ? start.line - 1 : start.line;
+    const insertIndex = input.operation === "insert_before" ? effectiveStartLine - 1 : effectiveStartLine;
     const next2 = [
       ...lines.slice(0, insertIndex),
       ...insertionLines,
@@ -267,34 +398,54 @@ function applyHashEdit(input, content, hashLen) {
     ].join("\n");
     return {
       operation: input.operation,
-      startLine: start.line,
-      endLine: start.line,
+      startLine: effectiveStartLine,
+      endLine: effectiveStartLine,
       content: lineEnding === "\r\n" ? next2.replace(/\n/g, "\r\n") : next2
     };
   }
   const normalizedEnd = normalizeHashRef(input.endRef ?? input.startRef);
   const end = parseHashRef(normalizedEnd);
   if (start.line > end.line) {
-    throw new Error(
-      `Invalid range: start line ${start.line} is after end line ${end.line}`
-    );
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid range: start line ${start.line} is after end line ${end.line}`
+    });
   }
-  const endVerify = verifyHash(end.line, end.hash, workContent, hashLen, lines);
+  const endVerify = verifyHash(end.line, end.hash, workContent, hashLen, lines, safeReapply);
   if (!endVerify.valid) {
-    throw new Error(`End reference invalid: ${endVerify.message}`);
+    throw new HashlineError({
+      code: endVerify.code ?? "HASH_MISMATCH",
+      message: `End reference invalid: ${endVerify.message}`,
+      expected: endVerify.expected,
+      actual: endVerify.actual,
+      candidates: endVerify.candidates,
+      lineNumber: end.line,
+      hint: endVerify.candidates && endVerify.candidates.length > 0 ? `Content may have moved. Candidates: ${endVerify.candidates.map((c) => `line ${c.lineNumber}`).join(", ")}` : "Re-read the file to get fresh hash references."
+    });
+  }
+  const effectiveEndLine = endVerify.relocatedLine ?? end.line;
+  if (effectiveStartLine > effectiveEndLine) {
+    throw new HashlineError({
+      code: "INVALID_RANGE",
+      message: `Invalid effective range after relocation: start line ${effectiveStartLine} is after end line ${effectiveEndLine}`,
+      hint: "The referenced lines may have been reordered. Re-read the file to get fresh references."
+    });
   }
   const replacement = input.operation === "delete" ? "" : input.replacement;
   if (replacement === void 0) {
-    throw new Error(`Operation "${input.operation}" requires "replacement" content`);
+    throw new HashlineError({
+      code: "MISSING_REPLACEMENT",
+      message: `Operation "${input.operation}" requires "replacement" content`
+    });
   }
-  const before = lines.slice(0, start.line - 1);
-  const after = lines.slice(end.line);
+  const before = lines.slice(0, effectiveStartLine - 1);
+  const after = lines.slice(effectiveEndLine);
   const replacementLines = input.operation === "delete" ? [] : replacement.split("\n");
   const next = [...before, ...replacementLines, ...after].join("\n");
   return {
     operation: input.operation,
-    startLine: start.line,
-    endLine: end.line,
+    startLine: effectiveStartLine,
+    endLine: effectiveEndLine,
     content: lineEnding === "\r\n" ? next.replace(/\n/g, "\r\n") : next
   };
 }
@@ -330,7 +481,7 @@ function createHashline(config) {
         const cached = cache.get(filePath, content);
         if (cached) return cached;
       }
-      const result = formatFileWithHashes(content, hl, pfx);
+      const result = formatFileWithHashes(content, hl, pfx, resolved.fileRev);
       if (filePath) {
         cache.set(filePath, content, result);
       }
@@ -346,16 +497,16 @@ function createHashline(config) {
       return buildHashMap(content, hl);
     },
     verifyHash(lineNumber, hash, currentContent) {
-      return verifyHash(lineNumber, hash, currentContent, hl);
+      return verifyHash(lineNumber, hash, currentContent, hl, void 0, resolved.safeReapply);
     },
     resolveRange(startRef, endRef, content) {
-      return resolveRange(startRef, endRef, content, hl);
+      return resolveRange(startRef, endRef, content, hl, resolved.safeReapply);
     },
     replaceRange(startRef, endRef, content, replacement) {
       return replaceRange(startRef, endRef, content, replacement, hl);
     },
     applyHashEdit(input, content) {
-      return applyHashEdit(input, content, hl);
+      return applyHashEdit(input, content, hl, resolved.safeReapply);
     },
     normalizeHashRef(ref) {
       return normalizeHashRef(ref);
@@ -365,10 +516,22 @@ function createHashline(config) {
     },
     shouldExclude(filePath) {
       return shouldExclude(filePath, resolved.exclude);
+    },
+    computeFileRev(content) {
+      return computeFileRev(content);
+    },
+    verifyFileRev(expectedRev, currentContent) {
+      return verifyFileRev(expectedRev, currentContent);
+    },
+    extractFileRev(annotatedContent) {
+      return extractFileRev(annotatedContent, pfx);
+    },
+    findCandidateLines(originalLineNumber, expectedHash, lines, hashLen) {
+      return findCandidateLines(originalLineNumber, expectedHash, lines, hashLen);
     }
   };
 }
-var import_picomatch, DEFAULT_EXCLUDE_PATTERNS, DEFAULT_PREFIX, DEFAULT_CONFIG, modulusCache, stripRegexCache, HashlineCache, globMatcherCache, textEncoder;
+var import_picomatch, DEFAULT_EXCLUDE_PATTERNS, DEFAULT_PREFIX, DEFAULT_CONFIG, HashlineError, modulusCache, stripRegexCache, HashlineCache, globMatcherCache, textEncoder;
 var init_hashline = __esm({
   "src/hashline.ts"() {
     "use strict";
@@ -429,7 +592,53 @@ var init_hashline = __esm({
       // 0 = adaptive
       cacheSize: 100,
       prefix: DEFAULT_PREFIX,
-      debug: false
+      debug: false,
+      fileRev: true,
+      safeReapply: false
+    };
+    HashlineError = class extends Error {
+      code;
+      expected;
+      actual;
+      candidates;
+      hint;
+      lineNumber;
+      filePath;
+      constructor(opts) {
+        super(opts.message);
+        this.name = "HashlineError";
+        this.code = opts.code;
+        this.expected = opts.expected;
+        this.actual = opts.actual;
+        this.candidates = opts.candidates;
+        this.hint = opts.hint;
+        this.lineNumber = opts.lineNumber;
+        this.filePath = opts.filePath;
+      }
+      toDiagnostic() {
+        const parts = [`[${this.code}] ${this.message}`];
+        if (this.filePath) {
+          parts.push(`  File: ${this.filePath}`);
+        }
+        if (this.lineNumber !== void 0) {
+          parts.push(`  Line: ${this.lineNumber}`);
+        }
+        if (this.expected !== void 0 && this.actual !== void 0) {
+          parts.push(`  Expected hash: ${this.expected}`);
+          parts.push(`  Actual hash:   ${this.actual}`);
+        }
+        if (this.candidates && this.candidates.length > 0) {
+          parts.push(`  Candidates (${this.candidates.length}):`);
+          for (const c of this.candidates) {
+            const preview = c.content.length > 60 ? c.content.slice(0, 60) + "..." : c.content;
+            parts.push(`    - line ${c.lineNumber}: ${preview}`);
+          }
+        }
+        if (this.hint) {
+          parts.push(`  Hint: ${this.hint}`);
+        }
+        return parts.join("\n");
+      }
     };
     modulusCache = /* @__PURE__ */ new Map();
     stripRegexCache = /* @__PURE__ */ new Map();
@@ -508,6 +717,7 @@ module.exports = __toCommonJS(src_exports);
 var import_fs3 = require("fs");
 var import_path3 = require("path");
 var import_os2 = require("os");
+var import_crypto = require("crypto");
 var import_url = require("url");
 
 // src/hooks.ts
@@ -599,7 +809,7 @@ function createFileReadAfterHook(cache, config) {
         return;
       }
     }
-    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix);
+    const annotated = formatFileWithHashes(content, hashLen || void 0, prefix, resolved.fileRev);
     output.output = annotated;
     debug("annotated", typeof filePath === "string" ? filePath : input.tool, "lines:", content.split("\n").length);
     if (cache && typeof filePath === "string") {
@@ -711,10 +921,32 @@ function createSystemPromptHook(config) {
         '- Hash references include both the line number AND the content hash, so `2:f1c` means "line 2 with hash f1c".',
         "- If you see a mismatch, do NOT proceed with the edit \u2014 re-read the file to get fresh references.",
         "",
+        "### File revision (`#HL REV:<hash>`):",
+        "- When files are read, the first line may contain a file revision header: `" + prefix + "REV:<8-char-hex>`.",
+        "- This is a hash of the entire file content. Pass it as the `fileRev` parameter to `hashline_edit` to verify the file hasn't changed.",
+        "- If the file was modified between read and edit, the revision check fails with `FILE_REV_MISMATCH` \u2014 re-read the file.",
+        "",
+        "### Safe reapply (`safeReapply`):",
+        "- Pass `safeReapply: true` to `hashline_edit` to enable automatic line relocation.",
+        "- If a line moved (e.g., due to insertions above), safe reapply finds it by content hash.",
+        "- If exactly one match is found, the edit proceeds at the new location.",
+        "- If multiple matches exist, the edit fails with `AMBIGUOUS_REAPPLY` \u2014 re-read the file.",
+        "",
+        "### Structured error codes:",
+        "- `HASH_MISMATCH` \u2014 line content changed since last read",
+        "- `FILE_REV_MISMATCH` \u2014 file was modified since last read",
+        "- `AMBIGUOUS_REAPPLY` \u2014 multiple candidate lines found during safe reapply",
+        "- `TARGET_OUT_OF_RANGE` \u2014 line number exceeds file length",
+        "- `INVALID_REF` \u2014 malformed hash reference",
+        "- `INVALID_RANGE` \u2014 start line is after end line",
+        "- `MISSING_REPLACEMENT` \u2014 replace/insert operation without replacement content",
+        "",
         "### Best practices:",
         "- Use hash references for all edit operations to ensure precision.",
         "- When making multiple edits, work from bottom to top to avoid line number shifts.",
-        "- For large replacements, use range references (e.g., `1:a3f to 10:b2c`) instead of individual lines."
+        "- For large replacements, use range references (e.g., `1:a3f to 10:b2c`) instead of individual lines.",
+        "- Use `fileRev` to guard against stale edits on critical files.",
+        "- Use `safeReapply: true` when editing files that may have shifted due to earlier edits."
       ].join("\n")
     );
   };
@@ -736,10 +968,12 @@ function createHashlineEditTool(config, cache) {
       operation: import_zod.z.enum(["replace", "delete", "insert_before", "insert_after"]).describe("Edit operation"),
       startRef: import_zod.z.string().describe('Start hash reference, e.g. "5:a3f" or "#HL 5:a3f|const x = 1;"'),
       endRef: import_zod.z.string().optional().describe("End hash reference for range operations. Defaults to startRef when omitted."),
-      replacement: import_zod.z.string().max(1e7).optional().describe("Replacement/inserted content. Required for replace/insert operations.")
+      replacement: import_zod.z.string().max(1e7).optional().describe("Replacement/inserted content. Required for replace/insert operations."),
+      fileRev: import_zod.z.string().optional().describe("File revision hash (8-char hex from #HL REV:<hash>). When provided, verifies the file hasn't changed before editing."),
+      safeReapply: import_zod.z.boolean().optional().describe("Enable safe reapply: if a line moved, attempt to find it by content hash. Fails on ambiguous matches.")
     },
     async execute(args, context) {
-      const { path, operation, startRef, endRef, replacement } = args;
+      const { path, operation, startRef, endRef, replacement, fileRev, safeReapply } = args;
       const absPath = (0, import_path2.isAbsolute)(path) ? path : (0, import_path2.resolve)(context.directory, path);
       const realDirectory = (0, import_fs2.realpathSync)((0, import_path2.resolve)(context.directory));
       const realWorktree = (0, import_fs2.realpathSync)((0, import_path2.resolve)(context.worktree));
@@ -793,15 +1027,21 @@ function createHashlineEditTool(config, cache) {
             operation,
             startRef,
             endRef,
-            replacement
+            replacement,
+            fileRev
           },
           current,
-          config.hashLength || void 0
+          config.hashLength || void 0,
+          safeReapply ?? config.safeReapply
         );
         nextContent = result.content;
         startLine = result.startLine;
         endLine = result.endLine;
       } catch (error) {
+        if (error instanceof HashlineError) {
+          throw new Error(`Hashline edit failed for "${displayPath}":
+${error.toDiagnostic()}`);
+        }
         const reason = error instanceof Error ? error.message : String(error);
         throw new Error(`Hashline edit failed for "${displayPath}": ${reason}`);
       }
@@ -838,6 +1078,33 @@ function createHashlineEditTool(config, cache) {
 
 // src/index.ts
 var CONFIG_FILENAME = "opencode-hashline.json";
+var tempDirs = /* @__PURE__ */ new Set();
+var exitListenerRegistered = false;
+function registerTempDir(dir) {
+  tempDirs.add(dir);
+  if (!exitListenerRegistered) {
+    exitListenerRegistered = true;
+    process.on("exit", () => {
+      for (const d of tempDirs) {
+        try {
+          (0, import_fs3.rmSync)(d, { recursive: true, force: true });
+        } catch {
+        }
+      }
+    });
+  }
+}
+function writeTempFile(tempDir, content) {
+  const name = `hl-${(0, import_crypto.randomBytes)(16).toString("hex")}.txt`;
+  const tmpPath = (0, import_path3.join)(tempDir, name);
+  const fd = (0, import_fs3.openSync)(tmpPath, import_fs3.constants.O_WRONLY | import_fs3.constants.O_CREAT | import_fs3.constants.O_EXCL, 384);
+  try {
+    (0, import_fs3.writeFileSync)(fd, content, "utf-8");
+  } finally {
+    (0, import_fs3.closeSync)(fd);
+  }
+  return tmpPath;
+}
 function sanitizeConfig(raw) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {};
   const r = raw;
@@ -866,6 +1133,12 @@ function sanitizeConfig(raw) {
   if (typeof r.debug === "boolean") {
     result.debug = r.debug;
   }
+  if (typeof r.fileRev === "boolean") {
+    result.fileRev = r.fileRev;
+  }
+  if (typeof r.safeReapply === "boolean") {
+    result.safeReapply = r.safeReapply;
+  }
   return result;
 }
 function loadConfigFile(filePath) {
@@ -906,17 +1179,8 @@ function createHashlinePlugin(userConfig) {
       } catch {
       }
     }
-    const tempFiles = /* @__PURE__ */ new Set();
-    const cleanupTempFiles = () => {
-      for (const f of tempFiles) {
-        try {
-          (0, import_fs3.unlinkSync)(f);
-        } catch {
-        }
-      }
-      tempFiles.clear();
-    };
-    process.on("exit", cleanupTempFiles);
+    const instanceTmpDir = (0, import_fs3.mkdtempSync)((0, import_path3.join)((0, import_os2.tmpdir)(), "hashline-"));
+    registerTempDir(instanceTmpDir);
     return {
       tool: {
         hashline_edit: createHashlineEditTool(config, cache)
@@ -959,9 +1223,7 @@ function createHashlinePlugin(userConfig) {
             if (config.maxFileSize > 0 && getByteLength2(content) > config.maxFileSize) continue;
             const cached = cache.get(filePath, content);
             if (cached) {
-              const tmpPath2 = (0, import_path3.join)((0, import_os2.tmpdir)(), `hashline-${p.id}.txt`);
-              (0, import_fs3.writeFileSync)(tmpPath2, cached, "utf-8");
-              tempFiles.add(tmpPath2);
+              const tmpPath2 = writeTempFile(instanceTmpDir, cached);
               p.url = `file://${tmpPath2}`;
               if (config.debug) {
                 try {
@@ -972,10 +1234,9 @@ function createHashlinePlugin(userConfig) {
               }
               continue;
             }
-            const annotated = formatFileWithHashes2(content, hashLen || void 0, prefix);
+            const annotated = formatFileWithHashes2(content, hashLen || void 0, prefix, config.fileRev);
             cache.set(filePath, content, annotated);
-            const tmpPath = (0, import_path3.join)((0, import_os2.tmpdir)(), `hashline-${p.id}.txt`);
-            (0, import_fs3.writeFileSync)(tmpPath, annotated, "utf-8");
+            const tmpPath = writeTempFile(instanceTmpDir, annotated);
             p.url = `file://${tmpPath}`;
             if (config.debug) {
               try {