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

package/scripts/lib/dashboard_screen.rb

@@ -0,0 +1,40 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "report_screen"
+
+# DashboardScreen (intent 331d) - the presentation half of the dashboard
+# screen. scripts/dashboard.rb's screen_fields sources every fact (Active, In
+# delivery, Delivered, Roadmap, Sessions, Changed, the two capped row lists)
+# through the same helpers report-screen and DaySummary already use, turning
+# a missing source into "not recorded" or "none" before it ever reaches
+# here; this module carries no data-sourcing logic of its own, only layout,
+# exactly like ReportScreen.render_state and IntentScreen.render do for
+# their own screens.
+module DashboardScreen
+  module_function
+
+  TEMPLATE_PATH = File.expand_path("../../templates/dashboard-screen.md", __dir__)
+
+  def render(fields, template: nil)
+    out = (template || File.read(TEMPLATE_PATH)).dup
+    out = out.gsub("{{scope}}", fields.fetch(:scope).to_s)
+    out = out.gsub("{{active}}", fields.fetch(:active).to_s)
+    out = out.gsub("{{in_delivery}}", fields.fetch(:in_delivery).to_s)
+    out = out.gsub("{{delivered}}", fields.fetch(:delivered).to_s)
+    out = out.gsub("{{roadmap}}", fields.fetch(:roadmap).to_s)
+    out = out.gsub("{{sessions}}", fields.fetch(:sessions).to_s)
+    out = out.gsub("{{changed}}", fields.fetch(:changed).to_s)
+    out = out.gsub("{{where_we_are.rows}}", where_we_are_rows(fields.fetch(:where_we_are, [])))
+    out = out.gsub("{{where_we_go_next.rows}}", where_we_go_next_rows(fields.fetch(:where_we_go_next, [])))
+    ReportScreen.fit_screen(out.gsub(/\n{3,}/, "\n\n"))
+  end
+
+  def where_we_are_rows(rows)
+    rows.map { |r| "| #{r[:graph_id]} | #{r[:intent]} | #{r[:stage]} | #{r[:progress]} | #{r[:lead]} |" }.join("\n")
+  end
+
+  def where_we_go_next_rows(rows)
+    rows.map { |r| "| #{r[:rank]} | #{r[:graph_id]} | #{r[:intent]} | #{r[:reason]} |" }.join("\n")
+  end
+end

package/scripts/lib/doctor_core.rb

@@ -91,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
@@ -1245,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/hook_replay.rb

