pi-better-edit

What is pi-better-edit? A high-precision file editing extension for pi-coding-agent that replaces volatile line numbers and token-wasting code echoes with immutable, content-addressed 3-character line hashes (szJ│code).

Core Philosophy: Local compute is free; the model's context window is the most precious resource. By shifting verification, snapshotting, and alignment to the host, pi-better-edit slashes output tokens by 40–60%, auto-rebases external file drift (e.g., Prettier, Git), and eliminates silent miswrites without forcing full-file re-reads.

Why You Need It

The 3 Fatal Editing Traps of Autonomous Coding Agents

File editing is the #1 point of failure for autonomous agents. Traditional tools break down in three distinct ways:

Core Pillars

1. 🪙 Token Economics (40–60% Context Savings)

• $O(R)$ Edit Payloads: The model emits only { "anchor_from": "a1b", "anchor_to": "c3d", "replace_with": "..." }, never regurgitating existing code.
• Self-Serving Diffs: Every applied edit returns fresh anchors in the post-edit diff — zero re-read roundtrips to chain edits.
• Disjoint Multi-Window Reads: Query up to 16 disjoint slices (windows: [{offset, limit}, ...]) in one turn instead of dumping 2,000 lines into context.
• Zero-Token Auto-Rebase: Non-conflicting shifts resolve locally via $O(m \log m)$ Patience LIS alignment — 0 tokens, 0 retries.
• Atomic Multi-Item Batches: Apply up to 32 same-file edits in one tool call; overlapping spans abort atomically before touching disk.

2. 🛡️ Resistance to External Writes (Drift & Concurrency)

• Auto-Formatter Immunity: Strips ASCII whitespace before hashing. Prettier, Black, and ESLint format-on-save passes never rotate anchors.
• Exterior Shift Auto-Rebase: External edits, git checkouts, or background processes outside the edit span rebase seamlessly without agent intervention.
• Fail-Closed Reject-and-Serve: Contested interior spans fail closed without disk corruption and immediately return fresh on-disk rows in the error ([E_STALE_RANGE], [E_UNVERIFIED_RANGE]) — recovering in exactly 1 turn.
• Session-Keyed Leases: Leases are isolated per session (served_leases), preventing cross-agent race conditions or state pollution.

3. 🎯 Zero Silent Miswrites (Formal MVCC)

• Decoupled Line Identity: Every line is tracked by an immutable, monotonic line_id in CAS snapshot storage, not ephemeral coordinates.
• Collision-Free Anchors: Coprime bitset probing ensures duplicate lines in a file receive distinct, unambiguous 3-character hashes.
• No Heuristic Guessing (ADR-0016): Retires fuzzy matching. If an anchor cannot be unambiguously resolved via lease lineage, it fails closed safely.
• Persisted Undo: undo_last_edit restores exact file content, BOM, line endings, and original anchors, persisting across session restarts.

Quick Start

Installation

# From npm
pi install npm:pi-better-edit

# From GitHub
pi install git:github.com/Rianico/pi-better-edit

# From local directory
pi install /path/to/pi-better-edit

Zero configuration required. pi automatically activates the extension on start.

How It Works

1. Read the file

read returns each line prefixed by a stable 3-character hash anchor:

ve7│function hello() {
szJ│  console.log("world");
kQm│}

2. Apply an edit

edit targets inclusive anchor bounds using the canonical named-object payload:

{
  "file": "src/main.ts",
  "edits": [
    {
      "anchor_from": "szJ",
      "anchor_to": "szJ",
      "replace_with": "  console.log('hi');\n"
    }
  ]
}

3. Receive the diff with fresh anchors

The tool applies the edit and returns a unified diff showing fresh anchors for subsequent edits—eliminating the need for follow-up read calls:

- szJ │   console.log("world");
+ a3m │   console.log('hi');
  kQm │ }

4. Batch multiple edits atomically

Batch up to 32 edits to the same file in a single transaction. If any edit fails or overlaps, none write:

{
  "file": "src/main.ts",
  "edits": [
    { "anchor_from": "a1b", "anchor_to": "a1b", "replace_with": "// Header comment\n" },
    { "anchor_from": "c3d", "anchor_to": "c3d", "replace_with": "  return true;\n" }
  ]
}

Systematic Architecture

pi-better-edit v2 replaces ad-hoc string matching and heuristic healing with a formal Multi-Version Concurrency Control (MVCC) architecture.

┌──────────────────────────────────────────────────────────────────────────────────┐
│                                STORAGE TIER                                      │
│  src/hash-store.ts & src/snapshot-store/                                         │
│  - file_snapshots: CAS snapshots (snapshot_id, path, snapshot_hash, line_count)  │
│  - line_lineage: Coordinate authority (snapshot_id, line_number) -> (line_id)    │
│  - line_id_counters: Monotonic integer block allocator per path                  │
│  - served_leases: Session-keyed immutable leases (session_id, path, anchor)      │
│  - file_undo: Snapshot-pinned undo history surviving restarts                    │
└────────────────────────────────────────┬─────────────────────────────────────────┘
                                         │
