pwn 0.5.739 → 0.5.741

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

@@ -12,9 +12,38 @@ describe 'PWN::AI::Agent::Tools finding_record' do
     handler = PWN::AI::Agent::Registry.lookup(name: 'finding_record').handler
     expect { handler.call('title' => 'fixture', 'poc_artifacts' => ['/tmp/legacy']) }.to raise_error(ArgumentError)
     fields = PWN::AI::Agent::Registry.lookup(name: 'finding_record').schema[:parameters][:properties]
-    expect(fields.keys).to include(:cwe, :cvss_score, :cvss_vector, :evidence_paths, :attack_chain_refs, :remediation, :confidence)
+    expect(fields.keys).to include(:cwe, :cvss_score, :cvss_vector, :evidence_paths, :artifact_handles, :severity_justification, :reproduction_steps, :attack_chain_refs, :remediation, :confidence)
     contract = PWN::AI::Agent::Registry.lookup(name: 'finding_record').schema[:parameters][:anyOf]
-    expect(contract.last[:required]).to include('poc', 'cwe', 'cvss_score', 'evidence_paths')
+    expect(contract.last[:required]).to include('poc', 'cwe', 'cvss_score', 'severity_justification', 'reproduction_steps')
+  end
+
+  it 'accepts handle-only findings through the registered schema and handler' do
+    Dir.mktmpdir do |dir|
+      allow(Dir).to receive(:home).and_return(dir)
+      stub_const('PWN::Plugins::Findings::FILE', File.join(dir, 'findings.jsonl'))
+      stub_const('PWN::Plugins::ArtifactRegistry::ROOT', File.join(dir, 'artifacts'))
+      artifact = PWN::Plugins::ArtifactRegistry.spill(bytes: 'puts :fixture', session_id: 'fixture')
+      args = { title: 'Fixture exposure', cwe: 'CWE-200', cvss_vector: 'CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:N/A:N',
+               cvss_score: 5.3, affected_asset: 'local fixture', poc: 'ruby poc.rb', attack_chain_refs: [],
+               remediation: 'Restrict access.', confidence: 0.9, artifact_handles: [{ handle: artifact[:handle], kind: 'poc', label: 'poc.rb' }],
+               severity_justification: 'Read-only data exposure; no availability impact demonstrated.',
+               reproduction_steps: ['Start the fixture.', 'Run ruby poc.rb and inspect its output.'] }
+      tool = PWN::AI::Agent::Registry.lookup(name: 'finding_record')
+      schema = JSONSchemer.schema(JSON.parse(JSON.generate(tool.schema[:parameters])))
+      expect(schema.valid?(JSON.parse(JSON.generate(args)))).to be(true)
+      row = tool.handler.call(JSON.parse(JSON.generate(args)))
+      expect(row[:evidence_artifacts].first).to include(handle: artifact[:handle], sha256: artifact[:sha256])
+      expect(row[:reproduction_steps]).to eq(args[:reproduction_steps])
+      dispatched = JSON.parse(PWN::AI::Agent::Dispatch.call(
+                                tool_call: { function: { name: 'finding_record', arguments: JSON.generate(args) } },
+                                scope_path: File.join(dir, 'absent.yaml'), session_id: 'fixture'
+                              ), symbolize_names: true)
+      expect(dispatched.dig(:result, :evidence_artifacts, 0)).to include(handle: artifact[:handle], sha256: artifact[:sha256])
+      %i[severity_justification reproduction_steps].each do |key|
+        expect(schema.valid?(JSON.parse(JSON.generate(args.except(key))))).to be(false)
+        expect { tool.handler.call(args.except(key)) }.to raise_error(ArgumentError, /#{key}/)
+      end
+    end
   end
 
   it 'registers expected tool names' do
@@ -22,8 +51,23 @@ describe 'PWN::AI::Agent::Tools finding_record' do
     expect(PWN::AI::Agent::Registry.lookup(name: 'finding_report')).not_to be_nil
   end
 
+  it 'exposes directed enables links and existing-finding link updates' do
+    schema = PWN::AI::Agent::Registry.lookup(name: 'finding_record').schema[:parameters]
+    expect(schema[:properties][:enables]).to include(type: 'array', uniqueItems: true)
+    validator = JSONSchemer.schema(JSON.parse(JSON.generate(schema)))
+    expect(validator.valid?({ 'op' => 'link', 'id' => 'ssrf', 'enables' => ['admin'] })).to be(true)
+    expect(validator.valid?({ 'op' => 'link', 'id' => 'ssrf' })).to be(false)
+    expect(validator.valid?({ 'op' => 'link', 'id' => 'ssrf', 'enables' => %w[admin admin] })).to be(false)
+  end
+
   it 'exposes verify retest and chain_impact operations' do
     fields = PWN::AI::Agent::Registry.lookup(name: 'finding_record').schema[:parameters][:properties]
     expect(fields[:op][:enum]).to include('verify', 'retest', 'chain_impact', 'gaps')
+    schema = JSONSchemer.schema(JSON.parse(JSON.generate(PWN::AI::Agent::Registry.lookup(name: 'finding_record').schema[:parameters])))
+    %w[verify retest].each do |op|
+      expect(schema.valid?({ 'op' => op, 'id' => 'fixture', 'kind' => 'script', 'execution_log' => '/tmp/output.log', 'impact' => 'fixture impact' })).to be(true)
+    end
+    expect(schema.valid?({ 'op' => 'gaps' })).to be(true)
+    expect(schema.valid?({ 'op' => 'chain_impact', 'ids' => %w[parent child], 'combined_impact_path' => '/tmp/chain.txt' })).to be(true)
   end
 end

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

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'shellwords'
+require 'json'
+require 'tmpdir'
+require 'fileutils'
+require 'base64'
 
 describe 'PWN::AI::Agent::Tools fuzz_campaign' do
   before(:all) do
@@ -11,4 +16,45 @@ describe 'PWN::AI::Agent::Tools fuzz_campaign' do
   it 'registers expected tool names' do
     expect(PWN::AI::Agent::Registry.lookup(name: 'fuzz_campaign')).not_to be_nil
   end
+
+  it 'starts AFL with a durable six-hour supervisor and correctly quoted paths' do
+    expect(PWN::Plugins::Jobs).to receive(:start).with(hash_including(max_runtime: 21_600, idempotency_key: 'afl-one', session_id: 'session-one')) do |opts|
+      argv = Shellwords.split(opts[:command])
+      expect(argv.any? { |part| part.include?('PWN::Plugins::AFLplusplus.campaign') }).to eq(true)
+      payload = JSON.parse(Base64.decode64(argv.last), symbolize_names: true)
+      expect(payload[:in_dir]).to eq('/tmp/input dir')
+      expect(payload[:out_dir]).to eq('/tmp/output dir')
+      expect(payload[:target]).to include('/tmp/target program')
+      { id: '012345abcdef' }
+    end
+    tool = PWN::AI::Agent::Registry.lookup(name: 'fuzz_campaign')
+    expect(tool.handler.call(action: 'start', in_dir: '/tmp/input dir', out_dir: '/tmp/output dir', target: '"/tmp/target program" @@', max_runtime: 21_600, session_id: 'session-one', idempotency_key: 'afl-one')).to include(id: '012345abcdef')
+  end
+
+  it 'status auto-triages unique crashes without a second tool call' do
+    Dir.mktmpdir('pwn-fuzz-status-') do |dir|
+      crashes = File.join(dir, 'crashes')
+      FileUtils.mkdir_p(crashes)
+      File.binwrite(File.join(crashes, 'id:000000,sig:11'), 'CRASH')
+      allow(PWN::Plugins::Jobs).to receive(:status).and_return(id: 'job1', status: 'COMPLETED')
+      allow(PWN::Plugins::GDBMI).to receive(:run_to_crash).and_return(signal: 'SIGSEGV', pc: '0x1', fault_addr: '0x1', backtrace: ['main'])
+      allow(PWN::Plugins::BinaryParser).to receive(:triage).and_return(file_type: 'elf')
+      allow(PWN::Plugins::ExploitDev).to receive(:from_crash).and_return(offset: 8)
+      tool = PWN::AI::Agent::Registry.lookup(name: 'fuzz_campaign')
+      row = tool.handler.call(action: 'status', id: 'job1', out_dir: dir, target: '/bin/true')
+      expect(row[:triage][:unique].length).to eq(1)
+      expect(row[:triage][:triaged].first).to include(:crash, :backtrace_hash)
+      expect(row[:triage][:pipeline]).to eq('pwn-re-003')
+    end
+  end
+
+  it 'starts a libFuzzer campaign through the same Jobs supervisor' do
+    expect(PWN::Plugins::Jobs).to receive(:start) do |opts|
+      payload = JSON.parse(Base64.decode64(Shellwords.split(opts[:command]).last), symbolize_names: true)
+      expect(payload[:engine].to_s).to include('libfuzzer')
+      { id: 'libf1' }
+    end
+    tool = PWN::AI::Agent::Registry.lookup(name: 'fuzz_campaign')
+    expect(tool.handler.call(action: 'start', engine: 'libfuzzer', in_dir: '/tmp/in', out_dir: '/tmp/out', target: '/tmp/fuzzme')).to include(id: 'libf1')
+  end
 end

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

@@ -15,4 +15,56 @@ describe 'PWN::AI::Agent::Tools job_run' do
     expect(PWN::AI::Agent::Registry.lookup(name: 'job_tail')).not_to be_nil
     expect(PWN::AI::Agent::Registry.lookup(name: 'job_kill')).not_to be_nil
   end
+
+  it 'forwards a six-hour runtime independently of dispatch timeout accounting' do
+    expect(PWN::Plugins::Jobs).to receive(:start).with(hash_including(command: 'printf scan', max_runtime: 21_600, cwd: '/tmp', idempotency_key: 'campaign-one')).and_return(id: '012345abcdef', status: 'RUNNING')
+    ledger = {}
+    response = JSON.parse(PWN::AI::Agent::Dispatch.call(
+                            tool_call: { function: { name: 'job_run', arguments: { command: 'printf scan', max_runtime: 21_600, cwd: '/tmp', idempotency_key: 'campaign-one' } } },
+                            budget_ledger: ledger
+                          ))
+    expect(response.dig('result', 'id')).to eq('012345abcdef')
+    expect(response).not_to have_key('budget')
+    expect(ledger).to be_empty
+  end
+
+  it 'tails by byte cursor with a bounded page and lets a new session discover jobs' do
+    reader = PWN::AI::Agent::Registry.lookup(name: 'job_tail')
+    expect(PWN::Plugins::Jobs).to receive(:tail).with(hash_including(id: '012345abcdef', offset: 17, length: PWN::AI::Agent::Result.page_length)).and_return(next_offset: 23, body: 'output')
+    expect(reader.handler.call(id: '012345abcdef', offset: 17, length: 50_000_000)).to include(next_offset: 23)
+    expect(PWN::Plugins::Jobs).to receive(:list).with(limit: 20).and_return([{ id: '012345abcdef' }])
+    expect(PWN::AI::Agent::Registry.lookup(name: 'job_status').handler.call({})).to include(id: '012345abcdef')
+  end
+
+  it 'routes predicted long shell work before Dispatch injects a blocking timeout' do
+    allow(PWN::AI::Agent::ToolGuard).to receive(:auto_job?).with(payload: 'printf slow').and_return(true)
+    expect(PWN::Plugins::Jobs).to receive(:start).with(hash_including(command: 'printf slow')).and_return(id: '012345abcdef', status: 'RUNNING')
+    ledger = {}
+    out = JSON.parse(PWN::AI::Agent::Dispatch.call(tool_call: { function: { name: 'shell', arguments: { command: 'printf slow' } } }, budget_ledger: ledger))
+    expect(out.dig('result', 'id')).to eq('012345abcdef')
+    expect(ledger).to be_empty
+  end
+
+  it 'runs a real serialized launch with environment overrides and incrementally retrieves its result' do
+    Dir.mktmpdir('pwn-job-tool-') do |root|
+      stub_const('PWN::Plugins::Jobs::JOBS_DIR', root)
+      invoke = lambda do |name, args|
+        JSON.parse(PWN::AI::Agent::Dispatch.call(tool_call: { function: { name: name, arguments: JSON.generate(args) } }), symbolize_names: true)
+      end
+      launched = invoke.call('job_run', command: 'printf "$PWN_JOB_TEST"', env: { PWN_JOB_TEST: 'supervised-output' }, max_runtime: 5, cwd: root)
+      id = launched.fetch(:result).fetch(:id)
+      Timeout.timeout(10) do
+        loop do
+          state = invoke.call('job_status', id: id).fetch(:result)
+          break if state[:status] != 'RUNNING'
+
+          sleep 0.05
+        end
+      end
+      expect(invoke.call('job_status', id: id).fetch(:result)).to include(status: 'COMPLETED', exit_code: 0)
+      page = invoke.call('job_tail', id: id, offset: 0).fetch(:result)
+      expect(page).to include(body: 'supervised-output', next_offset: 17)
+      expect(invoke.call('job_tail', id: id, offset: page[:next_offset]).dig(:result, :bytes)).to eq(0)
+    end
+  end
 end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+
+describe 'PWN::AI::Agent::Tools loot_query' do
+  before(:all) do
+    PWN::AI::Agent::Registry.discover(force: true)
+    load '/opt/pwn/lib/pwn/ai/agent/tools/loot_query.rb'
+  end
+
+  it 'registers expected tool names' do
+    expect(PWN::AI::Agent::Registry.lookup(name: 'loot_query')).not_to be_nil
+  end
+
+  it 'returns recon creds for lateral-movement planning in one Dispatch call' do
+    Dir.mktmpdir('pwn-loot-tool-') do |dir|
+      allow(Dir).to receive(:home).and_return(dir)
+      PWN::Plugins::Vault.store(
+        secret: 'hunter2',
+        username: 'admin',
+        host: 'app.example.test',
+        service: 'ssh',
+        source: 'recon',
+        where: 'banner:22',
+        finding_id: 'f00bar',
+        engagement: 'lab'
+      )
+      raw = PWN::AI::Agent::Dispatch.call(
+        tool_call: {
+          function: {
+            name: 'loot_query',
+            arguments: JSON.generate(host: 'app.example.test', engagement: 'lab')
+          }
+        },
+        scope_path: File.join(dir, 'absent.yaml')
+      )
+      row = JSON.parse(raw, symbolize_names: true).fetch(:result)
+      hit = Array(row[:records] || row).first
+      expect(hit[:username]).to eq('admin')
+      expect(hit[:finding_id]).to eq('f00bar')
+      expect(hit[:host]).to include('app.example.test')
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+
+describe 'PWN::AI::Agent::Tools nmap_scan' do
+  before(:all) do
+    PWN::AI::Agent::Registry.discover(force: true)
+    load '/opt/pwn/lib/pwn/ai/agent/tools/nmap_scan.rb'
+  end
+
+  it 'registers expected tool names' do
+    expect(PWN::AI::Agent::Registry.lookup(name: 'nmap_scan')).not_to be_nil
+  end
+
+  it 'queries yesterday\'s scan diff in one Dispatch call' do
+    expect(PWN::Plugins::NmapIt).to receive(:changes).with(hash_including(since: 'yesterday')).and_return(added_ports: [{ port: 80 }])
+    raw = PWN::AI::Agent::Dispatch.call(
+      tool_call: { function: { name: 'nmap_scan', arguments: JSON.generate(since: 'yesterday', engagement: 'lab') } },
+      scope_path: File.join(Dir.tmpdir, 'absent.yaml')
+    )
+    row = JSON.parse(raw, symbolize_names: true).fetch(:result)
+    expect(row[:added_ports].first[:port]).to eq(80)
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+
+describe 'PWN::AI::Agent::Tools nuclei_scan' do
+  before(:all) do
+    PWN::AI::Agent::Registry.discover(force: true)
+    load '/opt/pwn/lib/pwn/ai/agent/tools/nuclei_scan.rb'
+  end
+
+  it 'registers expected tool names' do
+    expect(PWN::AI::Agent::Registry.lookup(name: 'nuclei_scan')).not_to be_nil
+  end
+
+  it 'records a web finding from JSONL in one Dispatch call' do
+    Dir.mktmpdir('pwn-nuclei-tool-') do |dir|
+      stub_const('PWN::Plugins::Findings::FILE', File.join(dir, 'findings.jsonl'))
+      jsonl = File.join(dir, 'hit.jsonl')
+      File.write(jsonl, "#{JSON.generate(
+        'template-id' => 'exposed-panel',
+        'matched-at' => 'https://app.example.test/admin',
+        'info' => { 'name' => 'Exposed admin panel', 'severity' => 'medium' }
+      )}\n")
+      raw = PWN::AI::Agent::Dispatch.call(
+        tool_call: { function: { name: 'nuclei_scan', arguments: JSON.generate(jsonl: jsonl) } },
+        scope_path: File.join(dir, 'absent.yaml')
+      )
+      row = JSON.parse(raw, symbolize_names: true).fetch(:result)
+      expect(row[:findings].first[:template_id]).to eq('exposed-panel')
+      stored = PWN::Plugins::Findings.report
+      expect(stored.first[:matched_at]).to include('/admin')
+      expect(stored.first[:severity].to_s).to match(/medium/i)
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'json'
+require 'tmpdir'
+
+describe 'PWN::AI::Agent::Tools pwn_eval plugin schema' do
+  before(:all) do
+    PWN::AI::Agent::Registry.discover(force: true)
+    load '/opt/pwn/lib/pwn/ai/agent/tools/ruby_eval.rb'
+  end
+
+  it 'rejects an unknown plugin keyword before eval and echoes the schema' do
+    raw = PWN::AI::Agent::Dispatch.call(
+      tool_call: {
+        function: {
+          name: 'pwn_eval',
+          arguments: JSON.generate(code: 'PWN::Plugins::BasicAuth.encode(not_a_key: 1)')
+        }
+      },
+      scope_path: File.join(Dir.tmpdir, 'absent.yaml')
+    )
+    row = JSON.parse(raw, symbolize_names: true).fetch(:result)
+    expect(row[:error].to_s).to match(/unknown keyword/i)
+    expect(row[:schema]).to be_a(Hash)
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe 'PWN::AI::Agent::Tools radare2' do
+  before(:all) do
+    PWN::AI::Agent::Registry.discover(force: true)
+    load '/opt/pwn/lib/pwn/ai/agent/tools/radare2.rb'
+  end
+
+  it 'registers r2_functions and r2_disasm' do
+    expect(PWN::AI::Agent::Registry.lookup(name: 'r2_functions')).not_to be_nil
+    expect(PWN::AI::Agent::Registry.lookup(name: 'r2_disasm')).not_to be_nil
+  end
+end

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

