pwn 0.5.719 → 0.5.721

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

@@ -46,6 +46,21 @@ module PWN
           args = parse_args(raw: raw, entry: entry)
           required = Array(entry.schema&.dig(:parameters, :required))
           args = ToolGuard.coerce_args(args: args, required: required) if defined?(ToolGuard)
+          blob = args.inspect
+          if defined?(PWN::Plugins::Vault)
+            blob = PWN::Plugins::Vault.expand(text: blob)
+            args = expand_vault_args(args: args)
+          end
+          if defined?(Engagement)
+            denied = ToolGuard.scope_check!(args: args, command: blob) if defined?(ToolGuard) && ToolGuard.respond_to?(:scope_check!)
+            denied ||= Engagement.deny_if_out_of_scope(args: args, command: blob)
+            return JSON.generate(denied) if denied
+          end
+          if defined?(ToolGuard) && ToolGuard.respond_to?(:policy_decision)
+            pol = ToolGuard.policy_decision(name: entry.name, args: args)
+            return JSON.generate(pol) if pol.is_a?(Hash) && pol[:action] == 'deny'
+          end
+          return JSON.generate(success: false, error: 'taint: tool-output instruction in args', code: 'TAINT_DENY') if taint_blocked?(name: entry.name, args: args)
           if defined?(ToolGuard) && ToolGuard.respond_to?(:canary_leak?) &&
              ToolGuard.canary_leak?(text: args.inspect)
             return JSON.generate(success: false, error: 'refused: session canary in outbound args', code: 'CANARY_DENY', rule_id: 'canary')
@@ -59,6 +74,12 @@ module PWN
           end
           result = entry.handler.call(args)
           result = ToolGuard.quarantine_output(text: result) if defined?(ToolGuard) && result.is_a?(String) && ToolGuard.respond_to?(:quarantine_output)
