@zalom/plastic 1.8.0 → 1.10.0

package/scripts/hook-session-start

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 # encoding: UTF-8
-# Usage: hook-session-start <index_path> <store_root> <mode> [plugin_root]
+# Usage: hook-session-start <index_path> <plastic_home> <mode> [plugin_root]
 # Outputs hook JSON for the session-start hook. Exits silently if nothing to show.
 
 require "json"
@@ -9,10 +9,16 @@ require "yaml"
 require_relative "lib/bridge"
 require_relative "lib/boot_banner"
 require_relative "lib/qmd_sync"
-require_relative "doctor"
+require_relative "lib/doctor_core"
 
-index_path, store_root, mode, plugin_root = ARGV
-exit 0 unless index_path && store_root && mode
+index_path, plastic_home, mode, plugin_root = ARGV
+exit 0 unless index_path && plastic_home && mode
+
+# Plastic home and the store are two different paths (intent 231). The shim passes
+# home (~/.plastic) as argument 2; the store lives one level below it. Compose the
+# store exactly once here, so no later line re-derives it and no path can gain a
+# doubled store/ segment.
+store_dir = File.join(plastic_home, "store")
 
 # --- Parse INDEX.md ---
 
@@ -47,11 +53,11 @@ end
 bridge_data = nil
 if active.length == 1 && active.first =~ /store\/([\w-]+)\//
   dir_name = $1
-  intent_dir = "#{store_root}/store/#{dir_name}"
+  intent_dir = "#{store_dir}/#{dir_name}"
   session = ENV["CLAUDE_CODE_SESSION_ID"] || Process.pid.to_s
   intent_id = dir_name.split("--").first
   intent_name = active.first[/\[([^\]]+)\]/, 1] || "unknown"
-  bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_root, name: intent_name)
+  bridge_data = Bridge.derive(session, intent_id: intent_id, intent_dir: intent_dir, store: store_dir, name: intent_name)
 end
 
 # --- Detect stale future intents ---
@@ -68,7 +74,7 @@ stale_days = 3 if stale_days == 0
 future.each do |f|
   if f =~ /store\/([\w-]+)\//
     dir_name = $1
-    intent_file = "#{store_root}/store/#{dir_name}/#{dir_name}.md"
+    intent_file = "#{store_dir}/#{dir_name}/#{dir_name}.md"
     next unless File.exist?(intent_file)
 
     content = File.read(intent_file)
@@ -88,7 +94,7 @@ current_project = nil
 project_active = []
 project_future = []
 
-projects_path = "#{store_root}/projects.yml"
+projects_path = "#{plastic_home}/projects.yml"
 if File.exist?(projects_path)
   projects = YAML.safe_load(File.read(projects_path)) rescue {}
   cwd = Dir.pwd
@@ -96,7 +102,7 @@ if File.exist?(projects_path)
     project_path = File.expand_path(info["path"])
     if cwd.start_with?(project_path)
       current_project = { "slug" => slug, "parent" => info["parent"], "path" => project_path }
-      project_index = "#{store_root}/projects/#{slug}/INDEX.md"
+      project_index = "#{plastic_home}/projects/#{slug}/INDEX.md"
       if File.exist?(project_index)
         p_section = nil
         File.readlines(project_index).each do |pline|
@@ -122,7 +128,7 @@ end
 
 # --- Load PLASTIC.md conventions ---
 
-plastic_md_path = "#{store_root}/PLASTIC.md"
+plastic_md_path = "#{plastic_home}/PLASTIC.md"
 plastic_md = File.exist?(plastic_md_path) ? File.read(plastic_md_path).strip : nil
 
 # --- Load deprecations ---
@@ -130,7 +136,7 @@ plastic_md = File.exist?(plastic_md_path) ? File.read(plastic_md_path).strip : n
 dep_file = if plugin_root && !plugin_root.empty?
   "#{plugin_root}/deprecations.yml"
 else
-  "#{store_root}/deprecations.yml"
+  "#{plastic_home}/deprecations.yml"
 end
 
 deprecations = []
@@ -147,7 +153,7 @@ rescue
 end
 
 current_version = nil
-version_file = "#{store_root}/VERSION"
+version_file = "#{plastic_home}/VERSION"
 if File.exist?(version_file)
   current_version = File.read(version_file).strip
 elsif plugin_root && !plugin_root.empty?
@@ -167,7 +173,7 @@ end
 # --- Check for available updates (from previous session's check) ---
 
 update_notice = nil
