dsh-hashline-edit 0.2.2 → 0.2.3

package/lib/types/src/hashline/alphabet.d.ts

@@ -3,9 +3,10 @@
  *
  * WHY an environment variable rather than a settings-file key: `alphabet.ts` is a zero-import leaf
  * and every shape, regex, bitset and capacity constant below is derived at module load, so the
- * width can only be a process-wide, load-time value. Switching it changes every served anchor; the
- * persisted store stays safe because the anchor generation (`hash-identity.ts`) folds the width in,
- * so a switch is a hard generation miss (re-read), never a cross-width hit.
+ * width can only be a process-wide, load-time value. The build bakes it via esbuild `define`
+ * (`__ANCHOR_WIDTH__`), so a shipped bundle carries a literal and never reads the environment; the
+ * anchor generation (`hash-identity.ts`) folds the width in, so a width switch is a hard generation
+ * miss (re-read), never a cross-width hit.
  */
 export declare const ANCHOR_WIDTH_ENV_VAR = "PI_BETTER_EDIT_ANCHOR_WIDTH";
 /**

package/lib/types/src/hashline/hash-identity.d.ts

@@ -61,23 +61,28 @@ export declare const HASH_PROBE_STRIDE: number;
  */
 export declare const CANON_VERSION = 3;
 /**
- * The file-scoped anchor-derivation generation (issue #20, ADR-0031; ADR-0020 for the width axis).
+ * ANCHOR_GENERATION 1 (issue #20, ADR-0031): the file-scoped anchor-derivation generation.
  * It covers exactly: (1) the width (`HASH_LEN`, `ALPHA`, `HASH_SPACE`/`USABLE_HASH_SPACE`);
  * (2) the (path, content) seeding (`fileBaseIndex` seeds xxh32 with the canonical absolute path,
  * `contentBaseIndex` is the explicit content-only fallback); (3) the all-digit reservation
  * (`DIGIT_CHARS`/`RESERVED_HASH_SPELLINGS`/`RESERVED_BITS` pre-marked in allocation); (4) the probe
  * stride (`HASH_PROBE_STRIDE`, coprime with both spaces). Bump it whenever any of those change.
  *
- * WHY it is a function of the width now: the width is a runtime switch (default 4, optional 3), so a
- * width change MUST flip the generation or a store written at one width could be read at another.
- * Width 4 stays generation 1 — the original persisted generation — so existing stores keep their
- * anchors across this change; width 3 gets generation 2, and any future width gets `100 + width`.
- *
- * WHY: single owner of the anchor-generation value — anchor-bearing artifacts (the undo/snapshot
+ * WHY: single owner of the anchor-generation literal — anchor-bearing artifacts (the undo/snapshot
  * generation gate and the open-time sweep) read this axis only, never `CANON_VERSION`; the snapshot
  * cache key carries both (`${CANON_VERSION}:${ANCHOR_GENERATION}:${checksum}`), so a canon-only change
  * misses the cache without invalidating anchor state while a generation change invalidates both.
  */
+/**
+ * The file-scoped anchor-derivation generation. It covers the width (`HASH_LEN`, `ALPHA`,
+ * `HASH_SPACE`/`USABLE_HASH_SPACE`), the (path, content) seeding, the all-digit reservation and the
+ * probe stride. Bump it whenever any of those change.
+ *
+ * WHY it is a function of the width: the width is a build-time switch (ADR-0020: default 4, optional
+ * 3), so a width change MUST flip the generation or a store written at one width could be read at
+ * another. Width 4 stays generation 1 — the original persisted generation — so existing stores keep
+ * their anchors; width 3 gets generation 2, and any future width gets `100 + width`.
+ */
 export declare function anchorGenerationFor(width: number): number;
 export declare const ANCHOR_GENERATION: number;
 export declare function canon(line: string): string;

package/lib/types/src/host-utils.d.ts