+          note_taint(text: result)
+          if defined?(PWN::Plugins::Vault) && result.is_a?(String)
+            result = PWN::Plugins::Vault.redact(text: result)
+          elsif defined?(PWN::Plugins::Vault) && result.is_a?(Hash)
+            result = JSON.parse(PWN::Plugins::Vault.redact(text: JSON.generate(result)))
+          end
           JSON.generate(success: true, result: result, effect: effect(name: entry.name, args: args))
         rescue StandardError => e
           JSON.generate(
@@ -323,8 +344,8 @@ module PWN
           return :store if STORE_TOOLS.include?(name)
 
           blob = argv_blob(args: opts[:args])
-          return :browse if blob.match?(BROWSE_ARGV_RX)
           return :write if blob.match?(WRITE_ARGV_RX)
+          return :browse if blob.match?(BROWSE_ARGV_RX)
           return :eval if name == 'pwn_eval'
 
           :read
@@ -348,6 +369,53 @@ module PWN
           hash.each_with_object({}) { |(k, v), m| m[k.to_sym] = v }
         end
 
+        private_class_method def self.expand_vault_args(opts = {})
+          args = opts[:args]
+          return args unless args.is_a?(Hash)
+
+          args.transform_values do |v|
+            v.is_a?(String) ? PWN::Plugins::Vault.expand(text: v) : v
+          end
+        rescue StandardError
+          opts[:args]
+        end
+
+        private_class_method def self.note_taint(opts = {})
+          text = opts[:text].to_s
+          grams = text.scan(/.{24,}/).first(20)
+          store = Thread.current[:pwn_taint] ||= []
+          grams.each { |g| store << g[0, 64] }
+          store.shift while store.length > 200
+          store
+        end
+
+        private_class_method def self.taint_blocked?(opts = {})
+          mode = taint_mode
+          return false if mode == 'off'
+
+          blob = opts[:args].inspect
+          return false if blob.length < 24
+          return false if opts[:args].is_a?(Hash) && (opts[:args][:taint_ack] == true || opts[:args]['taint_ack'] == true)
+
+          hit = Array(Thread.current[:pwn_taint]).any? { |g| g.length >= 24 && blob.include?(g) }
+          return false unless hit
+          return false unless blob.match?(/curl |bash -c|sh -c|\|\s*sh\b/i)
+
+          mode == 'enforce'
+        rescue StandardError
+          false
+        end
+
+        private_class_method def self.taint_mode(opts = {})
+          override = opts[:mode]
+          return override.to_s unless override.to_s.empty?
+          return 'enforce' unless defined?(PWN::Env)
+
+          (PWN::Env.dig(:ai, :taint, :mode) || 'enforce').to_s
+        rescue StandardError
+          'enforce'
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors

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

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'ipaddr'
+require 'uri'
+
+module PWN
+  module AI
+    module Agent
+      # First-class engagement scope, RoE, and findings pointer.
+      module Engagement
+        ROOT = File.join(Dir.home, '.pwn', 'engagements')
+        ACTIVE_FILE = File.join(ROOT, 'active')
+
+        public_class_method def self.open(opts = {})
+          name = (opts[:name] || opts[:engagement] || 'default').to_s
+          raise 'ERROR: name is required' if name.empty?
+
+          FileUtils.mkdir_p(ROOT)
+          path = File.join(ROOT, "#{name}.json")
+          row = File.file?(path) ? JSON.parse(File.read(path), symbolize_names: true) : {}
+          row[:name] = name
+          row[:scope_cidrs] = Array(opts[:scope_cidrs] || row[:scope_cidrs])
+          row[:scope_domains] = Array(opts[:scope_domains] || row[:scope_domains])
+          row[:excluded] = Array(opts[:excluded] || row[:excluded])
+          row[:roe] = (opts[:roe] || row[:roe]).to_s
+          row[:window] = opts[:window] || row[:window]
+          row[:findings] ||= []
+          File.write(path, JSON.pretty_generate(row))
+          File.write(ACTIVE_FILE, name)
+          row.merge(path: path, active: true)
+        end
+
+        public_class_method def self.close(opts = {})
+          FileUtils.rm_f(ACTIVE_FILE) if opts.is_a?(Hash)
+          { active: nil }
+        end
+
+        public_class_method def self.status(opts = {})
+          name = (opts[:name] || current_name).to_s
+          return { active: nil } if name.empty?
+
+          path = File.join(ROOT, "#{name}.json")
+          return { active: name, missing: true } unless File.file?(path)
+
+          JSON.parse(File.read(path), symbolize_names: true).merge(active: name)
+        end
+
+        public_class_method def self.current_name(opts = {})
+          return nil unless opts.is_a?(Hash)
+          return nil unless File.file?(ACTIVE_FILE)
+
+          File.read(ACTIVE_FILE).strip
+        end
+
+        public_class_method def self.in_scope?(opts = {})
+          token = (opts[:host] || opts[:ip] || opts[:target] || opts[:url]).to_s
+          return true if token.empty?
+
+          row = status
+          return true if row[:active].nil? || row[:missing]
+
+          enforce = engagement_enforce
+          return true if enforce == 'off'
+
+          host = token
+          begin
+            host = URI.parse(token).host || token if token.include?('://')
+          rescue StandardError
+            host = token
+          end
+          host = host.sub(%r{\Ahttps?://}i, '').split('/').first.to_s.split(':').first
+          return false if Array(row[:excluded]).any? { |ex| host.include?(ex.to_s) }
+
+          cidrs = Array(row[:scope_cidrs]).map(&:to_s).reject(&:empty?)
+          domains = Array(row[:scope_domains]).map(&:to_s).reject(&:empty?)
+          return true if cidrs.empty? && domains.empty?
+
+          ip_ok = begin
+            addr = IPAddr.new(host)
+            cidrs.any? { |c| IPAddr.new(c).include?(addr) }
+          rescue StandardError
+            false
+          end
+          dom_ok = domains.any? { |d| host == d || host.end_with?(".#{d}") }
+          ip_ok || dom_ok
+        end
+
+        public_class_method def self.deny_if_out_of_scope(opts = {})
+          args = opts[:args] || opts[:command] || opts[:text]
+          blob = args.is_a?(Hash) ? args.inspect : args.to_s
+          tokens = blob.scan(/(?:\d{1,3}\.){3}\d{1,3}|[A-Za-z0-9.-]+\.[A-Za-z]{2,}/).uniq
+          bad = tokens.reject { |tok| in_scope?(host: tok) }
+          return nil if bad.empty?
+
+          {
+            success: false,
+            error: "out_of_scope: #{bad.first}",
+            code: 'SCOPE_DENY',
+            violating: bad
+          }
+        end
+
+        public_class_method def self.authors
+          "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+        end
+
+        public_class_method def self.help
+          puts "USAGE:
+            # Open or update an engagement and mark it active.
+            #{self}.open(
+              name: 'required - engagement name',
+              engagement: 'optional - alias for name',
+              scope_cidrs: 'optional - Array of CIDR strings',
+              scope_domains: 'optional - Array of DNS suffixes',
+              excluded: 'optional - Array of excluded hosts',
+              roe: 'optional - rules of engagement text',
+              window: 'optional - time window string'
+            )
+
+            # Clear the active engagement pointer.
+            #{self}.close(
+              name: 'optional - unused; closing always clears the active pointer'
+            )
+
+            # Return the active engagement document.
+            #{self}.status(
+              name: 'optional - engagement name (defaults to active)'
+            )
+
+            # Return the active engagement name or nil.
+            #{self}.current_name(
+              unused: 'optional - reserved'
+            )
+
+            # True when host/ip/url is inside the active engagement scope.
+            #{self}.in_scope?(
+              host: 'optional - DNS hostname to test against scope_domains',
+              ip: 'optional - IPv4 or IPv6 address to test against scope_cidrs',
+              target: 'optional - host or IP alias when the caller has one field',
+              url: 'optional - URL whose host is extracted and tested'
+            )
+
+            # Structured denial when args mention an out-of-scope host.
+            #{self}.deny_if_out_of_scope(
+              args: 'optional - Hash of tool args',
+              command: 'optional - command string',
+              text: 'optional - free-form blob to scan'
+            )
+
+            # Print the AUTHOR(S) string for this module.
+            #{self}.authors
+          "
+          constants.sort
+        end
+
+        private_class_method def self.engagement_enforce
+          v = (PWN::Env.dig(:ai, :engagement, :enforce) if defined?(PWN::Env))
+          (v || 'block').to_s
+        rescue StandardError
+          'block'
+        end
+      end
+    end
+  end
+end

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

