pwn 0.5.677 → 0.5.680

data/documentation/diagrams/pwn-ai-feedback-learning-loop.svg

@@ -249,10 +249,10 @@
 <!-- Dispatch&#45;&gt;Curric -->
 <g id="edge67" class="edge">
 <title>Dispatch&#45;&gt;Curric</title>
-<path fill="none" stroke="#fb7185" stroke-width="1.3" stroke-dasharray="5,2" d="M982.7,-511.69C962.61,-506.86 940.53,-502.04 920,-498.62 887.88,-493.28 650.15,-494.73 628.25,-470.62 621.97,-463.72 621.66,-456.24 628.25,-449.62 638.21,-439.62 2647.56,-445.93 2661,-441.62 2703.86,-427.9 2744.93,-396.11 2771.77,-371.93"/>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" stroke-dasharray="5,2" d="M982.71,-511.61C962.63,-506.78 940.54,-501.98 920,-498.62 885.68,-493.02 631.72,-496.29 608.25,-470.62 601.95,-463.74 601.66,-456.24 608.25,-449.62 618.31,-439.53 2647.42,-445.97 2661,-441.62 2703.86,-427.9 2744.93,-396.11 2771.77,-371.93"/>
 <polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="2773.51,-374.14 2777.51,-366.66 2769.72,-370.01 2773.51,-374.14"/>
-<text xml:space="preserve" text-anchor="middle" x="657.12" y="-462.07" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">counterfactual</text>
-<text xml:space="preserve" text-anchor="middle" x="657.12" y="-451.57" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">[REPEATING]</text>
+<text xml:space="preserve" text-anchor="middle" x="637.12" y="-462.07" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">counterfactual</text>
+<text xml:space="preserve" text-anchor="middle" x="637.12" y="-451.57" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">[REPEATING]</text>
 </g>
 <!-- Policy -->
 <g id="node17" class="node">
@@ -273,9 +273,9 @@
 <!-- Dispatch&#45;&gt;Snapshot -->
 <g id="edge17" class="edge">
 <title>Dispatch&#45;&gt;Snapshot</title>
-<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M982.79,-511.11C962.71,-506.26 940.6,-501.58 920,-498.62 859.87,-489.99 415.84,-514.67 374,-470.62 367.57,-463.86 367.47,-456.29 374,-449.62 388.54,-434.77 728.61,-449.09 748,-441.62 781.43,-428.75 811.74,-401.68 832.99,-378.87"/>
-<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="834.93,-380.9 838.24,-373.1 830.79,-377.13 834.93,-380.9"/>
-<text xml:space="preserve" text-anchor="middle" x="386" y="-456.82" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">probe</text>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M982.79,-511.08C962.71,-506.24 940.6,-501.57 920,-498.62 857.67,-489.73 397.41,-516.24 354,-470.62 347.57,-463.86 347.47,-456.29 354,-449.62 369.32,-433.99 727.57,-449.48 748,-441.62 781.44,-428.77 811.75,-401.69 832.99,-378.88"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="834.94,-380.91 838.24,-373.11 830.79,-377.15 834.94,-380.91"/>
+<text xml:space="preserve" text-anchor="middle" x="366" y="-456.82" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">probe</text>
 </g>
 <!-- Dispatch&#45;&gt;Observe -->
 <g id="edge23" class="edge">
@@ -354,9 +354,10 @@
 <!-- Result&#45;&gt;Learning -->
 <g id="edge13" class="edge">
 <title>Result&#45;&gt;Learning</title>
