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

package/scripts/roadmap-graph

@@ -0,0 +1,119 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# roadmap-graph - the CLI over the roadmap graph model (intent 337, G4):
+# `check`, `render`, `migrate`, every verb honouring --dry-run.
+#
+# Usage:
+#   roadmap-graph check <roadmap.md> [--dry-run]
+#   roadmap-graph render <roadmap.md> [--dry-run]
+#   roadmap-graph migrate <roadmap.md> [--dry-run]
+#
+# Exit codes:
+#   0 - printed / rendered / migrated cleanly (or a migrate skip: the
+#       roadmap already carries a graph)
+#   1 - a real finding: a cyclic graph, a dangling id, or a render/migrate
+#       refusal (no ## Graph, no grouping heading)
+#   2 - usage: no argument, an unknown verb, or a missing/non-file path
+
+require_relative "lib/roadmap_graph"
+require_relative "lib/roadmap_render"
+require_relative "lib/roadmap_migration"
+
+module RoadmapGraphCli
+  module_function
+
+  VERBS = %w[check render migrate].freeze
+
+  def usage
+    warn "Usage: roadmap-graph <#{VERBS.join('|')}> <roadmap.md> [--dry-run]"
+  end
+
+  def main(argv)
+    args = argv.dup
+    dry_run = !!args.delete("--dry-run")
+
+    verb = args.shift
+    unless verb && VERBS.include?(verb)
+      warn "roadmap-graph: unknown verb #{verb.inspect} (use #{VERBS.join(', ')})" if verb
+      usage
+      return 2
+    end
+
+    path = args.shift
+    unless path && File.file?(path)
+      warn "roadmap-graph: #{path.inspect} is not a file"
+      return 2
+    end
+
+    case verb
+    when "check" then check(path)
+    when "render" then render(path, dry_run)
+    when "migrate" then migrate(path, dry_run)
+    end
+  end
+
+  def check(path)
+    result = RoadmapGraph.analyze(path)
+    unless result[:has_graph]
+      warn "roadmap-graph check: #{result[:reason]}"
+      return 1
+    end
+    if result[:cycle]
+      warn "roadmap-graph check: cyclic graph: #{result[:cycle].join(' > ')}"
+      return 1
+    end
+    if result[:reason]
+      warn "roadmap-graph check: #{result[:reason]}"
+      return 1
+    end
+
+    puts "Batches: #{result[:batches].map { |b| b.join(', ') }.join(' | ')}"
+    puts "Ready: #{result[:ready].join(', ')}"
+    puts "Dead ends: #{result[:dead_ends].join(', ')}" unless result[:dead_ends].empty?
+
+    unless result[:dangling].empty?
+      warn "roadmap-graph check: graph names #{result[:dangling].map(&:inspect).join(', ')}, no batch entry"
+      return 1
+    end
+
+    0
+  end
+
+  def render(path, dry_run)
+    result = RoadmapRender.write(path, dry_run: dry_run)
+    unless result[:ok]
+      warn "roadmap-graph render: #{result[:error]}"
+      return 1
+    end
+
+    if dry_run
+      puts result[:content]
+    else
+      puts "roadmap-graph render: wrote #{path}"
+    end
+    0
+  end
+
+  def migrate(path, dry_run)
+    result = RoadmapMigration.write(path, dry_run: dry_run)
+    unless result[:ok]
+      if result[:skipped]
+        puts "roadmap-graph migrate: #{result[:reason]}"
+        return 0
+      end
+      warn "roadmap-graph migrate: #{result[:reason]}"
+      return 1
+    end
+
+    if dry_run
+      puts result[:content]
+    else
+      puts "roadmap-graph migrate: wrote #{path}"
+    end
+    0
+  end
+end
+
+exit(RoadmapGraphCli.main(ARGV)) if $PROGRAM_NAME == __FILE__

package/scripts/roadmap-savepoint

@@ -18,6 +18,7 @@
 # rebuilds an empty ledger.
 
 require_relative "lib/roadmap_savepoint"
+require_relative "lib/guarded_append"
 
 def opt(args, name)
   (i = args.index(name)) && args[i + 1]