@@ -128,6 +128,16 @@ module PWN
           entry[:score] = opts[:score].to_f if opts.key?(:score)
           src = opts[:judge_source].to_s
           entry[:judge_source] = src unless src.empty?
+          vv = (opts[:verifier_verdict] || opts['verifier_verdict']).to_s
+          entry[:verifier_verdict] = vv unless vv.empty?
+          vc = (opts[:verdict_class] || opts['verdict_class']).to_s
+          entry[:verdict_class] = vc unless vc.empty?
+          entry[:remediation_hint] = opts[:remediation_hint].to_s unless opts[:remediation_hint].to_s.empty?
+          if vv == 'pass' && opts.key?(:score) && opts[:score].to_f < 0.6
+            entry[:status] = 'conflicted'
+            entry[:success] = true
+            success = true
+          end
           FileUtils.mkdir_p(File.dirname(LEARNING_FILE))
           File.open(LEARNING_FILE, 'a') { |f| f.puts(JSON.generate(entry)) }
           maybe_prune_outcomes!
@@ -137,7 +147,7 @@ module PWN
           # are promoted into PWN::Memory[:lesson] so PromptBuilder recall
           # survives across sessions. Without this, the agent re-learns
           # "run rubocop after every patch" every turn (empty memory.json).
-          promote_process_lesson(entry: entry) if defined?(PWN::Memory)
+          promote_process_lesson(entry: entry) if defined?(PWN::Memory) && entry[:status].to_s != 'conflicted'
           if opts.key?(:score) && defined?(Curriculum) && Curriculum.respond_to?(:calibrate)
             pred = opts[:predicted]
             pred = Thread.current[:pwn_plan_predicted] if pred.nil?
@@ -186,11 +196,21 @@ module PWN
           jmean  = total.positive? ? weighted_judge_mean(rows: rows) : nil
           distrust = 0.0
           distrust = Reward.proxy_distrust.to_f.clamp(0.0, 1.0) if defined?(Reward) && Reward.respond_to?(:proxy_distrust)