@@ -105,6 +105,20 @@ describe PWN::AI::Agent::TurnFinalizer do
   end
 
   describe 'output path literals' do
+    it 'precommits immutable required_artifacts before cwd or request processing can drift' do
+      Dir.mktmpdir do |dir|
+        request = 'Read /tmp/input.md and write ./answer.md'
+        contract = described_class.commit_artifacts!(request: request, cwd: dir)
+        expect(contract[:required_artifacts]).to eq([File.join(dir, 'answer.md')])
+        expect(contract).to be_frozen
+        expect(contract[:required_artifacts]).to be_frozen
+        expect(described_class.required_artifacts(request: request)).to eq(contract[:required_artifacts])
+        expect(described_class.arbitrate(request: request, messages: [])[:unmet]).to include(criterion: 'artifact_missing', detail: File.join(dir, 'answer.md'))
+      end
+    ensure
+      Thread.current[:pwn_artifact_contract] = nil
+    end
+
     it 'does not interpret words inside earlier filenames as new instructions' do
       expect(described_class.output_paths(request: 'Write /tmp/read.md and /tmp/answer.md')).to eq(['/tmp/read.md', '/tmp/answer.md'])
     end
@@ -124,6 +138,68 @@ describe PWN::AI::Agent::TurnFinalizer do
     end
   end
 