@@ -0,0 +1,63 @@
+/** Retained line budget, matching pi's `DEFAULT_MAX_LINES`. */
+export declare const DEFAULT_MAX_LINES = 2000;
+/** Retained byte budget, matching pi's `DEFAULT_MAX_BYTES` (50KB). */
+export declare const DEFAULT_MAX_BYTES: number;
+/** The truncation report the core's read page renders. */
+export interface TruncationResult {
+    /** The truncated content. */
+    content: string;
+    /** Whether truncation occurred. */
+    truncated: boolean;
+    /** Which limit was hit: `"lines"`, `"bytes"`, or `null` when nothing was cut. */
+    truncatedBy: "lines" | "bytes" | null;
+    /** Total number of lines in the original content. */
+    totalLines: number;
+    /** Total number of bytes in the original content. */
+    totalBytes: number;
+    /** Number of complete lines in the truncated output. */
+    outputLines: number;
+    /** Number of bytes in the truncated output. */
+    outputBytes: number;
+    /** Whether the last line was partially truncated (tail truncation only). */
+    lastLinePartial: boolean;
+    /** Whether the first line exceeded the byte limit (head truncation only). */
+    firstLineExceedsLimit: boolean;
+    /** The line limit that was applied. */
+    maxLines: number;
+    /** The byte limit that was applied. */
+    maxBytes: number;
+}
+/** The two independent limits a truncation call applies. */
+export interface TruncationOptions {
+    /** Maximum number of lines; defaults to {@link DEFAULT_MAX_LINES}. */
+    maxLines?: number;
+    /** Maximum number of bytes; defaults to {@link DEFAULT_MAX_BYTES}. */
+    maxBytes?: number;
+}
+/**
+ * Format bytes as a human-readable size (`512B`, `1.5KB`, `2.0MB`).
+ * @param bytes - the byte count to render.
+ * @returns the pi-compatible size label.
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Truncate content from the head (keep the first N lines / bytes).
+ *
+ * WHY: the read page's oversize and truncation warnings must agree with the pi
+ * implementation the rest of the contract was written against, so this is a
+ * faithful port including its two edge rules: complete lines only, and an
+ * over-long first line yields empty content with `firstLineExceedsLimit`.
+ * @param content - the text to truncate.
+ * @param options - the line and byte limits.
+ * @returns the truncation report.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Serialize file mutation operations that target the same file; different files still run
+ * in parallel. A faithful port of pi's queue so the core's cut transaction keeps its
+ * lock ordering guarantees under the dsh host.
+ * @param filePath - the file the mutation targets.
+ * @param run - the critical section to run once the path is free.
+ * @returns the critical section's result.
+ */
+export declare function withFileMutationQueue<T>(filePath: string, run: () => Promise<T>): Promise<T>;

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

@@ -0,0 +1,34 @@
+/** The internal payload vocabulary the mutation engine consumes; no wire schema lives here. */
+type SpanRef = {
+    anchor_from: string;
+    anchor_to: string;
+    file?: string;
+    mode: "copy" | "cut";
+};
+type EditMode = "general" | "literal";
+type Placement = "in-place" | "before" | "after";
+export type DesiredContent = {
+    kind: "literal";
+    text: string;
+} | {
+    kind: "reference";
+    span: SpanRef;
+    mode: "copy" | "cut";
+} | {
+    kind: "empty";
+};
+export type NormalizedEditItem = {
+    target: {
+        anchor_from: string;
+        anchor_to: string;
+    };
+    at: Placement;
+    payload: DesiredContent;
+    file?: string;
+};
+export type NormalizedEditRequest = {
+    file: string;
+    edits: NormalizedEditItem[];
+    mode?: EditMode;
+};
+export {};

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

@@ -1,8 +1,9 @@
-import type { NormalizedEditRequest } from "../payload-contract.js";
+import type { NormalizedEditRequest } from "./edit-request.js";
 import { buildBatchResult } from "../edit-response.js";
 import type { PipelineOptions, ProcessedEditFile } from "./types.js";
 export type { PipelineOptions, ProcessedEditFile };
 export declare function previewEdits(request: NormalizedEditRequest, cwd: string, options?: Omit<PipelineOptions, "noPersist">): Promise<ProcessedEditFile>;
