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

package/scripts/lib/node_packet.rb

@@ -425,7 +425,15 @@ module NodePacket
     verify.split("\n").map(&:strip).reject(&:empty?).join("; ")
   end
 
-  def test_command_block(intent_dir:, project_reader: method(:default_project_reader))
+  # `files` (intent 355, n4, D5): a node's own declared `*_test.rb` files
+  # name the only test command the executor needs - `bin/test --only <those
+  # files>` - so it never has to invent one or fall back to the project's
+  # generic `release.verify`. A node that declares no test files (a docs-only
+  # node, say) still falls back to `project_reader` exactly as before.
+  def test_command_block(intent_dir:, files: [], project_reader: method(:default_project_reader))
+    named = Array(files).select { |f| f.to_s.end_with?("_test.rb") }
+    return "test command: ruby bin/test --only #{named.join(' ')}" if named.any?
+
     cmd = project_reader.call(intent_dir)
     cmd ? "test command: #{cmd}" : "test command: none recorded in the project record"
   end
@@ -435,14 +443,26 @@ module NodePacket
   # carries no lease. `worktree_block` already renders its own copy when the
   # worktree is unprovisioned; the two conditions often fire together, so a
   # directive already present is never repeated.
+  #
+  # `call_cap` (intent 355, n2, D2): one sentence naming this attempt's tool
+  # call cap and the return it hits at, so the executor learns the number
+  # from the packet it starts with, never from a denied call mid-edit
+  # (matrix 2.4). nil (a caller that names no cap) renders nothing here.
   def where_to_work_block(intent_dir:, worktree_reader: Arm.method(:worktree_block),
-                           project_reader: method(:default_project_reader), lease_missing: false)
+                           project_reader: method(:default_project_reader), lease_missing: false, call_cap: nil,
+                           files: [])
     wt = worktree_block(intent_dir: intent_dir, worktree_reader: worktree_reader)
-    parts = [wt, test_command_block(intent_dir: intent_dir, project_reader: project_reader)]
+    parts = [wt, test_command_block(intent_dir: intent_dir, files: files, project_reader: project_reader)]
     parts << STOP_DIRECTIVE if lease_missing && !wt.include?(STOP_DIRECTIVE)
+    parts << call_cap_sentence(call_cap) if call_cap
     parts.join("\n")
   end
 
+  def call_cap_sentence(call_cap)
+    "call budget: this attempt may make at most #{call_cap} tool calls; past that a hook denies the " \
+      "next one, so commit what is green and return failed_verification reason=call_budget."
+  end
+
   # --- section and list parsing (shared) -------------------------------------
 
   # The body of the FIRST heading, at exactly `level` `#` characters, whose
@@ -786,7 +806,8 @@ module NodePacket
   def build(intent_dir:, node:, budget_tokens: nil, hop_tokens: DEFAULT_HOP_TOKENS,
             holder: nil, expires: nil, model: nil, attempt: nil, out: nil, force: false,
             renamer: File.method(:rename), git_runner: DEFAULT_GIT_RUNNER,
-            worktree_reader: Arm.method(:worktree_block), project_reader: method(:default_project_reader))
+            worktree_reader: Arm.method(:worktree_block), project_reader: method(:default_project_reader),
+            call_cap: nil)
     intent_dir = File.expand_path(intent_dir)
 
     nb = node_block(intent_dir: intent_dir, node: node)
