pi-hashline-edit-pro 6.4.6 → 6.4.8

package/README.md

@@ -302,6 +302,7 @@ Output is capped at `limit` matched lines, 2000 rows, and 50KB of text, whicheve
 
 - History is per-file and single-level: only the most recent `replace`, `replace_match`, `insert`, `copy`, or `move` can be reverted. A same-message batch of `replace`/`insert` calls on one file counts as one entry: one undo reverts the whole batch.
 - History is persisted and survives session restarts. A failed `write` does not clear it.
+- Undo records older than `undoRetentionDays` (default 30; `0` keeps them forever) are deleted when the store opens.
 - Every applied `replace`, `replace_match`, `insert`, `copy`, or `move` is undoable; the undo record is saved before the edit is written.
 - A cross-file `move` stores one undo entry per file; `undo_last_change` reverts the file you name, so revert both sides to undo the whole move; a batched cross-file `move` reverts its destination side with the batch's undo and its source side with its own entry.
 - A successful `write` clears the history for that file.
@@ -353,7 +354,7 @@ The setting lives in `/hashline-config` as Auto-read all and in `config.json` as
 
 | Command | Description |
 | --- | --- |
-| `/hashline-config` | Open the settings window: auto-read anchors, auto-read all mode, git repos only, ignore folders/files, disable on models, read on disabled models, diff context lines, `grep` tool, copy/move tools, replace_match tool, required `path`, and strict input. Persists across sessions. |
+| `/hashline-config` | Open the settings window: auto-read anchors, auto-read all mode, git repos only, ignore folders/files, disable on models, read on disabled models, diff context lines, `grep` tool, copy/move tools, replace_match tool, required `path`, strict input, and undo retention. Persists across sessions. |
 | `/clear-anchors` | Clear the session's anchor claims. Anchors are re-claimed on the next `read`. |
 
 Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created when a setting is first changed in `/hashline-config`:
@@ -370,6 +371,7 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created when a se
   "requirePath": false,
   "strictInput": false,
   "diffContextLines": 1,
+  "undoRetentionDays": 30,
   "disableOnModels": [],
   "readOnDisabledModels": "vanilla"
 }
@@ -389,6 +391,7 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created when a se
 | `diffContextLines` | Diff context | `1` | Surrounding lines in post-edit diffs, 0-10 (needs Auto-read). |
 | `disableOnModels` | Disable on models | `[]` | Model globs matched case-insensitively against `provider/id`, the bare `id`, and `api`, with `*` and `?` wildcards. A matching model gets no anchored edit tools, no auto-read, and no write-echo refusal; `read` stays available as pi's ordinary read unless Read on disabled models is `remove`. |
 | `readOnDisabledModels` | Read on disabled models | `"vanilla"` | `read` for a model matched by `disableOnModels`: `"vanilla"` keeps pi's ordinary `read` active while the anchored edit tools stay off; `"remove"` disables `read` with the rest of the anchored tools. |
+| `undoRetentionDays` | Undo retention | `30` | Days to keep undo history; records older than this are deleted when the store opens. `0` keeps them forever (0-3650). |
 
 `disableOnModels` turns off the whole anchored surface for the models you name, so another edit tool (`apply_patch`, a shell read) can own the session without competing instructions. A match removes `replace`, `replace_match`, `insert`, `copy`, `move`, `grep`, and `undo_last_change` from the active tools, and also `read` when Read on disabled models is `remove`, registering pi's plain `grep` for those models, and it also skips the auto-read-all injection, the auto-read block after `write`, the post-edit diff substitution, and the `write` hook that refuses a `write` echoing a served anchor. Because the extension's `read` replaces the built-in one, a matched model has no `read` at all under `remove` unless another extension provides one; the default `vanilla` gives those models pi's ordinary `read` while the anchored edit tools stay off. The list is checked on `session_start`, on `model_select`, and again on `before_agent_start`, so a model change inside a session switches the surface immediately and another extension cannot re-add the tools mid-session. The default `[]` leaves every model unchanged.
 
@@ -411,6 +414,7 @@ When `PI_HASHLINE_DIR` is unset or empty, non-Windows platforms honor `XDG_CONFI
 | Auto-read all budget | 200KB floor; 2MB ceiling in `full` | total injection size derived from the model context window; `outline` is not capped at 2MB |
 | Stale-range feedback | first 100 lines | rows returned with `[E_RANGE_STALE]` |
 | Session anchors | 1,353,139 anchors in use | all tools; the least recently read or edited files are freed when the quota is exhausted (`[W_ANCHOR_RECLAIMED]`) |
+| Undo retention | 30 days by default (`undoRetentionDays` 0-3650) | `undo_last_change` history |
 
 `grep` uses the same 100MB file-size cutoff as `read`. Files over the line cap are skipped silently in directory searches.
 
@@ -418,9 +422,9 @@ When `PI_HASHLINE_DIR` is unset or empty, non-Windows platforms honor `XDG_CONFI
 
 All eight tools return machine-readable metadata in `details` alongside the model-visible text.
 
-All eight tools also declare an `outputSchema` and return `structuredContent`, so codemode scripts receive anchors, line numbers, diffs, and errors as data instead of parsing the rendered text. The model still receives `content`. Every structured result is either `{ ok: true, kind, ... }` or `{ ok: false, kind: "error", error: { code, message } }`; a failed call is still a tool error (`isError: true`) and also carries `structuredContent`, so a script can branch on the code without matching the message.
+All eight tools also declare an `outputSchema` and return `structuredContent`, so codemode scripts receive anchors, line numbers, diffs, and errors as data instead of parsing the rendered text. In a codemode session `tools.read()` resolves to the file's text, like the built-in `read`; pass `anchors: true` to receive `{ text, lines, notices }`, where `text` is the raw file content of the served window and `lines` carries the anchored rows. The model still receives `content`. Every structured result is either `{ ok: true, kind, ... }` or `{ ok: false, kind: "error", error: { code, message } }`; a failed call is still a tool error (`isError: true`) and also carries `structuredContent`, so a script can branch on the code without matching the message.
 
-`read` returns `{ kind: "read", path, text, lines, totalLines, startLine, nextOffset, truncated, blockedByLongLine, hadUtf8DecodeErrors }`, where each entry of `lines` is `{ line, text, anchor, rendered }` for a row that was served (`text` is what was shown, so an oversized line appears as its marker while keeping its anchor). An image read returns `{ kind: "image", path, mimeType }`.
+`read` returns `{ kind: "read", path, text, lines, totalLines, startLine, nextOffset, truncated, blockedByLongLine, hadUtf8DecodeErrors, notices }`, where `text` is the raw file content of the served window (no anchors, no footers) and each entry of `lines` is `{ line, text, anchor, rendered }` for a row that was served (`text` there is what was shown, so an oversized line appears as its marker while keeping its anchor). `notices` carries non-file notes such as the UTF-8 rewrite note and `[W_ANCHOR_RECLAIMED]`. An image read returns `{ type: "image", data, mimeType, note }`.
 
 `replace`, `replace_match`, `insert`, `copy`, `move`, and `undo_last_change` return `{ kind: "edit", verb, classification, path, text, diff, warnings, hints, firstChangedLine, anchors, anchorsOmitted }`, where `verb` is `"replaced"`, `"inserted"`, `"copied"`, `"moved"`, or `"undone"`, `anchors` are the live rows of the post-edit diff, and `anchorsOmitted` is true when the diff was truncated or carried no rows, meaning a fresh read is needed. A cross-file move reports the destination file and its anchors.
 
