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

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

package/scripts/lib/hook_registry.rb

@@ -54,6 +54,20 @@ module HookRegistry
           { "name" => "capture", "status" => "Capturing prompt into the session ledger..." },
         ] },
       ],
+      # This entry belongs to the Claude adapter half of Plastic's
+      # harness-agnostic-core / Claude-adapter split (intent 316a1, D3
+      # supersedes 316a's D6): MessageDisplay is not one of
+      # CODEX_LIVE_STATE_EVENTS, so codex_hooks_json (below) never picks it
+      # up; codex_hook_names stays exactly what it was (pinned by
+      # test/hook_registry_test.rb:82 and :110-111). Fires on every streamed
+      # chunk of every assistant message (D11); the launcher (hooks/message-
+      # display) decides with shell builtins and forks nothing on the common
+      # case, execing Ruby only for a candidate message.
+      "MessageDisplay" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "message-display", "status" => "" },
+        ] },
+      ],
     }
   end
 

package/scripts/lib/installer_core.rb

@@ -9,6 +9,7 @@ require "time"
 require_relative "hook_registry"
 require_relative "agent_models"
 require_relative "harness_text"
+require_relative "compact_instructions"
 
 # Shared installer machinery, instantiable with injected package root / store / agent
 # map so the verb scripts (install/update/uninstall/rollback) and their tests can run
@@ -33,6 +34,15 @@ class InstallerCore
   # Regex matching exactly one managed section (BEGIN line .. END line), non-greedy.
   CODEX_SECTION_RE = /^<!-- BEGIN PLASTIC INTEGRATION.*?-->\n.*?\n<!-- END PLASTIC INTEGRATION -->\n?/m
 
+  # Claude CLAUDE.md marked-section markers (intent 312). A pair of its own, not the
+  # Codex literals: the two managed files can be one file (a user who symlinks
+  # ~/.claude/CLAUDE.md at ~/.codex/AGENTS.md, or the reverse), and a shared literal
+  # would let one body silently replace the other and an uninstall of one strip both.
+  # doctor_core.rb matches these literals structurally, so keep the two in sync by hand.
+  CLAUDE_SECTION_BEGIN_PREFIX = "<!-- BEGIN PLASTIC COMPACT"
+  CLAUDE_SECTION_END = "<!-- END PLASTIC COMPACT -->"
+  CLAUDE_SECTION_RE = /^<!-- BEGIN PLASTIC COMPACT.*?-->\n.*?\n<!-- END PLASTIC COMPACT -->\n?/m
+
   # Curated essentials plus a pointer to ~/.plastic/PLASTIC.md and the plastic-conventions
   # skill, injected into ~/.codex/AGENTS.md. Not a slice of PLASTIC.md itself: AGENTS.md is
   # a shared file Codex merges from multiple sources, so this block stays a small,
@@ -66,8 +76,25 @@ class InstallerCore
     @agents = agents
   end
 
+  # Reads the package version from `package.json` when present (the source
+  # tree, and any dev checkout), falling back to the bare `VERSION` file the
+  # installer copies to `~/.plastic` (row B, spec 315b): an installed system
+  # carries VERSION but never package.json, so `rollback.rb` and `update.rb`
+  # constructing an InstallerCore with `package_root: ~/.plastic` crashed with
+  # a raw Errno::ENOENT before this fallback existed. Raises a named error,
+  # not a bare ENOENT, when neither file exists, so the caller is not
+  # misdirected toward the wrong missing file.
   def read_package_version(root)
-    File.read(File.join(root, "package.json")).then { |s| JSON.parse(s)["version"] }
+    package_json = File.join(root, "package.json")
+    version_file = File.join(root, "VERSION")
+
+    if File.exist?(package_json)
+      JSON.parse(File.read(package_json))["version"]
+    elsif File.exist?(version_file)
+      File.read(version_file).strip
+    else
+      raise "cannot determine the package version: neither #{package_json} nor #{version_file} exists"
+    end
   end
 
   # --- Channel derivation (the channel is encoded in the version string) ---
@@ -336,6 +363,7 @@ class InstallerCore
       "scripts/lib/lock.rb" => "scripts/lib/lock.rb",
       "scripts/plastic-lock" => "scripts/plastic-lock",
       "scripts/lib/hook_registry.rb" => "scripts/lib/hook_registry.rb",
+      "scripts/lib/compact_instructions.rb" => "scripts/lib/compact_instructions.rb",
       "scripts/agent-report" => "scripts/agent-report",
       "scripts/lib/insights.rb" => "scripts/lib/insights.rb",
       "scripts/insight-append" => "scripts/insight-append",
