openclacky 1.2.7 → 1.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8057fdabcb077c8ca378fcbbc0efa442abc6b9664464d2d8d1b737e0206d2ed9
-  data.tar.gz: 657f282a20664ef793d7ff663e963739f5fbdb478b8e174df9c5e459ec09231b
+  metadata.gz: '080944ed788d584c01c97ba01a27a63b2d2ab341ecf88140a63424460dcb105e'
+  data.tar.gz: 3c2b51bde81be7c18b3384297609f0163d5e6ed40de7121185a4cc374e576f10
 SHA512:
-  metadata.gz: fad3e045271032a1150745f1d8531aeed24ea376efdcd99346aeaeec4eb5f1edec187e9dbe38ee8d19e5a9cf599bfb7e5431ad55e5993f1dd243bb4ebf5faa2d
-  data.tar.gz: 95b1a7ec783b459f5c70b99d3535f5a0054d4a8c72d855d9c98b9771cde9d59cb33dcf609be844fade932e1487c82c525cf4354438c5ad4b271494a4166dc729
+  metadata.gz: c21e88b443f05ae75979ca4b890142ad15283382ba39fba434a3478f9f3a7f08b13c50fd5760d128662dee26374d69695e6b35e0d25e8f92cdad7351517f564f
+  data.tar.gz: fd37b0b3d64bc68ac777c84beef22be2c6f10c260b5e959273b953aae739c1f176bce7dae5c01c738acb332c5eded97eb973250f51576accbce58ee5f9e12139

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.8] - 2026-06-01
+
+### Added
+- Extensibility framework: patching, shell hooks, and channel user adapter plugins — customize Clacky behavior without modifying core code
+
+### Improved
+- Billing session list now shows session names, merged deleted sessions, and standardized token breakdown with cache hit/miss color coding
+
+### Fixed
+- Streaming LLM responses automatically retry when connection drops instead of silently truncating
+
+### More
+- Extend openclacky skill with additional extension points
+
 ## [1.2.7] - 2026-06-01
 
 ### Added

data/lib/clacky/agent.rb

@@ -137,6 +137,9 @@ module Clacky
       # Register built-in tools
       register_builtin_tools
 
+      # Load declarative shell hooks from ~/.clacky/hooks.yml
+      ShellHookLoader.load_into(@hooks)
+
       # Ensure user-space parsers are in place (~/.clacky/parsers/)
       Utils::ParserManager.setup!
 

data/lib/clacky/billing/billing_store.rb

@@ -4,7 +4,7 @@ require "json"
 require "fileutils"
 require "securerandom"
 require_relative "billing_record"
-
+require_relative "../session_manager"
 module Clacky
   module Billing
     # Persistent storage for billing records using JSONL files
@@ -115,8 +115,112 @@ module Clacky
         }
       end
 
