@zalom/plastic 2.0.0-alpha.22 → 2.0.0-alpha.24

package/scripts/lib/runner_dispatch.rb

@@ -6,7 +6,7 @@ require "yaml"
 require_relative "ready_set"
 require_relative "node_ledger"
 require_relative "node_file"
-require_relative "node_packet"
+require_relative "node_input"
 require_relative "node_worktree"
 require_relative "work_graph_validator"
 require_relative "runner_core"
@@ -14,14 +14,15 @@ require_relative "runner_policy"
 require_relative "worktree"
 require_relative "savepoint"
 require_relative "guarded_append"
+require_relative "harness_adapter"
 
 # RunnerDispatch (intent 340, G7, n5): validates the graph, computes the
-# ready set, applies RunnerPolicy, mints leases, builds packets, writes
+# ready set, applies RunnerPolicy, mints leases, builds node inputs, writes
 # `running`, and returns the dispatch plan `step` prints. Never spawns an
 # agent itself (327 D42): the session does that from the plan this returns.
 #
 # Pure and dependency-injected down to the clock: every side effect - the
-# full validator, the ready-set analyzer, the packet builder, the worktree
+# full validator, the ready-set analyzer, the input builder, the worktree
 # module, the ledger write, git itself - is an injectable keyword argument
 # with a real default, so a test never touches a real repository or a real
 # filesystem outside its own tmpdir.
@@ -31,7 +32,7 @@ module RunnerDispatch
   DEFAULT_LIMIT = 2
 
   # The return-schema instruction (327 D5): rides in the dispatch PLAN, never
-  # inside the packet, so `packet=<sha>` keeps naming a reproducible input
+  # inside the node input, so `input=<sha>` keeps naming a reproducible input
   # (matrix row 5.23). NodeReturn.parse (n4) is this text's implementation.
   RETURN_CONTRACT = <<~TEXT.freeze
     RETURN CONTRACT: reply with exactly one YAML document as your final
@@ -51,13 +52,13 @@ module RunnerDispatch
   SPAWN_AGENT = "plastic-executor"
 
   # matrix 6.1/6.2: one spawn block per dispatched node - agent, the model
-  # RunnerPolicy.model_for resolved, the packet path, the one test command
-  # (NodePacket.test_command_block, n4), and the call cap (n2) - fenced so a
+  # RunnerPolicy.model_for resolved, the node input path, the one test command
+  # (NodeInput.test_command_block, n4), and the call cap (n2) - fenced so a
   # session pastes it straight into the Agent tool (327 D42: the runner
   # itself never spawns).
-  def spawn_block(model:, packet:, test_command:, call_cap:, agent: SPAWN_AGENT)
-    lines = ["agent: #{agent}", "model: #{model}", "packet: #{packet}", test_command,
-             NodePacket.call_cap_sentence(call_cap)]
+  def spawn_block(model:, input:, test_command:, call_cap:, agent: SPAWN_AGENT)
+    lines = ["agent: #{agent}", "model: #{model}", "input: #{input}", test_command,
+             NodeInput.call_cap_sentence(call_cap)]
     (["```"] + lines + ["```"]).join("\n")
   end
 
@@ -65,16 +66,25 @@ module RunnerDispatch
   # :errors, :rearm_command, :dispatched, :stop, :parked, :status, :blockers,
   # :plan - fields that do not apply to a given outcome stay nil/empty rather
   # than being omitted, so a caller never has to guard with `dig`.
-  def dispatch(context, limit: DEFAULT_LIMIT, now: Time.now, config: {}, caps: ReadySet::DEFAULT_CAPS,
+  def dispatch(context, limit: DEFAULT_LIMIT, now: Time.now, config: {}, harness: nil, caps: ReadySet::DEFAULT_CAPS,
                validator: WorkGraphValidator.method(:validate),
                ready_analyzer: ReadySet.method(:analyze),
-               packet_builder: NodePacket.method(:build),
+               input_builder: NodeInput.method(:build),
                worktree: NodeWorktree,
                ledger: NodeLedger,
-               runner: Worktree::ShellRunner.new)
+               runner: Worktree::ShellRunner.new,
+               harness_adapter: HarnessAdapter)
     intent_dir = context.intent_dir
     savepoint_path = File.join(intent_dir.to_s, "savepoint.md")
 
