@zalom/plastic 2.0.0-alpha.9 → 2.0.1

package/scripts/lib/runner_policy.rb

@@ -0,0 +1,191 @@
+# 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-primary-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-primary-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: {}, harness: "claude-code")
+    alias_or_id = policy_for(kind)[:model_role] == :advisor ? advisor_model(config: config, harness: harness) :
+                                                              executor_model(config: config, harness: harness)
+    codex_harness?(harness) ? (AgentModels.codex_model_for(alias_or_id) || alias_or_id) : alias_or_id
+  end
+
+  def executor_model(config: {}, harness: "claude-code")
+    resolve_model(config, EXECUTOR_CONFIG_KEY, DEFAULT_EXECUTOR_MODEL, harness)
+  end
+
+  def advisor_model(config: {}, harness: "claude-code")
+    resolve_model(config, ADVISOR_CONFIG_KEY, DEFAULT_ADVISOR_MODEL, harness)
+  end
+
+  def effort_for(kind, config: {}, harness: "claude-code")
+    key = policy_for(kind)[:model_role] == :advisor ? ADVISOR_CONFIG_KEY : EXECUTOR_CONFIG_KEY
+    value = AgentModels.efforts_section(config, harness_name(harness))[key]
+    present?(value) ? value : AgentModels::DEFAULT_EFFORT
+  end
+
+  def resolve_model(config, key, shipped_default, harness)
+    value = AgentModels.models_section(config, harness: harness_name(harness))[key]
+    present?(value) ? value : shipped_default
+  end
+  private_class_method :resolve_model
+
+  def harness_name(harness)
+    codex_harness?(harness) ? "codex" : "claude"
+  end
+  private_class_method :harness_name
+
+  def codex_harness?(harness)
+    harness.to_s == "codex"
+  end
+  private_class_method :codex_harness?
+
+  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
+
+  # --- call budget (intent 355, n2) -------------------------------------------
+  #
+  # D2: a cap on tool calls per attempt, enforced by a PreToolUse hook that
+  # counts tool calls in the session transcript. Shipped per kind (matrix
+  # 2.1); `decision` carries one too even though it is never dispatched
+  # (327 D12 leaves it out of every lease table for the same reason), so
+  # `call_cap` never has to special-case an unknown kind here any more than
+  # `retry_cap` does.
+  CALL_CAP_TABLE = { "work" => 60, "verify" => 40, "research" => 40, "decision" => 10 }.freeze
+
+  # matrix 5.17's own fallback rule, one call: an unknown or nil kind reads
+  # `work`'s cap, never a fourth, undeclared number.
+  def call_cap(kind, config: {})
+    override = call_caps_section(config)[kind.to_s]
+    present?(override) ? override.to_i : CALL_CAP_TABLE.fetch(kind.to_s, CALL_CAP_TABLE["work"])
+  end
+
+  # matrix 2.2: `runner.call_caps.<kind>` in the project config overrides the
+  # shipped cap, the same nested-Hash shape AgentModels.models_section reads
+  # `agents.models` from - one more caller of the pattern, not a new one.
+  def call_caps_section(config)
+    return {} unless config.is_a?(Hash)
+
+    runner = config["runner"]
+    return {} unless runner.is_a?(Hash)
+
+    section = runner["call_caps"]
+    section.is_a?(Hash) ? section : {}
+  end
+  private_class_method :call_caps_section
+end

package/scripts/lib/runner_proposals.rb

