@zalom/plastic 2.0.0-alpha.21 → 2.0.0-alpha.23

package/scripts/lib/runner_until_empty.rb

@@ -0,0 +1,252 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "yaml"
+require "time"
+require "rbconfig"
+require_relative "runner_core"
+require_relative "runner_sweep"
+require_relative "runner_absorb"
+require_relative "runner_dispatch"
+require_relative "node_worktree"
+require_relative "lock"
+
+# RunnerUntilEmpty (intent 340b, G7c, n7): the Codex loop. `runner
+# until-empty` composes `step` and `node-run` itself, since Codex has no
+# session on the other end to make the subagent calls `step` only ever
+# prints a plan for - dispatch, run at most two `node-run` subprocesses at
+# once, absorb each return, and around again, stopping on complete,
+# stalled, needs_decision, a refused step, or an iteration cap.
+#
+# #step_once is one turn - abort-if-merging, the heartbeat, absorb every
+# return this call carries (serially, a plain Ruby loop, never a thread),
+# reclaim, reap, then dispatch - the same fixed order scripts/runner's own
+# `run_step_body` uses, returning data rather than printing it, so #run can
+# make its own stop/continue decision instead of scraping stdout. #run is
+# the loop: it grows `active` from whatever #step_once actually dispatched
+# (already capped at the concurrency ceiling by RunnerDispatch's own
+# running-count check, never a second cap layered on top here), spawns one
+# real `node-run` subprocess per newly dispatched node, and blocks for AT
+# LEAST one of them to finish before it ever calls #step_once again - so an
+# absorb is always a single, uncontended call, and a second `node-run`
+# finishing while the first is mid-absorb simply waits its own turn as the
+# next iteration's `returns`, never as a second in-flight absorb.
+#
+# A shared `<repo>/.git` between two worktrees is a real `index.lock`
+# collision risk at commit time; this module does not try to prevent it by
+# serializing the two `node-run` processes (that would throw away the
+# concurrency this node exists to deliver) - it records the collision, on
+# whichever side actually hit it, and lets the kind's retry cap (already
+# built) recover the node on a later attempt.
+#
+# Pure and dependency-injected: `step:`, `node_run_spawner:` and
+# `node_run_waiter:` are keyword seams with real defaults, so a test can
+# drive #run entirely off doubles (no real subprocess, no real git repo)
+# for every row except the ones that are precisely about real OS
+# concurrency or the real CLI arm.
+module RunnerUntilEmpty
+  module_function
+
+  MAX_CONCURRENCY = 2
+  DEFAULT_MAX_ITERATIONS = 200
+
+  NODE_RUN_SCRIPT = File.expand_path(File.join(__dir__, "..", "node-run")).freeze
+
+  # run(context, harness:) -> {status:, iterations:, ...}. `status` is one
+  # of complete, stalled, needs_decision, iteration_cap, refused - never
+  # anything else, and the loop returns the instant it reaches one of them.
+  def run(context, harness: nil, max_iterations: DEFAULT_MAX_ITERATIONS,
+          step: method(:step_once), node_run_spawner: method(:spawn_node_run),
+          node_run_waiter: method(:wait_for_node_run), out: $stdout)
+    active = {}
+    pending_returns = {}
+    iterations = 0
+
+    loop do
+      iterations += 1
+      if iterations > max_iterations
+        out.puts "until-empty: stopped at the iteration cap (#{max_iterations})"
+        return { status: "iteration_cap", iterations: iterations - 1 }
+      end
+
+      result = step.call(context, harness: harness, returns: pending_returns)
+      pending_returns = {}
+
+      unless result[:ok]
+        out.puts "until-empty: stopped, step refused (#{result[:reason]})"
+        return { status: "refused", reason: result[:reason], iterations: iterations }
+      end
+
+      Array(result[:absorbed]).each { |a| out.puts "absorbed #{a[:node]}: #{a[:state]}" }
+
+      case result[:status]
+      when "complete"
+        out.puts "complete"
+        return { status: "complete", iterations: iterations }
+      when "stalled"
+        out.puts "stalled"
+        Array(result[:blockers]).each { |b| out.puts "blocked: #{b}" }
+        return { status: "stalled", iterations: iterations, blockers: result[:blockers] }
+      when "needs_decision"
+        stop = result[:stop]
+        out.puts "needs_decision: #{stop[:node]} - #{stop[:question]}"
+        out.puts stop[:answer_command]
+        return { status: "needs_decision", iterations: iterations, stop: stop }
+      end
+
+      Array(result[:dispatched]).each do |node|
+        next if active.key?(node)
+
+        active[node] = node_run_spawner.call(context, node: node, harness: harness)
+      end
+
+      if active.empty?
+        out.puts "stalled"
+        out.puts "blocked: queued with no active node-run to wait on"
+        return { status: "stalled", iterations: iterations,
+                 blockers: ["queued with no active node-run to wait on"] }
+      end
+
+      finished = Array(node_run_waiter.call(active))
+      finished.each do |f|
+        active.delete(f[:node])
+        out.puts "until-empty: index.lock collision recorded for #{f[:node]}" if index_lock_collision?(f)
+        pending_returns[f[:node]] = f[:return_path]
+      end
+    end
+  end
+
+  # --- one turn ----------------------------------------------------------------
+
+  # step_once(context, harness:, returns:) -> {ok:, reason:, status:,
+  # dispatched: [node ids], stop:, blockers:, absorbed: [{node:, state:}]}.
+  # Every absorb in `returns` runs in this one Ruby method, in the order
+  # `returns` iterates, before `dispatch` ever runs (row 7.3) - never a
+  # second call to this method from another thread while one is already in
+  # flight (row 7.2), because #run above never starts a second one.
+  def step_once(context, harness:, returns: {}, allow_core_drift: false, now: Time.now,
+                sweep: RunnerSweep, absorb: RunnerAbsorb, dispatch: RunnerDispatch,
+                worktree: NodeWorktree, lock: Lock, config_loader: method(:load_agent_config))
+    abort_result = sweep.abort_if_merging(context)
+    unless abort_result[:ok]
+      return refusal("merge_in_progress", abort_result[:error])
+    end
+
+    lock.heartbeat(context.intent_dir, session: context.session) unless context.session.to_s.strip.empty?
+
+    return refusal("lock_not_held", nil) unless context.session
+
+    absorbed = returns.map do |node, path|
+      result = absorb.absorb(context, node: node, return_path: path, allow_core_drift: allow_core_drift, now: now)
+      { node: node, state: result[:state] }
+    end
+
+    swept = sweep.reclaim(context, skip: returns.keys, now: now)
+    reaped = worktree.reap(context)
+
+    agent_config = config_loader.call(context.plastic_home)
+    dispatch_result = dispatch.dispatch(context, config: agent_config, harness: harness, now: now)
+    unless dispatch_result[:ok]
+      return refusal(dispatch_result[:reason], Array(dispatch_result[:errors]).join("; "))
+    end
+
+    {
+      ok: true, reason: nil, status: dispatch_result[:status],
+      dispatched: dispatch_result[:dispatched].map { |d| d[:node] },
+      stop: dispatch_result[:stop], blockers: dispatch_result[:blockers], absorbed: absorbed,
+      reclaimed: swept[:reclaimed], extended: swept[:extended], reaped: reaped[:removed],
+    }
+  end
+
+  def refusal(reason, detail)
+    { ok: false, reason: reason, detail: detail, status: nil, dispatched: [], stop: nil, blockers: [],
+      absorbed: [] }
+  end
+  private_class_method :refusal
+
+  # Mirrors scripts/runner's own Runner.load_agent_config exactly (row
+  # 1.1 of nodes/n1.md): a missing or unparseable config.yml reads as {},
+  # never raises, and it is read fresh every call rather than cached, since
+  # a long-running until-empty process must see a config edit made mid-run
+  # the same way a fresh `step` call always would.
+  def load_agent_config(plastic_home)
+    path = File.join(plastic_home.to_s, "config.yml")
+    return {} unless File.exist?(path)
+
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+
+  # --- node-run, the real subprocess --------------------------------------------
+
+  # spawn_node_run(context, node:, harness:) -> a handle {node:, pid:,
+  # stdout_io:, stderr_io:}. `harness:` is accepted for symmetry with
+  # `step_once` even though node-run itself never takes a --harness flag -
+  # the harness was already recorded on the node's own `running` line by the
+  # dispatch this call followed, and node-run reads its packet off that
+  # line, never off this argv. RUBYOPT is cleared explicitly, the same
+  # contract every other ruby-spawning site in this tree carries.
+  def spawn_node_run(context, node:, harness: nil)
+    argv = [RbConfig.ruby, NODE_RUN_SCRIPT, context.intent_dir, "--node", node]
+    argv += ["--session", context.session] if context.session
+
+    out_r, out_w = IO.pipe
+    err_r, err_w = IO.pipe
+    pid = Process.spawn({ "RUBYOPT" => nil }, *argv, out: out_w, err: err_w)
+    out_w.close
+    err_w.close
+    { node: node, pid: pid, stdout_io: out_r, stderr_io: err_r }
+  end
+
+  # wait_for_node_run(active) -> [{node:, return_path:, stderr:}] for
+  # whichever ONE handle in `active` finishes first (real concurrency
+  # between two live node-run processes; this call itself blocks on
+  # whichever exits first, never both at once). `active` is keyed by node,
+  # so a caller never needs to search its own values by pid outside this
+  # method.
+  def wait_for_node_run(active)
+    pid, = Process.waitpid2(-1)
+    handle = active.values.find { |h| h[:pid] == pid }
+    return [] unless handle
+
+    [{ node: handle[:node], return_path: read_and_close(handle[:stdout_io]).to_s.strip,
+       stderr: read_and_close(handle[:stderr_io]) }]
+  rescue Errno::ECHILD
+    []
+  end
+
+  def read_and_close(io)
+    io.read
+  rescue StandardError
+    ""
+  ensure
+    begin
+      io.close
+    rescue StandardError
+      nil
+    end
+  end
+  private_class_method :read_and_close
+
+  # index_lock_collision?(finished) -> true when either the node-run
+  # subprocess's own stderr or the return body it wrote mentions
+  # `index.lock` - the shared signature of a git ref/index lock collision
+  # between two worktrees writing into one repository's `.git` at the same
+  # time (row 7.4). Never used to change what the loop does next: the
+  # finished node's return is absorbed exactly like any other, and the
+  # kind's own retry cap is what recovers it.
+  def index_lock_collision?(finished)
+    parts = [finished[:stderr].to_s]
+    path = finished[:return_path]
+    parts << safe_read_file(path) if path && !path.empty?
+    parts.join("\n").match?(/index\.lock/i)
+  end
+
+  def safe_read_file(path)
+    File.exist?(path) ? File.read(path) : ""
+  rescue StandardError
+    ""
+  end
+  private_class_method :safe_read_file
+end

