@zalom/plastic 2.0.0-alpha.9 → 2.0.2

package/scripts/lib/guarded_append.rb

@@ -0,0 +1,155 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# GuardedAppend - the shared fail-closed write guard behind NodeLedger's transition
+# lines and RoadmapSavepoint's roadmap ledger (intent 335, spec "Approach").
+#
+# One module function, #call: opens `path` RDWR|APPEND|CREAT, takes a non-blocking
+# exclusive lock with a bounded number of retries, and under that ONE hold reads the
+# current content, yields it to the caller's block, and appends whatever the block
+# returns. A block returning nil is a refusal: nothing is written. Read, decide, and
+# append happen inside one lock hold on purpose (spec "Approach"): that is what makes
+# "is this subject already running" and "append running" atomic against a second
+# writer, which a check followed by a separate append could never be.
+#
+# Pure and dependency-injected: `flock:` and `sleeper:` are constructor-style test
+# seams (never an environment variable, never a global); this module reads no
+# environment variable and shells out to nothing.
+module GuardedAppend
+  # Raised when the lock could not be taken within `retries` attempts (real
+  # contention), or when flock itself is unsupported on this filesystem and
+  # `strict: true` (spec D12a). Nothing is written either way; the caller is told
+  # plainly that nothing landed and must retry.
+  class Unavailable < StandardError; end
+
+  module_function
+
+  # Five attempts, 20 ms apart: about 100 ms of wall time total (spec D12).
+  DEFAULT_RETRIES = 5
+  DEFAULT_BACKOFF = 0.02
+
+  # Default lock and sleep seams: a real flock call, a real sleep. Tests inject
+  # replacements to simulate contention, recovery, and a flock-less filesystem
+  # hermetically, with no need for a real flock-less mount or a slow test run.
+  DEFAULT_FLOCK = ->(handle, mode) { handle.flock(mode) }
+  private_constant :DEFAULT_FLOCK
+
+  DEFAULT_SLEEPER = ->(seconds) { sleep(seconds) }
+  private_constant :DEFAULT_SLEEPER
+
+  # Open `path` (creating it if absent, never truncating it), take an exclusive
+  # non-blocking lock with up to `retries` attempts (`backoff` seconds apart), and
+  # under that one hold read the file's current content, yield it to the block, and
+  # append what the block returns.
+  #
+  # Returns :written when a line was appended, :refused when the block returned nil
+  # (nothing written, spec: a refusal). Raises Unavailable, writing nothing, when the
+  # lock could not be taken within `retries` attempts.
+  #
+  # `strict:` decides what happens when flock itself raises a SystemCallError OTHER
+  # than contention (EWOULDBLOCK/EAGAIN) - a filesystem without flock support,
+  # distinct from real contention (spec D12a): strict (the default) raises
+  # Unavailable; non-strict proceeds unguarded, since a single O_APPEND write still
+  # lands whole there. The SystemCallError rescue wraps the flock call only (spec
+  # D12b); an Errno::ENOENT from File.open (a missing parent directory) propagates
+  # as itself, never read as Unavailable.
+  def call(path, retries: DEFAULT_RETRIES, backoff: DEFAULT_BACKOFF, strict: true,
+           flock: DEFAULT_FLOCK, sleeper: DEFAULT_SLEEPER, &block)
+    created = !File.exist?(path)
+    handle = File.open(path, File::RDWR | File::APPEND | File::CREAT, 0o644)
+    begin
+      status = take_lock(handle, retries: retries, backoff: backoff, flock: flock, sleeper: sleeper)
+
+      case status
+      when :contended
+        raise Unavailable, "could not take an exclusive lock on #{path} after #{retries} attempts"
+      when :unsupported
+        if strict
+          raise Unavailable, "flock is unsupported on #{path} and strict: true refuses to proceed unguarded"
+        end
+
+        write_line(handle, &block)
+      when :locked
+        begin
+          write_line(handle, &block)
+        ensure
+          unlock(handle, flock: flock)
+        end
+      end
+    ensure
+      handle.close
+    end
+  rescue Unavailable
+    remove_freshly_created_empty_file(path) if created
+    raise
+  end
+
+  # Attempt the lock up to `retries` times. Returns :locked, :unsupported (a
+  # non-contention SystemCallError from flock, decided once, never retried), or
+  # :contended (every attempt failed with EWOULDBLOCK/EAGAIN or a false return).
+  # Sleeps `backoff` seconds after EVERY contended attempt, including the last, so
+  # the total backoff budget is exactly `retries` sleeps (spec D12: "about 100 ms of
+  # wall time in total" = 5 attempts * 20 ms, not 4).
+  def take_lock(handle, retries:, backoff:, flock:, sleeper:)
+    status = :contended
+    retries.times do
+      status = try_flock(handle, flock)
+      return status unless status == :contended
+
+      sleeper.call(backoff)
+    end
+    status
+  end
+  private_class_method :take_lock
+
+  # One attempt at the non-blocking exclusive lock. File#flock RAISES (does not
+  # return false) for every errno except EWOULDBLOCK/EAGAIN on most platforms, so
+  # both the "returns false" and the "raises EWOULDBLOCK" shapes read as contention;
+  # any other SystemCallError means flock is not supported on this filesystem.
+  def try_flock(handle, flock)
+    result = flock.call(handle, File::LOCK_EX | File::LOCK_NB)
+    result == false ? :contended : :locked
+  rescue Errno::EWOULDBLOCK, Errno::EAGAIN
+    :contended
+  rescue SystemCallError
+    :unsupported
+  end
+  private_class_method :try_flock
+
+  # Read the current content, yield it to the block, and write what it returns. A
+  # block returning nil writes nothing and reports :refused. Before a real write, if
+  # the content is non-empty and does not end in a newline, a newline is written
+  # first (spec D9a): a crash that truncated the previous write must not glue the
+  # next transition onto its tail. The handle is opened O_APPEND, so every write
+  # lands at the current end of file regardless of the read's cursor position.
+  def write_line(handle, &block)
+    content = handle.read
+    line = block.call(content)
+    return :refused if line.nil?
+
+    prefix = !content.empty? && !content.end_with?("\n") ? "\n" : ""
+    handle.write("#{prefix}#{line}")
+    handle.flush
+    :written
+  end
+  private_class_method :write_line
+
+  def unlock(handle, flock:)
+    flock.call(handle, File::LOCK_UN)
+  rescue SystemCallError
+    nil
+  end
+  private_class_method :unlock
+
+  # Row 7.9 (post-execution review): a give-up (Unavailable) must not leave a zero-byte
+  # file behind that File::CREAT created for a target that did not exist before this
+  # call. Only ever removes a file this same call created (never a pre-existing file,
+  # spec matrix 1.11) and only when it is still empty (no write ever reached it on the
+  # give-up paths this rescues).
+  def remove_freshly_created_empty_file(path)
+    File.unlink(path) if File.exist?(path) && File.zero?(path)
+  rescue SystemCallError
+    nil
+  end
+  private_class_method :remove_freshly_created_empty_file
+end

