@zalom/plastic 2.0.0-alpha.8 → 2.0.1

package/scripts/lib/runner_watch.rb

@@ -0,0 +1,389 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "time"
+require "rbconfig"
+require_relative "worktree"
+require_relative "runner_core"
+require_relative "runner_sweep"
+require_relative "ready_set"
+require_relative "node_ledger"
+require_relative "savepoint"
+require_relative "atomic_write"
+require_relative "runner_until_empty"
+require_relative "harness_adapter"
+require_relative "meter_watch"
+
+# RunnerWatch (intent 340a, G7b, n1): one tick over disk truth. The whole
+# watch minus the CLI and the dispatch branch (340a n2). Composes the
+# existing modules the way RunnerSweep and MeterWatch already do - the
+# git runner, the clock and the sweep module are all injected, nothing
+# reads ENV, nothing evals.
+#
+# Order, fixed by graph.md D2: take a non-blocking lock on
+# `<intent_dir>/watch.lock` for the whole tick (a losing tick is `busy`,
+# writes nothing); `RunnerSweep.abort_if_merging`; refuse the tick outright
+# on a half-finished merge (row 1.3), writing nothing; `RunnerSweep.reclaim`
+# (never `RunnerSweep.run`, D3: that method heartbeats the delivery lease,
+# which would keep a dead lead's lock fresh forever); classify (D4);
+# persist the snapshot and the record line only when `record:` holds.
+module RunnerWatch
+  module_function
+
+  LOCK_FILENAME = "watch.lock"
+  STATE_FILENAME = "watch.state"
+  RECORD_FILENAME = "watch.record"
+
+  # Classes that never dispatch (D8): a finished delivery re-running its own
+  # graph on every tick is exactly the bug a timer must not have.
+  FINISHED_CLASSES = %w[closed done_unreported].freeze
+
+  # tick(context, record:, dispatch:, harness:, now:, runner:, sweep:,
+  # until_empty:) -> {class:, blockers:, ready:, reclaimed:, dispatched:,
+  # tick:, busy:}. `dispatch:` (327 Q6, D7, D8) only ever runs under an
+  # explicit ask - never inferred from the class - and only when the lock is
+  # held, the class is not finished, and the meter does not read `stop`.
+  # `until_empty:` is `RunnerUntilEmpty` by default; a test can inject a
+  # double so the whole dispatch path never spawns a real `node-run`
+  # subprocess. `harness=` and `meter=` on the record line read `-` only
+  # when `dispatch:` itself was never asked for (D5) - every other refusal
+  # (an unheld lock, a finished class, a stopped meter) still consults and
+  # records the meter, since the tick DID look, it just chose not to act.
+  def tick(context, record: true, dispatch: false, harness: nil, now: Time.now,
+           runner: Worktree::ShellRunner.new, sweep: RunnerSweep, until_empty: RunnerUntilEmpty)
+    intent_dir = context.intent_dir.to_s
+    lock_handle = acquire_lock(File.join(intent_dir, LOCK_FILENAME))
+    return busy_result unless lock_handle
+
+    begin
+      abort_result = sweep.abort_if_merging(context, runner: runner)
+      unless abort_result[:ok]
+        return {
+          class: "merge_in_progress", blockers: [abort_result[:error]], ready: [],
+          reclaimed: [], dispatched: [], tick: nil, busy: false,
+        }
+      end
+
+      reclaim_result = sweep.reclaim(context, runner: runner, skip: [], now: now)
+      reclaimed_ids = Array(reclaim_result[:reclaimed]).map { |r| r[:node] }
+      extended = !Array(reclaim_result[:extended]).empty?
+
+      view = classify(context, runner: runner, now: now, intent_dir: intent_dir, extended: extended)
+
+      lock_state = context.session ? "held" : "not_held"
+      harness_field = "-"
+      meter_state = "-"
+      dispatched_ids = []
+
+      # B1: the dispatch loop and the persist step share one inner
+      # begin/ensure so a raise mid `until_empty.run` (a launchd SIGTERM, a
+      # Process.spawn Errno) still lands the snapshot and the record line
+      # with whatever `dispatched_ids` was collected before the raise, and
+      # then the exception keeps propagating past this method (the outer
+      # `ensure` below still releases the tick lock).
+      begin
+        if dispatch
+          harness_field = blank?(harness) ? "-" : harness.to_s
+          meter_state = read_meter_state(context)
+
+          if context.session && !FINISHED_CLASSES.include?(view[:class]) && meter_state != "stop"
+            run_until_empty_dispatch(context, harness: harness, until_empty: until_empty,
+                                      dispatched_ids: dispatched_ids)
+          end
+        end
+      ensure
+        if record
+          Worktree.ensure_gitignored(context.plastic_home, STATE_FILENAME, runner: runner)
+          write_snapshot(intent_dir, view[:snapshot])
+          append_record(
+            intent_dir, now: now, tick: view[:tick], klass: view[:class],
+            reclaimed: reclaimed_ids, ready: view[:ready], dispatched: dispatched_ids,
+            harness: harness_field, meter: meter_state, lock: lock_state
+          )
+        end
+      end
+
+      {
+        class: view[:class], blockers: view[:blockers], ready: view[:ready],
+        reclaimed: reclaimed_ids, dispatched: dispatched_ids, tick: view[:tick], busy: false,
+      }
+    ensure
+      release_lock(lock_handle)
+    end
+  end
+
+  # install_timer(context, home:, harness_key:, installer:) -> the written
+  # plist path. Graph.md D9: the Codex carrier is `runner watch
+  # --install-timer`, and it reuses MeterWatch's own writer through
+  # `label:`/`arguments:` rather than rendering plist XML here (row 3.5) - a
+  # second writer is exactly the drift D9 rules out. The label carries the
+  # intent id (row 3.4), so a second intent's timer never overwrites the
+  # first's job; `--dispatch --harness codex` rides the arguments only when
+  # `HarnessAdapter.unattended_start?` holds for the resolved harness (row
+  # 3.3), the same predicate `run_watch` itself already gates `--dispatch`
+  # on. `installer:` is `MeterWatch` by default so a test can inject a
+  # double that never touches a real home.
+  def install_timer(context, home:, harness_key:, installer: MeterWatch)
+    runner_path = File.expand_path(File.join(__dir__, "..", "runner"))
+    arguments = [RbConfig.ruby, runner_path, "watch", context.intent_dir.to_s]
+    arguments += ["--dispatch", "--harness", harness_key.to_s] if HarnessAdapter.unattended_start?(harness_key)
+
+    installer.install_timer(home: home, script_path: runner_path,
+                             label: "com.plastic.delivery-watch.#{context.intent_id}", arguments: arguments)
+  end
+
+  # run_until_empty_dispatch(context, harness:, until_empty:) -> every node
+  # id the loop dispatched (C30). `until_empty.run` gets `step:` wrapped
+  # around `until_empty.step_once` so this method sees every turn's own
+  # `:dispatched` ids, the same shape RunnerDispatch.dispatch returns
+  # (graph.md D8); `until_empty.run` itself still owns spawning and waiting
+  # on the real `node-run` subprocesses (never duplicated here).
+  def run_until_empty_dispatch(context, harness:, until_empty:, dispatched_ids:)
+    wrapped_step = lambda do |ctx, harness:, returns:|
+      result = until_empty.step_once(ctx, harness: harness, returns: returns)
+      dispatched_ids.concat(Array(result[:dispatched]))
+      result
+    end
+
+    until_empty.run(context, harness: harness, step: wrapped_step)
+  end
+  private_class_method :run_until_empty_dispatch
+
+  # read_meter_state(context) -> "ok", "reduce", "stop", "resume", "stale"
+  # (whatever MeterWatch's own tick last wrote), or "unavailable" for a
+  # missing or unparseable file (D8) - read-only, at MeterWatch's own state
+  # path under `context.plastic_home`, never through a MeterWatch instance
+  # (that class computes a FRESH state from the rate-limit cache; this tick
+  # only ever reads what it already wrote).
+  def read_meter_state(context)
+    path = File.join(context.plastic_home.to_s, ".cache", "meter-state.json")
+    return "unavailable" unless File.file?(path)
+
+    state = JSON.parse(File.read(path))["state"]
+    blank?(state) ? "unavailable" : state.to_s
+  rescue StandardError
+    "unavailable"
+  end
+  private_class_method :read_meter_state
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+  private_class_method :blank?
+
+  # fingerprint(context, runner:) -> the SHA256 D4 defines: savepoint.md's
+  # current content plus the intent branch head, so a commit that lands no
+  # ledger line still counts as movement (row 1.13). Public so a caller (and
+  # this file's own tests) can compute the exact value a tick would compute
+  # without duplicating the hashing here.
+  def fingerprint(context, runner: Worktree::ShellRunner.new)
+    content = savepoint_content(context.intent_dir)
+    Digest::SHA256.hexdigest("#{content}\x1f#{branch_head_sha(context, runner)}")
+  end
+
+  # --- the lock ----------------------------------------------------------------
+
+  def acquire_lock(path)
+    handle = File.open(path, File::CREAT | File::RDWR, 0o644)
+    return handle if handle.flock(File::LOCK_EX | File::LOCK_NB)
+
+    handle.close
+    nil
+  rescue SystemCallError
+    nil
+  end
+  private_class_method :acquire_lock
+
+  def release_lock(handle)
+    return unless handle
+
+    handle.flock(File::LOCK_UN)
+  rescue SystemCallError
+    nil
+  ensure
+    handle&.close
+  end
+  private_class_method :release_lock
+
+  def busy_result
+    { class: nil, blockers: [], ready: [], reclaimed: [], dispatched: [], tick: nil, busy: true }
+  end
+  private_class_method :busy_result
+
+  # --- classification (D4), first match wins ------------------------------------
+
+  def classify(context, runner:, now:, intent_dir:, extended: false)
+    content = savepoint_content(intent_dir)
+    recorded_pairs = Savepoint.savepoint_recorded_pairs(intent_dir)
+    previous = read_snapshot(intent_dir)
+    tick_number = (previous ? previous[:tick] : 0) + 1
+
+    if closed?(recorded_pairs)
+      return settle("closed", blockers: [], ready_ids: [], previous: previous, tick_number: tick_number,
+                     quiet_ticks: 0, content: content, context: context, runner: runner, now: now)
+    end
+
+    unless context.graph[:ok]
+      errors = Array(context.graph[:errors])
+      errors = ["graph.md could not be parsed"] if errors.empty?
+      return settle("stalled", blockers: errors, ready_ids: [], previous: previous, tick_number: tick_number,
+                     quiet_ticks: 0, content: content, context: context, runner: runner, now: now)
+    end
+
+    if RunnerCore.complete?(context)
+      return settle("done_unreported", blockers: [], ready_ids: [], previous: previous, tick_number: tick_number,
+                     quiet_ticks: 0, content: content, context: context, runner: runner, now: now)
+    end
+
+    ready_ids = ReadySet.analyze(intent_dir, now: now)[:ranked_ready].map { |r| r[:id] }
+    running = any_running?(content)
+
+    if !running && ready_ids.empty?
+      return settle("stalled", blockers: blocked_reasons(context), ready_ids: ready_ids, previous: previous,
+                     tick_number: tick_number, quiet_ticks: 0, content: content, context: context, runner: runner,
+                     now: now)
+    end
+
+    current_fingerprint = fingerprint(context, runner: runner)
+
+    # B2: a reclaim that extended a lease is evidence of live work (the
+    # sweep extends only when the node branch has commits newer than the
+    # expiry), so it counts as movement here, at the fingerprint
+    # comparison, after closed/malformed-graph/done_unreported/the
+    # nothing-running-nothing-ready stall have already returned above.
+    if extended || previous.nil? || previous[:fingerprint] != current_fingerprint
+      return settle("moving", blockers: [], ready_ids: ready_ids, previous: previous, tick_number: tick_number,
+                     quiet_ticks: 0, content: content, context: context, runner: runner, now: now,
+                     fingerprint: current_fingerprint)
+    end
+
+    next_quiet_ticks = previous[:quiet_ticks] + 1
+    if previous[:quiet_ticks] >= 1 && !unexpired_running_lease?(content, now)
+      klass = "stalled"
+      blockers = ["no observed movement for #{next_quiet_ticks} consecutive ticks and no unexpired running lease"]
+    else
+      klass = "quiet"
+      blockers = []
+    end
+
+    settle(klass, blockers: blockers, ready_ids: ready_ids, previous: previous, tick_number: tick_number,
+           quiet_ticks: next_quiet_ticks, content: content, context: context, runner: runner, now: now,
+           fingerprint: current_fingerprint)
+  end
+  private_class_method :classify
+
+  # Assembles the return view plus the snapshot that will be persisted, when
+  # `record:` is honored by the caller. `fingerprint:` defaults to a fresh
+  # computation so every class - not only moving/quiet/stalled-by-quiet -
+  # persists a value later ticks can compare against.
+  def settle(klass, blockers:, ready_ids:, previous:, tick_number:, quiet_ticks:, content:, context:, runner:,
+             now:, fingerprint: nil)
+    fp = fingerprint || RunnerWatch.fingerprint(context, runner: runner)
+    {
+      class: klass, blockers: blockers, ready: ready_ids, tick: tick_number,
+      snapshot: { fingerprint: fp, quiet_ticks: quiet_ticks, tick: tick_number, at: now.utc.iso8601 },
+    }
+  end
+  private_class_method :settle
+
+  def closed?(recorded_pairs)
+    recorded_pairs.include?(["Done", "delivered"]) || recorded_pairs.include?(["Done", "abandoned"])
+  end
+  private_class_method :closed?
+
+  def blocked_reasons(context)
+    rows = RunnerCore.status(context)
+    rows.values.reject { |v| ReadySet::TERMINAL_STATES.include?(v[:state]) || v[:ready] }
+        .flat_map { |v| v[:blockers] }
+        .uniq
+  end
+  private_class_method :blocked_reasons
+
+  def any_running?(content)
+    NodeLedger.status_from_content(content).value?("running")
+  end
+  private_class_method :any_running?
+
+  def unexpired_running_lease?(content, now)
+    status_map = NodeLedger.status_from_content(content)
+    entries = NodeLedger.entries_from_content(content)
+    status_map.any? do |subject, state|
+      next false unless state == "running"
+
+      last = entries.select { |e| !e[:torn] && e[:subject] == subject && e[:state] == "running" }.last
+      next false unless last
+
+      at = parse_time((last[:fields] || {})["expires"])
+      at && now < at
+    end
+  end
+  private_class_method :unexpired_running_lease?
+
+  def branch_head_sha(context, runner)
+    worktree = context.worktree
+    return "" if worktree.nil? || worktree.to_s.strip.empty?
+
+    res = runner.run("-C", worktree, "rev-parse", "HEAD")
+    res.success? ? res.stdout.to_s.strip : ""
+  rescue StandardError
+    ""
+  end
+  private_class_method :branch_head_sha
+
+  def parse_time(raw)
+    return nil if raw.nil? || raw.to_s.strip.empty?
+
+    Time.iso8601(raw.to_s)
+  rescue ArgumentError
+    nil
+  end
+  private_class_method :parse_time
+
+  def savepoint_content(intent_dir)
+    path = File.join(intent_dir.to_s, "savepoint.md")
+    File.exist?(path) ? File.read(path) : ""
+  end
+  private_class_method :savepoint_content
+
+  # --- the snapshot (D5) ---------------------------------------------------------
+
+  def read_snapshot(intent_dir)
+    path = File.join(intent_dir, STATE_FILENAME)
+    return nil unless File.file?(path)
+
+    data = JSON.parse(File.read(path))
+    { fingerprint: data["fingerprint"], quiet_ticks: data["quiet_ticks"].to_i, tick: data["tick"].to_i,
+      at: data["at"] }
+  rescue StandardError
+    nil
+  end
+  private_class_method :read_snapshot
+
+  def write_snapshot(intent_dir, snapshot)
+    path = File.join(intent_dir, STATE_FILENAME)
+    data = {
+      "fingerprint" => snapshot[:fingerprint], "quiet_ticks" => snapshot[:quiet_ticks],
+      "tick" => snapshot[:tick], "at" => snapshot[:at],
+    }
+    AtomicWrite.write(path, JSON.generate(data))
+  end
+  private_class_method :write_snapshot
+
+  # --- the record (D5) -----------------------------------------------------------
+
+  def append_record(intent_dir, now:, tick:, klass:, reclaimed:, ready:, dispatched:, harness: "-", meter: "-",
+                     lock:)
+    line = "#{now.utc.iso8601}  tick=#{tick} class=#{klass} reclaimed=#{list_or_dash(reclaimed)} " \
+           "ready=#{list_or_dash(ready)} dispatched=#{list_or_dash(dispatched)} harness=#{harness} " \
+           "meter=#{meter} lock=#{lock}\n"
+    File.open(File.join(intent_dir, RECORD_FILENAME), "a") { |f| f.write(line) }
+  end
+  private_class_method :append_record
+
+  def list_or_dash(list)
+    list.nil? || list.empty? ? "-" : list.join(",")
+  end
+  private_class_method :list_or_dash
+end