-<path fill="none" stroke="#34d399" stroke-width="1.3" d="M1436.68,-515.8C1417.86,-509.35 1394.52,-502.34 1373,-498.62 1336.18,-492.27 726.87,-497.59 701,-470.62 694.54,-463.89 694.43,-456.25 701,-449.62 711.32,-439.22 1742.38,-447.04 1756,-441.62 1787.86,-428.95 1815.93,-402.05 1835.46,-379.27"/>
-<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="1837.52,-381.18 1840.49,-373.24 1833.22,-377.59 1837.52,-381.18"/>
-<text xml:space="preserve" text-anchor="middle" x="732.5" y="-456.82" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">auto_introspect</text>
+<path fill="none" stroke="#34d399" stroke-width="1.3" d="M1436.68,-515.78C1417.86,-509.34 1394.53,-502.33 1373,-498.62 1335.07,-492.1 707.41,-498.39 680.75,-470.62 674.29,-463.89 674.17,-456.25 680.75,-449.62 691.27,-439.03 1742.12,-447.14 1756,-441.62 1787.86,-428.96 1815.93,-402.06 1835.47,-379.27"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="1837.52,-381.18 1840.5,-373.24 1833.22,-377.59 1837.52,-381.18"/>
+<text xml:space="preserve" text-anchor="middle" x="722.38" y="-462.07" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">auto_introspect</text>
+<text xml:space="preserve" text-anchor="middle" x="722.38" y="-451.57" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">(deferred after reply)</text>
 </g>
 <!-- Reward -->
 <g id="node15" class="node">
@@ -391,10 +392,10 @@
 <!-- Result&#45;&gt;Observe -->
 <g id="edge18" class="edge">
 <title>Result&#45;&gt;Observe</title>
-<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M1436.69,-515.69C1417.88,-509.22 1394.55,-502.22 1373,-498.62 1322.16,-490.15 481.64,-507.61 445.75,-470.62 439.25,-463.93 439.2,-456.27 445.75,-449.62 456.17,-439.05 966.53,-447.86 980,-441.62 1013.37,-426.19 1039.16,-391.33 1053.96,-367.02"/>
-<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="1056.27,-368.61 1057.91,-360.3 1051.44,-365.78 1056.27,-368.61"/>
-<text xml:space="preserve" text-anchor="middle" x="496.38" y="-462.07" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">auto_extrospect</text>
-<text xml:space="preserve" text-anchor="middle" x="496.38" y="-451.57" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">(AUTO_SECTIONS only)</text>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M1436.69,-515.68C1417.89,-509.21 1394.55,-502.21 1373,-498.62 1321.07,-489.99 462.42,-508.4 425.75,-470.62 419.25,-463.93 419.2,-456.27 425.75,-449.62 436.56,-438.66 966.02,-448.09 980,-441.62 1013.37,-426.2 1039.16,-391.34 1053.96,-367.03"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="1056.27,-368.62 1057.91,-360.3 1051.44,-365.78 1056.27,-368.62"/>
+<text xml:space="preserve" text-anchor="middle" x="476.38" y="-462.07" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">auto_extrospect</text>
+<text xml:space="preserve" text-anchor="middle" x="476.38" y="-451.57" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">(AUTO_SECTIONS only)</text>
 </g>
 <!-- Result&#45;&gt;Verify -->
 <g id="edge49" class="edge">

data/documentation/pwn-REPL.md

@@ -19,7 +19,7 @@ commands.
 | Command | Implemented in | Purpose |
 |---|---|---|
 | `pwn-ai` | `Agent::Loop` | Enter the AI agent TUI |
-| `pwn-vault` | `PWN::Plugins::Vault` | Decrypt → edit `~/.pwn/pwn.yaml` → re-encrypt |
+| `pwn-vault` | `PWN::Plugins::Vault` | Decrypt, edit `~/.pwn/pwn.yaml`, re-encrypt. Stays in the editor until `PWN::Config` accepts the file. |
 | `pwn-asm` | `Plugins::Assembly` | Multiline asm ↔ opcodes workbench |
 | `pwn-mesh` | `Meshtastic` gem | Meshtastic serial / MQTT client (Ruby ≥ 4.0; installed via `pwn setup`) |
 | `pwn-ai-memory` | `PWN::Memory` | View/edit persistent memory |

data/documentation/pwn-ai-Agent.md