+          orm = rows.select { |r| r[:judge_source].to_s != 'heuristic' && r[:source].to_s != 'heuristic' }
+          heur = rows.select { |r| r[:judge_source].to_s == 'heuristic' || r[:source].to_s == 'heuristic' }
+          orm_n = orm.length
+          heur_n = heur.length
+          orm_ok = orm.count { |r| r[:success] == true }
+          heur_ok = heur.count { |r| r[:success] == true }
           {
             total_outcomes: total,
             successes: ok,
             failures: total - ok,
             success_rate: raw,
+            success_rate_orm: orm_n.positive? ? (orm_ok.to_f / orm_n).round(3) : 0.0,
+            success_rate_heur: heur_n.positive? ? (heur_ok.to_f / heur_n).round(3) : 0.0,
+            orm_n: orm_n,
+            heur_n: heur_n,
             adjusted_success_rate: discount_success_rate(proxy: raw, judge: jmean, distrust: distrust),
             proxy_distrust: distrust,
             skills_known: skills,
@@ -215,6 +235,14 @@ module PWN
           # envelope rows (REQUEST:/GOAL: prefixes) without starving the block.
           rows  = prefer_primary_tasks(rows: outcomes(limit: limit * 4)).first(limit)
           fails = prefer_primary_tasks(rows: outcomes(limit: 200, success: false))
+          fails = fails.reject { |r| r[:status].to_s == 'conflicted' }
+          fails = fails.reject { |r| r[:verifier_verdict].to_s == 'pass' }
+          fails = fails.reject { |r| r[:details].to_s.match?(/\bPASS\b/) && r[:success] == true }
+          fails = fails.select do |r|
+            v = r[:verdict].to_s
+            v == 'wrong' || v == 'refused' || (r[:score].to_f < 0.3 && !r[:details].to_s.match?(/\bPASS\b/)) || r[:success] == false
+          end
+          fails = fails.reject { |r| r[:success] == true }
           # Do not mirror the same ids under both headings — that doubled the
           # failure signal and made RECENT OUTCOMES == RECENT FAILURES when the
           # last N attempts all failed (the injected block looked "stuck").
@@ -234,8 +262,12 @@ module PWN
             # Surface a one-line cause crumb so the agent can actually learn
             # from failures instead of only seeing that they failed.
             if r[:success] != true
-              crumb = cause_crumb(details: r[:details])
-              line += "\n      cause: #{crumb}" unless crumb.empty?
+              if r[:verdict_class].to_s == ''
+                crumb = cause_crumb(details: r[:details])
+                line += "\n      cause: #{crumb}" unless crumb.empty?
+              else
+                line += "\n      cause: #{r[:verdict_class]} #{r[:remediation_hint]}"
+              end
             end
             line
           end
@@ -244,7 +276,7 @@ module PWN
           d   = s[:proxy_distrust].to_f
           rate = d > 0.05 ? s[:adjusted_success_rate] : s[:success_rate]
           tag  = d > 0.05 ? ' adj' : ''
-          hdr = "RECENT OUTCOMES (success_rate=#{(rate.to_f * 100).round(1)}%#{tag}#{" judge_mean=#{jm}" if jm} over #{s[:total_outcomes]} attempts)"
+          hdr = "RECENT OUTCOMES (success_rate=#{(rate.to_f * 100).round(1)}%#{tag} success=orm:#{(s[:success_rate_orm].to_f * 100).round(1)}%(#{s[:orm_n]}) / heur:#{(s[:success_rate_heur].to_f * 100).round(1)}%(#{s[:heur_n]})#{" judge_mean=#{jm}" if jm} over #{s[:total_outcomes]} attempts)"
           out = "#{hdr}\n#{rows.map(&fmt).join("\n")}\n"
           out += "RECENT FAILURES (learn from these — do not repeat)\n#{fails.map(&fmt).join("\n")}\n" unless fails.empty?
           "#{out}\n"
@@ -1049,6 +1081,7 @@ module PWN
 
         private_class_method def self.cause_crumb(opts = {})
           d = opts[:details].to_s.gsub(/\s+/, ' ').strip
+          d = d.gsub(/overlap=\S+/, '').gsub(/ratio=\S+/, '').strip
           return '' if d.empty?
 
           # Prefer explicit FLAW / CORRECTED crumbs; else verdict(score) head.
@@ -1818,6 +1851,55 @@ module PWN
           File.write(LESSONS_FILE, JSON.pretty_generate(opts[:store]))
         end
 
+        private_class_method def self.learning_max_baks(opts = {})
+          n = opts[:max_baks]
+          return n.to_i if n.to_i.positive?
+          return 5 unless defined?(PWN::Env)
+
+          v = PWN::Env.dig(:ai, :learning, :max_baks)
+          v.to_i.positive? ? v.to_i : 5
+        rescue StandardError
+          5
+        end
+
+        public_class_method def self.list_conflicted(opts = {})
+          limit = (opts[:limit] || 50).to_i
+          outcomes(limit: 500).select { |r| r[:status].to_s == 'conflicted' }.first(limit)
+        end
+
+        public_class_method def self.requeue_conflicted(opts = {})
+          dry = opts[:dry_run] ? true : false
+          rows = list_conflicted(limit: 10_000)
+          return { rescored: 0, dry_run: dry } if rows.empty? || dry
+
+          n = 0
+          rows.each do |r|
+            note_outcome(
+              task: "requeue:#{r[:task]}",
+              success: true,
+              score: [r[:score].to_f, 0.7].max,
+              verifier_verdict: :pass,
+              details: 'rescored after verifier precedence',
+              tags: %w[requeue]
+            )
+            n += 1
+          end
+          { rescored: n, dry_run: false }
+        end
+
+        public_class_method def self.compact!(opts = {})
+          max_baks = (opts[:max_baks] || learning_max_baks).to_i
+          max_baks = 5 if max_baks <= 0
+          dir = File.dirname(LEARNING_FILE)
+          baks = Dir[File.join(dir, '*.bak*')].sort_by { |p| File.mtime(p) }.reverse
+          pruned = 0
+          baks.drop(max_baks).each do |path|
+            File.delete(path)
+            pruned += 1
+          end
+          { pruned: pruned, kept: [baks.length, max_baks].min, max_baks: max_baks }
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors
@@ -1839,7 +1921,25 @@ module PWN
               judge_source: 'required - judge source value consumed by #note_outcome',
               predicted: 'optional - predicted value consumed by #note_outcome',
               confidence: 'optional - confidence value consumed by #note_outcome',
-              engine: 'optional - engine value consumed by #note_outcome'
+              engine: 'optional - engine value consumed by #note_outcome',
+              verifier_verdict: 'optional - pass|fail from a deterministic verifier',
+              verdict_class: 'optional - missing_artifact|wrong_path|unverified_claim|scope_miss|partial_coverage|style_only',
+              remediation_hint: 'optional - one-line fix hint'
+            )
+
+            # List outcomes tagged conflicted (verifier PASS vs low judge).
+            #{self}.list_conflicted(
+              limit: 'optional - max entries (defaults to 50)'
+            )
+
+            # Rescore conflicted outcomes after verifier-precedence lands.
+            #{self}.requeue_conflicted(
+              dry_run: 'optional - true to count without writing'
+            )
+
+            # Prune excess *.bak siblings under the learning directory.
+            #{self}.compact!(
+              max_baks: 'optional - newest bak files to keep (defaults to 5)'
             )
 
             # Run outcomes and return its result

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