package/scripts/lib/savepoint.rb

@@ -3,14 +3,13 @@
 # frozen_string_literal: true
 
 # Savepoint: the intent-directory savepoint ledger and the stage derivation it
-# rests on (intent 303, split out of bridge.rb). Everything here is derived from
+# rests on (intent 303). Everything here is derived from
 # the files on disk inside one intent directory: which lifecycle files are real
 # (not the placeholder sentinel), which stage that makes, and the append-only
-# savepoint.md ledger that records each milestone. No session, no bridge, no
+# savepoint.md ledger that records each milestone. No session, no lock, no
 # lock: a caller that only wants to append a ledger line or ask "which stage is
-# this intent at" loads this file and nothing else. bridge.rb (the session
-# pointer, arm and disarm, lock repair) requires this file; this file never
-# requires the bridge.
+# this intent at" loads this file and nothing else. `scripts/lib/arm.rb` (arm,
+# disarm, lock repair) requires this file; this file never requires arm.rb.
 require "fileutils"
 require "time" # Time#iso8601 for the ledger timestamps
 
@@ -23,6 +22,36 @@ module Savepoint
   # (<id>--<slug>.md) is never sentineled; it is born complete.
   PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
 
+  # --- Node-graph transition subject vocabulary (intent 335, spec D17) -------
+  #
+  # Owned HERE, not on NodeLedger, because test/savepoint_split_test.rb:57 pins
+  # savepoint.rb to loading no other project file: NodeLedger requires this
+  # file and reuses these three names rather than duplicating them, so the
+  # dependency runs one way only. Intent 334 (G1) mints node ids and must
+  # agree with NODE_SUBJECT_RE: it is the single seam for the node id shape.
+
+  # The literal subject token for an intent-scope transition line ("Intent
+  # needs_decision question=..."), as opposed to a node-scope line.
+  INTENT_SUBJECT = "Intent"
+
+  # A node id: one or two lowercase letters (the node's kind prefix, e.g. "n"
+  # for work, "v" for verify) followed by digits.
+  NODE_SUBJECT_RE = /\A[a-z]{1,2}\d+\z/.freeze
+
+  # True iff a raw savepoint ledger line's subject (field 2, split on
+  # /\s{2,}/) is a transition candidate: the literal Intent token or a node
+  # id. A stage line ("How  checklist.md created") or a Lock takeover audit
+  # line never matches, by construction (spec Acceptance Criteria: "no stage
+  # token this tree writes collides with Intent or with the node id
+  # pattern").
+  def self.transition_candidate?(line)
+    parts = line.to_s.split(/\s{2,}/)
+    return false unless parts.length >= 2
+
+    subject = parts[1]
+    subject == INTENT_SUBJECT || subject.match?(NODE_SUBJECT_RE)
+  end
+
   def self.intent_file(intent_dir)
     dir_name = File.basename(intent_dir)
     "#{intent_dir}/#{dir_name}.md"
