pwn 0.5.627 → 0.5.628

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e41f7773a146dc00b0f3eb205ef5f0bd4ed7cc894e2a7b0448aa398fc3e23c0
-  data.tar.gz: 22e69de2b918558f4702adf91b68615eabe0ddc0d5676b4fe2beb1602c935f13
+  metadata.gz: 44fdb9e4897d83ad9ab54d65bc774eed6be14c379eea42b1a7984abab23c03bd
+  data.tar.gz: ba801dabf738c43b3fe7ce9cf40bdfb38d1cf62f7a0b98b05861626c33d2d008
 SHA512:
-  metadata.gz: 271dc24b5a41f4d16ac1a1a1f9c9d4ac6b0cfe2aa3358eb8d7e16058a9036f9e8d73c4528e8a17a8e9c6d31dc263c8a8de56047816f88caad35ba128874e8258
-  data.tar.gz: 5cacca96d75ff106f28b5d344b98bb91eb01887332598e28106379fccfafbaf2547ce7f27d983ac8d16ad71964480e2c0fce73ffd152ef3f46af771d8306672b
+  metadata.gz: 205805e3088246b711249ba3b778e9418fb1616ad576dde6c22c0c632409de88b2545fda88ee30316fe7a203a2ff9a46236136e94ba291a7dc27c800d7b8c02c
+  data.tar.gz: 4e439c01661f7707c9bf79e8e4be656e76f9d57d5bb17cf9778536bd1a8ebbc63aebd4effbcce38d4ed89f4cfdbe188072ab710a7374d0a951fd8a0c7bd7d0fd

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-06-05 17:51:34 UTC using RuboCop version 1.86.1.
+# on 2026-07-10 16:56:14 UTC using RuboCop version 1.88.2.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -13,7 +13,7 @@ Layout/TrailingWhitespace:
   Exclude:
     - 'lib/pwn/banner/radare2_ai.rb'
 
-# Offense count: 11
+# Offense count: 14
 # Configuration parameters: AllowedMethods, AllowedPatterns.
 Lint/NestedMethodDefinition:
   Exclude:
@@ -30,17 +30,16 @@ Lint/RedundantTypeConversion:
     - 'lib/pwn/plugins/jenkins.rb'
     - 'lib/pwn/plugins/repl.rb'
 
-# Offense count: 4
-Lint/ShadowedException:
-  Exclude:
-    - 'lib/pwn/sdr/decoder/flex.rb'
-    - 'lib/pwn/sdr/decoder/pocsag.rb'
-
-# Offense count: 302
+# Offense count: 296
 # This cop supports safe autocorrection (--autocorrect).
 Lint/UselessAssignment:
   Enabled: false
 
+# Offense count: 2
+Lint/UselessConstantScoping:
+  Exclude:
+    - 'lib/pwn/sdr/decoder/bluetooth.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: CheckForMethodsWithNoSideEffects.
@@ -49,7 +48,7 @@ Lint/Void:
     - 'bin/pwn_web_cache_deception'
 
 # Offense count: 1
-# Configuration parameters: LengthThreshold.
+# Configuration parameters: Max.
 Metrics/CollectionLiteralLength:
   Exclude:
     - 'lib/pwn/plugins/uri_scheme.rb'
@@ -66,7 +65,7 @@ Metrics/MethodLength:
   Exclude:
     - 'lib/pwn/banner/code_cave.rb'
 
-# Offense count: 8
+# Offense count: 9
 Naming/AccessorMethodName:
   Exclude:
     - 'lib/pwn/ai/anthropic.rb'
@@ -78,6 +77,13 @@ Naming/AccessorMethodName:
     - 'lib/pwn/plugins/jira_data_center.rb'
     - 'lib/pwn/plugins/vin.rb'
 
+# Offense count: 5
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/pwn/sdr/decoder/lora.rb'
+
 # Offense count: 2
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
@@ -98,7 +104,7 @@ Style/Alias:
 Style/ClassVars:
   Enabled: false
 
-# Offense count: 273
+# Offense count: 277
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, SingleLineConditionsOnly, IncludeTernaryExpressions.
 # SupportedStyles: assign_to_condition, assign_inside_condition
@@ -150,13 +156,11 @@ Style/MultipleComparison:
     - 'lib/pwn/www/duckduckgo.rb'
     - 'lib/pwn/www/twitter.rb'
 
