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

package/scripts/doctor.rb

@@ -10,8 +10,13 @@
 # Read-only — never modifies files.
 
 require "date"
+require "open3"
+require "timeout"
+require "fileutils"
+require "tmpdir"
 
 require_relative "lib/doctor_core"
+require_relative "lib/hook_replay"
 
 require_relative "lib/doctor_exclusions"
 require_relative "lib/qmd_sync"
@@ -22,6 +27,9 @@ require_relative "lib/links_projection"
 require_relative "lib/links_section"
 require_relative "lib/lock"
 require_relative "lib/savepoint"
+require_relative "lib/node_ledger"
+require_relative "lib/ready_set"
+require_relative "lib/index_projection"
 require_relative "lib/agent_models"
 require_relative "lib/outcome_guard"
 require_relative "lib/skill_lint"
@@ -30,6 +38,7 @@ require_relative "lib/power_tools"
 require_relative "lib/preflight"
 require_relative "lib/ruby_probe"
 require_relative "lib/doctor_session_ledger"
+require_relative "lib/intent_screen"
 
 # Diagnostic engine, instantiable with an injected store/agent map so tests can
 # run it hermetically (no eval, no global-constant rewriting).
@@ -46,6 +55,13 @@ class Doctor
   # (intent 60). Alias it here so the two can never drift.
   REQUIRED_FRONTMATTER_FIELDS = IntentValidator::REQUIRED_FIELDS
 
+  # Repo root, for the three display checks below that read shipped, static
+  # package content (the fixture fallback, the harness-adapters doc) rather
+  # than a runtime plastic_home path. Same derivation as
+  # StoreProvisioning::PACKAGE_ROOT (intent 61): scripts/doctor.rb lives one
+  # level under the root.
+  PACKAGE_ROOT = File.expand_path("..", __dir__)
+
 
 
   # --- Flag parsing ---
@@ -288,6 +304,167 @@ class Doctor
   # content scanning. check_global_store (above) is store/full-scope and includes
   # orphaned_intents / ghost_references, both explicitly forbidden at core by D1.
 
