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

package/scripts/runner

@@ -2,24 +2,28 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
+require "yaml"
+require "stringio"
 require_relative "lib/savepoint"
 require_relative "lib/ready_set"
 require_relative "lib/runner_core"
+require_relative "lib/harness_adapter"
 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).
+# (ready, sweep, rewind, until-empty) route and work so `step` can compose
+# them and so each can be tested alone, but stay out of the usage text (327
+# spec, 340b n7).
 #
-# `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.
+# `step`, `sweep`, `answer`, `rewind` and `until-empty` route to modules
+# later nodes deliver (RunnerDispatch and RunnerAbsorb for `step`;
+# RunnerSweep, RunnerAnswer, RunnerRewind, RunnerUntilEmpty 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]
@@ -34,7 +38,7 @@ module Runner
   module_function
 
   PUBLIC_VERBS = %w[step status answer].freeze
-  INTERNAL_VERBS = %w[ready sweep rewind].freeze
+  INTERNAL_VERBS = %w[ready sweep rewind until-empty watch].freeze
   VERBS = (PUBLIC_VERBS + INTERNAL_VERBS).freeze
 
   # verb -> [[ModuleName, lib_file], ...], required lazily inside the verb's
@@ -47,6 +51,8 @@ module Runner
     "sweep" => [["RunnerSweep", "runner_sweep"]],
     "answer" => [["RunnerAnswer", "runner_answer"]],
     "rewind" => [["RunnerRewind", "runner_rewind"]],
+    "until-empty" => [["RunnerUntilEmpty", "runner_until_empty"]],
+    "watch" => [["RunnerWatch", "runner_watch"]],
   }.freeze
 
   def usage
@@ -77,11 +83,21 @@ module Runner
   # 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],
+    "step" => %w[--return --allow-core-drift --harness],
     "answer" => %w[--node --answer],
     "rewind" => %w[--node --confirm],
+    "until-empty" => %w[--harness],
+    "watch" => %w[--dispatch --harness --install-timer --home],
   }.freeze
 
+  # The explicit YAML document-end marker (intent 340b, G7c, n1, row 1.28)
+  # separating the dispatch plan `step` has always printed from the
+  # harness-rendered block underneath it: stdout has never been one YAML
+  # document (absorb/reclaim/extend/reap lines print before the plan,
+  # decision/park lines after it), so a reader splits on this marker rather
+  # than guessing where the plan ends.
+  DOCUMENT_BOUNDARY = "...".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.
@@ -203,6 +219,10 @@ module Runner
       run_answer(intent_dir, args)
     when "rewind"
       run_rewind(intent_dir, args)
+    when "until-empty"
+      run_until_empty(intent_dir, args)
+    when "watch"
+      run_watch(intent_dir, args)
     else
       warn "runner: #{verb}'s module loaded but no dispatcher is wired up yet"
       exit 3
@@ -284,14 +304,156 @@ module Runner
     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.
