@zalom/plastic 2.0.0-alpha.4 → 2.0.0-alpha.6

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,71 @@
+#!/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.
+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.4",
+  "version": "2.0.0-alpha.6",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/dashboard.rb

@@ -56,13 +56,26 @@ rescue StandardError
   nil
 end
 
-# Returns the set of intent ids listed under a given INDEX.md section.
+# The link form's id: "- [id](path)...". The class excludes "[" (as well as
+# "]" and whitespace) so this can never match a wikilink line's OWN opening
+# bracket and key it as "[71" (row F, spec 315b): "- [[71]] ..." fails this
+# pattern outright (the character right after "- [" is itself "[", which the
+# class disallows), leaving it to WIKILINK_ID_RE below.
+LINK_ID_RE = /^- \[([^\[\]\s]+)/
+
+# The wikilink form's id: "- [[id]] name (em dash) description (date; ...)",
+# the shape mihradesign's INDEX.md and others use. Bare id, no brackets.
+WIKILINK_ID_RE = /^- \[\[([^\[\]]+)\]\]/
+
+# Returns the set of intent ids listed under a given INDEX.md section, link
+# form and wikilink form alike (row F5: Active, Abandoned, Completed, and a
+# store's Future section can all mix both forms).
 def index_section_ids(index_path, header)
   return [] unless File.exist?(index_path)
   body = File.read(index_path)
   seg = body[/^#{Regexp.escape(header)}\s*\n(.*?)(?=^## |\z)/m, 1]
   return [] unless seg
-  seg.scan(/^- \[([^\]\s]+)/).flatten
+  seg.scan(LINK_ID_RE).flatten + seg.scan(WIKILINK_ID_RE).flatten
 end
 
 # Bug found at intent 202's gate review: the date used to be anchored to the END of the
@@ -77,21 +90,37 @@ end
 # (end-intent's own Bridge.index_entry_match accepts either on read). Because regex
 # alternation is leftmost-first, this only ever matches the date immediately after the
 # link. It never continues scanning into the note prose, so a second date mentioned
-# later in a note's free text cannot be mistaken for the completion date.
-COMPLETION_DATE_RE = /^- \[([^\]\s]+).*?\)\s*[\u2014-]\s*(\d{4}-\d{2}-\d{2})\b/
+# later in a note's free text cannot be mistaken for the completion date. The id class
+# excludes "[" (row F) so this can never fire on a wikilink line's own opening bracket.
+COMPLETION_DATE_RE = /^- \[([^\[\]\s]+).*?\)\s*[\u2014-]\s*(\d{4}-\d{2}-\d{2})\b/
+
+# The wikilink form's completion date: "- [[id]] name (em dash) description
+# (date; other notes)". Real shape (mihradesign's INDEX.md): the date is the
+# first thing inside the entry's trailing parenthetical. A SEPARATE regex
+# from COMPLETION_DATE_RE (row F review finding), not one four-group
+# alternation: a four-group `scan` breaks `String#scan(...).to_h`, and a bare
+# `\(` alternative on the link form would harvest a date out of note prose on
+# an entry with no canonical date of its own.
+WIKILINK_COMPLETION_DATE_RE = /^- \[\[([^\[\]]+)\]\].*?\((\d{4}-\d{2}-\d{2})\b/
 
 # Map of intent id -> completion date string, parsed from the "## Completed" section
-# (lines like "- [12 (em dash) title](link) (em dash) 2026-06-10 optional note text").
-# Deterministic, content-derived. Observability: a populated "## Completed" section that
-# yields not one single dated entry is a parser regression, not a legitimately empty
-# result, so it is surfaced with a stderr warning rather than rotting invisibly (the same
-# silent-failure class intent 202's gate review caught this file already committing).
+# (lines like "- [12 (em dash) title](link) (em dash) 2026-06-10 optional note text",
+# or the wikilink form "- [[12]] title (em dash) description (2026-06-10; notes)").
+# Deterministic, content-derived. Two regexes scanned separately and merged into one
+# hash (row F), so each form's own matching rules stay independent: the wikilink
+# alternative can never steal a date out of a link-form entry's note prose, because it
+# never even looks at a link-form line (its "- [[" anchor cannot match a line whose
+# second character is not itself "["). Observability: a populated "## Completed"
+# section that yields not one single dated entry is a parser regression, not a
+# legitimately empty result, so it is surfaced with a stderr warning rather than
+# rotting invisibly (the same silent-failure class intent 202's gate review caught this
+# file already committing).
 def completion_dates(index_path)
   return {} unless File.exist?(index_path)
   body = File.read(index_path)
   seg = body[/^## Completed\s*\n(.*?)(?=^## |\z)/m, 1] || ""
   entry_count = seg.scan(/^- \[/).size
-  dates = seg.scan(COMPLETION_DATE_RE).to_h
+  dates = seg.scan(COMPLETION_DATE_RE).to_h.merge(seg.scan(WIKILINK_COMPLETION_DATE_RE).to_h)
   if entry_count.positive? && dates.empty?
     warn "dashboard: completion_dates parsed 0/#{entry_count} dates from the " \
          "\"## Completed\" section of #{index_path}; treat this as a parser regression, " \

package/scripts/doctor.rb

@@ -288,6 +288,167 @@ class Doctor
   # content scanning. check_global_store (above) is store/full-scope and includes
   # orphaned_intents / ghost_references, both explicitly forbidden at core by D1.
 
+  # Row E (spec D8, spec 315b): #check_core_files's own `version_match` only ever
+  # compares the SELECTED harness's `<dir>/plastic/VERSION` against the global
+  # VERSION, so a second installed harness left behind on an old version is never
+  # version-checked at all -- exactly how ten stale 1.14.1 Codex registrations
+  # survived a `pass`. This runs the same comparison for EVERY installed harness
+  # (agent_dir on disk), named `version_match_<key>` so the existing `version_match`
+  # name and position stay reserved for the selected harness (pinned tests:
+  # test/doctor_test.rb:1846,1861,1873). Full tier only (`run_checks`); never
+  # `run_core_checks`, which is `binary: true` and runs on the session-start boot
+  # path, where a second-harness warn would become a boot-time error for every user.
+  def check_harness_versions
+    global_version = read_version
+    return [] unless global_version
+
+    agents.filter_map do |key, config|
+      next unless config.is_a?(Hash) && File.directory?(config[:dir].to_s)
+
+      agent_version_path = File.join(config[:dir], "plastic", "VERSION")
+      name = "version_match_#{key}"
+
+      if !File.exist?(agent_version_path)
+        check(
+          category: "core_files", name: name, status: "warn",
+          message: "#{config[:name]}'s agent-side VERSION file not found at #{tilde(agent_version_path)}",
+          fixable: true,
+          fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+        )
+      else
+        agent_version = File.read(agent_version_path).strip
+        if global_version == agent_version
+          check(
+            category: "core_files", name: name, status: "pass",
+            message: "Global VERSION (#{global_version}) matches #{config[:name]}'s agent-side VERSION"
+          )
+        else
+          check(
+            category: "core_files", name: name, status: "warn",
+            message: "Version mismatch for #{config[:name]}: global=#{global_version}, agent=#{agent_version}",
+            details: [
+              "#{tilde(File.join(plastic_home, "VERSION"))}: #{global_version}",
+              "#{tilde(agent_version_path)}: #{agent_version}",
+            ],
+            fixable: true,
+            fix_hint: "Re-sync the stale harness: npx @zalom/plastic@latest install --reinstall <flag>, or plastic-rollback to a prior version"
+          )
+        end
+      end
+    end
+  end
+
+  # The Codex hook NAME expected per event, keyed off HookRegistry's own
+  # constants rather than a full built command string: naming it, not the
+  # literal dispatcher path, is what #check_codex_stale_registrations needs,
+  # so this never depends on plastic_home resolving to the same install the
+  # live hooks.json's commands were written under.
+  def codex_expected_names_by_event
+    names = {}
+    post_order = HookRegistry.events["PostToolUse"].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    names["PostToolUse"] = HookRegistry::CODEX_POST_HOOKS & post_order
+
+    HookRegistry::CODEX_LIVE_STATE_EVENTS.each do |event|
+      names[event] = HookRegistry.events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    end
+
+    end_order = HookRegistry.events["SessionEnd"].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    names["SessionEnd"] = HookRegistry::CODEX_SESSION_END_HOOKS & end_order
+    names
+  end
+
+  # Row E (spec D8, spec 315b): #codex_hooks_registered_check computes
+  # `want - got` and iterates `expected.each`, so it can see a MISSING registration
+  # but never an EXTRA one, and it can never even visit an event `expected` does not
+  # list at all (a retired event such as PreToolUse, which a stale ~/.codex/hooks.json
+  # can still carry). This scans the UNION of expected and live event keys instead, so
+  # a stale registration parked in a retired event is visible. Compares hook NAMES
+  # (see #codex_expected_names_by_event), not full command strings: a full-command
+  # comparison would embed this Doctor instance's own `plastic_home` in the expected
+  # dispatcher path, which is only guaranteed to match the live hooks.json's own
+  # dispatcher path in a real, single install, never a test that fakes one without the
+  # other. Full tier only (`run_checks`); never `run_core_checks` (D8).
+  #
+  # Post-execution review item 5: name-only comparison alone is blind to two real
+  # cases, both closed here without reintroducing any plastic_home coupling: (a) the
+  # SAME (event, name) pair registered more than once (each copy's name is
+  # individually expected, so a "not in the expected set" scan never sees the
+  # duplicate), and (b) a correctly-named entry whose dispatcher path is an OLD
+  # install, different from the path every OTHER Plastic entry in this same file
+  # actually uses -- the "correct" path here is whichever path the file's own
+  # majority of entries already agrees on, never a path this Doctor instance derives
+  # from its own plastic_home.
+  def check_codex_stale_registrations
+    config = agents["codex"]
+    return [] unless config.is_a?(Hash) && File.directory?(config[:dir].to_s)
+
+    home_dir = config[:home_dir] || config[:dir]
+    hooks_json = File.join(home_dir, "hooks.json")
+    data = read_json_safe(hooks_json)
+    return [] if data.nil? || !data.is_a?(Hash)
+
+    expected_names = codex_expected_names_by_event
+    live = data["hooks"].is_a?(Hash) ? data["hooks"] : {}
+
+    # One pass over every live Plastic entry (event, hook name, and the literal
+    # dispatcher-path token it actually invokes), shared by all three checks below.
+    entries = []
+    (expected_names.keys | live.keys).each do |event|
+      Array(live[event]).each do |group|
+        Array(group["hooks"]).each do |h|
+          cmd = h["command"]
+          next unless HookRegistry.codex_purge_command?(cmd)
+
+          dispatcher_path = cmd.to_s.split(/\s+/).reject(&:empty?).first.to_s.delete("\"'")
+          name = HookRegistry.command_basenames(cmd).last
+          entries << { event: event, name: name, dispatcher_path: dispatcher_path, cmd: cmd }
+        end
+      end
+    end
+
+    stale = []
+
+    # Not in the expected name set for this event at all (the original check).
+    entries.each do |e|
+      want_names = Array(expected_names[e[:event]])
+      stale << "#{e[:event]}: #{e[:cmd]}" unless want_names.include?(e[:name])
+    end
+
+    # (a) the same (event, name) pair registered more than once.
+    entries.group_by { |e| [e[:event], e[:name]] }.each_value do |group|
+      next if group.size <= 1
+
+      group.each { |e| stale << "#{e[:event]}: #{e[:cmd]} (duplicate registration of #{e[:name]})" }
+    end
+
+    # (b) a dispatcher path that differs from the path every other Plastic entry in
+    # this same file actually uses.
+    unless entries.empty?
+      majority_path = entries.map { |e| e[:dispatcher_path] }.tally.max_by { |(_path, count)| count }&.first
+      entries.each do |e|
+        next if e[:dispatcher_path] == majority_path
+
+        stale << "#{e[:event]}: #{e[:cmd]} (dispatcher path #{e[:dispatcher_path]} differs from " \
+                  "this file's other Plastic entries at #{majority_path})"
+      end
+    end
+
+    stale.uniq!
+
+    if stale.empty?
+      [check(
+        category: "agent_registration", name: "codex_stale_registrations", status: "pass",
+        message: "No stale Plastic Codex registrations found outside the expected hook set"
+      )]
+    else
+      [check(
+        category: "agent_registration", name: "codex_stale_registrations", status: "warn",
+        message: "#{stale.size} stale Codex registration(s) found outside the expected hook set",
+        details: stale, fixable: true,
+        fix_hint: "Re-run the Plastic installer with --codex --reinstall to purge stale entries"
+      )]
+    end
+  end
   # --- Check category 2: Conventions ---
 
   # When `scopes` is a non-nil Array of scope strings (e.g. ["global"] or
@@ -2235,6 +2396,8 @@ end
     all_checks += check_conventions(scopes: ["global"])
     all_checks += check_agent_registration(agent_key)
     all_checks += check_core_files(agent_key)
+    all_checks += check_harness_versions
+    all_checks += check_codex_stale_registrations
     all_checks += check_deprecations
     all_checks += check_config_asks(agent_key)
     all_checks += check_qmd

package/scripts/hook-capture

@@ -129,11 +129,20 @@ def truncate(text, max)
   "#{text[0, max - 3]}..."
 end
 
-# --- (a) tmp root + heartbeat, unconditional -------------------------------
+# --- (a) tmp root + heartbeat, guarded on the pointer (spec D9) ------------
+# Session start writes the `current` pointer; a capture with no pointer yet
+# means session start never ran for this session at all (a `-p` print
+# session, a resumed background job, an unregistered SessionStart hook), so
+# neither the per-session dir nor its heartbeat is created. UserPromptSubmit
+# fires before PostToolUse, so capture is the FIRST creator of every orphan
+# `.tmp/<sid>/` this guard prevents; hook-record carries the same guard for
+# its own (later) heartbeat write.
 begin
-  SessionLedger.ensure_tmp_root(store)
-  FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
-  File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  if File.exist?(SessionLedger.pointer_path(store, sid))
+    SessionLedger.ensure_tmp_root(store)
+    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+    File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  end
 rescue StandardError
   nil
 end
@@ -151,11 +160,14 @@ rescue StandardError
 end
 
 # --- (c) pending checklist line -------------------------------------------
+# Gated on SessionLedger.capture_worthy?(prompt) (spec D2), a pure predicate
+# over the RAW prompt so it sees the true first character and multi-line
+# shape; the line text itself is still the sanitized, truncated copy.
 unless skip_day_ledger
   begin
-    project = SessionLedger.project_slug(cwd, plastic_home: plastic_home)
-    clean = truncate(SessionLedger.sanitize_summary(prompt), 120)
-    if clean.length >= 10
+    if SessionLedger.capture_worthy?(prompt)
+      project = SessionLedger.project_slug(cwd, plastic_home: plastic_home)
+      clean = truncate(SessionLedger.sanitize_summary(prompt), 120)
       SessionLedger.open_day(store: store, day: today, templates: templates, author: sid)
       line = SessionLedger.checklist_line(:pending, sid, project, clean)
       SessionLedger.append_line(SessionLedger.checklist_path(store, today), line,

package/scripts/hook-message-display

@@ -0,0 +1,65 @@
+#!/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.
+
+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/hook-record

@@ -135,13 +135,21 @@ unless skip_day_ledger
   end
 end
 
-# --- (d) heartbeat, always -------------------------------------------------
+# --- (d) heartbeat, guarded on the pointer (spec D9) -----------------------
+# Session start writes the `current` pointer; with no pointer at all, session
+# start never ran for this session (a `-p` print session, a resumed
+# background job, an unregistered SessionStart hook), so neither the
+# per-session dir nor its heartbeat is created here -- guarding only the
+# write would still leave an empty directory that heartbeat_age's mtime
+# fallback reports as an orphan just the same.
 begin
   store ||= File.join(plastic_home, "store")
   sid ||= SessionLedger.short_session_id(nil, session_id)
-  SessionLedger.ensure_tmp_root(store)
-  FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
-  File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  if File.exist?(SessionLedger.pointer_path(store, sid))
+    SessionLedger.ensure_tmp_root(store)
+    FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store, sid))
+    File.write(SessionLedger.heartbeat_path(store, sid), "#{Time.now.utc.iso8601}\n")
+  end
 rescue StandardError
   nil
 end

package/scripts/hook-session-start

@@ -18,6 +18,24 @@ require_relative "lib/day_summary"
 index_path, plastic_home, mode, plugin_root = ARGV
 exit 0 unless index_path && plastic_home && mode
 
+# --- session id: the stdin payload's session_id, then the env var, then the
+# pid (spec 298 D1, row G, spec D4). Guarded on $stdin.tty? so a human running
+# this hook by hand at a real terminal never blocks on a read that never gets
+# an EOF; every real harness invocation pipes the SessionStart JSON payload,
+# never attaches a tty. Malformed or empty stdin (or no payload id) falls
+# through to the same env-var-then-pid chain this always had.
+stdin_payload = begin
+  if $stdin.tty?
+    nil
+  else
+    raw = $stdin.read
+    raw && !raw.strip.empty? ? JSON.parse(raw) : nil
+  end
+rescue StandardError
+  nil
+end
+payload_session_id = stdin_payload.is_a?(Hash) ? stdin_payload["session_id"].to_s : ""
+
 # Plastic home and the store are two different paths (intent 231). The shim passes
 # home (~/.plastic) as argument 2; the store lives one level below it. Compose the
 # store exactly once here, so no later line re-derives it and no path can gain a
@@ -361,7 +379,11 @@ begin
   author = "session" if author.empty?
   SessionLedger.open_day(store: store_dir, day: day, templates: templates, author: author)
 
-  session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
+  session = if !payload_session_id.empty?
+              payload_session_id
+            else
+              ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
+            end
   sid = SessionLedger.short_session_id(nil, session)
   SessionLedger.ensure_tmp_root(store_dir)
   FileUtils.mkdir_p(SessionLedger.session_tmp_dir(store_dir, sid))

package/scripts/intent-screen

@@ -8,18 +8,27 @@
 # 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)
 
 require_relative "lib/intent_screen"
+require_relative "lib/intent_screen_ansi"
 
 def usage_abort(message)
   warn "intent-screen: #{message}"
@@ -28,18 +37,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 +59,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