pwn 0.5.783 → 0.5.785

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43f675e7e241c2f9c2ac2b96c52b43259b337871bc3227fb2cbac832457f7f23
-  data.tar.gz: c053c15cff377d88ee43b25103203928eaa037c3bca976fd6d6483d5543ad5fd
+  metadata.gz: fef74967cd315acf1e070378d8e12000d552604b8d0f273d42638014d0a13a8c
+  data.tar.gz: 3d68aa5c28678b95a4b20acbe878a36c6d0cd8c04357ee3d18c768a7e0435c75
 SHA512:
-  metadata.gz: eca4d79da6a33b24ec42cbc39c7c07afd0cfec053f98a49655b2bd6ef3c93bbba32f91aa90e755fe88eb8ec7bb13db892f87ade9e6b715b2d14f0b867415e576
-  data.tar.gz: 8c8dad0dd07d97a0b4941fadf03683dd14cfe7fe045c06431d7f725c39ea4dadaac76988a722efaa9186abe71fa4ba731b95c8ae0fa58b1efd0d7baa367f45b1
+  metadata.gz: '0871b196e754cfe2134ba0372f4108b24113d9a1f7b0355257b31a032833c4b91bd1e52f53ff467a4e9e817375b9138b5691c15ef621c6026a34d32672f77d2b'
+  data.tar.gz: 2fef6064addee1ba16706d641f19af7a8bbf99432dfb1a13426fbd1d534d01b89d4a7f4dced9db9ad934d30db94dfcf908e88c993cb779424b706a0296db1cd2

data/.ruby-version

@@ -1 +1 @@
-4.0.6
+4.0.9

data/Gemfile

@@ -22,7 +22,7 @@ gem 'brakeman', '8.1.0'
 gem 'bson', '5.2.0'
 gem 'bundler', '>=4.0.23'
 gem 'bundler-audit', '>=0.9.3'
-gem 'bunny', '3.4.0'
+gem 'bunny', '3.5.0'
 gem 'colorize', '1.1.0'
 gem 'credit_card_validations', '10.0.0'
 gem 'curses', '1.7.0'
@@ -49,8 +49,8 @@ gem 'jwt', '3.3.0'
 gem 'libusb', '0.8.0'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
-gem 'mcp', '1.8.1'
-gem 'meshtastic', '0.0.189'
+gem 'mcp', '1.9.0'
+gem 'meshtastic', '0.0.192'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.26.0'
 gem 'msfrpc-client', '1.1.2'
@@ -59,7 +59,7 @@ gem 'net-ldap', '0.21.0'
 gem 'net-openvpn', '0.8.7'
 gem 'net-smtp', '0.5.2'
 gem 'nexpose', '7.3.0'
-gem 'nokogiri', '1.19.4'
+gem 'nokogiri', '1.19.7'
 gem 'nokogiri-diff', '0.3.0'
 gem 'oily_png', '1.2.1'
 gem 'open3', '0.3.0'
@@ -81,7 +81,7 @@ gem 'rmagick', '7.2.0'
 gem 'rqrcode', '3.2.0'
 gem 'rspec', '3.13.2'
 gem 'rtesseract', '3.1.4'
-gem 'rubocop', '1.92.1'
+gem 'rubocop', '1.92.2'
 gem 'rubocop-rake', '0.7.1'
 gem 'rubocop-rspec', '3.10.2'
 gem 'ruby-audio', '1.6.1'
@@ -89,12 +89,12 @@ gem 'ruby-nmap', '1.0.3'
 gem 'ruby-saml', '1.18.1'
 gem 'rvm', '1.11.3.9'
 gem 'savon', '2.17.5'
-gem 'selenium-devtools', '0.155.0'
-gem 'selenium-webdriver', '4.51.0'
+gem 'selenium-devtools', '0.156.0'
+gem 'selenium-webdriver', '4.52.0'
 gem 'slack-ruby-client', '3.3.0'
 gem 'socksify', '1.8.1'
 gem 'spreadsheet', '1.3.5'
-gem 'sqlite3', '2.10.1'
+gem 'sqlite3', '2.10.2'
 gem 'thin', '2.0.1'
 gem 'tty-prompt', '0.23.1'
 gem 'tty-spinner', '0.9.3'

data/README.md