@@ -38,9 +38,10 @@ $ pwn --ai "run bin/pwn_sast against ./src and push findings to DefectDojo"
  chosen)` DPO preference pair** in `~/.pwn/preferences.jsonl`.
 3. **Registry** hands Loop the tool schemas - the full set for frontier
  engines, or `CORE_TOOLS` + top-K keyword-relevant when
- `ai.agent.tool_router` is on. Rank can include a Q-advantage term from
- `Policy` after a pair has been visited at least twice. Planning still owns
- the task list. *(local)* `Learning.exemplars_for` splices a compressed
+ `ai.agent.tool_router` is on (default on for `ollama` / `openwebui`). Rank
+ can include a Q-advantage term from `Policy` after a pair has been visited
+ at least twice, plus `ai.agent.tool_preference` as a smaller tie-break.
+ Planning still owns the task list. *(local)* `Learning.exemplars_for` splices a compressed
  prior-success trace as few-shot; *(local)* `plan_first` forces a numbered
  tool plan before the first dispatch (optionally red-teamed by
  `Curriculum.red_team_plan`).
@@ -80,8 +81,10 @@ $ pwn --ai "run bin/pwn_sast against ./src and push findings to DefectDojo"
  outside world; a `:refuted` verify is itself recorded as a Mistakes
  `assumption` fingerprint.
 7. Results are appended to the message list; go to 5.
-8. When the reply has *no* tool_calls it's the **final answer** →
- `Learning.auto_introspect` fires (if enabled): *(local)*
+8. When the reply has *no* tool_calls it's the **final answer**. With
+ `defer_introspect` on (default), the user-visible reply returns first and
+ `Learning.auto_introspect` runs on a background thread. Specs and cron stay
+ inline. Then *(local)*
  `fact_check_local_final` auto-`extro_verify`s every CVE / version-shaped
  claim in the answer; **`Reward.judge`** scores (request, final) with a cheap LLM ORM →
  `{score, verdict, rationale, source}` (heuristic overlap only if the engine is unavailable); **`Policy.finish`** applies that judge score as
@@ -162,7 +165,7 @@ task_summary_interval_s: 8.0    # or every N seconds (verbose)
 task_summary_verbose: false     # mid-flight Progress: lines
 task_summary_llm: true          # LLM task decompose for autonomous goals (default on)
 request_kind_llm: null          # null = follow task_summary_llm; false = heuristic-only
-max_iters: 25                   # budget pressure may lower the effective cap (stricter on local engines)
+max_iters: 75                   # budget pressure may lower the effective cap (stricter on local engines)
 ```
 
 
@@ -176,8 +179,9 @@ max_iters: 25                   # budget pressure may lower the effective cap (s
   summary turn.
 - Run `mistakes_list` before retrying something that failed last session -
   the fix may already be recorded.
-- `ai.agent.tool_router: true` + `ai.agent.plan_first: true` when running on
-  a local model - that cuts mis-routing a lot.
+- Leave `ai.agent.tool_router` and `ai.agent.plan_first` on auto when running
+  a local model - that cuts mis-routing a lot. Tune `ai.agent.tool_preference`
+  if you want recall / sessions ahead of `shell` on ties.
 - Set `ai.reflect_engine:` to a frontier provider so lessons written to
   `~/.pwn/memory.json` stay high-signal even when the executing engine is
   local.
@@ -201,7 +205,10 @@ max_iters: 25                   # budget pressure may lower the effective cap (s
 | `reward_model` | `nil` | optional cheaper model id for `Reward.judge` / `.prm` (nil = active engine default) |
 | `reward_llm_timeout` | `12` | seconds for the cheap ORM chat (clamped 2..30) |
 | `verify_as_reward` | `nil` (auto) | browser-grounded claim sample policy |
-| `local_introspect` | `:failure_only` | ollama end-of-turn introspect policy |
+| `local_introspect` | `:failure_only` | ollama / openwebui end-of-turn introspect policy |
+| `tool_preference` | memory_recall-first list | Rank bonus + Policy suggested-action order |
+| `defer_introspect` | `true` | Post-answer Learning on a background thread |
+| `prompt_cache` | `true` | Engine-native prefix cache (not Ollama / Open WebUI) |
 
 Full detail: [Reinforcement Learning](Reinforcement-Learning.md).
 

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

