dsh-hashline-edit 0.2.0 → 0.2.2

package/lib/types/src/mutation-engine/types.d.ts

@@ -7,9 +7,10 @@
 import type { LineEnding } from "../edit-diff.js";
 import type { ResolvedRange } from "../served-session/serve-render.js";
 import type { HashStore } from "../hash-store.js";
+import type { EditDetails, RMetrics } from "../edit-response.js";
+import type { DomainErrorCode, RangeCause } from "../domain-errors.js";
+import type { ServedRow } from "../domain-errors.js";
 export interface PipelineOptions {
-    /** Workspace root used to re-assert lifecycle path boundaries at commit time. */
-    workspaceRoot?: string;
     accessMode?: number;
     signal?: AbortSignal;
     store?: HashStore;
@@ -31,21 +32,6 @@ export interface PipelineOptions {
      * window cannot show that.
      */
     onBeforeFirstCutWrite?: () => void | Promise<void>;
-    /**
-     * TEST-ONLY mid-member fault seam: called after a move's rename is durable and before its
-     * destination content is rewritten, so the rollback of that in-flight member is exercised.
-     */
-    onAfterMoveRename?: (toAbsolutePath: string) => void | Promise<void>;
-}
-/**
- * The honest outcome of a failed multi-member commit's rollback attempt. `restored` members are
- * proven back at their pre-images; `remaining` members were not rolled back; `uncertain` members
- * are those whose rollback attempt itself threw, so neither state can be claimed for them.
- */
-export interface TransactionRecoveryReport {
-    restored: string[];
-    remaining: string[];
-    uncertain: string[];
 }
 /**
  * (ticket-04b) One foreign `mode: "cut"` item as seen by the pre-pass: the submitted span anchors
@@ -59,26 +45,6 @@ export interface ForeignCutRecord {
     spanFrom: string;
     spanTo: string;
 }
-/**
- * The file-lifecycle action one transaction member carries.
- *
- * This is the engine-local vocabulary: apply_patch's plan IR maps onto it in
- * `src/apply-patch/commit.ts` so the mutation engine never imports the apply-patch layer.
- * Absent is an ordinary in-place edit.
- */
-export type MemberLifecycle = {
-    kind: "keep";
-} | {
-    kind: "add";
-    createdDirs: readonly string[];
-} | {
-    kind: "delete";
-} | {
-    kind: "move";
-    fromAbsolutePath: string;
-    toAbsolutePath: string;
-    createdDirs: readonly string[];
-};
 export interface ProcessedEditFile {
     path: string;
     absolutePath: string;
@@ -122,9 +88,53 @@ export interface ProcessedEditFile {
      * correlated two-file transaction; the in-memory buffer itself never touches these files.
      */
     foreignCuts: ForeignCutRecord[];
+}
+export interface MutationSuccess {
+    ok: true;
+    /** SAFETY: Normalized result content (LF). */
+    result: string;
+    /** SAFETY: Unified diff (hash-anchored) for model consumption. */
+    diff: string;
+    /** SAFETY: User-facing drift notice, if any (details only, not model content). */
+    drift: string | undefined;
+    /** SAFETY: Metrics for telemetry. */
+    metrics: RMetrics;
+    raw: ProcessedEditFile;
+    /** SAFETY: Full tool result (content + details) for pi's tool_result hook. */
+    toolResult: {
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: EditDetails;
+    };
+}
+export interface MutationFailure {
+    ok: false;
+    /**
+     * SAFETY: Machine code — a registry member (`DomainErrorCode`). `toFailure` validates every
+     * caught code through the envelope reader (`src/error-envelope.ts`): non-registry strings
+     * (errno pass-through included) route to `E_UNKNOWN`, so the union is honest.
+     */
+    code: DomainErrorCode;
+    /** SAFETY: Human message — model-facing signal when applicable. */
+    message: string;
+    /** SAFETY: Fresh served block for retry when available (reject-and-serve). */
+    servedBlock?: string;
+    servedRows?: ServedRow[];
     /**
-     * apply_patch lifecycle action for this member; absent is an ordinary edit. The correlated
-     * transaction reads it for pre-image capture, commit ordering, rollback and undo-row shape.
+     * SAFETY: the RAW `E_BAD_PAYLOAD` message behind a rendered refusal, when the route is one, so
+     * SAFETY: the tool seam can name the invoking tool instead of falling back to the neutral
+     * SAFETY: wording. Present only for `code: "E_BAD_PAYLOAD"`.
      */
-    lifecycle?: MemberLifecycle;
+    payloadMessage?: string;
+    /** SAFETY: User-facing diagnosis, never a model remedy — a GLOSSARY.md glossary term. */
+    cause?: RangeCause;
+    details?: {
+        code: DomainErrorCode;
+        cause: RangeCause;
+    };
 }
+export type MutationResult = MutationSuccess | MutationFailure;
+export declare function isMutationSuccess(r: MutationResult): r is MutationSuccess;
+export declare function isMutationFailure(r: MutationResult): r is MutationFailure;

package/lib/types/src/payload-contract.d.ts

@@ -0,0 +1,135 @@
+import { Type } from "typebox";
+import type { EditPlacement } from "./hashline/resolve.js";
+declare const normalizedEdit: unique symbol;
+/** Width-appropriate illustrative anchor for prompt examples (width is a build-time setting, ADR-0020). */
+export declare const ANCHOR_EXAMPLE: string;
+/**
+ * The `text_ref` payload: two inclusive bare anchors bounding a served span, an optional serving
+ * `file`, and a REQUIRED `mode` — `"copy"` re-inserts the span bytes, `"cut"` additionally retires
+ * them. Both modes apply to this file AND to another served file (ticket-04b): a foreign-source
+ * `"cut"` commits the insert and the source retirement as one correlated transaction (ADR-0028).
+ */
+type SpanRef = {
+    anchor_from: string;
+    anchor_to: string;
+    file?: string;
+    mode: "copy" | "cut";
+};
+/**
+ * Wire item (ticket-04): exactly one payload per item — `text` or `text_ref` — over the inclusive
+ * anchor pair, with optional `at` placement. There is no `op` field and no verbs: the key set IS
+ * the vocabulary (ADR-0007 line 26; content comes from the copy of another served file, which the
+ * wire expresses as `text_ref.file`).
+ */
+export type EditItem = {
+    anchor_from: string;
+    anchor_to: string;
+    at?: "in-place" | "before" | "after";
+    text?: string;
+    text_ref?: SpanRef;
+    /**
+     * The file this item edits; absent means the call's top-level `file`. One call may therefore
+     * cross files: each item resolves its anchors and its lease against the file it names.
+     */
+    file?: string;
+};
+type EditMode = "general" | "literal";
+/**
+ * Internal normalized vocabulary owned by the admission boundary (ticket-01, renamed ticket-04).
+ * The wire never names these shapes: `normReq` builds them once from the validated payload and
+ * everything downstream consumes the union — the engine switches on `payload.kind` exhaustively.
+ */
+export type Placement = "in-place" | "before" | "after";
+/**
+ * @public Intentional surface (knip): the tuple type is the wire/engine
+ * vocabulary check, so the binding is never imported — its reason to exist
+ * is the typecheck failure it produces when the unions drift.
+ */
+export declare const _placementVocabularyAgreement: [
+    Placement extends EditPlacement ? true : never,
+    EditPlacement extends Placement ? true : never
+];
+/** The anchor pair an item targets — placement and payload are relative to its resolved span. */
+type AnchorSpan = {
+    anchor_from: string;
+    anchor_to: string;
+};
+export type DesiredContent = {
+    kind: "literal";
+    text: string;
+} | {
+    kind: "reference";
+    span: SpanRef;
+    mode: "copy" | "cut";
+} | {
+    kind: "empty";
+};
+export type NormalizedEditItem = {
+    target: AnchorSpan;
+    at: Placement;
+    payload: DesiredContent;
+    /** The file this item edits, when the wire named one; absent means the request's `file`. */
+    file?: string;
+};
+export type NormalizedEditRequest = {
+    file: string;
+    edits: NormalizedEditItem[];
+    mode?: EditMode;
+};
+/** The wire-folded request (the admission analyzer's view): canonical keys, pre-union. */
+type PreAdmissionRequest = {
+    file: string;
+    edits: EditItem[];
+    mode?: EditMode;
+};
+type NormalizedPayload = NormalizedEditRequest & {
+    readonly [normalizedEdit]: true;
+};
+type RawPayload = string | number | boolean | null | undefined | Record<string, unknown>;
+export type NormReqResult = NormalizedPayload | RawPayload;
+export declare const anchorFromSchema: Type.TString;
+export declare const anchorToSchema: Type.TString;
+export declare const editFileSchema: Type.TString;
+export declare const editModeSchema: Type.TUnion<[Type.TLiteral<"general">, Type.TLiteral<"literal">]>;
+export declare const editItemSchema: Type.TObject<{
+    anchor_from: Type.TString;
+    anchor_to: Type.TString;
+    at: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TLiteral<"in-place">, Type.TLiteral<"before">, Type.TLiteral<"after">]>, Type.TNull]>>;
+    file: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    text: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    text_ref: Type.TOptional<Type.TUnion<[Type.TObject<{
+        anchor_from: Type.TString;
+        anchor_to: Type.TString;
+        file: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+        mode: Type.TUnion<[Type.TLiteral<"copy">, Type.TLiteral<"cut">]>;
+    }>, Type.TNull]>>;
+}>;
+export declare const editToolSchema: Type.TObject<{
+    file: Type.TString;
+    edits: Type.TArray<Type.TObject<{
+        anchor_from: Type.TString;
+        anchor_to: Type.TString;
+        at: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TLiteral<"in-place">, Type.TLiteral<"before">, Type.TLiteral<"after">]>, Type.TNull]>>;
+        file: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+        text: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+        text_ref: Type.TOptional<Type.TUnion<[Type.TObject<{
+            anchor_from: Type.TString;
+            anchor_to: Type.TString;
+            file: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+            mode: Type.TUnion<[Type.TLiteral<"copy">, Type.TLiteral<"cut">]>;
+        }>, Type.TNull]>>;
+    }>>;
+    mode: Type.TOptional<Type.TUnion<[Type.TUnion<[Type.TLiteral<"general">, Type.TLiteral<"literal">]>, Type.TNull]>>;
+}>;
+export declare const EDIT_DESCRIPTION: string;
+export declare const EDIT_SNIPPET: string;
+export declare const EDIT_GUIDELINES: string[];
+export declare function editRequestFrom(input: unknown): PreAdmissionRequest | undefined;
+export declare function normReq(input: unknown): NormReqResult;
+export declare function prepareEditArguments(args: unknown): Record<string, unknown>;
+export declare function getPreviewInput(args: unknown): {
+    file: string;
+    edits: EditItem[];
+} | null;
+export declare function assertReq(request: unknown): asserts request is NormalizedEditRequest;
+export {};