-# Offense count: 5
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantBegin:
   Exclude:
     - 'lib/pwn/plugins/transparent_browser.rb'
-    - 'lib/pwn/sdr/decoder/flex.rb'
-    - 'lib/pwn/sdr/decoder/pocsag.rb'
 
 # Offense count: 94
 # This cop supports safe autocorrection (--autocorrect).
@@ -172,13 +176,6 @@ Style/RedundantParentheses:
   Exclude:
     - 'lib/pwn/plugins/xxd.rb'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Style/RedundantSelf:
-  Exclude:
-    - 'lib/pwn/sdr/decoder/flex.rb'
-    - 'lib/pwn/sdr/decoder/pocsag.rb'
-
 # Offense count: 12
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantStringEscape:
@@ -189,14 +186,7 @@ Style/RedundantStringEscape:
     - 'lib/pwn/sast/redos.rb'
     - 'vagrant/provisioners/kali_customize.rb'
 
-# Offense count: 6
-# This cop supports safe autocorrection (--autocorrect).
-Style/RescueModifier:
-  Exclude:
-    - 'lib/pwn/sdr/decoder/flex.rb'
-    - 'lib/pwn/sdr/decoder/pocsag.rb'
-
-# Offense count: 19
+# Offense count: 17
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/SlicingWithRange:
   Exclude:

data/Gemfile

@@ -20,7 +20,7 @@ gem 'base32', '0.3.4'
 gem 'bitcoin-ruby', '0.0.20'
 gem 'brakeman', '8.0.5'
 gem 'bson', '5.2.0'
-gem 'bundler', '>=4.0.15'
+gem 'bundler', '>=4.0.16'
 gem 'bundler-audit', '>=0.9.3'
 gem 'bunny', '3.1.0'
 gem 'colorize', '1.1.0'

data/README.md

@@ -112,7 +112,7 @@ $ cd /opt/pwn
 $ ./install.sh
 $ ./install.sh ruby-gem
 $ pwn
-pwn[v0.5.627]:001 >>> PWN.help
+pwn[v0.5.628]:001 >>> PWN.help
 ```
 
 [![Installing the pwn Security Automation Framework](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/pwn_install.png)](https://youtu.be/G7iLUY4FzsI)
@@ -136,7 +136,7 @@ $ rvm use ruby-4.0.5@pwn
 $ gem uninstall --all --executables pwn
 $ gem install --verbose pwn
 $ pwn
-pwn[v0.5.627]:001 >>> PWN.help
+pwn[v0.5.628]:001 >>> PWN.help
 ```
 
 If using a multi-user RVM install:

data/lib/pwn/ai/agent/dispatch.rb

@@ -8,6 +8,22 @@ module PWN
       # Tool-call dispatch: takes a single tool_call object (OpenAI shape),
       # looks up the registered handler, parses args, runs it, and returns a
       # JSON string suitable for a role:'tool' message.
+      #
+      # TOLERANT DISPATCH (local-model scaffolding)
+      # -------------------------------------------
+      # Local models (qwen/llama/mistral on Ollama) frequently emit almost-
+      # right tool calls: `run_shell` instead of `shell`, trailing commas,
+      # single-quoted JSON, arguments as a bare string. Strict parsing burns
+      # an iteration and often spirals. Dispatch now:
+      #   * repair_name  — Levenshtein-matches unknown names to the closest
+      #                    registered tool and records a Mistakes fingerprint
+      #                    (source: :repair) so the KNOWN MISTAKES block
+      #                    eventually teaches the model the right name.
+      #   * parse_args   — falls back to a JSON5-ish clean-up pass (strip
+      #                    trailing commas, swap single→double quotes, wrap a
+      #                    bare scalar as the tool's sole required arg).
+      # Frontier engines never hit these paths — repair is a no-op when the
+      # name/JSON are already valid.
       module Dispatch
         # Supported Method Parameters::
         # json_str = PWN::AI::Agent::Dispatch.call(
@@ -22,10 +38,10 @@ module PWN
           name = (fn[:name] || fn['name']).to_s
           raw  = fn[:arguments] || fn['arguments'] || '{}'
 
-          entry = Registry.lookup(name: name)
+          entry = Registry.lookup(name: name) || Registry.lookup(name: repair_name(name: name))
           return JSON.generate(error: "unknown tool: #{name}") unless entry
 