+  # run_until_empty (intent 340b, G7c, n7): the Codex loop. Internal, like
+  # `rewind` (row 7.13) - `RunnerUntilEmpty.run` composes `step` and
+  # `node-run` itself, since Codex has no session on the other end to make
+  # the subagent calls `step` only ever prints a plan for. `--harness`
+  # threads into every turn the loop runs (row 7.5), never re-resolved per
+  # iteration from a literal. The lock check here is the same defence in
+  # depth `run_step_body` carries (B4): `RunnerUntilEmpty.step_once` refuses
+  # `lock_not_held` on its own first call regardless, so this exits before
+  # even constructing the loop's own state.
+  def run_until_empty(intent_dir, args)
+    harness_override = opt(args, "--harness")
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+
+    unless context.session
+      warn "runner: until-empty refused (lock_not_held)"
+      exit 1
+    end
+
+    result = RunnerUntilEmpty.run(context, harness: harness_override)
+
+    case result[:status]
+    when "complete", "stalled", "needs_decision", "iteration_cap"
+      exit 0
+    else
+      exit 1
+    end
+  end
+
+  # run_watch (intent 340a, G7b, n2): one tick over disk truth. Internal,
+  # like until-empty and rewind - the timer that carries it lives outside
+  # this process (a local `/loop` on Claude Code, a launchd job on Codex,
+  # n3/n4). `--dispatch` is unattended start (graph.md D7): refused here,
+  # before RunnerWatch.tick ever takes the tick lock or writes anything,
+  # when the resolved harness's `HarnessAdapter.unattended_start?` is
+  # false, so a refusal never leaves a `watch.record` line behind that
+  # looks like a completed tick.
+  # --install-timer (intent 340a, G7b, n3, graph.md D9): the Codex carrier.
+  # Writes the plist and prints the path plus the `launchctl load` command;
+  # never runs `launchctl` itself, so the owner stays in control of when the
+  # job actually loads. `--home` defaults to the OS home, as
+  # `scripts/meter-watch --install-timer` already does.
+  def run_watch(intent_dir, args)
+    dispatch = args.include?("--dispatch")
+    harness_override = opt(args, "--harness")
+    context = RunnerCore.context(intent_dir: intent_dir, env: ENV["CLAUDE_CODE_SESSION_ID"])
+    agent_config = load_agent_config(context.plastic_home)
+    harness = HarnessAdapter.resolve_key(config: agent_config, override: harness_override)
+
+    if args.include?("--install-timer")
+      home = opt(args, "--home") || Dir.home
+      plist_path = RunnerWatch.install_timer(context, home: home, harness_key: harness)
+      puts "plist: #{plist_path}"
+      puts "launchctl load #{plist_path}"
+      exit 0
+    end
+
+    if dispatch && !HarnessAdapter.unattended_start?(harness)
+      warn HarnessAdapter::UNATTENDED_START_SENTENCE
+      exit 1
+    end
+
+    result = RunnerWatch.tick(context, dispatch: dispatch, harness: harness)
+
+    puts "class: #{result[:class]}"
+    result[:blockers].each { |b| puts "blocked: #{b}" }
+    puts "ready: #{result[:ready].empty? ? '(none)' : result[:ready].join(', ')}"
+    puts "dispatched: #{result[:dispatched].empty? ? '(none)' : result[:dispatched].join(', ')}"
+    exit 0
+  end
+
+  # run_step (intent 340, G7, n5): one turn of the loop. The real work lives
+  # in #run_step_body below; this wrapper (intent 340b, G7c, n1, rows
+  # 1.21-1.25 and 1.29-1.31) exists ONLY to capture every byte `step` prints
+  # - stdout and stderr both, refusals included - and persist it to
+  # `<intent_dir>/runner-step.last` before the process actually exits, so a
+  # PreCompact hand-off (n3) always has something to render, even after one
+  # of the three pre-plan refusals that used to warn to stderr alone.
+  #
+  # `run_step_body` still calls Kernel#exit(N) at every one of its own exit
+  # points, exactly as before this node; wrapping it in a rescue for
+  # SystemExit lets this method capture the intended status, persist the
+  # file, replay the captured output onto the REAL stdout/stderr (so a
+  # subprocess caller like Open3.capture3 sees byte-identical output to
+  # before this node), and only then perform the one real process exit.
   def run_step(intent_dir, args)
+    out_buf = StringIO.new
+    err_buf = StringIO.new
+    real_stdout = $stdout
+    real_stderr = $stderr
+    exit_code = 0
+    begin
+      $stdout = out_buf
+      $stderr = err_buf
+      run_step_body(intent_dir, args)
+    rescue SystemExit => e
+      exit_code = e.status || 1
+    ensure
+      $stdout = real_stdout
+      $stderr = real_stderr
+    end
+
+    real_stdout.print(out_buf.string)
+    real_stderr.print(err_buf.string)
+    persist_runner_step_last(intent_dir, out_buf.string, err_buf.string)
+
+    exit(exit_code)
+  end
+
+  # Row 1.24: lives beside savepoint.md, never inside packets/ (which the
+  # reaper treats as attempt evidence). Row 1.32: registers itself in the
+  # store's own top-level `.gitignore` (Worktree.ensure_gitignored's own
+  # idempotent, non-raising append) the same way `*.lock` already is, so a
+  # file rewritten on every step never dirties the store tree. Row 1.25:
+  # wrapped in its own rescue - an unwritable intent directory must never
+  # crash a step that has already written its transitions.
+  def persist_runner_step_last(intent_dir, stdout_text, stderr_text)
+    home_root = Arm.home_for(intent_dir)
+    Worktree.ensure_gitignored(File.join(home_root, ".plastic"), "runner-step.last")
+
+    path = File.join(intent_dir, "runner-step.last")
+    File.write(path, "#{stdout_text}#{stderr_text}")
+  rescue StandardError => e
+    warn "runner: could not persist runner-step.last: #{e.message}"
+  end
+
+  # Intent 340b, G7c, n1, row 1.1: the config `HarnessAdapter.resolve_key`
+  # reads `agent.type` from. `context.plastic_home` is derived from the
+  # intent_dir's OWN ancestry (Arm.home_for -> Worktree.home_from_store), so
+  # a sandboxed test fixture never reaches the real ~/.plastic/config.yml
+  # (Arm.home_for's own docstring: "a sandboxed store never resolves to the
+  # real Dir.home") - this stays hermetic for free, the same way every other
+  # `context.plastic_home` read in this file already does. A missing or
+  # unparseable config.yml reads as {}, never raises.
+  def load_agent_config(plastic_home)
+    path = File.join(plastic_home.to_s, "config.yml")
+    return {} unless File.exist?(path)
+
+    YAML.safe_load(File.read(path)) || {}
+  rescue StandardError
+    {}
+  end
+
+  # run_step_body (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_body(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
@@ -322,6 +484,12 @@ module Runner
     # never defaulted true.
     allow_core_drift = args.include?("--allow-core-drift")
 