@@ -47,6 +48,12 @@ when "append"
   rescue ArgumentError => e
     warn "append: #{e.message}"
     exit 2
+  rescue GuardedAppend::Unavailable => e
+    # Intent 335 (spec D14): the write guard could not be taken; nothing was written. Exit 4
+    # rather than let a backtrace reach the six skill recipes that drive this CLI - it rescues
+    # ArgumentError alone today and would otherwise print one straight to the terminal.
+    warn "append: #{e.message}"
+    exit 4
   end
 
 when "rebuild"

package/scripts/runner

@@ -0,0 +1,397 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+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,
+# answer) are the only ones the skill body ever names; the internal verbs
+# (ready, sweep, rewind) route and work so `step` can compose them and so
+# each can be tested alone, but stay out of the usage text (327 spec).
+#
+# `step`, `sweep`, `answer` and `rewind` route to modules later nodes
+# deliver (RunnerDispatch and RunnerAbsorb for `step`; RunnerSweep,
+# RunnerAnswer, RunnerRewind for the rest). Each is required LAZILY, inside
+# its own verb branch: a verb whose module has not landed yet reports
+# plainly and exits nonzero, and every other verb - most importantly
+# `status`, which an operator polls constantly across all five of this
+# intent's dispatches - keeps working.
+#
+# Usage:
+#   runner <step|status|answer> <intent_dir> [--node ID] [--answer TEXT]
+#
+# Exit codes (matching the family scripts/node-transition and
+# scripts/ready-set already use):
+#   0 - success
+#   1 - the verb ran but reports failure (an invalid graph for `ready`)
+#   2 - usage: unknown verb, or not an intent directory
+#   3 - a routed verb's module has not been delivered yet
+module Runner
+  module_function
+
+  PUBLIC_VERBS = %w[step status answer].freeze
+  INTERNAL_VERBS = %w[ready sweep rewind].freeze
+  VERBS = (PUBLIC_VERBS + INTERNAL_VERBS).freeze
+
+  # verb -> [[ModuleName, lib_file], ...], required lazily inside the verb's
+  # own branch (row 1.6). `step` composes two modules (dispatching new work,
+  # then absorbing what a sub-agent reported back); every other routed verb
+  # names exactly one.
+  LAZY_MODULES = {
+    "step" => [["RunnerSweep", "runner_sweep"], ["RunnerAbsorb", "runner_absorb"],
+               ["RunnerDispatch", "runner_dispatch"]],
+    "sweep" => [["RunnerSweep", "runner_sweep"]],
+    "answer" => [["RunnerAnswer", "runner_answer"]],
+    "rewind" => [["RunnerRewind", "runner_rewind"]],
+  }.freeze
+
+  def usage
+    warn "Usage: runner <#{PUBLIC_VERBS.join('|')}> <intent_dir> [--node ID] [--answer TEXT]"
+  end
+
+  def intent_directory?(dir)
+    dir && File.directory?(dir) && File.exist?(Savepoint.intent_file(dir))
+  end
+
+  def opt(args, name)
+    (i = args.index(name)) && args[i + 1]
+  end
+
+  # opt_all(args, name) -> every value given for a repeated flag, in the order
+  # they appear, or [] when the flag never occurs (intent 340, G7, n8, row
+  # 8.1-8.3). `run_step` needs this, not `opt`, for `--return`: one step may
+  # carry more than one `--return NODE=PATH` pair (one per node the session
+  # is reporting back on), and `opt`'s single-value semantics would silently
+  # keep only the first, absorbing one node while stranding the other's
+  # lease until it expires.
+  def opt_all(args, name)
+    args.each_index.select { |i| args[i] == name }.map { |i| args[i + 1] }.compact
+  end
+
+  # KNOWN_FLAGS (minor 2): the exact flag vocabulary each verb accepts. A
+  # flag not in a verb's own list is refused rather than silently ignored -
+  # a mistyped `--session` used to vanish with no effect and the runner
+  # simply acted as whichever session `CLAUDE_CODE_SESSION_ID` names.
+  KNOWN_FLAGS = {
+    "step" => %w[--return --allow-core-drift],
+    "answer" => %w[--node --answer],
+    "rewind" => %w[--node --confirm],
+  }.freeze
+
+  # unrecognized_flag(verb, args) -> the first token in `args` that looks
+  # like a flag (`--...`) and is not in `verb`'s own KNOWN_FLAGS, or nil. A
+  # verb absent from KNOWN_FLAGS (status, ready, sweep) accepts none.
+  def unrecognized_flag(verb, args)
+    allowed = KNOWN_FLAGS.fetch(verb, [])
+    args.find { |a| a.is_a?(String) && a.start_with?("--") && !allowed.include?(a) }
+  end
+
+  def main(argv)
+    args = argv.dup
+    verb = args.shift
+
+    unless VERBS.include?(verb)
+      warn "runner: unknown verb #{verb.inspect}"
+      usage
+      exit 2
+    end
+
+    intent_dir_arg = args.shift
+    unless intent_directory?(intent_dir_arg && File.expand_path(intent_dir_arg))
+      warn "runner: #{intent_dir_arg.inspect} is not an intent directory"
+      usage
+      exit 2
+    end
+    intent_dir = File.expand_path(intent_dir_arg)
+
+    bad_flag = unrecognized_flag(verb, args)
+    if bad_flag
+      warn "runner: unknown flag #{bad_flag.inspect} for #{verb}"
+      usage
+      exit 2
+    end
+
+    case verb
+    when "status"
+      run_status(intent_dir)
+    when "ready"
+      run_ready(intent_dir)
+    else
+      run_lazy(verb, intent_dir, args)
+    end
+  end
+
+  def run_status(intent_dir)
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    rows = RunnerCore.status(context)
+
+    if rows.empty?
+      puts "No declared nodes."
+    else
+      rows.each do |id, view|
+        puts "#{id}  kind=#{view[:kind]}  state=#{view[:state]}  ready=#{view[:ready]}"
+        last = view[:last_transition]
+        puts "  last: #{last[:raw]}" if last
+      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"
+    unless complete
+      rows.each do |id, view|
+        next if ReadySet::TERMINAL_STATES.include?(view[:state])
+
+        view[:blockers].each { |b| puts "#{id} blocked: #{b}" }
+      end
+    end
+
+    exit 0
+  end
+
+  def run_ready(intent_dir)
+    analysis = ReadySet.analyze(intent_dir)
+    unless analysis[:ok]
+      warn "runner: #{analysis[:errors].join('; ')}"
+      exit 1
+    end
+
+    if analysis[:ranked_ready].empty?
+      puts "Ready: (none)"
+    else
+      puts "Ready: #{analysis[:ranked_ready].map { |r| r[:id] }.join(', ')}"
+    end
+    exit 0
+  end
+
+  # Requires this verb's module(s) lazily, then hands off. Nothing in n1
+  # delivers runner_dispatch.rb, runner_absorb.rb, runner_sweep.rb,
+  # runner_answer.rb, or runner_rewind.rb, so every LAZY_MODULES require
+  # raises LoadError today and every routed verb reports "not yet
+  # delivered" - the only thing this node needs to prove (row 1.6). Once a
+  # later node ships its file, the require succeeds and falls through to
+  # dispatch_lazy, which that node replaces with the real call.
+  def run_lazy(verb, intent_dir, args)
+    # The require target below is a runtime value, never an inline quoted
+    # literal, so it falls outside test/install_packaging_test.rb's
+    # require-closure guard on purpose: every file LAZY_MODULES names is a
+    # genuine later-node deliverable, none of which core_files should track
+    # until that node actually lands it.
+    LAZY_MODULES.fetch(verb, []).each { |(_name, file)| require_relative(File.join("lib", file)) }
+  rescue LoadError
+    warn "runner: #{verb} is not yet delivered (its module has not landed)"
+    exit 3
+  else
+    dispatch_lazy(verb, intent_dir, args)
+  end
+
+  def dispatch_lazy(verb, intent_dir, args)
+    case verb
+    when "step"
+      run_step(intent_dir, args)
+    when "sweep"
+      run_sweep(intent_dir, args)
+    when "answer"
+      run_answer(intent_dir, args)
+    when "rewind"
+      run_rewind(intent_dir, args)
+    else
+      warn "runner: #{verb}'s module loaded but no dispatcher is wired up yet"
+      exit 3
+    end
+  end
+
+  # run_sweep (intent 340, G7, n8): the standalone `sweep` verb, unreachable
+  # from the CLI until this node - `dispatch_lazy` had no `when "sweep"` arm
+  # even though `RunnerSweep.run` (n2) is a complete, documented standalone
+  # entry point, exactly the shape a bare `runner sweep` call needs (abort
+  # check, THEN the lease heartbeat, THEN reclaim - RunnerSweep's own fixed
+  # order). `step` never calls this method: it composes `abort_if_merging`
+  # and `reclaim` itself, interleaved around absorb.
+  def run_sweep(intent_dir, args)
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    result = RunnerSweep.run(context)
+
+    unless result[:ok]
+      warn "runner: #{result[:error]}"
+      warn "runner: run `#{result[:recovery_command]}` before the next sweep can run" if result[:recovery_command]
+      exit 1
+    end
+
+    result[:reclaimed].each { |r| puts "reclaimed #{r[:node]} (holder=#{r[:holder]})" }
+    result[:extended].each { |e| puts "extended #{e[:node]} (head=#{e[:head]})" }
+    puts "nothing to sweep" if result[:reclaimed].empty? && result[:extended].empty?
+    exit 0
+  end
+
+  # run_answer (intent 340, G7, n6): closes a decision node or unparks a
+  # work node the runner parked at `needs_decision` (327 D22, C26), then
+  # prints what became ready so the owner knows the loop can continue.
+  def run_answer(intent_dir, args)
+    node = opt(args, "--node")
+    text = opt(args, "--answer")
+
+    unless node
+      warn "runner: answer requires --node ID"
+      exit 2
+    end
+
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    result = RunnerAnswer.answer(context, node: node, text: text.to_s)
+
+    unless result[:ok]
+      warn "runner: answer refused (#{result[:reason]})"
+      exit 1
+    end
+
+    puts "answered #{node}"
+    puts "respun to #{result[:respun_to]}" if result[:respun_to]
+    puts "newly ready: #{result[:newly_ready].join(', ')}" if result[:newly_ready].any?
+    exit 0
+  end
+
+  # run_rewind (intent 340, G7, n6): confirm-gated reset of the intent
+  # branch to a node's own recorded commit, superseding every downstream
+  # node and respinning the rewound node itself (327 D15's rewind clause).
+  def run_rewind(intent_dir, args)
+    node = opt(args, "--node")
+    confirm = args.include?("--confirm")
+
+    unless node
+      warn "runner: rewind requires --node ID"
+      exit 2
+    end
+
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    result = RunnerRewind.rewind(context, node: node, confirm: confirm)
+
+    unless result[:ok]
+      warn "runner: rewind refused (#{result[:reason]})"
+      exit 1
+    end
+
+    puts "reset #{node} to #{result[:reset_to]}"
+    puts "superseded: #{result[:superseded].join(', ')}" if result[:superseded].any?
+    puts "respun to #{result[:respun_to]}"
+    exit 0
+  end
+
+  # run_step (intent 340, G7, n5): one turn of the loop, in the fixed order
+  # 327 D14 and RunnerSweep's own docstring name - abort on a stuck merge,
+  # the delivery-lease heartbeat, absorb every `--return NODE=PATH` this call
+  # carries, THEN reclaim (so a node this very call just absorbed is never
+  # reclaimed out from under its own return, matrix row 2.19/2.20) - and only
+  # then dispatch whatever is left ready. Never spawns an agent (327 D42):
+  # the session makes every subagent call from the plan this prints.
+  def run_step(intent_dir, args)
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+
+    # v1 minor 3/row 11.18: RunnerSweep.abort_if_merging already prints the
+    # whole sentence itself (its own error PLUS the recovery command) - this
+    # used to print both halves again, so the operator read the same merge
+    # warning twice for one refusal.
+    abort_result = RunnerSweep.abort_if_merging(context)
+    exit 1 unless abort_result[:ok]
+
+    Lock.heartbeat(intent_dir, session: context.session) unless context.session.to_s.strip.empty?
+
+    # B4: this is the runner's ACTUAL lock check now - the absorb loop below
+    # writes node transitions, and RunnerDispatch's own check (row 5.31/5.32)
+    # runs too late to stop that: a session holding no lock would otherwise
+    # have every `--return` it carries written anyway, attributed to
+    # whichever session's holder= happens to be on the node's `running`
+    # line. RunnerDispatch keeps its own check too, as defence in depth for
+    # a caller that reaches it some other way.
+    unless context.session
+      warn "runner: step refused (lock_not_held)"
+      warn RunnerDispatch.rearm_command(intent_dir)
+      exit 1
+    end
+
+    # M3/row 10.1: `--allow-core-drift` (D11) - the one escape hatch letting
+    # Plastic's own repository, which legitimately drifts from the installed
+    # manifest, dogfood its own runner. Threaded straight into the absorb,
+    # never defaulted true.
+    allow_core_drift = args.include?("--allow-core-drift")
+
+    returns = {}
+    opt_all(args, "--return").each do |pair|
+      node, path = pair.to_s.split("=", 2)
+      if node.to_s.empty? || path.to_s.empty?
+        warn "runner: malformed --return #{pair.inspect}, expected NODE=PATH"
+        exit 2
+      end
+      returns[node] = path
+    end
+
+    returns.each do |node, path|
+      absorbed = RunnerAbsorb.absorb(context, node: node, return_path: path, allow_core_drift: allow_core_drift)
+      puts "absorbed #{node}: #{absorbed[:state]}"
+      # M4/row 10.3: a refused proposal is surfaced here, not left to a
+      # savepoint comment the operator never sees - the exact reason the
+      # proposer's next attempt otherwise proposes the same thing again.
+      proposal = absorbed[:proposal]
+      puts "  proposal refused: #{Array(proposal[:errors]).join('; ')}" if proposal && !proposal[:ok]
+    end
+
+    swept = RunnerSweep.reclaim(context, skip: returns.keys)
+    swept[:reclaimed].each { |r| puts "reclaimed #{r[:node]} (holder=#{r[:holder]})" }
+    swept[:extended].each { |e| puts "extended #{e[:node]} (head=#{e[:head]})" }
+
+    # M5/row 10.4: NodeWorktree.reap runs once per step, right after the
+    # reclaim pass - D26's reaper, unreachable from anywhere until now.
+    reaped = NodeWorktree.reap(context)
+    reaped[:removed].each { |r| puts "reaped #{r[:node]} worktree" }
+
+    result = RunnerDispatch.dispatch(context)
+    unless result[:ok]
+      warn "runner: step refused (#{result[:reason]}): #{Array(result[:errors]).join('; ')}"
+      warn result[:rearm_command] if result[:rearm_command]
+      exit 1
+    end
+
+    case result[:status]
+    when "dispatched"
+      puts result[:plan]
+    when "queued"
+      puts "queued (concurrency ceiling reached)"
+    when "complete"
+      puts "complete"
+    when "needs_decision"
+      # printed below, alongside a dispatch plan when the same step also
+      # dispatched (M11/row 10.14) - `result[:stop]` is set whenever
+      # status is needs_decision.
+    else
+      puts "stalled"
+      result[:blockers].each { |b| puts "blocked: #{b}" }
+    end
+
+    # M11/row 10.14: a `needs_decision` stop must print even when THIS SAME
+    # step also dispatched other nodes ahead of the decision node in ranked
+    # order - `result[:status]` reads "dispatched" in that case (dispatched
+    # takes priority in RunnerDispatch's own report), which used to swallow
+    # the stop and its `runner answer` command entirely.
+    if result[:stop]
+      stop = result[:stop]
+      puts "needs_decision: #{stop[:node]} - #{stop[:question]}"
+      puts stop[:answer_command]
+    end
+
+    result[:parked].each do |p|
+      puts "parked #{p[:node]} (#{p[:reason]}): #{p[:question]}"
+      puts p[:answer_command]
+    end
+
+    exit 0
+  end
+end
+
+Runner.main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/savepoint-note

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# savepoint-note - the writer CLI for three savepoint kinds: Review (one line per
+# plan-review or post-execution-review verdict) and Commit (one line per commit landing
+# during Exec), both from intent 317, D17; and Report (one line per report screen printed,
+# intent 331f). None has an automatic seam (session-commit writes the day ledger, not the
+# intent ledger; the executor's own commits are plain git; a printed screen is a skill's own
+# reply, not a file write), so this is an explicit thin wrapper on
+# Savepoint.append_review_savepoint / append_commit_savepoint / append_report_savepoint.
+#
+# Usage:
+#   savepoint-note <intent_dir> --kind Review|Commit|Report --text "<text>"
+#
+# --text is normalized (D21): runs of two or more spaces collapse to one, so a
+# free-text kind that happens to contain a double space cannot key the dedup
+# primitive's split(/\s{2,}/) on the prefix alone and silently drop a later
+# line. A newline in --text is refused outright (exit 2, ledger unchanged)
+# rather than silently splitting one entry into two malformed ledger lines.
+#
+# Exit codes:
+#   0 - the line was appended (or was already recorded; both are success)
+#   2 - usage error, bad --kind, missing --text, a newline in --text, or the
+#       path is not an intent directory (one line on stderr, ledger unchanged)
+
+require_relative "lib/savepoint"
+
+def usage_abort(message)
+  warn "savepoint-note: #{message}"
+  exit 2
+end
+
+args = ARGV.dup
+kind = nil
+text = nil
+positional = []
+while (arg = args.shift)
+  case arg
+  when "--kind"
+    kind = args.shift
+  when "--text"
+    text = args.shift
+  else
+    usage_abort("unknown flag #{arg.inspect}") if arg.start_with?("--")
+    positional << arg
+  end
+end
+
+usage_abort("usage: savepoint-note <intent_dir> --kind Review|Commit|Report --text \"<text>\"") unless positional.length == 1
+
+intent_dir = File.expand_path(positional.first)
+usage_abort("#{intent_dir} is not an intent directory") unless File.exist?(Savepoint.intent_file(intent_dir))
+
+KINDS = %w[Review Commit Report].freeze
+usage_abort("--kind must be one of #{KINDS.join(', ')}, got #{kind.inspect}") unless KINDS.include?(kind)
+usage_abort("--text is required") if text.nil? || text.empty?
+usage_abort("--text must not contain a newline") if text.include?("\n")
+
+normalized = text.gsub(/ {2,}/, " ").strip
+usage_abort("--text is empty after normalization") if normalized.empty?
+
+case kind
+when "Review" then Savepoint.append_review_savepoint(intent_dir, normalized)
+when "Commit" then Savepoint.append_commit_savepoint(intent_dir, normalized)
+when "Report" then Savepoint.append_report_savepoint(intent_dir, normalized)
+end
+
+exit 0

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/scripts/spawn-preamble

