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

package/scripts/hook-savepoint

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# hook-savepoint (intent 311): the PreCompact hook body. Reads the harness
+# payload from stdin (session_id, cwd), takes the Plastic home from argv,
+# writes this session's hand-off for the pointer's day, and prints one
+# message: the fixed text, plus the written file's path when a session
+# resolved (both harnesses relay the same launcher and the Codex pin feeds
+# both sides the same payload, so the two stay equal). Always exits 0,
+# always prints the message.
+#
+# Usage: hook-savepoint <plastic_home>   (stdin: the hook JSON)
+
+require "json"
+require_relative "lib/session_ledger"
+require_relative "lib/handoff"
+
+MESSAGE = "PLASTIC SAVEPOINT - context is being compacted. The hand-off for this " \
+          "session is written in today's day ledger " \
+          "(store/.sessions/<day>/handoff--<session>.md). " \
+          "After compaction say continue to resume from it."
+
+written = nil
+begin
+  plastic_home = ARGV[0].to_s
+  raw = $stdin.tty? ? "" : $stdin.read.to_s
+  payload = raw.strip.empty? ? {} : JSON.parse(raw)
+  payload = {} unless payload.is_a?(Hash)
+  session_id = payload["session_id"].to_s
+
+  unless plastic_home.empty? || session_id.strip.empty?
+    store = File.join(File.expand_path(plastic_home), "store")
+    session = SessionLedger.short_session_id(session_id, nil)
+    day = Handoff.day_for(store, session, today: SessionLedger.day_id)
+    written = Handoff.write(store: store, day: day, session: session, trigger: "precompact",
+                            templates: File.expand_path("../templates", __dir__))
+  end
+rescue StandardError, JSON::ParserError
+  nil
+end
+
+message = written ? "#{MESSAGE} This session's file: #{written}" : MESSAGE
+puts JSON.generate("systemMessage" => message)
+exit 0

package/scripts/hook-session-start

@@ -13,10 +13,29 @@ require_relative "lib/boot_banner"
 require_relative "lib/qmd_sync"
 require_relative "lib/doctor_core"
 require_relative "lib/session_ledger"
+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
@@ -360,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))
@@ -381,6 +404,16 @@ begin
     end
   end
   parts << "PLASTIC: day ledger #{day} joined (#{open_count} open items, #{pending_count} pending)"
+
+  # The day summary (intent 311, spec D8): open items, the last five done,
+  # live auto intents, other active sessions. Never the raw ledger. A
+  # failure here leaves the joined line alone.
+  begin
+    summary = DaySummary.build(store: store_dir, day: day, session: sid, home: plastic_home, now: Time.now)
+    parts << summary unless summary.empty?
+  rescue StandardError
+    nil
+  end
 rescue StandardError
   nil
 end