package/scripts/lib/handoff.rb

@@ -19,6 +19,10 @@ module Handoff
   DONE_CAP = 10
   RECENT_CAP = 10
   OTHERS_CAP = 10
+  # Intent 340b (G7c, n4, D11/D12): runner-step.last is raw stdout+stderr,
+  # not a bounded list of items like every other section, so it gets a byte
+  # cap of its own rather than an item count.
+  RUNNER_CAP = 2048
   # A ledger summary may run to 200 characters; a hand-off line shows the
   # first 80, so the caps above are reachable inside the byte budget.
   SUMMARY_MAX = 80
@@ -34,15 +38,11 @@ module Handoff
     File.join(SessionLedger.day_dir(store, day), "handoff--#{session}.md")
   end
 
-  # The day this session's hand-off belongs to: the pointer's day id when
-  # the pointer holds one, else today (no pointer, or a pointer naming an
-  # intent), the same fallback SessionClose uses for the drop at close.
+  # The day this session's hand-off belongs to: the session's day from the
+  # day ledger (SessionLedger.session_day, graph.md D7), the same lookup
+  # SessionClose uses for the drop at close.
   def day_for(store, session, today:)
-    path = SessionLedger.pointer_path(store, session)
-    return today unless File.exist?(path)
-
-    value = File.read(path).strip
-    SessionLedger.valid_day_id?(value) ? value : today
+    SessionLedger.session_day(store, session, today: today)
   end
 
   def clip(summary)