+  it 'rejects host observations from an earlier turn even when stat and digest still match' do
+    Dir.mktmpdir do |dir|
+      path = File.join(dir, 'answer.md')
+      request = "Write #{path}"
+      described_class.commit_artifacts!(request: request)
+      before = described_class.artifact_snapshot(paths: [path])
+      File.write(path, 'verified first turn')
+      observations = described_class.observe_artifacts(paths: [path], before: before, effect: :write, success: true)
+      messages = [{ role: 'tool', artifact_observations: observations }]
+      expect(described_class.arbitrate(request: request, messages: messages)[:complete]).to eq(true)
+      described_class.commit_artifacts!(request: request)
+      result = described_class.arbitrate(request: request, messages: messages)
+      expect(result[:unmet]).to include(criterion: 'write_missing', detail: path)
+      expect(result[:unmet]).to include(criterion: 'readback_missing', detail: path)
+    end
+  ensure
+    Thread.current[:pwn_artifact_contract] = nil
+  end
+
+  it 'gates finalization on real Dispatch writes and current-turn stat plus SHA-256 for every committed path' do
+    PWN::AI::Agent::Registry.discover
+    loop_module = PWN::AI::Agent::Loop
+    allow(loop_module).to receive(:evidence_satisfied?).and_return(true)
+    allow(loop_module).to receive(:record_artifact_bounce)
+    Dir.mktmpdir do |dir|
+      paths = %w[first.md second.md].map { |name| File.join(dir, name) }
+      request = "Write #{paths.join(' and ')}"
+      contract = described_class.commit_artifacts!(request: request)
+      messages = [{ role: 'assistant', content: 'Both files were written and verified.' }]
+      finalize = -> { loop_module.send(:may_finalize?, request: request, messages: messages, text: 'Delivered both files.') }
+      expect(finalize.call).to eq(false)
+      paths.each_with_index do |path, index|
+        code = "File.write(#{path.inspect}, 'verified artifact #{index}')"
+        args = index.zero? ? { code: code } : { encoding: 'base64', data: Base64.strict_encode64(code) }
+        before = described_class.artifact_snapshot(paths: contract[:required_artifacts])
+        raw = PWN::AI::Agent::Dispatch.call(scope_policy: { enabled: false }, tool_call: { function: { name: 'pwn_eval', arguments: JSON.generate(args) } })
+        parsed = JSON.parse(raw)
+        expect(parsed.dig('result', 'error')).to be_nil
+        effect = PWN::AI::Agent::Dispatch.effect(name: 'pwn_eval', args: args)
+        expect(effect).to eq(:write)
+        observed = described_class.observe_artifacts(paths: contract[:required_artifacts], before: before, effect: effect, success: parsed['success'])
+        expect(observed.fetch(path)[:sha256]).to eq(Digest::SHA256.file(path).hexdigest)
+        expect(observed.fetch(path)[:stat][:size]).to eq(File.size(path))
+        messages << { role: 'tool', content: raw, artifact_observations: observed }
+        expect(finalize.call).to eq(index == 1)
+      end
+      File.write(paths.last, 'changed after readback')
+      expect(finalize.call).to eq(false)
+    end
+  ensure
+    Thread.current[:pwn_artifact_contract] = nil
+    Thread.current[:pwn_dispatch_budget] = nil
+  end
+
+  it 'precommits before cheap returns and uses the committed list for dispatch observation' do
+    source = File.read(PWN::AI::Agent::Loop.method(:run).source_location.first)
+    run = source[source.index('public_class_method def self.run(opts = {})')..]
+    expect(run.index('commit_artifacts!')).to be < run.index('cheap =')
+    expect(run).to include('allow_text_only = required_artifacts.empty?', 'cheap = allow_text_only', 'declared_paths = required_artifacts')
+    expect(run).to include('Thread.current[:pwn_artifact_contract] = prior_artifact_contract')
+  end
+
   it 'requires a current-turn write even when a file is newly present and readable' do
     Dir.mktmpdir do |dir|
       path = File.join(dir, 'answer.md')