+  # Row E (spec D8, spec 315b): #check_core_files's own `version_match` only ever
+  # compares the SELECTED harness's `<dir>/plastic/VERSION` against the global
+  # VERSION, so a second installed harness left behind on an old version is never
+  # version-checked at all -- exactly how ten stale 1.14.1 Codex registrations
+  # survived a `pass`. This runs the same comparison for EVERY installed harness
+  # (agent_dir on disk), named `version_match_<key>` so the existing `version_match`
+  # name and position stay reserved for the selected harness (pinned tests:
+  # test/doctor_test.rb:1846,1861,1873). Full tier only (`run_checks`); never
+  # `run_core_checks`, which is `binary: true` and runs on the session-start boot
+  # path, where a second-harness warn would become a boot-time error for every user.
+  def check_harness_versions
+    global_version = read_version
+    return [] unless global_version
+
+    agents.filter_map do |key, config|
+      next unless config.is_a?(Hash) && File.directory?(config[:dir].to_s)
+
+      agent_version_path = File.join(config[:dir], "plastic", "VERSION")
+      name = "version_match_#{key}"
+
+      if !File.exist?(agent_version_path)
+        check(
+          category: "core_files", name: name, status: "warn",
+          message: "#{config[:name]}'s agent-side VERSION file not found at #{tilde(agent_version_path)}",
+          fixable: true,
+          fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+        )
+      else
+        agent_version = File.read(agent_version_path).strip
+        if global_version == agent_version
+          check(
+            category: "core_files", name: name, status: "pass",
+            message: "Global VERSION (#{global_version}) matches #{config[:name]}'s agent-side VERSION"
+          )
+        else
+          check(
+            category: "core_files", name: name, status: "warn",
+            message: "Version mismatch for #{config[:name]}: global=#{global_version}, agent=#{agent_version}",
+            details: [
+              "#{tilde(File.join(plastic_home, "VERSION"))}: #{global_version}",
+              "#{tilde(agent_version_path)}: #{agent_version}",
+            ],
+            fixable: true,
+            fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+          )
+        end
+      end
+    end
+  end
+
+  # The Codex hook NAME expected per event, keyed off HookRegistry's own
+  # constants rather than a full built command string: naming it, not the
+  # literal dispatcher path, is what #check_codex_stale_registrations needs,
+  # so this never depends on plastic_home resolving to the same install the
+  # live hooks.json's commands were written under.
+  def codex_expected_names_by_event
+    names = {}
+    post_order = HookRegistry.events["PostToolUse"].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    names["PostToolUse"] = HookRegistry::CODEX_POST_HOOKS & post_order
+
+    HookRegistry::CODEX_LIVE_STATE_EVENTS.each do |event|
+      names[event] = HookRegistry.events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    end
+
+    end_order = HookRegistry.events["SessionEnd"].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    names["SessionEnd"] = HookRegistry::CODEX_SESSION_END_HOOKS & end_order
+    names
+  end
+
+  # Row E (spec D8, spec 315b): #codex_hooks_registered_check computes
+  # `want - got` and iterates `expected.each`, so it can see a MISSING registration
+  # but never an EXTRA one, and it can never even visit an event `expected` does not
+  # list at all (a retired event such as PreToolUse, which a stale ~/.codex/hooks.json
+  # can still carry). This scans the UNION of expected and live event keys instead, so
+  # a stale registration parked in a retired event is visible. Compares hook NAMES
+  # (see #codex_expected_names_by_event), not full command strings: a full-command
+  # comparison would embed this Doctor instance's own `plastic_home` in the expected
+  # dispatcher path, which is only guaranteed to match the live hooks.json's own
+  # dispatcher path in a real, single install, never a test that fakes one without the
+  # other. Full tier only (`run_checks`); never `run_core_checks` (D8).
+  #
+  # Post-execution review item 5: name-only comparison alone is blind to two real
+  # cases, both closed here without reintroducing any plastic_home coupling: (a) the
+  # SAME (event, name) pair registered more than once (each copy's name is
+  # individually expected, so a "not in the expected set" scan never sees the
+  # duplicate), and (b) a correctly-named entry whose dispatcher path is an OLD
+  # install, different from the path every OTHER Plastic entry in this same file
+  # actually uses -- the "correct" path here is whichever path the file's own
+  # majority of entries already agrees on, never a path this Doctor instance derives
+  # from its own plastic_home.
+  def check_codex_stale_registrations
+    config = agents["codex"]
+    return [] unless config.is_a?(Hash) && File.directory?(config[:dir].to_s)
+
+    home_dir = config[:home_dir] || config[:dir]
+    hooks_json = File.join(home_dir, "hooks.json")
+    data = read_json_safe(hooks_json)
+    return [] if data.nil? || !data.is_a?(Hash)
+
+    expected_names = codex_expected_names_by_event
+    live = data["hooks"].is_a?(Hash) ? data["hooks"] : {}
+
+    # One pass over every live Plastic entry (event, hook name, and the literal
+    # dispatcher-path token it actually invokes), shared by all three checks below.
+    entries = []
+    (expected_names.keys | live.keys).each do |event|
+      Array(live[event]).each do |group|
+        Array(group["hooks"]).each do |h|
+          cmd = h["command"]
+          next unless HookRegistry.codex_purge_command?(cmd)
+
+          dispatcher_path = cmd.to_s.split(/\s+/).reject(&:empty?).first.to_s.delete("\"'")
+          name = HookRegistry.command_basenames(cmd).last
+          entries << { event: event, name: name, dispatcher_path: dispatcher_path, cmd: cmd }
+        end
+      end
+    end
+
+    stale = []
+
+    # Not in the expected name set for this event at all (the original check).
+    entries.each do |e|
+      want_names = Array(expected_names[e[:event]])
+      stale << "#{e[:event]}: #{e[:cmd]}" unless want_names.include?(e[:name])
+    end
+
+    # (a) the same (event, name) pair registered more than once.
+    entries.group_by { |e| [e[:event], e[:name]] }.each_value do |group|
+      next if group.size <= 1
+
+      group.each { |e| stale << "#{e[:event]}: #{e[:cmd]} (duplicate registration of #{e[:name]})" }
+    end
+
+    # (b) a dispatcher path that differs from the path every other Plastic entry in
+    # this same file actually uses.
+    unless entries.empty?
+      majority_path = entries.map { |e| e[:dispatcher_path] }.tally.max_by { |(_path, count)| count }&.first
+      entries.each do |e|
+        next if e[:dispatcher_path] == majority_path
+
+        stale << "#{e[:event]}: #{e[:cmd]} (dispatcher path #{e[:dispatcher_path]} differs from " \
+                  "this file's other Plastic entries at #{majority_path})"
+      end
+    end
+
+    stale.uniq!
+
+    if stale.empty?
+      [check(
+        category: "agent_registration", name: "codex_stale_registrations", status: "pass",
+        message: "No stale Plastic Codex registrations found outside the expected hook set"
+      )]
+    else
+      [check(
+        category: "agent_registration", name: "codex_stale_registrations", status: "warn",
+        message: "#{stale.size} stale Codex registration(s) found outside the expected hook set",
+        details: stale, fixable: true,
+        fix_hint: "Re-run the Plastic installer with --codex --reinstall to purge stale entries"
+      )]
+    end
+  end
   # --- Check category 2: Conventions ---
 
   # When `scopes` is a non-nil Array of scope strings (e.g. ["global"] or
