pwn 0.5.780 → 0.5.781

data/documentation/Persistence.md

@@ -1,6 +1,7 @@
 # `~/.pwn/` - Persistence Map
 
-Every byte PWN remembers between processes lives here.
+Default user state lives here. Explicit artifact/output paths, worktrees,
+external services and environment overrides can place evidence elsewhere.
 
 ![~/.pwn map](diagrams/persistence-filesystem.svg)
 
@@ -35,7 +36,7 @@ Every byte PWN remembers between processes lives here.
 | `finetune/*.jsonl` | `Learning.export_finetune` · `Reward.export_dpo` | ShareGPT / OpenAI / DPO JSONL | `rm` | supervised + preference datasets - feed to a LoRA over the local model |
 | `backup/<ts>/` | `PWN::Migrate` | tree copy | rm -rf | timestamped snapshot taken before every `--migrate --fix` |
 | `quarantine/` | `PWN::Migrate` | quarantined originals | rm -rf | corrupt/incompatible state files moved aside so the owner re-seeds |
-| `~/.pwn_history` | Pry | text | rm | REPL input history |
+| `pwn_history` | Pry / pwn-ai | text | operator-managed | Shared durable input history at `~/.pwn/pwn_history` |
 
 
 ## `memory.json` safety

data/documentation/Plugin-Degradation.md

