pwn 0.5.739 → 0.5.741

data/spec/lib/pwn/ai/agent/dispatch_confirmation_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'yaml'
+require 'tmpdir'
+require 'fileutils'
+
+describe 'PWN::AI::Agent::Dispatch confirmation tiers' do
+  it 'does not execute an exploit-tier tool until the engagement ACK is cached' do
+    Dir.mktmpdir('pwn-ack-dispatch-') do |dir|
+      allow(Dir).to receive(:home).and_return(dir)
+      ran = false
+      PWN::AI::Agent::Registry.discover(force: true)
+      PWN::AI::Agent::Registry.register(
+        name: 'spec_exploit_tier',
+        toolset: 'pwn',
+        schema: {
+          name: 'spec_exploit_tier',
+          description: 'fixture exploit-tier tool',
+          parameters: { type: 'object', properties: { action: { type: 'string' } }, required: %w[action] }
+        },
+        handler: lambda { |_args|
+          ran = true
+          { ran: true }
+        }
+      )
+      scope = File.join(dir, '.pwn', 'scope.yaml')
+      FileUtils.mkdir_p(File.dirname(scope))
+      File.write(scope, YAML.dump('enabled' => false, 'confirmation' => { 'exploit' => 'prompt', 'destructive' => 'prompt', 'read_only' => 'auto', 'active_scan' => 'auto' }))
+      raw = PWN::AI::Agent::Dispatch.call(
+        tool_call: { function: { name: 'spec_exploit_tier', arguments: JSON.generate(action: 'ret2libc') } },
+        engagement_id: 'lab',
+        scope_path: scope
+      )
+      row = JSON.parse(raw, symbolize_names: true)
+      expect(ran).to eq(false)
+      expect(row[:needs_ack]).to eq(true)
+      expect(row[:diff].to_s).to include('spec_exploit_tier')
+      acked = PWN::AI::Agent::Dispatch.call(
+        tool_call: { function: { name: 'spec_exploit_tier', arguments: JSON.generate(action: 'ret2libc') } },
+        engagement_id: 'lab',
+        operator_ack: true,
+        scope_path: scope
+      )
+      expect(JSON.parse(acked, symbolize_names: true)[:success]).to eq(true)
+      expect(ran).to eq(true)
+    ensure
+      PWN::AI::Agent::Registry.instance_variable_get(:@entries).delete('spec_exploit_tier')
+    end
+  end
+end

data/spec/lib/pwn/ai/agent/dispatch_policy_spec.rb

@@ -29,6 +29,57 @@ RSpec.describe PWN::AI::Agent::Dispatch do
     expect(out.dig(:result, :stdout)).to include(' ... ')
   end
 
