@zalom/plastic 1.14.1 → 2.0.0-alpha.10

package/scripts/lib/compact_instructions.rb

@@ -0,0 +1,56 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "digest"
+
+# The compaction thresholds and the text Plastic installs into ~/.claude/CLAUDE.md
+# (intent 312; intent 296 D35 and D38).
+#
+# One home for the body, because two halves need it: installer_core.rb installs the
+# marked section, doctor_core.rb verifies the installed one is current. Same reason
+# hook_registry.rb is a shared lib rather than a literal duplicated on both sides.
+#
+# The thresholds are absolute token counts, not percentages. From
+# research--context-thresholds.md: models are reliable only to roughly 50 to 65 percent
+# of advertised context, and the mechanisms behind that (lost-in-the-middle, attention
+# dilution, distractor interference) are architectural, so a bigger window does not
+# repeal them. A percentage that is right at 200k, carried to 1M, would let five times
+# as many raw tokens accumulate before it fired.
+#
+# 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
+
+  # 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
+  # as stale, so the block states the shipped numbers and names the two keys as the
+  # override instead. It names the hand-off in words and never by path, so it reads
+  # correctly whether or not the hand-off writer is installed.
+  BODY = <<~MD.freeze
+    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
+      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
+      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.
+
+    Both numbers are absolute token counts for a 1M window. `context_offer_tokens` and
+    `context_insist_tokens` in `~/.plastic/config.yml` override them.
+
+    This section is managed by the Plastic installer. It is replaced on update and
+    removed on uninstall. Do not edit anything between the BEGIN and END markers.
+  MD
+
+  # The freshness hash the installer stamps into the BEGIN marker, so doctor can tell
+  # a current block from one an older version left behind. Same arithmetic as
+  # InstallerCore#marked_section, pinned equal by compact_instructions_test.
+  def self.body_hash
+    Digest::SHA256.hexdigest(BODY)[0, 12]
+  end
+end

package/scripts/lib/day_summary.rb