@@ -446,6 +623,14 @@ class Doctor
     # flagged: validate_graph does not compute it.
     checks.concat(graph_invariant_checks(intent_dirs))
 
+    # node_graph - ReadySet's own view of every intent carrying a real graph.md
+    # (intent 336, n7): dead ends, stale done nodes, and expired running leases,
+    # none of which any other doctor rule surfaces. Lives here rather than
+    # doctor_core.rb because test/doctor_core_split_test.rb pins that file's
+    # boot path to exactly three project files and 781 bytes of headroom;
+    # ReadySet's own require chain is 65,648 bytes, far past that budget.
+    checks.concat(node_graph_checks(intent_dirs))
+
     # cross_store_resolution — RESOLVES (not just shape-checks) every cross-store
     # `store:id` ref against the FULL store family via the relocation map
     # (relocation consulted first), closing the shape-only gap i1/i3/i4 leave open.
@@ -611,7 +796,14 @@ def done_signal_findings_for_dir(dir, label:, scope:, dirname:, terminal:, activ
     # reported as a fixable warn (backfilled_complete). Its exclusions go to their OWN
     # bucket so savepoint_operational's consumed/dead-row bookkeeping above never sees them.
     backfill_gaps = %w[spec.md plan.md].reject { |f| Savepoint.stage_file_present?(File.join(dir, f)) }
-    backfill_gaps << "actions/" unless Savepoint.has_real_action?(dir)
+    # Name whichever directory the intent actually used (post-execution
+    # review, non-blocking 8), consistent with Savepoint.missing_for_stage:
+    # a nodes/ directory on disk means the intent chose the node-graph
+    # convention, so a gap here is a missing nodes/, never the literal
+    # actions/ has_real_action? no longer implies.
+    unless Savepoint.has_real_action?(dir)
+      backfill_gaps << (File.directory?(File.join(dir, "nodes")) ? "nodes/" : "actions/")
+    end
     if backfill_gaps.any?
       suppressed_backfill = excluded_rules.include?("backfilled_complete")
       target = suppressed_backfill ? findings[:excluded_backfill] : findings[:unbackfilled]
@@ -646,6 +838,9 @@ def check_done_signals(scopes: nil)
   unbackfilled = []       # spec/plan/actions gaps on terminal intents (intent 308) - repairable
   excluded_backfill = []  # backfill gaps knowingly exempted via doctor-exclusions (intent 308)
   dead_rows_by_rule = Hash.new { |h, k| h[k] = [] }
+  index_drift = []        # intent 337 (G4): INDEX vs. the intent ledgers, scoped to what
+                           # savepoint_operational does not already report (row 6.7 - a silent or
+                           # absent ledger is already IndexProjection's own exclusion, row 5.13)
 
   done_signal_stores(scopes).each do |store|
     exclusions = DoctorExclusions.load(store[:index])
@@ -654,6 +849,14 @@ def check_done_signals(scopes: nil)
       exclusion_error_paths << exclusions[:path]
     end
 
+    if File.exist?(store[:index])
+      projection = IndexProjection.analyze(store[:store_dir], index_path: store[:index])
+      projection[:drift].each do |row|
+        index_drift << "#{store[:scope]}: #{row[:id]} - INDEX says #{row[:index_status]}, " \
+                        "the ledger's last Done line says #{row[:ledger_status]}"
+      end
+    end
+
     consumed = { "savepoint_operational" => [], "backfilled_complete" => [] }
     # `known_ids` (post-review fix): every intent id with a REAL DIRECTORY in this store, scanned
     # directly from disk - independent of INDEX.md. An id can have a directory on disk without
@@ -898,6 +1101,30 @@ def check_done_signals(scopes: nil)
     )
   end
 
+  # index_ledger_drift (intent 337, G4): a REAL terminal ledger line (Done
+  # delivered or abandoned) that disagrees with the INDEX section an intent
+  # currently sits in. Never fires for a silent or absent ledger - that gap
+  # is savepoint_operational's own concern, and IndexProjection's own drift
+  # computation already excludes it (row 5.13), so no id is ever double
+  # reported across the two checks (row 6.7). Warn+fixable: `index-projection
+  # <store_root> --write` is the repair, never invented here.
+  if index_drift.empty?
+    checks << check(
+      category: "done_signals", name: "index_ledger_drift", status: "pass",
+      message: "No INDEX section disagrees with an intent's own terminal ledger line"
+    )
+  else
+    checks << check(
+      category: "done_signals", name: "index_ledger_drift", status: "warn",
+      message: "#{index_drift.size} intent#{index_drift.size == 1 ? "" : "s"} whose terminal " \
+               "ledger line disagrees with the INDEX section it currently sits in",
+      details: index_drift, fixable: true,
+      fix_hint: "Reconcile via `index-projection <store_root> --write` (the ledger wins; only the " \
+                "conflicting entries move, every other byte of INDEX.md, including ## Clusters and " \
+                "## Relocated, is left untouched)."
+    )
+  end
+
   checks
 end
 