+  it 'explains an elided command after markdown data and accepts one corrected call' do
+    PWN::AI::Agent::Registry.discover
+    command = "cat <<-'MD'\n# Résumé ... inline prose\n...\n\tMD\n...\n"
+    denied = dispatch('shell', { command: command, timeout: 2 }).fetch(:result)
+    expect(denied).to include(error: 'invalid_payload', code: 'SYNTAX_DENY', rule_id: 'payload.placeholder', match: '...')
+    expect(denied[:offset]).to eq(command.b.rindex("\n...".b) + 1)
+    expect(command.byteslice(denied[:offset], denied[:match].bytesize)).to eq('...')
+    expect(denied[:remedy]).to include('placeholder_ok', 'base64', 'data')
+    expect(denied[:remedy]).to include('does not bypass')
+    corrected_command = command.byteslice(0, denied[:offset])
+    corrected = dispatch('shell', { command: corrected_command, timeout: 2 })
+    expect(corrected.dig(:result, :exit)).to eq(0)
+    expect(corrected.dig(:result, :stdout)).to include("# Résumé ... inline prose\n...\n")
+  end
+
+  it 'preserves decoded byte offsets through base64 and does not present encoding as a validation bypass' do
+    PWN::AI::Agent::Registry.discover
+    command = "cat <<-'MD'\n# Résumé ...\n…\n\tMD\n…\n"
+    args = { encoding: 'base64', data: Base64.strict_encode64(command), timeout: 2 }
+    denied = dispatch('shell', args).fetch(:result)
+    expect(denied[:match]).to eq('…')
+    expect(denied[:offset]).to eq(command.b.rindex('…'.b))
+    expect(denied[:byte_range]).to eq([denied[:offset], denied[:offset] + '…'.bytesize])
+    corrected = dispatch('shell', args.merge(data: Base64.strict_encode64(command.byteslice(0, denied[:offset]))))
+    expect(corrected.dig(:result, :exit)).to eq(0)
+    expect(corrected.dig(:result, :stdout)).to include('…')
+  end
+
+  it 'explains schema invalid_payload errors with the field and correction' do
+    PWN::AI::Agent::Registry.discover
+    denied = dispatch('shell', { command: 'printf ok', timeout: 20_000 })
+    expect(denied).to include(error: 'invalid_payload', rule_id: 'schema.maximum', offset: nil)
+    expect(denied[:match]).to eq('20000')
+    expect(denied[:remedy]).to include('/timeout', '10800')
+  end
+
+  it 'writes Ruby literal ellipses as data and denies a code stub before side effects' do
+    PWN::AI::Agent::Registry.discover
+    path = File.join(@dir, 'document.md')
+    code = "doc_with_ellipsis = <<~DOC\n  # Résumé\n  ...\n  def foo(<3dots>)\nDOC\nFile.write(#{path.inspect}, doc_with_ellipsis)"
+    result = dispatch('pwn_eval', { code: code, timeout: 2 })
+    expect(result.dig(:result, :error)).to be_nil
+    expect(File.read(path)).to eq("# Résumé\n...\ndef foo(<3dots>)\n")
+    File.delete(path)
+    stub = "File.write(#{path.inspect}, 'should not execute'); def foo(<3dots>); end"
+    denied = dispatch('pwn_eval', { code: stub, timeout: 2 }).fetch(:result)
+    expect(denied).to include(error: 'invalid_payload', rule_id: 'payload.placeholder', match: '<3dots>')
+    expect(denied[:offset]).to eq(stub.b.index('<3dots>'))
+    expect(File.exist?(path)).to eq(false)
+  end
+
   it 'loads a YAML-whitelisted plugin method as a callable tool' do
     PWN::AI::Agent::Registry.discover
     entry = PWN::AI::Agent::Registry.lookup(name: 'host_os_type')

data/spec/lib/pwn/ai/agent/loop_spec.rb

@@ -683,11 +683,97 @@ describe PWN::AI::Agent::Loop do # rubocop:disable Metrics/BlockLength
       chunk = src[/if Thread\.current\[:pwn_extinguished\].*?tools_called \+= 1/m]
       expect(chunk).to include('same_n = note_same_payload!')
       expect(chunk.index('note_same_payload!')).to be < chunk.index('Dispatch.call')
+      expect(chunk.index('Dispatch.call')).to be < chunk.index('note_payload_result!')
       expect(chunk).to match(/same_n >= 3/)
       raw = described_class.send(:checkpoint_result, name: 'shell', args: '{"command":"echo same"}')
       expect(JSON.parse(raw)).to include('success' => false, 'checkpoint' => true)
     end
 
