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

package/scripts/lib/stop_gate.rb

@@ -0,0 +1,95 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "json"
+require_relative "active_delivery"
+require_relative "lock"
+require_relative "ready_set"
+
+# StopGate (intent 340b, G7c, n4, D5/D7/D8/D9): may this session stop? Blocks
+# only when four conditions hold together: the payload's stop_hook_active is
+# true, runner.stop_hook parses as a real boolean true, this session holds
+# the delivering intent's delivery.lock live and in auto mode, and the last
+# runner step left work a new turn can actually move (some node is ready to
+# dispatch right now - a graph whose only non-terminal node is already
+# running, or that has no ready node at all, permits, because blocking that
+# would trip Claude Code's own eight-block ceiling for nothing).
+#
+# Fail-open is the design, not a fallback: a missing store, a torn lock, an
+# unreadable graph, a raised exception, a payload that is not JSON - every
+# one of those permits. #decide never raises.
+module StopGate
+  module_function
+
+  # decide(payload:, config_stop_hook:, session:, global_store:, project_roots:, ttl:, now:) ->
+  # {block: false} or {block: true, reason: "..."}.
+  #
+  # `payload` is the hook input: already a Hash, or the raw JSON text (row
+  # 4.19 - a payload that is not JSON permits, never raises). `config_stop_hook`
+  # is the raw string read-config returns for runner.stop_hook: parsed as a
+  # boolean here, never trusted as one.
+  def decide(payload:, config_stop_hook:, session:, global_store:, project_roots:,
+             ttl: Lock::TTL_SECONDS, now: Time.now, caps: nil)
+    payload = parse_payload(payload)
+
+    return permit unless payload["stop_hook_active"] == true
+    return permit unless flag_true?(config_stop_hook)
+
+    intent_dir = ActiveDelivery.resolve(global_store: global_store, project_roots: project_roots,
+                                        session: session, ttl: ttl, now: now)
+    return permit unless intent_dir
+
+    lock = Lock.read(intent_dir)
+    return permit unless lock
+    return permit unless lock["run_mode"].to_s == "auto"
+
+    return permit unless work_movable?(intent_dir, caps: caps)
+
+    block(intent_dir)
+  rescue StandardError
+    permit
+  end
+
+  # Accepts a Hash as-is, parses a String as JSON, and falls back to an
+  # empty Hash for anything else or anything that fails to parse - a
+  # malformed payload must never raise (row 4.19).
+  def parse_payload(payload)
+    return payload if payload.is_a?(Hash)
+    return {} unless payload.is_a?(String)
+
+    parsed = JSON.parse(payload)
+    parsed.is_a?(Hash) ? parsed : {}
+  rescue JSON::ParserError
+    {}
+  end
+
+  # A config value counts as on only when it parses as the literal boolean
+  # true (row 4.4): read-config emits strings, and the string "false" is
+  # truthy in Ruby, so testing the raw value would arm the hook on its own
+  # shipped default. Anything else, including an absent key (row 4.5), is off.
+  def flag_true?(value)
+    value.to_s.strip.downcase == "true"
+  end
+
+  # Some node is ready to dispatch right now. Never raises across this
+  # boundary (ReadySet.analyze already never does); an unreadable or absent
+  # graph, or an intent with no declared nodes, reads as ok: false or an
+  # empty ready set either way, and both permit.
+  def work_movable?(intent_dir, caps:)
+    analysis = caps ? ReadySet.analyze(intent_dir, caps: caps) : ReadySet.analyze(intent_dir)
+    analysis[:ok] && analysis[:ranked_ready].any?
+  end
+
+  def permit
+    { block: false }
+  end
+
+  # Names the next instruction (row 4.17): a session that is blocked and
+  # told nothing stops again immediately.
+  def block(intent_dir)
+    intent_id = File.basename(intent_dir.to_s)
+    reason = "Plastic: intent #{intent_id} still has ready work. Run `runner step` for it " \
+             "and dispatch what it prints before stopping."
+    { block: true, reason: reason }
+  end
+end

package/scripts/lib/verify_intent.rb