-      # Get daily cost breakdown for the last N days
-      # @param days [Integer] Number of days to include
+      # Get session-level summary statistics
+      # @param period [Symbol] :day, :week, :month, :year, or :all
+      # @param model [String, nil] Filter by model name
+      # @param limit [Integer] Maximum number of sessions to return
+      # @return [Array<Hash>] Session summaries sorted by cost descending
+      def session_summary(period: :month, model: nil, limit: 50)
+        from_time = period_start(period)
+        records = query(from: from_time, model: model)
+
+        # Load session names from session manager
+        session_names = load_session_names
+
+        # Group by session_id
+        by_session = records.group_by { |r| r.session_id || "unknown" }
+
+        active_sessions = []
+        deleted_records = []
+
+        by_session.each do |session_id, rs|
+          total_cost = rs.sum { |r| r.cost_usd || 0 }
+          total_prompt = rs.sum { |r| r.prompt_tokens || 0 }
+          total_completion = rs.sum { |r| r.completion_tokens || 0 }
+          total_cache_read = rs.sum { |r| r.cache_read_tokens || 0 }
+          total_cache_write = rs.sum { |r| r.cache_write_tokens || 0 }
+          first_record = rs.min_by { |r| r.timestamp }
+          last_record = rs.max_by { |r| r.timestamp }
+
+          entry = {
+            session_id: session_id,
+            session_name: session_names[session_id],
+            total_cost: total_cost.round(6),
+            total_tokens: total_prompt + total_completion,
+            prompt_tokens: total_prompt,
+            completion_tokens: total_completion,
+            cache_read_tokens: total_cache_read,
+            cache_write_tokens: total_cache_write,
+            requests: rs.size,
+            first_request: first_record&.timestamp&.iso8601,
+            last_request: last_record&.timestamp&.iso8601,
+            models: rs.map(&:model).uniq
+          }
+
+          if session_names[session_id]
+            active_sessions << entry
+          else
+            deleted_records << entry
+          end
+        end
+
+        # Merge all deleted sessions into a single row
+        if deleted_records.any?
+          merged = {
+            session_id: "_deleted_",
+            session_name: nil,
+            is_deleted: true,
+            total_cost: deleted_records.sum { |r| r[:total_cost] }.round(6),
+            total_tokens: deleted_records.sum { |r| r[:total_tokens] },
+            prompt_tokens: deleted_records.sum { |r| r[:prompt_tokens] },
+            completion_tokens: deleted_records.sum { |r| r[:completion_tokens] },
+            cache_read_tokens: deleted_records.sum { |r| r[:cache_read_tokens] },
+            cache_write_tokens: deleted_records.sum { |r| r[:cache_write_tokens] },
+            requests: deleted_records.sum { |r| r[:requests] },
+            first_request: deleted_records.map { |r| r[:first_request] }.compact.min,
+            last_request: deleted_records.map { |r| r[:last_request] }.compact.max,
+            models: deleted_records.flat_map { |r| r[:models] }.uniq
+          }
+          active_sessions << merged
+        end
+
+        # Sort by total cost descending
+        active_sessions.sort_by! { |s| -s[:total_cost] }
+
+        # Apply limit
+        limit ? active_sessions.first(limit) : active_sessions
+      end
+
+      # Load session names from session manager (including trashed sessions)
+      # Returns a hash mapping session_id to session name
+      def load_session_names
+        names = {}
+        begin
+          # Load from active sessions
+          manager = Clacky::SessionManager.new
+          manager.all_sessions.each do |session|
+            id = session[:session_id]
+            name = session[:name]
+            names[id] = name if id && name && !name.to_s.empty?
+          end
+
+          # Also load from trashed sessions
+          trash_dir = File.join(Dir.home, ".clacky", "trash", "sessions-trash")
+          if Dir.exist?(trash_dir)
+            Dir.glob(File.join(trash_dir, "*.json")).each do |filepath|
+              session = JSON.parse(File.read(filepath), symbolize_names: true) rescue next
+              id = session[:session_id]
+              name = session[:name]
+              names[id] = name if id && name && !name.to_s.empty?
+            end
+          end
+        rescue => e
+          # Silently fail if session manager is not available
+        end
+        names
+      end
+
+      # Get daily cost breakdown for the last N days      # @param days [Integer] Number of days to include
       # @param model [String, nil] Filter by model name
       # @return [Array<Hash>] Daily summaries with date and cost
       def daily_breakdown(days: 30, model: nil)

data/lib/clacky/cli.rb

@@ -942,6 +942,111 @@ module Clacky
     end
 
     # ── billing command ────────────────────────────────────────────────────────