@@ -513,7 +517,7 @@ All state lives under the config directory (see [Configuration](#configuration))
 | `hash-store.sqlite` (+ `-wal`, `-shm`) | Per-file snapshots of allocated anchors keyed by content checksum, plus the undo table. |
 | `sessions/<key>.registry.jsonl` | The session's anchor ownership log (`allocate`/`free`/`clear` events). |
 
-The undo table contains the complete pre-edit and post-edit text for the latest edit to each file, so treat the store as sensitive data. On POSIX systems the state directory is restricted to mode `0700` and the SQLite database plus its WAL/SHM sidecars to `0600`. Sidecar logs whose session file is gone are garbage-collected at startup (never the sidecar of a session that is currently loaded in this process); the in-memory ownership of a session is released when that session shuts down and rebuilt from its sidecar on next use. Served records live in memory only and are recomputed on the next read.
+The undo table contains the complete pre-edit and post-edit text for the latest edit to each file, so treat the store as sensitive data. Undo records older than `undoRetentionDays` are deleted when the store opens, and SQLite's `secure_delete` overwrites deleted content. On POSIX systems the state directory is restricted to mode `0700` and the SQLite database plus its WAL/SHM sidecars to `0600`. Sidecar logs whose session file is gone are garbage-collected at startup (never the sidecar of a session that is currently loaded in this process); the in-memory ownership of a session is released when that session shuts down and rebuilt from its sidecar on next use. Served records live in memory only and are recomputed on the next read.
 
 ### Isolated state
 

package/index.ts

@@ -29,10 +29,12 @@ import {
   toggleRequirePath,
   toggleStrictInput,
   adjustDiffContextLines,
+  adjustUndoRetentionDays,
+  getUndoRetentionDays,
   setAutoReadAllIgnoreFromText,
   setDisableOnModelsFromText,
 } from "./src/config";
-import { loadHashStore, pruneMissing } from "./src/hash-store";
+import { loadHashStore, pruneExpiredUndo, pruneMissing } from "./src/hash-store";
 import { type AnchorSessionContext, initRegistry, gcRegistrySidecars, clearRegistry, freeAnchors, freeAnchorsForPaths, sessionKeyFor, sessionContextReadable, withAnchorSession, releaseRegistrySession, formatAnchorReclaimNotice, takeReclaimedPaths } from "./src/anchor-registry";
 import { serveRows } from "./src/served";
 import { finalizeTurn, planAssistantMessage } from "./src/batch";
@@ -69,6 +71,7 @@ export default function (pi: ExtensionAPI): void {
   let autoReadAllRequireGit = true;
   let disableOnModels: string[] = [];
   let readOnDisabledModels: ReadOnDisabledModels = "vanilla";
+  let codemodeActive = false;
   let readFlavor: "anchored" | "vanilla" = "anchored";
   let readFlavorCwd: string | undefined;
   let autoReadAllInjected = false;
@@ -81,7 +84,8 @@ export default function (pi: ExtensionAPI): void {
 
   async function refreshEditTools(): Promise<void> {
     try {
-      const flags = await currentEditFlags(pi.getActiveTools().includes("codemode"));
+      codemodeActive = pi.getActiveTools().includes("codemode");
+      const flags = await currentEditFlags(codemodeActive);
       if (readFlavor !== "vanilla") regRead(pi, flags);
       regReplace(pi, flags);
       regReplaceMatch(pi, flags);
@@ -184,6 +188,11 @@ export default function (pi: ExtensionAPI): void {
     loadHashStore()
       .then(async store => {
         freeAnchorsForPaths(await pruneMissing(store));
+        try {
+          pruneExpiredUndo(store, await getUndoRetentionDays());
+        } catch (error) {
+          console.error("Failed to prune expired undo records:", error);
+        }
       })
       .catch(err => {
         console.error("Failed to load hash store:", err);
@@ -252,6 +261,7 @@ export default function (pi: ExtensionAPI): void {
   }));
 
   pi.on("before_agent_start", async (_event, ctx) => withRegistrySession(ctx, async () => {
+    if (pi.getActiveTools().includes("codemode") !== codemodeActive) await refreshEditTools();
     await syncModelGate(ctx.model, ctx.cwd);
     if (autoReadAll === "off" || autoReadAllInjected) return;
     if (modelDisabled(ctx.model, disableOnModels)) return;
@@ -288,6 +298,7 @@ export default function (pi: ExtensionAPI): void {
             else if (key === "disableOnModels") disableOnModels = await setDisableOnModelsFromText(value ?? "");
             else if (key === "readOnDisabledModels") readOnDisabledModels = await cycleReadOnDisabledModels(delta);
             else if (key === "diffContextLines") await adjustDiffContextLines(delta ?? 1);
+            else if (key === "undoRetentionDays") await adjustUndoRetentionDays((delta ?? 1) * 5);
             else if (key === "anchorGrepEnabled") {
               const enabled = await toggleAnchorGrep();
               grepEnabled = enabled;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "6.4.6",
+  "version": "6.4.8",
   "type": "module",
   "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 4-char tokenizer-friendly anchor that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",
@@ -61,15 +61,15 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.3.0",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^24",
-    "@vitest/coverage-v8": "^4.1.11",
-    "eslint": "^10.9.1",
-    "typebox": "^1.3.7",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.68.0",
-    "vitest": "^4.1.11"
+    "@types/node": "^24.19.2",
+    "@vitest/coverage-v8": "^5.0.5",
+    "eslint": "^10.13.0",
+    "typebox": "^1.4.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.5"
   },
   "allowScripts": {
     "@google/genai@1.52.0": true,

package/src/anchor-registry.ts

@@ -6,8 +6,8 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { sessionClaimsDir } from "./paths";
 import { contentChecksum } from "./hashline/hasher";
 import { ANCHOR_COUNT, anchorAt } from "./hashline/alphabet";
-import { HASH_PROBE_STRIDE } from "./hashline/hash";
-import { errCode, isRec, splitLines } from "./utils";
+import { HASH_PROBE_STRIDE, MAX_HASH_LINES } from "./hashline/hash";
+import { assertLineCount, errCode, isRec, splitLines, spliceAll } from "./utils";
 import * as Diff from "diff";
 import { lineChecksum } from "./hashline";
 import { getAllocatedState, persistSnapshot, type HashStore } from "./hash-store";
@@ -46,6 +46,7 @@ interface OwnedAnchorMap {
 }
 
 interface AnchorMintedSet {
+  readonly size: number;
   has(anchor: string): boolean;
   add(anchor: string): unknown;
   [Symbol.iterator](): IterableIterator<string>;
@@ -125,9 +126,12 @@ class ShadowOwnedMap implements OwnedAnchorMap {
 class ShadowMintedSet implements AnchorMintedSet {
   private readonly parent: AnchorMintedSet;
   private readonly added = new Set<string>();
+  private extra = 0;
+  private parentSize: number;
 
   constructor(parent: AnchorMintedSet) {
     this.parent = parent;
+    this.parentSize = parent.size;
   }
 
   has(anchor: string): boolean {
@@ -135,10 +139,22 @@ class ShadowMintedSet implements AnchorMintedSet {
   }
 
   add(anchor: string): this {
+    if (!this.added.has(anchor) && !this.parent.has(anchor)) this.extra += 1;
     this.added.add(anchor);
     return this;
   }
 
+  get size(): number {
+    if (this.parent.size !== this.parentSize) {
+      this.parentSize = this.parent.size;
+      this.extra = 0;
+      for (const anchor of this.added) {
+        if (!this.parent.has(anchor)) this.extra += 1;
+      }
+    }
+    return this.parentSize + this.extra;
+  }
+
   *[Symbol.iterator](): IterableIterator<string> {
     yield* this.parent;
     for (const anchor of this.added) {
@@ -555,16 +571,19 @@ export function reclaimAnchorSpace(state: SessionState, protectPath?: string): s
 
 export function mintAnchor(state: SessionState, protectPath?: string): string {
   for (;;) {
-    for (let probe = 0; probe < MINT_PROBE_LIMIT; probe++) {
-      state.probe = (state.probe + HASH_PROBE_STRIDE) % ANCHOR_COUNT;
-      const candidate = anchorAt(state.probe);
-      if (!state.owned.has(candidate) && !state.everMinted.has(candidate)) {
-        return candidate;
+    if (state.everMinted.size < ANCHOR_COUNT) {
+      for (let probe = 0; probe < MINT_PROBE_LIMIT; probe++) {
+        state.probe = (state.probe + HASH_PROBE_STRIDE) % ANCHOR_COUNT;
+        const candidate = anchorAt(state.probe);
+        if (!state.owned.has(candidate) && !state.everMinted.has(candidate)) {
+          return candidate;
+        }
       }
     }
     for (let step = 1; step <= ANCHOR_COUNT; step++) {
       const candidate = anchorAt((state.probe + step) % ANCHOR_COUNT);
       if (!state.owned.has(candidate)) {
+        state.probe = (state.probe + step) % ANCHOR_COUNT;
         for (const served of state.served.values()) served.delete(candidate);
         return candidate;
       }
@@ -861,7 +880,7 @@ export function alignOwnershipWithSpans(
       state.everMinted.add(settled[k]!);
       state.owned.set(settled[k]!, { path, checksum: newChecksums[start + k]! });
     }
-    anchors.splice(start, spanLength, ...settled);
+    spliceAll(anchors, start, spanLength, settled);
     offset += span.replacementCount - spanLength;
   }
   const rows: [string, string][] = minted.map((m) => [m.anchor, m.checksum]);
@@ -963,8 +982,9 @@ export async function allocateFileAnchors(
   ensureRegistry();
   const registry = current();
   const shadow = options?.shadow === true;
-  if (!shadow && registry) touchPath(registry, path);
   const lines = splitLines(content);
+  assertLineCount(lines.length, path, MAX_HASH_LINES);
+  if (!shadow && registry) touchPath(registry, path);
   const checksums = lines.map(lineChecksum);
   if (options?.previous?.spans) {
     const prevChecksums = splitLines(options.previous.content).map(lineChecksum);
@@ -1058,6 +1078,10 @@ export function resetRegistryForTests(): void {
   registries.clear();
 }
 
+export function lastUsedAtForTests(path: string): number | undefined {
+  return current()?.lastUsedAt.get(path);
+}
+
 async function readSidecarWindow(sidecar: string): Promise<{ text: string; filled: boolean }> {
   const handle = await open(sidecar, "r");
   const buffer = Buffer.alloc(SIDECAR_HEADER_BYTES);

package/src/batch.ts

@@ -28,7 +28,7 @@ import { saveUndo } from "./replace-undo";
 import { buildChanged, buildNoop, type RMetrics, type TResult } from "./replace-response";
 import { toEditVerb, withStructuredText, type EditStructured } from "./structured";
 import { serveRows, servedHashesFromDiff } from "./served";
-import { abortIf, assertByteLimit, assertLineLimit, errCode, isRec, mapIoError, splitLines } from "./utils";
+import { abortIf, assertByteLimit, assertLineLimit, errCode, isRec, mapIoError, splitLines, spliceAll } from "./utils";
 
 export interface PlannedMember {
   batchKey: number;
@@ -793,7 +793,7 @@ function composeBatchLines(baseContent: string, pieces: BatchPiece[]): string {
   const lines = splitLines(baseContent);
   const baseLineCount = lines.length;
   const descending = [...pieces].sort((a, b) => b.start - a.start);
-  for (const piece of descending) lines.splice(piece.start - 1, piece.end - piece.start + 1, ...piece.newLines);
+  for (const piece of descending) spliceAll(lines, piece.start - 1, piece.end - piece.start + 1, piece.newLines);
   let composed = lines.join("\n");
   if (lines.length > 0 && (baseContent.endsWith("\n") || lines[lines.length - 1] === "")) {
     composed += "\n";

package/src/config-ui.ts

@@ -1,8 +1,8 @@
 import { Key, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { readConfig, type Config } from "./config";
+import { DEFAULT_UNDO_RETENTION_DAYS, readConfig, type Config } from "./config";
 
-export type ConfigToggleKey = "autoRead" | "autoReadAll" | "autoReadAllRequireGit" | "autoReadAllIgnore" | "anchorGrepEnabled" | "copyMoveEnabled" | "replaceMatchEnabled" | "requirePath" | "strictInput" | "diffContextLines" | "disableOnModels" | "readOnDisabledModels";
+export type ConfigToggleKey = "autoRead" | "autoReadAll" | "autoReadAllRequireGit" | "autoReadAllIgnore" | "anchorGrepEnabled" | "copyMoveEnabled" | "replaceMatchEnabled" | "requirePath" | "strictInput" | "diffContextLines" | "disableOnModels" | "readOnDisabledModels" | "undoRetentionDays";
 
 export interface ConfigRow {
   key: ConfigToggleKey;
@@ -40,6 +40,7 @@ export function configRows(config: Config): ConfigRow[] {
     { key: "strictInput", group: "Edit behavior", depth: 0, label: "Strict input", hint: "Reject auto-fixable slips instead of warnings", enabled: config.strictInput === true },
     { key: "disableOnModels", group: "Model gating", depth: 0, label: "Disable on models", hint: "Model globs that turn off anchored tools (comma-separated)", enabled: (config.disableOnModels ?? []).length > 0, entries: config.disableOnModels ?? [] },
     { key: "readOnDisabledModels", group: "Model gating", depth: 1, dependsOn: "disableOnModels", gated: true, label: "Read on disabled models", hint: "Keep read available for models disabled above", enabled: (config.readOnDisabledModels ?? "vanilla") !== "remove", mode: config.readOnDisabledModels ?? "vanilla", cycle: ["remove", "vanilla"] },
+    { key: "undoRetentionDays", group: "State", depth: 0, label: "Undo retention", hint: "Days to keep undo history; 0 keeps it forever", enabled: (config.undoRetentionDays ?? DEFAULT_UNDO_RETENTION_DAYS) > 0, value: config.undoRetentionDays ?? DEFAULT_UNDO_RETENTION_DAYS },
   ];
   for (const row of rows) {
     if (row.gated !== true || row.dependsOn === undefined) continue;

package/src/config.ts

@@ -12,6 +12,9 @@ const READ_ON_DISABLED_MODELS: ReadOnDisabledModels[] = ["remove", "vanilla"];
 export const DEFAULT_DIFF_CONTEXT_LINES = 1;
 export const MIN_DIFF_CONTEXT_LINES = 0;
 export const MAX_DIFF_CONTEXT_LINES = 10;
+export const DEFAULT_UNDO_RETENTION_DAYS = 30;
+export const MIN_UNDO_RETENTION_DAYS = 0;
+export const MAX_UNDO_RETENTION_DAYS = 3650;
 
 export interface Config {
   autoRead: boolean;
@@ -26,6 +29,7 @@ export interface Config {
   diffContextLines?: number;
   disableOnModels?: string[];
   readOnDisabledModels?: ReadOnDisabledModels;
+  undoRetentionDays?: number;
 }
 
 const DEFAULT_CONFIG: Config = {
@@ -41,6 +45,7 @@ const DEFAULT_CONFIG: Config = {
   diffContextLines: DEFAULT_DIFF_CONTEXT_LINES,
   disableOnModels: [],
   readOnDisabledModels: "vanilla",
+  undoRetentionDays: DEFAULT_UNDO_RETENTION_DAYS,
 };
 
 function parseAutoReadAllMode(value: unknown): AutoReadAllMode {
@@ -101,6 +106,14 @@ export function normalizeDiffContextLines(value: unknown): number {
   return floored;
 }
 
+export function normalizeUndoRetentionDays(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_UNDO_RETENTION_DAYS;
+  const floored = Math.floor(value);
+  if (floored < MIN_UNDO_RETENTION_DAYS) return MIN_UNDO_RETENTION_DAYS;
+  if (floored > MAX_UNDO_RETENTION_DAYS) return MAX_UNDO_RETENTION_DAYS;
+  return floored;
+}
+
 function parseConfig(content: string): Config {
   const parsed = JSON.parse(content) as unknown;
   if (!isRec(parsed) || (parsed.autoRead !== undefined && typeof parsed.autoRead !== "boolean")) {
@@ -118,6 +131,7 @@ function parseConfig(content: string): Config {
   const autoReadAllIgnore = parsed.autoReadAllIgnore;
   const disableOnModels = parsed.disableOnModels;
   const readOnDisabledModels = parsed.readOnDisabledModels;
+  const undoRetentionDays = parsed.undoRetentionDays;
   const legacyDisableReadOnModels = parsed.disableReadOnModels;
   return {
     autoRead: typeof autoRead === "boolean" ? autoRead : DEFAULT_CONFIG.autoRead,
@@ -132,6 +146,7 @@ function parseConfig(content: string): Config {
     autoReadAllIgnore: parseAutoReadAllIgnore(autoReadAllIgnore),
     disableOnModels: parseDisableOnModels(disableOnModels),
     readOnDisabledModels: parseReadOnDisabledModels(readOnDisabledModels, legacyDisableReadOnModels),
+    undoRetentionDays: normalizeUndoRetentionDays(undoRetentionDays),
   };
 }
 
@@ -277,6 +292,9 @@ export const toggleStrictInput = (): Promise<boolean> => toggleFlag("strictInput
 export async function getDiffContextLines(): Promise<number> {
   return normalizeDiffContextLines((await readConfig()).diffContextLines);
 }
+export async function getUndoRetentionDays(): Promise<number> {
+  return normalizeUndoRetentionDays((await readConfig()).undoRetentionDays);
+}
 export async function adjustDiffContextLines(delta: number): Promise<number> {
   let next = DEFAULT_DIFF_CONTEXT_LINES;
   await updateConfig((c) => {
@@ -285,6 +303,14 @@ export async function adjustDiffContextLines(delta: number): Promise<number> {
   });
   return next;
 }
+export async function adjustUndoRetentionDays(delta: number): Promise<number> {
+  let next = DEFAULT_UNDO_RETENTION_DAYS;
+  await updateConfig((c) => {
+    next = normalizeUndoRetentionDays(normalizeUndoRetentionDays(c.undoRetentionDays) + delta);
+    c.undoRetentionDays = next;
+  });
+  return next;
+}
 export async function setAutoReadAllIgnore(dirs: string[]): Promise<string[]> {
   let next: string[] = [];
   await updateConfig((c) => {

package/src/copy-move.ts

@@ -23,7 +23,7 @@ import { formatAnchorReclaimNotice, servedForPath, takeReclaimedPaths, withAncho
 import { batchMemberFor, batchServedFor, ensureBatchBase, executeBatchMember, noteBatchFailure, pendingBatchMemberFor, registerBatchPlanner, type BatchBase, type BatchMemberPlanner, type PlannedMember } from "./batch";
 import { loadP, loadGuidelines } from "./prompts";
 import { assertTransferReq, normReq, type TransferReq } from "./payload-contract";
-import { abortIf, assertByteLimit, isRec, splitLines } from "./utils";
+import { abortIf, anchorCarryIndex, assertByteLimit, isRec, splitLines } from "./utils";
 import { toDisplayPath } from "./paths";
 import { getDiffContextLines } from "./config";
 import { resolveInCwd, writeAtomic } from "./fs-write";
@@ -145,7 +145,7 @@ export function buildTransferEdit(input: {
           : [...sourceLines, fileLines[anchorLine - 1]!],
       },
       foldedAnchorLines: 1,
-      anchorCarry: refs.direction === "after" ? 0 : sourceLines.length,
+      anchorCarry: anchorCarryIndex(refs.direction, sourceLines.length),
       endingOverrides: refs.direction === "after"
         ? [undefined, ...sourceEndings]
         : [...sourceEndings, undefined],
@@ -319,14 +319,14 @@ async function prepareCrossTransfer(input: {
       ? offsetEndings(1, sourceEndings)
       : sourceEndings;
   if (kind === "copy") {
-    return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: refs.direction === "after" ? 0 : moved.length } : {}), endingOverrides };
+    return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: anchorCarryIndex(refs.direction, moved.length) } : {}), endingOverrides };
   }
   const sourceEdit: HTEdit = {
     remove_from: sourcePreload.fileHashes[sourceStart - 1]!,
     remove_to: sourcePreload.fileHashes[sourceEnd - 1]!,
     text: [],
   };
-  return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: refs.direction === "after" ? 0 : moved.length } : {}), sourceEdit, endingOverrides };
+  return { sourcePreload, destinationPreload, sourceDisplay, destinationDisplay, destinationEdit, destinationFolded, ...(destinationFolded === 1 ? { anchorCarry: anchorCarryIndex(refs.direction, moved.length) } : {}), sourceEdit, endingOverrides };
 }
 
 function pairEntry(pipe: PipelineResult, separators: LineEnding[] | undefined): UndoEntry {
@@ -584,6 +584,7 @@ async function executeCrossFile(
       signal,
       preloadedNorm: prepared.destinationPreload,
       endingOverrides: prepared.endingOverrides,
+      ...(prepared.anchorCarry !== undefined ? { anchorCarry: prepared.anchorCarry } : {}),
     });
     if (kind === "copy") {
       return commitEdit(destinationPipe, {
@@ -827,6 +828,7 @@ export async function transferPreview(kind: TransferKind, request: unknown, cwd:
         served: plan.servedOverride,
         endingOverrides: plan.endingOverrides,
         signal,
+        ...(plan.anchorCarry !== undefined ? { anchorCarry: plan.anchorCarry } : {}),
       });
       return previewFromPipe(pipe);
     }
@@ -837,6 +839,7 @@ export async function transferPreview(kind: TransferKind, request: unknown, cwd:
       preloadedNorm: prepared.destinationPreload,
       endingOverrides: prepared.endingOverrides,
       signal,
+      ...(prepared.anchorCarry !== undefined ? { anchorCarry: prepared.anchorCarry } : {}),
     });
     if (kind === "copy") return previewFromPipe(destinationPipe);
     const sourcePipe = await execPipeline(sourcePath, prepared.sourceEdit!, cwd, {
@@ -943,6 +946,7 @@ export function buildTransferToolDef(kind: TransferKind, flags: EditToolFlags =
       ],
     },
     flags,
+    { scriptGuidelines: kind === "copy" },
   );
   return {
     name: kind,
@@ -1016,6 +1020,7 @@ export function buildTransferToolDef(kind: TransferKind, flags: EditToolFlags =
               preloadedNorm: preload,
               served: plan.servedOverride,
               endingOverrides: plan.endingOverrides,
+              ...(plan.anchorCarry !== undefined ? { anchorCarry: plan.anchorCarry } : {}),
             });
             return commitEdit(pipe, {
               path: pipe.path,

package/src/edit-common.ts

@@ -53,8 +53,19 @@ function preferenceGuideline(flags: EditToolFlags): string {
 const SHARED_EDIT_OPS = ["replace", "replace_match", "insert", "copy", "move"];
 const SHARED_PAYLOAD_OPS = ["replace", "replace_match", "insert"];
 const SHARED_DIFF_OPS = ["replace", "replace_match", "insert", "copy", "move", "undo_last_change"];
-const RESULT_CONTRACT_GUIDELINE =
-  'When called from a codemode script, failures resolve to `{ ok: false, kind: "error", error: { code, message } }`; branch on `ok` instead of `try`/`catch`.';
+const SHARED_SCRIPT_OPS = ["read", "replace", "replace_match", "insert", "copy", "move", "grep", "undo_last_change"];
+
+function resultContractGuideline(flags: EditToolFlags): string {
+  const tools = operationNames(SHARED_SCRIPT_OPS, flags);
+  return `${tools}: when called from a codemode script, failures resolve to \`{ ok: false, kind: "error", error: { code, message } }\`; branch on \`ok\` instead of \`try\`/\`catch\`.`;
+}
+const READ_SCRIPT_GUIDELINE =
+  '`read` in a codemode script resolves to the file\'s text, like the built-in `read`; pass `anchors: true` to receive `{ text, lines, notices }` with the raw file content and `lines[].anchor` for chained edits. An image read resolves to an image block.';
+const GREP_SCRIPT_GUIDELINE =
+  '`grep`: a codemode script receives `{ text, results }`; each `results[].lines[]` entry carries the matching line\'s `anchor` and `text`, so a result is editable without a fresh read.';
+function editScriptGuideline(flags: EditToolFlags): string {
+  return `${operationNames(SHARED_EDIT_OPS, flags)}: a codemode script receives \`{ ok, kind: "edit", classification, diff, anchors, anchorsOmitted }\`; reuse \`anchors[].anchor\` to chain the next edit, and read again when \`anchorsOmitted\` is true.`;
+}
 const SCRIPT_BATCH_GUIDELINE =
   "Script calls apply immediately in order, and only the most recent edit per file is undoable.";
 const SCRIPT_TRANSFER_GUIDELINE =
@@ -106,31 +117,20 @@ function strictInputGuideline(flags: EditToolFlags): string {
   return `${tools}: strict-input mode is on; auto-fixable slips are rejected instead of fixed with warnings.`;
 }
 
-function finalizePrompts(
-  description: string,
-  snippet: string,
-  guidelines: string[],
-  flags: EditToolFlags,
-  options?: { stringPayload?: boolean },
-): { description: string; snippet: string; guidelines: string[] } {
+export function withReplacePrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  let description = base.description;
   const shared = [batchGuideline(flags), pathGuideline(flags)];
-  if (flags.codemode) shared.push(RESULT_CONTRACT_GUIDELINE);
+  if (flags.codemode) shared.push(editScriptGuideline(flags));
   if (flags.autoRead) shared.push(diffGuideline(flags));
-  if (options?.stringPayload !== false) shared.push(payloadGuideline(flags));
+  shared.push(payloadGuideline(flags));
   if (flags.strictInput) shared.push(strictInputGuideline(flags));
-  return { description, snippet, guidelines: [...guidelines, ...shared] };
-}
-
-export function withReplacePrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  let description = base.description;
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
   if (!flags.replaceMatchEnabled) {
     description = description
       .split(/(?<=\.)\s+/)
       .filter((sentence) => !sentence.includes("`replace_match`"))
       .join(" ");
   }
-  return finalizePrompts(description, base.snippet, guidelines, flags);
+  return { description, snippet: base.snippet, guidelines: [...base.guidelines.map((guideline) => guideline.text), ...shared] };
 }
 
 function readGuidelineApplies(guideline: Guideline, flags: EditToolFlags): boolean {
@@ -141,7 +141,7 @@ function readGuidelineApplies(guideline: Guideline, flags: EditToolFlags): boole
 
 export function withReadPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const preference = preferenceGuideline(flags);
-  const script = flags.codemode ? [RESULT_CONTRACT_GUIDELINE] : [];
+  const script = flags.codemode ? [READ_SCRIPT_GUIDELINE, resultContractGuideline(flags)] : [];
   const applicable = base.guidelines.filter((guideline) => readGuidelineApplies(guideline, flags));
   if (flags.autoReadAllActive) {
     const rewritten = applicable.filter((guideline) => guideline.id !== READ_REREAD_ID).map((guideline) => guideline.text);
@@ -153,16 +153,14 @@ export function withReadPrompts(base: { description: string; snippet: string; gu
   return { description: base.description, snippet: base.snippet, guidelines: [preference, ...guidelines, ...script] };
 }
 
-export function withInsertPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
-  return finalizePrompts(base.description, base.snippet, guidelines, flags);
+export function withInsertPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, _flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  return { description: base.description, snippet: base.snippet, guidelines: base.guidelines.map((guideline) => guideline.text) };
 }
 
 export function withReplaceMatchPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
-  const prompted = finalizePrompts(base.description, base.snippet, guidelines, flags);
-  if (flags.strictInput) prompted.guidelines.push("`replace_match`: strict-input mode rejects an `old_string` that covers the whole range or retypes unchanged text.");
-  return prompted;
+  const guidelines = base.guidelines.map((guideline) => guideline.text);
+  if (flags.strictInput) guidelines.push("`replace_match`: strict-input mode rejects an `old_string` that covers the whole range or retypes unchanged text.");
+  return { description: base.description, snippet: base.snippet, guidelines };
 }
 
 function gatedEditOps(ops: string[], flags: EditToolFlags): string[] {
@@ -183,8 +181,8 @@ function joinOps(ops: string[], options?: { backtick?: boolean; separator?: "/"
 }
 
 export function withGrepPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text)];
-  if (flags.codemode) guidelines.push(RESULT_CONTRACT_GUIDELINE);
+  const guidelines = base.guidelines.map((guideline) => guideline.text);
+  if (flags.codemode) guidelines.push(GREP_SCRIPT_GUIDELINE);
   if (flags.copyMoveEnabled) return { description: base.description, snippet: base.snippet, guidelines };
   const description = base.description.replaceAll(GREP_OPS_PHRASE, joinOps(gatedEditOps(["replace", "insert", "copy", "move"], flags)));
   return { description, snippet: base.snippet, guidelines };
@@ -192,10 +190,9 @@ export function withGrepPrompts(base: { description: string; snippet: string; gu
 
 export function withUndoPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const ops = gatedEditOps(["replace", "replace_match", "insert", "copy", "move"], flags);
-  const script = flags.codemode ? [RESULT_CONTRACT_GUIDELINE, SCRIPT_UNDO_GUIDELINE] : [];
+  const script = flags.codemode ? [SCRIPT_UNDO_GUIDELINE] : [];
   let description = base.description;
   let guidelines = [
-    preferenceGuideline(flags),
     ...base.guidelines
       .filter((guideline) => flags.copyMoveEnabled || guideline.id !== UNDO_CROSS_FILE_MOVE_ID)
       .map((guideline) => (guideline.id === UNDO_WRITE_CLEARS_ID && !flags.autoRead ? NEUTRAL_UNDO_WRITE_CLEARS : guideline.text)),
@@ -208,9 +205,10 @@ export function withUndoPrompts(base: { description: string; snippet: string; gu
   return { description, snippet: base.snippet, guidelines };
 }
 
-export function withTransferPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = [preferenceGuideline(flags), ...base.guidelines.map((guideline) => guideline.text), ...(flags.codemode ? [SCRIPT_TRANSFER_GUIDELINE] : [])];
-  return finalizePrompts(base.description, base.snippet, guidelines, flags, { stringPayload: false });
+export function withTransferPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags, options?: { scriptGuidelines?: boolean }): { description: string; snippet: string; guidelines: string[] } {
+  const guidelines = base.guidelines.map((guideline) => guideline.text);
+  if (flags.codemode && options?.scriptGuidelines !== false) guidelines.push(SCRIPT_TRANSFER_GUIDELINE);
+  return { description: base.description, snippet: base.snippet, guidelines };
 }
 
 function staleAnchorMessage(ref: string, hash: string, owners: Array<OwnedAnchor | undefined>): string {

package/src/hash-store.ts

@@ -136,6 +136,7 @@ interface Prepared {
   undoDelete: (...params: SqlParams) => void;
   snapshotTime: (...params: SqlParams) => Record<string, unknown> | undefined;
   undoTime: (...params: SqlParams) => Record<string, unknown> | undefined;
+  undoExpired: (...params: SqlParams) => Record<string, unknown>[];
 }
 
 export interface HashStore {
@@ -183,6 +184,7 @@ function addColumnIfMissing(db: RawDb, statement: string): void {
 function buildStore(db: RawDb): { db: RawDb; stmts: Prepared } {
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA synchronous = NORMAL");
+  db.exec("PRAGMA secure_delete = ON");
   db.exec(
     "CREATE TABLE IF NOT EXISTS snapshots (" +
       "path TEXT PRIMARY KEY, " +
@@ -242,6 +244,7 @@ function buildStore(db: RawDb): { db: RawDb; stmts: Prepared } {
   const undoDelStmt = db.prepare("DELETE FROM undo WHERE path = ?");
   const snapshotTimeStmt = db.prepare("SELECT updated_at FROM snapshots WHERE path = ?");
   const undoTimeStmt = db.prepare("SELECT updated_at FROM undo WHERE path = ?");
+  const undoExpiredStmt = db.prepare("SELECT path FROM undo WHERE updated_at < ?");
   const stmts: Prepared = {
     get: (...params) => getStmt.get(...params) as Record<string, unknown> | undefined,
     getState: (...params) => getStateStmt.get(...params) as Record<string, unknown> | undefined,
@@ -253,6 +256,7 @@ function buildStore(db: RawDb): { db: RawDb; stmts: Prepared } {
     undoDelete: retriedWrite(undoDelStmt),
     snapshotTime: (...params) => snapshotTimeStmt.get(...params) as Record<string, unknown> | undefined,
     undoTime: (...params) => undoTimeStmt.get(...params) as Record<string, unknown> | undefined,
+    undoExpired: (...params) => withBusyRetry(() => undoExpiredStmt.all(...params) as Record<string, unknown>[]),
   };
   return { db, stmts };
 }
@@ -651,6 +655,17 @@ export async function pruneMissing(store: HashStore): Promise<string[]> {
   for (const path of missing) snapshotCache.delete(path);
   return missing;
 }
+export function pruneExpiredUndo(store: HashStore, retentionDays: number, now = Date.now()): string[] {
+  if (!Number.isFinite(retentionDays) || retentionDays <= 0) return [];
+  const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+  const rows = store.stmts.undoExpired(cutoff) as { path?: unknown }[];
+  const paths = rows.map((row) => row.path).filter((path): path is string => typeof path === "string");
+  if (paths.length === 0) return [];
+  withStore(() => {
+    for (const path of paths) store.stmts.undoDelete(path);
+  });
+  return paths;
+}
 
 
 

package/src/insert.ts

@@ -12,7 +12,7 @@ import { stripAnchorRow } from "./hashline/resolve";
 import { withAnchorSession } from "./anchor-registry";
 import { loadP, loadGuidelines } from "./prompts";
 import { assertInsertReq, normReq, type InsertReq } from "./payload-contract";
-import { isRec, literalEscapeHints, splitLines } from "./utils";
+import { anchorCarryIndex, isRec, literalEscapeHints, splitLines } from "./utils";
 import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper, resolveEditTargetWithRequirement, throwIfStrictInput, withInsertPrompts, DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-common";
 import type { RPreview, RRState } from "./replace-render";
 import { editResultSchema, withStructuredErrors } from "./structured";
@@ -98,6 +98,11 @@ function insertStripWarning(anchorLine: string | undefined, direction: "before"
   return { label: "text", indexOffset: anchorLine !== undefined && direction === "after" ? -1 : 0 };
 }
 
+function insertAnchorCarry(direction: "before" | "after", editParams: HTEdit, anchorLine: string | undefined): number | undefined {
+  if (anchorLine === undefined) return undefined;
+  return anchorCarryIndex(direction, editParams.text.length - 1);
+}
+
 function planInsertBatchMember(input: BatchPlannerInput): BatchMemberPlan {
   const req = normReq(input.member.args);
   assertInsertReq(req);
@@ -149,6 +154,7 @@ export async function insertPreview(request: unknown, cwd: string, signal?: Abor
       signal,
     });
     const { editParams, anchorLine, contentSeparators } = buildInsertEdit(normalized, preload, ref, targetPath);
+    const anchorCarry = insertAnchorCarry(normalized.direction, editParams, anchorLine);
     const pipe = await execPipeline(targetPath, editParams, cwd, {
       accessMode: constants.R_OK,
       noPersist: true,
@@ -156,6 +162,7 @@ export async function insertPreview(request: unknown, cwd: string, signal?: Abor
       signal,
       stripWarning: insertStripWarning(anchorLine, normalized.direction),
       endingOverrides: contentSeparators,
+      ...(anchorCarry !== undefined ? { anchorCarry } : {}),
     });
     return previewFromPipe(pipe);
   } catch (error: unknown) {
@@ -241,21 +248,21 @@ export function buildInsertToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): I
             maxLines: MAX_HASH_LINES,
           });
           const { editParams, anchorLine, contentSeparators } = buildInsertEdit(req, preload, ref, targetPath);
+          const anchorCarry = insertAnchorCarry(req.direction, editParams, anchorLine);
           const pipe = await execPipeline(targetPath, editParams, ctx.cwd, {
             accessMode: constants.R_OK | constants.W_OK,
             signal,
             preloadedNorm: preload,
             stripWarning: insertStripWarning(anchorLine, req.direction),
             endingOverrides: contentSeparators,
+            ...(anchorCarry !== undefined ? { anchorCarry } : {}),
           });
           return commitEdit(pipe, {
             path: pipe.path,
             absolutePath,
             mutationTargetPath,
             editAnchors: [editParams.remove_from, editParams.remove_to],
-            ...(anchorLine === undefined
-              ? {}
-              : { anchorCarry: req.direction === "after" ? 0 : editParams.text.length - 1 }),
+            ...(anchorCarry !== undefined ? { anchorCarry } : {}),
             signal,
             verb: "inserted",
             noopNoun: "Insertion",

package/src/read.ts

@@ -23,7 +23,7 @@ import { withAnchorSession, adoptAnchors, ownerOf, ownersDifferingOnlyByCase, fo
 import { serveRows } from "./served";
 import { snapshotCache } from "./hash-store/cache";
 import { Text } from "@earendil-works/pi-tui";
-import { anchoredLine, readResultSchema, withStructuredErrors, type AnchoredLine, type ReadResult } from "./structured";
+import { anchoredLine, readResultSchema, withStructuredErrors, type AnchoredLine, type ReadResult, type ReadTextResult } from "./structured";
 const R_DESC = loadP("../tool-prompts/read.md");
 const R_SNIPPET = loadP("../tool-prompts/read-snippet.md");
 function readGuide(): Guideline[] {
@@ -241,7 +241,6 @@ function anchorRefOf(args: unknown): { anchor: string; limit: number | undefined
 	const { offset, limit, path } = args;
 	if (typeof offset !== "string" || offset.length === 0 || /^\d+$/.test(offset)) return undefined;
 	const validLimit = typeof limit === "number" && Number.isInteger(limit) && limit >= 1 ? limit : undefined;
-	if (limit !== undefined && validLimit === undefined) return undefined;
 	return { anchor: offset, limit: validLimit, path: typeof path === "string" ? path : undefined };
 }
 
@@ -263,28 +262,79 @@ function anchorLineOf(anchor: string, path: string | undefined, cwd: unknown): n
 	return index < 0 ? undefined : index + 1;
 }
 
+const ANSI_ESC = String.fromCharCode(27);
+const CALL_ANSI_RE = new RegExp(`${ANSI_ESC}\\[[0-9;]*m`, "g");
+const CALL_ANSI_AT_RE = new RegExp(`^${ANSI_ESC}\\[[0-9;]*m`);
+
+function rawIndexForPlainIndex(text: string, plainIndex: number): number {
+	let raw = 0;
+	let plain = 0;
+	while (raw < text.length && plain < plainIndex) {
+		const escape = CALL_ANSI_AT_RE.exec(text.slice(raw));
+		if (escape !== null) {
+			raw += escape[0].length;
+			continue;
+		}
+		raw += 1;
+		plain += 1;
+	}
+	return raw;
+}
+
+export function insertBeforeExpandHint(text: string, suffix: string): string {
+	const plain = text.replace(CALL_ANSI_RE, "");
+	if (!plain.endsWith(" to expand)")) return `${text}${suffix}`;
+	const plainIndex = plain.lastIndexOf(" (");
+	const insertAt = plainIndex < 0 ? text.length : rawIndexForPlainIndex(text, plainIndex);
+	return `${text.slice(0, insertAt)}${suffix}${text.slice(insertAt)}`;
+}
+
+function anchorRangeLabel(ref: { anchor: string; limit: number | undefined }, line: number | undefined): string {
+	if (line === undefined) return ref.limit === undefined ? `:${ref.anchor}` : `:${ref.anchor} +${ref.limit}`;
+	return ref.limit === undefined ? `:${line} (${ref.anchor})` : `:${line}-${line + ref.limit - 1} (${ref.anchor})`;
+}
+
 function renderReadCall(args: unknown, theme: any, context: any): Text {
 	const normalized = normalizeReadCallArgs(args);
-	const rendered = builtinReadRenderCall(normalized, theme, context);
 	const ref = anchorRefOf(normalized);
-	if (ref === undefined) return rendered;
-	const marker = `:${ref.anchor}`;
-	const text = (rendered as unknown as { text: string }).text;
-	const index = text.lastIndexOf(marker);
-	if (index < 0) return rendered;
+	if (ref === undefined) return builtinReadRenderCall(normalized, theme, context);
+	const rendered = builtinReadRenderCall(isRec(normalized) ? { ...normalized, offset: undefined, limit: undefined } : normalized, theme, context);
 	const line = anchorLineOf(ref.anchor, ref.path, context?.cwd);
-	if (line === undefined) {
-		if (ref.limit === undefined) return rendered;
-		const suffix = theme.fg("warning", ` +${ref.limit}`);
-		rendered.setText(`${text.slice(0, index + marker.length)}${suffix}${text.slice(index + marker.length)}`);
-		return rendered;
-	}
-	const range = ref.limit === undefined ? `${line}` : `${line}-${line + ref.limit - 1}`;
-	const replacement = theme.fg("warning", `:${range} (${ref.anchor})`);
-	rendered.setText(`${text.slice(0, index)}${replacement}${text.slice(index + marker.length)}`);
+	const suffix = theme.fg("warning", anchorRangeLabel(ref, line));
+	const text = (rendered as unknown as { text: string }).text;
+	rendered.setText(insertBeforeExpandHint(text, suffix));
 	return rendered;
 }
 
+function buildReadToolSchema(codemode: boolean) {
+	return Type.Object({
+		path: Type.String({
+			description: "Path to the file to read (relative or absolute)",
+		}),
+		offset: Type.Optional(
+			Type.Union([
+				Type.Integer({ minimum: 1 }),
+				Type.String(),
+			], { description: "Line number (1-indexed) or a served anchor to start reading from" }),
+		),
+		limit: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				description: "Maximum number of lines to read from offset",
+			}),
+		),
+		...(codemode
+			? {
+					anchors: Type.Optional(
+						Type.Boolean({
+							description: "Return { text, lines, notices } with editable anchors instead of the plain file text to a codemode script",
+						}),
+					),
+				}
+			: {}),
+	});
+}
+
 export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FLAGS): void {
   const prompted = withReadPrompts({ description: R_DESC, snippet: R_SNIPPET, guidelines: readGuide() }, flags);
   pi.registerTool({
@@ -294,23 +344,7 @@ export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
     promptSnippet: prompted.snippet,
     promptGuidelines: prompted.guidelines,
 		prepareArguments: makePrepareArguments(),
-		parameters: Type.Object({
-			path: Type.String({
-				description: "Path to the file to read (relative or absolute)",
-			}),
-			offset: Type.Optional(
-				Type.Union([
-					Type.Integer({ minimum: 1 }),
-					Type.String(),
-				], { description: "Line number (1-indexed) or a served anchor to start reading from" }),
-			),
-			limit: Type.Optional(
-				Type.Integer({
-					minimum: 1,
-					description: "Maximum number of lines to read from offset",
-				}),
-			),
-		}),
+		parameters: buildReadToolSchema(flags.codemode),
 		outputSchema: readResultSchema,
 		executionMode: "sequential",
 		renderCall: renderReadCall,
@@ -346,8 +380,7 @@ export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
 						context: typeof ctx,
 					) => ReturnType<typeof builtinRead.execute>;
 					const imageResult = await executeBuiltinRead(_toolCallId, params, signal, _onUpdate, ctx);
-					const imageStructured: ReadResult = { ok: true, kind: "image", path: rawPath, mimeType: file.mimeType };
-					return { ...imageResult, structuredContent: imageStructured };
+					return { ...imageResult, structuredContent: imageResult.structuredContent as ReadResult };
 				}
 	      const { normalized, fileHashes, hadUtf8DecodeErrors, absolutePath: resolvedPath } = await readNormFile(
 	        rawPath, ctx.cwd, { signal, preloadedFile: file, maxLines: MAX_HASH_LINES },
@@ -363,25 +396,30 @@ export function regRead(pi: ExtensionAPI, flags: EditToolFlags = DEFAULT_EDIT_FL
 				serveRows(resolvedPath, fileHashes, fileLines, preview.servedHashes);
 				const snapshotId = await safeSnapId(absolutePath, "read");
 				const reclaimNotice = formatAnchorReclaimNotice(takeReclaimedPaths());
-				const previewText = [
-					preview.text,
+				const notices = [
 					hadUtf8DecodeErrors ? "[Non-UTF-8 bytes shown as U+FFFD; editing rewrites the file as UTF-8.]" : undefined,
 					reclaimNotice,
-				].filter((part): part is string => part !== undefined).join("\n\n");
+				].filter((part): part is string => part !== undefined);
+				const previewText = [preview.text, ...notices].join("\n\n");
+				const servedRawText = preview.anchoredLines.map((row) => fileLines[row.line - 1] ?? "").join("\n");
+				const rawTruncation = servedRawText.length > 0 ? truncateHead(servedRawText, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES }) : undefined;
 
-				const structuredContent: ReadResult = {
+				const readResult: ReadTextResult = {
 					ok: true,
 					kind: "read",
 					path: rawPath,
-					text: previewText,
+					text: rawTruncation?.content ?? "",
 					lines: preview.anchoredLines,
 					totalLines: preview.totalLines,
 					startLine: preview.startLine,
 					nextOffset: preview.nextOffset ?? null,
-					truncated: preview.truncation !== undefined,
+					truncated: preview.truncation !== undefined || rawTruncation?.truncated === true,
 					blockedByLongLine: preview.blockedByLongLine,
 					hadUtf8DecodeErrors,
+					notices,
 				};
+				const anchorsRequested = isRec(params) && params.anchors === true;
+				const structuredContent: ReadResult = flags.codemode && !anchorsRequested ? readResult.text : readResult;
 				return {
 					content: [{ type: "text", text: previewText }],
 					details: {

package/src/replace-diff.ts

@@ -159,6 +159,40 @@ function placeSpans(
   return placed;
 }
 
+function splitPlacedSpan(
+  span: PlacedSpan,
+  oldLines: string[],
+  newLines: string[],
+  oldHashes: string[],
+  newIndexByHash: ReadonlyMap<string, number>,
+): PlacedSpan[] {
+  if (span.oldStart > span.oldEnd || span.newStart > span.newEnd) return [span];
+  const pairs: Array<[number, number]> = [];
+  let lastNew = span.newStart - 1;
+  for (let oldIdx = span.oldStart; oldIdx <= span.oldEnd; oldIdx++) {
+    const newIdx = newIndexByHash.get(oldHashes[oldIdx]!);
+    if (newIdx === undefined || newIdx < span.newStart || newIdx > span.newEnd || newIdx <= lastNew) continue;
+    if (oldLines[oldIdx] !== newLines[newIdx]) continue;
+    pairs.push([oldIdx, newIdx]);
+    lastNew = newIdx;
+  }
+  if (pairs.length === 0) return [span];
+  const out: PlacedSpan[] = [];
+  let oldCursor = span.oldStart;
+  let newCursor = span.newStart;
+  for (const [oldIdx, newIdx] of pairs) {
+    if (oldCursor <= oldIdx - 1 || newCursor <= newIdx - 1) {
+      out.push({ oldStart: oldCursor, oldEnd: oldIdx - 1, newStart: newCursor, newEnd: newIdx - 1 });
+    }
+    oldCursor = oldIdx + 1;
+    newCursor = newIdx + 1;
+  }
+  if (oldCursor <= span.oldEnd || newCursor <= span.newEnd) {
+    out.push({ oldStart: oldCursor, oldEnd: span.oldEnd, newStart: newCursor, newEnd: span.newEnd });
+  }
+  return out;
+}
+
 function trimPlacedSpans(
   placed: PlacedSpan[],
   oldLines: string[],
@@ -166,22 +200,11 @@ function trimPlacedSpans(
   oldHashes: string[],
   newHashes: string[],
 ): PlacedSpan[] {
+  const newIndexByHash = new Map<string, number>();
+  for (let index = 0; index < newHashes.length; index++) newIndexByHash.set(newHashes[index]!, index);
   const out: PlacedSpan[] = [];
   for (const span of placed) {
-    let oldStart = span.oldStart;
-    let oldEnd = span.oldEnd;
-    let newStart = span.newStart;
-    let newEnd = span.newEnd;
-    while (oldStart <= oldEnd && newStart <= newEnd && oldLines[oldStart] === newLines[newStart] && oldHashes[oldStart] === newHashes[newStart]) {
-      oldStart += 1;
-      newStart += 1;
-    }
-    while (oldStart <= oldEnd && newStart <= newEnd && oldLines[oldEnd] === newLines[newEnd] && oldHashes[oldEnd] === newHashes[newEnd]) {
-      oldEnd -= 1;
-      newEnd -= 1;
-    }
-    if (oldStart > oldEnd && newStart > newEnd) continue;
-    out.push({ oldStart, oldEnd, newStart, newEnd });
+    for (const piece of splitPlacedSpan(span, oldLines, newLines, oldHashes, newIndexByHash)) out.push(piece);
   }
   return out;
 }
@@ -364,7 +387,7 @@ export function genDiff(
 ): { diff: string; firstChangedLine: number | undefined; lineNumbers: (number|undefined)[] } {
   const maxLineBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxLineBytes ?? DEFAULT_MAX_BYTES);
   const maxBytes = limits?.unlimited ? Number.POSITIVE_INFINITY : (limits?.maxBytes ?? DEFAULT_MAX_BYTES);
-  if (spans && newContentHashes && oldContentHashes) {
+  if (spans && spans.length > 0 && newContentHashes && oldContentHashes) {
     const anchored = genSpanDiff(oldContent, newContent, contextLines, newContentHashes, oldContentHashes, maxLineBytes, maxBytes, spans);
     if (anchored) {
       const diff = disambiguateDuplicateAnchors(anchored.diff);

package/src/replace.ts

@@ -87,6 +87,7 @@ export interface ExecPipelineOptions {
   stripWarning?: StripWarningLocation;
   endingOverrides?: (LineEnding | undefined)[];
   preserveDeletionSeparators?: boolean;
+  anchorCarry?: number;
 }
 
 export function hashSpan(hashes: string[], from: string, to: string): [number, number] | undefined {
@@ -205,20 +206,22 @@ export async function execPipeline(
   const result = anchorResult.content;
   const isNoop = result === originalNormalized;
 
+  const pipeSpan = isNoop ? undefined : spanForEdit(originalHashes, effectiveEdit.hash_bounds[0].hash, effectiveEdit.hash_bounds[1].hash, result);
+  if (pipeSpan && options?.anchorCarry !== undefined) pipeSpan.carry = options.anchorCarry;
+  const pipeSpans = pipeSpan ? [pipeSpan] : undefined;
+
   const resultHashes = isNoop
     ? originalHashes
     : await lineHashes(result, absolutePath, {
         content: originalNormalized,
         hashes: originalHashes,
+        ...(pipeSpans ? { spans: pipeSpans } : {}),
       }, hashStore, false, true);
   const warnings = [...editWarnings, ...(anchorResult.warnings ?? [])];
   await throwIfStrictInput(warnings);
   const { totalAddedLines, totalRemovedLines } = countLineChanges(
     effectiveEdit, originalHashes, isNoop,
   );
-
-  const pipeSpan = isNoop ? undefined : spanForEdit(originalHashes, effectiveEdit.hash_bounds[0].hash, effectiveEdit.hash_bounds[1].hash, result);
-  const pipeSpans = pipeSpan ? [pipeSpan] : undefined;
   return {
     path: displayPath,
     originalNormalized,

package/src/structured.ts

@@ -45,16 +45,17 @@ export type ReadTextResult = {
 	truncated: boolean;
 	blockedByLongLine: boolean;
 	hadUtf8DecodeErrors: boolean;
+	notices: string[];
 };
 
 export type ReadImageResult = {
-	ok: true;
-	kind: "image";
-	path: string;
+	type: "image";
+	data: string;
 	mimeType: string;
+	note: string;
 };
 
-export type ReadResult = ReadTextResult | ReadImageResult | StructuredError;
+export type ReadResult = ReadTextResult | ReadImageResult | string | StructuredError;
 
 export const readResultSchema = Type.Union([
 	Type.Object({
@@ -69,13 +70,15 @@ export const readResultSchema = Type.Union([
 		truncated: Type.Boolean(),
 		blockedByLongLine: Type.Boolean(),
 		hadUtf8DecodeErrors: Type.Boolean(),
+		notices: Type.Array(Type.String()),
 	}),
 	Type.Object({
-		ok: Type.Literal(true),
-		kind: Type.Literal("image"),
-		path: Type.String(),
+		type: Type.Literal("image"),
+		data: Type.String(),
 		mimeType: Type.String(),
+		note: Type.String(),
 	}),
+	Type.String(),
 	structuredErrorSchema,
 ]);
 

package/src/utils.ts

@@ -41,6 +41,24 @@ export function splitLines(text: string): string[] {
   return text.endsWith("\n") ? lines.slice(0, -1) : lines;
 }
 
+export function spliceAll<T>(target: T[], start: number, deleteCount: number, items: readonly T[]): T[] {
+  const rawStart = Number.isNaN(start) ? 0 : Math.trunc(start);
+  const at = rawStart < 0 ? Math.max(target.length + rawStart, 0) : Math.min(rawStart, target.length);
+  const rawCount = Number.isNaN(deleteCount) ? 0 : Math.trunc(deleteCount);
+  const remove = Math.max(0, Math.min(rawCount, target.length - at));
+  const removed = target.slice(at, at + remove);
+  const tail = target.slice(at + remove);
+  const additions: readonly T[] = items === target ? [...items] : items;
+  target.length = at;
+  for (const item of additions) target.push(item);
+  for (const item of tail) target.push(item);
+  return removed;
+}
+
+export function anchorCarryIndex(direction: "after" | "before", lineCount: number): number {
+  return direction === "after" ? 0 : lineCount;
+}
+
 export function visLines(text: string): string[] {
   return text.length === 0 ? [] : splitLines(text);
 }
@@ -194,10 +212,12 @@ export function clipLine(line: string, maxLen = 200): string {
 	const flat = line.replace(/\n/g, "\\n");
 	return flat.length > maxLen ? `${flat.slice(0, maxLen)}...` : flat;
 }
-export function assertLineLimit(content: string, displayPath: string, limit: number): void {
-	const count = splitLines(content).length;
+export function assertLineCount(count: number, displayPath: string, limit: number): void {
 	if (count > limit) throw new Error(formatLineLimit(displayPath, limit, count));
 }
+export function assertLineLimit(content: string, displayPath: string, limit: number): void {
+	assertLineCount(splitLines(content).length, displayPath, limit);
+}
 export function assertByteLimit(content: string, displayPath: string, limit = MAX_BYTES): void {
 	if (Buffer.byteLength(content, "utf-8") > limit) {
 		throw new Error(`[E_FILE_TOO_LARGE] File is too large: ${displayPath} (exceeds the ${limit / (1024 * 1024)}MB size limit). For very large files, use write.`);