pwn 0.5.761 → 0.5.762

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6748541ed45249f60331d0a819803c7c872527b763806edbcdd601ca30e862dc
-  data.tar.gz: e9f1ff039dafe19a3f250df08896bdf2498f6c5550d28dae4c83e2a071560c58
+  metadata.gz: 20f94659af48e0dba30534ed36cfaf8942497dcc5851e346a44ef40c51abb130
+  data.tar.gz: 8f91abcce730d25f6721d89aa6389090aa572b40ffe7449cd419a874d15d1932
 SHA512:
-  metadata.gz: 4c07ed5325a0db30c3933f8157e72b65e1f1ff3428e1944fb43f5809390cc647486fd9ed36b76c3986a2c55f75fba0d49c552ab3a1cb4b6dc1dc1e7669e3615f
-  data.tar.gz: 880e597ef1c96a3cc197bdf56b317f1e0854d17ffafcf7780c6f97ca198bce7dbcda6c971bdf0fba0d2feea29de7794f6e7af1cf9d17d99471e325e19db9582a
+  metadata.gz: 8174ba5855b3cb25e41eabe9c34a57add502f6b1d52caef2809bd603e66eab5dd1a169e01e1e06feb5c745ffddaa817fbaae9748458933c35c727a5a9c18b736
+  data.tar.gz: 111e5b05d8ad0c54f82ba0ae1836fb9ab1f8f3c1845c992d2dbacf7a241286e6ea139c9714d91e58ee80a246a119bdadf59e71d6a0f65e30fc224b96a9de2b7a

data/README.md

@@ -278,12 +278,12 @@ If this project helped you and you want to support the work, keep us caffeinated
 
 ### [**0x004D65726368**](https://0day.myspreadshop.com/) ###
 
