@zalom/plastic 2.0.0-alpha.22 → 2.0.0-alpha.24

package/scripts/lib/session_ledger.rb

@@ -154,14 +154,54 @@ module SessionLedger
     File.join(tmp_root(store), session_id)
   end
 
-  def pointer_path(store, session_id)
-    File.join(session_tmp_dir(store, session_id), "current")
-  end
-
   def heartbeat_path(store, session_id)
     File.join(session_tmp_dir(store, session_id), "heartbeat")
   end
 
+  # --- Session day (spec D7 replacement for the retired pointer) ------------
+
+  # Every day, ascending, no later than `today` and no earlier than `today`
+  # minus `window_days`, whose checklist carries at least one line tagged to
+  # `session` (any state). Each day's checklist is read inside its own
+  # rescue, so one unreadable or missing checklist skips that day only and
+  # never gives up on a later one. Returns an empty array when no day in the
+  # window carries the session's line, and on any error reading the store
+  # (never raises).
+  def session_days(store, session, today:, window_days: 7)
+    root = sessions_root(store)
+    return [] unless File.directory?(root)
+
+    today_date = Date.strptime(today, "%Y%m%d")
+    floor_date = today_date - window_days
+
+    days = Dir.children(root).select { |name| valid_day_id?(name) }.select do |name|
+      date = Date.strptime(name, "%Y%m%d")
+      date >= floor_date && date <= today_date
+    end.sort
+
+    days.select do |day|
+      begin
+        read_locked(checklist_path(store, day)).each_line.any? do |line|
+          parsed = parse_checklist_line(line)
+          parsed && parsed[:session] == session
+        end
+      rescue StandardError
+        false
+      end
+    end
+  rescue StandardError
+    []
+  end
+
+  # The newest day in `session_days`, the day this session's close and
+  # hand-off write belong to (intent 344, G11, D13: a session that crosses
+  # midnight carries lines on more than one day, and the newest is the one
+  # still open). Falls back to `today` when no day in the window carries the
+  # session's line.
+  def session_day(store, session, today:, window_days: 7)
+    session_days(store, session, today: today, window_days: window_days).last || today
+  end
+
   # Create `.tmp/` plus a `.gitignore` holding exactly `*`, if that file does
   # not already exist. The store is a local git repo that auto-commits
   # `add -A`, so without this ignore file every heartbeat write would enter

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/lib/worktree.rb

@@ -108,16 +108,16 @@ module Worktree
 
   # --- provisioning ----------------------------------------------------------
 
-  # Resolve the slug from the bridge's intent.store, create code + store
+  # Resolve the slug from the delivery's intent.store, create code + store
   # worktrees (idempotent: reuse an existing worktree path, do not error), write
-  # the `worktree` block plus `provisioned: true` onto bridge_data, return it.
+  # the `worktree` block plus `provisioned: true` onto delivery, return it.
   #
   # Fails open with a stderr log when the repo is non-git or unresolvable:
   # sets `provisioned: false` and leaves `code: null`. All git ops use
   # `git -C <resolved path>` -- never cwd (decision D6).
-  def provision(bridge_data, home: Dir.home, runner: ShellRunner.new)
-    return bridge_data unless bridge_data.is_a?(Hash)
-    intent = bridge_data["intent"] || {}
+  def provision(delivery, home: Dir.home, runner: ShellRunner.new)
+    return delivery unless delivery.is_a?(Hash)
+    intent = delivery["intent"] || {}
     intent_id = intent["id"].to_s
     store = intent["store"].to_s
     intent_slug = slug_from_dir(intent["dir"]) || slug_from_dir(store)
@@ -173,15 +173,15 @@ module Worktree
     # replaced by the fresh unprovisioned block; the guard must not fail harder
     # than the bug it guards.
     if code_ok
-      bridge_data["worktree"] = block
+      delivery["worktree"] = block
     else
-      existing = bridge_data["worktree"]
+      existing = delivery["worktree"]
       keep = existing.is_a?(Hash) && !blank?(existing["code"]) &&
              Dir.exist?(existing["code"].to_s)
