@zalom/plastic 2.0.0-alpha.12 → 2.0.0-alpha.14

package/hooks/message-display

@@ -57,8 +57,18 @@ if [ "$is_index_zero" = 1 ]; then
     *'"delta":"#'*|*'"delta": "#'*) handoff=1 ;;
     *'"delta":"▶'*|*'"delta": "▶'*) handoff=1 ;;
     *'"delta":"✔'*|*'"delta": "✔'*) handoff=1 ;;
-    *'"delta":"▶'*|*'"delta": "▶'*) handoff=1 ;;
-    *'"delta":"✔'*|*'"delta": "✔'*) handoff=1 ;;
+  esac
+  # 331a review fix (M12e): chunk 0 is not exempt from D5 either. The
+  # intent's own flagship shape -- a lead-in sentence and the opener in the
+  # SAME first chunk -- never starts with "#", "▶", or "✔", so the arm
+  # above alone never sees it. Joins it with the identical opener-anywhere
+  # globs used for a later chunk (M12a) rather than replacing anything:
+  # same reasoning as the comment at that site applies verbatim here.
+  case $INPUT in
+    *'"delta":"'*'▶'*|*'"delta": "'*'▶'*) handoff=1 ;;
+    *'"delta":"'*'✔'*|*'"delta": "'*'✔'*) handoff=1 ;;
+    *'"delta":"'*'\u25b6'*|*'"delta": "'*'\u25b6'*) handoff=1 ;;
+    *'"delta":"'*'\u2714'*|*'"delta": "'*'\u2714'*) handoff=1 ;;
   esac
 else
   # A later chunk: hand off when this message's directory already exists
@@ -74,6 +84,25 @@ else
     *'"delta":""'*|*'"delta": ""'*) handoff=1 ;;
     *'"delta":"\n"'*|*'"delta": "\n"'*) handoff=1 ;;
   esac
+  # 331a (D5): the hook engages anywhere. An opener can now fall ANYWHERE
+  # inside a later chunk's own delta, not only at its start (the shape
+  # tests just above), so these globs search the delta value rather than
+  # anchor to its opening quote. Still anchored to the "delta":" key itself
+  # (never dropped, matrix M12d) so an ordinary field elsewhere in the
+  # payload can never be mistaken for the delta's own text; within that,
+  # every shipped opener (## ▶, ## ✔, ▶ In delivery, ✔ + digit) contains a
+  # bare ▶ or ✔, so matching the bare glyph anywhere covers all four at
+  # once. Prose that merely shapes like an opener still hands off this way
+  # (an accepted over-match: Ruby's own grammar is the final, stricter
+  # arbiter and fails open on anything that is not a real one). Raw glyph
+  # and \u-escaped forms both count, since the encoder's choice is not ours
+  # to predict.
+  case $INPUT in
+    *'"delta":"'*'▶'*|*'"delta": "'*'▶'*) handoff=1 ;;
+    *'"delta":"'*'✔'*|*'"delta": "'*'✔'*) handoff=1 ;;
+    *'"delta":"'*'\u25b6'*|*'"delta": "'*'\u25b6'*) handoff=1 ;;
+    *'"delta":"'*'\u2714'*|*'"delta": "'*'\u2714'*) handoff=1 ;;
+  esac
 fi
 
 [ "$handoff" = 1 ] || exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.12",
+  "version": "2.0.0-alpha.14",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/dashboard.rb

@@ -27,6 +27,18 @@ require "date"
 require_relative "doctor"
 require_relative "lib/savepoint"
 require_relative "lib/lock"
+require_relative "lib/dashboard_screen"
+require_relative "lib/intent_screen"
+require_relative "lib/report_screen"
+require_relative "lib/roadmap_queue"
+require_relative "lib/day_summary"
+require_relative "lib/screen_paint"
+
+# Intent 331a (D6/R8): every caller-added screen kind file registers itself on
+# load, so this glob is the only wiring a new kind needs (scripts/report-screen:42
+# does the identical glob for the same reason). Sorted for a deterministic load
+# order; tolerates the directory being absent or empty.
+Dir.glob(File.join(__dir__, "lib", "screens", "*.rb")).sort.each { |f| require_relative f }
 
 PLASTIC_HOME = ENV.fetch("PLASTIC_HOME") { File.join(Dir.home, ".plastic") }
 