package/lib/types/src/served-session/serve-render.d.ts

@@ -14,13 +14,7 @@ export interface FileSnapshotContext {
 export declare function buildRangeServeRows(startLine: number, endLine: number, fileHashes: string[]): ServedRow[];
 export declare function denseServeRows(hashes: readonly string[]): ServedRow[];
 export declare function fmtServedRows(rows: ServedRow[], fileLines: string[]): string;
-export declare function paginationHint(nextOffset: number, more: number): string;
 export declare function servedPositionsOf(served: (string | null)[], hash: string): number[];
-/** Builds the reject-and-serve served rows + rendered block for a current on-disk range. */
-export declare function buildRangeServeBlock(startLine: number, endLine: number, fileHashes: string[], fileLines: string[]): {
-    servedRows: ServedRow[];
-    rendered: string;
-};
 /**
  * Builds an `[E_TARGET_LOST]` rejection for a retired leased identity whose range cannot be
  * identified (spec stale-identity-reject-and-serve D1/D6, ADR-0018 decisions 1-2). The payload

package/lib/types/src/undo-store.d.ts

@@ -25,23 +25,7 @@ export interface UndoRecord {
      * `null` is a row from before this column, or an ordinary single-file edit.
      */
     rawPre?: string | null;
-    /**
-     * The lifecycle action this row reverses. Absent/null is an ordinary edit (back-compatible).
-     * add = the file did not exist before; delete = the file does not exist after; move = a pure
-     * rename with an optional content edit.
-     */
-    lifecycle?: UndoLifecycle | null;
-    /** Move: the absolute path the file had before the transaction. */
-    fromPath?: string | null;
-    /** Move: the absolute path the file has after the transaction. */
-    toPath?: string | null;
-    /** The RAW post-transaction text when the commit wrote non-canonical bytes (pure move). */
-    rawPost?: string | null;
-    /** Add: the directories the add created, outermost first, JSON-encoded in the column. */
-    createdDirs?: readonly string[] | null;
 }
