@oh-my-pi/hashline 15.13.0 → 15.13.1

package/CHANGELOG.md

@@ -2,79 +2,144 @@
 
 ## [Unreleased]
 
+## [15.13.1] - 2026-06-15
+
 ### Breaking Changes
 
-- Changed `BlockResolution.isDelete` to `BlockResolution.op` (`"replace" | "delete" | "insert_after"`) so resolutions can describe every block-anchored op
-- Changed hashline file section headers from `¶PATH#TAG` to `[PATH#TAG]` so model-authored edits use ASCII delimiters instead of a pilcrow sigil.
+- Rejected edits anchored to lines not displayed in the tagged read/search output, requiring unseen ranges to be re-read before reapplying
+
+### Changed
+
+- Rejected `replace block`, `delete block`, and `insert after block` operations that resolve to a single line and instructed users to use the plain single-line form or anchor the true construct opener
+
+### Fixed
+
+- Auto-repaired one-sided multi-line boundary echoes by dropping delimiter-neutral duplicated boundary lines and emitted a boundary-echo warning
+- Normalized cwd-relative hashline paths to forward-slash form on Windows.
+- Parser now treats a leading `\` on inline payload bodies as the payload delimiter, matching standalone payload rows.
+- Restored the warning emitted when escaped indented payload rows (`\\    TEXT`) are accepted as payload delimiters.
+
+## [15.12.5] - 2026-06-13
+
+### Fixed
+
+- Fixed delimiter-balance boundary repair so it does not keep a deleted structural closer when the replacement payload already restates that closer.
+
+## [15.12.0] - 2026-06-12
+
+### Changed
+
+- Condensed all parser/applier/patcher error and warning messages: shorter wording, same diagnostic anchors (op names, line numbers, suggested fallback forms)
+
+## [15.11.4] - 2026-06-12
 
 ### Added
 
 - Added inward landing correction for `insert after block N:`: a body indented deeper than the block's closing line now slides back across the block's trailing closer lines and lands inside the block at its claimed depth, with a warning naming the landing line. Same conservative guards as the outward shift — comparable indentation only, closers only, abandoned when another hunk targets a crossed line; plain `insert after M:` stays literal
 - Added closer-anchor lowering for `insert after block N:`: anchoring on a pure closing-delimiter line (where no block begins, so resolution previously failed the whole patch) now applies as plain `insert after N:` with a warning teaching the opener-only rule. `resolveBlockEdits` gained an `onWarning` callback; apply, preview, and patcher paths surface it on `warnings`
+
+### Changed
+
+- Condensed the edit-tool prompt: one-line op definitions, 5–20-word rules, and a tighter `<critical>` recap; landing-correction mechanics are no longer described to the agent
+
+## [15.11.1] - 2026-06-11
+
+### Fixed
+
+- Fixed the `insert after block N:` prompt guidance so it explicitly says N must be the block opener, not the closing delimiter or last visible line, and points visible closing-line edits to plain `insert after M:`. ([#2292](https://github.com/can1357/oh-my-pi/issues/2292))
+
+## [15.11.0] - 2026-06-10
+
+### Changed
+
+- Block-unresolved errors (`replace block N:` / `delete block N` / `insert after block N:` failing to resolve a syntactic block) now append a numbered preview of the file around the anchor line — same `*`-marked context rows the hash-mismatch error shows — so the offending line is visible without a re-read
+
+## [15.10.11] - 2026-06-10
+
+### Breaking Changes
+
+- Changed `BlockResolution.isDelete` to `BlockResolution.op` (`"replace" | "delete" | "insert_after"`) so resolutions can describe every block-anchored op
+
+### Added
+
 - Added `insert after block N:` patch syntax to insert body rows after the last line of the tree-sitter-resolved block beginning on line N, so a statement can be placed after a construct without counting to its closing line
 - Added depth-guided landing correction for `insert after N:` hunks: a body indented shallower than its anchor line slides past the structural closer lines below the anchor until depth returns to the body's level, with a warning naming the final landing line. The shift never crosses content lines, skips incomparable indentation styles and pure-closer bodies, and is abandoned when another hunk targets a crossed line
 - Added a global byte ceiling to `InMemorySnapshotStore` (`maxTotalBytes`, default 64 MiB): the cap was previously per-file only, so a session reading many large files retained up to 30 paths × 4 full-text versions indefinitely
-- Added `maxAddedRunContext` option to control how many added lines are shown at each side of collapsed inserted runs, with `maxUnchangedRun` kept as a backward-compatible alias
-- Added a `BlockResolution` type and surfaced resolved block spans on `ApplyResult.blockResolutions` / `PatchSectionResult.blockResolutions`. `resolveBlockEdits` now accepts an `onResolved` callback that reports each `replace block N:` / `delete block N` anchor's resolved `[start, end]` span (and whether it was a delete). Spans are surfaced only on the no-drift apply paths, where the resolved line numbers line up with the tag the caller read.
-- Added `replace block N:` and `delete block N` patch syntax to replace or delete the entire syntactic block that begins on line N using tree-sitter-resolved spans
-- Added `BlockResolver` support in `Patcher` and `PatchSection.applyTo`/`applyPartialTo` to wire language-specific block-resolution at apply time
-- Added `resolveBlockEdits` and block edit type definitions to the package API for resolving deferred `replace block` / `delete block` edits
 
 ### Changed
 
-- Condensed all parser/applier/patcher error and warning messages: shorter wording, same diagnostic anchors (op names, line numbers, suggested fallback forms)
-- Condensed the edit-tool prompt: one-line op definitions, 5–20-word rules, and a tighter `<critical>` recap; landing-correction mechanics are no longer described to the agent
-- Block-unresolved errors (`replace block N:` / `delete block N` / `insert after block N:` failing to resolve a syntactic block) now append a numbered preview of the file around the anchor line — same `*`-marked context rows the hash-mismatch error shows — so the offending line is visible without a re-read
 - Trimmed the `replace block N:` ops entry in the patch prompt to grammar and pointing rules; the usage doctrine it duplicated stays in the rules section
 - Changed `buildCompactDiffPreview` to treat blank rows as gap separators alongside `…` markers: separators never stack (removed lines omitted from the preview no longer leave two adjacent), and leading/trailing separators are trimmed
-- Changed `buildCompactDiffPreview` to omit removed lines from the preview while preserving removal counts for offset tracking
-- Changed `buildCompactDiffPreview` to collapse long contiguous added runs with a bare `…` marker, keeping only the first and last `maxAddedRunContext` lines visible (the surrounding line numbers convey how many were elided)
-- Reworked the `edit` tool prompt (`prompt.md`): added a `replace block N` vs `replace N..M` decision rule, documented that a leading decorator/attribute/doc-comment is a separate node not swept into the block (point N at the first decorator line, or use `replace N..M` for a Rust-style `///` sibling comment), reframed the blast-radius guidance so "block replace" no longer reads as the dangerous option, and added a decorated-definition example.
 
 ### Fixed
 