@@ -0,0 +1,211 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# DaySummary (intent 311): the block SessionStart injects at boot, a bounded
+# rendering of the day ledger (open items, the last five done), the live
+# auto intents (an Active intent with a fresh delivery lock, across the
+# global and every project store), and the other sessions alive by their
+# heartbeat. Never the raw ledger (296 D36). No environment reads; every
+# path is injected.
+
+require "time"
+require_relative "session_ledger"
+require_relative "handoff"
+require_relative "lock"
+require_relative "report_screen"
+
+module DaySummary
+  module_function
+
+  # Every part at its cap with 80-character summaries is about 2.8 KB; the
+  # budget is the safety net above that, not the working limit.
+  BUDGET = 3072
+  HEARTBEAT_TTL = 3600
+  OPEN_CAP = 10
+  DONE_CAP = 5
+  LIVE_CAP = 5
+  SESSIONS_CAP = 10
+  LINE_MAX = 100
+  # Trimmed first when the budget is exceeded; Open is the last to shrink.
+  TRIM_ORDER = %i[others live done open].freeze
+  TITLES = {
+    open: "Open:",
+    done: "Done, last five:",
+    live: "Live auto intents:",
+    others: "Other active sessions:",
+  }.freeze
+  ISO8601_RE = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\b/
+  INDEX_DIR_RE = %r{store/([\w][\w.-]*?)(?:/|\))}
+  private_constant :ISO8601_RE, :INDEX_DIR_RE
+
+  def build(store:, day:, session:, home:, now: Time.now, heartbeat_ttl: HEARTBEAT_TTL)
+    lists = {
+      open: open_items(store, day),
+      done: last_done(store, day),
+      live: live_intents(home, now: now),
+      others: active_sessions(store, session, now: now, ttl: heartbeat_ttl),
+    }
+    hidden = Hash.new(0)
+    cap!(lists, hidden, :open, OPEN_CAP, keep: :newest)
+    cap!(lists, hidden, :done, DONE_CAP, keep: :newest)
+    cap!(lists, hidden, :live, LIVE_CAP, keep: :first)
+    cap!(lists, hidden, :others, SESSIONS_CAP, keep: :first)
+    return "" if lists.values.all?(&:empty?)
+
+    loop do
+      text = compose(day, lists, hidden)
+      return text if text.bytesize <= BUDGET
+
+      key = TRIM_ORDER.find { |k| !lists[k].empty? }
+      return text unless key
+
+      %i[open done].include?(key) ? lists[key].shift : lists[key].pop
+      hidden[key] += 1
+    end
+  end
+
+  # --- parts -------------------------------------------------------------------------
+
+  def open_items(store, day)
+    Handoff.read_items(store, day)
+           .select { |i| Handoff::OPEN_STATES.include?(i[:state]) }
+           .map { |i| "- [#{i[:session]}] [#{i[:project]}] #{Handoff.clip(i[:summary])}" }
+  end
+
+  def last_done(store, day)
+    Handoff.read_savepoint(store, day)
+           .select { |e| e[:event] == "Done" }
+           .map { |e| "- [#{e[:session]}] [#{e[:project]}] #{Handoff.clip(e[:summary])}" }
+  end
+
+  # The global store plus every projects/<slug>/store, each with its INDEX
+  # one level up, the way doctor enumerates them.
+  def stores(home)
+    list = [[File.join(home, "INDEX.md"), File.join(home, "store")]]
+    projects_root = File.join(home, "projects")
+    if File.directory?(projects_root)
+      Dir.children(projects_root).sort.each do |slug|
+        list << [File.join(projects_root, slug, "INDEX.md"), File.join(projects_root, slug, "store")]
+      end
+    end
+    list
+  end
+
+  def active_dirs(index_path)
+    return [] unless File.exist?(index_path)
+
+    dirs = []
+    current = nil
+    File.foreach(index_path) do |line|
+      if (m = line.match(/^##\s+(.+?)\s*$/))
+        current = m[1]
+        next
+      end
+      next unless current == "Active"
+
+      line.scan(INDEX_DIR_RE) { |(dirname)| dirs << dirname unless dirs.include?(dirname) }
+    end
+    dirs
+  end
+
+  def live_intents(home, now:)
+    stores(home).flat_map do |index_path, store_dir|
+      active_dirs(index_path).filter_map do |dirname|
+        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. 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)}"
+      end
+    end
+  rescue SystemCallError
+    []
+  end
+
+  def last_savepoint_line(dir)
+    path = File.join(dir, "savepoint.md")
+    if File.exist?(path)
+      File.readlines(path).reverse_each do |line|
+        text = line.strip
+        return text[0, LINE_MAX] if text.match?(ISO8601_RE)
+      end
+    end
+    "(no savepoint yet)"
+  rescue SystemCallError
+    "(no savepoint yet)"
+  end
+
+  def active_sessions(store, session, now:, ttl:)
+    tmp_root = SessionLedger.tmp_root(store)
+    return [] unless File.directory?(tmp_root)
+
+    Dir.children(tmp_root).sort.filter_map do |sid|
+      next if sid == session || sid.start_with?(".")
+
+      dir = File.join(tmp_root, sid)
+      next unless File.directory?(dir)
+
+      age = heartbeat_age(dir, now)
+      next if age.nil? || age > ttl
+
+      "- #{sid} (#{(age / 60).floor}m ago, on #{pointer_of(dir)})"
+    end
+  rescue SystemCallError
+    []
+  end
+
+  # Seconds since the session's last heartbeat: the ISO-8601 content of
+  # `heartbeat`, else that file's mtime, else the directory's mtime. The
+  # same reading doctor's orphan check uses, inverted here for liveness.
+  def heartbeat_age(dir, now)
+    heartbeat = File.join(dir, "heartbeat")
+    if File.file?(heartbeat)
+      begin
+        return now - Time.iso8601(File.read(heartbeat).strip)
+      rescue ArgumentError, IOError, SystemCallError
+        return now - File.mtime(heartbeat)
+      end
+    end
+    now - File.mtime(dir)
+  rescue SystemCallError
+    nil
+  end
+
+  def pointer_of(dir)
+    path = File.join(dir, "current")
+    return "?" unless File.file?(path)
+
+    value = File.read(path).strip
+    value.empty? ? "?" : value[0, 80]
+  rescue SystemCallError
+    "?"
+  end
+
+  # --- rendering, pure -------------------------------------------------------------
+
+  def cap!(lists, hidden, key, cap, keep:)
+    return unless lists[key].size > cap
+
+    hidden[key] += lists[key].size - cap
+    lists[key] = keep == :newest ? lists[key].last(cap) : lists[key].first(cap)
+  end
+
+  def compose(day, lists, hidden)
+    out = ["Day summary #{day}:"]
+    TITLES.each do |key, title|
+      next if lists[key].empty? && hidden[key].zero?
+
+      out << title
+      out.concat(lists[key])
+      out << "(+#{hidden[key]} more)" if hidden[key].positive?
+    end
+    out.join("\n")
+  end
+end

