@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.20

package/scripts/lib/guarded_append.rb

@@ -0,0 +1,155 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# GuardedAppend - the shared fail-closed write guard behind NodeLedger's transition
+# lines and RoadmapSavepoint's roadmap ledger (intent 335, spec "Approach").
+#
+# One module function, #call: opens `path` RDWR|APPEND|CREAT, takes a non-blocking
+# exclusive lock with a bounded number of retries, and under that ONE hold reads the
+# current content, yields it to the caller's block, and appends whatever the block
+# returns. A block returning nil is a refusal: nothing is written. Read, decide, and
+# append happen inside one lock hold on purpose (spec "Approach"): that is what makes
+# "is this subject already running" and "append running" atomic against a second
+# writer, which a check followed by a separate append could never be.
+#
+# Pure and dependency-injected: `flock:` and `sleeper:` are constructor-style test
+# seams (never an environment variable, never a global); this module reads no
+# environment variable and shells out to nothing.
+module GuardedAppend
+  # Raised when the lock could not be taken within `retries` attempts (real
+  # contention), or when flock itself is unsupported on this filesystem and
+  # `strict: true` (spec D12a). Nothing is written either way; the caller is told
+  # plainly that nothing landed and must retry.
+  class Unavailable < StandardError; end
+
+  module_function
+
+  # Five attempts, 20 ms apart: about 100 ms of wall time total (spec D12).
+  DEFAULT_RETRIES = 5
+  DEFAULT_BACKOFF = 0.02
+
+  # Default lock and sleep seams: a real flock call, a real sleep. Tests inject
+  # replacements to simulate contention, recovery, and a flock-less filesystem
+  # hermetically, with no need for a real flock-less mount or a slow test run.
+  DEFAULT_FLOCK = ->(handle, mode) { handle.flock(mode) }
+  private_constant :DEFAULT_FLOCK
+
+  DEFAULT_SLEEPER = ->(seconds) { sleep(seconds) }
+  private_constant :DEFAULT_SLEEPER
+
+  # Open `path` (creating it if absent, never truncating it), take an exclusive
+  # non-blocking lock with up to `retries` attempts (`backoff` seconds apart), and
+  # under that one hold read the file's current content, yield it to the block, and
+  # append what the block returns.
+  #
+  # Returns :written when a line was appended, :refused when the block returned nil
+  # (nothing written, spec: a refusal). Raises Unavailable, writing nothing, when the
+  # lock could not be taken within `retries` attempts.
+  #
+  # `strict:` decides what happens when flock itself raises a SystemCallError OTHER
+  # than contention (EWOULDBLOCK/EAGAIN) - a filesystem without flock support,
+  # distinct from real contention (spec D12a): strict (the default) raises
+  # Unavailable; non-strict proceeds unguarded, since a single O_APPEND write still
+  # lands whole there. The SystemCallError rescue wraps the flock call only (spec
+  # D12b); an Errno::ENOENT from File.open (a missing parent directory) propagates
+  # as itself, never read as Unavailable.
+  def call(path, retries: DEFAULT_RETRIES, backoff: DEFAULT_BACKOFF, strict: true,
+           flock: DEFAULT_FLOCK, sleeper: DEFAULT_SLEEPER, &block)
+    created = !File.exist?(path)
+    handle = File.open(path, File::RDWR | File::APPEND | File::CREAT, 0o644)
+    begin
+      status = take_lock(handle, retries: retries, backoff: backoff, flock: flock, sleeper: sleeper)
+
+      case status
+      when :contended
+        raise Unavailable, "could not take an exclusive lock on #{path} after #{retries} attempts"
+      when :unsupported
+        if strict
+          raise Unavailable, "flock is unsupported on #{path} and strict: true refuses to proceed unguarded"
+        end
+
+        write_line(handle, &block)
+      when :locked
+        begin
+          write_line(handle, &block)
+        ensure
+          unlock(handle, flock: flock)
+        end
+      end
+    ensure
+      handle.close
+    end
+  rescue Unavailable
+    remove_freshly_created_empty_file(path) if created
+    raise
+  end
+
+  # Attempt the lock up to `retries` times. Returns :locked, :unsupported (a
+  # non-contention SystemCallError from flock, decided once, never retried), or
+  # :contended (every attempt failed with EWOULDBLOCK/EAGAIN or a false return).
+  # Sleeps `backoff` seconds after EVERY contended attempt, including the last, so
+  # the total backoff budget is exactly `retries` sleeps (spec D12: "about 100 ms of
+  # wall time in total" = 5 attempts * 20 ms, not 4).
+  def take_lock(handle, retries:, backoff:, flock:, sleeper:)
+    status = :contended
+    retries.times do
+      status = try_flock(handle, flock)
+      return status unless status == :contended
+
+      sleeper.call(backoff)
+    end
+    status
+  end
+  private_class_method :take_lock
+
+  # One attempt at the non-blocking exclusive lock. File#flock RAISES (does not
+  # return false) for every errno except EWOULDBLOCK/EAGAIN on most platforms, so
+  # both the "returns false" and the "raises EWOULDBLOCK" shapes read as contention;
+  # any other SystemCallError means flock is not supported on this filesystem.
+  def try_flock(handle, flock)
+    result = flock.call(handle, File::LOCK_EX | File::LOCK_NB)
+    result == false ? :contended : :locked
+  rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+    :contended
+  rescue SystemCallError
+    :unsupported
+  end
+  private_class_method :try_flock
+
+  # Read the current content, yield it to the block, and write what it returns. A
+  # block returning nil writes nothing and reports :refused. Before a real write, if
+  # the content is non-empty and does not end in a newline, a newline is written
+  # first (spec D9a): a crash that truncated the previous write must not glue the
+  # next transition onto its tail. The handle is opened O_APPEND, so every write
+  # lands at the current end of file regardless of the read's cursor position.
+  def write_line(handle, &block)
+    content = handle.read
+    line = block.call(content)
+    return :refused if line.nil?
+
+    prefix = !content.empty? && !content.end_with?("\n") ? "\n" : ""
+    handle.write("#{prefix}#{line}")
+    handle.flush
+    :written
+  end
+  private_class_method :write_line
+
+  def unlock(handle, flock:)
+    flock.call(handle, File::LOCK_UN)
+  rescue SystemCallError
+    nil
+  end
+  private_class_method :unlock
+
+  # Row 7.9 (post-execution review): a give-up (Unavailable) must not leave a zero-byte
+  # file behind that File::CREAT created for a target that did not exist before this
+  # call. Only ever removes a file this same call created (never a pre-existing file,
+  # spec matrix 1.11) and only when it is still empty (no write ever reached it on the
+  # give-up paths this rescues).
+  def remove_freshly_created_empty_file(path)
+    File.unlink(path) if File.exist?(path) && File.zero?(path)
+  rescue SystemCallError
+    nil
+  end
+  private_class_method :remove_freshly_created_empty_file
+end