@@ -826,7 +847,8 @@ module NodePacket
     # ledger data (spec D3's self-cancellation risk).
     missing_lease = lease_missing?(node: node, holder: holder, expires: expires, model: model, entries: entries)
     where_text = where_to_work_block(intent_dir: intent_dir, worktree_reader: worktree_reader,
-                                      project_reader: project_reader, lease_missing: missing_lease)
+                                      project_reader: project_reader, lease_missing: missing_lease,
+                                      call_cap: call_cap, files: nb[:files])
 
     state = {
       node_text: nb[:text], ledger_text: ledger_text, intent_text: record[:intent],

package/scripts/lib/runner_dispatch.rb

@@ -45,6 +45,22 @@ module RunnerDispatch
 
   HARD_CAP_RE = /\Ais at its dispatch cap \((\d+)\/(\d+)\)\z/.freeze
 
+  # D8 (355, n6): the agent every dispatched, non-decision node names - a
+  # role, never a harness (matrix 6.5), and never `plastic-advisor`, which
+  # stays a deliberate, never-auto-dispatched consultation agent.
+  SPAWN_AGENT = "plastic-executor"
+
+  # matrix 6.1/6.2: one spawn block per dispatched node - agent, the model
+  # RunnerPolicy.model_for resolved, the packet path, the one test command
+  # (NodePacket.test_command_block, n4), and the call cap (n2) - fenced so a
+  # session pastes it straight into the Agent tool (327 D42: the runner
+  # itself never spawns).
+  def spawn_block(model:, packet:, test_command:, call_cap:, agent: SPAWN_AGENT)
+    lines = ["agent: #{agent}", "model: #{model}", "packet: #{packet}", test_command,
+             NodePacket.call_cap_sentence(call_cap)]
+    (["```"] + lines + ["```"]).join("\n")
+  end
+
   # dispatch(context, limit:) -> a result hash. Always carries :ok, :reason,
   # :errors, :rearm_command, :dispatched, :stop, :parked, :status, :blockers,
   # :plan - fields that do not apply to a given outcome stay nil/empty rather
@@ -195,6 +211,7 @@ module RunnerDispatch
     holder = context.session
     model = RunnerPolicy.model_for(kind, config: config)
     expires = RunnerPolicy.lease_expires(kind, now: now)
+    calls_cap = RunnerPolicy.call_cap(kind, config: config)
 
     # Row 10.16/M13: recorded BEFORE provisioning - a worktree this dispatch
     # finds already on disk (kept there by a prior failed_verification
@@ -223,7 +240,7 @@ module RunnerDispatch
     # default (row 10.9).
     build_result = packet_builder.call(intent_dir: intent_dir, node: node, holder: holder, expires: expires,
                                         model: model, force: true, worktree_reader: node_reader,
-                                        budget_tokens: node_declared_budget(intent_dir, node))
+                                        budget_tokens: node_declared_budget(intent_dir, node), call_cap: calls_cap)
     unless build_result[:ok]
       # M6: a failed packet build never leaves an orphan worktree behind, and
       # its errors travel back up so the step's report can name the node and
@@ -236,7 +253,7 @@ module RunnerDispatch
     precondition = lambda do |c|
       ReadySet.ready?(content: c, subject: node, graph: { edges: edges }, nodes: nodes_decl, caps: caps)[:ready]
     end
-    fields = { holder: holder, expires: expires, packet: build_result[:sha], model: model }
+    fields = { holder: holder, expires: expires, packet: build_result[:sha], model: model, calls: calls_cap }
 
     result = begin
       ledger.append_transition(savepoint_path, subject: node, state: "running", fields: fields, now: now,
@@ -254,10 +271,13 @@ module RunnerDispatch
       return { ok: false }
     end
 
+    test_command = NodePacket.test_command_block(intent_dir: intent_dir, files: (nodes_decl[node] || {})[:files])
+    spawn = spawn_block(model: model, packet: build_result[:path], test_command: test_command, call_cap: calls_cap)
+
     {
       ok: true,
       entry: { node: node, kind: kind.to_s, role: role_for(kind), model: model, worktree: provisioned[:path],
-                packet: build_result[:path] },
+                packet: build_result[:path], spawn: spawn },
     }
   end
 
@@ -461,7 +481,10 @@ module RunnerDispatch
   # Row 5.22/5.23/5.24: one machine-readable (YAML) document naming, per
   # dispatched node, the packet path, the model, the worktree, the kind and
   # the role, plus the return contract ONCE at the top level - never inside
-  # any one node's packet.
+  # any one node's packet. Row 6.4: "spawn" carries the same, already fully
+  # rendered spawn block for each dispatched node in order, so any reader of
+  # this data (YAML today, JSON if it is ever re-serialized) finds it under
+  # `spawn` rather than re-deriving it from the other fields.
   def render_plan(dispatched)
     return nil if dispatched.empty?
 
