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

package/scripts/lib/atomic_write.rb

@@ -0,0 +1,31 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# AtomicWrite (intent 334, n2, D19r): a sibling-temp-plus-rename write, the
+# same shape as Lock#write (scripts/lib/lock.rb) - a content write is never
+# an in-place truncate, so a crash mid-write can never leave an empty or
+# half-written target on disk. The temp file is a SIBLING in the same
+# directory as the target, never a system tmpdir, because File.rename can
+# raise EXDEV when the temp and the target live on different filesystems.
+# The temp name ends in .lock (post-execution review, non-blocking 5), the
+# same property Lock#write_temp_path documents: an orphan left by a crash
+# between the write and the rename is covered by the store's existing
+# *.lock gitignore rule rather than swept into its git add -A auto-commit.
+#
+# The renamer is injectable so the interrupted-write case (a rename that
+# raises) is testable with dependency injection, never eval or a global
+# (D19r).
+module AtomicWrite
+  module_function
+
+  def write(path, content, renamer: File.method(:rename))
+    dir = File.dirname(path)
+    temp = File.join(dir, ".#{File.basename(path)}.tmp.#{Process.pid}.#{Time.now.to_f}.#{rand(0xFFFFFF)}.lock")
+    File.write(temp, content)
+    renamer.call(temp, path)
+    true
+  rescue StandardError
+    File.delete(temp) if temp && File.exist?(temp)
+    raise
+  end
+end

package/scripts/lib/compact_instructions.rb

@@ -19,9 +19,9 @@ require "digest"
 #
 # Library only: no CLI, no ENV, no I/O.
 module CompactInstructions
-  # 35 and 50 percent of a 1M window.
-  OFFER_TOKENS = 350_000
-  INSIST_TOKENS = 500_000
+  # 15 and 25 percent of a 1M window (intent 355, n5, D7).
+  OFFER_TOKENS = 150_000
+  INSIST_TOKENS = 250_000
 
   # Static on purpose. A body rendered from the user's config would change its hash
   # every time they edited config.yml, and doctor would then report a correct install
@@ -32,10 +32,10 @@ module CompactInstructions
     Plastic watches this session's context. When the harness reports how much of the
     window is used:
 
-    - At 350,000 tokens, offer to compact. Say that the hand-off in today's day ledger
+    - At 150,000 tokens, offer to compact. Say that the hand-off in today's day ledger
       is written and current, and take no for an answer: a task that is nearly done
       does not need the interruption.
-    - At 500,000 tokens, insist. Take no new work, write the hand-off in today's day
+    - At 250,000 tokens, insist. Take no new work, write the hand-off in today's day
       ledger, and compact before continuing.
     - After a compaction, say continue. The day summary at boot and the hand-off carry
       the state; do not rebuild it by re-reading files.

package/scripts/lib/core_integrity.rb