@@ -670,15 +682,10 @@ end
 # recent_delivery_summary (D1 fix) uses this twice: once per intent label, so a
 # paragraph-long `intent` field collapses to a short name, and once on the fully assembled
 # summary string, the hard budget cap that holds no matter how the per-label math adds up.
+# Intent 331f: the one implementation now lives on ReportScreen; this delegates so dashboard.rb
+# and every ReportScreen render entry point share it.
 def truncate_on_word_boundary(text, max_chars)
-  t = text.to_s
-  return t if t.length <= max_chars
-  ellipsis = "…"
-  limit = [max_chars - ellipsis.length, 0].max
-  slice = t[0, limit]
-  cut = slice.rindex(/\s/)
-  slice = slice[0, cut] if cut && cut.positive?
-  "#{slice.rstrip}#{ellipsis}"
+  ReportScreen.truncate_on_word_boundary(text, max_chars)
 end
 
 # D3 fix (intent 202 gate review): completion dates only carry day granularity, and many
@@ -969,6 +976,211 @@ def render_json(records, scope_label)
   }
 end
 
+# ---------------------------------------------------------------------------
+# Screen renderer (intent 331d) - dashboard.rb continue|project <slug> --screen.
+#
+# Sources every fact through the same helpers report-screen and DaySummary
+# already use (Resolved contract, ACTION_1): a missing source prints "not
+# recorded" or "none", never a guess or a crash (R1). The classification
+# pipeline above (classify, rank_key, actionable?, QUADRANTS, disposition_of)
+# is read here, never edited: the screen is a new renderer over the same
+# records (D3), so every count and rank matches what --json already reports
+# for the identical scope.
+# ---------------------------------------------------------------------------
+
+SCREEN_ACTIVE_CAP = 8
+SCREEN_NEXT_CAP = 6
+SCREEN_NOT_RECORDED = "not recorded"
+
+def screen_scope_slug(scope)
+  scope.sub(/\Aproject:/, "")
+end
+
+# Tier root: PLASTIC_HOME for "global", PLASTIC_HOME/projects/<slug> for
+# "project:<slug>" (Resolved contract) - the same tier scripts/lib/qmd_sync.rb
+# already derives from a store path. Global's own roadmaps/INDEX.md sit
+# directly under PLASTIC_HOME, with no intervening "store" segment.
+def screen_tier_root(plastic_home, scope)
+  return plastic_home if scope == "global"
+  File.join(plastic_home, "projects", screen_scope_slug(scope))
+end
+
+# "global" spans every store (the same aggregate render_continue and --json's
+# continue-mode subset already read); a project scope narrows to its own
+# records. Never a project-only helper on the unscoped path (D10).
+def screen_scoped_records(records, scope)
+  return records if scope == "global"
+  records.select { |r| r[:scope] == scope }
+end
+
+def screen_active_count(scoped)
+  scoped.count { |r| r[:status] == "active" }
+end
+
+# D2: a stale or absent lock never counts as delivering.
+def screen_in_delivery_count(scoped, now:)
+  scoped.count do |r|
+    r[:status] == "active" && Lock.who(r[:intent_dir], now: now)["state"] == "fresh"
+  end
+end
+
+# D3: completed_on (the INDEX.md completion date) is the source of truth,
+# rec[:done_at] (the savepoint's own Done timestamp) the fallback when a
+# completed intent has no dated INDEX entry yet. `created` is never read.
+def screen_completion_date(rec)
+  raw = rec[:completed_on].to_s
+  raw = rec[:done_at].to_s if raw.empty?
+  return nil if raw.empty?
+  begin
+    Date.parse(raw)
+  rescue ArgumentError, TypeError
+    nil
+  end
+end
+
+def screen_delivered_count(scoped, now:)
+  today_date = now.to_date
+  scoped.count do |r|
+    next false unless r[:status] == "completed"
+    date = screen_completion_date(r)
+    next false unless date
+    diff = (today_date - date).to_i
+    diff >= 0 && diff <= 7
+  end
+end
+
+# "none" on state none/tie/exhausted or a missing roadmaps dir (R1, D4); the
+# live frontier otherwise (D17). RoadmapQueue itself tolerates an absent
+# directory (Dir.exist? guard), so this never crashes on a bare tier.
+def screen_roadmap_field(plastic_home, scope, now:)
+  tier = screen_tier_root(plastic_home, scope)
+  reader = RoadmapQueue.new(roadmaps_dir: File.join(tier, "roadmaps"),
+                             index_path: File.join(tier, "INDEX.md"), now: now)
+  payload = reader.which
+  return "none" if %w[none tie exhausted].include?(payload["state"])
+  "#{payload['roadmap']} · #{payload['frontier_wave']}"
+end
+
+# Sessions are global, never per-project (Resolved contract): always the
+# PLASTIC_HOME/store tmp root, and `session: nil` (A6) so the calling
+# session's own live heartbeat counts rather than being excluded as "self".
+def screen_sessions_count(plastic_home, now:)
+  store = File.join(plastic_home, "store")
+  DaySummary.active_sessions(store, nil, now: now, ttl: DaySummary::HEARTBEAT_TTL).size
+end
+
+def screen_changed_field(scoped)
+  latest = scoped.map { |r| r[:last_accessed_at].to_s }.reject(&:empty?).max
+  return SCREEN_NOT_RECORDED unless latest
+  t = begin
+    Time.parse(latest)
+  rescue ArgumentError, TypeError
+    nil
+  end
+  return SCREEN_NOT_RECORDED unless t
+  t.utc.strftime("%Y-%m-%d %H:%M UTC")
+end
+
+# D6, intent 331f: the one Lead freshness rule every screen shares - fresh prints
+# "agent · key", a stale lock prints "stale · N min" (never "not recorded" or a bare "idle",
+# which would either hide the staleness or contradict a live In-delivery count with a dead
+# lead), and no lock (or one that will not read) prints "idle".
+def screen_lead_field(rec, now:)
+  ReportScreen.lead_cell(rec[:intent_dir], now: now)
+end
+
+# D3 (331d1): the owner ruled no rendered row exceeds 115 visible columns.
+# The bound is on the WHOLE pipe-delimited row, not on one cell, so the
+# Intent cell gets whatever the other cells leave it. A cell short enough on
+# its own still drifts the row past the bound once the bar, the lead and the
+# scaffolding are added, which is the failure this measures away.
+SCREEN_ROW_MAX_COLUMNS = 115
+
+# D2 (331d1): the Intent cell carries the intent line up to but not including
+# its first colon. A Plastic intent line opens with a short name and then
+# explains itself after a colon, so the lead IS the name; a line with no
+# colon is already a name and passes through whole. Escaping happens here, so
+# the budget below measures what actually reaches the row.
+def screen_intent_title(rec)
+  # D8: one colon rule for every screen, on ReportScreen. `max:` is the whole line here
+  # because screen_fit_intent does this cell's own width budgeting a moment later.
+  cell(ReportScreen.title_before_colon(rec[:intent], max: rec[:intent].to_s.length + 1))
+end
+
+# The Intent cell fitted to what the row has left. `others` are the already
+# rendered sibling cells; the scaffolding is the leading "| ", a " | " between
+# every pair of cells, and the trailing " |". Intent 331f1: the one implementation now lives
+# on ReportScreen (fit_row_cell), measured in DISPLAY columns rather than String#length - an
+# `others` cell carrying a progress bar costs two columns per glyph, not one (RC1) - so
+# roadmap_state_entries_table's own Intent cell spends the same budget by the same rule.
+def screen_fit_intent(title, others)
+  ReportScreen.fit_row_cell(title, others, max: SCREEN_ROW_MAX_COLUMNS)
+end
+
+# D6: last_accessed_at descending, then id, capped at SCREEN_ACTIVE_CAP.
+def screen_where_we_are(scoped, now:)
+  active = scoped.select { |r| r[:status] == "active" }
+  ordered = active.sort_by { |r| [invert_ts(r[:last_accessed_at]), r[:id]] }
+  ordered.first(SCREEN_ACTIVE_CAP).map do |r|
+    items = IntentScreen.checklist_items(r[:intent_dir])
+    progress = IntentScreen.progress_fields(items)
+    graph_id = r[:id].to_s
+    stage = r[:lifecycle].to_s.capitalize
+    bar = "#{progress['progress.bar']} #{progress['progress.done']} / #{progress['progress.total']}"
+    lead = screen_lead_field(r, now: now)
+    {
+      graph_id: graph_id,
+      intent: screen_fit_intent(screen_intent_title(r), [graph_id, stage, bar, lead]),
+      stage: stage,
+      progress: bar,
+      lead: lead,
+    }
+  end
+end
+
+# A2: the exact pool render_json's dispatchable_queue ranks - actionable?
+# records, rank_key order, filtered to disposition defer/research (D12
+# excludes drive/triage). Rank is that queue's own 1-based position, so a
+# capped display row's rank always agrees with the uncapped --json contract.
+def screen_dispatchable_pool(scope_records)
+  ranked = scope_records.select { |r| actionable?(r) }.sort_by { |r| rank_key(r) }
+  ranked.select { |r| %w[defer research].include?(r[:disposition]) }
+end
+
+def screen_where_we_go_next(scope_records)
+  pool = screen_dispatchable_pool(scope_records)
+  pool.each_with_index.map do |r, i|
+    rank = i + 1
+    graph_id = r[:id].to_s
+    reason = r[:quadrant].to_s
+    {
+      rank: rank,
+      graph_id: graph_id,
+      intent: screen_fit_intent(screen_intent_title(r), [rank.to_s, graph_id, reason]),
+      reason: reason,
+    }
+  end.first(SCREEN_NEXT_CAP)
+end
+
+def screen_fields(records, scope, plastic_home:, now: Time.now)
+  scoped = screen_scoped_records(records, scope)
+  {
+    scope: scope,
+    active: screen_active_count(scoped),
+    in_delivery: screen_in_delivery_count(scoped, now: now),
+    delivered: screen_delivered_count(scoped, now: now),
+    roadmap: screen_roadmap_field(plastic_home, scope, now: now),
+    sessions: screen_sessions_count(plastic_home, now: now),
+    changed: screen_changed_field(scoped),
+    where_we_are: screen_where_we_are(scoped, now: now),
+    where_we_go_next: screen_where_we_go_next(scoped),
+  }
+end
+
+def render_screen(records, scope, plastic_home: PLASTIC_HOME, now: Time.now)
+  DashboardScreen.render(screen_fields(records, scope, plastic_home: plastic_home, now: now))
+end
+
 # ---------------------------------------------------------------------------
 # CLI
 # ---------------------------------------------------------------------------