@@ -470,7 +493,8 @@ module RunnerDispatch
       "dispatch" => dispatched.map do |d|
         { "node" => d[:node], "kind" => d[:kind], "role" => d[:role], "model" => d[:model],
           "worktree" => d[:worktree], "packet" => d[:packet] }
-      end
+      end,
+      "spawn" => dispatched.map { |d| d[:spawn] }
     )
   end
   private_class_method :render_plan

package/scripts/lib/runner_policy.rb

@@ -139,4 +139,35 @@ module RunnerPolicy
   def lease_expires(kind, now: Time.now)
     (now + (lease_minutes(kind) * 60)).utc.strftime("%Y-%m-%dT%H:%M:%SZ")
   end
+
+  # --- call budget (intent 355, n2) -------------------------------------------
+  #
+  # D2: a cap on tool calls per attempt, enforced by a PreToolUse hook that
+  # counts tool calls in the session transcript. Shipped per kind (matrix
+  # 2.1); `decision` carries one too even though it is never dispatched
+  # (327 D12 leaves it out of every lease table for the same reason), so
+  # `call_cap` never has to special-case an unknown kind here any more than
+  # `retry_cap` does.
+  CALL_CAP_TABLE = { "work" => 60, "verify" => 40, "research" => 40, "decision" => 10 }.freeze
+
+  # matrix 5.17's own fallback rule, one call: an unknown or nil kind reads
+  # `work`'s cap, never a fourth, undeclared number.
+  def call_cap(kind, config: {})
+    override = call_caps_section(config)[kind.to_s]
+    present?(override) ? override.to_i : CALL_CAP_TABLE.fetch(kind.to_s, CALL_CAP_TABLE["work"])
+  end
+
+  # matrix 2.2: `runner.call_caps.<kind>` in the project config overrides the
+  # shipped cap, the same nested-Hash shape AgentModels.models_section reads
+  # `agents.models` from - one more caller of the pattern, not a new one.
+  def call_caps_section(config)
+    return {} unless config.is_a?(Hash)
+
+    runner = config["runner"]
+    return {} unless runner.is_a?(Hash)
+
+    section = runner["call_caps"]
+    section.is_a?(Hash) ? section : {}
+  end
+  private_class_method :call_caps_section
 end

package/scripts/lib/runner_proposals.rb

@@ -46,6 +46,8 @@ module RunnerProposals
     "research" => "node-research.md",
   }.freeze
 
+  REVIEW_FIX_CAP = 2
+
   # accept(context, proposer:, proposed_nodes:, proposed_edges:, now:,
   # validator:, templates_dir:, renamer:) -> {ok:, minted:, validator:,
   # errors:}. `proposer` names the node whose return carried these proposals
@@ -129,6 +131,14 @@ module RunnerProposals
       edge_specs << { from: from, to: to }
     end
 
+    trial_nodes = loaded[:nodes].merge(node_specs.to_h { |s| [s[:id], { kind: s[:kind] }] })
+    existing_fixes = review_fix_count(loaded[:edges], loaded[:nodes])
+    trial_fixes = review_fix_count(trial_edges, trial_nodes)
+    if trial_fixes > [existing_fixes, REVIEW_FIX_CAP].max
+      return refuse(intent_dir, proposer,
+                     "proposal refused (review_fix_cap): would make #{trial_fixes} review fixes, the cap is #{REVIEW_FIX_CAP}", now)
+    end
+
     node_specs.each { |s| scaffold_node_file(intent_dir, s) }
     if node_specs.any? || edge_specs.any?
       append_to_graph(graph_path, node_specs: node_specs, edge_specs: edge_specs, renamer: renamer)
@@ -141,6 +151,17 @@ module RunnerProposals
     { ok: true, minted: node_specs.map { |s| s[:id] }, validator: safe_validate(validator, intent_dir), errors: [] }
   end
 