-[![PWN Sticker](https://image.spreadshirtmedia.com/image-server/v1/products/T1459A839PA3861PT28D1044068794FS8193/views/1,width=300,height=300,appearanceId=839,backgroundColor=000000/ultimate-hacker-t-shirt-to-convey-to-the-public-a-hackers-favorite-past-time.jpg)](https://0day.myspreadshop.com/stickers)
+[![PWN Sticker](https://image.spreadshirtmedia.com/image-server/v1/products/T1459A839PA3861PT28D1044068794W10000H3537/views/1,width=300,height=300,appearanceId=839,backgroundColor=000000/ultimate-hacker-t-shirt-to-convey-to-the-public-a-hackers-favorite-past-time.jpg)](https://0day.myspreadshop.com/home+%26+living+stickers+%26+magnets)
 
-[![Coffee Mug](https://image.spreadshirtmedia.com/image-server/v1/products/T1313A1PA3933PT10X2Y25D1020472680FS6327/views/3,width=300,height=300,appearanceId=1,backgroundColor=000000/https0dayinccom.jpg)](https://0day.myspreadshop.com/accessories+mugs+%26+drinkware)
+[![Coffee Mug](https://image.spreadshirtmedia.com/image-server/v1/products/T1313A1PA3933PT10X3Y20D1044068794W5491H1942/views/3,width=300,height=300,appearanceId=1,backgroundColor=000000,crop=detail,modelId=11707/ultimate-hacker-t-shirt-to-convey-to-the-public-a-hackers-favorite-past-time.jpg)](https://0day.myspreadshop.com/home+%26+living+mugs+%26+drinkwear)
 
-[![Mouse Pad](https://image.spreadshirtmedia.com/image-server/v1/products/T993A1PA2168PT10X162Y26D1044068794S100/views/1,width=300,height=300,appearanceId=1,backgroundColor=000000/ultimate-hacker-t-shirt-to-convey-to-the-public-a-hackers-favorite-past-time.jpg)](https://0day.myspreadshop.com/accessories)
+[![Mouse Pad](https://image.spreadshirtmedia.com/image-server/v1/products/T993A1PA2168PT10X162Y26D1044068794W6102H2158/views/1,width=300,height=300,appearanceId=1,backgroundColor=000000/ultimate-hacker-t-shirt-to-convey-to-the-public-a-hackers-favorite-past-time.jpg)](https://0day.myspreadshop.com/home+%26+living+other)
 
-[![0day Inc.](https://image.spreadshirtmedia.com/image-server/v1/products/T951A550PA3076PT17X0Y73D1020472680FS8515/views/1,width=300,height=300,appearanceId=70,backgroundColor=000000/https0dayinccom.jpg)](https://shop.spreadshirt.com/0day/0dayinc-A5c3e498cf937643162a01b5f?productType=951&appearance=70)
+[![0day Inc.](https://image.spreadshirtmedia.com/image-server/v1/products/T803A2PA1648PT32X20Y18D1020472680W8807H1441/views/1,width=300,height=300,appearanceId=2,backgroundColor=000000,crop=detail,modelId=1723/https0dayinccom.jpg)](https://0day.myspreadshop.com/0dayinc-A5c3e498cf937643162a01b5f?productType=803&sellable=1naaRYxY1zhOoQlv7Mdg-803-34&appearance=2&size=29)
 
-[![Black Fingerprint Hoodie](https://image.spreadshirtmedia.com/image-server/v1/products/T111A2PA3208PT17X169Y51D1020472728FS6268/views/1,width=300,height=300,appearanceId=2/https0dayinccom.jpg)](https://shop.spreadshirt.com/0day/blackfingerprint-A5c3e49db1cbf3a0b9596b4d0?productType=111&appearance=2)
+[![Black Fingerprint Hoodie](https://image.spreadshirtmedia.com/image-server/v1/products/T111A2PA4247PT17X198Y27D1020472728W12744H19015/views/1,width=300,height=300,appearanceId=5,backgroundColor=000000,crop=detail,modelId=1159/https0dayinccom.jpg)](https://0day.myspreadshop.com/blackfingerprint-A5c3e49db1cbf3a0b9596b4d0?productType=111&sellable=ekXXmGonOyclynglNE87-111-22&appearance=5)

data/documentation/Swarm.md

@@ -18,6 +18,119 @@ self-improvement loop covers the whole swarm.
 No daemon. Cross-session / cross-process communication == another `pwn-ai` (or
 a `PWN::Cron` job) calling `Swarm.ask` with the same `swarm_id`.
 
+## Run one mission with a built-in team
+
+```text
+/swarm mission Write and test a Ruby function that validates the supplied data format
+```
+
+No persona setup is required. The exact text after `/swarm mission ` remains the
+user request for **every** role; role instructions and JSON handoffs go in system
+context, not a replacement task. Empty requests fail before dispatch. Existing
+`dm`, `broadcast`, and `debate` retain their messaging semantics. `/swarm agents`
+lists available personas; `/swarm dm NAME REQUEST` messages one persona.
+The renamed slash commands replace the previous spellings without compatibility
+aliases. Ruby APIs `Swarm.solve`, `Swarm.ask`, and the `Solve` coordinator are unchanged.
+
+`/menu` and Tab use case-insensitive alphabetical ordering at every depth:
+root commands, command actions, and live parameter lists (including agents,
+jobs, MCP tools, sessions, skills, memory keys, and cron jobs). Exact spelling
+breaks case-insensitive ties; selections keep their original command payloads.
+
+1. **Antagonist** independently enumerates requirements and risks before seeing
+   a candidate. `R0` always contains the entire unchanged original request.
+2. **Protagonist** builds the candidate using the ordinary nested tool-calling
+   `Loop.run` through `Swarm.ask`, then declares relative artifact paths.
+3. **Antagonist** critiques the candidate and returns unresolved objections.
+4. **Verifier** proposes requirement-indexed commands and exact expected stdout.
+   The coordinator executes them via the registered `shell` tool and `Dispatch`,
+   capturing actual stdout, stderr, and exit status. Model-supplied observations
+   are never accepted as execution evidence.
+5. **Integrator** reviews those observations and either accepts or sends a
+   targeted repair to the protagonist. Repairs always repeat critique and tests.
+
+Acceptance additionally requires every requirement ID to have passing executed
+evidence, no open objections, every check to exit zero with its expected output,
+and unchanged artifact hashes and steering revision. A model's `accept` alone
+cannot complete the job. Candidate and handoff revisions are SHA-256-bound;
+changed files, stale handoffs, failed checks, uncovered requirements, malformed
+JSON, provider failures and limits return **INCOMPLETE**, never success. Structured
+records and raw execution observations are saved with owner-only permissions in
+`~/.pwn/swarm/<solve-id>/solve.json`. Every solve gets fresh role sessions, so an
+earlier candidate cannot contaminate the independent initial assessment.
+
+### Console and controls
+
+Open the swarm workspace with **Ctrl+S / Ctrl+G**, keep a mission in the composer,
+then press **v — Mission with team**. Enter confirms the exact draft and built-in
+roles; Esc aborts without changing the draft or cursor. The jobs detail view
+shows actual role phases, original requirements, provider/model routes, artifact
+hashes, and open objections. There is one integrated final result. Provider usage
+continues through the console's existing usage observer (no invented estimates).
+
+```text
+/swarm status JOB
+/swarm steer JOB Add this verification constraint
+/swarm pause JOB
+/swarm resume JOB
+/swarm cancel JOB
+```
+
+The same slash routes work in the legacy line console. Steering belongs to the
+coordinator and is propagated to later roles; it invalidates previously accepted
+candidate evidence without replacing the original goal. Pause stops future
+dispatch at safe boundaries. Cancel interrupts the owned model wait; an already
+running tool finishes first, and its changes are not undone. Another job cannot
+start in the same controller while solve owns the workspace. A workspace file
+lock also excludes overlapping solve coordinators across processes.
+
+### Role configuration and limits
+
+All roles inherit the already selected provider and that provider's configured
+default model. Optional overrides use **existing** persona fields; no new vault
+configuration keys or schema migration is needed:
+
+```text
+/swarm spawn solve_antagonist Review correctness --engine ollama --model YOUR_INSTALLED_MODEL
+```
+
+The other names are `solve_protagonist`, `solve_verifier`, and `solve_integrator`.
+They can also be defined in `agents.yml`. Engine/model overrides are request-local;
+there is no superiority ranking, automatic diversity, or fallback to a different
+provider. Remote credentials must already be configured. Solve never initiates
+OAuth login or prompts for API keys; configured OAuth refresh remains the provider's
+normal noninteractive operation. Implicit local-agent escalation is disabled for
+solve. A missing provider fails visibly rather than silently switching.
+
+Ruby API: `Swarm.solve(request:, workspace: Dir.pwd, rounds: 3, swarm_id: nil,
+steering: nil, on_state: nil, on_tool: nil, usage_observer: nil)`. `swarm_id` supplies
+role overrides; the returned solve ID identifies the independent records. The
+default round limit is 3 (API range 1–10), each role turn is limited to 25 model
+calls, and each of at most 32 checks per round has a 60-second tool timeout.
+
+### Boundaries, not a security sandbox
+
+The protagonist is the only model role with write-capable tools (`shell` and
+`pwn_eval`). Review roles have no tools; Dispatch denies invented tool calls even
+if a provider ignores its empty tool schema. Integrator repairs are dispatched
+back to that one writer. This is role capability enforcement, **not** confinement
+of arbitrary protagonist Ruby or shell code or other processes on the host.
+
+Verification runs in fresh disposable copies of declared regular-file artifacts;
+all test dependencies must be declared. Symlinks/out-of-workspace artifacts are
+rejected, and input copies must retain their candidate hashes after a check.
+Files over 128 KiB cannot currently be passed to full-content review and produce
+an explicit incomplete result. A disposable directory is **not an OS sandbox**:
+test code can use absolute paths, network, installed dependencies and host resources.
+Existing Dispatch confirmation and `ai_sandbox` policies still apply. Use only
+trusted test commands or supply external OS isolation when executing untrusted code.
+
+Requirement extraction and test relevance still require model judgment. Executed
+checks are evidence for their stated assertions, not mathematical proof of an
+arbitrary natural-language goal; the saved commands, outputs, requirements and
+revisions make that judgment inspectable. No live-provider reliability or automatic
+security isolation is implied by the deterministic offline integration tests.
+
 ## Define personas
 
 Each persona accepts optional `engine` and `model` keys. `model` is the exact

data/documentation/pwn-ai-Agent.md

@@ -300,7 +300,7 @@ and Ctrl+D still work. A running tool finishes cooperatively: neither rollback
 nor remote provider billing cancellation is promised. Swarm jobs should use
 noninteractive tools; their individual stdin prompts are not multiplexed.
 
-Typed `/swarm roster|status|create|use|spawn|retire|ask|broadcast|debate|tail|steer|cancel`
+Typed `/swarm agents|mission|status|create|use|spawn|retire|dm|broadcast|debate|tail|steer|pause|resume|cancel`
 commands remain available, including parameter completion. These are direct
 operator commands and do not add the workspace's extra confirmation step.
 `/swarm status JOB` includes retained outcomes. Jobs shown here belong to this

data/etc/default_skills/pwn/ai/agent/solve/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pwn-ai-agent-solve
+description: Drive PWN::AI::Agent::Solve from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::AI::Agent::Solve
+  source: pwn/ai/agent/solve.rb
+---
+
+# PWN::AI::Agent::Solve
+
+Revision-bound, single-writer team coordinator. Role replies are proposals, never observations. Only host-executed checks can become evidence.
+
+## When to use
+
+Call `PWN::AI::Agent::Solve` from `pwn_eval` when the task needs this module.
+Do not reimplement it in shell.
+
+## Methodologies
+
+Generated from `pwn/ai/agent/solve.rb`. Prefer the public class methods below.
+Class methods take `(opts = {})` and read `opts`.
+
+## How to call
+
+```ruby
+PWN::AI::Agent::Solve.help
+PWN::AI::Agent::Solve.help(opts)
+```
+
+## Public methods
+
+- `authors`
+- `help`
+
+## Source
+
+`pwn/ai/agent/solve.rb`
+
+## Verification
+
+`PWN::AI::Agent::Solve.respond_to?(:authors)` after the
+module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/ai/agent/swarm/SKILL.md

@@ -43,6 +43,7 @@ PWN::AI::Agent::Swarm.personas(opts)
 - `ask`
 - `debate`
 - `broadcast`
+- `solve`
 - `map_targets`
 - `fact_record`
 - `facts_prompt`

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

@@ -51,6 +51,9 @@ module PWN
           entry = Registry.lookup(name: name) || Registry.lookup(name: repair_name(name: name))
           return JSON.generate(error: "unknown tool: #{name}") unless entry
 
+          solve_tools = Thread.current[:pwn_solve_tools]
+          return JSON.generate(success: false, error: 'Tool denied by solve role capability boundary') if solve_tools && !solve_tools.include?(entry.name.to_s)
+
           args = parse_args(raw: raw, entry: entry)
           args = alias_known_keys(args: args, entry: entry)
           schema = entry.schema[:parameters] || entry.schema['parameters'] || { type: 'object' }

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

@@ -1704,6 +1704,8 @@ module PWN
         # export_finetune can later teach the LoRA to NOT need it.
         @escalate_warned = false
         private_class_method def self.escalate(opts = {})
+          return if Thread.current[:pwn_solve_tools]
+
           request    = opts[:request]
           turn_fails = opts[:turn_fails]
           persona    = agent_flag(key: :escalation_persona)
@@ -2058,7 +2060,7 @@ module PWN
           )
 
           runtime = Thread.current[:pwn_request_runtime]
-          if runtime.respond_to?(:call)
+          if runtime.respond_to?(:call) && !Thread.current[:pwn_solve_tools]
             return runtime.call(messages: messages, tools: tools) do |prepared, route|
               invoke_provider_chat(engine: (route || {})[:provider] || active_engine, messages: prepared, tools: tools, model: (route || {})[:model], temp: (route || {})[:temperature])
             end
@@ -3160,6 +3162,16 @@ module PWN
         end
 
         # Commit the returned tool before unwinding, without stale recovery work.
+        # Child handoffs are proposals, never a user completion. Solve owns
+        # the original objective and the final artifact/evidence gate.
+        private_class_method def self.solve_handoff?(opts = {})
+          return false unless opts[:solve_handoff] && Thread.current[:pwn_solve_tools] && Array(opts[:calls]).empty?
+
+          JSON.parse(opts[:text]).is_a?(Hash)
+        rescue JSON::ParserError
+          false
+        end
+
         private_class_method def self.steering_tool_checkpoint!(opts = {})
           opts[:steering]&.checkpoint(messages: opts[:messages], phase: :tool) do
             tc = opts[:tool_call]
@@ -3348,7 +3360,7 @@ module PWN
           trivia = world_knowledge?(request: request)
           catalog = catalog_lookup?(request: request)
           browse = request_need(request: request) == :browse
-          skip_compass = trivia || catalog || no_tools || browse
+          skip_compass = trivia || catalog || no_tools || browse || opts[:solve_handoff]
           # Trivia / catalog / browse do not get an implement-shaped
           # English compass. Inventing "apply code/host changes" there
           # keeps the model on a Navigate task after the page already loaded.
@@ -3372,7 +3384,7 @@ module PWN
           Thread.current[:pwn_plan_predicted] = nil
           cal_state = calibration_state
           force_plan = cal_state[:force_plan]
-          skip_plan = %i[howto recall greeting].include?(intent) || trivia || catalog || no_tools || browse
+          skip_plan = %i[howto recall greeting].include?(intent) || skip_compass
           did_plan = false
           if !skip_plan && (force_plan || agent_flag(key: :plan_first, default: local) || budget_exhaustion_hot?) && !Array(tools).empty?
             predicted = plan_first(messages: messages, request: request, ts_state: ts_state)
@@ -3523,6 +3535,8 @@ module PWN
 
             messages << msg
 
+            return text if solve_handoff?(opts.merge(text: text, calls: calls))
+
             if calls.empty?
               # P28 — refuse polite mid-goal handoffs so multi-step tasks stay autonomous.
               if incomplete_final?(text: text, last_iter: false)
@@ -3650,7 +3664,7 @@ module PWN
                 # P17 — never fork counterfactual when budget fingerprints dominate:
                 # CF is another mini agent loop and is the #1 amplifier of
                 # iteration-budget exhaustion on this host.
-                if count >= thresh && !retryable_execution_failure?(raw: raw) && !escalated && defined?(Curriculum) && !budget_exhaustion_hot?
+                if count >= thresh && !retryable_execution_failure?(raw: raw) && !escalated && defined?(Curriculum) && !budget_exhaustion_hot? && !opts[:solve_handoff]
                   cf = (turn_fails["cf:#{fkey}"] += 1) == 1 ? Curriculum.counterfactual(request: request, name: name, args: args, error: tele[:err] || raw[0, 200], hint: hint) : nil
                   hint = "#{hint}\n[pwn-ai/counterfactual] branch #{cf[:branch]} (score=#{cf[:score].round(2)}): #{cf[:content]}" if cf
                 end

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

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'tmpdir'
+require 'shellwords'
+require 'stringio'
+
+module PWN
+  module AI
+    module Agent
+      # Revision-bound, single-writer team coordinator. Role replies are proposals,
+      # never observations. Only host-executed checks can become evidence.
+      module Solve
+        ROLES = %w[protagonist antagonist verifier integrator].freeze
+
+        # Steering belongs to the objective, not to one child's replacement request.
+        class Control < Loop::Steering
+          class Stopped < Exception; end # rubocop:disable Lint/InheritException -- escape provider retry handlers
+          class Limit < Exception; end # rubocop:disable Lint/InheritException -- bounded role dispatch
+
+          def initialize(**args)
+            super
+            @solve_mutex = Mutex.new
+            @guidance = []
+            @paused = false
+            @stopped = false
+          end
+
+          def submit(instruction)
+            return if instruction.to_s.strip.empty?
+
+            @solve_mutex.synchronize { @guidance << instruction.to_s.dup }
+          end
+
+          def guidance
+            @solve_mutex.synchronize { @guidance.dup }
+          end
+
+          def begin_turn
+            @model_calls = 0
+          end
+
+          def model(messages:, &block)
+            check_stop
+            @model_calls = @model_calls.to_i + 1
+            raise Limit, 'Role model-call limit reached (25); objective remains incomplete.' if @model_calls > 25
+
+            super
+          end
+
+          def stop
+            @solve_mutex.synchronize { @stopped = true }
+            request_model_cancel
+          end
+
+          def pause(value)
+            @solve_mutex.synchronize { @paused = value }
+          end
+
+          def check_stop
+            loop do
+              stopped, paused = @solve_mutex.synchronize { [@stopped, @paused] }
+              raise Stopped, 'Solve cancelled at a safe boundary; completed work is not undone.' if stopped
+              break unless paused
+
+              sleep 0.05
+            end
+          end
+
+          def checkpoint(**options)
+            @phase = options[:phase] || :boundary
+            check_stop
+          rescue Stopped
+            yield if block_given?
+            raise
+          end
+        end
+
+        # Serial role dispatch ensures there is exactly one model writer.
+        class Run # rubocop:disable Metrics/ClassLength -- one revision-bound coordinator lifecycle
+          def initialize(opts)
+            @opts = opts
+            @request = opts[:request].to_s.dup.freeze
+            raise ArgumentError, 'request is required' if @request.strip.empty?
+
+            @workspace = File.realpath(opts[:workspace] || Dir.pwd)
+            @rounds = Integer(opts.fetch(:rounds, 3))
+            raise ArgumentError, 'rounds must be between 1 and 10' unless @rounds.between?(1, 10)
+
+            @control = opts[:steering] || Control.new(input: StringIO.new, output: StringIO.new)
+            raise ArgumentError, 'solve requires Solve::Control for coordinator-wide steering' unless @control.is_a?(Control)
+
+            @requirements = { 'R0' => @request }
+            @states = ROLES.to_h { |role| [role, 'waiting'] }
+            @records = []
+            @evidence = []
+            @objections = []
+            @artifacts = {}
+            @revision = nil
+            @repair = nil
+            @guidance = []
+          end
+
+          def run
+            prepare
+            assessment = turn('antagonist', 'assess')
+            Array(assessment.fetch(:requirements)).each_with_index { |text, i| @requirements["R#{i + 1}"] = text.to_s }
+            @assessment = assessment
+            @rounds.times do |index|
+              @round = index + 1
+              boundary
+              @guidance = guidance
+              @guidance.each_with_index { |instruction, i| @requirements["S#{i + 1}"] = instruction }
+              candidate = turn('protagonist', 'build')
+              @artifacts = observe(candidate.fetch(:artifacts))
+              raise ArgumentError, 'candidate must declare at least one existing artifact' if @artifacts.empty?
+
+              @revision = digest(run: @sid, round: @round, request: @request, requirements: @requirements, artifacts: @artifacts, guidance: @guidance)
+              @records << { role: 'coordinator', phase: 'candidate', revision: @revision, artifacts: @artifacts.dup, round: @round }
+              @candidate = candidate
+              critique = turn('antagonist', 'critique')
+              @objections = Array(critique.fetch(:objections))
+              verification = turn('verifier', 'verify')
+              @evidence = execute_checks(verification.fetch(:checks))
+              integration = turn('integrator', 'integrate')
+              boundary
+              return result('accepted', integration[:summary].to_s) if integration[:decision] == 'accept' && acceptable?
+
+              @repair = { instruction: integration[:repair], objections: @objections, evidence: @evidence,
+                          stale: !current?, uncovered: uncovered }
+            end
+            result('incomplete', 'Round limit reached; unresolved, stale, or unverified requirements remain.')
+          rescue Control::Stopped => e
+            result('cancelled', e.message)
+          rescue Control::Limit => e
+            result('incomplete', e.message)
+          rescue StandardError => e
+            result('incomplete', "#{e.class}: #{e.message}")
+          ensure
+            @lock&.flock(File::LOCK_UN)
+            @lock&.close
+          end
+
+          private
+
+          def prepare
+            Registry.discover
+            # A file lock also excludes another process's solve writer in this workspace.
+            lock_path = File.join(Dir.tmpdir, "pwn-solve-#{Digest::SHA256.hexdigest(@workspace)}.lock")
+            @lock = File.open(lock_path, File::RDWR | File::CREAT, 0o600)
+            raise 'another solve owns this workspace' unless @lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+            configured = Swarm.personas(swarm_id: @opts[:swarm_id])
+            @sid = Swarm.create(topic: @request)[:swarm_id]
+            @personas = ROLES.to_h do |role|
+              persona = configured[:"solve_#{role}"] || {}
+              engine = (persona[:engine] || Thread.current[:pwn_swarm_engine] || PWN::Env.dig(:ai, :active)).to_s
+              raise ArgumentError, "unsupported solve provider: #{engine}" unless Loop::ENGINE_MODS.key?(engine.to_sym)
+
+              provider = PWN::Env.dig(:ai, engine.to_sym) || {}
+              credentials = [provider[:key], provider.dig(:oauth, :bearer_token), provider.dig(:oauth, :refresh_token)]
+              raise ArgumentError, "solve_#{role}: configure #{engine} credentials first; solve never starts a login" if engine != 'ollama' && credentials.none? { |value| !value.to_s.strip.empty? && !value.to_s.match?(/\A(?:optional|required)\s*-/) }
+
+              [role, persona.merge(engine: engine, toolsets: role == 'protagonist' ? %w[terminal pwn] : [],
+                                   role: "#{persona[:role]}\nBuilt-in solve #{role}. Follow the structured handoff; original request is the sole objective.")]
+            end
+          end
+
+          def turn(role, phase)
+            boundary
+            @control.begin_turn
+            @states[role] = phase
+            emit
+            payload = { phase: phase, role: role, original_request: @request, requirements: @requirements,
+                        workspace: @workspace, round: @round, revision: @revision, guidance: guidance,
+                        assessment: @assessment, candidate: @candidate, artifacts: artifact_text,
+                        objections: @objections, evidence: @evidence, repair: @repair }
+            prior = Thread.current[:pwn_solve_tools]
+            Thread.current[:pwn_solve_tools] = role == 'protagonist' ? %w[shell pwn_eval] : []
+            reply = Swarm.ask(name: "solve_#{role}", persona: @personas.fetch(role), request: @request,
+                              swarm_id: @sid, handoff: "#{contract(phase)}\nSOLVE HANDOFF\n#{JSON.generate(payload)}",
+                              steering: @control, usage_observer: @opts[:usage_observer], on_tool: @opts[:on_tool])
+            row = JSON.parse(reply.fetch(:reply), symbolize_names: true)
+            raise ArgumentError, "#{role} handoff must be an object" unless row.is_a?(Hash)
+            raise ArgumentError, "#{role} returned a stale revision" if %w[critique verify integrate].include?(phase) && row[:revision] != @revision
+
+            @records << { role: role, phase: phase, revision: @revision, data: row }
+            @states[role] = 'done'
+            emit
+            row
+          ensure
+            Thread.current[:pwn_solve_tools] = prior
+          end
+
+          def contract(phase)
+            shapes = {
+              'assess' => '{"requirements":["every atomic requirement in original request"],"risks":["independent risk assessment"]}',
+              'build' => '{"artifacts":["relative/file"],"summary":"what changed"}',
+              'critique' => '{"revision":"exact revision","objections":["unresolved correctness issue; empty only if none"]}',
+              'verify' => '{"revision":"exact revision","checks":[{"requirements":["R0","R1"],"command":"real test command","stdout":"exact expected nonempty stdout"}]}',
+              'integrate' => '{"revision":"exact revision","decision":"accept or repair","repair":"targeted repair for protagonist","summary":"integrated result"}'
+            }
+            "Return ONLY a JSON object matching #{shapes.fetch(phase)}. Do not replace the objective. " \
+              'Protagonist alone may change files. Review roles have no tool access. Verification commands run by the coordinator ' \
+              'in a disposable copy of declared artifacts, not the working tree; declare all test dependencies as artifacts. ' \
+              'Checks must test the named requirements, not print a success claim. R0 covers the ENTIRE original request. ' \
+              'Never accept missing evidence, unresolved objections, or omitted requirements. Integration requests repairs; it does not write.'
+          end
+
+          def observe(paths)
+            Array(paths).to_h do |relative|
+              raise ArgumentError, 'artifact path must be relative' unless relative.is_a?(String) && !relative.start_with?('/')
+
+              path = File.realpath(File.join(@workspace, relative))
+              raise ArgumentError, "artifact outside workspace: #{relative}" unless path.start_with?("#{@workspace}/")
+              raise ArgumentError, "artifact must be a regular file: #{relative}" unless File.file?(path)
+              raise ArgumentError, "artifact symlink is not supported: #{relative}" unless path == File.expand_path(relative, @workspace)
+
+              [relative, Digest::SHA256.file(path).hexdigest]
+            end
+          end
+
+          def artifact_text
+            @artifacts.to_h do |path, sha|
+              bytes = File.binread(File.join(@workspace, path))
+              raise ArgumentError, "artifact too large for review: #{path} (limit 128 KiB)" if bytes.bytesize > 131_072
+
+              [path, { sha256: sha, text: bytes.encode('UTF-8', invalid: :replace, undef: :replace) }]
+            end
+          end
+
+          def execute_checks(checks)
+            raise ArgumentError, 'verifier must supply 1..32 checks' unless checks.is_a?(Array) && checks.length.between?(1, 32)
+
+            @states['verifier'] = 'checking'
+            emit
+            observations = checks.map do |check|
+              boundary
+              ids = Array(check[:requirements]).map(&:to_s)
+              raise ArgumentError, 'check must name known requirements' if ids.empty? || (ids - @requirements.keys).any?
+              raise ArgumentError, 'check needs a command and nonempty expected stdout' if check[:command].to_s.strip.empty? || check[:stdout].to_s.empty?
+
+              execute_check(check, ids)
+            end
+            @states['verifier'] = 'done'
+            @records << { role: 'verifier', phase: 'verification', revision: @revision, evidence: observations }
+            emit
+            observations
+          end
+
+          def execute_check(check, ids)
+            Dir.mktmpdir('pwn-solve-verify') do |copy|
+              @artifacts.each_key do |path|
+                destination = File.expand_path(path, copy)
+                raise ArgumentError, 'invalid artifact copy path' unless destination.start_with?("#{copy}/")
+
+                FileUtils.mkdir_p(File.dirname(destination))
+                FileUtils.cp(File.join(@workspace, path), destination)
+              end
+              copied = @artifacts.to_h { |path, _sha| [path, Digest::SHA256.file(File.join(copy, path)).hexdigest] }
+              raise 'candidate changed while copying verification inputs' unless copied == @artifacts
+
+              prior = Thread.current[:pwn_solve_tools]
+              Thread.current[:pwn_solve_tools] = ['shell']
+              command = "cd #{Shellwords.escape(copy)} && (#{check[:command]})"
+              raw = Dispatch.call(tool_call: { id: SecureRandom.hex(8), function: { name: 'shell', arguments: JSON.generate(command: command, timeout: 60) } })
+              @opts[:on_tool]&.call('shell', { command: command }, raw)
+              response = JSON.parse(raw, symbolize_names: true)
+              observed = response[:result].is_a?(Hash) ? response[:result] : {}
+              unchanged = @artifacts.all? { |path, sha| File.file?(File.join(copy, path)) && Digest::SHA256.file(File.join(copy, path)).hexdigest == sha }
+              { requirements: ids, revision: @revision, command: check[:command], stdout: observed[:stdout],
+                stderr: observed[:stderr], exitstatus: observed[:exit], raw: raw,
+                passed: response[:success] == true && observed[:exit].is_a?(Integer) && observed[:exit].zero? && observed[:stdout] == check[:stdout] && unchanged && current? }
+            ensure
+              Thread.current[:pwn_solve_tools] = prior
+            end
+          end
+
+          def current?
+            guidance == @guidance && observe(@artifacts.keys) == @artifacts
+          rescue StandardError
+            false
+          end
+
+          def uncovered
+            @requirements.keys - @evidence.select { |row| row[:passed] && row[:revision] == @revision }.flat_map { |row| row[:requirements] }
+          end
+
+          def acceptable?
+            !@evidence.empty? && @evidence.all? { |row| row[:passed] } && uncovered.empty? && @objections.empty? && current?
+          end
+
+          def digest(value)
+            Digest::SHA256.hexdigest(JSON.generate(value))
+          end
+
+          def guidance
+            @control.respond_to?(:guidance) ? @control.guidance : []
+          end
+
+          def boundary
+            @control&.check_stop
+          end
+
+          def emit
+            @opts[:on_state]&.call({ roles: @states.dup, request: @request, requirements: @requirements.dup,
+                                     artifacts: @artifacts.dup, objections: @objections.dup, round: @round, revision: @revision,
+                                     routing: (@personas || {}).transform_values { |row| row.slice(:engine, :model) } })
+          end
+
+          def result(status, summary)
+            @states.transform_values! { |state| %w[waiting done].include?(state) ? state : status }
+            emit
+            path = File.join(Swarm::SWARM_ROOT, @sid, 'solve.json') if @sid
+            report = ["#{status.upcase}: #{summary}", "Original request: #{@request}", "Revision: #{@revision || 'none'}",
+                      "Artifacts: #{@artifacts.keys.join(', ')}", "Evidence coverage: #{(@requirements.keys - uncovered).join(', ')}",
+                      "Unverified: #{uncovered.join(', ')}", "Open objections: #{@objections.join('; ')}", "Record: #{path}"].join("\n")
+            outcome = { ok: status == 'accepted', status: status, request: @request, swarm_id: @sid, revision: @revision,
+                        requirements: @requirements, artifacts: @artifacts, objections: @objections, evidence: @evidence,
+                        records: @records, uncovered: uncovered, reply: report, record_path: path }
+            File.write(path, JSON.pretty_generate(outcome), mode: 'w', perm: 0o600) if path
+            outcome
+          end
+        end
+
+        public_class_method def self.authors
+          'AUTHOR(S): 0day Inc. <support@0dayinc.com>'
+        end
+
+        public_class_method def self.help
+          puts "USAGE:
+            # Run a revision-bound team through the public Swarm solve entry point.
+            PWN::AI::Agent::Swarm.solve(request: 'required - original objective')
+            # Return module authors.
+            #{self}.authors
+          "
+        end
+      end
+    end
+  end
+end