@zalom/plastic 2.0.0-alpha.1 → 2.0.0-alpha.10

package/scripts/append-ledger

@@ -31,6 +31,7 @@
 #   3 - promote/tick could not take an exclusive lock (filesystem without flock support)
 
 require_relative "lib/session_ledger"
+require_relative "lib/handoff"
 
 VERBS = %w[pending item promote tick savepoint].freeze
 
@@ -129,10 +130,21 @@ def run_transition(from, to, event, store, day, session, project, opts)
     exit 2
   end
 
-  return unless opts[:savepoint]
+  if opts[:savepoint]
+    line = SessionLedger.savepoint_line(event, session, project, target_summary, now: Time.now)
+    SessionLedger.append_line(SessionLedger.savepoint_path(store, day), line, header: nil)
+  end
 
-  line = SessionLedger.savepoint_line(event, session, project, target_summary, now: Time.now)
-  SessionLedger.append_line(SessionLedger.savepoint_path(store, day), line, header: nil)
+  return unless to == :done
+
+  # The hand-off at every tick (intent 311, spec D4): derived and
+  # regenerable, so a failure here never fails the tick that was recorded.
+  begin
+    Handoff.write(store: store, day: day, session: session, trigger: "tick",
+                  templates: opts[:templates] || default_templates_dir)
+  rescue StandardError
+    nil
+  end
 end
 
 def run_savepoint(store, day, session, project, opts)
@@ -153,6 +165,7 @@ def main(argv)
   store = opts[:store] ? expand(opts[:store]) : File.join(plastic_home, "store")
   templates = opts[:templates] ? expand(opts[:templates]) : default_templates_dir
   usage_abort("templates dir not found: #{templates}") unless Dir.exist?(templates)
+  opts[:templates] = templates
   cwd = opts[:cwd] ? expand(opts[:cwd]) : Dir.pwd
 
   day = opts[:day] || SessionLedger.day_id

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/day-summary

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# day-summary (intent 311): print the block SessionStart injects at boot
+# (open items, the last five done, live auto intents, other active
+# sessions). Prints nothing when there is nothing to say.
+#
+# Usage:
+#   day-summary [--store <dir>] [--day <YYYYMMDD>] [--session <id>] [--home <dir>]
+#
+# Defaults: the home is $PLASTIC_HOME (~/.plastic), the store is <home>/store,
+# the day is today (local wall clock), the session is $CLAUDE_CODE_SESSION_ID.
+#
+# Exit codes: 0 done; 2 usage error.
+
+require_relative "lib/session_ledger"
+require_relative "lib/day_summary"
+
+def usage_abort(message)
+  warn "day-summary: #{message}"
+  exit 2
+end
+
+def expand(path)
+  File.expand_path(path.to_s.sub(/\A~/, Dir.home))
+end
+
+def parse_args(argv)
+  opts = {}
+  i = 0
+  while i < argv.length
+    flag = argv[i]
+    usage_abort("unknown argument #{flag.inspect}") unless flag.start_with?("--")
+    usage_abort("#{flag} requires a value") if i + 1 >= argv.length
+    key = flag.delete_prefix("--").to_sym
+    usage_abort("unknown flag #{flag.inspect}") unless %i[store day session home].include?(key)
+    opts[key] = argv[i + 1]
+    i += 2
+  end
+  opts
+end
+
+opts = parse_args(ARGV)
+home = opts[:home] ? expand(opts[:home]) : expand(ENV.fetch("PLASTIC_HOME", "~/.plastic"))
+store = opts[:store] ? expand(opts[:store]) : File.join(home, "store")
+day = opts[:day] || SessionLedger.day_id
+usage_abort("--day must be eight digits parsing as a real date, got #{day.inspect}") unless SessionLedger.valid_day_id?(day)
+session = SessionLedger.short_session_id(opts[:session], ENV["CLAUDE_CODE_SESSION_ID"])
+
+text = DaySummary.build(store: store, day: day, session: session, home: home)
+puts text unless text.empty?
+exit 0

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/end-intent