data/spec/lib/pwn/ai/cli_spec.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'spec_helper'
+require 'yaml'
 require 'open3'
 require 'tmpdir'
 
@@ -91,11 +92,21 @@ RSpec.describe 'PWN::AI::CLI' do
     expect { PWN::AI::CLI.help }.to output(/\.parse.*\.run.*\.authors/m).to_stdout
   end
 
+  it 'emits a YAML DAG for --plan-only without running the agent loop' do
+    expect(PWN::AI::Agent::Loop).not_to receive(:run)
+    expect(PWN::AI::Agent::Dispatch).not_to receive(:call)
+    out = StringIO.new
+    expect(PWN::AI::CLI.run(argv: ['--plan-only', '--ai', 'echo one then echo two'], output: out)).to eq(0)
+    dag = YAML.safe_load(out.string)
+    expect(dag['steps'].length).to be >= 2
+    expect(dag['steps'].first).to include('tool', 'args', 'side_effect', 'dependencies')
+  end
+
   it 'prints executable help without reading or creating a vault' do
     Dir.mktmpdir do |home|
       output, status = Open3.capture2e({ 'HOME' => home }, 'ruby', '-Ilib', 'bin/pwn-ai', '--help')
       expect(status.success?).to be(true), output
-      expect(output).to include('--analyze', '--replay', '--rerun')
+      expect(output).to include('--analyze', '--replay', '--rerun', '--plan-only', '--resume')
       expect(Dir.children(home)).to eq([])
     end
   end