@@ -1013,7 +1013,7 @@ module PWN
                 cwt_opts[:tool_choice] = has_tool_result && !still_acting ? 'auto' : 'required'
               end
             end
-            response = mod.chat_with_tools(**cwt_opts)
+            response = mod.chat_with_tools(cwt_opts)
             publish_usage(response: response, engine: engine)
             normalize_llm(response: response)
           else
@@ -1404,9 +1404,46 @@ module PWN
         private_class_method def self.answer_statement(opts = {})
           request = opts[:request].to_s
           session_id = opts[:session_id]
-          txt = <<~ACK.strip
-            Noted. No multi-step task breakdown for a general statement — ready when you have a question or a goal to accomplish.
-          ACK
+          system_role_content = opts[:system_role_content].to_s
+          engine = active_engine
+          mod_name = ENGINE_MODS[engine]
+          raise "ERROR: Unsupported AI engine for agent loop: #{engine}" unless mod_name
+
+          mod = Object.const_get(mod_name)
+          q_sys = <<~SYS
+            #{system_role_content}
+
+            INTENT: STATEMENT (this turn only)
+              The user is making a statement — not an autonomous multi-step goal.
+              Respond concisely in plain US English. Do NOT call tools unless a
+              single factual lookup is strictly required and already present in
+              context. Do NOT plan multi-step work. Do NOT invent task traces,
+              planner monologue, rubocop, rake, or live recon.
+          SYS
+
+          txt =
+            if mod.respond_to?(:chat)
+              r = mod.chat(
+                request: request,
+                system_role_content: q_sys,
+                spinner: true
+              )
+              if r.is_a?(Hash)
+                (r.dig(:choices, -1, :content) || r.dig(:choices, -1, :text) || r[:content]).to_s
+              else
+                r.to_s
+              end
+            else
+              messages = [
+                { role: 'system', content: q_sys },
+                { role: 'user', content: request }
+              ]
+              msg = call_engine(messages: messages, tools: nil)
+              msg.is_a?(Hash) ? msg[:content].to_s : msg.to_s
+            end
+
+          txt = txt.to_s.strip
+          txt = 'I do not have enough context to respond to your statement.' if txt.empty?
 
           append_session(session_id: session_id, role: 'user', content: request)
           append_session(session_id: session_id, role: 'assistant', content: txt)
@@ -1415,7 +1452,7 @@ module PWN
               session_id: session_id,
               request: request,
               final: txt,
-              predicted: 0.9,
+              predicted: 0.85,
               plan: [],
               ts_state: nil
             )

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

@@ -572,16 +572,22 @@ module PWN
           end
 
           ev = evaluate(limit: opts[:limit] || 40)
+          fallback = %w[memory_recall sessions_view pwn_eval shell mistakes_record mistakes_resolve learning_note_outcome memory_remember]
+          pref = begin
+            PWN::AI::Agent::Registry.preference_order
+          rescue StandardError
+            []
+          end
+          actions = pref.empty? ? fallback : pref
           rec = begin
-            recs = recommend(actions: %w[shell pwn_eval memory_recall sessions_view], epsilon: 0.0)
-            recs[:action]
+            recommend(actions: actions, epsilon: 0.0)[:action]
           rescue StandardError
             nil
           end
           lines << 'POLICY (R5 tabular Q / REINFORCE — advisory only, does not replace planning)'
           lines << "  episodes=#{s[:n_episodes]} states=#{s[:n_states]} pairs=#{s[:n_pairs]} updates=#{s[:n_updates]}"
           lines << "  mean_return=#{s[:mean_return] || '-'} mean|TD|=#{s[:mean_abs_td] || '-'} greedy_match=#{ev[:greedy_match] || '-'}"
-          lines << "  current_state=#{current_state || '(none)'} suggest=#{rec || '-'}"
+          lines << "  current_state=#{current_state || '(none)'} suggest=#{rec || '-'} tool_preference=#{actions.join(',')}"
           "#{lines.join("\n")}\n"
         rescue StandardError
           ''

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

