pwn 0.5.724 → 0.5.728

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1c409d6b05e3c061837ef187c74d22ff5e24d361aee4531be0943714a8f713b
-  data.tar.gz: dacfce51246aee0f02c84b5a8eae1651fe2853db2e0f192343c5fc8cfbc5462b
+  metadata.gz: '0018be9794020a4b996e0d67a076e2741ca124d475f1439a047a77ecc0667d9d'
+  data.tar.gz: 46eae2746ab67af7ace35e7dc4caa6e09897a187ec7295a6fe5b103a33262722
 SHA512:
-  metadata.gz: 6c29fd2cde7775f1923249f166af195dcc99ed0614c86536d3aeb56bcc7a3d29a28a3483b1b2c25bb736b2b78b28ab92a0906d690cd71d002ff335c41e1e5d78
-  data.tar.gz: cbcf28e1681df68a21a1da6f247bf645de861ee2a752af2f3735f09f2a59501bdd9d5fb5bf238dcc39ae2734ea173a3d515ddb3df1de2d7548de4fbbb67c5ea7
+  metadata.gz: dd8e061914bb0941234e210a8ea346d4f11dbd0babcd5137e93fe529b094826459b469f6cfb5d2e8cabdc306bbb8471df5703275035a9e8d27fc36352b50ec84
+  data.tar.gz: 4f361334ec04c20998333623be5c2d5b97ab27189dc52f1d4fda470ff40e743c38f58b1ae37b85244557a1f7eaf93954abd3baafdcb96c8bc8d57eb4fc71ff98

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'
@@ -88,9 +88,9 @@ gem 'ruby-audio', '1.6.1'
 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 'savon', '2.17.5'
+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,14 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Deploy the reviewed Ruby library tree with this executable, never setcap Ruby.
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'pwn'
+require 'pwn/plugins/capability_broker/daemon'
+
+begin
+  PWN::Plugins::CapabilityBroker::Daemon.main(argv: ARGV)
+rescue StandardError => e
+  warn "pwn-capd: #{e.message}"
+  exit 1
+end

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,136 @@
+# Capability broker and disposable sandbox
+
+## pwn-capd (P8)
+
+The native Ruby helper speaks one bounded JSON request per Unix connection.
+Ruby `Socket` and `pack` implement AF_PACKET send/capture and pcap encoding;
+the existing `ffi` gem calls Linux libc `prctl`, `capget` and `capset`.
+There is no Python runtime or fallback. Read-only ARP/ND queries retain the
+`/usr/sbin/ip` (iproute2) dependency, executed as an argument vector with a
+clean environment, bounded output and a five-second deadline.
+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.
+
+Requests are limited to 100,000 bytes including the newline; each connection
+has a 35-second total deadline. Ethernet sends accept 14..65,535 decoded bytes.
+Captures accept 1..128 packets, at most 30 seconds, and 4,096 bytes per packet.
+The helper sets `no_new_privs`, intersects effective/permitted capabilities
+with CAP_NET_RAW/CAP_NET_ADMIN, and clears both inheritable words before
+handling requests. It never adds a capability. Existing socket paths (including
+symlinks) and writable or foreign-owned socket directories are refused.
+
+Unprivileged protocol and native-executable smoke (no raw packets or privilege grants):
+
+```
+bundle exec rspec spec/lib/pwn/plugins/capability_broker_spec.rb spec/lib/pwn/plugins/capability_broker/daemon_spec.rb
+```
+
+Operator installation (NOT executed by the application): install the reviewed
+PWN Ruby package and its dependencies root-owned, including `bin/pwn-capd`,
+`lib/pwn/plugins/capability_broker.rb` and
+`lib/pwn/plugins/capability_broker/daemon.rb`. Keep the package's `bin/` and
+`lib/` layout intact; point the service ExecStart at that package's
+`bin/pwn-capd`. A root-managed installed-gem executable may also be exposed
+as `/usr/local/libexec/pwn-capd` (mode 0755). The executable, library tree,
+Ruby interpreter, gems and all ancestor directories must be administrator
+controlled and non-writable by clients. Clear user-controlled `RUBYOPT`,
+`RUBYLIB`, `GEM_HOME`, `GEM_PATH` and Bundler environment settings in the
+service; use only the reviewed installation's dependency paths.
+Do **not** setcap the shared Ruby 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/ruby`, strace, GDB, and target runtime libraries. The controller
+and isolated worker use Ruby stdlib only; no Python interpreter is launched by
+the sandbox driver (GDB itself may include Python support). 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.
+
+Sandbox verification (safe bwrap fixtures require working unprivileged namespaces):
+```
+bundle exec rspec spec/lib/pwn/plugins/sandbox_spec.rb spec/lib/pwn/plugins/sandbox/driver_spec.rb
+```
+
+The tests exercise `/bin/true`, read-only mounts, namespace isolation without
+network requests, timeouts, resource limits, SIGSEGV/GDB/strace replay,
+byte-exact stdin mutation and snapshot integrity. Docker command/cleanup unit
+checks are not evidence of a running Docker backend. The GDB fixture requests
+1024 MiB: this host's GDB can exhaust the default 256 MiB address-space budget.
+Instrumentation failures retain raw output and an unknown classification.
+
+Fuzz seeds are reproducible within this Ruby implementation, not bit-for-bit
+compatible with Python's PRNG sequence. Each iteration retains the execution
+and replay budget plus bounded backend startup/cleanup overhead; the minutes
+budget stops starting new iterations, rather than preempting cleanup.
+
+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/LoRaPHY-LICENSE.txt

@@ -0,0 +1,25 @@
+LoRa PHY coding equations in lib/pwn/sdr/decoder/lora.rb are adapted from
+https://github.com/jkadbear/LoRaPHY/blob/4fddd9a7b47682781c663608bfc4f196e4bf656d/LoRaPHY.m
+
+The MIT License (MIT)
+
+Copyright (C) 2020-2022 jkadbear, jkadbear@gmail.com
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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.