@@ -74,9 +74,34 @@ module Handoff
     end
   end
 
+  # Raw text of the delivering intent's runner-step.last, or nil when there
+  # is no intent, the file is absent, or it cannot be read (row 4.41: a torn
+  # file must never raise a PreCompact hand-off out of existence).
+  def read_runner_last(intent)
+    return nil if intent.to_s.strip.empty?
+
+    path = File.join(intent, "runner-step.last")
+    return nil unless File.file?(path)
+
+    text = File.read(path)
+    text.strip.empty? ? nil : text
+  rescue StandardError
+    nil
+  end
+
+  # Omitted entirely when no intent resolves or the file is absent/empty
+  # (row 4.39); capped like every other section otherwise (row 4.40).
+  def runner_section(intent)
+    text = read_runner_last(intent)
+    return nil unless text
+
+    clipped = text.bytesize > RUNNER_CAP ? "#{text.byteslice(0, RUNNER_CAP)}\n(truncated)" : text
+    "## Runner\n#{clipped}\n"
+  end
+
   # --- rendering, pure -----------------------------------------------------------
 
-  def render(store:, day:, session:, trigger:, now: Time.now)
+  def render(store:, day:, session:, trigger:, now: Time.now, intent: nil)
     raise ArgumentError, "unknown trigger: #{trigger.inspect}" unless TRIGGERS.include?(trigger)
 
     items = read_items(store, day)
@@ -102,8 +127,9 @@ module Handoff
       "Written #{now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')} at #{trigger}",
       "",
     ]
+    runner = runner_section(intent)
     loop do
-      text = compose(header, lists, hidden)
+      text = compose(header, lists, hidden, runner)
       return text if text.bytesize <= BUDGET
 
       key = TRIM_ORDER.find { |k| !lists[k].empty? }
@@ -123,12 +149,13 @@ module Handoff
     lists[key] = lists[key].last(cap)
   end
 
-  def compose(header, lists, hidden)
+  def compose(header, lists, hidden, runner = nil)
     sections = [
       section("Open", lists[:open], hidden[:open]),
       section("Done", lists[:done], hidden[:done]),
       section("Recent", lists[:recent], hidden[:recent]),
       section("Others today", lists[:others], hidden[:others]),
+      runner,
       "## Resume\n#{RESUME}\n",
     ]
     (header + sections.compact).join("\n")
@@ -168,13 +195,13 @@ module Handoff
   # partial hand-off and two writers for one session (a tick overlapping a
   # PreCompact) never share a temp name. Returns the path. With
   # `templates: nil` the day is not scaffolded, only its directory ensured.
-  def write(store:, day:, session:, trigger:, templates:, now: Time.now)
+  def write(store:, day:, session:, trigger:, templates:, now: Time.now, intent: nil)
     if templates
       SessionLedger.open_day(store: store, day: day, templates: templates, author: session)
     else
       FileUtils.mkdir_p(SessionLedger.day_dir(store, day))
     end
-    text = render(store: store, day: day, session: session, trigger: trigger, now: now)
+    text = render(store: store, day: day, session: session, trigger: trigger, now: now, intent: intent)
     target = path_for(store, day, session)
     tmp = File.join(File.dirname(target), ".handoff-#{session}-#{Process.pid}-#{Thread.current.object_id}.tmp")
     File.write(tmp, text)

package/scripts/lib/harness_adapter.rb