data/spec/lib/pwn/ai/router_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'tmpdir'
+
+describe PWN::AI::Router 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 'maps task classes from ai_router with fallback chains' do
+    stub_const('PWN::Env', {
+                 ai_router: {
+                   summarize: { engine: 'ollama', model: 'tinyllama', fallbacks: [{ engine: 'openwebui' }] },
+                   plan: { engine: 'ollama', fallbacks: [] },
+                   exploit_dev: { engine: 'ollama', model: 'qwen2.5-coder', fallbacks: [{ engine: 'openai', model: 'gpt-5' }] },
+                   triage: { engine: 'ollama', fallbacks: [{ engine: 'openwebui' }] }
+                 },
+                 ai: { active: 'grok', ollama: { model: 'tinyllama' } }
+               })
+    sum = described_class.resolve(task: :summarize)
+    expect(sum[:endpoints].first[:engine].to_s).to eq('ollama')
+    expect(sum[:allow_frontier]).to eq(false)
+    exp = described_class.resolve(task: :exploit_dev)
+    expect(exp[:endpoints].map { |row| row[:engine].to_s }).to include('ollama', 'openai')
+    expect(exp[:endpoints].first[:model].to_s).to include('coder')
+  end
+
+  it 'never spends frontier-model tokens on artifact summarization' do
+    Dir.mktmpdir('pwn-router-') do |dir|
+      allow(Dir).to receive(:home).and_return(dir)
+      stub_const('PWN::Plugins::ArtifactRegistry::ROOT', File.join(dir, 'artifacts'))
+      stub_const('PWN::Env', {
+                   ai_router: {
+                     summarize: { engine: 'grok', model: 'grok-4', fallbacks: [{ engine: 'openai' }, { engine: 'ollama', model: 'tinyllama' }] }
+                   },
+                   ai: { active: 'grok', grok: { model: 'grok-4' }, openai: { model: 'gpt-5' }, ollama: { model: 'tinyllama' } }
+                 })
+      described_class.reset_usage
+      %i[Grok OpenAI Anthropic Gemini].each do |name|
+        allow(PWN::AI.const_get(name)).to receive(:chat).and_raise('frontier must not be called')
+      end
+      allow(PWN::AI::Ollama).to receive(:chat).and_return('local artifact summary')
+      path = File.join(dir, 'big.txt')
+      File.write(path, 'A' * (PWN::AI::Context::WINDOW + 50))
+      row = PWN::AI::Context.attach_file(path: path, session_id: 'sum')
+      expect(row[:summarized]).to eq(true)
+      expect(described_class.usage.dig(:summarize, :frontier_tokens)).to eq(0)
+      expect(PWN::AI::Grok).not_to have_received(:chat)
+      expect(PWN::AI::OpenAI).not_to have_received(:chat)
+    end
+  end
+end