@@ -1000,9 +1227,12 @@ end
   #
   # Doctor's fourth check scope, invoked by `--intent <id>`. Never a store-wide sweep:
   # resolves exactly one intent directory (mirrors scripts/end-intent's resolve_intent_dir /
-  # scripts/project-links's --intent disambiguation) and returns five checks, four
-  # FAIL-severity, one WARN-severity (intent_savepoint_truthful stays WARN per intent 134's
-  # binding advisory-only ruling; see spec.md D2/D8 - do NOT escalate it to FAIL).
+  # scripts/project-links's --intent disambiguation) and returns seven checks, four
+  # FAIL-severity, three WARN-severity: intent_savepoint_truthful stays WARN per intent 134's
+  # binding advisory-only ruling (see spec.md D2/D8 - do NOT escalate it to FAIL),
+  # intent_ticks_lag is WARN-only per intent 329's ruling that a lagging tick warns rather
+  # than blocks, and intent_reports_printed is WARN-only per intent 331f (never re-litigates
+  # a ledger predating the Report kind).
   def check_intent_end(id, store: nil, disposition: nil)
     intent_dir, scope = resolve_single_intent_dir(id, store: store)
     unless intent_dir
@@ -1024,6 +1254,8 @@ end
       intent_structure_check(intent_dir),
       intent_lifecycle_artifacts_check(intent_dir, disposition),
       intent_checklist_complete_check(intent_dir),
+      intent_ticks_lag_check(intent_dir),
+      intent_reports_printed_check(intent_dir),
       intent_links_projection_check_for(id, scope),
       intent_savepoint_truthful_check(intent_dir, index_path: index_path),
     ]
@@ -1102,6 +1334,80 @@ end
     end
   end
 
+  # Intent 329: the checklist is the only input to the state screen's Progress bar, so an
+  # intent whose commit ledger has entries and whose checklist has no ticked item is
+  # reporting 0 progress on work that already landed. Advisory only (WARN), like
+  # intent_savepoint_truthful: a lagging tick is a lead's review finding, never a machine
+  # refusal. The commit count comes from this intent's own savepoint.md Commit ledger
+  # (intent 317 D17), never from git: git's detected base is the repo default branch, which
+  # is not the base a 2.0 intent branch forks from.
+  def intent_ticks_lag_check(intent_dir)
+    items = IntentScreen.checklist_items(intent_dir)
+    if items.empty?
+      return check(category: "intent_end", name: "intent_ticks_lag", status: "pass",
+                   message: "n/a: checklist.md has no items to tick")
+    end
+
+    ticked = items.count { |i| i[:done] }
+    commits = savepoint_commit_count(intent_dir)
+
+    if commits.positive? && ticked.zero?
+      check(category: "intent_end", name: "intent_ticks_lag", status: "warn",
+            message: "ticks lag the branch: #{commits} commit(s) recorded, " \
+                     "0 of #{items.size} checklist items ticked")
+    else
+      check(category: "intent_end", name: "intent_ticks_lag", status: "pass",
+            message: "#{ticked} of #{items.size} ticked, #{commits} commit(s) recorded")
+    end
+  end
+
+  # Intent 331f: every skill that shows state during Exec is bound to print a report screen and
+  # log a `Report` savepoint line (`savepoint-note --kind Report`). A commit landed with no
+  # Report line anywhere in the ledger is the exact defect this check exists to catch - the
+  # delivery ran but nothing on disk proves a screen was ever printed. WARN-only, like
+  # intent_ticks_lag: a lead's review finding, never a machine refusal. R6: never re-litigate
+  # history - an intent whose newest Commit line predates the day the Report kind shipped
+  # (Savepoint::REPORT_KIND_SINCE) passes, so every pre-existing ledger keeps passing
+  # `doctor --intent` (which exits 1 on an overall warn).
+  def intent_reports_printed_check(intent_dir)
+    path = File.join(intent_dir, "savepoint.md")
+    lines = File.exist?(path) ? File.readlines(path) : []
+    kinds = lines.filter_map { |l| l.strip.match(IntentScreen::SAVEPOINT_RE) }
+
+    commit_timestamps = kinds.select { |m| m[2] == "Commit" }.map { |m| m[1] }
+    if commit_timestamps.empty?
+      return check(category: "intent_end", name: "intent_reports_printed", status: "pass",
+                    message: "n/a: no commits recorded")
+    end
+
+    if kinds.any? { |m| m[2] == "Report" }
+      return check(category: "intent_end", name: "intent_reports_printed", status: "pass",
+                    message: "a Report line is recorded")
+    end
+
+    newest_commit_date = commit_timestamps.max[0, 10]
+    if newest_commit_date < Savepoint::REPORT_KIND_SINCE
+      return check(category: "intent_end", name: "intent_reports_printed", status: "pass",
+                    message: "n/a: newest commit (#{newest_commit_date}) predates the Report " \
+                             "kind (#{Savepoint::REPORT_KIND_SINCE})")
+    end
+
+    check(category: "intent_end", name: "intent_reports_printed", status: "warn",
+          message: "commits are recorded and no Report line exists")
+  end
+
+  # Count `Commit` lines in the intent's savepoint ledger, through the one regex that parses
+  # a savepoint line (IntentScreen::SAVEPOINT_RE; field 2 is the kind).
+  def savepoint_commit_count(intent_dir)
+    path = File.join(intent_dir, "savepoint.md")
+    return 0 unless File.exist?(path)
+
+    File.readlines(path).count do |line|
+      m = line.strip.match(IntentScreen::SAVEPOINT_RE)
+      m && m[2] == "Commit"
+    end
+  end
+
   def intent_links_projection_check_for(id, scope)
     ctx = build_links_projection_context
     node = ctx[:intents].find { |n| n[:id] == id && n[:scope] == scope }