package/scripts/lib/runner_watch.rb

@@ -0,0 +1,389 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "time"
+require "rbconfig"
+require_relative "worktree"
+require_relative "runner_core"
+require_relative "runner_sweep"
+require_relative "ready_set"
+require_relative "node_ledger"
+require_relative "savepoint"
+require_relative "atomic_write"
+require_relative "runner_until_empty"
+require_relative "harness_adapter"
+require_relative "meter_watch"
+
+# RunnerWatch (intent 340a, G7b, n1): one tick over disk truth. The whole
+# watch minus the CLI and the dispatch branch (340a n2). Composes the
+# existing modules the way RunnerSweep and MeterWatch already do - the
+# git runner, the clock and the sweep module are all injected, nothing
+# reads ENV, nothing evals.
+#
+# Order, fixed by graph.md D2: take a non-blocking lock on
+# `<intent_dir>/watch.lock` for the whole tick (a losing tick is `busy`,
+# writes nothing); `RunnerSweep.abort_if_merging`; refuse the tick outright
+# on a half-finished merge (row 1.3), writing nothing; `RunnerSweep.reclaim`
+# (never `RunnerSweep.run`, D3: that method heartbeats the delivery lease,
+# which would keep a dead lead's lock fresh forever); classify (D4);
+# persist the snapshot and the record line only when `record:` holds.
+module RunnerWatch
+  module_function
+
+  LOCK_FILENAME = "watch.lock"
+  STATE_FILENAME = "watch.state"
+  RECORD_FILENAME = "watch.record"
+
+  # Classes that never dispatch (D8): a finished delivery re-running its own
+  # graph on every tick is exactly the bug a timer must not have.
+  FINISHED_CLASSES = %w[closed done_unreported].freeze
+
+  # tick(context, record:, dispatch:, harness:, now:, runner:, sweep:,
+  # until_empty:) -> {class:, blockers:, ready:, reclaimed:, dispatched:,
+  # tick:, busy:}. `dispatch:` (327 Q6, D7, D8) only ever runs under an
+  # explicit ask - never inferred from the class - and only when the lock is
+  # held, the class is not finished, and the meter does not read `stop`.
+  # `until_empty:` is `RunnerUntilEmpty` by default; a test can inject a
+  # double so the whole dispatch path never spawns a real `node-run`
+  # subprocess. `harness=` and `meter=` on the record line read `-` only
+  # when `dispatch:` itself was never asked for (D5) - every other refusal
+  # (an unheld lock, a finished class, a stopped meter) still consults and
+  # records the meter, since the tick DID look, it just chose not to act.
+  def tick(context, record: true, dispatch: false, harness: nil, now: Time.now,
+           runner: Worktree::ShellRunner.new, sweep: RunnerSweep, until_empty: RunnerUntilEmpty)
+    intent_dir = context.intent_dir.to_s
+    lock_handle = acquire_lock(File.join(intent_dir, LOCK_FILENAME))
+    return busy_result unless lock_handle
+
+    begin
+      abort_result = sweep.abort_if_merging(context, runner: runner)
+      unless abort_result[:ok]
+        return {
+          class: "merge_in_progress", blockers: [abort_result[:error]], ready: [],
+          reclaimed: [], dispatched: [], tick: nil, busy: false,
+        }
+      end
+
+      reclaim_result = sweep.reclaim(context, runner: runner, skip: [], now: now)
+      reclaimed_ids = Array(reclaim_result[:reclaimed]).map { |r| r[:node] }
+      extended = !Array(reclaim_result[:extended]).empty?
+
+      view = classify(context, runner: runner, now: now, intent_dir: intent_dir, extended: extended)
+
+      lock_state = context.session ? "held" : "not_held"
+      harness_field = "-"
+      meter_state = "-"
+      dispatched_ids = []
+
+      # B1: the dispatch loop and the persist step share one inner
+      # begin/ensure so a raise mid `until_empty.run` (a launchd SIGTERM, a
+      # Process.spawn Errno) still lands the snapshot and the record line
+      # with whatever `dispatched_ids` was collected before the raise, and
+      # then the exception keeps propagating past this method (the outer
+      # `ensure` below still releases the tick lock).
+      begin
+        if dispatch
+          harness_field = blank?(harness) ? "-" : harness.to_s
+          meter_state = read_meter_state(context)
+
+          if context.session && !FINISHED_CLASSES.include?(view[:class]) && meter_state != "stop"
+            run_until_empty_dispatch(context, harness: harness, until_empty: until_empty,
+                                      dispatched_ids: dispatched_ids)
+          end
+        end
+      ensure
+        if record
+          Worktree.ensure_gitignored(context.plastic_home, STATE_FILENAME, runner: runner)
+          write_snapshot(intent_dir, view[:snapshot])
+          append_record(
+            intent_dir, now: now, tick: view[:tick], klass: view[:class],
+            reclaimed: reclaimed_ids, ready: view[:ready], dispatched: dispatched_ids,
+            harness: harness_field, meter: meter_state, lock: lock_state
+          )
+        end
+      end
+
+      {
+        class: view[:class], blockers: view[:blockers], ready: view[:ready],
+        reclaimed: reclaimed_ids, dispatched: dispatched_ids, tick: view[:tick], busy: false,
+      }
+    ensure
+      release_lock(lock_handle)
+    end
+  end
+
+  # install_timer(context, home:, harness_key:, installer:) -> the written
+  # plist path. Graph.md D9: the Codex carrier is `runner watch
+  # --install-timer`, and it reuses MeterWatch's own writer through
+  # `label:`/`arguments:` rather than rendering plist XML here (row 3.5) - a
+  # second writer is exactly the drift D9 rules out. The label carries the
+  # intent id (row 3.4), so a second intent's timer never overwrites the
+  # first's job; `--dispatch --harness codex` rides the arguments only when
+  # `HarnessAdapter.unattended_start?` holds for the resolved harness (row
+  # 3.3), the same predicate `run_watch` itself already gates `--dispatch`
+  # on. `installer:` is `MeterWatch` by default so a test can inject a
+  # double that never touches a real home.
+  def install_timer(context, home:, harness_key:, installer: MeterWatch)
+    runner_path = File.expand_path(File.join(__dir__, "..", "runner"))
+    arguments = [RbConfig.ruby, runner_path, "watch", context.intent_dir.to_s]
+    arguments += ["--dispatch", "--harness", harness_key.to_s] if HarnessAdapter.unattended_start?(harness_key)
+
+    installer.install_timer(home: home, script_path: runner_path,
+                             label: "com.plastic.delivery-watch.#{context.intent_id}", arguments: arguments)
+  end
+
+  # run_until_empty_dispatch(context, harness:, until_empty:) -> every node
+  # id the loop dispatched (C30). `until_empty.run` gets `step:` wrapped
+  # around `until_empty.step_once` so this method sees every turn's own
+  # `:dispatched` ids, the same shape RunnerDispatch.dispatch returns
+  # (graph.md D8); `until_empty.run` itself still owns spawning and waiting
+  # on the real `node-run` subprocesses (never duplicated here).
+  def run_until_empty_dispatch(context, harness:, until_empty:, dispatched_ids:)
+    wrapped_step = lambda do |ctx, harness:, returns:|
+      result = until_empty.step_once(ctx, harness: harness, returns: returns)
+      dispatched_ids.concat(Array(result[:dispatched]))
+      result
+    end
+
+    until_empty.run(context, harness: harness, step: wrapped_step)
+  end
+  private_class_method :run_until_empty_dispatch
+
+  # read_meter_state(context) -> "ok", "reduce", "stop", "resume", "stale"
+  # (whatever MeterWatch's own tick last wrote), or "unavailable" for a
+  # missing or unparseable file (D8) - read-only, at MeterWatch's own state
+  # path under `context.plastic_home`, never through a MeterWatch instance
+  # (that class computes a FRESH state from the rate-limit cache; this tick
+  # only ever reads what it already wrote).
+  def read_meter_state(context)
+    path = File.join(context.plastic_home.to_s, ".cache", "meter-state.json")
+    return "unavailable" unless File.file?(path)
+
+    state = JSON.parse(File.read(path))["state"]
+    blank?(state) ? "unavailable" : state.to_s
+  rescue StandardError
+    "unavailable"
+  end
+  private_class_method :read_meter_state
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+  private_class_method :blank?
+
+  # fingerprint(context, runner:) -> the SHA256 D4 defines: savepoint.md's
+  # current content plus the intent branch head, so a commit that lands no
+  # ledger line still counts as movement (row 1.13). Public so a caller (and
+  # this file's own tests) can compute the exact value a tick would compute
+  # without duplicating the hashing here.
+  def fingerprint(context, runner: Worktree::ShellRunner.new)
+    content = savepoint_content(context.intent_dir)
+    Digest::SHA256.hexdigest("#{content}\x1f#{branch_head_sha(context, runner)}")
+  end
+
+  # --- the lock ----------------------------------------------------------------
+
+  def acquire_lock(path)
+    handle = File.open(path, File::CREAT | File::RDWR, 0o644)
+    return handle if handle.flock(File::LOCK_EX | File::LOCK_NB)
+
+    handle.close
+    nil
+  rescue SystemCallError
+    nil
+  end
+  private_class_method :acquire_lock
+
+  def release_lock(handle)
+    return unless handle
+
+    handle.flock(File::LOCK_UN)
+  rescue SystemCallError
+    nil
+  ensure
+    handle&.close
+  end
+  private_class_method :release_lock
+
+  def busy_result
+    { class: nil, blockers: [], ready: [], reclaimed: [], dispatched: [], tick: nil, busy: true }
+  end
+  private_class_method :busy_result
+
+  # --- classification (D4), first match wins ------------------------------------
+
+  def classify(context, runner:, now:, intent_dir:, extended: false)
+    content = savepoint_content(intent_dir)
+    recorded_pairs = Savepoint.savepoint_recorded_pairs(intent_dir)
+    previous = read_snapshot(intent_dir)
+    tick_number = (previous ? previous[:tick] : 0) + 1
+
+    if closed?(recorded_pairs)
+      return settle("closed", blockers: [], ready_ids: [], previous: previous, tick_number: tick_number,
+                     quiet_ticks: 0, content: content, context: context, runner: runner, now: now)
+    end
+
+    unless context.graph[:ok]
+      errors = Array(context.graph[:errors])
+      errors = ["graph.md could not be parsed"] if errors.empty?
+      return settle("stalled", blockers: errors, ready_ids: [], previous: previous, tick_number: tick_number,
+                     quiet_ticks: 0, content: content, context: context, runner: runner, now: now)
+    end
+
+    if RunnerCore.complete?(context)
+      return settle("done_unreported", blockers: [], ready_ids: [], previous: previous, tick_number: tick_number,
+                     quiet_ticks: 0, content: content, context: context, runner: runner, now: now)
+    end
+
+    ready_ids = ReadySet.analyze(intent_dir, now: now)[:ranked_ready].map { |r| r[:id] }
+    running = any_running?(content)
+
+    if !running && ready_ids.empty?
+      return settle("stalled", blockers: blocked_reasons(context), ready_ids: ready_ids, previous: previous,
+                     tick_number: tick_number, quiet_ticks: 0, content: content, context: context, runner: runner,
+                     now: now)
+    end
+
+    current_fingerprint = fingerprint(context, runner: runner)
+
+    # B2: a reclaim that extended a lease is evidence of live work (the
+    # sweep extends only when the node branch has commits newer than the
+    # expiry), so it counts as movement here, at the fingerprint
+    # comparison, after closed/malformed-graph/done_unreported/the
+    # nothing-running-nothing-ready stall have already returned above.
+    if extended || previous.nil? || previous[:fingerprint] != current_fingerprint
+      return settle("moving", blockers: [], ready_ids: ready_ids, previous: previous, tick_number: tick_number,
+                     quiet_ticks: 0, content: content, context: context, runner: runner, now: now,
+                     fingerprint: current_fingerprint)
+    end
+
+    next_quiet_ticks = previous[:quiet_ticks] + 1
+    if previous[:quiet_ticks] >= 1 && !unexpired_running_lease?(content, now)
+      klass = "stalled"
+      blockers = ["no observed movement for #{next_quiet_ticks} consecutive ticks and no unexpired running lease"]
+    else
+      klass = "quiet"
+      blockers = []
+    end
+
+    settle(klass, blockers: blockers, ready_ids: ready_ids, previous: previous, tick_number: tick_number,
+           quiet_ticks: next_quiet_ticks, content: content, context: context, runner: runner, now: now,
+           fingerprint: current_fingerprint)
+  end
+  private_class_method :classify
+
+  # Assembles the return view plus the snapshot that will be persisted, when
+  # `record:` is honored by the caller. `fingerprint:` defaults to a fresh
+  # computation so every class - not only moving/quiet/stalled-by-quiet -
+  # persists a value later ticks can compare against.
+  def settle(klass, blockers:, ready_ids:, previous:, tick_number:, quiet_ticks:, content:, context:, runner:,
+             now:, fingerprint: nil)
+    fp = fingerprint || RunnerWatch.fingerprint(context, runner: runner)
+    {
+      class: klass, blockers: blockers, ready: ready_ids, tick: tick_number,
+      snapshot: { fingerprint: fp, quiet_ticks: quiet_ticks, tick: tick_number, at: now.utc.iso8601 },
+    }
+  end
+  private_class_method :settle
+
+  def closed?(recorded_pairs)
+    recorded_pairs.include?(["Done", "delivered"]) || recorded_pairs.include?(["Done", "abandoned"])
+  end
+  private_class_method :closed?
+
+  def blocked_reasons(context)
+    rows = RunnerCore.status(context)
+    rows.values.reject { |v| ReadySet::TERMINAL_STATES.include?(v[:state]) || v[:ready] }
+        .flat_map { |v| v[:blockers] }
+        .uniq
+  end
+  private_class_method :blocked_reasons
+
+  def any_running?(content)
+    NodeLedger.status_from_content(content).value?("running")
+  end
+  private_class_method :any_running?
+
+  def unexpired_running_lease?(content, now)
+    status_map = NodeLedger.status_from_content(content)
+    entries = NodeLedger.entries_from_content(content)
+    status_map.any? do |subject, state|
+      next false unless state == "running"
+
+      last = entries.select { |e| !e[:torn] && e[:subject] == subject && e[:state] == "running" }.last
+      next false unless last
+
+      at = parse_time((last[:fields] || {})["expires"])
+      at && now < at
+    end
+  end
+  private_class_method :unexpired_running_lease?
+
+  def branch_head_sha(context, runner)
+    worktree = context.worktree
+    return "" if worktree.nil? || worktree.to_s.strip.empty?
+
+    res = runner.run("-C", worktree, "rev-parse", "HEAD")
+    res.success? ? res.stdout.to_s.strip : ""
+  rescue StandardError
+    ""
+  end
+  private_class_method :branch_head_sha
+
+  def parse_time(raw)
+    return nil if raw.nil? || raw.to_s.strip.empty?
+
+    Time.iso8601(raw.to_s)
+  rescue ArgumentError
+    nil
+  end
+  private_class_method :parse_time
+
+  def savepoint_content(intent_dir)
+    path = File.join(intent_dir.to_s, "savepoint.md")
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :savepoint_content
+
+  # --- the snapshot (D5) ---------------------------------------------------------
+
+  def read_snapshot(intent_dir)
+    path = File.join(intent_dir, STATE_FILENAME)
+    return nil unless File.file?(path)
+
+    data = JSON.parse(File.read(path))
+    { fingerprint: data["fingerprint"], quiet_ticks: data["quiet_ticks"].to_i, tick: data["tick"].to_i,
+      at: data["at"] }
+  rescue StandardError
+    nil
+  end
+  private_class_method :read_snapshot
+
+  def write_snapshot(intent_dir, snapshot)
+    path = File.join(intent_dir, STATE_FILENAME)
+    data = {
+      "fingerprint" => snapshot[:fingerprint], "quiet_ticks" => snapshot[:quiet_ticks],
+      "tick" => snapshot[:tick], "at" => snapshot[:at],
+    }
+    AtomicWrite.write(path, JSON.generate(data))
+  end
+  private_class_method :write_snapshot
+
+  # --- the record (D5) -----------------------------------------------------------
+
+  def append_record(intent_dir, now:, tick:, klass:, reclaimed:, ready:, dispatched:, harness: "-", meter: "-",
+                     lock:)
+    line = "#{now.utc.iso8601}  tick=#{tick} class=#{klass} reclaimed=#{list_or_dash(reclaimed)} " \
+           "ready=#{list_or_dash(ready)} dispatched=#{list_or_dash(dispatched)} harness=#{harness} " \
+           "meter=#{meter} lock=#{lock}\n"
+    File.open(File.join(intent_dir, RECORD_FILENAME), "a") { |f| f.write(line) }
+  end
+  private_class_method :append_record
+
+  def list_or_dash(list)
+    list.nil? || list.empty? ? "-" : list.join(",")
+  end
+  private_class_method :list_or_dash
+end