-/** The lifecycle action one undo row reverses. */
-export type UndoLifecycle = "edit" | "add" | "delete" | "move";
 export type CutIntentDirection = "revert" | null;
 export interface CutIntent {
     txnId: string;
@@ -49,7 +33,7 @@ export interface CutIntent {
     direction: CutIntentDirection;
 }
 export interface UndoStmts {
-    undoUpsert: (path: string, content: string, bom: string, ending: string, hashes: string, resultContent: string, snapshotHash: string | null, transactionId: string | null, rawPre: string | null, lifecycle: string | null, fromPath: string | null, toPath: string | null, rawPost: string | null, createdDirs: string | null, anchorGeneration: number, updatedAt: number) => void;
+    undoUpsert: (path: string, content: string, bom: string, ending: string, hashes: string, resultContent: string, snapshotHash: string | null, transactionId: string | null, rawPre: string | null, anchorGeneration: number, updatedAt: number) => void;
     undoGet: (path: string) => Record<string, unknown> | undefined;
     undoDelete: (path: string) => void;
     undoGetTransaction: (transactionId: string) => Record<string, unknown>[];

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "dsh-hashline-edit",
-  "version": "0.2.0",
-  "description": "Hash-anchored read/apply_patch tools for DeepSeek Harness (dsh). Every line gets a unique 4-char hash (A-Za-z0-9) that stays stable across edits; apply_patch is the only file-mutation entry point and commits one patch batch per transaction. Undo persists across restarts.",
+  "version": "0.2.2",
+  "description": "Hash-anchored read/edit/undo_last_edit tools for DeepSeek Harness (dsh). Every line gets a unique 3- or 4-char hash (A-Za-z0-9, configurable) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "keywords": [
     "anchors",
-    "apply-patch",
     "coding-agent",
     "deepseek-harness",
     "dsh",
     "dsh-plugin",
+    "edit",
     "file-editing",
     "hash",
     "hash-anchored",
@@ -56,8 +56,17 @@
     "format:fix": "oxfmt .",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.dsh.json",
     "build": "node scripts/build-dsh.mjs",
+    "build:pi": "node scripts/build-dist.mjs",
     "prepublishOnly": "node scripts/build-dsh.mjs && pnpm run typecheck && pnpm run lint && pnpm run test:win",
     "canon:audit": "node scripts/canon-churn-audit.mjs",
+    "prompts:show": "node scripts/served-prompts.mjs",
+    "replay:read-expansion": "node scripts/read-expansion-replay.mjs",
+    "test:runtime": "node scripts/runtime-edge-test.mjs",
+    "verify:dist": "node scripts/verify-dist.mjs",
+    "verify:dist:mutations": "node scripts/verify-dist-mutations.mjs",
+    "measure:import": "node scripts/measure-import.mjs --max-ratio 0.75",
+    "smoke:install": "node scripts/install-smoke.mjs",
+    "prepare": "node scripts/prepare.mjs",
     "prepack": "node scripts/build-dsh.mjs",
     "audit": "pnpm audit --audit-level high --registry https://registry.npmjs.org/",
     "verify": "pnpm run lint && pnpm run format && pnpm run typecheck && pnpm run test:win:coverage"
@@ -65,6 +74,7 @@
   "dependencies": {
     "diff": "^8.0.2",
     "file-type": "^21.3.0",
+    "typebox": "^1.3.27",
     "unbash": "5.0.0",
     "xxhash-wasm": "^1.1.0"
   },
@@ -72,12 +82,14 @@
     "@babel/parser": "7.29.8",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
-    "@deepseek-ai/cordis": "4.0.6-alpha.2",
-    "@deepseek-ai/dsh-agent": "0.2.2-alpha.3",
-    "@deepseek-ai/dsh-fs": "0.2.2-alpha.3",
-    "@deepseek-ai/dsh-home-paths": "0.2.2-alpha.3",
-    "@deepseek-ai/dsh-sandbox": "0.2.2-alpha.3",
-    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-fs": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "*",
     "@semantic-release/git": "^11.0.1",
     "@semantic-release/github": "^12.0.9",
     "@semantic-release/npm": "^13.1.5",
@@ -97,7 +109,6 @@
     "web-tree-sitter": "0.27.1"
   },
   "engines": {
-    "dsh": ">=0.2.2-alpha.3 <0.2.3-0",
     "node": ">=24.0.0"
   },
   "packageManager": "pnpm@12.0.0",

package/prompts/edit-guidelines.md

@@ -0,0 +1,10 @@
+- edit: an `anchor` is the bare {{HASH_LEN}}-char hash (for example "{{ANCHOR_EXAMPLE}}"). A `HASH│content` line (for example `{{ANCHOR_EXAMPLE}}│    pass`) is a served row, and `│` separates the two. Copy only the {{HASH_LEN}} chars before `│` into `anchor_from`/`anchor_to`.
+- edit: give each item two anchors and exactly one payload. `file` is the text file. One item is one edit. Several items batch to that one file. Choose one payload field: `text` or `text_ref`. `at` is optional. A null in an optional field (`text`, `text_ref`, `at`, the top-level `mode`, `text_ref.file`) reads as absent. A null in a required field (`file`, `edits`, any anchor, `text_ref.mode`) is refused.
+- edit: `anchor_from`/`anchor_to` bound an inclusive range. In-place replaces both boundary lines. `before`/`after` insert at the boundary instead. Out-of-band writes (bash, scripts, formatters) bypass serve recording. When a served line changes, the refusal serves the current rows. Copy fresh anchors from it.
+- edit: `text` is plain file content. Join lines with `\n`. Use `""` to delete the range. The tool refuses a line that copies a served hash echo. `text` is verbatim, so include the indentation you want.
+- edit: place the payload with `at`. `"in-place"` (default) rewrites the range. `"before"`/`"after"` insert at its boundary and need a single-line resolved target. `text: ""` with before/after writes nothing (noop).
+- edit: `text_ref` `{anchor_from, anchor_to, mode}` writes the bytes of a served span into the target. `mode: "copy"` keeps the source. `mode: "cut"` removes those lines from the source. When `file` names another served file, both modes apply to that file's rows. A `cut` then removes the span there in the same call. `mode` is required. Prefer `text_ref` to reproduce served bytes exactly or to move them. Use `text` for content you author.
+- edit: an anchor is bound to the file that served it. The lease is (session, file, anchor). Copy `anchor_from`/`anchor_to` only from the served rows of the file the payload names. That is this file by default, or `text_ref.file` when it names another file.
+- edit: after success the diff serves fresh `HASH│content` rows: context rows and `+` rows. Copy new anchors from the diff for your next call. Verify that the diff matches your intended mutation.
+- edit: a `[MODEL] [W_*]` line in `content` is informational. The mutation was applied. A `[MODEL] [E_*]` line is your retry instruction or a rejection: follow it from the message alone. A `[MODEL]` line that presents `Current range (fresh read):` shows the current rows. Decide from them. A dimmed `[USER]` line in `details` is human info.
+- edit: batch independent ranges in one `edits` array. Inside it, every edit validates BEFORE the first rename, and any failure there writes nothing. A foreign `cut` writes its files in a fixed order, and a defeated rollback restores captured bytes or is repaired on the next run.

package/prompts/edit-snippet.md

@@ -0,0 +1 @@
+Edit a file range via `edit`: `{"file":file,"edits":[{"anchor_from":a,"anchor_to":b,"text":text}]}` — anchors are bare {{HASH_LEN}}-char hashes copied from served `HASH│content` from rows this file served this session. One payload per item: `text` is bare content (`""` deletes) or `text_ref` writes a served span (`"copy"` keeps source, `"cut"` removes it from this file or `file`). `at`: "in-place" (default), "before", "after". Chain from diff anchors.

package/prompts/edit.md

@@ -0,0 +1 @@
+Edit a range of lines in a text file via `edit`: `{ "file": file, "edits": [{ "anchor_from": a, "anchor_to": b, "text": text }, ...] }` (one file per call, or one per item `file`). Use rows this session served for the file: `read`, a diff, or a bash view. `anchor_from`/`anchor_to` are bare {{HASH_LEN}}-char HASH anchors. Copy the {{HASH_LEN}} chars before `│` in this file's served rows (lease (session, file, anchor)). One payload per item: `text` (`\n` joins lines, `""` deletes) or `text_ref` `{anchor_from, anchor_to, mode (required), file?}`, the bytes of a served span (`mode` `"copy"` keeps it, `"cut"` removes it). `file` names another served file. `at`: "in-place" (default), "before", "after". A null optional field reads as absent. `[MODEL] [E_*]` is your retry instruction. `[W_*]` is informational.

package/prompts/read-guidelines.md

@@ -1,6 +1,6 @@
-- read: call it only for information the tool never served you, such as content past the auto-read diff. A bash view or an auto-read already served the file, so apply_patch from those rows.
-- read: when you need several blocks or both boundaries of one replacement, put every range in ONE call. Use `{ file, windows: [{ offset, limit }] }`. Each window is served in that turn, so its anchors work in the same apply_patch call. A window can also be `{ around_anchor, radius }` to centre on a line this session already served. An anchor outside this session's served rows is omitted with an inline `[Window warning: ...]`.
+- read: call it only for information the tool never served you, such as content past the auto-read diff. A bash view or an auto-read already served the file, so edit from those rows.
+- read: when you need several blocks or both boundaries of one replacement, put every range in ONE call. Use `{ file, windows: [{ offset, limit }] }`. Each window is served in that turn, so its anchors work in the same edit. A window can also be `{ around_anchor, radius }` to centre on a line this session already served. An anchor outside this session's served rows is omitted with an inline `[Window warning: ...]`.
 - read: a requested window of 61 lines or fewer can widen to its enclosing block; overlapping or adjacent windows fold before this test. Caps are 80 lines for code and Markdown, 40 for plain text. Widened rows begin with `[widened <requested> -> <served>, <label>]`; above three requested windows the note is `[widened N windows: <ranges>]`. An over-cap Markdown section clamps and names `(section <extent>)`; over-cap code or plain text refuses with no note. `mode: "verbatim"` widens too, with no anchors.
-- read: when you will not apply_patch the file, pass `mode: "verbatim"` for plain content with no anchors. Examples are a config value, docs, a README, or skill content (a SKILL.md or any file in its directory). Omit `mode` when you intend to use the anchors with apply_patch, so the rows carry anchors.
-- read: send one file per call as `{ file, windows?, mode? }`, the same way `apply_patch` does. The single top-level `mode` applies to the file. To read several files, make parallel `read` calls.
+- read: when you will not edit the file, pass `mode: "verbatim"` for plain content with no anchors. Examples are a config value, docs, a README, or skill content (a SKILL.md or any file in its directory). Omit `mode` when you intend to edit, so the rows carry anchors.
+- read: send one file per call as `{ file, windows?, mode? }`, the same way `edit` does. The single top-level `mode` applies to the file. To read several files, make parallel `read` calls.
 - read: PNG/JPG images return as image attachments for multimodal models. Request one with `file` like any other file.

package/prompts/read.md

@@ -1 +1 @@
-Read one text file via `file`, with optional `windows` and top-level `mode`. To read several files, make parallel `read` calls. Served mode (default) returns each line as HASH│content with a 4-char alphanumeric hash. That hash is the `apply_patch` identity anchor, so copy only the 4 chars before `│`. Pass `mode: "verbatim"` for plain text with no anchors when you will not apply_patch. `mode: "verbatim"` is not capped by line budget. Name ranges with `windows`: `[{ offset, limit }]` (offset is 1-indexed, limit is a line count, maximum 16 windows) or `[{ around_anchor: "a1b2", radius: 10 }]` for a line this session served. When a page stops short, continue from the next unshown line with `windows: [{ offset, limit }]`. A requested window of 61 lines or fewer can widen to its enclosing block before serving; overlapping or adjacent windows fold before this test. Caps are 80 lines for code and Markdown, 40 for plain text. A widened page begins with `[widened <requested> -> <served>, <label>]`; more than three requested windows collapse to `[widened N windows: <ranges>]`. An over-cap Markdown section clamps to a cap-sized window and names `(section <extent>)`; an over-cap code or plain-text block refuses, serving the requested window. `mode: "verbatim"` widens the same way but adds no anchors. Inline `[...]` notices describe the served result, not file content. Empty files return `HASH│` (use an apply_patch identity hunk to insert). PNG/JPG/GIF/WebP return as image attachments for multimodal models. Binary and directory files are rejected. Hashes are file-scoped: an anchor is bound to the file it was served from.
+Read one text file via `file`, with optional `windows` and top-level `mode`. To read several files, make parallel `read` calls. Served mode (default) returns each line as HASH│content with a {{HASH_LEN}}-char alphanumeric hash. That hash is the `edit` anchor, so copy only the {{HASH_LEN}} chars before `│`. Pass `mode: "verbatim"` for plain text with no anchors when you will not edit. `mode: "verbatim"` is not capped by line budget. Name ranges with `windows`: `[{ offset, limit }]` (offset is 1-indexed, limit is a line count, maximum 16 windows) or `[{ around_anchor: "<anchor>", radius: 10 }]` for a line this session served. When a page stops short, continue from the next unshown line with `windows: [{ offset, limit }]`. A requested window of 61 lines or fewer can widen to its enclosing block before serving; overlapping or adjacent windows fold before this test. Caps are 80 lines for code and Markdown, 40 for plain text. A widened page begins with `[widened <requested> -> <served>, <label>]`; more than three requested windows collapse to `[widened N windows: <ranges>]`. An over-cap Markdown section clamps to a cap-sized window and names `(section <extent>)`; an over-cap code or plain-text block refuses, serving the requested window. `mode: "verbatim"` widens the same way but adds no anchors. Inline `[...]` notices describe the served result, not file content. Empty files return `HASH│` (edit to insert). PNG/JPG/GIF/WebP return as image attachments for multimodal models. Binary and directory files are rejected. Hashes are file-scoped: an anchor is bound to the file it was served from.

package/prompts/undo-last-edit-guidelines.md

@@ -1,2 +1,2 @@
-- undo_last_edit: reverts the most recent `apply_patch` batch that touched the file at `path`, and every member of that batch: text hunks plus file lifecycle actions (add/delete/move). The exception is a foreign `cut`: undo then restores the source file too. The file must still hold the edited bytes. An out-of-band write makes the call fail with `E_UNDO_STALE`, and the file stays byte-identical. Call it as soon as a result is bad.
-- undo_last_edit: a `write` to the file, or a later `apply_patch` batch, replaces the undo entry. A read, a bash view or an out-of-band write leaves the entry in place. An apply_patch result is bad when its diff shows `-HASH│` rows for lines you meant to keep. Examples are a closing brace, an import, or a declaration.
+- undo_last_edit: reverts the most recent `edit` call on the file at `path`, and every item of its `edits`. Its scope is the edited file. The exception is an edit that was a foreign `cut`: undo then restores the source file too. The file must still hold the edited bytes. An out-of-band write makes the call fail with `E_UNDO_STALE`, and the file stays byte-identical. Call it as soon as a result is bad.
+- undo_last_edit: a `write` to the file, or a later `edit`, replaces the undo entry. A read, a bash view or an out-of-band write leaves the entry in place. An edit is bad when its post-edit diff shows `-HASH│` rows for lines you meant to keep. Examples are a closing brace, an import, or a declaration.

package/prompts/undo-last-edit-snippet.md

@@ -1 +1 @@
-Undo the last `apply_patch` batch on the file at `path`
+Undo the last edit on the file at `path`

package/prompts/undo-last-edit.md

@@ -1 +1 @@
-Undo the last `apply_patch` batch that touched the file at `path`, reverting the whole batch — every text hunk plus file lifecycle actions (add/delete/move) — to its previous state. Use when an `apply_patch` produced incorrect results (e.g., wrong content, duplicated lines, broken syntax). The file must be unchanged since that batch.
+Undo the last edit on the file at `path`, reverting it to its previous state. Use when an edit produced incorrect results (e.g., wrong content, duplicated lines, broken syntax). The file must be unchanged since that edit.