@@ -64,6 +64,18 @@ module PWN
           unsatisfied incomplete_final empty_final evidence_final
         ].freeze
 
+        public_class_method def self.evidence_satisfied?(opts = {})
+          messages = Array(opts[:messages] || opts[:trace])
+          text = opts[:text].to_s
+          if defined?(TurnFinalizer) && TurnFinalizer.respond_to?(:arbitrate)
+            row = TurnFinalizer.arbitrate(request: opts[:request].to_s, messages: messages, paths: [])
+            return true if row[:complete] && row[:unmet].empty? && row[:ledger].any? { |_p, v| v[:write] && v[:read] }
+          end
+          write_or_read_evidenced?(messages: messages) && !text.strip.empty?
+        rescue StandardError
+          false
+        end
+
         public_class_method def self.debug_on?(opts = {})
           return true if opts[:debug]
           return true if defined?(PWN::Plugins::Log) && PWN::Plugins::Log.debug_enabled?
@@ -394,6 +406,7 @@ module PWN
         # the original request → force synthesis. English tasks are an advisory
         # compass only — an open verify tail must not block a finished ask.
         # The original request is the completion signal.
+
         private_class_method def self.evidence_enough_to_finalize?(opts = {})
           messages = Array(opts[:messages])
           turn_fails = opts[:turn_fails] || {}
