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

package/scripts/lib/doctor_core.rb

@@ -27,9 +27,10 @@ class Doctor
     "hermes" => { name: "Hermes",      dir: File.join(Dir.home, ".hermes") },
   }.freeze
 
-  # The Claude events hooks_registered expects in settings.json: the five-event map of
-  # cut-inventory 3b (intent 309 added SessionEnd, registered for close since intent 301).
-  CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit SessionEnd].freeze
+  # The Claude events hooks_registered expects in settings.json: the six-event map of
+  # cut-inventory 3b (intent 309 added SessionEnd, registered for close since intent 301;
+  # intent 316a added MessageDisplay, registered for message-display, Claude only).
+  CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit SessionEnd MessageDisplay].freeze
 
   # Launchers the installer places in the agent's hooks dir that are NOT hooks
   # (intent 204): plastic-statusline is the settings["statusLine"] command, wired
@@ -90,8 +91,19 @@ class Doctor
 
     JSON.parse(File.read(path))
   rescue JSON::ParserError
-    content = File.read(path).gsub(%r{//[^\n]*}, "").gsub(/,(\s*[}\]])/, '\1')
-    JSON.parse(content)
+    # The comment/trailing-comma-stripped retry below can itself raise
+    # JSON::ParserError on genuinely malformed content (a truncated file, or
+    # plain garbage). A nested begin/rescue is required here because a
+    # method-level `rescue` clause never catches an exception raised from
+    # INSIDE a sibling rescue clause's own body (only from the main body).
+    # Without this nesting a malformed settings.json crashes doctor instead
+    # of reporting a clean fail (intent 331e, F5).
+    begin
+      content = File.read(path).gsub(%r{//[^\n]*}, "").gsub(/,(\s*[}\]])/, '\1')
+      JSON.parse(content)
+    rescue
+      nil
+    end
   rescue
     nil
   end
@@ -1244,10 +1256,94 @@ class Doctor
     all_checks += check_manifest_sync(agent_key)
     all_checks += check_registered_project_paths
     all_checks += check_global_store_available
+    all_checks += check_display_registration(agent_key)
 
     summarize(all_checks, agent_key, binary: true)
   end
 
+  # The single `hooks/<name>` launcher basename for the MessageDisplay event,
+  # derived from HookRegistry rather than hand-kept (intent 331e), so a
+  # future rename of the hook stays in one place. Shared by
+  # check_display_registration (below, boot path) and scripts/doctor.rb's
+  # check_display_paints (full run), which resolves the SAME name under the
+  # agent_dir it was given.
+  def display_hook_launcher_name
+    group = HookRegistry.events["MessageDisplay"].first
+    "plastic-#{group['hooks'].first['name']}"
+  end
+
+  DISPLAY_HOOK_FIX_HINT = "Re-run the Plastic installer to repair the hook registration: " \
+                          "npx @zalom/plastic@<channel> install --reinstall --claude " \
+                          "(plastic-install --repair)".freeze
+
+  # display_hook_registered (intent 331e, D1, category "display"): the Claude
+  # settings carry the plastic-message-display command, on-disk, executable.
+  # Boot-path safe: resolves everything from the injected `agents` hash and
+  # `plastic_home`, never Dir.home or a real ~/.claude (E18). This is the same
+  # discipline check_claude_registration already follows.
+  #
+  # D3: a harness Doctor knows carries no display hook (Codex, Hermes) is a
+  # pass, not a fail, worded "plain by contract" like the paint check's own
+  # skip (scripts/doctor.rb's check_display_paints).
+  def check_display_registration(agent_key)
+    config = agents[agent_key]
+    unless agent_key == "claude"
+      return [check(
+        category: "display", name: "display_hook_registered", status: "pass",
+        message: "#{config[:name]} is plain by contract; no MessageDisplay hook to register"
+      )]
+    end
+
+    agent_dir = config[:dir]
+    settings_path = File.join(agent_dir, "settings.json")
+    settings = read_json_safe(settings_path)
+
+    if settings.nil?
+      return [check(
+        category: "display", name: "display_hook_registered", status: "fail",
+        message: "Cannot read #{tilde(settings_path)}: file missing or invalid",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    hooks = settings["hooks"].is_a?(Hash) ? settings["hooks"] : {}
+    commands = event_commands(hooks["MessageDisplay"])
+    launcher_name = display_hook_launcher_name
+
+    registered = commands.any? { |cmd| HookRegistry.command_basenames(cmd).include?(launcher_name) }
+
+    unless registered
+      return [check(
+        category: "display", name: "display_hook_registered", status: "fail",
+        message: "No MessageDisplay hook registered in #{tilde(settings_path)}",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    launcher_path = File.join(agent_dir, "hooks", launcher_name)
+
+    unless File.exist?(launcher_path)
+      return [check(
+        category: "display", name: "display_hook_registered", status: "fail",
+        message: "MessageDisplay is registered but #{tilde(launcher_path)} does not exist",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    unless File.executable?(launcher_path)
+      return [check(
+        category: "display", name: "display_hook_registered", status: "fail",
+        message: "#{tilde(launcher_path)} exists but is not executable",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    [check(
+      category: "display", name: "display_hook_registered", status: "pass",
+      message: "MessageDisplay hook registered and #{tilde(launcher_path)} is executable"
+    )]
+  end
+
   def check_registered_project_paths
     checks = []
 

package/scripts/lib/doctor_session_ledger.rb

@@ -18,6 +18,18 @@ require_relative "session_ledger"
 module DoctorSessionLedger
   ORPHAN_TTL_SECONDS = 24 * 60 * 60
 
+  # Row H (spec D9): a `.tmp/<sid>/` directory with no `current` pointer is a
+  # DIFFERENT orphan class than ORPHAN_TTL_SECONDS's -- a session where
+  # session start never ran at all (a `-p` print session, a resumed
+  # background job, an unregistered SessionStart hook), not a session that
+  # ran and then never closed. No choice of session id ever creates a
+  # pointer for that class, so it would otherwise stay invisible for the
+  # full 24 hours (or forever, once hook-capture/hook-record stop creating
+  # it at all). Short relative to ORPHAN_TTL_SECONDS on purpose: a session
+  # between its own start and its first pointer write is normal and must not
+  # be flagged, but that window is seconds, not hours.
+  NO_POINTER_TTL_SECONDS = 5 * 60
+
   # Seconds since the session's last heartbeat: the ISO-8601 content of `heartbeat`,
   # else that file's mtime, else the directory's mtime.
   def heartbeat_age(dir, now)
@@ -37,6 +49,7 @@ module DoctorSessionLedger
 
     store_dir = File.join(plastic_home, "store")
     orphans = orphaned_session_dirs(store_dir, now)
+    no_pointer = no_pointer_session_dirs(store_dir, now)
     shape = day_ledger_shape_problems(store_dir)
 
     checks = []
@@ -54,6 +67,20 @@ module DoctorSessionLedger
                                 "session is gone: a live session rewrites its heartbeat on every " \
                                 "prompt and edit, so only a listed directory may be removed, by hand.")
               end
+    checks << if no_pointer.empty?
+                check(category: "session_ledger", name: "no_pointer_session_tmp", status: "pass",
+                      message: "No .tmp/<session>/ directory has gone without a `current` pointer for " \
+                               "longer than #{NO_POINTER_TTL_SECONDS} seconds")
+              else
+                check(category: "session_ledger", name: "no_pointer_session_tmp", status: "warn",
+                      message: "#{no_pointer.size} .tmp/<session>/ director#{no_pointer.size == 1 ? "y" : "ies"} " \
+                               "with no `current` pointer for longer than #{NO_POINTER_TTL_SECONDS} seconds " \
+                               "(session start never ran for this session)",
+                      details: no_pointer, fixable: true,
+                      fix_hint: "Remove each listed .tmp/<session>/ directory after confirming that " \
+                                "session never started: no `current` pointer means session start never " \
+                                "ran for it, so this is not a live session missing a checklist entry.")
+              end
     checks << if shape.empty?
                 check(category: "session_ledger", name: "day_ledger_shape", status: "pass",
                       message: "Every .sessions/ entry is a YYYYMMDD day directory with its <day>.md file")
@@ -86,6 +113,31 @@ module DoctorSessionLedger
     [] # unreadable .tmp/: nothing to report, never a crash
   end
 
+  # Row H (spec D9): `.tmp/<sid>/` directories with no `current` pointer, past
+  # NO_POINTER_TTL_SECONDS. A different signal than #orphaned_session_dirs:
+  # that one is age-only and blind to whether a pointer exists at all, so a
+  # young no-pointer dir (a session between its start and its first pointer
+  # write) must not appear here even though it may well appear there once it
+  # ages past ORPHAN_TTL_SECONDS -- the two checks answer different questions
+  # and a dir can legitimately show up in neither, either, or both.
+  def no_pointer_session_dirs(store_dir, now)
+    tmp_root = SessionLedger.tmp_root(store_dir)
+    return [] unless File.directory?(tmp_root)
+
+    Dir.children(tmp_root).sort.filter_map do |name|
+      dir = File.join(tmp_root, name)
+      next unless File.directory?(dir)
+      next if File.exist?(File.join(dir, "current"))
+
+      age = heartbeat_age(dir, now)
+      next if age <= NO_POINTER_TTL_SECONDS
+
+      "global: #{dir} (session #{name}, no `current` pointer, last heartbeat #{age.round}s ago)"
+    end
+  rescue SystemCallError
+    [] # unreadable .tmp/: nothing to report, never a crash
+  end
+
   def day_ledger_shape_problems(store_dir)
     root = SessionLedger.sessions_root(store_dir)
     return [] unless File.directory?(root)

package/scripts/lib/graph_edges.rb

@@ -0,0 +1,121 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# GraphEdges (intent 334, n1): the shared `needs` syntax and cycle-path check
+# (327 D2r-D4r, D12r). Parses a "## Graph" section's edge lines into a node
+# set and an edge map, the one parser an intent's graph.md and a roadmap's
+# own ## Graph section both use unchanged (C1, fold A5): the same list-item
+# grammar, the same root keyword, the same cycle walk. Deliberately loose
+# about what an id looks like - a roadmap id is numeric ("334", "340a"), a
+# node id carries a kind prefix ("n1") - the kind-prefix rule belongs to
+# NodeFile and WorkGraphValidator, never here (D12r, fold A6).
+#
+# Grammar (D2r/D3r): a list item shaped "- <id> needs <target> [<target>
+# ...]", ending at end of line. The single literal target "nothing" declares
+# a root and must be the ONLY target on the line. Any line that does not
+# start with "- <token> needs" is prose and is skipped in silence. A line
+# that DOES look like an edge is held to the grammar strictly: no target at
+# all, "nothing" alongside other targets, or a target token carrying
+# sentence punctuation (a period, a colon, ...) rather than the loose
+# id-token charset, is an error naming the line, never a silently
+# mis-parsed edge or an invented node (fold A7).
+#
+# Pure and side-effect-free; never raises across the boundary, matching the
+# Result-hash convention every library in scripts/lib/ follows.
+module GraphEdges
+  module_function
+
+  EDGE_LEAD_RE = /\A-\s*(\S+)\s+needs\b(.*)\z/.freeze
+  TOKEN_RE = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/.freeze
+  ROOT_TARGET = "nothing"
+
+  # {nodes:, edges:, errors:} - nodes is the declared ids together with every
+  # id any edge targets (fold A5), in first-seen order; edges maps a declared
+  # id to its target ids (empty for a root); errors names each malformed
+  # edge-shaped line. Prose lines contribute nothing and raise nothing.
+  def parse(section_text)
+    declared_order = []
+    edges = {}
+    targeted = []
+    errors = []
+
+    section_text.to_s.each_line do |raw_line|
+      line = raw_line.chomp("\n").chomp("\r")
+      stripped = line.strip
+      next if stripped.empty?
+
+      m = stripped.match(EDGE_LEAD_RE)
+      next unless m
+
+      id = m[1]
+      raw_targets = m[2].to_s.strip.split(/\s+/)
+
+      if raw_targets.empty?
+        errors << "malformed edge line, no target: #{stripped.inspect}"
+        next
+      end
+
+      if raw_targets.include?(ROOT_TARGET) && raw_targets.length > 1
+        errors << "root target #{ROOT_TARGET.inspect} mixed with a real target, root must be the only target: #{stripped.inspect}"
+        next
+      end
+
+      bad_token = raw_targets.find { |t| t != ROOT_TARGET && !t.match?(TOKEN_RE) }
+      if bad_token
+        errors << "prose tail after targets: #{stripped.inspect}"
+        next
+      end
+
+      if edges.key?(id)
+        errors << "duplicate node declaration for #{id.inspect}: #{stripped.inspect}"
+        next
+      end
+
+      targets = raw_targets == [ROOT_TARGET] ? [] : raw_targets
+      declared_order << id
+      edges[id] = targets
+      targeted.concat(targets)
+    end
+
+    nodes = declared_order.dup
+    targeted.each { |t| nodes << t unless nodes.include?(t) }
+
+    { nodes: nodes, edges: edges, errors: errors }
+  end
+
+  # The cycle as a path with the entry id repeated (D4r), or nil when the
+  # graph is acyclic. A node reachable by two distinct paths (a diamond) is
+  # never mistaken for a cycle: once a node's whole subtree is walked clean
+  # it is marked visited and never re-examined.
+  def cycle(edges)
+    visiting = {}
+    visited = {}
+    path = []
+
+    edges.each_key do |node|
+      next if visited[node]
+      found = walk(node, edges, visiting, visited, path)
+      return found if found
+    end
+    nil
+  end
+
+  def walk(node, edges, visiting, visited, path)
+    if visiting[node]
+      idx = path.index(node)
+      return path[idx..] + [node]
+    end
+    return nil if visited[node]
+
+    visiting[node] = true
+    path.push(node)
+    (edges[node] || []).each do |target|
+      found = walk(target, edges, visiting, visited, path)
+      return found if found
+    end
+    path.pop
+    visiting.delete(node)
+    visited[node] = true
+    nil
+  end
+end

package/scripts/lib/graph_file.rb

@@ -0,0 +1,246 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_edges"
+require_relative "atomic_write"
+
+# GraphFile (intent 334, n2): the four graph.md sections (## Goal,
+# ## Decisions, ## Graph, ## Status), the verify:-none directive, and the two
+# writers - write_status and append_decision. Both writers refuse a cyclic
+# graph and both go through AtomicWrite (fold D19r). Fence-aware everywhere a
+# heading is located, so a fenced example carrying a fake "## " line never
+# splits or ends a real section (fold A8's sibling concern, applied to
+# section boundaries rather than edge lines).
+module GraphFile
+  module_function
+
+  FENCE_LINE_RE = /\A\s{0,3}(`{3,}|~{3,})/.freeze
+  DIRECTIVE_RE = /\A-\s*verify:\s*none(?:\s+reason=(.*))?\z/i.freeze
+
+  # {ok:, goal:, decisions:, graph:, status:, verify:, errors:}. `graph` is
+  # GraphEdges.parse's own Result hash, over the Graph section text with any
+  # verify:-none directive line stripped first (fold A8). A missing ## Graph
+  # section, or one that declares no nodes, is an error naming which (fold
+  # A10).
+  def parse(path)
+    return failure(["graph file not found: #{path}"]) unless File.exist?(path)
+
+    content = File.read(path)
+    goal = section_body(content, "## Goal")
+    decisions = section_body(content, "## Decisions")
+    graph_section = section_body(content, "## Graph")
+    status = section_body(content, "## Status")
+
+    errors = []
+    if graph_section.nil?
+      errors << "missing ## Graph section"
+      return { ok: false, goal: goal, decisions: decisions, graph: nil, status: status, verify: nil, errors: errors }
+    end
+
+    directive, directive_errors, remaining = extract_verify_directive(graph_section)
+    errors.concat(directive_errors)
+
+    parsed_graph = GraphEdges.parse(strip_fenced_blocks(remaining))
+    errors.concat(parsed_graph[:errors])
+    errors << "## Graph declares no nodes" if parsed_graph[:nodes].empty?
+
+    { ok: errors.empty?, goal: goal, decisions: decisions, graph: parsed_graph, status: status, verify: directive, errors: errors }
+  end
+
+  def failure(errors)
+    { ok: false, goal: nil, decisions: nil, graph: nil, status: nil, verify: nil, errors: errors }
+  end
+
+  # Rows shaped {node:, state:, detail:} parsed back from the ## Status
+  # table (D8r's round-trip guarantee).
+  def status_rows(path)
+    parsed = parse(path)
+    rows_from_table(parsed[:status])
+  end
+
+  # Replace the whole ## Status section with rows, creating the section if
+  # absent. Refuses a cyclic graph (D8r); goes through AtomicWrite (D19r).
+  def write_status(path, rows, renamer: File.method(:rename))
+    guard = refuse_if_cyclic(path)
+    return guard if guard
+
+    content = File.read(path)
+    new_content = replace_or_append_section(content, "## Status", render_status_table(rows))
+    AtomicWrite.write(path, new_content, renamer: renamer)
+    { ok: true, errors: [] }
+  end
+
+  # Append one answered decision as a list item to ## Decisions (C26),
+  # leaving every other section byte-identical. Refuses a cyclic graph.
+  def append_decision(path, text, renamer: File.method(:rename))
+    guard = refuse_if_cyclic(path)
+    return guard if guard
+
+    content = File.read(path)
+    bounds = section_bounds(content, "## Decisions")
+    return { ok: false, errors: ["missing ## Decisions section"] } unless bounds
+
+    start_idx, end_idx = bounds
+    heading_line_end = line_end(content, start_idx)
+    body = content[heading_line_end...end_idx]
+    trimmed = body.rstrip
+    trailing = body[trimmed.length..]
+    new_body = trimmed.empty? ? "- #{text}#{trailing}" : "#{trimmed}\n- #{text}#{trailing}"
+    new_content = content[0...heading_line_end] + new_body + content[end_idx..]
+    AtomicWrite.write(path, new_content, renamer: renamer)
+    { ok: true, errors: [] }
+  end
+
+  def refuse_if_cyclic(path)
+    parsed = parse(path)
+    return { ok: false, errors: parsed[:errors] } if parsed[:graph].nil?
+
+    cyc = GraphEdges.cycle(parsed[:graph][:edges])
+    return { ok: false, errors: ["cyclic graph, refusing to write: #{cyc.join(' > ')}"] } if cyc
+
+    nil
+  end
+
+  # --- verify: none directive --------------------------------------------------
+
+  def extract_verify_directive(graph_section)
+    return [nil, [], graph_section] if graph_section.nil?
+
+    reason = nil
+    present = false
+    errors = []
+    remaining_lines = []
+
+    graph_section.each_line do |line|
+      stripped = line.strip
+      m = stripped.match(DIRECTIVE_RE)
+      if m
+        present = true
+        captured = m[1].to_s.strip
+        if captured.empty?
+          errors << "verify: none requires reason=<text>: #{stripped.inspect}"
+        else
+          reason = captured
+        end
+      else
+        remaining_lines << line
+      end
+    end
+
+    directive = present ? { reason: reason } : nil
+    [directive, errors, remaining_lines.join]
+  end
+
+  # D18: drop every fenced line from `text`, so a fenced example edge inside a
+  # hand-written graph.md or roadmap ## Graph section is never handed to
+  # GraphEdges as real edge text. Non-fenced lines pass through unchanged.
+  def strip_fenced_blocks(text)
+    lines = []
+    each_fence_line(text) { |line, fenced| lines << line unless fenced }
+    lines.join
+  end
+
+  # --- fence-aware section location ---------------------------------------------
+
+  def each_fence_line(text)
+    return enum_for(:each_fence_line, text) unless block_given?
+
+    marker = nil
+    text.to_s.each_line do |line|
+      if marker
+        yield line, true
+        m = line.match(FENCE_LINE_RE)
+        next unless m && m[1][0] == marker[0] && m[1].length >= marker[1]
+        next unless line.sub(FENCE_LINE_RE, "").strip.empty?
+
+        marker = nil
+      else
+        m = line.match(FENCE_LINE_RE)
+        if m
+          marker = [m[1][0], m[1].length]
+          yield line, true
+        else
+          yield line, false
+        end
+      end
+    end
+  end
+
+  # [start_of_heading_line, start_of_next_top_level_heading_or_EOF] byte
+  # offsets for the FIRST line, outside any fence, whose stripped text
+  # exactly equals heading_text. nil when no such line exists.
+  def section_bounds(content, heading_text)
+    offset = 0
+    heading_start = nil
+
+    each_fence_line(content) do |line, fenced|
+      if !fenced && heading_start.nil? && line.strip == heading_text
+        heading_start = offset
+      elsif !fenced && heading_start && offset > heading_start && line.match?(/\A##[^#]/)
+        return [heading_start, offset]
+      end
+      offset += line.length
+    end
+
+    heading_start ? [heading_start, offset] : nil
+  end
+
+  def section_body(content, heading_text)
+    bounds = section_bounds(content, heading_text)
+    return nil unless bounds
+
+    start_idx, end_idx = bounds
+    content[(line_end(content, start_idx))...end_idx].to_s
+  end
+
+  def line_end(content, start_idx)
+    idx = content.index("\n", start_idx)
+    idx ? idx + 1 : content.length
+  end
+
+  def replace_or_append_section(content, heading_text, body_text)
+    rendered_body = body_text.to_s
+    rendered_body += "\n" unless rendered_body.end_with?("\n")
+    section = "#{heading_text}\n#{rendered_body}"
+
+    bounds = section_bounds(content, heading_text)
+    if bounds
+      start_idx, end_idx = bounds
+      tail = content[end_idx..].to_s
+      section += "\n" unless tail.empty?
+      content[0...start_idx] + section + tail
+    else
+      head = content.dup
+      head += "\n" unless head.end_with?("\n")
+      head += "\n" unless head.end_with?("\n\n")
+      head + section
+    end
+  end
+
+  # --- table rendering and reading -----------------------------------------------
+
+  def render_status_table(rows)
+    lines = ["| Node | State | Detail |", "| --- | --- | --- |"]
+    rows.each { |r| lines << "| #{r[:node]} | #{r[:state]} | #{r[:detail]} |" }
+    "#{lines.join("\n")}\n"
+  end
+
+  def rows_from_table(text)
+    return [] if text.nil?
+
+    lines = []
+    each_fence_line(text) do |line, fenced|
+      next if fenced
+
+      stripped = line.strip
+      lines << stripped if stripped.start_with?("|")
+    end
+    sep_idx = lines.index { |l| l.match?(/\A\|[\s:|-]+\|?\z/) }
+    return [] unless sep_idx
+
+    lines[(sep_idx + 1)..].map do |l|
+      cells = l.split("|", -1).map(&:strip)[1..-2].to_a
+      { node: cells[0], state: cells[1], detail: cells[2] }
+    end
+  end
+end

package/scripts/lib/graph_tree.rb

@@ -0,0 +1,98 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_edges"
+require_relative "ready_set"
+
+# GraphTree (intent 337, n2, folds 327a): draws any edge map ({id => [needs...]})
+# as an indented tree with box-drawing branches. A node may have any number
+# of children; a node several branches need (fan-out) is drawn once, at the
+# point where those branches join. A node that itself needs several things
+# (fan-in) can only occupy one position in the tree: it hangs under its
+# highest-batch need, ties broken by smallest id, with its other needs shown
+# as converging references at the join (row 2.14, folded at the 2026-09-10
+# plan review). Pure, plain text, no roadmap knowledge, so the same
+# renderer serves the roadmap file, the roadmap screens, and later the node
+# scope. Batch numbers (for placement) and the topological sort come from
+# ReadySet - the ONE sort (327 D1) - never a second local one here.
+module GraphTree
+  module_function
+
+  def render(edges:, labels:, marks:, width:)
+    edges = edges || {}
+    nodes = ReadySet.all_nodes(edges)
+
+    cyc = GraphEdges.cycle(edges)
+    if cyc
+      return { ok: false, text: nil, error: "cyclic graph, cannot render a tree: #{cyc.join(' > ')}", cycle: cyc }
+    end
+
+    if nodes.empty?
+      return { ok: true, text: "(no dependencies)\n", error: nil, cycle: nil }
+    end
+
+    batch_result = ReadySet.batches(edges)
+    batch_of = {}
+    batch_result[:batches].each_with_index { |layer, i| layer.each { |id| batch_of[id] = i + 1 } }
+
+    primary_parent = {}
+    converging = {}
+    nodes.each do |id|
+      needs = (edges[id] || []).uniq
+      next if needs.empty?
+
+      primary = needs.min_by { |n| [-(batch_of[n] || 0), n] }
+      primary_parent[id] = primary
+      others = needs - [primary]
+      converging[id] = others.sort unless others.empty?
+    end
+
+    children_of = Hash.new { |h, k| h[k] = [] }
+    primary_parent.each { |child, parent| children_of[parent] << child }
+    children_of.each_value { |list| list.sort! { |a, b| [batch_of[a] || 0, a] <=> [batch_of[b] || 0, b] } }
+
+    roots = nodes.select { |id| (edges[id] || []).empty? }.sort
+
+    labels ||= {}
+    marks ||= {}
+    critical = (marks[:critical_path] || []).to_a
+    ready = (marks[:ready] || []).to_a
+
+    lines = []
+    roots.each { |id| append_node(id, "", "", lines, children_of, labels, critical, ready, converging, width) }
+
+    { ok: true, text: "#{lines.join("\n")}\n", error: nil, cycle: nil }
+  end
+
+  # `ancestor_prefix` is the continuation string every ancestor above this
+  # node contributes ("│   " when that ancestor still has a later sibling
+  # to draw, "    " when it was the last child); `connector` is this node's
+  # own branch glyph off its parent ("├── " / "└── "), empty for a root.
+  def append_node(id, ancestor_prefix, connector, lines, children_of, labels, critical, ready, converging, width)
+    lines << render_line(ancestor_prefix + connector, id, labels, critical, ready, converging, width)
+
+    continuation = connector == "└── " ? "    " : (connector.empty? ? "" : "│   ")
+    child_ancestor_prefix = ancestor_prefix + continuation
+
+    children = children_of[id] || []
+    children.each_with_index do |child_id, i|
+      last = i == children.length - 1
+      child_connector = last ? "└── " : "├── "
+      append_node(child_id, child_ancestor_prefix, child_connector, lines, children_of, labels, critical, ready, converging, width)
+    end
+  end
+
+  def render_line(connector, id, labels, critical, ready, converging, width)
+    label = labels.fetch(id, id).to_s
+    text = critical.include?(id) ? "* #{label}" : label
+    text += " (also needs #{converging[id].join(', ')})" if converging[id]
+    text += " (ready)" if ready.include?(id)
+
+    available = width - connector.length
+    if available.positive? && text.length > available
+      text = available > 3 ? "#{text[0, available - 3]}..." : text[0, available]
+    end
+
+    "#{connector}#{text}"
+  end
+end