data/spec/lib/pwn/ffi/capstone_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe PWN::FFI::Capstone 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 'should respond to available?' do
+    expect(described_class).to respond_to :available?
+  end
+
+  it 'rejects disassemble when libcapstone is unavailable' do
+    allow(described_class).to receive(:available?).and_return(false)
+    expect { described_class.disassemble(bytes: "\x90") }.to raise_error(RuntimeError, /libcapstone not available/)
+  end
+
+  before(:each, :capstone_integration) do
+    expect(described_class.available?).to be(true),
+                                          "PWN_TEST_CAPSTONE=1 requires libcapstone. Load error: #{described_class.load_error}"
+  end
+
+  it 'disassembles nop', :capstone_integration do
+    row = described_class.disassemble(bytes: "\x90\xc3", arch: 'x86_64')
+    expect(row[:engine]).to eq('capstone')
+    expect(row[:insns].map { |i| i[:mnemonic] }).to include('nop')
+  end
+end

data/spec/lib/pwn/ffi/keystone_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe PWN::FFI::Keystone 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 'should respond to available?' do
+    expect(described_class).to respond_to :available?
+  end
+
+  it 'rejects assemble when libkeystone is unavailable' do
+    allow(described_class).to receive(:available?).and_return(false)
+    expect { described_class.assemble(asm: 'nop') }.to raise_error(RuntimeError, /libkeystone not available/)
+  end
+
+  before(:each, :keystone_integration) do
+    expect(described_class.available?).to be(true),
+                                          "PWN_TEST_KEYSTONE=1 requires libkeystone. Load error: #{described_class.load_error}"
+  end
+
+  it 'assembles nop; ret', :keystone_integration do
+    row = described_class.assemble(asm: "nop\nret", arch: 'x86_64')
+    expect(row[:engine]).to eq('keystone')
+    expect(row[:bytes].bytesize).to be >= 2
+  end
+end