@@ -43,6 +43,12 @@ module PWN
         CORE_TOOLS = %w[shell pwn_eval memory_remember memory_recall
                         mistakes_record mistakes_resolve learning_note_outcome].freeze
 
+        # Operator-tunable tool order. Prefer these names when keyword-fit
+        # (or other rank features) tie. Overridable via opts[:order],
+        # opts[:preference], or PWN::Env[:ai][:agent][:tool_preference].
+        # Explicit nil/empty order disables preference (no Env/DEFAULT fallback).
+        DEFAULT_PREFERENCE = %w[memory_recall sessions_view pwn_eval shell mistakes_record mistakes_resolve learning_note_outcome memory_remember].freeze
+
         @entries = {}
         @discovered = false
 
@@ -100,7 +106,9 @@ module PWN
         # tools = PWN::AI::Agent::Registry.definitions(
         #   enabled: 'optional - Array of toolset names to include; nil = all whose check passes',
         #   relevance: 'optional - user request; when set AND :tool_router is enabled, slim to CORE + top-K keyword matches',
-        #   top_k: 'optional - keyword-ranked tools to keep beyond CORE (default 10)'
+        #   top_k: 'optional - keyword-ranked tools to keep beyond CORE (default 10)',
+        #   order: 'optional - preference list forwarded only when this key is present',
+        #   preference: 'optional - alias of :order; same key-present rule'
         # )
 
         public_class_method def self.definitions(opts = {})
@@ -108,19 +116,84 @@ module PWN
           enabled = enabled.map(&:to_s) if enabled
           pool = @entries.values.select { |e| (enabled.nil? || enabled.include?(e.toolset)) && safe_check(entry: e) }
 
+          pref_fwd = {}
+          pref_fwd[:order] = opts[:order] if opts.key?(:order)
+          pref_fwd[:preference] = opts[:preference] if opts.key?(:preference)
+
           if opts[:relevance] && router_enabled?
-            keep  = rank(query: opts[:relevance], entries: pool).first(opts[:top_k] || 10).map(&:name)
+            keep = rank({ query: opts[:relevance], entries: pool }.merge(pref_fwd)).first(opts[:top_k] || 10).map(&:name)
             names = (CORE_TOOLS + keep).uniq
             pool  = pool.select { |e| names.include?(e.name) }
           end
 
+          pool = apply_preference({ items: pool }.merge(pref_fwd))
           pool.map { |e| { type: 'function', function: e.schema } }
         end
 
+        # Supported Method Parameters::
+        # order = PWN::AI::Agent::Registry.preference_order(
+        #   order: 'optional - Array of tool names; explicit nil/[] disables',
+        #   preference: 'optional - alias of :order. Explicit key disables Env/DEFAULT fallback'
+        # )
+
+        public_class_method def self.preference_order(opts = {})
+          explicit = opts.key?(:order) || opts.key?(:preference)
+          if explicit
+            raw = opts.key?(:preference) ? opts[:preference] : opts[:order]
+            return [] if raw.nil? || (raw.respond_to?(:empty?) && raw.empty?)
+
+            return Array(raw).map(&:to_s).reject(&:empty?)
+          end
+
+          raw = nil
+          raw = PWN::Env.dig(:ai, :agent, :tool_preference) if defined?(PWN::Env) && PWN::Env.is_a?(Hash)
+          raw = DEFAULT_PREFERENCE if raw.nil? || (raw.respond_to?(:empty?) && raw.empty?)
+          Array(raw).map(&:to_s).reject(&:empty?)
+        rescue StandardError
+          DEFAULT_PREFERENCE.dup
+        end
+
+        # Supported Method Parameters::
+        # sorted = PWN::AI::Agent::Registry.apply_preference(
+        #   items: 'required - Array of Entry objects or OpenAI tool hashes',
+        #   order: 'optional - forwarded to preference_order only when the key is set',
+        #   preference: 'optional - alias of :order; same key-present rule'
+        # )
+        #
+        # Stable sort: preferred names first, original index as the tie-break
+        # so equal-preference items keep their incoming order.
+        # Empty preference (explicit [] / nil) leaves items unsorted.
+
+        public_class_method def self.apply_preference(opts = {})
+          items = Array(opts[:items] || opts[:entries])
+          po = {}
+          po[:preference] = opts[:preference] if opts.key?(:preference)
+          po[:order] = opts[:order] if opts.key?(:order)
+          order = preference_order(po)
+          return items if order.empty?
+
+          index = {}
+          order.each_with_index { |name, i| index[name.to_s] = i }
+          fallback = order.length
+          items.sort_by.with_index do |item, orig|
+            name = if item.respond_to?(:name)
+                     item.name.to_s
+                   elsif item.is_a?(Hash)
+                     (item.dig(:function, :name) ||
+                      item.dig('function', 'name') ||
+                      item[:name] || item['name']).to_s
+                   else
+                     item.to_s
+                   end
+            [index.fetch(name, fallback), orig]
+          end
+        end
+
         # Supported Method Parameters::
         # ranked = PWN::AI::Agent::Registry.rank(
         #   query: 'required - user request text',
