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

package/scripts/lib/runner_proposals.rb

@@ -0,0 +1,254 @@
+# 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
+
+  # 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
+
+    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
+
+  # --- 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

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
+# packets/<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 NodePacket uses to name that attempt's packet file, so the
+  # extensions file for a `running` line always matches the packet 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")
+  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