@@ -595,7 +608,7 @@ module PWN
             request: request,
             messages: opts[:messages]
           )
-          return true if need == :write && !write_verified?(effects: effects)
+          return true if need == :write && !write_verified?(effects: effects, request: request, messages: opts[:messages])
           return true if need == :browse && !effects.include?(:browse)
           return true if need == :any && !effects.intersect?(%i[write browse eval])
 
@@ -607,10 +620,27 @@ module PWN
         private_class_method def self.write_verified?(opts = {})
           effects = Array(opts[:effects])
           idx = effects.index(:write)
-          return false if idx.nil?
+          if idx
+            tail = effects[(idx + 1)..] || []
+            return true if tail.intersect?(%i[read eval])
+          end
 
-          tail = effects[(idx + 1)..] || []
-          tail.intersect?(%i[read eval])
+          saw_write_argv = false
+          Array(opts[:messages]).each do |msg|
+            next unless msg.is_a?(Hash)
+
+            if msg[:role].to_s == 'assistant' && defined?(Dispatch)
+              Array(msg[:tool_calls]).each do |tc|
+                blob = Dispatch.send(:argv_blob, args: tc.dig(:function, :arguments) || tc.dig('function', 'arguments'))
+                saw_write_argv = true if blob.to_s.match?(Dispatch::WRITE_ARGV_RX)
+              end
+            elsif saw_write_argv && msg[:role].to_s == 'tool'
+              fx = stamped_effect(content: msg[:content])
+              return true if %i[read eval].include?(fx)
+            end
+          end
+
+          false
         rescue StandardError
           false
         end
@@ -875,6 +905,7 @@ module PWN
         end
 
         private_class_method def self.may_finalize?(opts = {})
+          return true if evidence_satisfied?(messages: opts[:messages], text: opts[:text], request: opts[:request])
           return false if incomplete_final?(text: opts[:text], last_iter: false)
           return false if request_unsatisfied?(
             request: opts[:request],
@@ -1678,6 +1709,7 @@ module PWN
             }
             # Ollama + abliterated / weak chat-templates often ignore tools: and
             # answer in prose (or print shell(...) as text). Force native
+
             # tool_calls until at least one tool result is already in history;
             # after that, auto so the model can emit a real final answer.
             # Respect explicit PWN::Env[:ai][:ollama][:tool_choice] override.
@@ -1705,10 +1737,6 @@ module PWN
           end
         end
 
-        # 3.1 — sliding-window history compaction for local models.
-        # Keep: system, original user, PLAN assistant (if any), last K tool
-        # pairs (assistant+tool), and the most recent assistant. Stale tool
-        # bodies are truncated to history_tool_max_chars.
         private_class_method def self.session_chat_history(opts = {})
           return [] unless defined?(PWN::Sessions) && PWN::Sessions.respond_to?(:to_llm_messages)
 
@@ -1831,15 +1859,15 @@ module PWN
 
         private_class_method def self.spill_tool_body(opts = {})
           text = opts[:text].to_s
-          digest = Digest::SHA256.hexdigest(text)[0, 16]
-          dir = HISTORY_SPILL_DIR
+          digest = Digest::SHA256.hexdigest(text)
+          dir = File.join(Dir.home, '.pwn', 'artifacts', 'transcripts', (Thread.current[:pwn_session_id] || 'default').to_s)
           FileUtils.mkdir_p(dir)
-          path = File.join(dir, "#{digest}.txt")
+          path = File.join(dir, "#{digest[0, 12]}.txt")
           File.binwrite(path, text) unless File.file?(path)
           head = text.byteslice(0, 2_048).to_s
           tail = text.bytesize > 3_072 ? text.byteslice(-1_024, 1_024).to_s : ''
           mid = tail.empty? ? '' : "\n...\n#{tail}"
-          "#{head}#{mid}\n[compacted path=#{path} sha256=#{digest} bytes=#{text.bytesize}]"
+          "#{head}#{mid}\n[compacted path=#{path} sha256=#{digest} bytes=#{text.bytesize} ref=#{path}]"
         rescue StandardError
           "[compacted bytes=#{opts[:text].to_s.bytesize}]"
         end