@@ -30,7 +59,7 @@ module Savepoint
 
   # Walk up from file_path; return the first ancestor that looks like an intent
   # directory (`.../store/<id>--<slug>`), else nil. Used to derive the savepoint
-  # target without needing a bridge. The input is always a file inside the intent
+  # target without needing the lock or arm machinery. The input is always a file inside the intent
   # dir (never the dir itself), so the walk-up starts at its parent.
   def self.intent_dir_for(file_path)
     dir = File.expand_path(file_path)
@@ -57,22 +86,47 @@ module Savepoint
     File.exist?(path)
   end
 
-  # True iff actions/ holds AT LEAST ONE real action file: a non-empty *.md whose
-  # first line is not the placeholder sentinel. A `.gitkeep` (no .md extension)
-  # never counts, an empty *.md never counts, and a sentinel-only *.md never
-  # counts. Pure and side-effect-free so the gate stays unit-testable. Fail-open:
-  # a missing actions/ dir globs to nothing and returns false (the gate then
-  # reports it needs a real action file); it never raises.
-  def self.has_real_action?(intent_dir)
-    Dir.glob("#{intent_dir}/actions/*.md").any? do |f|
+  # True iff DIR_NAME (actions/ or nodes/) holds AT LEAST ONE real *.md file: non-empty,
+  # first line not the placeholder sentinel. A `.gitkeep` (no .md extension) never counts.
+  # Pure and side-effect-free; fail-open (a missing dir globs to nothing, never raises).
+  def self.has_real_files_in?(dir_name, intent_dir)
+    Dir.glob("#{intent_dir}/#{dir_name}/*.md").any? do |f|
       File.file?(f) && File.size(f) > 0 && stage_file_present?(f)
     end
   rescue StandardError
     false
   end
 
