@zalom/plastic 1.11.0 → 1.13.0

package/scripts/doctor.rb

@@ -13,6 +13,7 @@ require "date"
 
 require_relative "lib/doctor_core"
 
+require_relative "lib/doctor_exclusions"
 require_relative "lib/qmd_sync"
 require_relative "lib/intent_validator"
 require_relative "lib/graph_rebuild"
@@ -531,17 +532,24 @@ class Doctor
 # check_done_signals's store-wide loop (211's territory, unchanged severities) and the new
 # per-intent check (check_intent_end) call, so the two surfaces can never independently
 # drift on what counts as a phantom line or a completeness gap. Returns
-# {conflict:, phantom:, gap:, stalled:} where conflict/phantom/stalled are nil or a finding
-# string, and gap is an ARRAY (0, 1, or 2 strings): the original inline code pushed the
-# "outcome missing" gap and the "audit echo missing" gap as two SEPARATE, independent `if`
-# blocks (never elsif), so a single terminal dir missing BOTH can legitimately contribute
-# two distinct gap strings in the same pass; collapsing that into one nilable field would
-# silently drop one of the two on a dir where both are true (verified against
-# test/doctor_done_signals_test.rb's fixtures before this extraction, per plan.md Step 3).
-def done_signal_findings_for_dir(dir, label:, scope:, dirname:, terminal:, active:)
+# {conflict:, phantom:, gap:, operational_gap:, excluded:, stalled:} where conflict/phantom/
+# stalled are nil or a finding string, and gap/operational_gap/excluded are ARRAYs (0, 1, or 2
+# strings): the original inline code pushed the "outcome missing" gap and the "audit echo
+# missing" gap as two SEPARATE, independent `if` blocks (never elsif), so a single terminal
+# dir missing BOTH can legitimately contribute two distinct gap strings in the same pass;
+# collapsing that into one nilable field would silently drop one of the two on a dir where
+# both are true (verified against test/doctor_done_signals_test.rb's fixtures before this
+# extraction, per plan.md Step 3).
+#
+# `excluded_rules:` (intent 274) is the set of rule names the caller's doctor-exclusions file
+# names for this one intent id. A savepoint_operational finding routes to :excluded instead of
+# :operational_gap when "savepoint_operational" is in that set; the :gap bucket (signals_complete,
+# the outcome.md check) never consults it, which is what keeps the exclusion key (intent_id,
+# rule) rather than just intent_id (see test/doctor_done_signals_test.rb case 12).
+def done_signal_findings_for_dir(dir, label:, scope:, dirname:, terminal:, active:, excluded_rules: [])
   outcome = File.join(dir, "outcome.md")
   outcome_real = Bridge.stage_file_present?(outcome)
-  findings = { conflict: nil, phantom: nil, gap: [], operational_gap: [], stalled: nil }
+  findings = { conflict: nil, phantom: nil, gap: [], operational_gap: [], excluded: [], stalled: nil }
 
   # HARD conflict: the deliverable exists but INDEX still says Active. This
   # is the one true INDEX-wins disagreement, so it stays a fail.
