pwn 0.5.784 → 0.5.787

data/documentation/Installation.md

@@ -34,7 +34,7 @@ anchors:
 | state | `swarm/`, `cron/`, `agents.yml`, `jobs/`, `missions/`, `runs/`, metrics | Preserve continuation associations and active work |
 | logs | `logs/` | Only explicitly registered disposable closed logs are eligible; unknown logs remain |
 | cache | `cache/` | Only producer-registered, checksum-verified, inactive disposable files |
-| tmp | `tmp/` | Same registration contract; never glob-delete arbitrary temp files |
+| tmp | `workspaces/runtime/` | Same registration contract; never glob-delete arbitrary temp files |
 | maintenance | `maintenance/`, legacy `session_cleanup_archive/` | Policy, permanent locks, metadata ledgers and recoverable quarantine |
 
 `maintenance/policy.json` is non-secret JSON, version 1. `batch_size` defaults to
@@ -42,7 +42,7 @@ anchors:
 `work_seconds: 30` and `work_bytes: 67108864` for dependency and maintenance
 payload reads, plus reserved disposable backup writes. Existing policy
 files acquire these defaults in memory, without rewriting operator values.
-`maintenance/layout.json` upgrades recognized inventory v1 to v2 separately from
+`maintenance/layout.json` upgrades recognized inventory v1 or v2 to v3 separately from
 policy; unknown inventory versions are refused. `retention_days` defaults to sessions 0, logs 30,
 cache 7, tmp 1, maintenance 90. Null disables that category's expiry. Session
 age is an additional floor, never an override of leases, provenance or evidence.
@@ -149,7 +149,7 @@ deployment or provider run is implied.
 
 The audit covers `Dir.tmpdir`, `Tempfile`, `mktmpdir` and atomic replacement
 call sites, not a filesystem filename sweep:
-- Festival speech input now uses `SessionCleanup.temporary` in `~/.pwn/tmp`, with
+- Festival speech input now uses `SessionCleanup.temporary` in `~/.pwn/workspaces/runtime`, with
   a lifetime lease and exact registration. Concurrent calls have unique names;
   normal completion unlinks the input and a crashed consumer leaves registered bytes.
 - Ghidra/BinaryParser canonical cache publication and managed temporary inputs
@@ -315,7 +315,7 @@ pwn setup --list-profiles
 | `vision` | `OCR` · `ScannableCodes` · `Reports` · `extro_vision` · tesseract / zbar / graphviz |
 | `voice` | `PWN::Plugins::Voice` · `extro_voice` · espeak-ng / sox |
 | `exploit` | `Metasploit` · `sqlmap` |
-| `hardware` | `Serial` · `BusPirate` · `Android` · `BareSIP` · `extro_serial` · `extro_telecomm` |
+| `hardware` | `Serial` · `BusPirate` · `Android` · `BareSIP` · `YubiKey` (HIDAPI/PC/SC, no `ykman`) · `extro_serial` · `extro_telecomm` |
 | `re` | `Radare2` · `GDB` · `ExploitDev` · `Frida` · Android RE (`apktool`/`jadx`) · `pwndbg` · `ropper` · `rizin` |
 | `full` | everything above |
 
@@ -365,7 +365,8 @@ What `--migrate` does:
    (`PWN::Migrate::STATE_FILES` - no re-implemented parsers). If the raw
    file has bytes but the owner returned its empty-fallback, the file is
    flagged incompatible.