+  # --- review fixes (355 D4) -------------------------------------------------
+
+  # review_fix_count(edges, nodes) -> how many work nodes GraphEdges.review_fixes
+  # finds, a node's kind read from its declaration and, when that is missing,
+  # from its id's NodeFile::KIND_PREFIX (343 D6).
+  def review_fix_count(edges, nodes)
+    ids = (edges.keys + edges.values.flatten).uniq
+    kinds = ids.to_h { |id| [id, (nodes[id] || {})[:kind] || NodeFile::KIND_PREFIX.key(id.to_s[/\A[a-z]+/])] }
+    GraphEdges.review_fixes(edges, kinds).length
+  end
+
   # --- node scaffolding --------------------------------------------------
 
   # A template's own placeholder id ("n1", "v1", ...) is replaced only as a

package/scripts/lib/session_usage.rb

@@ -0,0 +1,190 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+# SessionUsage (intent 355, D10): reads the harness transcripts modified since
+# a cutoff, dedupes assistant records by message id (the harness logs one
+# record per content block), and reports per session the model, the calls in
+# the window, the boot and last context, the median step, the steps over 5k,
+# and the cache read. Context is input plus cache read plus cache write.
+# Broken records are counted and named, never averaged over. The transcripts
+# root and the rate-limit cache path are injected; nothing reads ENV.
+class SessionUsage
+  WINDOW = 5 * 3600
+  BIG_STEP = 5_000
+  LABEL_WIDTH = 70
+  NO_PROMPT = "(no prompt)"
+  SYNTHETIC_MODEL = "<synthetic>"
+  CONTEXT_FIELDS = %w[input_tokens cache_read_input_tokens cache_creation_input_tokens].freeze
+  TRANSCRIPT_GLOBS = [File.join("*", "*.jsonl"), File.join("*", "*", "subagents", "*.jsonl")].freeze
+  HEADERS = ["session", "model", "calls", "boot", "last", "median step", "big steps", "cache read", "broken", "prompt"].freeze
+
+  def initialize(transcripts_root:, rate_limits_path:, now: Time.now)
+    @transcripts_root = transcripts_root
+    @rate_limits_path = rate_limits_path
+    @now = now
+  end
+
+  def cutoff(since: nil)
+    return [since, "since"] if since
+
+    reset = reset_time
+    return [reset - WINDOW, "rate-limit reset"] if reset && reset > @now
+
+    [@now - WINDOW, "last 5 hours"]
+  end
+
+  def report(since: nil)
+    at, source = cutoff(since: since)
+    header = { "status" => "ok", "root" => @transcripts_root, "cutoff" => at.getutc.iso8601, "cutoff_source" => source }
+    return header.merge("status" => "unavailable") unless File.directory?(@transcripts_root)
+
+    broken = []
+    sessions = transcripts(at).filter_map { |path| summarize(path, at, broken) }
+    header.merge("sessions" => sessions.sort_by { |s| -s["cache_read"] }, "broken" => broken)
+  end
+
+  def self.render_text(report)
+    return "Session usage: unavailable (no transcripts directory at #{report['root']})\n" if report["status"] == "unavailable"
+
+    out = +"Session usage since #{report['cutoff']} (#{report['cutoff_source']})\n\n"
+    out << (report["sessions"].empty? ? "(no sessions)\n" : table(report["sessions"]))
+    return out if report["broken"].empty?
+
+    out << "\nBroken records (#{report['broken'].size}):\n"
+    report["broken"].each { |b| out << "  #{b['file']}:#{b['line']}  #{b['error']}\n" }
+    out
+  end
+
+  def self.table(sessions)
+    rows = sessions.map do |s|
+      boot = tokens(s["boot"]) + (s["started_before_cutoff"] ? "*" : "")
+      [s["id"], s["model"].to_s, s["calls"].to_s, boot, tokens(s["last"]), tokens(s["median_step"]),
+       s["big_steps"].to_s, tokens(s["cache_read"]), s["broken"].to_s, s["label"]]
+    end
+    widths = HEADERS.each_index.map { |i| ([HEADERS] + rows).map { |r| r[i].length }.max }
+    lines = ([HEADERS] + rows).map { |r| r.each_with_index.map { |cell, i| cell.ljust(widths[i]) }.join("  ").rstrip }
+    note = sessions.any? { |s| s["started_before_cutoff"] } ? "\n* boot predates the cutoff\n" : ""
+    lines.join("\n") + "\n" + note
+  end
+
+  def self.tokens(count)
+    return "-" if count.nil?
+
+    count.abs >= 1_000 ? format("%.1fk", count / 1_000.0) : count.to_s
+  end
+
+  private_class_method :table, :tokens
+
+  private
+
+  def reset_time
+    return unless File.file?(@rate_limits_path)
+
+    value = JSON.parse(File.read(@rate_limits_path))["resets_at"].to_s
+    return if value.empty?
+
+    value.match?(/\A\d+\z/) ? Time.at(value.to_i).utc : Time.iso8601(value)
+  rescue JSON::ParserError, ArgumentError, TypeError
+    nil
+  end
+
+  def transcripts(cutoff)
+    TRANSCRIPT_GLOBS.flat_map { |glob| Dir.glob(File.join(@transcripts_root, glob)) }
+                    .select { |path| File.mtime(path) >= cutoff }
+                    .sort
+  end
+
+  def summarize(path, cutoff, broken)
+    calls = {}
+    label = nil
+    torn = 0
+    File.foreach(path).with_index(1) do |line, number|
+      next if line.strip.empty?
+
+      record = JSON.parse(line)
+      raise TypeError, "record is not a JSON object" unless record.is_a?(Hash)
+
+      label ||= prompt_line(record)
+      call = call_from(record)
+      next unless call
+
+      calls[call[:id]] = calls.key?(call[:id]) ? call.merge(at: calls[call[:id]][:at]) : call
+    rescue JSON::ParserError
+      torn += 1
+      broken << { "file" => path, "line" => number, "error" => "unparsable JSON" }
+    rescue ArgumentError, TypeError => e
+      torn += 1
+      broken << { "file" => path, "line" => number, "error" => e.message }
+    end
+    row(path, calls.values, cutoff, label, torn)
+  end
+
+  def row(path, calls, cutoff, label, torn)
+    window = calls.each_index.select { |i| calls[i][:at] >= cutoff }
+    return if window.empty? && torn.zero?
+
+    steps = window.filter_map { |i| calls[i][:context] - calls[i - 1][:context] if i.positive? }
+    {
+      "id" => File.basename(path, ".jsonl"),
+      "file" => path,
+      "label" => label || NO_PROMPT,
+      "model" => calls.last && calls.last[:model],
+      "calls" => window.size,
+      "boot" => calls.first && calls.first[:context],
+      "last" => calls.last && calls.last[:context],
+      "median_step" => median(steps),
+      "big_steps" => steps.count { |step| step > BIG_STEP },
+      "cache_read" => window.sum { |i| calls[i][:cache_read] },
+      "broken" => torn,
+      "started_before_cutoff" => !calls.empty? && calls.first[:at] < cutoff,
+    }
+  end
+
+  def call_from(record)
+    return unless record["type"] == "assistant"
+
+    message = record["message"]
+    raise TypeError, "assistant record without a message" unless message.is_a?(Hash)
+    return if message["model"] == SYNTHETIC_MODEL
+
+    usage = message["usage"]
+    raise ArgumentError, "assistant record without message id or usage" unless message["id"] && usage.is_a?(Hash)
+
+    {
+      id: message["id"],
+      model: message["model"],
+      at: Time.iso8601(record["timestamp"].to_s),
+      context: CONTEXT_FIELDS.sum { |field| usage[field].to_i },
+      cache_read: usage["cache_read_input_tokens"].to_i,
+    }
+  end
+
+  def prompt_line(record)
+    return unless record["type"] == "user" && !record["isMeta"]
+
+    text = prompt_text(record["message"].is_a?(Hash) ? record["message"]["content"] : nil)
+    return if text.nil?
+
+    first = text.lines.map(&:strip).find { |line| !line.empty? && !line.start_with?("<") }
+    first && first[0, LABEL_WIDTH]
+  end
+
+  def prompt_text(content)
+    return content if content.is_a?(String)
+    return unless content.is_a?(Array)
+
+    block = content.find { |b| b.is_a?(Hash) && b["type"] == "text" }
+    block && block["text"]
+  end
+
+  def median(values)
+    return if values.empty?
+
+    sorted = values.sort
+    middle = sorted.size / 2
+    sorted.size.odd? ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2
+  end
+end

