rubino-agent 0.4.0 → 0.5.0

data/lib/rubino/tools/grep_tool.rb

@@ -70,7 +70,19 @@ module Rubino
         before  = (ctx || arguments["before"] || arguments[:before] || 0).to_i.clamp(0, 50)
         after   = (ctx || arguments["after"]  || arguments[:after]  || 0).to_i.clamp(0, 50)
 
-        expanded_path = File.expand_path(path)
+        expanded_path = expand_workspace_path(path)
+        # Search is BROAD (#406): grep resolves any NON-secret path like
+        # Hermes/Claude/Codex. A grep whose `path` is a SECRET file directly
+        # (#446) is gated UPSTREAM by Security::ApprovalPolicy#decide (→ :ask),
+        # exactly like read — so it is NOT refused here; an approved grep of a
+        # secret file proceeds, a denied/headless one never reaches #call.
+        #
+        # F2: a DIRECTORY grep with `include: "*.env"` is NOT a secret target —
+        # the gate above can't see it — but rg's --glob OVERRIDES the default
+        # hidden-exclusion and would LEAK the matched .env lines. We therefore
+        # post-filter the RESULTS (see #filter_secret_hits): any result line that
+        # points at a secret file is stripped, so secrets never escape via an
+        # include-glob regardless of approval.
         return "Error: Path not found: #{path}" unless File.exist?(expanded_path)
 
         if ripgrep_available?
@@ -86,6 +98,28 @@ module Rubino
         system("which rg > /dev/null 2>&1")
       end
 
+      # True when an rg output line (`<file>:<lineno>:…`, a `<file>:<lineno>-…`
+      # context line, or a bare `--` separator) points at a secret/credential
+      # file — used to strip it from the result set so an include-glob over a
+      # directory can't leak a secret (F2). rg prints the file path verbatim
+      # from the search root we gave it; when the root is a single FILE rg omits
+      # the path prefix, but that case is the directly-targeted (approved) grep,
+      # so we resolve a bare line against `search_root` and let it fall through
+      # as non-secret. The `--` separator carries no path and is kept.
+      def secret_result_line?(line, search_root)
+        return false if line.nil? || line.start_with?("--")
+
+        # Split off the leading "<file>:<lineno>" — rg uses ':' for matches and
+        # ':'/'-' for context, always after the line number. Take everything up
+        # to the LAST ':' or '-' that precedes a digit run + delimiter.
+        m = line.match(/\A(.*?):\d+[:-]/)
+        return false unless m
+
+        file = m[1]
+        file = File.expand_path(file, search_root) unless file.start_with?(File::SEPARATOR)
+        !secret_path_category(file).nil?
+      end
+
       def search_with_ripgrep(pattern, path, include_pattern, max_results, before, after)
         # Build argv array and use Open3 to avoid shell injection — pattern
         # and path are passed as separate arguments, never interpolated into a
@@ -104,29 +138,75 @@ module Rubino
         argv += ["-A", after.to_s]  if after.positive?
         argv += [pattern, path]
 
-        output = IO.popen(argv, err: %i[child out], &:read)
+        # STREAM rg's output line-by-line and STOP after max_results (#375a).
+        # `IO.popen(argv).read` buffered the ENTIRE rg output — a pattern that
+        # matches a huge file produced +100MB in memory just to `.first(50)` it.
+        # Read until we have max_results+1 lines (the +1 detects "there are
+        # more"), then close the pipe (SIGPIPE stops rg) so neither memory nor
+        # CPU scale with the match count.
+        # F2: filter secret hits ONLY for a DIRECTORY search (an include-glob
+        # like `*.env` can pull a credential file in). A grep whose path is the
+        # secret FILE itself was already approved by the upstream gate, so its
+        # own lines must be returned, not stripped.
+        filter_secrets = File.directory?(path)
+        lines = []
+        more_exist = false
+        IO.popen(argv, err: %i[child out]) do |io|
+          io.each_line do |line|
+            # Drop a hit that points at a secret file BEFORE it counts toward the
+            # cap, so a result set of only-secrets doesn't crowd out the cap with
+            # content we'll never return.
+            next if filter_secrets && secret_result_line?(line, path)
+
+            if lines.size >= max_results
+              more_exist = true
+              break
+            end
+            lines << line
+          end
+          io.close # close early → rg gets SIGPIPE and stops scanning
+        end
         status = $?.exitstatus