-          args = parse_args(raw: raw)
+          args = parse_args(raw: raw, entry: entry)
           result = entry.handler.call(args)
           JSON.generate(success: true, result: result)
         rescue StandardError => e
@@ -36,15 +52,69 @@ module PWN
           )
         end
 
+        # Supported Method Parameters::
+        # fixed = PWN::AI::Agent::Dispatch.repair_name(
+        #   name: 'required - possibly-wrong tool name emitted by the model'
+        # )
+        #
+        # Returns the closest registered tool name by Levenshtein distance
+        # (max distance = 1/3 of the emitted name, min 3) or nil when nothing
+        # is close enough. Every successful repair is fingerprinted into
+        # Mistakes so the negative-feedback loop trains the model's output
+        # format via its own system prompt.
+
+        public_class_method def self.repair_name(opts = {})
+          name = opts[:name].to_s
+          return nil if name.empty?
+
+          pool = Registry.all.map(&:name)
+          return nil if pool.empty?
+
+          best, dist = pool.map { |n| [n, DidYouMean::Levenshtein.distance(n, name)] }
+                           .min_by(&:last)
+          thresh = [(name.length / 3.0).ceil, 3].max
+          return nil if dist > thresh
+
+          if defined?(Mistakes)
+            Mistakes.record(
+              tool: 'tool_name',
+              error: "model emitted '#{name}', repaired to '#{best}'",
+              args: name,
+              source: :repair
+            )
+          end
+          best
+        rescue StandardError
+          nil
+        end
+
         private_class_method def self.parse_args(opts = {})
-          raw = opts[:raw]
+          raw   = opts[:raw]
+          entry = opts[:entry]
           case raw
           when Hash   then symbolize(hash: raw)
-          when String then raw.strip.empty? ? {} : JSON.parse(raw, symbolize_names: true)
+          when String then parse_string_args(raw: raw, entry: entry)
           when nil    then {}
           else symbolize(hash: raw.to_h)
           end
+        end
+
+        private_class_method def self.parse_string_args(opts = {})
+          raw   = opts[:raw].to_s
+          entry = opts[:entry]
+          return {} if raw.strip.empty?
+
+          JSON.parse(raw, symbolize_names: true)
         rescue JSON::ParserError => e