+  # True iff the intent has at least one real action file, whether delivered as
+  # legacy actions/*.md or as a node graph's nodes/*.md (intent 334, G1, D10r):
+  # an intent delivered as nodes is exactly as real as one delivered as
+  # actions, so doctor and the exec-stage gate never report a backfill gap on
+  # a fully delivered node-graph intent. Checks actions/ first (the common
+  # path today), falling through to nodes/ only when actions/ has nothing.
+  def self.has_real_action?(intent_dir)
+    has_real_files_in?("actions", intent_dir) || has_real_files_in?("nodes", intent_dir)
+  rescue StandardError
+    false
+  end
+
+  # Intent 336 (G3, D13): a real graph.md is 327 D41's replacement for
+  # plan.md/checklist.md on the common path, so a node-shaped intent is
+  # judged on graph.md and nodes/ alone, whether or not spec.md is real - the
+  # graph IS the spec under D41. Checked using only this file's own
+  # primitives (stage_file_present?, has_real_files_in?), because
+  # test/savepoint_split_test.rb pins this file to loading no other project
+  # file and no YAML: GraphFile/NodeFile/ReadySet are never required here. An
+  # intent with no real graph.md (or a sentinel-placeholder one,
+  # stage_file_present? already reads that as absent) derives exactly what it
+  # derived before this intent.
   def self.derive_stage(intent_dir)
     return "done" if stage_file_present?("#{intent_dir}/outcome.md")
