pwn 0.5.621 → 0.5.626

data/documentation/Home.md

@@ -36,10 +36,10 @@
 | | |
 |---|---|
 | [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama |
-| [Agent Tool Registry](Agent-Tool-Registry.md) | 10 toolsets · 54 LLM-callable tools |
+| [Agent Tool Registry](Agent-Tool-Registry.md) | 10 toolsets · 61 LLM-callable tools |
 | [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection — the self-improvement loop |
 | [Mistakes](Mistakes.md) | **Negative feedback** — fingerprint failures · do-NOT-repeat · `[REPEATING]`/`[REGRESSED]` · inline self-correction |
-| [Extrospection](Extrospection.md) | World-awareness — snapshot · drift · intel · **watch** · **verify** · correlate · **rf** · **web** |
+| [Extrospection](Extrospection.md) | World-awareness — snapshot · drift · intel · **watch** · **verify** · **rf_tune** · correlate · **rf** · **web** |
 | [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
 | [Sessions](Sessions.md) | Transcript persistence + reflection |
 | [Cron](Cron.md) | Scheduled autonomous jobs |
@@ -58,11 +58,11 @@
 | [SAST (48 rules)](SAST.md) | Static analysis + test-case engine |
 | [WWW (21 drivers)](WWW.md) | Browser automations for real sites |
 | [AWS (90 services)](AWS.md) | Cloud-security enumeration |
-| [SDR](SDR.md) | GQRX · FlipperZero · RFIDler · SonMicro · **Decoder::* (20 protocols)** |
+| [SDR](SDR.md) | GQRX · FlipperZero · RFIDler · SonMicro · **Decoder::* (20)** · FFI-accelerated DSP |
 | [Blockchain](Blockchain.md) | BTC · ETH helpers |
 | [Bounty](Bounty.md) | Lifecycle / auth-replay tooling |
 | [Reports](Reporting.md) | HTML/JSON output + DefectDojo/Jira |
-| [FFI](FFI.md) | Native calls |
+| [FFI](FFI.md) | Native DSP/RF backends (Volk · Liquid · FFTW · HackRF · RTL-SDR · SoapySDR) |
 | [Banner](Banner.md) | 15 startup banners |
 
 ## 🛠️ Meta

data/documentation/How-PWN-Works.md

@@ -27,12 +27,12 @@ hardware).
 | Module | Role |
 |---|---|
 | `Loop` | plan → dispatch tool_calls → observe → repeat until final answer |
-| `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** · 54 tools |
+| `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** · 61 tools |
 | `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
 | `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / **KNOWN MISTAKES + FIXES** / METRICS / EXTROSPECTION blocks |
 | `Metrics` · `Learning` | **introspection** — how well am I doing? |
 | `Mistakes` | **negative feedback** — fingerprint failures, do NOT repeat, `[REPEATING]`/`[REGRESSED]`, inline `correction_hint` |
-| `Extrospection` | **extrospection** — what does the world look like? (host · net · toolchain · repo · env · **rf**) |
+| `Extrospection` | **extrospection** — on-demand world sensing (`intel` · **`verify`** · **`watch`** · **`rf_tune`**) + ambient baseline (host · net · toolchain · repo · env · **rf** · **web**) joined to introspection via `correlate` |
 | `Swarm` | multi-agent personas over a shared JSONL bus |
 
 See [Agent Tool Registry](Agent-Tool-Registry.md) for every tool the LLM can call.
@@ -56,7 +56,11 @@ See [Persistence](Persistence.md) for the byte-level layout of each file.
 
 The reason L2 exists is to close this loop on every turn — successes
 become skills/lessons, **failures become fingerprinted mistakes with fixes**,
-and both are re-injected into the very next system prompt:
+**world-state is sensed on demand** (`extro_verify` / `extro_watch` /
+`extro_rf_tune` / `extro_osint` / `extro_serial` / `extro_telecomm` / `extro_packet` / `extro_vision` / `extro_voice` / `extro_intel`) and correlated against those failures, and
+**all six prompt blocks** (MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES ·
+TOOL EFFECTIVENESS · EXTROSPECTION) are re-injected into the very next system
+prompt:
 
 ![Self-improvement loop](diagrams/pwn-ai-feedback-learning-loop.svg)
 

data/documentation/Mistakes.md

@@ -90,6 +90,15 @@ and the entry re-enters the `KNOWN MISTAKES` block tagged `[REGRESSED]` with
 its (now-insufficient) previous fix shown inline — the strongest possible
 "your last fix didn't hold" signal.
 
+## Join with Extrospection
+
+A tool failure is **not always the agent's fault**. Before treating a
+`[REPEATING]` signature as a pure technique bug, call `extro_correlate` —
+it cross-checks Mistakes / Metrics / Learning against host/toolchain/rf/web
+drift so the agent can distinguish "I called the API wrong" from "nmap was
+upgraded", "the HackRF was unplugged", or "the target DOM moved". See
+[Extrospection](Extrospection.md#extro_correlate--the-point-of-the-whole-thing).
+
 **See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
 [Extrospection](Extrospection.md) · [Persistence](Persistence.md) ·
 [pwn-ai Agent](pwn-ai-Agent.md)

data/documentation/SDR.md

@@ -6,7 +6,7 @@
 
 | Module | Purpose |
 |---|---|
-| **`GQRX`** | Remote-control a running GQRX instance over TCP: tune, set demod, squelch, record, `get_spectrum_snapshot` (pure-Ruby FFT — median noise floor, DC/LO-leakage null, band-edge guard), `fast_scan_range` |
+| **`GQRX`** | Remote-control a running GQRX instance over TCP: tune, set demod, squelch, record, `get_spectrum_snapshot` (pure-Ruby FFT — median NF, relative peak/prominence, **plan-parametric** min-distance & −6 dB BW), `fast_scan_range` (**always RAW @ sample_rate** panoramic capture; band-plan IF deferred to refine/decoder; `#fft_plan_geometry` derives sep/merge/refine/snap from `(plan_bw, step, res)`; local-FFT refine + S-meter confirm; schema-parity with `scan_range`) |
 | `FlipperZero` | Serial control of Flipper (sub-GHz, NFC, IR, iButton) |
 | `RFIDler` | 125 kHz RFID reader/emulator |
 | `SonMicroRFID` | SM130 13.56 MHz reader |
@@ -16,16 +16,39 @@
 ## CLI
 
 ```bash
-# FFT sweep — SNR-gated peak detection (no false-positive flood)
-pwn_gqrx_scanner --start 430e6 --stop 440e6 --fft-scan \
+# FFT sweep — plan-parametric peak geometry + local-FFT refine for exact centres
+# Works for ALL band plans (CW 150 Hz → FLEX 20 kHz → FM 200 kHz → GPS 30 MHz)
+pwn_gqrx_scanner -a pager_flex --fft-scan                 # alias: flex_pager
+pwn_gqrx_scanner -a fm_radio   --fft-scan --min-snr-db 18
+pwn_gqrx_scanner -a am_radio   --fft-scan --no-refine
+pwn_gqrx_scanner --scan-ranges 430.000.000-440.000.000 --fft-scan \
                  --avg 8 --min-snr-db 10 --capture-secs 0.10
+# Skip refine (pure panoramic): add --no-refine
+# Explicit S-meter lock (skips auto-cal from live NF): -S -55
 
 # Classic iterative S-meter scan
-pwn_gqrx_scanner --start 118e6 --stop 137e6 --step 12.5e3 \
-                 --strength-lock -60 --audio-gain-db 6
+pwn_gqrx_scanner -a aviation_vhf
+pwn_gqrx_scanner -s 118.000.000-137.000.000 -D AM -b 25.000 -P 4 -S -60
 ```
 
-See skill `pwn_gqrx_scanner_fast_vs_iterative_scanning` for the trade-off.
+### `--fft-scan` geometry (all 84 band plans)
+
+Every detector/refine/merge knob is a pure function of the two band-plan
+invariants already on each plan (`bandwidth` → `plan_bw_hz`, `precision` →
+`step_hz = 10**(precision-1)`) plus spectrum resolution `res_hz = sample_rate/nfft`:
+
+| Stage | Rule |
+|---|---|
+| Capture IF | **Always** `M RAW sample_rate` (IQRECORD is demod IF — never plan FM/20 kHz) |
+| Peak height / prom | Relative: `median_nf + 12 dB`, prom ≥ 8 dB |
+| Peak min-distance | `#fft_plan_geometry` → `sep_hz = max(0.5·plan, step, floor)` |
+| Occupied BW | −6 dB-from-peak contour, hard-capped to `± plan_bw` |
+| Centre | Power-weighted centroid of −6 dB lobe → raster snap |
+| Merge | `tol = max(½ plan, step, ½ measured_bw, 2·res)` |
+| Refine window | ~0.6·plan (capped so next neighbour is outside); local high-res FFT |
+| Strength lock | Auto from live S-meter NF + 8 dB unless `-S` given |
+
+See skill `pwn_gqrx_scanner_fast_vs_iterative_scanning` for the full trade-off.
 
 ## REPL example
 
@@ -38,20 +61,70 @@ PWN::SDR::FrequencyAllocation.lookup(freq: 433_920_000)
 # => { band: 'ISM 433', typical: ['garage doors', 'weather stations', …] }
 ```
 
+
+## Native DSP acceleration (`PWN::FFI`)
+
+`PWN::SDR::Decoder::DSP` transparently accelerates hot paths when the host
+has the matching shared libraries:
+
+| DSP method | Backend | Library |
+|---|---|---|
+| `unpack_s16le` | `PWN::FFI::Volk` | libvolk |
+| `resample` | `PWN::FFI::Liquid` | libliquid |
+| `dc_block(m:)` | `PWN::FFI::Liquid` | libliquid |
+| `rms_dbfs` (≥64) | `PWN::FFI::Volk` | libvolk |
+
+```ruby
+PWN::FFI.backends
+# => {FFTW: true, HackRF: true, Liquid: true, RTLSdr: true, SoapySDR: true, Volk: true}
+
+# Force pure-Ruby (e.g. for tests / A/B)
+PWN::SDR::Decoder::DSP.native = false
+```
+
+Front-end inventory & raw I/Q capture:
+
+```ruby
+PWN::FFI::SoapySDR.list_devices
+# => [{driver: "hackrf", label: "HackRF Pro #0 …", serial: "…"}, …]
+
+PWN::FFI::RTLSdr.list_devices
+dev = PWN::FFI::HackRF.open
+PWN::FFI::HackRF.configure(device: dev, freq_hz: 433_920_000, rate_hz: 10e6)
+PWN::FFI::HackRF.close(device: dev)
+```
+
+See [FFI](FFI.md) for the full binding surface and design rules.
+
 ## RF ↔ Extrospection
 
-The AI agent is RF-aware. `extro_snapshot(sections: [:rf])` runs `probe_rf`
-(RTL-SDR / HackRF / SoapySDR / Flipper / GQRX-socket inventory) and RF signal
-intel is recorded with a first-class `:rf` observation category:
+The AI agent is RF-aware. Two layers:
+
+| Layer | Call | Role |
+|---|---|---|
+| **Passive inventory** | `extro_snapshot(sections: [:rf])` → `probe_rf` | RTL-SDR / HackRF / SoapySDR / Flipper / GQRX-socket presence |
+| **Active sense organ** | **`extro_rf_tune(freq: "101.1")`** | Connect to a *running* GQRX remote-control socket, tune, demod, measure strength, sample RDS → `now_playing` / `station` |
 
 ```ruby
+# record a recon finding
 extro_observe(source: 'gqrx', category: :rf, target: '433.920MHz',
               data: 'peak -34.2 dBFS bw=200k FSK — likely garage remote')
+
+# ask the radio a question (RDS on FM broadcast)
+extro_rf_tune(freq: '101.1')
+# → { ok:true, freq:"101.1 MHz", strength_dbfs:-2.8, station:"X96",
+#     now_playing:"Mr. Brightside by The Killers", rds:{pi,ps_name,radiotext}, … }
+# → observe(category: :rf, ttl: 300)   # songs are ephemeral
 ```
 
+RDS sampling is `PWN::SDR::Decoder::RDS.sample` (non-interactive Hash). The
+TTY spinner (`Decoder::RDS.decode`) stays the human path used by
+`GQRX.init_freq(decoder: :rds)`. Agents and cron use `extro_rf_tune` /
+`.sample(interactive: false)`.
+
 `extro_correlate` then cross-references `:rf` observations against missing
 `RF_BINS` / unplugged hardware so the agent can tell "no signal" from "no
-dongle".
+dongle" / "GQRX remote control is down".
 
 **See also:** [Hardware](Hardware.md) · [Extrospection](Extrospection.md)
 

data/documentation/Skills-Memory-Learning.md

@@ -19,18 +19,26 @@ its own performance, turns wins into permanent capability, and — critically
 ## The lifecycle of a lesson
 
 ```text
-1. Dispatch runs a tool           → Metrics.record(tool, ok?, ms)
-   ↳ tool FAILED?                 → Mistakes.record(tool, error)  (count++, cross-session)
-   ↳ same sig ≥3×?                → guard_repeated_failure + inline correction_hint
-2. Final answer produced          → Learning.auto_reflect(session_id)
-3. Reflect finds a durable insight → Memory.remember(lesson_xxxx, …)
-4. A whole workflow succeeded      → Learning.distill_skill(name, session_id, references:)
-5. Found a fix for a mistake       → mistakes_resolve(sig, fix) → Memory :lesson "AVOID X — FIX: Y"
-6. Next launch: PromptBuilder injects all five blocks → the model already knows.
+1. Dispatch runs a tool              → Metrics.record(tool, ok?, ms)
+   ↳ tool FAILED?                    → Mistakes.record(tool, error)  (count++, cross-session)
+   ↳ same sig ≥3×?                   → guard_repeated_failure + inline correction_hint
+2. Agent senses the world (opt)      → extro_verify / watch / rf_tune / osint / serial / telecomm / packet / vision / voice / intel / observe
+   ↳ extro_verify → :refuted         → Mistakes.record(tool:'assumption', …)  # proactive
+   ↳ extro_verify → :confirmed       → observe(:intel, ttl:30d)
+3. Final answer produced             → Learning.auto_introspect(session_id)
+   ↳ if auto_extrospect enabled      → Extrospection.auto_extrospect  # AUTO_SECTIONS only
+4. Reflect finds a durable insight   → Memory.remember(lesson_xxxx, …)
+5. A whole workflow succeeded         → Learning.distill_skill(name, session_id, references:)
+6. Found a fix for a mistake          → mistakes_resolve(sig, fix) → Memory :lesson "AVOID X — FIX: Y"
+7. Next launch: PromptBuilder injects all six blocks → the model already knows:
+     MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS · EXTROSPECTION
 ```
 
-See **[Mistakes](Mistakes.md)** for the full negative-feedback mechanics
-(fingerprinting, `[REPEATING]`, `[REGRESSED]`, user-correction detection).
+`extro_correlate` is the **join** — it tells the agent whether a failure was
+*its* fault (belongs in Mistakes) or *the world* changed (kernel upgrade,
+dongle unplugged, target DOM moved). See **[Mistakes](Mistakes.md)** for the
+negative-feedback mechanics and **[Extrospection](Extrospection.md)** for the
+outward half.
 
 ## Skill file format
 
@@ -66,7 +74,89 @@ the `## References` section, deduplicates, and exposes them via
 | `mistakes_reset(confirm: true)` | new host/engagement — prior failure patterns no longer apply |
 | `metrics_reset(confirm: true)` | fixed a broken tool; stale 0 % is misleading |
 | `skill_delete(name)` | auto-distilled skill turned out low-quality |
-| `learning_auto_reflect_toggle(enabled: false)` | during noisy fuzz loops |
+| `learning_auto_introspect_toggle(enabled: false)` | during noisy fuzz loops |
+
+## Example questions that trigger Introspection
+
+Natural-language prompts that should fire the **inward** half of the learning
+feedback loop (Memory · Skills · Learning · Mistakes · Metrics). Pair these with
+the outward catalog in [Extrospection](Extrospection.md#example-questions-that-trigger-extrospection)
+when deciding which side of the loop to exercise.
+
+### Memory (`memory_remember`, `memory_recall`, `memory_forget`, `memory_clear`)
+
+- “Remember that our preferred AI engine for long recon chains is grok-4.5.”
+- “What do we already know about OpenSSH 8.2p1 from prior sessions?”
+- “Forget the stale fact about the old HackRF serial — it was replaced.”
+- “Store this as a durable lesson: always back up source files before patching.”
+- “Recall any preference we set for Burp/ZAP proxy ports.”
+
+### Skills (`skill_list`, `skill_view`, `skill_create`, `skill_add_reference`, `skill_delete`, `learning_distill_skill`)
+
+- “What skills do we have for SQLi / RDS / GQRX scanning?”
+- “Show me the full body of `vulnerability_research_fundamentals`.”
+- “Distill this successful session into a reusable skill for ADS-B capture.”
+- “Add CWE-89 and T1190 as references on the `sqli_union_enum` skill.”
+- “Delete the low-quality auto-distilled skill from yesterday’s fuzz loop.”
+- “Create a skill that walks GQRX remote control → `extro_rf_tune` → observe.”
+
+### Learning outcomes & reflection (`learning_note_outcome`, `learning_reflect`, `learning_outcomes`, `learning_stats`, `learning_consolidate`)
+
+- “Record that the video-generation pipeline succeeded (ffmpeg + flite).”
+- “What was our success rate over the last 50 attempts?”
+- “Reflect on session `20260709_172057_49594079` and extract durable lessons.”
+- “Show only the recent *failures* tagged with `extrospection` or `rf`.”
+- “Consolidate near-duplicate MEMORY lessons — cap at 200 entries.”
+- “Reset learning outcomes; the dev experiment noise polluted the rate.” *(destructive)*
+
+### Mistakes / negative feedback (`mistakes_list`, `mistakes_record`, `mistakes_resolve`, `mistakes_reset`)
+
+- “What mistakes keep recurring across sessions?”
+- “I just assumed Registry had `.list` — record that as an assumption mistake.”
+- “Resolve signature `1b6f88b46ce2` — the fix is use `.all` / `.lookup`, not `.list`.”
+- “Show only unresolved fingerprints sorted by count.”
+- “That last approach was wrong; fingerprint it so we don’t repeat it.”
+- “Wipe mistakes.json for a clean slate on the new engagement host.” *(destructive)*
+
+### Metrics / tool effectiveness (`metrics_summary`, `metrics_reset`)
+
+- “Which tools have the lowest success rate right now?”
+- “How often has `shell` been called, and what’s its avg duration?”
+- “Is `extro_rf_tune` healthier than the old GQRX helpers by metrics?”
+- “Reset metrics after we fixed the broken tool so the 0 % doesn’t steer us away.” *(destructive)*
+
+### Sessions / transcripts (`sessions_list`, `sessions_view`, `sessions_current`, `sessions_stats`, `sessions_delete`)
+
+- “What’s the active session id?”
+- “List the last 10 sessions and their sizes.”
+- “Open session X and show the last 50 turns (truncated).”
+- “How much disk are session transcripts using overall?”
+- “Delete the noisy fuzz-experiment transcript so reflect() stays high-signal.”
+
+### Loop toggles & housekeeping
+
+- “Disable auto-introspect while we fuzz; re-enable for the summary turn.”
+- “Is auto-introspect currently on?”
+- “Revalidate MEMORY facts that contain CVEs / versions / URLs.” *(joins Extrospection.revalidate_memory)*
+- “Why did that tool start failing — my fault or world drift?” → `extro_correlate` then Mistakes vs Learning
+
+### Short “trigger” patterns the agent should recognize
+
+| Pattern | Likely tools |
+|--------|----------------|
+| “Remember / recall / forget that…” | `memory_remember` / `memory_recall` / `memory_forget` |
+| “What skills do we have for… / distill this” | `skill_*` / `learning_distill_skill` |
+| “Did that work? / note the outcome / success rate” | `learning_note_outcome` / `learning_stats` |
+| “Reflect on this session / extract lessons” | `learning_reflect` / `sessions_current` |
+| “Don’t do that again / that was wrong / resolve…” | `mistakes_record` / `mistakes_resolve` / `mistakes_list` |
+| “Which tools are unhealthy / avg duration” | `metrics_summary` |
+| “What did we run in session X / active session” | `sessions_view` / `sessions_current` |
+| “Disable reflection while we fuzz” | `learning_auto_introspect_toggle` |
+
+Contrast with **Extrospection** examples: weather in Chicago, “what’s on 101.1”,
+CVE fact-checks, and host drift are *outside-world* senses. The table above is
+purely *self* measurement — how well the agent did, what it must stop repeating,
+and which procedures to promote permanently.
 
 **See also:** [Mistakes](Mistakes.md) — the negative-feedback half ·
 [Extrospection](Extrospection.md) — the outward-facing half ·