@@ -9,7 +9,7 @@ require_relative "scaffold_intent"
 # (`Doctor#run_intent_check`), a net-new added-line em-dash diff guard (the first standing
 # implementation of this check; the only prior automated em-dash check,
 # `test/skill_command_lint_test.rb`, asserts against two FIXED file sets and cannot scan a
-# diff), a diffstat, and an optional caller-supplied `--suite` command folded into the same
+# diff), a diffstat, and an optional caller-supplied `--suite` command merged into the same
 # verdict.
 #
 # Repo resolution and base-branch detection are NOT re-implemented here: `resolve_repo_dir`,
@@ -245,7 +245,7 @@ module VerifyIntent
 
   # Every `Report`-kind savepoint line for this intent, oldest first: [timestamp, text].
   # Never fails or gates anything (D3: the diffstat check already prints a summary block,
-  # this folds into the same verdict so verify-intent surfaces them too) - a delivery with
+  # this merges into the same verdict so verify-intent surfaces them too) - a delivery with
   # no Report line is visible to `doctor`'s intent_reports_printed_check instead.
   def report_lines(intent_dir)
     path = File.join(intent_dir, "savepoint.md")

package/scripts/lib/work_graph_validator.rb

@@ -8,14 +8,14 @@ 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
+# research kinds (review A17). {ok:, missing:, errors:}, the same Result shape
+# ProjectValidator returns (review B7). Named apart from
 # IntentValidator#validate_graph, which already exists for the KNOWLEDGE
-# graph and stays unrelated to this one under D40 (fold B9).
+# graph and stays unrelated to this one under D40 (review 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
+# short-circuiting on the first one (see: "the owner fixes one thing per
 # run").
 module WorkGraphValidator
   module_function
@@ -140,7 +140,7 @@ module WorkGraphValidator
 
   # 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
+  # with "needs nothing" and targeted by nothing is fully isolated (review
   # A13).
   def node_touches_graph?(id, edges)
     (edges[id] || []).any? || edges.values.any? { |targets| targets.include?(id) }
@@ -159,7 +159,7 @@ module WorkGraphValidator
   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
+  # node's own id, and that heading must own at least one data row (review
   # 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)

package/scripts/new-intent

@@ -362,7 +362,7 @@ def main(argv)
   # 4a. I1 reciprocity: write the child's id into EACH source intent's frontmatter
   # `chain` (the formative-reciprocity backlink), for BOTH the `--parent` and the
   # `--sources` path. `sources` is the redundant-explicit set from step 3 (it already
-  # folds in `--parent`). Collect the touched source files so their `## Links` can be
+  # includes `--parent`). Collect the touched source files so their `## Links` can be
   # re-projected once the chain edges are on disk.
   source_files = []
   sources.each do |src_id|

package/scripts/node-run