+    it 'allows verbatim retries after nonzero exits and checkpoints repeated successes' do
+      Thread.current[:pwn_same_payload] = Hash.new(0)
+      args = { command: 'test -f ready', timeout: 2 }
+      4.times do
+        expect(described_class.send(:note_same_payload!, name: 'shell', args: args)).to eq(1)
+        raw = JSON.generate(success: true, result: { exit: 1, stdout: '', stderr: '' })
+        described_class.send(:note_payload_result!, name: 'shell', args: args, raw: raw)
+        expect(described_class.send(:guard_repeated_failure, name: 'shell', args: args, count: 650, raw: raw, result: raw)).to eq(raw)
+      end
+      expect(described_class.send(:note_same_payload!, name: 'shell', args: args)).to eq(1)
+      described_class.send(:note_payload_result!, name: 'shell', args: args, raw: JSON.generate(success: true, result: { exit: 0 }))
+      expect(described_class.send(:note_same_payload!, name: 'shell', args: args)).to eq(2)
+      expect(described_class.send(:note_same_payload!, name: 'shell', args: args)).to eq(3)
+    ensure
+      Thread.current[:pwn_same_payload] = nil
+      Thread.current[:pwn_extinguished] = nil
+    end
+
+    it 'retries a real failing shell command verbatim until it succeeds without a checkpoint' do
+      PWN::AI::Agent::Registry.discover
+      Thread.current[:pwn_same_payload] = Hash.new(0)
+      Thread.current[:pwn_dispatch_budget] = nil
+      Dir.mktmpdir('retry-checkpoint') do |dir|
+        program = 'p=ARGV.fetch(0); n=File.exist?(p) ? File.read(p).to_i+1 : 1; File.write(p,n); puts n; exit(n<4 ? 7 : 0)'
+        args = { command: "ruby -e '#{program}' #{File.join(dir, 'attempts').inspect}", timeout: 10 }
+        exits = 4.times.map do
+          expect(described_class.send(:note_same_payload!, name: 'shell', args: args)).to eq(1)
+          raw = PWN::AI::Agent::Dispatch.call(scope_policy: { enabled: false }, tool_call: { function: { name: 'shell', arguments: JSON.generate(args) } })
+          described_class.send(:note_payload_result!, name: 'shell', args: args, raw: raw)
+          parsed = JSON.parse(raw)
+          expect(parsed['error']).to be_nil
+          parsed.dig('result', 'exit')
+        end
+        expect(exits).to eq([7, 7, 7, 0])
+        expect(File.read(File.join(dir, 'attempts'))).to eq('4')
+      end
+    ensure
+      Thread.current[:pwn_same_payload] = nil
+      Thread.current[:pwn_dispatch_budget] = nil
+    end
+
+    it 'permits repeated timeout retries while Dispatch increases the same payload deadline' do
+      PWN::AI::Agent::Registry.discover
+      Thread.current[:pwn_same_payload] = Hash.new(0)
+      Thread.current[:pwn_dispatch_budget] = nil
+      entry = PWN::AI::Agent::Registry.lookup(name: 'shell')
+      deadlines = []
+      allow(entry.handler).to receive(:call) do |args|
+        deadlines << args[:timeout]
+        deadlines.length < 4 ? { error: 'timeout after test deadline' } : { exit: 0, stdout: 'finished' }
+      end
+      args = { command: 'unchanged command', timeout: 1 }
+      4.times do
+        expect(described_class.send(:note_same_payload!, name: 'shell', args: args)).to eq(1)
+        raw = PWN::AI::Agent::Dispatch.call(scope_policy: { enabled: false }, tool_call: { function: { name: 'shell', arguments: JSON.generate(args) } })
+        described_class.send(:note_payload_result!, name: 'shell', args: args, raw: raw)
+        expect(JSON.parse(raw)['error']).to be_nil
+        result = described_class.send(:guard_repeated_failure, name: 'shell', args: args, count: 650, raw: raw, result: raw) if deadlines.length < 4
+        expect(result).not_to include('EXTINGUISHED') if result
+      end
+      expect(deadlines).to eq([1, 181, 361, 541])
+      expect(Thread.current[:pwn_dispatch_budget].dig(:chains, 'shell', :active)).to be_nil
+    ensure
+      Thread.current[:pwn_same_payload] = nil
+      Thread.current[:pwn_dispatch_budget] = nil
+      Thread.current[:pwn_extinguished] = nil
+    end
+
+    it 'does not mistake policy denials, checkpoints or stdout text for retryable execution failures' do
+      [
+        { checkpoint: true, result: { exit: 1 } },
+        { error: 'retry_required' },
+        { error: 'budget_exhausted', result: { error: 'timeout' } },
+        { code: 'SCOPE_DENY', result: { exit: 1 } },
+        { success: true, result: { exit: 0, stdout: 'timeout exit_code=1' } },
+        { success: false, error: 'invalid_payload' }
+      ].each do |raw|
+        expect(described_class.send(:retryable_execution_failure?, raw: JSON.generate(raw))).to eq(false)
+      end
+      [{ result: { exit_code: 2 } }, { result: { exit_status: '3' } }, { error: 'Timeout::Error: expired' }, { result: { timed_out: true } }].each do |raw|
+        expect(described_class.send(:retryable_execution_failure?, raw: raw)).to eq(true)
+      end
+      expect(described_class.send(:retryable_execution_failure?, raw: 'timeout in plain text')).to eq(false)
+    end
+
     it 'records a timeout increment mistake instead of treating success:true as ok' do
       tmp = Dir.mktmpdir
       stub_const('PWN::AI::Agent::Mistakes::MISTAKES_FILE', File.join(tmp, 'mistakes.json'))

data/spec/lib/pwn/ai/agent/registry_spec.rb