package/scripts/lib/doctor_core.rb

@@ -15,6 +15,7 @@ require "digest"
 require "rubygems"
 
 require_relative "hook_registry"
+require_relative "compact_instructions"
 
 class Doctor
   DEFAULT_PLASTIC_HOME = File.join(Dir.home, ".plastic")
@@ -26,7 +27,10 @@ class Doctor
     "hermes" => { name: "Hermes",      dir: File.join(Dir.home, ".hermes") },
   }.freeze
 
-  CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit].freeze
+  # The Claude events hooks_registered expects in settings.json: the six-event map of
+  # cut-inventory 3b (intent 309 added SessionEnd, registered for close since intent 301;
+  # intent 316a added MessageDisplay, registered for message-display, Claude only).
+  CLAUDE_HOOK_EVENTS = %w[SessionStart PreCompact PostToolUse UserPromptSubmit SessionEnd MessageDisplay].freeze
 
   # Launchers the installer places in the agent's hooks dir that are NOT hooks
   # (intent 204): plastic-statusline is the settings["statusLine"] command, wired
@@ -40,9 +44,8 @@ class Doctor
     folgezettel-id
     read-config
     hook-session-start
-    hook-continue
-    hook-future-intent-check
-    hook-gate-check
+    hook-capture
+    hook-record
     validate-intent
     doctor.rb
   ].freeze
@@ -329,7 +332,7 @@ class Doctor
     hooks_dir = File.join(agent_dir, "hooks")
 
     # Derived from HookRegistry.events (intent 204), not a hand-kept list, so
-    # every registered hook (all 15, including the enforcement gates) is checked.
+    # every registered hook is checked.
     expected_launchers = HookRegistry.claude_launcher_names
 
     # hooks_exist
@@ -396,12 +399,6 @@ class Doctor
       )
     end
 
-    # claude_hooks_implemented (intent 244): the edit-path gates now live as
-    # branches inside one dispatcher (scripts/hook-edit-gates), which is
-    # exactly the shape that let links-gate ship registered and dead on
-    # Codex (intent 200's failure class, one level up).
-    checks << claude_hooks_implemented_check
-
     # hooks_registered — settings.json has Plastic hooks for required events
     settings_path = File.join(agent_dir, "settings.json")
     settings = read_json_safe(settings_path)
@@ -456,7 +453,7 @@ class Doctor
 
       # hooks_match_registry (intent 108, D7): the live settings must carry
       # EXACTLY the registrations HookRegistry defines; any drift (a missing
-      # gate, a stray plastic hook, a stale matcher) is how bash-gate shipped
+      # hook, a stray plastic hook, a stale matcher) is how a hook shipped
       # dead once already.
       expected = HookRegistry.claude_settings_hooks(hook_dir: hooks_dir)
       diffs = []
@@ -513,9 +510,56 @@ class Doctor
     # agents_exist — auto-mode role files (plastic-*.md) synced into <dir>/agents
     checks << flat_agents_check(agent_dir, "--claude")
 
+    # compact-instructions block in CLAUDE.md (intent 312)
+    checks << claude_compact_instructions_check(agent_dir)
+
     checks
   end
 
