@zalom/plastic 2.0.0-alpha.9 → 2.0.2

package/scripts/lib/runner_sweep.rb

@@ -0,0 +1,231 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require "fileutils"
+require_relative "worktree"
+require_relative "lock"
+require_relative "node_ledger"
+require_relative "ready_set"
+require_relative "savepoint"
+
+# RunnerSweep (intent 340, G7, n2): the first thing every `step` does. Two
+# separately callable entry points - #abort_if_merging and #reclaim - plus
+# #run, which composes them for a caller that has no absorb step to interleave.
+# `step` (a later node) calls #abort_if_merging, runs absorb, then calls
+# #reclaim itself, so a reclaimed node's just-landed work from absorb is never
+# thrown away by a stale read (matrix row 2.20).
+#
+# #abort_if_merging refuses the whole step when the intent worktree already
+# has a merge in progress (`MERGE_HEAD` resolves): dispatching on top of a
+# half-finished merge would hand the next node a diff full of someone else's
+# conflict markers. Nothing is written when this fires - not the ledger, not
+# graph.md, not even the delivery lease heartbeat (row 2.2, row 2.16: the
+# heartbeat runs strictly after the abort check).
+#
+# #reclaim walks every node whose CURRENT status (the ledger's own resolution,
+# never a raw scan) is `running`, skipping anything named in `skip:` (the
+# nodes this step already absorbed, row 2.19) or already terminal (a `done`
+# node is never touched, row 2.12 - it simply never shows up as `running`).
+# An expired lease with no commits on the node's own branch newer than its
+# expiry is reclaimed outright. An expired lease whose branch DOES carry
+# newer commits is extended instead, up to twice per attempt (row 2.7); the
+# extension is never a ledger transition (`running` cannot re-enter `running`
+# under the transition layer), so it is one line appended to
+# attempts/<node>--a<N>.extensions, `N` derived from the ledger's own attempt
+# count (row 2.18), never trusted from the caller. A third expiry reclaims
+# regardless of new commits.
+#
+# Pure and dependency-injected: every git call goes through an injected
+# `runner:` (default Worktree::ShellRunner), never cwd; the delivery-lease
+# heartbeat goes through an injected `heartbeat:` (default Lock.heartbeat) so
+# ordering (row 2.16) is provable without a real lock file. No eval, no
+# ENV/global-constant seam.
+module RunnerSweep
+  module_function
+
+  # D-ish: at most two extensions per attempt (row 2.7); the third expiry
+  # reclaims regardless of new commits.
+  MAX_EXTENSIONS_PER_ATTEMPT = 2
+
+  # abort_if_merging(context, runner:) -> {ok:, error:, recovery_command:}.
+  # `context.worktree` is nil for a global-store-only intent (no git repo to
+  # merge into); that case is always ok - there is nothing to abort.
+  def abort_if_merging(context, runner: Worktree::ShellRunner.new)
+    worktree = context&.worktree
+    return { ok: true, error: nil, recovery_command: nil } if blank?(worktree)
+
+    res = runner.run("-C", worktree, "rev-parse", "-q", "--verify", "MERGE_HEAD")
+    return { ok: true, error: nil, recovery_command: nil } unless res.success?
+
+    recovery_command = "git -C #{worktree} merge --abort"
+    warn "runner: a merge is already in progress in #{worktree}; run `#{recovery_command}` " \
+         "before the next step can dispatch"
+    { ok: false, error: "a merge is in progress in #{worktree}", recovery_command: recovery_command }
+  end
+
+  # reclaim(context, runner:, skip:, now:) -> {reclaimed: [{node:, holder:,
+  # expired:}], extended: [{node:, head:, time:}]}. Reads the ledger fresh on
+  # every call (no cache), which is what makes calling it AFTER absorb (row
+  # 2.20) actually see absorb's own just-landed work rather than a stale
+  # snapshot taken before it.
+  def reclaim(context, runner: Worktree::ShellRunner.new, skip: [], now: Time.now)
+    intent_dir = context.intent_dir
+    content = savepoint_content(intent_dir)
+    entries = NodeLedger.entries_from_content(content)
+    status_map = NodeLedger.status_from_content(content)
+    skip_set = Array(skip).map(&:to_s)
+
+    reclaimed = []
+    extended = []
+
+    status_map.each do |subject, state|
+      next unless state == "running"
+      next unless subject.match?(Savepoint::NODE_SUBJECT_RE)
+      next if skip_set.include?(subject)
+
+      last = entries.select { |e| !e[:torn] && e[:subject] == subject && e[:state] == "running" }.last
+      next unless last
+
+      fields = last[:fields] || {}
+      expires_raw = fields["expires"]
+      expires_at = parse_time(expires_raw)
+      next unless expires_at
+      next if now < expires_at # row 2.5: an unexpired lease is left alone
+
+      holder = fields["holder"]
+      branch = node_branch(context, subject)
+      head_sha, head_time = branch_head(runner, context.worktree, branch)
+      has_new_commits = head_time && head_time > expires_at
+
+      if has_new_commits
+        attempt = current_attempt(entries, subject)
+        count = extension_count(intent_dir, subject, attempt)
+        if count < MAX_EXTENSIONS_PER_ATTEMPT
+          record_extension(intent_dir, subject, attempt, head_sha, now)
+          extended << { node: subject, head: head_sha, time: now.utc.iso8601 }
+          next
+        end
+        # row 2.7: the cap is spent - fall through and reclaim anyway.
+      end
+
+      NodeLedger.append_transition(
+        savepoint_path(intent_dir),
+        subject: subject,
+        state: "reclaimed",
+        fields: { holder: holder, expired: expires_raw },
+        now: now
+      )
+      reclaimed << { node: subject, holder: holder, expired: expires_raw }
+    end
+
+    { reclaimed: reclaimed, extended: extended }
+  end
+
+  # run(context, runner:, skip:, now:, heartbeat:) -> the composed report a
+  # caller with no absorb step to interleave uses directly. Order is fixed on
+  # purpose (row 2.2, row 2.16): abort check, THEN the lease heartbeat, THEN
+  # reclaim - never the reverse, and never a write of any kind before the
+  # abort check has cleared.
+  def run(context, runner: Worktree::ShellRunner.new, skip: [], now: Time.now, heartbeat: Lock.method(:heartbeat))
+    abort_result = abort_if_merging(context, runner: runner)
+    unless abort_result[:ok]
+      return {
+        ok: false, aborted: true, error: abort_result[:error],
+        recovery_command: abort_result[:recovery_command], reclaimed: [], extended: [],
+      }
+    end
+
+    session = context&.session
+    heartbeat.call(context.intent_dir, session: session, now: now) unless blank?(session)
+
+    result = reclaim(context, runner: runner, skip: skip, now: now)
+    {
+      ok: true, aborted: false, error: nil, recovery_command: nil,
+      reclaimed: result[:reclaimed], extended: result[:extended],
+    }
+  end
+
+  # --- internals ---------------------------------------------------------------
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+  private_class_method :blank?
+
+  def savepoint_path(intent_dir)
+    File.join(intent_dir.to_s, "savepoint.md")
+  end
+  private_class_method :savepoint_path
+
+  def savepoint_content(intent_dir)
+    path = savepoint_path(intent_dir)
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :savepoint_content
+
+  # The node's own worktree branch (n3's naming: `plastic/<id>--<slug>--<node>`),
+  # derived from the intent id/slug alone - never through NodeWorktree, which
+  # this node does not depend on.
+  def node_branch(context, node)
+    "plastic/#{context.intent_id}--#{context.intent_slug}--#{node}"
+  end
+  private_class_method :node_branch
+
+  # [head_sha, committer_time] for `branch` in `worktree`'s repo, or [nil, nil]
+  # when the worktree is gone, the branch does not exist, or anything else
+  # about the git call fails (row 2.13: never raise).
+  def branch_head(runner, worktree, branch)
+    return [nil, nil] if blank?(worktree) || blank?(branch)
+
+    res = runner.run("-C", worktree, "log", "-1", "--format=%H%x1f%cI", branch)
+    return [nil, nil] unless res.success?
+
+    sha, iso = res.stdout.to_s.strip.split("\x1f")
+    [sha, parse_time(iso)]
+  rescue StandardError
+    [nil, nil]
+  end
+  private_class_method :branch_head
+
+  def parse_time(raw)
+    return nil if blank?(raw)
+
+    Time.iso8601(raw.to_s)
+  rescue ArgumentError
+    nil
+  end
+  private_class_method :parse_time
+
+  # Row 2.18: the attempt number comes from the ledger's own count of
+  # `running` lines since the subject's last terminal line - the exact same
+  # arithmetic NodeInput uses to name that attempt's input file, so the
+  # extensions file for a `running` line always matches the node input it extends.
+  def current_attempt(entries, subject)
+    ReadySet.attempts_count(entries, subject)
+  end
+  private_class_method :current_attempt
+
+  def extensions_path(intent_dir, node, attempt)
+    File.join(intent_dir.to_s, "attempts", "#{node}--a#{attempt}.extensions")
+  end
+  private_class_method :extensions_path
+
+  # Row 2.8: counted from the attempt-scoped file alone, so a prior attempt's
+  # extensions never count against a fresh dispatch.
+  def extension_count(intent_dir, node, attempt)
+    path = extensions_path(intent_dir, node, attempt)
+    return 0 unless File.exist?(path)
+
+    File.read(path).each_line.count { |l| !l.strip.empty? }
+  end
+  private_class_method :extension_count
+
+  # Row 2.9: the observed head sha and the time, one line, append-only.
+  def record_extension(intent_dir, node, attempt, head_sha, now)
+    path = extensions_path(intent_dir, node, attempt)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.open(path, "a") { |f| f.write("#{now.utc.iso8601}  head=#{head_sha}\n") }
+  end
+  private_class_method :record_extension
+end

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 node input 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