package/scripts/lib/hook_registry.rb

@@ -54,6 +54,20 @@ module HookRegistry
           { "name" => "capture", "status" => "Capturing prompt into the session ledger..." },
         ] },
       ],
+      # This entry belongs to the Claude adapter half of Plastic's
+      # harness-agnostic-core / Claude-adapter split (intent 316a1, D3
+      # supersedes 316a's D6): MessageDisplay is not one of
+      # CODEX_LIVE_STATE_EVENTS, so codex_hooks_json (below) never picks it
+      # up; codex_hook_names stays exactly what it was (pinned by
+      # test/hook_registry_test.rb:82 and :110-111). Fires on every streamed
+      # chunk of every assistant message (D11); the launcher (hooks/message-
+      # display) decides with shell builtins and forks nothing on the common
+      # case, execing Ruby only for a candidate message.
+      "MessageDisplay" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "message-display", "status" => "" },
+        ] },
+      ],
     }
   end
 

package/scripts/lib/hook_replay.rb

@@ -0,0 +1,211 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "timeout"
+
+# HookReplay (intent 331a, T1; promoted to a production lib in 331e) - streams
+# text through a MessageDisplay launcher the way Claude Code streams an
+# assistant reply, chunk by chunk, and returns every chunk's raw stdout.
+#
+# 331a's test/support/hook_replay.rb held this as test-only code; 331e's
+# doctor `display_hook_paints` check (scripts/doctor.rb) needs the exact same
+# mechanics to replay the INSTALLED launcher for real, so the logic lives
+# here and test/support/hook_replay.rb now delegates to it (a require, not a
+# duplicate). Never require this from scripts/lib/doctor_core.rb: that file
+# is the SessionStart boot path (test/doctor_core_split_test.rb T2 pins its
+# exact require set), and the paint check that needs this lib runs only from
+# the full scripts/doctor.rb.
+module HookReplay
+  module_function
+
+  # Streams `text` through `hook_path` in fixed-size chunks. `session_id`/
+  # `message_id` default to fixed values since nothing about a replay depends
+  # on the ambient session at all.
+  #
+  # `env` (intent 331e): extra child-process environment, merged over the
+  # PLASTIC_TMP entry every call already sets (a caller's own key wins). A
+  # `nil` value unsets that variable in the child (Process.spawn's own
+  # convention) is how a caller forces NO_COLOR off regardless of the ambient
+  # environment. Default `{}` keeps every existing caller's behavior
+  # unchanged: this is an extension, not a fork.
+  #
+  # `timeout` (intent 331e): when given, bounds EACH chunk's spawn to that
+  # many seconds. A bare `Timeout.timeout` around `Open3.capture3` does not
+  # reliably bound a genuinely hanging child: capture3's own wait still
+  # blocks on Process.waitpid for the child regardless of the raised
+  # Timeout::Error (the same gotcha scripts/hook-record works around), so a
+  # timeout here spawns directly and kills the child on expiry instead.
+  # Default `nil` keeps every existing caller on the original unbounded
+  # Open3.capture3 path.
+  def replay(hook_path:, tmp_root:, text:, chunk: 40, session_id: "s-replay", message_id: "replay",
+              env: {}, timeout: nil)
+    chunks = text.scan(/.{1,#{chunk}}/m)
+    chunks = [""] if chunks.empty?
+    full_env = { "PLASTIC_TMP" => tmp_root }.merge(env)
+
+    chunks.each_with_index.map do |delta, i|
+      payload = {
+        "session_id" => session_id, "message_id" => message_id, "index" => i,
+        "final" => i == chunks.length - 1, "delta" => delta, "cwd" => tmp_root,
+        "hook_event_name" => "MessageDisplay",
+      }
+      out, err, exitstatus = run_one(hook_path, payload, full_env, tmp_root, timeout)
+      { index: i, exitstatus: exitstatus, stdout: out, stderr: err, final: payload["final"] }
+    end
+  end
+
+  # replay_concurrent (intent 331a1) - streams `text` through `hook_path` the
+  # way `replay` does, but fires every chunk in its OWN thread, staggered by
+  # `gap_ms` (plus up to half a gap of jitter when `jitter` is true) rather
+  # than run sequentially. This is what reproduces the decision-race defect
+  # 331a1 fixes: Claude Code fires the per-chunk hook processes CONCURRENTLY
+  # in production, and `replay`'s strictly-sequential default never puts two
+  # chunks in flight at once, so it could never have reproduced the race in
+  # the first place.
+  #
+  # `gap_ms: 5` plus jitter is the default on purpose, not "fire everything
+  # at once": firing all 335 chunks of the live session capture with no
+  # stagger at all takes about 8 s of wall clock on this 8-core machine,
+  # because EACH chunk boots its own real Ruby process and the completions
+  # cluster at the tail once every core is saturated - a load real streaming
+  # never produces (a real stream delivers a chunk every few tens of
+  # milliseconds, one at a time). One Ruby process per streamed chunk is the
+  # actual throughput ceiling here, not something this method works around.
+  #
+  # `replay`'s own signature and sequential default are UNCHANGED by this
+  # method's existence (`scripts/doctor.rb:2571` calls `replay` directly and
+  # must keep working exactly as it does today) - this is a sibling method
+  # in the same module, never a replacement.
+  #
+  # Returns the SAME result shape `replay` returns (one Hash per chunk, keys
+  # index/exitstatus/stdout/stderr/final), ordered by index regardless of
+  # the order the threads actually finish in.
+  def replay_concurrent(hook_path:, tmp_root:, text:, chunk: 40, session_id: "s-replay",
+                         message_id: "replay", env: {}, gap_ms: 5, jitter: true)
+    chunks = text.scan(/.{1,#{chunk}}/m)
+    chunks = [""] if chunks.empty?
+    full_env = { "PLASTIC_TMP" => tmp_root }.merge(env)
+    gap = gap_ms / 1000.0
+
+    results = Array.new(chunks.length)
+    threads = chunks.each_with_index.map do |delta, i|
+      payload = {
+        "session_id" => session_id, "message_id" => message_id, "index" => i,
+        "final" => i == chunks.length - 1, "delta" => delta, "cwd" => tmp_root,
+        "hook_event_name" => "MessageDisplay",
+      }
+      Thread.new do
+        begin
+          delay = i * gap
+          delay += (rand * gap / 2.0) if jitter
+          sleep(delay)
+          out, err, exitstatus = run_one(hook_path, payload, full_env, tmp_root, nil)
+          results[i] = { index: i, exitstatus: exitstatus, stdout: out, stderr: err, final: payload["final"] }
+        rescue StandardError => e
+          # A raise inside a thread body is invisible until join, and an
+          # unrescued one aborts `threads.each(&:join)` at the first dead
+          # thread: every later thread is then never joined and outlives the
+          # call, racing whatever the caller does next (typically removing
+          # the very tmp root those threads are still writing under). Report
+          # the failure as this chunk's own result instead, so the array is
+          # always complete, every thread is always joined, and a replay
+          # tells its caller what went wrong rather than throwing at it.
+          results[i] = { index: i, exitstatus: nil, stdout: "", stderr: e.message,
+                         final: payload["final"] }
+        end
+      end
+    end
+    threads.each { |thread| thread.join }
+    results
+  end
+
+  # Indices of the chunks that reached the terminal as raw Markdown: a
+  # non-final chunk that emitted nothing at all, after the engaging chunk.
+  # A chunk "passed through" when its stdout is empty; a chunk was
+  # "blanked" (correctly buffered, not shown raw) when its stdout contains
+  # `"displayContent":""`. Only chunks with an index greater than the
+  # engaging chunk's own index count - the engaging chunk is the first one
+  # (at or after `start_index`) whose stdout is non-empty, and chunks
+  # before it already reached the terminal live, verbatim, through the
+  # ordinary passthrough path (they were never candidates for buffering at
+  # all, so an empty stdout from one of them is not this defect).
+  def passthrough_indices(outs, start_index: 0)
+    engaging = outs.find { |o| o[:index] >= start_index && !o[:stdout].to_s.empty? }
+    return [] unless engaging
+
+    outs.select { |o| o[:index] > engaging[:index] && o[:final] != true && o[:stdout].to_s.empty? }
+        .map { |o| o[:index] }
+  end
+
+  def run_one(hook_path, payload, full_env, tmp_root, timeout)
+    return capture(hook_path, payload, full_env) unless timeout
+
+    run_bounded(hook_path, payload, full_env, tmp_root, timeout)
+  end
+
+  def capture(hook_path, payload, full_env)
+    out, err, status = Open3.capture3(full_env, hook_path, stdin_data: JSON.generate(payload))
+    [out, err, status.exitstatus]
+  end
+
+  # Spawn directly (never Open3.capture3) so a timeout can actually kill the
+  # child, with stdin/stdout/stderr routed through scratch files under the
+  # caller's own tmp_root, and never pipes, so a stalled or oversized write can
+  # never deadlock the read side, and never anywhere outside tmp_root, so a
+  # bounded replay carries the same "writes only under the injected tmp
+  # root" guarantee as the unbounded path.
+  def run_bounded(hook_path, payload, full_env, tmp_root, timeout)
+    token = "#{Process.pid}-#{(Time.now.to_f * 1_000_000).to_i}-#{rand(1_000_000)}"
+    in_path = File.join(tmp_root, ".hook-replay-in-#{token}")
+    out_path = File.join(tmp_root, ".hook-replay-out-#{token}")
+    err_path = File.join(tmp_root, ".hook-replay-err-#{token}")
+    File.write(in_path, JSON.generate(payload))
+
+    pid = Process.spawn(full_env, hook_path, in: in_path, out: out_path, err: err_path)
+    exitstatus =
+      begin
+        Timeout.timeout(timeout) { Process.wait(pid) }
+        $?.exitstatus
+      rescue Timeout::Error
+        kill_and_reap(pid)
+        nil # nil exitstatus is the caller's signal that this chunk timed out
+      end
+
+    out = File.exist?(out_path) ? File.read(out_path) : ""
+    err = File.exist?(err_path) ? File.read(err_path) : ""
+    [out, err, exitstatus]
+  ensure
+    [in_path, out_path, err_path].each { |p| File.delete(p) if p && File.exist?(p) }
+  end
+
+  def kill_and_reap(pid)
+    Process.kill("KILL", pid)
+  rescue StandardError
+    nil
+  ensure
+    begin
+      Process.wait(pid)
+    rescue StandardError
+      nil
+    end
+  end
+
+  # The final chunk's parsed displayContent, or nil when it emitted nothing
+  # (no envelope at all: the message never engaged).
+  def final_display_content(outs)
+    final = outs.last
+    return nil if final[:stdout].to_s.empty?
+
+    JSON.parse(final[:stdout]).dig("hookSpecificOutput", "displayContent")
+  rescue JSON::ParserError
+    nil
+  end
+
+  # True when any chunk's spawn hit its timeout (run_bounded's nil-exitstatus
+  # signal). A replay made with no `timeout:` never reports true.
+  def timed_out?(outs)
+    outs.any? { |o| o[:exitstatus].nil? }
+  end
+end

package/scripts/lib/index_projection.rb

@@ -0,0 +1,201 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "doctor_exclusions"
+require_relative "graph_file"
+require_relative "atomic_write"
+
+# IndexProjection (intent 337, n5): computes every intent's status from its
+# own savepoint.md ledger, reads the status INDEX.md currently claims, and
+# reports the drift between them. The ledger wins WHERE THE LEDGER SPEAKS
+# (row 5.1/5.2): a REAL terminal line (Done delivered/abandoned, or a
+# classifiable Done detail) beats a stale INDEX section. An intent whose
+# ledger is silent (no terminal line) or absent (no savepoint.md at all)
+# keeps the status INDEX already carries (row 5.13, folded at the
+# 2026-09-10 plan review): 63 of 451 intents in the plastic store have no
+# savepoint.md and 59 more never reach a Done line, and a literal reading
+# would demote all of them. This module computes and compares only; it
+# writes nothing (row 5.11) and reads no clock or environment variable.
+module IndexProjection
+  module_function
+
+  INDEX_SECTIONS = %w[Active Future Completed Abandoned].freeze
+  TERMINAL_STATUSES = %w[Completed Abandoned].freeze
+  EXCLUSION_RULES = %w[savepoint_operational backfilled_complete].freeze
+
+  # `store_path` holds the intent directories (a project's own `store/`, or
+  # the global `~/.plastic/store`). `index_path` defaults to a sibling
+  # `INDEX.md` inside `store_path` (matching every fixture in this test
+  # file), but the real Plastic layout keeps INDEX.md one level ABOVE
+  # `store/` - callers there (doctor.rb, the CLI) pass it explicitly.
+  def analyze(store_path, index_path: nil)
+    index_path ||= File.join(store_path, "INDEX.md")
+    index_map = read_index(index_path)
+    dir_ids = store_intent_ids(store_path)
+
+    excluded = excluded_ids(index_path)
+
+    drift = index_map.filter_map do |id, index_status|
+      next if index_status == "Future" # 5.5: Future has no ledger counterpart
+      next if excluded.include?(id) # 5.12
+
+      ledger_status = ledger_status_for(store_path, id)
+      next unless TERMINAL_STATUSES.include?(ledger_status) # 5.3/5.13
+      next if ledger_status == index_status
+
+      { id: id, index_status: index_status, ledger_status: ledger_status }
+    end
+
+    index_only = (index_map.keys - dir_ids).reject { |id| excluded.include?(id) }
+                                            .map { |id| { id: id, index_status: index_map[id] } }
+    directory_only = (dir_ids - index_map.keys).reject { |id| excluded.include?(id) }
+                                                .map { |id| { id: id } }
+
+    { ok: true, drift: drift, index_only: index_only, directory_only: directory_only, errors: [] }
+  end
+
+  # Render the four status sections (## Active, ## Future, ## Completed,
+  # ## Abandoned) from the projection and write through AtomicWrite. Only
+  # entries `analyze` actually reported as `drift` ever move - an entry
+  # whose ledger is silent or absent never appears in `drift` (row 5.13),
+  # so --write can never demote it (row 6.14). Every other line, including
+  # ## Clusters and ## Relocated (or any other section), is untouched
+  # (row 6.13): only the four named headings are ever replaced.
+  def write(store_path, index_path:, renamer: File.method(:rename))
+    return { ok: false, written: false, error: "no INDEX.md at #{index_path}" } unless File.exist?(index_path)
+
+    analysis = analyze(store_path, index_path: index_path)
+    text = read_utf8(index_path)
+
+    original_lines = {}
+    INDEX_SECTIONS.each do |heading|
+      section_body(text, heading).each_line do |line|
+        next unless line.strip.start_with?("- [")
+
+        m = line.strip.match(/\A-\s*\[(\S+)\s/)
+        original_lines[m[1]] = line if m
+      end
+    end
+
+    moves = analysis[:drift].each_with_object({}) { |r, h| h[r[:id]] = r[:ledger_status] }
+
+    new_bodies = INDEX_SECTIONS.each_with_object({}) do |heading, h|
+      kept = section_body(text, heading).each_line.reject do |line|
+        stripped = line.strip
+        next false unless stripped.start_with?("- [")
+
+        m = stripped.match(/\A-\s*\[(\S+)\s/)
+        m && moves.key?(m[1])
+      end
+      arriving = moves.select { |_id, target| target == heading }.keys
+      h[heading] = (kept + arriving.filter_map { |id| original_lines[id] }).join
+    end
+
+    content = text
+    INDEX_SECTIONS.each do |heading|
+      content = GraphFile.replace_or_append_section(content, "## #{heading}", new_bodies[heading].rstrip + "\n")
+    end
+
+    AtomicWrite.write(index_path, content, renamer: renamer)
+    { ok: true, written: true, moved: analysis[:drift], error: nil }
+  end
+
+  # --- INDEX -------------------------------------------------------------------
+
+  def read_index(index_path)
+    map = {}
+    return map unless File.exist?(index_path)
+
+    text = read_utf8(index_path)
+    INDEX_SECTIONS.each do |heading|
+      section_body(text, heading).each_line do |line|
+        stripped = line.strip
+        next unless stripped.start_with?("- [")
+
+        m = stripped.match(/\A-\s*\[(\S+)\s/)
+        map[m[1]] = heading if m
+      end
+    end
+    map
+  end
+
+  def section_body(text, heading)
+    m = text.match(/^##\s+#{Regexp.escape(heading)}\s*$(.*?)(?=^##\s|\z)/m)
+    m ? m[1] : ""
+  end
+
+  # --- store directories ---------------------------------------------------------
+
+  def store_intent_ids(store_path)
+    return [] unless Dir.exist?(store_path)
+
+    Dir.entries(store_path).select { |e| e.include?("--") && File.directory?(File.join(store_path, e)) }
+       .map { |e| e.split("--", 2).first }
+  end
+
+  def intent_dir_for(store_path, id)
+    Dir.glob(File.join(store_path, "#{id}--*")).find { |p| File.directory?(p) }
+  end
+
+  # --- the ledger (savepoint.md) --------------------------------------------------
+
+  # "Completed", "Abandoned", "Active" (no terminal line yet), "unknown" (no
+  # directory or no savepoint.md), or "indeterminate" (a Done line whose
+  # detail is neither delivered/merged nor abandoned, row 5.14).
+  def ledger_status_for(store_path, id)
+    dir = intent_dir_for(store_path, id)
+    return "unknown" unless dir
+
+    sp_path = File.join(dir, "savepoint.md")
+    return "unknown" unless File.exist?(sp_path)
+
+    parsed = complete_lines(read_utf8(sp_path)).filter_map { |l| parse_line(l) }
+    last_done = parsed.reverse.find { |p| p[:kind] == "Done" }
+    return "Active" unless last_done
+
+    classify_done_detail(last_done[:detail]) || "indeterminate"
+  end
+
+  # Drop the trailing torn fragment: a savepoint line that never got its
+  # closing newline because the process died mid-append (row 5.6). Works
+  # whether the file ends in a newline (the dropped element is the empty
+  # string split(-1) always yields after a final "\n") or not (the dropped
+  # element is the torn fragment itself).
+  def complete_lines(content)
+    return [] if content.to_s.empty?
+
+    lines = content.split("\n", -1)
+    lines.pop
+    lines.reject { |l| l.strip.empty? }
+  end
+
+  def parse_line(line)
+    parts = line.strip.split(/\s{2,}/, 3)
+    return nil unless parts.length == 3
+
+    { time: parts[0], kind: parts[1], detail: parts[2] }
+  end
+
+  def classify_done_detail(detail)
+    d = detail.to_s.strip
+    return "Abandoned" if d.start_with?("abandoned")
+    return "Completed" if d.start_with?("delivered") || d.start_with?("merged")
+
+    nil
+  end
+
+  # --- doctor exclusions (row 5.12) -----------------------------------------------
+
+  def excluded_ids(index_path)
+    loaded = DoctorExclusions.load(index_path)
+    EXCLUSION_RULES.flat_map { |rule| loaded[:rules][rule] || [] }.uniq
+  end
+
+  # --- utf-8 -----------------------------------------------------------------------
+
+  def read_utf8(path)
+    text = File.read(path)
+    text.force_encoding(Encoding::UTF_8)
+    text.valid_encoding? ? text : text.scrub("")
+  end
+end