@@ -17,7 +17,7 @@ describe PWN::AI::Agent::Registry do
   it 'CORE_TOOLS is recall-then-act including skills_recall before pwn_eval' do
     expect(described_class.const_defined?(:ACT_PREFERENCE)).to eq false
     expect(described_class::CORE_TOOLS).to eq(
-      %w[memory_recall session_recall skills_recall pwn_eval shell mistakes_record mistakes_resolve learning_note_outcome memory_remember skills_update]
+      %w[memory_recall session_recall skills_recall pwn_eval shell mistakes_record mistakes_resolve learning_note_outcome memory_remember skills_update artifact_read artifact_grep job_run job_status job_tail job_result job_kill]
     )
     expect(described_class::DEFAULT_PREFERENCE).to eq(described_class::CORE_TOOLS)
     expect(described_class::DEFAULT_PREFERENCE).not_to include('sessions_view')

data/spec/lib/pwn/ai/agent/result_spec.rb

@@ -1,8 +1,91 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'tmpdir'
 
 describe PWN::AI::Agent::Result do
+  around do |example|
+    Dir.mktmpdir('pwn-result-') do |dir|
+      @artifact_root = dir
+      example.run
+    end
+  end
+
+  before { stub_const('PWN::Plugins::ArtifactRegistry::ROOT', @artifact_root) }
+
+  it 'spills real Dispatch output before redaction while retaining failure status' do
+    PWN::AI::Agent::Registry.discover
+    file = File.join(@artifact_root, 'strings.txt')
+    size = 50 * 1024 * 1024
+    row = "strings payload\n"
+    content = (row * ((size / row.bytesize) + 1)).byteslice(0, size)
+    File.binwrite(file, content)
+    response = JSON.parse(PWN::AI::Agent::Dispatch.call(
+                            tool_call: { function: { name: 'shell', arguments: { command: "cat #{file}; exit 7", timeout: 5 } } },
+                            scope_path: File.join(@artifact_root, 'absent.yml')
+                          ))
+    result = response.fetch('result')
+    expect(result['exit']).to eq(7)
+    expect(result['artifact']).to be_a(Hash)
+    saved = JSON.parse(File.binread(result['artifact']['path']))
+    expect(saved['stdout']).to eq(content)
+    expect(saved['exit']).to eq(7)
+    expect(PWN::AI::Agent::Loop.send(:retryable_execution_failure?, raw: JSON.generate(response))).to eq(true)
+  end
+
+  it 'pages and searches through actual tool schemas within the smallest inline budget' do
+    PWN::AI::Agent::Registry.discover
+    allow(PWN::Env).to receive(:dig).and_call_original
+    allow(PWN::Env).to receive(:dig).with(:ai, :agent, :artifact_max_tokens).and_return(1024)
+    raw = ("\x00\xff".b * 4096) + "needle-at-end\n".b
+    summary = JSON.parse(described_class.condition(content: raw, session_id: 'roundtrip'))
+    handle = summary.fetch('artifact').fetch('handle')
+    reconstructed = +''.b
+    offset = 0
+    messages = [{ role: 'system', content: 'Read the saved bytes.' }, { role: 'user', content: 'Inspect the dump.' }]
+    loop do
+      tc = { id: "page-#{offset}", function: { name: 'artifact_read', arguments: { handle: handle, offset: offset, length: 50_000_000 } } }
+      response = PWN::AI::Agent::Dispatch.call(tool_call: tc, scope_path: File.join(@artifact_root, 'absent.yml'))
+      safe = described_class.condition(content: response)
+      expect(safe.bytesize).to be <= described_class.token_limit
+      page = JSON.parse(safe).fetch('result')
+      expect(page).not_to have_key('artifact')
+      reconstructed << Base64.strict_decode64(page.fetch('body'))
+      messages << { role: 'assistant', content: '', tool_calls: [tc] }
+      messages << { role: 'tool', tool_call_id: tc[:id], content: safe }
+      PWN::AI::Agent::Loop.send(:compact_history!, messages: messages)
+      expect(messages.length).to be <= 14
+      break if page.fetch('eof')
+
+      expect(page.fetch('next_offset')).to be > offset
+      offset = page.fetch('next_offset')
+    end
+    expect(reconstructed).to eq(raw)
+    response = PWN::AI::Agent::Dispatch.call(
+      tool_call: { function: { name: 'artifact_grep', arguments: { handle: handle, regex: 'needle-at-end' } } },
+      scope_path: File.join(@artifact_root, 'absent.yml')
+    )
+    safe = described_class.condition(content: response)
+    expect(safe.bytesize).to be <= described_class.token_limit
+    expect(JSON.parse(safe).dig('result', 'matches')).not_to be_empty
+  end
+
+  it 'preserves oversized results byte for byte instead of truncating' do
+    raw = ("strings row\n" * 10_000).b + "\x00\xff".b
+    summary = JSON.parse(described_class.condition(content: raw, session_id: 'paging-test'))
+    expect(summary['artifact']['handle']).to match(%r{\Apaging-test/[0-9a-f]{8}\.bin\z})
+    expect(File.binread(summary['artifact']['path'])).to eq(raw)
+    expect(summary['artifact']['sha256']).to eq(Digest::SHA256.hexdigest(raw))
+    expect(summary['summary']).to include('artifact_read', 'artifact_grep')
+    expect(JSON.generate(summary).bytesize).to be < described_class.token_limit
+  end
+
+  it 'spills above the configured conservative token bound' do
+    allow(PWN::Env).to receive(:dig).and_call_original
+    allow(PWN::Env).to receive(:dig).with(:ai, :agent, :artifact_max_tokens).and_return(2048)
+    expect(described_class.condition(content: 'x' * 2048)).to eq('x' * 2048)
+    expect(JSON.parse(described_class.condition(content: 'x' * 2049))['artifact']['bytes']).to eq(2049)
+  end
   it 'should display information for authors' do
     authors_response = PWN::AI::Agent::Result
     expect(authors_response).to respond_to :authors