@@ -9,6 +9,7 @@
 - [Intro](#intro)
   * [What is PWN](#what-is-pwn)
   * [Why PWN](#why-pwn)
+    * [Vault and Sandboxing](#vault-and-sandboxing)
   * [How PWN Works](#how-pwn-works)
 - [Documentation](#documentation)
 - [Installation](#installation)
@@ -88,6 +89,42 @@ is driving security decisions without you watching every click.
 
 Full page: [Why PWN](documentation/Why-PWN.md)
 
+##### **Vault and Sandboxing** #####
+
+Agentic security research, bug bounty hunting and penetration testing put
+credentials, client evidence and untrusted target content in the same tool loop.
+Vault and sandboxing reduce accidental secret persistence and limit local damage
+from untrusted PoCs or target-supplied prompt injection:
+
+- **Keep secrets separate from the conversation.** [Vault](lib/pwn/plugins/vault.rb)
+  encrypts configuration and captured credential values at rest. Use
+  `{{vault:label}}` references: [Dispatch](lib/pwn/ai/agent/dispatch.rb) resolves
+  them at the tool boundary and redacts known stored secrets from returned results.
+  Together with transcript/log redaction, this reduces copying raw secrets into
+  prompts, logs and reusable context. Store/query loot under explicit engagement
+  IDs with host/service/finding provenance. Use unique labels: reference expansion
+  can search across engagements, so these IDs are not credential access controls.
+- **Contain tool effects, not just model instructions.** The
+  [mandatory runtime boundary](documentation/Runtime-Source-Protection.md) uses
+  Linux workers to separate tool writes from protected source and controller state;
+  [mission containment](documentation/Mission-Cancellation.md) owns their descendants.
+  Unnamed writes default to `~/.pwn/workspaces/runtime`. Other destinations must
+  come from the original operator request, not tool output; naming a file can
+  grant its parent directory. Protected source stays read-only even if named.
+  Missing required Landlock/seccomp or namespace support makes execution fail closed.
+  Optional `strict`/`permissive`/`off` profiles do not disable that mandatory boundary.
+
+**Know the limits.** Encryption at rest does not protect secrets from an active
+process that has unlocked them or promise LLM-provider privacy. Vault is not
+whole-filesystem or evidence/artifact encryption, and redaction can miss secrets.
+Sandboxing is not authorization, complete network isolation, a perfect container,
+or a guarantee against bugs or prompt injection. Operators still need target
+authorization and scope, least-privilege credentials, and separate evidence access,
+retention and encryption controls.
+
+Details: [Configuration](documentation/Configuration.md) ·
+[Optional hardware-backed vaults and recovery](documentation/YubiKey-Vaults.md)
+
 #### **How PWN Works** ####
 
 PWN is five layers. Dependencies only point downward, so each level stays

data/Rakefile

@@ -5,12 +5,30 @@
 exec('bundle', 'exec', 'rake', *ARGV) unless ENV['BUNDLE_BIN_PATH'] || ENV['RUBYOPT'].to_s.include?('bundler/setup')
 
 require 'bundler/setup'
+require 'English'
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rdoc/task'
 require 'rubocop/rake_task'
 
-RSpec::Core::RakeTask.new(:spec)
+# RSpec's stock task maps a signalled child to exit 1 without naming the
+# signal. Preserve that evidence when an interrupted run has no summary.
+class DiagnosticSpecTask < RSpec::Core::RakeTask
+  def run_task(verbose)
+    super
+  rescue SystemExit
+    status = $CHILD_STATUS
+    if status
+      result = status.signaled? ? "signal=#{Signal.signame(status.termsig)}" : "exit=#{status.exitstatus}"
+      warn "RSpec child failed: #{result}"
+    end
+    raise
+  end
+end
+
+DiagnosticSpecTask.new(:spec) do |task|
+  task.rspec_opts = "#{task.rspec_opts} --require ./spec/support/gate_failure_formatter.rb --format progress --format GateFailureFormatter"
+end
 task :silence_rspec_filter_banner do
   ENV['PWN_RAKE_SPEC'] = '1'
 end

data/bin/pwn

@@ -81,7 +81,8 @@ begin
       warn result.to_s[0, 700]
     end
 
-    final = PWN::AI::Agent::Loop.run(
+    require 'pwn/plugins/repl/ai'
+    final = PWN::Plugins::REPL.pwn_ai_run_steerable(
       request: prompt,
       session_id: sess[:id],
       enabled_toolsets: PWN::Env.dig(:ai, :agent, :toolsets),

data/bin/pwn_setup

@@ -58,7 +58,7 @@ pwn_driver = PWN::Driver::Parser.new do |options|
   end
 
   options.on('--[no-]cron',
-             '<Optional - Enable (default) or disable OS-native persistence of pwn-ai cron jobs>') do |o|
+             '<Optional - Enable (default) or disable the built-in pwn-ai cron worker; no OS scheduler changes>') do |o|
     opts[:cron] = o
   end
 end

data/bin/pwn_web_cache_deception

@@ -33,6 +33,18 @@ PWN::Driver::Parser.new do |options|
     opts[:mfa] = f
   end
 
+  options.on('--yubikey-account=NAME', '<Optional - Exact OATH account; supports GitHub, Synack, Twitter, BugCrowd, CoinbasePro, AppCobaltIO; Paypal SMS adapter unsupported; requires --yubikey-confirm; enables MFA even with --no-mfa; never an OTP slot>') do |name|
+    opts[:yubikey_account] = name
+  end
+
+  options.on('--yubikey-confirm', '<Required with --yubikey-account - Explicit OATH consent: HOTP advances counters; ykman may authenticate/delete remembered keys and delete corrupted OATH credentials>') do |confirm|
+    opts[:yubikey_confirm] = confirm
+  end
+
+  options.on('--yubikey-serial=SERIAL', '<Optional - Decimal YubiKey serial; requires --yubikey-account>') do |serial|
+    opts[:yubikey_serial] = serial
+  end
+
   options.on('-pPROXY', '--proxy=PROXY', '<Optional - HTTP or Socks Proxy || tor>') do |p|
     opts[:proxy] = p
   end
@@ -60,6 +72,24 @@ pwn_www_mod_str = opts[:pwn_www_mod_str].to_s.scrub.strip.chomp
 
 username = opts[:username].to_s.scrub.strip.chomp
 
+yubikey = nil
+raise ArgumentError, 'YubiKey serial requires --yubikey-account with an exact OATH account name' if opts[:yubikey_account].nil? && !opts[:yubikey_serial].nil?
+raise ArgumentError, '--yubikey-confirm requires --yubikey-account with an exact OATH account name' if opts[:yubikey_account].nil? && !opts[:yubikey_confirm].nil?
+
+unless opts[:yubikey_account].nil?
+  supported_oath_modules = %w[GitHub Synack Twitter BugCrowd CoinbasePro AppCobaltIO]
+  raise ArgumentError, "YubiKey OATH is supported only with --pwn-www-mod=#{supported_oath_modules.join('|')}; the Paypal adapter is SMS-only" unless supported_oath_modules.include?(pwn_www_mod_str)
+
+  yubikey = { account: opts[:yubikey_account], confirm: opts[:yubikey_confirm] }
+  unless opts[:yubikey_serial].nil?
+    serial = opts[:yubikey_serial]
+    raise ArgumentError, 'YubiKey serial must be a decimal string without whitespace' unless serial.is_a?(String) && serial.match?(/\A[0-9]+\z/)
+
+    yubikey[:serial] = serial
+  end
+  PWN::Plugins::AuthenticationHelper.validate_mfa_options(yubikey: yubikey, mfa: opts[:mfa], mfa_token: opts[:mfa_token])
+end
+
 password = opts[:password] # Don't cast to string to detect if PWN::Plugins::AuthenticationHelper is necessary
 if password.nil?
   password = PWN::Plugins::AuthenticationHelper.mask_password
@@ -67,11 +97,7 @@ else
   password = opts[:password].to_s.scrub.strip.chomp
 end
 
-if opts[:mfa]
-  mfa = true
-else
-  mfa = false
-end
+mfa = opts[:mfa] || false
 
 proxy = opts[:proxy].to_s.scrub.strip.chomp unless opts[:proxy].nil?
 
@@ -151,12 +177,14 @@ begin
       browser_obj = pwn_www_mod.open(browser_type: :chrome)
     end
     # Now AuthN via PWN::WWW::<MODULE>
-    browser_obj = pwn_www_mod.login(
+    login_opts = {
       browser_obj: browser_obj,
       username: username,
       password: password,
       mfa: mfa
-    )
+    }
+    login_opts[:yubikey] = yubikey unless yubikey.nil?
+    browser_obj = pwn_www_mod.login(login_opts)
     puts "#{@green}complete.#{@end_of_color}\n\n\n"
   elsif pwn_www_mod_str == '' && proxy
     browser_obj = PWN::Plugins::TransparentBrowser.open(

data/build_gem.sh

@@ -44,7 +44,7 @@ if [[ $old_ruby_version == $new_ruby_version ]]; then
   export rvmsudo_secure_path=1
   rvmsudo /bin/bash --login -c "cd ${pwn_root} && ./reinstall_gemset.sh"
   cd /tmp && cd "$pwn_root"
-  rvmsudo /bin/bash --login -c "cd ${pwn_root} && bundle exec rake"
+  ruby "${pwn_root}/scripts/build_gate.rb" rvmsudo /bin/bash --login -c "cd ${pwn_root} && bundle exec rake"
   rvmsudo /bin/bash --login -c "cd ${pwn_root} && bundle exec rake install"
   rvmsudo /bin/bash --login -c "cd ${pwn_root} && bundle exec rake rerdoc"
   echo "Invoking bundle-audit Gemfile Scanner..."

data/documentation/AI-Integration.md

@@ -15,7 +15,7 @@ agent code never cares which model is behind it.
 | `grok` | `PWN::AI::Grok` | `key:` **or** `oauth: true` | OAuth = RFC-8628 device-code flow using xAI's public Grok-CLI client id (no secret) - see skill `xai_grok_oauth_device_flow` |
 | `gemini` | `PWN::AI::Gemini` | `key:` | function-calling native |
 | `ollama` | `PWN::AI::Ollama` | none (stock) | Direct Ollama server (default `http://127.0.0.1:11434`). Native `/api/chat` (`num_ctx`, `num_predict`, `keep_alive`, low `tool_temp`) and `/api/embed` for `PWN::MemoryIndex`. No prefix-cache field. |
-| `openwebui` | `PWN::AI::OpenWebUI` | `key:` (JWT / API token) + `base_uri:` | Open WebUI gateway - OpenAI-compatible `/api/v1/chat/completions` plus proxied Ollama `/ollama/api/*` (including embed) |
+| `openwebui` | `PWN::AI::OpenWebUI` | `key:` (JWT / API token) + `base_uri:` | Open WebUI gateway - OpenAI-compatible `/api/v1/chat/completions` plus proxied Ollama `/ollama/api/*`. Workspace tools such as Ask Jev run server-side through `tool_ids` on `chat` / `workspace_tool`. A client `tools` array on that same request disables them. |
 
 > PWN is **model-agnostic**. `ai.<engine>.model` is passed straight through to
 choose a provider-supported model ID (or a tag from `ollama list`).
@@ -56,12 +56,14 @@ The trailing `nil` prevents the console from echoing the returned bearer.
 Successful enrollment updates the live environment and calls the private
 `persist_oauth_to_vault` helper, as token refresh does. It uses the configured
 `driver_opts.pwn_env_path` and `pwn_dec_path`, defaulting to
-`~/.pwn/pwn.yaml` and its `.decryptor` file. Existing decryption artifacts are
-required; missing artifacts leave tokens in the session only and produce a
+`~/.pwn/pwn.yaml` and its legacy `.decryptor` file. A [YubiKey vault](YubiKey-Vaults.md)
+uses its hardware selector instead and does not need a software sidecar.
+Unavailable credentials or hardware leave tokens in the session only and produce a
 notice. Tokens are not printed by the enrollment success message.
 
-Persistence retains unrelated settings and the existing key/IV, encrypts a
-private temporary file, and replaces the vault only after encryption succeeds.
+Persistence retains unrelated settings and the encryption backend, decrypts and
+merges in memory, writes only ciphertext to a private temporary file, and
+replaces the vault only after encryption succeeds.
 The resulting vault has mode `0600`. The original vault remains unchanged on
 a persistence failure; the helper does not create or rotate decryptor secrets.
 

data/documentation/Agent-Tool-Registry.md

@@ -6,13 +6,13 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 
 ![Tool registry](diagrams/agent-tool-registry.svg)
 
-## Toolsets to tools  (16 toolsets · 150 tools)
+## Toolsets to tools  (16 toolsets · 152 tools)
 
 | 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` | `pty_expect` · `job_run` · `job_status` · `job_result` · `job_tail` · `job_kill` · `pty_open` · `pty_send` · `pty_read` · `pty_close` · `pty_session` · `shell` | Foreground host commands plus `PWN::Plugins::Jobs` durable supervisors |
-| `pwn` | `binary_triage` · `browser_goto` · `capabilities` · `debug_session` · `gdb_run_to_crash` · `binary_diff` · `crash_triage` · `emulate` · `detonate` · `decompile` · `exploitdev` · `finding_record` · `finding_report` · `chain_score` · `fuzz_campaign` · `intel_lookup` · `loot_query` · `nmap_scan` · `nuclei_scan` · `r2_functions` · `r2_disasm` · `recon_run` · `pwn_eval` · `sandbox_run` · `sandbox_fuzz` · `sbom_scan` · `swarm_map` | `TOPLEVEL_BINDING.eval` in the live REPL process, after `ToolGuard`; SBOM engines via `PWN::Plugins::SBOM` store CVE leads as recon observations, not findings; r2pipe JSON via `PWN::Plugins::Radare2`; gdb MI3 crash reports via `PWN::Plugins::GDBMI`; nmap XML ingest/diff via `PWN::Plugins::NmapIt`, which skips a known port unless `refresh: true`; nuclei/httpx JSONL via `PWN::Plugins::Nuclei` writes a recon observation (a template match is not a finding) and accepts a `Recon.handoff` record; TransparentBrowser navigation captures screenshot/DOM/HAR via `browser_goto`; engagement loot via `PWN::Plugins::Vault` |
+| `pwn` | `binary_triage` · `browser_goto` · `browser_act` · `workspace_tool` · `capabilities` · `debug_session` · `gdb_run_to_crash` · `binary_diff` · `crash_triage` · `emulate` · `detonate` · `decompile` · `exploitdev` · `finding_record` · `finding_report` · `chain_score` · `fuzz_campaign` · `intel_lookup` · `loot_query` · `nmap_scan` · `nuclei_scan` · `r2_functions` · `r2_disasm` · `recon_run` · `pwn_eval` · `sandbox_run` · `sandbox_fuzz` · `sbom_scan` · `swarm_map` | `TOPLEVEL_BINDING.eval` in the live REPL process, after `ToolGuard`; SBOM engines via `PWN::Plugins::SBOM` store CVE leads as recon observations, not findings; r2pipe JSON via `PWN::Plugins::Radare2`; gdb MI3 crash reports via `PWN::Plugins::GDBMI`; nmap XML ingest/diff via `PWN::Plugins::NmapIt`, which skips a known port unless `refresh: true`; nuclei/httpx JSONL via `PWN::Plugins::Nuclei` writes a recon observation (a template match is not a finding) and accepts a `Recon.handoff` record; TransparentBrowser navigation captures screenshot/DOM/HAR via `browser_goto`; engagement loot via `PWN::Plugins::Vault` |
 | `mcp` | `mcp` | `PWN::AI::MCP` session broker → any `PWN::AI::MCP::*` stdio client |
 | `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` · `memory_lean` | `PWN::Memory` → `~/.pwn/memory.json` |
 | `skills` | `skills_recall` · `skills_update` · `skill_list` · `skill_view` · `skill_create` · `skills_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` · `skills_consolidate` | `~/.pwn/skills/<name>/SKILL.md` (**[agentskills.io](https://agentskills.io) spec**; legacy flat `*.md` auto-migrated) |

data/documentation/Backup-Retention.md

@@ -0,0 +1,82 @@
+# Shared recovery backup retention
+
+All PWN-owned recovery producers use `PWN::Backups` and the single
+`~/.pwn/backup` store. The limit is **seven total generation folders**, not seven
+per producer. Producer payloads and recovery receipts are grouped inside their
+transaction's generation. No new adjacent learning, preference, skill or
+Terminator `.bak` / `.pwnbak` files are produced.
+
+## Producers
+
+| Producer | Contents |
+| --- | --- |
+| Migrate | Exact registry-owned state paths, encrypted configuration and decryptor; verified snapshot manifest; no recursive logs/cache/backup copies |
+| Learning | Learning rewrites and original evidence-migration index |
+| Reward | Preference rewrite recovery |
+| SkillReview / SkillConsolidation | Original skill bytes |
+| PolicyEvaluation | Pinned routing-policy rollback snapshot |
+| Setup | Original Terminator configuration |
+| SessionCleanup | Session/layout recovery, dependency removal, continuation retirement and disposable quarantine payloads with their recovery receipts |
+
+Immutable learning evidence, artifacts, evaluation inputs and user-requested
+exports are not disposable backup generations. Device read/write backup commands,
+GitHub gist exports and Jenkins-to-S3 transfer operate on operator-selected data,
+not PWN's internal recovery state.
+
+## Admission, locking and failures
+
+The permanent `.retention.lock` serializes cooperating producers. Maintenance
+acquires its maintenance lock, then the Learning writer lock, then the backup
+lock. Ordinary backup producers acquire Learning before backups and never acquire
+maintenance. Learning reentrancy is bound to the owning PID and thread; an
+attempt to acquire Learning underneath an unowned backup transaction is rejected.
+Maintenance still defers when the Learning writer is busy.
+
+Before a new folder is admitted, oldest completed, unpinned generations may be
+expired to make room. Prepared/interrupted generations, explicit pins and current
+literal evidence references remain protected. Malformed reference data fails
+closed when expiry would be needed. Pins count **inside** the seven-folder limit:
+if they occupy capacity, the next producer fails before modifying its source.
+Unknown legacy folders count toward capacity but are not silently certified or
+expired. A pre-existing over-limit store can therefore block admission until an
+explicit offline remediation is performed; importing this source does not fix a
+live store or grant permission to prune it.
+
+Transactions publish `prepared` before payload/source changes and `complete`
+only after successful return. Exceptions, interrupted/blocked results and failed
+receipts leave prepared recovery. Copies are hash-verified and fsynced. Keep the
+transaction open through source mutation and receipt publication. Restoring one
+store does not undo all children of a maintenance operation.
+
+Use the owning store's recovery API (`SessionCleanup.recover`,
+`Learning.rollback_evidence`, skill review rollback or policy rollback) first.
+`Backups.reconcile` only acknowledges recovery: it requires the exact generation,
+its inspected manifest SHA-256 and explicit confirmation. It retains a pin by
+default; `pinned: false` permits normal retention but does not override live
+references. It does not restore payloads or declare a failed operation successful.
+Never edit shared/hardlinked historical payloads in place; restore by copying.
+
+## Upgrade and legacy relocation
+
+Schema 12 changes the existing retention policy from three to seven, preserving
+pins and other policy fields. A second migration is byte-stable. The old
+`Migrate.prune_backups` entry point is a compatibility report only; it cannot run
+an independent three-generation pruning policy. Retention happens at producer
+admission, not via another scheduler.
+
+`Backups.relocate_legacy(paths: ..., dry_run: true)` previews exact recognized
+legacy paths. Applying requires `dry_run: false, writers_stopped: true`, owned
+non-symlink sources, unchanged verified copies and no references to their old
+paths. The shared generation contains an origin mapping before originals are
+removed. Unknown, referenced or over-capacity inputs must be resolved explicitly,
+not bypassed. Existing cleanup recovery readers remain available for legacy
+ledgers. Legacy diagnostic/cache expiry is a separate explicit operation and is
+not a new backup producer.
+
+## Deployment boundary
+
+Source changes do not upgrade installed gems, existing clients or immutable cron
+releases. Deploy a matched release and restart only explicitly authorized
+processes separately. Use only PWN's existing internal cron worker; no systemd,
+native scheduler, live provider calls or live backup pruning is required for
+fixture verification. Tests must use an isolated HOME and scratch storage.

data/documentation/Configuration.md

@@ -5,18 +5,22 @@ Provider and plugin configuration lives in **one encrypted YAML file**, loaded b
 constant **`PWN::Env`** (whose nested settings are mutable) (a redacted copy is available as
 `PWN::EnvRedacted`).
 
-The file is **AES-encrypted at rest** by `PWN::Plugins::Vault`. Its key/IV
-live in a sibling **`~/.pwn/pwn.yaml.decryptor`** file (or in
-`PWN_DECRYPTOR_KEY` / `PWN_DECRYPTOR_IV` env vars). Never edit `pwn.yaml`
-by hand - use the **`pwn-vault`** REPL command, which decrypts, opens
-`$EDITOR`, re-encrypts, and reloads `PWN::Env`. If `PWN::Config` rejects the
+The file is **AES-encrypted at rest** by `PWN::Plugins::Vault`. Legacy CBC key/IV
+values live in a sibling **`~/.pwn/pwn.yaml.decryptor`** file (or in
+`PWN_DECRYPTOR_KEY` / `PWN_DECRYPTOR_IV` env vars). Explicitly selected
+[YubiKey vaults](YubiKey-Vaults.md) instead use an authenticated hardware-derived
+AES-GCM envelope and need no software decryptor. Never edit ciphertext by hand;
+use the **`pwn-vault`** REPL command, which edits a private temporary copy,
+re-encrypts before replacing the original, and reloads `PWN::Env`. If `PWN::Config` rejects the
 edited file, the editor reopens until the vault loads cleanly, so you do not
 leave the REPL stuck on a decrypt / re-edit / encrypt loop.
 
 If `~/.pwn/pwn.yaml` does not exist on first run, `PWN::Config.default_env`
 writes a fully-commented template with every key below (values set to
 `'optional - ...'` / `'required - ...'` placeholder strings), encrypts it, and
-generates the decryptor.
+generates the legacy decryptor. `default_env(yubikey: { slot: 2 })` explicitly
+selects hardware protection for a new vault and omits that sidecar; it does not
+provision the device slot or silently convert an existing file.
 
 > **Before configuring**, run `pwn setup` - the
 > [doctor](Installation.md#pwn-setup--the-post-install-doctor--provisioner)

data/documentation/Contributing.md

@@ -6,7 +6,7 @@
 lib/pwn/                # all namespaces
 lib/pwn/setup.rb        # PWN::Setup - doctor/provisioner data tables
 lib/pwn/migrate.rb      # PWN::Migrate - ~/.pwn state doctor / auto-migrator
-lib/pwn/plugins/        # 107 top-level plugin autoloads
+lib/pwn/plugins/        # 108 top-level plugin autoloads
 lib/pwn/ai/agent/       # agent core
 lib/pwn/ai/agent/tools/ # LLM tool registrations
 bin/                    # 56 executables: 53 pwn_* drivers + pwn / pwn-ai / pwn-capd (incl. pwn_setup)

data/documentation/Cron.md

@@ -2,17 +2,26 @@
 
 `PWN::Cron` (`lib/pwn/cron.rb`) stores job definitions in
 `~/.pwn/cron/jobs.yml`. `pwn setup` starts (or reuses) a background cron
-worker and installs an OS-native keep-alive so YAML jobs fire on schedule
-without a per-job crontab line:
-
-- Linux: `systemd --user` (Restart=always), else `crontab @reboot`
-- macOS: `launchd`
-- Windows: `schtasks`
-- otherwise: `crontab @reboot` when `crontab(1)` exists
-
-You can still pass `install_crontab: true` on `cron_create` to add a
-per-job system line. `PWN::Cron.install_worker_crontab` is idempotent and
-does not remove existing per-job lines.
+worker. Setup, migration and startup only seed internal job definitions;
+they never install, start, repair or remove native scheduler units. After a
+reboot, start/reuse the portable worker with `pwn setup --cron`; automatic
+jobs require that worker, while manual commands do not. `--no-cron` disables
+the internal worker without changing host services.
+
+**Housekeeping must never use systemd or another native scheduler.**
+The one enabled housekeeping default, `session_cleanup`, uses only this existing
+worker or a manual command. `install_native_job` and each platform-specific job
+installer explicitly skip housekeeping (`housekeeping_internal_only`),
+including recognizable cleanup payloads under another name. Native worker
+contexts exclude housekeeping from ticks and direct job execution.
+
+Generic scheduler APIs remain for unrelated custom jobs: `install_crontab:
+true` can still add their per-job system lines. They are not called by setup,
+migration or default seeding. Existing housekeeping units/drop-ins are left
+untouched and require explicit operator approval for removal; they are never
+re-enabled automatically. See [Installation](Installation.md) for the legacy
+service migration boundary. Do not create another worker or run cleanup just
+to validate scheduling.
 
 ![Cron scheduling](diagrams/cron-scheduling.svg)
 
@@ -34,33 +43,53 @@ does not remove existing per-job lines.
 | `cron_enable` / `cron_disable` | Toggle without deleting |
 | `cron_remove` | Delete from `jobs.yml` (does **not** scrub crontab - `crontab -e` yourself) |
 
-## Seeded self-improvement jobs (`PWN::Cron.install_defaults`)
-
-`pwn setup --migrate` and first-launch default installation seed six jobs into a fresh
-`~/.pwn/cron/jobs.yml` via `PWN::Cron.install_defaults`:
-
-| Name | Schedule | Enabled | Ruby |
-|---|---|---|---|
-| `curriculum_practice_nightly` | `0 3 * * *` | **no** | `Curriculum.practice(limit: 3)` - opt-in; runs `Loop.run` with real tools |
-| `curriculum_offline_judge` | `30 3 * * *` | **no** | `Curriculum.offline_judge(...)` - opt-in; spends API tokens |
-| `curriculum_train_weekly` | `0 4 * * 0` | **no** | `Curriculum.train_and_gate(dry_run: true)` - opt-in; needs trainer+GPU to actually train |
-| `session_cleanup` | `45 3 * * *` | **yes** | Guarded unsummarized-session cleanup with backups, dependency checks and activity leases; see [Installation](Installation.md) |
-| `learning_consolidate_nightly` | `0 5 * * *` | **yes** | `Learning.consolidate` - memory GC |
-| `pwn_stores_lean_nightly` | `15 5 * * *` | **yes** | `Learning.gc_stores!` - lean memory, learning.jsonl, mistakes, policy, sessions |
+## Default housekeeping and explicit curriculum opt-in
+
+`PWN::Cron.install_defaults` seeds **one** enabled job on a fresh install:
+`session_cleanup`, daily at `45 3 * * *`, guarded until its first scheduled slot.
+It calls `SessionCleanup.coordinate` through the existing internal worker:
+
+1. Shared maintenance: preflight, evidence migration, protected-session cleanup,
+   and disposable storage maintenance.
+2. Memory consolidation (`Learning.consolidate`, including Memory lean).
+3. Learning outcome retention (`Learning.prune_outcomes!`).
+4. Mistakes retention (`Mistakes.lean!`).
+5. Policy trajectory retention (`Policy.lean!`).
+
+The coordinator holds the permanent maintenance lock across these phases and
+records their separate results. Blocked/incomplete maintenance skips retention;
+dry-run does not consolidate memory or mutate stores. Store writer locks and
+existing gold/recent/protected-entry policies remain in force. It does not call
+`gc_stores!`, which would repeat memory consolidation and session cleanup.
+
+Existing jobs are preserved verbatim, including disabled/custom schedules and
+legacy curriculum aliases. Existing `learning_consolidate_nightly` and
+`pwn_stores_lean_nightly` are **not** removed automatically. If either exists
+when a missing session job is seeded, that job uses maintenance-only payloads
+rather than duplicate retention. Consolidate those live schedules only after
+all writers and the matched helper have been safely upgraded and tested.
+
+Curriculum schedules are **not seeded at all**, including after deletion,
+startup, or repeat migration. `CURRICULUM_JOBS` contains optional templates for
+`curriculum_practice_nightly`, `curriculum_train_weekly`, and
+`curriculum_offline_judge`. Explicitly create a selected template only when
+wanted; templates default disabled:
 
-- **practice / judge / train** ship **disabled**. Practice self-plays via `Loop.run` (shell, browsers). Judge hits the live model. Train is a no-op without a LoRA trainer. Enable with `cron_enable` when you want that loop.
-- **consolidate + lean + session cleanup** stay on: they operate on local `~/.pwn` state; cleanup can delete eligible transcripts after verified backups and guards, so the injected MEMORY / LEARNING / session tail stays high-signal.
-
-- **practice** - top unresolved `Mistakes` under `Reward.judge`; auto-`resolve` with ≥2 holdouts
-- **offline_judge** - backfill outcome/process labels + plan calibration from PLAN `p(success)=` so `:failure_only` local introspect does not starve the corpus; also runs `Reward.warm_sentinel` so the reward-sentinel window can fill on local hosts
-- **dedupe** - legacy alias `offline_judge_nightly` counts as the same job; `install_defaults` will not double-seed `30 3 * * *` and disables the alias when both exist
-- **train** - export SFT + balanced DPO, LoRA-train `pwn-vN+1`, replay Mistakes.top, promote only on win. `dry_run: false` only with a trainer+GPU
-- **consolidate** - memory GC (semantic merge + importance eviction) so the injected MEMORY block stays high-signal
+```ruby
+spec = PWN::Cron::CURRICULUM_JOBS.find { |job| job[:name] == 'curriculum_practice_nightly' }
+PWN::Cron.create(spec.merge(enabled: false, sync_native: false))
+```
 
-See [Reinforcement Learning](Reinforcement-Learning.md).
+Practice runs real tools, judge can spend provider tokens, and training needs
+its own explicit configuration/approval. See [Reinforcement Learning](Reinforcement-Learning.md).
 
-`cron_disable(id:)` turns either off; `install_defaults` is idempotent (including legacy alias collapse) and
-never overwrites a job you already have with the same name.
+For schedule-only deletion without touching native schedulers, use
+`PWN::Cron.remove(id: exact_id, sync_native: false)`. It preserves job logs and
+other evidence. Registry writes use a permanent lock and atomic replacement;
+completion updates merge into the current registry and never resurrect a deleted
+job. Old workers without this protocol must drain safely before a registry edit;
+never use a forced stop while a job is writing. A current worker reloads the
+registry each tick; ordinary schedule changes need no restart.
 
 ## Example
 

data/documentation/Diagrams.md

@@ -24,7 +24,7 @@ a dependency guarantee. External services/radios require separate live verificat
 [source](diagrams/dot/persistence-filesystem.dot) · doc: [Persistence](Persistence.md)
 ![persistence-filesystem](diagrams/persistence-filesystem.svg)
 
-### Plugin Ecosystem (107 modules)
+### Plugin Ecosystem (108 modules)
 [source](diagrams/dot/plugin-ecosystem.dot) · doc: [Plugins](Plugins.md)
 ![plugin-ecosystem](diagrams/plugin-ecosystem.svg)
 
@@ -69,7 +69,7 @@ a dependency guarantee. External services/radios require separate live verificat
 [source](diagrams/dot/ai-integration-tool-calling.dot) · doc: [AI Integration](AI-Integration.md)
 ![ai-integration-tool-calling](diagrams/ai-integration-tool-calling.svg)
 
-### Agent Tool Registry (16 toolsets · 150 tools)
+### Agent Tool Registry (16 toolsets · 152 tools)
 [source](diagrams/dot/agent-tool-registry.dot) · doc: [Agent Tool Registry](Agent-Tool-Registry.md)
 ![agent-tool-registry](diagrams/agent-tool-registry.svg)
 

data/documentation/General-PWN-Usage.md

@@ -18,13 +18,14 @@ $ pwn setup --migrate --fix   # after `gem update pwn`: verify + autofix ~/.pwn
 ```
 
 See [Installation](Installation.md) for every flag and the
-`PWN::Setup` / `PWN::Migrate` API.
+`PWN::Setup` / `PWN::Migrate` API. Unspecified `pwn-ai` writes use
+`~/.pwn/workspaces/runtime`; see [Operability](Operability.md).
 
 ## Inside the REPL
 
 ```ruby
 PWN.help                            # top-level help
-PWN::Plugins.constants.sort         # list all 107 plugins
+PWN::Plugins.constants.sort         # list all 108 plugins
 PWN::Plugins::NmapIt.help           # per-plugin usage
 PWN::Setup.check                    # capability doctor from inside the REPL
 PWN::Migrate.status                 # ~/.pwn state-file compatibility rows
@@ -40,7 +41,7 @@ history                             # what you've typed → copy into a driver
 | `pwn-ai` | Enter the agent TUI (SHIFT+ENTER = newline, ENTER = submit) |
 | `pwn-asm` | Multi-line assembly ↔ opcode workbench |
 | `pwn-mesh` | Meshtastic serial / bluetooth / TCP / MQTT client (Ruby ≥ 4.0) |
-| `pwn-vault` | Decrypt → edit `~/.pwn/pwn.yaml` in `$EDITOR` → re-encrypt |
+| `pwn-vault` | Edit a private temporary copy, then replace `~/.pwn/pwn.yaml` only after encryption succeeds (legacy or YubiKey) |
 | `pwn-ai-memory` | Inspect / edit `~/.pwn/memory.json` |
 | `pwn-ai-sessions` | List / view / delete transcripts |
 | `pwn-ai-cron` | List / run scheduled jobs |