+    # Intent 340b, G7c, n1, rows 1.19/1.20/D21: resolved ONCE for the whole
+    # step through HarnessAdapter, never a literal - `harness:` (this call's
+    # `--harness` override, or nil) wins over `config`'s own `agent.type`.
+    # Every node this call dispatches carries the SAME value, and the
+    # caller (scripts/runner) reads it back off the report to pick which
+    # harness's block to render.
+    harness_key = harness_adapter.resolve_key(config: config, override: harness)
+
     # Row 5.31/5.32: this is RunnerDispatch's OWN lock check, never a shelled
     # `node-transition` call - append_transition below is used in-process
     # (RunnerAbsorb's own pattern), so nothing here inherits node-transition's
@@ -122,7 +132,7 @@ module RunnerDispatch
     dispatched = []
     parked = []
     stop = nil
-    packet_failures = []
+    input_failures = []
     ceiling_blocked = false
 
     analysis[:ranked_ready].each do |row|
@@ -161,11 +171,11 @@ module RunnerDispatch
         next
       end
 
-      result = dispatch_one(context, node: node, kind: kind, now: now, config: config, caps: caps,
-                             edges: edges, nodes_decl: nodes_decl, packet_builder: packet_builder,
+      result = dispatch_one(context, node: node, kind: kind, now: now, config: config, harness: harness_key,
+                             caps: caps, edges: edges, nodes_decl: nodes_decl, input_builder: input_builder,
                              worktree: worktree, ledger: ledger, runner: runner)
-      if result[:packet_build_failed]
-        packet_failures << result
+      if result[:input_build_failed]
+        input_failures << result
         next
       end
       next unless result[:ok]
@@ -182,7 +192,8 @@ module RunnerDispatch
     RunnerCore.render_status(context) if dispatched.any? || stop || parked.any?
 
     build_report(context: context, dispatched: dispatched, stop: stop, parked: parked,
-                 ceiling_blocked: ceiling_blocked, packet_failures: packet_failures, running_count: running_count)
+                 ceiling_blocked: ceiling_blocked, input_failures: input_failures, running_count: running_count,
+                 harness: harness_key)
   end
 
   # --- guarded re-entries into graph.md (M9) ----------------------------------
@@ -201,10 +212,10 @@ module RunnerDispatch
   end
   private_class_method :safe_analyze
 
-  # --- one node's whole dispatch (packet, lease, `running`) -------------------
+  # --- one node's whole dispatch (node input, lease, `running`) -------------------
 
-  def dispatch_one(context, node:, kind:, now:, config:, caps:, edges:, nodes_decl:, packet_builder:, worktree:,
-                    ledger:, runner:)
+  def dispatch_one(context, node:, kind:, now:, config:, harness:, caps:, edges:, nodes_decl:, input_builder:,
+                    worktree:, ledger:, runner:)
     intent_dir = context.intent_dir
     savepoint_path = File.join(intent_dir.to_s, "savepoint.md")
 
@@ -220,7 +231,7 @@ module RunnerDispatch
     pre_existing_worktree = worktree_pre_existing?(worktree, context, node, kind)
 
     # Row 5.16/5.29: only a `work` node gets a worktree, and this is the
-    # node-scoped `worktree_reader:` D23 injects into NodePacket.build - it
+    # node-scoped `worktree_reader:` D23 injects into NodeInput.build - it
     # names THIS node's own worktree and branch, never the intent's.
     provisioned = RunnerPolicy.worktree?(kind) ? worktree.provision(context, node: node, kind: kind, runner: runner)
                                                 : unprovisioned
@@ -228,32 +239,36 @@ module RunnerDispatch
       { "code" => provisioned[:path], "code_branch" => provisioned[:branch], "provisioned" => !!provisioned[:provisioned] }
     end
 
-    # Row 5.18: build the packet BEFORE writing `running` - a `running` line
-    # naming bytes that do not exist yet is worse than a packet nobody reads.
+    # Row 5.18: build the node input BEFORE writing `running` - a `running` line
+    # naming bytes that do not exist yet is worse than a node input nobody reads.
     # Row 5.30: `force: true` always - a fresh attempt number this dispatch
     # computes is, by construction, never one `running` has already claimed,
     # so an existing file at that path is always an orphan from a step that
