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

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,6 +13,7 @@ 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
@@ -381,6 +382,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/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,206 @@
+# 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"
+
+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.
+        next if (Lock.read(dir) || {})["run_mode"].to_s == "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")
@@ -508,9 +509,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/handoff.rb

@@ -0,0 +1,184 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Handoff (intent 311): one session's hand-off, a pure rendering of its share
+# of a day ledger (checklist.md and savepoint.md), written into the day
+# directory as handoff--<session>.md at every tick, at PreCompact, and at
+# close. Derived and regenerable: every write renders in full, so a lost or
+# stale copy costs nothing. No environment reads; every path is injected.
+
+require "fileutils"
+require_relative "session_ledger"
+
+module Handoff
+  module_function
+
+  TRIGGERS = %w[tick precompact close].freeze
+  BUDGET = 6144
+  OPEN_CAP = 20
+  DONE_CAP = 10
+  RECENT_CAP = 10
+  OTHERS_CAP = 10
+  # A ledger summary may run to 200 characters; a hand-off line shows the
+  # first 80, so the caps above are reachable inside the byte budget.
+  SUMMARY_MAX = 80
+  OPEN_STATES = %i[open pending].freeze
+  # Trimmed first when the budget is exceeded; Open is the last to shrink.
+  TRIM_ORDER = %i[others recent done open].freeze
+  RESUME = "Say continue; the day summary at boot and this file carry the state."
+
+  SAVEPOINT_TAIL_RE = /\A\[([^\]]*)\] \[([^\]]*)\] (.*)\z/m
+  private_constant :SAVEPOINT_TAIL_RE
+
+  def path_for(store, day, session)
+    File.join(SessionLedger.day_dir(store, day), "handoff--#{session}.md")
+  end
+
+  # The day this session's hand-off belongs to: the pointer's day id when
+  # the pointer holds one, else today (no pointer, or a pointer naming an
+  # intent), the same fallback SessionClose uses for the drop at close.
+  def day_for(store, session, today:)
+    path = SessionLedger.pointer_path(store, session)
+    return today unless File.exist?(path)
+
+    value = File.read(path).strip
+    SessionLedger.valid_day_id?(value) ? value : today
+  end
+
+  def clip(summary)
+    text = summary.to_s
+    text.length > SUMMARY_MAX ? "#{text[0, SUMMARY_MAX]}..." : text
+  end
+
+  # --- readers ---------------------------------------------------------------------
+
+  def read_items(store, day)
+    SessionLedger.read_locked(SessionLedger.checklist_path(store, day))
+                 .each_line.filter_map { |l| SessionLedger.parse_checklist_line(l) }
+  end
+
+  # Parsed savepoint lines, file order: {time:, event:, session:, project:,
+  # summary:}. A line that does not follow the ledger grammar is skipped.
+  def read_savepoint(store, day)
+    SessionLedger.read_locked(SessionLedger.savepoint_path(store, day)).each_line.filter_map do |raw|
+      line = raw.chomp.scrub
+      next if line.empty?
+
+      time, event, rest = line.split(/\s{2,}/, 3)
+      next unless time && event && rest
+
+      match = SAVEPOINT_TAIL_RE.match(rest)
+      next unless match
+
+      { time: time, event: event, session: match[1], project: match[2], summary: match[3] }
+    end
+  end
+
+  # --- rendering, pure -----------------------------------------------------------
+
+  def render(store:, day:, session:, trigger:, now: Time.now)
+    raise ArgumentError, "unknown trigger: #{trigger.inspect}" unless TRIGGERS.include?(trigger)
+
+    items = read_items(store, day)
+    mine = items.select { |i| i[:session] == session }
+    lists = {
+      open: mine.select { |i| OPEN_STATES.include?(i[:state]) }.map { |i| item_line(i) },
+      done: mine.select { |i| i[:state] == :done }.map { |i| item_line(i) },
+      recent: read_savepoint(store, day).select { |e| e[:session] == session }.map { |e| recent_line(e) },
+      others: others_lines(items, session),
+    }
+    hidden = Hash.new(0)
+    cap!(lists, hidden, :open, OPEN_CAP)
+    cap!(lists, hidden, :done, DONE_CAP)
+    cap!(lists, hidden, :recent, RECENT_CAP)
+    if lists[:others].size > OTHERS_CAP
+      hidden[:others] += lists[:others].size - OTHERS_CAP
+      lists[:others] = lists[:others].first(OTHERS_CAP)
+    end
+
+    header = [
+      "# Hand-off: session #{session}, #{day}",
+      "",
+      "Written #{now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')} at #{trigger}",
+      "",
+    ]
+    loop do
+      text = compose(header, lists, hidden)
+      return text if text.bytesize <= BUDGET
+
+      key = TRIM_ORDER.find { |k| !lists[k].empty? }
+      return text unless key
+
+      # Open, Done, and Recent keep their newest entries; Others has no order.
+      key == :others ? lists[key].pop : lists[key].shift
+      hidden[key] += 1
+    end
+  end
+
+  # Keeps the newest `cap` lines (the file is chronological) and counts the rest.
+  def cap!(lists, hidden, key, cap)
+    return unless lists[key].size > cap
+
+    hidden[key] += lists[key].size - cap
+    lists[key] = lists[key].last(cap)
+  end
+
+  def compose(header, lists, hidden)
+    sections = [
+      section("Open", lists[:open], hidden[:open]),
+      section("Done", lists[:done], hidden[:done]),
+      section("Recent", lists[:recent], hidden[:recent]),
+      section("Others today", lists[:others], hidden[:others]),
+      "## Resume\n#{RESUME}\n",
+    ]
+    (header + sections.compact).join("\n")
+  end
+
+  def section(title, lines, hidden)
+    return nil if lines.empty? && hidden.zero?
+
+    body = lines.dup
+    body << "(+#{hidden} more)" if hidden.positive?
+    "## #{title}\n#{body.join("\n")}\n"
+  end
+
+  def item_line(item)
+    "- [#{item[:project]}] #{clip(item[:summary])}"
+  end
+
+  def recent_line(event)
+    "- #{event[:time][11, 5]}Z #{event[:event]} #{clip(event[:summary])}"
+  end
+
+  def others_lines(items, session)
+    items.reject { |i| i[:session] == session }
+         .group_by { |i| i[:session] }
+         .sort
+         .map do |sid, theirs|
+      open = theirs.count { |i| OPEN_STATES.include?(i[:state]) }
+      done = theirs.count { |i| i[:state] == :done }
+      "- #{sid}: #{open} open, #{done} done"
+    end
+  end
+
+  # --- writing -------------------------------------------------------------------
+
+  # Opens the day first (a tick after midnight never fails), renders, and
+  # writes through a per-process temp file and rename, so a crash leaves no
+  # partial hand-off and two writers for one session (a tick overlapping a
+  # PreCompact) never share a temp name. Returns the path. With
+  # `templates: nil` the day is not scaffolded, only its directory ensured.
+  def write(store:, day:, session:, trigger:, templates:, now: Time.now)
+    if templates
+      SessionLedger.open_day(store: store, day: day, templates: templates, author: session)
+    else
+      FileUtils.mkdir_p(SessionLedger.day_dir(store, day))
+    end
+    text = render(store: store, day: day, session: session, trigger: trigger, now: now)
+    target = path_for(store, day, session)
+    tmp = File.join(File.dirname(target), ".handoff-#{session}-#{Process.pid}-#{Thread.current.object_id}.tmp")
+    File.write(tmp, text)
+    File.rename(tmp, target)
+    target
+  end
+end