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

package/bin/lib/context_budget.rb

@@ -0,0 +1,453 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "json"
+require "open3"
+require "rbconfig"
+require "tmpdir"
+require "yaml"
+
+# ContextBudget (intent 313): the measurement behind Plastic's two ruled context
+# numbers. Intent 296 ruled the core block under 8,192 bytes and the whole
+# per-boot doctrine read under 15,000, and until this module both were estimates
+# in a design document. Everything here is measured: the bench builds a fixture
+# home by running the real installer into a temporary HOME, runs the real
+# `scripts/hook-session-start` against it N times, and reports what a boot
+# actually costs.
+#
+# Maintainer tool. It lives under bin/ beside bin/test, is never registered in
+# installer_core.rb, and is never installed into ~/.plastic: it reads repo
+# fixtures, so it has no meaning on an installed copy.
+#
+# Hermetic and DI throughout: every path is a keyword argument, the boot
+# subprocess's environment is a pure function of the fixture, and the runner is
+# injectable. Nothing reads the real ~/.plastic or ~/.claude, and nothing here
+# touches the network.
+module ContextBudget
+  # The two ruled ceilings (intent 296) plus the one ratchet intent 313 adds.
+  #
+  #   core              PLASTIC.md, the always-on core block. 296's ruling.
+  #   boot              the additionalContext hook-session-start emits. 296's
+  #                     whole-read ruling, enforced on the only quantity that is
+  #                     actually read on every boot and can be measured exactly.
+  #   boot_plus_catalog boot injection plus the skill catalog the harness loads.
+  #                     Not a ruling: a 313 ratchet over the measured 16,537, so
+  #                     the second-largest per-boot cost cannot regrow unwatched.
+  #                     Lower it as the catalog shrinks; never raise it.
+  CEILINGS = { core: 8_192, boot: 15_000, boot_plus_catalog: 17_500 }.freeze
+
+  # The doctrine working set (boot + _decision-tables.md + the median skill body)
+  # is reported against this target, never enforced: its median term steps by
+  # about a kilobyte whenever a skill is added or removed, so a suite that went
+  # red on that step would enforce nothing anybody ruled. The gap is printed.
+  WORKING_SET_TARGET = 15_000
+
+  DEFAULT_REPEAT = 5
+
+  # Fixed inputs. The stale-intent line renders an age, so the fixture's future
+  # intents are created this many days before *today*: the rendered "(30 days)"
+  # is then a constant instead of a number that drifts with the calendar.
+  FIXTURE_STALE_DAYS = 30
+  FIXTURE_SESSION_ID = "plastic-context-bench"
+
+  # What the fixture deliberately leaves out of the measurement, printed with the
+  # table so a reader knows what the number does not cover.
+  EXCLUSIONS = [
+    "the update notice and the prior-day sweep line (both transient, absent from a steady-state boot)",
+    "the QMD status line (PATH carries only the running interpreter's directory, so qmd is unfindable on any host)",
+    "the harness's own system prompt and tool schemas (not Plastic's, and not readable from here)",
+  ].freeze
+
+  Measurement = Struct.new(:lines, :words, :tokens, :bytes, :tokens_by_bytes)
+
+  # The word-based token estimate is skill_lint.rb:104's arithmetic exactly, so
+  # the bench and skill-lint can never report different numbers for one file.
+  # bytes / 4 is a second, independent estimate printed for cross-check. Neither
+  # is a tokenizer; both are deterministic and offline.
+  def self.measure(body)
+    words = body.split(/\s+/).reject(&:empty?).length
+    Measurement.new(body.lines.count, words, (words * 1.3).round,
+                    body.bytesize, (body.bytesize / 4.0).round)
+  end
+
+  # skill_lint.rb:82-90's split, so a skill's frontmatter is counted once (in the
+  # catalog row) and its body once (in the median-body row), never both.
+  def self.split_skill(content)
+    parts = content.split("---", 3)
+    return [nil, content] if parts.length < 3
+
+    [parts[1], parts[2]]
+  end
+
+  def self.skill_paths(repo:)
+    Dir.glob(File.join(repo, "skills", "*", "SKILL.md")).sort
+  end
+
+  # What the harness loads at boot: every skill's name and description VALUES,
+  # YAML-parsed. Not the raw frontmatter (that would count the keys and the
+  # operational fields), and not a line regex (that would truncate a folded
+  # description at its first line).
+  def self.skill_catalog_bytes(repo:)
+    skill_paths(repo: repo).sum do |path|
+      frontmatter, = split_skill(File.read(path))
+      data = YAML.safe_load(frontmatter.to_s, permitted_classes: [Date, Time], aliases: true) || {}
+      data["name"].to_s.bytesize + data["description"].to_s.bytesize
+    end
+  end
+
+  def self.skill_body_sizes(repo:)
+    skill_paths(repo: repo).map do |path|
+      _frontmatter, body = split_skill(File.read(path))
+      body.bytesize
+    end
+  end
+
+  def self.median(values)
+    return 0 if values.empty?
+
+    sorted = values.sort
+    middle = sorted.length / 2
+    return sorted[middle] if sorted.length.odd?
+
+    ((sorted[middle - 1] + sorted[middle]) / 2.0).round
+  end
+
+  # A fixed Plastic home: a real install, then a fixed store on top of it.
+  #
+  # The install matters. A fixture without ~/.claude fails
+  # Doctor#check_agent_registration (doctor_core.rb:307-314), which short-circuits
+  # the rest of the core checks and renders the degraded banner, measuring a boot
+  # no real session sees. Running the real installer costs about a quarter of a
+  # second and gives `doctor --core run: success`.
+  Fixture = Struct.new(:home, :plastic_home, :index, :project_dir, keyword_init: true) do
+    def self.build(dir:, repo:, today: Date.today)
+      ContextBudget.build_fixture(dir: dir, repo: repo, today: today)
+    end
+  end
+
+  def self.build_fixture(dir:, repo:, today: Date.today)
+    home = File.realpath(dir)
+    plastic_home = File.join(home, ".plastic")
+    FileUtils.mkdir_p(File.join(home, ".claude"))
+    install_into(home: home, plastic_home: plastic_home, repo: repo)
+
+    project_dir = File.join(home, "project")
+    FileUtils.mkdir_p(project_dir)
+    # On macOS Dir.pwd resolves /var to /private/var. The hook compares Dir.pwd
+    # against the registered project path with start_with?, so an unresolved path
+    # silently loses the project banner from the measured context.
+    project_dir = File.realpath(project_dir)
+
+    write_global_store(plastic_home: plastic_home, today: today)
+    write_project_store(plastic_home: plastic_home, project_dir: project_dir, today: today)
+
+    Fixture.new(home: home, plastic_home: plastic_home,
+                index: File.join(plastic_home, "INDEX.md"), project_dir: project_dir)
+  end
+
+  def self.install_into(home:, plastic_home:, repo:)
+    installer = File.join(repo, "scripts", "install.rb")
+    raise "install: #{installer} not found; #{repo} is not a Plastic checkout" unless File.file?(installer)
+
+    env = { "HOME" => home, "PLASTIC_HOME" => plastic_home, "RUBYOPT" => nil }
+    out, err, status = Open3.capture3(env, RbConfig.ruby, installer, "--claude", chdir: repo)
+    return if status.success?
+
+    raise "install failed (exit #{status.exitstatus}): #{err.strip}#{out.strip}"
+  end
+
+  # Intent ids are written one call per intent, never as one array literal:
+  # packaging_no_store_ids_test.rb flags any shipped literal carrying five or
+  # more digit-leading tokens, and bin/ is inside package.json's files set.
+  def self.write_global_store(plastic_home:, today:)
+    store = File.join(plastic_home, "store")
+    write_intent(store, "0001", "a-global-intent-in-flight", 1, today)
+    write_intent(store, "0002", "a-parked-global-intent", FIXTURE_STALE_DAYS, today)
+    write_intent(store, "0003", "another-parked-global-intent", FIXTURE_STALE_DAYS, today)
+
+    File.write(File.join(plastic_home, "INDEX.md"), <<~MD)
+      # Index
+
+      ## Active
+      #{index_line("0001", "a-global-intent-in-flight", "a global intent that is being delivered right now")}
+
+      ## Future
+      #{index_line("0002", "a-parked-global-intent", "a parked global intent waiting on a ruling")}
+      #{index_line("0003", "another-parked-global-intent", "another parked global intent waiting on a ruling")}
+    MD
+  end
+
+  def self.write_project_store(plastic_home:, project_dir:, today:)
+    project_root = File.join(plastic_home, "projects", "fixture")
+    store = File.join(project_root, "store")
+    write_intent(store, "0100", "a-project-intent-in-flight", 1, today)
+    write_intent(store, "0101", "a-parked-project-intent", FIXTURE_STALE_DAYS, today)
+
+    File.write(File.join(project_root, "INDEX.md"), <<~MD)
+      # Index
+
+      ## Active
+      #{index_line("0100", "a-project-intent-in-flight", "a project intent that is being delivered right now")}
+
+      ## Future
+      #{index_line("0101", "a-parked-project-intent", "a parked project intent waiting for a decision")}
+    MD
+
+    registration = { "projects" => { "fixture" => { "path" => project_dir, "parent" => nil } } }
+    File.write(File.join(plastic_home, "projects.yml"), YAML.dump(registration))
+  end
+
+  def self.index_line(id, slug, title)
+    "- [#{id} — #{title}](store/#{id}--#{slug}/#{id}--#{slug}.md)"
+  end
+
+  def self.write_intent(store, id, slug, age_days, today)
+    dir = File.join(store, "#{id}--#{slug}")
+    FileUtils.mkdir_p(dir)
+    File.write(File.join(dir, "#{id}--#{slug}.md"), <<~MD)
+      ---
+      id: "#{id}"
+      created: #{(today - age_days).iso8601}
+      author: bench
+      ---
+
+      ## Intent
+      A fixed fixture intent, so the bench measures the same boot every time.
+    MD
+  end
+
+  # The child environment is a pure function of the fixture, so a test can assert
+  # containment without running anything.
+  #
+  # PATH is exactly the running interpreter's directory, and that is load-bearing
+  # twice. The hook backticks scripts/read-config three times and read-config's
+  # shebang is `#!/usr/bin/env ruby`, so a PATH carrying /usr/bin would run those
+  # three reads under the system Ruby while the report named a different one. And
+  # with nothing else on PATH, `qmd` cannot be found on any host, so the QMD
+  # status line never appears and the measurement reproduces off this machine.
+  def self.child_env(fixture)
+    {
+      "HOME" => fixture.home,
+      "PLASTIC_HOME" => fixture.plastic_home,
+      "PLASTIC_TMP" => File.join(fixture.home, "tmp"),
+      "CLAUDE_CODE_SESSION_ID" => FIXTURE_SESSION_ID,
+      "PATH" => File.dirname(RbConfig.ruby),
+      "RUBYOPT" => nil,
+    }
+  end
+
+  DEFAULT_RUNNER = lambda do |env, *command, **options|
+    Open3.capture3(env, *command, **options)
+  end
+
+  # Runs the real hook once. Returns [additionalContext, elapsed_ms]. A failed or
+  # empty boot raises rather than scoring as a small, passing number.
+  def self.boot(fixture:, repo:, runner: DEFAULT_RUNNER)
+    hook = File.join(repo, "scripts", "hook-session-start")
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    out, err, status = runner.call(child_env(fixture), RbConfig.ruby, hook,
+                                   fixture.index, fixture.plastic_home, "global", repo,
+                                   chdir: fixture.project_dir)
+    elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(1)
+
+    raise "boot failed (exit #{status.exitstatus}): #{err.strip}" unless status.success?
+    raise "boot wrote to stderr: #{err.strip}" unless err.to_s.strip.empty?
+
+    context = JSON.parse(out).dig("hookSpecificOutput", "additionalContext").to_s
+    raise "boot emitted no additionalContext" if context.empty?
+
+    [context, elapsed_ms]
+  end
+
+  Sample = Struct.new(:bytes, :ms, keyword_init: true)
+
+  Row = Struct.new(:key, :label, :bytes, :tokens, :tokens_by_bytes, :ceiling, :target, keyword_init: true) do
+    def enforced?
+      !ceiling.nil?
+    end
+
+    # The ceiling is a strict bound: "under 8,192" means 8,192 itself is over.
+    def over?
+      enforced? && bytes >= ceiling
+    end
+
+    def headroom
+      enforced? ? ceiling - bytes : nil
+    end
+
+    def gap
+      target.nil? ? nil : bytes - target
+    end
+  end
+
+  Report = Struct.new(:rows, :samples, :context, :repeat, :fragment, :ruby_version, :ruby_bin, keyword_init: true) do
+    def row(key)
+      rows.find { |candidate| candidate.key == key }
+    end
+
+    def byte_spread
+      samples.map(&:bytes).max - samples.map(&:bytes).min
+    end
+
+    def failures
+      crossed = rows.select(&:over?).map do |candidate|
+        "#{candidate.key} (#{candidate.label}) is #{candidate.bytes} bytes; ceiling #{candidate.ceiling}"
+      end
+      return crossed if byte_spread.zero?
+
+      crossed + ["byte spread across #{repeat} repeats is #{byte_spread}, expected 0"]
+    end
+
+    def ok?
+      failures.empty?
+    end
+
+    def to_table
+      ContextBudget.render(self)
+    end
+  end
+
+  def self.run(repo:, repeat: DEFAULT_REPEAT, core_file: nil, dir: nil, today: Date.today)
+    unless repeat.is_a?(Integer) && repeat >= 1
+      raise ArgumentError, "repeat must be an integer of at least 1 (got #{repeat.inspect})"
+    end
+
+    return report_for(dir: dir, repo: repo, repeat: repeat, core_file: core_file, today: today) if dir
+
+    Dir.mktmpdir("plastic-context-bench") do |tmp|
+      report_for(dir: tmp, repo: repo, repeat: repeat, core_file: core_file, today: today)
+    end
+  end
+
+  def self.report_for(dir:, repo:, repeat:, core_file:, today:)
+    fixture = Fixture.build(dir: dir, repo: repo, today: today)
+    # --core-file swaps the core block so a crossed ceiling can be observed
+    # without editing a real file. check_core_files runs with include_drift:
+    # false, so the swap does not change the banner.
+    FileUtils.cp(core_file, File.join(fixture.plastic_home, "PLASTIC.md")) if core_file
+
+    contexts = []
+    samples = repeat.times.map do
+      context, elapsed_ms = boot(fixture: fixture, repo: repo)
+      contexts << context
+      Sample.new(bytes: context.bytesize, ms: elapsed_ms)
+    end
+
+    Report.new(rows: build_rows(fixture: fixture, repo: repo, context: contexts.first),
+               samples: samples, context: contexts.first, repeat: repeat,
+               fragment: fragment_bytes(repo: repo),
+               ruby_version: RUBY_VERSION, ruby_bin: RbConfig.ruby)
+  end
+
+def self.build_rows(fixture:, repo:, context:)
+  core = measure(File.read(File.join(fixture.plastic_home, "PLASTIC.md")))
+  boot_measurement = measure(context)
+  catalog = measure(skill_catalog_text(repo: repo))
+  bodies = skill_body_sizes(repo: repo)
+  median_body = median(bodies)
+  fragment = fragment_bytes(repo: repo)
+
+  combined = boot_measurement.bytes + catalog.bytes
+  working_set = boot_measurement.bytes + fragment + median_body
+
+  # tokens(w) is a word count of a real body, so the rows that are arithmetic
+  # over other rows (a sum, a median) print "-" there rather than a number that
+  # looks measured and is not. Every row still carries bytes and bytes / 4.
+  [
+    row(:core, "core block (PLASTIC.md)", core.bytes, tokens: core.tokens, ceiling: CEILINGS[:core]),
+    row(:boot, "boot injection (SessionStart additionalContext)", boot_measurement.bytes,
+        tokens: boot_measurement.tokens, ceiling: CEILINGS[:boot]),
+    row(:skill_catalog, "skill catalog (#{bodies.length} name + description values)",
+        catalog.bytes, tokens: catalog.tokens),
+    row(:boot_plus_catalog, "boot injection + skill catalog", combined,
+        ceiling: CEILINGS[:boot_plus_catalog]),
+    row(:median_skill_body, "median skill body (of #{bodies.length})", median_body),
+    row(:working_set, "doctrine working set (boot + fragment + median body)",
+        working_set, target: WORKING_SET_TARGET),
+  ]
+end
+
+# The catalog as one body, so its word-token estimate is measured the same way
+# every other body's is.
+def self.skill_catalog_text(repo:)
+  skill_paths(repo: repo).map do |path|
+    frontmatter, = split_skill(File.read(path))
+    data = YAML.safe_load(frontmatter.to_s, permitted_classes: [Date, Time], aliases: true) || {}
+    "#{data["name"]}#{data["description"]}"
+  end.join
+end
+
+  def self.fragment_bytes(repo:)
+    path = File.join(repo, "skills", "_decision-tables.md")
+    File.file?(path) ? File.size(path) : 0
+  end
+
+def self.row(key, label, bytes, tokens: nil, ceiling: nil, target: nil)
+  Row.new(key: key, label: label, bytes: bytes, tokens: tokens,
+          tokens_by_bytes: (bytes / 4.0).round, ceiling: ceiling, target: target)
+end
+
+  def self.render(report)
+    byte_samples = report.samples.map(&:bytes)
+    ms_samples = report.samples.map(&:ms)
+
+    lines = []
+    lines << "Plastic context budget bench (intent 313)"
+    lines << ""
+    lines << "  ruby      #{report.ruby_version}  (#{report.ruby_bin})"
+    lines << "  repeats   #{report.repeat}  boot bytes min/median/max #{stat_line(byte_samples)}"
+    lines << "  time      ms min/median/max #{stat_line(ms_samples)} - indicative only, never a pass/fail signal"
+    lines << "  fixture   a real `scripts/install.rb --claude` into a temporary HOME, then a fixed store"
+    lines << "            (1 active + 2 future global intents, 1 active + 1 future project intents)"
+    lines << "  estimator words * 1.3 (skill-lint's arithmetic) as tokens(w); bytes / 4 as tokens(b) - neither is a tokenizer"
+    lines << ""
+    lines << format("  %-52s %8s %9s %9s %9s %9s", "row", "bytes", "tokens(w)", "tokens(b)", "ceiling", "headroom")
+
+    report.rows.each do |current|
+      ceiling = current.enforced? ? current.ceiling.to_s : "reported"
+      headroom = current.enforced? ? current.headroom.to_s : "-"
+      lines << format("  %-52s %8d %9s %9d %9s %9s",
+                      current.label, current.bytes, current.tokens || "-", current.tokens_by_bytes,
+                      ceiling, headroom)
+    end
+
+    working_set = report.row(:working_set)
+    if working_set&.target
+      lines << ""
+      lines << "  The doctrine working set is reported against intent 296's ruled target of " \
+               "#{working_set.target} bytes, not enforced:"
+      lines << "  it stands at #{working_set.bytes} (#{format('%+d', working_set.gap)} against the target), " \
+               "where the fragment is #{report.fragment} bytes."
+      lines << "  Its median term steps by about a kilobyte whenever a skill is added or removed; " \
+               "the skill bodies are the gap."
+    end
+
+    lines << ""
+    lines << "  Not counted:"
+    EXCLUSIONS.each { |exclusion| lines << "  - #{exclusion}" }
+
+    lines << ""
+    if report.ok?
+      lines << "  PASS - every ceiling holds and the #{report.repeat} repeats are byte-identical."
+    else
+      lines << "  FAIL"
+      report.failures.each { |failure| lines << "  - #{failure}" }
+    end
+
+    lines.join("\n") + "\n"
+  end
+
+  def self.stat_line(values)
+    sorted = values.sort
+    "#{sorted.first}/#{median_of_samples(sorted)}/#{sorted.last}"
+  end
+
+  def self.median_of_samples(sorted)
+    middle = sorted.length / 2
+    return sorted[middle] if sorted.length.odd?
+
+    ((sorted[middle - 1] + sorted[middle]) / 2.0).round(1)
+  end
+end