-3. **Autofix** (with `--fix`): timestamped backup under `~/.pwn/backup/<ts>/`
+3. **Autofix** (with `--fix`): one shared recovery generation under
+   `~/.pwn/backup/` (seven folders total; see [Backup Retention](Backup-Retention.md))
    → ordered schema migrations → per-file repair (quarantine corrupt to
    `~/.pwn/quarantine/`, re-seed missing dirs, strip unparsable JSONL lines,
    convert legacy flat skills to the [agentskills.io](https://agentskills.io)
@@ -410,8 +411,10 @@ and schedule-only deletion. Already-running old binaries must be upgraded before
 their startup/config-refresh hooks can be relied on to honor the new defaults.
 
 **Housekeeping never uses systemd or any other native scheduler.**
-`session_cleanup`, `learning_consolidate_nightly`, and `pwn_stores_lean_nightly`
-run only through PWN's built-in cron worker or manual commands. Native job
+`session_cleanup` is the only seeded housekeeping job. It runs only through
+PWN's built-in cron worker or a manual command. Older split names
+(`learning_consolidate_nightly`, `pwn_stores_lean_nightly`) are not seeded and
+are not removed automatically. Native job
 installers explicitly skip them with `housekeeping_internal_only`; this also
 covers renamed payloads that invoke `SessionCleanup` or `session_cleanup.rb`.
 Generic scheduler APIs remain available for unrelated custom jobs. Native
@@ -680,7 +683,7 @@ row as `MISSING` until a key is set.
 Everything above is a thin CLI over two autoloaded modules:
 
 ```ruby
-PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, state:, pkg_manager:, os:, arch: }
+PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, state:, pkg_manager:, os:, arch:, native_libraries_missing: }
 PWN::Setup.deps(profile: :web, yes: true) # install, then re-check
 PWN::Setup.list_profiles
 PWN::Setup.migrate(fix: true)             # thin wrapper → PWN::Migrate.run
@@ -715,7 +718,7 @@ Vagrant, CI) picks it up automatically.
 ```ruby
 pwn[CURRENT_VERSION]:001 >>> PWN::Setup.check[:ok]          # => true
 pwn[CURRENT_VERSION]:002 >>> PWN::Migrate.needed?           # => false
-pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 107
+pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 108
 pwn[CURRENT_VERSION]:004 >>> PWN::SAST.constants.count      # => 48
 pwn[CURRENT_VERSION]:005 >>> pwn-ai                         # launches agent TUI
 ```

data/documentation/Mission-Cancellation.md

@@ -0,0 +1,134 @@
+# Mission process lifetime and cancellation
+
+## Implemented boundary
+
+The curses ordinary-request path, local slash-command workers, each curses
+swarm job, and the non-curses `pwn_ai_run_steerable` entrypoint execute provider,
+controller, and tool work
+in a mission-owned Linux PID namespace. CTRL+C kills
+namespace PID 1 through a pidfd, waits for its supervisor to reap it, joins the
+IPC reader, and only then releases the UI's running state. A process group is
+not the ownership boundary: setsid, double forks, and nested child namespaces
+remain descendants of the mission namespace. Other sessions and unrelated
+processes are not signalled.
+
+There is no systemd, cgroup, application compiler, or PGID fallback.
+`PWN::AI::Agent::MissionNamespace` is Ruby code using stdlib Fiddle for Linux pidfds and
+process-death signals. Its runtime prerequisite is **util-linux `unshare`**
+(`pwn setup --profile ai`). Linux user/PID namespaces and pidfds must be enabled;
+unsupported kernels or local policy fail closed with setup guidance.
+
+Ruby recreates its timer thread after fork, so creating a user namespace from a
+Ruby fork is not supported. For ordinary launches the controller **execs** an
+`unshare --user --map-current-user --keep-caps` supervisor. That fresh Ruby
+supervisor creates a PID namespace and forks its init. It passes a pidfd back
+through a private Unix socket; the init waits for acknowledgement before running
+any request. Killing the supervisor also kills its init through PDEATHSIG.
+The controller, its cwd, and unrelated embedded PWN REPL modes are unchanged.
+
+Curses/native, legacy, slash, swarm and one-shot CLI requests use named,
+serializable descriptors, not serialized Ruby closures. Configuration, loaded
+skill metadata and routing context travel as typed JSON over inherited private
+sockets, never in argv or plaintext staging files. RequestRuntime's tool-worker
+snapshot excludes locks and caller cancellation callbacks; the enclosing owner
+provides cancellation. Replies and events remain JSON with generation fencing.
+Loaded Ruby skill scripts are required in the worker. Embedders with additional
+trusted plugin initializers can explicitly set
+`PWN::AI::Agent::MissionNamespace.bootstrap_requires = ['/absolute/plugin/bootstrap.rb']`.
+Arbitrary monkey patches, IO objects and Proc values are not serializable.
+
+For applications explicitly launched in a single-identity user namespace,
+MissionNamespace can fork its PID supervisor directly. This preserves trusted
+in-memory Ruby closures without calling unshare(NEWUSER) from Ruby. The caller
+must bootstrap explicitly with `unshare --user --map-current-user --keep-caps`;
+there is no automatic re-exec of an embedded application. The unit-test runner
+uses this real-kernel mode for in-memory mocks; exec/PTy fixtures explicitly
+force the ordinary descriptor path. Both paths create a real per-mission PID
+namespace and reject unavailable containment.
+
+Ordinary-request events carry a generation; swarm child messages carry job
+IDs, and console swarm callbacks carry an epoch invalidated by CTRL+C.
+Provider calls, including ordinary-request title refresh, remain in the child.
+Steering uses a separate JSON control pipe. The UI never deserializes Ruby
+objects from the child.
+
+## Detached jobs
+
+Detached jobs started by a tool inside a mission inherit that mission's
+namespace. They can continue after the individual tool returns, but **not**
+after mission completion, cancellation, or namespace-owner death. Normal
+mission completion also tears down remaining detached descendants. This is
+intentionally different from cross-session durable jobs. A standalone
+`AISandbox.protect_call` without an enclosing mission creates its own namespace
+and ends that lifetime when the call ends.
+
+Existing files and already-submitted remote operations are not rolled back.
+The local process guarantee does not revoke work accepted by an external
+service or remote host. Kernel-blocked uninterruptible I/O may delay reaping;
+the UI must remain busy rather than claim readiness early.
+
+## Controller-state separation
+
+Tool workers are denied writes to their RequestRuntime artifact/checkpoint
+root, including its spill directories and inherited descriptors. The actual
+worker-symlink -> parent-spill reproducer now fails at the worker's symlink
+with permission denied, and the synthetic source directory remains unchanged.
+The audited controller stores (sessions/traces, transcript artifacts,
+learning/policy/metrics, skills, logs, vault/configuration and mission state) are
+also excluded from worker grants. See the finite writer checklist in
+[Runtime-Source-Protection](Runtime-Source-Protection.md). Unspecified tool
+writes stay in `~/.pwn/workspaces/runtime`; another path is allowed only when
+the original operator request names it. Naming a missing file grants its parent,
+including when that parent contains unrelated unreadable directories, so the
+named file can be created. Controller state and tool output
+workspaces must be disjoint: a parent directory containing protected state
+cannot safely receive a broad Landlock write grant.
+
+## Verification and remaining scope
+
+RSpec owns the subprocess fixtures under `spec/support/harness/mission_*.rb`.
+`spec/integration/mission_cancel_spec.rb` exercises ordinary console next-request
+readiness and generation fencing, blocked-provider descendants, setsid escape,
+normal-exit double forks, unrelated-process preservation, mission-lived tool
+jobs, swarm cancellation, and fail-closed bootstrap. The namespace-denial
+fixture injects EPERM; namespace creation/teardown tests use the real kernel.
+`spec/integration/controller_spill_spec.rb` exercises actual RequestRuntime,
+Dispatch, sandbox restriction, and parent spill persistence with synthetic paths.
+
+Local slash-command maintenance/model/MCP workers now use the same hard process
+ownership. Their completion and UI-state messages are generation-fenced JSON;
+CTRL+C reaps the owner before returning ready. Maintenance already committed
+before cancellation is not rolled back. Model persistence decrypts and encrypts
+in memory; its staging file contains only ciphertext (or is empty). An offline
+SIGKILL regression interrupts encryption startup and verifies unchanged original
+ciphertext and absence of plaintext in the abandoned stage. Native curses PTY
+coverage includes cancellation during a blocked local command and a successful
+next mission.
+
+The legacy regex-ReAct fallback now runs its provider/parser/tool loop in the
+same MissionProcess owner. Completed history is transferred by JSON; native
+containment failures are terminal rather than an excuse to retry uncontained.
+Its actual after_read hook and PTY fixture cover detached Ruby/bash descendants,
+CTRL+C, no late writes and a successful next request. Workspace policy
+clarification does not block these offline gates.
+
+Native PTY regressions drive actual terminal CTRL+C through both the curses
+console and `pwn_ai_run_steerable`, assert no late descendant writes, then complete
+a second mission. Compiler-free package acceptance builds and installs into a
+private scratch GEM_HOME with compiler/make commands replaced by failing shims,
+activates that exact specification, checks an empty extensions list and no
+mission shared object, then executes a descriptor. Root and nonroot acceptance
+must be reported separately; these are offline checks, not provider or hardware
+evidence.
+
+Root loses host-wide DAC override when it enters a user namespace. A host-root
+mission therefore cannot traverse another user's mode-0700 home merely because
+its parent could. Test roots and deployment workspaces must be traversable by
+the mapped host identity. Do not chmod the operator's home to make a fixture
+pass. Filesystem fixtures beneath a private nonroot HOME must use that identity,
+including when their outer test runner is root. The integrated root fixture uses
+an isolated mount namespace: only its task-owned scratch layout is bound at a
+root-traversable path, with HOME, TMPDIR and inherited stdout/stderr logs opened
+inside that layout. Inherited logs opened below the inaccessible real home would
+correctly fail the protected-descriptor preflight. Neither the host mount table
+nor the operator's directory permissions are changed.

data/documentation/Operability.md

@@ -57,6 +57,24 @@ PKI DMs remain unsupported. Topic `region` is an opaque prefix, not the radio's
 regulatory-band setting; `radio_index` is distinct from legacy `channel_num`.
 See [General Usage](General-PWN-Usage.md) and [REPL](pwn-REPL.md).
 
+## Current runtime contract
+
+These are source contracts. A checkout edit does not change an installed gem or
+a process that is already running. Restart after installing the matching package.
+
+| Contract | Current behavior |
+| --- | --- |
+| Tool writes | Unspecified `pwn-ai` writes and `TMPDIR` use `~/.pwn/workspaces/runtime`. Another path is writable only when the original operator request names it, including `mv`/`to`. A missing file grants its parent so the file can be created; that parent is still granted when it contains unrelated unreadable directories. `/opt/pwn` and the loaded package stay read-only. |
+| Mission lifetime | CTRL+C kills the mission through `PWN::AI::Agent::MissionNamespace`. That owner is Ruby plus util-linux `unshare` and Linux pidfds. There is no compiled `pwn_mission` extension and no systemd fallback. |
+| Recovery copies | Every PWN recovery producer uses `PWN::Backups` and `~/.pwn/backup/`, seven generation folders total. Adjacent `.bak` files are not the current producer. |
+| Housekeeping | A fresh install seeds one internal `session_cleanup` coordinator. Curriculum jobs are not seeded. Housekeeping never uses systemd. |
+| YubiKey | `PWN::Plugins::YubiKey` is native Ruby over HIDAPI and PC/SC. `required_bins` is empty and no `ykman` process is started. A library probe is not a connected device. Fixture coverage is not physical interoperability. See [YubiKey](YubiKey.md). |
+
+Details: [Runtime Source Protection](Runtime-Source-Protection.md),
+[Mission Cancellation](Mission-Cancellation.md),
+[Backup Retention](Backup-Retention.md), [Cron](Cron.md),
+[Persistence](Persistence.md).
+
 ## Deployment and safe verification
 
 1. Inspect the intended checkout and preserve existing changes before upgrading.

data/documentation/Persistence.md

@@ -7,8 +7,8 @@ external services and environment overrides can place evidence elsewhere.
 
 | Path | Owner | Format | Reset tool | Purpose |
 |---|---|---|---|---|
-| `pwn.yaml` | `PWN::Config` · `PWN::Plugins::Vault` | AES-encrypted YAML | `pwn-vault` | engines, keys, agent options |
-| `pwn.yaml.decryptor` | `PWN::Plugins::Vault` | key/IV | - | decrypts `pwn.yaml` (or set `PWN_DECRYPTOR_KEY`/`_IV`) |
+| `pwn.yaml` | `PWN::Config` · `PWN::Plugins::Vault` | Legacy AES-CBC or authenticated YubiKey-derived AES-GCM | `pwn-vault` | engines, keys, agent options; see [hardware vaults](YubiKey-Vaults.md) |
+| `pwn.yaml.decryptor` | `PWN::Plugins::Vault` | Legacy key/IV | - | decrypts legacy `pwn.yaml` (or set `PWN_DECRYPTOR_KEY`/`_IV`); absent for hardware-only vaults |
 | **`.schema`** | **`PWN::Migrate`** | JSON `{schema:,pwn_version:,at:}` | `pwn setup --migrate` | **schema stamp - drives the one-line drift warning on launch** |
 | `memory.json` | `PWN::Memory` | JSON array | `memory_clear` | facts · prefs · lessons · env - injected into every prompt |
 | `memory.idx` | `PWN::MemoryIndex` | JSON `{key → {sha,vec}}` | `PWN::MemoryIndex.reset` | local embedding index over `memory.json` - powers **relevance-ranked** MEMORY injection (incremental; only re-embeds changed entries) |
@@ -34,7 +34,8 @@ external services and environment overrides can place evidence elsewhere.
 | `curriculum/` | `PWN::AI::Agent::Curriculum` | JSONL | rm -rf | self-play reproducers · train/gate A/B eval sets |
 | `curriculum_kpi.jsonl` | `PWN::AI::Agent::Curriculum.practice_kpi` | JSONL | rm | outer curriculum KPI snapshots (repeating-mistake trend) |
 | `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` |
+| `workspaces/runtime/` | `PWN::Plugins::AISandbox` · `SessionCleanup.temporary` | files | operator-managed | Unspecified `pwn-ai` writes, `TMPDIR`, and registered disposable inputs such as Festival speech. Another path is writable only when the original request names it. `/opt/pwn` stays read-only |
+| `backup/<generation>/` | `PWN::Backups` | shared generations | see [Backup Retention](Backup-Retention.md) | One store, seven generation folders total, for every recovery producer including migrate |
 | `quarantine/` | `PWN::Migrate` | quarantined originals | rm -rf | corrupt/incompatible state files moved aside so the owner re-seeds |
 | `pwn_history` | Pry / pwn-ai | text | operator-managed | Shared durable input history at `~/.pwn/pwn_history` |
 
@@ -69,8 +70,9 @@ for the full `PWN::Migrate` API.
 tar czf pwn-state-$(date +%F).tgz -C "$HOME" .pwn
 ```
 
-`pwn setup --migrate --fix` also writes one automatically to
-`~/.pwn/backup/<timestamp>/` before touching anything.
+`pwn setup --migrate --fix` admits one generation through `PWN::Backups` under
+`~/.pwn/backup/` before it changes state. That store holds seven generations
+total, not a new unbounded tree per run. See [Backup Retention](Backup-Retention.md).
 
 ## Start fresh for a new engagement
 

data/documentation/Plugin-Degradation.md

@@ -75,6 +75,20 @@ Required: `searchsploit`. Fallback: `intel_lookup`.
 
 Required: `subfinder`, `httpx`. Fallback: `NmapIt.scan` + `Corpus.get`.
 
+## pwn-plugins-yubikey
+
+Required: none. `required_bins` is empty. Preflight probes HIDAPI and PC/SC
+through `available?` and reports `FIDO native transport` or
+`PC/SC native transport` when a library is missing. It never opens a device,
+requests a PIN, or performs a challenge. An `ok` library probe does not
+establish device availability, provisioning, or authorization.
+Hardware-backed vault operations require the selected YubiKey and its existing
+HMAC-SHA1 OTP slot; missing devices, denied touch, or authentication failures
+raise without falling back to a disk master key or software MFA. Restore device
+access before retrying. Dispatch blocks the handler when vault expansion fails;
+if output redaction fails after execution, it withholds the result and reports
+that the handler executed, so verify its effects before retrying.
+
 ## pwn-plugins-credentialattack
 
 Required: `hydra`, `john`, `hashcat`. Fallback: `pwn_eval` + `Corpus`.

data/documentation/Plugins.md

@@ -1,4 +1,4 @@
-# `PWN::Plugins` - All 107 Modules
+# `PWN::Plugins` - All 108 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`.
@@ -64,6 +64,7 @@ show-source PWN::Plugins::Fuzz.http
 |---|---|
 | `OAuth2` · `BasicAuth` · `AuthenticationHelper` | credential flows |
 | `Vault` | Local encrypted configuration and engagement loot helpers; not a HashiCorp Vault client |
+| [`YubiKey`](YubiKey.md) | Native Ruby HID/PC/SC operations, HMAC-backed vaults and OATH codes |
 
 ### Hardware / Physical
 | Module | Purpose | Doc |
@@ -97,6 +98,6 @@ show-source PWN::Plugins::Fuzz.http
 
 ## Full alphabetical list
 
-`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`
+`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 YubiKey Zaproxy`
 
 [← Home](Home.md) · [Diagrams](Diagrams.md)

data/documentation/Policy-Benchmark.md

@@ -9,37 +9,37 @@ not a simulated language model.
 
 ## Run from a source checkout
 
-```sh
-ruby scripts/benchmark_policy.rb --self-check
-ruby scripts/benchmark_policy.rb --output /tmp/pwn-policy-benchmark.json
-bundle exec rubocop scripts/benchmark_policy.rb
+There is no standalone `scripts/benchmark_policy.rb`. The worker lives in
+`PWN::AI::Agent::PolicyEvaluation` and runs only in a fresh Ruby process.
+
+```ruby
+require './lib/pwn/ai/agent/policy_evaluation'
+PWN::AI::Agent::PolicyEvaluation.export_training(dir: '/tmp/pwn-policy-snapshots')
 ```
 
-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, 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.
-They deliberately do **not** require an improvement of a predetermined size.
+`export_training` writes `off.json` and `on.json` under a new directory whose
+parent is a real directory, then returns held-out reports for seeds 0 and 1.
+It does not promote. Frozen snapshots are compared with `evaluate` or
+`pwn-ai --policy evaluate`. Do not load this from the live agent console.
+The worker exits nonzero if persistence changes during evaluation, splits
+overlap, a negative control succeeds, or a positive control fails.
+It does **not** require an improvement of a predetermined size.
 
 ## Relation to existing evaluation
 
 `lib/pwn/ai/agent/curriculum.rb` provides live self-play, judge-based practice,
 mistake-derived evaluation prompts, and adapter training/promotion gates. This
-standalone script does not invoke those paths. It provides a small, independently
+module does not invoke those paths. It provides a small, independently
 scored experiment where the training labels come from actual task achievement,
 not `Reward.judge`, model prose, or a previously assigned reward. It calls
 `Policy.begin_episode`, `observe_step`, and `finish` with those labels during
 training. This is not a test of Reward's verification-record binding, the live
 Loop, Metrics learning, memory retrieval, or adapter training.
 
-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.
+The experimental driver is `PWN::AI::Agent::PolicyEvaluation`. Its public
+methods spawn a fresh Ruby process that loads only Policy and Registry after
+clearing the environment. Loading the module does not enable evaluation or
+promotion.
 
 ## Protocol
 
@@ -161,21 +161,19 @@ 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:
+To export snapshots and run repeated evaluations in **fresh subprocesses**:
 
-```sh
-ruby scripts/benchmark_policy.rb --heldout \
-  --snapshot-dir /tmp/pwn-policy-snapshots \
-  --output /tmp/pwn-policy-heldout.json
+```ruby
+require './lib/pwn/ai/agent/policy_evaluation'
+PWN::AI::Agent::PolicyEvaluation.export_training(dir: '/tmp/pwn-policy-snapshots')
 ```
 
-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 snapshot directory must be **new**. Its parent must be a real directory,
+not a symlink. `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. Export does not
+promote anything or discover/read 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,
@@ -231,13 +229,14 @@ not train or write the live policy. The Ruby API supports other indices 0..7.
 
 From a source checkout, this disposable demonstration stays entirely under a
 new `/tmp` directory (use `pwn-ai` instead of `ruby -Ilib bin/pwn-ai` for an
-installed executable):
+installed executable). Export writes `off.json` and `on.json`; it does not
+promote:
 
 ```sh
 umask 077
 work=$(mktemp -d /tmp/pwn-offline-policy.XXXXXX)
-ruby scripts/benchmark_policy.rb --heldout \
-  --snapshot-dir "$work/snapshots" --output "$work/benchmark.json"
+ruby -Ilib -rpwn/ai/agent/policy_evaluation -e \
+  "PWN::AI::Agent::PolicyEvaluation.export_training(dir: '$work/snapshots')"
 ruby -Ilib bin/pwn-ai --policy evaluate \
   --baseline "$work/snapshots/off.json" --candidate "$work/snapshots/on.json" \
   > "$work/reports.json"

data/documentation/Runtime-Source-Protection.md

@@ -0,0 +1,162 @@
+# Runtime source protection
+
+> The mandatory worker boundary protects source and separates the finite
+> controller-state inventory below from tool writes. Checkpoint persistence also
+> uses pinned fd-relative no-follow directory operations. Process containment
+> owns detached tool jobs until mission completion/cancellation; it is not a
+> substitute for filesystem protection. Unspecified tool writes use
+> `~/.pwn/workspaces/runtime`. A path is writable outside that directory only
+> when the original operator request names it. An explicit destination grants
+> its parent even when that parent contains unrelated unreadable directories,
+> so a new file can be created there. Source checkouts stay read-only
+> even if named. See [Mission-Cancellation](Mission-Cancellation.md).
+
+A pwn-ai RequestRuntime dispatch executes its registered handler in an AISandbox
+worker. This boundary is mandatory even when the optional `ai_sandbox` profile
+is `off`. It covers shell, Ruby evaluation, other registered handlers, nested
+Dispatch calls, and fork/exec descendants including durable Jobs supervisors.
+Direct library calls made by an operator outside a RequestRuntime are not AI
+runtime tool calls and are unchanged. Legacy regex-ReAct Ruby and shell blocks
+also use the mandatory worker boundary (inside their enclosing mission); they
+no longer evaluate directly in the mission controller. The source-denial
+regression drives both languages through the actual Pry after_read hook.
+
+The host protects `/opt/pwn` when present and the real source root containing the
+loaded package. Linux Landlock ABI 3 or newer denies content writes, truncation,
+creation, removal, and linking under those roots. It resolves symlinks and `..`
+in the kernel: scripts are not rewritten. Repo reads remain available. The UI
+process does not change cwd. Relative reads use the task directory when it is
+outside protected source; otherwise they use `~/.pwn/workspaces/runtime`.
+Unnamed new files and temporary files go to that runtime directory. `/tmp`, the
+launch directory, and the rest of `~/.pwn` are not default write grants. A path
+named by the original operator request is created and granted; naming a file
+grants its parent so the file can be created. That parent grant is a directory
+rule, so a new file can still be created when the parent contains unrelated
+unreadable directories. Do not create the missing destination as a directory.
+Protected source is never granted.
+Standard null/zero/random devices are available. Other filesystem writes fail
+closed. This bounded write set permits hardlink-alias exclusion without scanning
+all mounted filesystems or changing checkout permissions.
+
+## Fail-closed requirements and restrictions
+
+- Supported syscall ABIs are Linux x86_64 and aarch64; libseccomp is required.
+  Missing enforcement prevents handler execution, rather than falling back to
+  regex checks or unsandboxed execution.
+- Landlock does not mediate file metadata changes. The worker therefore denies
+  chmod/chown, timestamp and extended-attribute mutation system-wide, including
+  outside source. Ordinary outside content writes and file creation still work.
+  Tools that need those metadata operations require a different supported
+  execution environment, not an exception to source protection.
+- Mount/namespace manipulation, ptrace/process-memory writes, and io_uring setup
+  are denied. Existing descriptors into protected roots are closed in the child.
+- Host preflight inventories multiply linked protected file identities and
+  excludes matching aliases in every writable tree. Aliases elsewhere receive
+  no write grant. Alias inventories are cached against source inode/link-count/
+  ctime fingerprints and writable-root identity; source link changes invalidate
+  that cache. Unreadable subtrees encountered during alias scanning are excluded.
+  This includes generated rdoc assets linked to installed gem assets; no source
+  files are chmodded, deleted, or automatically rewritten.
+- Protected root ancestors cannot grant inherited write permission without also
+  granting it to source. Creating a new sibling directly in such an ancestor is
+  consequently denied; use an existing writable outside directory.
+- This is a local process/filesystem effect boundary, not isolation of remote
+  services or already-running privileged daemons commanded over IPC/network.
+  It does not defend against a concurrent external actor replacing policy paths
+  or introducing new hardlink aliases after preflight. Do not run untrusted
+  external writers against the protected installation.
+- Handler-local Ruby variables and in-memory plugin state do not propagate back
+  to the UI. Persistent outputs and durable job state do. A handler that requires
+  process-local state across calls must not assume the old in-process evaluator.
+
+## Sandboxed swarm control
+
+`agent_spawn` and `agent_ask` handlers still run inside the mandatory worker.
+Their Swarm calls use a private socket to request only the controller's typed
+`spawn`/`ask` operations. The controller checks request tool permissions, rejects
+unknown fields/operations and traversal identifiers, and never invokes a
+worker-selected Registry handler, callback, Ruby expression, or filesystem path.
+Nested persona tools pass through Dispatch and get their own mandatory workers.
+
+Before launch the controller provisions the fixed swarm directory, persona file,
+and continuation lock with no-follow ancestry and regular-file/single-link
+checks. Workers cannot write the persona file, swarm subtree, or request
+checkpoint tree, nor rename their ancestors. No parent-directory write grant is
+added. Child Loop receipts remain controller-observed and are rechecked when
+merged into the parent. This preserves sandboxed spawn/ask state creation without
+allowing arbitrary controller callbacks.
+
+## Finite parent-writer audit
+
+The worker deny set now includes these controller-owned stores, even before a
+store exists. Missing paths still split the ancestor's Landlock grant, preventing
+first-write symlink planting. Existing inherited descriptors and hardlink aliases
+are covered by the same preflight as source. Store constants are resolved in the
+controller, not from model/tool output. Both lexical paths and canonical store
+aliases are denied, so a configured symlink cannot expose controller state
+through another otherwise writable directory.
+
+| Parent writer | Protected state |
+| --- | --- |
+| RequestRuntime checkpoints and EngagementMemory | Request-specific artifact root; checkpoint lock/temp/final persistence is also fd-relative/no-follow |
+| Sessions and SessionTrace | Sessions root, including support, leases, traces and requests |
+| Loop transcript compaction, ArtifactRegistry, swarm bus spills | Default artifacts root and configured ArtifactRegistry root |
+| Learning, Policy, Metrics, Reward, Mistakes, ToolGuard | Declared files/directories, learning and metrics subtrees; absent sibling staging paths cannot be planted |
+| Memory and MemoryIndex | Memory, archive and index files |
+| OpenGoal, Mission and TaskDAG | Goal file, missions and runs roots |
+| SkillReview and Curriculum | Ledger, curriculum/finetune roots, default/configured skill directories and loaded skill parents |
+| Provider credential persistence and local model configuration | Default vault/decryptor and configured driver paths |
+| Session redaction's Vault persistence | Engagements tree, legacy vault file and master-key path |
+| Log and Extrospection | Default logs and declared Extrospection stores |
+| Typed swarm controller | Swarm subtree, personas and continuation lock |
+
+The regression first reproduced an actual worker redirect of the transcript
+spill directory: after the worker returned, Loop created a file in synthetic
+protected source. It now receives permission denied, as does the earlier
+RequestRuntime spill reproducer. An independent fixture attempts 29 state
+mutations across existing directories/files and an absent staging path in both
+ordinary and symlinked-store layouts, while also creating a legitimate output in
+a disjoint workspace.
+
+Tools that directly mutate these controller stores are deliberately denied;
+only spawn/ask currently have the typed broker exception. This is not a promise
+that arbitrary in-process stateful plugins retain their old behavior. New parent
+writers or custom stores require an inventory update. The guarantee assumes a
+trusted initial controller layout and excludes concurrent external filesystem
+writers as described above; it is not a general host sandbox.
+
+## Completion evidence and uncertainty
+
+Required artifact names come from the original operator request (including
+explicit amendments), not cached model guesses or tool transcripts. Unquoted
+prose such as `i.e.` does not create a required file named `i.e`; explicitly
+quoted filenames are still honored.
+
+RequestRuntime snapshots required artifacts before dispatch and, on success,
+reads their stat, bounded head/tail and SHA-256 from the host. Successful actual
+file deltas count even if payload classification called the tool `eval` rather
+than `write`. Receipts accumulate across separate calls/iterations and survive
+transcript compaction. A failed tool, unchanged stale file, or tool stdout claim
+cannot create a receipt. Current bytes/identity must still match at completion.
+A combined write/read call does not require a ritual second call.
+
+Unknown side effects remain replay-fenced. A timeout/interruption or failed
+mutation is not erased by unrelated successful artifacts. On an attempted final
+answer the loop returns a structured `blocked` outcome with action ID and payload
+hash, instead of endlessly asking for rewrites. Exact-target operator-approved
+reconciliation is still required for genuine uncertainty; the existing HTTP
+reconciliation API is unchanged. Kernel/preflight failure before the handler
+starts is recorded as `rejected`, not falsely labeled an uncertain mutation.
+
+## Verification and deployment
+
+Offline specs exercise actual kernel workers, symlink/parent traversal denial,
+metadata denial, nested Dispatch, a detached Jobs worker, fail-closed unsupported
+protection/hardlinks, and the Loop → Dispatch → cumulative host receipt path with
+an actual generated PDF and separate text output. Provider messages in that
+replay are fixtures, not a live remote-model test.
+
+Source changes do not update an installed gem or a running pwn-ai process.
+Deploy the matching source/package files and restart the remote process through
+the operator's normal deployment procedure. Inspect the reported root/hardlink
+and kernel requirements before claiming that host is operational.

data/documentation/Transparent-Browser.md

@@ -52,5 +52,16 @@ All four honor `proxy:` (Burp / `tor`) so attribution stays controlled, reuse
 **one** browser handle across anchors, and `close` in an `ensure`. See
 [Extrospection](Extrospection.md) for the full loop.
 
+## Jev action loop
+
+`act` and `browser_act` run only when Open WebUI is configured and its model
+list contains a Jev model. Jev receives the visible control table and returns
+one operation plus one index: `CLICK`, `TYPE_TEXT`, `SELECT`, `SCROLL_UP`,
+`SCROLL_DOWN`, `WAIT`, `DONE`, or `BLOCKED`. It does not receive screenshots
+and it does not emit selectors. If the active pwn-ai model is not Jev, that
+model still writes the field text for `TYPE_TEXT`. Other pwn-ai work stays on
+the active model. This is the indexed-action idea from
+[jev-ultrafast](https://github.com/browser-use/jev-ultrafast), not TypeSafe's
+multi-head API and not a claim of its measured latency.
 
 [← Home](Home.md) · [BurpSuite](BurpSuite.md) · [WWW](WWW.md) · [Extrospection](Extrospection.md)

data/documentation/Troubleshooting.md

@@ -32,8 +32,9 @@ $ pwn setup --migrate --dry-run  # report only
 ```
 
 Corrupt / incompatible files are moved to `~/.pwn/quarantine/` (never
-deleted); a full timestamped backup is written to `~/.pwn/backup/<ts>/`
-first. Missing config keys added by the new release are deep-merged into
+deleted). Recovery copies go to one shared generation under `~/.pwn/backup/`
+first; the store keeps seven generations total. See
+[Backup Retention](Backup-Retention.md). Missing config keys added by the new release are deep-merged into
 your encrypted `~/.pwn/pwn.yaml` **under** your existing values. See
 [Installation § Upgrading](Installation.md#upgrading--pwn-state-migration-pwnmigrate).