pwn 0.5.723 → 0.5.725

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ba71758dbd8a3d5231af6489af4c3dd2bd25c0c16df3fd3292b14a77abdf851
-  data.tar.gz: 31c99dda2f5bac281c8ba2b4cc7b7b4493f6c3f09cbbe6788a1067d177ec5ecc
+  metadata.gz: 3ada4e79d8d8864ce2ea48b7378b4d10e124e7925d050424d3ef10e269438d5f
+  data.tar.gz: 714c044b1ab48bf33ca175d73fee3997d0788ed9d34e6c124d59c7fdf630c01e
 SHA512:
-  metadata.gz: 5f17d3c8729c22425cfef5b71746c82bc03eaec569b2d470a83e0734a72e8f411bf8542bc302091211f5f6dc578e5fb64b5a72f97fdb2d8d2f4b8f9f7601100d
-  data.tar.gz: 6359d1601fa3cc2f340c3edd8efbe71578c0d580c1c7da6dcc212cd2ab56011455cb10578e11d7be9c359c406b2da5d33a6c1eedaa46f73a5a2a0e59d12c8199
+  metadata.gz: 2472a6aa034cd281f4b2b67804558b7f40827abfca843857b7f713d1c492a9ea1e3c2bfd03282134bc2d2270e1db77cdc7c20876b0f4baf58d5b36c929ba536f
+  data.tar.gz: e7550328388a59e8d4047bceef0da28446850c2b0d40670930e104ea3ca7a89559aa65db510bd2d2e60f02053f85a98890a5bd96fee7d0435d1a53c845a5fe44

data/Gemfile

@@ -49,7 +49,7 @@ gem 'jwt', '3.2.0'
 gem 'libusb', '0.8.0'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
-gem 'mcp', '1.5.0'
+gem 'mcp', '1.5.1'
 gem 'meshtastic', '0.0.175'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.25.0'
@@ -89,8 +89,8 @@ gem 'ruby-nmap', '1.0.3'
 gem 'ruby-saml', '1.18.1'
 gem 'rvm', '1.11.3.9'
 gem 'savon', '2.17.4'
-gem 'selenium-devtools', '0.152.0'
-gem 'selenium-webdriver', '4.48.0'
+gem 'selenium-devtools', '0.153.0'
+gem 'selenium-webdriver', '4.49.0'
 gem 'slack-ruby-client', '3.2.0'
 gem 'socksify', '1.8.1'
 gem 'spreadsheet', '1.3.5'

data/bin/pwn-ai

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'pwn/ai/cli'
+
+exit PWN::AI::CLI.run(argv: ARGV)

data/bin/pwn-capd

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Packaging-compatible driver; privileged deployments execute daemon.py directly.
+exec('/usr/bin/python3', '-I', File.expand_path('../lib/pwn/plugins/capability_broker/daemon.py', __dir__), *ARGV)

data/documentation/AI-Integration.md

@@ -113,8 +113,9 @@ puts resp[:content]
 
 ## Model diversity in Swarm
 
-Because each persona in [`agents.yml`](Swarm.md) can override `engine:`, an
-`agent_debate` can pit several *different providers* against each other - real
+Because each persona in [`agents.yml`](Swarm.md) can override `engine:` and
+`model:`, an `agent_debate` can compare different models on the same provider
+or several *different providers* against each other - real
 antagonism, not one model role-playing three voices. The same mechanism backs
 `ai.agent.escalation_persona`: when a local model is stuck, `Loop.run` asks a
 frontier persona for a 3-line corrective hint and injects it as a synthetic

data/documentation/Agent-Tool-Registry.md

@@ -10,10 +10,11 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 
 | Toolset | Tools | Backed by |
 |---|---|---|
+| `http` | `http_proxy_start` · `http_proxy_stop` · `http_proxy_entries` · `http_proxy_rules` · `http_replay` | `PWN::Plugins::MitmProxy`: native HTTP HAR capture/replay; opaque CONNECT tunnels |
 | `terminal` | `shell` | `Open3.capture3` on the host, after `PWN::AI::Agent::ToolGuard` |
 | `pwn` | `pwn_eval` | `TOPLEVEL_BINDING.eval` in the live REPL process, after `ToolGuard` |
 | `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` · **`memory_lean`** | `PWN::Memory` → `~/.pwn/memory.json` |