@@ -66,6 +66,8 @@
 #      refused before removal; pass --discard-worktree-changes to override
 #      deliberately.
 #   6  retired in 2.0 (intent 308): the structure check reports and proceeds.
+#   7  hollow delivered report refused (317a D7) - intent 308's one deliberate
+#      exception to report-and-proceed; --allow-hollow-report overrides.
 
 require "fileutils"
 require "date"
@@ -77,6 +79,7 @@ require_relative "lib/savepoint"
 require_relative "lib/lock"
 require_relative "lib/intent_validator"
 require_relative "lib/outcome_guard"
+require_relative "lib/report_screen"
 require_relative "lib/backfill_intent"
 
 DISPOSITIONS = %w[delivered abandoned].freeze
@@ -99,6 +102,7 @@ def parse_args(argv)
   opts = {
     store: nil, id: nil, disposition: nil, index: nil,
     outcome_summary: nil, index_note: nil, no_commit: false, dry_run: false,
+    allow_hollow_report: false,
     session: nil, discard_worktree_changes: false,
   }
   i = 0
@@ -115,6 +119,7 @@ def parse_args(argv)
     when "--discard-worktree-changes" then opts[:discard_worktree_changes] = true
     when "--no-commit"                then opts[:no_commit] = true
     when "--dry-run"                  then opts[:dry_run] = true
+    when "--allow-hollow-report"      then opts[:allow_hollow_report] = true
     else
       usage_abort("unknown argument #{arg.inspect}")
     end
@@ -215,7 +220,75 @@ end
 # Replace the body of the intent file's `## Outcome` section with `summary`,
 # leaving every other section and the frontmatter untouched. No-op (returns
 # content unchanged) when summary is blank or the section is not found.