-      bridge_data["worktree"] = block unless keep
+      delivery["worktree"] = block unless keep
     end
 
-    bridge_data
+    delivery
   end
 
   # Remove the worktree (then `git worktree prune`), clear the worktree block.
@@ -189,21 +189,21 @@ module Worktree
   # policy on top via `finish`; this is the plain remove. Pass `remove: false` to
   # clear the block WITHOUT touching git (so `finish` can merge first, then call
   # release to drop the worktree once the code branch is integrated).
-  def release(bridge_data, home: Dir.home, runner: ShellRunner.new, remove: true)
-    return bridge_data unless bridge_data.is_a?(Hash)
-    block = bridge_data["worktree"]
-    return bridge_data unless block.is_a?(Hash)
+  def release(delivery, home: Dir.home, runner: ShellRunner.new, remove: true)
+    return delivery unless delivery.is_a?(Hash)
+    block = delivery["worktree"]
+    return delivery unless block.is_a?(Hash)
 
     if remove
-      slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
+      slug = slug_for_store(delivery.dig("intent", "store").to_s, home: home)
       repo = repo_for(slug, home: home)
 
       remove_worktree(runner, repo: repo, worktree: block["code"]) if repo && block["code"]
       prune(runner, repo: repo) if repo
     end
 
-    bridge_data.delete("worktree")
-    bridge_data
+    delivery.delete("worktree")
+    delivery
   end
 
   # --- cleanup policy (merge-vs-remove) -------------------------------------
@@ -222,19 +222,19 @@ module Worktree
   # Fail-open and idempotent throughout: a missing block, missing branch, or any
   # git failure never raises and never blocks teardown. All git ops use
   # `git -C <path>`, never cwd (decision D6). No-op when nothing was provisioned.
-  def finish(bridge_data, home: Dir.home, runner: ShellRunner.new, merge: false)
-    return bridge_data unless bridge_data.is_a?(Hash)
-    block = bridge_data["worktree"]
-    return bridge_data unless block.is_a?(Hash)
+  def finish(delivery, home: Dir.home, runner: ShellRunner.new, merge: false)
+    return delivery unless delivery.is_a?(Hash)
+    block = delivery["worktree"]
+    return delivery unless block.is_a?(Hash)
 
     if merge
-      slug = slug_for_store(bridge_data.dig("intent", "store").to_s, home: home)
+      slug = slug_for_store(delivery.dig("intent", "store").to_s, home: home)
       repo = repo_for(slug, home: home)
       branch = block["code_branch"]
       merge_branch(runner, repo: repo, branch: branch) if repo && !blank?(branch)
     end
 
-    release(bridge_data, home: home, runner: runner, remove: true)
+    release(delivery, home: home, runner: runner, remove: true)
   end
 
   # Merge `branch` into the repo's default branch from the main checkout. The
@@ -298,8 +298,8 @@ module Worktree
   # --- lock ------------------------------------------------------------------
 
   # True iff ANOTHER session's delivery.lock is FRESH on this intent's dir