+  # Claude CLAUDE.md marker literals. Keep in sync with
+  # InstallerCore::CLAUDE_SECTION_BEGIN_PREFIX / CLAUDE_SECTION_END (doctor does not
+  # require installer_core, so the literals are duplicated, exactly as for Codex). The
+  # BODY and its hash are NOT duplicated: they come from the shared CompactInstructions.
+  CLAUDE_COMPACT_BEGIN_PREFIX = "<!-- BEGIN PLASTIC COMPACT"
+  CLAUDE_COMPACT_END = "<!-- END PLASTIC COMPACT -->"
+
+  # Present, well formed, and current. The Codex AGENTS.md check stops at well formed;
+  # this one also compares the hash in the BEGIN marker against the shipped body, so a
+  # block an older version left behind is reported rather than trusted.
+  def claude_compact_instructions_check(agent_dir)
+    claude_md = File.join(agent_dir, "CLAUDE.md")
+    name = "claude_compact_instructions"
+    hint = "Re-run the Plastic installer with --claude"
+
+    unless File.exist?(claude_md)
+      return check(category: "agent_registration", name: name, status: "fail",
+                   message: "CLAUDE.md not found at #{tilde(claude_md)}, so the compaction instructions are not installed",
+                   fixable: true, fix_hint: hint)
+    end
+
+    content = File.read(claude_md)
+    b = content.index(CLAUDE_COMPACT_BEGIN_PREFIX)
+    e = content.index(CLAUDE_COMPACT_END)
+    well_formed = b && e && e > b && content[b...e].include?("-->")
+
+    unless well_formed
+      return check(category: "agent_registration", name: name, status: "fail",
+                   message: "CLAUDE.md is missing the compact-instructions block or its section is malformed",
+                   fixable: true, fix_hint: hint)
+    end
+
+    installed_hash = content[b..][/hash:(\w+)/, 1]
+    if installed_hash != CompactInstructions.body_hash
+      return check(category: "agent_registration", name: name, status: "fail",
+                   message: "the compact-instructions block in CLAUDE.md is stale " \
+                            "(hash:#{installed_hash}, current is hash:#{CompactInstructions.body_hash})",
+                   fixable: true, fix_hint: hint)
+    end
+
+    check(category: "agent_registration", name: name, status: "pass",
+          message: "CLAUDE.md carries the current compact-instructions block")
+  end
+
   # Unfiltered classification (intent 276, spec Approach table): mode (a)
   # unowned warns, mode (b) current-but-missing fails, a retired/non-hook
   # launcher is skipped, a third-party hook stays silent.
@@ -569,71 +613,6 @@ class Doctor
     )
   end
 
-  def claude_dispatcher_gate_names(source)
-    case_start = source.index(/^\s*case gate\b/)
-    return nil unless case_start
-
-    case_body = source[case_start..-1]
-    end_idx = case_body.index(/^\s*end\b/)
-    scanned = end_idx ? case_body[0...end_idx] : case_body
-    names = scanned.scan(/^\s*when\s+"([^"]+)"/).flatten.uniq
-    names.empty? ? nil : names
-  end
-
-  def claude_hooks_implemented_check
-    dispatcher_path = File.join(plastic_home, "scripts", "hook-edit-gates")
-
-    unless File.exist?(dispatcher_path)
-      return check(
-        category: "agent_registration", name: "claude_hooks_implemented", status: "fail",
-        message: "scripts/hook-edit-gates not found at #{tilde(dispatcher_path)}; cannot verify " \
-                 "the edit-path gate registry and dispatcher agree",
-        fixable: true, fix_hint: "Re-run the Plastic installer"
-      )
-    end
-
-    dispatcher_names = claude_dispatcher_gate_names(File.read(dispatcher_path))
-
-    if dispatcher_names.nil?
-      return check(
-        category: "agent_registration", name: "claude_hooks_implemented", status: "fail",
-        message: "Could not read any gate names out of #{tilde(dispatcher_path)}: the `case gate` " \
-                 "statement no longer matches the shape this check expects, so the registry was " \
-                 "never actually checked against the real dispatcher. Update " \
-                 "claude_dispatcher_gate_names in doctor.rb to the file's new shape.",
-        fixable: false
-      )
-    end
-
-    registry_names = HookRegistry::GATE_TOOLS.keys
-    missing_branch = registry_names - dispatcher_names
-    dead_branch = dispatcher_names - registry_names
-
-    if missing_branch.empty? && dead_branch.empty?
-      return check(
-        category: "agent_registration", name: "claude_hooks_implemented", status: "pass",
-        message: "Every registered edit-path gate has a scripts/hook-edit-gates branch, and every " \
-                 "dispatcher branch is registered"
-      )
-    end
-
-    details = missing_branch.map do |name|
-      "#{name} is in HookRegistry::GATE_TOOLS but scripts/hook-edit-gates has no branch for it, " \
-        "so the dispatcher skips it on every edit and it never blocks anything"
-    end
-    details += dead_branch.map do |name|
-      "#{name} has a branch in scripts/hook-edit-gates but is not in HookRegistry::GATE_TOOLS, so " \
-        "the dispatcher never reaches it and it is dead code"
-    end
-
-    check(
-      category: "agent_registration", name: "claude_hooks_implemented", status: "fail",
-      message: "The edit-path gate registry and scripts/hook-edit-gates disagree on " \
-               "#{details.size} gate(s)",
-      details: details, fixable: false
-    )
-  end
-
   def flat_skills_check(agent_dir, installer_flag)
     skills_root = File.join(agent_dir, "skills")
     found = Dir.glob(File.join(skills_root, "plastic-*", "SKILL.md"))
