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

package/bin/test

@@ -2,7 +2,10 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# Runs the FULL Minitest suite in a single process.
+# Runs the Minitest suite in a single process, either the whole suite or a
+# named subset via --only (intent 355, n4, D5). Every run, named or full,
+# goes through FailuresReporter, so a green run costs one line and a red run
+# prints only the failures plus that line, never a dot per test.
 #
 # `release.verify` used to be `ruby -Itest test/*_test.rb`, but Ruby runs only
 # the first glob-expanded file as the program — the rest land in ARGV and are
@@ -12,17 +15,34 @@
 # loaded.
 
 root = File.expand_path("..", __dir__)
-
-files = Dir.glob(File.join(root, "test", "**", "*_test.rb")).sort
-abort "No test files found under #{File.join(root, "test")}" if files.empty?
+discover = -> { Dir.glob(File.join(root, "test", "**", "*_test.rb")).sort }
 
 # `bin/test --list` prints the discovered files without running them, so the
 # discovery logic can be tested cheaply (no full-suite execution).
 if ARGV.delete("--list")
+  files = discover.call
+  abort "No test files found under #{File.join(root, "test")}" if files.empty?
   puts files.map { |f| f.sub("#{root}/", "") }
   exit 0
 end
 
+only_index = ARGV.index("--only")
+if only_index
+  named = ARGV.slice!(only_index..-1)
+  named.shift
+  abort "--only requires at least one test file" if named.empty?
+  files = named.map { |f| File.expand_path(f, root) }
+  missing = files.reject { |f| File.exist?(f) }
+  unless missing.empty?
+    warn "no such test file: #{missing.map { |f| f.sub("#{root}/", "") }.join(', ')}"
+    exit 2
+  end
+else
+  files = discover.call
+  abort "No test files found under #{File.join(root, "test")}" if files.empty?
+end
+
 $LOAD_PATH.unshift File.join(root, "test")
+require_relative "../test/lib/failures_reporter"
 require "minitest/autorun"
 files.each { |f| require f }

package/hooks/call-budget

@@ -0,0 +1,4 @@
+#!/bin/bash
+INPUT=$(cat)
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+echo "$INPUT" | env -u RUBYOPT ruby --disable-gems "$SCRIPT_DIR/../scripts/hook-call-budget"

package/hooks/hooks.json