+# 317a S9 (D7): the self-render gate. Renders the delivered screen's sources on
+# the intent's own record and names what would come out hollow. This is intent
+# 308's ONE deliberate exception to report-and-proceed: a hollow DELIVERED
+# close is refused with exit 7 (--allow-hollow-report overrides), because 317
+# closed exactly this way and the owner read a screen full of "not recorded".
+# Abandoned closes and machine-backfilled outcomes (the backfill marker) are
+# exempt: the reader cannot expect labels the writer never had.
+def hollow_report_reason(intent_dir, disposition)
+  return nil unless disposition == "delivered"
+
+  outcome = File.join(intent_dir, "outcome.md")
+  return nil unless File.exist?(outcome)
+  text = File.read(outcome)
+  return nil if text.include?("<!-- backfilled from the record by end-intent on ")
+
+  # The gate's evidence bar (A7/B7): it judges only records that CLAIM the
+  # modern convention - at least one actions/*.md heading carrying an S-label.
+  # A terse legacy close with no labeled matrix stays report-and-proceed.
+  heading_labels = Dir.glob(File.join(intent_dir, "actions", "*.md")).sort.flat_map do |path|
+    ReportScreen.split_by_headings(File.read(path)).filter_map do |heading, _body|
+      heading.to_s.sub(/\A#+\s*/, "").split(/[^A-Za-z0-9]+/).find { |tok| tok.match?(/\AS\d+\z/) }
+    end
+  end.uniq
+  return nil if heading_labels.empty?
+
+  rows = ReportScreen.delivered_rows(intent_dir)
+  return "outcome.md ## Delivered renders no rows although a labeled action matrix exists" if rows.empty?
+
+  needs = ReportScreen.section_of(text, "## Needs you").gsub(/<!--.*?-->/m, "").strip
+  if !needs.empty? && needs != "None" && ReportScreen.needs_you_rows(intent_dir).empty?
+    return "## Needs you has content that would render as None"
+  end
+
+  labels = rows.map { |r| r[:label] }
+  if (labels & heading_labels).empty?
+    return "delivered row labels (#{labels.first(3).join(', ')}...) match no action-file heading (#{heading_labels.first(3).join(', ')}...)"
+  end
+  if rows.all? { |r| ReportScreen.proven_by(intent_dir, r[:label]) == ReportScreen::NOT_RECORDED }
+    return "every Proven-by cell renders not recorded although labeled action headings exist"
+  end
+
+  nil
+rescue StandardError => e
+  warn "end-intent: hollow-report gate crashed (#{e.message}); proceeding without it"
+  nil
+end
+
+# 317a S7 (D5, A8): stamp the live lock's run_mode into outcome.md frontmatter
+# INSIDE the close step - after the gate, before the INDEX move and the store
+# commit - so the stamped file rides the close commit and mode survives disarm.
+def stamp_outcome_mode(intent_dir)
+  data = Lock.read(intent_dir)
+  run_mode = data && data["run_mode"].to_s
+  return if run_mode.nil? || run_mode.empty?
+
+  path = File.join(intent_dir, "outcome.md")
+  return unless File.exist?(path)
+  text = File.read(path)
+  return unless text.start_with?("---")
+  head, body = text[3..].split("---", 2)
+  return if body.nil? || head.match?(/^mode:/)
+
+  File.write(path, "---#{head}mode: #{run_mode}\n---#{body}")
+rescue StandardError => e
+  warn "end-intent: mode stamp failed (#{e.message}); proceeding without it"
+end
+
 def stamp_outcome_summary(content, summary)
+
   return content if summary.nil? || summary.to_s.strip.empty?
 
   lines = content.lines
@@ -654,6 +727,26 @@ def main(argv)
   reason = OutcomeGuard.reason(intent_dir, disposition)
   warn "end-intent: outcome.md: #{reason} (proceeding; doctor --intent #{id} reports it)" if reason
 
+  # 1a2. The self-render gate (317a S9, D7): refuse a hollow delivered close
+  # BEFORE any terminal mutation - INDEX, savepoint, and store stay untouched
+  # on exit 7 (A9).
+  hollow = hollow_report_reason(intent_dir, disposition)
+  if hollow
+    if opts[:allow_hollow_report]
+      warn "end-intent: hollow delivered report overridden (--allow-hollow-report): #{hollow}"
+    else
+      warn "end-intent: refusing a hollow delivered close: #{hollow}"
+      warn "end-intent: write outcome.md's ## Delivered as the labeled | Row | What | table " \
+           "matching the action-file headings (templates/outcome.md shows the shape), " \
+           "or pass --allow-hollow-report to close anyway"
+      exit 7
+    end
+  end
+
+  # 1a3. Mode stamp (317a S7, D5): run_mode into outcome frontmatter while the
+  # lock still exists, so the stamped file rides the close commit.
+  stamp_outcome_mode(intent_dir)
+
   # 1b. Intent-file `## Outcome` summary stamp (no-op unless given).
   if opts[:outcome_summary]
     intent_file = Savepoint.intent_file(intent_dir)

package/scripts/hook-capture

@@ -31,7 +31,8 @@ end
 exit 0 unless payload.is_a?(Hash)
 
 session_id = payload["session_id"].to_s
-prompt = payload["user_prompt"].to_s
+prompt = payload["prompt"].to_s
+prompt = payload["user_prompt"].to_s if prompt.empty?
 cwd = payload["cwd"].to_s
 cwd = Dir.pwd if cwd.empty?
 
@@ -128,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
@@ -150,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-close

@@ -25,9 +25,11 @@ payload =
 
 store = File.join(File.expand_path(plastic_home), "store")
 filer = File.expand_path("file-session-intent", __dir__)
+templates = File.expand_path("../templates", __dir__)
 begin
   SessionClose.run(payload: payload, store: store, today: SessionLedger.day_id,
-                   spawner: SessionClose.default_spawner(filer))
+                   spawner: SessionClose.default_spawner(filer),
+                   handoff: SessionClose.default_handoff(templates))
 rescue StandardError
   nil
 end

package/scripts/hook-message-display

@@ -0,0 +1,74 @@
+#!/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.
+
+# 317a (B1): the requires sit inside their own rescue - a missing or broken
+# lib file must never surface as a non-zero exit or stderr on a chunk of an
+# ordinary message (LoadError is a ScriptError, outside StandardError).
+begin
+  require "json"
+  require "time"
+  require "tmpdir"
+  require "yaml"
+  require_relative "lib/message_display"
+rescue ScriptError, StandardError
+  exit 0
+end
+
+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