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

package/scripts/lib/runner_dispatch.rb

@@ -0,0 +1,482 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require "yaml"
+require_relative "ready_set"
+require_relative "node_ledger"
+require_relative "node_file"
+require_relative "node_packet"
+require_relative "node_worktree"
+require_relative "work_graph_validator"
+require_relative "runner_core"
+require_relative "runner_policy"
+require_relative "worktree"
+require_relative "savepoint"
+require_relative "guarded_append"
+
+# RunnerDispatch (intent 340, G7, n5): validates the graph, computes the
+# ready set, applies RunnerPolicy, mints leases, builds packets, 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
+# 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.
+module RunnerDispatch
+  module_function
+
+  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
+  # (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
+    message, nothing else around it. Keys: node, status, commit, summary,
+    findings, proposed_nodes, proposed_edges, question, reason. status is one
+    of done, failed_verification, needs_decision, blocked. done requires
+    commit; needs_decision requires question; failed_verification and
+    blocked require reason. Anything that does not parse under this closed
+    schema is refused as failed_verification reason=return_unparsable.
+  TEXT
+
+  HARD_CAP_RE = /\Ais at its dispatch cap \((\d+)\/(\d+)\)\z/.freeze
+
+  # dispatch(context, limit:) -> a result hash. Always carries :ok, :reason,
+  # :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,
+               validator: WorkGraphValidator.method(:validate),
+               ready_analyzer: ReadySet.method(:analyze),
+               packet_builder: NodePacket.method(:build),
+               worktree: NodeWorktree,
+               ledger: NodeLedger,
+               runner: Worktree::ShellRunner.new)
+    intent_dir = context.intent_dir
+    savepoint_path = File.join(intent_dir.to_s, "savepoint.md")
+
+    # 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
+    # CLI-level lock refusal (exit 4) for free.
+    return lock_refusal(intent_dir) unless context.session
+
+    content = read_savepoint(savepoint_path)
+    entries = NodeLedger.entries_from_content(content)
+
+    # Row 5.1/5.2/5.3: the full validator runs only when the ledger holds no
+    # `running` line for ANY node yet (327 D17's exact precondition) - every
+    # later dispatch skips it and relies on the cheaper re-read below.
+    #
+    # M9: both the validator and the ready analyzer re-parse graph.md fresh
+    # (RunnerCore.context's own first read, already guarded, is not reused
+    # here on purpose - row 5.4), and a malformed graph.md - non-UTF-8 bytes,
+    # say - raises out of both rather than reporting :ok false. Guarded here
+    # so `step` refuses cleanly instead of dying with a raw stack trace.
+    if entries.none? { |e| e[:state] == "running" }
+      full = safe_validate(validator, intent_dir)
+      return invalid_graph_result(full[:errors]) unless full[:ok]
+    end
+
+    # Row 5.4: re-read graph.md and cycle-check on EVERY dispatch, first or
+    # not. ReadySet.analyze re-parses graph.md and nodes/ from disk itself,
+    # so nothing here trusts `context.graph`, which was resolved once,
+    # before this step even started.
+    analysis = safe_analyze(ready_analyzer, intent_dir, now: now, caps: caps)
+    return invalid_graph_result(analysis[:errors]) unless analysis[:ok]
+
+    loaded = RunnerCore.safe_load_graph(intent_dir)
+    return invalid_graph_result(loaded[:errors]) unless loaded[:ok]
+
+    edges = loaded[:edges]
+    nodes_decl = loaded[:nodes]
+
+    # Minor 9: count `running` only for NODE subjects - an `Intent` subject
+    # in a running-like state must never eat a dispatch slot meant for the
+    # concurrency ceiling over nodes.
+    running_count = NodeLedger.status_from_content(content).count do |subject, s|
+      s == "running" && subject.to_s.match?(Savepoint::NODE_SUBJECT_RE)
+    end
+    slots = [limit.to_i - running_count, 0].max
+
+    dispatched = []
+    parked = []
+    stop = nil
+    packet_failures = []
+    ceiling_blocked = false
+
+    analysis[:ranked_ready].each do |row|
+      break if stop
+
+      node = row[:id].to_s
+      kind = (nodes_decl[node] || {})[:kind] || row[:kind]
+
+      # Row 5.33: the ONLY overlap check anywhere in this loop - re-evaluated
+      # against the latest on-disk content on every iteration, so a sibling
+      # this very step just dispatched (its `running` line already written)
+      # is seen by the very next candidate, without RunnerDispatch ever
+      # carrying its own copy of the overlap rule.
+      live = ReadySet.ready?(content: content, subject: node, graph: { edges: edges }, nodes: nodes_decl,
+                              caps: caps)
+      next unless live[:ready]
+
+      if kind.to_s == "decision"
+        stop = write_decision_stop(savepoint_path, intent_dir, node, ledger: ledger, now: now)
+        content = read_savepoint(savepoint_path)
+        next
+      end
+
+      if RunnerPolicy.at_retry_cap?(entries, node, kind)
+        parked << write_retry_cap_park(savepoint_path, intent_dir, node, kind, entries, ledger: ledger, now: now)
+        content = read_savepoint(savepoint_path)
+        entries = NodeLedger.entries_from_content(content)
+        next
+      end
+
+      # M10: a ready node that cannot dispatch because every slot is taken
+      # is QUEUED, not stalled - the graph can still continue, it is merely
+      # waiting on the ceiling, matrix row 10.13.
+      if slots <= 0
+        ceiling_blocked = true
+        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,
+                             worktree: worktree, ledger: ledger, runner: runner)
+      if result[:packet_build_failed]
+        packet_failures << result
+        next
+      end
+      next unless result[:ok]
+
+      dispatched << result[:entry]
+      slots -= 1
+      content = read_savepoint(savepoint_path)
+      entries = NodeLedger.entries_from_content(content)
+    end
+
+    # Row 5.34: re-render graph.md's ## Status once, after every write this
+    # step made, mirroring RunnerAbsorb's own single call after its own
+    # transition.
+    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)
+  end
+
+  # --- guarded re-entries into graph.md (M9) ----------------------------------
+
+  def safe_validate(validator, intent_dir)
+    validator.call(intent_dir)
+  rescue StandardError => e
+    { ok: false, errors: ["graph.md could not be read: #{e.message}"] }
+  end
+  private_class_method :safe_validate
+
+  def safe_analyze(ready_analyzer, intent_dir, now:, caps:)
+    ready_analyzer.call(intent_dir, now: now, caps: caps)
+  rescue StandardError => e
+    { ok: false, errors: ["graph.md could not be read: #{e.message}"] }
+  end
+  private_class_method :safe_analyze
+
+  # --- one node's whole dispatch (packet, lease, `running`) -------------------
+
+  def dispatch_one(context, node:, kind:, now:, config:, caps:, edges:, nodes_decl:, packet_builder:, worktree:,
+                    ledger:, runner:)
+    intent_dir = context.intent_dir
+    savepoint_path = File.join(intent_dir.to_s, "savepoint.md")
+
+    holder = context.session
+    model = RunnerPolicy.model_for(kind, config: config)
+    expires = RunnerPolicy.lease_expires(kind, now: now)
+
+    # Row 10.16/M13: recorded BEFORE provisioning - a worktree this dispatch
+    # finds already on disk (kept there by a prior failed_verification
+    # attempt, D7) must never be the one a later rollback in this same call
+    # deletes; only a worktree THIS call actually creates may be rolled back.
+    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
+    # 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
+    node_reader = lambda do |intent_dir:|
+      { "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.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
+    # 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
+    # default (row 10.9).
+    build_result = packet_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))
+    unless build_result[:ok]
+      # M6: a failed packet 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,
+                         worktree: worktree, created_this_dispatch: !pre_existing_worktree)
+      return { ok: false, packet_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 }
+
+    result = begin
+      ledger.append_transition(savepoint_path, subject: node, state: "running", fields: fields, now: now,
+                                precondition: precondition)
+    rescue GuardedAppend::Unavailable
+      :unavailable
+    end
+
+    # Row 5.20: a refused (or unavailable) `running` write rolls back both
+    # 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,
+                         worktree: worktree, created_this_dispatch: !pre_existing_worktree)
+      return { ok: false }
+    end
+
+    {
+      ok: true,
+      entry: { node: node, kind: kind.to_s, role: role_for(kind), model: model, worktree: provisioned[:path],
+                packet: build_result[:path] },
+    }
+  end
+
+  # The node's own declared budget: (frontmatter), or nil when it names
+  # none - M7. Parsed directly off the node file, never through
+  # `nodes_decl` (ReadySet.load_graph's own decl hash carries only kind and
+  # files, never budget), so this stays independent of that module.
+  def node_declared_budget(intent_dir, node)
+    path = ReadySet.find_node_path(intent_dir, node)
+    return nil unless path
+
+    nf = NodeFile.parse(path)
+    nf[:ok] ? nf[:budget] : nil
+  end
+  private_class_method :node_declared_budget
+
+  # true iff a `work` node's own worktree already exists BEFORE this call
+  # provisions anything - the pre-check `rollback_dispatch` needs to tell a
+  # worktree this dispatch created from one it merely found (row 10.16).
+  def worktree_pre_existing?(worktree, context, node, kind)
+    return false unless RunnerPolicy.worktree?(kind)
+
+    p = worktree.paths(context, node: node)
+    !!(p && p["path"] && Dir.exist?(p["path"]))
+  end
+  private_class_method :worktree_pre_existing?
+
+  def role_for(kind)
+    kind.to_s == "verify" ? "advisor" : "executor"
+  end
+
+  def unprovisioned
+    { ok: true, path: nil, branch: nil, provisioned: false }
+  end
+  private_class_method :unprovisioned
+
+  # 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)
+    return unless RunnerPolicy.worktree?(kind)
+    return unless created_this_dispatch
+
+    p = worktree.paths(context, node: node)
+    return if p["path"].nil? || !Dir.exist?(p["path"])
+
+    Worktree.remove_worktree(runner, repo: p["repo"], worktree: p["path"])
+    Worktree.prune(runner, repo: p["repo"])
+  end
+  private_class_method :rollback_dispatch
+
+  # --- decision stop and the retry-cap park -----------------------------------
+
+  # Row 5.9/5.10: a ready decision node is never dispatched - it stops the
+  # WHOLE step (any node ranked after it this step is simply not reached)
+  # and writes its own `needs_decision` line so it reads that way from
+  # `status` too, carrying the exact `runner answer` command that clears it.
+  def write_decision_stop(savepoint_path, intent_dir, node, ledger:, now:)
+    question = decision_question(intent_dir, node)
+    safe_append(ledger, savepoint_path, node, "needs_decision", { question: question }, now: now)
+    { reason: "decision", node: node, question: question, answer_command: answer_command(intent_dir, node) }
+  end
+  private_class_method :write_decision_stop
+
+  # Row 5.11/5.27/5.28: a node at RunnerPolicy's SOFT cap is parked at
+  # `needs_decision` with a synthesized `question=` rather than dispatched a
+  # further time, carrying the same `runner answer` shape.
+  def write_retry_cap_park(savepoint_path, intent_dir, node, kind, entries, ledger:, now:)
+    count = RunnerPolicy.retry_count(entries, node)
+    cap = RunnerPolicy.retry_cap(kind)
+    question = "#{node} has failed verification #{count} time(s), its #{kind} retry cap is #{cap}; " \
+               "retry, rewind, or abandon it?"
+    safe_append(ledger, savepoint_path, node, "needs_decision", { question: question }, now: now)
+    { reason: "retry_cap", node: node, question: question, answer_command: answer_command(intent_dir, node) }
+  end
+  private_class_method :write_retry_cap_park
+
+  def safe_append(ledger, savepoint_path, node, state, fields, now:)
+    ledger.append_transition(savepoint_path, subject: node, state: state, fields: fields, now: now)
+  rescue GuardedAppend::Unavailable
+    nil
+  end
+  private_class_method :safe_append
+
+  def decision_question(intent_dir, node)
+    path = ReadySet.find_node_path(intent_dir, node)
+    fallback = "#{node} needs an owner decision; see its ## Question section"
+    return fallback unless path
+
+    nf = NodeFile.parse(path)
+    return fallback unless nf[:ok]
+
+    section = NodeFile.split_by_headings(nf[:body]).find { |(heading, _)| heading.to_s.strip == "## Question" }
+    text = section && section[1].to_s.strip
+    text && !text.empty? ? squash(text) : fallback
+  end
+  private_class_method :decision_question
+
+  def squash(text)
+    text.to_s.gsub(/\s+/, " ").strip
+  end
+  private_class_method :squash
+
+  # Row 5.10/5.28: the one command shape every stop and every park prints,
+  # matching scripts/runner's own published usage
+  # (`runner <step|status|answer> <intent_dir> [--node ID] [--answer TEXT]`).
+  def answer_command(intent_dir, node)
+    "runner answer #{intent_dir} --node #{node} --answer \"<your answer>\""
+  end
+
+  # Row 5.32: re-arms delivery.lock for a resumed session with a new id -
+  # `plastic-lock arm` is the shipped command that takes ownership again.
+  def rearm_command(intent_dir)
+    "plastic-lock arm --intent-dir #{intent_dir}"
+  end
+
+  # --- refusals and the report -------------------------------------------------
+
+  def empty_result
+    { ok: true, reason: nil, errors: [], rearm_command: nil, dispatched: [], stop: nil, parked: [],
+      status: nil, blockers: [], plan: nil }
+  end
+  private_class_method :empty_result
+
+  def lock_refusal(intent_dir)
+    empty_result.merge(ok: false, reason: "lock_not_held", rearm_command: rearm_command(intent_dir))
+  end
+  private_class_method :lock_refusal
+
+  def invalid_graph_result(errors)
+    empty_result.merge(ok: false, reason: "invalid_graph", errors: Array(errors))
+  end
+  private_class_method :invalid_graph_result
+
+  def build_report(context:, dispatched:, stop:, parked:, ceiling_blocked: false, packet_failures: [],
+                    running_count: 0)
+    base = empty_result.merge(dispatched: dispatched, stop: stop, parked: parked,
+                               plan: render_plan(dispatched))
+
+    if dispatched.any?
+      base.merge(status: "dispatched")
+    elsif stop
+      base.merge(status: "needs_decision")
+    elsif ceiling_blocked || running_count.to_i.positive?
+      # M10/v2 NEW-7: a ready node waiting on the concurrency ceiling is one
+      # shape of "still in flight" - a graph where every ready node is
+      # ALREADY running (no candidate ever reaches the ceiling check at all,
+      # so `ceiling_blocked` never sets) is the ordinary busy case, and it
+      # used to fall all the way through to `stalled`. Any node genuinely
+      # `running` means the graph can still continue on its own.
+      base.merge(status: "queued")
+    else
+      # Row 5.25: complete iff EVERY declared node is terminal - an empty
+      # ready set from parked/blocked nodes must never read as finished.
+      complete = RunnerCore.complete?(context)
+      if complete
+        base.merge(status: "complete")
+      else
+        # M6/row 10.7: a failed packet 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) }
+        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('; ')})"
+  end
+  private_class_method :packet_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
+  # (D22: the exit here is `runner answer`, never another dispatch), rather
+  # than one more indistinguishable blocker line.
+  def named_blockers(context)
+    intent_dir = context.intent_dir
+    rows = RunnerCore.status(context)
+    rows.each_with_object([]) do |(id, view), out|
+      next if ReadySet::TERMINAL_STATES.include?(view[:state])
+
+      view[:blockers].each { |b| out << name_blocker(intent_dir, id, b) }
+    end
+  end
+  private_class_method :named_blockers
+
+  def name_blocker(intent_dir, id, blocker)
+    rest = blocker.to_s.sub(/\A#{Regexp.escape(id)} /, "")
+    m = rest.match(HARD_CAP_RE)
+    return "#{id}: #{blocker}" unless m
+
+    "#{id} has reached its hard attempt backstop (#{m[1]}/#{m[2]}) - #{answer_command(intent_dir, id)}"
+  end
+  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
+  # the role, plus the return contract ONCE at the top level - never inside
+  # any one node's packet.
+  def render_plan(dispatched)
+    return nil if dispatched.empty?
+
+    YAML.dump(
+      "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] }
+      end
+    )
+  end
+  private_class_method :render_plan
+
+  def read_savepoint(path)
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :read_savepoint
+end

package/scripts/lib/runner_policy.rb

@@ -0,0 +1,142 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "ready_set"
+require_relative "node_worktree"
+require_relative "agent_models"
+
+# RunnerPolicy (intent 340, G7, n5): the kind table. Four facts per kind -
+# which model it runs on, whether it gets a worktree, its SOFT retry cap, and
+# its diff rule - looked up by one fallback rule: an unknown or nil kind gets
+# `work`'s row, the widest of the four, never no policy at all (matrix 5.17,
+# mirroring ReadySet's own `caps.fetch(kind) { caps["work"] }` fallback).
+#
+# This is deliberately a SECOND, SOFTER cap than ReadySet::DEFAULT_CAPS
+# (327 D22): that cap is the transition layer's hard backstop, counted as
+# `running` lines since the last terminal line, and `node-transition` is
+# never changed to accept an override of it. RunnerPolicy's cap is counted
+# from `failed_verification` lines alone (ReadySet.failed_verification_count,
+# matrix 5.12) - a node reclaimed after a crash, with no failed_verification
+# line at all, never trips this cap, exactly as 327 D12 specifies: "work runs
+# ... retry cap 2 ... verify ... retry cap 1 ... research ... retry cap 1".
+#
+# Pure and dependency-injected: `model_for` takes `config:` (an already
+# loaded config hash, AgentModels' own `agents.models` shape), never reads
+# ENV or a real config.yml itself - the caller (RunnerDispatch) owns loading
+# real config, this module only resolves values out of what it is handed.
+module RunnerPolicy
+  module_function
+
+  # D31 (327): "One advisor: the smartest model available, or the model set
+  # in user config." Never the cheap tier - that is the one thing D31 rules
+  # out for a verify node (matrix 5.14).
+  #
+  # D19 (327): "knows nothing about either harness." The executor default
+  # resolves through AgentModels::TIER_DEFAULTS, the one place
+  # `plastic-executor`'s shipped tier is already declared (post-execution
+  # review minor 4), rather than a second, independently-drifting literal
+  # here. `plastic-advisor` carries no lifecycle-stage entry in
+  # TIER_DEFAULTS at all (it is a consultation agent, never auto-dispatched
+  # - see agent_models.rb's own docstring), so its default stays the one
+  # literal this table cannot source from anywhere else.
+  DEFAULT_EXECUTOR_MODEL = AgentModels::TIER_DEFAULTS.fetch("plastic-executor")
+  DEFAULT_ADVISOR_MODEL = "opus"
+
+  EXECUTOR_CONFIG_KEY = "plastic-executor"
+  ADVISOR_CONFIG_KEY = "plastic-advisor"
+
+  # {model_role:, worktree:, retry_cap:, diff_rule:, lease_minutes:} per kind
+  # (327 D12). `decision` carries no retry cap or lease: it is never
+  # dispatched (RunnerDispatch stops the loop on one instead), so nothing
+  # here ever needs to answer "how long is a decision node's lease".
+  KIND_TABLE = {
+    "work" => { model_role: :executor, worktree: true, retry_cap: 2, diff_rule: :inside_files,
+                lease_minutes: 180 },
+    "verify" => { model_role: :advisor, worktree: false, retry_cap: 1, diff_rule: :none,
+                  lease_minutes: 30 },
+    "research" => { model_role: :executor, worktree: false, retry_cap: 1, diff_rule: :none,
+                    lease_minutes: 60 },
+    "decision" => { model_role: nil, worktree: false, retry_cap: nil, diff_rule: :none,
+                    lease_minutes: nil },
+  }.freeze
+
+  # matrix 5.17: an unknown, nil, or blank kind gets `work`'s whole row.
+  def policy_for(kind)
+    KIND_TABLE.fetch(kind.to_s, KIND_TABLE["work"])
+  end
+
+  # matrix 5.13/5.14/5.15: work and research resolve the executor model,
+  # verify resolves the advisor model, and a config with no override falls
+  # back to the shipped default rather than an empty string (`running`
+  # requires a non-blank `model=`).
+  def model_for(kind, config: {})
+    policy_for(kind)[:model_role] == :advisor ? advisor_model(config: config) : executor_model(config: config)
+  end
+
+  def executor_model(config: {})
+    resolve_model(config, EXECUTOR_CONFIG_KEY, DEFAULT_EXECUTOR_MODEL)
+  end
+
+  def advisor_model(config: {})
+    resolve_model(config, ADVISOR_CONFIG_KEY, DEFAULT_ADVISOR_MODEL)
+  end
+
+  def resolve_model(config, key, shipped_default)
+    value = AgentModels.models_section(config)[key]
+    present?(value) ? value : shipped_default
+  end
+  private_class_method :resolve_model
+
+  def present?(value)
+    !(value.nil? || value.to_s.strip.empty?)
+  end
+  private_class_method :present?
+
+  # matrix 5.16/5.17: only `work` gets a worktree; an unknown kind falls back
+  # to `work`'s own row like every other field here. `KIND_TABLE["work"]` is
+  # kept equal to `NodeWorktree::WORKTREE_KINDS` by the assertion below, so
+  # the two lists cannot silently drift apart.
+  raise "RunnerPolicy/NodeWorktree kind lists have drifted" unless KIND_TABLE.select { |_, v| v[:worktree] }.keys ==
+                                                                    NodeWorktree::WORKTREE_KINDS
+
+  def worktree?(kind)
+    !!policy_for(kind)[:worktree]
+  end
+
+  def diff_rule(kind)
+    policy_for(kind)[:diff_rule]
+  end
+
+  # matrix 5.12: the SOFT cap, or nil for a kind that carries none (decision).
+  def retry_cap(kind)
+    policy_for(kind)[:retry_cap]
+  end
+
+  # The soft-cap count itself: every non-torn `failed_verification` line for
+  # `node`, delegated to ReadySet (matrix 5.12's "counts from
+  # failed_verification lines", never from attempts).
+  def retry_count(entries, node)
+    ReadySet.failed_verification_count(entries, node.to_s)
+  end
+
+  # true only when a real cap exists AND the count has reached it (a nil cap,
+  # e.g. `decision`, never trips).
+  def at_retry_cap?(entries, node, kind)
+    cap = retry_cap(kind)
+    return false if cap.nil?
+
+    retry_count(entries, node) >= cap
+  end
+
+  # matrix 5.21: `expires=` on `running` comes from the kind's own lease
+  # length, never one shared constant - a long `work` build must not be
+  # reclaimed under a still-working executor the way a quick `verify` pass
+  # would be.
+  def lease_minutes(kind)
+    policy_for(kind)[:lease_minutes] || policy_for("work")[:lease_minutes]
+  end
+
+  def lease_expires(kind, now: Time.now)
+    (now + (lease_minutes(kind) * 60)).utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+  end
+end