@@ -17,6 +17,18 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook\" call-budget",
+            "statusMessage": ""
+          }
+        ]
+      }
+    ],
     "PreCompact": [
       {
         "matcher": "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalom/plastic",
-  "version": "2.0.0-alpha.20",
+  "version": "2.0.0-alpha.21",
   "description": "Intent-driven idea development system for AI coding agents",
   "type": "module",
   "bin": {

package/scripts/hook-call-budget

@@ -0,0 +1,222 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Usage: hook-call-budget (reads the PreToolUse stdin JSON payload)
+#
+# Intent 355, n2 (review fix n8). A node gets a call budget by kind
+# (RunnerPolicy.call_cap): a cap on tool calls per attempt. RunnerDispatch
+# writes the cap onto the running line as `calls=` and states it as one
+# sentence in the node's own input, so the executor learns the number before
+# it ever gets denied.
+#
+# Inside a subagent the hook input's session_id and transcript_path are the
+# MAIN session's, never the subagent's own (v1 finding). So this hook caps
+# ONLY a subagent call: agent_id present in the payload. A call with no
+# agent_id (the main thread, a plain conversation, a live --agent session's
+# own turns) is never capped and the decision returns before any file is
+# touched.
+#
+# Which node a subagent is working is read from the subagent's OWN
+# transcript, at <dirname(transcript_path)>/<session_id>/subagents/
+# agent-<agent_id>.jsonl (the main transcript_path plus the main session_id
+# plus the subagent's own agent_id): its first user record carries the
+# dispatch prompt, and the lead/spawn block always pastes the node's packet
+# path into that prompt (PACKET_PATH_RE). The packet path names the intent
+# directory directly (its grandparent), so this hook never scans the store to
+# find it. No packet path in that first prompt means allow.
+#
+# The cap applies only when that node's LATEST transition line in
+# <intent>/savepoint.md is `running` and carries `calls=`; a later `done` or
+# `failed_verification` line (or a sibling node's own running line) means no
+# cap. Past the cap, a Bash call that runs only a safe git verb (add, commit,
+# status, rev-parse, log) is still allowed, so the denial the hook itself
+# orders (commit what is green) is never the thing the hook blocks.
+#
+# Pure and dependency-injected down to the paths it reads; the trailing block
+# guarded by `$PROGRAM_NAME == __FILE__` is this file's only I/O (stdin,
+# stdout), so a test can `load` this file and call HookCallBudget's module
+# functions directly without spawning a process or touching stdin.
+
+require "json"
+require_relative "lib/node_ledger"
+require_relative "lib/savepoint"
+
+module HookCallBudget
+  module_function
+
+  RETURN_INSTRUCTION = "commit what is green and return failed_verification reason=call_budget"
+
+  # A node id, then "--a", then an attempt number, inside a /packets/
+  # directory: the exact shape RunnerDispatch's spawn block pastes into a
+  # subagent's own first prompt. Captures [full_path, node].
+  PACKET_PATH_RE = %r{(\S+/packets/([a-z]{1,2}\d+)--a\d+\.packet)}.freeze
+
+  FIRST_RECORD_SCAN_LIMIT = 20
+
+  GIT_ALLOWED_VERBS = %w[add commit status rev-parse log].freeze
+  GIT_UNSAFE_RE = /[;&|\n]|\$\(|`/.freeze
+
+  # The one decision: nil (allow, no output) or a deny payload Hash. Never
+  # raises across its own boundary.
+  def decide(payload)
+    return nil unless payload.is_a?(Hash)
+
+    agent_id = payload["agent_id"]
+    return nil if agent_id.to_s.strip.empty?
+
+    session_id = payload["session_id"].to_s
+    transcript_path = payload["transcript_path"].to_s
+    return nil if session_id.empty? || transcript_path.empty?
+
+    sub_path = subagent_transcript_path(transcript_path, session_id, agent_id)
+
+    prompt = begin
+      first_user_prompt_text(sub_path)
+    rescue StandardError
+      nil
+    end
+    return nil unless prompt
+
+    match = PACKET_PATH_RE.match(prompt)
+    return nil unless match
+
+    node = match[2]
+    intent_dir = File.dirname(File.dirname(match[1]))
+
+    cap = node_cap(intent_dir, node)
+    return nil unless cap
+
+    count = begin
+      count_tool_use_blocks(sub_path)
+    rescue StandardError => e
+      note_unreadable(intent_dir, session_id, e.message)
+      return nil
+    end
+
+    return nil if count <= cap
+    return nil if git_only_bash_call?(payload)
+
+    deny_payload("#{node} is past its call budget (#{count}/#{cap} tool calls); #{RETURN_INSTRUCTION}")
+  end
+
+  def subagent_transcript_path(main_transcript_path, session_id, agent_id)
+    File.join(File.dirname(main_transcript_path), session_id, "subagents", "agent-#{agent_id}.jsonl")
+  end
+
+  # The first `"type":"user"` record in `path`'s own transcript, rendered to
+  # plain text (message.content as a string, or the joined text blocks of a
+  # content array). Scans at most FIRST_RECORD_SCAN_LIMIT lines: the dispatch
+  # prompt is always the transcript's opening record, so this never touches
+  # the bulk of a long-running subagent's history. Raises on a genuinely
+  # unreadable path (a directory, a permission error); the caller decides
+  # what that means.
+  def first_user_prompt_text(path)
+    File.open(path) do |f|
+      f.each_line.first(FIRST_RECORD_SCAN_LIMIT).each do |raw|
+        record = begin
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          next
+        end
+        next unless record.is_a?(Hash) && record["type"] == "user"
+
+        return message_text(record)
+      end
+    end
+    nil
+  end
+
+  def message_text(record)
+    content = record.dig("message", "content")
+    case content
+    when String
+      content
+    when Array
+      content.select { |b| b.is_a?(Hash) && b["type"] == "text" }.map { |b| b["text"].to_s }.join("\n")
+    else
+      ""
+    end
+  end
+
+  # The cap named on `node`'s LATEST (file-order) non-torn transition line in
+  # `intent_dir`/savepoint.md, or nil when that line is not `running`, carries
+  # no `calls=`, or does not exist at all (matrix 2.6/2.6b: a later done/
+  # failed_verification line, or a sibling node's own running line, never
+  # caps this node).
+  def node_cap(intent_dir, node)
+    path = File.join(intent_dir, "savepoint.md")
+    return nil unless File.exist?(path)
+
+    latest = NodeLedger.entries(path).select { |e| !e[:torn] && e[:subject] == node }.last
+    return nil unless latest && latest[:state] == "running"
+
+    cap = (latest[:fields] || {})["calls"]
+    cap ? cap.to_i : nil
+  end
+
+  # Streams `path` a line at a time, counting `"type":"tool_use"` content
+  # blocks with a plain regex rather than a full JSON parse per line (matrix
+  # 2.5/2.8): a 3 MB transcript counts in well under 50 ms this way.
+  def count_tool_use_blocks(path)
+    count = 0
+    File.foreach(path) { |ln| count += ln.scan(/"type"\s*:\s*"tool_use"/).length }
+    count
+  end
+
+  # Past the cap, a Bash call is still allowed when its command runs only one
+  # safe git verb (matrix 2.7/D3): the git add/commit the denial itself
+  # orders must never be the call the hook blocks. Any chaining token
+  # (`;`, `&`, `|`, a newline, a subshell or a backtick) refuses the whole
+  # command, so a compound command can never smuggle an unrelated call past
+  # the cap riding on a leading `git`.
+  def git_only_bash_call?(payload)
+    return false unless payload["tool_name"].to_s == "Bash"
+
+    command = payload.dig("tool_input", "command").to_s.strip
+    return false if command.empty? || GIT_UNSAFE_RE.match?(command)
+
+    tokens = command.split(/\s+/)
+    return false unless tokens.shift == "git"
+
+    tokens.shift(2) if tokens.first == "-C"
+    GIT_ALLOWED_VERBS.include?(tokens.first)
+  end
+
+  def deny_payload(reason)
+    { "hookSpecificOutput" => { "hookEventName" => "PreToolUse", "permissionDecision" => "deny",
+                                 "permissionDecisionReason" => reason } }
+  end
+
+  # Best-effort note that the transcript could not be counted (matrix 2.9): a
+  # plain milestone line, the same shared primitive Commit/Review/Report
+  # lines already use, dedup'd on (stage, milestone) so a repeat failure in
+  # the same session with the same message is not written twice.
+  def note_unreadable(intent_dir, session_id, message, now: Time.now)
+    Savepoint.append_savepoint_line(intent_dir, "CallBudget", "transcript unreadable for #{session_id}: #{message}",
+                                     now)
+  rescue StandardError
+    nil
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  raw = begin
+    $stdin.read
+  rescue StandardError
+    nil
+  end
+
+  if raw && !raw.strip.empty?
+    payload = begin
+      JSON.parse(raw)
+    rescue StandardError
+      nil
+    end
+
+    result = HookCallBudget.decide(payload)
+    puts JSON.generate(result) if result
+  end
+
+  exit 0
+end

package/scripts/hook-session-start

@@ -36,6 +36,22 @@ rescue StandardError
 end
 payload_session_id = stdin_payload.is_a?(Hash) ? stdin_payload["session_id"].to_s : ""
 
+# --- subagent marker (intent 355 spec D9, node n7; review fix n8, B6): the
+# stdin payload carries agent_id only when this SessionStart call runs
+# inside a spawned agent. agent_type alone is not enough: a live
+# `claude --agent` session carries agent_type on every turn but never
+# agent_id, so keying on agent_type would boot a live agent session with the
+# core banner only. Read from that payload only, never from an environment
+# variable, so a helper needs the core banner alone. An absent agent_id (the
+# common case) is a live session. Any exception here still boots the banner,
+# never nothing: the rescue falls back to a live session, whose own content
+# already comes from paths this file already guards independently.
+subagent_session = begin
+  stdin_payload.is_a?(Hash) && !!stdin_payload["agent_id"]
+rescue StandardError
+  false
+end
+
 # 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
@@ -254,9 +270,9 @@ begin
   end
 rescue Exception
   # Any failure (timeout, missing binary, parse error) — stay silent, never crash.
-end
+end unless subagent_session
 
-if plastic_md
+if plastic_md && !subagent_session
   # Conventions always loaded first
   parts << plastic_md
   parts << "\n---\n"
@@ -292,7 +308,7 @@ if plastic_md
   end
 end
 
-if active_deprecations.any?
+if active_deprecations.any? && !subagent_session
   parts << ""
   active_deprecations.each do |dep|
     severity = dep["severity"] || "info"
@@ -319,7 +335,7 @@ if active_deprecations.any?
   end
 end
 
-if update_notice
+if update_notice && !subagent_session
   parts.unshift("! #{update_notice}\n")
 end
 
@@ -367,7 +383,7 @@ begin
   end
 rescue StandardError
   nil
-end
+end unless subagent_session
 
 # --- Session day ledger: open or join today, write the per-session pointer
 # and heartbeat (intent 298, spec D4). Best-effort: any failure here degrades
@@ -416,7 +432,7 @@ begin
   end
 rescue StandardError
   nil
-end
+end unless subagent_session
 
 # Emit nothing when there is genuinely nothing to surface (no conventions,
 # no deprecations, no update notice).

package/scripts/lib/compact_instructions.rb

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

package/scripts/lib/doctor_core.rb

@@ -30,7 +30,8 @@ class Doctor
   # 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
+  CLAUDE_HOOK_EVENTS = %w[SessionStart PreToolUse PreCompact PostToolUse UserPromptSubmit SessionEnd
+                          MessageDisplay].freeze
 
   # Launchers the installer places in the agent's hooks dir that are NOT hooks
   # (intent 204): plastic-statusline is the settings["statusLine"] command, wired

package/scripts/lib/graph_edges.rb

@@ -118,4 +118,20 @@ module GraphEdges
     visited[node] = true
     nil
   end
+
+  # The declared work ids whose `needs` reach a verify node without passing
+  # through another verify node (343 D7), in declaration order. `kinds` maps
+  # an id to its node kind, so this module stays blind to where a kind lives.
+  def review_fixes(edges, kinds)
+    edges.keys.select { |id| kinds[id] == "work" && reaches_verify?(id, edges, kinds, {}) }
+  end
+
+  def reaches_verify?(node, edges, kinds, seen)
+    (edges[node] || []).any? do |target|
+      next false if seen[target]
+
+      seen[target] = true
+      kinds[target] == "verify" || reaches_verify?(target, edges, kinds, seen)
+    end
+  end
 end

package/scripts/lib/hook_registry.rb

@@ -34,6 +34,17 @@ module HookRegistry
           { "name" => "check-update", "status" => "" },
         ] },
       ],
+      # Intent 355, n2: the call budget guard. Not one of the edit-path
+      # gates intent 302 removed (those denied a write on content; this
+      # denies a call on a per-attempt COUNT, read from the session's own
+      # transcript, never from the tool's arguments) - see scripts/hook-
+      # call-budget. Claude only: CODEX_LIVE_STATE_EVENTS below does not
+      # carry PreToolUse, so codex_hooks_json never projects it.
+      "PreToolUse" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "call-budget", "status" => "" },
+        ] },
+      ],
       "PreCompact" => [
         { "matcher" => "", "hooks" => [
           { "name" => "savepoint", "status" => "Saving Plastic intent state..." },
@@ -75,8 +86,9 @@ module HookRegistry
   # the PostToolUse record hook collapses from Claude's multi-tool matcher onto
   # Codex's single apply_patch tool (181 F4: apply_patch is Codex's sole
   # file-mutation tool; tool_name always reports apply_patch), and the live-state
-  # events project through whole. Since intent 302 there is no PreToolUse group at
-  # all: the edit-path gates are gone on both harnesses. Command invokes the
+  # events project through whole. PreToolUse (intent 355, n2's call-budget guard,
+  # Claude only) is not one of CODEX_LIVE_STATE_EVENTS below, so Codex still
+  # carries no PreToolUse group of its own. Command invokes the
   # codex-hook dispatcher with the hook name. Guide-settled shape [guide Part 3]:
   # top-level {"hooks":{<Event>: [{"matcher","hooks":[{"type":"command","command",
   # "statusMessage"}]}]}}, identical to Claude's shape, string command. Single

package/scripts/lib/installer_core.rb

@@ -438,6 +438,8 @@ class InstallerCore
       "scripts/verify-intent" => "scripts/verify-intent",
       "scripts/lib/exec_worktree.rb" => "scripts/lib/exec_worktree.rb",
       "scripts/exec-worktree" => "scripts/exec-worktree",
+      "scripts/lib/session_usage.rb" => "scripts/lib/session_usage.rb",
+      "scripts/session-usage" => "scripts/session-usage",
       "scripts/doctor.rb" => "scripts/doctor.rb",
       "scripts/lib/doctor_core.rb" => "scripts/lib/doctor_core.rb",
       "scripts/lib/hook_replay.rb" => "scripts/lib/hook_replay.rb",
@@ -543,6 +545,12 @@ class InstallerCore
       # by scripts/runner's `step`.
       "scripts/lib/runner_policy.rb" => "scripts/lib/runner_policy.rb",
       "scripts/lib/runner_dispatch.rb" => "scripts/lib/runner_dispatch.rb",
+      # Intent 355 (n2): the call budget PreToolUse hook (RunnerPolicy.call_cap
+      # is its cap table, above); its launcher (hooks/call-budget) ships via
+      # hook_files' own glob, so only the hook script itself needs an entry.
+      "scripts/hook-call-budget" => "scripts/hook-call-budget",
+      "scripts/meter-watch" => "scripts/meter-watch",
+      "scripts/lib/meter_watch.rb" => "scripts/lib/meter_watch.rb",
       # Intent 340 (G7, n6): answer (closes a decision node or unparks a
       # work node parked at needs_decision), proposals (mints ids for what
       # an executor proposed), and rewind (resets the intent branch to a
@@ -564,8 +572,8 @@ class InstallerCore
       version: 3
       execution_mode: subagent-driven
       stale_threshold_days: 3
-      context_offer_tokens: 350000
-      context_insist_tokens: 500000
+      context_offer_tokens: 150000
+      context_insist_tokens: 250000
       hash_length: 6
       hash_algorithm: sha256-base36
       max_slug_words: 5

package/scripts/lib/meter_watch.rb

@@ -0,0 +1,179 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "time"
+require "fileutils"
+require "rbconfig"
+require_relative "atomic_write"
+
+# MeterWatch (intent 355, n5, D6): reads the owner's rate-limit cache on a
+# timer and writes one state file a session watches, instead of every session
+# parsing the cache and re-deriving the thresholds for itself. No model call
+# is spent on a tick that leaves the state unchanged.
+#
+# Everything is injected: home (holds config.yml and .cache/), the clock, the
+# cache path, and the renamer AtomicWrite uses. Nothing reads ENV, nothing
+# calls launchctl, and --install-timer (scripts/meter-watch) only ever writes
+# under the injected home.
+class MeterWatch
+  DEFAULT_REDUCE_AT = 55
+  DEFAULT_STOP_AT = 85
+  DEFAULT_WEEKLY_STOP_AT = 97
+  TICK_SECONDS = 20 * 60
+  STALE_AFTER_SECONDS = TICK_SECONDS * 2
+
+  def initialize(home:, cache_path: nil, config_path: nil, now: Time.now, renamer: File.method(:rename))
+    @home = home
+    @cache_path = cache_path || File.join(home, ".cache", "rate-limits.json")
+    @config_path = config_path || File.join(home, "config.yml")
+    @state_path = File.join(home, ".cache", "meter-state.json")
+    @now = now
+    @renamer = renamer
+    @reduce_at, @stop_at, @weekly_stop_at = load_thresholds
+  end
+
+  attr_reader :state_path
+
+  def tick
+    previous = read_state
+    state = compute_state(previous)
+    write_if_changed(previous, state)
+  end
+
+  private
+
+  def compute_state(previous)
+    return base_state("unavailable") unless File.file?(@cache_path)
+    return stopped?(previous) ? previous : base_state("stale") if stale?
+
+    cache = JSON.parse(File.read(@cache_path))
+    five_hour = cache["five_hour"]
+    seven_day = cache["seven_day"]
+    resets_at = cache["resets_at"]
+
+    # Resume compares `now` against the STOP's OWN resets_at (carried
+    # forward on `previous`, from the tick that first wrote "stop"), never
+    # the cache's current resets_at: the cache moves resets_at on to the
+    # NEXT window before five_hour/seven_day themselves drop, so comparing
+    # against the live value would never report resume (B4).
+    label = if stopped?(previous) && reset_passed?(previous["resets_at"])
+              "resume"
+            else
+              classify(five_hour, seven_day)
+            end
+
+    base_state(label, five_hour: five_hour, seven_day: seven_day, resets_at: resets_at)
+  rescue JSON::ParserError
+    base_state("unavailable")
+  end
+
+  def stopped?(previous)
+    previous && previous["state"] == "stop"
+  end
+
+  def classify(five_hour, seven_day)
+    return "stop" if five_hour.to_f >= @stop_at
+    return "stop" if seven_day.to_f >= @weekly_stop_at
+    return "reduce" if five_hour.to_f >= @reduce_at
+
+    "ok"
+  end
+
+  def stale?
+    File.mtime(@cache_path) < (@now - STALE_AFTER_SECONDS)
+  rescue Errno::ENOENT
+    true
+  end
+
+  def reset_passed?(resets_at)
+    at = parse_time(resets_at)
+    at && @now >= at
+  end
+
+  def parse_time(value)
+    return nil if value.nil? || value.to_s.empty?
+
+    text = value.to_s
+    text.match?(/\A\d+\z/) ? Time.at(text.to_i).utc : Time.iso8601(text)
+  rescue ArgumentError, TypeError
+    nil
+  end
+
+  def base_state(label, five_hour: nil, seven_day: nil, resets_at: nil)
+    {
+      "state" => label,
+      "five_hour" => five_hour,
+      "seven_day" => seven_day,
+      "resets_at" => resets_at,
+      "checked_at" => @now.getutc.iso8601,
+    }
+  end
+
+  def write_if_changed(previous, state)
+    return state if previous && previous["state"] == state["state"]
+
+    FileUtils.mkdir_p(File.dirname(@state_path))
+    AtomicWrite.write(@state_path, JSON.generate(state), renamer: @renamer)
+    state
+  end
+
+  def read_state
+    return nil unless File.file?(@state_path)
+
+    JSON.parse(File.read(@state_path))
+  rescue JSON::ParserError
+    nil
+  end
+
+  def load_thresholds
+    config = File.file?(@config_path) ? (YAML.safe_load(File.read(@config_path)) || {}) : {}
+    meter = config["meter"].is_a?(Hash) ? config["meter"] : {}
+    [
+      meter.fetch("reduce_at", DEFAULT_REDUCE_AT),
+      meter.fetch("stop_at", DEFAULT_STOP_AT),
+      meter.fetch("weekly_stop_at", DEFAULT_WEEKLY_STOP_AT),
+    ]
+  end
+
+  class << self
+    # Writes the LaunchAgent plist under an injectable home; never loads it
+    # with launchctl (scripts/meter-watch --install-timer calls this and
+    # nothing else). RunAtLoad primes the first tick; StartInterval repeats
+    # it every 20 minutes.
+    def install_timer(home:, script_path:, ruby: RbConfig.ruby, interval: TICK_SECONDS)
+      agents_dir = File.join(home, "Library", "LaunchAgents")
+      FileUtils.mkdir_p(agents_dir)
+      plist_path = File.join(agents_dir, "com.plastic.meter-watch.plist")
+      File.write(plist_path, plist(script_path, home, ruby, interval))
+      plist_path
+    end
+
+    private
+
+    def plist(script_path, home, ruby, interval)
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+          <key>Label</key>
+          <string>com.plastic.meter-watch</string>
+          <key>ProgramArguments</key>
+          <array>
+            <string>#{ruby}</string>
+            <string>#{script_path}</string>
+            <string>--home</string>
+            <string>#{home}</string>
+          </array>
+          <key>StartInterval</key>
+          <integer>#{interval}</integer>
+          <key>RunAtLoad</key>
+          <true/>
+        </dict>
+        </plist>
+      XML
+    end
+  end
+end