@@ -0,0 +1,184 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# HarnessAdapter (intent 340b, G7c, n1): the one module in Plastic that knows
+# a harness by name. It resolves the current key from config `agent.type`,
+# renders a dispatch plan into that harness's instructions, and answers what
+# the ledger should record. `runner step` calls it; nothing else in the
+# runner does (spec D1).
+#
+# Pure: every input is an argument, nothing here reads ENV or a real
+# config.yml itself - the caller (scripts/runner) owns loading real config,
+# this module only resolves values out of what it is handed, the same
+# discipline RunnerPolicy already holds for model resolution.
+module HarnessAdapter
+  module_function
+
+  # The only two harnesses this module knows (spec D2). An unknown key -
+  # config-authored or from `--harness` - always falls back to this rather
+  # than to no adapter at all (matrix row 1.3): a plan with no rendering
+  # under it is worse than a plan rendered for the wrong harness, because the
+  # first is silent.
+  DEFAULT_KEY = "claude-code"
+  KNOWN_KEYS = %w[claude-code codex].freeze
+
+  # The exact sentence 340a's watch prints to stderr and exits 1 with,
+  # before any write, when `--dispatch` is asked of a harness
+  # #unattended_start? refuses (graph.md D7). Quoted verbatim in
+  # docs/reference/harness-adapters.md (D12); change the wording in one
+  # place only.
+  UNATTENDED_START_SENTENCE =
+    "Unattended start is delivered only where a Ruby loop owns dispatch (Codex, through runner " \
+    "watch --dispatch); on Claude Code the runner is the harness session (327 Q6), so arm /loop " \
+    "over runner watch in a live session instead."
+
+  # unattended_start?(key) -> true only for "codex" (graph.md D7): the one
+  # harness where a Ruby loop (RunnerUntilEmpty, through `runner watch
+  # --dispatch`) owns dispatch end to end with nobody on the other end
+  # making subagent calls. Claude Code IS the harness session (327 Q6), and
+  # an unknown key is never granted unattended start either - this module
+  # stays the only place that names a harness, so RunnerWatch asks this
+  # predicate and never compares a key against "codex" itself.
+  def unattended_start?(key)
+    key.to_s == "codex"
+  end
+
+  # kind -> the Claude Code agent type dispatched for it (spec Approach).
+  # Verify and research carry no `Bash` in their own frontmatter (n2); this
+  # table only names WHICH agent a kind maps to. An unknown kind gets
+  # `work`'s row, the widest of the three, never no agent type at all
+  # (matrix row 1.10), mirroring RunnerPolicy's own kind-table fallback.
+  AGENT_TYPE_BY_KIND = {
+    "work" => "plastic-node-work",
+    "verify" => "plastic-node-verify",
+    "research" => "plastic-node-research",
+  }.freeze
+
+  def agent_type_for_kind(kind)
+    AGENT_TYPE_BY_KIND.fetch(kind.to_s, AGENT_TYPE_BY_KIND["work"])
+  end
+
+  # resolve_key(config:, override:) -> the harness key for one call (matrix
+  # rows 1.1-1.3, 1.18). `override` (the CLI's `--harness KEY`, spec D2) wins
+  # over `config`'s own `agent.type` for that one call; either source is
+  # squashed (whitespace collapsed, matrix row 1.18) before it is even
+  # compared, so a config-authored value carrying a tab or a newline can
+  # never reach `NodeLedger` unsquashed and raise `ArgumentError` mid-dispatch,
+  # after the node input is already built. A value that still is not one of
+  # KNOWN_KEYS after squashing falls back to DEFAULT_KEY with a warning
+  # (never to no adapter), so this method's return is always one of the two
+  # known, clean strings - safe to hand straight to a ledger field.
+  def resolve_key(config: {}, override: nil)
+    raw = blank?(override) ? agent_type_from_config(config) : override.to_s
+    squashed = squash(raw)
+    return squashed if KNOWN_KEYS.include?(squashed)
+
+    warn "harness_adapter: unknown harness #{raw.inspect}, falling back to #{DEFAULT_KEY.inspect}"
+    DEFAULT_KEY
+  end
+
+  def agent_type_from_config(config)
+    return DEFAULT_KEY unless config.is_a?(Hash)
+
+    value = config.dig("agent", "type")
+    value = config.dig(:agent, :type) if blank?(value)
+    blank?(value) ? DEFAULT_KEY : value.to_s
+  end
+  private_class_method :agent_type_from_config
+
+  def squash(text)
+    text.to_s.strip.gsub(/\s+/, " ")
+  end
+  private_class_method :squash
+
+  def blank?(value)
+    value.nil? || value.to_s.strip.empty?
+  end
+  private_class_method :blank?
+
+  # render(dispatched, harness:, return_contract:) -> the rendered
+  # instruction block for `harness` (a String), or nil for an empty dispatch
+  # list (matrix row 1.14: a step that dispatched nothing prints no
+  # instruction block for a session to act on). `dispatched` is the runner's
+  # own plan entries (RunnerDispatch's `:dispatched` shape): [{node:, kind:,
+  # role:, model:, worktree:, input:}, ...]. The model and the node input path
+  # ride straight from each entry - never a fresh lookup (matrix row 1.11)
+  # and never a summary (matrix row 1.12) - and `return_contract` (the exact
+  # text RunnerDispatch::RETURN_CONTRACT already carries in the YAML plan)
+  # renders exactly once, above every node, never per node (matrix row 1.13).
+  def render(dispatched, return_contract:, harness: DEFAULT_KEY)
+    entries = Array(dispatched)
+    return nil if entries.empty?
+
+    key = KNOWN_KEYS.include?(harness.to_s) ? harness.to_s : DEFAULT_KEY
+    key == "codex" ? render_codex(entries, return_contract) : render_claude_code(entries, return_contract)
+  end
+
+  # The Claude Code rendering (spec Approach): per dispatched node, the agent
+  # type from the kind, the model the plan already resolved, and the node input
+  # path as the whole prompt.
+  def render_claude_code(entries, return_contract)
+    blocks = entries.map do |d|
+      "Dispatch #{agent_type_for_kind(d[:kind])} for #{d[:node]} (model: #{d[:model]}):\n  prompt: #{d[:input]}"
+    end
+    "#{return_contract.to_s.strip}\n\n#{blocks.join("\n\n")}\n"
+  end
+  private_class_method :render_claude_code
+
+  # The Codex rendering: a Codex node runs end to end through `scripts/
+  # node-run` (n6), which reads the ledger's own `running` line directly and
+  # never through this printed block - so this names, per node, the same
+  # facts the block gives Claude Code (kind, model, node input path) framed as
+  # `node-run` calls, proving the seam renders SOMETHING for the second
+  # harness rather than nothing (matrix row 1.27), without inventing detail
+  # that belongs to n6's own adapter.
+  def render_codex(entries, return_contract)
+    blocks = entries.map do |d|
+      "node-run #{d[:node]} (#{d[:kind]}, model: #{d[:model]}):\n  input: #{d[:input]}"
+    end
+    "#{return_contract.to_s.strip}\n\n#{blocks.join("\n\n")}\n"
+  end
+  private_class_method :render_codex
+
+  # cross_harness_resume(entries) -> [{node:, harnesses: [...], commits: {...}}, ...]
+  # (spec D12, 340b n8). `entries` is a node ledger's own parsed lines (the
+  # shape `NodeLedger.entries`/`entries_from_content` return): every declared
+  # node's own `harness=` values, read across every non-torn line for that
+  # subject in file order, deduplicated by first appearance (matrix row 8.6:
+  # the starting harness is whichever key showed up first). A `reclaimed`
+  # line carries no `harness=` of its own and is never a boundary here (row
+  # 8.7) - it is simply a line with nothing to contribute, scanned like any
+  # other. A node whose lines carry one key, or none at all, reports nothing
+  # (rows 8.2, 8.3): an old ledger with no `harness=` field anywhere must
+  # stay silent rather than raise.
+  #
+  # Every node named by ANY entry is scanned (row 8.8), not only the first;
+  # `RunnerAbsorb` is what put `harness=` on both the running line and the
+  # terminal line, so the commit that lands with the finishing harness's own
+  # terminal line is exactly the evidence a resumed node actually left
+  # behind (row 8.5).
+  def cross_harness_resume(entries)
+    live = Array(entries).reject { |e| e[:torn] }
+    nodes = live.map { |e| e[:subject] }.uniq
+
+    nodes.filter_map do |node|
+      node_lines = live.select { |e| e[:subject] == node }
+      keys = []
+      commits = Hash.new { |h, k| h[k] = [] }
+
+      node_lines.each do |e|
+        fields = e[:fields] || {}
+        key = fields["harness"]
+        next if blank?(key)
+
+        keys << key unless keys.include?(key)
+        commit = fields["commit"]
+        commits[key] << commit unless blank?(commit) || commits[key].include?(commit)
+      end
+
+      next if keys.size < 2
+
+      { node: node, harnesses: keys, commits: keys.to_h { |k| [k, commits[k]] } }
+    end
+  end
+end