@@ -1208,20 +1514,37 @@ end
     expected_pair = Savepoint.savepoint_milestone(intent_dir, File.basename(Savepoint.intent_file(intent_dir)))
 
     phantoms = Savepoint.savepoint_phantom_lines(intent_dir)
+    # Intent 335 (spec C2/C5): a torn or unattributed node/Intent transition
+    # line has no reader anywhere else in the tree, so this is where it
+    # surfaces. NodeLedger.anomalies never touches a stage line (its own
+    # transition-candidate gate excludes them), so this is purely additive
+    # beside the phantom check above.
+    transition_anomalies = NodeLedger.anomalies(savepoint)
     problems = []
     problems << "born line #{born_pair.inspect} does not match the expected #{expected_pair.inspect}" \
       if born_pair != expected_pair
     problems << "#{phantoms.size} phantom savepoint line(s): " \
                 "#{phantoms.map { |l, r| "#{l} (#{r})" }.join("; ")}" if phantoms.any?
+    problems << "#{transition_anomalies.size} torn/unattributed transition line(s): " \
+                "#{transition_anomalies.map { |a| "#{a[:line]} (#{a[:reason]})" }.join("; ")}" \
+      if transition_anomalies.any?
 
     if problems.empty?
       check(category: "intent_end", name: "intent_savepoint_truthful", status: "pass",
             message: "Savepoint born line and phantom-line state are truthful")
     else
+      # A torn or unattributed transition line's CONTENT cannot be repaired by
+      # a rebuild (rebuild_savepoint preserves it verbatim, spec D13), unlike a
+      # born-line mismatch or a stage phantom, which rebuild does fix. Say so
+      # explicitly rather than pointing at a fix that will not fix it.
+      fix_hint = "Rebuild the ledger via Savepoint.rebuild_savepoint"
+      fix_hint += "; note: rebuild preserves a torn or unattributed transition line " \
+                  "verbatim and does not repair one - hand-edit it or accept the finding" \
+        if transition_anomalies.any?
       check(category: "intent_end", name: "intent_savepoint_truthful", status: "warn",
             message: "#{problems.size} savepoint truthfulness issue(s) (advisory, never blocking)",
             details: problems,
-            fixable: true, fix_hint: "Rebuild the ledger via Savepoint.rebuild_savepoint")
+            fixable: true, fix_hint: fix_hint)
     end
   end
 
@@ -1367,6 +1690,90 @@ end
     end
   end
 