@@ -21,6 +104,6 @@ describe PWN::AI::Agent::Result do
     big = 'x' * 10_000
     out = described_class.condition(content: big)
     expect(out.length).to be < 10_000
-    expect(out).to include('truncated')
+    expect(out).to include('artifact_read')
   end
 end

data/spec/lib/pwn/ai/agent/task_dag_spec.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'yaml'
+require 'json'
+require 'tmpdir'
+require 'fileutils'
+require 'timeout'
+
+describe PWN::AI::Agent::TaskDAG do
+  it 'should display information for authors' do
+    expect(described_class).to respond_to :authors
+  end
+
+  it 'should display information for existing help method' do
+    expect(described_class).to respond_to :help
+  end
+
+  it 'emits a YAML DAG with steps, tool, args, side-effect tier, and dependencies' do
+    expect(PWN::AI::Agent::Dispatch).not_to receive(:call)
+    expect(PWN::AI::Agent::Loop).not_to receive(:run)
+    dag = described_class.plan(request: 'echo one then echo two')
+    yaml = YAML.dump(JSON.parse(JSON.generate(dag)))
+    parsed = YAML.safe_load(yaml)
+    steps = parsed['steps'] || parsed[:steps]
+    expect(steps.length).to be >= 2
+    first = steps.first.transform_keys(&:to_s)
+    expect(first).to include('id', 'tool', 'args', 'side_effect', 'dependencies')
+    expect(%w[read_only active_scan exploit destructive]).to include(first['side_effect'])
+  end
+
+  it 'skips completed steps after a killed executor is resumed' do
+    Dir.mktmpdir('pwn-dag-') do |dir|
+      log = File.join(dir, 'log.txt')
+      dag = {
+        'version' => 1,
+        'request' => 'two-step',
+        'steps' => [
+          { 'id' => 's1', 'tool' => 'shell', 'args' => { 'command' => "printf first >> #{log}" }, 'side_effect' => 'read_only', 'dependencies' => [] },
+          { 'id' => 's2', 'tool' => 'shell', 'args' => { 'command' => "printf second >> #{log}" }, 'side_effect' => 'read_only', 'dependencies' => ['s1'] }
+        ]
+      }
+      PWN::AI::Agent::Registry.discover(force: true)
+      load '/opt/pwn/lib/pwn/ai/agent/tools/shell.rb'
+      run_id = 'kill-resume'
+      pid = Process.fork do
+        described_class.execute(dag: dag, run_id: run_id, root: dir, halt_after: 's1')
+        exit!
+      end
+      begin
+        Timeout.timeout(10) do
+          Process.wait(pid)
+        end
+      rescue Timeout::Error
+        Process.kill('KILL', pid)
+        Process.wait(pid)
+      end
+      expect(File.read(log)).to eq('first')
+      described_class.execute(run_id: run_id, root: dir)
+      expect(File.read(log)).to eq('firstsecond')
+    end
+  end
+end