package/scripts/lib/hook_registry.rb

@@ -34,6 +34,17 @@ module HookRegistry
           { "name" => "check-update", "status" => "" },
         ] },
       ],
+      # Intent 355, n2: the call budget guard. Not one of the edit-path
+      # gates intent 302 removed (those denied a write on content; this
+      # denies a call on a per-attempt COUNT, read from the session's own
+      # transcript, never from the tool's arguments) - see scripts/hook-
+      # call-budget. Claude only: CODEX_LIVE_STATE_EVENTS below does not
+      # carry PreToolUse, so codex_hooks_json never projects it.
+      "PreToolUse" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "call-budget", "status" => "" },
+        ] },
+      ],
       "PreCompact" => [
         { "matcher" => "", "hooks" => [
           { "name" => "savepoint", "status" => "Saving Plastic intent state..." },
@@ -68,6 +79,18 @@ module HookRegistry
           { "name" => "message-display", "status" => "" },
         ] },
       ],
+      # Continuation on Claude Code (intent 340b, G7c, n4, D5/D7): registered
+      # statically here, like every other hook, and decided at runtime by
+      # StopGate, which reads runner.stop_hook itself (default false, D9).
+      # Not one of CODEX_LIVE_STATE_EVENTS, CODEX_POST_HOOKS or
+      # CODEX_SESSION_END_HOOKS, so codex_hooks_json never picks it up and
+      # codex_hook_names stays at its pinned six (test/hook_registry_test.rb,
+      # test/codex_hooks_test.rb).
+      "Stop" => [
+        { "matcher" => "", "hooks" => [
+          { "name" => "stop", "status" => "" },
+        ] },
+      ],
     }
   end
 