@@ -0,0 +1,71 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+
+# CoreIntegrity (intent 340, G7, n1): re-hashes the files an installed
+# ~/.plastic/manifest.json lists, so the runner's own "am I running trusted
+# code" check has one implementation. scripts/doctor.rb's
+# Doctor#check_install_integrity does this same arithmetic inline today,
+# per-agent (Codex/Hermes/Claude), against each agent's own manifest; this
+# module is not a refactor of that (out of scope for this node), it exists
+# so the runner - and a later node that points doctor at it - never have to
+# reimplement the same hashing loop a third time.
+#
+# Pure and side-effect-free: `check` takes plastic_home: and never raises
+# across its boundary. A missing, unreadable, or non-JSON manifest.json is a
+# named refusal (`reason:`), never an exception. A manifest-listed file that
+# no longer exists is reported under `missing`, distinct from `drifted` (a
+# file that exists but no longer hashes to the manifest's recorded value).
+module CoreIntegrity
+  module_function
+
+  def check(plastic_home:)
+    manifest_path = File.join(plastic_home.to_s, "manifest.json")
+    return refusal("manifest.json not found at #{manifest_path}") unless File.exist?(manifest_path)
+
+    raw = begin
+      File.read(manifest_path)
+    rescue StandardError => e
+      return refusal("manifest.json is unreadable: #{e.message}")
+    end
+
+    data = begin
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      return refusal("manifest.json is not valid JSON: #{e.message}")
+    end
+
+    files = data.is_a?(Hash) ? data["files"] : nil
+    return refusal("manifest.json's files: is not a mapping") unless files.is_a?(Hash)
+
+    drifted = []
+    missing = []
+    files.each do |path, expected_hash|
+      unless File.exist?(path)
+        missing << path
+        next
+      end
+
+      # v1 minor 6/row 11.16: a tracked file that exists but cannot be read
+      # (permissions changed under this process) must never raise out of a
+      # module whose whole contract is "never raises across its boundary" -
+      # unreadable is reported the same way a hash mismatch is: this
+      # process cannot confirm the file matches what the manifest expects,
+      # which is exactly what `drifted` already means.
+      actual_hash = begin
+        Digest::SHA256.file(path).hexdigest
+      rescue SystemCallError
+        nil
+      end
+      drifted << path if actual_hash.nil? || actual_hash != expected_hash
+    end
+
+    { ok: drifted.empty? && missing.empty?, drifted: drifted, missing: missing, reason: nil }
+  end
+
+  def refusal(reason)
+    { ok: false, drifted: [], missing: [], reason: reason }
+  end
+end

package/scripts/lib/dashboard_screen.rb

@@ -0,0 +1,40 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "report_screen"
+
+# DashboardScreen (intent 331d) - the presentation half of the dashboard
+# screen. scripts/dashboard.rb's screen_fields sources every fact (Active, In
+# delivery, Delivered, Roadmap, Sessions, Changed, the two capped row lists)
+# through the same helpers report-screen and DaySummary already use, turning
+# a missing source into "not recorded" or "none" before it ever reaches
+# here; this module carries no data-sourcing logic of its own, only layout,
+# exactly like ReportScreen.render_state and IntentScreen.render do for
+# their own screens.
+module DashboardScreen
+  module_function
+
+  TEMPLATE_PATH = File.expand_path("../../templates/dashboard-screen.md", __dir__)
+
+  def render(fields, template: nil)
+    out = (template || File.read(TEMPLATE_PATH)).dup
+    out = out.gsub("{{scope}}", fields.fetch(:scope).to_s)
+    out = out.gsub("{{active}}", fields.fetch(:active).to_s)
+    out = out.gsub("{{in_delivery}}", fields.fetch(:in_delivery).to_s)
+    out = out.gsub("{{delivered}}", fields.fetch(:delivered).to_s)
+    out = out.gsub("{{roadmap}}", fields.fetch(:roadmap).to_s)
+    out = out.gsub("{{sessions}}", fields.fetch(:sessions).to_s)
+    out = out.gsub("{{changed}}", fields.fetch(:changed).to_s)
+    out = out.gsub("{{where_we_are.rows}}", where_we_are_rows(fields.fetch(:where_we_are, [])))
+    out = out.gsub("{{where_we_go_next.rows}}", where_we_go_next_rows(fields.fetch(:where_we_go_next, [])))
+    ReportScreen.fit_screen(out.gsub(/\n{3,}/, "\n\n"))
+  end
+
+  def where_we_are_rows(rows)
+    rows.map { |r| "| #{r[:graph_id]} | #{r[:intent]} | #{r[:stage]} | #{r[:progress]} | #{r[:lead]} |" }.join("\n")
+  end
+
+  def where_we_go_next_rows(rows)
+    rows.map { |r| "| #{r[:rank]} | #{r[:graph_id]} | #{r[:intent]} | #{r[:reason]} |" }.join("\n")
+  end
+end

package/scripts/lib/day_summary.rb

