@zalom/plastic 2.0.0-alpha.2 → 2.0.0-alpha.20

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,7 +79,9 @@ 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"
+require_relative "lib/outcome_report"
 
 DISPOSITIONS = %w[delivered abandoned].freeze
 
@@ -99,6 +103,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 +120,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
@@ -171,6 +177,64 @@ def resolve_plastic_home_and_scope(store)
   end
 end
 
+# --- outcome generation, before the backfill (intent 339, G6, spec D10) -----
+#
+# Generates outcome.md from graph.md, nodes/, and the ledger, BEFORE the
+# backfill step runs, and only into a file that is missing or still the
+# scaffold placeholder (`Savepoint.stage_file_present?` false) - a real,
+# hand-written outcome.md is never touched (row 7.2). Only when a graph.md
+# exists at all (row 7.3): every intent without one closes exactly as it did
+# before this intent. The model is parsed AFTER the `stage_file_present?`
+# guard, not before: a real hand-written outcome.md returns at that guard
+# regardless of graph.md's own health, so a close that was never going to
+# generate anything must never print a parse warning about it. Refuses a
+# report model that reports itself broken (row v1f.2, B2): a malformed
+# `## Graph` fails `model[:ok]` and the close falls straight through to the
+# backfill, rather than adopting parse damage as delivery fact - agreeing
+# with the shipped `outcome-report` CLI, which exits 3 on the same
+# directory. The generated text is then checked against
+# BOTH close gates - `OutcomeGuard` and the hollow-report gate below - before
+# being adopted (row 7.4); when either would refuse it, the write is
+# reverted and the close falls through to intent 308's unchanged backfill
+# (row 7.5), so no close gains an exit 7 it did not have before this intent.
+# Fails open on any exception (row 7.6), the same report-and-proceed shape
+# every other close step in this file uses. `generator:` is the injectable
+# seam (mirrors run_structure_check's `gate:`).
+def run_generate_outcome(intent_dir, disposition:, generator: OutcomeReport.method(:write))
+  graph_path = File.join(intent_dir, "graph.md")
+  return unless File.exist?(graph_path)
+
+  outcome_path = File.join(intent_dir, "outcome.md")
+  return if Savepoint.stage_file_present?(outcome_path)
+
+  report_model = OutcomeReport.model(intent_dir)
+  unless report_model[:ok]
+    warn "end-intent: graph.md failed to parse (#{report_model[:errors].join('; ')}); falling back to the backfill"
+    return
+  end
+
+  original_exists = File.exist?(outcome_path)
+  original_content = original_exists ? File.read(outcome_path) : nil
+
+  generator.call(intent_dir, disposition: disposition)
+
+  guard_reason = OutcomeGuard.reason(intent_dir, disposition)
+  hollow = hollow_report_reason(intent_dir, disposition)
+  if guard_reason || hollow
+    if original_exists
+      File.write(outcome_path, original_content)
+    elsif File.exist?(outcome_path)
+      File.delete(outcome_path)
+    end
+    warn "end-intent: generated outcome.md would be refused (#{[guard_reason, hollow].compact.join('; ')}); " \
+         "falling back to the backfill"
+  else
+    warn "end-intent: outcome.md generated from graph.md and the ledger"
+  end
+rescue StandardError => e
+  warn "end-intent: outcome generation crashed (#{e.message}); proceeding without it"
+end
+
 # Backfill (intent 308): write the judgment documents that are missing or still the
 # placeholder from the record (BackfillIntent). Fail-open: a crash here warns and the
 # close proceeds, the same contract as the structure check below.