@@ -372,6 +400,9 @@ class InstallerCore
       "scripts/lib/harness_text.rb" => "scripts/lib/harness_text.rb",
       "scripts/codex-hook" => "scripts/codex-hook",
       "scripts/spawn-preamble" => "scripts/spawn-preamble",
+      "scripts/lib/report_screen.rb" => "scripts/lib/report_screen.rb",
+      "scripts/report-screen" => "scripts/report-screen",
+      "scripts/savepoint-note" => "scripts/savepoint-note",
       "scripts/lib/store_provisioning.rb" => "scripts/lib/store_provisioning.rb",
       "scripts/provision-project-store" => "scripts/provision-project-store",
       "scripts/lib/project_validator.rb" => "scripts/lib/project_validator.rb",
@@ -408,6 +439,22 @@ class InstallerCore
       "scripts/lib/session_backfill.rb" => "scripts/lib/session_backfill.rb",
       "scripts/lib/session_close.rb" => "scripts/lib/session_close.rb",
       "scripts/lib/session_git.rb" => "scripts/lib/session_git.rb",
+      "scripts/lib/handoff.rb" => "scripts/lib/handoff.rb",
+      "scripts/lib/day_summary.rb" => "scripts/lib/day_summary.rb",
+      "scripts/write-handoff" => "scripts/write-handoff",
+      "scripts/day-summary" => "scripts/day-summary",
+      "scripts/lib/intent_screen.rb" => "scripts/lib/intent_screen.rb",
+      "scripts/intent-screen" => "scripts/intent-screen",
+      "scripts/hook-savepoint" => "scripts/hook-savepoint",
+      # Intent 316a: hooks/* only glob-copies scripts/*, never scripts/lib/*
+      # (see hook_files above), so the two lib files a require_relative
+      # between themselves are unguarded there — these three literal
+      # entries are their only protection (test/install_sync_test.rb:23-29
+      # greps installer_core.rb's own source text for "scripts/<name>").
+      "scripts/lib/intent_screen_ansi.rb" => "scripts/lib/intent_screen_ansi.rb",
+      "scripts/lib/screen_paint.rb" => "scripts/lib/screen_paint.rb",
+      "scripts/lib/message_display.rb" => "scripts/lib/message_display.rb",
+      "scripts/hook-message-display" => "scripts/hook-message-display",
     }
   end
 
@@ -421,6 +468,8 @@ class InstallerCore
       version: 3
       execution_mode: subagent-driven
       stale_threshold_days: 3
+      context_offer_tokens: 350000
+      context_insist_tokens: 500000
       hash_length: 6
       hash_algorithm: sha256-base36
       max_slug_words: 5
@@ -779,6 +828,11 @@ class InstallerCore
     choice = statusline_choice(settings_path, argv: argv, input: input, reinstall: reinstall)
     merge_claude_hooks(settings_path, choice: choice)
 
+    # Instruction injection (intent 312): the compact-instructions block into
+    # ~/.claude/CLAUDE.md. A partial-ownership user file, so it is NOT manifest-tracked
+    # (stripped surgically on uninstall), the same treatment ~/.codex/AGENTS.md gets.
+    inject_claude_compact_md(File.join(config[:dir], "CLAUDE.md"))
+
     # Write manifest
     manifest_path = File.join(plastic_dir, "manifest.json")
     write_manifest(installed, manifest_path)
@@ -1344,14 +1398,28 @@ class InstallerCore
     raise e
   end
 
-  def codex_section(body: CODEX_AGENTS_MD_BODY)
+  # A managed instruction file may be a symlink into a dotfiles repo. write_text_atomic
+  # renames a temp file over its argument, which would replace the link with a regular
+  # file and silently detach it, so every read and write resolves the link first and the
+  # change lands on its target (intent 312).
+  def resolve_managed_path(path)
+    File.symlink?(path) ? File.realpath(path) : path
+  rescue Errno::ENOENT
+    path
+  end
+
+  def marked_section(body: CODEX_AGENTS_MD_BODY, begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                     end_marker: CODEX_SECTION_END)
     hash = Digest::SHA256.hexdigest(body)[0, 12]
-    "#{CODEX_SECTION_BEGIN_PREFIX} hash:#{hash} -->\n#{body.strip}\n#{CODEX_SECTION_END}\n"
+    "#{begin_prefix} hash:#{hash} -->\n#{body.strip}\n#{end_marker}\n"
   end
 
   # Returns :created / :appended / :replaced / :refused. Never raises on a normal user file.
