pwn 0.5.635 → 0.5.636

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 347b9c864507e706e465e27933acee3d03b8fca35529e3c63bfb374a50763061
-  data.tar.gz: 98764623bb85939b3dc681c1703ad4f5e50bc9450caef5773c39855b3b4b469e
+  metadata.gz: 41a8a5c5d750508d4f3904d7a05151719e2c86fa4cf20001a3aab0985910963d
+  data.tar.gz: 7af0757b53bdfa6c97d86a9415a2cbf41ca9447b3f9e438b95b2424f5d835cbf
 SHA512:
-  metadata.gz: 3fe90d0d5abb8876bcb55d3be503725f7819426b2b42ea1e10c756c3c7c3f4d4060bace652e8617ba5d74af1078dab2d6250c5c5c57e0a3ca52eaf3a9410492b
-  data.tar.gz: d778fc2e42b1276b2731546fc84f893bf7174f903d8c3880a75c1930509d3a4e55e387e0c38ed61cfb43ad19e9e9e824c0f336b6e559d409d8fd6604da00ddfe
+  metadata.gz: 8053f31ef3138368e50c1b6920fa7804945f508daabc31191ba2a9578f3c31f7e6629e1ca901a409ec82e4cefdf3a824fa48bcfe4fdcd8ab4a1a9da0f168e1da
+  data.tar.gz: 592bfb24c2c2a610813fcd5b8431478d4774ef312405f446393db9cbb305c2c223b129a0714b9b464adc9976e682b1754a4e5d760d0ca28b00ba99778df21d7a

data/Rakefile

@@ -16,7 +16,13 @@ if defined?(RDoc::Task)
   RDoc::Task.new do |rdoc|
     rdoc.rdoc_files.include('lib/**/*.rb')
     rdoc.rdoc_dir = 'rdoc'
+    rdoc.options << '--quiet'
   end
+  # RDoc::Task's default :clobber_rdoc uses Rake's verbose FileUtils, which
+  # echoes "rm -r rdoc" to STDOUT on every `rake` (via :rerdoc). Replace it
+  # with a silent rm_rf so the default task emits only spec/rubocop output.
+  Rake::Task[:clobber_rdoc].clear_actions
+  task(:clobber_rdoc) { FileUtils.rm_rf('rdoc') }
 end
 
 default_tasks = %i[spec rubocop]

data/bin/pwn_setup

@@ -29,6 +29,16 @@ pwn_driver = PWN::Driver::Parser.new do |options|
     opts[:list] = o
   end
 
+  options.on('-m', '--migrate',
+             '<Optional - Verify ~/.pwn state files are compatible with this pwn version; apply schema migrations>') do |o|
+    opts[:migrate] = o
+  end
+
+  options.on('-f', '--fix',
+             '<Optional - With --migrate: also autofix incompatible files (backup taken first)>') do |o|
+    opts[:fix] = o
+  end
+
   options.on('-y', '--yes',
              '<Optional - Assume yes; non-interactive (CI-friendly)>') do |o|
     opts[:yes] = o
@@ -45,6 +55,12 @@ pwn_driver.parse!
 begin
   if opts[:list]
     PWN::Setup.list_profiles
