pi-readcache 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,8 @@
 # 🧠 pi-readcache
 
 [![pi coding agent](https://img.shields.io/badge/pi-coding%20agent-6f6bff?logo=terminal&logoColor=white)](https://pi.dev/)
-[![license](https://img.shields.io/npm/l/pi-mermaid.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/pi-readcache.svg)](https://www.npmjs.com/package/pi-readcache)
+[![license](https://img.shields.io/npm/l/pi-readcache.svg)](LICENSE)
 
 A pi extension that overrides the built-in `read` tool with hash-based, replay-aware caching.
 
@@ -22,7 +23,7 @@ When the extension is active, `read` may return:
 - unchanged marker (`mode: unchanged`)
 - unchanged range marker (`mode: unchanged_range`)
 - unified diff for full-file reads (`mode: diff`)
-- baseline fallback (`mode: full_fallback`)
+- baseline fallback (`mode: baseline_fallback`)
 
 Plus:
 - `/readcache-status` to inspect replay/coverage/savings
@@ -49,9 +50,9 @@ After installation, you can use pi normally. If pi is already running when you i
 
 | Action | Command | Expected result |
 |---|---|---|
-| Baseline read | `read src/foo.ts` | `mode: full` or `mode: full_fallback` |
+| Baseline read | `read src/foo.ts` | `mode: full` or `mode: baseline_fallback` |
 | Repeat read (no file change) | `read src/foo.ts` | `[readcache: unchanged, ...]` |
-| Range read | `read src/foo.ts:1-120` | `mode: full`, `full_fallback`, or `unchanged_range` |
+| Range read | `read src/foo.ts:1-120` | `mode: full`, `baseline_fallback`, or `unchanged_range` |
 | Inspect replay/cache state | `/readcache-status` | tracked scopes, replay window, mode counts, estimated savings |
 | Invalidate full scope | `/readcache-refresh src/foo.ts` | next full read re-anchors |
 | Invalidate range scope | `/readcache-refresh src/foo.ts 1-120` | next range read re-anchors |
@@ -62,9 +63,24 @@ After installation, you can use pi normally. If pi is already running when you i
 - Compaction is a strict replay barrier for trust reconstruction:
   - replay starts at the latest active `compaction + 1`.
   - pre-compaction trust is not used after that barrier.
-- First read after that barrier for a path/scope will re-anchor with baseline (`full`/`full_fallback`).
+- First read after that barrier for a path/scope will re-anchor with baseline (`full`/`baseline_fallback`).
 - For exact current file text, the assistant should still perform an actual `read` in current context.
 
+### Diff usefulness gate (why you sometimes get full content instead of a diff)
+
+For full-file reads, `mode: diff` is emitted only when the generated patch is clearly more useful than baseline text.
+
+Current defaults:
+- `MAX_DIFF_TO_BASE_RATIO = 0.9`
+  - if `diffBytes >= selectedBytes * 0.9`, diff is considered not useful and falls back to baseline (`mode: baseline_fallback`)
+- `MAX_DIFF_TO_BASE_LINE_RATIO = 0.85`
+  - if patch line count is greater than `selectedRequestedLines * 0.85`, diff is considered too large/noisy and falls back to baseline
+
+Why these defaults:
+- avoids near-full-file patch spam on high-churn edits
+- improves readability for the model versus very large hunks
+- keeps token savings meaningful when diff mode is used
+
 ---
 
 ## For extension developers (and curious cats)
@@ -88,7 +104,7 @@ flowchart TD
   F -- no --> G[mode=full, attach metadata]
   F -- yes + same hash --> H[mode=unchanged/unchanged_range]
   F -- yes + full scope + useful diff --> I[mode=diff]
-  F -- otherwise --> J[mode=full_fallback]
+  F -- otherwise --> J[mode=baseline_fallback]
   G --> K[persist object + overlay trust]
   H --> K
   I --> K
@@ -127,15 +143,15 @@ Rules:
 
 ## File map
 
-- `extension/index.ts` - extension entrypoint + lifecycle reset hooks
-- `extension/src/tool.ts` - `read` override decision engine
-- `extension/src/replay.ts` - replay reconstruction, trust transitions, overlay
-- `extension/src/meta.ts` - metadata/invalidation validators and extractors
-- `extension/src/commands.ts` - `/readcache-status`, `/readcache-refresh`, `readcache_refresh`
-- `extension/src/object-store.ts` - content-addressed storage (`.pi/readcache/objects`)
-- `extension/src/diff.ts` - unified diff creation + usefulness gating
-- `extension/src/path.ts` - path/range parsing and normalization
-- `extension/src/telemetry.ts` - replay window/mode/savings reporting
+- `index.ts` - extension entrypoint + lifecycle reset hooks
+- `src/tool.ts` - `read` override decision engine
+- `src/replay.ts` - replay reconstruction, trust transitions, overlay
+- `src/meta.ts` - metadata/invalidation validators and extractors
+- `src/commands.ts` - `/readcache-status`, `/readcache-refresh`, `readcache_refresh`
+- `src/object-store.ts` - content-addressed storage (`.pi/readcache/objects`)
+- `src/diff.ts` - unified diff creation + usefulness gating
+- `src/path.ts` - path/range parsing and normalization
+- `src/telemetry.ts` - replay window/mode/savings reporting
 
 ## Tool-override compatibility contract
 
@@ -147,7 +163,6 @@ Because this overrides built-in `read`, it must preserve:
 ## Development
 
 ```bash
-cd extension
 npm install
 npm run typecheck
 npm test

package/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ToolDefinition } from "@mariozechner/pi-coding-agent";
 import { registerReadcacheCommands } from "./src/commands.js";
 import { clearReplayRuntimeState, createReplayRuntimeState } from "./src/replay.js";
 import { pruneObjectsOlderThan } from "./src/object-store.js";
@@ -6,7 +6,7 @@ import { createReadOverrideTool } from "./src/tool.js";
 
 export default function (pi: ExtensionAPI): void {
 	const runtimeState = createReplayRuntimeState();
-	pi.registerTool(createReadOverrideTool(runtimeState));
+	pi.registerTool(createReadOverrideTool(runtimeState) as unknown as ToolDefinition);
 	registerReadcacheCommands(pi, runtimeState);
 
 	const clearCaches = (): void => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-readcache",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "🧠 Pi extension that optimizes read tool calls with replay-aware caching and compaction-safe trust reconstruction",
   "author": "Gurpartap Singh",
   "license": "MIT",

package/src/commands.ts

@@ -5,6 +5,7 @@ import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
 	ExtensionContext,
+	ToolDefinition,
 } from "@mariozechner/pi-coding-agent";
 import { type Static, Type } from "@sinclair/typebox";
 import { READCACHE_CUSTOM_TYPE, SCOPE_FULL, scopeRange } from "./constants.js";
@@ -50,7 +51,7 @@ function formatModeCounts(modeCounts: ReturnType<typeof collectReplayTelemetry>[
 		`unchanged=${modeCounts.unchanged}`,
 		`unchanged_range=${modeCounts.unchanged_range}`,
 		`diff=${modeCounts.diff}`,
-		`full_fallback=${modeCounts.full_fallback}`,
+		`baseline_fallback=${modeCounts.baseline_fallback}`,
 	].join(", ");
 }
 
@@ -324,5 +325,5 @@ export function registerReadcacheCommands(pi: ExtensionAPI, runtimeState: Replay
 		},
 	});
 
-	pi.registerTool(createReadcacheRefreshTool(pi, runtimeState));
+	pi.registerTool(createReadcacheRefreshTool(pi, runtimeState) as unknown as ToolDefinition);
 }

package/src/constants.ts

@@ -5,7 +5,8 @@ export const SCOPE_FULL = "full" as const;
 
 export const MAX_DIFF_FILE_BYTES = 2 * 1024 * 1024;
 export const MAX_DIFF_FILE_LINES = 12_000;
-export const MAX_DIFF_TO_BASE_RATIO = 1.0;
+export const MAX_DIFF_TO_BASE_RATIO = 0.9;
+export const MAX_DIFF_TO_BASE_LINE_RATIO = 0.85;
 
 export const DEFAULT_EXCLUDED_PATH_PATTERNS = [
 	".env*",

package/src/diff.ts

@@ -2,6 +2,7 @@ import { formatPatch, structuredPatch } from "diff";
 import {
 	MAX_DIFF_FILE_BYTES,
 	MAX_DIFF_FILE_LINES,
+	MAX_DIFF_TO_BASE_LINE_RATIO,
 	MAX_DIFF_TO_BASE_RATIO,
 } from "./constants.js";
 
@@ -11,6 +12,7 @@ export interface DiffLimits {
 	maxFileBytes: number;
 	maxFileLines: number;
 	maxDiffToBaseRatio: number;
+	maxDiffToBaseLineRatio: number;
 }
 
 export interface DiffComputation {
@@ -25,6 +27,7 @@ export const DEFAULT_DIFF_LIMITS: DiffLimits = {
 	maxFileBytes: MAX_DIFF_FILE_BYTES,
 	maxFileLines: MAX_DIFF_FILE_LINES,
 	maxDiffToBaseRatio: MAX_DIFF_TO_BASE_RATIO,
+	maxDiffToBaseLineRatio: MAX_DIFF_TO_BASE_LINE_RATIO,
 };
 
 function sanitizePathForPatch(pathDisplay: string): string {
@@ -125,6 +128,15 @@ export function isDiffUseful(
 	if (diffBytes === 0) {
 		return false;
 	}
+	if (diffBytes >= selectedBytes * limits.maxDiffToBaseRatio) {
+		return false;
+	}
+
+	const selectedRequestedLines = lineCount(selectedCurrentText);
+	const diffLines = lineCount(diffText);
+	if (diffLines > selectedRequestedLines * limits.maxDiffToBaseLineRatio) {
+		return false;
+	}
 
-	return diffBytes < selectedBytes * limits.maxDiffToBaseRatio;
+	return true;
 }

package/src/meta.ts

@@ -22,14 +22,23 @@ function isNonNegativeInteger(value: unknown): value is number {
 	return typeof value === "number" && Number.isInteger(value) && value >= 0;
 }
 
-function isReadCacheMode(value: unknown): value is ReadCacheMode {
-	return (
-		value === "full" ||
-		value === "unchanged" ||
-		value === "unchanged_range" ||
-		value === "diff" ||
-		value === "full_fallback"
-	);
+function normalizeReadCacheMode(value: unknown): ReadCacheMode | undefined {
+	if (value === "full") {
+		return "full";
+	}
+	if (value === "unchanged") {
+		return "unchanged";
+	}
+	if (value === "unchanged_range") {
+		return "unchanged_range";
+	}
+	if (value === "diff") {
+		return "diff";
+	}
+	if (value === "baseline_fallback") {
+		return "baseline_fallback";
+	}
+	return undefined;
 }
 
 function isReadCacheDebugReason(value: unknown): value is ReadCacheDebugV1["reason"] {
@@ -44,7 +53,8 @@ function isReadCacheDebugReason(value: unknown): value is ReadCacheDebugV1["reas
 		value === "diff_unavailable_or_empty" ||
 		value === "diff_not_useful" ||
 		value === "diff_payload_truncated" ||
-		value === "diff_emitted"
+		value === "diff_emitted" ||
+		value === "bypass_cache"
 	);
 }
 
@@ -111,48 +121,69 @@ export function isScopeKey(value: unknown): value is ScopeKey {
 	return Number.isInteger(start) && Number.isInteger(end) && start > 0 && end >= start;
 }
 
-export function isReadCacheMetaV1(value: unknown): value is ReadCacheMetaV1 {
+function parseReadCacheMetaV1(value: unknown): ReadCacheMetaV1 | undefined {
 	if (!isRecord(value)) {
-		return false;
+		return undefined;
 	}
 
 	if (value.v !== READCACHE_META_VERSION) {
-		return false;
+		return undefined;
 	}
 
 	if (typeof value.pathKey !== "string" || value.pathKey.length === 0) {
-		return false;
+		return undefined;
 	}
 
 	if (!isScopeKey(value.scopeKey)) {
-		return false;
+		return undefined;
 	}
 
 	if (typeof value.servedHash !== "string" || value.servedHash.length === 0) {
-		return false;
+		return undefined;
 	}
 
-	if (!isReadCacheMode(value.mode)) {
-		return false;
+	const mode = normalizeReadCacheMode(value.mode);
+	if (!mode) {
+		return undefined;
 	}
 
-	const requiresBaseHash = value.mode === "unchanged" || value.mode === "unchanged_range" || value.mode === "diff";
+	const requiresBaseHash = mode === "unchanged" || mode === "unchanged_range" || mode === "diff";
 	if (requiresBaseHash) {
 		if (typeof value.baseHash !== "string" || value.baseHash.length === 0) {
-			return false;
+			return undefined;
 		}
 	} else if (value.baseHash !== undefined && (typeof value.baseHash !== "string" || value.baseHash.length === 0)) {
-		return false;
+		return undefined;
 	}
 
-	return (
-		isPositiveInteger(value.totalLines) &&
-		isPositiveInteger(value.rangeStart) &&
-		isPositiveInteger(value.rangeEnd) &&
-		value.rangeEnd >= value.rangeStart &&
-		isNonNegativeInteger(value.bytes) &&
-		(value.debug === undefined || isReadCacheDebugV1(value.debug))
-	);
+	if (
+		!isPositiveInteger(value.totalLines) ||
+		!isPositiveInteger(value.rangeStart) ||
+		!isPositiveInteger(value.rangeEnd) ||
+		value.rangeEnd < value.rangeStart ||
+		!isNonNegativeInteger(value.bytes) ||
+		(value.debug !== undefined && !isReadCacheDebugV1(value.debug))
+	) {
+		return undefined;
+	}
+
+	return {
+		v: READCACHE_META_VERSION,
+		pathKey: value.pathKey,
+		scopeKey: value.scopeKey,
+		servedHash: value.servedHash,
+		...(typeof value.baseHash === "string" ? { baseHash: value.baseHash } : {}),
+		mode,
+		totalLines: value.totalLines,
+		rangeStart: value.rangeStart,
+		rangeEnd: value.rangeEnd,
+		bytes: value.bytes,
+		...(value.debug !== undefined ? { debug: value.debug } : {}),
+	};
+}
+
+export function isReadCacheMetaV1(value: unknown): value is ReadCacheMetaV1 {
+	return parseReadCacheMetaV1(value) !== undefined;
 }
 
 export function isReadCacheInvalidationV1(value: unknown): value is ReadCacheInvalidationV1 {
@@ -202,11 +233,7 @@ export function extractReadMetaFromSessionEntry(entry: SessionEntry): ReadCacheM
 	}
 
 	const candidate = message.details.readcache;
-	if (!isReadCacheMetaV1(candidate)) {
-		return undefined;
-	}
-
-	return candidate;
+	return parseReadCacheMetaV1(candidate);
 }
 
 export function extractInvalidationFromSessionEntry(entry: SessionEntry): ReadCacheInvalidationV1 | undefined {

package/src/replay.ts

@@ -6,20 +6,28 @@ import type {
 	ReadCacheInvalidationV1,
 	ReadCacheMetaV1,
 	ScopeKey,
+	ScopeRangeKey,
 	ScopeTrust,
 } from "./types.js";
 
 type SessionManagerView = ExtensionContext["sessionManager"];
 
+type RangeBlockersByPath = Map<string, Set<ScopeRangeKey>>;
+
 const OVERLAY_SEQ_START = 1_000_000_000;
 
+interface ReplayMemoEntry {
+	knowledge: KnowledgeMap;
+	blockedRangesByPath: RangeBlockersByPath;
+}
+
 interface OverlayState {
 	leafId: string | null;
 	knowledge: KnowledgeMap;
 }
 
 export interface ReplayRuntimeState {
-	memoByLeaf: Map<string, KnowledgeMap>;
+	memoByLeaf: Map<string, ReplayMemoEntry>;
 	overlayBySession: Map<string, OverlayState>;
 	nextOverlaySeq: number;
 }
@@ -41,6 +49,21 @@ function cloneKnowledgeMap(source: KnowledgeMap): KnowledgeMap {
 	return cloned;
 }
 
+function cloneRangeBlockersByPath(source: RangeBlockersByPath): RangeBlockersByPath {
+	const cloned: RangeBlockersByPath = new Map();
+	for (const [pathKey, scopes] of source.entries()) {
+		cloned.set(pathKey, new Set(scopes));
+	}
+	return cloned;
+}
+
+function cloneReplayMemoEntry(source: ReplayMemoEntry): ReplayMemoEntry {
+	return {
+		knowledge: cloneKnowledgeMap(source.knowledge),
+		blockedRangesByPath: cloneRangeBlockersByPath(source.blockedRangesByPath),
+	};
+}
+
 function getMemoKey(sessionId: string, leafId: string | null, boundaryKey: string): string {
 	return `${sessionId}:${leafId ?? "null"}:${boundaryKey}`;
 }
@@ -55,6 +78,36 @@ function ensureScopeMap(knowledge: KnowledgeMap, pathKey: string): Map<ScopeKey,
 	return created;
 }
 
+function isRangeScope(scopeKey: ScopeKey): scopeKey is ScopeRangeKey {
+	return scopeKey !== SCOPE_FULL;
+}
+
+function ensureRangeBlockerSet(blockedRangesByPath: RangeBlockersByPath, pathKey: string): Set<ScopeRangeKey> {
+	const existing = blockedRangesByPath.get(pathKey);
+	if (existing) {
+		return existing;
+	}
+	const created = new Set<ScopeRangeKey>();
+	blockedRangesByPath.set(pathKey, created);
+	return created;
+}
+
+function setRangeBlocker(blockedRangesByPath: RangeBlockersByPath, pathKey: string, scopeKey: ScopeRangeKey): void {
+	const scopes = ensureRangeBlockerSet(blockedRangesByPath, pathKey);
+	scopes.add(scopeKey);
+}
+
+function clearRangeBlocker(blockedRangesByPath: RangeBlockersByPath, pathKey: string, scopeKey: ScopeRangeKey): void {
+	const scopes = blockedRangesByPath.get(pathKey);
+	if (!scopes) {
+		return;
+	}
+	scopes.delete(scopeKey);
+	if (scopes.size === 0) {
+		blockedRangesByPath.delete(pathKey);
+	}
+}
+
 export function getTrust(knowledge: KnowledgeMap, pathKey: string, scopeKey: ScopeKey): ScopeTrust | undefined {
 	return knowledge.get(pathKey)?.get(scopeKey);
 }
@@ -95,6 +148,61 @@ function leafHasChildren(sessionManager: SessionManagerView, leafId: string | nu
 	return sessionManager.getEntries().some((entry) => entry.parentId === leafId);
 }
 
+function replaySnapshotFromBranch(branchEntries: SessionEntry[], startIndex: number): ReplayMemoEntry {
+	const knowledge: KnowledgeMap = new Map();
+	const blockedRangesByPath: RangeBlockersByPath = new Map();
+	const normalizedStart = Math.max(0, Math.min(startIndex, branchEntries.length));
+	let seq = 0;
+
+	for (let index = normalizedStart; index < branchEntries.length; index += 1) {
+		const entry = branchEntries[index];
+		if (!entry) {
+			continue;
+		}
+
+		const meta = extractReadMetaFromSessionEntry(entry);
+		if (meta) {
+			seq += 1;
+			applyReadMetaTransition(knowledge, meta, seq, blockedRangesByPath);
+			continue;
+		}
+
+		const invalidation = extractInvalidationFromSessionEntry(entry);
+		if (invalidation) {
+			applyInvalidation(knowledge, invalidation, blockedRangesByPath);
+		}
+	}
+
+	return {
+		knowledge,
+		blockedRangesByPath,
+	};
+}
+
+function getReplayMemoEntryForLeaf(
+	sessionManager: SessionManagerView,
+	runtimeState: ReplayRuntimeState,
+): { memoEntry: ReplayMemoEntry; sessionId: string; leafId: string | null } {
+	const sessionId = sessionManager.getSessionId();
+	const leafId = sessionManager.getLeafId();
+	const branchEntries = sessionManager.getBranch();
+	const boundary = findReplayStartIndex(branchEntries);
+	const memoKey = getMemoKey(sessionId, leafId, boundary.boundaryKey);
+
+	let memoEntry = runtimeState.memoByLeaf.get(memoKey);
+	if (!memoEntry) {
+		const replayMemo = replaySnapshotFromBranch(branchEntries, boundary.startIndex);
+		memoEntry = cloneReplayMemoEntry(replayMemo);
+		runtimeState.memoByLeaf.set(memoKey, memoEntry);
+	}
+
+	return {
+		memoEntry,
+		sessionId,
+		leafId,
+	};
+}
+
 export function createReplayRuntimeState(): ReplayRuntimeState {
 	return {
 		memoByLeaf: new Map(),
@@ -128,13 +236,21 @@ export function findReplayStartIndex(branchEntries: SessionEntry[]): ReplayBound
 	};
 }
 
-export function applyReadMetaTransition(knowledge: KnowledgeMap, meta: ReadCacheMetaV1, seq: number): void {
+export function applyReadMetaTransition(
+	knowledge: KnowledgeMap,
+	meta: ReadCacheMetaV1,
+	seq: number,
+	blockedRangesByPath?: RangeBlockersByPath,
+): void {
 	const { pathKey, scopeKey, servedHash, baseHash, mode } = meta;
 	const fullTrust = getTrust(knowledge, pathKey, SCOPE_FULL);
 	const rangeTrust = scopeKey === SCOPE_FULL ? undefined : getTrust(knowledge, pathKey, scopeKey);
 
-	if (mode === "full" || mode === "full_fallback") {
+	if (mode === "full" || mode === "baseline_fallback") {
 		setTrust(knowledge, pathKey, scopeKey, servedHash, seq);
+		if (blockedRangesByPath && isRangeScope(scopeKey)) {
+			clearRangeBlocker(blockedRangesByPath, pathKey, scopeKey);
+		}
 		return;
 	}
 
@@ -174,14 +290,24 @@ export function applyReadMetaTransition(knowledge: KnowledgeMap, meta: ReadCache
 	}
 }
 
-export function applyInvalidation(knowledge: KnowledgeMap, invalidation: ReadCacheInvalidationV1): void {
+export function applyInvalidation(
+	knowledge: KnowledgeMap,
+	invalidation: ReadCacheInvalidationV1,
+	blockedRangesByPath?: RangeBlockersByPath,
+): void {
 	const scopes = knowledge.get(invalidation.pathKey);
-	if (!scopes) {
-		return;
-	}
 
 	if (invalidation.scopeKey === SCOPE_FULL) {
 		knowledge.delete(invalidation.pathKey);
+		blockedRangesByPath?.delete(invalidation.pathKey);
+		return;
+	}
+
+	if (blockedRangesByPath && isRangeScope(invalidation.scopeKey)) {
+		setRangeBlocker(blockedRangesByPath, invalidation.pathKey, invalidation.scopeKey);
+	}
+
+	if (!scopes) {
 		return;
 	}
 
@@ -192,53 +318,40 @@ export function applyInvalidation(knowledge: KnowledgeMap, invalidation: ReadCac
 }
 
 export function replayKnowledgeFromBranch(branchEntries: SessionEntry[], startIndex: number): KnowledgeMap {
-	const knowledge: KnowledgeMap = new Map();
-	const normalizedStart = Math.max(0, Math.min(startIndex, branchEntries.length));
-	let seq = 0;
-
-	for (let index = normalizedStart; index < branchEntries.length; index += 1) {
-		const entry = branchEntries[index];
-		if (!entry) {
-			continue;
-		}
-
-		const meta = extractReadMetaFromSessionEntry(entry);
-		if (meta) {
-			seq += 1;
-			applyReadMetaTransition(knowledge, meta, seq);
-			continue;
-		}
-
-		const invalidation = extractInvalidationFromSessionEntry(entry);
-		if (invalidation) {
-			applyInvalidation(knowledge, invalidation);
-		}
-	}
-
-	return knowledge;
+	return replaySnapshotFromBranch(branchEntries, startIndex).knowledge;
 }
 
 export function buildKnowledgeForLeaf(
 	sessionManager: SessionManagerView,
 	runtimeState: ReplayRuntimeState,
 ): KnowledgeMap {
-	const sessionId = sessionManager.getSessionId();
-	const leafId = sessionManager.getLeafId();
-	const branchEntries = sessionManager.getBranch();
-	const boundary = findReplayStartIndex(branchEntries);
-	const memoKey = getMemoKey(sessionId, leafId, boundary.boundaryKey);
-
-	let replayKnowledge = runtimeState.memoByLeaf.get(memoKey);
-	if (!replayKnowledge) {
-		replayKnowledge = replayKnowledgeFromBranch(branchEntries, boundary.startIndex);
-		runtimeState.memoByLeaf.set(memoKey, cloneKnowledgeMap(replayKnowledge));
-	}
-
+	const { memoEntry, sessionId, leafId } = getReplayMemoEntryForLeaf(sessionManager, runtimeState);
 	const overlayState = ensureOverlayForLeaf(runtimeState, sessionId, leafId);
 	if (leafHasChildren(sessionManager, leafId)) {
 		overlayState.knowledge.clear();
 	}
-	return mergeKnowledge(replayKnowledge, overlayState.knowledge);
+	return mergeKnowledge(memoEntry.knowledge, overlayState.knowledge);
+}
+
+export function isRangeScopeBlockedByInvalidation(
+	sessionManager: SessionManagerView,
+	runtimeState: ReplayRuntimeState,
+	pathKey: string,
+	scopeKey: ScopeKey,
+): boolean {
+	if (!isRangeScope(scopeKey)) {
+		return false;
+	}
+
+	const { memoEntry, sessionId, leafId } = getReplayMemoEntryForLeaf(sessionManager, runtimeState);
+	const blockedScopes = memoEntry.blockedRangesByPath.get(pathKey);
+	if (!blockedScopes?.has(scopeKey)) {
+		return false;
+	}
+
+	const overlayState = ensureOverlayForLeaf(runtimeState, sessionId, leafId);
+	const overlayScopeTrust = overlayState.knowledge.get(pathKey)?.get(scopeKey);
+	return overlayScopeTrust === undefined;
 }
 
 export function overlaySet(

package/src/telemetry.ts

@@ -19,7 +19,7 @@ function createModeCounts(): ReadCacheModeCounts {
 		unchanged: 0,
 		unchanged_range: 0,
 		diff: 0,
-		full_fallback: 0,
+		baseline_fallback: 0,
 	};
 }
 

package/src/tool.ts

@@ -20,7 +20,13 @@ import { computeUnifiedDiff, isDiffUseful } from "./diff.js";
 import { buildReadCacheMetaV1 } from "./meta.js";
 import { hashBytes, loadObject, persistObjectIfAbsent } from "./object-store.js";
 import { normalizeOffsetLimit, parseTrailingRangeIfNeeded, scopeKeyForRange } from "./path.js";
-import { buildKnowledgeForLeaf, createReplayRuntimeState, overlaySet, type ReplayRuntimeState } from "./replay.js";
+import {
+	buildKnowledgeForLeaf,
+	createReplayRuntimeState,
+	isRangeScopeBlockedByInvalidation,
+	overlaySet,
+	type ReplayRuntimeState,
+} from "./replay.js";
 import { compareSlices, splitLines, truncateForReadcache } from "./text.js";
 import type {
 	ReadCacheDebugReason,
@@ -44,12 +50,18 @@ export const readToolSchema = Type.Object({
 	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
 	offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
 	limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+	bypass_cache: Type.Optional(
+		Type.Boolean({
+			description:
+				"If true, bypass readcache optimization for this call and return baseline read output for the requested scope",
+		}),
+	),
 });
 
 export type ReadToolParams = Static<typeof readToolSchema>;
 
 function buildReadDescription(): string {
-	return `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. Returns full text, unchanged marker, or unified diff. Treat output as authoritative for requested scope. Use readcache_refresh only when output is insufficient for correctness; it forces full baseline payload for file and increases repeated-read context usage.`;
+	return `Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. Returns full text, unchanged marker, or unified diff. Treat output as authoritative for requested scope. Set bypass_cache=true to force baseline output for this call only. If an edit fails because exact old text was not found, re-read the same path and scope with bypass_cache=true before retrying edit. Use readcache_refresh only when output is insufficient for correctness across calls; it invalidates trust for the selected scope until that scope is re-anchored by a baseline read, and increases repeated-read context usage.`;
 }
 
 function hasImageContent(result: AgentToolResult<ReadToolDetails | undefined>): boolean {
@@ -161,7 +173,11 @@ function buildDebugInfo(
 	};
 }
 
-function selectBaseTrust(pathKnowledge: Map<ScopeKey, ScopeTrust> | undefined, scopeKey: ScopeKey): ScopeTrust | undefined {
+function selectBaseTrust(
+	pathKnowledge: Map<ScopeKey, ScopeTrust> | undefined,
+	scopeKey: ScopeKey,
+	rangeScopeBlocked: boolean,
+): ScopeTrust | undefined {
 	if (!pathKnowledge) {
 		return undefined;
 	}
@@ -170,6 +186,10 @@ function selectBaseTrust(pathKnowledge: Map<ScopeKey, ScopeTrust> | undefined, s
 		return pathKnowledge.get(SCOPE_FULL);
 	}
 
+	if (rangeScopeBlocked) {
+		return undefined;
+	}
+
 	const exactTrust = pathKnowledge.get(scopeKey);
 	const fullTrust = pathKnowledge.get(SCOPE_FULL);
 	if (!exactTrust) {
@@ -288,9 +308,33 @@ export function createReadOverrideTool(runtimeState: ReplayRuntimeState = create
 			throwIfAborted(signal);
 			const pathKey = parsed.absolutePath;
 			const scopeKey = scopeKeyForRange(start, end, totalLines);
+
+			if (params.bypass_cache === true) {
+				const meta = buildReadcacheMeta(
+					pathKey,
+					scopeKey,
+					current.currentHash,
+					"full",
+					totalLines,
+					start,
+					end,
+					current.bytes.byteLength,
+					undefined,
+					buildDebugInfo(scopeKey, undefined, "bypass_cache"),
+				);
+				await persistAndOverlay(runtimeState, ctx, pathKey, scopeKey, current.currentHash, current.text);
+				return attachMetaToBaseline(baselineResult, meta);
+			}
+
 			const knowledge = buildKnowledgeForLeaf(ctx.sessionManager, runtimeState);
 			const pathKnowledge = knowledge.get(pathKey);
-			const baseHash = selectBaseTrust(pathKnowledge, scopeKey)?.hash;
+			const rangeScopeBlocked = isRangeScopeBlockedByInvalidation(
+				ctx.sessionManager,
+				runtimeState,
+				pathKey,
+				scopeKey,
+			);
+			const baseHash = selectBaseTrust(pathKnowledge, scopeKey, rangeScopeBlocked)?.hash;
 
 			if (!baseHash) {
 				const meta = buildReadcacheMeta(
@@ -346,7 +390,7 @@ export function createReadOverrideTool(runtimeState: ReplayRuntimeState = create
 					pathKey,
 					scopeKey,
 					current.currentHash,
-					"full_fallback",
+					"baseline_fallback",
 					totalLines,
 					start,
 					end,

package/src/types.ts

@@ -10,7 +10,7 @@ export interface ScopeTrust {
 	seq: number;
 }
 
-export type ReadCacheMode = "full" | "unchanged" | "unchanged_range" | "diff" | "full_fallback";
+export type ReadCacheMode = "full" | "unchanged" | "unchanged_range" | "diff" | "baseline_fallback";
 
 export type ReadCacheDebugReason =
 	| "no_base_hash"
@@ -23,7 +23,8 @@ export type ReadCacheDebugReason =
 	| "diff_unavailable_or_empty"
 	| "diff_not_useful"
 	| "diff_payload_truncated"
-	| "diff_emitted";
+	| "diff_emitted"
+	| "bypass_cache";
 
 export interface ReadCacheDebugV1 {
 	reason: ReadCacheDebugReason;