package/scripts/intent-screen

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+# intent-screen (intent 316) - prints the intent screen for one intent directory:
+# the title, the field table (Store, Status, Stage, Savepoint, Progress, Next,
+# Insight, each with a note), and the Steps table, filled from the record by
+# scripts/lib/intent_screen.rb. The session adds the What-this-means bullets and
+# the close; it never edits the numbers.
+#
+# Usage:
+#   intent-screen <intent_dir> [--template <path>] [--ansi]
+#
+# The store root is the directory two levels above the intent (<root>/store/<id--slug>);
+# the template defaults to templates/intent-screen.md next to this script's dir,
+# in-repo (<repo>/scripts -> <repo>/templates) and installed (~/.plastic/scripts ->
+# ~/.plastic/templates) alike.
+#
+# --ansi (intent 316a, O3): emits scripts/lib/intent_screen_ansi.rb's styled
+# truecolor block instead of the plain Markdown screen. Plain stays the
+# default with no flag. Two things force plain even WITH --ansi (D18): NO_COLOR
+# present in the environment (any value counts), or a non-TTY stdout — the
+# true default form of D2, not IntentScreenAnsi's own uncoloured layout. The
+# library (scripts/lib/intent_screen_ansi.rb) is pure and never reads either;
+# this script is the one place allowed to.
+#
+# Exit codes:
+#   0 - the screen is on stdout
+#   2 - usage error, or the path is not an intent directory (one line on stderr)
+#
+# Harness-agnostic core: no harness assumption lives here. This script holds
+# the plain/ANSI selection (intent 316a1, D3) and belongs to the same
+# harness-agnostic core as lib/intent_screen.rb and lib/intent_screen_ansi.rb.
+
+require_relative "lib/intent_screen"
+require_relative "lib/intent_screen_ansi"
+
+def usage_abort(message)
+  warn "intent-screen: #{message}"
+  exit 2
+end
+
+args = ARGV.dup
+template_path = nil
+ansi = false
+positional = []
+while (arg = args.shift)
+  case arg
+  when "--template"
+    template_path = args.shift or usage_abort("--template needs a path")
+  when "--ansi"
+    ansi = true
+  else
+    usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
+    positional << arg
+  end
+end
+
+usage_abort("usage: intent-screen <intent_dir> [--template <path>] [--ansi]") unless positional.length == 1
+intent_dir = File.expand_path(positional.first)
+usage_abort("#{intent_dir} is not an intent directory") unless IntentScreen.intent_dir?(intent_dir)
+
+store_root = File.expand_path("../..", intent_dir)
+template_path ||= File.expand_path("../templates/intent-screen.md", __dir__)
+usage_abort("template not found at #{template_path}") unless File.exist?(template_path)
+
+plain = -> { IntentScreen.render(intent_dir: intent_dir, store_root: store_root, template: File.read(template_path)) }
+
+degrade_to_plain = ENV.key?("NO_COLOR") || !$stdout.tty?
+
+$stdout.write(
+  if ansi && !degrade_to_plain
+    IntentScreenAnsi.render(intent_dir: intent_dir, store_root: store_root, color: true)
+  else
+    plain.call
+  end
+)
+exit 0

package/scripts/lib/arm.rb

@@ -94,8 +94,21 @@ module Arm
     }
   end
 
+  # Owner rule 2026-08-31: does this session already have a live top-level
+  # pointer pointing SOMEWHERE ELSE (the day ledger or another intent)? A
+  # pointer already on this intent is the owner re-arming mid-delivery and
+  # stays idempotent. True means a
+  # conversation session. Reads only; rescues to false (fail open).
+  def preexisting_pointer?(session, home:)
+    path = pointer_path(session, home: home)
+    File.exist?(path) && !File.read(path).to_s.strip.empty?
+  rescue StandardError
+    false
+  end
+
   # --- the pointer -------------------------------------------------------------
 
+
   def pointer_path(session, home:)
     store = global_store(home)
     SessionLedger.pointer_path(store, SessionLedger.short_session_id(nil, session))
@@ -125,12 +138,24 @@ module Arm
   # lock data read and touches nothing.
   def arm(intent_dir:, session:, mode: "auto", home: Dir.home, harness: nil,
           agent: nil, model: nil, thread: nil, now: Time.now, runner: Worktree::ShellRunner.new,
-          host: Socket.gethostname)
+          host: Socket.gethostname, allow_inline: false)
     raise ArgumentError, "mode must be auto or guided" unless %w[auto guided].include?(mode.to_s)
     dir = File.expand_path(intent_dir)
     key = resolve_session(session, store: store_for(dir), intent_id: intent_id_for(dir))
     h = home_for(dir, home: home)
 
+    # Owner rule 2026-08-31: the main session never delivers an intent inline.
+    # A session that already carries a top-level session pointer is a
+    # conversation session (SessionStart wrote it at boot); arming there is
+    # inline delivery and is refused BEFORE any lock is taken. A dispatched or
+    # headless session has no pre-existing pointer and arms freely.
+    # --allow-inline is the explicit owner override. Fail open on read errors:
+    # a broken pointer file must never block a legitimate delivery.
+    if !allow_inline && preexisting_pointer?(key, home: h) &&
+       read_pointer(key, home: h).to_s.strip != intent_id_for(dir)
+      return { status: :inline_refused, lock: nil, worktree: nil, session: key, pointer: nil }
+    end
+
     status, lock = Lock.acquire(dir, session: key, host: host, now: now,
                                 harness: harness, agent: agent, model: model,
                                 thread: thread, run_mode: mode.to_s)

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,9 +27,10 @@ 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 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
@@ -508,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.

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)