+  elsif opts[:migrate]
+    r = PWN::Setup.migrate(
+      fix: opts[:fix] || opts[:yes],
+      dry_run: opts[:dry_run]
+    )
+    exit 1 unless r && r[:after] && r[:after][:incompatible].empty?
   elsif opts[:deps] || opts[:profile]
     PWN::Setup.deps(
       profile: opts[:profile],

data/documentation/Home.md

@@ -17,7 +17,7 @@
 | [What is PWN](What-is-PWN.md) | One-paragraph elevator pitch |
 | [Why PWN](Why-PWN.md) | Design philosophy - why another framework |
 | [How PWN Works](How-PWN-Works.md) | The five layers, with the architecture diagram |
-| [Installation](Installation.md) | `gem install pwn` → `pwn setup` doctor/provisioner · capability profiles |
+| [Installation](Installation.md) | `gem install pwn` → `pwn setup` doctor/provisioner · capability profiles · `--migrate` state doctor |
 | [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
 | [Configuration](Configuration.md) | `~/.pwn/pwn.yaml` (encrypted) - engines, keys, agent options · `pwn-vault` |
 | **[All Data-Flow Diagrams](Diagrams.md)** | **27 SVGs** in one scrollable page |
@@ -36,13 +36,14 @@
 | | |
 |---|---|
 | [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama |
-| [Agent Tool Registry](Agent-Tool-Registry.md) | 10 toolsets · 61 LLM-callable tools |
+| [Agent Tool Registry](Agent-Tool-Registry.md) | 10 toolsets · **71** LLM-callable tools |
 | [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection - the self-improvement loop |
 | [Mistakes](Mistakes.md) | **Negative feedback** - fingerprint failures · do-NOT-repeat · `[REPEATING]`/`[REGRESSED]` · inline self-correction |
-| [Extrospection](Extrospection.md) | World-awareness - snapshot · drift · intel · **watch** · **verify** · **rf_tune** · correlate · **rf** · **web** |
+| [Reinforcement Learning](Reinforcement-Learning.md) | **`Reward` + `Curriculum`** - ORM/PRM judge · sentinel · HER · self-play · DPO export · **regression-gated LoRA** |
+| [Extrospection](Extrospection.md) | World-awareness - snapshot · drift · intel · **watch** · **verify** · **rf_tune** · **osint** · serial · telecomm · packet · vision · voice · correlate |
 | [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
 | [Sessions](Sessions.md) | Transcript persistence + reflection |
-| [Cron](Cron.md) | Scheduled autonomous jobs |
+| [Cron](Cron.md) | Scheduled autonomous jobs (nightly self-play + weekly weight-loop seeded by default) |
 
 ## 🧩 Capability Namespaces  (`lib/pwn/*`)
 
@@ -62,14 +63,14 @@
 | [Blockchain](Blockchain.md) | BTC · ETH helpers |
 | [Bounty](Bounty.md) | Lifecycle / auth-replay tooling |
 | [Reports](Reporting.md) | HTML/JSON output + DefectDojo/Jira |
-| [FFI](FFI.md) | Native DSP/RF backends (Volk · Liquid · FFTW · HackRF · RTL-SDR · SoapySDR) |
+| [FFI](FFI.md) | Native DSP/RF backends (Volk · Liquid · FFTW · HackRF · RTL-SDR · **AdalmPluto** · SoapySDR · Stdio) |
 | [Banner](Banner.md) | 15 startup banners |
 
 ## 🛠️ Meta
 
 | | |
 |---|---|
-| [`~/.pwn/` Filesystem Map](Persistence.md) | Every file PWN writes and why |
+| [`~/.pwn/` Filesystem Map](Persistence.md) | Every file PWN writes and why · `PWN::Migrate` state doctor |
 | [Troubleshooting](Troubleshooting.md) | Common errors and fixes |
 | [Contributing](Contributing.md) | Conventions, RuboCop, spec rules |
 

data/documentation/Installation.md

@@ -208,7 +208,8 @@ row as `MISSING` until a key is set.
 Everything above is a thin CLI over one autoloaded module:
 
 ```ruby
-PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, pkg_manager:, os:, arch: }
+PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, state:, pkg_manager:, os:, arch: }
+PWN::Setup.migrate(fix: true)             # verify + autofix ~/.pwn state files (see PWN::Migrate)
 PWN::Setup.deps(profile: :web, yes: true) # install, then re-check
 PWN::Setup.list_profiles
 PWN::Setup.pkg_manager                    # → { key: :apt, install: 'sudo apt-get install -y', sudo: true }
@@ -237,3 +238,27 @@ pwn[CURRENT_VERSION]:004 >>> pwn-ai                         # launches agent TUI
 **Next:** [Configuration](Configuration.md) · [General Usage](General-PWN-Usage.md)
 
 [← Home](Home.md)
+
+---
+
+## Upgrading — `~/.pwn` state migration
+
+After `gem update pwn`, run the state doctor to verify (and autofix)
+every persisted file under `~/.pwn` against the new release:
+
+```bash
+pwn setup --migrate            # verify + apply schema migrations (backup taken)
+pwn setup --migrate --fix      # also autofix incompatible files
+pwn setup --migrate --dry-run  # report only, write nothing
+```
+
+`PWN::Migrate` (autoloaded) stamps `~/.pwn/.schema` with the release
+schema number, checks each state file (`memory.json`, `metrics.json`,
+`mistakes.json`, `learning.jsonl`, `agents.yml`, `cron/jobs.yml`,
+`skills/`, …) against its owning module's loader, and — with `--fix` —
+deep-merges any keys the current `PWN::Config.env_template` added into
+your encrypted `~/.pwn/pwn.yaml` **without overwriting your values**.
+Every run takes a timestamped backup under `~/.pwn/backup/<ts>/` first.
+
+The plain `pwn` launcher will also print a one-line drift warning on
+startup whenever `~/.pwn/.schema` predates the running gem.

data/lib/pwn/config.rb

@@ -7,26 +7,16 @@ module PWN
   # Used to manage PWN configuration settings within PWN drivers.
   module Config
     # Supported Method Parameters::
-    # env = PWN::Config.default_env(
-    #   pwn_env_path: 'optional - Path to pwn.yaml file.  Defaults to ~/.pwn/pwn.yaml'
-    # )
-    public_class_method def self.default_env(opts = {})
-      pwn_env_path = opts[:pwn_env_path]
-      pwn_dec_path = "#{pwn_env_path}.decryptor"
-
-      puts "
-        [*] NOTICE:
-        1. Writing minimal PWN::Env to:
-           #{pwn_env_path}
-        2. Your decryptor file will be written to:
-           #{pwn_dec_path}
-        3. Use the pwn-vault command in the pwn prototyping driver to update:
-           #{pwn_env_path}
-        4. For optimal security, it's recommended to move:
-           #{pwn_dec_path}
-           to a secure location and use the --pwn-dec parameter for PWN drivers.
-      "
-      env = {
+    # tmpl = PWN::Config.env_template
+    #
+    # The canonical current-release ~/.pwn/pwn.yaml shape as a pure Hash
+    # (no I/O, no vault write, no puts).  Single source of truth used by:
+    #   * PWN::Config.default_env      — seed a fresh ~/.pwn/pwn.yaml
+    #   * PWN::Migrate.vault_drift     — diff a user vault against this release
+    #   * PWN::Migrate.backfill_vault  — deep-merge missing keys UNDER the
+    #     user values on `pwn setup --migrate --fix`
+    public_class_method def self.env_template
+      {
         ai: {
           active: 'grok',
           module_reflection: false,
@@ -174,6 +164,31 @@ module PWN
           provider: 'yaml'
         }
       }
+    rescue StandardError => e
+      raise e
+    end
+
+    # Supported Method Parameters::
+    # env = PWN::Config.default_env(
+    #   pwn_env_path: 'optional - Path to pwn.yaml file.  Defaults to ~/.pwn/pwn.yaml'
+    # )
+    public_class_method def self.default_env(opts = {})
+      pwn_env_path = opts[:pwn_env_path]
+      pwn_dec_path = "#{pwn_env_path}.decryptor"
+
+      puts "
+        [*] NOTICE:
+        1. Writing minimal PWN::Env to:
+           #{pwn_env_path}
+        2. Your decryptor file will be written to:
+           #{pwn_dec_path}
+        3. Use the pwn-vault command in the pwn prototyping driver to update:
+           #{pwn_env_path}
+        4. For optimal security, it's recommended to move:
+           #{pwn_dec_path}
+           to a secure location and use the --pwn-dec parameter for PWN drivers.
+      "
+      env = env_template
 
       # Remove beginning colon from key names
 
@@ -393,6 +408,13 @@ module PWN
       Pry.config.refresh_pwn_env = false if defined?(Pry)
 
       puts "[*] PWN::Env loaded via: #{pwn_env_path}\n"
+
+      # Upgrade drift — cheap schema-stamp check only (no per-file probes).
+      if defined?(PWN::Migrate) && PWN::Migrate.needed?
+        puts "[!] ~/.pwn state predates pwn #{PWN::VERSION} (schema " \
+             "#{PWN::Migrate.installed_schema} < #{PWN::Migrate::SCHEMA_VERSION}). " \
+             'Run `pwn setup --migrate --fix` to autofix (backup taken first).'
+      end
     rescue StandardError => e
       raise e
     end

data/lib/pwn/migrate.rb

@@ -0,0 +1,716 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'yaml'
+require 'fileutils'
+require 'time'
+
+module PWN
+  # PWN::Migrate — the ~/.pwn state **doctor** and **auto-migrator**.
+  #
+  # PWN persists a growing set of files under `~/.pwn` (encrypted config,
+  # memory, learning outcomes, metrics, mistakes, extrospection, cron
+  # jobs, agents, skills, sessions, swarm buses, …).  Each file is owned
+  # by a different module and each release can add keys or change shape.
+  # A user upgrading `gem install pwn` between two versions could
+  # therefore hit `KeyError`, `NoMethodError for nil`, or a silent
+  # empty-fallback because their on-disk state predates the new loader.
+  #
+  # `PWN::Migrate` closes that gap.  It is called from:
+  #
+  #   * `pwn setup --migrate`       — explicit doctor + autofix
+  #   * `PWN::Setup.check`          — read-only ~/.pwn state section
+  #   * `PWN::Config.refresh_env`   — one-line drift warning on every launch
+  #
+  # It works by:
+  #
+  #   1. Stamping `~/.pwn/.schema` with `{ schema:, pwn_version:, at: }`
+  #      the first time it runs.  Any release that changes the on-disk
+  #      shape of a `~/.pwn` file bumps `SCHEMA_VERSION` here and appends
+  #      an idempotent lambda to `MIGRATIONS`.
+  #   2. Declaratively verifying every state file against its OWNING
+  #      module's own loader (`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. Autofixing:  timestamped backup → ordered schema migrations →
+  #      per-file repair (quarantine corrupt / re-seed missing) →
+  #      `pwn.yaml` deep-key backfill (missing keys from the current
+  #      `PWN::Config.env_template` are merged in-place under the user's
+  #      values, then the vault is re-encrypted with the SAME key/iv).
+  #
+  # Everything is idempotent, dry-run capable, and never overwrites a
+  # user-set value.
+  module Migrate
+    PWN_ROOT       = File.join(Dir.home, '.pwn')
+    SCHEMA_FILE    = File.join(PWN_ROOT, '.schema')
+    BACKUP_ROOT    = File.join(PWN_ROOT, 'backup')
+    QUARANTINE_DIR = File.join(PWN_ROOT, 'quarantine')
+
+    # Bump this whenever the shape of any file under ~/.pwn changes in a
+    # way that requires a one-time transform.  Add the transform as an
+    # entry in MIGRATIONS keyed by the NEW schema number.
+    SCHEMA_VERSION = 1
+
+    OK   = "\e[32mok\e[0m"
+    BAD  = "\e[31mFAIL\e[0m"
+    WARN = "\e[33mdrift\e[0m"
+
+    # ──────────────────────────────────────────────────────────────────
+    # Declarative registry of every persisted ~/.pwn artefact.
+    #
+    # Each entry knows how to (a) locate itself, (b) ask its owning
+    # module to load it, and (c) decide whether the loaded shape is what
+    # this pwn version expects.  Verifiers are intentionally SHALLOW —
+    # they detect "loader gave up and returned the fallback" rather than
+    # re-validating every key, so ownership stays with the module.
+    #
+    # :fix values:
+    #   :quarantine — move the file aside; owner re-seeds on next write
+    #   :vault      — deep-merge missing keys from PWN::Config.env_template
+    #   :seed       — call the owner's idempotent seeder (dirs / defaults)
+    #   :jsonl      — strip unparsable lines only (keeps good history)
+    #   :skills     — PWN::Config.migrate_legacy_skills
+    # ──────────────────────────────────────────────────────────────────
+    STATE_FILES = {
+      'pwn.yaml' => {
+        owner: 'PWN::Config',
+        kind: :vault,
+        fix: :vault,
+        verify: lambda { |p, _raw|
+          return { ok: false, why: 'missing' } unless File.file?(p)
+
+          enc = PWN::Plugins::Vault.file_encrypted?(file: p)
+          # Shape (missing keys vs env_template) is checked separately in
+          # .vault_drift because it requires the decryptor.
+          { ok: enc, why: enc ? nil : 'not encrypted (run PWN::Plugins::Vault.create)' }
+        }
+      },
+      'memory.json' => {
+        owner: 'PWN::Memory',
+        kind: :json,
+        fix: :quarantine,
+        verify: lambda { |_p, raw|
+          m = PWN::Memory.load
+          bad = m.reject { |_k, v| v.is_a?(Hash) && v.key?(:value) }
+          { ok: !(m.empty? && raw.to_s.length > 4) && bad.empty?,
+            why: bad.any? ? "#{bad.length} entries missing :value" : nil }
+        }
+      },
+      'memory.idx' => {
+        owner: 'PWN::MemoryIndex',
+        kind: :blob,
+        fix: :quarantine,
+        verify: ->(_p, _raw) { { ok: true } }
+      },
+      'learning.jsonl' => {
+        owner: 'PWN::AI::Agent::Learning',
+        kind: :jsonl,
+        fix: :jsonl,
+        verify: :jsonl
+      },
+      'preferences.jsonl' => {
+        owner: 'PWN::AI::Agent::Reward',
+        kind: :jsonl,
+        fix: :jsonl,
+        verify: :jsonl
+      },
+      'metrics.json' => {
+        owner: 'PWN::AI::Agent::Metrics',
+        kind: :json,
+        fix: :quarantine,
+        verify: lambda { |_p, raw|
+          m = PWN::AI::Agent::Metrics.load
+          fell_back = m == { tools: {}, updated_at: nil } && raw.to_s.length > 4
+          { ok: m.is_a?(Hash) && m.key?(:tools) && !fell_back,
+            why: fell_back ? 'loader fell back to empty (unparsable / wrong shape)' : nil }
+        }
+      },
+      'mistakes.json' => {
+        owner: 'PWN::AI::Agent::Mistakes',
+        kind: :json,
+        fix: :quarantine,
+        verify: lambda { |_p, raw|
+          m = PWN::AI::Agent::Mistakes.load
+          fell_back = m.empty? && raw.to_s.length > 4
+          { ok: m.is_a?(Hash) && !fell_back, why: fell_back ? 'loader fell back to {}' : nil }
+        }
+      },
+      'extrospection.json' => {
+        owner: 'PWN::AI::Agent::Extrospection',
+        kind: :json,
+        fix: :quarantine,
+        verify: lambda { |_p, raw|
+          m = PWN::AI::Agent::Extrospection.load
+          shape = m.is_a?(Hash) && m.key?(:observations) && m[:observations].is_a?(Array)
+          fell_back = shape && m[:snapshot].to_h.empty? && m[:observations].empty? && raw.to_s.length > 8
+          { ok: shape && !fell_back, why: shape ? nil : 'missing :observations array' }
+        }
+      },
+      'reward_sentinel.json' => {
+        owner: 'PWN::AI::Agent::Reward',
+        kind: :json,
+        fix: :quarantine,
+        verify: ->(_p, _raw) { { ok: true } }
+      },
+      'agents.yml' => {
+        owner: 'PWN::AI::Agent::Swarm',
+        kind: :yaml,
+        fix: :quarantine,
+        verify: lambda { |_p, raw|
+          m = PWN::AI::Agent::Swarm.personas
+          fell_back = m.empty? && raw.to_s.strip.length > 4
+          bad = m.reject { |_k, v| v.is_a?(Hash) && v[:role] }
+          { ok: !fell_back && bad.empty?,
+            why: (fell_back && 'loader fell back to {}') || (bad.any? && "#{bad.length} personas missing :role") || nil }
+        }
+      },
+      'cron/jobs.yml' => {
+        owner: 'PWN::Cron',
+        kind: :yaml,
+        fix: :seed,
+        verify: lambda { |_p, raw|
+          j = PWN::Cron.list
+          fell_back = j.empty? && raw.to_s.strip.length > 8
+          bad = j.reject { |_id, v| v.is_a?(Hash) && v[:schedule] }
+          { ok: !fell_back && bad.empty?,
+            why: (fell_back && 'loader fell back to {}') || (bad.any? && "#{bad.length} jobs missing :schedule") || nil }
+        }
+      },
+      'skills/' => {
+        owner: 'PWN::Config',
+        kind: :dir,
+        fix: :skills,
+        verify: lambda { |p, _raw|
+          return { ok: true } unless File.directory?(p)
+
+          legacy = Dir.glob(File.join(p, '*.{rb,md,txt,skill,yml,yaml}')).length
+          { ok: legacy.zero?, why: legacy.zero? ? nil : "#{legacy} legacy flat skill file(s)" }
+        }
+      },
+      'sessions/' => { owner: 'PWN::Sessions', kind: :dir, fix: :seed, verify: ->(_p, _r) { { ok: true } } },
+      'swarm/' => { owner: 'PWN::AI::Agent::Swarm', kind: :dir, fix: :seed, verify: ->(_p, _r) { { ok: true } } },
+      'curriculum/' => { owner: 'PWN::AI::Agent::Curriculum', kind: :dir, fix: :seed, verify: ->(_p, _r) { { ok: true } } },
+      'finetune/' => { owner: 'PWN::AI::Agent::Curriculum', kind: :dir, fix: :seed, verify: ->(_p, _r) { { ok: true } } },
+      'extrospection/' => { owner: 'PWN::AI::Agent::Extrospection', kind: :dir, fix: :seed, verify: ->(_p, _r) { { ok: true } } }
+    }.freeze
+
+    # Ordered, idempotent one-shot transforms.  Key == the schema number
+    # a ~/.pwn tree is AT after the lambda runs.  Add a new entry every
+    # time SCHEMA_VERSION is bumped.  Each lambda receives (root, io).
+    MIGRATIONS = {
+      1 => lambda { |root, io|
+        # v0 → v1 : agentskills.io directory layout + seeded RL cron jobs
+        #           + ensure all state subdirs exist.
+        %w[skills sessions swarm cron curriculum finetune extrospection].each do |d|
+          FileUtils.mkdir_p(File.join(root, d))
+        end
+        r = begin
+          PWN::Config.migrate_legacy_skills
+        rescue StandardError
+          { migrated: 0 }
+        end
+        io.puts "    · migrate_legacy_skills → #{r[:migrated]} converted" if r[:migrated].to_i.positive?
+        PWN::Cron.install_defaults if defined?(PWN::Cron)
+      }
+    }.freeze
+
+    # ──────────────────────────────────────────────────────────────────
+    # public api
+    # ──────────────────────────────────────────────────────────────────
+
+    # Supported Method Parameters::
+    # schema = PWN::Migrate.installed_schema
+    #
+    # → Integer schema number stamped in ~/.pwn/.schema (0 when absent).
+
+    public_class_method def self.installed_schema
+      return 0 unless File.file?(SCHEMA_FILE)
+
+      JSON.parse(File.read(SCHEMA_FILE))['schema'].to_i
+    rescue StandardError
+      0
+    end
+
+    # Supported Method Parameters::
+    # bool = PWN::Migrate.needed?
+    #
+    # Cheap predicate for PWN::Config.refresh_env — schema stamp only,
+    # no per-file probes, so it adds ~0 to launch time.
+
+    public_class_method def self.needed?
+      File.directory?(PWN_ROOT) && installed_schema < SCHEMA_VERSION
+    rescue StandardError
+      false
+    end
+
+    # Supported Method Parameters::
+    # rows = PWN::Migrate.status
+    #
+    # Per-file compatibility report — the machine-readable half of
+    # `.check`.  Never writes.  Never raises (each verifier is rescued).
+
+    public_class_method def self.status
+      files = STATE_FILES.map do |rel, meta|
+        path = File.join(PWN_ROOT, rel)
+        exists = meta[:kind] == :dir ? File.directory?(path) : File.file?(path)
+        raw = exists && meta[:kind] != :dir ? safe_read(path: path) : nil
+        v = verify_one(path: path, raw: raw, meta: meta)
+        {
+          rel: rel, path: path, owner: meta[:owner], kind: meta[:kind],
+          exists: exists, size: exists ? File.size?(path) : nil,
+          ok: v[:ok], why: v[:why], fix: meta[:fix]
+        }
+      end
+      {
+        root: PWN_ROOT,
+        schema_installed: installed_schema,
+        schema_current: SCHEMA_VERSION,
+        pwn_version: (defined?(PWN::VERSION) ? PWN::VERSION : nil),
+        needs_migration: needed?,
+        files: files,
+        incompatible: files.reject { |f| f[:ok] }
+      }
+    rescue StandardError => e
+      raise e
+    end
+
+    # Supported Method Parameters::
+    # PWN::Migrate.check(
+    #   io: 'optional - IO to write the report to (default $stdout)'
+    # )
+    #
+    # Human-readable ~/.pwn state doctor.  Read-only.  Called from
+    # PWN::Setup.check so `pwn setup` shows this alongside the
+    # native-gem / toolchain report.
+
+    public_class_method def self.check(opts = {})
+      io = opts[:io] || $stdout
+      st = status
+
+      io.puts "~/.pwn state         schema #{st[:schema_installed]} → #{st[:schema_current]} " \
+              "#{st[:needs_migration] ? "(#{WARN} — run `pwn setup --migrate`)" : "(#{OK})"}"
+      st[:files].each do |f|
+        mark = f[:ok] ? OK : BAD
+        note = f[:ok] ? '' : "→ #{f[:why]}  [fix: #{f[:fix]}]"
+        sz   = f[:exists] ? human_size(bytes: f[:size]) : '—'
+        io.puts "  #{f[:rel].ljust(22)} #{mark}   #{sz.to_s.ljust(8)} #{f[:owner].to_s.ljust(30)} #{note}"
+      end
+      unless st[:incompatible].empty?
+        io.puts
+        io.puts "#{st[:incompatible].length} file(s) incompatible with pwn #{st[:pwn_version]} — " \
+                'run `pwn setup --migrate --fix` to autofix (a timestamped backup is taken first).'
+      end
+      st
+    rescue StandardError => e
+      raise e
+    end
+
+    # Supported Method Parameters::
+    # report = PWN::Migrate.run(
+    #   fix:     'optional - also autofix incompatible files (default: schema-migrations only)',
+    #   backup:  'optional - take timestamped backup of ~/.pwn first (default true)',
+    #   dry_run: 'optional - report what WOULD happen, write nothing (default false)',
+    #   key:     'optional - vault key   (default: read ~/.pwn/pwn.yaml.decryptor)',
+    #   iv:      'optional - vault iv    (default: read ~/.pwn/pwn.yaml.decryptor)',
+    #   io:      'optional - IO to write to (default $stdout)'
+    # )
+    #
+    # 1. backup  2. schema migrations installed→current  3. per-file
+    # autofix (when fix:true)  4. pwn.yaml key backfill (when fix:true
+    # and decryptor available)  5. stamp .schema.
+
+    public_class_method def self.run(opts = {})
+      fix     = opts[:fix] ? true : false
+      dry_run = opts[:dry_run] ? true : false
+      backup  = opts.fetch(:backup, true)
+      io      = opts[:io] || $stdout
+
+      FileUtils.mkdir_p(PWN_ROOT)
+      before = status
+      io.puts "PWN::Migrate — pwn #{before[:pwn_version]} · ~/.pwn schema " \
+              "#{before[:schema_installed]} → #{before[:schema_current]}" \
+              "#{'  (dry-run)' if dry_run}"
+
+      bpath = nil
+      if backup && !dry_run && File.directory?(PWN_ROOT)
+        bpath = backup!
+        io.puts "  backup   : #{bpath}"
+      end
+
+      # ── ordered schema migrations ────────────────────────────────────
+      applied = []
+      ((before[:schema_installed] + 1)..SCHEMA_VERSION).each do |n|
+        m = MIGRATIONS[n]
+        next unless m
+
+        io.puts "  migrate  : v#{n - 1} → v#{n}"
+        m.call(PWN_ROOT, io) unless dry_run
+        applied << n
+      end
+
+      # ── per-file autofix ─────────────────────────────────────────────
+      fixed = []
+      if fix
+        before[:incompatible].each do |f|
+          io.puts "  fix      : #{f[:rel].ljust(22)} [#{f[:fix]}]  #{f[:why]}"
+          next if dry_run
+
+          fixed << f.merge(result: apply_fix(file: f))
+        end
+
+        # pwn.yaml key backfill runs even when the vault verifier passed —
+        # "encrypted" ≠ "has every key this release added".
+        vd = backfill_vault(key: opts[:key], iv: opts[:iv], dry_run: dry_run, io: io)
+        fixed << vd if vd && vd[:added].to_i.positive?
+      end
+
+      stamp! unless dry_run
+
+      after = status
+      io.puts
+      io.puts "  result   : #{after[:incompatible].length} incompatible remaining " \
+              "(was #{before[:incompatible].length}) · schema now #{after[:schema_installed]}"
+
+      { backup: bpath, applied_migrations: applied, fixed: fixed,
+        before: before, after: after, dry_run: dry_run }
+    rescue StandardError => e
+      raise e
+    end
+
+    # Supported Method Parameters::
+    # drift = PWN::Migrate.vault_drift(
+    #   key: 'optional - vault key', iv: 'optional - vault iv'
+    # )
+    #
+    # Deep-diff the user's decrypted pwn.yaml against the current
+    # PWN::Config.env_template.  → { missing: [dotted.paths], user: {…} }
+    # Returns nil when the decryptor is unavailable (never prompts).
+
+    public_class_method def self.vault_drift(opts = {})
+      key, iv = decryptor(opts)
+      return nil unless key && iv
+
+      yaml = File.join(PWN_ROOT, 'pwn.yaml')
+      return nil unless File.file?(yaml) && PWN::Plugins::Vault.file_encrypted?(file: yaml)
+
+      user = PWN::Plugins::Vault.dump(file: yaml, key: key, iv: iv)
+      tmpl = env_template
+      { missing: missing_paths(tmpl: tmpl, user: user), user: user, template: tmpl }
+    rescue StandardError
+      nil
+    end
+
+    # Supported Method Parameters::
+    # r = PWN::Migrate.backfill_vault(
+    #   key: 'optional', iv: 'optional', dry_run: false, io: $stdout
+    # )
+    #
+    # Decrypt → deep-merge template UNDER user (never overwrites) →
+    # re-encrypt with the SAME key/iv.  This is the fix for the #1
+    # upgrade break: `NoMethodError: undefined method '[]' for nil` when
+    # a release added `env[:ai][:new_engine][:…]` and the user's vault
+    # predates it.
+
+    public_class_method def self.backfill_vault(opts = {})
+      io      = opts[:io] || $stdout
+      dry_run = opts[:dry_run] ? true : false
+      d = vault_drift(key: opts[:key], iv: opts[:iv])
+      unless d
+        io.puts '  vault    : skipped (no decryptor available — run with --pwn-dec or set key:/iv:)'
+        return nil
+      end
+      if d[:missing].empty?
+        io.puts "  vault    : #{OK} (no missing keys vs PWN::Config.env_template)"
+        return { rel: 'pwn.yaml', added: 0, missing: [] }
+      end
+
+      io.puts "  vault    : #{WARN} #{d[:missing].length} missing key(s) — backfilling under user values"
+      d[:missing].first(8).each { |p| io.puts "             + #{p}" }
+      io.puts "             … (+#{d[:missing].length - 8} more)" if d[:missing].length > 8
+      return { rel: 'pwn.yaml', added: d[:missing].length, missing: d[:missing], dry_run: true } if dry_run
+
+      merged = deep_defaults(user: d[:user], tmpl: d[:template])
+      yaml   = File.join(PWN_ROOT, 'pwn.yaml')
+      key, iv = decryptor(opts)
+      # Same colon-stripping default_env uses so the file stays diff-clean.
+      File.write(yaml, YAML.dump(merged).gsub(/^(\s*):/, '\1'))
+      File.chmod(0o600, yaml)
+      PWN::Plugins::Vault.encrypt(file: yaml, key: key, iv: iv)
+
+      { rel: 'pwn.yaml', added: d[:missing].length, missing: d[:missing] }
+    rescue StandardError => e
+      io.puts "  vault    : #{BAD} #{e.class}: #{e.message}"
+      nil
+    end
+
+    # Supported Method Parameters::
+    # tmpl = PWN::Migrate.env_template
+    #
+    # The canonical current-release pwn.yaml shape, WITHOUT the I/O
+    # side-effects of PWN::Config.default_env.  Prefers
+    # PWN::Config.env_template when that refactor is present.
+
+    public_class_method def self.env_template
+      return PWN::Config.env_template if PWN::Config.respond_to?(:env_template)
+
+      # Fallback: intercept default_env's write path.  Never reached once
+      # PWN::Config.env_template ships, but keeps Migrate self-sufficient.
+      {}
+    end
+
+    # ──────────────────────────────────────────────────────────────────
+    # internals
+    # ──────────────────────────────────────────────────────────────────
+
+    private_class_method def self.verify_one(opts = {})
+      meta = opts[:meta]
+      path = opts[:path]
+      raw  = opts[:raw]
+      # Nonexistent leaf files are fine — owners lazily seed on first
+      # write.  A missing pwn.yaml IS a problem though (kind :vault).
+      return { ok: true } if !File.exist?(path) && meta[:kind] != :vault
+
+      # Raw parseability first (owners rescue → fallback so we'd never see it).
+      case meta[:kind]
+      when :json
+        JSON.parse(raw.to_s) if raw
+      when :yaml
+        YAML.safe_load(raw.to_s, permitted_classes: [Symbol, Time, Date], aliases: true) if raw
+      end
+
+      v = meta[:verify]
+      return jsonl_verify(path: path) if v == :jsonl
+
+      v.call(path, raw)
+    rescue JSON::ParserError, Psych::SyntaxError => e
+      { ok: false, why: "unparsable #{meta[:kind]}: #{e.message[0, 60]}" }
+    rescue StandardError => e
+      { ok: false, why: "#{e.class}: #{e.message[0, 80]}" }
+    end
+
+    private_class_method def self.jsonl_verify(opts = {})
+      path  = opts[:path]
+      total = 0
+      bad   = 0
+      File.foreach(path) do |l|
+        next if l.strip.empty?
+
+        total += 1
+        JSON.parse(l)
+      rescue StandardError
+        bad += 1
+      end
+      { ok: bad.zero?, why: bad.zero? ? nil : "#{bad}/#{total} lines unparsable" }
+    end
+
+    private_class_method def self.apply_fix(opts = {})
+      f = opts[:file]
+      case f[:fix]
+      when :quarantine
+        quarantine!(rel: f[:rel])
+      when :jsonl
+        strip_bad_jsonl!(rel: f[:rel])
+      when :skills
+        PWN::Config.migrate_legacy_skills
+      when :seed
+        FileUtils.mkdir_p(File.join(PWN_ROOT, f[:rel])) if f[:kind] == :dir
+        PWN::Cron.install_defaults if f[:rel].start_with?('cron/') && defined?(PWN::Cron)
+        :seeded
+      when :vault
+        :deferred_to_backfill
+      else
+        :noop
+      end
+    rescue StandardError => e
+      "#{e.class}: #{e.message}"
+    end
+
+    private_class_method def self.quarantine!(opts = {})
+      src = File.join(PWN_ROOT, opts[:rel])
+      return :absent unless File.exist?(src)
+
+      dst = File.join(QUARANTINE_DIR, Time.now.utc.strftime('%Y%m%d_%H%M%S'))
+      FileUtils.mkdir_p(dst)
+      FileUtils.mv(src, File.join(dst, File.basename(opts[:rel])))
+      "quarantined → #{dst}"
+    end
+
+    private_class_method def self.strip_bad_jsonl!(opts = {})
+      path = File.join(PWN_ROOT, opts[:rel])
+      return :absent unless File.file?(path)
+
+      good = []
+      bad  = 0
+      File.foreach(path) do |l|
+        next if l.strip.empty?
+
+        JSON.parse(l)
+        good << l
+      rescue StandardError
+        bad += 1
+      end
+      File.write(path, good.join)
+      "dropped #{bad} bad line(s), kept #{good.length}"
+    end
+
+    private_class_method def self.backup!
+      ts  = Time.now.utc.strftime('%Y%m%d_%H%M%S')
+      dst = File.join(BACKUP_ROOT, ts)
+      FileUtils.mkdir_p(dst)
+      Dir.children(PWN_ROOT).each do |c|
+        next if %w[backup quarantine sessions swarm].include?(c) # large / regenerable
+
+        src = File.join(PWN_ROOT, c)
+        FileUtils.cp_r(src, dst)
+      rescue StandardError
+        next
+      end
+      dst
+    end
+
+    private_class_method def self.stamp!
+      FileUtils.mkdir_p(PWN_ROOT)
+      File.write(
+        SCHEMA_FILE,
+        JSON.pretty_generate(
+          schema: SCHEMA_VERSION,
+          pwn_version: (defined?(PWN::VERSION) ? PWN::VERSION : nil),
+          at: Time.now.utc.iso8601
+        )
+      )
+      SCHEMA_VERSION
+    end
+
+    private_class_method def self.decryptor(opts = {})
+      key = opts[:key]
+      iv  = opts[:iv]
+      return [key, iv] if key && iv
+
+      dec = File.join(PWN_ROOT, 'pwn.yaml.decryptor')
+      return [nil, nil] unless File.file?(dec)
+
+      d = YAML.load_file(dec, symbolize_names: true)
+      [d[:key], d[:iv]]
+    rescue StandardError
+      [nil, nil]
+    end
+
+    private_class_method def self.safe_read(opts = {})
+      path = opts[:path]
+      File.size(path) > 5_000_000 ? nil : File.read(path)
+    rescue StandardError
+      nil
+    end
+
+    private_class_method def self.human_size(opts = {})
+      bytes = opts[:bytes]
+      return '' if bytes.nil?
+
+      u = %w[B K M G]
+      i = 0
+      n = bytes.to_f
+      while n >= 1024 && i < u.length - 1
+        n /= 1024
+        i += 1
+      end
+      format('%<n>.4g%<u>s', n: n, u: u[i])
+    end
+
+    # template UNDER user — user values always win; template only fills
+    # holes.  Arrays are treated as leaves (never element-merged).
+    private_class_method def self.deep_defaults(opts = {})
+      user = opts[:user]
+      tmpl = opts[:tmpl]
+      return user unless tmpl.is_a?(Hash)
+      return tmpl unless user.is_a?(Hash)
+
+      out = user.dup
+      tmpl.each do |k, tv|
+        uv = out.key?(k) ? out[k] : out[k.to_s]
+        out[k] = if tv.is_a?(Hash)
+                   deep_defaults(user: uv, tmpl: tv)
+                 elsif uv.nil? && !out.key?(k) && !out.key?(k.to_s)
+                   tv
+                 else
+                   uv
+                 end
+      end
+      out
+    end
+
+    private_class_method def self.missing_paths(opts = {})
+      tmpl   = opts[:tmpl]
+      user   = opts[:user]
+      prefix = opts[:prefix] || ''
+      out    = []
+      return out unless tmpl.is_a?(Hash)
+
+      tmpl.each do |k, tv|
+        dotted = prefix.empty? ? k.to_s : "#{prefix}.#{k}"
+        uv = nil
+        if user.is_a?(Hash)
+          uv = user[k]
+          uv = user[k.to_s] if uv.nil?
+        end
+        if tv.is_a?(Hash)
+          if uv.is_a?(Hash)
+            out.concat(missing_paths(tmpl: tv, user: uv, prefix: dotted))
+          else
+            out << dotted
+          end
+        elsif !user.is_a?(Hash) || (!user.key?(k) && !user.key?(k.to_s))
+          out << dotted
+        end
+      end
+      out
+    end
+
+    # Author(s):: 0day Inc. <support@0dayinc.com>
+
+    public_class_method def self.authors
+      "AUTHOR(S):
+        0day Inc. <support@0dayinc.com>
+      "
+    end
+
+    # Display Usage for this Module
+
+    public_class_method def self.help
+      puts "USAGE:
+        # Is ~/.pwn older than this pwn release's schema?
+        #{self}.needed?             # => true/false (cheap; used by refresh_env)
+
+        # Read-only per-file compatibility report.
+        #{self}.status              # => { schema_installed:, schema_current:, files:[…], incompatible:[…] }
+        #{self}.check               # human-readable to $stdout
+
+        # Apply schema migrations + (optionally) autofix incompatible files.
+        # Always takes a timestamped backup under ~/.pwn/backup/<ts>/ first.
+        #{self}.run(
+          fix:     'optional - also autofix per-file (default false)',
+          backup:  'optional - default true',
+          dry_run: 'optional - default false',
+          key:     'optional - vault key (default: ~/.pwn/pwn.yaml.decryptor)',
+          iv:      'optional - vault iv'
+        )
+
+        # pwn.yaml specifically — deep-merge missing keys from the
+        # current release template UNDER the user's values, re-encrypt.
+        #{self}.vault_drift         # => { missing: [dotted.paths], … } or nil
+        #{self}.backfill_vault
+
+        # Data:
+        #{self}::SCHEMA_VERSION     # bump when a ~/.pwn file shape changes
+        #{self}::STATE_FILES        # rel-path → owner → verifier → fix
+        #{self}::MIGRATIONS         # ordered idempotent transforms
+
+        # From the shell:
+        pwn setup --migrate                # == #{self}.run
+        pwn setup --migrate --fix          # == #{self}.run(fix: true)
+        pwn setup --migrate --dry-run
+
+        #{self}.authors
+      "
+    end
+  end
+end

data/lib/pwn/setup.rb

@@ -372,6 +372,13 @@ module PWN
       end
       io.puts
 
+      # ~/.pwn state ----------------------------------------------------
+      migrate = nil
+      if defined?(PWN::Migrate)
+        migrate = PWN::Migrate.check(io: io)
+        io.puts
+      end
+
       total   = NATIVE_GEMS.size + TOOLCHAIN.size
       missing = gem_missing.size + bin_missing.size
       io.puts "#{total - missing} / #{total} capabilities usable · #{missing} degraded"
@@ -381,8 +388,9 @@ module PWN
         io.puts '    `pwn setup --profile <name>` for a subset. See `pwn setup --list-profiles`.'
       end
 
-      { ok: missing.zero?, native_gems_missing: gem_missing, toolchain_missing: bin_missing,
-        pkg_manager: pm[:key], os: os, arch: arch }
+      { ok: missing.zero? && Array(migrate && migrate[:incompatible]).empty?,
+        native_gems_missing: gem_missing, toolchain_missing: bin_missing,
+        state: migrate, pkg_manager: pm[:key], os: os, arch: arch }
     rescue StandardError => e
       raise e
     end
@@ -493,6 +501,28 @@ module PWN
       raise e
     end
 
+    # Supported Method Parameters::
+    # PWN::Setup.migrate(
+    #   fix:     'optional - also autofix incompatible ~/.pwn files (default false)',
+    #   dry_run: 'optional - print what WOULD happen (default false)',
+    #   yes:     'optional - alias for fix:true (CI-friendly)',
+    #   io:      'optional - IO to write to (default $stdout)'
+    # )
+    #
+    # Delegate to PWN::Migrate.run — verify every ~/.pwn state file is
+    # compatible with THIS pwn release and (optionally) autofix it.  A
+    # timestamped backup of ~/.pwn is taken first.  See `PWN::Migrate.help`.
+
+    public_class_method def self.migrate(opts = {})
+      PWN::Migrate.run(
+        fix: opts[:fix] || opts[:yes],
+        dry_run: opts[:dry_run],
+        io: opts[:io] || $stdout
+      )
+    rescue StandardError => e
+      raise e
+    end
+
     # ------------------------------------------------------------------
 
     private_class_method def self.detect_os_attr(opts = {})
@@ -585,6 +615,8 @@ module PWN
         pwn setup --profile sdr --yes
         pwn setup --list-profiles
         pwn setup --dry-run --profile net
+        pwn setup --migrate                  # verify + upgrade ~/.pwn schema
+        pwn setup --migrate --fix            # also autofix incompatible files
 
         #{self}.authors
       "

data/lib/pwn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PWN
-  VERSION = '0.5.635'
+  VERSION = '0.5.636'
 end

data/lib/pwn.rb

@@ -19,6 +19,7 @@ module PWN
   autoload :Cron, 'pwn/cron'
   autoload :Memory, 'pwn/memory'
   autoload :MemoryIndex, 'pwn/memory_index'
+  autoload :Migrate, 'pwn/migrate'
   autoload :Sessions, 'pwn/sessions'
   autoload :Setup, 'pwn/setup'
   autoload :Driver, 'pwn/driver'

data/spec/documentation/installation_md_spec.rb

@@ -57,9 +57,9 @@ RSpec.describe 'documentation/Installation.md' do
     end
 
     it 'programmatic API section is truthful' do
-      expect(PWN::Setup).to respond_to(:check, :deps, :list_profiles, :pkg_manager)
+      expect(PWN::Setup).to respond_to(:check, :deps, :list_profiles, :pkg_manager, :migrate)
       expect(PWN::Setup.check(io: StringIO.new).keys)
-        .to eq(%i[ok native_gems_missing toolchain_missing pkg_manager os arch])
+        .to eq(%i[ok native_gems_missing toolchain_missing state pkg_manager os arch])
       expect(PWN::Setup.pkg_manager.keys).to eq(%i[key install sudo])
       expect(PWN::Setup.constants).to include(:NATIVE_GEMS, :TOOLCHAIN, :PROFILES)
     end

data/spec/lib/pwn/ai/agent/mistakes_spec.rb

@@ -15,6 +15,8 @@ describe PWN::AI::Agent::Mistakes do
 
   it 'fingerprints, counts and resolves recurring failures' do
     stub_const('PWN::AI::Agent::Mistakes::MISTAKES_FILE', File.join(Dir.mktmpdir, 'mistakes.json'))
+    stub_const('PWN::AI::Agent::Reward::PREFERENCES_FILE', File.join(Dir.mktmpdir, 'prefs.jsonl')) if defined?(PWN::AI::Agent::Reward)
+    stub_const('PWN::Memory::MEMORY_FILE', File.join(Dir.mktmpdir, 'memory.json')) if defined?(PWN::Memory)
     PWN::AI::Agent::Mistakes.reset
     a = PWN::AI::Agent::Mistakes.record(tool: 'shell', error: 'nmpa: command not found at /tmp/x:42')
     b = PWN::AI::Agent::Mistakes.record(tool: 'shell', error: 'nmpa: command not found at /var/y:99')

data/spec/lib/pwn/migrate_spec.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe PWN::Migrate do
+  it 'should display information for authors' do
+    authors_response = PWN::Migrate
+    expect(authors_response).to respond_to :authors
+  end
+
+  it 'should display information for existing help method' do
+    help_response = PWN::Migrate
+    expect(help_response).to respond_to :help
+  end
+
+  it 'exposes the schema / state-file data tables' do
+    expect(PWN::Migrate::SCHEMA_VERSION).to be_a(Integer)
+    expect(PWN::Migrate::STATE_FILES).to be_a(Hash)
+    expect(PWN::Migrate::STATE_FILES).to have_key('pwn.yaml')
+    expect(PWN::Migrate::MIGRATIONS).to be_a(Hash)
+    expect(PWN::Migrate::MIGRATIONS.keys.max).to eq(PWN::Migrate::SCHEMA_VERSION)
+  end
+
+  it 'env_template is the pure hash used for vault backfill' do
+    t = PWN::Config.env_template
+    expect(t).to be_a(Hash)
+    expect(t).to have_key(:ai)
+    expect(t[:ai]).to have_key(:agent)
+    expect(PWN::Migrate.env_template).to eq(t)
+  end
+
+  # ────────────────────────────────────────────────────────────────────
+  #  functional round-trip in a tmp sandbox — never touches real ~/.pwn
+  # ────────────────────────────────────────────────────────────────────
+  context 'sandboxed ~/.pwn', :aggregate_failures do
+    include_context 'pwn tmp sandbox'
+
+    let(:io) { StringIO.new }
+
+    before do
+      # Skills verifier globs the REAL PWN::Config.pwn_skills_path unless
+      # redirected — keep it inside the sandbox too.
+      allow(PWN::Config).to receive(:pwn_skills_path).and_return(File.join(@tmp, 'skills'))
+    end
+
+    it '.needed? / .status on a fresh (empty) root' do
+      expect(PWN::Migrate.installed_schema).to eq(0)
+      expect(PWN::Migrate.needed?).to be true
+
+      st = PWN::Migrate.status
+      expect(st[:schema_installed]).to eq(0)
+      expect(st[:schema_current]).to eq(PWN::Migrate::SCHEMA_VERSION)
+      expect(st[:files]).to be_an(Array)
+      # only pwn.yaml is REQUIRED to exist; every other absent file is ok:true
+      missing_vault = st[:files].find { |f| f[:rel] == 'pwn.yaml' }
+      expect(missing_vault[:ok]).to be false
+    end
+
+    it '.run applies migrations, stamps .schema, and clears needed?' do
+      r = PWN::Migrate.run(fix: false, backup: false, io: io)
+      expect(r[:applied_migrations]).to include(1)
+      expect(File).to exist(File.join(@tmp, '.schema'))
+      expect(PWN::Migrate.installed_schema).to eq(PWN::Migrate::SCHEMA_VERSION)
+      expect(PWN::Migrate.needed?).to be false
+      # migration 1 seeds the state subdirs
+      %w[skills sessions swarm cron curriculum finetune extrospection].each do |d|
+        expect(File).to be_directory(File.join(@tmp, d))
+      end
+    end
+
+    it 'detects & autofixes a corrupt JSON store (quarantine)' do
+      File.write(File.join(@tmp, 'metrics.json'), '{{{ not json')
+      st = PWN::Migrate.status
+      row = st[:files].find { |f| f[:rel] == 'metrics.json' }
+      expect(row[:ok]).to be false
+      expect(row[:why]).to match(/unparsable/)
+
+      PWN::Migrate.run(fix: true, backup: false, io: io)
+      expect(File).not_to exist(File.join(@tmp, 'metrics.json'))
+      expect(Dir.glob(File.join(@tmp, 'quarantine', '*', 'metrics.json'))).not_to be_empty
+      # owner falls back cleanly after quarantine
+      expect(PWN::AI::Agent::Metrics.load).to eq(tools: {}, updated_at: nil)
+    end
+
+    it 'detects & autofixes bad JSONL lines without losing good history' do
+      path = File.join(@tmp, 'learning.jsonl')
+      File.write(path, %({"task":"a","success":true}\nNOT JSON\n{"task":"b","success":false}\n))
+      row = PWN::Migrate.status[:files].find { |f| f[:rel] == 'learning.jsonl' }
+      expect(row[:ok]).to be false
+      expect(row[:why]).to match(%r{1/3})
+
+      PWN::Migrate.run(fix: true, backup: false, io: io)
+      kept = File.readlines(path)
+      expect(kept.length).to eq(2)
+      kept.each { |l| expect { JSON.parse(l) }.not_to raise_error }
+    end
+
+    it 'detects legacy flat skills and converts them (fix: :skills)' do
+      sroot = File.join(@tmp, 'skills')
+      FileUtils.mkdir_p(sroot)
+      File.write(File.join(sroot, 'legacy_probe.md'), "# legacy\n\nBody line.\n")
+      row = PWN::Migrate.status[:files].find { |f| f[:rel] == 'skills/' }
+      expect(row[:ok]).to be false
+
+      PWN::Migrate.run(fix: true, backup: false, io: io)
+      expect(File).to exist(File.join(sroot, 'legacy-probe', 'SKILL.md'))
+      expect(Dir.glob(File.join(sroot, '*.md'))).to be_empty
+    end
+
+    it 'deep_defaults never overwrites a user value' do
+      user = { ai: { active: 'anthropic', anthropic: { key: 'sk-LIVE' } } }
+      tmpl = PWN::Config.env_template
+      merged = PWN::Migrate.send(:deep_defaults, user: user, tmpl: tmpl)
+      expect(merged[:ai][:active]).to eq('anthropic')            # user wins
+      expect(merged[:ai][:anthropic][:key]).to eq('sk-LIVE')     # user wins
+      expect(merged[:ai][:anthropic]).to have_key(:model)        # backfilled
+      expect(merged[:ai]).to have_key(:agent)                    # whole subtree backfilled
+      expect(merged).to have_key(:cron)                          # top-level backfilled
+    end
+
+    it 'missing_paths reports dotted keys absent from a stale user vault' do
+      stale = { ai: { active: 'grok', grok: { key: 'x' } } }
+      miss  = PWN::Migrate.send(:missing_paths, tmpl: PWN::Config.env_template, user: stale)
+      expect(miss).to include('ai.agent')
+      expect(miss).to include('memory')
+      expect(miss).not_to include('ai.active')
+    end
+
+    it 'dry_run writes nothing' do
+      r = PWN::Migrate.run(fix: true, backup: true, dry_run: true, io: io)
+      expect(r[:dry_run]).to be true
+      expect(File).not_to exist(File.join(@tmp, '.schema'))
+      expect(Dir.glob(File.join(@tmp, 'backup', '*'))).to be_empty
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,5 +1,40 @@
 # frozen_string_literal: true
 
 require 'pwn'
+require 'stringio'
 
 Dir[File.join(__dir__, 'support', '**', '*.rb')].each { |f| require f }
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Keep `rake` output clean.
+#
+#  RSpec binds its formatter to $stdout at configure-time (before any example
+#  runs), so redirecting $stdout / $stderr *inside* each example swallows any
+#  incidental `puts` / `print` / `p` / `warn` emitted by the code under test
+#  WITHOUT affecting the progress dots or failure reports.
+#
+#  Escape hatches:
+#    - `PWN_SPEC_VERBOSE=1 rake spec`               → no redirection at all
+#    - `it '...', :stdout do ... end`               → per-example opt-out
+# ─────────────────────────────────────────────────────────────────────────────
+RSpec.configure do |config|
+  next if ENV['PWN_SPEC_VERBOSE']
+
+  original_stdout = $stdout
+  original_stderr = $stderr
+  devnull = StringIO.new
+
+  config.before(:each) do |example|
+    next if example.metadata[:stdout]
+
+    devnull.truncate(0)
+    devnull.rewind
+    $stdout = devnull
+    $stderr = devnull
+  end
+
+  config.after(:each) do
+    $stdout = original_stdout
+    $stderr = original_stderr
+  end
+end

data/spec/support/sandbox.rb

@@ -49,6 +49,12 @@ RSpec.shared_context 'pwn tmp sandbox' do
       stub_const(const, File.join(@tmp, rel)) if Object.const_defined?(owner)
     end
     stub_const('PWN::MemoryIndex::INDEX_FILE', File.join(@tmp, 'memory.idx')) if defined?(PWN::MemoryIndex)
+    if defined?(PWN::Migrate)
+      stub_const('PWN::Migrate::PWN_ROOT', @tmp)
+      stub_const('PWN::Migrate::SCHEMA_FILE', File.join(@tmp, '.schema'))
+      stub_const('PWN::Migrate::BACKUP_ROOT', File.join(@tmp, 'backup'))
+      stub_const('PWN::Migrate::QUARANTINE_DIR', File.join(@tmp, 'quarantine'))
+    end
 
     # Controllable env — module_reflection OFF so nothing hits an engine.
     @agent_cfg = {}

data/third_party/pwn_rdoc.jsonl

@@ -908,6 +908,7 @@
 {"messages":[{"role":"user","content":"PWN::Bounty::LifecycleAuthzReplay.write_yaml Usage"},{"role":"assistant","content":"`PWN::Bounty::LifecycleAuthzReplay.write_yaml`: "}]}
 {"messages":[{"role":"user","content":"PWN::Config.authors Usage"},{"role":"assistant","content":"`PWN::Config.authors`: Author(s)\n\n0day Inc. <support@0dayinc.com>\n"}]}
 {"messages":[{"role":"user","content":"PWN::Config.default_env Usage"},{"role":"assistant","content":"`PWN::Config.default_env`: Supported Method Parameters\n\nenv = PWN::Config.default_env(\n\npwn_env_path: 'optional - Path to pwn.yaml file.  Defaults to ~/.pwn/pwn.yaml'\n\n)\n"}]}
+{"messages":[{"role":"user","content":"PWN::Config.env_template Usage"},{"role":"assistant","content":"`PWN::Config.env_template`: Supported Method Parameters\n\ntmpl = PWN::Config.env_template\n\nThe canonical current-release ~/.pwn/pwn.yaml shape as a pure Hash (no I/O, no vault write, no puts).  Single source of truth used by:\n\n* PWN::Config.default_env      — seed a fresh ~/.pwn/pwn.yaml\n* PWN::Migrate.vault_drift     — diff a user vault against this release\n* PWN::Migrate.backfill_vault  — deep-merge missing keys UNDER the\n  user values on `pwn setup --migrate --fix`\n"}]}
 {"messages":[{"role":"user","content":"PWN::Config.help Usage"},{"role":"assistant","content":"`PWN::Config.help`: "}]}
 {"messages":[{"role":"user","content":"PWN::Config.init_driver_options Usage"},{"role":"assistant","content":"`PWN::Config.init_driver_options`: Supported Method Parameters\n\nenv = PWN::Config.init_driver_options\n"}]}
 {"messages":[{"role":"user","content":"PWN::Config.load_memory Usage"},{"role":"assistant","content":"`PWN::Config.load_memory`: Supported Method Parameters\n\nPWN::Config.load_memory\n"}]}
@@ -1047,6 +1048,28 @@
 {"messages":[{"role":"user","content":"PWN::MemoryIndex.save_index Usage"},{"role":"assistant","content":"`PWN::MemoryIndex.save_index`: "}]}
 {"messages":[{"role":"user","content":"PWN::MemoryIndex.sha Usage"},{"role":"assistant","content":"`PWN::MemoryIndex.sha`: "}]}
 {"messages":[{"role":"user","content":"PWN::MemoryIndex.to_context Usage"},{"role":"assistant","content":"`PWN::MemoryIndex.to_context`: Supported Method Parameters\n\nctx = PWN::MemoryIndex.to_context(query:, limit: 6)\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.apply_fix Usage"},{"role":"assistant","content":"`PWN::Migrate.apply_fix`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.authors Usage"},{"role":"assistant","content":"`PWN::Migrate.authors`: Author(s)\n\n0day Inc. <support@0dayinc.com>\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.backfill_vault Usage"},{"role":"assistant","content":"`PWN::Migrate.backfill_vault`: Supported Method Parameters\n\nr = PWN::Migrate.backfill_vault(\n\nkey: 'optional', iv: 'optional', dry_run: false, io: $stdout\n\n)\n\nDecrypt → deep-merge template UNDER user (never overwrites) →re-encrypt with the SAME key/iv.  This is the fix for the #1 upgrade break: ‘NoMethodError: undefined method ’[]‘ for nil` when a release added `env[:new_engine]` and the user’s vault predates it.\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.backup! Usage"},{"role":"assistant","content":"`PWN::Migrate.backup!`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.check Usage"},{"role":"assistant","content":"`PWN::Migrate.check`: Supported Method Parameters\n\nPWN::Migrate.check(\n\nio: 'optional - IO to write the report to (default $stdout)'\n\n)\n\nHuman-readable ~/.pwn state doctor.  Read-only.  Called from PWN::Setup.check so ‘pwn setup` shows this alongside the native-gem / toolchain report.\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.decryptor Usage"},{"role":"assistant","content":"`PWN::Migrate.decryptor`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.deep_defaults Usage"},{"role":"assistant","content":"`PWN::Migrate.deep_defaults`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.env_template Usage"},{"role":"assistant","content":"`PWN::Migrate.env_template`: Supported Method Parameters\n\ntmpl = PWN::Migrate.env_template\n\nThe canonical current-release pwn.yaml shape, WITHOUT the I/O side-effects of PWN::Config.default_env.  Prefers PWN::Config.env_template when that refactor is present.\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.help Usage"},{"role":"assistant","content":"`PWN::Migrate.help`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.human_size Usage"},{"role":"assistant","content":"`PWN::Migrate.human_size`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.installed_schema Usage"},{"role":"assistant","content":"`PWN::Migrate.installed_schema`: Supported Method Parameters\n\nschema = PWN::Migrate.installed_schema\n\n→ Integer schema number stamped in ~/.pwn/.schema (0 when absent).\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.jsonl_verify Usage"},{"role":"assistant","content":"`PWN::Migrate.jsonl_verify`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.missing_paths Usage"},{"role":"assistant","content":"`PWN::Migrate.missing_paths`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.needed? Usage"},{"role":"assistant","content":"`PWN::Migrate.needed?`: Supported Method Parameters\n\nbool = PWN::Migrate.needed?\n\nCheap predicate for PWN::Config.refresh_env — schema stamp only, no per-file probes, so it adds ~0 to launch time.\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.quarantine! Usage"},{"role":"assistant","content":"`PWN::Migrate.quarantine!`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.run Usage"},{"role":"assistant","content":"`PWN::Migrate.run`: Supported Method Parameters\n\nreport = PWN::Migrate.run(\n\nfix:     'optional - also autofix incompatible files (default: schema-migrations only)',\nbackup:  'optional - take timestamped backup of ~/.pwn first (default true)',\ndry_run: 'optional - report what WOULD happen, write nothing (default false)',\nkey:     'optional - vault key   (default: read ~/.pwn/pwn.yaml.decryptor)',\niv:      'optional - vault iv    (default: read ~/.pwn/pwn.yaml.decryptor)',\nio:      'optional - IO to write to (default $stdout)'\n\n)\n\nbackup  2. schema migrations installed→current  3. per-file\n\n\nautofix (when fix:true)  4. pwn.yaml key backfill (when fix:true and decryptor available)  5. stamp .schema.\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.safe_read Usage"},{"role":"assistant","content":"`PWN::Migrate.safe_read`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.stamp! Usage"},{"role":"assistant","content":"`PWN::Migrate.stamp!`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.status Usage"},{"role":"assistant","content":"`PWN::Migrate.status`: Supported Method Parameters\n\nrows = PWN::Migrate.status\n\nPer-file compatibility report — the machine-readable half of ‘.check`.  Never writes.  Never raises (each verifier is rescued).\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.strip_bad_jsonl! Usage"},{"role":"assistant","content":"`PWN::Migrate.strip_bad_jsonl!`: "}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.vault_drift Usage"},{"role":"assistant","content":"`PWN::Migrate.vault_drift`: Supported Method Parameters\n\ndrift = PWN::Migrate.vault_drift(\n\nkey: 'optional - vault key', iv: 'optional - vault iv'\n\n)\n\nDeep-diff the user’s decrypted pwn.yaml against the current PWN::Config.env_template.  → { missing: [dotted.paths], user: {…} } Returns nil when the decryptor is unavailable (never prompts).\n"}]}
+{"messages":[{"role":"user","content":"PWN::Migrate.verify_one Usage"},{"role":"assistant","content":"`PWN::Migrate.verify_one`: "}]}
 {"messages":[{"role":"user","content":"PWN::Plugins.authors Usage"},{"role":"assistant","content":"`PWN::Plugins.authors`: Author(s)\n\n0day Inc. <support@0dayinc.com>\n"}]}
 {"messages":[{"role":"user","content":"PWN::Plugins.help Usage"},{"role":"assistant","content":"`PWN::Plugins.help`: "}]}
 {"messages":[{"role":"user","content":"PWN::Plugins::Android.adb_net_connect Usage"},{"role":"assistant","content":"`PWN::Plugins::Android.adb_net_connect`: Supported Method Parameters\n\nPWN::Plugins::Android.adb_net_connect(\n\nadb_path: 'required - path to adb binary',\ntarget: 'required - target host or IP to connect',\nport: 'optional - defaults to tcp 5555'\n\n)\n"}]}
@@ -2149,6 +2172,7 @@
 {"messages":[{"role":"user","content":"PWN::Setup.gem_loadable? Usage"},{"role":"assistant","content":"`PWN::Setup.gem_loadable?`: "}]}
 {"messages":[{"role":"user","content":"PWN::Setup.help Usage"},{"role":"assistant","content":"`PWN::Setup.help`: "}]}
 {"messages":[{"role":"user","content":"PWN::Setup.list_profiles Usage"},{"role":"assistant","content":"`PWN::Setup.list_profiles`: Supported Method Parameters\n\nPWN::Setup.list_profiles(\n\nio: 'optional - IO to write to (default $stdout)'\n\n)\n"}]}
+{"messages":[{"role":"user","content":"PWN::Setup.migrate Usage"},{"role":"assistant","content":"`PWN::Setup.migrate`: Supported Method Parameters\n\nPWN::Setup.migrate(\n\nfix:     'optional - also autofix incompatible ~/.pwn files (default false)',\ndry_run: 'optional - print what WOULD happen (default false)',\nyes:     'optional - alias for fix:true (CI-friendly)',\nio:      'optional - IO to write to (default $stdout)'\n\n)\n\nDelegate to PWN::Migrate.run — verify every ~/.pwn state file is compatible with THIS pwn release and (optionally) autofix it.  A timestamped backup of ~/.pwn is taken first.  See ‘PWN::Migrate.help`.\n"}]}
 {"messages":[{"role":"user","content":"PWN::Setup.pkg_manager Usage"},{"role":"assistant","content":"`PWN::Setup.pkg_manager`: Supported Method Parameters\n\nPWN::Setup.pkg_manager\n"}]}
 {"messages":[{"role":"user","content":"PWN::Setup.which Usage"},{"role":"assistant","content":"`PWN::Setup.which`: "}]}
 {"messages":[{"role":"user","content":"PWN::WWW.authors Usage"},{"role":"assistant","content":"`PWN::WWW.authors`: Author(s)\n\n0day Inc. <support@0dayinc.com>\n"}]}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pwn
 version: !ruby/object:Gem::Version
-  version: 0.5.635
+  version: 0.5.636
 platform: ruby
 authors:
 - 0day Inc.
@@ -2040,6 +2040,7 @@ files:
 - lib/pwn/ffi/volk.rb
 - lib/pwn/memory.rb
 - lib/pwn/memory_index.rb
+- lib/pwn/migrate.rb
 - lib/pwn/plugins.rb
 - lib/pwn/plugins/android.rb
 - lib/pwn/plugins/assembly.rb
@@ -2489,6 +2490,7 @@ files:
 - spec/lib/pwn/ffi_spec.rb
 - spec/lib/pwn/memory_index_spec.rb
 - spec/lib/pwn/memory_spec.rb
+- spec/lib/pwn/migrate_spec.rb
 - spec/lib/pwn/plugins/android_spec.rb
 - spec/lib/pwn/plugins/assembly_spec.rb
 - spec/lib/pwn/plugins/authentication_helper_spec.rb