@@ -12,6 +12,7 @@ require "time"
 require_relative "session_ledger"
 require_relative "handoff"
 require_relative "lock"
+require_relative "report_screen"
 
 module DaySummary
   module_function
@@ -113,8 +114,12 @@ module DaySummary
         dir = File.join(store_dir, dirname)
         next unless File.directory?(dir) && Lock.fresh?(dir, now: now)
         # A guided session's lock is live but not autonomous; a lock with no
-        # run_mode (a 1.14 auto team) counts as auto.
-        next if (Lock.read(dir) || {})["run_mode"].to_s == "guided"
+        # run_mode (a 1.14 auto team) counts as auto. 317a (B9): when the lock
+        # carries no run_mode, the outcome frontmatter stamp (D5) is asked
+        # before defaulting, so a guided close never reads as auto.
+        run_mode = (Lock.read(dir) || {})["run_mode"].to_s
+        run_mode = ReportScreen.outcome_frontmatter(dir)["mode"].to_s if run_mode.empty?
+        next if run_mode == "guided"
 
         id, slug = dirname.split("--", 2)
         "- #{id} #{slug}: #{last_savepoint_line(dir)}"

package/scripts/lib/doctor_core.rb

@@ -27,9 +27,11 @@ 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 PreToolUse 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
@@ -90,8 +92,19 @@ class Doctor
 
     JSON.parse(File.read(path))
   rescue JSON::ParserError