+  # ReadySet over every intent carrying a real graph.md (intent 336, n7):
+  # dead ends, stale done nodes, and expired running leases. An intent with
+  # no real graph.md is skipped entirely (never touches ReadySet); a
+  # malformed or cyclic one is reported by name, never raised out of doctor.
+  def node_graph_checks(intent_dirs)
+    dead_ends = []
+    stale = []
+    expired = []
+    malformed = []
+
+    intent_dirs.each do |d|
+      graph_path = File.join(d[:path], "graph.md")
+      next unless Savepoint.stage_file_present?(graph_path)
+
+      analysis = ReadySet.analyze(d[:path])
+      unless analysis[:ok]
+        malformed << "#{d[:name]}: #{analysis[:errors].join('; ')}"
+        next
+      end
+
+      savepoint_path = File.join(d[:path], "savepoint.md")
+      analysis[:nodes].each do |id, view|
+        dead_ends << "#{d[:name]}/#{id}" if view[:dead_end]
+        stale << "#{d[:name]}/#{id}" if view[:stale]
+        expired << "#{d[:name]}/#{id}" if view[:state] == "running" && expired_running_lease?(savepoint_path, id)
+      end
+    end
+
+    [
+      node_graph_finding_check(
+        "node_graph_dead_ends", dead_ends,
+        "No node waits on a need that resolves to superseded or abandoned",
+        "Re-plan or supersede the dead-end node's need chain, or abandon the node itself"
+      ),
+      node_graph_finding_check(
+        "node_graph_stale_done", stale,
+        "No done node rests on a need superseded after it finished",
+        "Re-verify the stale node against the superseding work, or record the staleness in revisions.md"
+      ),
+      node_graph_finding_check(
+        "node_graph_expired_running_lease", expired,
+        "No running node's lease has expired unreclaimed",
+        "Run `node-transition <intent_dir> --node <id> --state reclaimed --field holder=<h> " \
+        "--field expired=<iso>` to sweep it"
+      ),
+      node_graph_finding_check(
+        "node_graph_malformed", malformed,
+        "Every intent's graph.md parses cleanly",
+        "Fix the malformed graph.md or nodes/ file named in the details"
+      ),
+    ]
+  end
+
+  # True iff `id`'s last running line in the ledger at `savepoint_path` carries
+  # an `expires=` strictly in the past. An unparseable or absent expires=
+  # never counts as expired (fail milder than the bug).
+  def expired_running_lease?(savepoint_path, id, now: Time.now)
+    entry = NodeLedger.last_running(savepoint_path, id)
+    return false unless entry
+
+    expires_raw = (entry[:fields] || {})["expires"]
+    expiry = begin
+      expires_raw && Time.iso8601(expires_raw)
+    rescue ArgumentError
+      nil
+    end
+    !!(expiry && now > expiry)
+  end
+
+  # One node-graph check: pass when `findings` is empty, otherwise warn
+  # (never fail, matching graph_finding_check's own precedent - an existing
+  # store never turns red on an advisory graph finding).
+  def node_graph_finding_check(name, findings, pass_message, fix_hint)
+    if findings.empty?
+      check(category: "conventions", name: name, status: "pass", message: pass_message)
+    else
+      check(
+        category: "conventions", name: name, status: "warn",
+        message: "#{findings.size} #{name} violation(s)",
+        details: findings, fixable: false, fix_hint: fix_hint
+      )
+    end
+  end
+
   # --- Check category 3: Agent registration ---
 
 
@@ -2227,6 +2634,240 @@ end
     end
   end
 