+    desc "patch_new ID TARGET", "Scaffold a runtime patch for a method (TARGET like Clacky::Tools::WebSearch#execute)"
+    long_desc <<-LONGDESC
+      Generate a method-override patch under ~/.clacky/patches/ID/. The current
+      method fingerprint is computed automatically and stored in meta.yml; you
+      only edit the method body in patch.rb. If a future gem version changes the
+      targeted method, the fingerprint will no longer match and the patch is
+      auto-disabled on next start (rather than applied and risking breakage).
+
+      Examples:
+        $ clacky patch_new fix-search Clacky::Tools::WebSearch#execute -d "bump timeout"
+    LONGDESC
+    option :desc, type: :string, aliases: "-d", default: "", desc: "Short description"
+    def patch_new(id, target)
+      require_relative "patch_loader"
+      path = Clacky::PatchLoader.scaffold(id, target, description: options[:desc])
+      puts "Created patch: #{path}"
+      puts "Edit patch.rb, then run: clacky patch_verify"
+    rescue ArgumentError, StandardError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "patch_verify", "Load ~/.clacky/patches/ and report applied / disabled / skipped"
+    def patch_verify
+      require "clacky"
+      result = Clacky::PatchLoader.last_result
+
+      if result.applied.empty? && result.disabled.empty? && result.skipped.empty?
+        puts "No patches found in ~/.clacky/patches/"
+        return
+      end
+
+      result.applied.each  { |id| puts "[OK]       #{id}" }
+      result.disabled.each { |(id, reason)| puts "[DISABLED] #{id} — #{reason}" }
+      result.skipped.each  { |(id, reason)| puts "[SKIP]     #{id} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
+    desc "patch_list", "List patches under ~/.clacky/patches/ and their status"
+    def patch_list
+      invoke :patch_verify, []
+    end
+
+    desc "hook_new", "Scaffold a starter ~/.clacky/hooks.yml with an example guard script"
+    def hook_new
+      require_relative "shell_hook_loader"
+      path = Clacky::ShellHookLoader.scaffold
+      puts "Created hooks config: #{path}"
+      puts "Edit it, then run: clacky hook_verify"
+    rescue ArgumentError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "hook_verify", "Load ~/.clacky/hooks.yml and report which hooks register"
+    def hook_verify
+      require_relative "agent/hook_manager"
+      require_relative "shell_hook_loader"
+      hm = Clacky::HookManager.new
+      result = Clacky::ShellHookLoader.load_into(hm)
+
+      if result.registered.empty? && result.skipped.empty?
+        puts "No hooks found in ~/.clacky/hooks.yml"
+        return
+      end
+
+      result.registered.each { |(event, name)| puts "[OK]   #{event} → #{name}" }
+      result.skipped.each { |(name, reason)| puts "[SKIP] #{name} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
+    desc "channel_new NAME", "Scaffold a custom channel adapter at ~/.clacky/channels/NAME/"
+    long_desc <<-LONGDESC
+      Generate a ready-to-edit channel adapter skeleton. The skeleton already
+      self-registers and implements the full adapter interface with TODO markers —
+      you only fill in the method bodies, then run `clacky channel_verify`.
+
+      Examples:
+        $ clacky channel_new slack
+    LONGDESC
+    def channel_new(name)
+      require_relative "server/channel"
+      path = Clacky::Channel::Adapters::UserAdapterLoader.scaffold(name)
+      puts "Created channel adapter: #{path}"
+      puts "Edit the TODO sections, then run: clacky channel_verify"
+    rescue ArgumentError => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
+    desc "channel_verify", "Load user channel adapters and report which are valid"
+    def channel_verify
+      require_relative "server/channel"
+      result = Clacky::Channel::Adapters::UserAdapterLoader.last_result
+
+      if result.loaded.empty? && result.skipped.empty?
+        puts "No custom channel adapters found in ~/.clacky/channels/"
+        return
+      end
+
+      result.loaded.each { |n| puts "[OK]   #{n}" }
+      result.skipped.each { |(n, reason)| puts "[SKIP] #{n} — #{reason}" }
+      exit 1 if result.skipped.any?
+    end
+
     desc "billing", "Show billing summary and usage statistics"
     long_desc <<-LONGDESC
       Display billing summary with token usage and cost breakdown.

data/lib/clacky/client.rb

@@ -258,7 +258,16 @@ module Clacky
         response.env.body = sse_buf if response.body.to_s.empty?
         raise_error(response)
       end
-      MessageFormat::Bedrock.parse_response(aggregator.to_h)
+
+      result = aggregator.to_h
+      # A complete Converse stream always emits stopReason in its messageStop
+      # frame. Its absence means the upstream cut the stream mid-response,
+      # leaving a half-written message; retry rather than accept the truncation.
+      if result["stopReason"].nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without stopReason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::Bedrock.parse_response(result)
     end
 
     def parse_simple_bedrock_response(response)
@@ -307,7 +316,16 @@ module Clacky
         recovered = Struct.new(:status, :body).new(response.status, recovered_body)
         raise_error(recovered)
       end
-      MessageFormat::Anthropic.parse_response(aggregator.to_h)
+
+      result = aggregator.to_h
+      # A complete Messages stream always emits stop_reason in its message_delta
+      # frame. Its absence means the upstream cut the stream mid-response,
+      # leaving a half-written message; retry rather than accept the truncation.
+      if result["stop_reason"].nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without stop_reason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::Anthropic.parse_response(result)
     end
 
     def parse_simple_anthropic_response(response)
@@ -360,7 +378,18 @@ module Clacky
         response.env.body = sse_buf if response.body.to_s.empty?
         raise_error(response)
       end
-      MessageFormat::OpenAI.parse_response(aggregator.to_h)
+
+      result = aggregator.to_h
+      # A complete chat-completion stream always terminates with a frame
+      # carrying finish_reason. Its absence means the upstream cut the stream
+      # mid-response (e.g. proxy idle-timeout, connection reset that Faraday
+      # didn't surface as an exception), leaving a half-written message. Treat
+      # as retryable so we don't hand a silently truncated answer to the agent.
+      if result.dig("choices", 0, "finish_reason").nil?
+        raise Clacky::UpstreamTruncatedError,
+          "[LLM] Streaming response ended without finish_reason (upstream cut the stream). Retrying..."
+      end
+      MessageFormat::OpenAI.parse_response(result)
     end
 
     def parse_simple_openai_response(response)

data/lib/clacky/default_skills/deploy/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: deploy
 description: Deploy Rails applications to Railway. Handles first-time setup and re-deploys idempotently using Railway CLI. Trigger on: "deploy", "deploy to railway", "railway deploy", "发布", "部署", "上线".
-user-invocable: true
+agent: coding
+disable-model-invocation: false
 ---
 
 # Deploy Rails App to Railway

data/lib/clacky/default_skills/extend-openclacky/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: extend-openclacky
+description: Customize, fix, override or extend openclacky itself — e.g. change a built-in tool's behavior, intercept/audit/block tool calls with shell scripts, or plug in a new IM channel (Slack, in-house IM, etc.). Trigger on phrases like "patch clacky", "patch openclacky", "change WebSearch behavior", "block dangerous commands", "audit tool use", "add Slack channel", "改 openclacky 内置", "改 clacky 内置", "monkey patch openclacky", "拦截工具调用". Do NOT trigger for ordinary feature work in the user's own project that doesn't touch openclacky.
+---
+
+# Extending Openclacky
+
+Openclacky ships three official extension mechanisms that survive `gem update` and never require editing the gem source.
+**Never tell the user to `bundle show openclacky` and edit the gem — always use one of these.**
+
+## Pick the right mechanism
+
+| User wants to… | Use | Scaffold | Verify |
+|---|---|---|---|
+| Change behavior of an **existing method** in openclacky (e.g. `WebSearch#execute` timeout, fix a bug in a built-in tool) | **Patch** | `clacky patch_new <id> "Const#method" -d "<desc>"` | `clacky patch_verify` |
+| **Audit / block / observe** tool calls (block `rm -rf /`, log every shell command) — no Ruby needed | **Shell Hook** | `clacky hook_new <id> -e <event>` | `clacky hook_verify` |
+| Plug openclacky into a **new IM platform** (Slack, in-house IM, custom webhook…) | **Channel Adapter** | `clacky channel_new <platform_id>` | `clacky channel_verify` |
+
+## Authoritative documentation
+
+Each mechanism has a full reference doc — read the relevant one with `web_fetch` before writing code:
+
+- Patches → https://www.openclacky.com/docs/extend-patches
+- Shell Hooks → https://www.openclacky.com/docs/extend-shell-hooks
+- Channel Adapters → https://www.openclacky.com/docs/extend-channel-adapter
+
+## Execution playbook
+
+1. **Identify** which mechanism fits (use the table above; ask if genuinely ambiguous).
+2. **Read the doc** for that mechanism with `web_fetch`. Don't guess fields, hook events, or required methods — the doc is the contract.
+3. **Run the scaffold** CLI command. It generates the file(s) in `~/.clacky/...` with correct meta.
+4. **Edit** the generated file to implement the user's intent. Keep generated meta fields (`target`, `event`, `platform_id`, the `Clacky::ChannelRegistry.register(...)` line, etc.) intact unless the doc says otherwise.
+5. **Verify** with the matching `*_verify` command. Surface any `[FAIL]` lines to the user verbatim.
+
+## When NOT to use this skill
+
+- The user is building features in their own application that just *use* openclacky — that's normal coding, no patch/hook/channel needed.
+- The user wants a brand-new tool/skill for *their* project — use `.clacky/skills/` or `.clacky/tools/`, not these gem-level mechanisms.
+- The change can be made via `clacky config set ...` — prefer config over patches.

data/lib/clacky/default_skills/mcp-manager/SKILL.md

@@ -5,13 +5,6 @@ description: |
   reconfigure. Edits ~/.clacky/mcp.json so the user never writes JSON by hand.
   Trigger on: add mcp, install mcp, setup mcp, configure mcp, mcp list, mcp remove,
   mcp probe, mcp reconfigure.
-argument-hint: "add | list | probe <name> | remove <name> | reconfigure <name>"
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - AskFollowupQuestion
 ---
 
 # MCP Manager Skill

data/lib/clacky/patch_loader.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "yaml"
+
+begin
+  require "prism"
+rescue LoadError
+  # Prism is a stdlib on Ruby 3.3+. On older Rubies we fall back to
+  # RubyVM::AbstractSyntaxTree (available since 2.6).
+end
+
+module Clacky
+  # Runtime patch layer. Loads user/AI-authored patches from ~/.clacky/patches/
+  # that override existing methods via Module#prepend, WITHOUT touching the
+  # installed gem source (so `gem update` never loses them).
+  #
+  # Each patch lives in its own directory:
+  #   ~/.clacky/patches/<id>/
+  #     meta.yml    declares target + a fingerprint of the original method source
+  #     patch.rb    a prepend module that overrides the target method
+  #
+  # Safety — fingerprint drift:
+  #   meta.yml records a SHA256 of the targeted method's source at authoring time.
+  #   Before applying, the loader recomputes the fingerprint of the method as it
+  #   exists in the CURRENTLY installed gem. If they differ, the upstream code has
+  #   changed and the patch may no longer be valid, so by default the patch is
+  #   DISABLED (moved to _disabled/) rather than applied — a stale patch must never
+  #   silently corrupt behavior.
+  #
+  # meta.yml:
+  #   id: fix-web-search-timeout
+  #   description: bump default timeout to 30s
+  #   target: "Clacky::Tools::WebSearch#execute"   # '#' = instance, '.' = class method
+  #   fingerprint: "a3f8c…"
+  #   gem_version: "0.7.0"
+  #   on_mismatch: disable                         # disable | warn (default disable)
+  module PatchLoader
+    DEFAULT_DIR  = File.expand_path("~/.clacky/patches")
+    DISABLED_DIR = "_disabled"
+
+    Result = Struct.new(:applied, :disabled, :skipped, keyword_init: true)
+
+    class << self
+      def load_all(dir: DEFAULT_DIR)
+        result = Result.new(applied: [], disabled: [], skipped: [])
+        if Dir.exist?(dir)
+          Dir.glob(File.join(dir, "*", "meta.yml")).sort.each do |meta_path|
+            patch_dir = File.dirname(meta_path)
+            next if File.basename(File.dirname(patch_dir)) == DISABLED_DIR
+
+            apply_one(patch_dir, meta_path, result)
+          end
+        end
+        @last_result = result
+        result
+      end
+
+      def last_result
+        @last_result || load_all
+      end
+
+      # Generate a ready-to-edit patch (meta.yml + patch.rb) for a target method.
+      # Computes the current fingerprint automatically so the author never does it
+      # by hand. The patch.rb skeleton prepends a module that overrides the method
+      # and calls super by default.
+      # @param target [String] "Const::Path#method" or "Const::Path.method"
+      # @return [String] path to the new patch directory
+      def scaffold(id, target, description: "", dir: DEFAULT_DIR)
+        slug = id.to_s.strip.downcase.gsub(/[^a-z0-9_-]+/, "-").gsub(/\A-+|-+\z/, "")
+        raise ArgumentError, "invalid patch id: #{id.inspect}" if slug.empty?
+
+        fp = fingerprint(target)  # also validates the target resolves
+
+        patch_dir = File.join(dir, slug)
+        raise ArgumentError, "patch already exists: #{patch_dir}" if Dir.exist?(patch_dir)
+
+        FileUtils.mkdir_p(patch_dir)
+        File.write(File.join(patch_dir, "meta.yml"), <<~YAML)
+          id: #{slug}
+          description: #{description.to_s.empty? ? "(describe what this fixes)" : description}
+          target: "#{target}"
+          fingerprint: "#{fp}"
+          gem_version: "#{Clacky::VERSION}"
+          on_mismatch: disable
+        YAML
+        File.write(File.join(patch_dir, "patch.rb"), patch_skeleton(slug, target))
+        patch_dir
+      end
+
+      def patch_skeleton(slug, target)
+        const_name, sep, method_name = target.partition(/[#.]/)
+        mod_const = "Patch_#{slug.gsub(/[^a-zA-Z0-9_]/, "_")}"
+        prepend_target = sep == "#" ? const_name : "#{const_name}.singleton_class"
+
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Patch for #{target}
+          # Only edit the method body below. Call `super` to keep the original behavior.
+          module #{mod_const}
+            def #{method_name}(*args, **kwargs, &blk)
+              # TODO: your fix here. Examples:
+              #   result = super
+              #   result
+              super
+            end
+          end
+
+          #{prepend_target}.prepend(#{mod_const})
+        RUBY
+      end
+
+      # Recompute the fingerprint of a target's method as currently installed.
+      # @param target [String] "Const::Path#instance_method" or "Const::Path.class_method"
+      # @return [String] SHA256 hex of the method's source
+      # @raise [RuntimeError] if the target can't be resolved
+      def fingerprint(target)
+        meth = original_method(resolve_method(target))
+        file, lineno = meth.source_location
+        raise "no source location for #{target} (defined in C or eval?)" unless file && lineno
+
+        first, last = method_line_range(file, lineno, meth.name, meth)
+        raise "cannot locate source for #{target} in #{file}:#{lineno}" unless first && last
+
+        lines = File.readlines(file)[(first - 1)...last]
+        Digest::SHA256.hexdigest(lines.join)
+      end
+
+      def method_line_range(file, lineno, name, meth)
+        if defined?(Prism)
+          range = prism_line_range(file, lineno, name)
+          return range if range
+        end
+
+        ast_line_range(meth)
+      end
+
+      def prism_line_range(file, lineno, name)
+        result = Prism.parse_file(file)
+        return nil unless result.success?
+
+        node = find_def_at(result.value, lineno, name.to_sym)
+        return nil unless node
+
+        loc = node.location
+        [loc.start_line, loc.end_line]
+      end
+
+      def find_def_at(node, lineno, name)
+        return nil unless node
+
+        if node.is_a?(Prism::DefNode) && node.name == name && node.location.start_line == lineno
+          return node
+        end
+
+        node.compact_child_nodes.each do |child|
+          found = find_def_at(child, lineno, name)
+          return found if found
+        end
+        nil
+      end
+
+      def ast_line_range(meth)
+        return nil unless defined?(RubyVM::AbstractSyntaxTree)
+
+        node = RubyVM::AbstractSyntaxTree.of(meth)
+        return nil unless node
+
+        [node.first_lineno, node.last_lineno]
+      rescue StandardError
+        nil
+      end
+
+      # Walk past any methods introduced by our own patches (files under the
+      # patches dir) so the fingerprint always reflects the original upstream
+      # definition, even after a prepend has already been applied.
+      def original_method(meth)
+        current = meth
+        while current
+          file, = current.source_location
+          break if file.nil? || !file.start_with?(DEFAULT_DIR)
+
+          nxt = current.super_method
+          break if nxt.nil?
+
+          current = nxt
+        end
+        current
+      end
+
+      def resolve_method(target)
+        if target.include?("#")
+          const_name, method_name = target.split("#", 2)
+          const = resolve_const(const_name)
+          const.instance_method(method_name.to_sym)
+        elsif target.include?(".")
+          const_name, method_name = target.split(".", 2)
+          const = resolve_const(const_name)
+          const.method(method_name.to_sym)
+        else
+          raise "invalid target (need '#' or '.'): #{target}"
+        end
+      end
+
+      def apply_one(patch_dir, meta_path, result)
+        id = File.basename(patch_dir)
+        meta = YAMLCompat.load_file(meta_path) || {}
+        target = meta["target"].to_s
+        recorded = meta["fingerprint"].to_s
+
+        if target.empty? || recorded.empty?
+          result.skipped << [id, "meta.yml missing target or fingerprint"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        current = begin
+          fingerprint(target)
+        rescue StandardError => e
+          result.skipped << [id, "cannot fingerprint #{target}: #{e.message}"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        if current != recorded
+          handle_mismatch(patch_dir, id, meta, result)
+          return
+        end
+
+        patch_rb = File.join(patch_dir, "patch.rb")
+        unless File.exist?(patch_rb)
+          result.skipped << [id, "patch.rb not found"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        require patch_rb
+        result.applied << id
+        log(:info, id, "applied → #{target}")
+      rescue StandardError, ScriptError => e
+        result.skipped << [id, e.message]
+        log(:warn, id, e.message)
+      end
+
+      def handle_mismatch(patch_dir, id, meta, result)
+        reason = "fingerprint mismatch — upstream code for #{meta["target"]} changed"
+        if meta["on_mismatch"].to_s == "warn"
+          result.skipped << [id, "#{reason} (kept, not applied)"]
+          log(:warn, id, result.skipped.last[1])
+          return
+        end
+
+        disable!(patch_dir, id)
+        result.disabled << [id, reason]
+        log(:warn, id, "#{reason} — disabled")
+      end
+
+      def disable!(patch_dir, id)
+        base = File.dirname(patch_dir)
+        dest_root = File.join(base, DISABLED_DIR)
+        FileUtils.mkdir_p(dest_root)
+        dest = File.join(dest_root, id)
+        FileUtils.rm_rf(dest)
+        FileUtils.mv(patch_dir, dest)
+      rescue StandardError => e
+        log(:error, id, "failed to disable: #{e.message}")
+      end
+
+      def resolve_const(name)
+        name.split("::").reject(&:empty?).inject(Object) do |mod, part|
+          mod.const_get(part)
+        end
+      end
+
+      def log(level, id, msg)
+        Clacky::Logger.public_send(level, "[PatchLoader] #{id}: #{msg}")
+      end
+    end
+  end
+end