@duckmind/dm-darwin-x64 0.66.5 → 0.66.6

package/extensions/dm-lens/clients/read-guard.js

@@ -1,10 +1,20 @@
+import { createHash } from "node:crypto";
 import * as fs from "node:fs";
+import { BoundedSet } from "./bounded-cache.js";
 import { incrementDegradationCount } from "./degradation-ledger.js";
 import { createFileTime } from "./file-time.js";
 import { hashDiagnosticContent } from "./lsp/diagnostic-binding.js";
-import { normalizeEphemeralMapKey, normalizeFilePath } from "./path-utils.js";
-import { logReadGuardEvent } from "./read-guard-logger.js";
-export const READ_GUARD_STATE_VERSION = 1;
+import {
+  normalizeEphemeralMapKey,
+  normalizeFilePath,
+  realpathOrResolve
+} from "./path-utils.js";
+import {
+  logReadGuardEvent,
+  sanitizeCorrelationId
+} from "./read-guard-logger.js";
+import { beginScope, moveBranch } from "./session-scope.js";
+export const READ_GUARD_STATE_VERSION = 2;
 const DEFAULT_CONFIG = {
   enabled: true,
   mode: "block",
@@ -15,9 +25,73 @@ const DEFAULT_CONFIG = {
     { pattern: "*.log", mode: "allow" }
   ]
 };
-const OWN_EDIT_STALE_GRACE_MS = Math.max(0, Number.parseInt(process.env.DM_LENS_READ_GUARD_OWN_EDIT_GRACE_MS ?? "120000", 10) || 120000);
 const READ_HASH_MAX_LINES = Math.max(0, Number.parseInt(process.env.DM_LENS_READ_GUARD_HASH_MAX_LINES ?? "3000", 10) || 3000);
 const READ_BINDING_MAX_BYTES = 4 * 1024 * 1024;