@@ -997,6 +1209,8 @@ def main(argv)
   json = argv.delete("--json")
   data = argv.delete("--data")
   plain = argv.delete("--plain")
+  screen = argv.delete("--screen")
+  ansi = argv.delete("--ansi")
   all = argv.delete("--all")
   limit_active = extract_flag_value(argv, "--limit-active")
   limit_next = extract_flag_value(argv, "--limit-next")
@@ -1047,6 +1261,22 @@ def main(argv)
     return 0
   end
 
+  if screen
+    if mode == "project" && (slug.nil? || slug.empty?)
+      warn "usage: dashboard.rb project <slug> --screen"
+      return 2
+    end
+    scope = mode == "project" ? "project:#{slug}" : "global"
+    text = render_screen(records, scope, plastic_home: PLASTIC_HOME, now: Time.now)
+    # A4: the identical capability guard scripts/report-screen:161 applies -
+    # NO_COLOR always wins to plain; a non-tty stdout stays plain unless the
+    # PLASTIC_FORCE_COLOR test seam is set.
+    ansi_enabled = ansi && ENV["NO_COLOR"].to_s.empty? &&
+                   ($stdout.tty? || ENV["PLASTIC_FORCE_COLOR"] == "1")
+    print(ansi_enabled ? (ScreenPaint.paint(text, color: true) || text) : text)
+    return 0
+  end
+
   case mode
   when "continue" then print render_continue(records)
   when "project"

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"
@@ -47,6 +52,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 ---
@@ -1162,11 +1174,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 six checks, four
-  # FAIL-severity, two 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), and
+  # 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.
+  # 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
@@ -1189,6 +1202,7 @@ end
       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),
     ]
@@ -1294,6 +1308,41 @@ end
     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)
@@ -2431,6 +2480,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)
@@ -2449,6 +2732,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