@@ -24,6 +24,7 @@
 
 require_relative "lib/savepoint"
 require_relative "lib/worktree"
+require_relative "lib/intent_screen"
 
 # Verbatim honoring instruction. Kept as one constant so the contract doc and the
 # test assert against the exact same string.
@@ -115,11 +116,17 @@ STAGE_LABELS = {
   "exec" => "Exec", "done" => "Done"
 }.freeze
 
+# Intent 317, D6: a dispatched agent's "Current stage:" line must name the last
+# LIFECYCLE line (What/Why/How/Exec/Done), never a trailing Lock/Review/Commit
+# line - the bug spawn-preamble shared with IntentScreen.savepoint_fields
+# before this guard (plan review finding B1).
 def current_stage(intent_dir)
   ledger = File.join(intent_dir, Savepoint::SAVEPOINT_FILE)
   if File.exist?(ledger)
-    last = File.read(ledger).each_line.map(&:strip).reject(&:empty?).last
-    return last if last
+    lines = File.read(ledger).each_line.map(&:strip).reject(&:empty?)
+    lifecycle = lines.select { |l| IntentScreen.lifecycle_line?(l) }
+    return lifecycle.last if lifecycle.any?
+    return lines.last if lines.any?
   end
   STAGE_LABELS.fetch(Savepoint.derive_stage(intent_dir), Savepoint.derive_stage(intent_dir))
 end