data/spec/lib/pwn/migrate_spec.rb

@@ -80,11 +80,11 @@ describe PWN::Migrate do
       File.write(File.join(@tmp, '.schema'), JSON.generate(schema: 2))
       expect(described_class.needed?).to be(true)
       result = described_class.run(fix: false, backup: false, io: io)
-      expect(result[:applied_migrations]).to eq([3])
+      expect(result[:applied_migrations]).to eq([3, 4])
       expected = Marshal.load(Marshal.dump(original))
       expected['custom']['model'] = nil
       expect(YAML.safe_load_file(path)).to eq(expected)
-      expect(described_class.installed_schema).to eq(3)
+      expect(described_class.installed_schema).to eq(described_class::SCHEMA_VERSION)
       bytes = File.binread(path)
       described_class::MIGRATIONS.fetch(3).call(@tmp, io)
       expect(File.binread(path)).to eq(bytes)
@@ -174,10 +174,38 @@ describe PWN::Migrate do
       stale = { ai: { active: 'grok', grok: { key: 'x' } } }
       miss  = PWN::Migrate.send(:missing_paths, tmpl: PWN::Config.env_template, user: stale)
       expect(miss).to include('ai.agent')
+      expect(miss).to include('ai_sandbox')
+      expect(miss).to include('ai_router')
       expect(miss).to include('memory')
       expect(miss).not_to include('ai.active')
     end
 