package/bin/plastic-bench

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Plastic context budget bench (intent 313). Measures what a session boot costs
+# in context: the core block, the SessionStart injection, the skill catalog the
+# harness loads beside it, and the doctrine working set. Exits non-zero when a
+# ceiling is crossed or when repeated boots of a fixed fixture disagree.
+#
+# Maintainer tool: it reads this repository's own files and a fixture home it
+# builds with the real installer, so it is never installed into ~/.plastic.
+#
+# Usage: bin/plastic-bench [--repeat N] [--core-file PATH] [--repo PATH]
+#
+#   --repeat N       boots to run (default 5, minimum 1)
+#   --core-file PATH measure this file as the core block instead of the repo's
+#                    PLASTIC.md; the way a crossed ceiling is proved observable
+#                    without editing a real file
+#   --repo PATH      the Plastic checkout to measure (default: this one)
+#
+# Exit codes: 0 every ceiling holds, 1 a ceiling was crossed, 2 bad usage.
+
+require_relative "lib/context_budget"
+
+USAGE = <<~TEXT
+  usage: plastic-bench [--repeat N] [--core-file PATH] [--repo PATH]
+
+    --repeat N        boots to run against the fixture (default #{ContextBudget::DEFAULT_REPEAT}, minimum 1)
+    --core-file PATH  measure this file as the core block instead of PLASTIC.md
+    --repo PATH       the Plastic checkout to measure (default: this checkout)
+    --help            this message
+
+  Exits 0 when every ceiling holds, 1 when one is crossed, 2 on bad usage.
+TEXT
+
+def fail_usage(message)
+  warn "plastic-bench: #{message}"
+  warn USAGE
+  exit 2
+end
+
+repeat = ContextBudget::DEFAULT_REPEAT
+core_file = nil
+repo = File.expand_path("..", __dir__)
+
+argv = ARGV.dup
+until argv.empty?
+  case (flag = argv.shift)
+  when "--help", "-h"
+    puts USAGE
+    exit 0
+  when "--repeat"
+    value = argv.shift
+    fail_usage("--repeat needs a whole number of at least 1") unless value.to_s.match?(/\A\d+\z/)
+    repeat = value.to_i
+    fail_usage("--repeat needs a whole number of at least 1") if repeat < 1
+  when "--core-file"
+    core_file = argv.shift
+    fail_usage("--core-file needs a path") if core_file.to_s.empty?
+    fail_usage("--core-file #{core_file} does not exist") unless File.file?(core_file)
+  when "--repo"
+    repo = argv.shift
+    fail_usage("--repo needs a path") if repo.to_s.empty?
+    fail_usage("--repo #{repo} is not a directory") unless File.directory?(repo)
+  else
+    fail_usage("unknown argument #{flag}")
+  end
+end
+
+begin
+  report = ContextBudget.run(repo: repo, repeat: repeat, core_file: core_file)
+rescue StandardError => error
+  warn "plastic-bench: #{error.message}"
+  exit 1
+end
+
+print report.to_table
+exit(report.ok? ? 0 : 1)

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,81 @@
+#!/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.
+  # 317a (B11): a screen can open with "## " (state, delivered), a bare "▶"
+  # (roster), or a bare "✔" (delay); the JSON may carry the glyph raw or
+  # \u-escaped depending on the encoder. All globs are literal bytes - case
+  # matching is byte-wise, so multibyte literals are safe under bash 3.2.
+  case $INPUT in
+    *'"delta":"#'*|*'"delta": "#'*) handoff=1 ;;
+    *'"delta":"▶'*|*'"delta": "▶'*) handoff=1 ;;
+    *'"delta":"✔'*|*'"delta": "✔'*) handoff=1 ;;
+    *'"delta":"▶'*|*'"delta": "▶'*) handoff=1 ;;
+    *'"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":"**'*|*'"delta": "**'*) 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/hooks/savepoint