data/spec/lib/pwn/ai/agent/tool_guard_spec.rb

@@ -29,6 +29,38 @@ describe PWN::AI::Agent::ToolGuard do
   end
 
   describe '.placeholder?' do
+    it 'ignores shell multiline quoted data and tab-stripped or quoted-delimiter heredocs' do
+      ["printf '%s' '\n...\n'", "printf '%s' \"\n…\n\"", "cat <<-'MD'\n...\n\tMD\n", "cat <<'DOC-END'\n...\nDOC-END\n", "cat <<A <<\"B\"\n...\nA\n…\nB\n"].each do |text|
+        expect(described_class.placeholder?(text: text, language: :shell)).to eq(false), text
+      end
+    end
+
+    it 'uses Ruby tokens to distinguish literal content and real syntax from code stubs' do
+      ["File.write(path, \"line\n...\n\")", "File.write(path, %q{\n...\n})", "File.write(path, <<~DOC)\n  ...\nDOC\n", 'x = 1...3', 'def foo(...); bar(...); end'].each do |text|
+        expect(described_class.placeholder?(text: text, language: :ruby)).to eq(false), text
+      end
+      ['def foo(<3dots>); end', "def foo(...)\n", "def foo\n...\nend"].each do |text|
+        expect(described_class.placeholder?(text: text, language: :ruby)).to eq(true), text
+      end
+    end
+
+    it 'keeps comments and escaped shell words as data but detects code after a heredoc' do
+      ["# ...\nprintf ok", 'printf %s \\...', 'cat <<< "..."', "cat <<D\\OC\n...\nDOC\n"].each do |text|
+        expect(described_class.placeholder?(text: text)).to eq(false), text
+      end
+      ['printf ok; ...', "cat <<-'EOF'\n...\n\tEOF\n...", '…', '<...>'].each do |text|
+        expect(described_class.placeholder?(text: text)).to eq(true), text
+      end
+    end
+
+    it 'locates Ruby stubs in bytes without selecting ellipses from literal tokens' do
+      text = 'doc = %q{é ...}; def foo(<3dots>); end'
+      match = described_class.placeholder_match(text: text, language: :ruby)
+      expect(match[:offset]).to eq(text.b.index('<3dots>'))
+      expect(text.byteslice(match[:offset], match[:match].bytesize)).to eq('<3dots>')
+      expect(described_class.placeholder?(text: 'def foo(<3dots>); end', language: :ruby, placeholder_ok: true)).to eq(false)
+    end
+
     it 'matches ellipsis placeholders' do
       expect(described_class.placeholder?(text: '...')).to be true
       expect(described_class.placeholder?(text: '{...}')).to be true
@@ -56,6 +88,13 @@ describe PWN::AI::Agent::ToolGuard do
   end
 
   describe '.coerce_args' do
+    it 'locates the actual unsupported shell syntax after quoted UTF-8 literals' do
+      text = "printf 'é PIPESTATUS'; echo ${PIPESTATUS[0]}"
+      matched = described_class.bashism_match(text: text)
+      expect(matched).to include(rule_id: 'payload.shell_syntax', match: 'PIPESTATUS')
+      expect(matched[:offset]).to eq(text.b.rindex('PIPESTATUS'))
+    end
+
     it 'aliases value onto the first required key' do
       args = described_class.coerce_args(args: { value: 'id' }, required: %w[command])
       expect(args[:command]).to eq('id')
@@ -82,6 +121,15 @@ describe PWN::AI::Agent::ToolGuard do
       out = described_class.invalid_payload(hint: 'ellipsis', offending_token: '...', text: 'foo ... bar')
       expect(out[:byte_range]).to eq([4, 7])
     end
+
+    it 'returns a matched substring, byte offset and actionable remedy for UTF-8 payloads' do
+      text = 'é …'
+      out = described_class.invalid_payload(hint: 'ellipsis', offending_token: '…', text: text)
+      expect(out[:match]).to eq('…')
+      expect(out[:offset]).to eq('é '.bytesize)
+      expect(text.byteslice(out[:offset], out[:match].bytesize)).to eq(out[:match])
+      expect(out[:remedy]).not_to be_empty
+    end
   end
 
   describe '.host_load / .deadline_s' do