@@ -0,0 +1,128 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "timeout"
+
+# HookReplay (intent 331a, T1; promoted to a production lib in 331e) - streams
+# text through a MessageDisplay launcher the way Claude Code streams an
+# assistant reply, chunk by chunk, and returns every chunk's raw stdout.
+#
+# 331a's test/support/hook_replay.rb held this as test-only code; 331e's
+# doctor `display_hook_paints` check (scripts/doctor.rb) needs the exact same
+# mechanics to replay the INSTALLED launcher for real, so the logic lives
+# here and test/support/hook_replay.rb now delegates to it (a require, not a
+# duplicate). Never require this from scripts/lib/doctor_core.rb: that file
+# is the SessionStart boot path (test/doctor_core_split_test.rb T2 pins its
+# exact require set), and the paint check that needs this lib runs only from
+# the full scripts/doctor.rb.
+module HookReplay
+  module_function
+
+  # Streams `text` through `hook_path` in fixed-size chunks. `session_id`/
+  # `message_id` default to fixed values since nothing about a replay depends
+  # on the ambient session at all.
+  #
+  # `env` (intent 331e): extra child-process environment, merged over the
+  # PLASTIC_TMP entry every call already sets (a caller's own key wins). A
+  # `nil` value unsets that variable in the child (Process.spawn's own
+  # convention) is how a caller forces NO_COLOR off regardless of the ambient
+  # environment. Default `{}` keeps every existing caller's behavior
+  # unchanged: this is an extension, not a fork.
+  #
+  # `timeout` (intent 331e): when given, bounds EACH chunk's spawn to that
+  # many seconds. A bare `Timeout.timeout` around `Open3.capture3` does not
+  # reliably bound a genuinely hanging child: capture3's own wait still
+  # blocks on Process.waitpid for the child regardless of the raised
+  # Timeout::Error (the same gotcha scripts/hook-record works around), so a
+  # timeout here spawns directly and kills the child on expiry instead.
+  # Default `nil` keeps every existing caller on the original unbounded
+  # Open3.capture3 path.
+  def replay(hook_path:, tmp_root:, text:, chunk: 40, session_id: "s-replay", message_id: "replay",
+              env: {}, timeout: nil)
+    chunks = text.scan(/.{1,#{chunk}}/m)
+    chunks = [""] if chunks.empty?
+    full_env = { "PLASTIC_TMP" => tmp_root }.merge(env)
+
+    chunks.each_with_index.map do |delta, i|
+      payload = {
+        "session_id" => session_id, "message_id" => message_id, "index" => i,
+        "final" => i == chunks.length - 1, "delta" => delta, "cwd" => tmp_root,
+        "hook_event_name" => "MessageDisplay",
+      }
+      out, err, exitstatus = run_one(hook_path, payload, full_env, tmp_root, timeout)
+      { index: i, exitstatus: exitstatus, stdout: out, stderr: err, final: payload["final"] }
+    end
+  end
+
+  def run_one(hook_path, payload, full_env, tmp_root, timeout)
+    return capture(hook_path, payload, full_env) unless timeout
+
+    run_bounded(hook_path, payload, full_env, tmp_root, timeout)
+  end
+
+  def capture(hook_path, payload, full_env)
+    out, err, status = Open3.capture3(full_env, hook_path, stdin_data: JSON.generate(payload))
+    [out, err, status.exitstatus]
+  end
+
+  # Spawn directly (never Open3.capture3) so a timeout can actually kill the
+  # child, with stdin/stdout/stderr routed through scratch files under the
+  # caller's own tmp_root, and never pipes, so a stalled or oversized write can
+  # never deadlock the read side, and never anywhere outside tmp_root, so a
+  # bounded replay carries the same "writes only under the injected tmp
+  # root" guarantee as the unbounded path.
+  def run_bounded(hook_path, payload, full_env, tmp_root, timeout)
+    token = "#{Process.pid}-#{(Time.now.to_f * 1_000_000).to_i}-#{rand(1_000_000)}"
+    in_path = File.join(tmp_root, ".hook-replay-in-#{token}")
+    out_path = File.join(tmp_root, ".hook-replay-out-#{token}")
+    err_path = File.join(tmp_root, ".hook-replay-err-#{token}")
+    File.write(in_path, JSON.generate(payload))
+
+    pid = Process.spawn(full_env, hook_path, in: in_path, out: out_path, err: err_path)
+    exitstatus =
+      begin
+        Timeout.timeout(timeout) { Process.wait(pid) }
+        $?.exitstatus
+      rescue Timeout::Error
+        kill_and_reap(pid)
+        nil # nil exitstatus is the caller's signal that this chunk timed out
+      end
+
+    out = File.exist?(out_path) ? File.read(out_path) : ""
+    err = File.exist?(err_path) ? File.read(err_path) : ""
+    [out, err, exitstatus]
+  ensure
+    [in_path, out_path, err_path].each { |p| File.delete(p) if p && File.exist?(p) }
+  end
+
+  def kill_and_reap(pid)
+    Process.kill("KILL", pid)
+  rescue StandardError
+    nil
+  ensure
+    begin
+      Process.wait(pid)
+    rescue StandardError
+      nil
+    end
+  end
+
+  # The final chunk's parsed displayContent, or nil when it emitted nothing
+  # (no envelope at all: the message never engaged).
+  def final_display_content(outs)
+    final = outs.last
+    return nil if final[:stdout].to_s.empty?
+
+    JSON.parse(final[:stdout]).dig("hookSpecificOutput", "displayContent")
+  rescue JSON::ParserError
+    nil
+  end
+
+  # True when any chunk's spawn hit its timeout (run_bounded's nil-exitstatus
+  # signal). A replay made with no `timeout:` never reports true.
+  def timed_out?(outs)
+    outs.any? { |o| o[:exitstatus].nil? }
+  end
+end

package/scripts/lib/installer_core.rb

@@ -331,12 +331,26 @@ class InstallerCore
     end
   end
 
+  # Intent 331a (D6/R7): a screen kind file (scripts/lib/screens/<kind>.rb)
+  # must reach an installed ~/.plastic the same way a new template or hook
+  # does - glob-derived, so "add a file, not a diff" is actually true for an
+  # installed Plastic, not just an in-repo one. This repo ships none yet;
+  # the glob answers {} until one exists.
+  def screen_files
+    Dir.glob(File.join(package_root, "scripts", "lib", "screens", "*.rb")).each_with_object({}) do |path, acc|
+      next unless File.file?(path)
+
+      rel = File.join("scripts", "lib", "screens", File.basename(path))
+      acc[rel] = rel
+    end
+  end
+
   # Files copied into ~/.plastic on install/update. Every verb script + the shared lib
   # must be here so the installed ~/.plastic/scripts copy is self-complete (sync-guarded
-  # by install_sync_test). The templates half is glob-derived (template_files above); the
-  # rest stays a hand-written literal.
+  # by install_sync_test). The templates and screen-kind halves are glob-derived
+  # (template_files, screen_files above); the rest stays a hand-written literal.
   def core_files
-    hand_registered_files.merge(template_files).merge(hook_files)
+    hand_registered_files.merge(template_files).merge(hook_files).merge(screen_files)
   end
 
   def hand_registered_files
@@ -423,6 +437,7 @@ class InstallerCore
       "scripts/exec-worktree" => "scripts/exec-worktree",
       "scripts/doctor.rb" => "scripts/doctor.rb",
       "scripts/lib/doctor_core.rb" => "scripts/lib/doctor_core.rb",
+      "scripts/lib/hook_replay.rb" => "scripts/lib/hook_replay.rb",
       "scripts/lib/rule_catalog.rb" => "scripts/lib/rule_catalog.rb",
       "scripts/lib/doctor_exclusions.rb" => "scripts/lib/doctor_exclusions.rb",
       "scripts/lib/doctor_session_ledger.rb" => "scripts/lib/doctor_session_ledger.rb",
@@ -454,6 +469,11 @@ class InstallerCore
       "scripts/lib/intent_screen_ansi.rb" => "scripts/lib/intent_screen_ansi.rb",
       "scripts/lib/screen_paint.rb" => "scripts/lib/screen_paint.rb",
       "scripts/lib/message_display.rb" => "scripts/lib/message_display.rb",
+      # Intent 331d (A1): scripts/dashboard.rb require_relatives this lib
+      # directly; templates/dashboard-screen.md and scripts/lib/screens/
+      # dashboard.rb are glob-derived (template_files, screen_files above)
+      # and need no entry here.
+      "scripts/lib/dashboard_screen.rb" => "scripts/lib/dashboard_screen.rb",
       "scripts/hook-message-display" => "scripts/hook-message-display",
     }
   end

package/scripts/lib/message_display.rb

@@ -46,11 +46,32 @@ require_relative "screen_paint"
 # buffered or blanked. D10 (any failure while finalizing returns the
 # buffered original, never nil, never "") and D12 (color: false never
 # buffers or blanks anything) are unchanged.
+#
+# Intent 331a: engagement is late-capable. A chunk carrying a screen opener
+# engages the message from that chunk on, whatever its own index - not only
+# chunk 0. Chunks before it pass through untouched (they already reached the
+# terminal live, via the ordinary passthrough path). The engaging chunk
+# returns the text before the opener as its displayContent and buffers the
+# opener onward at its OWN index; SCREEN now carries that index (a decimal
+# integer, not an empty marker) so the final chunk - a separate process in
+# production - knows where to start waiting and splicing (D3/D6), and so
+# NOSCREEN, no longer a final answer (D2), can be replaced once a later
+# chunk engages. A fence line immediately wrapping the opener is dropped
+# (D4): a lone fence in the engaging chunk's own prefix, and a lone closing
+# fence right after the painted region in `finalize`. Neither ever reaches
+# back into an earlier, already-displayed chunk.
 class MessageDisplay
   # 317a (A4): engagement is grammar, not identity - any screen-family
   # opener engages, with NO intent-id resolution (the roster and delay
-  # screens have none to resolve). ScreenPaint owns the full grammar.
+  # screens have none to resolve). ScreenPaint owns the full grammar. Used
+  # per LINE (331a), not only against the start of a whole delta: a chunk's
+  # own text is scanned line by line for the first line that opens a screen,
+  # wherever it falls.
   ENGAGE_RE = /\A(?:##? )?[▶✔] /.freeze
+  # 331a (D4): a lone fence line, opening (optional info string) or closing
+  # (never one), by itself on its own line.
+  FENCE_OPEN_RE = /\A```[^\n]*\z/.freeze
+  FENCE_CLOSE_RE = /\A```\z/.freeze
   BUFFER_DIR_NAME = "plastic-message-display"
   BUFFER_MAX_AGE_SECONDS = 3600
   SCREEN_FILE = "SCREEN"
@@ -114,27 +135,30 @@ class MessageDisplay
   private
 
   # Chunk 0 decides, synchronously, before anything else touches this
-  # message: recognize the marker (after leading whitespace only) AND
-  # resolve the id, both before anything is buffered or blanked (F4). Either
-  # failure writes NOSCREEN so every later chunk can decide instantly rather
-  # than waiting out its own budget for a decision that will never arrive.
+  # message: does ITS OWN delta carry an opener anywhere (331a; used to be
+  # only at the very start)? No opener writes NOSCREEN so every later chunk
+  # can decide instantly rather than waiting out its own budget for a
+  # decision that will never arrive - but NOSCREEN is no longer final (D2):
+  # a later chunk carrying an opener still replaces it.
   def handle_chunk_zero(dir, delta, _cwd, final)
-    stripped = delta.sub(/\A[ \t]+/, "")
-    unless ENGAGE_RE.match?(stripped)
+    split = split_at_opener(delta)
+    unless split
       write_noscreen(dir)
       return nil
     end
 
-    write_screen(dir)
-    write_chunk(dir, 0, delta)
-    final ? finalize_final(dir, 0) : ""
+    engage(dir, 0, split, final)
   end
 
-  # A later chunk (index > 0) never redoes chunk 0's work: it only asks
-  # whether a decision already exists, waiting for one (bounded) when it
-  # does not and the chunk looks like it could matter. The final chunk
-  # always waits for the decision regardless of its own shape.
+  # A later chunk (index > 0) tests its OWN delta for an opener FIRST,
+  # before consulting any existing decision (331a, D2): an opener engages
+  # the message whatever the current decision says, including when NOSCREEN
+  # is already on disk. Only once its own delta carries no opener does it
+  # fall back to the original decision-driven wait.
   def handle_later_chunk(dir, index, delta, final)
+    split = split_at_opener(delta)
+    return engage(dir, index, split, final) if split
+
     decision = wait_for_decision(dir, gate_delta: final ? nil : delta)
 
     return nil unless decision == :screen
@@ -143,6 +167,51 @@ class MessageDisplay
     final ? finalize_final(dir, index) : ""
   end
 
+  # Engages the message starting at THIS chunk (whatever its index): writes
+  # SCREEN carrying this chunk's index (replacing any NOSCREEN, D2/D6),
+  # buffers the opener onward at this chunk's own index, and returns the
+  # text before the opener (fence-stripped, D4) as the displayContent. When
+  # this chunk is also final, the prefix is prepended to whatever `finalize`
+  # produces (painted, or the buffered original on a fail-open) rather than
+  # dropped.
+  def engage(dir, index, split, final)
+    prefix, rest = split
+    prefix = strip_preceding_fence(prefix)
+    write_screen(dir, index)
+    remove_noscreen(dir)
+    write_chunk(dir, index, rest)
+
+    return prefix unless final
+
+    finalized = finalize_final(dir, index)
+    prefix.empty? ? finalized : "#{prefix}#{finalized}"
+  end
+
+  # Scans `delta` line by line for the first line that opens a screen
+  # (331a: an opener can fall anywhere in a chunk's own delta, not only at
+  # its start). Returns [prefix, rest] - the text before that line, and the
+  # line onward - or nil when no line in this delta engages.
+  def split_at_opener(delta)
+    lines = delta.each_line.to_a
+    idx = lines.index { |line| ENGAGE_RE.match?(line.sub(/\A[ \t]+/, "")) }
+    return nil unless idx
+
+    [lines[0...idx].join, lines[idx..].join]
+  end
+
+  # 331a (D4): a lone fence line immediately preceding the opener, inside
+  # THIS SAME chunk's own prefix, is dropped - it never reaches the screen
+  # (it would otherwise print directly above the painted block). A fence in
+  # an earlier chunk is never touched: it was already displayed, verbatim,
+  # by that earlier chunk's own return value.
+  def strip_preceding_fence(prefix)
+    lines = prefix.each_line.to_a
+    return prefix if lines.empty?
+    return prefix unless FENCE_OPEN_RE.match?(lines.last.strip)
+
+    lines[0...-1].join
+  end
+
   # Checks for an existing decision first (free) and only pays the cheap
   # shape test, then the bounded poll, when neither SCREEN nor NOSCREEN is
   # there yet. `gate_delta: nil` (the final chunk) skips the shape test
@@ -169,6 +238,20 @@ class MessageDisplay
     nil
   end
 
+  # 331a (M5a): the start index crosses process boundaries through SCREEN's
+  # own content, never in-memory state - the final chunk is routinely a
+  # SEPARATE process from the one that engaged. An empty or missing file
+  # reads back as 0 (chunk 0 engaged, today's shape, so nothing that ever
+  # wrote an empty SCREEN breaks).
+  def read_start_index(dir)
+    path = File.join(dir, SCREEN_FILE)
+    return 0 unless File.exist?(path)
+
+    File.read(path).to_i
+  rescue StandardError
+    0
+  end
+
   # Cheap, local, no file I/O: could this chunk's own delta plausibly be
   # part of an intent screen (ignoring leading whitespace)? Every chunk of
   # every ordinary prose message answers no, at zero cost.
@@ -177,28 +260,38 @@ class MessageDisplay
     stripped.empty? || stripped.start_with?("|") || stripped.start_with?("**")
   end
 
-  # The final chunk additionally waits (same budget) for every earlier chunk
-  # file to exist before it reassembles and splices. On timeout it proceeds
-  # anyway with whatever is there (matrix, lead's guard): never nil, never
-  # swallowed.
+  # The final chunk additionally waits (same budget) for every chunk file
+  # from the start index onward to exist before it reassembles and splices
+  # (331a, D3/M5: from the start index, not from 0 - chunks before the
+  # engaging one were never buffered at all, so waiting for them would only
+  # ever burn the whole budget for files that will never appear). On
+  # timeout it proceeds anyway with whatever is there (matrix, lead's
+  # guard): never nil, never swallowed.
   def finalize_final(dir, index)
-    wait_for_chunk_files(dir, index)
+    start_index = read_start_index(dir)
+    wait_for_chunk_files(dir, start_index, index)
 
     buffered = nil
     begin
-      buffered = read_buffered_chunks(dir, index)
+      buffered = read_buffered_chunks(dir, start_index, index)
       finalize(buffered, nil)
     rescue StandardError
-      buffered
+      # A read failing inside the assignment above leaves `buffered` at its
+      # nil default (the assignment never completes), which the review pass
+      # caught: D8/D10 promise the buffered original on any finalize
+      # failure, never nil, once chunks were blanked. `||=` covers exactly
+      # that gap without touching the ordinary case (buffered already holds
+      # the real chunks read before `finalize` itself raised).
+      buffered ||= ""
     ensure
       FileUtils.rm_rf(dir)
     end
   end
 
-  def wait_for_chunk_files(dir, index)
-    return if index <= 0
+  def wait_for_chunk_files(dir, start_index, index)
+    return if index <= start_index
 
-    needed = (0...index).map(&:to_s)
+    needed = (start_index...index).map(&:to_s)
     max_polls_for_budget.times do
       return if needed.all? { |n| File.exist?(File.join(dir, n)) }
 
@@ -212,11 +305,12 @@ class MessageDisplay
     (@wait_ms / @poll_ms.to_f).ceil
   end
 
-  # Whatever chunk files exist, in index order, concatenated -- gaps (a
-  # chunk that never arrived, or arrived too late) are skipped rather than
-  # blocking reassembly (lead's guard: never return nothing).
-  def read_buffered_chunks(dir, index)
-    (0..index).filter_map do |i|
+  # Whatever chunk files exist FROM THE START INDEX onward, in index order,
+  # concatenated -- gaps (a chunk that never arrived, or arrived too late)
+  # are skipped rather than blocking reassembly (lead's guard: never return
+  # nothing).
+  def read_buffered_chunks(dir, start_index, index)
+    (start_index..index).filter_map do |i|
       path = File.join(dir, i.to_s)
       File.exist?(path) ? File.read(path) : nil
     end.join
@@ -239,11 +333,22 @@ class MessageDisplay
     start = lines.index { |l| ScreenPaint.classify(l) == :opener }
     return buffered unless start
 
-    stop = ScreenPaint.region_end(lines, start)
-    painted = ScreenPaint.paint(lines[start...stop].join, color: true, markdown_safe: true)
+    region_stop = ScreenPaint.region_end(lines, start)
+    painted = ScreenPaint.paint(lines[start...region_stop].join, color: true, markdown_safe: true)
     return buffered unless painted
 
-    suffix = lines[stop..].to_a.join.sub(/\A\n+/, "")
+    # 331a (D4): a lone CLOSING fence immediately after the painted region is
+    # dropped - never the painting boundary itself (region_stop, used above,
+    # is untouched), only where the suffix starts. An unrelated fenced code
+    # block further down, with prose or a blank line between it and the
+    # region, is never adjacent, so it always survives verbatim (M8b); a
+    # closing fence never carries an info string, so an adjacent OPENING
+    # fence of a real code block (which usually does) is never mistaken for
+    # it either.
+    suffix_start = region_stop
+    suffix_start += 1 if suffix_start < lines.length && FENCE_CLOSE_RE.match?(lines[suffix_start].strip)
+
+    suffix = lines[suffix_start..].to_a.join.sub(/\A\n+/, "")
     out = +"#{lines[0...start].join}#{painted.rstrip}\n"
     out << "\n#{suffix}" unless suffix.empty?
     out
@@ -253,17 +358,26 @@ class MessageDisplay
     atomic_write(File.join(dir, index.to_s), delta)
   end
 
-  # IntentScreen/IntentScreenAnsi's store_root: is the TIER root (what HOLDS
-  # store/ — e.g. .../projects/<slug> or plastic_home itself), never the
-  # store/ directory itself; resolve_intent_dir's `root:` is already that.
-  def write_screen(dir)
-    atomic_write(File.join(dir, SCREEN_FILE), "")
+  # SCREEN's content is the engaging chunk's own index, as a decimal integer
+  # (331a, D6) - read back by `read_start_index` so the final chunk (a
+  # separate process, in production) knows where to start waiting and
+  # splicing, and so `finalize_final` never touches chunks that were passed
+  # through untouched before engagement.
+  def write_screen(dir, index)
+    atomic_write(File.join(dir, SCREEN_FILE), "#{index}\n")
   end
 
   def write_noscreen(dir)
     atomic_write(File.join(dir, NOSCREEN_FILE), "")
   end
 
+  # 331a (D2/D6): NOSCREEN is no longer a final answer - a later chunk that
+  # engages replaces it with SCREEN and, for safety, removes NOSCREEN so a
+  # stale marker can never be read back once the real decision exists.
+  def remove_noscreen(dir)
+    FileUtils.rm_f(File.join(dir, NOSCREEN_FILE))
+  end
+
   def atomic_write(path, content)
     FileUtils.mkdir_p(File.dirname(path))
     tmp_path = "#{path}.tmp#{Process.pid}-#{rand(1_000_000)}"