@@ -1,6 +1,6 @@
 #!/bin/bash
-cat <<'HOOKJSON'
-{
-  "systemMessage": "PLASTIC SAVEPOINT — Context is being compacted.\n\nYou MUST perform the savepoint procedure NOW:\n1. Read .plastic/INDEX.md to find active intent(s)\n2. For each active intent in .plastic/store/ID--slug/:\n   a. Update checklist.md (check off completed items)\n   b. Create/update savepoint.md (in-progress work, next steps, blockers, discoveries)\n   c. Update intent.md Build/Observe sections with session work\n3. Update .plastic/INDEX.md active section\n4. Commit: git add .plastic/ && git commit -m 'chore: savepoint — [intent name]'\n5. Tell the user: 'Context is getting large. I have saved progress to the active intent. Please run /clear and say continue to resume.'\n\nDO NOT skip this. The user's work depends on it."
-}
-HOOKJSON
+INPUT=""
+[ -t 0 ] || INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "$INPUT" | env -u RUBYOPT ruby "$SCRIPT_DIR/../scripts/hook-savepoint" "$HOME/.plastic"
+exit 0

package/package.json

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

package/scripts/agent-report

@@ -22,6 +22,8 @@
 # Exit codes: 0 (report emitted), 2 (usage).
 
 require_relative "lib/savepoint"
+require_relative "lib/intent_screen"
+
 def parse_args(argv)
   role = nil
   positional = []
@@ -67,11 +69,15 @@ STAGE_LABELS = {
   "exec" => "Exec", "done" => "Done"
 }.freeze
 
+# Intent 317, D6: name the last LIFECYCLE line, never a trailing Lock/Review/
+# Commit line (same guard as spawn-preamble; plan review finding B1).
 def current_stage(intent_dir)
   ledger = File.join(intent_dir, Savepoint::SAVEPOINT_FILE)
   if File.exist?(ledger)
-    last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
-    return last if last
+    lines = File.read(ledger).each_line.map(&:strip).reject(&:empty?)
+    lifecycle = lines.select { |l| IntentScreen.lifecycle_line?(l) }
+    return lifecycle.last if lifecycle.any?
+    return lines.last if lines.any?
   end
   STAGE_LABELS.fetch(Savepoint.derive_stage(intent_dir), Savepoint.derive_stage(intent_dir))
 end