-- Normalized cwd-relative hashline paths to forward-slash form on Windows.
-- Fixed delimiter-balance boundary repair so it does not keep a deleted structural closer when the replacement payload already restates that closer.
-- Fixed the `insert after block N:` prompt guidance so it explicitly says N must be the block opener, not the closing delimiter or last visible line, and points visible closing-line edits to plain `insert after M:`. ([#2292](https://github.com/can1357/oh-my-pi/issues/2292))
 - Fixed the boundary-echo repair stripping payload edges without the balance-neutrality guard its own documentation promised: in brace-heavy code where bare `}` lines repeat, a payload intentionally beginning/ending with lines identical to the range's neighbors had both edges silently dropped, writing content that differed from what was authored
 - Fixed lenient bare-body handling silently mutating payloads: interior blank rows in an un-prefixed body were dropped outright, and a body of numeric-keyed literals (`1: "one"` dict/YAML shapes) satisfied the uniform line-prefix check and had its keys stripped from every line — blank rows are now preserved when proven interior, and the uniform strip refuses lone-literal remainders
 - Fixed the multi-section "all-or-nothing" claim being false for write failures: commits run serially, so a mid-batch write error left earlier sections on disk while the thrown error said nothing — the error now lists exactly which sections were written and which were not
 - Fixed `delete`/`replace` ranges ending on the phantom trailing line of a newline-terminated file silently stripping the file's final newline; such anchors are now rejected with guidance toward `N-1` / `insert tail:` (inserts there remain valid, and genuine empty last lines of unterminated files stay deletable)
-- Fixed compact edit previews to omit deleted content, keep visible lines anchored to the current file, and collapse long inserted runs with a bare `…` elision marker.
-- Fixed compact edit previews to render added/current lines without diff-prefix padding and normalize adjacent ASCII/Unicode elision markers to one `…`.
-- Stripped read-output line-number prefixes (`N:`) from auto-piped bare body rows so that pasting `3:text` without a `+` prefix no longer injects `3:` as literal content. Stripping is applied only when *every* bare row in the hunk carries the prefix (the signature of a pasted snapshot) and removes at most one prefix per row, so a genuine body that merely starts with `digits:` (YAML port maps, timestamps) is left intact ([#1492](https://github.com/can1357/oh-my-pi/issues/1492)).
-- Fixed missing-header diagnostics and copied-content prefix stripping to consistently teach and recognize 4-hex snapshot tags.
-- Fixed delimiter-balance boundary repair to also drop a single duplicated structural opener (e.g. a restated `foo(` / `if (x) {` signature line surviving just above the range), not only duplicated closers. Zero-balance duplicates remain untouched.
-- Fixed hashline replacements that accidentally restated unchanged lines above and below the selected range so they no longer duplicate both boundary lines ([#1664](https://github.com/can1357/oh-my-pi/issues/1664)).
-
-## [15.13.0] - 2026-06-14
 
-## [15.12.5] - 2026-06-13
+## [15.10.5] - 2026-06-08
 
-## [15.12.0] - 2026-06-12
+### Added
 
-## [15.11.4] - 2026-06-12
+- Added `maxAddedRunContext` option to control how many added lines are shown at each side of collapsed inserted runs, with `maxUnchangedRun` kept as a backward-compatible alias
 
-## [15.11.1] - 2026-06-11
+### Changed
 
-## [15.11.0] - 2026-06-10
+- Changed `buildCompactDiffPreview` to omit removed lines from the preview while preserving removal counts for offset tracking
+- Changed `buildCompactDiffPreview` to collapse long contiguous added runs with a bare `…` marker, keeping only the first and last `maxAddedRunContext` lines visible (the surrounding line numbers convey how many were elided)
 
-## [15.10.11] - 2026-06-10
+### Fixed
 
-## [15.10.5] - 2026-06-08
+- Fixed compact edit previews to omit deleted content, keep visible lines anchored to the current file, and collapse long inserted runs with a bare `…` elision marker.
+- Fixed compact edit previews to render added/current lines without diff-prefix padding and normalize adjacent ASCII/Unicode elision markers to one `…`.
 
 ## [15.10.3] - 2026-06-08
 
+### Added
+
+- Added a `BlockResolution` type and surfaced resolved block spans on `ApplyResult.blockResolutions` / `PatchSectionResult.blockResolutions`. `resolveBlockEdits` now accepts an `onResolved` callback that reports each `replace block N:` / `delete block N` anchor's resolved `[start, end]` span (and whether it was a delete). Spans are surfaced only on the no-drift apply paths, where the resolved line numbers line up with the tag the caller read.
+
+### Changed
+
+- Reworked the `edit` tool prompt (`prompt.md`): added a `replace block N` vs `replace N..M` decision rule, documented that a leading decorator/attribute/doc-comment is a separate node not swept into the block (point N at the first decorator line, or use `replace N..M` for a Rust-style `///` sibling comment), reframed the blast-radius guidance so "block replace" no longer reads as the dangerous option, and added a decorated-definition example.
+
 ## [15.10.2] - 2026-06-08
 
+### Fixed
+
+- Stripped read-output line-number prefixes (`N:`) from auto-piped bare body rows so that pasting `3:text` without a `+` prefix no longer injects `3:` as literal content. Stripping is applied only when *every* bare row in the hunk carries the prefix (the signature of a pasted snapshot) and removes at most one prefix per row, so a genuine body that merely starts with `digits:` (YAML port maps, timestamps) is left intact ([#1492](https://github.com/can1357/oh-my-pi/issues/1492)).
+
 ## [15.9.67] - 2026-06-06
 
+### Breaking Changes
+
+- Changed hashline file section headers from `¶PATH#TAG` to `[PATH#TAG]` so model-authored edits use ASCII delimiters instead of a pilcrow sigil.
+
+### Fixed
+
+- Fixed missing-header diagnostics and copied-content prefix stripping to consistently teach and recognize 4-hex snapshot tags.
+
 ## [15.8.2] - 2026-06-03
 
+### Fixed
+
+- Fixed delimiter-balance boundary repair to also drop a single duplicated structural opener (e.g. a restated `foo(` / `if (x) {` signature line surviving just above the range), not only duplicated closers. Zero-balance duplicates remain untouched.
+
 ## [15.8.0] - 2026-06-02
 
+### Fixed
+
+- Fixed hashline replacements that accidentally restated unchanged lines above and below the selected range so they no longer duplicate both boundary lines ([#1664](https://github.com/can1357/oh-my-pi/issues/1664)).
+
 ## [15.7.0] - 2026-05-31
 
+### Added
+
+- Added `replace block N:` and `delete block N` patch syntax to replace or delete the entire syntactic block that begins on line N using tree-sitter-resolved spans
+- Added `BlockResolver` support in `Patcher` and `PatchSection.applyTo`/`applyPartialTo` to wire language-specific block-resolution at apply time
+- Added `resolveBlockEdits` and block edit type definitions to the package API for resolving deferred `replace block` / `delete block` edits
+
 ## [15.5.13] - 2026-05-29
 
 ### Breaking Changes
@@ -85,7 +150,7 @@
 ### Added
 
 - Added `maxPaths` and `maxVersionsPerPath` options to `InMemorySnapshotStore` to bound tracked paths and per-path snapshot history
-- Re-introduced balance-validated boundary repair in `applyEdits`. A replacement hunk (`replace N..M:` + body) is normalized so its payload preserves the deleted region's delimiter balance: when the body restates a closing delimiter that survives just outside the range (duplicate `}` / `);` / `]`) the echo is dropped, and when the range deletes a structural closer the body never restates (missing closer) the closer is spared instead of deleted. A repair fires only when one boundary operation drives the per-channel `()` / `[]` / `{}` imbalance to exactly zero while leaving surrounding text byte-identical (single-line ops are limited to pure structural-closer lines), so balance-preserving edits and intentional balanced duplicates are never touched. Bracket couples are also bounded by line count: structural balance delta repair is capped to 10 duplicate lines across all channels combined, massive balanced blocks are skipped.
+- Re-introduced balance-validated boundary repair in `applyEdits`. A replacement hunk (`replace N..M:` + body) is normalized so its payload preserves the deleted region's delimiter balance: when the body restates a closing delimiter that survives just outside the range (duplicate `}` / `);` / `]`) the echo is dropped, and when the range deletes a structural closer the body never restates (missing closer) the closer is spared instead of deleted. A repair fires only when one boundary operation drives the per-channel `()` / `[]` / `{}` imbalance to exactly zero while leaving surrounding text byte-identical (single-line ops are limited to pure structural-closer lines), so balance-preserving edits and intentional balanced duplicates are never touched. Bracket counting skips strings, template literals, and comments. Each repair surfaces a `delimiter-balance` warning through `ApplyResult.warnings`.
 
 ### Changed
 
@@ -153,7 +218,7 @@
 
 ### Breaking Changes
 
-- Redesigned hashline syntax around range anchors (`A-B:`, `A:`, `BOF:`, `EOF:`) and per-line payload sigils (`|`, `↑`, `↓`). Old op-line insert syntax and `\` payload continuations are no longer supported.
+- Changed hashline payload continuations from `+TEXT` to `\TEXT`; use `\` for an explicit blank payload line.
 
 ### Added
 
@@ -166,7 +231,7 @@
 
 ### Removed
 
-- Removed legacy deletion semantics that treated bare `A-B:` as a blank-line replacement; a bare range anchor now deletes the range.
+- Removed the `A-B!` / `A!` deletion operator. Use `A-B:` with the desired payload (or empty payload to blank the range) instead.
 
 All notable changes to this package will be documented in this file.
 

package/dist/types/messages.d.ts

@@ -96,3 +96,20 @@ export declare const HEADTAIL_DRIFT_WARNING = "Applied the `insert head:`/`inser
  * ({@link Patcher.prepare}) and preview/diff paths so both stay in lockstep.
  */
 export declare function missingSnapshotTagMessage(sectionPath: string): string;
+/**
+ * An anchored edit referenced lines the read that minted the cited tag never
+ * displayed (a partial range, or a structural summary that collapsed bodies).
+ * Editing lines you have not read is the off-by-memory failure that mangles
+ * files; reject and make the model re-read those exact lines first.
+ */
+export declare function unseenLinesMessage(sectionPath: string, unseenLines: readonly number[], tag: string): string;
+/** Op kind of a deferred block edit, for {@link blockSingleLineMessage}. */
+export type BlockOp = "replace" | "delete" | "insert_after";
+/**
+ * A `replace block`/`delete block`/`insert after block` anchor resolved to a
+ * single line — almost always a bare statement the model mis-anchored, not a
+ * multi-line construct. The plain op is unambiguous for one line; the block
+ * form only earns its keep when it spares counting a closing line you cannot
+ * see. Reject and point at both fixes.
+ */
+export declare function blockSingleLineMessage(line: number, op: BlockOp): string;

package/dist/types/snapshots.d.ts

@@ -11,6 +11,15 @@ export interface Snapshot {
     readonly hash: string;
     /** Timestamp (ms since epoch) the version was recorded. */
     recordedAt: number;
+    /**
+     * 1-indexed file lines a producer (read/search) actually *displayed* under
+     * this tag. A partial read (range, or a structural summary that collapsed
+     * bodies) leaves this sparse; a whole-file read fills every line. Multiple
+     * reads of the same content union into one set. `undefined` means "no
+     * provenance recorded" — the patcher then skips the seen-line check and
+     * applies as before. Mutated in place as more of the same content is read.
+     */
+    seenLines?: Set<number>;
 }
 /**
  * Storage seam for full-file version snapshots. The patcher calls {@link head}
@@ -22,8 +31,19 @@ export declare abstract class SnapshotStore {
     abstract head(path: string): Snapshot | null;
     /** Recorded version for `path` whose tag equals `hash`, or `null`. */
     abstract byHash(path: string, hash: string): Snapshot | null;
-    /** Record the full normalized text of `path` and return its content tag. */
-    abstract record(path: string, fullText: string): string;
+    /**
+     * Record the full normalized text of `path` and return its content tag.
+     * `seenLines` (optional) are the 1-indexed lines the producer displayed;
+     * they merge into {@link Snapshot.seenLines} across reads of identical text.
+     */
+    abstract record(path: string, fullText: string, seenLines?: Iterable<number>): string;
+    /**
+     * Merge `lines` into the {@link Snapshot.seenLines} of the version whose tag
+     * equals `hash`. No-op when no such version is retained (the content aged
+     * out or was overwritten). Lets producers attach displayed lines after the
+     * tag was already minted (the body is formatted after the hash is computed).
+     */
+    abstract recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
     /** Drop the version history for a single path. */
     abstract invalidate(path: string): void;
     /** Drop every version history. */
@@ -55,7 +75,8 @@ export declare class InMemorySnapshotStore extends SnapshotStore {
     constructor(options?: InMemorySnapshotStoreOptions);
     head(path: string): Snapshot | null;
     byHash(path: string, hash: string): Snapshot | null;
-    record(path: string, fullText: string): string;
+    record(path: string, fullText: string, seenLines?: Iterable<number>): string;
+    recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
     invalidate(path: string): void;
     clear(): void;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/hashline",
-	"version": "15.13.0",
+	"version": "15.13.1",
 	"description": "Hashline: a compact, line-anchored patch language and applier. Pluggable FS/IO so it works over disk, in-memory, or any custom backend.",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",

package/src/apply.ts

@@ -443,6 +443,50 @@ function describeBoundaryRepair(group: ReplacementGroup, action: string): string
 	);
 }
 
+/**
+ * A single-sided boundary echo in an otherwise delimiter-balanced *multi-line*
+ * replacement: the payload's leading XOR trailing edge exactly restates the
+ * surviving line(s) just outside the range — the off-by-one "range one line
+ * short of the keeper I retyped" mistake (e.g. att: payload ends with
+ * `const x = [];` and line B+1 is the same `const x = [];`). Two-sided echoes
+ * are handled by {@link findBoundaryEcho}; delimiter-imbalanced one-sided echoes
+ * by {@link findDuplicateSuffix}/{@link findDuplicatePrefix}.
+ *
+ * Scoped to multi-line ranges (a construct rewrite) on purpose: a single-line
+ * `replace N..N` expanding into several lines is an *expansion* where every
+ * payload line is intentional new content, so a payload line that happens to
+ * equal a neighbor stays — only a genuine block rewrite retypes a boundary
+ * keeper by mistake. The dropped lines must be delimiter-neutral so removing the
+ * duplicate keeps the already-balanced result balanced, and must not consume the
+ * whole payload.
+ */
+function findOneSidedBoundaryEcho(
+	group: ReplacementGroup,
+	fileLines: readonly string[],
+): { side: "leading" | "trailing"; count: number } | undefined {
+	if (group.deleteIndices.length <= 1) return undefined;
+	const leading = countDuplicateLeadingBoundaryLines(group, fileLines);
+	const trailing = countDuplicateTrailingBoundaryLines(group, fileLines);
+	if (leading > 0 === trailing > 0) return undefined;
+	const side = leading > 0 ? "leading" : "trailing";
+	const count = leading > 0 ? leading : trailing;
+	if (count >= group.payload.length) return undefined;
+	const echoLines =
+		side === "leading" ? group.payload.slice(0, count) : group.payload.slice(group.payload.length - count);
+	if (!balanceIsZero(computeDelimiterBalance(echoLines))) return undefined;
+	return { side, count };
+}
+
+function describeOneSidedEchoRepair(group: ReplacementGroup, side: "leading" | "trailing", count: number): string {
+	const where = side === "leading" ? "above" : "below";
+	return (
+		`Auto-repaired a replacement boundary echo at line ${group.startLine}: ` +
+		`dropped ${count} ${side} payload line(s) identical to the surviving line(s) just ${where} the range. ` +
+		`The range was one line short of the content you retyped — issue the payload as the final content for the ` +
+		`selected range only, and widen the range to consume any keeper you restate.`
+	);
+}
+
 /**
  * Normalize replacement groups so common off-by-one boundaries do not duplicate
  * unchanged surrounding lines or structural closers. Returns the repaired edit
@@ -481,6 +525,16 @@ function repairReplacementBoundaries(
 			computeDelimiterBalance(fileLines.slice(group.startLine - 1, group.endLine)),
 		);
 		if (balanceIsZero(delta)) {
+			const oneSided = findOneSidedBoundaryEcho(group, fileLines);
+			if (oneSided) {
+				warnings.push(describeOneSidedEchoRepair(group, oneSided.side, oneSided.count));
+				const trimmed =
+					oneSided.side === "leading"
+						? inserts.slice(oneSided.count)
+						: inserts.slice(0, inserts.length - oneSided.count);
+				out.push(...trimmed, ...deletes);
+				continue;
+			}
 			out.push(...inserts, ...deletes);
 			continue;
 		}

package/src/block.ts

@@ -15,6 +15,7 @@
 import { STRUCTURAL_CLOSER_RE } from "./apply";
 import {
 	BLOCK_RESOLVER_UNAVAILABLE,
+	blockSingleLineMessage,
 	blockUnresolvedMessage,
 	insertAfterBlockCloserLoweredWarning,
 	insertAfterBlockUnresolvedLoweredWarning,
@@ -110,6 +111,15 @@ export function resolveBlockEdits(
 				}`,
 			);
 		}
+		if (span.start === span.end) {
+			// A single-line block resolution means line N is a bare statement, not
+			// the opening line of a multi-line construct — the common mis-anchor
+			// that lands a body in the wrong scope (e.g. between a `case` body line
+			// and its `break;`). The plain op is exact for one line, so reject and
+			// point at it; drop instead on the lenient preview path.
+			if (onUnresolved === "drop") continue;
+			throw new Error(`line ${edit.lineNum}: ${blockSingleLineMessage(edit.anchor.line, op)}`);
+		}
 		options.onResolved?.({
 			anchorLine: edit.anchor.line,
 			start: span.start,

package/src/messages.ts

@@ -179,3 +179,64 @@ export const HEADTAIL_DRIFT_WARNING =
 export function missingSnapshotTagMessage(sectionPath: string): string {
 	return `Missing hashline snapshot tag for ${sectionPath}; use \`${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}tag${HL_FILE_SUFFIX}\` from your latest read/search output. To create a new file, use the write tool.`;
 }
+
+/** Compress a line list into a sorted `1-4, 7, 10-12` range string. */
+function formatLineRanges(lines: readonly number[]): string {
+	const sorted = [...new Set(lines)].sort((a, b) => a - b);
+	if (sorted.length === 0) return "";
+	const parts: string[] = [];
+	let start = sorted[0];
+	let prev = sorted[0];
+	for (let i = 1; i <= sorted.length; i++) {
+		const current = sorted[i];
+		if (current === prev + 1) {
+			prev = current;
+			continue;
+		}
+		parts.push(start === prev ? `${start}` : `${start}-${prev}`);
+		start = current;
+		prev = current;
+	}
+	return parts.join(", ");
+}
+
+/**
+ * An anchored edit referenced lines the read that minted the cited tag never
+ * displayed (a partial range, or a structural summary that collapsed bodies).
+ * Editing lines you have not read is the off-by-memory failure that mangles
+ * files; reject and make the model re-read those exact lines first.
+ */
+export function unseenLinesMessage(sectionPath: string, unseenLines: readonly number[], tag: string): string {
+	return (
+		`This edit targets line(s) ${formatLineRanges(unseenLines)} of ${sectionPath} that were not shown in the ` +
+		`read/search output for ${HL_FILE_PREFIX}${sectionPath}${HL_FILE_HASH_SEP}${tag}${HL_FILE_SUFFIX} — a partial ` +
+		`range, a search hit, or a structural summary that collapsed bodies was displayed, not those exact lines. ` +
+		`Re-read those lines, then re-issue the edit against the fresh tag. NEVER author hunks against line numbers ` +
+		`you have not seen in the current snapshot.`
+	);
+}
+
+/** Op kind of a deferred block edit, for {@link blockSingleLineMessage}. */
+export type BlockOp = "replace" | "delete" | "insert_after";
+
+/**
+ * A `replace block`/`delete block`/`insert after block` anchor resolved to a
+ * single line — almost always a bare statement the model mis-anchored, not a
+ * multi-line construct. The plain op is unambiguous for one line; the block
+ * form only earns its keep when it spares counting a closing line you cannot
+ * see. Reject and point at both fixes.
+ */
+export function blockSingleLineMessage(line: number, op: BlockOp): string {
+	const blockForm = op === "insert_after" ? "insert after block" : op === "delete" ? "delete block" : "replace block";
+	const plainForm =
+		op === "insert_after"
+			? `insert after ${line}:`
+			: op === "delete"
+				? `delete ${line}`
+				: `replace ${line}..${line}:`;
+	return (
+		`\`${blockForm} ${line}\` resolved a single-line block — line ${line} is a bare statement, not the opening line ` +
+		`of a multi-line construct. For that one line use \`${plainForm}\`; to act on an enclosing construct, anchor ${blockForm} ` +
+		`on the line that OPENS it (e.g. its \`function\`/\`if\`/\`case\` header), never a statement inside it.`
+	);
+}

package/src/patcher.ts

@@ -28,7 +28,7 @@ import { computeFileHash, formatHashlineHeader } from "./format";
 import type { Filesystem, WriteResult } from "./fs";
 import { isNotFound } from "./fs";
 import type { Patch, PatchSection } from "./input";
-import { HEADTAIL_DRIFT_WARNING, missingSnapshotTagMessage } from "./messages";
+import { HEADTAIL_DRIFT_WARNING, missingSnapshotTagMessage, unseenLinesMessage } from "./messages";
 import { MismatchError } from "./mismatch";
 import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { Recovery, type RecoveryResult } from "./recovery";
@@ -341,6 +341,22 @@ export class Patcher {
 	#recordFullSnapshot(canonicalPath: string, normalized: string): string {
 		return this.snapshots.record(canonicalPath, normalized);
 	}
+
+	/**
+	 * Reject an anchored edit that references a line the read which minted
+	 * `expected` never displayed. The snapshot's `seenLines` is the set of
+	 * 1-indexed lines a producer (read/search) actually showed under that tag;
+	 * absent or empty means no provenance was recorded, so the edit applies as
+	 * before. Only runs on the no-drift path, where anchor line numbers index
+	 * the tagged content 1:1.
+	 */
+	#assertSeenLines(section: PatchSection, canonicalPath: string, expected: string): void {
+		const seen = this.snapshots.byHash(canonicalPath, expected)?.seenLines;
+		if (!seen || seen.size === 0) return;
+		const unseen = section.collectAnchorLines().filter(line => !seen.has(line));
+		if (unseen.length === 0) return;
+		throw new Error(unseenLinesMessage(section.path, unseen, expected));
+	}
 	#mismatchError(
 		section: PatchSection,
 		canonicalPath: string,
@@ -404,6 +420,10 @@ export class Patcher {
 		// the caller read, so echo them back. (A drifted file falls through to
 		// recovery below, where line numbers shift, so resolutions are dropped.)
 		if (expected === undefined || liveMatches) {
+			// The line numbers in `edits` index the exact content the tag names.
+			// Reject any anchor the read never displayed: editing lines the model
+			// has not seen is the off-by-memory mistake that mangles files.
+			if (expected !== undefined) this.#assertSeenLines(section, canonicalPath, expected);
 			const result = applyEdits(normalized, resolved);
 			return withResolveWarnings(blockResolutions.length > 0 ? { ...result, blockResolutions } : result);
 		}

package/src/prompt.md

@@ -27,8 +27,8 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 - Line numbers and the `[PATH#TAG]` header come from your latest `read`/`search` (`LINE:TEXT` rows).
 - Numbers refer to the ORIGINAL file; they do not shift as hunks apply.
 - They die with the call: every applied edit mints a fresh `#TAG` and renumbers — anchor the next edit on the edit response or a fresh `read`.
-- Touch only lines you literally saw as `LINE:TEXT`; the tag certifies the snapshot, not your knowledge of it.
-- Elided regions (`…`) are UNSEEN — never place or span a hunk across one; `read` it first.
+- Touch only lines your latest `read`/`search` literally displayed as `LINE:TEXT`; the tag certifies the snapshot, not your memory of it. A hunk anchored on a line you never displayed is REJECTED — re-`read` those exact lines first. (Seeing a line ≠ it holding the code you mean: confirm the numbers map to the construct you intend, especially far from your last-read window.)
+- Elided regions are UNSEEN: `…`/`..` markers and a collapsed `N-M:` summary row (only boundary lines N and M were shown) hide their interior. NEVER place or span a hunk inside one — `read` the range first.
 - Never start or end a range mid-expression or mid-block.
 - Indent body rows exactly for the depth they should live at.
 - On a stale-tag rejection or any surprising result: STOP and re-`read` before further edits.
@@ -36,9 +36,9 @@ There is NO other body row kind. NEVER write `-old` or a bare/context line. To k
 - Ranges cover ONLY lines whose content changes. Never widen over unchanged lines — a stale wide range shreds everything it spans.
 - Whole construct → `replace block N` (tree-sitter resolves the end); lines inside it → `replace N..M`.
 - `replace block N` resolves EXACTLY the node at N. Leading decorators/attributes/doc-comments are separate nodes: point N at the FIRST decorator to sweep both; standalone line-comments are never swept — use `replace N..M`.
-- `insert after block N`: N is the opener, never the closer or last visible line; saw the closer? Use plain `insert after M:`.
+- Block ops (`replace block`/`delete block`/`insert after block`) anchor the OPENING line of a MULTI-LINE construct — never its closer, its last line, or a bare statement inside it. Anchoring a single statement resolves to ONE line and is REJECTED: use the plain op (`replace N..N` / `delete N` / `insert after N`) for one line, or point N at the real opener. Saw the closer? Use plain `insert after M:`.
 - Non-adjacent changes = separate hunks; untouched lines stay out of every range.
-- Pure additions use `insert`, never a widened `replace` — retyped keepers are exactly what gets dropped.
+- Pure additions use `insert`, never a widened `replace` — retyped keepers are exactly what gets dropped. A multi-line `replace` whose body restates the line just outside the range is auto-dropped as an off-by-one keeper (with a warning), but issue the payload as the final content for the range only and never lean on the repair.
 - NEVER format/restyle code with this tool; run the project formatter instead.
 </rules>
 

package/src/snapshots.ts

@@ -36,6 +36,15 @@ export interface Snapshot {
 	readonly hash: string;
 	/** Timestamp (ms since epoch) the version was recorded. */
 	recordedAt: number;
+	/**
+	 * 1-indexed file lines a producer (read/search) actually *displayed* under
+	 * this tag. A partial read (range, or a structural summary that collapsed
+	 * bodies) leaves this sparse; a whole-file read fills every line. Multiple
+	 * reads of the same content union into one set. `undefined` means "no
+	 * provenance recorded" — the patcher then skips the seen-line check and
+	 * applies as before. Mutated in place as more of the same content is read.
+	 */
+	seenLines?: Set<number>;
 }
 
 /**
@@ -50,8 +59,20 @@ export abstract class SnapshotStore {
 	/** Recorded version for `path` whose tag equals `hash`, or `null`. */
 	abstract byHash(path: string, hash: string): Snapshot | null;
 
-	/** Record the full normalized text of `path` and return its content tag. */
-	abstract record(path: string, fullText: string): string;
+	/**
+	 * Record the full normalized text of `path` and return its content tag.
+	 * `seenLines` (optional) are the 1-indexed lines the producer displayed;
+	 * they merge into {@link Snapshot.seenLines} across reads of identical text.
+	 */
+	abstract record(path: string, fullText: string, seenLines?: Iterable<number>): string;
+
+	/**
+	 * Merge `lines` into the {@link Snapshot.seenLines} of the version whose tag
+	 * equals `hash`. No-op when no such version is retained (the content aged
+	 * out or was overwritten). Lets producers attach displayed lines after the
+	 * tag was already minted (the body is formatted after the hash is computed).
+	 */
+	abstract recordSeenLines(path: string, hash: string, lines: Iterable<number>): void;
 
 	/** Drop the version history for a single path. */
 	abstract invalidate(path: string): void;
@@ -65,6 +86,13 @@ const DEFAULT_MAX_VERSIONS_PER_PATH = 4;
 /** Global ceiling on retained snapshot text across all paths (UTF-16 code units). */
 const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 
+/** Union `lines` into `snapshot.seenLines`, lazily creating the set. */
+function mergeSeenLines(snapshot: Snapshot, lines: Iterable<number> | undefined): void {
+	if (lines === undefined) return;
+	if (snapshot.seenLines === undefined) snapshot.seenLines = new Set<number>();
+	for (const line of lines) snapshot.seenLines.add(line);
+}
+
 export interface InMemorySnapshotStoreOptions {
 	/** Maximum number of distinct paths tracked at once (default 30). LRU eviction. */
 	maxPaths?: number;
@@ -114,15 +142,17 @@ export class InMemorySnapshotStore extends SnapshotStore {
 		return history?.find(version => version.hash === hash) ?? null;
 	}
 
-	record(path: string, fullText: string): string {
+	record(path: string, fullText: string, seenLines?: Iterable<number>): string {
 		const hash = computeFileHash(fullText);
 		// `get` refreshes LRU recency for `path`.
 		const history = this.#versions.get(path) ?? [];
 		const existing = history.find(version => version.hash === hash);
 		if (existing) {
 			// Same content state observed again: refresh recency and promote to
-			// head (it is the current file content), then reuse the tag.
+			// head (it is the current file content), then reuse the tag. Union any
+			// newly-displayed lines so re-reading more of the file widens coverage.
 			existing.recordedAt = Date.now();
+			mergeSeenLines(existing, seenLines);
 			if (history[0] !== existing) {
 				this.#versions.set(path, [existing, ...history.filter(version => version !== existing)]);
 			}
@@ -130,10 +160,16 @@ export class InMemorySnapshotStore extends SnapshotStore {
 		}
 
 		const snapshot: Snapshot = { path, text: fullText, hash, recordedAt: Date.now() };
+		mergeSeenLines(snapshot, seenLines);
 		this.#versions.set(path, [snapshot, ...history].slice(0, this.#maxVersionsPerPath));
 		return hash;
 	}
 
+	recordSeenLines(path: string, hash: string, lines: Iterable<number>): void {
+		const version = this.#versions.get(path)?.find(snapshot => snapshot.hash === hash);
+		if (version) mergeSeenLines(version, lines);
+	}
+
 	invalidate(path: string): void {
 		this.#versions.delete(path);
 	}