+        # When WE deliberately close the pipe early after hitting the cap
+        # (#391/regression #375), rg is killed mid-scan and exits non-zero —
+        # and on some platforms the broken-pipe exit is reported as 1, the SAME
+        # code rg uses for a genuine "no matches". The old `status != 1` guard
+        # therefore EXCLUDED that case and fell through to the `status == 1`
+        # branch, dropping the 50 matches we already collected and reporting
+        # "No matches". Whenever we collected matches AND closed early (more_exist),
+        # it is unambiguously a success regardless of rg's exit code; a real
+        # "no matches" is 0 collected lines and we never closed early, so it
+        # still reaches the status==1 branch and reports correctly.
+        status = 0 if lines.any? && (more_exist || status != 1)
 
         if status == 0
-          all_lines = output.lines
-          lines     = all_lines.first(max_results)
-          more      = all_lines.size - lines.size
+          # We can't cheaply know the exact remaining count once we stop early,
+          # so report "more" without an exact number when the cap was hit.
+          more      = more_exist
           header    = "#{lines.size} match(es) shown" \
-                      "#{" (#{more} more — raise max_results or narrow the pattern)" if more.positive?}"
+                      "#{" (more — raise max_results or narrow the pattern)" if more}"
           full      = "#{header}:\n\n#{lines.join}"
           { output: full,
-            metrics: "#{lines.size} match#{"es" if lines.size != 1}#{"+" if more.positive?}",
+            metrics: "#{lines.size} match#{"es" if lines.size != 1}#{"+" if more}",
             body: Util::Output.preview(full),
             body_kind: :plain }
         elsif status == 1
           "No matches found for pattern: #{pattern}"
         else
-          "Error executing search: #{output}"
+          "Error executing search: #{lines.join}"
         end
       end
 
       def search_with_ruby(pattern, path, include_pattern, max_results, before, after)
-        regex   = Regexp.new(pattern)
+        # The Ruby fallback is the LIVE path whenever rg isn't on PATH. A bad
+        # pattern the model emits (e.g. an unclosed paren) would otherwise
+        # raise RegexpError and hand the model a raw exception; return a clean,
+        # actionable tool error instead.
+        begin
+          regex = Regexp.new(pattern)
+        rescue RegexpError => e
+          return "Error: invalid regex pattern: #{e.message}"
+        end
         results = []
 
         # ripgrep accepts a single FILE as well as a directory; mirror that
@@ -134,8 +214,22 @@ module Rubino
         # `path` is a file we search it directly (include_pattern is moot).
         files = File.file?(path) ? [path] : Dir.glob(File.join(path, "**", include_pattern || "*"))
 
+        # Honor .gitignore the SAME way the rg path does (#375b): without this
+        # the fallback returned a different, larger set (build artifacts,
+        # node_modules, ignored secrets) than rg — non-deterministic on whether
+        # rg is installed. A single FILE path the model targeted directly is
+        # always searched (mirrors rg searching an explicit file argument).
+        ignore = Util::IgnoreRules.new
+        searching_file = File.file?(path)
+
         files.each do |file|
           next unless File.file?(file)
+          next if !searching_file && ignore.ignored?(file, path)
+          # F2: in a DIRECTORY search, never read a secret file's lines into
+          # results (an include-glob like `*.env` would otherwise leak it). A
+          # single-file grep the model targeted directly is already approved
+          # upstream, so it is searched normally.
+          next if !searching_file && secret_path_category(file)
           next if binary_file?(file)
 
           begin

data/lib/rubino/tools/multi_edit_tool.rb

@@ -57,7 +57,11 @@ module Rubino
         return "Error: file_path is required" if file_path.nil? || file_path.to_s.empty?
         return "Error: edits must be a non-empty array" if !edits.is_a?(Array) || edits.empty?
 
-        expanded = File.expand_path(file_path)
+        expanded = expand_workspace_path(file_path)
+        # SECRET/credential edits (#446) are no longer HARD-refused here — they
+        # are gated UPSTREAM by Security::ApprovalPolicy#decide (→ :ask): an
+        # APPROVED multi_edit of your .env actually applies, a denied/headless
+        # one never reaches #call. The workspace sandbox below is unchanged.
         return workspace_violation_message(file_path) unless within_workspace?(expanded)
         return "Error: File not found: #{file_path}" unless File.exist?(expanded)
 
@@ -65,7 +69,11 @@ module Rubino
           return gate
         end
 
-        content       = File.read(expanded)
+        # Read RAW bytes (binary) so the read-modify-write preserves every byte
+        # outside the matched spans — a non-UTF-8 byte on an untouched line is
+        # written back verbatim (#326). The model-supplied needles/replacements
+        # are matched and spliced as bytes too (see Base#to_match_bytes).
+        content       = read_for_edit(expanded)
         working       = content.dup
         applied_count = 0
 
@@ -80,30 +88,77 @@ module Rubino
           replace_all = edit["replace_all"] || edit[:replace_all] || false
 
           return "Error: edit ##{idx + 1} is missing old_string or new_string" if old_s.nil? || new_s.nil?
+          # Empty needle would match at every char boundary and corrupt the
+          # file under replace_all (#329a) — reject it like a missing string.
+          return "Error: edit ##{idx + 1}: old_string is empty" if old_s.empty?
           return "Error: edit ##{idx + 1}: old_string and new_string are identical" if old_s == new_s
-          unless working.include?(old_s)
+
+          old_b = to_match_bytes(old_s)
+          new_b = to_match_bytes(new_s)
+
+          unless working.include?(old_b)
+            # Mental model was wrong — let the model's next read of this path
+            # bypass dedup and fetch fresh bytes for recovery (r5 B3).
+            @read_tracker&.note_edit_failure(expanded)
             return "Error: edit ##{idx + 1}: old_string not found (check whitespace; " \
                    "remember edits see the result of prior edits)"
           end
 
-          count = working.scan(old_s).size
+          count = working.scan(old_b).size
           if count > 1 && !replace_all
             return "Error: edit ##{idx + 1}: #{count} matches for old_string. " \
                    "Add surrounding context to disambiguate, or set replace_all: true."
           end
 
           working = if replace_all
-                      working.gsub(old_s) { new_s }
+                      working.gsub(old_b) { new_b }
                     else
-                      working.sub(old_s) { new_s }
+                      working.sub(old_b) { new_b }
                     end
           applied_count += replace_all ? count : 1
         end
 
-        File.write(expanded, working)
-        "Applied #{edits.size} edit(s), #{applied_count} replacement(s) in #{file_path}"
+        # Crash-safe write: temp-in-same-dir + fsync + atomic rename. The tool's
+        # description advertises "atomically" — make it true on the disk seam too,
+        # so a SIGINT/crash mid-flush leaves the ORIGINAL file intact (HIGH-1).
+        Util::AtomicFile.write_atomic(expanded, working)
+        # Refresh-on-own-write so a follow-up edit to this file isn't refused
+        # as "changed on disk since last read" (r5 B2).
+        @read_tracker&.note_write(expanded, working)
+        { output: "Applied #{edits.size} edit(s), #{applied_count} replacement(s) in #{file_path}",
+          metrics: "#{edits.size} edit#{"s" if edits.size != 1} · " \
+                   "#{applied_count} replacement#{"s" if applied_count != 1}",
+          body: build_diff_preview(edits),
+          body_kind: :diff }
       rescue StandardError => e
-        "Error: #{e.message}"
+        # Uniform with WriteTool/EditTool: a read-only target (Errno::EACCES)
+        # or any other filesystem error returns a clean message.
+        "Error editing #{file_path}: #{e.message}"
+      end
+
+      # Inline diff for the applied result, mirroring EditTool: per edit, the
+      # old lines as `-` then the new lines as `+`, edits separated by a blank
+      # line. Trimmed to the first MAX_DIFF_LINES so a big batch stays a
+      # preview (the edits all still apply).
+      MAX_DIFF_LINES = 16
+
+      private
+
+      def build_diff_preview(edits)
+        lines = []
+        edits.each_with_index do |edit, idx|
+          old_s = edit["old_string"] || edit[:old_string]
+          new_s = edit["new_string"] || edit[:new_string]
+          lines << "" unless idx.zero?
+          lines.concat(old_s.to_s.lines.map { |l| "- #{l.chomp}" })
+          lines.concat(new_s.to_s.lines.map { |l| "+ #{l.chomp}" })
+        end
+        if lines.size > MAX_DIFF_LINES
+          dropped = lines.size - MAX_DIFF_LINES
+          lines   = lines.first(MAX_DIFF_LINES)
+          lines << "  [… #{dropped} more line(s)]"
+        end
+        lines.join("\n")
       end
     end
   end

data/lib/rubino/tools/patch_tool.rb

@@ -66,6 +66,11 @@ module Rubino
         hunks.each do |hunk|
           file_path = File.expand_path(hunk[:file], base_path)
 
+          # SECRET/credential patches (#446) are no longer HARD-refused here —
+          # they are gated UPSTREAM by Security::ApprovalPolicy#decide, which
+          # scans the patch's target paths and prompts (→ :ask) when ANY hunk
+          # touches a secret; an approved apply_patch proceeds, a denied/headless
+          # one never reaches #call. The workspace sandbox below is unchanged.
           unless within_workspace?(file_path)
             return [nil, workspace_violation_message(hunk[:file]) +
                          " (no changes applied — apply_patch is two-phase)"]

data/lib/rubino/tools/read_attachment_tool.rb

@@ -93,7 +93,9 @@ module Rubino
                  "reads documents and text. Inspect other kinds via the shell."
         end
 
-        markdown = Rubino::Documents.to_markdown(cls.path, mime: cls.mime)
+        # Thread the cancel_token so a runaway/bomb conversion is interruptible
+        # mid-flight and bounded by the converter's wall-clock/element caps.
+        markdown = Rubino::Documents.to_markdown(cls.path, mime: cls.mime, cancel_token: @cancel_token)
         # No in-process converter (unknown format / optional gem absent): degrade
         # with the actionable shell-extraction hint, exactly like the preamble.
         # NEVER raise -- a missing gem must not break the turn.

data/lib/rubino/tools/read_tool.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Rubino
   module Tools
     # Reads a file with `cat -n` style line numbers, offset/limit windowing,
@@ -49,7 +51,12 @@ module Rubino
 
         return "Error: file_path is required" if file_path.nil? || file_path.to_s.empty?
 
-        expanded = File.expand_path(file_path)
+        expanded = expand_workspace_path(file_path)
+        # Reads are BROAD (#406): like Hermes/Claude/Codex, read resolves any
+        # NON-secret path with no prompt (clone-and-inspect). A SECRET/credential
+        # path (#446) is NOT refused here anymore — it is gated UPSTREAM by
+        # Security::ApprovalPolicy#decide (→ :ask), so an APPROVED read returns
+        # the real bytes while a denied/headless read never reaches #call.
         return "Error: File not found: #{file_path}" unless File.exist?(expanded)
         return "Error: Not a regular file: #{file_path}" unless File.file?(expanded)
 
@@ -64,20 +71,21 @@ module Rubino
         offset = 1 if offset < 1
         limit  = DEFAULT_LIMIT if limit <= 0
 
-        # Stash mtime BEFORE rendering so a slow render on a huge file doesn't
-        # race with a concurrent writer — we want the mtime the model "saw",
-        # not the one at end-of-render.
-        mtime = File.mtime(expanded)
-        @read_tracker&.register(expanded, mtime)
-
-        # Re-reading the exact same window (same file, offset, limit, unchanged
-        # mtime) within a turn just re-injects bytes already in context. Return
-        # a short nudge instead so the conversation doesn't carry the same
-        # content twice. A real edit bumps mtime, so legitimate re-reads pass.
-        dup = @read_tracker&.register_window(expanded, offset, limit, mtime)
-        if dup && dup > 1
+        # Stash mtime + content hash BEFORE rendering so a slow render on a huge
+        # file doesn't race with a concurrent writer — we want the state the
+        # model "saw", not the one at end-of-render. The hash is the single
+        # source of truth the edit-gate and dedup both consult.
+        mtime  = File.mtime(expanded)
+        digest = Digest::SHA256.hexdigest(File.binread(expanded))
+        @read_tracker&.register(expanded, mtime, digest)
+
+        # Re-reading the exact same window of UNCHANGED bytes just re-injects
+        # content already in context. Skip the work with a nudge — but only when
+        # the file still hashes the same, the TTL holds, and no edit-failure
+        # recovery is pending (those serve fresh content). See ReadTracker.
+        if @read_tracker&.duplicate_read?(expanded, offset, limit, digest)
           return { output: "[DUPLICATE READ] Exact repeat of an earlier read of #{file_path} " \
-                           "(lines #{offset}-#{offset + limit - 1}) this turn — reuse that result " \
+                           "(lines #{offset}-#{offset + limit - 1}) — reuse that result " \
                            "instead of re-reading.",
                    metrics: "duplicate" }
         end
@@ -161,12 +169,22 @@ module Rubino
         last_shown  = offset - 1
         byte_capped = false
 
-        File.open(expanded, "r") do |io|
+        # Open as UTF-8 regardless of the process locale (#273): under a bare
+        # C/POSIX locale the default external encoding is US-ASCII, which would
+        # tag every line ASCII and force the scrub below to mangle perfectly
+        # valid UTF-8 file content. Pinning UTF-8 reads it correctly.
+        File.open(expanded, "r:UTF-8") do |io|
           io.each_line do |line|
             total_lines += 1
             next if total_lines < offset
             break if total_lines > last_line
 
+            # A single non-UTF-8 byte (e.g. a Latin-1 `é` in a legacy/EU
+            # source comment) would otherwise blow up `chomp`/`format` with
+            # "invalid byte sequence in UTF-8". Scrub it to the replacement
+            # char so the model can still read (and then edit) the file —
+            # lossy but graceful, instead of a blind read failure.
+            line = line.scrub unless line.valid_encoding?
             chomped = line.chomp
             chomped = chomped.byteslice(0, MAX_LINE_WIDTH) + "… [line truncated]" if chomped.bytesize > MAX_LINE_WIDTH
             out << format("%6d\t%s\n", total_lines, chomped)

data/lib/rubino/tools/read_tracker.rb

@@ -1,29 +1,45 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Rubino
   module Tools
-    # Tracks which files the model has Read during the current session so
-    # Edit and MultiEdit can refuse to write to a file the model never
-    # opened. Without this, the model is free to "remember" the contents of
-    # a file from training-time priors and edit a string that isn't actually
-    # there, corrupting the file silently when the gsub goes through anyway
-    # because the match happens to occur by accident.
+    # Single source of truth for per-path read/write state in a session, keyed
+    # on {content-hash, mtime}. Edit / MultiEdit / Write consult it before
+    # writing so the model can't edit a file it never opened (and would then be
+    # editing from training-time priors), and ReadTool consults it to skip
+    # re-emitting bytes already in context.
+    #
+    # WHY hash AND mtime (not mtime alone): the agent's OWN write bumps mtime,
+    # and so does a no-op `touch`, a CRLF normalisation, or a linter that
+    # rewrites the file to byte-identical content. mtime alone false-collides
+    # on all of those and trips the stale-read guard against the agent itself
+    # (r5 B2). We therefore record the content hash too: a path is "fresh" when
+    # EITHER the mtime is unchanged OR the on-disk content still hashes to what
+    # we last saw — so a touch / CRLF / linter rewrite to the same bytes does
+    # not force a re-read.
+    #
+    # REFRESH-ON-OWN-WRITE (r5 B2): a successful write/edit records the NEW
+    # content+mtime here via #note_write, so the agent's own writes are
+    # authoritative and the very next edit to the same file passes the gate
+    # instead of "changed on disk since last read".
     #
-    # The tracker also stashes the mtime at the moment of read so the edit
-    # path can detect "file changed under us" — the user saving from a
-    # separate editor, or another tool mutating the file after the read.
+    # DEDUP + RECOVERY (r5 B3): the duplicate-read nudge must SKIP WORK but
+    # NEVER serve stale bytes. #duplicate_read? returns true only when the same
+    # window was read AND the file still hashes to what that read saw AND a
+    # short TTL has not elapsed AND no edit-failure recovery is pending for the
+    # path. A failed edit calls #note_edit_failure(path); the next read of that
+    # path always serves fresh content (the dedup is suppressed once).
     #
-    # Lifecycle: one instance PER SESSION (see .for_session), shared by
-    # every turn's ToolExecutor in this process — a read in turn 1 still
-    # satisfies the gate in turn 2 while the file is unchanged on disk; any
-    # mtime bump forces a re-read (#151). Resume in a NEW process does NOT
-    # carry the tracker — the model must re-read after a resume before
-    # editing. That's the conservative call: the file may have changed on
-    # disk in the gap.
+    # Lifecycle: one instance PER SESSION (see .for_session), shared by every
+    # turn's ToolExecutor in this process. Resume in a NEW process does NOT
+    # carry the tracker — the model must re-read after a resume before editing.
     class ReadTracker
-      # One tracker per session id, lazily created, process-local. A nil or
-      # empty id (one-shot calls without a session) gets a throwaway
-      # instance, preserving the old per-executor behaviour there.
+      # How long a duplicate-read nudge stays valid. Past this the model may
+      # legitimately want the bytes back in context (long turn, summarised
+      # away), so we serve the content again rather than nudge.
+      DEDUP_TTL_SECONDS = 120
+
       @registry = {}
       @registry_mutex = Mutex.new
 
@@ -41,47 +57,149 @@ module Rubino
       end
 
       def initialize
-        @reads   = {}
-        @windows = Hash.new(0)
+        # path => { mtime:, hash: } — the last state we KNOW for this path,
+        # whether from a read or from the agent's own write.
+        @state = {}
+        # [path, offset, limit] => { hash:, at: } — windows already served, so
+        # an identical re-read of unchanged bytes is a duplicate.
+        @windows = {}
+        # paths whose last edit failed: the next read bypasses dedup so a
+        # recovery re-read always returns fresh content.
+        @recover = {}
+        @mutex = Mutex.new
+      end
+
+      # Records a successful read: stash mtime + content hash so a later edit
+      # can confirm the file is unchanged, and a later read of the same window
+      # can be deduped.
+      def register(path, mtime, content_hash = nil)
+        key = canonical(path)
+        return unless key
+
+        @mutex.synchronize do
+          @state[key] = { mtime: mtime, hash: content_hash || hash_of(key) }
+        end
       end
 
-      def register(path, mtime)
+      # Records the agent's OWN successful write/edit: the new content is now
+      # authoritative, so the next edit must NOT trip the stale-read guard
+      # (r5 B2). Pass the bytes just written so we hash exactly those and don't
+      # re-read the file (which could race a concurrent writer).
+      def note_write(path, new_content, mtime = nil)
         key = canonical(path)
         return unless key
 
-        @reads[key] = mtime
+        @mutex.synchronize do
+          @state[key] = { mtime: mtime || file_mtime(key), hash: hash_bytes(new_content) }
+          # An applied write is the freshest possible content — clear any
+          # pending recovery flag and stale window records for this path.
+          @recover.delete(key)
+          @windows.reject! { |(wpath, _o, _l), _v| wpath == key }
+        end
       end
 
-      # Records a read of an exact (path, offset, limit, mtime) window and
-      # returns how many times that identical window has now been requested in
-      # this session. >1 means the model is re-reading bytes it already has in
-      # context — ReadTool uses this to return a [DUPLICATE READ] nudge instead
-      # of re-emitting the same content. Keyed on mtime so a real edit between
-      # reads (mtime bump) is NOT treated as a duplicate.
-      def register_window(path, offset, limit, mtime)
+      # Flags that the last edit/multi_edit to +path+ FAILED, so the model's
+      # next read of it bypasses dedup and gets fresh disk content for recovery
+      # (r5 B3). One-shot: consumed by the next duplicate_read? check.
+      def note_edit_failure(path)
         key = canonical(path)
-        return 1 unless key
+        return unless key
 
-        sig = [key, offset.to_i, limit.to_i, mtime]
-        @windows[sig] += 1
+        @mutex.synchronize { @recover[key] = true }
       end
 
       def seen?(path)
         key = canonical(path)
         return false unless key
 
-        @reads.key?(key)
+        @mutex.synchronize { @state.key?(key) }
+      end
+
+      # True when the file on disk still matches what we last saw. The content
+      # hash is AUTHORITATIVE for change-detection: we never trust mtime alone to
+      # declare freshness, because on a coarse-mtime filesystem (Docker/linuxkit
+      # VM, some network mounts, two rapid consecutive writes) an external
+      # content change can land WITHOUT the mtime advancing — trusting mtime <=
+      # stored there would let an edit proceed on stale bytes and clobber the
+      # external change. So mtime is at most a hint: a NEWER mtime means recheck;
+      # an equal/older mtime still falls through to a hash comparison. The hash
+      # arm also lets a no-op touch / CRLF / linter rewrite to identical bytes
+      # pass without forcing a re-read (r5 B2). Returns false when we never saw
+      # the file, or it genuinely changed on disk.
+      def fresh?(path)
+        key = canonical(path)
+        return false unless key
+
+        @mutex.synchronize do
+          state = @state[key]
+          next false unless state
+
+          # Content hash is authoritative: equal/older mtime does NOT prove
+          # freshness on a coarse-mtime FS, so always confirm via the hash.
+          state[:hash] && state[:hash] == hash_of(key)
+        end
       end
 
       def mtime_at_read(path)
         key = canonical(path)
         return nil unless key
 
-        @reads[key]
+        @mutex.synchronize { @state[key]&.fetch(:mtime, nil) }
+      end
+
+      # Records a read of an exact (path, offset, limit) window and reports
+      # whether this is a duplicate the model can reuse instead of re-reading.
+      # It is a duplicate ONLY when: the same window was served before, the file
+      # still hashes to what that window saw, the TTL hasn't elapsed, AND no
+      # edit-failure recovery is pending for the path. Otherwise it records the
+      # fresh window and returns false (serve the content).
+      def duplicate_read?(path, offset, limit, content_hash = nil)
+        key = canonical(path)
+        return false unless key
+
+        digest = content_hash || hash_of(key)
+        sig = [key, offset.to_i, limit.to_i]
+
+        @mutex.synchronize do
+          # A pending recovery (prior edit failed) always serves fresh content
+          # once, then clears.
+          if @recover.delete(key)
+            @windows[sig] = { hash: digest, at: monotonic }
+            next false
+          end
+
+          prior = @windows[sig]
+          if prior && prior[:hash] == digest && (monotonic - prior[:at]) <= DEDUP_TTL_SECONDS
+            true
+          else
+            @windows[sig] = { hash: digest, at: monotonic }
+            false
+          end
+        end
       end
 
       private
 
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def file_mtime(key)
+        File.mtime(key)
+      rescue SystemCallError
+        nil
+      end
+
+      def hash_of(key)
+        hash_bytes(File.binread(key))
+      rescue SystemCallError
+        nil
+      end
+
+      def hash_bytes(bytes)
+        Digest::SHA256.hexdigest(bytes.to_s)
+      end
+
       # Same canonicalization rule as Base#canonical_path: realpath when the
       # file exists. Keeps the tracker stable across symlink components, so a
       # read via `./foo` and an edit via the full path both hit the same key.