@@ -215,7 +279,137 @@ 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.
+#
+# Intent 334 (G1, fold A3; post-execution review, blocking 2): the legacy
+# "S3" label grammar applies only to actions/*.md headings, and the node id
+# grammar (kind prefix n/v/d/r plus digits, D1r) applies only to nodes/*.md
+# headings - never both over both directories. This repo's own house words
+# for plan review and post-execution review are "v1" and "v2"; widening the
+# node-id alternative onto actions/ headings turned that prose into a
+# manufactured label and refused legitimate legacy closes at exit 7.
+ACTION_ID_LABEL_RE = /\AS\d+\z/.freeze
+NODE_ID_LABEL_RE = /\A[nvdr][1-9]\d*\z/.freeze
+
+# The id-shaped tokens found in `paths`' headings, matched against
+# `id_label_re` only - the caller picks the grammar for the directory.
+def heading_id_labels(paths, id_label_re)
+  paths.flat_map do |path|
+    ReportScreen.split_by_headings(File.read(path)).flat_map do |heading, _body|
+      heading.to_s.sub(/\A#+\s*/, "").split(/[^A-Za-z0-9]+/).select { |tok| tok.match?(id_label_re) }
+    end
+  end
+end
+
+# 339 S9 (D18): a node id counts as a label in an actions/*.md heading too,
+# but only when it stands alone as one of the heading's " - "-delimited
+# segments - this repo's own convention, "### S1 - n1 - Title" (this action
+# file's own headings, post-fold) or the bare "### n1 - Title". Never as a
+# free word inside ordinary prose: the comment above ACTION_ID_LABEL_RE
+# records exactly why intent 334 restricted the node-id grammar to
+# nodes/*.md headings in the first place, and that reasoning does not change
+# here - a word-scan widened onto actions/ headings would let this repo's own
+# house words ("v1", "v2" for plan review and post-execution review)
+# manufacture a label out of ordinary prose and refuse a legitimate legacy
+# close. Segment position is what a word-scan cannot see: "v2" embedded
+# mid-sentence is never its own " - "-delimited segment, but a heading built
+# to this convention always puts the node id in one.
+def heading_node_id_segments(paths, id_label_re)
+  paths.flat_map do |path|
+    ReportScreen.split_by_headings(File.read(path)).flat_map do |heading, _body|
+      heading.to_s.sub(/\A#+\s*/, "").split(/\s+-\s+/).map(&:strip).select { |seg| seg.match?(id_label_re) }
+    end
+  end
+end
+
+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 a
+  # labeled convention - at least one actions/*.md heading carrying an
+  # S-label or a node-id segment, or at least one nodes/*.md heading carrying
+  # a node id ("n1", "v2", "d3", "r4"). A terse legacy close with no labeled
+  # matrix stays report-and-proceed (intent 334, G1, D10r).
+  #
+  # Every matching token per heading is kept, not just the first (fold A3):
+  # a legacy actions/ heading can carry BOTH an S-label and prose that reads
+  # like a node id ("### The v2 rewrite (S3)"). Restricting the word-scan
+  # node-id grammar to nodes/*.md headings (post-execution review, blocking
+  # 2) means "v2" in that heading is never even tested against it, so the
+  # heading's real "S3" label is never at risk.
+  #
+  # 339 S9 (D18): a graph-era action file headed by node id alone ("### n1 -
+  # Title", no S-label) used to yield an empty label set here and the gate
+  # returned before judging anything - every such record closed unjudged by
+  # silent exemption. `heading_node_id_segments` widens the actions/*.md side
+  # to see that shape without reopening the word-scan hole above: it matches
+  # a node id only when the heading's own " - "-delimited segments carry one,
+  # never a free word in prose. The node_paths call stays exactly as it was;
+  # nodes/*.md headings already resolve node ids correctly (test_node_id_
+  # labels_are_recognized) and their heading grammar is controlled, so a
+  # word-scan there carries none of the prose risk.
+  action_paths = Dir.glob(File.join(intent_dir, "actions", "*.md")).sort
+  node_paths = Dir.glob(File.join(intent_dir, "nodes", "*.md")).sort
+  heading_labels = (heading_id_labels(action_paths, ACTION_ID_LABEL_RE) +
+                     heading_node_id_segments(action_paths, NODE_ID_LABEL_RE) +
+                     heading_id_labels(node_paths, NODE_ID_LABEL_RE)).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
@@ -645,6 +839,11 @@ def main(argv)
     end
   end
 
+  # 0a. Generate outcome.md from graph.md and the ledger, when there is one
+  # (intent 339, G6, spec D10) - before the backfill, so a real graph never
+  # falls through to the terse backfill it exists to replace.
+  run_generate_outcome(intent_dir, disposition: disposition)
+
   # 1. Backfill from the record (intent 308), then the structure self-check and the
   # outcome guard, both report-only since 308.
   run_backfill(intent_dir, store: store, id: id, disposition: disposition,
@@ -654,6 +853,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

@@ -5,12 +5,11 @@
 # Usage: hook-capture (reads the UserPromptSubmit stdin JSON payload)
 # Intent 298. One UserPromptSubmit process replacing hook-continue,
 # hook-future-intent-check, and hook-auto-arm: it appends a pending line to
-# the session day ledger, detects "continue" and "auto" prompts, and hints at
-# matching Future intents. Every job runs in its own rescue and the hook
-# always exits 0 (spec D2).
+# the session day ledger and detects "continue" and "auto" prompts. Every job
+# runs in its own rescue and the hook always exits 0 (spec D2). Intent 345
+# (D7, 323) removed the per-prompt Future-intent hint step entirely.
 
 require "json"
-require "yaml"
 require "open3"
 require "fileutils"
 require_relative "lib/session_ledger"
@@ -31,7 +30,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?
 
@@ -41,98 +41,26 @@ templates = File.expand_path("../templates", __dir__)
 sid = SessionLedger.short_session_id(nil, session_id)
 today = SessionLedger.day_id
 
-# --- Extracted matching logic, shared by both the global and project store
-# passes of job (f) below (mirrors hook-future-intent-check verbatim). ---
-def future_intent_matches(store_root, message)
-  index_path = File.join(store_root, "INDEX.md")
-  return [] unless File.exist?(index_path)
-
-  lines = File.readlines(index_path)
-  future_dirs = []
-  section = nil
-
-  lines.each do |line|
-    section = :future if line.start_with?("## Future")
-    section = nil if line.start_with?("## ") && !line.start_with?("## Future")
-    next unless section == :future && line.strip.start_with?("- [")
-
-    future_dirs << $1 if line =~ /store\/([\w-]+)\//
-  end
-  return [] if future_dirs.empty?
-
-  matches = []
-  message_words = message.split(/\W+/).reject { |w| w.length < 4 }
-
-  future_dirs.each do |dir|
-    intent_path = File.join(store_root, "store", dir, "#{dir}.md")
-    next unless File.exist?(intent_path)
-
-    content = File.read(intent_path)
-
-    tags = []
-    tags = $1.split(",").map(&:strip).map(&:downcase) if content =~ /^tags:\s*\[([^\]]+)\]/
-
-    intent_name = ""
-    intent_name = $1.downcase if content =~ /^intent:\s*["']?(.+?)["']?\s*$/
-
-    keywords = (tags + intent_name.split(/\W+/).reject { |w| w.length < 4 }).map(&:downcase).uniq
-
-    matched_keywords = keywords.select { |kw| message.include?(kw) }
-    name_matches = message_words.select { |w| intent_name.include?(w) }
-    matched_keywords = (matched_keywords + name_matches).uniq
-
-    next if matched_keywords.empty?
-
-    index_line = lines.find { |l| l.include?(dir) }&.strip || "#{dir} - #{intent_name}"
-    matches << { "index_line" => index_line, "keywords" => matched_keywords }
-  end
-  matches
-end
-
-# The store_root that carries the current project's own store, resolved from
-# cwd through projects.yml, mirroring SessionLedger.project_slug's matching
-# but returning nil (not "global") when nothing matches, since there is then
-# no distinct second store to hint against.
-def resolve_project_store_root(cwd, plastic_home)
-  projects_path = File.join(plastic_home, "projects.yml")
-  return nil unless File.exist?(projects_path)
-
-  data = begin
-    YAML.safe_load(File.read(projects_path))
-  rescue StandardError
-    nil
-  end
-  data = {} unless data.is_a?(Hash)
-  projects = data["projects"].is_a?(Hash) ? data["projects"] : {}
-  expanded_cwd = File.expand_path(cwd)
-
-  matches = projects.filter_map do |slug, info|
-    next unless info.is_a?(Hash) && slug.is_a?(String)
-
-    path = info["path"]
-    next unless path
-
-    root = File.expand_path(path)
-    next unless expanded_cwd == root || expanded_cwd.start_with?("#{root}#{File::SEPARATOR}")
-
-    [root.length, slug]
-  end
-
-  best = matches.max_by { |(length, _slug)| length }
-  best ? File.join(plastic_home, "projects", best[1]) : nil
-end
-
 def truncate(text, max)
   return text if text.length <= 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 +78,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,
@@ -170,7 +101,7 @@ system_message = nil
 
 # --- (d) "continue" cockpit -------------------------------------------------
 begin
-  if prompt.match?(/\bcontinue\b/i)
+  if prompt.to_s.strip.downcase == "continue"
     dashboard = File.expand_path("dashboard.rb", __dir__)
     if File.exist?(dashboard)
       cockpit, _err, status = Open3.capture3({ "RUBYOPT" => nil }, "ruby", dashboard, "continue")
@@ -211,25 +142,6 @@ rescue StandardError
   nil
 end
 
-# --- (f) Future-intent hint, global store then the project's own store -----
-begin
-  message = prompt.to_s.downcase
-  if message.strip.length >= 10 && message.strip != "continue"
-    matches = future_intent_matches(plastic_home, message)
-    project_root = resolve_project_store_root(cwd, plastic_home)
-    matches += future_intent_matches(project_root, message) if project_root
-
-    if matches.any?
-      parts = ["PLASTIC - Future intents related to this message:\n"]
-      matches.each { |m| parts << "#{m["index_line"]} (matched: #{m["keywords"].join(", ")})" }
-      parts << "\nConsider asking the user if they want to activate any of these, or note the connection."
-      context_parts << parts.join("\n")
-    end
-  end
-rescue StandardError
-  nil
-end
-
 exit 0 if context_parts.empty?
 
 payload_out = {

package/scripts/hook-message-display

@@ -0,0 +1,81 @@
+#!/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")
+
+    # PLASTIC_HOOK_TRACE=<file> (331a1): opt-in, off by default, one JSON
+    # object appended per chunk. This script is the only place allowed to
+    # read the environment; MessageDisplay takes the sink as an argument.
+    trace_path = ENV["PLASTIC_HOOK_TRACE"].to_s
+    trace = trace_path.empty? ? nil : MessageDisplay.file_trace(trace_path)
+
+    handler = MessageDisplay.new(
+      tmp_root: tmp_root,
+      plastic_home: plastic_home,
+      color: color_enabled?(plastic_home),
+      now: Time.now,
+      trace: trace,
+    )
+    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/index-projection

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# index-projection - the CLI over IndexProjection (intent 337, G4): prints
+# the drift between INDEX.md and the intent ledgers for one store root
+# (INDEX.md plus a store/ directory), exits non-zero when any drift exists.
+# --write renders INDEX.md's four status sections from the projection
+# through AtomicWrite; every other byte, including ## Clusters and
+# ## Relocated, is untouched.
+#
+# Usage:
+#   index-projection <store_root> [--write]
+#
+# Exit codes:
+#   0 - no drift (or, with --write, the write landed cleanly)
+#   1 - drift exists (a real terminal-ledger conflict, an INDEX entry with
+#       no directory, or a directory INDEX does not list)
+#   2 - usage: no argument, or the path is not a store root
+
+require_relative "lib/index_projection"
+
+module IndexProjectionCli
+  module_function
+
+  def usage
+    warn "Usage: index-projection <store_root> [--write]"
+  end
+
+  def main(argv)
+    args = argv.dup
+    write = !!args.delete("--write")
+
+    root = args.shift
+    unless root && Dir.exist?(root)
+      warn "index-projection: #{root.inspect} is not a store root"
+      usage
+      return 2
+    end
+
+    index_path = File.join(root, "INDEX.md")
+    store_dir = File.join(root, "store")
+    unless File.exist?(index_path)
+      warn "index-projection: no INDEX.md at #{index_path}"
+      return 2
+    end
+
+    if write
+      result = IndexProjection.write(store_dir, index_path: index_path)
+      unless result[:ok]
+        warn "index-projection: #{result[:error]}"
+        return 2
+      end
+      puts "index-projection: wrote #{index_path} (#{result[:moved].length} moved)"
+      return 0
+    end
+
+    analysis = IndexProjection.analyze(store_dir, index_path: index_path)
+    print_report(analysis)
+
+    (analysis[:drift].empty? && analysis[:index_only].empty? && analysis[:directory_only].empty?) ? 0 : 1
+  end
+
+  def print_report(analysis)
+    puts "Drift (#{analysis[:drift].length}):"
+    analysis[:drift].each { |r| puts "  #{r[:id]}: INDEX=#{r[:index_status]} ledger=#{r[:ledger_status]}" }
+    puts "INDEX-only (#{analysis[:index_only].length}):"
+    analysis[:index_only].each { |r| puts "  #{r[:id]} (#{r[:index_status]})" }
+    puts "Directory-only (#{analysis[:directory_only].length}):"
+    analysis[:directory_only].each { |r| puts "  #{r[:id]}" }
+  end
+end
+
+exit(IndexProjectionCli.main(ARGV)) if $PROGRAM_NAME == __FILE__