+  # --- Check category: display (intent 331e, D1) ---
+  #
+  # Three of the four `display` checks live HERE, not in doctor_core.rb: they
+  # need Open3/Timeout to spawn the installed hook as a real subprocess, and
+  # that must never attach to the SessionStart boot path
+  # (test/doctor_core_split_test.rb T2 pins doctor_core.rb's require set
+  # exactly). check_display_registration (the fourth, --core-scoped) lives in
+  # doctor_core.rb instead, alongside display_hook_launcher_name, which this
+  # file's check_display_paints reuses to name the SAME installed launcher.
+
+  # The ambient defeater active for THIS invocation, or nil. `no_color` is
+  # DI'd (default ENV["NO_COLOR"]) rather than read deep inside this method,
+  # so a test can force it on or off without touching the real process
+  # environment. Shared by check_display_paints (a defeater turns a
+  # would-be fail into a pass, R3) and check_display_not_defeated (a
+  # defeater is what it warns about).
+  def active_display_defeater(no_color: ENV["NO_COLOR"])
+    return "NO_COLOR" unless no_color.to_s.empty?
+
+    cfg = load_yaml_safe(File.join(plastic_home, "config.yml"))
+    display_cfg = cfg.is_a?(Hash) ? cfg["display"] : nil
+    return "display.ansi_screen: false in config.yml" if display_cfg.is_a?(Hash) &&
+                                                          display_cfg.fetch("ansi_screen", true) == false
+
+    nil
+  end
+
+  # The shipped fixture's path: plastic_home's own templates/ first (a real
+  # install), the package's own templates/ otherwise (running from a repo
+  # checkout, or an install whose templates/ predates this fixture). Neither
+  # existing means no fixture at all.
+  def display_fixture_path(package_root: PACKAGE_ROOT)
+    [File.join(plastic_home, "templates", "display-fixture.md"),
+     File.join(package_root, "templates", "display-fixture.md")].find { |p| File.file?(p) }
+  end
+
+  # The fixture's replayable text: its header comment (see
+  # templates/display-fixture.md) is for a human reading the file on disk,
+  # never sent through the hook.
+  def display_fixture_text(path)
+    File.read(path).sub(/\A<!--.*?-->\n\n?/m, "")
+  end
+
+  # display_hook_paints (D1, R1/R2/R3): replays the shipped fixture through
+  # the INSTALLED launcher (`<agent_dir>/hooks/plastic-message-display`,
+  # never this package's own hooks/message-display. That is R1's whole point: an
+  # installed launcher can predate the package's, and replaying the wrong
+  # one reports pass while the real stack is stale) and expects a painted
+  # (ANSI) screen back.
+  #
+  # A known defeater active (NO_COLOR, or display.ansi_screen: false) turns
+  # a no-SGR result into a PASS, naming the defeater and noting it reflects
+  # this invocation's own environment (R3). display_not_defeated is what
+  # warns about a defeater; this check never fails because of one.
+  def check_display_paints(agent_key, no_color: ENV["NO_COLOR"],
+                            tmp_dir_factory: -> { Dir.mktmpdir("plastic-doctor-display") },
+                            timeout_seconds: 10, package_root: PACKAGE_ROOT)
+    config = agents[agent_key]
+    unless agent_key == "claude"
+      return [check(
+        category: "display", name: "display_hook_paints", status: "pass",
+        message: "#{config[:name]} is plain by contract; no display hook to replay"
+      )]
+    end
+
+    fixture_path = display_fixture_path(package_root: package_root)
+    unless fixture_path
+      return [check(
+        category: "display", name: "display_hook_paints", status: "fail",
+        message: "Shipped display fixture is missing (templates/display-fixture.md)",
+        fixable: false
+      )]
+    end
+
+    agent_dir = config[:dir]
+    launcher_path = File.join(agent_dir, "hooks", display_hook_launcher_name)
+    unless File.file?(launcher_path) && File.executable?(launcher_path)
+      return [check(
+        category: "display", name: "display_hook_paints", status: "fail",
+        message: "Installed launcher #{tilde(launcher_path)} is missing or not executable; cannot replay",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    text = display_fixture_text(fixture_path)
+    tmp_dir = tmp_dir_factory.call
+    outs =
+      begin
+        HookReplay.replay(hook_path: launcher_path, tmp_root: tmp_dir, text: text,
+                           env: { "PLASTIC_HOME" => plastic_home }, timeout: timeout_seconds)
+      rescue StandardError => e
+        # Process.spawn (inside HookReplay) can raise before a pid ever
+        # exists: a permissions race, or a launcher that vanishes between the
+        # executable? check above and the spawn, or any other unexpected
+        # error. Unlike this codebase's defensive style elsewhere
+        # (read_json_safe, load_yaml_safe), nothing here degraded that into
+        # a clean check result, so an unlucky replay crashed the entire
+        # doctor run instead of failing just this one check (intent 331e,
+        # F6). `return` still runs the `ensure` below before unwinding.
+        return [check(
+          category: "display", name: "display_hook_paints", status: "fail",
+          message: "Replaying the installed launcher raised #{e.class}: #{e.message}",
+          fixable: false
+        )]
+      ensure
+        FileUtils.remove_entry(tmp_dir) if tmp_dir && File.exist?(tmp_dir)
+      end
+
+    if HookReplay.timed_out?(outs)
+      return [check(
+        category: "display", name: "display_hook_paints", status: "fail",
+        message: "Replaying the installed launcher timed out after #{timeout_seconds}s; painting could not be verified",
+        fixable: false
+      )]
+    end
+
+    defeater = active_display_defeater(no_color: no_color)
+    if defeater
+      return [check(
+        category: "display", name: "display_hook_paints", status: "pass",
+        message: "Painting is defeated by #{defeater} for this invocation; the replay's plain " \
+                  "output reflects that setting, not a broken hook"
+      )]
+    end
+
+    content = HookReplay.final_display_content(outs)
+    if content.to_s.include?("\e[")
+      [check(
+        category: "display", name: "display_hook_paints", status: "pass",
+        message: "The installed hook returned a painted (ANSI) screen"
+      )]
+    else
+      [check(
+        category: "display", name: "display_hook_paints", status: "fail",
+        message: "The installed hook returned no ANSI escape sequence; painting may be broken",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+  end
+
+  # display_not_defeated (D1, R3/R4): warns, never fails, on each active
+  # defeater, naming the setting and its effect. Every result, pass or warn alike,
+  # names the verbose transcript view (Ctrl+O, R4): it redraws every
+  # screen as plain tables too, but it has no on-disk setting doctor can
+  # read, so its absence from these warnings is never proof that view paints.
+  def check_display_not_defeated(agent_key, no_color: ENV["NO_COLOR"])
+    config = agents[agent_key]
+    unless agent_key == "claude"
+      return [check(
+        category: "display", name: "display_not_defeated", status: "pass",
+        message: "#{config[:name]} is plain by contract; no display defeaters apply"
+      )]
+    end
+
+    warnings = []
+    warnings << "NO_COLOR is set: forces every screen to plain text for this invocation" unless no_color.to_s.empty?
+
+    cfg = load_yaml_safe(File.join(plastic_home, "config.yml"))
+    display_cfg = cfg.is_a?(Hash) ? cfg["display"] : nil
+    if display_cfg.is_a?(Hash) && display_cfg.fetch("ansi_screen", true) == false
+      warnings << "config.yml sets display.ansi_screen: false: forces every screen to plain text"
+    end
+
+    settings = read_json_safe(File.join(config[:dir], "settings.json"))
+    if settings.is_a?(Hash) && settings["verbose"] == true
+      warnings << "settings.json sets verbose: true: the verbose transcript view (Ctrl+O) redraws every screen as plain tables"
+    end
+
+    transcript_note = "The Ctrl+O verbose transcript view also redraws every screen as plain " \
+                      "tables and has no on-disk setting; its absence above is never proof that view paints."
+
+    if warnings.empty?
+      [check(
+        category: "display", name: "display_not_defeated", status: "pass",
+        message: "No known display defeaters active", details: [transcript_note]
+      )]
+    else
+      [check(
+        category: "display", name: "display_not_defeated", status: "warn",
+        message: "#{warnings.size} display defeater(s) active",
+        details: warnings + [transcript_note]
+      )]
+    end
+  end
+
+  # display_surfaces_documented (D1/D4): the harness-adapters doc names the
+  # three surface classes. Reads the package's own shipped doc: static
+  # content, not a runtime path, the same shape as check_skill_lint reading the
+  # package's own skills/ tree.
+  #
+  # `docs/` ships in NEITHER package.json's `files` list NOR
+  # InstallerCore's manifest (grep confirms zero references), so on every
+  # real install `package_root` resolves to a `~/.plastic` that has no
+  # `docs/` tree at all; only a repo checkout carries it. Absence of the
+  # doc there is therefore not a defect to report; it is this install
+  # having nothing to verify, the same skip-as-pass vocabulary D3 and R3
+  # already use elsewhere in this category. This check fails only when the
+  # doc DOES exist (a repo checkout) but has rotted: no `## Surfaces`
+  # section, or one missing a required literal.
+  def check_display_surfaces_documented(package_root: PACKAGE_ROOT)
+    doc_path = File.join(package_root, "docs", "reference", "harness-adapters.md")
+
+    unless File.file?(doc_path)
+      return [check(
+        category: "display", name: "display_surfaces_documented", status: "pass",
+        message: "Reference docs are not shipped to this install (#{tilde(doc_path)} absent); " \
+                  "nothing to verify"
+      )]
+    end
+
+    content = File.read(doc_path)
+    section = content[/^## Surfaces\n(.*?)(?=\n## |\z)/m, 1].to_s
+
+    required = ["Claude Code normal view", "agents view", "Codex", "claude -p", "verbose transcript view"]
+    missing = required.reject { |literal| section.include?(literal) }
+
+    if section.empty?
+      [check(
+        category: "display", name: "display_surfaces_documented", status: "fail",
+        message: "docs/reference/harness-adapters.md has no ## Surfaces section", fixable: false
+      )]
+    elsif missing.empty?
+      [check(
+        category: "display", name: "display_surfaces_documented", status: "pass",
+        message: "harness-adapters.md documents every display surface class"
+      )]
+    else
+      [check(
+        category: "display", name: "display_surfaces_documented", status: "fail",
+        message: "## Surfaces section is missing: #{missing.join(', ')}", details: missing, fixable: false
+      )]
+    end
+  end
+
   # --- Run all checks ---
 
   def run_checks(agent_key)
@@ -2235,6 +2876,8 @@ end
     all_checks += check_conventions(scopes: ["global"])
     all_checks += check_agent_registration(agent_key)
     all_checks += check_core_files(agent_key)
+    all_checks += check_harness_versions
+    all_checks += check_codex_stale_registrations
     all_checks += check_deprecations
     all_checks += check_config_asks(agent_key)
     all_checks += check_qmd
@@ -2243,6 +2886,10 @@ end
     all_checks += check_session_ledger(scopes: ["global"])
     all_checks += check_skill_lint
     all_checks += check_install_integrity
+    all_checks += check_display_registration(agent_key)
+    all_checks += check_display_paints(agent_key)
+    all_checks += check_display_not_defeated(agent_key)
+    all_checks += check_display_surfaces_documented
 
     summarize(all_checks, agent_key)
   end