@@ -578,12 +586,13 @@ def done_signal_findings_for_dir(dir, label:, scope:, dirname:, terminal:, activ
     # reconstructible via maintenance-run --tool rebuild-savepoint, so this is repairable and
     # reported as a fixable warn (savepoint_operational).
     savepoint = File.join(dir, "savepoint.md")
+    bucket = excluded_rules.include?("savepoint_operational") ? findings[:excluded] : findings[:operational_gap]
     if !File.exist?(savepoint)
-      findings[:operational_gap] << "#{label}: terminal in INDEX but savepoint.md is missing " \
-                                    "entirely (operational - reconstructible)"
+      bucket << "#{label}: terminal in INDEX but savepoint.md is missing " \
+                "entirely (operational - reconstructible)"
     elsif File.read(savepoint) !~ /\bDone\b.*\b(delivered|abandoned)\b/
-      findings[:operational_gap] << "#{label}: terminal in INDEX but savepoint.md has no " \
-                                    "`Done delivered|abandoned` line (operational - reconstructible)"
+      bucket << "#{label}: terminal in INDEX but savepoint.md has no " \
+                "`Done delivered|abandoned` line (operational - reconstructible)"
     end
 
     # Stalled completion: unchanged, never consulted amnesty.
@@ -601,10 +610,20 @@ def check_done_signals(scopes: nil)
   conflicts = []
   gaps = []              # delivery-claim (outcome.md) gaps only - legacy, informational
   operational_gaps = []  # savepoint gaps (missing file, or missing Done echo) - repairable
+  excluded = []           # savepoint gaps knowingly exempted via doctor-exclusions (intent 274)
+  exclusion_errors = []   # malformed doctor-exclusions lines, scope-tagged
+  exclusion_error_paths = []
+  exclusion_paths = []    # files that actually contributed a live exclusion
   stalled = []
   phantoms = []
 
   done_signal_stores(scopes).each do |store|
+    exclusions = DoctorExclusions.load(store[:index])
+    if exclusions[:errors].any?
+      exclusion_errors.concat(exclusions[:errors].map { |e| "#{store[:scope]}: #{e}" })
+      exclusion_error_paths << exclusions[:path]
+    end
+
     index_sections_by_dir(store[:index]).each do |dirname, in_sections|
       dir = File.join(store[:store_dir], dirname)
       next unless File.directory?(dir)
@@ -612,17 +631,26 @@ def check_done_signals(scopes: nil)
       terminal = (in_sections & ["Completed", "Abandoned"]).any?
       active = in_sections.include?("Active") && !terminal
       label = "#{store[:scope]} store/#{dirname}"
+      intent_id = dirname.split("--", 2).first
+      excluded_rules = DoctorExclusions.rules_for(exclusions, intent_id)
 
       findings = done_signal_findings_for_dir(
-        dir, label: label, scope: store[:scope], dirname: dirname, terminal: terminal, active: active
+        dir, label: label, scope: store[:scope], dirname: dirname, terminal: terminal, active: active,
+        excluded_rules: excluded_rules
       )
       conflicts << findings[:conflict] if findings[:conflict]
       phantoms << findings[:phantom] if findings[:phantom]
       gaps.concat(findings[:gap])
       operational_gaps.concat(findings[:operational_gap])
+      if findings[:excluded].any?
+        excluded.concat(findings[:excluded])
+        exclusion_paths << exclusions[:path]
+      end
       stalled << findings[:stalled] if findings[:stalled]
     end
   end
+  exclusion_paths.uniq!
+  exclusion_error_paths.uniq!
 
   checks = []
 
@@ -662,18 +690,39 @@ def check_done_signals(scopes: nil)
     )
   end
 
