@miller-tech/uap 2.11.0 → 2.16.2

package/dist/delivery/agentic-executor.d.ts

@@ -42,26 +42,6 @@ export declare function editDiagnosticsEnabled(): boolean;
  * Which way that trades is model-dependent, so it is measured, not asserted.
  */
 export declare function readWindowBytes(): number;
-/**
- * One window of a file, plus an honest statement of what was left out.
- *
- * `read_file` used to return `contents.slice(0, readWindowBytes())` and say
- * nothing about it. On a big file that is a trap with no exit: the model asks
- * for the file, receives the first 8 KB, and has no way to learn that the rest
- * exists or how to reach it.
- *
- * Measured live on 2026-08-11 (cognition-engine, run …T015944): the mission was
- * "replace the 6 lateral joins in setup.sql at lines 607, 803, 861, 928, 1047,
- * 1101". setup.sql is 246,583 bytes / 8,025 lines, so the window ended at line
- * 270 — 3.2% of the file, and ALL SIX target lines were unreachable. The model
- * read that same 8 KB 76 times and listed directories 133 more, across 439
- * rounds and 2h55m, before the run was killed. It was not confused; it was
- * hunting for text the tool would never return.
- *
- * So: `offset` to move the window, and a trailer that names the range, the
- * total, and the exact call for the next chunk. The trailer matters more than
- * the parameter — a truncation nobody is told about cannot be worked around.
- */
 export declare function readFileWindow(contents: string, opts?: {
     offset?: number;
     windowBytes?: number;
@@ -676,14 +656,81 @@ export declare function readRoundsEnv(name: string, fallback: number): number;
  * the operator just tried to disable stayed on at its default. Split rather
  * than loosened, so round thresholds keep rejecting 0.
  */
-export declare function readCountEnv(name: string, fallback: number): number;
+export declare function readCountEnv(name: string, fallback: number, env?: NodeJS.ProcessEnv): number;
 export declare function newReadCache(): ReadCache;
+/**
+ * Content-hash de-duplication for read_file results (Harness-Loop-Graph state
+ * hashing). The ReadCache above decides whether a read is a REPEAT; this store
+ * decides whether the repeat's RESULT can be collapsed to a compact reference.
+ * The hash is computed from the bytes just read off disk — the saving is in
+ * the result handed back to the model, never in skipped I/O, so an external
+ * modification between reads is caught by the hash itself and always serves
+ * fresh content.
+ *
+ * The reference is served ONLY when this exact window was already served IN
+ * THE CURRENT CONVERSATION with an identical hash. v1.148.21 served
+ * "UNCHANGED — act on what you have" unconditionally and deadlocked runs (76
+ * re-reads, 64 nudges, zero writes in 36 minutes — see
+ * test/delivery/dedup-serves-content.test.ts): a model that no longer HAS the
+ * content cannot act on a pointer to it. Each turn starts a fresh conversation
+ * (runTurn rebuilds `messages`, and messages are never pruned mid-turn — the
+ * context budget stop fires first), so the run-level entry survives the turn
+ * boundary but `served` does not: the first read of a turn always pays full
+ * content, only repeats within that same turn collapse.
+ */
+export interface StateHashEntry {
+    sha256: string;
+    bytes: number;
+    round: number;
+    turn: number;
+}
+export interface StateHashStore {
+    /** Run-level: `${absPath}@${offsetLine}` → first-seen hash metadata. */
+    entries: Map<string, StateHashEntry>;
+    /**
+     * Conversation-level: windows whose full content the CURRENT turn has
+     * already received. Cleared at every turn open — see the block above.
+     */
+    served: Set<string>;
+}
+/** Stable prefix so the call site can recognise a reference (and not double-nudge it). */
+export declare const STATE_HASH_REF_PREFIX = "[unchanged:";
+/** Below this many bytes, re-sending the content is cheaper than the reference to it. */
+export declare const STATE_HASH_DEFAULT_MIN_BYTES = 1024;
+export declare function newStateHashStore(): StateHashStore;
+/** On by default; UAP_DELIVER_STATE_HASH=0 disables, same env style as the other deliver rails. */
+export declare function stateHashEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function stateHashMinBytes(env?: NodeJS.ProcessEnv): number;
+export declare function isStateHashReference(result: string): boolean;
+/**
+ * Record the hash of the bytes just read and, when this window was already
+ * served to this conversation with an identical hash, return the compact
+ * reference to substitute for the full result. Returns null when full content
+ * must be served — first sight of the window, a hash change, below the size
+ * floor, or content this conversation has never received.
+ */
+export declare function stateHashReference(store: StateHashStore, abs: string, rel: string, content: string, offsetLine: number, round: number, turn: number): string | null;
+/** Mark a window's full content as served to the current conversation. */
+export declare function markStateHashServed(store: StateHashStore, abs: string, offsetLine: number): void;
+/**
+ * A successful write/edit invalidates every recorded window of the path. The
+ * store is deliberately NOT refreshed with the new hash here: the model has
+ * never been SHOWN the post-write bytes (edit_file's whitespace-tolerant match
+ * can land text that differs from what it sent), so the next read must serve
+ * full content and re-record — a refreshed hash would serve a compact
+ * reference to bytes the model never received.
+ */
+export declare function invalidateStateHash(store: StateHashStore, abs: string): void;
 /**
  * Returns a terse steer when this exact read was already served and nothing has
  * changed since; null when the call should run normally.
  */
 export declare function repeatReadNote(cache: ReadCache, projectRoot: string, name: string, args: Record<string, unknown>, round: number): string | null;
-export declare function runTool(projectRoot: string, name: string, args: Record<string, unknown>, bashTimeoutMs: number, protectedFiles: ReadonlySet<string>, protectGateConfigs: boolean, allowBash: boolean, contractFiles?: ReadonlySet<string>, sweep?: BashSweep, protectIac?: boolean, writeLedger?: Set<string>): string;
+export declare function runTool(projectRoot: string, name: string, args: Record<string, unknown>, bashTimeoutMs: number, protectedFiles: ReadonlySet<string>, protectGateConfigs: boolean, allowBash: boolean, contractFiles?: ReadonlySet<string>, sweep?: BashSweep, protectIac?: boolean, writeLedger?: Set<string>, stateHash?: {
+    store: StateHashStore;
+    round: number;
+    turn: number;
+}): string;
 /**
  * After a Rust-relevant write, run an incremental `cargo check` and return a
  * compact feedback note for the tool result ('' when not applicable). Errors

package/dist/delivery/agentic-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentic-executor.d.ts","sourceRoot":"","sources":["../../src/delivery/agentic-executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agentic-executor.d.ts","sourceRoot":"","sources":["../../src/delivery/agentic-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,OAAO,EAOL,KAAK,SAAS,EAEf,MAAM,iBAAiB,CAAC;AAKzB;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAKxC;AAgCD,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,MAAM,CAwCR;AAED,+DAA+D;AAC/D,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/D,MAAM,CA6BR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAA8B,GACvC,MAAM,CAWR;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,IAAI,MAAM,CAK7C;AA8ED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kEAAkE;IAClE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAeD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAE1E;AASD;;;;;;oEAMoE;AACpE,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAEhF;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,QAGvC,CAAC;AAEL;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,KAAK,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAgC,GACzD,OAAO,CAaT;AAED,QAAA,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqID,CAAC;AA2BX;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAmC5F;AA0CD,gFAAgF;AAChF,wBAAgB,gCAAgC,IAAI,OAAO,CAE1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CA0Bf;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0F/E;AAKD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkDjF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB3F;AAsBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBlG;AAUD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CASf;AAeD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAgBnG;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AA6BD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ1F;AAqCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,GAAG,CACP,MAAM,EACN;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CACjF,CAAC;IACF;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,MAAM,CAAC;AAmBrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAI,GACb;IACD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;CACtB,CAuDA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAuC,GAC/D,MAAM,GAAG,SAAS,CA0EpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAMR;AAED,wBAAgB,YAAY,IAAI,SAAS,CAExC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACrC;;;OAGG;IACH,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACrB;AAED,0FAA0F;AAC1F,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAEnD,yFAAyF;AACzF,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE9E;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE9E;AAMD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAqBf;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAGhG;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAO5E;AAWD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CAsCf;AAED,wBAAgB,OAAO,CACrB,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,EACnC,kBAAkB,EAAE,OAAO,EAC3B,SAAS,EAAE,OAAO,EAClB,aAAa,GAAE,WAAW,CAAC,MAAM,CAAa,EAI9C,KAAK,GAAE,SAA2B,EAClC,UAAU,GAAE,OAAe,EAI3B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAGzB,SAAS,CAAC,EAAE;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjE,MAAM,CAojBR;AAED;;;;;GAKG;AACH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAKhE;AAsCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CA0B3E;AAYD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,OAAO,GAChB,OAAO,GAAG,SAAS,CAGrB;AAyFD;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,sBAAsB,GAC3B,YAAY,CAqhBd;AAED;;;;GAIG;AAEH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB3E;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAIxD"}

package/dist/delivery/agentic-executor.js

@@ -23,6 +23,7 @@ import { normalizeToolPath } from './path-normalize.js';
 import { generationHeartbeatMs, startGenerationTicker } from './heartbeat.js';
 import { withModelSlot, recordModelSuccess, recordModelExhaustion, isExhaustionError } from '../utils/model-slot-lease.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync, rmSync } from 'fs';
+import { createHash } from 'crypto';
 import { join, dirname, resolve, relative, isAbsolute } from 'path';
 import { fetchModelWithRetry, isEndpointUnreachable, ENDPOINT_UNREACHABLE, TRANSIENT_HTTP_STATUSES } from '../models/long-fetch.js';
 import { resolveRequestCredential } from '../models/openai-compat-client.js';
@@ -87,6 +88,13 @@ const DEFAULT_READ_WINDOW_BYTES = 8_000;
  * total, and the exact call for the next chunk. The trailer matters more than
  * the parameter — a truncation nobody is told about cannot be worked around.
  */
+/**
+ * Prefix of the past-EOF note readFileWindow returns when the window starts
+ * beyond the last line. The read_file tool handler keys off this exact
+ * prefix: a past-EOF read served NO content, so it must not mark the window
+ * as served to the state-hash conversation set.
+ */
+const PAST_EOF_NOTE_PREFIX = 'NOTE: offset ';
 export function readFileWindow(contents, opts = {}) {
     const windowBytes = Math.max(1, opts.windowBytes ?? readWindowBytes());
     const lines = contents.split('\n');
@@ -97,7 +105,7 @@ export function readFileWindow(contents, opts = {}) {
     const rawOffset = Number(opts.offset);
     const startLine = Number.isFinite(rawOffset) ? Math.max(1, Math.trunc(rawOffset)) : 1;
     if (startLine > totalLines) {
-        return (`NOTE: offset ${startLine} is past the end of ${opts.path ?? 'the file'} ` +
+        return (`${PAST_EOF_NOTE_PREFIX}${startLine} is past the end of ${opts.path ?? 'the file'} ` +
             `(${totalLines} lines). Read from an earlier line.`);
     }
     const from = lines.slice(startLine - 1);
@@ -1328,8 +1336,8 @@ export function readRoundsEnv(name, fallback) {
  * the operator just tried to disable stayed on at its default. Split rather
  * than loosened, so round thresholds keep rejecting 0.
  */
-export function readCountEnv(name, fallback) {
-    const raw = process.env[name];
+export function readCountEnv(name, fallback, env = process.env) {
+    const raw = env[name];
     if (raw === undefined || raw.trim() === '')
         return fallback;
     const n = Number(raw.trim());
@@ -1340,6 +1348,78 @@ export function readCountEnv(name, fallback) {
 export function newReadCache() {
     return { seen: new Map(), nextSeq: 1 };
 }
+/** Stable prefix so the call site can recognise a reference (and not double-nudge it). */
+export const STATE_HASH_REF_PREFIX = '[unchanged:';
+/** Below this many bytes, re-sending the content is cheaper than the reference to it. */
+export const STATE_HASH_DEFAULT_MIN_BYTES = 1024;
+export function newStateHashStore() {
+    return { entries: new Map(), served: new Set() };
+}
+/** On by default; UAP_DELIVER_STATE_HASH=0 disables, same env style as the other deliver rails. */
+export function stateHashEnabled(env = process.env) {
+    return env.UAP_DELIVER_STATE_HASH !== '0';
+}
+export function stateHashMinBytes(env = process.env) {
+    return readCountEnv('UAP_DELIVER_STATE_HASH_MIN_BYTES', STATE_HASH_DEFAULT_MIN_BYTES, env);
+}
+function stateHashKey(abs, offsetLine) {
+    return `${abs}@${offsetLine}`;
+}
+export function isStateHashReference(result) {
+    return result.startsWith(STATE_HASH_REF_PREFIX);
+}
+/**
+ * Record the hash of the bytes just read and, when this window was already
+ * served to this conversation with an identical hash, return the compact
+ * reference to substitute for the full result. Returns null when full content
+ * must be served — first sight of the window, a hash change, below the size
+ * floor, or content this conversation has never received.
+ */
+export function stateHashReference(store, abs, rel, content, offsetLine, round, turn) {
+    if (!stateHashEnabled())
+        return null;
+    const bytes = Buffer.byteLength(content, 'utf-8');
+    if (bytes < stateHashMinBytes())
+        return null;
+    const key = stateHashKey(abs, offsetLine);
+    const sha256 = createHash('sha256').update(content, 'utf-8').digest('hex');
+    const prior = store.entries.get(key);
+    if (!prior || prior.sha256 !== sha256) {
+        // New window or CHANGED content: refresh the stored hash. Writes also
+        // invalidate eagerly (see invalidateStateHash), but an edit that happened
+        // outside the write tools — run_bash, another process — is caught here,
+        // by the hash itself.
+        store.entries.set(key, { sha256, bytes, round, turn });
+        return null;
+    }
+    if (!store.served.has(key))
+        return null;
+    return (`${STATE_HASH_REF_PREFIX} sha256:${sha256.slice(0, 12)}… ${rel} is unchanged since ` +
+        `turn ${prior.turn} round ${prior.round} (${bytes} bytes) — that content is already in this ` +
+        'conversation; act on it instead of re-reading. For a different region, call read_file with an offset.]');
+}
+/** Mark a window's full content as served to the current conversation. */
+export function markStateHashServed(store, abs, offsetLine) {
+    if (!stateHashEnabled())
+        return;
+    store.served.add(stateHashKey(abs, offsetLine));
+}
+/**
+ * A successful write/edit invalidates every recorded window of the path. The
+ * store is deliberately NOT refreshed with the new hash here: the model has
+ * never been SHOWN the post-write bytes (edit_file's whitespace-tolerant match
+ * can land text that differs from what it sent), so the next read must serve
+ * full content and re-record — a refreshed hash would serve a compact
+ * reference to bytes the model never received.
+ */
+export function invalidateStateHash(store, abs) {
+    for (const key of [...store.entries.keys()]) {
+        if (key === abs || key.startsWith(`${abs}@`)) {
+            store.entries.delete(key);
+            store.served.delete(key);
+        }
+    }
+}
 /** mtime of a path, or null when it does not exist / is unreadable. */
 function mtimeOf(p) {
     try {
@@ -1400,7 +1480,10 @@ sweep = disabledSweep(), protectIac = false,
 // Run-scoped write ledger (see AgenticExecutorOptions.writeLedger). Recorded
 // at the actual writeFileSync sites — NOT via the sweep's `authorised` map,
 // which is a no-op when bash is disabled, exactly when the ledger matters.
-writeLedger) {
+writeLedger, 
+// Content-hash dedup context (see stateHashReference). Optional — callers
+// that omit it (tests, one-off dispatches) simply get no result collapsing.
+stateHash) {
     let pathNote = '';
     // Contain/repair garbled tool-call paths against the known project root before
     // any filesystem op — the small model mangles prefixes/subdirs and the write
@@ -1443,7 +1526,32 @@ writeLedger) {
                 return (`NOTE: '${String(args.path)}' is a DIRECTORY, not a file — use list_dir for it. ` +
                     `Its contents:\n${entries}`);
             }
-            return readFileWindow(readFileSync(abs, 'utf-8'), {
+            const fullContent = readFileSync(abs, 'utf-8');
+            // Content-hash dedup: the bytes are already read (no I/O saved — that is
+            // what keeps an external edit detectable); what a repeat saves is the
+            // full RESULT. Only a window this conversation has already received,
+            // unchanged, collapses to a reference — see stateHashReference.
+            if (stateHash) {
+                const offsetLine = Number.isFinite(Number(args.offset))
+                    ? Math.max(1, Math.trunc(Number(args.offset)))
+                    : 1;
+                const ref = stateHashReference(stateHash.store, abs, String(args.path), fullContent, offsetLine, stateHash.round, stateHash.turn);
+                if (ref)
+                    return ref;
+                const result = readFileWindow(fullContent, {
+                    offset: args.offset,
+                    path: String(args.path),
+                });
+                // Mark served ONLY when the window actually returned content. A
+                // past-EOF read gets the "offset past the end" note — no bytes — so
+                // recording it would let a repeat serve a reference claiming content
+                // the model never received is "already in this conversation".
+                if (!result.startsWith(PAST_EOF_NOTE_PREFIX)) {
+                    markStateHashServed(stateHash.store, abs, offsetLine);
+                }
+                return result;
+            }
+            return readFileWindow(fullContent, {
                 offset: args.offset,
                 path: String(args.path),
             });
@@ -1603,6 +1711,9 @@ writeLedger) {
             writeFileSync(abs, String(args.content ?? ''), 'utf-8');
             recordAuthorisedWrite(sweep, rel, String(args.content ?? ''));
             writeLedger?.add(rel);
+            // The write succeeded: every recorded read of this path is now stale.
+            if (stateHash)
+                invalidateStateHash(stateHash.store, abs);
             // Per-write compile feedback for Rust: without it, a weak model writes
             // whole turns of code against types it invented, and the turn-end gate
             // reports an avalanche it cannot dig out of (observed live 2026-07-10:
@@ -1762,6 +1873,9 @@ writeLedger) {
             writeFileSync(abs, updated, 'utf-8');
             recordAuthorisedWrite(sweep, rel, updated);
             writeLedger?.add(rel);
+            // The edit succeeded: every recorded read of this path is now stale.
+            if (stateHash)
+                invalidateStateHash(stateHash.store, abs);
             const rustCheckNote = maybeRustWriteCheck(projectRoot, rel);
             const jsCheckNote = maybeJsSyntaxCheck(projectRoot, rel);
             const plural = batch.length === 1 ? 'replacement' : 'replacements';
@@ -1828,6 +1942,9 @@ writeLedger) {
             writeFileSync(abs, ranged.text, 'utf-8');
             recordAuthorisedWrite(sweep, rel, ranged.text);
             writeLedger?.add(rel);
+            // The edit succeeded: every recorded read of this path is now stale.
+            if (stateHash)
+                invalidateStateHash(stateHash.store, abs);
             const rustCheckNote = maybeRustWriteCheck(projectRoot, rel);
             const jsCheckNote = maybeJsSyntaxCheck(projectRoot, rel);
             return (`OK: replaced lines ${Number(args.start_line)}-${Number(args.end_line)} ` +
@@ -2119,6 +2236,12 @@ export function createAgenticExecutor(model, opts) {
     const protectIac = opts.protectIac ?? false;
     // run_bash executes only when kernel-contained (uap sandbox sets
     // UAP_SANDBOX_ACTIVE=1) or the operator explicitly opts in (audit X3).
+    // Run-level content-hash dedup store: hash entries survive turn boundaries
+    // (cross-turn persistence within the run), while the `served` set is cleared
+    // at each turn open — see stateHashReference for why the two have different
+    // lifetimes. Incremented once per turn by the wrapper below.
+    const stateHashStore = newStateHashStore();
+    let stateHashTurn = 0;
     const allowBash = opts.allowBash === true ||
         process.env.UAP_SANDBOX_ACTIVE === '1' ||
         process.env.UAP_DELIVER_ALLOW_BASH === '1';
@@ -2151,6 +2274,13 @@ export function createAgenticExecutor(model, opts) {
         const summaries = [];
         // Per-session: what this agent has already read, and at what mtime.
         const readCache = newReadCache();
+        // A turn is a fresh conversation (messages rebuilt above), so no content
+        // from a previous turn is in context: clear the served set, and the first
+        // read of anything this turn pays full content again. Without this the
+        // compact reference would point at content the model never received —
+        // the v1.148.21 deadlock.
+        stateHashStore.served.clear();
+        const turn = stateHashTurn;
         // Read-only-streak nudge: a weak model in a gap-closure/whole-mission epic
         // can spend EVERY round on read_file/list_dir and end the turn with zero
         // writes — attempt after attempt (run I live, 2026-07-17: two 5-turn
@@ -2334,7 +2464,10 @@ export function createAgenticExecutor(model, opts) {
                 if (recovered.length > 0) {
                     const written = [];
                     for (const block of recovered) {
-                        const result = runTool(opts.projectRoot, 'write_file', { path: block.path, content: block.content }, bashTimeoutMs, protectedFiles, protectGateConfigs, allowBash, contractFiles, sweep, protectIac, opts.writeLedger);
+                        const result = runTool(opts.projectRoot, 'write_file', { path: block.path, content: block.content }, bashTimeoutMs, protectedFiles, protectGateConfigs, allowBash, contractFiles, sweep, protectIac, opts.writeLedger, 
+                        // Recovered writes mutate files too — the store must hear about
+                        // them or the next read could collapse to a stale reference.
+                        { store: stateHashStore, round, turn });
                         opts.onEvent?.({
                             round,
                             kind: 'tool',
@@ -2475,7 +2608,7 @@ export function createAgenticExecutor(model, opts) {
                 }
                 // A repeated read gets a NUDGE, never a denial — see repeatReadNote.
                 const repeat = repeatReadNote(readCache, opts.projectRoot, call.function.name, args, round);
-                const toolResult = runTool(opts.projectRoot, call.function.name, args, bashTimeoutMs, protectedFiles, protectGateConfigs, allowBash, contractFiles, sweep, protectIac, opts.writeLedger);
+                const toolResult = runTool(opts.projectRoot, call.function.name, args, bashTimeoutMs, protectedFiles, protectGateConfigs, allowBash, contractFiles, sweep, protectIac, opts.writeLedger, { store: stateHashStore, round, turn });
                 // #2a: per-tool-call progress — refresh the deliver heartbeat now, not
                 // just at turn end, so wedge-detection tracks real intra-turn activity.
                 opts.onToolProgress?.();
@@ -2514,7 +2647,14 @@ export function createAgenticExecutor(model, opts) {
                 // to proceed, and it simply asks again. Live: 76 re-reads of one file,
                 // 64 nudges, ZERO writes in 36 minutes. Serve the content, and prepend
                 // the nudge so repetition still costs it nothing but a line.
-                const result = repeat ? `${repeat}\n\n${toolResult}` : toolResult;
+                // The state-hash reference is the ONE safe exception: it is only ever
+                // returned for content this very conversation has already received in
+                // full (see stateHashReference), and it already carries the steer — so
+                // the repeat note, which promises "content follows anyway", must NOT
+                // be prepended over it.
+                const result = repeat && !isStateHashReference(toolResult)
+                    ? `${repeat}\n\n${toolResult}`
+                    : toolResult;
                 opts.onEvent?.({
                     round,
                     kind: 'tool',
@@ -2542,6 +2682,10 @@ export function createAgenticExecutor(model, opts) {
      * must not be left holding it.
      */
     return async (prompt) => {
+        // Turn counter for the state-hash reference labels ("unchanged since turn
+        // N"). Incremented here — the single per-turn entry point — not in
+        // runTurn, which has early-return paths a counter inside it would miss.
+        stateHashTurn += 1;
         const sweep = beginBashSweep(opts.projectRoot, allowBash);
         // Fold the sweep's observed changes into the run write ledger: tool writes
         // are recorded at their writeFileSync sites, but shell writes only become