+function hashFileBytes(filePath) {
+  return createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+const ABSENT_SIZE = -1;
+function observeAuthoredBytes(filePath, knownHash, authoredRanges) {
+  try {
+    const stat = fs.statSync(filePath);
+    const hash = knownHash !== undefined ? knownHash : stat.size <= READ_BINDING_MAX_BYTES ? hashFileBytes(filePath) : undefined;
+    return {
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      ctimeMs: stat.ctimeMs,
+      ...hash !== undefined && { hash },
+      ...authoredRanges !== undefined && { authoredRanges },
+      ...authoredRanges !== undefined && {
+        authoredLineCount: splitLines(fs.readFileSync(filePath, "utf-8")).length
+      }
+    };
+  } catch {
+    return { size: ABSENT_SIZE, mtimeMs: 0, ctimeMs: 0 };
+  }
+}
+function composeAuthoredRanges(previous, next, nextLineCount) {
+  const ranges = previous.authoredLineCount !== undefined && nextLineCount === previous.authoredLineCount ? [...previous.authoredRanges ?? [], ...next] : next;
+  const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+  const merged = [];
+  for (const [start, end] of sorted) {
+    const last = merged.at(-1);
+    if (last && start <= last[1] + 1)
+      last[1] = Math.max(last[1], end);
+    else
+      merged.push([start, end]);
+  }
+  return merged;
+}
+function authoredRangeCovers(authored, touchedLines, editRanges) {
+  if (authored.authoredRanges === undefined)
+    return true;
+  const requested = editRanges ?? (touchedLines ? [touchedLines] : undefined);
+  return requested !== undefined && requested.every(([start, end]) => authored.authoredRanges.some(([authoredStart, authoredEnd]) => start >= authoredStart && end <= authoredEnd));
+}
+function isValidAuthoredRanges(value) {
+  return Array.isArray(value) && value.every((range) => Array.isArray(range) && range.length === 2 && Number.isFinite(range[0]) && Number.isFinite(range[1]));
+}
+function authoredBytesIntact(filePath, authored) {
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return authored.size === ABSENT_SIZE;
+  }
+  if (stat.size === authored.size && stat.mtimeMs === authored.mtimeMs && stat.ctimeMs === authored.ctimeMs)
+    return true;
+  if (authored.hash === undefined || stat.size !== authored.size)
+    return false;
+  try {
+    if (hashFileBytes(filePath) !== authored.hash)
+      return false;
+  } catch {
+    return false;
+  }
+  authored.mtimeMs = stat.mtimeMs;
+  authored.ctimeMs = stat.ctimeMs;
+  return true;
+}
 const READ_GUARD_MAX_FILES = 256;
 const READ_GUARD_MAX_RECORDS_PER_FILE = 128;
 const NO_TRIM = {
@@ -52,6 +126,9 @@ function enforceRecordCapForFile(records) {
 }
 const READ_GUARD_MAX_EDITS_PER_FILE = 256;
 const READ_GUARD_MAX_UNCONSUMED_FILES = 4096;
+const READ_GUARD_MAX_AUTHORED_FILES = READ_GUARD_MAX_UNCONSUMED_FILES;
+const READ_GUARD_MAX_CHECKED_CALLS = 16;
+const READ_GUARD_MAX_CHECKED_PATHS_PER_CALL = 128;
 const READ_GUARD_IDLE_EVICT_MS_DEFAULT = 30 * 60000;
 export function captureReadContentBinding(filePath, offset, limit) {
   try {
@@ -134,24 +211,40 @@ export function lineContentHash(line) {
 function readRangeCoversLine(read, lineNo) {
   return lineNo >= read.effectiveOffset && lineNo <= read.effectiveOffset + read.effectiveLimit - 1;
 }
-function readEffectiveRangeCoversRange(read, [startLine, endLine]) {
-  return readRangeCoversLine(read, startLine) && readRangeCoversLine(read, endLine);
+function newestViewOfLine(reads, lineNo) {
+  for (let i = reads.length - 1;i >= 0; i -= 1) {
+    if (reads[i].provisional !== true && readRangeCoversLine(reads[i], lineNo)) {
+      return reads[i];
+    }
+  }
+  return;
+}
+function hashLines(lines, firstLine) {
+  const hashes = {};
+  lines.forEach((line, i) => {
+    hashes[firstLine + i] = lineContentHash(line);
+  });
+  return lines.length > 0 ? hashes : undefined;
 }
 function captureLineHashes(filePath, offset, limit) {
   if (limit <= 0 || limit > READ_HASH_MAX_LINES)
     return;
   try {
     const lines = splitLines(fs.readFileSync(filePath, "utf-8"));
-    const hashes = {};
+    const start = Math.max(1, offset);
     const end = Math.min(lines.length, offset + limit - 1);
-    for (let lineNo = Math.max(1, offset);lineNo <= end; lineNo++) {
-      hashes[lineNo] = lineContentHash(lines[lineNo - 1] ?? "");
-    }
-    return Object.keys(hashes).length > 0 ? hashes : undefined;
+    return hashLines(lines.slice(start - 1, end), start);
   } catch {
     return;
   }
 }
+export function deliveredLineEvidence(text, offset) {
+  const lines = splitLines(text);
+  return {
+    lineCount: lines.length,
+    lineHashes: lines.length <= READ_HASH_MAX_LINES ? hashLines(lines, offset) : undefined
+  };
+}
 export function currentLinesMatchReadSnapshot(filePath, read, [startLine, endLine]) {
   const hashes = read.lineHashes ?? {};
   const missingLines = [];
@@ -202,21 +295,25 @@ export class ReadGuard {
   fileTime;
   exemptions = new Set;
   pendingCreations = new Map;
-  writtenThisSession = new Set;
-  unchangedThisSession = new Set;
+  writtenThisSession = new Map;
+  checkedPathsByCall = new Map;
+  expiredWrites = new BoundedSet(READ_GUARD_MAX_FILES);
   knownPathIndex = new Map;
   trimAccumulators = new Map;
   sessionId;
-  sessionStartMs;
-  constructor(sessionId, config = {}) {
+  scope;
+  constructor(sessionId, config = {}, scope = beginScope({ role: "primary" })) {
+    this.scope = scope;
     this.sessionId = sessionId;
-    this.sessionStartMs = Date.now();
     this.config = { ...DEFAULT_CONFIG, ...config };
     this.fileTime = createFileTime(sessionId);
   }
   key(filePath) {
     return normalizeFilePath(filePath);
   }
+  licenseKey(filePath) {
+    return normalizeFilePath(realpathOrResolve(filePath));
+  }
   idleEvictMs() {
     const value = Number.parseInt(process.env.DM_LENS_READ_GUARD_IDLE_EVICT_MS ?? "", 10);
     return Number.isSafeInteger(value) && value > 0 ? value : READ_GUARD_IDLE_EVICT_MS_DEFAULT;
@@ -233,13 +330,16 @@ export class ReadGuard {
     this.edits.delete(filePath);
     this.fileLastUsed.delete(filePath);
     this.consumedReadFiles.delete(filePath);
-    this.writtenThisSession.delete(filePath);
+    const droppedAuthorship = this.writtenThisSession.delete(filePath);
     for (const [syntacticKey, stored] of this.knownPathIndex) {
       if (stored === filePath)
         this.knownPathIndex.delete(syntacticKey);
     }
-    if (reason === "idle-timeout")
+    if (reason === "idle-timeout") {
+      if (droppedAuthorship)
+        this.noteExpiredWrite(filePath);
       return;
+    }
     const isRisingEdge = incrementDegradationCount({
       kind: "read-guard-file-evicted",
       subject: filePath,
@@ -254,6 +354,53 @@ export class ReadGuard {
       });
     }
   }
+  noteExpiredWrite(filePath, reason = "idle-timeout") {
+    if (this.expiredWrites.has(filePath))
+      return;
+    this.expiredWrites.add(filePath);
+    if (reason === "authorship-cap") {
+      const isRisingEdge = incrementDegradationCount({
+        kind: "read-guard-authorship-cap",
+        subject: this.sessionId,
+        reason: "authorship cap evicted a live write record"
+      });
+      if (isRisingEdge) {
+        logReadGuardEvent({
+          event: "read_file_evicted",
+          sessionId: this.sessionId,
+          filePath,
+          metadata: { reason, authorshipDropped: true }
+        });
+      }
+      return;
+    }
+    logReadGuardEvent({
+      event: "read_file_evicted",
+      sessionId: this.sessionId,
+      filePath,
+      metadata: { reason, authorshipDropped: true }
+    });
+  }
+  enforceAuthorshipCap() {
+    let excess = this.writtenThisSession.size - READ_GUARD_MAX_AUTHORED_FILES;
+    if (excess <= 0)
+      return;
+    for (const [filePath, authored] of this.writtenThisSession) {
+      if (excess <= 0)
+        return;
+      if (!authored.retired)
+        continue;
+      this.writtenThisSession.delete(filePath);
+      excess -= 1;
+    }
+    for (const filePath of this.writtenThisSession.keys()) {
+      if (excess <= 0)
+        return;
+      this.writtenThisSession.delete(filePath);
+      this.noteExpiredWrite(filePath, "authorship-cap");
+      excess -= 1;
+    }
+  }
   touchFile(filePath) {
     const now = Date.now();
     this.fileLastUsed.set(filePath, now);
@@ -285,20 +432,44 @@ export class ReadGuard {
       this.evictFile(victim, "file-cap-unconsumed");
     }
   }
+  dropProvisionalReads() {
+    let dropped = 0;
+    for (const [filePath, records] of this.reads) {
+      const kept = records.filter((record) => {
+        if (!record.provisional)
+          return true;
+        dropped += 1;
+        return false;
+      });
+      if (kept.length === 0)
+        this.reads.delete(filePath);
+      else if (kept.length !== records.length)
+        this.reads.set(filePath, kept);
+    }
+    return dropped;
+  }
+  dropProvisionalReadByCall(toolCallId) {
+    for (const [filePath, records] of this.reads) {
+      const source = `native-read:${toolCallId}:provisional`;
+      const index = records.findIndex((record) => record.source === source);
+      if (index < 0)
+        continue;
+      records.splice(index, 1);
+      if (records.length === 0)
+        this.reads.delete(filePath);
+      return true;
+    }
+    return false;
+  }
   recordRead(record, opts) {
     const filePath = this.key(record.filePath);
-    if (opts?.supersedes) {
-      const records = this.reads.get(filePath);
-      const provisionalSource = `native-read:${opts.supersedes.toolCallId}:provisional`;
-      const provisionalIndex = records?.findIndex((candidate) => candidate.source === provisionalSource);
-      if (provisionalIndex !== undefined && provisionalIndex >= 0)
-        records.splice(provisionalIndex, 1);
-    }
+    if (opts?.supersedes)
+      this.dropProvisionalReadByCall(opts.supersedes.toolCallId);
     this.knownPathIndex.set(normalizeEphemeralMapKey(record.filePath), filePath);
     const storedRecord = {
       ...record,
       filePath,
-      lineHashes: record.lineHashes ?? captureLineHashes(filePath, record.effectiveOffset, record.effectiveLimit)
+      lineHashes: record.lineHashes ?? (opts?.captureLineHashes === false ? undefined : captureLineHashes(filePath, record.effectiveOffset, record.effectiveLimit))
     };
     const arr = this.reads.get(storedRecord.filePath) ?? [];
     this.consumedReadFiles.delete(storedRecord.filePath);
@@ -377,9 +548,80 @@ export class ReadGuard {
         });
       }
     }
-    this.fileTime.read(storedRecord.filePath);
+    if (opts?.stampFileTime !== false)
+      this.fileTime.read(storedRecord.filePath);
+  }
+  retireChangedAuthorship(rawFilePath) {
+    return this.retireIfChanged(this.key(rawFilePath));
+  }
+  noteCheckedPaths(rawToolCallId, rawPaths) {
+    const toolCallId = sanitizeCorrelationId(rawToolCallId);
+    if (toolCallId === undefined || rawPaths.length === 0)
+      return;
+    let checked = this.checkedPathsByCall.get(toolCallId);
+    if (!checked) {
+      checked = new Set;
+      this.checkedPathsByCall.set(toolCallId, checked);
+      while (this.checkedPathsByCall.size > READ_GUARD_MAX_CHECKED_CALLS) {
+        const oldest = this.checkedPathsByCall.keys().next();
+        if (oldest.done === true)
+          break;
+        this.checkedPathsByCall.delete(oldest.value);
+      }
+    }
+    for (const rawPath of rawPaths) {
+      if (checked.size >= READ_GUARD_MAX_CHECKED_PATHS_PER_CALL)
+        return;
+      checked.add(this.licenseKey(rawPath));
+    }
   }
-  recordSymbolRead(filePath, symbol, turnIndex, writeIndex) {
+  consumeCheckedAtCall(toolCallId, filePath) {
+    const callId = sanitizeCorrelationId(toolCallId);
+    if (callId === undefined)
+      return false;
+    const checked = this.checkedPathsByCall.get(callId);
+    const licensedPath = this.licenseKey(filePath);
+    if (checked?.has(licensedPath) !== true)
+      return false;
+    checked.delete(licensedPath);
+    if (checked.size === 0)
+      this.checkedPathsByCall.delete(callId);
+    return true;
+  }
+  retireIfChanged(filePath, writer, force = false) {
+    const authored = this.writtenThisSession.get(filePath);
+    if (!authored || authored.retired || !force && authoredBytesIntact(filePath, authored))
+      return false;
+    authored.retired = true;
+    const isRisingEdge = incrementDegradationCount({
+      kind: "read-guard-authorship-retired",
+      subject: filePath,
+      reason: force ? "authored range was unknown; the next edit needs a read" : "another writer changed the bytes the conversation wrote; the next edit needs a read"
+    });
+    if (isRisingEdge)
+      logReadGuardEvent({
+        event: "authorship_retired",
+        sessionId: this.sessionId,
+        filePath,
+        metadata: {
+          authoredSize: authored.size,
+          hashed: authored.hash !== undefined,
+          ...writer !== undefined && { writer },
+          ...authored.toolCallId !== undefined && {
+            toolCallId: authored.toolCallId
+          }
+        }
+      });
+    return true;
+  }
+  fileTimeMoved(filePath) {
+    return this.fileTime.hasChanged(this.key(filePath));
+  }
+  diskMovedSinceStamp(filePath) {
+    const key = this.key(filePath);
+    return this.fileTime.get(key) !== undefined && this.fileTime.hasChanged(key);
+  }
+  recordSymbolRead(filePath, symbol, turnIndex, writeIndex, toolCallId) {
     const span = Math.max(1, symbol.endLine - symbol.startLine + 1);
     this.recordRead({
       filePath,
@@ -396,7 +638,8 @@ export class ReadGuard {
       },
       turnIndex,
       writeIndex,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      ...toolCallId !== undefined && { toolCallId }
     });
   }
   checkEdit(filePath, touchedLines, editRanges, options) {
@@ -423,22 +666,39 @@ export class ReadGuard {
     const effectiveMode = exemptionMode === "warn" ? "warn" : undefined;
     const fileReads = this.reads.get(filePath);
     if (!fileReads || fileReads.length === 0) {
-      if (this.wasWrittenThisSession(filePath)) {
-        this.injectCreationRead(filePath, 0, 0);
+      this.retireChangedAuthorship(filePath);
+      if (this.writtenThisSession.get(filePath)?.retired) {
+        const verdict = this.blockOrWarn("authorship-retired", `\uD83D\uDD04 RETRYABLE — File modified since your write: \`${filePath}\` no longer holds the bytes this conversation wrote. Read it first, then retry: \`read path="${filePath}"\`.`, undefined, effectiveMode);
+        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
+          reasonKind: "authorship_retired"
+        });
+        return verdict;
+      }
+      const authored = this.writtenThisSession.get(filePath);
+      if (authored && authoredRangeCovers(authored, touchedLines, editRanges)) {
         const verdict = this.allow();
         this.recordVerdict(filePath, "edit", touchedLines, verdict, {
           reasonKind: "session_authored"
         });
         return verdict;
       }
-      const verdict = this.blockOrWarn("zero-read", `\uD83D\uDD04 RETRYABLE — Edit without read: you have not read \`${filePath}\` in this conversation. Read it first, then retry: \`read path="${filePath}"\`.`, undefined, effectiveMode);
+      if (authored) {
+        const verdict = this.blockOrWarn("authorship-range", `\uD83D\uDD04 RETRYABLE — Edit without read: this write only covered part of \`${filePath}\`; read the requested lines first, then retry.`, undefined, effectiveMode);
+        this.recordVerdict(filePath, "edit", touchedLines, verdict, {
+          reasonKind: "authorship_range"
+        });
+        return verdict;
+      }
+      const writeRecordExpired = this.expiredWrites.has(filePath);
+      const verdict = this.blockOrWarn("zero-read", writeRecordExpired ? `\uD83D\uDD04 RETRYABLE — Edit without read: the earlier write record for \`${filePath}\` expired, so it needs a read again. Read it first, then retry: \`read path="${filePath}"\`.` : `\uD83D\uDD04 RETRYABLE — Edit without read: you have not read \`${filePath}\` in this conversation. Read it first, then retry: \`read path="${filePath}"\`.`, undefined, effectiveMode);
       this.recordVerdict(filePath, "edit", touchedLines, verdict, {
-        reasonKind: "zero_read"
+        reasonKind: "zero_read",
+        ...writeRecordExpired ? { writeRecordExpired } : {}
       });
       return verdict;
     }
     const lastBoundRead = [...fileReads].reverse().find((read) => read.contentBinding !== undefined);
-    if (lastBoundRead?.contentBinding && !currentContentMatchesBinding(filePath, lastBoundRead.contentBinding)) {
+    if (lastBoundRead?.contentBinding && !currentContentMatchesBinding(filePath, lastBoundRead.contentBinding) && !this.newerReadSupersedesBinding(filePath, fileReads, lastBoundRead, touchedLines, editRanges)) {
       const verdict = this.blockOrWarn("file-modified", `\uD83D\uDD04 RETRYABLE — File modified since read
 
 You last read \`${filePath}\` at ${new Date(lastBoundRead.timestamp).toISOString()}.
@@ -454,15 +714,12 @@ To proceed:
       });
       return verdict;
     }
-    let ignoredOwnEditStaleness = false;
     let ignoredHashStaleness = false;
     let ignoredOldTextResolvedStaleness = false;
     if (this.fileTime.hasChanged(filePath)) {
       const lastRead = fileReads[fileReads.length - 1];
       if (options?.oldTextResolved === true) {
         ignoredOldTextResolvedStaleness = true;
-      } else if (this.canTreatStalenessAsOwnPriorEdit(filePath, lastRead.timestamp)) {
-        ignoredOwnEditStaleness = true;
       } else if (this.canIgnoreStalenessByHashes(filePath, fileReads, touchedLines, editRanges)) {
         ignoredHashStaleness = true;
       } else {
@@ -491,7 +748,6 @@ To proceed:
     const rangesToCheck = editRanges && editRanges.length > 1 ? editRanges : [touchedLines];
     let viaSymbol = false;
     for (const range of rangesToCheck) {
-      const snapshotValidation = this.validateRangeSnapshot(filePath, range, !!options?.skipSnapshotCheck);
       const coverage = this.checkCoverage(filePath, range);
       if (!coverage.covered) {
         const lastRead = fileReads[fileReads.length - 1];
@@ -521,11 +777,9 @@ Read the relevant section first, then retry the edit:
         });
         return verdict;
       }
+      const snapshotValidation = this.validateRangeSnapshot(filePath, range, !!options?.skipSnapshotCheck);
       if (snapshotValidation.shouldBlock && !options?.skipSnapshotCheck) {
         const [editStart, editEnd] = range;
-        const RANGE_STALE_GRACE_MS = 60000;
-        const lastRead = fileReads[fileReads.length - 1];
-        const graceActive = ignoredOwnEditStaleness && Date.now() - lastRead.timestamp < RANGE_STALE_GRACE_MS;
         const relocation = this.findRelocation(filePath, fileReads, range);
         const relocationNote = relocation ? `
 
@@ -552,7 +806,7 @@ Re-read the relevant section, then retry the edit using the current line range/c
             missingLines: snapshotValidation.missingLines
           },
           ...relocation ? { relocation } : {}
-        }, graceActive ? "warn" : effectiveMode);
+        }, effectiveMode);
         if (relocation && rangesToCheck.length === 1) {
           verdict.relocation = relocation;
         }
@@ -560,7 +814,6 @@ Re-read the relevant section, then retry the edit using the current line range/c
           reasonKind: "range_stale",
           range,
           mismatchedLines: snapshotValidation.mismatchedLines.slice(0, 20),
-          graceActive,
           relocatedTo: relocation?.to ?? null,
           relocationAutoApplyOffered: !!verdict.relocation
         });
@@ -573,7 +826,6 @@ Re-read the relevant section, then retry the edit using the current line range/c
     this.recordVerdict(filePath, "edit", touchedLines, verdict, {
       reasonKind: ignoredOldTextResolvedStaleness ? "file_modified_oldtext_unique" : viaSymbol ? "symbol_coverage" : "range_coverage",
       viaSymbol,
-      ignoredOwnEditStaleness,
       ignoredHashStaleness,
       oldTextResolved: ignoredOldTextResolvedStaleness
     });
@@ -592,7 +844,7 @@ Re-read the relevant section, then retry the edit using the current line range/c
   }
   getTrackedPaths() {
     const tracked = new Set(this.reads.keys());
-    for (const written of this.writtenThisSession)
+    for (const written of this.writtenThisSession.keys())
       tracked.add(written);
     return [...tracked];
   }
@@ -600,18 +852,27 @@ Re-read the relevant section, then retry the edit using the current line range/c
     const stored = this.knownPathIndex.get(normalizeEphemeralMapKey(filePath));
     this.evictFile(stored ?? this.key(filePath), "external-delete");
   }
-  noteCreatedFile(filePath, turnIndex, writeIndex) {
+  noteCreatedFile(filePath, turnIndex, writeIndex, toolCallId) {
     this.pendingCreations.set(normalizeEphemeralMapKey(filePath), {
       turnIndex,
-      writeIndex
+      writeIndex,
+      ...toolCallId !== undefined && { toolCallId }
     });
   }
-  recordWritten(rawFilePath) {
+  recordWritten(rawFilePath, opts) {
+    if (opts?.branchEpoch !== undefined && opts.branchEpoch !== this.currentBranchEpoch) {
+      incrementDegradationCount({
+        kind: "read-guard-write-after-branch-move",
+        subject: "recordWritten",
+        reason: `a write captured at branch epoch ${opts.branchEpoch} landed at ${this.currentBranchEpoch}; not credited to the new branch`
+      });
+      return;
+    }
     const filePath = this.key(rawFilePath);
-    this.unchangedThisSession.delete(filePath);
     this.knownPathIndex.set(normalizeEphemeralMapKey(rawFilePath), filePath);
-    this.fileTime.read(filePath);
-    this.writtenThisSession.add(filePath);
+    if (opts?.stampFileTime !== false)
+      this.fileTime.read(filePath);
+    this.creditAuthorship(filePath, opts);
     if (this.reads.has(filePath))
       this.consumedReadFiles.add(filePath);
     this.touchFile(filePath);
@@ -620,14 +881,9 @@ Re-read the relevant section, then retry the edit using the current line range/c
     const creation = this.pendingCreations.get(creationKey);
     if (creation) {
       this.pendingCreations.delete(creationKey);
-      this.injectCreationRead(filePath, creation.turnIndex, creation.writeIndex);
+      this.injectCreationRead(filePath, creation.turnIndex, creation.writeIndex, creation.toolCallId, opts?.writtenContent);
     }
   }
-  recordUnchanged(rawFilePath) {
-    const filePath = this.key(rawFilePath);
-    if (!this.writtenThisSession.has(filePath))
-      this.unchangedThisSession.add(filePath);
-  }
   addExemption(filePath) {
     this.exemptions.add(this.key(filePath));
     logReadGuardEvent({
@@ -676,6 +932,11 @@ Re-read the relevant section, then retry the edit using the current line range/c
       this.touchFile(key);
     return this.reads.get(key) ?? [];
   }
+  contentMatchesLastRead(filePath) {
+    const reads = this.getReadHistory(filePath);
+    const binding = [...reads].reverse().find((read) => read.contentBinding?.fullFile)?.contentBinding;
+    return binding === undefined ? undefined : currentContentMatchesBinding(filePath, binding);
+  }
   getTrimStats(filePath) {
     const stats = this.trimAccumulators.get(this.key(filePath));
     return stats ? { ...stats } : undefined;
@@ -689,7 +950,88 @@ Re-read the relevant section, then retry the edit using the current line range/c
       ])
     };
   }
-  importState(state) {
+  exportAuthorship() {
+    return {
+      written: [...this.writtenThisSession].flatMap(([filePath, authored]) => authored.retired ? [] : [filePath]),
+      entries: [...this.writtenThisSession].map(([filePath, authored]) => ({
+        filePath,
+        ...authored
+      }))
+    };
+  }
+  importAuthorship(state, onBranch) {
+    const result = { imported: 0, dropped: 0 };
+    const authorship = state;
+    const entries = Array.isArray(authorship?.entries) ? authorship.entries : [];
+    const withEntry = new Set;
+    for (const entry of entries) {
+      const candidate = entry;
+      if (typeof candidate?.filePath !== "string")
+        continue;
+      withEntry.add(candidate.filePath);
+      if (typeof candidate.toolCallId !== "string" || !onBranch.has(candidate.toolCallId) || typeof candidate.size !== "number" || typeof candidate.mtimeMs !== "number" || typeof candidate.ctimeMs !== "number" || candidate.hash !== undefined && typeof candidate.hash !== "string" || candidate.retired !== undefined && candidate.retired !== true || candidate.authoredRanges !== undefined && !isValidAuthoredRanges(candidate.authoredRanges) || candidate.authoredLineCount !== undefined && typeof candidate.authoredLineCount !== "number") {
+        result.dropped += 1;
+        continue;
+      }
+      const filePath = this.key(candidate.filePath);
+      this.knownPathIndex.set(normalizeEphemeralMapKey(candidate.filePath), filePath);
+      this.writtenThisSession.set(filePath, {
+        size: candidate.size,
+        mtimeMs: candidate.mtimeMs,
+        ctimeMs: candidate.ctimeMs,
+        ...candidate.hash !== undefined && { hash: candidate.hash },
+        toolCallId: candidate.toolCallId,
+        ...candidate.retired === true && { retired: true },
+        ...candidate.authoredRanges !== undefined && {
+          authoredRanges: candidate.authoredRanges
+        },
+        ...candidate.authoredLineCount !== undefined && {
+          authoredLineCount: candidate.authoredLineCount
+        }
+      });
+      result.imported += 1;
+    }
+    this.enforceAuthorshipCap();
+    if (Array.isArray(authorship?.written)) {
+      for (const filePath of authorship.written)
+        if (typeof filePath === "string" && !withEntry.has(filePath))
+          result.dropped += 1;
+    }
+    return result;
+  }
+  retainBranch(onBranch) {
+    const result = { kept: 0, dropped: 0 };
+    for (const [filePath, records] of this.reads) {
+      const kept = [];
+      for (const read of records)
+        if (read.toolCallId !== undefined && onBranch.has(read.toolCallId))
+          kept.push(read);
+      result.kept += kept.length;
+      result.dropped += records.length - kept.length;
+      if (kept.length > 0) {
+        this.reads.set(filePath, kept);
+        continue;
+      }
+      this.reads.delete(filePath);
+    }
+    for (const [filePath, authored] of this.writtenThisSession)
+      if (authored.toolCallId === undefined || !onBranch.has(authored.toolCallId))
+        this.writtenThisSession.delete(filePath);
+    this.edits.clear();
+    this.expiredWrites.clear();
+    this.pendingCreations.clear();
+    this.checkedPathsByCall.clear();
+    this.fileTime.clear();
+    moveBranch(this.scope);
+    return result;
+  }
+  get currentBranchEpoch() {
+    return this.scope.branchEpoch();
+  }
+  get lineageKey() {
+    return `${process.pid}:${this.scope.scopeId}`;
+  }
+  importBranch(state, onBranch) {
     const result = { imported: 0, dropped: 0 };
     if (!state || state.version !== READ_GUARD_STATE_VERSION)
       return result;
@@ -704,21 +1046,15 @@ Re-read the relevant section, then retry the edit using the current line range/c
       if (!Array.isArray(records) || records.length === 0)
         continue;
       const filePath = this.key(rawPath);
-      let lines;
-      try {
-        lines = splitLines(fs.readFileSync(filePath, "utf-8"));
-      } catch {
-        result.dropped += records.length;
-        continue;
-      }
-      for (const record of records) {
-        const rehydrated = { ...record, filePath };
-        if (this.readHashesStillMatch(rehydrated, lines)) {
-          this.recordRead(rehydrated);
-          result.imported += 1;
-        } else {
+      const exists = fs.existsSync(filePath);
+      for (const read of records) {
+        const id = read?.toolCallId;
+        if (!exists || typeof id !== "string" || !onBranch.has(id)) {
           result.dropped += 1;
+          continue;
         }
+        this.recordRead({ ...read, filePath, lineHashes: read.lineHashes ?? {} }, { stampFileTime: false });
+        result.imported += 1;
       }
     }
     return result;
@@ -729,13 +1065,56 @@ Re-read the relevant section, then retry the edit using the current line range/c
       this.touchFile(key);
     return this.edits.get(key) ?? [];
   }
-  injectCreationRead(filePath, turnIndex, writeIndex) {
-    let lineCount = 0;
+  mayAdvanceAuthorship(filePath, opts) {
+    if (opts?.advanceAuthorship === undefined)
+      return true;
+    if (opts.advanceAuthorship !== true)
+      return false;
+    return this.consumeCheckedAtCall(opts.toolCallId, filePath);
+  }
+  creditAuthorship(filePath, opts) {
+    const existing = this.writtenThisSession.get(filePath);
+    if (!existing && opts?.allowFirstAuthorship === false)
+      return;
+    if (existing?.retired)
+      return;
+    if (opts?.authorship === "unknown") {
+      if (existing)
+        this.retireIfChanged(filePath, "bridge", true);
+      return;
+    }
+    if (existing && !this.mayAdvanceAuthorship(filePath, opts)) {
+      this.retireIfChanged(filePath, "bridge");
+      return;
+    }
+    const observed = observeAuthoredBytes(filePath, opts?.contentHash, opts?.authoredRanges);
+    const { authoredRanges: _observedRanges, ...observedWithoutRanges } = observed;
+    const composedRanges = existing?.authoredRanges === undefined ? existing ? undefined : observed.authoredRanges : opts?.authoredRanges === undefined ? undefined : composeAuthoredRanges(existing, opts.authoredRanges, observed.authoredLineCount);
+    const toolCallId = opts?.toolCallId ?? existing?.toolCallId;
+    this.writtenThisSession.delete(filePath);
+    this.writtenThisSession.set(filePath, {
+      ...observedWithoutRanges,
+      ...composedRanges !== undefined ? {
+        authoredRanges: composedRanges,
+        ...observed.authoredLineCount !== undefined && {
+          authoredLineCount: observed.authoredLineCount
+        }
+      } : {},
+      ...toolCallId !== undefined && { toolCallId }
+    });
+    this.enforceAuthorshipCap();
+  }
+  injectCreationRead(filePath, turnIndex, writeIndex, toolCallId, writtenContent) {
+    let evidence;
     try {
-      lineCount = splitLines(fs.readFileSync(filePath, "utf-8")).length;
+      evidence = writtenContent !== undefined ? deliveredLineEvidence(writtenContent, 1) : {
+        lineCount: splitLines(fs.readFileSync(filePath, "utf-8")).length,
+        lineHashes: undefined
+      };
     } catch {
       return;
     }
+    const { lineCount, lineHashes } = evidence;
     if (lineCount === 0)
       return;
     this.recordRead({
@@ -745,33 +1124,13 @@ Re-read the relevant section, then retry the edit using the current line range/c
       effectiveOffset: 1,
       effectiveLimit: lineCount,
       expandedByLsp: false,
+      ...lineHashes && { lineHashes },
       turnIndex,
       writeIndex,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      ...toolCallId !== undefined && { toolCallId }
     });
   }
-  wasWrittenThisSession(filePath) {
-    if (this.unchangedThisSession.has(filePath))
-      return false;
-    if (this.writtenThisSession.has(filePath))
-      return true;
-    try {
-      return fs.statSync(filePath).mtimeMs >= this.sessionStartMs;
-    } catch {
-      return false;
-    }
-  }
-  canTreatStalenessAsOwnPriorEdit(filePath, lastReadTimestamp) {
-    const edits = this.edits.get(filePath) ?? [];
-    const latest = edits.at(-1);
-    if (!latest)
-      return false;
-    if (latest.verdict !== "allowed" && latest.verdict !== "warned")
-      return false;
-    if (latest.timestamp < lastReadTimestamp)
-      return false;
-    return Date.now() - latest.timestamp <= OWN_EDIT_STALE_GRACE_MS;
-  }
   canIgnoreStalenessByHashes(filePath, reads, touchedLines, editRanges) {
     let lines;
     try {
@@ -784,69 +1143,51 @@ Re-read the relevant section, then retry the edit using the current line range/c
       const lastRead = reads.at(-1);
       return !!lastRead && this.readHashesStillMatch(lastRead, lines);
     }
-    return rangesToCheck.every((range) => reads.some((read) => this.readCoversRange(read, range) && this.readRangeHashesStillMatch(read, lines, range)));
-  }
-  readCoversRange(read, [editStart, editEnd]) {
-    const readStart = Math.max(1, read.effectiveOffset - this.config.contextLines);
-    const readEnd = read.effectiveOffset + read.effectiveLimit - 1 + this.config.contextLines;
-    if (editStart >= readStart && editEnd <= readEnd)
+    return rangesToCheck.every(([startLine, endLine]) => {
+      for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
+        const view = newestViewOfLine(reads, lineNo);
+        if (!view || !this.readRangeHashesStillMatch(view, lines, [lineNo, lineNo])) {
+          return false;
+        }
+      }
       return true;
-    if (!read.enclosingSymbol)
-      return false;
-    return read.enclosingSymbol.startLine <= editStart && read.enclosingSymbol.endLine >= editEnd;
+    });
   }
-  validateRangeSnapshot(filePath, range, snapshotCheckSkipped) {
+  validateRangeSnapshot(filePath, [startLine, endLine], snapshotCheckSkipped) {
     const reads = this.reads.get(filePath) ?? [];
-    const candidates = reads.filter((read) => this.readCoversRange(read, range));
-    let status = "unavailable";
-    let matchingReadIndex = -1;
-    let missingLines = [];
-    let mismatchedLines = [];
-    let checkedCandidateCount = 0;
-    let unavailableCandidateCount = 0;
-    let hashUnavailableCandidateCount = 0;
-    let lastMismatchTimestamp = -1 / 0;
-    let lastUnavailableTimestamp = -1 / 0;
-    for (let i = 0;i < candidates.length; i += 1) {
-      const validation = currentLinesMatchReadSnapshot(filePath, candidates[i], range);
-      if (!validation.checked) {
-        unavailableCandidateCount += 1;
-        if (readEffectiveRangeCoversRange(candidates[i], range)) {
-          hashUnavailableCandidateCount += 1;
-        }
-        if (status === "unavailable") {
-          missingLines = validation.missingLines;
-        }
-        lastUnavailableTimestamp = Math.max(lastUnavailableTimestamp, candidates[i].timestamp);
+    const runs = [];
+    const missingLines = [];
+    for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
+      const view = newestViewOfLine(reads, lineNo);
+      if (!view || view.lineHashes?.[lineNo] === undefined) {
+        missingLines.push(lineNo);
         continue;
       }
-      checkedCandidateCount += 1;
-      if (validation.matches) {
-        status = "match";
-        matchingReadIndex = i;
-        missingLines = [];
-        mismatchedLines = [];
-        break;
+      const last = runs.at(-1);
+      if (last?.read === view && last.range[1] === lineNo - 1) {
+        last.range[1] = lineNo;
+      } else {
+        runs.push({ read: view, range: [lineNo, lineNo] });
       }
-      status = "mismatch";
-      missingLines = [];
-      mismatchedLines = validation.mismatchedLines;
-      lastMismatchTimestamp = Math.max(lastMismatchTimestamp, candidates[i].timestamp);
     }
-    const shouldBlock = status === "mismatch" && lastUnavailableTimestamp <= lastMismatchTimestamp && checkedCandidateCount > 0 && hashUnavailableCandidateCount === 0;
+    const mismatchedLines = [];
+    let checkedLineCount = 0;
+    for (const { read, range } of runs) {
+      checkedLineCount += range[1] - range[0] + 1;
+      mismatchedLines.push(...currentLinesMatchReadSnapshot(filePath, read, range).mismatchedLines);
+    }
+    const status = mismatchedLines.length > 0 ? "mismatch" : missingLines.length === 0 ? "match" : "unavailable";
+    const shouldBlock = status === "mismatch";
     const outcome = shouldBlock ? snapshotCheckSkipped ? "bypassed-content-match" : "enforced-block" : status === "match" ? "enforced-pass" : "not-decidable";
     logReadGuardEvent({
       event: "range_snapshot_validation",
       sessionId: this.sessionId,
       filePath,
       metadata: {
-        range,
+        range: [startLine, endLine],
         status,
-        candidateReadCount: candidates.length,
-        checkedCandidateCount,
-        unavailableCandidateCount,
-        hashUnavailableCandidateCount,
-        matchingReadIndex,
+        viewRunCount: runs.length,
+        checkedLineCount,
         missingLineCount: missingLines.length,
         mismatchedLineCount: mismatchedLines.length,
         missingLines: missingLines.slice(0, 20),
@@ -855,16 +1196,7 @@ Re-read the relevant section, then retry the edit using the current line range/c
         outcome
       }
     });
-    return {
-      status,
-      matchingReadIndex,
-      missingLines,
-      mismatchedLines,
-      candidateReadCount: candidates.length,
-      checkedCandidateCount,
-      unavailableCandidateCount,
-      shouldBlock
-    };
+    return { status, missingLines, mismatchedLines, shouldBlock };
   }
   readRangeHashesStillMatch(read, lines, [startLine, endLine]) {
     const hashes = read.lineHashes ?? {};
@@ -880,32 +1212,40 @@ Re-read the relevant section, then retry the edit using the current line range/c
     }
     return true;
   }
+  newerReadSupersedesBinding(filePath, fileReads, boundRead, touchedLines, editRanges) {
+    if (!touchedLines)
+      return false;
+    const rangesToCheck = editRanges && editRanges.length > 1 ? editRanges : [touchedLines];
+    const boundIndex = fileReads.lastIndexOf(boundRead);
+    if (boundIndex < 0)
+      return false;
+    for (const candidate of fileReads.slice(boundIndex + 1).reverse()) {
+      if (candidate.provisional === true)
+        continue;
+      const deliversEveryEditedLine = rangesToCheck.every((range) => {
+        const evidence = currentLinesMatchReadSnapshot(filePath, candidate, range);
+        return evidence.checked && evidence.matches;
+      });
+      if (deliversEveryEditedLine)
+        return true;
+    }
+    return false;
+  }
   findRelocation(filePath, reads, [startLine, endLine]) {
     const span = endLine - startLine + 1;
     if (span < 2)
       return;
-    let wanted;
-    for (let i = reads.length - 1;i >= 0; i -= 1) {
-      const hashes = reads[i].lineHashes;
-      if (!hashes)
-        continue;
-      const seq = [];
-      let complete = true;
-      for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
-        const h = hashes[lineNo];
-        if (h === undefined) {
-          complete = false;
-          break;
-        }
-        seq.push(h);
-      }
-      if (complete) {
-        wanted = seq;
-        break;
+    const source = newestViewOfLine(reads, startLine);
+    if (!source?.lineHashes)
+      return;
+    const wanted = [];
+    for (let lineNo = startLine;lineNo <= endLine; lineNo += 1) {
+      const hash = source.lineHashes[lineNo];
+      if (hash === undefined || newestViewOfLine(reads, lineNo) !== source) {
+        return;
       }
+      wanted.push(hash);
     }
-    if (!wanted)
-      return;
     let lines;
     try {
       lines = splitLines(fs.readFileSync(filePath, "utf-8"));