@@ -3002,17 +3030,21 @@ module PWN
                 text: text
               )
                 turn_fails['unsatisfied'] += 1
-                unmet = completion_unmet(request: request, messages: messages)
-                warn "[pwn-ai/loop] original request not evidenced on iter=#{i} unmet=#{unmet.join(',')}; continuing"
-                debug_progress(msg: "bounce unsatisfied unmet=#{unmet.join(',')} snippet=#{debug_snippet(text: text)}")
-                messages << {
-                  role: 'user',
-                  content: "[pwn-ai] The original request is not evidenced yet. unmet=#{unmet.join(',')} " \
-                           'Keep calling CORE_TOOLS (shell, pwn_eval) until that request is ' \
-                           'done or a tool returned failure evidence. pwn-ai does not decide ' \
-                           'authorization. Do not declare completion from a listing or a refusal.'
-                }
-                next
+                if turn_fails['unsatisfied'] >= 2 && evidence_satisfied?(request: request, messages: messages, text: text)
+                  debug_progress(msg: 'nag cap: evidence_satisfied after 2 bounces')
+                else
+                  unmet = completion_unmet(request: request, messages: messages)
+                  warn "[pwn-ai/loop] original request not evidenced on iter=#{i} unmet=#{unmet.join(',')}; continuing"
+                  debug_progress(msg: "bounce unsatisfied unmet=#{unmet.join(',')} snippet=#{debug_snippet(text: text)}")
+                  messages << {
+                    role: 'user',
+                    content: "[pwn-ai] The original request is not evidenced yet. unmet=#{unmet.join(',')} " \
+                             'Keep calling CORE_TOOLS (shell, pwn_eval) until that request is ' \
+                             'done or a tool returned failure evidence. pwn-ai does not decide ' \
+                             'authorization. Do not declare completion from a listing or a refusal.'
+                  }
+                  next
+                end
               end
               debug_progress(msg: "final accepted chars=#{text.to_s.length}")
               quiet_debug_tui!(reason: 'final')
@@ -3143,14 +3175,26 @@ module PWN
           TurnFinalizer.leave_user_path! if defined?(TurnFinalizer)
         end
 
+        public_class_method def self.budget_status(opts = {})
+          t0 = opts[:t0] || Thread.current[:pwn_loop_t0] || Time.now
+          elapsed = Time.now - t0
+          remain = (opts[:remaining_s] || Thread.current[:pwn_loop_budget_s] || 10_800).to_f - elapsed
+          {
+            elapsed_s: elapsed.round,
+            remaining_tool_budget_s: [remain, 0].max.round,
+            mutations_used: Thread.current[:pwn_loop_mutations].to_i,
+            mutations_max: 10,
+            context_tokens_used: Thread.current[:pwn_loop_tokens].to_i,
+            est_max: 128_000
+          }
+        end
+
         # Author(s):: 0day Inc. <support@0dayinc.com>
 
         public_class_method def self.authors
           "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
         end
 
-        # Display Usage for this Module
-
         public_class_method def self.help
           puts "USAGE:
             # Run debug on and return its result
@@ -3158,6 +3202,14 @@ module PWN
               debug: 'optional - debug value consumed by #debug_on?'
             )
 
+            # True when write-then-readback evidence satisfies the original request.
+            #{self}.evidence_satisfied?(
+              messages: 'optional - Array of role/content hashes',
+              trace: 'optional - alias for messages',
+              text: 'optional - final answer text',
+              request: 'optional - original request'
+            )
+
             # True only when the ask needs a live host/file/browser effect. World-knowledge
             #{self}.catalog_lookup?(
               request: 'required - request value consumed by #catalog_lookup?'
@@ -3201,6 +3253,12 @@ module PWN
               force_tools: 'optional - force tools value consumed by #run'
             )
 
+            # Remaining time/token/mutation budget for the current loop.
+            #{self}.budget_status(
+              t0: 'optional - session start Time (defaults to thread t0)',
+              remaining_s: 'optional - override remaining tool budget seconds'
+            )
+
             # Print the AUTHOR(S) string for this module.
             #{self}.authors
           "