@oh-my-pi/hashline 17.1.7 → 17.2.0

package/src/patcher.ts

@@ -25,6 +25,7 @@
 import * as path from "node:path";
 import { applyEdits } from "./apply";
 import { hasBlockEdit, resolveBlockEdits } from "./block";
+import { commitClipboard, forkClipboard, validateClipboardSequence } from "./clipboard";
 import { computeFileHash, formatHashlineHeader } from "./format";
 import type { Filesystem, WriteResult } from "./fs";
 import { isNotFound } from "./fs";
@@ -35,13 +36,14 @@ import {
 	pathRecoveredFromTagMessage,
 	type RevealedLine,
 	unseenLinesMessage,
+	writeDriftWarning,
 } from "./messages";
 import { MismatchError } from "./mismatch";
 import { detectLineEnding, type LineEnding, normalizeToLF, restoreLineEndings, stripBom } from "./normalize";
 import { InvalidAbsoluteRangeError } from "./parser";
 import { Recovery, type RecoveryResult } from "./recovery";
 import type { Snapshot, SnapshotStore } from "./snapshots";
-import type { ApplyResult, BlockResolution, BlockResolver, BlockSpan, Edit, FileOp } from "./types";
+import type { ApplyResult, BlockResolution, BlockResolver, BlockSpan, Clipboard, Edit, FileOp } from "./types";
 
 /**
  * Upper bound on the number of unseen anchor lines whose actual file content
@@ -80,6 +82,12 @@ export interface PatcherOptions {
 	 * validate on content hash alone and any anchor into the tagged content applies.
 	 */
 	enforceSeenLines?: boolean;
+	/**
+	 * Host-owned clipboard register shared across batches, so `CUT` content
+	 * can be `PASTE`d by a later {@link Patcher.apply} call. Each batch works
+	 * on a fork and publishes it back only after writes land.
+	 */
+	clipboard?: Clipboard;
 }
 
 /** Per-section result returned by {@link Patcher.apply} / {@link Patcher.commit}. */
@@ -98,7 +106,13 @@ export interface PatchSectionResult {
 	persisted: string;
 	/** Final text that the {@link Filesystem} actually wrote (may differ if the FS transformed it). */
 	written: string;
-	/** 4-hex content-hash tag for `after`. Use to anchor follow-up edits. */
+	/**
+	 * 4-hex content-hash tag. Hashes the content the {@link Filesystem}
+	 * reports actually landed on disk (see `written`), which normally equals
+	 * `after` but can diverge when the write path transforms content (e.g. an
+	 * ACP-bridge write reformatted by the client's format-on-save). Use to
+	 * anchor follow-up edits.
+	 */
 	fileHash: string;
 	/** Hashline section header (`[path#tag]`) of the post-edit content. */
 	header: string;
@@ -109,9 +123,8 @@ export interface PatchSectionResult {
 	/** Destination path when this section includes `MV DEST`. */
 	moveDest?: string;
 	/**
-	 * Resolved spans for any `replace_block`/`delete_block` ops, present when the
-	 * apply matched the tagged content. Undefined for patches with no block ops
-	 * (and for resolutions routed through drift recovery, where numbers shift).
+	 * Resolved spans for block ops, present when the apply matched the tagged
+	 * content. Undefined for patches with no block ops and for drift recovery.
 	 */
 	blockResolutions?: BlockResolution[];
 }
@@ -151,6 +164,8 @@ function hasAnchorScopedEdit(edits: readonly Edit[]): boolean {
 		if (edit.kind === "delete") return true;
 		// A `replace_block N:` edit anchors to concrete content on line N.
 		if (edit.kind === "block") return true;
+		// A `CUT` range reads concrete content.
+		if (edit.kind === "cut") return true;
 		return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor";
 	});
 }