-    # crashed between building the packet and writing `running`, safe to
+    # crashed between building the node input and writing `running`, safe to
     # overwrite outright.
     # Row 5.20/10.8: the node's own declared budget: (M7) - nil when the node
-    # names none, in which case NodePacket.build falls back to its own
+    # names none, in which case NodeInput.build falls back to its own
     # default (row 10.9).
-    build_result = packet_builder.call(intent_dir: intent_dir, node: node, holder: holder, expires: expires,
+    build_result = input_builder.call(intent_dir: intent_dir, node: node, holder: holder, expires: expires,
                                         model: model, force: true, worktree_reader: node_reader,
                                         budget_tokens: node_declared_budget(intent_dir, node), call_cap: calls_cap)
     unless build_result[:ok]
-      # M6: a failed packet build never leaves an orphan worktree behind, and
+      # M6: a failed input build never leaves an orphan worktree behind, and
       # its errors travel back up so the step's report can name the node and
       # the reason instead of a bare "stalled" (row 10.6/10.7).
-      rollback_dispatch(context, node: node, kind: kind, packet_path: build_result[:path], runner: runner,
+      rollback_dispatch(context, node: node, kind: kind, input_path: build_result[:path], runner: runner,
                          worktree: worktree, created_this_dispatch: !pre_existing_worktree)
-      return { ok: false, packet_build_failed: true, node: node, errors: build_result[:errors] }
+      return { ok: false, input_build_failed: true, node: node, errors: build_result[:errors] }
     end
 
     precondition = lambda do |c|
       ReadySet.ready?(content: c, subject: node, graph: { edges: edges }, nodes: nodes_decl, caps: caps)[:ready]
     end
-    fields = { holder: holder, expires: expires, packet: build_result[:sha], model: model, calls: calls_cap }
+    # Row 1.19/1.20/D21: harness= rides alongside model= on every `running`
+    # line, resolved once by the caller through HarnessAdapter and threaded
+    # straight through here - never re-resolved, never a literal.
+    fields = { holder: holder, expires: expires, input: build_result[:sha], model: model, harness: harness,
+               calls: calls_cap }
 
     result = begin
       ledger.append_transition(savepoint_path, subject: node, state: "running", fields: fields, now: now,
@@ -266,18 +281,18 @@ module RunnerDispatch
     # side effects this method already produced - the node never ran, so
     # nothing may act like it did.
     unless result == :written
-      rollback_dispatch(context, node: node, kind: kind, packet_path: build_result[:path], runner: runner,
+      rollback_dispatch(context, node: node, kind: kind, input_path: build_result[:path], runner: runner,
                          worktree: worktree, created_this_dispatch: !pre_existing_worktree)
       return { ok: false }
     end
 
-    test_command = NodePacket.test_command_block(intent_dir: intent_dir, files: (nodes_decl[node] || {})[:files])
-    spawn = spawn_block(model: model, packet: build_result[:path], test_command: test_command, call_cap: calls_cap)
+    test_command = NodeInput.test_command_block(intent_dir: intent_dir, files: (nodes_decl[node] || {})[:files])
+    spawn = spawn_block(model: model, input: build_result[:path], test_command: test_command, call_cap: calls_cap)
 
     {
       ok: true,
       entry: { node: node, kind: kind.to_s, role: role_for(kind), model: model, worktree: provisioned[:path],
-                packet: build_result[:path], spawn: spawn },
+                input: build_result[:path], spawn: spawn },
     }
   end
 
@@ -316,10 +331,10 @@ module RunnerDispatch
 
   # Row 10.16/M13: `created_this_dispatch:` gates the worktree half of the
   # rollback - a worktree this call did not create (kept on disk by a prior
-  # attempt's failed_verification, D7) is never touched, only a packet this
-  # call's own `packet_builder` may have written is ever deleted.
-  def rollback_dispatch(context, node:, kind:, packet_path:, runner:, worktree:, created_this_dispatch:)
-    File.delete(packet_path) if packet_path && File.exist?(packet_path)
+  # attempt's failed_verification, D7) is never touched, only a node input this
+  # call's own `input_builder` may have written is ever deleted.
+  def rollback_dispatch(context, node:, kind:, input_path:, runner:, worktree:, created_this_dispatch:)
+    File.delete(input_path) if input_path && File.exist?(input_path)
     return unless RunnerPolicy.worktree?(kind)
     return unless created_this_dispatch
 
@@ -400,7 +415,7 @@ module RunnerDispatch
 
   def empty_result
     { ok: true, reason: nil, errors: [], rearm_command: nil, dispatched: [], stop: nil, parked: [],
-      status: nil, blockers: [], plan: nil }
+      status: nil, blockers: [], plan: nil, harness: nil }
   end
   private_class_method :empty_result
 
@@ -414,10 +429,10 @@ module RunnerDispatch
   end
   private_class_method :invalid_graph_result
 
-  def build_report(context:, dispatched:, stop:, parked:, ceiling_blocked: false, packet_failures: [],
-                    running_count: 0)
+  def build_report(context:, dispatched:, stop:, parked:, ceiling_blocked: false, input_failures: [],
+                    running_count: 0, harness: nil)
     base = empty_result.merge(dispatched: dispatched, stop: stop, parked: parked,
-                               plan: render_plan(dispatched))
+                               plan: render_plan(dispatched), harness: harness)
 
     if dispatched.any?
       base.merge(status: "dispatched")
@@ -438,21 +453,21 @@ module RunnerDispatch
       if complete
         base.merge(status: "complete")
       else
-        # M6/row 10.7: a failed packet build writes no ledger line at all,
+        # M6/row 10.7: a failed input build writes no ledger line at all,
         # so `named_blockers` (ledger-derived) never sees it on its own -
         # its own node and reason are named here so `stalled` never prints
         # bare.
-        blockers = named_blockers(context) + packet_failures.map { |f| packet_failure_blocker(f) }
+        blockers = named_blockers(context) + input_failures.map { |f| input_failure_blocker(f) }
         base.merge(status: "stalled", blockers: blockers)
       end
     end
   end
   private_class_method :build_report
 
-  def packet_failure_blocker(failure)
-    "#{failure[:node]}: packet build failed (#{Array(failure[:errors]).join('; ')})"
+  def input_failure_blocker(failure)
+    "#{failure[:node]}: node input build failed (#{Array(failure[:errors]).join('; ')})"
   end
-  private_class_method :packet_failure_blocker
+  private_class_method :input_failure_blocker
 
   # Row 5.25a/5.26: every unfinished node's own blockers, with ReadySet's
   # hard-attempt-cap wording renamed so it reads as the named backstop it is
@@ -479,9 +494,9 @@ module RunnerDispatch
   private_class_method :name_blocker
 
   # Row 5.22/5.23/5.24: one machine-readable (YAML) document naming, per
-  # dispatched node, the packet path, the model, the worktree, the kind and
+  # dispatched node, the node input path, the model, the worktree, the kind and
   # the role, plus the return contract ONCE at the top level - never inside
-  # any one node's packet. Row 6.4: "spawn" carries the same, already fully
+  # any one node's input. Row 6.4: "spawn" carries the same, already fully
   # rendered spawn block for each dispatched node in order, so any reader of
   # this data (YAML today, JSON if it is ever re-serialized) finds it under
   # `spawn` rather than re-deriving it from the other fields.
@@ -492,7 +507,7 @@ module RunnerDispatch
       "return_contract" => RETURN_CONTRACT,
       "dispatch" => dispatched.map do |d|
         { "node" => d[:node], "kind" => d[:kind], "role" => d[:role], "model" => d[:model],
-          "worktree" => d[:worktree], "packet" => d[:packet] }
+          "worktree" => d[:worktree], "input" => d[:input] }
       end,
       "spawn" => dispatched.map { |d| d[:spawn] }
     )

package/scripts/lib/runner_sweep.rb

@@ -32,7 +32,7 @@ require_relative "savepoint"
 # 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
-# packets/<node>--a<N>.extensions, `N` derived from the ledger's own attempt
+# 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.
 #
@@ -199,15 +199,15 @@ module RunnerSweep
 
   # 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 NodePacket uses to name that attempt's packet file, so the
-  # extensions file for a `running` line always matches the packet it extends.
+  # 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, "packets", "#{node}--a#{attempt}.extensions")
+    File.join(intent_dir.to_s, "attempts", "#{node}--a#{attempt}.extensions")
   end
   private_class_method :extensions_path
 

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