┌────────────────────────────────────────▼─────────────────────────────────────────┐
│                                SESSION TIER                                      │
│  src/served-session/session.ts                                                   │
│  - Leases: Granted on read, diff, rejection fresh-reads, and undo                │
│  - Immutability: Leases are strictly READ-ONLY during edit resolution            │
│  - Re-Serve Upsert: Atomic upsert updates leases when presentation changes       │
└────────────────────────────────────────┬─────────────────────────────────────────┘
                                         │
┌────────────────────────────────────────▼─────────────────────────────────────────┐
│                       RESOLUTION & REBASE TIER                                   │
│  src/hashline/lease-resolve.ts & src/hashline/served-verification.ts             │
│  - On-Demand CAS Materialization: Materializes current disk state                │
│  - Patience LIS Pin Backbone: O(m log m) non-crossing line alignment             │
│  - Minimal Displacement Tie-Breaking: Deterministic unique pairing               │
│  - Span Contiguity Gate: Asserts interior span is not torn                       │
└────────────────────────────────────────┬─────────────────────────────────────────┘
                                         │
┌────────────────────────────────────────▼─────────────────────────────────────────┐
│                                MUTATION TIER                                     │
│  src/mutation-engine/pipeline.ts & src/hashline/apply.ts                         │
│  - Working Buffer: Preceding delta rebase for multi-item batches                 │
│  - WAL Lineage Commit: Atomically commits final snapshot and updates leases      │
│  - Fail-Closed Intercepts: Rejections emit fresh read ranges                     │
└──────────────────────────────────────────────────────────────────────────────────┘

1. Immutable Line Identity & Leases

• Every line has an immutable surrogate key (line_id) allocated from a monotonic counter (line_id_counters).
• When lines are delivered to an agent via read, diffs, or fresh-read rejections, a session-scoped lease (served_leases) binds (session_id, file_path, anchor) -> line_id.
• During an edit, lease lookups are strictly read-only. An edit cannot re-stamp or guess a lease.

2. Multi-Version Snapshot Lineage

• Content-addressed CAS snapshots (file_snapshots) track each materialized file version.
• line_lineage maps each line coordinate to its immutable line_id, 32-bit canon hash, and verbatim presentation anchor.
• When disk content shifts externally, the tool pairs the latest snapshot ($S_{latest}$) with disk using Patience LIS alignment, preserving identities for surviving lines and allocating fresh IDs only for novel lines.

3. Patience LIS Pin Backbone ($O(m \log m)$)

• Uniquely matching anchor pins form candidate pairs.
• The engine computes the Longest Increasing Subsequence (LIS) via patience sorting in $O(m \log m)$ time.
• Multiple maximal LIS candidates are disambiguated by minimal total displacement ($\sum |p_i - c_i|$).
• Contested symmetric swaps (e.g. equal-length function swaps) or ambiguous duplicate blocks fail closed, marking affected lines as retired rather than guessing.

4. Working Buffer with Preceding Deltas

• Multi-item batches (edits: [e_0, e_1, ...]) resolve their baseline coordinates $s'_k$ in the current snapshot.
• Active in-memory buffer positions are computed by accounting strictly for preceding edits: $$\Delta_k = \sum_{j < k, s'{end, j} < s'{start, k}} \left( |R_j| - (s'{end, j} - s'{start, j} + 1) \right)$$
• If any two edit items overlap or nest, the batch aborts atomically ([E_BATCH_ABORT]) before modifying disk.

5. Unified Span Verification (ADR-0023)

• resolveLeasedEdit verifies the entire span against line_lineage before touching disk.
• Canon evidence is file-scoped and verified via 32-bit digests (canon_hash), eliminating duplicate plaintext storage.

Tools

Payload Contract

{
  "file": "src/example.ts",
  "edits": [
    {
      "anchor_from": "a1b",
      "anchor_to": "c3d",
      "replace_with": "const status = 'ready';\n"
    }
  ],
  "mode": "general"
}

• file: Path to the target text file (must be a file, never a directory).
• edits: Array of 1 to 32 edit items. An empty replace_with string deletes the targeted range.
• mode: "general" (default) refuses text containing served anchor prefixes; "literal" allows verbatim insertion of lines beginning with HASH│.

Interoperability with pi-lens

pi-better-edit composes with pi-lens diagnostics, formatting, and its read-before-edit guard:

• Read expansion: pi-lens widens a partial read (limit <= 100) to the enclosing symbol or markdown heading section (cap 300 lines, 200 ms budget, disabled by --no-lsp); a read without limit is never widened. Anchors always describe the rows actually served, so failure triage counts served rows rather than the requested window. To keep the requested window, pass limit > 100, read the whole file, or start pi with --no-lsp.
• Format and autofix: pi-lens' deferred agent_end format and autofix passes rewrite files outside the model's turn. A whitespace-only rewrite is absorbed by the whitespace-insensitive canon (ADR-0005), so anchors survive; a real fix rotates the affected anchors, and the next edit fails closed with [E_STALE_RANGE] or [E_TARGET_LOST] and serves the current rows.
• Guard compatibility: every served row (reads, multi-window reads, reject-and-serve payloads, post-edit diffs) is reported to pi-lens through its read bridge, so retries and chained edits satisfy the read-before-edit guard without manual re-reads.
• Overlapping reports are merged by pi-lens and are expected, not a bug.
• Opt-in: /pi-better-edit lens (auto by default when pi-lens is detected, else off; override via PI_BETTER_EDIT_LENS_BRIDGE=auto|on|off). Core editing never depends on pi-lens — with the bridge off or absent, behavior is unchanged.