data/spec/lib/pwn/ai/agent/tools/ai_sandbox_spec.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'fileutils'
+require 'json'
+
+describe 'PWN::AI::Agent::Tools sandbox strict' do
+  before(:all) do
+    PWN::AI::Agent::Registry.discover(force: true)
+    load '/opt/pwn/lib/pwn/ai/agent/tools/shell.rb'
+    load '/opt/pwn/lib/pwn/ai/agent/tools/ruby_eval.rb'
+  end
+
+  it 'raises a sandbox violation for shell rm and pwn_eval FileUtils.rm_rf without touching disk' do
+    root = '/tmp/fake_root'
+    FileUtils.mkdir_p(root)
+    marker = File.join(root, 'keep')
+    File.write(marker, 'safe')
+    begin
+      stub_const('PWN::Env', { ai_sandbox: 'strict' })
+      shell = PWN::AI::Agent::Dispatch.call(
+        tool_call: { function: { name: 'shell', arguments: JSON.generate(command: 'rm -rf /tmp/fake_root') } },
+        scope_path: File.join(Dir.tmpdir, 'absent.yaml')
+      )
+      ruby = PWN::AI::Agent::Dispatch.call(
+        tool_call: { function: { name: 'pwn_eval', arguments: JSON.generate(code: "FileUtils.rm_rf('/tmp/fake_root')") } },
+        scope_path: File.join(Dir.tmpdir, 'absent.yaml')
+      )
+      expect(JSON.parse(shell, symbolize_names: true).fetch(:result)[:error].to_s).to match(/sandbox violation/i)
+      expect(JSON.parse(ruby, symbolize_names: true).fetch(:result)[:error].to_s).to match(/sandbox violation/i)
+      expect(File.file?(marker)).to be true
+    ensure
+      FileUtils.rm_rf(root)
+    end
+  end
+end

data/spec/lib/pwn/ai/agent/tools/binary_triage_spec.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'tmpdir'
+require 'json'
+require 'open3'
 
 describe 'PWN::AI::Agent::Tools binary_triage' do
   before(:all) do
@@ -11,4 +14,22 @@ describe 'PWN::AI::Agent::Tools binary_triage' do
   it 'registers expected tool names' do
     expect(PWN::AI::Agent::Registry.lookup(name: 'binary_triage')).not_to be_nil
   end
+
+  it 'returns mitigations and attack surface from one Dispatch call on a stripped ELF' do
+    Dir.mktmpdir('pwn-triage-tool-') do |dir|
+      allow(Dir).to receive(:home).and_return(dir)
+      stub_const('PWN::Plugins::ArtifactRegistry::ROOT', File.join(dir, 'artifacts'))
+      source = File.join(dir, 'fixture.c')
+      path = File.join(dir, 'fixture')
+      File.write(source, "#include <stdio.h>\nint main(void) { puts(\"https://example.test\"); return 0; }\n")
+      out, status = Open3.capture2e('cc', '-O0', '-fstack-protector-all', '-o', path, source)
+      expect(status.success?).to eq(true), out
+      Open3.capture2e('strip', '--strip-all', path)
+      raw = PWN::AI::Agent::Dispatch.call(tool_call: { function: { name: 'binary_triage', arguments: JSON.generate(path: path, session_id: 'fixture') } }, scope_path: File.join(dir, 'absent.yaml'))
+      row = JSON.parse(raw, symbolize_names: true).fetch(:result)
+      expect(row[:protections]).to include(:nx, :pie, :relro, :canary, :cfi)
+      expect(row[:handle].to_s).to include('fixture/')
+      expect(JSON.generate(row[:interesting_strings])).to include('https://example.test')
+    end
+  end
 end