@@ -907,22 +886,21 @@ class Doctor
   # by hand), or a dispatcher branch nobody registers (bash-gate's shape, intent
   # 203, in the opposite direction). This check closes both directions at once.
 
-  # The Codex gate names HookRegistry actually registers: the six apply_patch-gated
-  # names (CODEX_PRE_HOOKS + CODEX_POST_HOOKS), the two Bash-matcher shell gates
-  # (CODEX_BASH_HOOKS), and the live-state hook names Codex inherits whole from
-  # `events` (CODEX_LIVE_STATE_EVENTS). No parsing needed: these are HookRegistry's
-  # own Ruby constants.
+  # The Codex hook names HookRegistry actually registers: the apply_patch record
+  # hook (CODEX_POST_HOOKS) and the live-state hook names Codex inherits whole from
+  # `events` (CODEX_LIVE_STATE_EVENTS), plus the SessionEnd close hook (intent 309,
+  # CODEX_SESSION_END_HOOKS). The PreToolUse gate names left in 2.0 (intent 302). No
+  # parsing needed: these are HookRegistry's own Ruby constants.
   def codex_registry_gate_names
     live_state = HookRegistry::CODEX_LIVE_STATE_EVENTS.flat_map do |event|
       HookRegistry.events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
     end
-    (HookRegistry::CODEX_PRE_HOOKS + HookRegistry::CODEX_POST_HOOKS +
-     HookRegistry::CODEX_BASH_HOOKS + live_state).uniq
+    (HookRegistry::CODEX_POST_HOOKS + live_state + HookRegistry::CODEX_SESSION_END_HOOKS).uniq
   end
 
   def codex_dispatcher_gate_names(source)
     names = []