Error and Warning Contract

pi-better-edit enforces a strict, machine-actionable diagnostic contract (ADR-0021):

• [E_*] indicates an edit rejection — nothing was written to disk.
• [W_*] indicates an applied mutation with an informational warning.
• Range-family rejections carry structured details.cause values (retirement, never-served, served-range staleness) — never-served on a leased span means a boundary row, because an unread interior between two leased boundaries is accepted (ADR-0024).

Domain Rejections ([E_*])

Applied Warnings ([W_*])

Comparison

Capability Comparison

Edge Case Behavior

Reproducible Benchmarks

All claims are backed by deterministic verification batteries and reproducible benchmarks.

1. Deterministic Tool Battery (27 Scenarios)

The tool battery executes 27 complex edge-case scenarios (concurrent exterior inserts, duplicate function blocks, interior modifications, symmetric reorders, foreign-anchor isolation, BOM preservation, and batch interactions) without LLM sampling:

Reproduce locally:

pnpm run eval

2. Practical Coding-Agent Benchmark

Measures a realistic refactoring workflow in pi with model thinking enabled (opencode-go/gpt-5.6-luna), testing recovery from external drift:

Reproduce locally:

pnpm run benchmark:practical

3. Theoretical Envelope Savings

Measures raw payload serialization overhead across a pinned 12-edit corpus:

• Single edit: -40.0% token overhead vs str_replace.
• Multi-item batch: -42.7% token overhead vs str_replace.

Reproduce locally:

pnpm run benchmark:tokens

4. Independent Benchmark: Explicit Edit Benchmark

Explicit Edit Benchmark is an independent, community-run dataset that scores harnesses and Pi editing extensions on the same 226 byte-exact edit tasks (replacements, insertions, deletions, moves, copies, unicode, large files). It is maintained by alexshpunt, not by this project, and every observation ships with its configuration.

Scope. That arm is pinned to pi-better-edit@1.7.0 — the retired 1.x heuristic era — so the score describes the predecessor architecture, not the MVCC v2 line. It updates here when the benchmark pin moves to 2.x.

• Explorer, filtered to pi-better-edit
• Raw observations
• Contribute a run: npm run benchmark:extension:submit -- --extension pi-better-edit --auth-file ~/.pi/agent/auth.json

How Anchors Work

1. Whitespace Canonicalization: Each line is stripped of ASCII whitespace ([ \t\r\n]) before hashing. External formatting passes (prettier, black, eslint --fix) do not alter line hashes. Token-level edits (quotes, semicolons, variable names) rotate the hash.
2. xxHash32 & Base62 Space: Canonical lines are hashed using xxHash32 and mapped to 3-character base62 strings (A-Za-z0-9), providing $62^3 = 238,328$ unique anchors.
3. Collision-Free Coprime Probing: When duplicate lines occur in a file, collision resolution probes using a stride coprime to the hash space ($62^2 + 62 + 1 = 3,907$). Every line in a file receives a unique anchor.
4. SQLite WAL CAS Storage: Line hashes and snapshots are persisted in ~/.config/pi-better-edit/hash-store.sqlite (honoring XDG_CONFIG_HOME). Snapshot retention is governed by proportional LRU vacuuming under a 50MB budget.

Upgrading from 1.x

Version 2.0 represents a major architectural upgrade from heuristic healing to formal MVCC:

1. Heuristic Healing Deleted (ADR-0016): Heuristic guessing of relocated anchors (tryHealOrphanedSpan) is completely removed to eliminate silent miswrites on duplicate code.
2. Boundary Rule Replaces E_UNSERVED_RANGE (ADR-0020): The old E_UNSERVED_RANGE code is retired. If one boundary lease is retired while the other survives unshifted, the tool emits [E_UNVERIFIED_RANGE] with a fresh read. If both bounds are lost, it emits [E_TARGET_LOST].
3. Unified Diagnostic Contract (ADR-0021): Rejections use [E_*]; successful mutations with caveats use [W_*]. Structured diagnoses live in details.cause.
4. Additive Store Migration: The SQLite schema migrates additively from version 6 to 7. Existing project files are untouched.

Development

# Install dependencies
pnpm install

# Run unit and integration tests
pnpm test

# Run quality checks
pnpm run lint
pnpm run format
pnpm run typecheck

# Run evaluation batteries
pnpm run eval

License

MIT

Acknowledgments

• Can Bölük for seminal insights on The Harness Problem.
• @oh-my-pi/hashline by can1357 for pioneering the hashline patch concept.
• pi-hashline-edit by RimuruW and pi-hashline-edit-pro by YuGiMob for foundational agent extension designs.