-cache_file = "#{store_root}/.cache/update-check.json"
+cache_file = "#{plastic_home}/.cache/update-check.json"
 if File.exist?(cache_file)
   cache = JSON.parse(File.read(cache_file)) rescue {}
   if cache["updateAvailable"]
@@ -181,7 +187,7 @@ end
 # session: any failure or exception degrades to a banner and we continue.
 
 core_health = begin
-  Doctor.new(plastic_home: store_root).run_core_checks("claude")
+  Doctor.new(plastic_home: plastic_home).run_core_checks("claude")
 rescue
   nil
 end
@@ -212,7 +218,7 @@ parts << ""
 # slow/broken/missing qmd appends nothing and the hook continues cleanly.
 begin
   require "timeout"
-  qmd_status = Timeout.timeout(2) { QmdSync.status(plastic_home: store_root) }
+  qmd_status = Timeout.timeout(2) { QmdSync.status(plastic_home: plastic_home) }
   if qmd_status[:present]
     if qmd_status[:all_registered]
       parts << "QMD: #{qmd_status[:registered].size} Plastic collections indexed (search with the qmd skill)."

package/scripts/lib/apply_patch_envelope.rb

@@ -13,16 +13,27 @@
 # Part 4] the hook stdin schema, including `tool_input.command` as the carrier of
 # the apply_patch envelope text (consumed by scripts/codex-hook).
 #
-# Residual gap (in neither the guide nor 181, per Decision 14): the apply_patch
-# V4A envelope INNER grammar parsed below (`*** Begin/End Patch`, `*** Add/Update/
-# Delete File:`, `*** Move to:`, `+`/`-`/context lines) is not primary-sourced.
-# There is no live Codex to verify it against (the owner has none installed), so
-# this parser is built to the best-known public V4A shape and FAILS OPEN on
-# anything else. Returns [] and warns on any missing or unparseable envelope:
-# gates fail OPEN (orchestrator-locks fail-open rule). The PostToolUse gate-check
-# artifact backstop re-validates the intent file after the write, so a fail-open
-# create-gate is still netted. A real Codex run after delivery is the only future
-# check on this residual.
+# Grammar provenance (intent 239, 2026-08-12). The V4A envelope grammar parsed below
+# is primary-sourced: it is embedded verbatim in the native codex binary and was
+# extracted from codex-cli 0.146.0 into test/fixtures/codex-v4a-grammar.txt, which
+# carries the binary's path, size and SHA256 in its header.
+# test/codex_v4a_grammar_test.rb checks this parser's markers against that grammar,
+# and a live test re-extracts from an installed binary so the fixture cannot drift
+# (it skips cleanly on a machine with no codex).
+#
+# Two deliberate differences from the real grammar, both in the safe direction:
+# codex requires the envelope's first line to be "*** Begin Patch" and its last to be
+# "*** End Patch", while this parser scans for the markers on any line of the
+# payload, not only the first and last; and "*** Environment ID:", a real production
+# of the grammar, is ignored here rather than parsed, because it names no file
+# operation. Both markers still must form a WHOLE LINE (start-of-text or a
+# preceding LF, and end-of-text or a following LF): per add_line: "+" /(.*)/ LF, a
+# content line such as "+*** End Patch" is legal file content, not a terminator, so a
+# bare substring search would misparse it as the real marker (see
+# line_anchored_index below). Anything else unparseable FAILS OPEN: parse returns []
+# and warns, so gates allow the write (orchestrator-locks fail-open rule), and the
+# PostToolUse gate-check backstop re-validates the intent file after the write
+# lands.
 module ApplyPatchEnvelope
   module_function
 
@@ -39,9 +50,11 @@ module ApplyPatchEnvelope
   # patch text by scanning for the Begin/End markers regardless of wrapping.
   def parse(command)
     text = command.is_a?(Array) ? command.join("\n") : command.to_s
-    b = text.index(BEGIN_MARK)
-    e = text.index(END_MARK)
-    return warn_empty("no Begin/End Patch markers") if b.nil? || e.nil? || e < b
+    b = line_anchored_index(text, BEGIN_MARK, 0)
+    return warn_empty("no Begin/End Patch markers") if b.nil?
+
+    e = line_anchored_index(text, END_MARK, b + BEGIN_MARK.length)
+    return warn_empty("no Begin/End Patch markers") if e.nil?
 
     body = text[(b + BEGIN_MARK.length)...e]
     ops = []