-    %w[STATE_HOOKS SHELL_HOOKS].each do |const|
+    %w[STATE_HOOKS].each do |const|
       m = source.match(/^#{const}\s*=\s*%w\[([^\]]*)\]/)
       names.concat(m[1].split(/\s+/)) if m
     end
@@ -960,7 +938,7 @@ class Doctor
       return check(
         category: "agent_registration", name: "codex_hooks_implemented", status: "fail",
         message: "Could not read any gate names out of #{tilde(dispatcher_path)}: the " \
-                 "STATE_HOOKS/SHELL_HOOKS constants and the `case gate` statement no longer " \
+                 "STATE_HOOKS constant and the `case gate` statement no longer " \
                  "match the shape this check expects, so the registry could not be checked " \
                  "against the real dispatcher. This is exactly the silent-pass failure this " \
                  "check exists to prevent; update codex_dispatcher_gate_names in doctor.rb " \
@@ -1005,8 +983,8 @@ class Doctor
     toml = File.read(config_toml) rescue ""
     warns = []
     # guide Part 3: `codex_hooks` is a deprecated alias for `[features] hooks`; catch both.
-    warns << "hooks are disabled ([features] hooks = false); Plastic gates will not fire" if toml.match?(/^\s*(?:codex_)?hooks\s*=\s*false/)
-    warns << "sandbox_mode = \"read-only\"; apply_patch writes (and gates) cannot run" if toml.match?(/^\s*sandbox_mode\s*=\s*["']read-only["']/)
+    warns << "hooks are disabled ([features] hooks = false); Plastic hooks will not fire" if toml.match?(/^\s*(?:codex_)?hooks\s*=\s*false/)
+    warns << "sandbox_mode = \"read-only\"; apply_patch writes (and the record hook) cannot run" if toml.match?(/^\s*sandbox_mode\s*=\s*["']read-only["']/)
     return nil if warns.empty?
 
     check(

package/scripts/lib/doctor_session_ledger.rb

@@ -0,0 +1,158 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require_relative "session_ledger"
+
+# DoctorSessionLedger (intent 308) - the `session_ledger` doctor category, mixed into
+# Doctor. Two checks over the batch-1 store areas that Doctor's intent walker never
+# visits (both are dot-prefixed, and the walker stays ignorant of them by design: see
+# test/store_walker_compat_test.rb). They live in the GLOBAL store only: every writer of
+# .tmp/ and .sessions/ (hook-capture, hook-record, hook-session-start, Arm, SessionClose)
+# targets the global store, so a project scope gets no finding and no check.
+#
+# Read-only: the orphan check names directories and never removes one, because a
+# heartbeat is only refreshed on prompts and edits, so an old heartbeat is evidence, not
+# proof, that the session is gone. Fail-open: an unreadable directory is skipped, never
+# raised. Depends on the including class for `plastic_home` and `check`.
+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)
+    heartbeat = File.join(dir, "heartbeat")
+    if File.file?(heartbeat)
+      begin
+        return now - Time.iso8601(File.read(heartbeat).strip)
+      rescue ArgumentError, IOError, SystemCallError
+        return now - File.mtime(heartbeat)
+      end
+    end
+    now - File.mtime(dir)
+  end
+
+  def check_session_ledger(scopes: nil, now: Time.now)
+    return [] unless scopes.nil? || scopes.include?("global")
+
+    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 = []
+    checks << if orphans.empty?
+                check(category: "session_ledger", name: "orphaned_session_tmp", status: "pass",
+                      message: "No .tmp/<session>/ directory has a heartbeat older than " \
+                               "#{ORPHAN_TTL_SECONDS / 3600} hours")
+              else
+                check(category: "session_ledger", name: "orphaned_session_tmp", status: "warn",
+                      message: "#{orphans.size} .tmp/<session>/ director#{orphans.size == 1 ? "y" : "ies"} " \
+                               "with a heartbeat older than #{ORPHAN_TTL_SECONDS / 3600} hours " \
+                               "(the session close hook never ran)",
+                      details: orphans, fixable: true,
+                      fix_hint: "Remove each listed .tmp/<session>/ directory after confirming that " \
+                                "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")
+              else
+                check(category: "session_ledger", name: "day_ledger_shape", status: "warn",
+                      message: "#{shape.size} .sessions/ shape problem#{shape.size == 1 ? "" : "s"}",
+                      details: shape, fixable: true,
+                      fix_hint: "For a day directory missing its <day>.md, run " \
+                                "`ruby ~/.plastic/scripts/file-session-intent --day <day> --carry-to " \
+                                "<today> --store <store>`; rename or remove an entry that is not a " \
+                                "YYYYMMDD day directory.")
+              end
+    checks
+  end
+
+  def orphaned_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)
+
+      age = heartbeat_age(dir, now)
+      next if age <= ORPHAN_TTL_SECONDS
+
+      "global: #{dir} (session #{name}, last heartbeat #{(age / 3600).floor}h ago)"
+    end
+  rescue SystemCallError
+    [] # 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)
+
+    Dir.children(root).sort.filter_map do |name|
+      path = File.join(root, name)
+      if !File.directory?(path)
+        "global: .sessions/#{name} is not a directory (only day directories belong here)"
+      elsif !SessionLedger.valid_day_id?(name)
+        "global: .sessions/#{name} is not a YYYYMMDD day id"
+      elsif !File.file?(SessionLedger.day_file(store_dir, name))
+        "global: .sessions/#{name} has no #{name}.md day file"
+      end
+    end
+  rescue SystemCallError
+    [] # unreadable .sessions/: nothing to report, never a crash
+  end
+end