+          # Tolerant retry: strip trailing commas, normalise single quotes,
+          # coerce a bare scalar into the tool's sole required parameter.
+          cleaned = raw.gsub(/,(\s*[}\]])/, '\1').tr("'", '"')
+          begin
+            return JSON.parse(cleaned, symbolize_names: true)
+          rescue JSON::ParserError
+            req = Array(entry&.schema&.dig(:parameters, :required))
+            return { req.first.to_sym => raw.strip.gsub(/\A["']|["']\z/, '') } if req.length == 1 && !raw.strip.start_with?('{', '[')
+          end
           raise ArgumentError, "invalid JSON arguments: #{e.message}"
         end
 
@@ -72,6 +142,8 @@ module PWN
                 }
               )
 
+              PWN::AI::Agent::Dispatch.repair_name(name: 'run_shell')  # => 'shell'
+
               #{self}.authors
           USAGE
         end

data/lib/pwn/ai/agent/learning.rb

@@ -23,8 +23,10 @@ module PWN
       # Everything is file-backed under ~/.pwn so it survives across REPL
       # restarts and is shared by every future session.
       module Learning
-        LEARNING_FILE = File.join(Dir.home, '.pwn', 'learning.jsonl')
+        LEARNING_FILE      = File.join(Dir.home, '.pwn', 'learning.jsonl')
+        FINETUNE_DIR       = File.join(Dir.home, '.pwn', 'finetune')
         MAX_MEMORY_ENTRIES = 200
+        CLAIM_RX           = /CVE-\d{4}-\d{4,7}|\b[A-Za-z][\w.+-]{2,}\s+v?\d+\.\d+(?:\.\d+)?\b/
 
         # Supported Method Parameters::
         # entry = PWN::AI::Agent::Learning.note_outcome(
@@ -127,6 +129,82 @@ module PWN
           "#{out}\n"
         end
 
+        # Supported Method Parameters::
+        # msgs = PWN::AI::Agent::Learning.exemplars_for(
+        #   request: 'required - current user request',
+        #   limit: 'optional - max exemplar traces to return (default 1)',
+        #   max_msgs: 'optional - cap on messages per exemplar (default 6)'
+        # )
+        #
+        # Retrieval-augmented BEHAVIOUR: keyword-matches request against
+        # prior successful outcomes in learning.jsonl, loads the matching
+        # session, and compresses its (user, tool, assistant) trace into a
+        # short few-shot exemplar Loop.run splices between system and user.
+        # Local models are dramatically better with 1 concrete example than
+        # with 25 abstract lessons.
+
+        public_class_method def self.exemplars_for(opts = {})
+          request  = opts[:request].to_s.downcase
+          limit    = (opts[:limit]    || 1).to_i
+          max_msgs = (opts[:max_msgs] || 6).to_i
+          return [] if request.strip.empty?
+
+          tokens = request.scan(/[a-z0-9_]{3,}/).uniq
+          return [] if tokens.empty?
+
+          hits = outcomes(limit: 500, success: true)
+                 .reject { |r| r[:session_id].to_s.empty? }
+                 .map    { |r| [r, tokens.count { |t| r[:task].to_s.downcase.include?(t) }] }
+                 .reject { |_, s| s.zero? }
+                 .sort_by { |_, s| -s }
+                 .first(limit)
+                 .map(&:first)
+
+          hits.flat_map { |r| compress_exemplar(session_id: r[:session_id], max_msgs: max_msgs) }
+        rescue StandardError
+          []
+        end
+
+        # Supported Method Parameters::
+        # info = PWN::AI::Agent::Learning.export_finetune(
+        #   format: 'optional - :sharegpt (default) | :openai_jsonl',
+        #   out: 'optional - output path (default ~/.pwn/finetune/pwn-YYYYMMDD.jsonl)',
+        #   min_tools: 'optional - only sessions with >= N tool messages (default 1)'
+        # )
+        #
+        # Turns the learning corpus into a supervised dataset: every session
+        # whose learning.jsonl outcome is success:true becomes one training
+        # sample (system, user, assistant/tool_calls, tool, ..., final). Pair
+        # with a weekly PWN::Cron job that runs `ollama create qwen-pwn -f
+        # Modelfile` over the export - the only path to ACTUAL parity with a
+        # frontier model, because it changes the weights not just the scaffold.
+
+        public_class_method def self.export_finetune(opts = {})
+          fmt       = (opts[:format] || :sharegpt).to_sym
+          min_tools = (opts[:min_tools] || 1).to_i
+          FileUtils.mkdir_p(FINETUNE_DIR)
+          out = opts[:out] || File.join(FINETUNE_DIR, "pwn-#{Time.now.utc.strftime('%Y%m%d')}.jsonl")
+
+          sids = outcomes(limit: 10_000, success: true).map { |r| r[:session_id] }.compact.uniq
+          rows = 0
+          File.open(out, 'w') do |f|
+            sids.each do |sid|
+              t = PWN::Sessions.load(session_id: sid)
+              next if t.count { |e| e[:role].to_s == 'tool' } < min_tools
+
+              conv = t.map { |e| { role: e[:role].to_s, content: e[:content].to_s } }
+                      .reject { |e| e[:role] == 'system' && e[:content].start_with?('Session started') }
+              line = case fmt
+                     when :openai_jsonl then { messages: conv }
+                     else { conversations: conv.map { |m| { from: sharegpt_role(role: m[:role]), value: m[:content] } } }
+                     end
+              f.puts(JSON.generate(line))
+              rows += 1
+            end
+          end
+          { path: out, format: fmt, sessions: sids.length, samples: rows, bytes: File.size(out) }
+        end
+
         # Supported Method Parameters::
         # skill = PWN::AI::Agent::Learning.distill_skill(
         #   name: 'required - snake_case name for the new skill',
@@ -216,6 +294,7 @@ module PWN
             tags: %w[auto loop]
           )
           reflect(session_id: session_id)
+          fact_check_local_final(final: opts[:final])
           Extrospection.auto_extrospect(session_id: session_id) if defined?(Extrospection)
         rescue StandardError => e
           warn "[pwn-ai/learning] auto_introspect swallowed: #{e.class}: #{e.message}"
@@ -382,6 +461,48 @@ module PWN
           lessons.uniq.first(5)
         end
 
+        # Auto fact-check post-filter: local models hallucinate CVEs /
+        # versions ~5-10x more than frontier ones. When the active engine is
+        # :ollama, scan the final for CVE / version-shaped claims and hand
+        # each to Extrospection.verify - refuted claims become
+        # Mistakes(tool:'assumption') so KNOWN MISTAKES warns every future
+        # run off that specific hallucination.
+        private_class_method def self.fact_check_local_final(opts = {})
+          return unless defined?(PWN::Env) && PWN::Env.dig(:ai, :active).to_s.downcase.to_sym == :ollama
+          return unless defined?(Extrospection) && Extrospection.respond_to?(:verify)
+
+          claims = opts[:final].to_s.scan(CLAIM_RX).flatten.compact.uniq.first(3)
+          claims.each { |c| Extrospection.verify(claim: c, commit: true) }
+        rescue StandardError => e
+          warn "[pwn-ai/learning] fact_check swallowed: #{e.class}: #{e.message}"
+        end
+
+        private_class_method def self.compress_exemplar(opts = {})
+          sid = opts[:session_id]
+          cap = opts[:max_msgs] || 6
+          t = PWN::Sessions.load(session_id: sid)
+          user = t.find  { |e| e[:role].to_s == 'user' }
+          fin  = t.rfind { |e| e[:role].to_s == 'assistant' }
+          return [] unless user && fin
+
+          tools = t.select { |e| e[:role].to_s == 'tool' }.first([cap - 2, 0].max)
+          msgs  = [{ role: 'user', content: "[exemplar] #{user[:content].to_s[0, 400]}" }]
+          tools.each { |e| msgs << { role: 'assistant', content: "[exemplar tool] #{e[:content].to_s[0, 300]}" } }
+          msgs << { role: 'assistant', content: "[exemplar final] #{fin[:content].to_s[0, 400]}" }
+          msgs
+        rescue StandardError
+          []
+        end
+
+        private_class_method def self.sharegpt_role(opts = {})
+          case opts[:role].to_s
+          when 'user'      then 'human'
+          when 'assistant' then 'gpt'
+          when 'tool'      then 'observation'
+          else 'system'
+          end
+        end
+
         private_class_method def self.build_skill_from_session(opts = {})
           session_id = opts[:session_id]
           name       = opts[:name]
@@ -422,6 +543,8 @@ module PWN
               PWN::AI::Agent::Learning.reflect(session_id: sid)              # LLM or heuristic → PWN::Memory
               PWN::AI::Agent::Learning.auto_introspect(session_id: sid, request: req, final: text)
               PWN::AI::Agent::Learning.distill_skill(name: 'quick_recon', session_id: sid)
+              PWN::AI::Agent::Learning.exemplars_for(request: 'nmap sweep 10/8')  # few-shot for Loop.run
+              PWN::AI::Agent::Learning.export_finetune(format: :sharegpt)        # -> ~/.pwn/finetune/*.jsonl
               PWN::AI::Agent::Learning.consolidate(max_entries: 200)         # dedupe + prune Memory
               PWN::AI::Agent::Learning.to_context(limit: 5)                  # injected by PromptBuilder
               PWN::AI::Agent::Learning.stats

data/lib/pwn/ai/agent/loop.rb

@@ -32,8 +32,25 @@ module PWN
       #      have to fail 3× again to re-learn what it already knew.
       # PromptBuilder.mistakes_block re-injects the top open mistakes and
       # top known fixes into the system prompt of every future turn.
+      #
+      # LOCAL-MODEL SCAFFOLDING
+      # -----------------------
+      # When the active engine is :ollama (or the corresponding :agent flags
+      # are set) Loop.run additionally:
+      #   * threads request → PromptBuilder for relevance-ranked MEMORY,
+      #   * threads request → Registry.definitions(relevance:) for a slimmed
+      #     tool set (:tool_router),
+      #   * splices Learning.exemplars_for(request:) between system and user
+      #     as few-shot behaviour retrieval,
+      #   * runs a plan-then-act pre-pass (:plan_first) so the model
+      #     externalises a tool plan before its first dispatch,
+      #   * escalates to a frontier persona for a 3-line corrective hint
+      #     once ≥ ESCALATE_AFTER_FAILS in-turn failures accumulate
+      #     (:escalation_persona) — the local model still produces the final
+      #     answer so Learning/Metrics stay attributed to :ollama.
       module Loop
-        DEFAULT_MAX_ITERS = 777
+        DEFAULT_MAX_ITERS    = 777
+        ESCALATE_AFTER_FAILS = 4
 
         ENGINE_MODS = {
           openai: 'PWN::AI::OpenAI',
@@ -67,6 +84,21 @@ module PWN
           DEFAULT_MAX_ITERS
         end
 
+        private_class_method def self.active_engine
+          e = (PWN::Env.dig(:ai, :active) if defined?(PWN::Env)).to_s.downcase.to_sym
+          e == :'' ? :openai : e
+        rescue StandardError
+          :openai
+        end
+
+        private_class_method def self.agent_flag(opts = {})
+          key = opts[:key]
+          v = (PWN::Env.dig(:ai, :agent, key) if defined?(PWN::Env))
+          v.nil? ? opts[:default] : v
+        rescue StandardError
+          opts[:default]
+        end
+
         # Record per-tool telemetry AND, when the dispatch failed, fingerprint
         # the failure into PWN::AI::Agent::Mistakes so recurring errors are
         # counted, surfaced in the system prompt, and can be resolved with an
@@ -81,7 +113,7 @@ module PWN
           err     = raw[/"error":"([^"]{1,300})"/, 1]
           err   ||= raw[/"stderr":"([^"]{4,300})"/, 1] unless ok
           dur     = started ? (Time.now - started) : 0.0
-          Metrics.record(name: name, success: ok, duration: dur, error: err) if defined?(Metrics)
+          Metrics.record(name: name, success: ok, duration: dur, error: err, engine: opts[:engine]) if defined?(Metrics)
           m = nil
           m = Mistakes.record(tool: name, error: err || raw[0, 300], args: opts[:args], session_id: opts[:session_id], source: :tool) if !ok && defined?(Mistakes)
           { ok: ok, err: err, mistake: m }
@@ -136,6 +168,50 @@ module PWN
           "#{guard}\n#{result}"
         end
 
+        # Plan-then-act pre-pass: force the (usually local) model to
+        # externalise a numbered tool plan BEFORE it may call any tool. The
+        # plan rides along as an assistant message so every subsequent
+        # iteration attends over it — cheap chain-of-thought scaffolding
+        # without leaking to the user.
+        private_class_method def self.plan_first(opts = {})
+          messages = opts[:messages]
+          plan_msg = call_engine(
+            messages: messages + [{ role: 'user',
+                                    content: 'Before acting, list the exact tool calls (name + key args) you will make, in order. Reply ONLY with the numbered plan — do NOT call any tool yet.' }],
+            tools: nil
+          )
+          return unless plan_msg && !plan_msg[:content].to_s.strip.empty?
+
+          messages << { role: 'assistant', content: "PLAN:\n#{plan_msg[:content].to_s.strip}" }
+        rescue StandardError => e
+          warn "[pwn-ai/loop] plan_first swallowed: #{e.class}: #{e.message}"
+        end
+
+        # Swarm escalation circuit-breaker: when a local model has burned
+        # ≥ ESCALATE_AFTER_FAILS distinct failures this turn, ask a frontier
+        # persona for a 3-line corrective hint and inject it as a synthetic
+        # tool result. Every escalation is recorded as a Mistake so
+        # export_finetune can later teach the LoRA to NOT need it.
+        private_class_method def self.escalate(opts = {})
+          request    = opts[:request]
+          turn_fails = opts[:turn_fails]
+          persona    = agent_flag(key: :escalation_persona)
+          return nil unless persona && defined?(Swarm) && Swarm.personas.key?(persona.to_sym)
+
+          summary = turn_fails.map { |k, v| "#{k}: #{v}×" }.join(', ')
+          hint = Swarm.ask(
+            name: persona.to_s,
+            request: "Local agent is stuck on: #{request}\nFailed attempts: #{summary}\n" \
+                     'Give a 3-line corrective hint (which tool, which args, why). Reply with the hint ONLY.'
+          )
+          reply = hint.is_a?(Hash) ? hint[:reply].to_s : hint.to_s
+          Mistakes.record(tool: 'escalation', error: "local stuck after #{turn_fails.values.sum} fails; frontier hint requested", session_id: opts[:session_id], source: :loop) if defined?(Mistakes)
+          reply.strip.empty? ? nil : "[pwn-ai/escalation] frontier hint (#{persona}):\n#{reply.strip}"
+        rescue StandardError => e
+          warn "[pwn-ai/loop] escalate swallowed: #{e.class}: #{e.message}"
+          nil
+        end
+
         # Supported Method Parameters::
         # msg = PWN::AI::Agent::Loop.normalize_llm(
         #   response: 'required - chat_with_tools response Hash from any provider'
@@ -184,9 +260,7 @@ module PWN
           messages = opts[:messages]
           tools = opts[:tools]
 
-          engine = (PWN::Env.dig(:ai, :active) if defined?(PWN::Env)).to_s.downcase.to_sym
-          engine = :openai if engine == :''
-
+          engine = active_engine
           mod_name = ENGINE_MODS[engine]
           raise "ERROR: Unsupported AI engine for agent loop: #{engine}" unless mod_name
 
@@ -216,20 +290,24 @@ module PWN
           request = opts[:request].to_s
           session_id = opts[:session_id]
           on_tool = opts[:on_tool]
-          system_role_content = opts[:system_role_content] ||= PWN::AI::Agent::PromptBuilder.build(session_id: session_id)
+          engine = active_engine
+          local  = engine == :ollama
+          system_role_content = opts[:system_role_content] ||= PWN::AI::Agent::PromptBuilder.build(session_id: session_id, request: request)
 
           Registry.discover
           expose_current_session(session_id: session_id)
           Mistakes.check_user_correction(request: request, session_id: session_id) if defined?(Mistakes)
 
-          tools    = Registry.definitions(enabled: opts[:enabled_toolsets])
-          messages = [
-            { role: 'system', content: system_role_content },
-            { role: 'user',   content: request }
-          ]
+          tools    = Registry.definitions(enabled: opts[:enabled_toolsets], relevance: request)
+          messages = [{ role: 'system', content: system_role_content }]
+          messages.concat(Learning.exemplars_for(request: request)) if local && defined?(Learning) && Learning.respond_to?(:exemplars_for)
+          messages << { role: 'user', content: request }
           append_session(session_id: session_id, role: 'user', content: request)
 
+          plan_first(messages: messages) if agent_flag(key: :plan_first, default: local) && !Array(tools).empty?
+
           turn_fails = Hash.new(0)
+          escalated  = false
 
           max_iters.times do |i|
             msg = call_engine(messages: messages, tools: tools)
@@ -251,7 +329,7 @@ module PWN
               entry   = Registry.lookup(name: name)
               started = Time.now
               raw     = Dispatch.call(tool_call: tc)
-              tele    = record_metrics(name: name, started: started, raw: raw, args: args, session_id: session_id)
+              tele    = record_metrics(name: name, started: started, raw: raw, args: args, session_id: session_id, engine: engine)
               result  = Result.condition(content: raw, entry: entry)
 
               unless tele[:ok]
@@ -281,6 +359,15 @@ module PWN
                 content: "#{name} → #{result[0, 1_024]}"
               )
             end
+
+            next unless local && !escalated && turn_fails.values.sum >= ESCALATE_AFTER_FAILS
+
+            hint = escalate(request: request, turn_fails: turn_fails, session_id: session_id)
+            if hint
+              messages << { role: 'tool', tool_call_id: "escalation_#{i}", name: 'frontier_hint', content: hint }
+              append_session(session_id: session_id, role: 'tool', content: "frontier_hint → #{hint[0, 1_024]}")
+            end
+            escalated = true
           end
 
           Mistakes.record(tool: 'agent_loop', error: 'iteration budget exhausted without a final answer', session_id: session_id, source: :loop) if defined?(Mistakes)
@@ -309,6 +396,11 @@ module PWN
               Supported engines: #{ENGINE_MODS.keys.join(', ')}
               Set PWN::Env[:ai][:active] to choose; PWN::Env[:ai][:agent][:max_iters] to bound.
 
+              Local-model scaffolding (PWN::Env[:ai][:agent]):
+                :plan_first          - Boolean, plan-then-act pre-pass (default: engine == :ollama)
+                :tool_router         - Boolean, slim Registry.definitions to CORE + top-K relevant
+                :escalation_persona  - Swarm persona name for frontier corrective hints when stuck
+
               #{self}.authors
           USAGE
         end