data/spec/lib/pwn/ai/agent/tools/browser_goto_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+
+describe 'PWN::AI::Agent::Tools browser_goto' do
+  before(:all) do
+    PWN::AI::Agent::Registry.discover(force: true)
+    load '/opt/pwn/lib/pwn/ai/agent/tools/browser_goto.rb'
+  end
+
+  it 'registers expected tool names' do
+    expect(PWN::AI::Agent::Registry.lookup(name: 'browser_goto')).not_to be_nil
+  end
+
+  it 'records an auth-bypass finding with pixel and HAR proof in one Dispatch call' do
+    Dir.mktmpdir('pwn-tb-tool-') do |dir|
+      allow(Dir).to receive(:home).and_return(dir)
+      stub_const('PWN::Plugins::ArtifactRegistry::ROOT', File.join(dir, 'artifacts'))
+      stub_const('PWN::Plugins::Findings::FILE', File.join(dir, 'findings.jsonl'))
+      har = JSON.generate(
+        'log' => {
+          'version' => '1.2',
+          'creator' => { 'name' => 'fixture', 'version' => '1' },
+          'entries' => [{ 'request' => { 'method' => 'GET', 'url' => 'https://app.example.test/admin' } }]
+        }
+      )
+      raw = PWN::AI::Agent::Dispatch.call(
+        tool_call: {
+          function: {
+            name: 'browser_goto',
+            arguments: JSON.generate(
+              url: 'https://app.example.test/admin',
+              title: 'Auth bypass',
+              severity: 'high',
+              html: '<html><h1>Dashboard</h1></html>',
+              har: har,
+              session_id: 'web'
+            )
+          }
+        },
+        scope_path: File.join(dir, 'absent.yaml')
+      )
+      row = JSON.parse(raw, symbolize_names: true).fetch(:result)
+      finding = row[:finding]
+      expect(finding[:title]).to match(/auth bypass/i)
+      arts = Array(finding[:poc_artifacts]) + Array(finding[:evidence_artifacts]).flat_map { |item| [item[:path], item[:stored]] }
+      shot = arts.find { |path| File.file?(path.to_s) && File.binread(path).b.start_with?("\x89PNG".b) }
+      har_path = arts.find { |path| File.file?(path.to_s) && File.read(path).include?('/admin') }
+      expect(shot).not_to be_nil
+      expect(har_path).not_to be_nil
+      stored = PWN::Plugins::Findings.report
+      expect(stored.first[:title]).to match(/auth bypass/i)
+    end
+  end
+end

data/spec/lib/pwn/ai/agent/tools/exploitdev_spec.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'tmpdir'
+require 'json'
+require 'open3'
 
 describe 'PWN::AI::Agent::Tools exploitdev' do
   before(:all) do
@@ -11,4 +14,43 @@ describe 'PWN::AI::Agent::Tools exploitdev' do
   it 'registers expected tool names' do
     expect(PWN::AI::Agent::Registry.lookup(name: 'exploitdev')).not_to be_nil
   end
+
+  it 'builds a ret2libc chain end-to-end through Dispatch' do
+    Dir.mktmpdir('pwn-ret2libc-tool-') do |dir|
+      src = File.join(dir, 'vuln.c')
+      bin = File.join(dir, 'vuln')
+      File.write(src, <<~C)
+        #include <stdio.h>
+        #include <stdlib.h>
+        #include <unistd.h>
+        char cmd[] = "echo RET2LIBC_OK";
+        void keep(void) { __asm__ volatile("pop %rdi; ret"); }
+        int main(int argc, char **argv) {
+          char buf[64];
+          (void)argv;
+          if (argc > 100) { system(cmd); keep(); }
+          read(0, buf, 256);
+          return 0;
+        }
+      C
+      out, status = Open3.capture2e('cc', '-O0', '-fno-stack-protector', '-no-pie', '-o', bin, src)
+      expect(status.success?).to eq(true), out
+      raw = PWN::AI::Agent::Dispatch.call(
+        tool_call: { function: { name: 'exploitdev', arguments: JSON.generate(action: 'ret2libc', path: bin, offset: 72, extra: 'cmd') } },
+        scope_path: File.join(dir, 'absent.yaml')
+      )
+      row = JSON.parse(raw, symbolize_names: true).fetch(:result)
+      expect(row[:payload]).not_to be_empty
+      expect(row[:plt].keys.map(&:to_s)).to include('system')
+      expect(row[:pop_rdi]).to be_a(Integer)
+      packed = [row[:payload_hex] || row['payload_hex']].pack('H*')
+      packed = row[:payload].to_s if packed.empty?
+      io = PWN::Plugins::ExploitDev.io(cmd: [bin], pty: false)
+      PWN::Plugins::ProcessTube.send_raw(id: io[:id], bytes: packed)
+      out = PWN::Plugins::ProcessTube.recvuntil(id: io[:id], until: 'RET2LIBC_OK', timeout: 3)
+      expect(out.to_s).to include('RET2LIBC_OK')
+    ensure
+      PWN::Plugins::ProcessTube.close(id: io[:id]) if defined?(io) && io
+    end
+  end
 end