+
+    if stage_file_present?("#{intent_dir}/graph.md")
+      return "exec" if has_real_files_in?("nodes", intent_dir)
+      return "how"
+    end
+
     if stage_file_present?("#{intent_dir}/plan.md") &&
        has_real_action?(intent_dir) &&
        stage_file_present?("#{intent_dir}/checklist.md")
@@ -87,19 +141,49 @@ module Savepoint
     files = []
     ifile = File.basename(intent_file(intent_dir))
     files << ifile if File.exist?("#{intent_dir}/#{ifile}")
-    ["spec.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
+    ["spec.md", "graph.md", "plan.md", "checklist.md", "outcome.md"].each do |f|
       files << f if stage_file_present?("#{intent_dir}/#{f}")
     end
-    files << "actions/" if has_real_action?(intent_dir)
+    # Name the directory that actually exists (review B3): a nodes-only intent
+    # must never claim the literal "actions/" artifact it does not have.
+    # Checks actions/ first, matching D15r's read order.
+    if has_real_files_in?("actions", intent_dir)
+      files << "actions/"
+    elsif has_real_files_in?("nodes", intent_dir)
+      files << "nodes/"
+    end
     files
   end
 
   def self.missing_for_stage(stage, intent_dir = nil)
     ifile = intent_dir ? File.basename(intent_file(intent_dir)) : "intent.md"
+    # A How-stage intent that already started a nodes/ directory is named
+    # accordingly, so the next-step hint never tells a node-graph intent to
+    # go make an actions/ directory it will never use (review B3). Mirrors
+    # has_real_files_in?'s actions-first order and its real-file requirement
+    # (post-execution review, non-blocking 4): an intent carrying real files
+    # in both directories, or a real actions/ file beside an empty or
+    # .gitkeep-only nodes/, is named actions/, never nodes/.
+    action_label = if intent_dir && has_real_files_in?("actions", intent_dir)
+      "actions/"
+    elsif intent_dir && has_real_files_in?("nodes", intent_dir)
+      "nodes/"
+    else
+      "actions/"
+    end
     case stage
     when "what" then [ifile]
     when "why" then ["spec.md"]
-    when "how" then ["plan.md", "actions/", "checklist.md"]
+    when "how"
+      # A node-shaped How intent (a real graph.md already) is named after its
+      # own two artifacts, never the three D41 removed from its path (review
+      # B3, extended by 336 D13): checked via stage_file_present? alone, the
+      # same primitive derive_stage itself uses.
+      if intent_dir && stage_file_present?("#{intent_dir}/graph.md")
+        ["graph.md", "nodes/"]
+      else
+        ["plan.md", action_label, "checklist.md"]
+      end
     when "exec" then ["outcome.md"]
     else []
     end
@@ -227,6 +311,18 @@ module Savepoint
     append_savepoint_line(intent_dir, "Commit", text, now)
   end
 
+  # The day the Report kind (below) shipped. `doctor`'s intent_reports_printed_check reads
+  # this so it never re-litigates a ledger recorded before the kind existed (intent 331f, R6).
+  REPORT_KIND_SINCE = "2026-09-05"
+
+  # Append a `Report` line: one per report screen printed (intent 331f, D2/D3). Same primitive
+  # as append_review_savepoint/append_commit_savepoint above, so the line shape, dedup, and
+  # timestamp format never drift. `savepoint_milestone` maps FILENAMES only, so a Report line
+  # is never mistaken for a file-landing lifecycle line by construction.
+  def self.append_report_savepoint(intent_dir, text, now: Time.now)
+    append_savepoint_line(intent_dir, "Report", text, now)
+  end
+
   TERMINAL_DISPOSITIONS = %w[delivered abandoned].freeze
 
   # Append the terminal bookend `Done  delivered|abandoned`, written by the
@@ -246,6 +342,17 @@ module Savepoint
   # A Plastic 1.x ledger may carry a `Tier  <value>` line after the spec.md
   # milestone (removed in 2.0, intent 304); a rebuild drops it, and the phantom
   # detector ignores it, so a 1.x store reads clean.
+  #
+  # Every transition line (intent 335, spec D13) is preserved VERBATIM, in its
+  # original relative order, after the reconstructed stage skeleton. It is
+  # never dropped and never refused: a transition line's evidence fields
+  # (`holder=`, `expires=`, `gates=`, ...) have no file-mtime analog to
+  # reconstruct from, so refusing instead of preserving would make this method
+  # destroy the graph's only status on every intent that carries one. Relative
+  # order BETWEEN a stage line and a transition line is not preserved (safe:
+  # status is computed per subject, and the two families share no subject);
+  # relative order WITHIN the transition lines is preserved, which is what
+  # "last line per subject in file order" depends on.
   def self.rebuild_savepoint(intent_dir)
     ordered = [
       File.basename(intent_file(intent_dir)),
@@ -259,13 +366,24 @@ module Savepoint
       stamp = File.mtime(path).utc.iso8601
       ["#{stamp}  #{stage}  #{milestone}\n"]
     end
-    File.write(File.join(intent_dir, SAVEPOINT_FILE), lines.join)
+
+    savepoint_path = File.join(intent_dir, SAVEPOINT_FILE)
+    if File.exist?(savepoint_path)
+      # #scrub before scanning (post-execution review row 7.8), the same way
+      # NodeLedger.entries does (matrix 2.44): a stray non-UTF-8 byte anywhere
+      # in the ledger must not raise out of the one repair tool three doctor
+      # fix hints and maintenance-run --tool rebuild-savepoint point at.
+      transition_lines = File.read(savepoint_path).scrub.each_line.select { |raw| transition_candidate?(raw) }
+      lines += transition_lines.map { |raw| raw.end_with?("\n") ? raw : "#{raw}\n" }
+    end
+
+    File.write(savepoint_path, lines.join)
     lines.length
   end
 
   # --- Phantom-line detection (intent 134) ------------------------------------
   #
-  # A companion to the ledger, not a new writer: pure, disk-only, hermetic (no bridge or
+  # A companion to the ledger, not a new writer: pure, disk-only, hermetic (no lock or
   # session resolution, no writes), matching intent 52's savepoint-decoupling precedent. Under
   # a gate-routing misfire (bug 131) or an out-of-band merge (124a's precedent), a ledger line
   # can go stale or duplicate without the file evidence agreeing. This detects, never repairs;
@@ -308,6 +426,10 @@ module Savepoint
     File.read(path).each_line do |raw|
       line = raw.strip
       next if line.empty?
+      # A transition line (intent 335) is never a stage phantom candidate: its
+      # own repeated-line semantics (dedup-free by design, spec D11) are
+      # NodeLedger's concern, not this detector's.
+      next if transition_candidate?(line)
       parts = line.split(/\s{2,}/)
       next if parts.length < 3
       pair = [parts[1], parts[2]]

package/scripts/lib/scaffold_intent.rb

@@ -3,7 +3,6 @@
 
 require "fileutils"
 require_relative "worktree"
-require_relative "bridge"
 require_relative "savepoint"
 require_relative "intent_validator"
 
@@ -21,7 +20,7 @@ require_relative "intent_validator"
 # copy or a mechanical rendering of a committed artifact.
 #
 # Pure and dependency-injected: never calls `exit` or `abort`, never reads `ARGV` or
-# `ENV` directly (only via the ambient `Dir.home` default, matching Bridge/Worktree
+# `ENV` directly (only via the ambient `Dir.home` default, matching this module's own
 # convention). A git seam is injected as `runner:`, defaulting to
 # `Worktree::ShellRunner.new`, so tests drive this in process with a fake runner and
 # never touch real git. Every method returns a value; `scripts/scaffold-intent` maps the
@@ -29,6 +28,10 @@ require_relative "intent_validator"
 module ScaffoldIntent
   module_function
 
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+
   # --- path resolution (pure) --------------------------------------------------
 
   def expand(path)
@@ -211,7 +214,7 @@ module ScaffoldIntent
       end
     end
 
-    unless Bridge.blank?(test_summary)
+    unless blank?(test_summary)
       out << "\n"
       out << "Test summary from #{test_summary}:\n"
       out << "```\n"