-        #   entries: 'optional - Entry pool to rank (default .all)'
+        #   entries: 'optional - Entry pool to rank (default .all)',
+        #   order: 'optional - preference list forwarded to preference_order'
         # )
         #
         # C1 advantage-weighted router: score = α·keyword_sim + β·(tool
@@ -136,11 +209,23 @@ module PWN
 
           tokens = query.scan(/[a-z0-9_]{3,}/).uniq
           # C1 — advantage-weighted router:
-          #   score = α·keyword_sim + β·advantage + γ·UCB(tool) + δ·prm_advantage + ε·Q_adv
+          #   score = alpha*keyword_sim + beta*advantage + gamma*UCB(tool)
+          #         + delta*prm_advantage + eps_q*Q_adv + zeta*pref_score
           # UCB gives untried / low-N tools an exploration bonus so a single
           # early failure (before its dep was installed) does not blacklist
           # it forever; advantage prefers tools that outperform the fleet.
+          # zeta * pref_score (zeta=0.35) boosts Env/opts tool preference;
+          # alpha stays 1.0 so keyword fit remains the primary signal.
+          # zeta is 0 when preference is empty so ties are not pref-boosted.
           alpha = 1.0
+          po = {}
+          po[:preference] = opts[:preference] if opts.key?(:preference)
+          po[:order] = opts[:order] if opts.key?(:order)
+          pref_order = preference_order(po)
+          zeta = pref_order.empty? ? 0.0 : 0.35
+          pref_index = {}
+          pref_order.each_with_index { |n, i| pref_index[n.to_s] = i }
+          pref_n = [pref_order.length, 1].max
           # P4 — haircut advantage weight when reward proxy is hacked
           trust = defined?(Metrics) && Metrics.respond_to?(:proxy_trust) ? Metrics.proxy_trust : 1.0
           beta  = 0.3 * trust
@@ -187,10 +272,14 @@ module PWN
                     else
                       0.0
                     end
-            [e, sim, (alpha * sim) + (beta * adv) + (gamma * ucb) + (delta * prm) + (eps_q * qadv)]
+            pidx = pref_index[e.name]
+            pref = pidx.nil? ? 0.0 : ((pref_n - pidx).to_f / pref_n)
+            total = (alpha * sim) + (beta * adv) + (gamma * ucb) + (delta * prm) + (eps_q * qadv) + (zeta * pref)
+            [e, sim, total]
           end
+          # Equal keyword-fit (and equal total): preferred name first.
           scored.reject { |_, sim, _| sim.zero? }
-                .sort_by { |_, _, s| -s }
+                .sort_by { |e, _, s| [-s, pref_index.fetch(e.name, pref_n), e.name] }
                 .map(&:first)
         end
 

data/lib/pwn/ai/anthropic.rb

@@ -2,7 +2,6 @@
 
 require 'json'
 require 'rest-client'