@@ -75,8 +98,9 @@ module HookRegistry
   # the PostToolUse record hook collapses from Claude's multi-tool matcher onto
   # Codex's single apply_patch tool (181 F4: apply_patch is Codex's sole
   # file-mutation tool; tool_name always reports apply_patch), and the live-state
-  # events project through whole. Since intent 302 there is no PreToolUse group at
-  # all: the edit-path gates are gone on both harnesses. Command invokes the
+  # events project through whole. PreToolUse (intent 355, n2's call-budget guard,
+  # Claude only) is not one of CODEX_LIVE_STATE_EVENTS below, so Codex still
+  # carries no PreToolUse group of its own. Command invokes the
   # codex-hook dispatcher with the hook name. Guide-settled shape [guide Part 3]:
   # top-level {"hooks":{<Event>: [{"matcher","hooks":[{"type":"command","command",
   # "statusMessage"}]}]}}, identical to Claude's shape, string command. Single
@@ -149,7 +173,7 @@ module HookRegistry
   # name here in the SAME change. Skip it and every existing install keeps a dead
   # registration no update will ever clean up.
   #
-  # Never fold these into claude_launcher_names: that method is what doctor's
+  # Never merge these into claude_launcher_names: that method is what doctor's
   # hooks_exist demands be present on disk, so a retired name there makes a correct
   # install report missing launchers.
   RETIRED_HOOK_NAMES = %w[