@@ -204,6 +219,7 @@ export class Patcher {
 	readonly snapshots: SnapshotStore;
 	readonly recovery: Recovery;
 	readonly blockResolver: BlockResolver | undefined;
+	readonly clipboard: Clipboard | undefined;
 	readonly #enforceSeenLines: boolean;
 
 	constructor(options: PatcherOptions) {
@@ -214,6 +230,7 @@ export class Patcher {
 		this.snapshots = options.snapshots;
 		this.recovery = new Recovery(options.snapshots);
 		this.blockResolver = options.blockResolver;
+		this.clipboard = options.clipboard;
 		this.#enforceSeenLines = options.enforceSeenLines ?? true;
 	}
 
@@ -224,16 +241,34 @@ export class Patcher {
 	 * {@link PatchSectionResult} per section in the original patch order.
 	 */
 	async apply(patch: Patch): Promise<PatcherApplyResult> {
+		// One register per batch: `CUT` in one section feeds `PASTE` in a later
+		// one, so content can move across files. A host-owned register
+		// (see PatcherOptions.clipboard) additionally persists across batches:
+		// work on a fork and publish it per landed section, so a failed batch
+		// never poisons the persistent register and a mid-batch failure still
+		// preserves content already cut from disk.
+		const clipboard = forkClipboard(this.clipboard);
+
 		// Single-section fast path.
 		if (patch.sections.length === 1) {
-			const prepared = await this.prepare(patch.sections[0]);
-			return { sections: [await this.commit(prepared)] };
+			const prepared = await this.prepare(patch.sections[0], clipboard);
+			const result = await this.commit(prepared);
+			if (this.clipboard !== undefined) commitClipboard(clipboard, this.clipboard);
+			return { sections: [result] };
 		}
 
 		// Prepare every section first so any failure (stale hash, missing
 		// file, parse error, in-memory no-op) surfaces before any write.
 		const prepared: PreparedSection[] = [];
-		for (const section of patch.sections) prepared.push(await this.prepare(section));
+		// Register state after each section's prepare. Commits are non-atomic:
+		// when a later write fails, the sections before it are already on disk,
+		// so the host register must reflect exactly the landed prefix — content
+		// a landed CUT deleted would otherwise be lost.
+		const sectionStates: Clipboard[] = [];
+		for (const section of patch.sections) {
+			prepared.push(await this.prepare(section, clipboard));
+			sectionStates.push(forkClipboard(clipboard));
+		}
 		assertUniqueCanonicalPaths(prepared);
 		for (const entry of prepared) {
 			if (entry.isNoop) {
@@ -259,6 +294,7 @@ export class Patcher {
 					{ cause: error },
 				);
 			}
+			if (this.clipboard !== undefined) commitClipboard(sectionStates[index], this.clipboard);
 		}
 		return { sections: results };
 	}
@@ -268,8 +304,10 @@ export class Patcher {
 	 * No writes hit the filesystem. Use for CI checks and dry runs.
 	 */
 	async preflight(patch: Patch): Promise<void> {
+		// Dry run: fork the register and never publish it back.
+		const clipboard = forkClipboard(this.clipboard);
 		const prepared: PreparedSection[] = [];
-		for (const section of patch.sections) prepared.push(await this.prepare(section));
+		for (const section of patch.sections) prepared.push(await this.prepare(section, clipboard));
 		assertUniqueCanonicalPaths(prepared);
 		for (const entry of prepared) {
 			if (entry.isNoop) {
@@ -303,10 +341,13 @@ export class Patcher {
 	 * {@link PreparedSection} which can be fed to {@link commit} to land
 	 * the result on the filesystem.
 	 *
+	 * `clipboard` is the register shared by `CUT`/`PASTE` ops. Pass the batch
+	 * register when preparing several sections so content can move across files.
+	 *
 	 * Throws on parse error, missing-file-for-anchored-edit, or unrecovered
 	 * tag mismatch ({@link MismatchError}).
 	 */
-	async prepare(section: PatchSection): Promise<PreparedSection> {
+	async prepare(section: PatchSection, clipboard?: Clipboard): Promise<PreparedSection> {
 		const parsed = await this.#parseWithRangeDiagnostics(section);
 		const parseWarnings = [...parsed.warnings];
 		const fileOp = parsed.fileOp;
@@ -353,6 +394,7 @@ export class Patcher {
 		const lineEnding = detectLineEnding(text);
 		const normalized = normalizeToLF(text);
 
+		const register = clipboard ?? {};
 		const applyResult =
 			fileOp?.kind === "rem"
 				? this.#applyWithRecovery({
@@ -361,6 +403,7 @@ export class Patcher {
 						exists: read.exists,
 						normalized,
 						edits: [],
+						clipboard: register,
 					})
 				: this.#applyWithRecovery({
 						section: target,
@@ -368,6 +411,7 @@ export class Patcher {
 						exists: read.exists,
 						normalized,
 						edits: parsed.edits,
+						clipboard: register,
 					});
 
 		return new PreparedSection(
@@ -488,9 +532,32 @@ export class Patcher {
 		}
 
 		const write: WriteResult = await this.fs.writeText(section.path, persisted);
-		const fileHash = this.#recordFullSnapshot(canonicalPath, after);
 		const op = exists ? "update" : "create";
 
+		// `write.text` is the FS adapter's report of what actually landed on
+		// disk (see `WriteResult`), which for an ACP-bridge write can diverge
+		// from `after` when the client transforms content on save (e.g.
+		// format-on-save reformatting indentation the tool never touched).
+		// Keying the snapshot on `after` unconditionally would record a hash
+		// for content that no longer exists on disk: the next `read` sees the
+		// drifted file, tag validation misses, and hunk resolution proceeds
+		// against a baseline the file has already left — the mechanism behind
+		// "single-line edit reformats the whole file". Re-derive the recorded
+		// text from what was actually persisted and hash THAT.
+		//
+		// Deliberately does NOT touch `after` (or the diff/`newText` derived
+		// from it downstream): `after` stays the content this section asked
+		// for, so the model-visible diff stays scoped to the intended hunk
+		// instead of ballooning to a whole-file diff against a formatter's
+		// output on every drifted write. The drift itself is a warning, not a
+		// diff — an O(1) signal instead of an O(file-size) one. Comparing the
+		// normalized forms (rather than raw `write.text`/`persisted`) avoids a
+		// false "drift" purely from BOM/line-ending restoration asymmetry.
+		const recorded = normalizeToLF(stripBom(write.text).text);
+		const driftedOnWrite = recorded !== after;
+		const fileHash = this.#recordFullSnapshot(canonicalPath, recorded);
+		const allWarnings = driftedOnWrite ? [...warnings, writeDriftWarning(section.path)] : warnings;
+
 		return {
 			path: section.path,
 			canonicalPath,
@@ -503,7 +570,7 @@ export class Patcher {
 			header: formatHashlineHeader(section.path, fileHash),
 			firstChangedLine: applyResult.firstChangedLine,
 			blockResolutions: applyResult.blockResolutions,
-			warnings,
+			warnings: allWarnings,
 		};
 	}
 
@@ -609,8 +676,9 @@ export class Patcher {
 		exists: boolean;
 		normalized: string;
 		edits: readonly Edit[];
+		clipboard: Clipboard;
 	}): ApplyResult {
-		const { section, canonicalPath, exists, normalized, edits } = args;
+		const { section, canonicalPath, exists, normalized, edits, clipboard } = args;
 		const expected = exists ? section.fileHash : undefined;
 		// The 4-hex tag is content-derived: when the live text hashes to it,
 		// trust the match and apply directly. `storedSnapshotForTag` feeds the
@@ -643,6 +711,11 @@ export class Patcher {
 				onWarning: warning => resolveWarnings.push(warning),
 			});
 		}
+		// Surface clipboard sequencing mistakes (`PASTE` before any capture,
+		// capturing over un-pasted `CUT` content) with their targeted message
+		// before the recovery path below, which swallows apply failures and
+		// re-surfaces them as tag-mismatch errors.
+		validateClipboardSequence(resolved, clipboard);
 		const withResolveWarnings = (result: ApplyResult): ApplyResult =>
 			resolveWarnings.length === 0
 				? result
@@ -659,7 +732,7 @@ export class Patcher {
 			if (expected !== undefined && this.#enforceSeenLines) {
 				this.#assertSeenLines(section, expected, matchedSnapshot);
 			}
-			const result = applyEdits(normalized, resolved);
+			const result = applyEdits(normalized, resolved, { clipboard });
 			return withResolveWarnings(blockResolutions.length > 0 ? { ...result, blockResolutions } : result);
 		}
 		// Head/tail-only inserts are position-stable: "start"/"end" cannot move
@@ -667,7 +740,7 @@ export class Patcher {
 		// content and warn instead of hard-failing — unlike an anchored
 		// mismatch, which cannot be safely relocated and must reject.
 		if (!hasAnchorScopedEdit(resolved)) {
-			const result = applyEdits(normalized, resolved);
+			const result = applyEdits(normalized, resolved, { clipboard });
 			return withResolveWarnings({ ...result, warnings: [HEADTAIL_DRIFT_WARNING, ...(result.warnings ?? [])] });
 		}
 		// File drifted: map every anchor from the tagged snapshot to unchanged
@@ -677,6 +750,7 @@ export class Patcher {
 			currentText: normalized,
 			fileHash: expected,
 			edits: resolved,
+			clipboard,
 		});
 		if (recovered) return withResolveWarnings(recoveryToApplyResult(recovered));
 		const hashRecognized = this.snapshots.byHash(canonicalPath, expected) !== null;

package/src/prompt.md

@@ -1,49 +1,43 @@
-Your patch language names lines to replace, delete, or insert at, then lists the new content. Rule of thumb: a header ending in `:` is followed by `+` body rows; `DEL` has no body.
+Line-anchored patch language: name original lines to replace, cut, or insert at, then list new content. A header ending in `:` takes `+` body rows; `CUT`, `PASTE`, `REM`, `MV` take none.
 
 <headers>
-Every file section starts with `[PATH#TAG]`. `TAG` = 4-hex snapshot tag from your latest `read`/`search`, REQUIRED on every section — no hashless form. Create new files with `write`; hashline only edits existing files.
+Every file section starts `[PATH#TAG]`. `TAG` = 4-hex snapshot tag from your latest `read`/`search` — REQUIRED on every section. Create new files with `write`; hashline only edits existing files.
 </headers>
 
 <ops>
-`SWAP N.=M:` — replace original lines N.=M with the body rows below. INCLUSIVE — line M is consumed too.
-`SWAP.BLK N:` — replace the whole syntactic block that BEGINS on line N; tree-sitter resolves the closing line. Body rows below.
-`DEL N.=M` — delete original lines N.=M. No body.
-`DEL.BLK N` — delete the whole syntactic block that BEGINS on line N.
-`INS.PRE N:` — insert the body rows immediately before line N.
-`INS.POST N:` — insert the body rows immediately after line N.
-`INS.BLK.POST N:` — insert the body rows after the END of the block that BEGINS on line N — outside it, at sibling depth. To append inside a block, use `INS.POST`.
-`INS.HEAD:` / `INS.TAIL:` — insert the body rows at the very start / end of the file.
-`REM` — delete the whole file named by the section header. No body, no line ops.
-`MV DEST` — move/rename the section file to `DEST` (a path, quoted when it contains spaces). Line edits above `MV` land on the source first, then the final content is written at `DEST`.
-Single line: `SWAP N.=N:` / `DEL N`. The range is the ORIGINAL lines you touch; body length is irrelevant (replacing 1 line with 10 is still `SWAP N.=N:`).
+`SWAP N.=M:` — replace original lines N.=M (INCLUSIVE).
+`SWAP.BLK N:` — replace the whole syntactic block BEGINNING on line N; its closing line is resolved for you.
+`CUT N.=M` / `CUT.BLK N` — delete lines N.=M / the block beginning at N, and capture them for `PASTE`.
+`INS.PRE N:` / `INS.POST N:` — insert immediately before / after line N.
+`INS.BLK.POST N:` — insert after the END of the block beginning at N, outside it at sibling depth. Append inside a block → `INS.POST`.
+`INS.HEAD:` / `INS.TAIL:` — insert at the very start / end of the file.
+`PASTE.PRE N` / `PASTE.POST N` / `PASTE.HEAD` / `PASTE.TAIL` / `PASTE.BLK.POST N` — insert the clipboard at the position (the clipboard IS the body).
+`REM` — delete the whole section file. `MV DEST` — move/rename to `DEST` (quote paths with spaces); edits above `MV` land on the source first, final content written at `DEST`.
+Single line: `SWAP N.=N:` / `CUT N`. Range = ORIGINAL lines touched; body length irrelevant (1 line → 10 is still `SWAP N.=N:`).
 </ops>
 
 <body-rows>
-Body rows appear only under a `:` header. Every body row is `+TEXT` — add a literal line `TEXT`, verbatim (leading whitespace kept); `+` alone adds a blank line. No other row kind. NEVER write `-old` or a bare/context line. To keep a line, leave it out of every range. Literal lines starting with `-`/`+` still need the body prefix: Markdown `- item` → `+- item`, `+ item` → `++ item`.
+Only under a `:` header. Every row is `+TEXT`, verbatim (leading whitespace kept); `+` alone = blank line. NEVER `-old` or bare/context rows — the range deletes; the body is only the final content. Keep a line: leave it out of every range. Literal leading `-`/`+` keeps the prefix: `- item` → `+- item`, `+ item` → `++ item`.
 </body-rows>
 
 <rules>
-- Line numbers + `[PATH#TAG]` header come from your latest `read`/`search` (`LINE:TEXT` rows).
-- Numbers refer to the ORIGINAL file; never 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 your latest `read`/`search` literally displayed as `LINE:TEXT`; the tag certifies the snapshot, not your memory. A hunk anchored on a line you never displayed is REJECTED — re-`read` first. Seeing a line ≠ it holds the code you mean; confirm numbers map to the construct you intend, especially far from your read window.
-- Elided regions are UNSEEN: `…`/`..` markers and a collapsed `N-M:` summary row (only boundary lines N and M 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.
-- One hunk per range; body = final content, never an old/new pair.
-- Ranges cover ONLY lines whose content changes. Never widen over unchanged lines — a stale wide range shreds everything it spans.
-- Whole construct → `SWAP.BLK N` (tree-sitter resolves the end); lines inside it → `SWAP N.=M`.
-- `SWAP.BLK 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 `SWAP N.=M`.
-- Block ops (`SWAP.BLK`/`DEL.BLK`/`INS.BLK.POST`) anchor the OPENING line of a MULTI-LINE construct — never its closer, last line, or a bare inner statement. Anchoring one statement resolves to ONE line and is REJECTED: use the plain op (`SWAP N.=N` / `DEL N` / `INS.POST N`), or point N at the real opener. Saw the closer? Use plain `INS.POST M:`.
-- Markdown: a heading line IS a block opener — `SWAP.BLK`/`DEL.BLK`/`INS.BLK.POST` on a `##`/`###` heading resolves its WHOLE section (heading through every nested deeper heading, up to the next same-or-higher heading). So `DEL.BLK` drops the section, `SWAP.BLK` rewrites it, `INS.BLK.POST` lands after it (end the inserted body with a blank line to keep the next heading separated).
-- Non-adjacent changes = separate hunks; untouched lines stay out of every range.
-- Pure additions use `INS.PRE` / `INS.POST` / `INS.HEAD` / `INS.TAIL`, never a widened `SWAP` — retyped keepers are exactly what gets dropped. (A multi-line `SWAP` whose body restates the line just past the range is auto-dropped as an off-by-one keeper with a warning — issue the payload for the range only; never lean on the repair.)
-- NEVER format/restyle code with this tool; run the project formatter instead.
+- Line numbers + `#TAG` come from your latest `read`/`search` (`LINE:TEXT` rows); numbers name ORIGINAL lines, never shifted by applied hunks.
+- Applied edits renumber the file and change the `#TAG` — take the next edit's numbers from the edit response or a fresh `read`.
+- Touch only displayed lines — hunks on undisplayed lines are REJECTED. Far from your read window? Re-`read`; confirm numbers map to the intended construct.
+- Elided regions are UNSEEN (`…`/`..` markers, collapsed `N-M:` summary rows) — NEVER place or span a hunk inside one; `read` the range first.
+- NEVER start or end a range mid-expression or mid-block.
+- Ranges cover ONLY changed lines — never widen over keepers. Non-adjacent changes = separate hunks.
+- Whole construct → `SWAP.BLK N`; lines inside one → `SWAP N.=M`.
+- `SWAP.BLK` 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 `SWAP N.=M`).
+- Block ops anchor the OPENING line of a MULTI-LINE construct — never the closer, last line, or a bare inner statement; one statement → plain op (`SWAP N.=N:` / `CUT N` / `INS.POST N:`). Saw the closer? `INS.POST M:`.
+- Markdown: a heading IS a block opener — block ops on `##`/`###` resolve the WHOLE section (through deeper nested headings, up to the next same-or-higher heading). `INS.BLK.POST` after a section: end the body with a blank line to keep the next heading separated.
+- Pure additions → `INS.PRE`/`INS.POST`/`INS.HEAD`/`INS.TAIL`, never a widened `SWAP`.
+- Move code with `CUT`+`PASTE`, never retype. Clipboard: top-to-bottom across the whole patch (cross-file moves), persists across edit calls, latest `CUT` wins, and `PASTE` repeats freely. Pasted indentation is verbatim; re-indent via `SWAP`.
+- NEVER format/restyle code with this tool; run the project formatter.
 </rules>
 
 <example>
-Original (the exact shape `read` returns):
+`read` output shape:
 ```
 [greet.py#A1B2]
 1:def greet(name):
@@ -52,40 +46,7 @@ Original (the exact shape `read` returns):
 4:greet("world")
 ```
 
-Insert a guard after line 1:
-```
-[greet.py#A1B2]
-INS.POST 1:
-+    if not name: name = "stranger"
-```
-
-Replace line 2 with two lines:
-```
-[greet.py#A1B2]
-SWAP 2.=2:
-+    greeting = "Hi"
-+    msg = f"{greeting}, {name}"
-```
-
-Delete line 3:
-```
-[greet.py#A1B2]
-DEL 3
-```
-
-Delete the whole file:
-```
-[greet.py#A1B2]
-REM
-```
-
-Rename or move the file:
-```
-[greet.py#A1B2]
-MV greet_v2.py
-```
-
-Move after editing:
+Edit, then move:
 ```
 [greet.py#A1B2]
 SWAP 1.=3:
@@ -94,16 +55,7 @@ SWAP 1.=3:
 MV lib/greet.py
 ```
 
-Add a header and trailer:
-```
-[greet.py#A1B2]
-INS.HEAD:
-+# generated header
-INS.TAIL:
-+greet("everyone")
-```
-
-Insert Markdown bullets — the leading `+` is the body-row marker; the file receives `- task`:
+Markdown bullets — the file receives `- task`:
 ```
 [PLAN.md#A1B2]
 INS.POST 2:
@@ -111,7 +63,15 @@ INS.POST 2:
 +  - nested task
 ```
 
-Replace the whole `greet` function block — `SWAP.BLK 1:` resolves lines 1–3 (the `def` header through `print(msg)`); line 4 is a separate statement and stays:
+Move `greet` to a sibling file — clipboard flows across sections:
+```
+[greet.py#A1B2]
+CUT.BLK 1
+[other.py#3C4D]
+PASTE.HEAD
+```
+
+`SWAP.BLK 1:` resolves lines 1–3 (`def` header through `print(msg)`); line 4 is a separate statement and stays:
 ```
 [greet.py#A1B2]
 SWAP.BLK 1:
@@ -119,7 +79,7 @@ SWAP.BLK 1:
 +    print(f"Hello, {name}")
 ```
 
-A decorator/doc-comment is a SEPARATE block — `SWAP.BLK` on the `def`/`fn` line keeps it. Point N at the decorator to take both; here line 1 is `@cache`, so anchoring on the `def` (line 2) would orphan `@cache`:
+Decorator/doc-comment = SEPARATE block — point N at the decorator to take both; anchoring the `def` (line 2) would orphan `@cache`:
 ```
 [svc.py#C3D4]
 SWAP.BLK 1:
@@ -130,14 +90,14 @@ SWAP.BLK 1:
 </example>
 
 <anti-patterns>
-# WRONG — empty `SWAP` to delete. RIGHT: DEL 4
+# WRONG — empty `SWAP` to delete. RIGHT: CUT 4
 SWAP 4.=4:
 
-# WRONG — range describes post-edit size. RIGHT: SWAP 1.=1: (body length is irrelevant)
+# WRONG — range sized to the post-edit content. RIGHT: SWAP 1.=1: (body length irrelevant)
 SWAP 1.=2:
 +def greet(name):
 
-# WRONG — `-` rows / bare context lines do not exist. The range deletes; the body is only the new content.
+# WRONG — `-` rows / bare context lines do not exist; the range deletes, the body is only new content.
 SWAP 3.=3:
     msg = "Hello, " + name
 -   print(msg)
@@ -146,27 +106,29 @@ SWAP 3.=3:
 SWAP 3.=3:
 +   return msg
 
-# WRONG — a pure insertion done as a widened `SWAP`: you want to add one line after 2,
-# but you replace 2.=4, retype the keepers, and drop one (here line 4, `greet("world")`).
+# WRONG — pure insertion as a widened `SWAP`: retyped keepers get dropped (here line 4).
 SWAP 2.=4:
 +    msg = "Hello, " + name
 +    extra = compute(name)
 +    print(msg)
-# RIGHT — touch nothing you keep; the new line is the whole body.
+# RIGHT — touch nothing you keep.
 INS.POST 2:
 +    extra = compute(name)
 
-# WRONG — `INS.BLK.POST N:` anchored on a closing delimiter / last visible line. RIGHT: plain `INS.POST M:`
+# WRONG — `INS.BLK.POST` anchored on the closing delimiter / last visible line. RIGHT: plain `INS.POST M:`
 INS.BLK.POST 3:
 +after()
 # RIGHT
 INS.POST 3:
 +after()
+
+# WRONG — body rows under PASTE; the clipboard is the body. RIGHT: capture first, then a bodyless `PASTE.POST 20`.
+PASTE.POST 20:
++function f() {}
 </anti-patterns>
 
 <critical>
-If you remember nothing else:
-1. RE-GROUND AFTER EVERY EDIT. Every apply mints a fresh `#TAG` and renumbers — take the next edit's numbers from the edit response or a fresh `read`. Stale tag or surprise? STOP, re-`read`.
-2. RANGES ARE TIGHT. Cover only lines that change; a stale wide range shreds everything it spans. Whole construct → `SWAP.BLK N`.
-3. THE BODY IS THE FINAL CONTENT. Every body row starts with `+`; Markdown bullets use `+- item`, not `- item`.
+1. RE-GROUND AFTER EVERY EDIT — applied edits renumber the file and change the `#TAG`; take next numbers from the edit response or a fresh `read`. Stale tag or surprise? STOP, re-`read`.
+2. RANGES ARE TIGHT — cover only lines that change. Whole construct → `SWAP.BLK N`.
+3. BODY = FINAL CONTENT — every body row starts with `+`; Markdown bullets use `+- item`, not `- item`.
 </critical>

package/src/recovery.ts

@@ -10,13 +10,15 @@ import { diffLineRuns } from "@oh-my-pi/pi-natives";
 import { applyEdits } from "./apply";
 import { RECOVERY_EXTERNAL_WARNING, RECOVERY_LINE_REMAP_WARNING, RECOVERY_SESSION_CHAIN_WARNING } from "./messages";
 import type { SnapshotStore } from "./snapshots";
-import type { Anchor, ApplyResult, Edit } from "./types";
+import type { Anchor, ApplyResult, Clipboard, Edit } from "./types";
 
 export interface RecoveryArgs {
 	path: string;
 	currentText: string;
 	fileHash: string;
 	edits: readonly Edit[];
+	/** Shared clipboard register for `cut`/`paste` edits, threaded into the replay apply. */
+	clipboard?: Clipboard;
 }
 
 export interface RecoveryResult {
@@ -41,6 +43,12 @@ function getEditAnchors(edit: Edit): Anchor[] {
 	// Recovery only ever receives already-resolved edits (no `block`); this arm
 	// exists for type-exhaustiveness over the full `Edit` union.
 	if (edit.kind === "block") return [edit.anchor];
+	if (edit.kind === "cut") {
+		// Every captured line is an anchor: changed interior content is unsafe.
+		const anchors: Anchor[] = [];
+		for (let line = edit.range.start.line; line <= edit.range.end.line; line++) anchors.push({ line });
+		return anchors;
+	}
 	return edit.cursor.kind === "before_anchor" || edit.cursor.kind === "after_anchor" ? [edit.cursor.anchor] : [];
 }
 
@@ -213,6 +221,21 @@ function remapEditsToCurrent(previousText: string, currentText: string, edits: r
 			remapped.push({ ...edit, anchor });
 			continue;
 		}
+		if (edit.kind === "cut") {
+			// Map every captured line; an unmapped interior line means the
+			// content drifted and cannot be moved safely. Uniform offsets keep
+			// the mapped range contiguous.
+			const start = mapLine(edit.range.start.line);
+			if (start === null) return null;
+			let end = start;
+			for (let line = edit.range.start.line + 1; line <= edit.range.end.line; line++) {
+				const mapped = mapLine(line);
+				if (mapped === null) return null;
+				end = mapped;
+			}
+			remapped.push({ ...edit, range: { start: { line: start }, end: { line: end } } });
+			continue;
+		}
 
 		let blockStart = edit.blockStart;
 		if (blockStart !== undefined) {
@@ -243,12 +266,13 @@ function replayRemappedAnchorsOnCurrent(
 	currentText: string,
 	edits: readonly Edit[],
 	recoveryWarning: string,
+	clipboard: Clipboard | undefined,
 ): RecoveryResult | null {
 	const remapped = remapEditsToCurrent(previousText, currentText, edits);
 	if (remapped === null) return null;
 	let applied: ApplyResult;
 	try {
-		applied = applyEdits(currentText, remapped.edits);
+		applied = applyEdits(currentText, remapped.edits, clipboard === undefined ? {} : { clipboard });
 	} catch {
 		return null;
 	}
@@ -276,13 +300,13 @@ export class Recovery {
 	 * caller should then surface a {@link MismatchError}.
 	 */
 	tryRecover(args: RecoveryArgs): RecoveryResult | null {
-		const { path, currentText, fileHash, edits } = args;
+		const { path, currentText, fileHash, edits, clipboard } = args;
 		// When retained texts collide on the 16-bit tag, use the latest one.
 		// Recovery still requires its anchors and context to map unambiguously.
 		const snapshot = this.store.byHash(path, fileHash);
 		if (!snapshot) return null;
 		const recoveryWarning =
 			this.store.head(path) === snapshot ? RECOVERY_EXTERNAL_WARNING : RECOVERY_SESSION_CHAIN_WARNING;
-		return replayRemappedAnchorsOnCurrent(snapshot.text, currentText, edits, recoveryWarning);
+		return replayRemappedAnchorsOnCurrent(snapshot.text, currentText, edits, recoveryWarning, clipboard);
 	}
 }