@@ -54,8 +54,10 @@ Required: `zaproxy`. Fallback: `nuclei`, `httpx`, `TransparentBrowser`, `PWN::Pl
 ## pwn-plugins-packet
 
 Required: `CAP_NET_RAW` **or** the capability broker helper. Install the helper
-from `documentation/Capability-Broker-Sandbox.md` (setcap the helper binary, not
-the Ruby interpreter). Fallback: `Packet.tcp_connect_scan` / `PWN::Plugins::Sock`.
+from [Capability-Broker-Sandbox](Capability-Broker-Sandbox.md) using its dedicated
+service capability boundary. Do not setcap the Ruby interpreter or Ruby script
+(Linux ignores script file capabilities). Fallback: `Packet.tcp_connect_scan` /
+`PWN::Plugins::Sock`.
 
 ## pwn-plugins-k8s
 

data/documentation/Plugins.md

@@ -1,4 +1,4 @@
-# `PWN::Plugins` - All 67 Modules
+# `PWN::Plugins` - All 107 Modules
 
 Every plugin is a plain Ruby module of `public_class_method def self.x(opts = {})`
 methods with self-documenting `.help`. Source: `lib/pwn/plugins/*.rb`.
@@ -11,7 +11,7 @@ methods with self-documenting `.help`. Source: `lib/pwn/plugins/*.rb`.
 PWN::Plugins.constants.sort
 PWN::Plugins::BurpSuite.help
 ls PWN::Plugins::NmapIt
-show-source PWN::Plugins::Fuzz.generate
+show-source PWN::Plugins::Fuzz.http
 ```
 
 ## By category
@@ -63,7 +63,7 @@ show-source PWN::Plugins::Fuzz.generate
 | Module | Purpose |
 |---|---|
 | `OAuth2` · `BasicAuth` · `AuthenticationHelper` | credential flows |
-| `Vault` | HashiCorp Vault |
+| `Vault` | Local encrypted configuration and engagement loot helpers; not a HashiCorp Vault client |
 
 ### Hardware / Physical
 | Module | Purpose | Doc |
@@ -97,13 +97,6 @@ show-source PWN::Plugins::Fuzz.generate
 
 ## Full alphabetical list
 
-`Android Assembly AuthenticationHelper BareSIP BasicAuth BeEF
-BlackDuckBinaryAnalysis BurpSuite BusPirate Char CreditCard DAOLDAP DAOMongo
-DAOPostgres DAOSQLite3 DefectDojo DetectOS EIN FileFu Fuzz Git Github
-HackerOne Hunter IPInfo IRC Jenkins JiraDataCenter JSONPathify Log MailAgent
-Metasploit MonkeyPatch MSR206 NessusCloud NexposeVulnScan NmapIt OAuth2 OCR
-OpenAPI OpenVAS Packet PDFParse Pony PS PWNLogger RabbitMQ REPL ScannableCodes
-Serial Shodan SlackClient Sock Spider SSN ThreadPool Tor TransparentBrowser
-TTYSpinner TwitterAPI URIScheme Vault VIN Voice Vsphere XXD Zaproxy`
+`AFLplusplus AISandbox Android ArtifactRegistry Assembly AuthenticationHelper BareSIP BasicAuth BeEF BinaryAnalysis BinaryParser BinWorkspace BlackDuckBinaryAnalysis BurpSuite BusPirate Capability CapabilityBroker Char CredentialAttack CreditCard DAOLDAP DAOMongo DAOPostgres DAOSQLite3 Debugger DefectDojo DetectOS Detonate EIN Emulator ExploitDB ExploitDev FileFu Findings Frida Fuzz GDB GDBMI GDBMi Ghidra GhidraHeadless Git Github GoogleWorkspace HackerOne Handler Httpx Hunter IPInfo IRC Jenkins JiraDataCenter Jobs JSONPathify K8s Log MailAgent Metasploit MethodCatalog MitmProxy MonkeyPatch MSR206 NessusCloud NexposeVulnScan NmapIt Nuclei OAuth2 OCR OpenAPI OpenVAS Packet PDFParse Pony PreflightChecker ProcessTube PS PWNLogger RabbitMQ Radare2 Recon REDB REPL ROP Sandbox SBOM ScannableCodes Semgrep Serial Shodan SlackClient Sock Spider Sqlmap SSN ThreadPool Tor TransparentBrowser TTYSpinner TwitterAPI URIScheme Vault VIN Voice Volatility Vsphere XXD Zaproxy`
 
 [← Home](Home.md) · [Diagrams](Diagrams.md)

data/documentation/Policy-Benchmark.md

@@ -356,6 +356,10 @@ raise restored.inspect unless restored[:rolled_back]
 ```
 
 Rollback verifies the receipt's explicit target, backup path and prior digest,
+and requires `receipt_version: 1`, `change_kind: routing_policy` and the
+`acceptance_sha256` of freshly re-executed deterministic reports. Old unversioned
+receipts are rejected rather than silently upgraded. The receipt is a local audit
+record, not hostile-writer attestation. Rollback also
 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

data/documentation/Reinforcement-Learning.md

@@ -1,5 +1,21 @@
 # Reinforcement Learning in pwn-ai
 
+## Verified completion versus learning scores
+
+Use `verified_completion` (pass/fail/unknown), not legacy judge `success`, to
+measure delivered work. `claimed_completion` preserves the judge claim and
+`false_completion_rate` divides refuted claims by checked claims, remaining null
+when none were checked. Executable harness false-success instead compares a
+released marker against the entire run outcome, including exit status and caps.
+
+`Learning.regression_task` exports an inert file/JSON recipe from an exact
+persisted verifier failure and request digest; expected bytes are independently
+authored and its split remains `regression`. Frozen policy promotion reruns
+acceptance, checks per-task regressions and requires explicit approval/stopped
+writers; rollback needs its versioned receipt and unchanged promoted target.
+See [Harness Evaluation](Harness-Evaluation.md) and [Policy Benchmark](Policy-Benchmark.md).
+
+
 ## Retained learning evidence and session cleanup
 
 Learning outcomes can retain a versioned `evidence_ref` (`version`, `id`,
@@ -90,7 +106,7 @@ local adapter.
 That path can promote a new local adapter when the candidate beats the current
 one. Without a trainer it still **exports** the datasets and a manual CLI. Live improvement does not wait on weights.
 
-ESR and ASR are the rates RSI actually compares. ESR is `verified_exploit_tools / vulnerable_tools`. ASR is `successful_attacks / total_attack_attempts`. `Learning.rsi_tick` stores the pair and writes an `rsi` lesson when ESR falls. Tool telemetry and the judge score are separate. A passing suite is not either rate.
+ESR and ASR are the rates RSI records; only an ESR drop triggers its regression lesson. ESR is `verified_exploit_tools / vulnerable_tools`. ASR is `successful_attacks / total_attack_attempts`. `Learning.rsi_tick` stores the pair and writes an `rsi` lesson when ESR falls. Tool telemetry and the judge score are separate. A passing suite is not either rate.
 
 RSI's rate tick does not generate or promote policy candidates. For the separate
 **offline operator evaluation** path, use `pwn-ai --policy evaluate` and review
@@ -275,7 +291,7 @@ that a live language model performs better.
 | **W1** `.record_preference` | Preference ledger from corrections, resolve, counterfactual, critic, and practice. |
 | `.practice_kpi` | Week-over-week trend of repeating mistakes (outer curriculum health). |
 
-## Budget pressure (iteration ceiling)
+## Budget pressure (side-work control)
 
 When unresolved `agent_loop` / `assistant_answer` budget-exhaustion fingerprints
 dominate, the loop marks the budget path hot and tightens *side work* only:
@@ -332,7 +348,7 @@ This is the live control list. Track the outcomes, not source comments.
     :reward_llm_timeout: 12  # cheap ORM chat timeout seconds (clamped 2..30)
     :local_introspect: :failure_only   # ollama cost rule; remote always introspects
     :introspect_every_n: 3
-    :max_iters: 777          # hard cap for this request; scars do not lower it
+    :max_iters: 777          # advisory counter; not a hard completion cap
     :defer_introspect: true  # post-answer Learning after the user-visible reply
     :prompt_cache: true      # engine-native prefix cache (not ollama / openwebui)
     :tool_preference: [memory_recall, session_recall, skills_recall, pwn_eval, shell, mistakes_record, mistakes_resolve, learning_note_outcome, memory_remember, skills_update]

data/documentation/Reporting.md

@@ -35,13 +35,14 @@ Nuclei and SBOM leads stay recon observations until a later `verify` reproduces
 ## Example
 
 ```ruby
-findings = PWN::SAST::Factory.start(dir_path: './src')
+require 'fileutils'
+rows = PWN::SAST::Factory.scan(dir_path: './src')
+FileUtils.mkdir_p('./out')
 PWN::Reports::SAST.generate(
-  dir_path: './src', results_hash: findings, output_dir: './out'
-)
-PWN::Plugins::DefectDojo.importscan(
-  engagement_id: 42, file: './out/report.json', scan_type: 'PWN SAST'
+  dir_path: './out', results_hash: { data: rows }, report_name: 'report'
 )
+# Importing is a separate authenticated operation; use DefectDojo.help and
+# pwn_defectdojo_importscan --help for the installed integration's contract.
 ```
 
 [← Home](Home.md) · [SAST](SAST.md) · [Fuzzing](Fuzzing.md)

data/documentation/SAST.md

@@ -1,6 +1,8 @@
 # `PWN::SAST` - Static Application Security Testing
 
-48 modules in `PWN::SAST`: 45 language-aware scan rules plus `Factory`, `TestCaseEngine`, and `Version`.
+48 top-level modules in `PWN::SAST`. `Factory` is the Java XML-factory/XXE
+pattern rule, not the rule loader; `TestCaseEngine` executes rules.
+The `pwn_sast` driver orchestrates the selected rules.
 Source: `lib/pwn/sast/*.rb`. CLI: `bin/pwn_sast`.
 
 ![SAST pipeline](diagrams/code-scanning-sast.svg)
@@ -9,15 +11,17 @@ Source: `lib/pwn/sast/*.rb`. CLI: `bin/pwn_sast`.
 
 ```bash
 # CLI driver
-pwn_sast -d /path/to/src -o /tmp/sast_out
+pwn_sast --help  # inspect the installed driver's source/output options
 ```
 
 ```ruby
 # REPL / pwn_eval
-findings = PWN::SAST::Factory.start(dir_path: '/path/to/src')
-PWN::Reports::SAST.generate(dir_path: '/path/to/src',
-                            results_hash: findings,
-                            output_dir: '/tmp/sast_out')
+require 'fileutils'
+rows = PWN::SAST::Factory.scan(dir_path: '/path/to/src')
+FileUtils.mkdir_p('/tmp/sast_out')
+PWN::Reports::SAST.generate(dir_path: '/tmp/sast_out',
+                            results_hash: { data: rows },
+                            report_name: 'report')
 ```
 
 ## Rule families (48 modules)
@@ -30,14 +34,15 @@ PWN::Reports::SAST.generate(dir_path: '/path/to/src',
 | **Crypto / secrets** | `MD5` · `SSL` · `Keystore` · `PaddingOracle` · `PrivateKey` · `Signature` · `Token` · `Password` · `Base64` · `HTTPAuthorizationHeader` |
 | **Memory / native** | `BannedFunctionCallsC` · `UseAfterFree` |
 | **Infra / meta** | `AWS` · `AMQPConnectAsGuest` · `ApacheFileSystemUtilAPI` · `PomVersion` · `Version` · `Port` · `Logger` · `ThrowErrors` · `TaskTag` · `Emoticon` |
-| **Engine** | `Factory` (loader) · `TestCaseEngine` (probe generator) |
+| **Engine** | `Factory` (Java XML-factory/XXE rule) · `TestCaseEngine` (probe generator) |
 
 ## Write a rule
 
 Each rule implements `self.scan(opts = {})` taking `dir_path:` and returning an
-array of `{file:, line:, match:, cwe:, severity:}` hashes. Copy any existing
-rule in `lib/pwn/sast/`, add your regex/AST logic, and it's auto-loaded by
-`Factory`.
+array of TestCaseEngine result rows (including timestamp, security references,
+filename/line and raw/test-case content). Inspect an existing rule and the
+report renderer rather than inventing a findings schema. Add its namespace
+autoload, paired spec and generated module skill; the driver selects rules.
 
 ## Downstream
 

data/documentation/SDR-Decoder-Coverage.md

@@ -3,7 +3,13 @@
 **Verdict: the “full protocol decode in all modules” requirement is not complete.**
 A valid frame in one mode is useful implementation, not full coverage of the named protocol family.
 
-Audit snapshot: **2026-09-09T20:20:02.204954+00:00**. This is a working-tree audit, not a release or a claim about HEAD. Other workers were changing decoders during review; the exact reviewed bytes are identified by SHA-256 in `/tmp/pwn-decoder-completion-matrix.json`, with retained text in `/tmp/pwn-decoder-audit-snapshot.json`. Later edits require delta review. The audit itself changes documentation only; it does not stage, commit, alter decoder code, or endorse unrelated pre-existing staged files.
+Historical protocol audit snapshot: **2026-09-09T20:20:02.204954+00:00**.
+The current documentation review reconfirmed 24 registry aliases / 21 modules
+and the GQRX forwarding correction below. Other mode-level acceptance rows retain
+their historical evidence boundaries; no live RF or new conformance run is implied.
+Temporary audit files cited below are not shipped evidence and may expire.
+
+Original audit context: This is a working-tree audit, not a release or a claim about HEAD. Other workers were changing decoders during review; the exact reviewed bytes are identified by SHA-256 in `/tmp/pwn-decoder-completion-matrix.json`, with retained text in `/tmp/pwn-decoder-audit-snapshot.json`. Later edits require delta review. The audit itself changes documentation only; it does not stage, commit, alter decoder code, or endorse unrelated pre-existing staged files.
 
 ## Inventory and evidence contract
 
@@ -51,7 +57,7 @@ Local evidence: `lib/pwn/sdr/decoder.rb`, `base.rb`, `dsp.rb`; `spec/lib/pwn/sdr
 | BASE-3 | Overrun/dropped-byte source status checked, discontinuity raises; unknown counts stay nil | Queue backpressure is not hardware-loss telemetry. Validate adapters on actual devices; UDP audio sequence/loss remains unmeasured. Do not report unknown loss as zero. |
 | DSP-1 | Ruby fallback and optional DSPNative packed unpack/magnitude/FM, radix-2 FFT; FFTW/VOLK/Liquid helpers elsewhere | Numeric precision/scale, N versus N-1 FM samples, prior IQ and byte remainder must match across backends/chunks. Generic resampling/timing helpers do not establish continuous protocol tracking. |
 | DSP-2 | Native kernel benchmark artifacts in `ext/pwn_dsp/` | Record selected backend and benchmark entire decode pipeline at each row's rate. Existing README explicitly says kernel-only rates omit acquisition/channelizer/protocol/queueing. |
-| GQRX-1 | `init_freq` resolves registry and forwards common streaming controls; RDS `.sample` avoided when streaming requested | Current allowlist forwards source/file/sample_rate/chunk_bytes but drops protocol `mode`, `iq_format`, `backend`, native executable, modulation, channel/key/context options. Direct `.decode` successes are not GQRX end-to-end acceptance. Implement explicit validated per-decoder option forwarding and test every unique target. |
+| GQRX-1 | `init_freq` resolves registry and forwards common streaming controls; RDS `.sample` avoided when streaming requested | Current `init_freq` strips only GQRX-owned controls and forwards remaining decoder context, including mode/backend/format and callbacks; resolved `freq_obj` stays authoritative. Any explicit decoder context prevents the legacy RDS `.sample` shortcut. `gqrx_spec.rb` covers forwarding. This fixes the historical allowlist defect, not all decoder conformance. |
 | NATIVE-1 | Optional native DSP/SCH and required native LTE bridge; custom native GPS/RDS/RTL433/RFID processes | Namespace comment “100% ruby-native / no external binary” is stale. State accurately: first-party Ruby coordination plus named C/C++ libraries/processes; external fixture generators are not runtime dependencies. If “native” means exclusively Ruby, these backends need an explicit requirement decision. |
 
 ### RF and performance requirements
@@ -516,14 +522,14 @@ Priority orders risk and integration value; it is not a claim that later rows ar
 - Executed `bundle exec rspec spec/lib/pwn/sdr/decoder_spec.rb spec/lib/pwn/sdr/decoder/base_spec.rb spec/lib/pwn/sdr/decoder/dsp_spec.rb` in `/opt/pwn`: **44 examples, 0 failures**. This verifies only that focused run; it is not a protocol-completeness metric.
 - An earlier process launched from the research interpreter had a different gem environment and failed Bundler dependency materialization. The actual terminal environment ran the focused specs successfully. No package installation or lockfile changes were made by this audit.
 - All module/spec inventory and acceptance-ID coverage are checked programmatically against `REGISTRY.values.uniq`; source/spec hashes identify what was read. No fabricated decoded frames or measurements are used.
-- No full `rake`, complete optional-native matrix, sensitivity test or live RF test was run by this documentation audit. Full gates can regenerate module skills and concurrent implementation was active; run them after integration settles. Neither this limitation nor a future green suite resolves the OPEN acceptance rows.
+- No full `rake`, complete optional-native matrix, sensitivity test or live RF test was run by this documentation audit. Concurrent implementation was active; run full gates after integration settles. Current normal rake/spec does not regenerate tracked module skills; `rake module_skills` is explicit. Neither this limitation nor a future green suite resolves the OPEN acceptance rows.
 - Citation retrieval used direct HTTP and PDF text extraction because the configured web extractor was search-only. NOAA's old APT host failed DNS; the NOAA KLM guide was retrieved instead. Semtech's product page timed out; LoRa mode/synchronization context uses the retrieved independent implementation reference, not an unread manufacturer datasheet. The RDS commercial catalogue page was insufficient for clause-level claims; use the actual redsea reference and a pinned licensed standard for final conformance.
 
 ### Required completion artifacts
 
 For every acceptance ID, attach a pinned standard clause/profile, supported-mode list, public entry-point command, source/fixture hash, independent expected decoded fields, negative/ciphertext outcomes, actual execution result, and end-to-end rate/latency evidence. Preserve unsupported variants and unavailable sources as OPEN. A finite catalogue row needs every pinned device ID, including disabled-by-default entries; a finite standard row needs every declared message/PHY combination, not an illustrative subset.
 
-This document is exhaustive over the current registry and reviewed files, **not a declaration of exhaustive protocol conformance**. It intentionally does not claim completion from a test count.
+The historical matrix covers its enumerated registry and reviewed files, **not a declaration of exhaustive protocol conformance**. It intentionally does not claim completion from a test count.
 
 ## Sources
 

data/documentation/SDR.md

@@ -15,7 +15,7 @@
 | `RFIDler` | 125 kHz RFID reader/emulator |
 | `SonMicroRFID` | SM130 13.56 MHz reader |
 | `FrequencyAllocation` | ITU/FCC band-plan lookup - "what lives at 433.92 MHz?" |
-| **`Decoder::*`** | 20 protocol demodulators/decoders (+ Base/DSP helpers) - `ADSB APT Bluetooth DECT FLEX GPS GSM Iridium LoRa LTE Morse P25 Pager POCSAG RDS RFID RTL433 RTTY WiFi ZigBee` |
+| **`Decoder::*`** | 21 protocol demodulators/decoders (+ Base/DSP helpers) - `ADSB APT Bluetooth DECT FLEX GPS GSM Iridium LoRa LTE Morse P25 Pager POCSAG RDS RFID RTL433 RTTY Tempest WiFi ZigBee` |
 
 ## CLI
 
@@ -57,14 +57,15 @@ See skill `pwn_gqrx_scanner_fast_vs_iterative_scanning` for the full trade-off.
 ## REPL example
 
 ```ruby
-g = PWN::SDR::GQRX.connect(host: '127.0.0.1', port: 7356)
-PWN::SDR::GQRX.set_freq(gqrx_sock: g, freq: 433_920_000)
-PWN::SDR::GQRX.set_demod(gqrx_sock: g, demod: 'AM')
-snap = PWN::SDR::GQRX.get_spectrum_snapshot(gqrx_sock: g)
-PWN::SDR::FrequencyAllocation.lookup(freq: 433_920_000)
-# => { band: 'ISM 433', typical: ['garage doors', 'weather stations', ...] }
+g = PWN::SDR::GQRX.connect(target: '127.0.0.1', port: 7356)
+PWN::SDR::GQRX.init_freq(gqrx_sock: g, freq: '433.920.000',
+                        demodulator_mode: :AM, keep_alive: true)
+snap = PWN::SDR::GQRX.get_spectrum_snapshot(gqrx_sock: g, nfft: 2048)
+plans = PWN::SDR::FrequencyAllocation.band_plans
+PWN::SDR::GQRX.disconnect(gqrx_sock: g)
 ```
 
+This is active tuning of an already running GQRX instance, not an offline test.
 
 ## Native DSP acceleration (`PWN::FFI`)
 
@@ -100,39 +101,26 @@ iq = PWN::FFI::HackRF.capture(freq_hz: 433_920_000, rate_hz: 10e6, samples: 262_
 
 See [FFI](FFI.md) for the full binding surface and design rules.
 
-## True-air I/Q decode (`Base.run_iq`)
-
-Every `PWN::SDR::Decoder::*` module can decode straight from hardware I/Q
-without GQRX in the loop. `Base.run_iq` auto-selects the first working
-front-end (`:file` -> `:rtlsdr` -> `:adalm_pluto` -> `:hackrf` -> `:soapy`),
-streams, unpacks, and feeds the module's demodulator. If no hardware or
-capture file is present it degrades gracefully to `Base.run_detector`
-(energy/burst characterizer) so you still get structured JSONL output.
-
-```ruby
-# Force a specific radio, sample rate, or replay a capture file:
-fo = PWN::SDR::GQRX.init_freq(freq: '929.612.500', decoder: :flex)
-fo[:iq_source] = :hackrf          # or :rtlsdr / :adalm_pluto / :soapy / :file
-fo[:iq_rate]   = 2_048_000
-fo[:iq_file]   = '/tmp/flex.cu8'  # replay instead of live air
-PWN::SDR::Decoder::Flex.decode(freq_obj: fo)
-
-# Or drive the pipeline directly:
-PWN::SDR::Decoder::Base.run_iq(
-  freq_obj:    fo,
-  protocol:    'ADSB',
-  demod:       PWN::SDR::Decoder::ADSB::Demod.new,
-  sample_rate: 2_000_000,
-  source:      :auto           # :rtlsdr|:hackrf|:adalm_pluto|:soapy|:file
-)
-```
-
-| Decoder | Air path | I/Q entry point |
-|---|---|---|
-| ADSB, Bluetooth, DECT, GPS, GSM, Iridium, LoRa, LTE, P25, RFID, RTL433, WiFi, ZigBee | `run_iq` (wideband) | `#feed_iq(iq, rate:)` |
-| APT, FLEX, Morse, Pager, POCSAG, RTTY | `run_iq(fm_demod: true)` or `run_native` | `#feed(audio)` |
-| RDS | GQRX built-in RDS (`RDS.sample`) | n/a |
-
+## Decode input boundaries
+
+The current registry has 24 aliases mapping to 21 protocol modules, including
+`Tempest`; `Flex` is the Ruby constant behind `:flex`. It is not a claim of full
+protocol or live-air coverage. See the mode-by-mode
+[SDR Decoder Coverage](SDR-Decoder-Coverage.md) matrix before choosing a source.
+
+Use each public decoder's `.help` and explicit `source: :file`, `file:`,
+`sample_rate:` and `iq_format:` controls for an offline replay. Do not call
+`GQRX.init_freq(decoder: ...)` merely to construct a fixture: it can start decoding
+and perform live I/O. Audio, MPX, amplitude traces, synchronized symbols and raw
+IQ are different inputs; a parser success does not prove RF acquisition.
+
+`Base.run_iq` streams supported integer IQ sources through DSP to a supplied
+demodulator. Its low-level default permits an energy-detector fallback, but
+protocol `.decode` methods can require `fallback: :raise`. An energy observation
+is never payload decoding. Explicit `.detect` exposes detection separately.
+RDS's default GQRX polling is station metadata, while its native `redsea` backend
+accepts MPX. GPS, LTE, RTL433 and RFID have mode-specific native boundaries;
+missing executables/libraries and unsupported modes must remain visible.
 
 ## RF ↔ Extrospection
 

data/documentation/Session-Workflow.md

@@ -12,20 +12,24 @@ operator cheat sheet.
 
 ## Life of a line
 
-1. Entering `pwn-ai` always creates a **new** `~/.pwn/sessions/<timestamp>_<hex>.jsonl`.
+1. A new activation creates a session; explicit session-picker or CLI resume
+   selects an existing stable session ID instead.
 2. Cheap intents (greeting, how-to, recall) never open a host-work goal.
 3. Everything else is an autonomous goal. `Loop.run` keeps CORE_TOOLS until
    the original request is done or a tool returned failure evidence.
    pwn-ai does not decide authorization.
-4. An unfinished host-work request is written to `~/.pwn/open_goal.json`.
-5. An accepted final answer deletes that file. Budget exhaust leaves it.
+4. RequestRuntime retains the original objective, amendments, tool evidence and
+   verification contract in request/session-bound checkpoints. OpenGoal keeps the
+   matching resume pointer; `~/.pwn/open_goal.json` is the legacy global form.
+5. Verified completion can clear the matching open goal. Cancellation, failed
+   checks or uncertain side effects do not turn unfinished work into success.
 
 ```
 you type a line
         |
         +-- greeting / how-to / recall -----> short answer, no tools
         |
-        +-- continue / resume / keep going --> reload open_goal.json
+        +-- continue / resume / keep going --> restore this session's open request
         |
         +-- last / previous session ---------> prior JSONL, not this line
         |
@@ -38,7 +42,8 @@ you type a line
 
 ## Unfinished goals
 
-File: `~/.pwn/open_goal.json` (`PWN::AI::Agent::OpenGoal`).
+Owner: `PWN::AI::Agent::OpenGoal`, with request-bound persistence and a per-session
+pointer. Legacy `~/.pwn/open_goal.json` is accepted only for its matching session.
 
 | You type (whole line) | Effect |
 |---|---|
@@ -51,18 +56,22 @@ File: `~/.pwn/open_goal.json` (`PWN::AI::Agent::OpenGoal`).
 | `resume the goal` / `resume the task` / `resume work` | same |
 
 The line must be **only** that phrase (optional `please` / `the goal|task|work`
-and a trailing `.` / `!`). A new sentence is a new goal and **replaces** the
-saved request.
+and a trailing `.` / `!`). A new sentence is not a bare resume. Replacing a
+checkpointed CLI objective requires `--replace-session ID`, a new prompt/contract
+and `--approve-replacement`; the old checkpoint remains unchanged.
 
 `continue scanning the lab` is a new ask, not a resume.
 
-Delete `~/.pwn/open_goal.json` to drop a stuck checkpoint.
+Use `pwn-ai --resume-session EXACT_SESSION_ID` after a process restart. Do not
+delete checkpoint files as a recovery shortcut: retain evidence and inspect
+uncertain mutations before deciding whether any action is safe to repeat.
+`--resume RUN_ID` is TaskDAG resume, not session resume.
 
 ---
 
 ## This session vs last session
 
-Entering `pwn-ai` is a new transcript. "Last session" is the newest other
+Without explicit resume, entering `pwn-ai` starts a new transcript. "Last session" is the newest other
 `~/.pwn/sessions/*.jsonl`.
 
 | Phrase | Where it reads |
@@ -94,7 +103,7 @@ Whole-line greetings only, so `hi, scan this host` stays a goal:
 
 | Need | Done only when |
 |---|---|
-| Write / update / regenerate / docs / fix | A **write** effect, then a later **read** (`cat`, `ruby -c`, eval read) |
+| Write / update / regenerate / docs / fix | Current-turn exact-target host write/readback evidence, matching current bytes and every applicable authored check; an unrelated read or test is insufficient |
 | Browser / navigate / `TransparentBrowser` | A **browse** effect (goto / dump_links / close) |
 | Hostname / uname / cwd / whoami | Any live **read** |
 | Other long goals (bounty, scrape, recon) | **write**, **browse**, or **eval** (`ls` alone is not enough) |
@@ -103,7 +112,11 @@ These do **not** count as finishing a write: `memory_remember`,
 `learning_note_outcome`, `mistakes_*`, rspec/rubocop green, a README listing,
 or "I will do that next time."
 
-After you mutate a file, read it back before a final.
+After mutation, verify the actual requested target. Literal/artifact checks and
+host-authored contracts are stronger than effect categories. Browser activity or
+an eval is not by itself proof of arbitrary semantic task completion. Child-agent
+prose is not evidence; the parent must accept current exact-target receipts and
+rerun its own integration checks. See [Harness Evaluation](Harness-Evaluation.md).
 
 ---
 
@@ -127,7 +140,7 @@ going.
 | Path | Role |
 |---|---|
 | `~/.pwn/sessions/<id>.jsonl` | This activation's transcript |
-| `~/.pwn/open_goal.json` | Unfinished host-work request |
+| OpenGoal request/session records (legacy `~/.pwn/open_goal.json`) | Unfinished request and matching-session resume pointer |
 | `~/.pwn/memory.json` | Durable facts (not "last line") |
 
 [← Home](Home.md)

data/documentation/Sessions.md

@@ -29,6 +29,13 @@ appended as JSON-per-line to `~/.pwn/sessions/<id>.jsonl`.
 | `sessions_stats` | totals across the whole directory |
 | `sessions_lean` | prune stubs and aged unreferenced transcripts; compact oversized tool/assistant content (pins gold outcomes and open-mistake refs) |
 
+Session titles, dependency pins and shared activity leases are described in
+[Installation](Installation.md). Scheduled cleanup is not equivalent to deleting
+all old transcripts. Verified retained learning evidence can release some source
+pins only after migration/readback; see [Reinforcement Learning](Reinforcement-Learning.md).
+Exact unfinished requests resume through `pwn-ai --resume-session ID`, not a new
+one-shot session.
+
 ## File format
 
 ```json

data/documentation/Skills-Memory-Learning.md

@@ -1,9 +1,15 @@
 # Memory · Skills · Learning · Mistakes · Metrics · Policy - Introspection
 
-The inward half of the pwn-ai feedback loop: the agent writes what it did, and the next prompt can see it. Wins become skills. Failures become fingerprinted mistakes.
+The inward half of the pwn-ai feedback loop: the agent writes what it did, and the next prompt can see it. Verified procedures may support reviewed skill updates; routine wins do not create skills. Failures become fingerprinted mistakes.
 
 ![Memory / Skills detail](diagrams/memory-skills-detailed.svg)
 
+Completion metrics distinguish checked host completion from judge claims and
+legacy quality scores. Failure-derived recipes stay regression data; frozen
+held-out evaluation never feeds back into the source snapshot. Skill review and
+routing-policy promotion are separate guarded operations, not automatic proof
+of general improvement. See [Operability](Operability.md).
+
 ## The six stores
 
 | Store | File | Write tool | Read tool | Injected as |
@@ -19,7 +25,7 @@ The inward half of the pwn-ai feedback loop: the agent writes what it did, and t
 
 `PWN::AI::Agent::Metrics` keeps two rates that RSI can compare across turns.
 
-ESR is `verified_exploit_tools / vulnerable_tools`. A tool enters `verified_exploit_tools` only when an exploit attempt for that tool name succeeds. A tool enters `vulnerable_tools` when the caller marks it vulnerable, or when a successful exploit names that target. Repeating the same tool does not change the counts. The rate stays nil until at least one vulnerable tool exists.
+ESR is `verified_exploit_tools / vulnerable_tools`. The numerator uses distinct tool/CWE names while the denominator uses distinct vulnerable assets: this can exceed 1 and is not a comparable success percentage. A tool enters `verified_exploit_tools` only when an exploit attempt for that tool name succeeds. A tool enters `vulnerable_tools` when the caller marks it vulnerable, or when a successful exploit names that target. Repeating the same tool does not change the counts. The rate stays nil until at least one vulnerable tool exists.
 
 ASR is `successful_attacks / total_attack_attempts`. Every attack attempt increments the denominator. A reproduced impact, a still-open retest, or an accepted `chain_impact` increments the numerator. This one is an attempt ratio, not a set of tool names.
 
@@ -55,7 +61,7 @@ wiping durable facts, preferences, and lessons. Clearing is still available via
    ↳ if auto_extrospect enabled      → Extrospection.auto_extrospect  # AUTO_SECTIONS only
 7. Reflect.on(engine: reflect_engine)→ Memory.remember(lesson_xxxx, ...)   # teacher-student: a
                                        frontier engine may WRITE the lesson a local engine READS
-8. A whole workflow succeeded         → Learning.distill_skill(name, session_id, references:)
+8. Explicit distillation / SkillReview → reviewed reusable procedure (not every success)
 9. Found a fix for a mistake          → mistakes_resolve(sig, fix) → Memory :lesson "AVOID X - FIX: Y"
 10. (weekly, cron) Learning.export_finetune (min judge score + process-reward compress) +
      Reward.export_dpo (per-source cap + trajectory geometry scrub) → ~/.pwn/finetune/*.jsonl → LoRA over the local
@@ -250,7 +256,8 @@ episode:
 1. `begin_episode` opens before the first tool rank.
 2. `observe_step` writes a hygiene reward after each tool (`semantic_ok`).
 3. `finish` (from `Learning.auto_introspect`, or Loop if introspect is skipped)
-   adds the `Reward.judge` terminal score and updates Q and REINFORCE.
+   records the resolved outcome. Unknown outcomes do not train; positive terminal
+   credit requires independently attributed action IDs, not judge prose alone.
 
 State is a short key: request kind, a hash of the active English task, last
 action, fail count bin, and engine. Files:

data/documentation/Swarm.md

@@ -131,6 +131,12 @@ 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.
 
+Parent completion does not trust a child's success prose. Current child receipts
+can satisfy only parent-required exact targets with matching request/turn/action
+provenance and current readback; the parent reruns its integration checks. The
+offline Swarm fault lanes in [Harness Evaluation](Harness-Evaluation.md) exercise
+missing, stale, lying and tampered artifacts without live providers.
+
 ## Define personas
 
 Each persona accepts optional `engine` and `model` keys. `model` is the exact

data/documentation/Transparent-Browser.md

@@ -15,7 +15,7 @@ JS-heavy.
 b = PWN::Plugins::TransparentBrowser.open(
   browser_type: :headless,           # :chrome | :firefox | :headless | :rest
   proxy:        'http://127.0.0.1:8080',
-  with_devtools: true
+  devtools:     true
 )
 b[:browser].goto 'https://target'
 b[:browser].text_field(name: 'q').set 'pwn'

data/documentation/Troubleshooting.md

@@ -100,10 +100,13 @@ fix the port via `pwn-vault` (`~/.pwn/pwn.yaml`).
 Fixed in current `PWN::Cron` / `Swarm` - both loaders now pass
 `permitted_classes: [Symbol]`. If you see it, `gem update pwn`.
 
-## Agent stops early ("max iterations")
+## Agent stops before verified completion
 
-Raise `ai.agent.max_iters` in `~/.pwn/pwn.yaml` (edit via `pwn-vault`), or
-split the request.
+Inspect the request log under `~/.pwn/logs/` (or `PWN_DEBUG_DIR`) and the
+persisted request/verification checkpoint. Increasing `max_iters` is not a
+completion fix: current Loop does not finalize merely because that count was
+reached. Preserve failure evidence and resume the unfinished objective; see
+[Session Workflow](Session-Workflow.md) and [Harness Evaluation](Harness-Evaluation.md).
 
 ## A tool is stuck at 0 % success
 

data/documentation/What-is-PWN.md

@@ -12,14 +12,14 @@ with a **tool-calling AI agent** on top that can run the same methods.
 
 | Namespace | Count | What it is |
 |---|---|---|
-| `PWN::Plugins::*` | **67** | Wrappers for external and native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, ...) |
+| `PWN::Plugins::*` | **107** | Wrappers for external and native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, ...) |
 | `PWN::SAST::*` | **48** | Static-analysis rules across C/Java/Go/Python/Ruby/Scala/PHP/TS |
 | `PWN::AWS::*` | **90** | One module per AWS service for cloud enumeration |
 | `PWN::WWW::*` | **22** | Site-specific browser automations (HackerOne, BugCrowd, GitHub, Google, LinkedIn, ...) |
-| `PWN::SDR::*` | **6** (+ **20** protocol decoders + Base/DSP) | GQRX, FlipperZero, RFIDler, SonMicro, band tables, `Decoder::{ADSB,POCSAG,RDS,LoRa,...}` |
-| `PWN::FFI::*` | **8** | Native DSP/RF backends: Volk · Liquid · FFTW · RTLSdr · HackRF · AdalmPluto · SoapySDR · Stdio |
+| `PWN::SDR::*` | **6** (+ **21** protocol decoders + Base/DSP) | GQRX, FlipperZero, RFIDler, SonMicro, band tables, `Decoder::{ADSB,POCSAG,RDS,LoRa,...}` |
+| `PWN::FFI::*` | **11** | Native bindings (including DSPNative, Capstone and Keystone): Volk · Liquid · FFTW · RTLSdr · HackRF · AdalmPluto · SoapySDR · Stdio |
 | `PWN::AI::*` | **6** engines | OpenAI, Anthropic, Grok (OAuth device-flow), Gemini, Ollama, Open WebUI |
-| `bin/pwn_*` + `pwn` | **54** | Headless CLI executables for CI/CD |
+| `bin/` (including `pwn-ai` and `pwn-capd`) | **56** | Headless CLI executables for CI/CD |
 | Agent toolsets | **16** · **150 tools** | terminal · pwn · memory · skills · sessions · learning · metrics · policy · extrospection · cron · swarm · reward · curriculum · http · mcp · manifest |
 
 ## Three ways to use it

data/documentation/Why-PWN.md

@@ -32,7 +32,7 @@ critical when the caller is an autonomous agent.
 |---|---|
 | "Trust our scanner" | `cat lib/pwn/sast/sql.rb` - read the regex yourself |
 | Per-seat license for the glue | MIT-licensed glue; bring your own Burp Pro / Nessus key |
-| Agent output is a PDF | Agent output is a `PWN::Reports` object *and* a distilled skill *and* a memory entry |
+| Agent output is a PDF | Reports, memories and reusable skills are separate explicit outputs; one does not prove the others were created |
 | One vendor's model | Six interchangeable engines; swarm can pit them against each other |
 
 ## Why the feedback loop matters