@@ -0,0 +1,224 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+require "yaml"
+require "fileutils"
+require_relative "lib/savepoint"
+require_relative "lib/node_ledger"
+require_relative "lib/node_packet"
+require_relative "lib/node_worktree"
+require_relative "lib/node_file"
+require_relative "lib/ready_set"
+require_relative "lib/runner_core"
+require_relative "lib/codex_adapter"
+
+# node-run - the Codex leg of one node's whole attempt (intent 340b, G7c, n6).
+#
+# On Claude Code a subagent dispatch IS the executor; on Codex the executor
+# is a subprocess, so this script owns the timing of a whole node: it reads
+# the node's live `running` line, resolves the packet that line names,
+# builds the `codex exec` argv for the node's kind (CodexAdapter), runs it
+# in the node's worktree with the packet on stdin, reads the executor's
+# final message, and writes it to the attempt's own return path.
+#
+# It writes NO ledger transition, on any path - success, refusal or error
+# alike. That is the whole point: exactly one thing writes `done` (the
+# runner's own six-check absorb gate), and a second writer here would throw
+# that guarantee away. The caller absorbs with `runner step --return
+# ID=PATH` through the same six checks every other return goes through.
+#
+# Usage:
+#   node-run <intent_dir> --node <id> [--session SID] [--now ISO8601]
+#            [--timeout-seconds N]
+#
+# Exit codes: 0 - a return file was written (whatever its content actually
+# says; that judgment belongs to the absorb gate, not this script). Every
+# other code is a REFUSAL: nothing is written, node-run never even reached
+# `codex exec`.
+#   2 - usage: not an intent directory, or missing --node
+#   3 - the node has no live `running` line
+#   4 - the running line is held by another session
+#   5 - the packet the running line names is missing from disk
+#   6 - the packet on disk does not hash to the running line's packet=
+#   7 - no worktree could be resolved to run in
+module NodeRunCLI
+  module_function
+
+  def usage
+    warn "Usage: node-run <intent_dir> --node <id> [--session SID] [--now ISO8601] " \
+         "[--timeout-seconds N]"
+  end
+
+  def opt(args, name)
+    (i = args.index(name)) && args[i + 1]
+  end
+
+  def intent_directory?(dir)
+    dir && File.directory?(dir) && File.exist?(Savepoint.intent_file(dir))
+  end
+
+  # <intent_dir>/packets/<node>--a<N>.return.yml (spec): beside the packet,
+  # one per attempt, the same treatment packet files already get - never
+  # reused across attempts, so a second attempt's return can never be
+  # mistaken for the first's.
+  def return_path(intent_dir, node, attempt)
+    File.join(intent_dir, "packets", "#{node}--a#{attempt}.return.yml")
+  end
+
+  # The node's own declared kind, read straight off its node file - "work"
+  # when the file cannot be found or parsed at all (mirroring RunnerPolicy's
+  # own unknown-kind fallback), but the LITERAL string it declares
+  # otherwise, even an invalid one (matrix row 6.10): CodexAdapter's own
+  # kind table only distinguishes "read-only" (verify, research) from
+  # everything else, so an unrecognized kind still gets the widest, safest
+  # treatment rather than no treatment at all.
+  def resolve_kind(intent_dir, node)
+    path = ReadySet.find_node_path(intent_dir, node)
+    return "work" unless path
+
+    parsed = NodeFile.parse(path)
+    kind = parsed[:kind].to_s.strip
+    kind.empty? ? "work" : kind
+  end
+
+  # The directory `codex exec -C` runs in: a `work` node's own worktree when
+  # one is actually provisioned on disk, else the shared intent worktree -
+  # verify and research nodes never get a worktree of their own (327 D6,
+  # D29), so the only place they could ever leave a diff is the intent
+  # worktree itself, exactly where NodeWorktree.changed_paths already looks
+  # for one.
+  def node_target_dir(context, node:, kind:)
+    if NodeWorktree::WORKTREE_KINDS.include?(kind.to_s)
+      p = NodeWorktree.paths(context, node: node)
+      return p["path"] if p["path"] && Dir.exist?(p["path"])
+    end
+    context.worktree
+  end
+
+  # A synthetic, deliberately non-YAML-mapping line the absorb gate reads as
+  # unparsable (spec Approach: "a return file the gate reads as
+  # unparsable"), covering every subprocess failure the same way: a nonzero
+  # exit, a timeout, an empty message file, and a message with no YAML
+  # document either way. Carries no colon-shaped `key: value` text on
+  # purpose, so it can never accidentally parse as a YAML mapping that
+  # happens to satisfy NodeReturn's own schema.
+  def unparsable_body(node, result)
+    reason =
+      if result[:timed_out]
+        "node-run - codex exec for #{node} timed out with no usable return"
+      elsif !result[:exit_code].nil? && result[:exit_code] != 0
+        "node-run - codex exec for #{node} exited #{result[:exit_code]} with no usable return"
+      else
+        "node-run - codex exec for #{node} produced no parsable YAML document on either " \
+          "--output-last-message or stdout"
+      end
+    "#{reason}\n"
+  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-run: #{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-run: --node is required"
+      usage
+      exit 2
+    end
+
+    session_flag = opt(args, "--session")
+    now_flag = opt(args, "--now")
+    timeout_flag = opt(args, "--timeout-seconds")
+
+    begin
+      now_flag ? Time.iso8601(now_flag) : Time.now
+    rescue ArgumentError
+      warn "node-run: --now must be ISO 8601"
+      exit 2
+    end
+
+    context = RunnerCore.context(intent_dir: intent_dir, session: session_flag,
+                                  env: ENV["CLAUDE_CODE_SESSION_ID"])
+
+    savepoint_path = File.join(intent_dir, "savepoint.md")
+    current_status = NodeLedger.status_for(savepoint_path, node)
+    running_entry = NodeLedger.last_running(savepoint_path, node)
+    unless current_status == "running" && running_entry
+      warn "node-run: #{node} has no live running line (state is #{current_status})"
+      exit 3
+    end
+
+    fields = running_entry[:fields] || {}
+    holder = fields["holder"]
+    if context.session.nil? || context.session.to_s != holder.to_s
+      warn "node-run: #{node}'s running line is held by #{holder.inspect}, not this session"
+      exit 4
+    end
+
+    kind = resolve_kind(intent_dir, node)
+
+    # matrix row 6.11: the attempt number comes from NodePacket's own
+    # counter, never a hand count. `lease_flag_given: false` because the
+    # running line this attempt is acting on ALREADY exists on disk (it is
+    # what we just read above) - counting it a second time would double it
+    # (the same count, plus one, that produced it in the first place when
+    # the packet was originally built).
+    attempt = NodePacket.compute_attempt_number(intent_dir: intent_dir, node: node, lease_flag_given: false)
+    packet_path = NodePacket.packet_path(intent_dir: intent_dir, node: node, attempt: attempt)
+
+    unless File.exist?(packet_path)
+      warn "node-run: #{node}'s packet is missing at #{packet_path}"
+      exit 5
+    end
+
+    packet_bytes = File.binread(packet_path)
+    actual_sha = Digest::SHA256.hexdigest(packet_bytes)[0, 12]
+    expected_sha = fields["packet"]
+    unless expected_sha && actual_sha == expected_sha
+      warn "node-run: #{node}'s packet at #{packet_path} does not hash to packet=#{expected_sha.inspect} " \
+           "(computed #{actual_sha})"
+      exit 6
+    end
+
+    worktree = node_target_dir(context, node: node, kind: kind)
+    if worktree.nil? || !Dir.exist?(worktree)
+      warn "node-run: #{node} has no resolvable worktree to run in"
+      exit 7
+    end
+
+    out_path = return_path(intent_dir, node, attempt)
+    FileUtils.mkdir_p(File.dirname(out_path))
+    message_path = "#{out_path}.msg"
+
+    timeout_seconds = timeout_flag ? timeout_flag.to_i : CodexAdapter.timeout_seconds(kind)
+    codex_argv = CodexAdapter.build_argv(kind: kind, worktree: worktree, output_last_message: message_path)
+
+    result = CodexAdapter.execute(codex_argv, stdin_data: packet_bytes, timeout_seconds: timeout_seconds,
+                                   output_last_message_path: message_path)
+
+    # matrix rows 6.20-6.22: a nonzero exit or a timeout is authoritative -
+    # any message text the child managed to leave behind is never trusted
+    # once either has happened. Only a clean exit with no usable message at
+    # all falls to "no parsable YAML document".
+    failed = result[:timed_out] || (!result[:exit_code].nil? && result[:exit_code] != 0)
+    body = failed ? unparsable_body(node, result) : (result[:message] || unparsable_body(node, result))
+
+    File.write(out_path, body)
+    File.delete(message_path) if File.exist?(message_path)
+
+    puts out_path
+    exit 0
+  end
+end
+
+NodeRunCLI.main(ARGV) if $PROGRAM_NAME == __FILE__

package/scripts/read-config

@@ -33,6 +33,12 @@ DEFAULTS = {
   },
   "architect" => {
     "style" => nil
+  },
+  # Intent 340b (G7c, n4, D9): the Stop hook's runtime arm. Off until the
+  # owner's C32 ruling; read-config emits it as the string "false", which
+  # StopGate parses as a boolean itself rather than trusting.
+  "runner" => {
+    "stop_hook" => false
   }
 }.freeze