+declare function runCorrelatedTransaction(writePlans: ProcessedEditFile[], sectionPlans: ProcessedEditFile[], options: PipelineOptions | undefined, sessionKey: string): Promise<BatchOutcome>;
 /** What one plan or committed batch reports: the primary file leads, every section rides the result. */
 interface BatchOutcome {
     result: string;
@@ -20,3 +21,9 @@ interface BatchOutcome {
 export declare function planEditTargets(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<ProcessedEditFile[] | undefined>;
 export declare function apply(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<BatchOutcome>;
 export declare function execEdits(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<ProcessedEditFile>;
+/**
+ * Visibility-only export of the correlated transaction for apply_patch's commit seam. The
+ * function body is the one the cut path already uses; apply_patch members carry an optional
+ * lifecycle action read by that body. No engine semantics change.
+ */
+export { runCorrelatedTransaction as commitTransaction };

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

@@ -7,10 +7,9 @@
 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;
@@ -32,6 +31,21 @@ 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
@@ -45,6 +59,26 @@ 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;
@@ -88,53 +122,9 @@ 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[];
     /**
-     * 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"`.
+     * 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.
      */
-    payloadMessage?: string;
-    /** SAFETY: User-facing diagnosis, never a model remedy — a GLOSSARY.md glossary term. */
-    cause?: RangeCause;
-    details?: {
-        code: DomainErrorCode;
-        cause: RangeCause;
-    };
+    lifecycle?: MemberLifecycle;
 }
-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/served-session/serve-render.d.ts

@@ -14,7 +14,13 @@ 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,7 +25,23 @@ 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;
@@ -33,7 +49,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, 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, lifecycle: string | null, fromPath: string | null, toPath: string | null, rawPost: string | null, createdDirs: 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.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.",
+  "version": "0.2.3",
+  "description": "Hash-anchored read/apply_patch 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; apply_patch is the only file-mutation entry point and commits one patch batch per transaction. Undo persists across restarts.",
   "keywords": [
     "anchors",
+    "apply-patch",
     "coding-agent",
     "deepseek-harness",
     "dsh",
     "dsh-plugin",
-    "edit",
     "file-editing",
     "hash",
     "hash-anchored",
@@ -56,17 +56,8 @@
     "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"
@@ -74,7 +65,6 @@
   "dependencies": {
     "diff": "^8.0.2",
     "file-type": "^21.3.0",
-    "typebox": "^1.3.27",
     "unbash": "5.0.0",
     "xxhash-wasm": "^1.1.0"
   },
@@ -82,14 +72,12 @@
     "@babel/parser": "7.29.8",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
-    "@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": "*",
+    "@deepseek-ai/cordis": "4.1.0",
+    "@deepseek-ai/dsh-agent": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-fs": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-home-paths": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-sandbox": "0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.2.2-rc.1",
     "@semantic-release/git": "^11.0.1",
     "@semantic-release/github": "^12.0.9",
     "@semantic-release/npm": "^13.1.5",
@@ -105,10 +93,19 @@
     "vite": "^8.3.5",
     "vitest": "^4.1.8"
   },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0",
+    "@deepseek-ai/dsh-agent": ">=0.2.2-rc.1 <0.2.3-0",
+    "@deepseek-ai/dsh-fs": ">=0.2.2-rc.1 <0.2.3-0",
+    "@deepseek-ai/dsh-home-paths": ">=0.2.2-rc.1 <0.2.3-0",
+    "@deepseek-ai/dsh-sandbox": ">=0.2.2-rc.1 <0.2.3-0",
+    "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1 <0.2.3-0"
+  },
   "optionalDependencies": {
     "web-tree-sitter": "0.27.1"
   },
   "engines": {
+    "dsh": ">=0.2.2-rc.1 <0.2.3-0",
     "node": ">=24.0.0"
   },
   "packageManager": "pnpm@12.0.0",

package/prompts/apply-patch-guidelines.md

@@ -0,0 +1,10 @@
+- apply_patch: one call = one transaction. Collect every related file change (code, tests, docs, config) into one patch; split only when an earlier RESULT must decide a later edit.
+- apply_patch: two addressing modes. Fragment mode (`@@` or `@@ <context>`) locates by exact content and needs no served state. Identity mode (`@@<a>` / `@@<a>-<b>`) targets rows this session served and never writes the old text back.
+- apply_patch: the character after `@@` selects the mode. `@@` followed immediately by exactly {{HASH_LEN}} anchor characters is identity mode; `@@` followed by a space is Codex context mode (`@@ <line>`); a bare `@@` starts the search at the file start. Any other token is a syntax rejection.
+- apply_patch: fragment mode must match exactly once. Zero or several hits reject and serve the candidate rows; add surrounding context to disambiguate, never guess.
+- apply_patch: identity mode accepts only `+` lines; an empty body deletes the span. A `-` or context line in an identity hunk, or body lines in a Copy/Cut hunk, rejects at admission with its patch line number.
+- apply_patch: every hunk resolves against the file as it was before the call; later windows begin after the previous hunk's end. Overlapping target ranges in one file reject the whole batch.
+- apply_patch: lifecycle joins the same transaction and undo. `*** Add File:` content lines all start with `+`; `*** Delete File:` removes the file; `*** Move to:` must immediately follow `*** Update File:` and renames before its hunks apply; an existing move target rejects.
+- apply_patch: a rejection writes nothing. Read the `- patch line N ([E_*], path): ...` lines, then use the immediately following `HASH│content` block — those are the current rows and anchors; retry directly without issuing a separate `read`.
+- apply_patch: a success starts with `Updated N files:` and ends with the changed lines' fresh anchors per file; use those anchors directly in the next identity hunk. `[W_*]` lines are informational.
+- apply_patch: paths are workspace-relative or workspace-absolute; `..`, `.git`, and symlink targets reject. Whole-file replacement is one `*** Update File:` identity hunk spanning every served line with `+` lines for the new content.

package/prompts/apply-patch.md

@@ -0,0 +1 @@
+Apply one Codex-format patch to one or more files in a single transaction: `{ input: string }`. `input` is the complete patch text: `*** Begin Patch` ... `*** End Patch`, with `*** Add File:`, `*** Delete File:`, `*** Update File:` (plus optional `*** Move to:`) and hunks addressed either by content (`@@` or `@@ <context>` with ` `/`-`/`+` lines) or by served anchors (`@@<a>` / `@@<a>-<b>` with `+` lines only). `*** Copy From:` / `*** Cut From:` copy or move a served span from another file. Every target validates before anything is written; a rejection changes nothing and returns the current rows with anchors. On success the result lists the changed files and the new anchors for the changed lines, so a follow-up call needs no `read`. To replace a whole file, use `*** Update File:` with one identity hunk spanning every served line and `+` lines for the new content.

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 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: 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: 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 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: 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: 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 {{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.
+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 `apply_patch` identity anchor, so copy only the {{HASH_LEN}} 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: "<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│` (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.

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

@@ -1,2 +1,2 @@
-- 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.
+- 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.

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

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

package/prompts/undo-last-edit.md

@@ -1 +1 @@
-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.
+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.