package/scripts/lib/savepoint.rb

@@ -145,7 +145,7 @@ module Savepoint
     ["spec.md", "graph.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
       files << f if stage_file_present?("#{intent_dir}/#{f}")
     end
-    # Name the directory that actually exists (fold B3): a nodes-only intent
+    # Name the directory that actually exists (review B3): a nodes-only intent
     # must never claim the literal "actions/" artifact it does not have.
     # Checks actions/ first, matching D15r's read order.
     if has_real_files_in?("actions", intent_dir)
@@ -160,7 +160,7 @@ module Savepoint
     ifile = intent_dir ? File.basename(intent_file(intent_dir)) : "intent.md"
     # A How-stage intent that already started a nodes/ directory is named
     # accordingly, so the next-step hint never tells a node-graph intent to
-    # go make an actions/ directory it will never use (fold B3). Mirrors
+    # go make an actions/ directory it will never use (review B3). Mirrors
     # has_real_files_in?'s actions-first order and its real-file requirement
     # (post-execution review, non-blocking 4): an intent carrying real files
     # in both directories, or a real actions/ file beside an empty or
@@ -177,7 +177,7 @@ module Savepoint
     when "why" then ["spec.md"]
     when "how"
       # A node-shaped How intent (a real graph.md already) is named after its
-      # own two artifacts, never the three D41 removed from its path (fold
+      # own two artifacts, never the three D41 removed from its path (review
       # B3, extended by 336 D13): checked via stage_file_present? alone, the
       # same primitive derive_stage itself uses.
       if intent_dir && stage_file_present?("#{intent_dir}/graph.md")

package/scripts/lib/session_git.rb

@@ -245,7 +245,7 @@ module SessionGit
   # The branch HEAD points to, even on an unborn branch (review R3: a fresh
   # `git init`, zero commits). `git rev-parse --abbrev-ref HEAD` FAILS on an
   # unborn branch (there is no commit for it to resolve yet), which the old
-  # implementation misread as "cannot determine a branch" and folded into
+  # implementation misread as "cannot determine a branch" and merged into
   # the detached-HEAD case. `git symbolic-ref --quiet --short HEAD` succeeds
   # on both a normal AND an unborn branch (HEAD is a symbolic ref to
   # `refs/heads/<name>` in both cases) and only fails when HEAD is
@@ -354,7 +354,7 @@ module SessionGit
 
     # An unknown mode/workspace value, or workspace: worktree's degradation
     # to checkout, is itself a degradation (spec D2, BLOCKER 3 ruling), so
-    # it always turns the outcome into a Note, folding both facts into the
+    # it always turns the outcome into a Note, merging both facts into the
     # single savepoint line spec D7 allows.
     Result.new(message: "#{flow_notes.join('; ')}; #{result.message}", event: "Note")
   end