-require 'tty-spinner'
 require 'securerandom'
 require 'base64'
 require 'digest'
@@ -418,10 +417,8 @@ module PWN
         browser_obj = PWN::Plugins::TransparentBrowser.open(browser_type: :rest)
         rest_client = browser_obj[:browser]::Request
 
-        if spinner
-          spin = TTY::Spinner.new(format: :dots)
-          spin.auto_spin
-        end
+        spin = PWN::Plugins::TTYSpinner.start if spinner
+        spin.auto_spin if spinner
 
         retry_count = 0
         begin
@@ -479,7 +476,7 @@ module PWN
             raise e
           end
         ensure
-          spin.stop if spinner
+          PWN::Plugins::TTYSpinner.stop(spin: spin)
         end
       end
 

data/lib/pwn/ai/gemini.rb

@@ -2,7 +2,6 @@
 
 require 'json'
 require 'rest-client'
-require 'tty-spinner'
 require 'securerandom'
 
 module PWN
@@ -55,10 +54,8 @@ module PWN
         browser_obj = PWN::Plugins::TransparentBrowser.open(browser_type: :rest)
         rest_client = browser_obj[:browser]::Request
 
-        if spinner
-          spin = TTY::Spinner.new(format: :dots)
-          spin.auto_spin
-        end
+        spin = PWN::Plugins::TTYSpinner.start if spinner
+        spin.auto_spin if spinner
 
         retry_count = 0
         begin
@@ -103,7 +100,7 @@ module PWN
             raise e
           end
         ensure
-          spin.stop if spinner
+          PWN::Plugins::TTYSpinner.stop(spin: spin)
         end
       end
 

data/lib/pwn/ai/grok.rb

@@ -2,7 +2,6 @@
 
 require 'json'
 require 'rest-client'
-require 'tty-spinner'
 require 'uri'
 require 'base64'
 
@@ -424,10 +423,8 @@ module PWN
         browser_obj = PWN::Plugins::TransparentBrowser.open(browser_type: :rest)
         rest_client = browser_obj[:browser]::Request
 
-        if spinner
-          spin = TTY::Spinner.new(format: :dots)
-          spin.auto_spin
-        end
+        spin = PWN::Plugins::TTYSpinner.start if spinner
+        spin.auto_spin if spinner
 
         retry_count = 0
         begin
@@ -495,7 +492,7 @@ module PWN
         end
         "#{e.message}: #{e.response}"
       ensure
-        spin.stop if spinner
+        PWN::Plugins::TTYSpinner.stop(spin: spin)
       end
 
       # Supported Method Parameters::
@@ -695,6 +692,9 @@ module PWN
         temp = opts[:temp].to_f
         temp = engine[:temp].to_f.nonzero? || 1 if temp.zero?
 
+        spinner = opts[:spinner]
+        timeout = opts[:timeout]
+
         conv_id = nil
         if defined?(PWN::AI::Agent::PromptCache) &&
            PWN::AI::Agent::PromptCache.enabled?(engine: :grok)
@@ -722,8 +722,8 @@ module PWN
           http_method: :post,
           rest_call: 'chat/completions',
           http_body: http_body,
-          timeout: opts[:timeout],
-          spinner: opts[:spinner],
+          timeout: timeout,
+          spinner: spinner,
           quiet: opts[:quiet],
           headers: (conv_id ? { 'x-grok-conv-id' => conv_id } : nil)
         )

data/lib/pwn/ai/ollama.rb

@@ -3,7 +3,6 @@
 require 'json'
 require 'base64'
 require 'securerandom'
-require 'tty-spinner'
 
 module PWN
   module AI
@@ -75,10 +74,8 @@ module PWN
         browser_obj = PWN::Plugins::TransparentBrowser.open(browser_type: :rest)
         rest_client = browser_obj[:browser]::Request
 
-        if spinner
-          spin = TTY::Spinner.new(format: :dots)
-          spin.auto_spin
-        end
+        spin = PWN::Plugins::TTYSpinner.start if spinner
+        spin.auto_spin if spinner
 
         retry_count = 0
         begin