@@ -73,4 +86,24 @@ module ApplyPatchEnvelope
     $stderr.puts "plastic apply_patch parse: #{reason}; gate fails open"
     []
   end
+
+  # Finds the first occurrence of `mark` starting at or after `from` that forms a
+  # WHOLE LINE: immediately preceded by start-of-text or a newline, and immediately
+  # followed by end-of-text or a newline. A bare `text.index(mark)` would also match
+  # `mark` sitting inside a longer line, such as the content line "+*** End Patch"
+  # (legal per add_line: "+" /(.*)/ LF), which is not a terminator.
+  def line_anchored_index(text, mark, from)
+    pos = from
+    loop do
+      idx = text.index(mark, pos)
+      return nil if idx.nil?
+
+      line_start = idx.zero? || text[idx - 1] == "\n"
+      after = idx + mark.length
+      line_end = after == text.length || text[after] == "\n"
+      return idx if line_start && line_end
+
+      pos = idx + 1
+    end
+  end
 end

package/scripts/lib/bridge.rb

@@ -9,6 +9,7 @@ require "digest"
 require "socket"
 require_relative "worktree"
 require_relative "lock"
+require_relative "spec_header"
 
 module Bridge
   STAGES = %w[what why how exec done].freeze
@@ -662,13 +663,10 @@ module Bridge
   # matching the skill and agent contracts). Returns nil when spec.md is
   # absent, empty, or its first line does not match, so a missing/malformed
   # Tier line changes nothing about existing rebuild behavior.
+  # The grammar itself now lives in SpecHeader (scripts/lib/spec_header.rb, intent 213);
+  # this method is a thin read on top of it.
   def self.savepoint_tier(intent_dir)
-    path = File.join(intent_dir, "spec.md")
-    return nil unless File.exist?(path)
-    first = File.open(path, &:gets)
-    return nil if first.nil?
-    m = first.chomp.strip.match(/\ATier:\s*(S|M|L)\z/)
-    m && m[1]
+    SpecHeader.parse_file(File.join(intent_dir, "spec.md"))[:tier]
   end
 
   # Reconstruct the ledger from files on disk (timestamps from mtimes), in
@@ -767,12 +765,16 @@ module Bridge
     phantoms
   end
 
-  def self.derive(session, intent_id:, intent_dir:, store:, name:, tmp: tmp_dir)
+  # Pure compute (intent 230): build the bridge state and write NOTHING. `derive`
+  # is the writing wrapper over this; `arm` and `repair_lock` use the pure form so
+  # the single bridge write happens only after the delivery lock and the worktree
+  # have both settled. Joins the pure `derive_stage` / `derive_key` family.
+  def self.derive_data(session, intent_id:, intent_dir:, store:, name:)
     stage = derive_stage(intent_dir)
     has = has_files(intent_dir)
     missing = missing_for_stage(stage, intent_dir) - has
 
