pwn 0.5.766 → 0.5.772

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

@@ -3,6 +3,8 @@
 require 'json'
 require 'fileutils'
 require 'time'
+require 'digest'
+require 'securerandom'
 
 module PWN
   module AI
@@ -14,6 +16,9 @@ module PWN
         CONTINUE_RX = /\A\s*(continue|resume|keep going|pick up|carry on)(?:\s+(?:please|the\s+)?(?:goal|task|work))?\s*[.!]?\s*\z/i
 
         public_class_method def self.goal_file
+          runtime = Thread.current[:pwn_request_runtime]
+          return File.join(File.dirname(GOAL_FILE), 'open_goals', Digest::SHA256.hexdigest(runtime.session_id), "#{Digest::SHA256.hexdigest(runtime.request_id)}.json") if runtime
+
           GOAL_FILE
         end
 
@@ -29,6 +34,16 @@ module PWN
           nil
         end
 
+        public_class_method def self.for_session(opts = {})
+          sid = opts[:session_id].to_s
+          pointer = File.join(File.dirname(GOAL_FILE), 'open_goals', Digest::SHA256.hexdigest(sid), 'current.json')
+          path = File.file?(pointer) ? pointer : GOAL_FILE
+          return unless File.file?(path)
+
+          row = JSON.parse(File.read(path), symbolize_names: true)
+          row if row[:session_id] == sid && !row[:request].to_s.empty?
+        end
+
         public_class_method def self.begin!(opts = {})
           request = opts[:request].to_s.strip
           return if request.empty?
@@ -40,7 +55,10 @@ module PWN
             mission_id: opts[:mission_id].to_s,
             updated_at: Time.now.utc.iso8601
           }
-          File.write(goal_file, "#{JSON.pretty_generate(row)}\n")
+          runtime = Thread.current[:pwn_request_runtime]
+          row.merge!(request_id: runtime.request_id, checkpoint_path: runtime.checkpoint_path) if runtime
+          atomic_write(path: goal_file, row: row)
+          atomic_write(path: File.join(File.dirname(goal_file), 'current.json'), row: row) if runtime
           row
         end
 
@@ -50,6 +68,11 @@ module PWN
           return :held if mission_open?
 
           File.delete(goal_file)
+          pointer = File.join(File.dirname(goal_file), 'current.json')
+          if Thread.current[:pwn_request_runtime] && File.file?(pointer)
+            row = JSON.parse(File.read(pointer), symbolize_names: true)
+            File.delete(pointer) if row[:request_id] == Thread.current[:pwn_request_runtime].request_id
+          end
           :ok
         rescue StandardError
           :ok
@@ -76,6 +99,11 @@ module PWN
             # Run current and return its result
             #{self}.current
 
+            # Look up only the named session's resumable request.
+            #{self}.for_session(
+              session_id: 'required - exact session identity; no cross-session fallback'
+            )
+
             # Run begin and return its result
             #{self}.begin!(
               request: 'required - request value consumed by #begin!',
@@ -97,6 +125,20 @@ module PWN
           constants.sort
         end
 
