@zalom/plastic 2.0.0-alpha.5 → 2.0.0-alpha.7

package/hooks/hooks.json

@@ -64,6 +64,18 @@
           }
         ]
       }
+    ],
+    "MessageDisplay": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" message-display",
+            "statusMessage": ""
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/message-display

@@ -0,0 +1,73 @@
+#!/bin/bash
+# hooks/message-display (intent 316a, O6, round 3 concurrency fix): the
+# MessageDisplay launcher. Fires on every streamed chunk of every assistant
+# message (D11), so the common case — an ordinary chunk of an ordinary
+# message — must decide with shell builtins alone and fork nothing. Only a
+# candidate message hands off to Ruby (scripts/hook-message-display), which
+# is the one place allowed to do real work.
+#
+# No command substitution, no backticks, no sed/jq/cat: case, [, parameter
+# expansion and printf are all builtins. Deliberately does NOT copy hooks/
+# capture's SCRIPT_DIR-via-subshell pattern (cd into dirname of $0, inside a
+# command substitution, then pwd) — that forks a subshell on every single
+# invocation, which is exactly the cost this hook cannot carry.
+#
+# A live run under a real pty found Claude Code fires these chunk processes
+# CONCURRENTLY: a chunk with index > 0 can arrive, and be judged here,
+# before chunk 0 ever runs. The OLD hand-off test — "does a buffer already
+# exist for this message" — answered no in that race and silently dropped
+# the chunk before Ruby ever saw it, no matter what MessageDisplay's own
+# (correct) polling logic would have done. So a later chunk is now also
+# handed off when its OWN delta looks like it could be part of a screen
+# (leading "|" or "**Steps**", or blank — the same cheap test Ruby itself
+# uses to decide whether a wait is worth paying for), and the final chunk is
+# ALWAYS handed off, whatever it looks like, since it is the one that must
+# not race. Ruby is the one place that actually waits (bounded, injectable
+# for tests); this script only ever decides once, fast, and never sleeps.
+#
+# Claude adapter: Claude Code only; the core is harness-agnostic.
+IFS= read -r -d '' INPUT          # returns 1 at EOF: do NOT set -e
+case $INPUT in *'"message_id"'*) ;; *) exit 0 ;; esac
+rest=${INPUT#*\"message_id\"}; rest=${rest#*\"}; mid=${rest%%\"*}
+rest=${INPUT#*\"session_id\"}; rest=${rest#*\"}; sid=${rest%%\"*}
+
+SCRIPT_DIR=${0%/*}
+TMP_ROOT=${PLASTIC_TMP:-${TMPDIR:-/tmp}}
+export PLASTIC_TMP="$TMP_ROOT"
+MSGDIR="$TMP_ROOT/plastic-message-display/$sid/$mid"
+
+is_index_zero=0
+case $INPUT in *'"index":0'*|*'"index": 0'*) is_index_zero=1 ;; esac
+
+is_final=0
+case $INPUT in *'"final":true'*|*'"final": true'*) is_final=1 ;; esac
+
+handoff=0
+if [ "$is_index_zero" = 1 ]; then
+  # Chunk 0 decides synchronously; a bare "#" first delta, in either JSON
+  # spacing, is the only shape that can possibly open a screen. Must be a
+  # single "#", not "##" — a real screen's own first delta can be as short
+  # as "## " — a "##" glob would filter out exactly the message this hook
+  # exists to recognize.
+  case $INPUT in
+    *'"delta":"#'*|*'"delta": "#'*) handoff=1 ;;
+  esac
+else
+  # A later chunk: hand off when this message's directory already exists
+  # (chunk 0 already left a decision or a chunk file), when this chunk is
+  # final (it must always be checked, whatever it looks like), or when its
+  # own delta is shaped like part of a screen — a Markdown table row, the
+  # "**Steps**" heading, or a blank line, in either JSON spacing.
+  [ -d "$MSGDIR" ] && handoff=1
+  [ "$is_final" = 1 ] && handoff=1
+  case $INPUT in
+    *'"delta":"|'*|*'"delta": "|'*) handoff=1 ;;
+    *'"delta":"**Steps**'*|*'"delta": "**Steps**'*) handoff=1 ;;
+    *'"delta":""'*|*'"delta": ""'*) handoff=1 ;;
+    *'"delta":"\n"'*|*'"delta": "\n"'*) handoff=1 ;;
+  esac
+fi
+
+[ "$handoff" = 1 ] || exit 0
+
+printf '%s' "$INPUT" | env -u RUBYOPT ruby "$SCRIPT_DIR/../scripts/hook-message-display"

package/package.json

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

package/scripts/hook-message-display

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# hook-message-display (intent 316a, O4): the MessageDisplay hook CLI. Reads
+# the harness's per-chunk JSON payload from stdin, hands it to MessageDisplay
+# (the pure handler class), and prints the hookSpecificOutput envelope when a
+# String comes back. Always exits 0, whatever happens — a raised exception
+# here must never surface as a non-zero exit or stray stderr on an ordinary
+# chunk of an ordinary message (matrix 31).
+#
+# This script is the one place in the O4 stack allowed to read ENV, the
+# clock, or Dir.tmpdir: MessageDisplay itself takes tmp_root/plastic_home/
+# color/now as constructor arguments and touches none of them directly.
+#
+# Claude adapter: Claude Code only; the core is harness-agnostic.
+
+require "json"
+require "time"
+require "tmpdir"
+require "yaml"
+require_relative "lib/message_display"
+
+def color_enabled?(plastic_home)
+  return false unless ENV["NO_COLOR"].to_s.empty?
+
+  cfg_path = File.join(plastic_home, "config.yml")
+  return true unless File.exist?(cfg_path)
+
+  cfg = YAML.safe_load(File.read(cfg_path))
+  display = cfg.is_a?(Hash) ? cfg["display"] : nil
+  return true unless display.is_a?(Hash)
+
+  display.fetch("ansi_screen", true) != false
+rescue StandardError
+  true
+end
+
+begin
+  raw = $stdin.tty? ? "" : $stdin.read
+  payload = raw.to_s.strip.empty? ? nil : JSON.parse(raw)
+
+  if payload.is_a?(Hash)
+    tmp_root = ENV["PLASTIC_TMP"].to_s.empty? ? Dir.tmpdir : ENV["PLASTIC_TMP"]
+    plastic_home = File.expand_path(ENV["PLASTIC_HOME"] || "~/.plastic")
+
+    handler = MessageDisplay.new(
+      tmp_root: tmp_root,
+      plastic_home: plastic_home,
+      color: color_enabled?(plastic_home),
+      now: Time.now,
+    )
+    result = handler.handle(payload)
+
+    if result.is_a?(String)
+      puts JSON.generate(
+        "hookSpecificOutput" => {
+          "hookEventName" => "MessageDisplay",
+          "displayContent" => result,
+        },
+      )
+    end
+  end
+rescue StandardError
+  nil
+end
+exit 0

package/scripts/intent-screen

@@ -8,18 +8,31 @@
 # the close; it never edits the numbers.
 #
 # Usage:
-#   intent-screen <intent_dir> [--template <path>]
+#   intent-screen <intent_dir> [--template <path>] [--ansi]
 #
 # The store root is the directory two levels above the intent (<root>/store/<id--slug>);
 # the template defaults to templates/intent-screen.md next to this script's dir,
 # in-repo (<repo>/scripts -> <repo>/templates) and installed (~/.plastic/scripts ->
 # ~/.plastic/templates) alike.
 #
+# --ansi (intent 316a, O3): emits scripts/lib/intent_screen_ansi.rb's styled
+# truecolor block instead of the plain Markdown screen. Plain stays the
+# default with no flag. Two things force plain even WITH --ansi (D18): NO_COLOR
+# present in the environment (any value counts), or a non-TTY stdout — the
+# true default form of D2, not IntentScreenAnsi's own uncoloured layout. The
+# library (scripts/lib/intent_screen_ansi.rb) is pure and never reads either;
+# this script is the one place allowed to.
+#
 # Exit codes:
 #   0 - the screen is on stdout
 #   2 - usage error, or the path is not an intent directory (one line on stderr)
+#
+# Harness-agnostic core: no harness assumption lives here. This script holds
+# the plain/ANSI selection (intent 316a1, D3) and belongs to the same
+# harness-agnostic core as lib/intent_screen.rb and lib/intent_screen_ansi.rb.
 
 require_relative "lib/intent_screen"
+require_relative "lib/intent_screen_ansi"
 
 def usage_abort(message)
   warn "intent-screen: #{message}"
@@ -28,18 +41,21 @@ end
 
 args = ARGV.dup
 template_path = nil
+ansi = false
 positional = []
 while (arg = args.shift)
   case arg
   when "--template"
     template_path = args.shift or usage_abort("--template needs a path")
+  when "--ansi"
+    ansi = true
   else
     usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
     positional << arg
   end
 end
 
-usage_abort("usage: intent-screen <intent_dir> [--template <path>]") unless positional.length == 1
+usage_abort("usage: intent-screen <intent_dir> [--template <path>] [--ansi]") unless positional.length == 1
 intent_dir = File.expand_path(positional.first)
 usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
 
@@ -47,6 +63,15 @@ store_root = File.expand_path("../..", intent_dir)
 template_path ||= File.expand_path("../templates/intent-screen.md", __dir__)
 usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
 
-$stdout.write IntentScreen.render(intent_dir: intent_dir, store_root: store_root,
-                                  template: File.read(template_path))
+plain = -> { IntentScreen.render(intent_dir: intent_dir, store_root: store_root, template: File.read(template_path)) }
+
+degrade_to_plain = ENV.key?("NO_COLOR") || !$stdout.tty?
+
+$stdout.write(
+  if ansi && !degrade_to_plain
+    IntentScreenAnsi.render(intent_dir: intent_dir, store_root: store_root, color: true)
+  else
+    plain.call
+  end
+)
 exit 0

package/scripts/lib/doctor_core.rb

@@ -27,9 +27,10 @@ class Doctor
     "hermes" => { name: "Hermes",      dir: File.join(Dir.home, ".hermes") },
   }.freeze
 
-  # The Claude events hooks_registered expects in settings.json: the five-event map of
-  # cut-inventory 3b (intent 309 added SessionEnd, registered for close since intent 301).
-  CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit SessionEnd].freeze
+  # The Claude events hooks_registered expects in settings.json: the six-event map of
+  # cut-inventory 3b (intent 309 added SessionEnd, registered for close since intent 301;
+  # intent 316a added MessageDisplay, registered for message-display, Claude only).
+  CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit SessionEnd MessageDisplay].freeze
 
   # Launchers the installer places in the agent's hooks dir that are NOT hooks
   # (intent 204): plastic-statusline is the settings["statusLine"] command, wired

package/scripts/lib/hook_registry.rb

@@ -54,6 +54,20 @@ module HookRegistry
           { "name" => "capture", "status" => "Capturing prompt into the session ledger..." },
         ] },
       ],
+      # This entry belongs to the Claude adapter half of Plastic's
+      # harness-agnostic-core / Claude-adapter split (intent 316a1, D3
+      # supersedes 316a's D6): MessageDisplay is not one of
+      # CODEX_LIVE_STATE_EVENTS, so codex_hooks_json (below) never picks it
+      # up; codex_hook_names stays exactly what it was (pinned by
+      # test/hook_registry_test.rb:82 and :110-111). Fires on every streamed
+      # chunk of every assistant message (D11); the launcher (hooks/message-
+      # display) decides with shell builtins and forks nothing on the common
+      # case, execing Ruby only for a candidate message.
+      "MessageDisplay" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "message-display", "status" => "" },
+        ] },
+      ],
     }
   end
 

package/scripts/lib/installer_core.rb

@@ -443,6 +443,14 @@ class InstallerCore
       "scripts/lib/intent_screen.rb" => "scripts/lib/intent_screen.rb",
       "scripts/intent-screen" => "scripts/intent-screen",
       "scripts/hook-savepoint" => "scripts/hook-savepoint",
+      # Intent 316a: hooks/* only glob-copies scripts/*, never scripts/lib/*
+      # (see hook_files above), so the two lib files a require_relative
+      # between themselves are unguarded there — these three literal
+      # entries are their only protection (test/install_sync_test.rb:23-29
+      # greps installer_core.rb's own source text for "scripts/<name>").
+      "scripts/lib/intent_screen_ansi.rb" => "scripts/lib/intent_screen_ansi.rb",
+      "scripts/lib/message_display.rb" => "scripts/lib/message_display.rb",
+      "scripts/hook-message-display" => "scripts/hook-message-display",
     }
   end
 

package/scripts/lib/intent_screen.rb

@@ -1,9 +1,19 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 # IntentScreen (intent 316) - fills templates/intent-screen.md from one intent's
-# record: the intent file, the tier's INDEX.md, savepoint.md, and checklist.md.
+# record: the intent file, the tier's INDEX.md, savepoint.md and checklist.md.
 # Every number on the screen comes from here so the session never writes one by
 # eye. Pure: explicit paths in, a Markdown string out; no ENV, no Dir.pwd.
+#
+# Intent 316a fixed three defects the field code inherited into both the plain
+# renderer and the ANSI renderer (scripts/lib/intent_screen_ansi.rb): the
+# Insight row dumping a multi-clause remainder into the note column, an empty
+# "What this means" heading rendering bold with nothing under it, and step
+# text cut mid-sentence. `step_text`, `insight_fields` and `next_fields` are
+# public so the ANSI renderer reuses the exact same trims (D3) rather than
+# re-deriving them and drifting.
+#
+# Harness-agnostic core: no harness assumption lives here.
 module IntentScreen
   BAR_WIDTH = 20
   ON = "█"
@@ -11,10 +21,22 @@ module IntentScreen
   PLACEHOLDER_SENTINEL = "<!-- plastic:placeholder -->"
   SECTIONS = %w[Active Future Completed Abandoned].freeze
   ITEM_RE = /^\s*- \[([ xX])\]\s+(.*)$/
-  STEP_PREFIX_RE = /\A(?:Step|S)\s*\d+\s*[-:·]\s*/i
+  # Em dash and en dash added (intent 316a O1e): a checklist item written
+  # "S1 — text" (the em dash every checklist this intent writes, and the one a
+  # reviewer reads, uses) kept its prefix under the old character class and
+  # rendered "S1  [ open ]  S1 — text" on screen.
+  STEP_PREFIX_RE = /\A(?:Step|S)\s*\d+\s*[-:·—–]\s*/i
   INSIGHT_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s+·\s+\S+\s+·\s+.+?\s+—\s+(.+)\z/
   SAVEPOINT_RE = /\A(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ)\s{2,}(\S+)\s{2,}(.+?)\s*\z/
 
+  # Word-boundary truncation caps (intent 316a D3/O1a/O1c). Never a clause
+  # trim: a clause trim on step text destroys a pinned `OPEN:` row
+  # (test/intent_screen_test.rb:171-178) that a mid-sentence cut would eat.
+  INSIGHT_VALUE_MAX = 72
+  INSIGHT_NOTE_MAX = 96
+  NEXT_VALUE_MAX = 72
+  STEP_TEXT_MAX = 110
+
   # Where a resume lands, from the ledger's last line (the boarding matrix).
   def self.landing_stage(stage, milestone)
     case stage
@@ -54,8 +76,6 @@ module IntentScreen
     fields.merge!(next_fields(items, status, checklist_present: items_present?(intent_dir)))
     fields.merge!(insight_fields(intent_text))
     fields["steps.rows"] = steps_rows(items)
-    fields["meaning"] = ""
-    fields["close"] = ""
 
     out = template.dup
     fields.each { |k, v| out = out.gsub("{{#{k}}}", v.to_s) }
@@ -171,7 +191,11 @@ module IntentScreen
       "progress.note" => note }
   end
 
-  def self.next_fields(items, status, checklist_present:)
+  # `escape_pipes:` (intent 316a O1d, default true) keeps the plain Markdown
+  # table's pipe-escaping; the ANSI renderer, which never emits a table,
+  # passes `escape_pipes: false` to get the raw value instead of a literal
+  # `\|`. Named to not shadow the module's own `escape` method.
+  def self.next_fields(items, status, checklist_present:, escape_pipes: true)
     return { "next" => "", "next.note" => "" } if %w[Completed Abandoned].include?(status)
     return { "next" => "write checklist.md", "next.note" => "How" } unless checklist_present
 
@@ -179,43 +203,83 @@ module IntentScreen
     return { "next" => "", "next.note" => "all steps done" } unless idx
 
     head, = split_first_clause(items[idx][:text])
-    { "next" => "S#{idx + 1} · #{escape(head)}", "next.note" => "first open step" }
+    head = truncate_words(head, NEXT_VALUE_MAX)
+    head = escape(head) if escape_pipes
+    { "next" => "S#{idx + 1} · #{head}", "next.note" => "first open step" }
   end
 
   def self.steps_rows(items)
     return "| | | no steps yet |" if items.empty?
 
     items.each_with_index.map do |item, i|
-      "| S#{i + 1} | #{item[:done] ? 'done' : 'open'} | #{escape(item[:text])} |"
+      "| S#{i + 1} | #{item[:done] ? 'done' : 'open'} | #{escape(step_text(item[:text]))} |"
     end.join("\n")
   end
 
+  # Public (intent 316a O1c) so the ANSI renderer trims step text identically:
+  # word-boundary truncation only, never a clause trim, at STEP_TEXT_MAX.
+  def self.step_text(text)
+    truncate_words(text, STEP_TEXT_MAX)
+  end
+
   def self.escape(text)
     text.gsub("|", "\\|")
   end
 
   # --- ## Insights ----------------------------------------------------------------
 
-  def self.insight_fields(intent_text)
+  def self.insight_fields(intent_text, escape_pipes: true)
     section = intent_text.split(/^## Insights\s*$/, 2)[1].to_s.split(/^## /, 2)[0].to_s
     entry = section.lines.map(&:strip).reverse.map { |l| l.match(INSIGHT_RE) }.compact.first
     return { "insight" => "none yet", "insight.note" => "" } unless entry
 
     ts, text = entry[1], entry[2].strip
     head, tail = split_first_clause(text)
+    value = truncate_words(head, INSIGHT_VALUE_MAX)
+    tail = tail.empty? ? "" : truncate_words(tail, INSIGHT_NOTE_MAX)
     note = tail.empty? ? human_time(ts) : "#{human_time(ts)} · #{tail}"
-    { "insight" => escape(head), "insight.note" => escape(note) }
+    if escape_pipes
+      { "insight" => escape(value), "insight.note" => escape(note) }
+    else
+      { "insight" => value, "insight.note" => note }
+    end
   end
 
+  # First clause of `text`, and at most one following clause as the tail.
+  # Anything past the second clause is discarded (intent 316a O1a): the old
+  # behavior dumped the ENTIRE remainder into the note (an 800-character
+  # real-world tail starting mid-list). Boundary is a `.` or `;` immediately
+  # followed by whitespace-then-more or end of string, so "alpha.2" and "2.0"
+  # are never mistaken for clause ends.
   def self.split_first_clause(text)
-    m = text.match(/\A(.+?)[.;](\s+.*|\z)/m)
-    head = m ? m[1] : text
-    tail = m ? m[2].to_s.strip : ""
-    if head.length > 60
-      cut = head[0, 60].rindex(" ") || 60
-      tail = "#{head[cut..].strip} #{tail}".strip
-      head = head[0, cut].strip
-    end
+    head, rest = clause_and_rest(text)
+    return [head, ""] unless rest
+
+    second, more = clause_and_rest(rest)
+    tail = more ? second : rest
     [head, tail]
   end
+
+  # Returns [clause_without_terminal_punctuation, remainder_or_nil]. `nil` for
+  # the remainder means either no boundary exists at all, or the boundary
+  # sits at the absolute end of `text` (a single trailing clause with nothing
+  # after it) — both cases where there is no SECOND clause to fold in.
+  def self.clause_and_rest(text)
+    m = text.match(/\A(.+?)[.;](\s+(.*)|\z)/m)
+    return [text, nil] unless m
+
+    remainder = m[2].to_s.strip
+    remainder.empty? ? [m[1], nil] : [m[1], remainder]
+  end
+
+  # Word-boundary truncation with a trailing "…" when cut, never mid-word and
+  # never a clause trim (intent 316a D3).
+  def self.truncate_words(text, max)
+    return text if text.length <= max
+    return "…" if max <= 1
+
+    cut = text[0, max - 1].rindex(" ")
+    cut = max - 1 if cut.nil? || cut.zero?
+    "#{text[0, cut].rstrip}…"
+  end
 end

package/scripts/lib/intent_screen_ansi.rb

@@ -0,0 +1,201 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "intent_screen"
+
+# IntentScreenAnsi (intent 316a, O2) - renders one intent screen with raw
+# truecolor ANSI escapes, productionizing 318's mockup--render.rb. Standard
+# library only. Calls the SAME public IntentScreen.* field methods
+# scripts/intent-screen calls (store_fields, index_fields, savepoint_fields,
+# checklist_items, progress_fields, next_fields, insight_fields,
+# items_present?, fallback_name, step_text) and re-derives nothing, so every
+# field the ANSI block prints is the identical value the plain screen prints
+# (D3), just carried through a different layout.
+#
+# `color:` is a constructor/call argument, never an environment read (D18):
+# the plain path (`color: false`) is one call away and testable without
+# touching NO_COLOR or a TTY. No ENV, no Dir.pwd, no Dir.home.
+#
+# Harness-agnostic core: no harness assumption lives here. `markdown_safe:`
+# (intent 316a1, D3/D5) is the one choice a caller supplies rather than a
+# choice this module makes for itself: a display surface that passes raw
+# ANSI through untouched should not inherit a concession it never needed.
+# See docs/reference/harness-adapters.md for which caller asks for it and
+# why.
+module IntentScreenAnsi
+  ESC = "\e"
+  RESET = "#{ESC}[0m".freeze
+  BOLD = "#{ESC}[1m".freeze
+  TEAL = "#{ESC}[38;2;45;212;191m".freeze
+  AMBER = "#{ESC}[38;2;245;158;11m".freeze
+  GRAPHITE_BG = "#{ESC}[48;2;31;41;55m".freeze
+  MIDGREY = "#{ESC}[38;2;148;163;184m".freeze
+  NEARWHITE = "#{ESC}[38;2;243;244;246m".freeze
+
+  BAR_CELLS = 24
+  EIGHTHS = [" ", "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█"].freeze
+
+  DEFAULT_WIDTH = 100
+
+  ELLIPSIS = "…"
+
+  def self.render(intent_dir:, store_root:, color: true, width: DEFAULT_WIDTH, markdown_safe: false)
+    base = File.basename(intent_dir)
+    id = base.split("--", 2).first
+    intent_text = File.read(File.join(intent_dir, "#{base}.md"))
+
+    fields = {}
+    fields.merge!(IntentScreen.store_fields(store_root))
+    status, title = IntentScreen.index_fields(store_root, id)
+    fields["status"] = status
+    fields["status.note"] = status == "unlisted" ? "no INDEX.md line names this id" : "listed under ## #{status} in INDEX.md"
+    fields["id"] = id
+    fields["name"] = title || IntentScreen.fallback_name(intent_text)
+    fields.merge!(IntentScreen.savepoint_fields(intent_dir, intent_text))
+    items = IntentScreen.checklist_items(intent_dir)
+    fields.merge!(IntentScreen.progress_fields(items))
+    fields.merge!(IntentScreen.next_fields(items, status, checklist_present: IntentScreen.items_present?(intent_dir), escape_pipes: false))
+    fields.merge!(IntentScreen.insight_fields(intent_text, escape_pipes: false))
+    fields.transform_values! { |v| markdown_safe ? clean(v) : v }
+
+    done_n = fields["progress.done"].to_i
+    total_n = fields["progress.total"].to_i
+
+    out = +""
+    out << fit("▶ #{fields['id']} · #{fields['name']}", width) { |t| styled(t, color, BOLD, NEARWHITE) }
+    out << "\n\n"
+
+    # The 4th column marks a row whose value is already a finished, pre-fit
+    # string (the Progress bar, built above from styled glyphs plus a count)
+    # rather than raw field text still needing `fit_plain`. Naming that
+    # explicitly here reads better than testing the value for a leading ESC
+    # byte further down, which is really just asking "is this the Progress
+    # row?" through a type check.
+    field_rows = [
+      ["Store", fields["store"], fields["store.note"], false],
+      ["Status", fields["status"], fields["status.note"], false],
+      ["Stage", fields["stage"], fields["stage.note"], false],
+      ["Savepoint", fields["savepoint"], fields["savepoint.note"], false],
+      ["Progress", "#{render_bar(done_n, total_n, color)}  #{done_n} / #{total_n}", fields["progress.note"], true],
+      ["Next", fields["next"], fields["next.note"], false],
+      ["Insight", fields["insight"], fields["insight.note"], false],
+    ]
+    key_width = field_rows.map { |k, _, _, _| k.length }.max
+    prefix_width = key_width + 4 # "  " + key.ljust + "  "
+
+    field_rows.each do |key, value, note, prebuilt|
+      value_budget = [width - prefix_width, 0].max
+      value_text = prebuilt ? value : fit_plain(value, value_budget)
+      out << "  #{styled(key.ljust(key_width), color, BOLD)}  #{value_text}\n"
+      next if note.to_s.empty?
+
+      note_budget = [width - prefix_width, 0].max
+      indent = " " * prefix_width
+      out << "#{indent}#{fit(note, note_budget) { |t| styled(t, color, MIDGREY) }}\n"
+    end
+
+    out << "\n"
+    out << fit("Steps", width) { |t| styled(t, color, BOLD, NEARWHITE) }
+    out << "\n\n"
+
+    if items.empty?
+      out << "  no steps yet\n"
+    else
+      # Padded to the widest label (matrix B2): at 10+ steps "S10" is one
+      # column wider than "S1..S9", and without padding every badge past S9
+      # drifts out of column with the rows above it.
+      label_width = "S#{items.size}".length
+      items.each_with_index do |item, i|
+        num = "S#{i + 1}".ljust(label_width)
+        badge = status_cell(item[:done], color)
+        prefix_plain = "  #{num}  [ #{item[:done] ? 'done' : 'open'} ]  "
+        text_budget = [width - prefix_plain.length, 0].max
+        step = IntentScreen.step_text(item[:text])
+        text = fit_plain(markdown_safe ? clean(step) : step, text_budget)
+        out << "  #{num}  [#{badge}]  #{text}\n"
+      end
+    end
+
+    out
+  end
+
+  # --- markdown-noise stripping, adapter-optional (intent 316a1, D3/D5) ------
+  #
+  # Not every display surface passes text through a Markdown renderer, so
+  # stripping is not this module's call to make (see `markdown_safe:` on
+  # `render` above; the justification for WHY a caller would ever ask for
+  # this lives with that caller, in scripts/lib/message_display.rb). When
+  # asked, strips backticks and neutralises `*`/`_` runs from a value.
+  # Single underscores are left alone: they are common inside ordinary words
+  # (`intent_screen.rb`) and GFM does not treat an intraword underscore as
+  # emphasis; only a run of 2+ (the bold marker `__`) is markdown-active.
+  def self.clean(text)
+    text.to_s.delete("`*").gsub(/_{2,}/, "")
+  end
+
+  # --- width cap (D15, matrix 18) --------------------------------------------
+
+  # Truncates `text` to `max` visible columns with a trailing ellipsis when
+  # cut, then yields the truncated plain text to the block for coloring.
+  # Coloring never adds visible width. The cap itself is harness-neutral: a
+  # fixed width, not a re-flow, is what lets a column layout survive whatever
+  # display eventually shows it — no display's own wrapping is assumed here.
+  def self.fit(text, max)
+    plain = fit_plain(text, max)
+    block_given? ? yield(plain) : plain
+  end
+
+  def self.fit_plain(text, max)
+    return "" if max <= 0
+    return text if text.length <= max
+    return ELLIPSIS[0, max] if max <= 1
+
+    "#{text[0, max - 1]}#{ELLIPSIS}"
+  end
+
+  # --- palette ----------------------------------------------------------------
+
+  def self.styled(text, color, *codes)
+    return text unless color
+
+    "#{codes.join}#{text}#{RESET}"
+  end
+
+  def self.status_cell(done, color)
+    label = done ? " done " : " open "
+    return label unless color
+
+    hue = done ? TEAL : AMBER
+    "#{hue}#{BOLD}#{label}#{RESET}"
+  end
+
+  # `.dup` matters, not just style (318's own note, carried forward): these
+  # constants are built via string interpolation, which frozen_string_literal
+  # does NOT freeze automatically — only static literals get that. `.freeze`
+  # above makes them immutable, but `bar << ...` below still needs its OWN
+  # mutable copy or it would raise (or, without the freeze, silently corrupt
+  # the shared constant for every later call in the same process — matrix 16).
+  def self.render_bar(done, total, color)
+    ratio = total.zero? ? 0.0 : done.to_f / total
+
+    unless color
+      on = total.zero? ? 0 : (done * BAR_CELLS) / total
+      return ("#" * on) + ("." * (BAR_CELLS - on))
+    end
+
+    units = (ratio * BAR_CELLS * 8).round.clamp(0, BAR_CELLS * 8)
+    full, rem = units.divmod(8)
+    full = [full, BAR_CELLS].min
+
+    bar = TEAL.dup
+    bar << ("█" * full)
+    if full < BAR_CELLS && rem.positive?
+      bar << EIGHTHS[rem]
+      full += 1
+    end
+    track = BAR_CELLS - full
+    bar << GRAPHITE_BG << (" " * track) if track.positive?
+    bar << RESET
+    bar
+  end
+end

package/scripts/lib/message_display.rb

@@ -0,0 +1,382 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "intent_screen"
+require_relative "intent_screen_ansi"
+require_relative "store_discovery"
+require_relative "store_provisioning"
+
+# MessageDisplay (intent 316a, O4/O5, round 3 concurrency fix) - the Claude
+# Code MessageDisplay hook handler. One process per streamed chunk of every
+# assistant message (D11), so it must be cheap and decide fast. Pure: every
+# dependency (tmp_root, plastic_home, color, now, wait_ms, poll_ms, sleeper)
+# is a constructor argument, never an ENV read, a Dir.pwd/Dir.home read, or
+# the real Time.now/Kernel#sleep — the thin CLI (scripts/hook-message-display)
+# is the one place allowed to read any of those.
+#
+# Claude adapter: Claude Code only; the core is harness-agnostic. (intent
+# 316a1, D3 supersedes 316a's D6.) This is the sole caller that asks
+# IntentScreenAnsi.render for `markdown_safe: true` (scripts/lib/
+# intent_screen_ansi.rb) — see `finalize` below for why.
+#
+# A live run under a real pty (round 3) found that Claude Code fires the
+# per-chunk hook processes CONCURRENTLY, not strictly in order. Chunk 0 is
+# the one that recognizes the screen and creates the buffer (D13), and it can
+# lose the race to chunks with a higher index: they would find no buffer yet
+# and pass their raw Markdown straight through, producing a half plain /
+# half styled screen. This class now survives that:
+#
+#   - One file per chunk (index-named), written atomically (temp name in the
+#     same directory, then File.rename), so reassembly never depends on
+#     arrival order — only on the index each chunk already carries.
+#   - A decision file written BEFORE anything slow: chunk 0 writes SCREEN
+#     (the resolved intent dir + store root) the moment it engages, or
+#     NOSCREEN the moment it does not, so later chunks can decide without
+#     redoing any of chunk 0's work.
+#   - A later chunk asks a cheap, local question before ever waiting: could
+#     this delta plausibly be part of a screen (leading "|", "**Steps**", or
+#     blank)? An ordinary prose chunk arriving before SCREEN/NOSCREEN exists
+#     passes through at once, at zero cost. A chunk shaped like part of a
+#     screen polls for the decision, bounded (wait_ms/poll_ms), then fails
+#     open. The final chunk always waits for the decision, whatever its own
+#     shape, since it is the one that must not race — and it additionally
+#     waits (same budget) for every earlier chunk file to exist before it
+#     splices, returning whatever it does have rather than nothing when the
+#     budget runs out.
+#
+# Protocol (D13, preserved): chunk 0 still decides, once, before anything is
+# 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.
+class MessageDisplay
+  MARKER_RE = /\A## ▶ (\S+) · /.freeze
+  BUFFER_DIR_NAME = "plastic-message-display"
+  BUFFER_MAX_AGE_SECONDS = 3600
+  SCREEN_FILE = "SCREEN"
+  NOSCREEN_FILE = "NOSCREEN"
+
+  def initialize(tmp_root:, plastic_home:, color:, now:, wait_ms: 300, poll_ms: 20,
+                 sleeper: ->(seconds) { sleep(seconds) })
+    @tmp_root = tmp_root
+    @plastic_home = plastic_home
+    @color = color
+    @now = now
+    @wait_ms = wait_ms
+    @poll_ms = poll_ms
+    @sleeper = sleeper
+  end
+
+  def handle(payload)
+    return nil unless @color
+    return nil unless payload.is_a?(Hash)
+
+    prune_old_buffers
+
+    message_id = payload["message_id"].to_s
+    session_id = payload["session_id"].to_s
+    delta = payload["delta"].to_s
+    final = payload["final"] == true
+    index = payload["index"]
+    cwd = payload["cwd"].to_s
+
+    return nil if message_id.empty? || session_id.empty?
+
+    dir = self.class.buffer_path(tmp_root: @tmp_root, session_id: session_id, message_id: message_id)
+
+    if index == 0
+      handle_chunk_zero(dir, delta, cwd, final)
+    else
+      handle_later_chunk(dir, index, delta, final)
+    end
+  end
+
+  # The message directory both this class and the bash launcher (hooks/
+  # message-display) must agree on byte for byte (matrix 40): the launcher
+  # checks this exact path's existence to decide whether chunk > 0 of an
+  # engaged message gets handed to Ruby at all.
+  def self.buffer_path(tmp_root:, session_id:, message_id:)
+    File.join(tmp_root, BUFFER_DIR_NAME, session_id, message_id)
+  end
+
+  def self.chunk_path(tmp_root:, session_id:, message_id:, index:)
+    File.join(buffer_path(tmp_root: tmp_root, session_id: session_id, message_id: message_id), index.to_s)
+  end
+
+  def self.screen_path(tmp_root:, session_id:, message_id:)
+    File.join(buffer_path(tmp_root: tmp_root, session_id: session_id, message_id: message_id), SCREEN_FILE)
+  end
+
+  def self.noscreen_path(tmp_root:, session_id:, message_id:)
+    File.join(buffer_path(tmp_root: tmp_root, session_id: session_id, message_id: message_id), NOSCREEN_FILE)
+  end
+
+  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.
+  def handle_chunk_zero(dir, delta, cwd, final)
+    stripped = delta.sub(/\A[ \t]+/, "")
+    m = stripped.match(MARKER_RE)
+    resolved = m && resolve_intent_dir(m[1], cwd)
+
+    unless resolved
+      write_noscreen(dir)
+      return nil
+    end
+
+    write_screen(dir, resolved)
+    write_chunk(dir, 0, delta)
+    final ? finalize_final(dir, 0) : ""
+  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.
+  def handle_later_chunk(dir, index, delta, final)
+    decision = wait_for_decision(dir, gate_delta: final ? nil : delta)
+
+    return nil unless decision == :screen
+
+    write_chunk(dir, index, delta)
+    final ? finalize_final(dir, index) : ""
+  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
+  # entirely and always polls for the decision.
+  def wait_for_decision(dir, gate_delta:)
+    decision = read_decision_now(dir)
+    return decision if decision
+
+    return :timeout if gate_delta && !maybe_screen?(gate_delta)
+
+    max_polls_for_budget.times do
+      @sleeper.call(@poll_ms / 1000.0)
+      decision = read_decision_now(dir)
+      return decision if decision
+    end
+
+    :timeout
+  end
+
+  def read_decision_now(dir)
+    return :screen if File.exist?(File.join(dir, SCREEN_FILE))
+    return :noscreen if File.exist?(File.join(dir, NOSCREEN_FILE))
+
+    nil
+  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.
+  def maybe_screen?(delta)
+    stripped = delta.lstrip
+    stripped.empty? || stripped.start_with?("|") || stripped.start_with?("**Steps**")
+  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.
+  def finalize_final(dir, index)
+    wait_for_chunk_files(dir, index)
+
+    buffered = nil
+    begin
+      buffered = read_buffered_chunks(dir, index)
+      decision = read_screen_decision(dir)
+      finalize(buffered, decision)
+    rescue StandardError
+      buffered
+    ensure
+      FileUtils.rm_rf(dir)
+    end
+  end
+
+  def wait_for_chunk_files(dir, index)
+    return if index <= 0
+
+    needed = (0...index).map(&:to_s)
+    max_polls_for_budget.times do
+      return if needed.all? { |n| File.exist?(File.join(dir, n)) }
+
+      @sleeper.call(@poll_ms / 1000.0)
+    end
+  end
+
+  def max_polls_for_budget
+    return 0 unless @poll_ms.to_f.positive?
+
+    (@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|
+      path = File.join(dir, i.to_s)
+      File.exist?(path) ? File.read(path) : nil
+    end.join
+  end
+
+  def read_screen_decision(dir)
+    content = File.read(File.join(dir, SCREEN_FILE))
+    intent_dir, store_root = content.split("\n")
+    { intent_dir: intent_dir, store_root: store_root }
+  end
+
+  def finalize(buffered, decision)
+    intent_dir = decision[:intent_dir]
+    store_root = decision[:store_root]
+    # markdown_safe: true (intent 316a1, D5) - Claude Code still Markdown-
+    # processes displayContent even inside a raw ANSI block (316a's live
+    # capture showed backticks silently stripped from step text), so the
+    # Claude adapter asks the harness-agnostic core to strip markdown noise
+    # before it ever reaches the block. A harness whose display surface
+    # passes raw ANSI through untouched would ask for false instead.
+    ansi = IntentScreenAnsi.render(intent_dir: intent_dir, store_root: store_root, color: true, markdown_safe: true)
+    plain = IntentScreen.render(intent_dir: intent_dir, store_root: store_root, template: File.read(template_path))
+    splice(buffered, plain, ansi)
+  end
+
+  def template_path
+    File.expand_path("../../templates/intent-screen.md", __dir__)
+  end
+
+  def write_chunk(dir, index, delta)
+    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, resolved)
+    atomic_write(File.join(dir, SCREEN_FILE), "#{resolved[:intent_dir]}\n#{resolved[:root]}\n")
+  end
+
+  def write_noscreen(dir)
+    atomic_write(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)}"
+    File.write(tmp_path, content)
+    File.rename(tmp_path, path)
+  end
+
+  # D16: replace the plain render's own text wherever it sits in the buffered
+  # message, keeping everything after it verbatim. Falls back to a line-based
+  # boundary (the "## ▶ " line through the last line starting with "|") only
+  # when the buffered text does not start with the plain render exactly (the
+  # model reformatted something, or a chunk gap broke the exact match) — the
+  # fallback also has to work for a checklist-less intent, whose only Steps
+  # row is "| | | no steps yet |".
+  def splice(buffered, plain, ansi)
+    suffix =
+      if buffered.start_with?(plain)
+        buffered[plain.length..]
+      else
+        line_based_suffix(buffered, plain)
+      end
+    return buffered if suffix.nil?
+
+    "#{ansi.rstrip}\n\n#{suffix}"
+  end
+
+  # Bounded fallback (matrix, lead's B1): walk forward from the "## ▶ " line
+  # only through the screen's OWN contiguous run of blank lines, "|"-prefixed
+  # table rows and the "**Steps**" heading, and stop at the first line that is
+  # none of those. The boundary is the last "|" line seen before that stop —
+  # never the last "|" line anywhere in the message. Scanning to the end
+  # unbounded (the old behavior) swallows any prose the model wrote between
+  # the screen and an unrelated Markdown table further down (a real hazard:
+  # Plastic replies carry tables often).
+  def line_based_suffix(buffered, plain)
+    lines = buffered.lines
+    start_idx = lines.index { |l| l.start_with?("## ▶ ") }
+    return nil unless start_idx
+
+    last_pipe_idx = nil
+    i = start_idx + 1
+    while i < lines.length
+      line = lines[i]
+      stripped = line.strip
+      break unless stripped.empty? || line.start_with?("|") || stripped == "**Steps**"
+
+      last_pipe_idx = i if line.start_with?("|")
+      i += 1
+    end
+    return nil unless last_pipe_idx
+
+    # Guard: never let the bounded scan consume more lines than the freshly
+    # rendered plain screen itself has. If it would, something about the
+    # buffered text does not match the shape splice() expects at all — pass
+    # the original through rather than risk eating real prose.
+    consumed = last_pipe_idx + 1 - start_idx
+    return nil if consumed > plain.lines.length
+
+    lines[(last_pipe_idx + 1)..].join
+  end
+
+  # O5: candidates are every discovered store holding a "<id>--*" directory.
+  # A single candidate resolves outright (no ambiguity to break). With two or
+  # more, the store whose project root is a path prefix of the payload's cwd
+  # decides; if that narrows to anything other than exactly one, pass through
+  # rather than guess (matrix 36).
+  #
+  # "cwd is a path prefix" is checked against the project's REAL checkout
+  # path (projects.yml's own `path:`, e.g. ~/apps/personal/plastic) — never
+  # against StoreDiscovery's `root` (~/.plastic/projects/<slug>, which only
+  # holds INDEX.md and store/). Those are two different directories; a real
+  # session's cwd lives under the former, never the latter. The global store
+  # has no such checkout path, so it never wins by cwd — only by being the
+  # sole candidate.
+  def resolve_intent_dir(id, cwd)
+    pattern = "#{glob_escape(id)}--*"
+    candidates = StoreDiscovery.discover(@plastic_home)[:stores].filter_map do |s|
+      dir = Dir.glob(File.join(s[:store], pattern)).find { |d| File.directory?(d) }
+      dir && { slug: s[:slug], root: s[:root], intent_dir: dir }
+    end
+    return nil if candidates.empty?
+    return candidates.first if candidates.length == 1
+
+    registered = StoreProvisioning.load_projects(@plastic_home)
+    cwd_matches = candidates.select do |c|
+      real_path = registered.dig(c[:slug], "path")
+      real_path && (cwd == real_path || cwd.start_with?("#{real_path}#{File::SEPARATOR}"))
+    end
+    return cwd_matches.first if cwd_matches.length == 1
+
+    nil
+  end
+
+  # A recognized id should just be [A-Za-z0-9]+, but the id comes out of the
+  # assistant's own streamed text, not a trusted schema — escape glob
+  # metacharacters rather than assume it is well-formed.
+  def glob_escape(str)
+    str.gsub(/([*?\[\]{}])/) { "\\#{Regexp.last_match(1)}" }
+  end
+
+  def prune_old_buffers
+    root = File.join(@tmp_root, BUFFER_DIR_NAME)
+    return unless File.directory?(root)
+
+    Dir.children(root).each do |session_dir|
+      full = File.join(root, session_dir)
+      next unless File.directory?(full)
+
+      age = @now.to_i - File.mtime(full).to_i
+      FileUtils.rm_rf(full) if age > BUFFER_MAX_AGE_SECONDS
+    end
+  rescue StandardError
+    nil
+  end
+end

package/skills/intent-continuing/SKILL.md

@@ -103,7 +103,11 @@ For a live intent's directory:
    the next thing the stage needs (see the matrix). The newest `## Insights` entry supplies
    the human-readable context; an entry marked `(autonomous)` means an auto team was
    delivering it, so say so and offer to hand back to `plastic-auto`.
-5. **Print the intent screen, then continue at that stage.** Run
+5. **Print the intent screen as the first thing in the reply, then continue at that stage.**
+   The screen must open the message with nothing before it. On Claude Code, a fail-open
+   `MessageDisplay` hook recognizes a reply that opens this way and substitutes a styled ANSI
+   rendering for it there; the transcript and every other harness keep exactly this plain
+   form, and nothing about how the screen is printed here ever changes. Run
    `ruby ~/.plastic/scripts/intent-screen <intent_dir>` and print its output as it is: the
    title, the field table, and the Steps table come from the record, never by eye. Under it
    write **What this means** as two to four bullets in plain words (what the intent is for,

package/templates/intent-screen.md

@@ -10,13 +10,8 @@
 | **Next** | {{next}} | {{next.note}} |
 | **Insight** | {{insight}} | {{insight.note}} |
 
-**What this means**
-{{meaning}}
-
 **Steps**
 
 | Step | Status | What |
 | --- | --- | --- |
 {{steps.rows}}
-
-{{close}}