@@ -0,0 +1,275 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "node_file"
+require_relative "node_ids"
+require_relative "graph_edges"
+require_relative "graph_file"
+require_relative "atomic_write"
+require_relative "ready_set"
+require_relative "node_ledger"
+require_relative "savepoint"
+require_relative "work_graph_validator"
+
+# RunnerProposals (intent 340, G7, n6): accepts or refuses what an executor
+# proposed in its return (327 D15, D28, D30). The runner mints every node id;
+# an executor never sees or picks one. A proposed node is scaffolded from its
+# kind's template, its id substituted everywhere the template hard-codes its
+# own placeholder (`n1`, `v1`, `d1`, `r1` - the frontmatter key, the H1, and
+# the failure-mode matrix heading), and appended to graph.md's ## Graph
+# section as a fresh, undispatched line - no ledger line at all, which reads
+# as "planned" by construction. A proposed edge is accepted only when both
+# endpoints exist (among the already-declared nodes or a node this very call
+# is minting), its head is not `running`, and the resulting graph stays
+# acyclic (D30); a refusal writes one ledger comment naming which of the
+# three failed.
+#
+# One call, one all-or-nothing write (D15's "nothing is partially written"):
+# every proposed node and edge is validated BEFORE anything touches disk. A
+# single rejected edge refuses the WHOLE call, leaving graph.md and nodes/
+# byte-identical to how #accept found them, and burning no minted id (an id
+# is only ever consumed once a node FILE actually exists; NodeIds.taken never
+# sees one this call abandoned).
+#
+# Pure and dependency-injected: the full validator re-run (327 D17's "a mid-
+# run scaffold is checked, not merely accepted"), the templates directory,
+# the clock and the rename call are all injectable keyword arguments with
+# real defaults, so a test never touches a real ~/.plastic install.
+module RunnerProposals
+  module_function
+
+  KIND_TEMPLATES = {
+    "work" => "node-work.md",
+    "verify" => "node-verify.md",
+    "decision" => "node-decision.md",
+    "research" => "node-research.md",
+  }.freeze
+
+  REVIEW_FIX_CAP = 2
+
+  # accept(context, proposer:, proposed_nodes:, proposed_edges:, now:,
+  # validator:, templates_dir:, renamer:) -> {ok:, minted:, validator:,
+  # errors:}. `proposer` names the node whose return carried these proposals
+  # - it is used only to attribute the refusal comment; the runner itself
+  # decides everything about the proposal's fate.
+  def accept(context, proposer:, proposed_nodes: [], proposed_edges: [], now: Time.now,
+             validator: WorkGraphValidator.method(:validate), templates_dir: nil,
+             renamer: File.method(:rename))
+    intent_dir = context.intent_dir
+    graph_path = File.join(intent_dir, "graph.md")
+    templates_root = templates_dir || File.join(context.plastic_home.to_s, "templates")
+
+    # v2 NEW-5/row 11.8: `ReadySet.load_graph` documents itself as never
+    # raising, but that guarantee is only as good as the parser underneath
+    # it - a `graph.md` carrying invalid UTF-8 bytes raises `ArgumentError`
+    # out of `GraphFile`'s own fence-line scan before `load_graph` ever gets
+    # a chance to catch it. M4 made this call reachable straight from
+    # `RunnerAbsorb#absorb`, so a `--return` carrying a proposal against a
+    # malformed graph used to die with a raw stack trace instead of a plain
+    # refusal.
+    loaded = safe_load_graph(intent_dir)
+    return refuse(intent_dir, proposer, "graph.md is unreadable: #{loaded[:errors].join('; ')}", now) if loaded[:unreadable]
+
+    declared = loaded[:edges].keys
+    status_map = NodeLedger.status_from_content(read_savepoint(intent_dir))
+
+    mint_pool = NodeIds.taken(intent_dir).dup
+    node_specs = []
+
+    Array(proposed_nodes).each do |raw|
+      spec = stringify(raw)
+      kind = spec["kind"].to_s
+      template_name = KIND_TEMPLATES[kind]
+      unless template_name
+        return refuse(intent_dir, proposer, "proposed node kind #{kind.inspect} has no template", now)
+      end
+
+      template_path = File.join(templates_root, template_name)
+      unless File.exist?(template_path)
+        return refuse(intent_dir, proposer, "missing template for kind #{kind.inspect} at #{template_path}", now)
+      end
+
+      id = NodeFile.mint_id(kind, mint_pool)
+      mint_pool << id
+      node_specs << {
+        id: id, kind: kind, template_path: template_path,
+        needs: Array(spec["needs"]).map(&:to_s),
+        files: spec["files"].nil? ? nil : Array(spec["files"]),
+        budget: spec["budget"],
+      }
+    end
+
+    trial_edges = loaded[:edges].dup
+    node_specs.each { |s| trial_edges[s[:id]] = s[:needs] }
+    known_ids = declared + node_specs.map { |s| s[:id] }
+
+    edge_specs = []
+    Array(proposed_edges).each do |raw|
+      e = stringify(raw)
+      from = e["from"].to_s
+      to = e["to"].to_s
+
+      unless known_ids.include?(from) && known_ids.include?(to)
+        return refuse(intent_dir, proposer,
+                       "edge #{from}->#{to} refused (endpoint_unknown): both ends must be a declared or proposed node", now)
+      end
+
+      if status_map.fetch(from, "planned") == "running"
+        return refuse(intent_dir, proposer,
+                       "edge #{from}->#{to} refused (head_running): #{from} is currently running", now)
+      end
+
+      trial = trial_edges.dup
+      trial[from] = (trial[from] || []) + [to]
+      if GraphEdges.cycle(trial)
+        return refuse(intent_dir, proposer,
+                       "edge #{from}->#{to} refused (would_cycle): would make the graph cyclic", now)
+      end
+
+      trial_edges = trial
+      edge_specs << { from: from, to: to }
+    end
+
+    trial_nodes = loaded[:nodes].merge(node_specs.to_h { |s| [s[:id], { kind: s[:kind] }] })
+    existing_fixes = review_fix_count(loaded[:edges], loaded[:nodes])
+    trial_fixes = review_fix_count(trial_edges, trial_nodes)
+    if trial_fixes > [existing_fixes, REVIEW_FIX_CAP].max
+      return refuse(intent_dir, proposer,
+                     "proposal refused (review_fix_cap): would make #{trial_fixes} review fixes, the cap is #{REVIEW_FIX_CAP}", now)
+    end
+
+    node_specs.each { |s| scaffold_node_file(intent_dir, s) }
+    if node_specs.any? || edge_specs.any?
+      append_to_graph(graph_path, node_specs: node_specs, edge_specs: edge_specs, renamer: renamer)
+    end
+
+    # v2 NEW-5/row 11.8: the accept itself already landed on disk by this
+    # point (327 D17's "a mid-run scaffold is checked" runs strictly AFTER
+    # the write) - a raising validator must report a broken verdict, never
+    # turn an already-successful accept into an uncaught exception.
+    { ok: true, minted: node_specs.map { |s| s[:id] }, validator: safe_validate(validator, intent_dir), errors: [] }
+  end
+
+  # --- review fixes (355 D4) -------------------------------------------------
+
+  # review_fix_count(edges, nodes) -> how many work nodes GraphEdges.review_fixes
+  # finds, a node's kind read from its declaration and, when that is missing,
+  # from its id's NodeFile::KIND_PREFIX (343 D6).
+  def review_fix_count(edges, nodes)
+    ids = (edges.keys + edges.values.flatten).uniq
+    kinds = ids.to_h { |id| [id, (nodes[id] || {})[:kind] || NodeFile::KIND_PREFIX.key(id.to_s[/\A[a-z]+/])] }
+    GraphEdges.review_fixes(edges, kinds).length
+  end
+
+  # --- node scaffolding --------------------------------------------------
+
+  # A template's own placeholder id ("n1", "v1", ...) is replaced only as a
+  # whole token, so minting past 9 (a proposed "n10") never mangles a
+  # coincidental substring match.
+  def substitute_id(text, old_id, new_id)
+    text.to_s.gsub(/(?<![A-Za-z0-9_-])#{Regexp.escape(old_id.to_s)}(?![A-Za-z0-9_-])/, new_id.to_s)
+  end
+
+  def scaffold_node_file(intent_dir, spec)
+    parsed_template = NodeFile.parse(spec[:template_path])
+    old_id = parsed_template[:node]
+    raw = File.read(spec[:template_path])
+    parts = raw.split("---", 3)
+    body = substitute_id(parts[2].to_s, old_id, spec[:id])
+
+    files = spec[:files].nil? ? parsed_template[:files] : spec[:files]
+    budget = spec[:budget].nil? ? parsed_template[:budget] : spec[:budget]
+
+    frontmatter = "---\nnode: #{spec[:id]}\nkind: #{spec[:kind]}\nfiles: [#{Array(files).join(', ')}]\nbudget: #{budget}\n---"
+    path = File.join(intent_dir, "nodes", "#{spec[:id]}.md")
+    FileUtils.mkdir_p(File.dirname(path))
+    File.write(path, "#{frontmatter}#{body}")
+  end
+  private_class_method :scaffold_node_file
+
+  # --- graph.md editing ----------------------------------------------------
+
+  # Appends one "- <id> needs <targets>" line per minted node, then applies
+  # each accepted edge onto the line (existing or just-appended) whose id
+  # matches its `from`, through GraphFile's own public section helpers
+  # (section_bounds, section_body, replace_or_append_section - none of them
+  # private_class_method'd) so this stays a plain text edit, never a second
+  # bespoke parser.
+  def append_to_graph(graph_path, node_specs:, edge_specs:, renamer:)
+    content = File.read(graph_path)
+    bounds = GraphFile.section_bounds(content, "## Graph")
+    return unless bounds
+
+    body = GraphFile.section_body(content, "## Graph").to_s
+    lines = body.split("\n")
+
+    node_specs.each do |s|
+      rendered = s[:needs].empty? ? "nothing" : s[:needs].join(" ")
+      lines << "- #{s[:id]} needs #{rendered}"
+    end
+
+    edge_specs.each do |e|
+      idx = lines.index { |l| l.strip.match?(/\A-\s*#{Regexp.escape(e[:from])}\s+needs\b/) }
+      next unless idx
+
+      stripped = lines[idx].strip
+      m = stripped.match(/\A-\s*(\S+)\s+needs\s+(.*)\z/)
+      targets = m[2].to_s.strip.split(/\s+/)
+      targets = [] if targets == ["nothing"]
+      targets << e[:to] unless targets.include?(e[:to])
+      lines[idx] = "- #{e[:from]} needs #{targets.empty? ? 'nothing' : targets.join(' ')}"
+    end
+
+    new_body = lines.join("\n")
+    new_content = GraphFile.replace_or_append_section(content, "## Graph", new_body)
+    AtomicWrite.write(graph_path, new_content, renamer: renamer)
+  end
+  private_class_method :append_to_graph
+
+  # --- refusal -------------------------------------------------------------
+
+  # One ledger comment (a plain milestone-style line through Savepoint's own
+  # public append primitive, never a state transition - a refused proposal
+  # changes nothing about the proposer's own status) naming which of the
+  # three checks failed. Dedup'd by (stage, text) like every other such line,
+  # so an identical refusal repeated verbatim across retries writes once.
+  def refuse(intent_dir, proposer, reason, now)
+    Savepoint.append_savepoint_line(intent_dir, "Proposal", "#{proposer}: #{reason}", now)
+    { ok: false, minted: [], validator: nil, errors: [reason] }
+  end
+  private_class_method :refuse
+
+  # --- guarded re-entries into graph.md (v2 NEW-5/row 11.8) -------------------
+
+  # `unreadable: true` marks the ONE case a raise actually happened -
+  # distinct from `ReadySet.load_graph`'s own ordinary `ok: false` (a
+  # cyclic graph, a missing node file, ...), which callers here already
+  # tolerate and must keep tolerating unchanged.
+  def safe_load_graph(intent_dir)
+    ReadySet.load_graph(intent_dir)
+  rescue StandardError => e
+    { ok: false, edges: {}, nodes: {}, errors: ["graph.md could not be read: #{e.message}"], unreadable: true }
+  end
+  private_class_method :safe_load_graph
+
+  def safe_validate(validator, intent_dir)
+    validator.call(intent_dir)
+  rescue StandardError => e
+    { ok: false, missing: [], errors: ["graph.md could not be validated: #{e.message}"] }
+  end
+  private_class_method :safe_validate
+
+  # --- internals -------------------------------------------------------------
+
+  def stringify(hash)
+    (hash || {}).each_with_object({}) { |(k, v), memo| memo[k.to_s] = v }
+  end
+  private_class_method :stringify
+
+  def read_savepoint(intent_dir)
+    path = File.join(intent_dir.to_s, "savepoint.md")
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :read_savepoint
+end

package/scripts/lib/runner_rewind.rb

@@ -0,0 +1,201 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "node_ledger"
+require_relative "ready_set"
+require_relative "node_file"
+require_relative "node_ids"
+require_relative "graph_file"
+require_relative "atomic_write"
+require_relative "runner_core"
+require_relative "worktree"
+require_relative "node_worktree"
+
+# RunnerRewind (intent 340, G7, n6): resets the intent branch to a node's own
+# recorded commit, marks every downstream node superseded (its evidence no
+# longer stands once the code it was built on is gone), and respins the
+# rewound node itself the same way RunnerAnswer's hard-cap path does - never
+# a plain `planned` line, because `failed_verification_count` is counted per
+# subject id over the WHOLE ledger and never resets; only a brand new id
+# starts clean.
+#
+# Internal, confirm-gated (327 D15's rewind clause): `confirm:` must be
+# explicitly true, and the whole intent must be quiescent (no `running` node
+# anywhere) before a branch reset is safe to make - resetting the branch
+# under a live executor's own worktree would move the base it is building on
+# out from under it.
+#
+# Pure and dependency-injected: every git call goes through an injected
+# `runner:` (default Worktree::ShellRunner), always `-C <path>`, never cwd;
+# the clock and the rename call are injectable the same way every other
+# runner_* module here already is.
+module RunnerRewind
+  module_function
+
+  def rewind(context, node:, confirm:, now: Time.now, ledger: NodeLedger,
+             runner: Worktree::ShellRunner.new, renamer: File.method(:rename),
+             worktree: NodeWorktree)
+    node = node.to_s
+    return refusal("confirm_required") unless confirm
+
+    intent_dir = context.intent_dir
+    # M9: a second, unguarded re-parse of graph.md - RunnerCore.context's
+    # own first read is already safe, but this fresh read is not.
+    loaded = RunnerCore.safe_load_graph(intent_dir)
+    return refusal("invalid_graph", detail: Array(loaded[:errors]).join("; ")) unless loaded[:ok]
+
+    edges = loaded[:edges]
+    nodes_decl = loaded[:nodes]
+    before_content = read_savepoint(intent_dir)
+    entries = NodeLedger.entries_from_content(before_content)
+    status_map = NodeLedger.status_from_content(before_content)
+
+    return refusal("a_node_is_running") if status_map.value?("running")
+
+    commit = last_commit(entries, node)
+    return refusal("no_recorded_commit") if commit.nil? || commit.to_s.strip.empty?
+
+    return refusal("no_intent_worktree") if blank?(context.worktree)
+
+    reset = runner.run("-C", context.worktree, "reset", "--hard", commit)
+    return refusal("git_reset_failed", detail: reset.stderr.to_s.strip) unless reset.success?
+
+    downstream = downstream_of(node, edges)
+    downstream.each do |d|
+      ledger.append_transition(savepoint_path(intent_dir), subject: d, state: "superseded",
+                                fields: { by: node }, now: now)
+      # M5/D7: a rewind-superseded node's evidence no longer stands once the
+      # code it was built on is gone - its worktree releases here too.
+      worktree.release(context, node: d, state: "superseded", runner: runner)
+    end
+
+    succ_id = respin(intent_dir, node, nodes_decl, edges, ledger: ledger, now: now, renamer: renamer,
+                      context: context, worktree: worktree, runner: runner)
+
+    RunnerCore.render_status(context)
+
+    {
+      ok: true, reset_to: commit, superseded: downstream, respun_to: succ_id, errors: [],
+      newly_ready: newly_ready(intent_dir, before_content: before_content, before_nodes: nodes_decl,
+                                before_edges: edges),
+    }
+  end
+
+  # --- downstream: everything that, directly or transitively, needs the
+  # rewound node - the mirror of ReadySet.critical_paths' own successors map.
+
+  def downstream_of(node, edges)
+    successors = Hash.new { |h, k| h[k] = [] }
+    edges.each { |id, targets| (targets || []).each { |t| successors[t] << id } }
+
+    seen = []
+    stack = successors[node].dup
+    until stack.empty?
+      n = stack.pop
+      next if seen.include?(n)
+
+      seen << n
+      stack.concat(successors[n] || [])
+    end
+    seen.sort
+  end
+  private_class_method :downstream_of
+
+  def last_commit(entries, node)
+    last = entries.select { |e| !e[:torn] && e[:subject] == node && e[:state] == "done" }.last
+    last && (last[:fields] || {})["commit"]
+  end
+  private_class_method :last_commit
+
+  # --- the respin (327 D22, same shape as RunnerAnswer's hard-cap path) ------
+
+  def respin(intent_dir, node, nodes_decl, edges, ledger:, now:, renamer:,
+             context:, worktree: NodeWorktree, runner: Worktree::ShellRunner.new)
+    decl = nodes_decl[node] || {}
+    kind = decl[:kind]
+    node_path = ReadySet.find_node_path(intent_dir, node)
+    parsed = NodeFile.parse(node_path)
+
+    mint_pool = NodeIds.taken(intent_dir).dup
+    succ_id = NodeFile.mint_id(kind, mint_pool)
+
+    raw = File.read(node_path)
+    parts = raw.split("---", 3)
+    body = substitute_id(parts[2].to_s, node, succ_id)
+    files = parsed[:files] || decl[:files] || []
+    budget = parsed[:budget]
+
+    frontmatter = "---\nnode: #{succ_id}\nkind: #{kind}\nfiles: [#{Array(files).join(', ')}]\nbudget: #{budget}\n---"
+    succ_path = File.join(intent_dir, "nodes", "#{succ_id}.md")
+    FileUtils.mkdir_p(File.dirname(succ_path))
+    File.write(succ_path, "#{frontmatter}#{body}")
+
+    append_graph_line(File.join(intent_dir, "graph.md"), succ_id, edges[node] || [], renamer: renamer)
+
+    ledger.append_transition(savepoint_path(intent_dir), subject: node, state: "superseded",
+                              fields: { by: succ_id }, now: now)
+
+    # M5/D7: the rewound node's own worktree releases too, same as the
+    # downstream nodes above.
+    worktree.release(context, node: node, state: "superseded", runner: runner)
+
+    succ_id
+  end
+  private_class_method :respin
+
+  def append_graph_line(graph_path, id, needs, renamer:)
+    content = File.read(graph_path)
+    body = GraphFile.section_body(content, "## Graph").to_s
+    lines = body.split("\n")
+    rendered = needs.empty? ? "nothing" : needs.join(" ")
+    lines << "- #{id} needs #{rendered}"
+    new_body = lines.join("\n")
+    new_content = GraphFile.replace_or_append_section(content, "## Graph", new_body)
+    AtomicWrite.write(graph_path, new_content, renamer: renamer)
+  end
+  private_class_method :append_graph_line
+
+  def substitute_id(text, old_id, new_id)
+    text.to_s.gsub(/(?<![A-Za-z0-9_-])#{Regexp.escape(old_id.to_s)}(?![A-Za-z0-9_-])/, new_id.to_s)
+  end
+  private_class_method :substitute_id
+
+  def newly_ready(intent_dir, before_content:, before_nodes:, before_edges:)
+    after = RunnerCore.safe_load_graph(intent_dir)
+    return [] unless after[:ok]
+
+    after_content = read_savepoint(intent_dir)
+
+    after[:nodes].keys.select do |id|
+      was = before_nodes.key?(id) &&
+            ReadySet.ready?(content: before_content, subject: id, graph: { edges: before_edges },
+                             nodes: before_nodes)[:ready]
+      now_ready = ReadySet.ready?(content: after_content, subject: id, graph: { edges: after[:edges] },
+                                   nodes: after[:nodes])[:ready]
+      now_ready && !was
+    end.sort
+  end
+  private_class_method :newly_ready
+
+  def refusal(reason, detail: nil)
+    { ok: false, reason: reason, detail: detail, reset_to: nil, superseded: [], respun_to: nil, newly_ready: [] }
+  end
+  private_class_method :refusal
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+  private_class_method :blank?
+
+  def read_savepoint(intent_dir)
+    path = savepoint_path(intent_dir)
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :read_savepoint
+
+  def savepoint_path(intent_dir)
+    File.join(intent_dir.to_s, "savepoint.md")
+  end
+  private_class_method :savepoint_path
+end