-  # savepoint_operational (intent 211, NEW): missing savepoint.md or missing Done echo -
-  # repairable via maintenance-run --tool rebuild-savepoint, so this stays warn+fixable.
-  if operational_gaps.empty?
+  # savepoint_operational (intent 211; intent 274 adds the per-store doctor-exclusions index):
+  # missing savepoint.md or missing Done echo - repairable via maintenance-run --tool
+  # rebuild-savepoint for most gaps, or knowingly excluded for the ones 219 D6 forbids ever
+  # repairing (no real outcome.md to echo a disposition from). Three branches (spec D4/D5):
+  # a malformed exclusion file can never report pass (loud), a clean remaining gap set reports
+  # pass with the exclusion count folded in, and a real remaining gap set stays warn, same as
+  # before intent 274, with the same count folded in when exclusions applied.
+  exclusion_suffix = excluded.empty? ? "" : " (#{excluded.size} excluded via #{exclusion_paths.join(", ")})"
+
+  if exclusion_errors.any?
+    checks << check(
+      category: "done_signals", name: "savepoint_operational", status: "warn",
+      message: "#{operational_gaps.size} terminal intent#{operational_gaps.size == 1 ? "" : "s"} " \
+               "missing an operational savepoint.md or its Done echo, and " \
+               "#{exclusion_errors.size} doctor-exclusions error#{exclusion_errors.size == 1 ? "" : "s"} " \
+               "(a malformed exclusion file never suppresses a finding)#{exclusion_suffix}",
+      details: operational_gaps + exclusion_errors, fixable: true,
+      fix_hint: "Fix the malformed doctor-exclusions file(s) (#{exclusion_error_paths.join(", ")}) - " \
+                "format `rule_name id id id`, blank lines and # comments ignored - then reconstruct " \
+                "any remaining real gap via `maintenance-run --tool rebuild-savepoint --intent <id> " \
+                "--apply` (197-conformant: receipt-before-write via RevisionsWriter, one intent per " \
+                "invocation, owner-approval-gated)."
+    )
+  elsif operational_gaps.empty?
     checks << check(
       category: "done_signals", name: "savepoint_operational", status: "pass",
-      message: "No terminal intent is missing an operational savepoint.md or its Done echo"
+      message: "No terminal intent is missing an operational savepoint.md or its Done echo#{exclusion_suffix}"
     )
   else
     checks << check(
       category: "done_signals", name: "savepoint_operational", status: "warn",
       message: "#{operational_gaps.size} terminal intent#{operational_gaps.size == 1 ? "" : "s"} " \
-               "missing an operational savepoint.md or its Done echo (reconstructible)",
+               "missing an operational savepoint.md or its Done echo (reconstructible)#{exclusion_suffix}",
       details: operational_gaps, fixable: true,
       fix_hint: "Reconstruct the minimal two-line started/Done echo via " \
                 "`maintenance-run --tool rebuild-savepoint --intent <id> --apply` (197-conformant: " \

package/scripts/lib/bridge.rb

@@ -37,8 +37,9 @@ module Bridge
   # `## Active` block); such bridges are purged. An Active intent's bridge is kept
   # unconditionally, because while the intent is live the bridge is still load-
   # bearing: it is the continuation signal (a parked or interrupted run resumes
-  # from it) and the anti-collision lock (it keys the per-session statusline so
-  # parallel sessions do not overwrite each other). An age window was the wrong
+  # from it) and the anti-collision lock for parallel deliveries on one store,
+  # keeping each session's gate checks and locks from overwriting another's. An
+  # age window was the wrong
   # axis: it left dead bridges resident for ~2 days AND could reap bridges of
   # interrupted-but-still-active intents, which are exactly the ones to preserve.
 
@@ -121,7 +122,7 @@ module Bridge
   # The CLAUDE_CODE_SESSION_ID fallback (intent 79) carries the bg/headless real
   # session id (Claude Code passes session_id on stdin, not via an env var; the
   # headless id lives in CLAUDE_CODE_SESSION_ID). Keying by the real id (instead of
-  # a derived hash) lets the statusline, which receives that same id on stdin, find
+  # a derived hash) lets the gate hooks, which receive that same id on stdin, find
   # the bridge by direct filename lookup.
   def self.resolve_session(explicit, intent_id:, store:)
     return explicit.to_s.strip unless blank?(explicit)

package/scripts/lib/doctor_core.rb

@@ -32,7 +32,9 @@ class Doctor
   # (intent 204): plastic-statusline is the settings["statusLine"] command, wired
   # outside HookRegistry.events entirely, so it must be excluded from the
   # orphan-launcher scan below or a correct install would report a false orphan.
-  CLAUDE_NON_HOOK_LAUNCHERS = %w[plastic-statusline].freeze
+  # Defined in HookRegistry (intent 275) so the installer's purge can read it too;
+  # this is an alias, not a second source of truth.
+  CLAUDE_NON_HOOK_LAUNCHERS = HookRegistry::CLAUDE_NON_HOOK_LAUNCHERS
 
   REQUIRED_SCRIPTS = %w[
     folgezettel-id
@@ -105,6 +107,19 @@ class Doctor
     path.sub(Dir.home, "~")
   end
 
+  # Every hook command string registered under one settings.json event, flattened
+  # across that event's matcher groups. Shape-tolerant on purpose: settings.json is
+  # hand-editable and may carry anything at all under an event key.
+  def event_commands(groups)
+    return [] unless groups.is_a?(Array)
+
+    groups.flat_map do |group|
+      next [] unless group.is_a?(Hash) && group["hooks"].is_a?(Array)
+
+      group["hooks"].map { |h| h.is_a?(Hash) ? h["command"].to_s : "" }
+    end
+  end
+
   def check(category:, name:, status:, message:, details: [], fixable: false, fix_hint: nil)
     result = {
       category: category,
@@ -243,7 +258,10 @@ class Doctor
         message: "#{orphans.size} hook launcher(s) on disk are not registered in HookRegistry",
         details: orphans.map { |h| "#{tilde(hooks_dir)}/#{h}" },
         fixable: true,
-        fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude (prunes stale launchers)"
+        fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude (prunes " \
+                  "stale launchers). The plastic- prefix is reserved for Plastic's own hooks: " \
+                  "if one of these is yours, rename it (for example to ~/.claude/hooks/" \
+                  "writing-style) and re-register it in settings.json before re-running."
       )
     end
 
@@ -265,14 +283,30 @@ class Doctor
       )
     else
       hooks = settings["hooks"] || {}
+
+      # A live registration is a launcher Plastic ships TODAY (intent 277).
+      # claude_purge_command?, which this replaced, answers "was this ever ours":
+      # right for the installer's purge, wrong here, because a SessionStart
+      # carrying only the retired plastic-lock-gate satisfied the event while
+      # nothing shipped to run it.
       missing_events = CLAUDE_HOOK_EVENTS.reject do |event|
-        groups = hooks[event]
-        next false unless groups.is_a?(Array)
+        event_commands(hooks[event]).any? { |cmd| HookRegistry.claude_current_command?(cmd) }
+      end
 
-        groups.any? do |group|
-          group.is_a?(Hash) && group["hooks"].is_a?(Array) &&
-            group["hooks"].any? { |h| h["command"].to_s.include?("plastic-") }
-        end
+      # Name the launcher when a missing event still carries a Plastic-owned
+      # command. Inside a missing event every such command is by construction not
+      # a current one, and a bare "SessionStart" reads as "nothing registered" to
+      # someone looking at a settings.json that plainly holds a plastic- entry.
+      # Events with no Plastic entry keep the bare name: two tests compare details
+      # by element equality and by count.
+      missing_details = missing_events.map do |event|
+        stale = event_commands(hooks[event])
+                .flat_map { |cmd| HookRegistry.command_basenames(cmd) }
+                .select { |name| HookRegistry.claude_purgeable_launcher_names.include?(name) }
+                .uniq
+        next event if stale.empty?
+
+        "#{event} (registered command is not a current Plastic hook: #{stale.join(', ')})"
       end
 
       if missing_events.empty?
@@ -284,7 +318,7 @@ class Doctor
         checks << check(
           category: "agent_registration", name: "hooks_registered", status: "fail",
           message: "#{missing_events.size} hook event(s) not registered in settings.json",
-          details: missing_events,
+          details: missing_details,
           fixable: true, fix_hint: "Re-run the Plastic installer: npx @zalom/plastic@latest --claude"
         )
       end
@@ -309,7 +343,7 @@ class Doctor
       live_plastic = (settings["hooks"] || {}).flat_map do |event, groups|
         Array(groups).flat_map do |g|
           next [] unless g.is_a?(Hash) && g["hooks"].is_a?(Array)
-          g["hooks"].map { |h| h["command"].to_s }.select { |c| c.include?("plastic-") }
+          g["hooks"].map { |h| h["command"].to_s }.select { |c| HookRegistry.claude_purge_command?(c) }
                     .map { |c| "#{event}: #{c}" }
         end
       end

package/scripts/lib/doctor_exclusions.rb

@@ -0,0 +1,93 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "rule_catalog"
+
+# DoctorExclusions - resolves, reads, and parses one store's per-store `doctor-exclusions`
+# table (intent 274): the record of knowingly-exempt (intent_id, rule) pairs that lets doctor
+# skip a finding it can never legitimately repair (219 D6 forbids inventing a disposition for
+# an unrepairable gap).
+#
+# Location (spec D6): sibling to that store's INDEX.md, resolved via `path_for` from the same
+# `store[:index]` Doctor#done_signal_stores already yields - zero new store-discovery logic.
+# Deliberately no `.md` extension: this is a config table, not a markdown document indexed by
+# QMD or walked by lifecycle machinery.
+#
+# Format (spec D6), `/etc/hosts`-shaped: `rule_name id id id`, one rule per line. Blank lines
+# and `#`-comment lines are ignored. Duplicate rule lines union their ids.
+#
+# Error contract (spec D5): fail open, loud in doctor. A missing file is the normal case -
+# zero exclusions, zero errors, identical to before this file existed. A malformed line never
+# excludes anything (fail milder than the bug: a typo must not silently suppress a real
+# regression) and contributes one error string naming its 1-based line number. An unreadable
+# file contributes one error and zero exclusions. This module NEVER raises.
+module DoctorExclusions
+  module_function
+
+  FILENAME = "doctor-exclusions"
+
+  # Same shape test/packaging_no_store_ids_test.rb already defines for a real Folgezettel id:
+  # digit-leading, then any mix of letters and digits.
+  FOLGEZETTEL_ID = /\A\d+[a-zA-Z0-9]*\z/
+
+  def path_for(index_path)
+    File.join(File.dirname(index_path), FILENAME)
+  end
+
+  # PURE. { rules: { rule_name => [ids] }, errors: [String] }. A line producing any error
+  # contributes nothing to rules; duplicate rule lines union their ids without an error.
+  #
+  # `scrub` (never raises) before any regex/String op: a hand-edited file can carry a byte
+  # sequence invalid in its declared encoding (e.g. a stray Latin-1 byte in a comment), and
+  # String#strip/split/=~ all raise Encoding::CompatibilityError on that input. Scrubbing
+  # replaces the invalid byte with U+FFFD and keeps this module's never-raises contract (D5)
+  # true for every input, not just well-formed UTF-8.
+  def parse(text)
+    rules = {}
+    errors = []
+
+    text.to_s.scrub.each_line.with_index(1) do |raw_line, n|
+      line = raw_line.strip
+      next if line.empty? || line.start_with?("#")
+
+      line = line.sub(/(?:\A|\s)#.*\z/, "").rstrip
+      tokens = line.split
+      rule = tokens.shift
+      line_errors = []
+
+      line_errors << "line #{n}: rule \"#{rule}\" lists no intent ids" if tokens.empty?
+      unless RuleCatalog.excludable_check?(rule)
+        line_errors << "line #{n}: unknown or non-excludable rule \"#{rule}\""
+      end
+      tokens.each do |tok|
+        line_errors << "line #{n}: \"#{tok}\" is not a Folgezettel intent id" unless tok =~ FOLGEZETTEL_ID
+      end
+
+      if line_errors.empty?
+        (rules[rule] ||= []).concat(tokens)
+        rules[rule].uniq!
+      else
+        errors.concat(line_errors)
+      end
+    end
+
+    { rules: rules, errors: errors }
+  end
+
+  # IO. `parse`'s shape plus `path:`. Never raises: a missing file is the normal case (zero
+  # exclusions, zero errors); an unreadable file (permission, is-a-directory, any
+  # SystemCallError) yields one error and zero exclusions.
+  def load(index_path)
+    path = path_for(index_path)
+    return { rules: {}, errors: [], path: path } unless File.exist?(path)
+
+    parse(File.read(path)).merge(path: path)
+  rescue SystemCallError => e
+    { rules: {}, errors: ["#{path}: unreadable (#{e.message})"], path: path }
+  end
+
+  # Rule names excluding `intent_id` in an already-`load`ed result. [] when none.
+  def rules_for(loaded, intent_id)
+    loaded[:rules].select { |_rule, ids| ids.include?(intent_id) }.keys
+  end
+end

package/scripts/lib/hook_registry.rb

@@ -186,6 +186,110 @@ module HookRegistry
           .uniq.sort.map { |name| "plastic-#{name}" }
   end
 
+  # Launchers the installer places in the agent's hooks dir that `events` does not
+  # register (intent 204): plastic-statusline is the settings["statusLine"] command.
+  # Defined here rather than in doctor_core so the installer's purge can recognise it
+  # without depending on the doctor; Doctor::CLAUDE_NON_HOOK_LAUNCHERS aliases it.
+  CLAUDE_NON_HOOK_LAUNCHERS = %w[plastic-statusline].freeze
+
+  # Hook names Plastic HAS registered and no longer does (intent 275). Purge-only:
+  # an old install still carries these entries in settings.json / hooks.json, and
+  # nothing else can tell us they were ever ours.
+  #
+  # MAINTENANCE DUTY: renaming or removing a hook from `events` means adding its old
+  # 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
+  # hooks_exist demands be present on disk, so a retired name there makes a correct
+  # install report missing launchers.
+  RETIRED_HOOK_NAMES = %w[
+    code-gate create-gate links-gate lock-gate savepoint-pre
+    qmd-search retrieval-gate model-instructions opus-manual
+  ].freeze
+
+  RETIRED_CLAUDE_LAUNCHERS = RETIRED_HOOK_NAMES.map { |n| "plastic-#{n}" }.freeze
+
+  # Filenames of Plastic's Codex dispatcher, current and retired. Codex hooks are
+  # not per-hook launcher files: every command is `"<dispatcher>" <name>`, so the
+  # dispatcher's own filename is what identifies an entry as ours.
+  CODEX_DISPATCHER_BASENAMES = %w[codex-hook].freeze
+
+  # Every launcher name the installer may purge from settings.json: what we register
+  # now, the non-hook launchers we place, and what we used to register.
+  def claude_purgeable_launcher_names
+    (claude_launcher_names + CLAUDE_NON_HOOK_LAUNCHERS + RETIRED_CLAUDE_LAUNCHERS).uniq.sort
+  end
+
+  # Current Codex hook names, from the same sources codex_hooks_json builds from.
+  def codex_hook_names
+    live = CODEX_LIVE_STATE_EVENTS.flat_map do |event|
+      events[event].flat_map { |g| g["hooks"].map { |h| h["name"] } }
+    end
+    (CODEX_PRE_HOOKS + CODEX_POST_HOOKS + CODEX_BASH_HOOKS + live).uniq.sort
+  end
+
+  def codex_purgeable_hook_names
+    (codex_hook_names + RETIRED_HOOK_NAMES).uniq.sort
+  end
+
+  # Is this settings.json hook command one of OURS? (intent 275)
+  #
+  # Ownership is registry membership, never a substring: the substring test this
+  # replaced deleted a user's own ~/.claude/hooks/plastic-writing-style hook on
+  # update. Tokenised rather than first-token-only because legacy entries take the
+  # form `ruby <path>/plastic-<name>.rb`, and those must still be purged.
+  def claude_purge_command?(cmd)
+    known = claude_purgeable_launcher_names
+    command_basenames(cmd).any? { |name| known.include?(name) }
+  end
+
+  # Is this settings.json hook command one Plastic registers TODAY? (intent 277)
+  #
+  # The narrower twin of claude_purge_command?. The purge asks "was this ever
+  # ours", because it has to recognise an old entry in order to remove it. A
+  # liveness check asks "is there something here that still runs", and the two
+  # sets differ by exactly the entries that make the answers disagree: a
+  # SessionStart carrying only plastic-lock-gate satisfied doctor's
+  # hooks_registered while no such launcher ships anymore.
+  #
+  # Sourced from claude_launcher_names alone, so RETIRED_CLAUDE_LAUNCHERS is out
+  # (that is the bug) and CLAUDE_NON_HOOK_LAUNCHERS is out too: plastic-statusline
+  # is settings["statusLine"], not a hook of any event, so a group whose only
+  # Plastic entry is the statusline command has no hook registered in it.
+  # Tokenised through command_basenames like the purge predicate, so a quoted
+  # path or the legacy `ruby <path>/plastic-<name>.rb` form still resolves.
+  def claude_current_command?(cmd)
+    known = claude_launcher_names
+    command_basenames(cmd).any? { |name| known.include?(name) }
+  end
+
+  # Is this ~/.codex/hooks.json command one of ours? Every Plastic Codex entry
+  # invokes our dispatcher by path (`"<plastic_home>/scripts/codex-hook" <name>`),
+  # so the dispatcher's filename identifies it. Basename EQUALITY, so a user's
+  # ~/bin/codex-hook-wrapper is not ours; the argument is not filtered on, because
+  # a command that already runs our dispatcher is ours whatever gate it names, and
+  # filtering would strand any name we forgot to retire.
+  #
+  # Tokenised the same way claude_purge_command? is (command_basenames), NOT a
+  # naive cmd.split.first: a first-token split breaks whenever plastic_home
+  # contains a space, since the shell-quoted dispatcher path then splits across
+  # multiple whitespace tokens and the true first token is only half the path.
+  # command_basenames strips quote characters per token, so whichever token
+  # carries the dispatcher's trailing `/codex-hook"` still resolves to the bare
+  # basename "codex-hook" after its trailing quote is stripped.
+  def codex_purge_command?(cmd)
+    command_basenames(cmd).any? { |name| CODEX_DISPATCHER_BASENAMES.include?(name) }
+  end
+
+  # Each whitespace-separated token reduced to a comparable launcher name:
+  # quotes stripped, directories dropped, a trailing .rb removed.
+  def command_basenames(cmd)
+    cmd.to_s.split(/\s+/).reject(&:empty?).map do |token|
+      File.basename(token.delete("\"'")).sub(/\.rb\z/, "")
+    end
+  end
+
   # The settings.json shape merge_claude_hooks expects: single-group events map
   # to a Hash, multi-group events to an Array (the merge loop handles both).
   def claude_settings_hooks(hook_dir:)