-    data = {
+    {
       "session" => session,
       "intent" => {
         "id" => intent_id,
@@ -816,7 +818,14 @@ module Bridge
         "delegates" => []
       }
     }
+  end
 
+  # Compute AND persist. Contract unchanged (intent 230 kept it deliberately):
+  # `scripts/hook-session-start` calls this and wants the immediate write, and
+  # test/bridge_worktree_derive_test.rb pins write-on-call.
+  def self.derive(session, intent_id:, intent_dir:, store:, name:, tmp: tmp_dir)
+    data = derive_data(session, intent_id: intent_id, intent_dir: intent_dir,
+                       store: store, name: name)
     write(session, data, tmp: tmp)
     data
   end
@@ -881,6 +890,19 @@ module Bridge
 
   # --- Auto mode (intent 27) ---
 
+  # Intent 230: freshly composed state carries worktree.code = nil, so a failed
+  # Worktree.provision would have nothing to keep. Seed the block from the bridge
+  # already on disk when it names a code path, so provision's keep-rule (see
+  # Worktree.provision) can preserve it. Provision SUCCESS overwrites this with
+  # the freshly resolved (identical) pointer, so this only matters on failure.
+  def self.carry_prior_worktree(data, session, tmp: tmp_dir)
+    prior = read(session, intent_id: data.dig("intent", "id"), tmp: tmp)
+    block = prior && prior["worktree"]
+    data["worktree"] = block if block.is_a?(Hash) && !blank?(block["code"])
+    data
+  end
+  private_class_method :carry_prior_worktree
+
   # Shared arming spine (intent 96): resolve the session key, derive intent state,
   # set the caller-controlled auto flag, acquire the delivery lock, provision the
   # per-intent worktrees, persist, and purge terminal bridges. arm_auto (auto: true)
@@ -893,7 +915,10 @@ module Bridge
     if blank?(session) && blank?(ENV["CLAUDE_CODE_SESSION_ID"])
       $stderr.puts "plastic: no session id available; arming with derived bridge key #{key}"
     end
-    data = derive(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
+    # Compute only (intent 230). Nothing reaches disk until the lock is ours and
+    # the worktree has settled; a LockHeldError below must leave the previous
+    # bridge exactly as it was.
+    data = derive_data(key, intent_id: intent_id, intent_dir: intent_dir, store: store, name: name)
     data["build"]["auto"] = auto
 
     # Acquire the durable delivery lock (D1/D2): session-keyed, O_EXCL, in the
@@ -924,6 +949,8 @@ module Bridge
         "run #{skill_ref('plastic-doctor', harness: harness)} fix the lock"
     end
 
+    carry_prior_worktree(data, key)
+
     # Provision the per-intent worktrees (mandatory code worktree for project
     # intents; fail-open for non-git / global-only). Never let a provision error
     # break arming: the lock and auto flag still matter.
@@ -959,13 +986,24 @@ module Bridge
   # Degrade path for disarm_auto when no intent_id is given (intent 131): the
   # session's sole per-intent bridge when there is exactly one, else the
   # legacy single-key file. Keeps the common single-intent auto path working
-  # without every caller having to name the intent id explicitly.
+  # without every caller having to name the intent id explicitly. With TWO or
+  # more per-intent bridges it refuses to guess (intent 233); see below.
   def self.sole_bridge_data(session, tmp: tmp_dir)
     matches = Dir.glob(File.join(tmp, "plastic-#{session}--*.json")).reject { |f| f.end_with?(".tmp") }
     if matches.length == 1
       data = (JSON.parse(File.read(matches.first)) rescue nil)
       return data if data
     end
+    # Refuse to guess among siblings (intent 233): with 2+ per-intent bridges
+    # the legacy single-key file below can carry EITHER sibling, so falling
+    # through would let a no-id disarm release the wrong intent's lock. A
+    # disarm that does nothing is recoverable; one that unlocks a live
+    # delivery is not. Zero matches keeps the legacy fallback (131 migration).
+    if matches.length > 1
+      $stderr.puts "plastic: session #{session} has #{matches.length} bridges; " \
+                   "disarm needs an explicit intent_id (refusing to guess)"
+      return nil
+    end
     read(session, tmp: tmp)
   end
 
@@ -979,6 +1017,9 @@ module Bridge
   # (one per concurrent intent), so disarm must target ONE of them. When
   # intent_id is nil, degrades to the session's sole bridge (see
   # sole_bridge_data) so the common single-intent path keeps working.
+  #
+  # The lock clear is conditional (intent 233): a failed release leaves the
+  # cached lock fields alone so the orphan stays findable.
   def self.disarm_auto(session, intent_id: nil)
     data = blank?(intent_id) ? sole_bridge_data(session) : read(session, intent_id: intent_id)
     return nil unless data
@@ -994,14 +1035,39 @@ module Bridge
       $stderr.puts "plastic: worktree release raised, continuing: #{e.message}"
     end
 
+    # Check what the release actually DID before touching the cache (intent
+    # 233). Blanking the cache after a failed release orphans the durable
+    # delivery.lock: the file stays on disk and nothing points at it any more.
+    # Rescue mirrors the Worktree.release rescue above: warn, never raise,
+    # never abort the rest of the tail (the guard fails milder than the bug).
     dir = bridge_intent_dir(data)
+    release_status = nil
     if dir
       owner = data.dig("lock", "owner_session")
       owner = session if blank?(owner)
-      Lock.release(dir, session: owner)
+      begin
+        release_status = Lock.release(dir, session: owner)
+      rescue => e
+        release_status = :raised
+        $stderr.puts "plastic: delivery lock release raised for #{dir}, continuing: #{e.message}"
+      end
     end
-    data["lock"] = { "owner_session" => nil, "acquired_at" => nil,
-                     "host" => nil, "type" => nil, "delegates" => [] }
+
+    # Success means "no lock left on disk": :released (we deleted it), :none
+    # (there was none), and nil (no intent dir, so no release was attempted).
+    # Only :not_owner and a raised release keep the cache pointing at the lock
+    # so plastic-lock fix / reclaim / doctor can still find and repair it.
+    if release_status.nil? || release_status == :released || release_status == :none
+      data["lock"] = { "owner_session" => nil, "acquired_at" => nil,
+                       "host" => nil, "type" => nil, "delegates" => [] }
+    else
+      $stderr.puts "plastic: delivery lock NOT released for #{dir} (#{release_status}); " \
+                   "bridge lock cache preserved for repair"
+      data["lock"] = {} unless data["lock"].is_a?(Hash)
+    end
+    # Diagnostic only (D5): the primary contract stays "owner_session non-nil
+    # after disarm means the lock was not released".
+    data["lock"]["release_status"] = release_status.nil? ? nil : release_status.to_s
 
     write(session, data)
     purge_done_bridges(session: session)
@@ -1070,11 +1136,13 @@ module Bridge
       actions << "lock #{status}"
     end
 
-    data = derive(key, intent_id: intent_id, intent_dir: dir, store: store,
-                  name: name, tmp: tmp)
+    data = derive_data(key, intent_id: intent_id, intent_dir: dir, store: store,
+                       name: name)
     data["build"]["auto"] = auto
     data["lock"] = lock_cache(lock_data)
 
+    carry_prior_worktree(data, key, tmp: tmp)
+
     # Provision the per-intent worktrees so the rebuilt bridge carries
     # worktree.code (intent 136). Without it, cwd/edited-path selection has no
     # key: the repaired intent loses its own code gate and a concurrent sibling
@@ -1598,8 +1666,8 @@ module Bridge
   end
 
   # A TRAILING `# plastic-ok` shell comment: the auditable escape for
-  # sanctioned bash/interpreter writes (mirrors the retrieval gate's
-  # `# qmd-ok`). The hook logs every use to ~/.plastic/.cache/gate-escapes.log.
+  # sanctioned bash/interpreter writes. The hook logs every use to
+  # ~/.plastic/.cache/gate-escapes.log.
   PLASTIC_OK_RE = /(?:\A|\s)#\s*plastic-ok\s*\z/.freeze
 
   def self.bash_escape?(command)

package/scripts/lib/codex_edit_gates.rb

@@ -0,0 +1,138 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# CodexEditGates (intent 251): the merged Codex apply_patch edit path. One
+# process, one stdin parse, one envelope parse, five gates in-process.
+#
+# Before this, ~/.codex/hooks.json registered five separate PreToolUse commands
+# on the apply_patch matcher and three of them spawned a further run_core child
+# per file operation: eight processes per edit, ten across a full edit cycle.
+# This is the Codex mirror of what intent 244 did for Claude (spec D-e of that
+# intent parked it as a successor).
+#
+# Every DECISION here comes from scripts/lib/edit_gates.rb, the same functions
+# scripts/hook-edit-gates drives for Claude. This file contributes exactly three
+# Codex-specific things and nothing else:
+#   1. the per-operation Context (the patch envelope carries a path plus ADDED
+#      lines, not Claude's file_path plus content pair),
+#   2. the add-only rule for create-gate (Update/Delete/Move defer to the
+#      PostToolUse gate-check backstop, intent 102 spec Decision 5), and
+#   3. the two-pass evaluation that keeps savepoint-pre's ledger append
+#      unconditional across a multi-operation patch (intent 244 spec D-c).
+#
+# NO SUBPROCESS MAY EVER BE ADDED TO THIS FILE. That is the whole point of the
+# intent, and test/codex_edit_gates_test.rb asserts it against this source.
+require "stringio"
+require_relative "edit_gates"
+require_relative "hook_registry"
+
+module CodexEditGates
+  module_function
+
+  # Pass 1 and pass 2 of the two-pass evaluation (spec D3). Both slices preserve
+  # HookRegistry::CODEX_GATE_TOOLS key order, which is Claude's evaluation order
+  # (spec D5): savepoint-pre, lock-gate, code-gate, links-gate, create-gate.
+  SAVEPOINT_TOOLS = HookRegistry::CODEX_GATE_TOOLS.select { |gate, _| gate == "savepoint-pre" }.freeze
+  DENY_TOOLS      = HookRegistry::CODEX_GATE_TOOLS.reject { |gate, _| gate == "savepoint-pre" }.freeze
+
+  # One Context per file operation. gate_path and file_path both carry the
+  # envelope's raw path, exactly as the five popened cores received it in ARGV[0]
+  # before the merge. content is always a String (never nil), because
+  # ApplyPatchEnvelope gives a Delete op a nil added_content and today's
+  # dispatcher already called .to_s on it at every call site. harness is "codex"
+  # so lock-gate and the claim gate render deny reasons in the $plastic-<name>
+  # form (intent 201 D2).
+  def context_for(payload, op, env: ENV)
+    session = payload["session_id"]
+    session = env["CLAUDE_CODE_SESSION_ID"] if session.to_s.empty?
+
+    EditGates::Context.new(
+      tool_name: payload["tool_name"],
+      session: (session unless session.to_s.empty?),
+      gate_path: op.path,
+      file_path: op.path,
+      savepoint_path: op.path,
+      content: op.added_content.to_s,
+      harness: "codex",
+    )
+  end
+
+  # create-gate is a pre-write veto for ADD operations only (spec D2).
+  # EditGates.create_gate has no such rule: fed a partial Update hunk as content
+  # it would run IntentValidator on a fragment and FALSE-DENY a legitimate write.
+  def create_gate(ctx, op)
+    return EditGates::ALLOW unless op.op == :add
+    EditGates.create_gate(ctx)
+  end
+
+  def route_for(op)
+    lambda do |gate, ctx|
+      case gate
+      when "savepoint-pre" then EditGates.savepoint_pre(ctx)
+      when "lock-gate"     then EditGates.lock_gate(ctx)
+      when "code-gate"     then EditGates.code_gate(ctx)
+      when "links-gate"    then EditGates.links_gate(ctx)
+      when "create-gate"   then create_gate(ctx, op)
+      end
+    end
+  end
+
+  # True iff tool_name is a NON-EMPTY string that no CODEX_GATE_TOOLS entry
+  # matches. An empty/missing tool_name already means "the harness matched but
+  # did not name the tool" and every gate runs (EditGates.tool_applies?'s own
+  # empty-name rule); this is the OTHER unmatched case, a non-empty tool_name
+  # this dispatcher does not recognize. Checked once against "apply_patch",
+  # since every CODEX_GATE_TOOLS value is the identical single-entry list.
+  def unexpected_tool_name?(tool_name)
+    return false if tool_name.to_s.empty?
+    !EditGates.tool_applies?(tool_name, %w[apply_patch])
+  end
+
+  # Returns the process exit code. Two passes (spec D3):
+  #   pass 1 runs savepoint-pre over EVERY op. It never denies, and running it
+  #   before any deny check keeps its started ledger append unconditional, so
+  #   op B's ledger line still lands when op A is blocked.
+  #   pass 2 runs the four denying gates per op, first deny wins.
+  # EditGates.dispatch returns 0 both for "allowed" and for lock-gate's JSON
+  # deny, so pass 2 captures stdout per op: a non-empty buffer IS a deny, and it
+  # is printed and evaluation stops. Without that capture a second op could emit
+  # a second deny JSON.
+  #
+  # Codex only ever invokes this dispatcher from the apply_patch matcher, so by
+  # the time we get here the harness HAS already matched, regardless of what
+  # tool_name the payload itself carries. A non-empty, unrecognized tool_name
+  # (a future Codex rename, or a malformed/adversarial payload) must therefore
+  # never silently skip every gate: that is the coverage WEAKENING
+  # EditGates.tool_applies?'s own empty-name rule exists to prevent, just
+  # triggered from the opposite direction (an unrecognized name here, not a
+  # missing one there). Loud and safe: warn once to err and run all five gates
+  # exactly as if tool_name had been "apply_patch", rather than silent and
+  # permissive.
+  def dispatch(ops:, payload:, out: $stdout, err: $stderr)
+    if unexpected_tool_name?(payload["tool_name"])
+      err.puts "plastic codex edit-gates: unexpected tool_name #{payload["tool_name"].inspect}; " \
+                "the apply_patch matcher already selected this dispatcher, so all five gates run anyway"
+      payload = payload.merge("tool_name" => "apply_patch")
+    end
+
+    pairs = ops.map { |op| [op, context_for(payload, op)] }
+
+    pairs.each do |op, ctx|
+      EditGates.dispatch(ctx: ctx, route: route_for(op), gate_tools: SAVEPOINT_TOOLS,
+                         out: StringIO.new, err: err)
+    end
+
+    pairs.each do |op, ctx|
+      buffer = StringIO.new
+      code = EditGates.dispatch(ctx: ctx, route: route_for(op), gate_tools: DENY_TOOLS,
+                                out: buffer, err: err)
+      return code unless code.zero?
+      next if buffer.string.empty?
+
+      out.print buffer.string
+      return 0
+    end
+
+    0
+  end
+end