-    content = File.read(path).gsub(%r{//[^\n]*}, "").gsub(/,(\s*[}\]])/, '\1')
-    JSON.parse(content)
+    # The comment/trailing-comma-stripped retry below can itself raise
+    # JSON::ParserError on genuinely malformed content (a truncated file, or
+    # plain garbage). A nested begin/rescue is required here because a
+    # method-level `rescue` clause never catches an exception raised from
+    # INSIDE a sibling rescue clause's own body (only from the main body).
+    # Without this nesting a malformed settings.json crashes doctor instead
+    # of reporting a clean fail (intent 331e, F5).
+    begin
+      content = File.read(path).gsub(%r{//[^\n]*}, "").gsub(/,(\s*[}\]])/, '\1')
+      JSON.parse(content)
+    rescue
+      nil
+    end
   rescue
     nil
   end
@@ -1244,10 +1257,94 @@ class Doctor
     all_checks += check_manifest_sync(agent_key)
     all_checks += check_registered_project_paths
     all_checks += check_global_store_available
+    all_checks += check_display_registration(agent_key)
 
     summarize(all_checks, agent_key, binary: true)
   end
 
+  # The single `hooks/<name>` launcher basename for the MessageDisplay event,
+  # derived from HookRegistry rather than hand-kept (intent 331e), so a
+  # future rename of the hook stays in one place. Shared by
+  # check_display_registration (below, boot path) and scripts/doctor.rb's
+  # check_display_paints (full run), which resolves the SAME name under the
+  # agent_dir it was given.
+  def display_hook_launcher_name
+    group = HookRegistry.events["MessageDisplay"].first
+    "plastic-#{group['hooks'].first['name']}"
+  end
+
+  DISPLAY_HOOK_FIX_HINT = "Re-run the Plastic installer to repair the hook registration: " \
+                          "npx @zalom/plastic@<channel> install --reinstall --claude " \
+                          "(plastic-install --repair)".freeze
+
+  # display_hook_registered (intent 331e, D1, category "display"): the Claude
+  # settings carry the plastic-message-display command, on-disk, executable.
+  # Boot-path safe: resolves everything from the injected `agents` hash and
+  # `plastic_home`, never Dir.home or a real ~/.claude (E18). This is the same
+  # discipline check_claude_registration already follows.
+  #
+  # D3: a harness Doctor knows carries no display hook (Codex, Hermes) is a
+  # pass, not a fail, worded "plain by contract" like the paint check's own
+  # skip (scripts/doctor.rb's check_display_paints).
+  def check_display_registration(agent_key)
+    config = agents[agent_key]
+    unless agent_key == "claude"
+      return [check(
+        category: "display", name: "display_hook_registered", status: "pass",
+        message: "#{config[:name]} is plain by contract; no MessageDisplay hook to register"
+      )]
+    end
+
+    agent_dir = config[:dir]
+    settings_path = File.join(agent_dir, "settings.json")
+    settings = read_json_safe(settings_path)
+
+    if settings.nil?
+      return [check(
+        category: "display", name: "display_hook_registered", status: "fail",
+        message: "Cannot read #{tilde(settings_path)}: file missing or invalid",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    hooks = settings["hooks"].is_a?(Hash) ? settings["hooks"] : {}
+    commands = event_commands(hooks["MessageDisplay"])
+    launcher_name = display_hook_launcher_name
+
+    registered = commands.any? { |cmd| HookRegistry.command_basenames(cmd).include?(launcher_name) }
+
+    unless registered
+      return [check(
+        category: "display", name: "display_hook_registered", status: "fail",
+        message: "No MessageDisplay hook registered in #{tilde(settings_path)}",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    launcher_path = File.join(agent_dir, "hooks", launcher_name)
+
+    unless File.exist?(launcher_path)
+      return [check(
+        category: "display", name: "display_hook_registered", status: "fail",
+        message: "MessageDisplay is registered but #{tilde(launcher_path)} does not exist",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    unless File.executable?(launcher_path)
+      return [check(
+        category: "display", name: "display_hook_registered", status: "fail",
+        message: "#{tilde(launcher_path)} exists but is not executable",
+        fixable: true, fix_hint: DISPLAY_HOOK_FIX_HINT
+      )]
+    end
+
+    [check(
+      category: "display", name: "display_hook_registered", status: "pass",
+      message: "MessageDisplay hook registered and #{tilde(launcher_path)} is executable"
+    )]
+  end
+
   def check_registered_project_paths
     checks = []
 

package/scripts/lib/doctor_session_ledger.rb

@@ -18,6 +18,18 @@ require_relative "session_ledger"
 module DoctorSessionLedger
   ORPHAN_TTL_SECONDS = 24 * 60 * 60
 
+  # Row H (spec D9): a `.tmp/<sid>/` directory with no `current` pointer is a
+  # DIFFERENT orphan class than ORPHAN_TTL_SECONDS's -- a session where
+  # session start never ran at all (a `-p` print session, a resumed
+  # background job, an unregistered SessionStart hook), not a session that
+  # ran and then never closed. No choice of session id ever creates a
+  # pointer for that class, so it would otherwise stay invisible for the
+  # full 24 hours (or forever, once hook-capture/hook-record stop creating
+  # it at all). Short relative to ORPHAN_TTL_SECONDS on purpose: a session
+  # between its own start and its first pointer write is normal and must not
+  # be flagged, but that window is seconds, not hours.
+  NO_POINTER_TTL_SECONDS = 5 * 60
+
   # Seconds since the session's last heartbeat: the ISO-8601 content of `heartbeat`,
   # else that file's mtime, else the directory's mtime.
   def heartbeat_age(dir, now)
@@ -37,6 +49,7 @@ module DoctorSessionLedger
 
     store_dir = File.join(plastic_home, "store")
     orphans = orphaned_session_dirs(store_dir, now)
+    no_pointer = no_pointer_session_dirs(store_dir, now)
     shape = day_ledger_shape_problems(store_dir)
 
     checks = []
@@ -54,6 +67,20 @@ module DoctorSessionLedger
                                 "session is gone: a live session rewrites its heartbeat on every " \
                                 "prompt and edit, so only a listed directory may be removed, by hand.")
               end
+    checks << if no_pointer.empty?
+                check(category: "session_ledger", name: "no_pointer_session_tmp", status: "pass",
+                      message: "No .tmp/<session>/ directory has gone without a `current` pointer for " \
+                               "longer than #{NO_POINTER_TTL_SECONDS} seconds")
+              else
+                check(category: "session_ledger", name: "no_pointer_session_tmp", status: "warn",
+                      message: "#{no_pointer.size} .tmp/<session>/ director#{no_pointer.size == 1 ? "y" : "ies"} " \
+                               "with no `current` pointer for longer than #{NO_POINTER_TTL_SECONDS} seconds " \
+                               "(session start never ran for this session)",
+                      details: no_pointer, fixable: true,
+                      fix_hint: "Remove each listed .tmp/<session>/ directory after confirming that " \
+                                "session never started: no `current` pointer means session start never " \
+                                "ran for it, so this is not a live session missing a checklist entry.")
+              end
     checks << if shape.empty?
                 check(category: "session_ledger", name: "day_ledger_shape", status: "pass",
                       message: "Every .sessions/ entry is a YYYYMMDD day directory with its <day>.md file")
@@ -86,6 +113,31 @@ module DoctorSessionLedger
     [] # unreadable .tmp/: nothing to report, never a crash
   end
 
+  # Row H (spec D9): `.tmp/<sid>/` directories with no `current` pointer, past
+  # NO_POINTER_TTL_SECONDS. A different signal than #orphaned_session_dirs:
+  # that one is age-only and blind to whether a pointer exists at all, so a
+  # young no-pointer dir (a session between its start and its first pointer
+  # write) must not appear here even though it may well appear there once it
+  # ages past ORPHAN_TTL_SECONDS -- the two checks answer different questions
+  # and a dir can legitimately show up in neither, either, or both.
+  def no_pointer_session_dirs(store_dir, now)
+    tmp_root = SessionLedger.tmp_root(store_dir)
+    return [] unless File.directory?(tmp_root)
+
+    Dir.children(tmp_root).sort.filter_map do |name|
+      dir = File.join(tmp_root, name)
+      next unless File.directory?(dir)
+      next if File.exist?(File.join(dir, "current"))
+
+      age = heartbeat_age(dir, now)
+      next if age <= NO_POINTER_TTL_SECONDS
+
+      "global: #{dir} (session #{name}, no `current` pointer, last heartbeat #{age.round}s ago)"
+    end
+  rescue SystemCallError
+    [] # unreadable .tmp/: nothing to report, never a crash
+  end
+
   def day_ledger_shape_problems(store_dir)
     root = SessionLedger.sessions_root(store_dir)
     return [] unless File.directory?(root)

package/scripts/lib/graph_edges.rb

@@ -0,0 +1,137 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# GraphEdges (intent 334, n1): the shared `needs` syntax and cycle-path check
+# (327 D2r-D4r, D12r). Parses a "## Graph" section's edge lines into a node
+# set and an edge map, the one parser an intent's graph.md and a roadmap's
+# own ## Graph section both use unchanged (C1, fold A5): the same list-item
+# grammar, the same root keyword, the same cycle walk. Deliberately loose
+# about what an id looks like - a roadmap id is numeric ("334", "340a"), a
+# node id carries a kind prefix ("n1") - the kind-prefix rule belongs to
+# NodeFile and WorkGraphValidator, never here (D12r, fold A6).
+#
+# Grammar (D2r/D3r): a list item shaped "- <id> needs <target> [<target>
+# ...]", ending at end of line. The single literal target "nothing" declares
+# a root and must be the ONLY target on the line. Any line that does not
+# start with "- <token> needs" is prose and is skipped in silence. A line
+# that DOES look like an edge is held to the grammar strictly: no target at
+# all, "nothing" alongside other targets, or a target token carrying
+# sentence punctuation (a period, a colon, ...) rather than the loose
+# id-token charset, is an error naming the line, never a silently
+# mis-parsed edge or an invented node (fold A7).
+#
+# Pure and side-effect-free; never raises across the boundary, matching the
+# Result-hash convention every library in scripts/lib/ follows.
+module GraphEdges
+  module_function
+
+  EDGE_LEAD_RE = /\A-\s*(\S+)\s+needs\b(.*)\z/.freeze
+  TOKEN_RE = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/.freeze
+  ROOT_TARGET = "nothing"
+
+  # {nodes:, edges:, errors:} - nodes is the declared ids together with every
+  # id any edge targets (fold A5), in first-seen order; edges maps a declared
+  # id to its target ids (empty for a root); errors names each malformed
+  # edge-shaped line. Prose lines contribute nothing and raise nothing.
+  def parse(section_text)
+    declared_order = []
+    edges = {}
+    targeted = []
+    errors = []
+
+    section_text.to_s.each_line do |raw_line|
+      line = raw_line.chomp("\n").chomp("\r")
+      stripped = line.strip
+      next if stripped.empty?
+
+      m = stripped.match(EDGE_LEAD_RE)
+      next unless m
+
+      id = m[1]
+      raw_targets = m[2].to_s.strip.split(/\s+/)
+
+      if raw_targets.empty?
+        errors << "malformed edge line, no target: #{stripped.inspect}"
+        next
+      end
+
+      if raw_targets.include?(ROOT_TARGET) && raw_targets.length > 1
+        errors << "root target #{ROOT_TARGET.inspect} mixed with a real target, root must be the only target: #{stripped.inspect}"
+        next
+      end
+
+      bad_token = raw_targets.find { |t| t != ROOT_TARGET && !t.match?(TOKEN_RE) }
+      if bad_token
+        errors << "prose tail after targets: #{stripped.inspect}"
+        next
+      end
+
+      if edges.key?(id)
+        errors << "duplicate node declaration for #{id.inspect}: #{stripped.inspect}"
+        next
+      end
+
+      targets = raw_targets == [ROOT_TARGET] ? [] : raw_targets
+      declared_order << id
+      edges[id] = targets
+      targeted.concat(targets)
+    end
+
+    nodes = declared_order.dup
+    targeted.each { |t| nodes << t unless nodes.include?(t) }
+
+    { nodes: nodes, edges: edges, errors: errors }
+  end
+
+  # The cycle as a path with the entry id repeated (D4r), or nil when the
+  # graph is acyclic. A node reachable by two distinct paths (a diamond) is
+  # never mistaken for a cycle: once a node's whole subtree is walked clean
+  # it is marked visited and never re-examined.
+  def cycle(edges)
+    visiting = {}
+    visited = {}
+    path = []
+
+    edges.each_key do |node|
+      next if visited[node]
+      found = walk(node, edges, visiting, visited, path)
+      return found if found
+    end
+    nil
+  end
+
+  def walk(node, edges, visiting, visited, path)
+    if visiting[node]
+      idx = path.index(node)
+      return path[idx..] + [node]
+    end
+    return nil if visited[node]
+
+    visiting[node] = true
+    path.push(node)
+    (edges[node] || []).each do |target|
+      found = walk(target, edges, visiting, visited, path)
+      return found if found
+    end
+    path.pop
+    visiting.delete(node)
+    visited[node] = true
+    nil
+  end
+
+  # The declared work ids whose `needs` reach a verify node without passing
+  # through another verify node (343 D7), in declaration order. `kinds` maps
+  # an id to its node kind, so this module stays blind to where a kind lives.
+  def review_fixes(edges, kinds)
+    edges.keys.select { |id| kinds[id] == "work" && reaches_verify?(id, edges, kinds, {}) }
+  end
+
+  def reaches_verify?(node, edges, kinds, seen)
+    (edges[node] || []).any? do |target|
+      next false if seen[target]
+
+      seen[target] = true
+      kinds[target] == "verify" || reaches_verify?(target, edges, kinds, seen)
+    end
+  end
+end