-  def inject_codex_agents_md(path, body: CODEX_AGENTS_MD_BODY)
-    section = codex_section(body: body)
+  def inject_marked_section(path, body: CODEX_AGENTS_MD_BODY,
+                            begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                            end_marker: CODEX_SECTION_END, section_re: CODEX_SECTION_RE)
+    section = marked_section(body: body, begin_prefix: begin_prefix, end_marker: end_marker)
+    path = resolve_managed_path(path)
 
     unless File.exist?(path)
       FileUtils.mkdir_p(File.dirname(path))
@@ -1360,14 +1428,14 @@ class InstallerCore
     end
 
     content = File.read(path)
-    has_begin = content.include?(CODEX_SECTION_BEGIN_PREFIX)
-    has_end = content.include?(CODEX_SECTION_END)
+    has_begin = content.include?(begin_prefix)
+    has_end = content.include?(end_marker)
 
     # 22a safety rule: never write if the existing section cannot be parsed.
     return :refused if has_begin && !has_end
 
     if has_begin
-      write_text_atomic(path, content.sub(CODEX_SECTION_RE, section))
+      write_text_atomic(path, content.sub(section_re, section))
       :replaced
     else
       base = content.end_with?("\n") ? content : content + "\n"
@@ -1376,18 +1444,41 @@ class InstallerCore
     end
   end
 
+  # --- The two blocks Plastic ships, each with its own marker pair ---
+
+  def codex_section(body: CODEX_AGENTS_MD_BODY)
+    marked_section(body: body)
+  end
+
+  def inject_codex_agents_md(path, body: CODEX_AGENTS_MD_BODY)
+    inject_marked_section(path, body: body)
+  end
+
+  # The compact-instructions block for ~/.claude/CLAUDE.md (intent 312).
+  def claude_compact_section(body: CompactInstructions::BODY)
+    marked_section(body: body, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                   end_marker: CLAUDE_SECTION_END)
+  end
+
+  def inject_claude_compact_md(path, body: CompactInstructions::BODY)
+    inject_marked_section(path, body: body, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                          end_marker: CLAUDE_SECTION_END, section_re: CLAUDE_SECTION_RE)
+  end
+
   # Remove exactly Plastic's managed section from a user-owned AGENTS.md. Preserve all other
   # content. Delete the file only if Plastic created it and nothing else remains. Returns the
   # path when it acted, nil on no-op. Mirrors remove_claude_hooks: dedicated surgical strip,
   # never the manifest whole-file-delete path.
-  def strip_codex_section(path)
+  def strip_marked_section(path, begin_prefix: CODEX_SECTION_BEGIN_PREFIX,
+                           section_re: CODEX_SECTION_RE)
+    path = resolve_managed_path(path)
     return nil unless File.exist?(path)
     content = File.read(path)
-    return nil unless content.include?(CODEX_SECTION_BEGIN_PREFIX)
+    return nil unless content.include?(begin_prefix)
 
     # Remove the section plus the single separator newline the append introduced, so a
     # standard user file round-trips byte-identical.
-    stripped = content.sub(/\n?#{CODEX_SECTION_RE}/, "")
+    stripped = content.sub(/\n?#{section_re}/, "")
 
     if stripped.strip.empty?
       File.delete(path)                 # Plastic-created file: nothing else left
@@ -1398,6 +1489,15 @@ class InstallerCore
     path
   end
 
+  def strip_codex_section(path)
+    strip_marked_section(path)
+  end
+
+  def strip_claude_compact_section(path)
+    strip_marked_section(path, begin_prefix: CLAUDE_SECTION_BEGIN_PREFIX,
+                         section_re: CLAUDE_SECTION_RE)
+  end
+
   # --- Uninstall ---
 
   def handle_uninstall(uninstall_agents)
@@ -1424,6 +1524,7 @@ class InstallerCore
     puts "     ls ~/.claude/skills | grep '^plastic-'      # → no output"
     puts "     ls ~/.claude/hooks | grep '^plastic-'       # → no output"
     puts "     grep -c plastic ~/.claude/settings.json     # → only hook refs gone"
+    puts "     grep 'PLASTIC COMPACT' ~/.claude/CLAUDE.md  # → no output"
     puts "\n  To also delete your intent store: rm -rf #{tilde(plastic_home)}\n\n"
   end
 
@@ -1470,6 +1571,11 @@ class InstallerCore
       settings_path = File.join(config[:dir], "settings.json")
       remove_claude_hooks(settings_path) if File.exist?(settings_path)
       removed.concat(migrate_legacy_plugin(config[:dir]))
+
+      # The compact-instructions block in the user-owned CLAUDE.md (intent 312): a
+      # surgical strip, never the manifest whole-file-delete path above.
+      stripped = strip_claude_compact_section(File.join(config[:dir], "CLAUDE.md"))
+      removed << stripped if stripped
     end
 
     # Codex: surgically strip Plastic's marked section from the user-owned AGENTS.md