+    it 'upgrades a schema-3 vault with new pwn.yaml keys without changing user values' do
+      yaml = File.join(@tmp, 'pwn.yaml')
+      dec = File.join(@tmp, 'pwn.yaml.decryptor')
+      stale = { ai: { active: 'grok', grok: { key: 'sk-KEEP' } } }
+      File.write(yaml, YAML.dump(stale).gsub(/^(\s*):/, '\1'))
+      PWN::Plugins::Vault.create(file: yaml, decryptor_file: dec)
+      File.write(File.join(@tmp, '.schema'), JSON.generate(schema: 3))
+      expect(described_class.needed?).to be(true)
+      result = described_class.run(fix: true, backup: false, io: io)
+      expect(result[:applied_migrations]).to eq([4])
+      creds = YAML.safe_load_file(dec, symbolize_names: true)
+      user = PWN::Plugins::Vault.dump(file: yaml, key: creds[:key], iv: creds[:iv])
+      expect(user[:ai][:active]).to eq('grok')
+      expect(user[:ai][:grok][:key]).to eq('sk-KEEP')
+      expect(user[:ai_sandbox]).to eq('off')
+      expect(user[:ai_router]).to be_a(Hash)
+      expect(user[:ai_router][:summarize] || user[:ai_router]['summarize']).to be_a(Hash)
+      routes = user.dig(:ai, :agent, :model_routes) || user.dig('ai', 'agent', 'model_routes')
+      expect(routes).to include(:exploit_dev).or include('exploit_dev')
+      second = described_class.run(fix: true, backup: false, io: io)
+      expect(second[:applied_migrations]).to eq([])
+      again = PWN::Plugins::Vault.dump(file: yaml, key: creds[:key], iv: creds[:iv])
+      expect(again[:ai][:grok][:key]).to eq('sk-KEEP')
+      expect(described_class.needed?).to be(false)
+    end
+
     it 'dry_run writes nothing' do
       r = PWN::Migrate.run(fix: true, backup: true, dry_run: true, io: io)
       expect(r[:dry_run]).to be true