+    # Intent 340b, G7c, n1, row 1.2/1.4: `--harness KEY` overrides config
+    # `agent.type` for this one call - how one machine drives both adapters
+    # without editing config. `nil` when absent, so HarnessAdapter falls
+    # through to config's own value untouched.
+    harness_override = opt(args, "--harness")
+
     returns = {}
     opt_all(args, "--return").each do |pair|
       node, path = pair.to_s.split("=", 2)
@@ -351,7 +519,8 @@ module Runner
     reaped = NodeWorktree.reap(context)
     reaped[:removed].each { |r| puts "reaped #{r[:node]} worktree" }
 
-    result = RunnerDispatch.dispatch(context)
+    agent_config = load_agent_config(context.plastic_home)
+    result = RunnerDispatch.dispatch(context, config: agent_config, harness: harness_override)
     unless result[:ok]
       warn "runner: step refused (#{result[:reason]}): #{Array(result[:errors]).join('; ')}"
       warn result[:rearm_command] if result[:rearm_command]
@@ -374,6 +543,21 @@ module Runner
       result[:blockers].each { |b| puts "blocked: #{b}" }
     end
 
+    # Intent 340b, G7c, n1, rows 1.6/1.13/1.14/1.27/1.28: the YAML plan keeps
+    # printing exactly as it did before this node (327's contract) - this is
+    # the rendered block UNDERNEATH it, for the harness `result[:harness]`
+    # resolved (config's `agent.type`, or this call's own `--harness`
+    # override), separated by an explicit YAML document-end marker so a
+    # reader splits on that marker rather than a heuristic. `render` returns
+    # nil for an empty dispatch list (row 1.14), so nothing extra ever
+    # prints when this step dispatched nothing.
+    block = HarnessAdapter.render(result[:dispatched], harness: result[:harness],
+                                   return_contract: RunnerDispatch::RETURN_CONTRACT)
+    if block
+      puts DOCUMENT_BOUNDARY
+      puts block
+    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

package/scripts/verify-intent

@@ -11,7 +11,7 @@
 #
 # --base overrides the auto-detected diff base (default: the merge base with the repo's
 # detected default branch) for repos where detection is ambiguous. --suite is an optional
-# caller-supplied command to run (in the repo directory) and fold into the verdict. No
+# caller-supplied command to run (in the repo directory) and merge into the verdict. No
 # other flags exist.
 #
 # Checks, all run every invocation (the fourth only when --suite is given):

package/skills/auto/SKILL.md

@@ -165,7 +165,7 @@ ledger is missing (then rebuild it with `Savepoint.rebuild_savepoint`).
 | `How  plan.md created` / `How  checklist.md created` / `Exec  started` | Exec (verify plan, matrix, checklist) |
 | `Exec  outcome.md created` | Exec done; complete the intent |
 | A terminal savepoint line (`delivered` or `abandoned`) | Terminal; do not resume |
-| A node or `Intent` transition line (`n1  running ...`, `Intent  needs_decision ...`) | Exec; a graph delivery is in progress - drive it through `scripts/runner`'s three public verbs, `step` (one turn of the dispatch loop), `status` (renders ledger state, safe to poll constantly), and `answer` (closes a `needs_decision` node) - read node status through `NodeLedger.status` before dispatching anything, never re-derive it by eye |
+| A node or `Intent` transition line (`n1  running ...`, `Intent  needs_decision ...`) | Exec; a graph delivery is in progress - drive it through `scripts/runner`'s three public verbs, `step` (one turn of the dispatch loop), `status` (renders ledger state, safe to poll constantly), and `answer` (closes a `needs_decision` node) - read node status through `NodeLedger.status` before dispatching anything, never re-derive it by eye. `scripts/graph-measure` is the read-only sibling over that same ledger, with its own three public verbs `intent`, `budget`, and `cohorts` - it never dispatches and never writes |
 
 Filesystem fallback, in order: `checklist.md` with items checked means resume Exec from the
 first unchecked item; `plan.md` plus `checklist.md` means enter Exec; `spec.md` alone means

package/skills/conventions/references/knowledge-graph.md

@@ -45,3 +45,12 @@ This chapter holds the linking doctrine from Frontmatter and the branch-vs-root
   the relation on the PREDECESSOR's `chain` (and mirror it as a
   `[[id--slug|<target's full intent: text>]]` wikilink in `## Links`).
 - **Rule of thumb:** if the intent could exist without its parent, it's a root.
