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

package/scripts/lib/work_graph_validator.rb

@@ -0,0 +1,201 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "graph_file"
+require_relative "graph_edges"
+require_relative "node_file"
+require_relative "action_graph_shim"
+
+# WorkGraphValidator (intent 334, n4): the in-batch reader over one intent's
+# graph.md and nodes/ - 327's rule for budget, files, and the decision and
+# research kinds (fold A17). {ok:, missing:, errors:}, the same Result shape
+# ProjectValidator returns (fold B7). Named apart from
+# IntentValidator#validate_graph, which already exists for the KNOWLEDGE
+# graph and stays unrelated to this one under D40 (fold B9).
+#
+# Built over GraphFile, GraphEdges, and NodeFile only - never IntentValidator,
+# never ReportScreen. Every check accumulates into `errors` rather than
+# short-circuiting on the first one (fold: "the owner fixes one thing per
+# run").
+module WorkGraphValidator
+  module_function
+
+  def validate(intent_dir)
+    missing = []
+    errors = []
+
+    graph_path = File.join(intent_dir, "graph.md")
+    parsed = GraphFile.parse(graph_path)
+    errors.concat(parsed[:errors])
+
+    graph = parsed[:graph]
+    if graph.nil?
+      # G9 (intent 342, D6/D7/D12): a legacy intent that never got a
+      # graph.md still reads as a valid work graph, structurally, through
+      # the backward shim - but only when graph.md is genuinely absent.
+      # A graph.md that exists but is malformed (no "## Graph" section)
+      # must never fall through to the synthetic chain and hide its own
+      # error (D12's whole point). The fresh error list here is
+      # deliberate: `errors` above already holds the not-found error from
+      # `parsed[:errors]`, and reusing it would return ok: false for every
+      # legacy intent in the store.
+      if !File.exist?(graph_path) && ActionGraphShim.shape(intent_dir) == :actions
+        return validate_actions_shape(intent_dir)
+      end
+
+      missing << "graph.md ## Graph section"
+      return { ok: false, missing: missing, errors: errors }
+    end
+
+    nodes = graph[:nodes]
+    edges = graph[:edges]
+    declared_ids = edges.keys
+
+    # Intent-scope dangling check: every node must be declared with its own
+    # needs-line here (unlike a roadmap, which may have undeclared roots -
+    # that reconciliation is G4's, not this validator's).
+    (nodes - declared_ids).each { |id| errors << "needs target #{id.inspect} names no declared node" }
+
+    cyc = GraphEdges.cycle(edges)
+    errors << "cyclic graph, cannot validate: #{cyc.join(' > ')}" if cyc
+
+    node_paths = Dir.glob(File.join(intent_dir, "nodes", "*.md")).sort
+    parsed_nodes = {}
+    paths_by_id = Hash.new { |h, k| h[k] = [] }
+
+    node_paths.each do |path|
+      nf = NodeFile.parse(path)
+      nf[:errors].each { |e| errors << "#{File.basename(path)}: #{e}" }
+      id = nf[:node]
+      next unless id
+
+      paths_by_id[id] << path
+      parsed_nodes[id] ||= nf
+    end
+
+    paths_by_id.each do |id, paths|
+      next unless paths.length > 1
+
+      errors << "node id #{id.inspect} claimed by more than one file: #{paths.map { |p| File.basename(p) }.join(', ')}"
+    end
+
+    declared_ids.each do |id|
+      missing << "nodes/ file for #{id}" unless parsed_nodes.key?(id)
+      errors << "declared node #{id.inspect} has no node file under nodes/" unless parsed_nodes.key?(id)
+    end
+    parsed_nodes.each_key do |id|
+      errors << "node file for #{id.inspect} exists but ## Graph declares no such node" unless declared_ids.include?(id)
+    end
+
+    work_nodes = []
+    verify_nodes = []
+
+    declared_ids.each do |id|
+      nf = parsed_nodes[id]
+      next unless nf
+
+      case nf[:kind]
+      when "verify"
+        verify_nodes << id
+        errors << "verify node #{id.inspect} has no ## Criteria" unless has_section?(nf[:body], "## Criteria")
+      when "decision"
+        errors << "decision node #{id.inspect} has no ## Question with a question" unless has_nonblank_section?(nf[:body], "## Question")
+      when "research"
+        errors << "research node #{id.inspect} has no ## Deposit" unless has_section?(nf[:body], "## Deposit")
+      when "work"
+        work_nodes << id
+        errors << "work node #{id.inspect} has no ## Steps" unless has_section?(nf[:body], "## Steps")
+        errors << "work node #{id.inspect} has no ## Proven by" unless has_section?(nf[:body], "## Proven by")
+      end
+    end
+
+    above_trivial_bar = work_nodes.length >= 2
+    if above_trivial_bar
+      verify_directive = parsed[:verify]
+      directive_ok = verify_directive && !verify_directive[:reason].to_s.empty?
+
+      unless directive_ok
+        attached = verify_nodes.select { |vid| node_touches_graph?(vid, edges) }
+        if attached.empty?
+          errors << "two or more work nodes require a verify node attached to the graph, or a verify: none reason=<text> directive"
+        end
+      end
+
+      work_nodes.each do |id|
+        nf = parsed_nodes[id]
+        next unless nf
+
+        errors << "work node #{id.inspect} has no failure-mode matrix under a heading carrying its id" unless has_valid_matrix?(id, nf[:body])
+      end
+    end
+
+    verify_nodes.each do |id|
+      next if node_touches_graph?(id, edges)
+
+      errors << "verify node #{id.inspect} exists but no edge reaches it (attach it or drop it)"
+    end
+
+    { ok: errors.empty?, missing: missing, errors: errors }
+  end
+
+  # A node "touches" the graph when some edge involves it on either side:
+  # it targets something, or something targets it. A verify node declared
+  # with "needs nothing" and targeted by nothing is fully isolated (fold
+  # A13).
+  def node_touches_graph?(id, edges)
+    (edges[id] || []).any? || edges.values.any? { |targets| targets.include?(id) }
+  end
+
+  def has_section?(body, heading_text)
+    NodeFile.split_by_headings(body.to_s).any? { |heading, _| heading.strip == heading_text }
+  end
+
+  def has_nonblank_section?(body, heading_text)
+    NodeFile.split_by_headings(body.to_s).any? { |heading, section| heading.strip == heading_text && !section.strip.empty? }
+  end
+
+  def heading_tokens(heading)
+    heading.to_s.sub(/\A#+\s*/, "").split(/[^A-Za-z0-9]+/)
+  end
+
+  # The matrix table must sit under a heading whose tokens include the
+  # node's own id, and that heading must own at least one data row (fold
+  # A1 - the same table-owning rule report_screen's resolver uses, so a
+  # node's own Proven-by cell is never "not recorded" the moment it ships).
+  def has_valid_matrix?(id, body)
+    NodeFile.split_by_headings(body.to_s).any? do |heading, section|
+      heading_tokens(heading).include?(id) && NodeFile.table_rows(section).any?
+    end
+  end
+
+  # The structural check the synthetic (actions/-only) shape gets, and
+  # nothing more (D6): at least one node, unique ids, every needs target
+  # names a declared node, acyclic. Never the kind-section rules, the
+  # failure-mode matrix bar, or the verify-attachment bar - a legacy action
+  # file labels its headings "S1", or nothing at all, and was never asked
+  # to meet a bar written for a graph authored under 327.
+  def validate_actions_shape(intent_dir)
+    errors = []
+    graph = ActionGraphShim.view(intent_dir)[:graph] || { nodes: [], edges: {}, errors: [] }
+    nodes = graph[:nodes]
+    edges = graph[:edges]
+
+    errors << "actions/ yields no nodes" if nodes.empty?
+    # D16: uniqueness is checked over the node array, not edges.keys - a
+    # Hash key set is unique by construction, so checking edges.keys can
+    # never fire.
+    errors << "duplicate node ids in synthetic chain" if nodes.uniq.length != nodes.length
+
+    # D16: every needs target is checked against the declared node list,
+    # not the node list against its own key set (nodes - edges.keys, which
+    # can never differ since the builder mints edges.keys from nodes).
+    (edges.values.flatten.uniq - nodes).each do |id|
+      errors << "needs target #{id.inspect} names no declared node"
+    end
+
+    cyc = GraphEdges.cycle(edges)
+    errors << "cyclic graph, cannot validate: #{cyc.join(' > ')}" if cyc
+
+    { ok: errors.empty?, missing: [], errors: errors }
+  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/node-packet

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "lib/node_packet"
+require_relative "lib/savepoint"
+
+# node-packet - the CLI over NodePacket (intent 338, G5). Builds one node's
+# whole input from disk and writes it to packets/<node>--a<N>.packet (or
+# --out), printing a parsable summary and the exact node-transition running
+# command intent 340's runner should record.
+#
+# Usage:
+#   node-packet <intent_dir> --node <id> [--budget N] [--hop-tokens N]
+#               [--holder H] [--expires E] [--model M] [--attempt N]
+#               [--out PATH] [--force]
+#
+# Exit codes (spec D17, shared with node-transition's family):
+#   0 - the packet was written (or the identical bytes already existed)
+#   2 - usage: not an intent directory, missing --node, or an unknown node
+#   3 - an unreadable, cyclic or unparsable graph, node file, or record
+#   4 - overflow past the third cut; nothing was written
+#   5 - an existing attempt file whose bytes differ; nothing was written
+module NodePacketCLI
+  module_function
+
+  def usage
+    warn "Usage: node-packet <intent_dir> --node <id> [--budget N] [--hop-tokens N] " \
+         "[--holder H] [--expires E] [--model M] [--attempt N] [--out PATH] [--force]"
+  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
+
+  def main(argv)
+    args = argv.dup
+    intent_dir_arg = args.shift
+
+    unless intent_directory?(intent_dir_arg && File.expand_path(intent_dir_arg))
+      warn "node-packet: #{intent_dir_arg.inspect} is not an intent directory"
+      usage
+      exit 2
+    end
+    intent_dir = File.expand_path(intent_dir_arg)
+
+    node = opt(args, "--node")
+    if node.to_s.strip.empty?
+      warn "node-packet: --node is required"
+      usage
+      exit 2
+    end
+
+    budget = opt(args, "--budget")
+    hop_tokens = opt(args, "--hop-tokens")
+    attempt = opt(args, "--attempt")
+    out = opt(args, "--out")
+    holder = opt(args, "--holder")
+    expires = opt(args, "--expires")
+    model = opt(args, "--model")
+    force = args.include?("--force")
+
+    result = NodePacket.build(
+      intent_dir: intent_dir,
+      node: node,
+      budget_tokens: budget ? budget.to_i : NodePacket::DEFAULT_BUDGET_TOKENS,
+      hop_tokens: hop_tokens ? hop_tokens.to_i : NodePacket::DEFAULT_HOP_TOKENS,
+      holder: holder,
+      expires: expires,
+      model: model,
+      attempt: attempt ? attempt.to_i : nil,
+      out: out,
+      force: force,
+    )
+
+    if result[:ok]
+      puts NodePacket.summary_line(result)
+      puts result[:running_command]
+      exit 0
+    end
+
+    Array(result[:errors]).each { |e| warn "node-packet: #{e}" }
+    puts result[:needs_decision_command] if result[:needs_decision_command]
+    exit result[:exit_code]
+  end
+end
+
+NodePacketCLI.main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/node-transition

@@ -0,0 +1,291 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "time"
+require_relative "lib/savepoint"
+require_relative "lib/node_ledger"
+require_relative "lib/ready_set"
+require_relative "lib/guarded_append"
+require_relative "lib/lock"
+require_relative "lib/arm"
+
+# node-transition - the CLI over NodeLedger that REFUSES what the graph does not
+# allow (intent 335, G2). An orchestrator can run this by hand today, before the
+# runner (intent 340) exists.
+#
+# Usage:
+#   node-transition <intent_dir> --node <id|Intent> --state <state> [--field k=v]...
+#                    [--comment "..."] [--needs a,b] [--session SID] [--now ISO8601]
+#   node-transition report <intent_dir>
+#
+# Exit codes (spec D18, matching the tree: scripts/append-ledger:125 uses 3 for a
+# guard that could not be taken, scripts/end-intent:675 uses 4 for a lock-ownership
+# refusal):
+#   0 - the line was appended
+#   2 - usage: not an intent directory, bad subject, unknown state, missing
+#       required field, a tab or newline in a value
+#   3 - the ledger guard was unavailable; nothing was written
+#   4 - running, and the caller does not hold delivery.lock
+#   5 - running, and the subject is not ready
+#   6 - reclaimed, and the subject's last running line has not expired
+module NodeTransition
+  module_function
+
+  # The readiness precondition for `running` (intent 336, G3): ReadySet.ready?
+  # applied to `subject` against `edges`/`nodes` already parsed once, before
+  # the guard is ever taken (spec: "parsed once, before the guard"). Takes
+  # `content` (the ledger's raw text), never a path, so this method can be run
+  # twice: once as a cheap unguarded pre-check for a fast, readable refusal,
+  # and once - the AUTHORITATIVE decision - as the guard's precondition,
+  # evaluated against the exact content GuardedAppend just read under its
+  # lock hold (post-execution review row 7.1, carried forward by 336). A
+  # path-based re-read here would defeat the guard: two callers could each
+  # open their own handle, both see "planned", and both go on to append
+  # `running`.
+  def running_ready?(content, subject, edges, nodes, caps: ReadySet::DEFAULT_CAPS)
+    ReadySet.ready?(content: content, subject: subject, graph: { edges: edges }, nodes: nodes, caps: caps)
+  end
+
+  # graph.md and nodes/ for `subject`'s readiness (intent 336, G3): a genuinely
+  # missing graph.md degrades gracefully to no known needs/kind/files (the
+  # same fallback the temporary needs_from_graph reader gave, so a legacy
+  # intent with no graph.md still dispatches ad hoc node ids), while a
+  # PRESENT but broken graph.md (no ## Graph section, a cycle) is a clean
+  # refusal, never a raise - {edges:, nodes:, error:}.
+  def resolve_graph_and_nodes(intent_dir)
+    graph_path = File.join(intent_dir, "graph.md")
+    return { edges: {}, nodes: {}, error: nil } unless File.exist?(graph_path)
+
+    loaded = ReadySet.load_graph(intent_dir)
+    return { edges: loaded[:edges] || {}, nodes: loaded[:nodes] || {}, error: nil } if loaded[:ok]
+
+    { edges: {}, nodes: {}, error: loaded[:errors].join("; ") }
+  end
+
+  # Session resolution per spec D16: an explicit --session is authoritative and
+  # NEVER falls through (an explicit non-owner is refused outright, never
+  # silently granted ownership through a fallback). Without it, try the
+  # environment's CLAUDE_CODE_SESSION_ID, then the derived `auto-` key, and keep
+  # the first candidate that actually HOLDS the lock (owner or delegate,
+  # Lock.holds?) - so the fallback can never grant ownership to a session that
+  # does not have it.
+  def resolve_owning_session(intent_dir, explicit:, env_session:)
+    if explicit && !explicit.to_s.strip.empty?
+      return Lock.holds?(intent_dir, session: explicit) ? explicit : nil
+    end
+
+    store = Arm.store_for(intent_dir)
+    intent_id = Arm.intent_id_for(intent_dir)
+    candidates = [env_session, Arm.derive_key(store, intent_id)].reject { |c| c.to_s.strip.empty? }
+    candidates.find { |c| Lock.holds?(intent_dir, session: c) }
+  end
+
+  def intent_directory?(dir)
+    dir && File.directory?(dir) && File.exist?(Savepoint.intent_file(dir))
+  end
+
+  def valid_subject?(subject)
+    subject == Savepoint::INTENT_SUBJECT || subject.to_s.match?(Savepoint::NODE_SUBJECT_RE)
+  end
+
+  def opt(args, name)
+    (i = args.index(name)) && args[i + 1]
+  end
+
+  def opt_all(args, name)
+    args.each_index.select { |i| args[i] == name }.map { |i| args[i + 1] }
+  end
+
+  def parse_fields(args)
+    opt_all(args, "--field").each_with_object({}) do |pair, memo|
+      key, value = pair.to_s.split("=", 2)
+      memo[key] = value if key && !key.empty?
+    end
+  end
+
+  def usage
+    warn "Usage: node-transition <intent_dir> --node <id|Intent> --state <state> " \
+         "[--field k=v]... [--comment \"...\"] [--needs a,b] [--session SID] [--now ISO8601]"
+    warn "       node-transition report <intent_dir>"
+  end
+
+  def run_report(intent_dir)
+    unless intent_directory?(intent_dir)
+      warn "node-transition: #{intent_dir.inspect} is not an intent directory"
+      usage
+      exit 2
+    end
+
+    savepoint_path = File.join(intent_dir, "savepoint.md")
+    anomalies = NodeLedger.anomalies(savepoint_path)
+    if anomalies.empty?
+      puts "node-transition report: no torn or unattributed transition lines"
+    else
+      anomalies.each { |a| puts "#{a[:reason]}: #{a[:line]}" }
+    end
+    exit 0
+  end
+
+  def main(argv)
+    args = argv.dup
+    head = args.shift
+
+    if head == "report"
+      report_dir_arg = args.shift
+      run_report(report_dir_arg && File.expand_path(report_dir_arg))
+      return
+    end
+
+    intent_dir_arg = head
+    unless intent_directory?(intent_dir_arg && File.expand_path(intent_dir_arg))
+      warn "node-transition: #{intent_dir_arg.inspect} is not an intent directory"
+      usage
+      exit 2
+    end
+    intent_dir = File.expand_path(intent_dir_arg)
+
+    subject = opt(args, "--node")
+    state = opt(args, "--state")
+    comment = opt(args, "--comment")
+    needs_flag = opt(args, "--needs")
+    session_flag = opt(args, "--session")
+    now_flag = opt(args, "--now")
+    fields = parse_fields(args)
+
+    if subject.nil? || state.nil?
+      warn "node-transition: --node and --state are required"
+      usage
+      exit 2
+    end
+
+    unless valid_subject?(subject)
+      warn "node-transition: #{subject.inspect} is neither #{Savepoint::INTENT_SUBJECT} nor a valid node id"
+      exit 2
+    end
+
+    unless NodeLedger::STATES.include?(state)
+      warn "node-transition: unknown state #{state.inspect}"
+      exit 2
+    end
+
+    now = begin
+      now_flag ? Time.iso8601(now_flag) : Time.now
+    rescue ArgumentError
+      warn "node-transition: --now must be ISO 8601"
+      exit 2
+    end
+
+    begin
+      fields.each_value { |v| NodeLedger.normalize_value(v) }
+      NodeLedger.normalize_value(comment) if comment
+    rescue ArgumentError => e
+      warn "node-transition: #{e.message}"
+      exit 2
+    end
+
+    missing = NodeLedger.missing_fields(state, fields)
+    unless missing.empty?
+      warn "node-transition: state #{state} requires #{missing.join(', ')}"
+      exit 2
+    end
+
+    savepoint_path = File.join(intent_dir, "savepoint.md")
+    precondition = nil
+
+    case state
+    when "running"
+      owning_session = resolve_owning_session(intent_dir, explicit: session_flag,
+                                                            env_session: ENV["CLAUDE_CODE_SESSION_ID"])
+      unless owning_session
+        warn "node-transition: the caller does not hold delivery.lock for #{intent_dir}"
+        exit 4
+      end
+
+      if subject == Savepoint::INTENT_SUBJECT
+        # The node readiness rule (four conditions over the work graph) is
+        # scoped to node subjects; the intent-scope subject is never gated by
+        # it, so a legacy intent with no graph.md at all can still write an
+        # Intent line (spec Acceptance Criteria; matrix "Transition the
+        # Intent subject").
+        precondition = nil
+      else
+        resolved = resolve_graph_and_nodes(intent_dir)
+        if resolved[:error]
+          warn "node-transition: #{resolved[:error]}"
+          exit 5
+        end
+
+        needs_override = needs_flag ? needs_flag.split(",").map(&:strip).reject(&:empty?) : nil
+        edges = needs_override ? resolved[:edges].merge(subject => needs_override) : resolved[:edges]
+        nodes = resolved[:nodes]
+
+        # Fast, unguarded pre-check: a cheap, readable refusal for the common
+        # case, but NEVER the authoritative decision (post-execution review
+        # row 7.1, carried forward by 336). The authoritative check is the
+        # `precondition` below, run inside GuardedAppend's lock hold against
+        # the content it actually read. `edges` and `nodes` are parsed once,
+        # above, before the guard is ever taken (spec D1).
+        precheck_content = File.exist?(savepoint_path) ? File.read(savepoint_path) : ""
+        result = running_ready?(precheck_content, subject, edges, nodes)
+        unless result[:ready]
+          warn "node-transition: #{result[:blockers].join('; ')}"
+          exit 5
+        end
+
+        precondition = ->(content) { running_ready?(content, subject, edges, nodes)[:ready] }
+      end
+    when "reclaimed"
+      running_entry = NodeLedger.last_running(savepoint_path, subject)
+      unless running_entry
+        warn "node-transition: #{subject} has no running line to reclaim"
+        exit 6
+      end
+
+      # Post-execution review row 7.4: expiry alone is not enough. A `done`
+      # node whose last `running` line's expires= happens to be in the past
+      # must not revert to `planned` and become re-dispatchable - reclaim is
+      # deliberately lock-free (spec D43), so this status check is the only
+      # thing that stops it. Row 7.5 pins that a genuinely running, expired
+      # subject is still reclaimable, so the crash sweep keeps working.
+      current_status = NodeLedger.status_for(savepoint_path, subject)
+      unless current_status == "running"
+        warn "node-transition: #{subject} is #{current_status}, not running; nothing to reclaim"
+        exit 6
+      end
+
+      expires_raw = (running_entry[:fields] || {})["expires"]
+      expiry_time = begin
+        expires_raw && Time.iso8601(expires_raw)
+      rescue ArgumentError
+        nil
+      end
+
+      unless expiry_time && now > expiry_time
+        warn "node-transition: #{subject}'s running line has not expired yet"
+        exit 6
+      end
+    end
+
+    result = begin
+      NodeLedger.append_transition(savepoint_path, subject: subject, state: state, fields: fields,
+                                    comment: comment, now: now, precondition: precondition)
+    rescue GuardedAppend::Unavailable => e
+      warn "node-transition: #{e.message}"
+      exit 3
+    rescue ArgumentError => e
+      warn "node-transition: #{e.message}"
+      exit 2
+    end
+
+    if result == :refused
+      warn "node-transition: #{subject} was no longer ready by the time the write lock was taken"
+      exit 5
+    end
+
+    puts "node-transition: appended #{state} for #{subject}"
+    exit 0
+  end
+end
+
+NodeTransition.main(ARGV) if $PROGRAM_NAME == __FILE__