-  # (intent 108, D2): the durable lock file decides; /tmp bridges are not
-  # consulted and no pid is probed. current_session being the owner or a
+  # (intent 108, D2): the durable lock file decides alone, and no pid is
+  # probed. current_session being the owner or a
   # delegate does not count as "other". A stale lock does not hold (explicit
   # takeover reclaims it).
   def lock_held_by_other?(intent_id:, store:, current_session:, home: Dir.home,

package/scripts/lib/worktree_sweep.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 require_relative "worktree"
-require_relative "bridge"
+require_relative "index_entry"
 
 # WorktreeSweep -- the one-time orphan sweep for store worktrees retired by
 # intent 178 (D2). Pure candidate classification plus a thin apply step, both
@@ -62,7 +62,7 @@ module WorktreeSweep
 
   # The INDEX.md section heading (e.g. "Active", "Completed") that lists this
   # intent dir, or nil if no INDEX.md entry links to it. Reuses
-  # Bridge.index_entry_match so this never drifts from the shared parser.
+  # IndexEntry.match so this never drifts from the shared parser.
   def index_status(intent_dir, name)
     store = File.dirname(intent_dir)
     index = File.join(File.dirname(store), "INDEX.md")
@@ -75,7 +75,7 @@ module WorktreeSweep
         section = stripped.sub(/\A##\s*/, "").strip
         next
       end
-      m = Bridge.index_entry_match(stripped)
+      m = IndexEntry.match(stripped)
       next unless m
       return section if m[3].to_s.include?(name)
     end

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-packet → node-input}

@@ -2,30 +2,30 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-require_relative "lib/node_packet"
+require_relative "lib/node_input"
 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
+# node-input - the CLI over NodeInput (intent 338, G5). Builds one node's
+# whole input from disk and writes it to attempts/<node>--a<N>.input (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]
+#   node-input <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)
+#   0 - the node input 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 NodeInputCLI
   module_function
 
   def usage
-    warn "Usage: node-packet <intent_dir> --node <id> [--budget N] [--hop-tokens N] " \
+    warn "Usage: node-input <intent_dir> --node <id> [--budget N] [--hop-tokens N] " \
          "[--holder H] [--expires E] [--model M] [--attempt N] [--out PATH] [--force]"
   end
 
@@ -42,7 +42,7 @@ module NodePacketCLI
     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"
+      warn "node-input: #{intent_dir_arg.inspect} is not an intent directory"
       usage
       exit 2
     end
@@ -50,7 +50,7 @@ module NodePacketCLI
 
     node = opt(args, "--node")
     if node.to_s.strip.empty?
-      warn "node-packet: --node is required"
+      warn "node-input: --node is required"
       usage
       exit 2
     end
@@ -64,11 +64,11 @@ module NodePacketCLI
     model = opt(args, "--model")
     force = args.include?("--force")
 
-    result = NodePacket.build(
+    result = NodeInput.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,
+      budget_tokens: budget ? budget.to_i : NodeInput::DEFAULT_BUDGET_TOKENS,
+      hop_tokens: hop_tokens ? hop_tokens.to_i : NodeInput::DEFAULT_HOP_TOKENS,
       holder: holder,
       expires: expires,
       model: model,
@@ -78,15 +78,15 @@ module NodePacketCLI
     )
 
     if result[:ok]
-      puts NodePacket.summary_line(result)
+      puts NodeInput.summary_line(result)
       puts result[:running_command]
       exit 0
     end
 
-    Array(result[:errors]).each { |e| warn "node-packet: #{e}" }
+    Array(result[:errors]).each { |e| warn "node-input: #{e}" }
     puts result[:needs_decision_command] if result[:needs_decision_command]
     exit result[:exit_code]
   end
 end
 
-NodePacketCLI.main(ARGV) if $PROGRAM_NAME == __FILE__
+NodeInputCLI.main(ARGV) if $PROGRAM_NAME == __FILE__

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_input"
+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 node input that line names,
+# builds the `codex exec` argv for the node's kind (CodexAdapter), runs it
+# in the node's worktree with the node input 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 node input the running line names is missing from disk
+#   6 - the node input on disk does not hash to the running line's input=
+#   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>/attempts/<node>--a<N>.return.yml (spec): beside the node input,
+  # one per attempt, the same treatment input 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, "attempts", "#{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 NodeInput'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 node input was originally built).
+    attempt = NodeInput.compute_attempt_number(intent_dir: intent_dir, node: node, lease_flag_given: false)
+    input_path = NodeInput.input_path(intent_dir: intent_dir, node: node, attempt: attempt)
+
+    unless File.exist?(input_path)
+      warn "node-run: #{node}'s node input is missing at #{input_path}"
+      exit 5
+    end
+
+    input_bytes = File.binread(input_path)
+    actual_sha = Digest::SHA256.hexdigest(input_bytes)[0, 12]
+    expected_sha = fields["input"]
+    unless expected_sha && actual_sha == expected_sha
+      warn "node-run: #{node}'s node input at #{input_path} does not hash to input=#{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: input_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__