@@ -198,7 +195,7 @@ module PWN
           raise e
         end
       ensure
-        spin.stop if spinner
+        PWN::Plugins::TTYSpinner.stop(spin: spin)
       end
 
       # Pull a user-visible answer out of a reasoning/"thinking" channel.

data/lib/pwn/ai/open_ai.rb

@@ -3,7 +3,6 @@
 require 'json'
 require 'base64'
 require 'securerandom'
-require 'tty-spinner'
 require 'digest'
 require 'uri'
 
@@ -460,10 +459,8 @@ module PWN
         browser_obj = PWN::Plugins::TransparentBrowser.open(browser_type: :rest)
         rest_client = browser_obj[:browser]::Request
 
-        if spinner
-          spin = TTY::Spinner.new(format: :dots)
-          spin.auto_spin
-        end
+        spin = PWN::Plugins::TTYSpinner.start if spinner
+        spin.auto_spin if spinner
 
         retry_count = 0
         begin
@@ -534,7 +531,7 @@ module PWN
         end
         "#{e.message}: #{e.response}"
       ensure
-        spin.stop if spinner
+        PWN::Plugins::TTYSpinner.stop(spin: spin)
       end
 
       # Supported Method Parameters::

data/lib/pwn/ai/open_web_ui.rb

@@ -3,7 +3,6 @@
 require 'json'
 require 'base64'
 require 'securerandom'
-require 'tty-spinner'
 
 module PWN
   module AI
@@ -87,10 +86,8 @@ module PWN
         browser_obj = PWN::Plugins::TransparentBrowser.open(browser_type: :rest)
         rest_client = browser_obj[:browser]::Request
 
-        if spinner
-          spin = TTY::Spinner.new(format: :dots)
-          spin.auto_spin
-        end
+        spin = PWN::Plugins::TTYSpinner.start if spinner
+        spin.auto_spin if spinner
 
         retry_count = 0
         begin
@@ -226,7 +223,7 @@ module PWN
           raise e
         end
       ensure
-        spin.stop if spinner
+        PWN::Plugins::TTYSpinner.stop(spin: spin)
       end
 
       # Pull a user-visible answer out of a reasoning/"thinking" channel.

data/lib/pwn/blockchain/btc.rb

@@ -3,7 +3,6 @@
 require 'base64'
 require 'json'
 require 'rest-client'
-require 'tty-spinner'
 require 'date'
 
 module PWN
@@ -54,10 +53,7 @@ module PWN
         browser_obj = PWN::Plugins::TransparentBrowser.open(browser_type: :rest)
         rest_client = browser_obj[:browser]::Request
 
-        if spinner
-          spin = TTY::Spinner.new(format: :dots)
-          spin.auto_spin
-        end
+        spin = PWN::Plugins::TTYSpinner.start if spinner
 
         retries = 0
         case http_method.to_s.scrub.downcase.to_sym
@@ -109,7 +105,7 @@ module PWN
       rescue StandardError => e
         raise e
       ensure
-        spin.stop if spinner
+        PWN::Plugins::TTYSpinner.stop(spin: spin)
       end
 
       private_class_method def self.btc_rpc_call(opts = {})

data/lib/pwn/blockchain/eth.rb

@@ -2,7 +2,6 @@
 
 require 'json'
 require 'rest-client'
-require 'tty-spinner'
 
 module PWN
   module Blockchain
@@ -41,10 +40,7 @@ module PWN
         browser_obj = PWN::Plugins::TransparentBrowser.open(browser_type: :rest)
         rest_client = browser_obj[:browser]::Request
 
-        if spinner
-          spin = TTY::Spinner.new(format: :dots)
-          spin.auto_spin
-        end
+        spin = PWN::Plugins::TTYSpinner.start if spinner
 
         retries = 0
         case http_method
@@ -96,7 +92,7 @@ module PWN
       rescue StandardError => e
         raise e
       ensure
-        spin.stop if spinner
+        PWN::Plugins::TTYSpinner.stop(spin: spin)
       end
 
       # Supported Method Parameters::