-| `skills` | **`skills_recall`** · `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` | `~/.pwn/skills/<name>/SKILL.md` (**[agentskills.io](https://agentskills.io) spec**; legacy flat `*.md` auto-migrated) |
+| `skills` | `skills_consolidate` · **`skills_recall`** · `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` | `~/.pwn/skills/<name>/SKILL.md` (**[agentskills.io](https://agentskills.io) spec**; legacy flat `*.md` auto-migrated) |
 | `sessions` | **`session_recall`** · `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` · **`sessions_lean`** | `PWN::Sessions` → `~/.pwn/sessions/` |
 | `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · **`learning_gc_stores`** · **`learning_purge_noise`** · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** · **`mistakes_lean`** · **`reward_judge`** · **`reward_prm`** · **`reward_sentinel`** · **`reward_preferences`** · **`reward_export_dpo`** · **`reward_warm_sentinel`** · **`reward_scrub_preferences`** · **`reward_preference_balance`** · **`curriculum_practice`** · **`curriculum_train`** · **`curriculum_hindsight`** · **`curriculum_offline_judge`** · **`curriculum_preference_balance`** | `PWN::AI::Agent::Learning` + `Mistakes` + `Reward` + `Curriculum` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` + `~/.pwn/preferences.jsonl` + `~/.pwn/curriculum/` + `~/.pwn/finetune/` |
 | `reward` | **`reward_generator_mix`** | `PWN::AI::Agent::Reward.generator_mix` → online preference source-mix controller (`preferences.jsonl`) |
@@ -23,6 +24,7 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 | `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · **`extro_watch`** · **`extro_verify`** · **`extro_rf_tune`** · **`extro_osint`** · **`extro_serial`** · **`extro_telecomm`** · **`extro_packet`** · **`extro_vision`** · **`extro_voice`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ Serial/Packet/OCR/Voice/BareSIP/TransparentBrowser/GQRX) → `~/.pwn/extrospection.json` |
 | `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |
 | `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |
+| `manifest` | `host_os_type` | YAML tool declarations in `lib/pwn/ai/tools/*.yaml` via `PWN::AI::Agent::Manifest` |
 
 The `learning` toolset is deliberately large: **Mistakes** (negative feedback),
 **Reward** (outcome and process judges, sentinel, preference ledger) and

data/documentation/Capability-Broker-Sandbox.md

@@ -0,0 +1,97 @@
+# Capability broker and disposable sandbox
+
+## pwn-capd (P8)
+
+The Python stdlib helper speaks one bounded JSON request per Unix connection.
+Linux SO_PEERCRED authenticates the configured caller UID; the client also
+checks the daemon UID. The socket is mode 0600. Only explicitly configured
+interfaces are accepted. Operations: `status`, `raw_send` (base64 Ethernet
+frame), `capture` (bounded in-memory pcap), `arp` / `nd` (typed IP kernel
+neighbor-cache queries). There is no command endpoint, arbitrary privileged
+output path, firewall mutation, or implicit sudo. ARP/ND currently query cache;
+they do not actively solicit neighbors or mutate entries.
+
+Operator installation (NOT executed by the application): install
+`lib/pwn/plugins/capability_broker/daemon.py` (not the Ruby packaging driver)
+root-owned under `/usr/local/libexec/pwn-capd`, mode 0755, in a root-owned
+non-writable directory. Do **not** setcap the system Ruby/Python interpreter
+or this script: Linux ignores script file capabilities, and granting a shared
+interpreter network privileges exposes every script. Use a dedicated systemd
+service with `User=<operator>`,  `AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN`,
+`CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN`, `NoNewPrivileges=yes`,
+`ProtectSystem=strict`, `ProtectHome=yes`, `RuntimeDirectory=pwn-capd`,
+`RestrictAddressFamilies=AF_UNIX AF_PACKET AF_NETLINK`, and the reviewed helper
+as ExecStart. The socket owner and configured peer UID must match that operator.
+Enable a preconfigured unit with `sudo systemctl start pwn-capd`.
+For an audited one-shot sudo launch use:
+
+```
+sudo /usr/local/libexec/pwn-capd --uid "$(id -u)" --interface lo
+```
+
+Never authorize unrestricted sudo access to arbitrary helper arguments. Pin
+UID, socket and interface in sudoers. Only add engagement interfaces after
+operator review. CAP_NET_ADMIN is reserved for future neighbor management;
+current operations need CAP_NET_RAW, while neighbor queries are read-only.
+
+Ruby API (explicit require until central autoload is integrated):
+
+```ruby
+require 'pwn/plugins/capability_broker'
+PWN::Plugins::CapabilityBroker.request(operation: 'status')
+PWN::Plugins::CapabilityBroker.request(operation: 'arp', iface: 'lo', address: '127.0.0.1')
+PWN::Plugins::CapabilityBroker.request(operation: 'nd', iface: 'lo', address: '::1')
+# Packet.send(pkt:, iface:, socket:) and Packet.capture(path:, count:, timeout:, iface:, socket:)
+```
+
+`PWN_CAPD_SOCKET` overrides `/run/pwn-capd/control.sock`. Capture artifacts are
+written and read back by the unprivileged client, never by the daemon.
+Absent broker returns degraded error and missing local CAP_NET_RAW accurately;
+there is no fabricated capture path or privileged Ruby remediation.
+
+## Sandbox (P13)
+
+```ruby
+require 'pwn/plugins/sandbox'
+PWN::Plugins::Sandbox.run(binary: '/path/safe-fixture', argv: [], stdin: '', timeout: 10, memory_mb: 256)
+PWN::Plugins::Sandbox.fuzz(target: '/path/safe-fixture', corpus: '/path/seeds', minutes: 1, seed: 0)
+s = PWN::Plugins::Sandbox.snapshot(binary: '/path/safe-fixture')
+PWN::Plugins::Sandbox.rollback(snapshot: s[:snapshot], backend: 'bwrap')
+```
+
+Docker is default, image `pwn-sandbox:local`; it must be provisioned locally,
+with `/usr/bin/python3`, strace, GDB, and target runtime libraries. No implicit
+pull, installation, daemon startup or host-execution fallback occurs. Use the
+included `lib/pwn/plugins/sandbox/Dockerfile` to build explicitly. Network none,
+read-only root/artifacts, unprivileged UID, all caps dropped, no-new-privileges,
+pid/cpu/memory/swap constraints, disposable bounded tmpfs, forced cleanup.
+Instrumentation runs are separate replays with the same input, not observation
+of the original execution. Signals, PC, backtrace, raw GDB output are returned;
+exploitable classification is `unknown` if the GDB plugin is absent. No invented
+classification. Current `-nx` configuration deliberately does not load arbitrary
+user GDB startup scripts. Install a reviewed exploitable plugin into the image
+and extend its explicit initialization if classification is required.
+
+Explicit `backend: 'bwrap'` works without a Docker daemon where unprivileged
+user namespaces are permitted. It exposes only read-only system runtime trees
+and target artifact, creates fresh user/network/PID/mount namespaces, and hides
+home. It is a **weaker resource tier**: per-process RLIMIT_AS, not an aggregate
+cgroup budget or fork-bomb protection. Use Docker/microVM for hostile samples.
+No automatic backend fallback. Snapshot/rollback means verified immutable input
+copies and fresh disposable environments, **not live process/VM checkpoints**.
+Fuzzing is bounded seeded bit-flip stdin mutation, not coverage-guided AFL.
+
+Tools register via `require 'pwn/ai/agent/tools/sandbox'`: `sandbox_run` and
+`sandbox_fuzz`; normal Registry discovery finds that file.
+
+Verification:
+```
+bundle exec rspec spec/lib/pwn/plugins/{packet,capability_broker,sandbox}_spec.rb
+python3 spec/lib/pwn/plugins/capd_test.py
+python3 spec/lib/pwn/plugins/sandbox_test.py
+```
+
+Safe real Docker smoke after explicit provisioning:
+```
+bundle exec ruby -Ilib -rpwn/plugins/sandbox -e 'p PWN::Plugins::Sandbox.run(binary: "/bin/true")'
+```

data/documentation/Policy-Benchmark.md

@@ -18,8 +18,9 @@ bundle exec rubocop scripts/benchmark_policy.rb
 The experiment uses Ruby and its standard libraries; it does not require the
 full application boot sequence. Use a fresh Ruby process, not the live agent
 console. JSON is printed to stdout and optionally written to `--output`.
-`--self-check` runs independent scorer tests and both complete experimental arms;
-it prints a short pass message instead of a report. Use the options separately.
+`--self-check` runs independent scorer tests, both complete experimental arms,
+and two fresh snapshot workers; it prints short pass messages instead of a
+report. Use the options separately.
 The benchmark exits nonzero if persistence changes during evaluation, splits
 overlap, a negative control succeeds, or a positive control fails. Self-checks
 also require actual training updates in the on arm and none in the off arm.
@@ -36,8 +37,9 @@ not `Reward.judge`, model prose, or a previously assigned reward. It calls
 training. This is not a test of Reward's verification-record binding, the live
 Loop, Metrics learning, memory retrieval, or adapter training.
 
-The new `scripts/` directory keeps this experimental driver outside the installed
-CLI and production module tree; no module manifest or generated skill is needed.
+The experimental driver remains in `scripts/`. The opt-in `PolicyEvaluation`
+module launches only this fixed runner; it does not load the live agent in its
+workers. Its module autoload does not enable evaluation or promotion.
 
 ## Protocol
 
@@ -60,6 +62,10 @@ CLI and production module tree; no module manifest or generated skill is needed.
    answer keys to choose actions. Each call writes into a fresh task directory.
    Exact artifact correctness supplies a binary training label to Policy; the
    off arm executes the same work but Policy declines to update.
+   Each call has an explicit action ID. Only after the independent artifact
+   check, `finish` receives a `controlled_comparison` attribution receipt naming
+   that ID. This is a one-action isolated experiment, not a claim that the last
+   action in an arbitrary live trace caused the outcome.
 4. **Held-out evaluation.** Only after training, materialize eight distinct
    held-out inputs with literal answer keys: four numeric and four inventory
    tasks. Assert no training input appears in evaluation. Task families and
@@ -117,6 +123,9 @@ No fixed gains are embedded in the report.
 
 - **Completion:** tasks with at least one objectively successful attempt divided
   by evaluated tasks. A failed attempt does not count as task completion.
+- **Artifact check score:** each attempt earns 1.0 only for an exact correct
+  artifact with unchanged input, otherwise 0.0; phase score is its mean across
+  attempts. Report rows retain the actual artifact body as well as its hash.
 - **False-success count/rate:** attempts claiming `ok: true` without achieving the
   task; rate denominator is executed attempts, not tasks. This is false reporting
   by the handler, not acceptance of that report by the independent checker.
@@ -149,3 +158,139 @@ would undermine the no-network/no-credentials guarantee. A future live-model
 study should use a separately reviewed runner, identical model/tool budgets,
 external objective verifiers, frozen held-out evaluation, and actual provider
 usage records. Do not present this controller experiment as that study.
+
+## Opt-in independent snapshot evaluation (R5)
+
+The original commands and `off`/`on` report shape still work. To additionally
+export snapshots and run repeated evaluations in **fresh subprocesses**, use:
+
+```sh
+ruby scripts/benchmark_policy.rb --heldout \
+  --snapshot-dir /tmp/pwn-policy-snapshots \
+  --output /tmp/pwn-policy-heldout.json
+```
+
+The snapshot directory must be **new**, below `/tmp`, with no symlink parents.
+`off.json` and `on.json` are genuine Policy JSON tables after the same real
+training schedule. Exported `updated_at` metadata is normalized to `null` for
+reproducible snapshot digests; no Q entries or rewards are fabricated. Export
+happens before that arm's evaluation. Neither `--heldout` nor `--snapshot-dir`
+promotes anything or discovers/reads a real home-directory policy.
+
+The added `heldout` array contains protocol `pwn-policy-heldout-v2`, for suite
+indices 0 and 1. Each worker runs three frozen arms: `off` (baseline snapshot,
+policy disabled), `baseline` (baseline enabled), and `candidate` (candidate
+enabled). Workers never call begin/observe/finish, warmup, or reset the caller's
+policy. Resets and snapshot installation occur only inside temporary HOME.
+Only fixed local handlers are registered; no provider, shell tool, credential,
+user config, or network client is loaded. Environment variables, including Ruby
+startup hooks, are removed before spawning Ruby. Workers have a 30-second
+deadline; stalled children are killed and reaped. Snapshot inputs must be regular
+non-symlink files, at most 4 MiB, with valid numeric `q`, `h`, `visits`, `returns`,
+`n_updates`, and `td_abs_sum` fields. Parent directories cannot be symlinks.
+
+Suite indices 0..7 are bounded deterministic variations, **not random trials**.
+Numeric inputs and separate literal answer keys are scaled by `seed + 1`;
+inventory IDs and separate answer keys are offset by `100 * seed`. This does not
+call a candidate algorithm to construct its answer key. Even indices use flat
+paths and compact JSON; odd indices use nested paths containing spaces, pretty
+JSON, and read-only inputs. Every arm runs eight tasks, 16 negative controls and
+eight positive controls. Training fixtures remain unchanged and disjoint.
+These are two task families and two filesystem configurations, not unseen tools
+or broad environment generalization. Both environment types are required for
+promotion eligibility.
+For externally supplied snapshots, `disjoint_inputs` describes the harness's
+fixture sets, not proof of the snapshot's training history; that history is not
+attested by this runner.
+
+Explicit snapshots from another controlled experiment can be evaluated without
+booting the application:
+
+```ruby
+require './lib/pwn/ai/agent/policy_evaluation'
+evaluator = PWN::AI::Agent::PolicyEvaluation
+reports = [0, 1].map do |seed|
+  evaluator.evaluate(baseline: '/tmp/baseline.json',
+                     candidate: '/tmp/candidate.json', seed: seed)
+end
+```
+
+With fixed source revisions and snapshot bytes, snapshot reports reproduce all
+fields except `elapsed_seconds`. They contain no wall-clock timestamps, random
+IDs or temporary paths. The original training report still contains the timing
+and metadata variability described above.
+
+## Explicit promotion and rollback
+
+This is an **operator-invoked local eligibility gate**, not automatic online
+policy promotion. `Policy.finish` and Loop do not call it. The existing online
+learning behavior is not redirected or promoted by this module. No live policy
+path is defaulted, and writes require `enabled: true` **and** `quiescent: true`.
+The latter is an operator assertion: **stop all agent processes and policy
+writers first**. The existing Policy writer does not share a transaction lock
+with this module; concurrent live learning or concurrent promotions are not
+supported. Restart writers only after the operation and readback complete.
+
+Promotion requires 2..8 reports with distinct valid suite indices covering both
+filesystem configurations. It then **reruns each suite in a fresh worker** using
+the specified snapshot bytes. Every non-timing report field must match the fresh
+execution, including source/harness digests, snapshot digests, input hashes,
+artifact bodies and hashes, action choices, scores, controls, and frozen-policy
+checks. Hashes alone are not signatures or evidence of trusted authorship;
+re-execution is the authority. Model-written `passed: true`, edited scores,
+invented artifact bodies, stale source revisions, or copied duplicate reports
+cannot substitute for those executions. Supplied elapsed times are discarded;
+only newly measured times enter the gate.
+
+For **every** repeated suite, compared with both baseline-on and off:
+
+- completion and mean artifact-check score must not decrease;
+- no previously solved individual task may become unsolved (aggregate gains
+  cannot hide a task/family regression);
+- false-success count **and rate**, repeated mistakes and tool calls must not rise;
+- elapsed time must be at most `baseline_seconds * 1.25 + 0.02`, a fixed local
+  jitter allowance rather than evidence of a statistically established speedup.
+
+Each suite must also improve completion, false-success count, repeated mistakes,
+or calls relative to baseline-on. Better training returns, more updates, or a
+timing-only change cannot qualify. The gate fails closed when verification fails.
+Snapshots, source digests and live-baseline bytes must still match. An explicit
+live target must already exist and equal the evaluated baseline byte-for-byte.
+The previous policy is saved beside it as a digest-named rollback JSON before a
+same-directory atomic replacement and exact readback. No trajectory file is
+modified. Preserve the returned receipt for rollback.
+
+A disposable demonstration using the opt-in benchmark output above:
+
+```ruby
+require './lib/pwn/ai/agent/policy_evaluation'
+evaluator = PWN::AI::Agent::PolicyEvaluation
+baseline = '/tmp/pwn-policy-snapshots/off.json'
+candidate = '/tmp/pwn-policy-snapshots/on.json'
+reports = JSON.parse(File.read('/tmp/pwn-policy-heldout.json'), symbolize_names: true).fetch(:heldout)
+live = '/tmp/pwn-policy-demo-live.json' # NOT the real online policy
+File.open(live, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |f| f.write(File.binread(baseline)) }
+receipt = evaluator.promote(enabled: true, quiescent: true,
+                            baseline: baseline, candidate: candidate,
+                            reports: reports, live_path: live)
+raise receipt.inspect unless receipt[:promoted]
+restored = evaluator.rollback(enabled: true, quiescent: true,
+                              live_path: live, receipt: receipt)
+raise restored.inspect unless restored[:rolled_back]
+```
+
+Rollback verifies the receipt's explicit target, backup path and prior digest,
+validates the backup schema, and refuses if the live file no longer matches the
+promoted candidate digest. Missing, altered or symlink backups/targets fail
+closed. Both methods default to a disabled result; rejected operations return
+`promoted: false` or `rolled_back: false` with a reason. `evaluate` raises on an
+invalid snapshot, worker failure, or deadline. Force-killing a worker can leave
+its temporary directory; this is not an OS sandbox for untrusted code.
+
+**Limit:** this gate measures only the fixed benchmark action vocabulary and
+public task families. A real online policy containing unrelated tools may show
+no gain and be rejected; passing does not validate those unrelated routes or
+establish live LLM gains. A production rollout still needs separately reviewed,
+representative objective tasks and operator judgment. Do not interpret this
+small public held-out set as a secret test or optimize repeatedly against it
+and then claim independent generalization.

data/documentation/Proxy-Skills-Hygiene.md

@@ -0,0 +1,102 @@
+# Native HTTP capture and skill hygiene
+
+## Native HTTP proxy (P16)
+
+`PWN::Plugins::MitmProxy` uses WEBrick's native proxy/CONNECT transport and
+Net::HTTP for interception. It does not require mitmproxy, Burp, or ZAP.
+Only backend `native` is accepted. HTTPS CONNECT tunnels work, but their
+contents are **not decrypted**: captured entries explicitly have
+`_capture: opaque_connect`. HTTP requests and responses are captured to HAR 1.2.
+
+```ruby
+require 'pwn/plugins/mitm_proxy'
+proxy = PWN::Plugins::MitmProxy.start(har_path: '/tmp/engagement.har')
+browser = PWN::Plugins::TransparentBrowser.open(
+  browser_type: :headless_chrome, capture_proxy: proxy
+)
+# Navigate the browser using its normal API. Chrome loopback bypass is disabled.
+entries = PWN::Plugins::MitmProxy.entries(proxy: proxy)
+entry = PWN::Plugins::MitmProxy.http_replay(
+  proxy: proxy, request_id: entries.first[:_request_id],
+  mutations: { method: 'POST', path: '/fixture', headers: { 'X-Test' => 'yes' }, body: 'sample' }
+)
+# Close the browser separately, then stop its caller-owned proxy:
+PWN::Plugins::MitmProxy.stop(proxy: proxy)
+```
+
+Agent toolset `http`: `http_proxy_start`, `http_proxy_entries`,
+`http_proxy_rules`, `http_replay`, `http_proxy_stop`. Lifecycle tools return
+JSON descriptors; subsequent calls use `proxy_id: descriptor[:id]`.
+The plugin also accepts `proxy:` descriptors. IDs are process-local, not
+persistent replay handles after restart.
+
+Replace the entire active rule list with `rules(proxy:, rules:)`. Rules are
+literal substitutions (not regex):
+
+```ruby
+[{ phase: 'request', field: 'header:x-test', match: 'old', replace: 'new' },
+ { phase: 'response', field: 'body', match: 'old', replace: 'new' }]
+```
+
+Fields are `body`, request-only `url`, or `header:NAME`. Replay mutations are
+`method`, `url`, `path`, `query`, `headers`, `body`; null header values remove
+headers. Hop-by-hop/framing headers are regenerated. Binary HAR bodies use
+base64 encoding. Replay does not mutate the original captured entry.
+
+HAR files contain **unredacted traffic**, including any cookies and credentials
+sent by the operator. They are created mode 0600; use engagement storage and
+retention controls. Only loopback fixtures are used by the regression tests.
+There is no built-in scope policy for proxy traffic; enforcement belongs in
+engagement network isolation or the central scope layer. Binding is loopback
+by default. Upstream HTTP timeout defaults to 30 seconds. Bodies and the
+session capture collection are currently buffered in memory, not streamed.
+
+## On-demand skills consolidation (P19)
+
+`PWN::AI::Agent::SkillConsolidation.consolidate(content:, evidence: {}, now:,
+stale_days: 90)` returns a pure proposal: `content`, `version`, `changed`,
+`deduplicated`, `promoted`, and `review`.
+
+- Deduplicates RL notes, ignoring leading date annotations and whitespace.
+- Conflicting text for one feedback ID, explicit negation against a SOP line,
+  regressed proofs, and stale verification move to a **not active SOP** review
+  section. Unmanaged SOP prose is never automatically deleted or rewritten.
+- Promotions require resolved status, three distinct explicitly successful
+  verification sessions, and recent non-future verification. Failure counts
+  and failure-session IDs do not count as successful evidence.
+- Managed promoted procedures are rechecked for stale or regressed proofs.
+- Stamps `<!-- pwn-skill-version: HASH12 updated: ISO8601 -->` after YAML
+  frontmatter; unchanged content remains byte-identical on subsequent passes.
+
+`consolidate_file(path:)` previews by default. Applying requires
+`dry_run: false, confirm: true, expected_sha256: preview[:source_sha256]`.
+It serializes cooperating consolidation writers, checks the original content,
+keeps a content-addressed backup, atomically replaces the file, and verifies
+readback. Symlink files are rejected. No weekly job is installed.
+
+Agent tool `skills_consolidate(name:, dry_run: true)` targets an already
+installed skill; it does not accept model-provided verification evidence.
+It reloads the skill index after an explicitly confirmed write.
+
+## Precise correction evidence (P20) and integration hooks
+
+Docker socket permissions, registry pull denial and template parsing remain
+distinct classes/signatures. Generic path fixes cannot resolve non-path
+failures; raw-socket fixes cannot resolve ordinary filesystem/daemon
+permissions. Legacy incompatible fixes are excluded from KNOWN FIXES.
+
+For promotion evidence, the successful verification hook should call:
+
+```ruby
+PWN::AI::Agent::Mistakes.note_hint_outcome(
+  signature: signature, helped: true, session_id: verified_session_id
+)
+```
+
+Failed hints clear that stability evidence. `skills_consolidate` consumes
+`verified_sessions` and `last_verified` keyed by the existing RL signature.
+The parent loop must pass `session_id` only after real verification; callers
+that omit it cannot promote notes merely by incrementing a counter.
+Session-recall/index consumers can read the `pwn-skill-version` stamp and
+prefer current installed content over historical SOP text. This module does
+not modify central loop or session-recall selection behavior.

data/documentation/Recon-Findings-API.md

@@ -0,0 +1,31 @@
+# Recon / Findings integration (P17 / P10)
+
+## Parent integration hooks
+
+- Existing autoloaded `PWN::Plugins::Recon` now exposes `run(opts)`; no new plugin autoload needed. New agent registration file: `lib/pwn/ai/agent/tools/recon_run.rb` (normal Registry discovery).
+- `finding_record` handler uses `PWN::Plugins::Findings.record_structured(opts)`. The loop can treat `ArgumentError` as incomplete finding input; **do not infer a working PoC from accepted input**. No Loop/config/CLI changes in this patch.
+- P3 hook: `Recon.run(..., ingest: true)` calls `PWN::AI::Context.ingest(path, session_id: engagement_id, **ingest_options)` after atomic persistence and JSON readback. `ingestor: callable` supports an alternate implementation with the same signature. Ingestion failure is returned in `result[:ingestion]` without discarding recon evidence. Preserve the literal asset ID in ingested chunks. Plugin callers opt in; the agent tool defaults ingestion on.
+
+## Recon model
+
+`Recon.run(target: '127.0.0.1', modules: %w[nmap banner tls], ports: [443], engagement_id: 'lab', ingest: true)`.
+
+Single hostname/IP target (no arbitrary CLI switches, URL, CIDR, or shell command), explicit integer ports, per-operation timeout 15 seconds by default (maximum 300). `nmap` uses an unprivileged TCP connect scan, without sudo or NSE. Existing `NmapIt` API remains untouched. `banner` passively reads up to 4096 bytes; it does not send an HTTP request. `tls` collects the certificate with `trust_verified: false` (not a trust audit). Optional `subfinder` and `nuclei` run **only if explicitly named**, and unavailable tools return module status rather than fabricate results. Nuclei observations are not automatically promoted to findings.
+
+Output: `{schema_version: 1, engagement_id:, assets: [{id:, address:, protocol:, port:, observations: [], evidence_paths: []}], modules: [], path:, ingestion: ...}`.
+
+Stored at `~/.pwn/engagements/<engagement>/recon/assets.json`; `root:` overrides the engagements directory for isolated fixtures. Raw scan evidence is persisted beside it. IDs are `asset-` plus the first 24 hex SHA256 characters of lowercase address, protocol, port joined by `|`. Repeated same-identity observations merge across runs, not overwrite other assets. DNS names and resolved IPs are distinct identities unless the source explicitly supplies the same address; the pipeline does not silently infer aliases.
+
+Use `affected_asset: asset[:id]` and `evidence_paths: asset[:evidence_paths]` in a structured finding. Stable IDs survive report generation and JSON ingestion unchanged.
+
+## Strict findings boundary and compatibility
+
+`record_structured` requires title, CWE identifier (`CWE-<positive integer>`), complete CVSS 3.0/3.1 base vector and matching numeric base score, affected_asset, nonempty existing readable absolute evidence_paths, nonempty PoC command/code string, attack_chain_refs array, remediation string, and numeric confidence 0..1. Chain refs must already exist in the same engagement. Invalid input raises before appending. CVSS 2/4, temporal/environmental vectors are explicitly unsupported (rejected, not normalized).
+
+Legacy `Findings.record`, query/report, chain, render, and SARIF output remain callable; legacy record is not the strict API. Agent record and chain operations are strict. Existing query/export tool operations remain available. Accepted structured rows mark `verification_status: not_executed`; evidence hashes prove captured bytes, not exploit execution. Severity is derived from the validated score. No automatic escalation for linked findings.
+
+Markdown/HTML/JSON report payloads compose connected explicit references into attack-chain sections, preserving all finding fields. Combined severity is maximum recorded constituent severity with a rationale explicitly disclaiming escalation and combined exploitability. This is not a computed CVSS chain score.
+
+## Verification boundaries
+
+Specs use disposable localhost TCP/TLS fixtures and real nmap connect scans. Optional external scanner outputs are parser fixtures, not internet engagements. Context hook failures are visible; embeddings are never synthesized. No remote scanning is necessary to run these focused specs.

data/documentation/Reinforcement-Learning.md

@@ -47,10 +47,10 @@ This is the live numeric controller. It does not replace planning.
 
 | Piece | What it is |
 |---|---|
-| State | request kind, task family, plan quality, answer completeness, usable-result, last action, fail bin, and engine |
+| State | request kind, task family, plan quality, answer completeness, usable-result, last action, fail bin, engine, and sanitized host-observed capability/verification scope |
 | Action | tool name, or `final` |
 | Step reward | 0; −0.01 per tool after 8 |
-| Terminal reward | `Reward.judge` × confidence (sole large R). `plan_coverage` is a tag, not the score. |
+| Terminal reward | Resolved training score mapped to −1..1 × confidence (sole large R), attributed only to independently linked actions. `plan_coverage` is a tag, not the score. |
 | Updates | Q-learning (`alpha=0.15`, `gamma=0.85`) and REINFORCE (`alpha=0.05`). Stored trajectories replay twice on warmup so a short table is not empty advice. |
 | Budget | Eight finished episodes (live or warmup-credited) unlock greedy suggestions. Until then the prompt omits them. |
 | Steer | Q-advantage in `Registry.rank` once the episode budget is met; keyword fit and CORE_TOOLS still come first. Suggested actions follow `Registry.preference_order` (`ai.agent.tool_preference`). |
@@ -81,6 +81,58 @@ current session request and invalidated by subsequent tool execution. The API
 trusts the host verifier to cover the complete request; it cannot infer missing
 criteria or automatically verify arbitrary tasks. LLM judgments remain fallible.
 
+### Executed acceptance checks and artifact attribution
+
+For stronger verification, pass a host-owned `verification_contract` to
+`Loop.run`, or use `Reward.run_verification(request:, session_id:, contract:)`.
+The contract contains `root`, `requirements` (distinct verbatim clauses of the
+original request), and `checks`. Each check names its `requirement` and kind:
+
+- `file`: an in-root regular `path` whose bytes equal `expected`.
+- `json`: an in-root regular `path` whose parsed JSON equals `expected`.
+- `command`: a literal `argv`, expected `exit_code` (default zero), and optional
+  expected stdout. Requires `allow_commands: true`.
+- `http`: an exact `url` listed in `allowed_urls`, expected response bytes, and
+  expected `status` (default 200). GET only, with no redirects.
+
+Check failures are negative evidence. Missing requirements, unavailable checks,
+and timeouts stay unknown even if the LLM judge awards a high score. Later tool
+execution invalidates a runner report without falling back to presumed success.
+The runner records output digests, not raw command output or expected values.
+Artifact reads use no-follow descriptors, validate their actual location through
+Linux `/proc/self/fd`, and enforce the byte limit while reading. If descriptor
+location validation is unavailable, the check stays unknown rather than using
+an unsafe pathname fallback.
+The caller must supply the complete acceptance checklist: matching clauses to
+the original text is not semantic proof that the checklist covers every intent.
+
+Commands have a cleared environment, private HOME set to the selected root,
+bounded output and timeout, and process-group cleanup. This is **not an OS
+sandbox**: opt-in commands retain the process's filesystem/network permissions.
+Only run trusted checks, using an external sandbox for untrusted programs.
+
+At the final boundary, Loop executes the contract and publishes a verification
+event through `on_tool`. Around dispatched actions it snapshots declared
+artifact digests. Matching the final checked digest to its last observed writer
+produces an `independent_verifier` attribution receipt. This establishes artifact
+provenance, not universal causal proof. Controlled comparisons in isolated
+evaluation can supply a separate `controlled_comparison` receipt.
+
+Policy distributes the existing terminal reward across uniquely linked action
+IDs. Unlinked actions receive no positive training credit; an accounting-only
+final row retains unattributed terminal reward. Adding successful no-op commands
+does not create more reward. Known per-step cost remains; unknown task outcomes
+still do not train. Ordinary model-judged runs without attribution may retain
+outcome/lesson records, but do not positively reinforce guessed tool contributions.
+
+`Loop.run(trusted_context:)` accepts host observations, not model arguments.
+Policy stores only fixed environment/capability/failure/verification categories;
+state backoff stays within that observed scope. Registry checks declared tool
+prerequisites before ranking, including core tools, so a known absent prerequisite
+cannot be outweighed by a historical success score. Unknown availability is not
+treated as absence. Default local scope observes the Ruby runtime and `/bin/sh`;
+callers must supply observations for remote/container-specific capabilities.
+
 Policy observations also capture allowlisted operation, argument-role/type
 features, and result classification, without retaining raw argument values.
 These condition next-tool ranking only after enough contextual samples exist,

data/documentation/Swarm.md

@@ -12,7 +12,7 @@ self-improvement loop covers the whole swarm.
 
 | Path | Contains |
 |---|---|
-| `~/.pwn/agents.yml` | Persona registry (name → role/engine/toolsets/max_iters) |
+| `~/.pwn/agents.yml` | Persona registry (name → role/engine/model/toolsets/max_iters) |
 | `~/.pwn/swarm/<id>/bus.jsonl` | Append-only chat every persona reads/writes |
 | `~/.pwn/swarm/<id>/personas.json` | persona name → `PWN::Sessions` id |
 
@@ -21,6 +21,41 @@ a `PWN::Cron` job) calling `Swarm.ask` with the same `swarm_id`.
 
 ## Define personas
 
+Each persona accepts optional `engine` and `model` keys. `model` is the exact
+provider model identifier (case and punctuation are preserved). Omit `engine`
+to inherit the active engine; omit `model` or leave it blank to use the selected
+provider's configured default model. Existing engine-only entries still work.
+
+For example, edit `~/.pwn/agents.yml`:
+
+```yaml
+reviewer:
+  role: Review implementation and tests.
+  engine: openai
+  model: gpt-6-astra
+  toolsets: [terminal, pwn]
+local_reviewer:
+  role: Independently review implementation and tests.
+  engine: ollama
+  model: your-installed-model:tag
+  toolsets: [terminal, pwn]
+```
+
+Replace model identifiers with models available to your configured providers.
+Personas can use different models on the same provider or different providers.
+The selection applies to `ask`, `debate`, and `broadcast`; overrides are scoped
+to each persona execution, restored after nested calls/errors, and do not rewrite
+global provider defaults. An omitted model uses the provider default, not an
+enclosing persona's model override. Provider authentication is unchanged.
+
+`agent_spawn` also accepts `model:` and `agent_list` reports it.
+
+On upgrade, `pwn setup --migrate` applies schema 3: existing persona entries
+without a `model` key receive an unset YAML `model:` field (null, meaning the
+selected provider's default). Existing model values, engine selections, and
+custom persona fields are preserved. Re-running migration makes no further
+changes. A missing `agents.yml` is not created by this migration.
+
 ```ruby
 agent_spawn(name: 'red_team',
             role: 'Offensive operator. Propose the most aggressive next step.',
@@ -82,8 +117,8 @@ agent_ask(name: 'red_team', swarm_id: tx[:swarm_id],
           request: 'blue_team raised WAF concerns - revise the payload.')
 ```
 
-Because each persona can pin a **different engine**, the debate is real model
-diversity, not one model role-playing.
+Each persona can pin a **different engine and/or model**, rather than requiring
+every persona to use one provider's default model.
 
 **See also:** [pwn-ai Agent](pwn-ai-Agent.md) ·
 [Agent Tool Registry](Agent-Tool-Registry.md) · [Sessions](Sessions.md)