package/scripts/meter-watch

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# meter-watch (intent 355, n5, D6): reads the rate-limit cache under --home
+# and writes ~/.plastic/.cache/meter-state.json with the state (ok, reduce,
+# stop, resume, stale, unavailable), the two raw percentages, the reset
+# time, and when it was checked. A session watches that one file instead of
+# every session parsing the cache and re-deriving the thresholds.
+#
+# Usage:
+#   meter-watch [--home DIR]
+#   meter-watch --install-timer [--home DIR]
+#
+# --install-timer writes a LaunchAgent plist under --home (default
+# ~/.plastic when --home is not given) that runs this tick every 20
+# minutes. It never calls launchctl; load it yourself with the command it
+# prints. The Plastic installer never calls --install-timer on its own.
+#
+# Exit codes: 0 reported (unavailable included); 2 usage error.
+
+require "json"
+require_relative "lib/meter_watch"
+
+def usage_abort(message)
+  warn "meter-watch: #{message}"
+  warn "Usage: meter-watch [--home DIR] [--install-timer]"
+  exit 2
+end
+
+home = File.join(Dir.home, ".plastic")
+install_timer = false
+
+argv = ARGV.dup
+until argv.empty?
+  case (token = argv.shift)
+  when "--home"
+    usage_abort("--home requires a value") if argv.empty?
+    home = argv.shift
+  when "--install-timer"
+    install_timer = true
+  else
+    usage_abort("unknown argument #{token.inspect}")
+  end
+end
+
+home = File.expand_path(home)
+
+if install_timer
+  plist_path = MeterWatch.install_timer(home: home, script_path: File.expand_path(__FILE__))
+  puts "Installed LaunchAgent at #{plist_path}"
+  puts "Run `launchctl load #{plist_path}` to activate it."
+  exit 0
+end
+
+state = MeterWatch.new(home: home).tick
+puts JSON.generate(state)