+        private_class_method def self.atomic_write(opts = {})
+          path = opts[:path]
+          FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
+          temp = "#{path}.#{SecureRandom.hex(8)}.tmp"
+          File.open(temp, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+            file.write(JSON.generate(opts[:row]))
+            file.flush
+            file.fsync
+          end
+          File.rename(temp, path)
+        ensure
+          File.unlink(temp) if temp && File.exist?(temp)
+        end
+
         private_class_method def self.mission_open?(opts = {})
           return false unless defined?(PWN::AI::Agent::Mission)
 

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module PWN
   module AI
     module Agent
@@ -157,6 +159,9 @@ module PWN
           schema = opts[:schema]
           return schema unless schema.is_a?(Hash)
 
+          depth = opts.fetch(:depth, 0)
+          raise JSON::NestingError, 'tool schema exceeds JSON nesting limit (100)' if depth >= 100
+
           result = schema.dup
           type = schema[:type] || schema['type'] || opts[:inherited_type]
           result[:type] = type if type && !schema.key?(:type) && !schema.key?('type')
@@ -164,7 +169,7 @@ module PWN
             key = schema.key?(combiner) ? combiner : combiner.to_s
             next unless schema[key].is_a?(Array)
 
-            result[key] = schema[key].map { |branch| explicit_root_types(schema: branch, inherited_type: type) }
+            result[key] = schema[key].map { |branch| explicit_root_types(schema: branch, inherited_type: type, depth: depth + 2) }
           end
           result
         end

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

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'base64'
+require 'digest'
+require 'fileutils'
+require 'securerandom'
+require 'time'
+require 'uri'
 require 'pwn/ai/agent/profiles'
 require 'pwn/ai/agent/engagement_memory'
 require 'pwn/session_trace'
@@ -9,34 +15,368 @@ module PWN
   module AI
     module Agent
       # Connect request-scoped routing, evidence context and replay records.
-      class RequestRuntime
+      class RequestRuntime # rubocop:disable Metrics/ClassLength -- one owner for routing, scope and durable evidence
+        OUTCOMES = %w[complete incomplete blocked cancelled verification_error].freeze
+        attr_reader :original_request, :request, :session_id, :request_id, :contract, :amendments, :outcome, :checkpoint_path, :engine, :last_provider_attempts
+
         def initialize(opts = {})
           @session_id = opts[:session_id].to_s
-          @request = opts[:request].to_s
+          @request_id = (opts[:request_id] || SecureRandom.uuid).to_s.freeze
+          @original_request = opts[:request].to_s.dup.freeze
+          @request = @original_request
+          @cwd = Dir.pwd
+          @amendments = [].freeze
+          @observations = {}
+          @events = []
+          @effects = {}
+          @evidence = []
+          @provider_config = Marshal.load(Marshal.dump(opts[:provider_config] || (defined?(PWN::Env) ? PWN::Env[:ai] : {}) || {}))
+          @engine = opts[:engine] || Thread.current[:pwn_swarm_engine] || @provider_config[:active] || :openai
+          @model = opts[:model] || Thread.current[:pwn_swarm_model]
+          @explicit_route = opts[:engine] || opts[:model] || Thread.current[:pwn_swarm_engine] || Thread.current[:pwn_swarm_model]
+          @provider_attempts = opts.fetch(:provider_attempts, 5).to_i.clamp(1, 100)
+          @cancel = opts[:cancel]
+          @generation = 0
+          @enabled_toolsets = opts[:enabled_toolsets]&.map { |item| item.to_s.dup.freeze }&.freeze
+          @verification_contract = opts[:verification_contract] && Marshal.load(Marshal.dump(opts[:verification_contract]))
+          @mutex = Mutex.new
+          @started_at = Time.now
+          @trace = opts.fetch(:trace, true)
+          @retrieve = opts.fetch(:retrieve, true)
+          root = opts[:artifact_root] || File.join(PWN::Sessions.sessions_dir, 'requests')
+          @checkpoint_path = File.join(root, Digest::SHA256.hexdigest(@session_id), "#{Digest::SHA256.hexdigest(@request_id)}.json")
+          restore! if opts[:resume]
+          rebuild_contract!
           @profile = opts[:profile]
           @router = Profiles.new(profiles: opts[:profiles] || {})
+          @engine = @router.lookup(name: @profile)[:provider] if @profile && !@explicit_route
           @memory = EngagementMemory.new(original_goal: @request, session_id: @session_id,
-                                         root: opts[:artifact_root] || File.expand_path('~/.pwn/artifacts'),
+                                         root: root,
                                          window: opts[:window] || 128_000, tool_cap: opts[:tool_cap] || 8192)
           @route = {}
           @retrieval = nil
+          checkpoint!
           record(event: 'request', data: { content: @request })
         end
 
+        # A resumed execution cannot inherit an earlier terminal success.
+        def start!
+          @outcome = nil
+          checkpoint!
+        end
+
+        # Steering is additive unless the operator explicitly says replace/cancel.
+        def amend!(opts = {})
+          instruction = opts.fetch(:instruction).to_s
+          mode = if instruction.strip.match?(/\Acancel\z/i)
+                   'cancel'
+                 elsif instruction.match?(/\Areplace:\s*/i)
+                   'replace'
+                 else
+                   'add'
+                 end
+          @amendments = (@amendments + [{ mode: mode, instruction: instruction.dup.freeze }.freeze]).freeze
+          @request = if mode == 'replace'
+                       instruction.sub(/\Areplace:\s*/i, '').freeze
+                     elsif mode == 'add'
+                       "#{@request}\n#{instruction}".freeze
+                     else
+                       @request
+                     end
+          rebuild_contract!
+          mode == 'cancel' ? finish!(status: 'cancelled') : checkpoint!
+        end
+
+        # Only host observations enter this store, never parsed tool stdout.
+        def observe!(opts = {})
+          @mutex.synchronize do
+            opts.fetch(:observations).each { |path, row| @observations[path.to_s] = row }
+            checkpoint!
+          end
+        end
+
+        def observations
+          @mutex.synchronize { Marshal.load(Marshal.dump(@observations)) }
+        end
+
+        # Called only by the enclosing Loop, never by a provider tool payload.
+        # Recheck bytes/identity before rebinding to the parent's turn. The
+        # parent still runs its own literal and authored integration checks.
+        def accept_child!(opts = {})
+          child = opts.fetch(:runtime)
+          return unless child.outcome&.dig(:status) == 'complete' && child.contract[:started_at] >= @started_at
+
+          rows = child.observations.select do |path, row|
+            next false unless @contract[:required_artifacts].include?(path) && row[:artifact_turn_id] == child.contract[:id]
+
+            current = TurnFinalizer.artifact_snapshot(paths: [path])[path]
+            current && current == row.except(:artifact_turn_id, :action_id, :tool, :child_request_id, :child_turn_id, :child_provenance)
+          end
+          rows.transform_values! do |row|
+            row.merge(artifact_turn_id: @contract[:id], child_request_id: child.request_id, child_turn_id: child.contract[:id],
+                      child_provenance: Array(row[:child_provenance]) + [{ request_id: child.request_id, turn_id: child.contract[:id], sha256: row[:sha256], action_id: row[:action_id] }])
+          end
+          observe!(observations: rows) unless rows.empty?
+        end
+
+        def events
+          @mutex.synchronize { Marshal.load(Marshal.dump(@events)) }
+        end
+
+        # Private copies keep credentials and defaults out of checkpoints.
+        def provider_config(engine)
+          Marshal.load(Marshal.dump(@provider_config[engine.to_sym] || {}))
+        end
+
+        def update_provider_oauth(engine, oauth)
+          @provider_config[engine.to_sym] ||= {}
+          @provider_config[engine.to_sym][:oauth] = Marshal.load(Marshal.dump(oauth))
+          :updated
+        end
+
+        def check_cancelled!
+          raise Interrupt, 'request cancelled' if @outcome&.dig(:status) == 'cancelled' || @cancel&.call
+        end
+
+        # Unknown tools are exclusive barriers; shell cannot opt into reads.
+        def each_tool_batch(calls)
+          batch = []
+          resources = []
+          calls.each do |call|
+            metadata = Dispatch.scheduling(tool_call: call)
+            if metadata[:exclusive] || batch.length >= 8 || resources.intersect?(metadata[:resources])
+              yield batch unless batch.empty?
+              batch = []
+              resources = []
+            end
+            batch << call
+            resources.concat(metadata[:resources])
+            next unless metadata[:exclusive]
+
+            yield batch
+            batch = []
+            resources = []
+          end
+          yield batch unless batch.empty?
+        end
+
+        def scheduled_calls(calls, session_id:, eligible: nil)
+          Enumerator.new do |output|
+            each_tool_batch(calls) do |batch|
+              reads = eligible ? batch.select { |call| eligible.call(call) } : batch
+              results = dispatch_reads(reads, session_id: session_id)
+              batch.each { |call| output << [call, results[call]] }
+            end
+          end
+        end
+
+        def dispatch_reads(calls, session_id:)
+          return {} if calls.length < 2
+
+          locals = Thread.current.keys.to_h { |key| [key, Thread.current[key]] }
+          workers = calls.map do |call|
+            Thread.new do
+              locals.each { |key, value| Thread.current[key] = value }
+              check_cancelled!
+              Dispatch.call(tool_call: call, session_id: session_id)
+            end
+          end
+          workers.each do |worker|
+            check_cancelled! until worker.join(0.05)
+          end
+          calls.zip(workers.map(&:value)).to_h
+        ensure
+          workers&.each { |worker| worker.kill if worker.alive? }
+          workers&.each(&:join)
+        end
+
+        def tool_allowed?(opts = {})
+          @enabled_toolsets.nil? || @enabled_toolsets.include?(opts[:toolset].to_s) || @enabled_toolsets.include?(opts[:name].to_s)
+        end
+
+        def verification_contract
+          Marshal.load(Marshal.dump(@verification_contract))
+        end
+
+        def bind_verification!(opts = {})
+          contract = opts[:contract]
+          return unless contract
+          raise ArgumentError, 'verification contract replacement requires a new request' if @verification_contract && @verification_contract != contract
+
+          @verification_contract = Marshal.load(Marshal.dump(contract))
+          checkpoint!
+        end
+
+        def session_bound?(opts = {})
+          return false unless opts[:session_id].to_s == @session_id && opts[:request].to_s == @request
+
+          users = Array(opts[:rows]).select { |row| row[:role].to_s == 'user' }.map { |row| row[:content].to_s }
+          expected = [@original_request] + @amendments.map { |row| row[:instruction] }
+          users.last(expected.length) == expected
+        end
+
+        def verification!(opts = {})
+          report = opts.fetch(:report)
+          @mutex.synchronize do
+            @events << { phase: 'verification', report: report, request_id: @request_id,
+                         request_sha256: Digest::SHA256.hexdigest(@request),
+                         original_sha256: Digest::SHA256.hexdigest(@original_request),
+                         amendments_sha256: Digest::SHA256.hexdigest(JSON.generate(@amendments)),
+                         at: Time.now.utc.iso8601(9) }
+            checkpoint!
+          end
+        end
+
+        # Host verifier adapters supply observations, never tool stdout. Each
+        # record is bound to a literal source clause and an exact remote target.
+        def observe_evidence!(opts = {})
+          requirement = opts.fetch(:requirement).to_s
+          source = [{ id: 'original', text: @original_request }] + @amendments.each_with_index.map { |row, index| { id: "amendment:#{index}", text: row[:instruction] } }
+          source = source.find { |row| row[:text].include?(requirement) }
+          raise ArgumentError, 'evidence must name an original or amended requirement' if requirement.empty? || !source || !@request.include?(requirement)
+          raise ArgumentError, 'unsupported evidence kind' unless %w[http command answer].include?(opts[:kind].to_s)
+
+          row = { id: SecureRandom.uuid, request_id: @request_id, source_id: source[:id], requirement: requirement,
+                  offset: source[:text].index(requirement), requirement_sha256: Digest::SHA256.hexdigest(requirement),
+                  scope_sha256: Digest::SHA256.hexdigest(@request), kind: opts[:kind].to_s, locator: opts[:locator],
+                  sha256: opts.fetch(:sha256), passed: opts[:passed] == true && evidence_target_matches?(opts), provenance: 'host_verifier',
+                  observed_at: Time.now.utc.iso8601(9), max_age: opts[:max_age] || (300 if opts[:kind].to_s == 'http') }
+          @mutex.synchronize do
+            @evidence << Marshal.load(Marshal.dump(row))
+            checkpoint!
+          end
+          row
+        end
+
+        def evidence
+          @mutex.synchronize { Marshal.load(Marshal.dump(@evidence)) }
+        end
+
+        def host_evidenced?(host)
+          evidence.any? do |row|
+            next false unless row[:kind] == 'http' && fresh_evidence?(row)
+
+            URI.parse(row[:locator]).host == host.to_s.downcase
+          end
+        end
+
+        def scope_evidenced?
+          remaining = @request.dup
+          evidence.select { |row| fresh_evidence?(row) }.each { |row| remaining.gsub!(row[:requirement], '') }
+          remaining.match?(/\A[\s.,;:!?]*\z/)
+        end
+
+        # Recovery is an explicit operator action after an independent target
+        # read. Merely obtaining a successful HTTP response never clears doubt.
+        def reconcile_effect!(opts = {})
+          raise ArgumentError, 'operator approval required' unless opts[:operator_approved] == true
+
+          key = opts.fetch(:payload_sha256)
+          row = evidence.find { |item| item[:id] == opts[:evidence_id] && item[:kind] == 'http' && fresh_evidence?(item) }
+          action = events.reverse.find { |item| item[:payload_sha256] == key && item[:phase] == 'start' }
+          raise ArgumentError, 'fresh exact-target reconciliation evidence required' unless row && action && action[:target] && row[:locator] == action[:target] && Time.iso8601(row[:observed_at]) > Time.iso8601(action[:at])
+
+          @mutex.synchronize do
+            raise ArgumentError, 'effect is not uncertain' unless @effects[key] == 'uncertain'
+
+            @effects[key] = 'reconciled'
+            @events << { phase: 'reconciliation', payload_sha256: key, evidence_id: row[:id], at: Time.now.utc.iso8601(9) }
+            checkpoint!
+          end
+          :reconciled
+        end
+
+        def fresh_evidence?(row)
+          observed = Time.iso8601(row[:observed_at])
+          latest = @evidence.reverse.find { |item| item[:kind] == row[:kind] && item[:locator] == row[:locator] && item[:requirement] == row[:requirement] }
+          return false unless latest && latest[:id] == row[:id]
+
+          row[:request_id] == @request_id && row[:scope_sha256] == Digest::SHA256.hexdigest(@request) && row[:passed] &&
+            observed >= @started_at && observed <= Time.now && (!row[:max_age] || Time.now - observed <= row[:max_age].to_f)
+        end
+
+        def unmet
+          @mutex.synchronize { @effects.value?('uncertain') ? ['uncertain_side_effect'] : [] }
+        end
+
+        # A started mutation stays uncertain across interruption or process death.
+        # Changing timeout/action IDs does not authorize replay of that mutation.
+        def execute_tool(opts = {}, &)
+          check_cancelled!
+          payload = opts.fetch(:args).reject { |key, _| key.to_s == 'timeout' }
+          key = Digest::SHA256.hexdigest(JSON.generate([opts.fetch(:name), canonical(payload)]))
+          mutation = !%w[read recall].include?(opts.fetch(:effect).to_s)
+          action = { action_id: opts[:action_id], tool: opts[:name], payload_sha256: key, effect: opts[:effect].to_s,
+                     target: payload[:url] || payload['url'] }
+          denied = @mutex.synchronize do
+            if mutation && @effects[key] == 'uncertain'
+              true
+            else
+              @effects[key] = 'uncertain' if mutation
+              @events << action.merge(phase: 'start', at: Time.now.utc.iso8601(9))
+              checkpoint!
+              false
+            end
+          end
+          return { success: false, error: 'uncertain_side_effect', hint: 'Inspect the target before any operator-approved recovery; this mutation was not replayed.' } if denied
+
+          begin
+            result = provider_attempt(&)
+            failed = result.is_a?(Hash) && (result[:error] || result['error'] || result[:success] == false || result['success'] == false)
+            state = if failed
+                      mutation ? 'uncertain' : 'failed'
+                    else
+                      'completed'
+                    end
+            result
+          ensure
+            @mutex.synchronize do
+              state ||= mutation ? 'uncertain' : 'interrupted'
+              @effects[key] = state if mutation
+              @events << action.merge(phase: 'end', state: state, at: Time.now.utc.iso8601(9))
+              checkpoint!
+            end
+          end
+        end
+
+        def finish!(opts = {})
+          status = opts.fetch(:status).to_s
+          raise ArgumentError, 'invalid request outcome' unless OUTCOMES.include?(status)
+
+          @outcome = { status: status, unmet: Array(opts[:unmet]), at: Time.now.utc.iso8601 }.freeze
+          checkpoint!
+          @outcome
+        end
+
         def call(messages:, tools:)
           prepared = @memory.compact(messages: messages)
-          prepared = retrieval_context(prepared) unless tools.nil?
-          routes = @router.routes(name: @profile, engine: Thread.current[:pwn_swarm_engine], model: Thread.current[:pwn_swarm_model])
-          if routes.empty?
-            @route = {}
-            response = yield(prepared, @route)
-          else
-            response = @router.call(name: @profile, engine: Thread.current[:pwn_swarm_engine], model: Thread.current[:pwn_swarm_model]) do |route|
-              @route = route
-              input = prepared
-              input = [{ role: 'system', content: route[:system_prompt] }] + prepared if route[:system_prompt] && !route[:system_prompt].empty?
-              yield(input, route)
+          prepared = retrieval_context(prepared) if @retrieve && !tools.nil?
+          routes = @router.routes(name: @profile, engine: (@engine if !@profile || @explicit_route), model: (@model if !@profile || @explicit_route))
+          routes = [{ provider: @engine, model: @model }] if routes.empty?
+          attempt = 0
+          previous = Thread.current[:pwn_provider_attempt_owner]
+          begin
+            check_cancelled!
+            Thread.current[:pwn_provider_attempt_owner] = self
+            @route = routes[[attempt, routes.length - 1].min]
+            attempt += 1
+            @last_provider_attempts = attempt
+            input = Marshal.load(Marshal.dump(prepared))
+            input = [{ role: 'system', content: @route[:system_prompt] }] + input if @route[:system_prompt] && !@route[:system_prompt].empty?
+            provider_event('provider_start', attempt)
+            begin
+              response = provider_attempt { yield(input, @route) }
+            ensure
+              provider_event('provider_end', attempt)
             end
+          rescue StandardError => e
+            raise unless attempt < @provider_attempts && provider_transient?(e)
+
+            check_cancelled!
+            provider_backoff(e, attempt)
+            retry
+          ensure
+            Thread.current[:pwn_provider_attempt_owner] = previous
           end
           record(event: 'response', data: response)
           response
@@ -57,10 +397,140 @@ module PWN
 
         private
 
+        def evidence_target_matches?(opts)
+          return true unless opts[:kind].to_s == 'http'
+
+          uri = URI.parse(opts[:locator].to_s)
+          return false unless %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo
+
+          requirement = opts[:requirement].to_s
+          urls = URI.extract(requirement, %w[http https])
+          return urls.include?(uri.to_s) unless urls.empty?
+
+          hosts = requirement.scan(/(?<![\w.-])(?:[a-z0-9-]+\.)+[a-z0-9-]+(?![\w.-])/i).map(&:downcase)
+          hosts.empty? || hosts.include?(uri.host.downcase)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        def provider_event(phase, attempt)
+          @mutex.synchronize do
+            @events << { phase: phase, attempt: attempt, provider: @route[:provider], model: @route[:model], at: Time.now.utc.iso8601(9) }
+            checkpoint!
+          end
+        end
+
+        def provider_backoff(error, attempt)
+          return unless error.respond_to?(:http_code) && error.http_code.to_i == 429
+
+          delay = PWN::AI::HttpRetry.retry_after_s(response: error.response, retry_count: attempt)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay
+          while (remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)).positive?
+            check_cancelled!
+            sleep [remaining, 0.05].min
+          end
+        end
+
+        # A cancellation callback is observed even while a provider is blocked.
+        # No extra request deadline is introduced. Join every owned worker.
+        def provider_attempt
+          return yield unless @cancel
+
+          locals = Thread.current.keys.to_h { |key| [key, Thread.current[key]] }
+          worker = Thread.new do
+            locals.each { |key, value| Thread.current[key] = value }
+            yield
+          end
+          worker.report_on_exception = false
+          check_cancelled! until worker.join(0.05)
+          check_cancelled!
+          worker.value
+        ensure
+          worker.kill if worker&.alive?
+          worker&.join
+        end
+
+        def provider_transient?(error)
+          return false if PWN::AI::HttpRetry.quota_exhausted?(error: error)
+
+          status = error.respond_to?(:http_code) ? error.http_code.to_i : 0
+          error.is_a?(Timeout::Error) || error.is_a?(SocketError) || error.is_a?(EOFError) ||
+            [Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH].any? { |klass| error.is_a?(klass) } ||
+            status == 429 || status.between?(500, 599) || PWN::AI::HttpRetry.retryable?(error: error)
+        end
+
+        def canonical(value)
+          case value
+          when Hash then value.keys.sort_by(&:to_s).to_h { |key| [key.to_s, canonical(value[key])] }
+          when Array then value.map { |item| canonical(item) }
+          else value
+          end
+        end
+
+        def rebuild_contract!
+          @contract = { id: @request_id, request: @request, cwd: @cwd,
+                        required_artifacts: TurnFinalizer.output_paths(request: @request, cwd: @cwd).map(&:freeze).freeze,
+                        started_at: @started_at }.freeze
+        end
+
+        def checkpoint!
+          FileUtils.mkdir_p(File.dirname(@checkpoint_path), mode: 0o700)
+          File.open("#{@checkpoint_path}.lock", File::RDWR | File::CREAT, 0o600) do |lock|
+            lock.flock(File::LOCK_EX)
+            current = File.file?(@checkpoint_path) ? JSON.parse(File.read(@checkpoint_path)).fetch('generation', 0) : 0
+            raise IOError, 'stale request checkpoint: reload before proceeding' unless current == @generation
+
+            @generation += 1
+            write_checkpoint!
+          end
+        end
+
+        def write_checkpoint!
+          rows = @observations.transform_values do |row|
+            row.merge(head: Base64.strict_encode64(row[:head]), tail: Base64.strict_encode64(row[:tail]))
+          end
+          data = { version: 1, generation: @generation, session_id: @session_id, request_id: @request_id, original_request: @original_request,
+                   request: @request, amendments: @amendments, cwd: @cwd, started_at: @started_at.iso8601(9),
+                   observations: rows, outcome: @outcome, events: @events, effects: @effects, evidence: @evidence,
+                   enabled_toolsets: @enabled_toolsets, verification_contract: @verification_contract }
+          FileUtils.mkdir_p(File.dirname(@checkpoint_path), mode: 0o700)
+          temp = "#{@checkpoint_path}.#{SecureRandom.hex(8)}.tmp"
+          File.open(temp, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+            file.write(JSON.generate(data))
+            file.flush
+            file.fsync
+          end
+          File.rename(temp, @checkpoint_path)
+        ensure
+          File.unlink(temp) if temp && File.exist?(temp)
+        end
+
+        def restore!
+          data = JSON.parse(File.read(@checkpoint_path), symbolize_names: true)
+          raise ArgumentError, 'request checkpoint identity mismatch' unless data[:version] == 1 && data[:session_id] == @session_id && data[:request_id] == @request_id
+
+          @original_request = data.fetch(:original_request).freeze
+          @generation = data.fetch(:generation, 0)
+          @enabled_toolsets = data[:enabled_toolsets]&.freeze
+          @verification_contract = data[:verification_contract]
+          @request = data.fetch(:request).freeze
+          @cwd = data.fetch(:cwd)
+          @started_at = Time.iso8601(data.fetch(:started_at))
+          @amendments = data.fetch(:amendments).map(&:freeze).freeze
+          @outcome = data[:outcome]&.freeze
+          @events = data.fetch(:events, [])
+          @effects = data.fetch(:effects, {}).transform_keys(&:to_s)
+          @evidence = data.fetch(:evidence, [])
+          @observations = data.fetch(:observations).to_h do |path, row|
+            [path.to_s, row.merge(head: Base64.strict_decode64(row[:head]), tail: Base64.strict_decode64(row[:tail]))]
+          end
+        end
+
         def record(event:, data:)
-          env = defined?(PWN::Env) ? PWN::Env : {}
-          engine = @route[:provider] || Thread.current[:pwn_swarm_engine] || env.dig(:ai, :active)
-          model = @route[:model] || Thread.current[:pwn_swarm_model] || env.dig(:ai, engine.to_s.to_sym, :model)
+          return unless @trace
+
+          engine = @route[:provider] || @engine
+          model = @route[:model] || @model || @provider_config.dig(engine.to_s.to_sym, :model)
           PWN::SessionTrace.append(session_id: @session_id, event: event, data: data, model: model,
                                    params: @route.merge(provider: engine))
         end
@@ -86,6 +556,27 @@ module PWN
             #{self}.authors
             # Print this usage.
             #{self}.help
+
+            # RequestRuntime instances own immutable original_request, ordered amendments,
+            # an effective request, a revision-bound host observation ledger and outcome.
+            # new accepts request:, session_id:, request_id:, artifact_root:, resume:,
+            # profile:, profiles:, window:, tool_cap:, trace:, retrieve:,
+            # enabled_toolsets:, verification_contract:, provider_config:, engine:,
+            # model:, provider_attempts: (default 5 across all routes), cancel: callback.
+            # scheduled_calls(calls, session_id:) overlaps at most eight audited
+            # independent reads; conflicting resources and unknown tools are barriers.
+            # evidence holds typed host verifier observations with source clause IDs,
+            # exact locators, digests and freshness. Tool stdout is never evidence.
+            # reconcile_effect!(payload_sha256:, evidence_id:, operator_approved:)
+            # requires fresh independent exact-target proof after uncertainty.
+            # execute_tool owns durable start/end events and uncertain mutation replay denial.
+            # events includes verifier reports independent of compacted chat messages.
+            # Checkpoint generation checks reject stale writers. Loop restores a session's
+            # active OpenGoal identity on a bare continue request.
+            # amend!(instruction:) adds scope by default; replace: and cancel are explicit.
+            # observe!(observations:) accepts host-only TurnFinalizer snapshots.
+            # finish!(status:, unmet:) persists complete/incomplete/blocked/cancelled/verification_error.
+            # resume: true requires the same session_id/request_id/root and never replays tools.
           "
         end
       end