+
+## Naming
+
+A thing is named after the concept family it lives under. A node is a graph-engineering
+concept, so its name comes from graph engineering (node, edge, ready set, critical path),
+from the Plastic concepts coined on top of it (intent, ledger, packet, lease, gate, runner),
+and from the software and AI engineering concepts those rest on (review, fix, test, verify,
+dispatch, executor, reviewer). A name from outside that stack is refused. Where no existing
+concept fits, that is a design finding to raise, not a word to coin.

package/skills/doctor/SKILL.md

@@ -223,7 +223,7 @@ knowingly-exempt `(intent_id, rule)` pairs. Format: one `rule_name id id id` lin
 blank lines and `#` comments ignored. v1 honors exactly one rule, `savepoint_operational`.
 
 **Reading the count.** When any exclusion applies, the `savepoint_operational` check's message
-folds in the count and the file's path, e.g. `"... (3 excluded via ~/.plastic/doctor-exclusions)"`.
+includes the count and the file's path, e.g. `"... (3 excluded via ~/.plastic/doctor-exclusions)"`.
 A malformed line in the file forces the check to `warn` with the parse error in `details`, even
 when zero real gaps remain, so a broken file is never silently permissive.
 
@@ -262,7 +262,7 @@ Locks exist for auto teams: a `delivery.lock` file in the intent directory names
 session, and the `record` hook refreshes its mtime on every edit (the lease heartbeat; stale
 means older than the TTL). Direct work takes no lock. When a lock reads held by a session
 that is gone, when work resumes after a crash, reboot, or `/tmp` wipe, or when the user says
-"fix the lock", "who holds the lock", or "reclaim the lock", use the CLI (intent 304 folded
+"fix the lock", "who holds the lock", or "reclaim the lock", use the CLI (intent 304 merged
 the former locking skill here):
 
 | Verb | What it does | When |
@@ -290,7 +290,7 @@ these verbs (claims, worktrees, the station ledger).
 ## Provisioning a project store
 
 When a project is registered in `~/.plastic/projects.yml` but has no store on disk (doctor
-reports `project_store_dir`), provision it (intent 304 folded the former provisioning skill
+reports `project_store_dir`), provision it (intent 304 merged the former provisioning skill
 here). The slug is the project's key under `projects`; an unregistered slug exits non-zero and
 creates nothing, and this procedure never edits `projects.yml`.
 

package/skills/intent-creating/evals/evals.json

@@ -35,7 +35,7 @@
       "scope": "behavior",
       "set": "validation",
       "prompt": "Create an intent that is the direct continuation of intent 41: it emerged from intent 41's lifecycle and could not exist without it.",
-      "expected_output": "Because the new intent was genuinely CREATED FROM 41 (D1), it carries 41 in --sources (or branches from 41, which folds 41 into sources via the redundant-explicit rule). The reciprocal I1 backlink lands: intent 41's frontmatter chain gains the new intent's id. This is the created-from case, contrasted with the related-but-not-spawned case in eval 1.",
+      "expected_output": "Because the new intent was genuinely CREATED FROM 41 (D1), it carries 41 in --sources (or branches from 41, which merges 41 into sources via the redundant-explicit rule). The reciprocal I1 backlink lands: intent 41's frontmatter chain gains the new intent's id. This is the created-from case, contrasted with the related-but-not-spawned case in eval 1.",
       "files": [],
       "assertions": [
         {

package/skills/intent-executing/SKILL.md

@@ -35,6 +35,12 @@ node returns.
 The dispatch step is the paste, not a lead's hand-typed brief: copy each spawn block into the
 Agent tool as its own dispatch, verbatim.
 
+On Claude Code, the session spawns each dispatched node as a background subagent of its
+per-kind agent (`plastic-node-work`, `plastic-node-verify`, `plastic-node-research`) named in
+the spawn block. On Codex, one node runs over `codex exec` in a sandbox scoped to its kind and
+writes only a return file, which the next `step` absorbs the same way it absorbs a Claude Code
+return.
+
 ## status
 
 `ruby scripts/runner status <intent_dir>` renders the graph's ledger state: which nodes are

package/skills/tutorial/references/track-2-auto.md

@@ -67,7 +67,7 @@ No new command. At each stage boundary (What, Why, How, Exec) the agent briefs i
 fixed three-line shape: State (what happened and why it matters), Risk (the one thing that
 could bite, or "nothing flagged"), and Call (the decision left to the user, or the call the
 agent is taking on its own). That is the depth for a medium or large intent. A small intent
-gets one briefing, at How, folding in what the earlier stages would have said.
+gets one briefing, at How, merging in what the earlier stages would have said.
 
 Checkpoint: in the most recent report, point at the State line, the Risk line, and the Call
 line.