package/scripts/read-config

@@ -14,9 +14,9 @@ require_relative "lib/agent_models"
 DEFAULTS = {
   "version" => 3,
   "stale_threshold_days" => 3,
-  # Absolute token counts for a 1M window, 35 and 50 percent (intent 312, 296 D38).
-  "context_offer_tokens" => 350_000,
-  "context_insist_tokens" => 500_000,
+  # Absolute token counts for a 1M window, 15 and 25 percent (intent 355, n5, D7).
+  "context_offer_tokens" => 150_000,
+  "context_insist_tokens" => 250_000,
   "execution_mode" => "subagent-driven",
   "hash_length" => 6,
   "hash_algorithm" => "sha256-base36",

package/scripts/runner

@@ -5,6 +5,7 @@
 require_relative "lib/savepoint"
 require_relative "lib/ready_set"
 require_relative "lib/runner_core"
+require_relative "lib/runner_proposals"
 
 # runner - the one executable over the graph-ready loop's declared node graph
 # (intent 340, G7, n1). A subcommand table: the public verbs (step, status,
@@ -138,6 +139,10 @@ module Runner
       end
     end
 
+    graph = context.graph || {}
+    fixes = RunnerProposals.review_fix_count(graph[:edges] || {}, graph[:nodes] || {})
+    puts "review fixes: #{fixes} of #{RunnerProposals::REVIEW_FIX_CAP}"
+
     complete = RunnerCore.complete?(context)
     puts
     puts complete ? "complete" : "stalled"

package/scripts/session-usage

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# session-usage (intent 355, D10): read the harness transcripts since a cutoff
+# and report per session the model, calls, boot context, last context, median
+# step, steps over 5k, and cache read. Broken records are counted and named.
+#
+# Usage:
+#   session-usage [--since <iso8601>] [--format text|json] [--root <dir>] [--rate-limits <file>]
+#
+# Defaults: the root is ~/.claude/projects, the rate-limit cache is
+# ~/.plastic/.cache/rate-limits.json, and the cutoff is that cache's reset
+# time minus five hours, else the last five hours.
+#
+# Exit codes: 0 reported (unavailable included); 2 usage error.
+
+require "json"
+require "time"
+require_relative "lib/session_usage"
+
+FLAGS = %w[--since --format --root --rate-limits].freeze
+FORMATS = %w[text json].freeze
+
+def usage_abort(message)
+  warn "session-usage: #{message}"
+  warn "Usage: session-usage [--since <iso8601>] [--format text|json] [--root <dir>] [--rate-limits <file>]"
+  exit 2
+end
+
+def parse_args(argv)
+  usage_abort("every flag takes a value") if argv.length.odd?
+  opts = argv.each_slice(2).to_h
+  unknown = opts.keys - FLAGS
+  usage_abort("unknown flag #{unknown.first.inspect}") unless unknown.empty?
+  usage_abort("unknown format #{opts['--format'].inspect}") if opts["--format"] && !FORMATS.include?(opts["--format"])
+  opts
+end
+
+def parse_since(value)
+  value && Time.iso8601(value)
+rescue ArgumentError
+  usage_abort("--since #{value.inspect} is not an ISO 8601 time")
+end
+
+opts = parse_args(ARGV)
+usage = SessionUsage.new(
+  transcripts_root: File.expand_path(opts.fetch("--root", File.join(Dir.home, ".claude", "projects"))),
+  rate_limits_path: File.expand_path(opts.fetch("--rate-limits", File.join(Dir.home, ".plastic", ".cache", "rate-limits.json")))
+)
+report = usage.report(since: parse_since(opts["--since"]))
+if opts["--format"] == "json"
+  puts JSON.pretty_generate(report)
+else
+  print SessionUsage.render_text(report)
+end

package/skills/auto/SKILL.md

@@ -13,20 +13,18 @@ user-invocable: true
 Announce: "Taking over intent [ID] - [name] for autonomous delivery."
 
 **Advisory (not a rule).** At auto-mode start, recommend once that the user run this
-orchestrating main session on the best available thinking model (Fable, Opus, or whatever
-supersedes them). This is advice only: it changes no behavior. Dispatched agents keep their
-configured model and never resolve to Fable unless an explicit `agents.models.<name>` config
-override names Fable for that role. The two advisors, `plastic-advisor` and
-`plastic-faux-advisor`, are consultation roles the user or the main session summons
-deliberately; the auto pipeline never dispatches them.
+orchestrating session on the best available thinking model (Fable, Opus, or whatever supersedes
+them); this is advice only, and dispatched agents keep their configured model, never resolving
+to Fable without an explicit `agents.models.<name>` config override. `plastic-advisor` and
+`plastic-faux-advisor` are consultation roles the user or this session summons deliberately;
+the auto pipeline never dispatches them.
 
 ## Precondition
 
 An active intent MUST exist in INDEX.md. If none exists, refuse: "No active intent found.
 Create one first with /plastic-intent-creating."
 
-If several active intents exist, ask the user which one to deliver (the one question auto asks
-at boarding, before delivery starts).
+If several active intents exist, ask which to deliver (the one question auto asks at boarding).
 
 **Picking work when no intent is specified.** If the user says "auto" without naming an intent
 and none is active, consult the roadmap first (the primary planning surface), then fall back to
@@ -42,9 +40,8 @@ frontier batch is still delivering, report it and wait, never dispatch a later b
 `exhausted` means fall back to `ruby ~/.plastic/scripts/dashboard.rb all --json` and work its
 `dispatchable_queue` in `rank` order, leaving `human_only` and `next_big_thing` for the user.
 
-QMD-first (when available): when the user describes the work rather than naming an intent, run
-`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` before scanning the store, then open the
-authoritative intent file for the hit you take over. The command is a no-op when QMD is absent.
+QMD-first (when available): when the user describes the work instead of naming an intent, run
+`ruby ~/.plastic/scripts/qmd-sync search "<terms>"` first, then open the hit's authoritative intent file; a no-op when QMD is absent.
 
 ## Take the intent (do this FIRST)
 
@@ -90,6 +87,12 @@ tier and no stage agent; depth follows the work.
 Two boots is the normal delivery; the third is the exception the risk rule names. The lead is
 this session (the `plastic-enforcer` role), never a dispatched agent.
 
+A lead is a choice, not a requirement (D8, 355). `runner step` computes the plan and prints a
+spawn block per node - agent, model, packet path, the test command, the call cap - fenced for a
+session to paste into the Agent tool; the runner never spawns (327 D42). A lead earns its keep
+on a graph carrying a decision node, weighing its `needs_decision` stop; a graph with none runs
+end to end from `runner step` alone.
+
 ## Team
 
 - **plastic-enforcer**: this session. Writes the Why and How record, dispatches, folds reviews,
@@ -148,13 +151,10 @@ each one as a delegate before (or when) it needs to write into the intent dir:
 
 Only the owner can delegate. Delegates cannot re-delegate or release.
 
-Headless note: in a headless or background run the session id may be unset; the arm verb then
-keys the lock by a derived key and the record hook still writes the savepoint ledger from the
-written path. Verify the lock with `plastic-lock status` rather than assuming.
+Headless note: in a headless or background run the session id may be unset; the arm verb then keys the lock by a derived key and the record hook still writes the ledger.
+Verify with `plastic-lock status` rather than assuming.
 
-Solo fallback: on a harness with no agent dispatch (Codex CLI today), this session walks the
-five steps itself: it still writes the matrix, still writes the tests first, and reviews its own
-plan against the matrix before code, saying so in `## Insights`.
+Solo fallback: on a harness with no agent dispatch (Codex CLI today), this session walks the five steps itself, still writing the matrix and the tests first and reviewing its own plan against the matrix before code, saying so in `## Insights`.
 
 ## Stage-Aware Entry
 

package/skills/intent-executing/SKILL.md

@@ -44,6 +44,10 @@ Dispatches subagents to do the work. The controller never implements. It dispatc
 
 The post-execution review in Step 3 runs by risk (the rule lives in the auto skill). When it runs, the reviewer is a separate agent with fresh context, never the maker. The plan itself is reviewed before code by the adversarial plan reviewer (`plan-reviewer-prompt.md`), dispatched by the lead at How.
 
+### Graph dispatch: the paste
+
+When the plan is a graph (`nodes/*.md`, not `plan.md` plus action files), the dispatch step is the paste, not a lead's hand-typed brief. `runner step` computes readiness, applies policy, and prints a spawn block per dispatched node - agent, model, packet path, the one test command, the call cap - fenced in its own stdout. Copy each block into the Agent tool as its own dispatch, verbatim; the runner itself never spawns an agent (327 D42).
+
 ### Inline (Fallback)
 Executes tasks sequentially in the current session. Use when subagents aren't available or user explicitly requests inline mode.
 

package/templates/config.yml

@@ -2,11 +2,11 @@ version: 3
 project_roots:
   - ~/.plastic/projects
 stale_threshold_days: 3
-# When to compact. Absolute token counts for a 1M window (35 and 50 percent), not
+# When to compact. Absolute token counts for a 1M window (15 and 25 percent), not
 # percentages: models are reliable only to roughly 50 to 65 percent of advertised
 # context, so a percentage that is right at 200k floats to an untested size at 1M.
-context_offer_tokens: 350000
-context_insist_tokens: 500000
+context_offer_tokens: 150000
+context_insist_tokens: 250000
 execution_mode: subagent-driven
 hash_length: 6
 hash_algorithm: sha256-base36