pwn 0.5.783 → 0.5.784

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43f675e7e241c2f9c2ac2b96c52b43259b337871bc3227fb2cbac832457f7f23
-  data.tar.gz: c053c15cff377d88ee43b25103203928eaa037c3bca976fd6d6483d5543ad5fd
+  metadata.gz: 41b180063b404ae6511a5df181eb969dcf2970b1ac128225369d6ec69afb30cc
+  data.tar.gz: 7936dc0f2c4552327650e74f3f0af790da4fbd353ca5d48cb651542d3f550acd
 SHA512:
-  metadata.gz: eca4d79da6a33b24ec42cbc39c7c07afd0cfec053f98a49655b2bd6ef3c93bbba32f91aa90e755fe88eb8ec7bb13db892f87ade9e6b715b2d14f0b867415e576
-  data.tar.gz: 8c8dad0dd07d97a0b4941fadf03683dd14cfe7fe045c06431d7f725c39ea4dadaac76988a722efaa9186abe71fa4ba731b95c8ae0fa58b1efd0d7baa367f45b1
+  metadata.gz: 1184f82a572f136b6421f04059b5e05e79642e7f68337f376392c816aeb023b0bd0d74c15f0916c84078ad7188d255f0776ac04d2a87cbb31e9ee8fa59e6dc16
+  data.tar.gz: 851035353589425ab5ff5fdefb04c9c2a1f2c91fce7cb5d1e02067bd0eebb16905284bbf6cd7cde6373fa2ea9b7b1f6dbf531089ee9319988bd62ec7e83cdeb1

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,7 +49,7 @@ 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 'mcp', '1.8.2'
 gem 'meshtastic', '0.0.189'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.26.0'
@@ -94,7 +94,7 @@ gem 'selenium-webdriver', '4.51.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/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_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/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/Backup-Retention.md

@@ -0,0 +1,27 @@
+# Historical migration backup retention
+
+## Explicit legacy diagnostic and generated-copy expiry
+
+`PWN::SessionCleanup.expire_legacy` is a separate, explicit maintenance entry point, defaulting to a preview. Apply requires `dry_run: false` and a **new external** `manifest:` path for one compressed metadata ledger; it does not archive payloads back into the managed home or run session/swarm retirement.
+
+Only recognized expired closed request logs, the exact `learning.jsonl.bak-lean-YYYYMMDD` and `preferences.jsonl.bak-p15-YYYYMMDDhhmmss` recovery families, and verified duplicate BinaryParser triage caches qualify. Root recovery retains at least the latest three nonempty parseable copies per family, all literal reference pins, and copies younger than thirty days. Cache expiry requires byte-identical retained ArtifactRegistry evidence; absent inputs are not claimed reproducible. Decompiler stdout caches are not adopted by this policy.
+
+The operation holds the canonical maintenance lock, rejects unsafe path/inode identities, checks retained references without exposing content, and checks process descriptors before classification and unlink. Existing producer leases must be available. Retained recovery/evidence proofs and candidate hashes are rechecked before unlink. An unreadable process inventory fails closed; do not bypass it when an older client is active. Coordinate any legacy writers before applying, and keep the learning producer lock during root recovery expiry. The external ledger records prepared versus completed state; it is not an undo archive. Existing immutable workers require a separately verified matched release before this entry point is deployed; it is not automatically enabled by importing the source.
+
+## Migration generations
+
+Migration backups are recovery generations, not an indefinite archive of every distinct historical byte. `PWN::Migrate.prune_backups` stays duplicate-only until an operator explicitly authorizes historical expiry. Its optional `expire_history: true` argument or private `~/.pwn/backup/.retention-policy.json` enables generation retention:
+
+```json
+{"version":1,"expire_history":true,"keep":3,"pins":[]}
+```
+
+`keep` cannot be less than three. `pins` contains exact timestamp generation directory names. Current structured evidence paths and prepared/interrupted or explicitly pinned maintenance records also retain their referenced generations. Quoted directory inventories and historical prose are not evidence dependencies. No logs, metrics, or historical learning versions are copied aside merely because their bytes are unique.
+
+Before expiry, the newest retained point must cover every existing current migration-owned input path, and current encrypted configuration and decryptor bytes must match retained recovery copies. Every retained and expiring payload is hashed, current inputs and references are rechecked, symlinks are rejected, and deletion shares the snapshot producer's permanent `.retention.lock`. The ordinary maintenance transaction supplies its own maintenance lock and cooperative work admission. Manual backup-only calls must also coordinate live writers before apply. Default automatic batches consider at most ten older generations; exhausted admission defers expiry rather than weakening protection.
+
+The single mode-0600 `.retention-manifest.json.gz` contains prepared/committed inventories and expiry names, not a second payload tree. Older unpinned versions are permanently expired: that manifest is an audit record, not an undo payload. Incomplete historical snapshots are never retrospectively certified complete. Their extant payloads can be verified for bounded recovery; the newly produced complete snapshot establishes current coverage. Restore by **copying only migration-owned paths**, not overlaying an entire old home, and never edit hardlinked backup bytes in place. Keep explicit pins for any recovery boundary needed during an active migration.
+
+Scheduled retention is called by the managed v10 `SessionCleanup.maintain` helper through PWN's internal cron worker. No native scheduler or systemd installation is needed. Use `PWN::Migrate.prune_backups(dry_run: true)` for a strictly backup-only preview; do not invoke full session maintenance to test backup expiry. When no generation can expire, this preview avoids scanning evidence bodies and reports `evidence_scan: not_needed_no_expiry`; it is not a fresh payload-integrity audit.
+
+An isolated maintenance release may coexist with older interactive clients: run the worker from the release's immutable `lib` load path, verify source/release/live-helper SHA-256 equality, and leave the active gem and clients untouched. The cron helper does not retrofit methods into those clients. A later normal application upgrade is separate from this scoped maintenance deployment.

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 three enabled housekeeping defaults below use only this existing worker
+or manual commands. `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/How-PWN-Works.md

@@ -20,7 +20,7 @@ hardware).
 | `pwn --ai PROMPT` | `bin/pwn` | Headless one-shot agent (CI-friendly) |
 | `pwn setup` | `lib/pwn/setup.rb` · `bin/pwn_setup` | Post-install doctor + capability provisioner + `--migrate` state doctor (also `pwn --setup[=PROFILE]`) |
 | `bin/` (including `pwn-ai` and `pwn-capd`) | 56 files | Thin OptionParser wrappers plus the `pwn` REPL / one-shot agent |
-| `PWN::Cron` | `lib/pwn/cron.rb` | Scheduled jobs + background worker (`pwn setup`). Fresh install seeds hygiene on (`learning_consolidate_nightly`, `pwn_stores_lean_nightly`) and curriculum practice/judge/train off |
+| `PWN::Cron` | `lib/pwn/cron.rb` | Scheduled jobs + background worker (`pwn setup`). Fresh install seeds one `session_cleanup` housekeeping coordinator; curriculum schedules require explicit creation. Existing schedules are preserved |
 
 ## L2 - AI agent core (`lib/pwn/ai/agent/`)
 

data/documentation/Installation.md

@@ -1,5 +1,190 @@
 # Installation
 
+## Housekeeping deployment and diagnostics
+
+The packaged `etc/default_cron/session_cleanup.rb` is the shared implementation
+for `/maintenance run`, `/maintenance dry-run`, `/sessions cleanup`, and the
+managed `session_cleanup` cron job. `/maintenance status` reports physical file
+counts, bytes, configured retention, budgets, incomplete scans and safe error
+classes. These are storage counts, not the session menu's pagination count.
+Curses executes maintenance on its existing command worker, not its render/input
+thread. Ctrl+C requests a safe boundary; committed work is not rolled back.
+
+Upgrade the installed gem, run `pwn setup --migrate --fix`, then restart PWN
+clients **and the existing cron worker**. Source-checkout edits alone do not
+update installed endpoints. Schema 11 seeds a version-1 housekeeping policy and
+refreshes the managed helper. Existing job IDs, schedules, disabled states,
+custom Ruby payloads, custom unmarked helpers and policy edits are preserved.
+A custom helper is not automatically upgraded. Fresh setup is idempotent and
+registration never runs cleanup; the default job retains its next-slot guard.
+Startup performs fixed-path checks and coalesces a daily background request in
+`maintenance/background.json`. The existing cron worker consumes it through the
+existing enabled job, never through a second worker. Disabled jobs stay disabled.
+Do not apply maintenance while old untracked clients are running: unknown
+legacy ownership blocks mutation rather than guessing which sessions are active.
+
+Storage is organized into logical categories without relocating literal evidence
+anchors:
+
+| Category | Existing/new locations under `~/.pwn` | Retention contract |
+|---|---|---|
+| sessions | `sessions/` including support and requests | Eligible unsummarized, inactive, unreferenced transcripts only; physical deletion with backups |
+| learning | `learning.jsonl`, `learning/`, `memory*.json`, `mistakes.json`, policy/curriculum/extrospection stores, finetune and preference records | Evidence migration retains exact verified snapshots; unknown records remain protected |
+| artifacts | `artifacts/`, `exports/`, `findings.jsonl`, engagements, corpora and binary workspaces | Durable evidence, not disposable cache |
+| state | `swarm/`, `cron/`, `agents.yml`, `jobs/`, `missions/`, `runs/`, metrics | Preserve continuation associations and active work |
+| logs | `logs/` | Only explicitly registered disposable closed logs are eligible; unknown logs remain |
+| cache | `cache/` | Only producer-registered, checksum-verified, inactive disposable files |
+| tmp | `tmp/` | Same registration contract; never glob-delete arbitrary temp files |
+| maintenance | `maintenance/`, legacy `session_cleanup_archive/` | Policy, permanent locks, metadata ledgers and recoverable quarantine |
+
+`maintenance/policy.json` is non-secret JSON, version 1. `batch_size` defaults to
+100; `scan_limit` to 100000. Cooperative admission defaults to `work_items: 100000`,
+`work_seconds: 30` and `work_bytes: 67108864` for dependency and maintenance
+payload reads, plus reserved disposable backup writes. Existing policy
+files acquire these defaults in memory, without rewriting operator values.
+`maintenance/layout.json` upgrades recognized inventory v1 to v2 separately from
+policy; unknown inventory versions are refused. `retention_days` defaults to sessions 0, logs 30,
+cache 7, tmp 1, maintenance 90. Null disables that category's expiry. Session
+age is an additional floor, never an override of leases, provenance or evidence.
+Learning/artifacts/state remain non-expiring: their policy slots are descriptive,
+not authorization to erase evidence. `budget_bytes` enforces pressure eviction
+for verified inactive disposable files (logs 256 MiB, cache 512 MiB, tmp 256 MiB,
+maintenance 1 GiB), including before ordinary expiry. Null retention still
+disables deletion. Budgets never evict protected evidence. Over-budget protected storage needs
+operator review, not automatic deletion. Inventory scans are bounded and report
+incompleteness rather than claiming a complete total. `bytes` counts logical file
+bytes; `unique_bytes` counts each inode once per category. Directory discovery is
+streamed for inventory and dependency trees. Work/time admission is cooperative
+between phases and items, not a hard deadline: an admitted read, hash or atomic
+commit completes. Exhausted/partial dependency indexes block deletion and report
+`incomplete`/`interrupted`. Retrying recomputes dependencies; no timeout kills a writer.
+Disposable cleanup reserves the complete payload transaction before its first
+hash: one bounded read for preview, or five payload-size passes for verification,
+backup read/write, backup verification and final source verification on apply.
+Reads reject size changes and cannot follow unlimited concurrent growth. Quarantine,
+legacy-backup inventory/compaction, atomic-temp recovery and transaction-status
+reads also use byte admission. Policy/cursor metadata and durable ledger writes
+are control overhead, not a hard total-filesystem-I/O quota; directory name
+discovery is not a payload-byte allowance. An oversized item is retained, with
+the overall maintenance run marked `incomplete`/`interrupted`; raise the explicit
+work budget to process it. Once admitted, backup/commit finishes even if the
+deadline expires mid-write.
+
+Producer integration uses `PWN::SessionCleanup.register_disposable(path:,
+category:, expires_at:)` after closing a reproducible file. Producers must hold
+its permanent `<path>.lease` exclusively while writing, and readers hold it
+shared throughout use. The registry records exact SHA-256, inode and byte count.
+Changed, unknown, symlinked, active and invalid files are retained with reasons.
+Disposable scans persist a lexical round-robin cursor in
+`maintenance/disposable.cursor`; `scan_limit` bounds inspected manifests per run.
+Completed/missing manifests remain for audit, including normal temporary-producer
+unlinks, but cannot monopolize later scans. Active/changed entries are revisited
+on the next circuit. The cursor is scheduling state only: cleanup never removes
+or relocates registry entries, and rechecks registration bytes under the producer
+lease so a concurrent renewal cannot authorize deletion using an old expiry.
+Dry-run does not advance the cursor. A partial circuit reports `incomplete`.
+Registration is not permission to classify evidence as disposable. Legacy caches
+and logs are not implicitly registered. Transcript compaction/append instead use
+a permanent transcript `.write.lock`; compaction temporary files are unique,
+cleaned in ensure, fsynced and atomically replaced. Corrupt transcripts raise,
+not silently compact into partial transcripts.
+
+Ghidra decompile and BinaryParser triage now publish and read their canonical
+caches under permanent leases. Ordinary `Log.append` diagnostics now go to
+`logs/pwn.log`, rotating at 1,024,000 bytes into registered closed segments.
+Debug streams hold a lifetime lease and register after request closure; active
+streams cannot be evicted. Historical `/tmp/pwn.log` and learning logs are not
+implicitly deleted. Cache writes and transcript compaction clean their own
+temporary outputs on failure rather than leaving routine temp garbage.
+
+Routine disposable cleanup writes exact private backups and prepared/committed
+ledgers under `maintenance/quarantine/`. Only verified committed disposable
+backups expire after the maintenance retention period or under budget pressure.
+Interrupted `expiry_prepared` operations resume from verified remaining backups.
+Broad operations also have prepared/committed/interrupted metadata ledgers under
+`maintenance/runs/`, exposed by status. Prepared/corrupt ledgers
+and unique evidence are never expired. `prune_legacy_backups` recognizes actual
+committed session snapshots, dependency-removal backups, learning migration and
+continuation-retirement ledgers. After retention or under maintenance pressure it
+reclaims **redundant physical bytes** using checksum/readback-verified atomic
+hardlink replacement. Recovery filenames remain intact; the last copy is never
+removed. Unknown/uncommitted records are excluded. A cross-filesystem link failure
+retains the original. Prepared/committed compaction journals are resumable.
+
+`PWN::SessionCleanup.recovery_status(ledger: absolute_ledger_path)` identifies
+supported actions. `recover(ledger:, action:, dry_run: true)` is explicit:
+- `restore`: quarantine or legacy session copies, with no overwrite of different bytes;
+- `rollback`: Learning's validated rollback or an unchanged continuation retirement;
+- `rollback_dependencies`: exact targeted store rollback, after restoring source sessions;
+- `resume`: re-evaluate broad maintenance, resume backup compaction, or re-evaluate
+  offline layout migration (apply requires `writers_stopped: true`).
+Use `dry_run: false` only after reviewing the plan. Restoring a metadata ledger
+never undoes data changes. Broad operations have independently committed children,
+not a fictitious all-or-nothing rollback. Unknown schemas require manual review.
+`reorganize` remains explicit and offline; this upgrade does not move existing paths.
+
+### Housekeeping acceptance ledger (isolated fixtures)
+
+`spec/lib/pwn/session_cleanup_recovery_spec.rb` exercises the actual maintenance
+entry point, without live stores or providers:
+
+| Requirement | Regression evidence | Boundary |
+|---|---|---|
+| Byte admission precedes disposable payload I/O | Expired 1 MiB cache with `work_bytes: 1024` remains intact; no payload read/hash or backup, run incomplete/interrupted | Cooperative allowance, not a hard filesystem-I/O cap |
+| Repeated bounded scans progress | `scan_limit: 1`, two expired caches and a normally unlinked temporary producer; repeated runs delete both caches and retain all manifests | Registry pathname discovery still enumerates names; inspection is bounded |
+| Active/mutated data remains protected | Held shared lease and changed payload survive while later eligible data is processed; released lease is revisited | Requires cooperating permanent producer leases |
+| Re-registration is not lost | Renewing the same file between discovery and lease acquisition retains it; republished cache survives a later cursor circuit | Cursor never moves/deletes registry records |
+| Admitted commit finishes safely | Deadline expires after backup publication; exact backup and committed child deletion survive, enclosing run is interrupted | Not all-or-nothing rollback |
+| Related quarantine reads respect admission | Expired 1 MiB backup exceeds an 8 KiB work allowance and remains committed/unexpired | Legacy/atomic paths also admit reads; their existing integrity/recovery regressions remain enabled |
+
+The completed isolated-HOME `bundle exec rake` gate passed 4,568 examples with
+zero failures and inspected 1,161 files with no RuboCop offenses (exit 0).
+Cancellation regressions distinguish preservation before deletion admission from
+completion of an already-admitted commit; redaction covers the canonical log and
+debug/progress/mirror/stderr/fallback sinks. These are fixture-based verification,
+not live deployment acceptance: no live-store maintenance, installed-helper
+deployment or provider run is implied.
+
+### Temporary producer ownership audit
+
+The audit covers `Dir.tmpdir`, `Tempfile`, `mktmpdir` and atomic replacement
+call sites, not a filesystem filename sweep:
+- Festival speech input now uses `SessionCleanup.temporary` in `~/.pwn/tmp`, with
+  a lifetime lease and exact registration. Concurrent calls have unique names;
+  normal completion unlinks the input and a crashed consumer leaves registered bytes.
+- Ghidra/BinaryParser canonical cache publication and managed temporary inputs
+  journal atomic ownership (inode/device, expected hash, exact target) under
+  `maintenance/atomic`. `recover_atomic_temps` rejects active writers, changed or
+  partial bytes, missing journals and unknown paths. Routine maintenance applies
+  retention; explicit recovery can inspect an abandoned journal immediately.
+- Sandbox/Detonate, GPS, RFID, OSINT bridge and GhidraHeadless work directories,
+  GDB stdin, and policy-evaluation/Solve verification trees are scoped block or
+  owner-cleaned resources. Old unregistered crash remnants are retained, not
+  inferred disposable from a prefix. GhidraHeadless's legacy/custom cache is not
+  silently enrolled as a canonical cache.
+- Nmap/Nuclei scan output, proxy HAR, browser screenshots, APK output, Workspace
+  downloads, history spill and Burp diagnostics may be unique evidence. Their
+  existing literal paths remain; no age-based global `/tmp` cleanup is authorized.
+- OAuth/vault/selection, learning/session/map and SDR image atomic outputs may be
+  only-copy state or evidence. Their own ensure/rollback protocols remain; unknown
+  remnants are not automatically discarded. Solve lock inodes are permanent.
+This is an intentional ownership/evidence boundary, not a claim that every plugin
+scratch file is automatically reclaimable.
+
+Swarm registry retirement alone deliberately keeps its saved conversation.
+The command route exposes `/swarm retire NAME --continuation` explicitly.
+`PWN::AI::Agent::Swarm.retire(name:, swarm_id:, local: true, continuation: true)`
+explicitly retires the inactive association with a backup and prepared/committed
+ledger. It does not itself delete the transcript. A later persona request creates
+a new session; active associations cannot be retired. Persona map writers and
+cleanup share a permanent continuation lock.
+
+Safe checks: `/maintenance status` and `/maintenance dry-run` do not call a
+provider. Do not use `run` as a diagnostic on production data without reviewing
+the preview. Permission and disk failures retain recoverable bytes and report
+error classes; no blanket root-directory chmod is attempted.
+
+
 PWN ships as a **single Ruby gem** whose runtime is 100 % `autoload`ed -
 a plugin whose native extension or OS binary is missing costs nothing until
 you actually touch that constant. That means the install is **two steps**:
@@ -82,7 +267,7 @@ External toolchain                              used by
   skills/        drift  1 legacy flat file(s)   PWN::Config     → run --migrate --fix
   ...
 
-cron worker                 ok   systemd --user pid=...
+cron worker                 ok   internal worker pid=...
 
 31 / 36 capabilities usable · 5 degraded
 
@@ -196,9 +381,11 @@ predates the running gem (`PWN::Migrate.needed?`).
 Schema `v1` also seeds `PWN::Cron.install_defaults` - the nightly
 `curriculum_practice` and weekly `curriculum_train` self-improvement jobs
 (see [Reinforcement Learning](Reinforcement-Learning.md)). `pwn setup`
-also starts the background cron worker and persists it via the OS scheduler
-(systemd --user / launchd / schtasks / crontab) so those YAML jobs run
-without a per-job crontab line. Live Policy files (`policy.json`,
+also starts or reuses the single portable background cron worker. Setup,
+migration and startup seeding never install, enable, repair or remove OS
+scheduler units. Defaults live only in `~/.pwn/cron/jobs.yml`; the worker
+must be running for automatic execution (start it again after reboot with
+`pwn setup --cron`). Manual commands remain available without a worker. Live Policy files (`policy.json`,
 `policy_traj.jsonl`) are created on first agent turn when `ai.agent.policy`
 is on.
 
@@ -208,8 +395,40 @@ in the scheduler's local timezone. First launch also seeds it through
 is installed to `~/.pwn/cron/session_cleanup.rb`; managed copies refresh on
 subsequent launches/migrations, while unmarked custom helpers are preserved.
 An existing job named `session_cleanup` keeps its ID, schedule, enabled state,
-payload and native scheduler drop-ins. New jobs defer cleanup until their first
-scheduled time, rather than deleting during initial catch-up.
+payload. Legacy native scheduler files are left untouched for an explicit
+operator-approved removal; they are never refreshed or re-enabled by setup.
+New jobs defer cleanup until their first scheduled time, rather than deleting
+during initial catch-up.
+
+Fresh installs now seed only this job, with `SessionCleanup.coordinate`: shared
+evidence-first maintenance, memory consolidation, then separate learning,
+mistakes and policy retention phases. Existing split maintenance schedules are
+preserved until explicitly consolidated after a safe matched-code deployment.
+Curriculum schedules require explicit creation; startup and repeat migrations
+never recreate deleted curriculum jobs. See [Cron](Cron.md) for opt-in templates
+and schedule-only deletion. Already-running old binaries must be upgraded before
+their startup/config-refresh hooks can be relied on to honor the new defaults.
+
+**Housekeeping never uses systemd or any other native scheduler.**
+`session_cleanup`, `learning_consolidate_nightly`, and `pwn_stores_lean_nightly`
+run only through PWN's built-in cron worker or manual commands. Native job
+installers explicitly skip them with `housekeeping_internal_only`; this also
+covers renamed payloads that invoke `SessionCleanup` or `session_cleanup.rb`.
+Generic scheduler APIs remain available for unrelated custom jobs. Native
+worker launchers mark their execution context and exclude housekeeping;
+legacy PWN systemd cgroups are also excluded. An inherited terminal
+`INVOCATION_ID` alone is not a scheduler context.
+
+Existing installations require an explicit operator decision before stopping
+legacy services or processes. Inventory `pwn-cron-*.timer` and `.service`, map
+job IDs to `jobs.yml`, preserve custom schedules, then (only with approval)
+disable and stop the housekeeping timers/services and the legacy shared
+worker service, archive their unit files/drop-ins, remove those exact files,
+and run the user manager's daemon-reload. Do not remove unrelated custom job
+units or change lingering globally. Coordinate old clients before deploying
+the new code, retain `jobs.yml` unchanged, then start/reuse one internal
+worker and verify its PID and guarded tick. Do not run cleanup to validate
+this transition or re-enable legacy housekeeping units.
 
 Cleanup calls a session named only when its persisted metadata has
 `title_source: summary`, a nonblank title and summary, and a positive integer
@@ -321,6 +540,19 @@ Loop requests and title writers hold independent leases, and crashes release
 descriptors automatically. Stale lock contents or reused PIDs confer no ownership.
 Never unlink lock files: that would split the synchronization inode.
 
+Routine maintenance supports multiple simultaneously running upgraded clients;
+there is no blanket shutdown requirement. Evidence migration takes exclusive
+nonblocking leases per source transcript through index publication, skips active
+sources (`evidence_migration.deferred_active_sessions`), and revisits them on a
+later run after their writers finish. Unrelated eligible sessions can still be
+removed. A busy Learning writer returns
+`evidence_migration.deferred: learning_writer_active` with `apply_blocked: true`
+rather than waiting or interrupting the writer; retry on a later cron tick or
+manual invocation. The permanent maintenance lock admits one applying owner;
+a second receives `Session maintenance already running` immediately. Title
+workers and durable job dependencies retain their existing protections.
+This is routine maintenance, not the explicitly offline layout migration.
+
 Old installed processes cannot be upgraded by refreshing the cron helper alone.
 `legacy_owners` reports launchers without the held PID/start-identity capability
 marker; `unknown_legacy_ownership` means their in-memory session IDs are unknown,
@@ -347,6 +579,15 @@ rake install                         # or: rvmsudo rake install (multi-user RVM)
 pwn setup --profile full --yes       # same provisioner, same data tables
 ```
 
+The `upgrade_pwn.sh` → `build_gem.sh` validation gate still runs through
+`rvmsudo` on multi-user RVM installations. Its merged stdout/stderr is streamed
+and retained in the invoking user's `~/.pwn/logs/build-gate.log` (mode 0600,
+last 1 MiB, replaced on the next gate). The path is printed before execution
+and on failure; installation does not continue after a failed gate. `rake spec`
+also prints each failure immediately and reports the RSpec child's exit status
+or signal, so a later terminated example cannot hide earlier failure details.
+A signal report is diagnostic evidence, not a claim about who sent the signal.
+
 The legacy `./install.sh` / `packer/provisioners/pwn.sh` bash paths still
 work, but they now simply delegate to `pwn setup` - the `case $os` package
 lists have been consolidated into `PWN::Setup::NATIVE_GEMS` / `::TOOLCHAIN`.

data/documentation/Persistence.md

@@ -26,7 +26,7 @@ external services and environment overrides can place evidence elsewhere.
 | `extrospection/voice/*` | `Extrospection` | wav / txt | `rm -rf` | TTS/STT artifacts from `extro_voice` |
 | `sessions/*.jsonl` | `PWN::Sessions` | JSON-per-line | `sessions_delete` | full transcript per pwn-ai run (with per-step `step_reward` from `Reward.prm`) |
 | `open_goal.json` | `PWN::AI::Agent::OpenGoal` | JSON | delete the file | unfinished host-work request so `continue` / `resume` picks it up |
-| `cron/jobs.yml` | `PWN::Cron` | YAML | `cron_remove` | scheduled jobs. Fresh install seeds hygiene (`learning_consolidate_nightly` + `pwn_stores_lean_nightly` **on**) and curriculum practice/judge/train **off** |
+| `cron/jobs.yml` | `PWN::Cron` | YAML | `cron_remove` | Scheduled jobs; fresh install seeds only the `session_cleanup` housekeeping coordinator. Curriculum schedules require explicit creation and are not recreated after deletion |
 | `cron/log/*.log` | `PWN::Cron` | text | rm | last_run output |
 | `agents.yml` | `PWN::AI::Agent::Swarm` | YAML | edit / `agent_spawn` | persona registry |
 | `swarm/<id>/bus.jsonl` | `Swarm` | JSON-per-line | rm -rf | append-only multi-agent chat |

data/documentation/Reinforcement-Learning.md

@@ -359,14 +359,13 @@ This is the live control list. Track the outcomes, not source comments.
 ```ruby
 # Seeded idempotently by PWN::Cron.install_defaults (pwn setup --migrate):
 PWN::Cron.install_defaults
-# -> curriculum_practice_nightly   0 3  * * *  Curriculum.practice(limit: 3)
-# -> curriculum_offline_judge     30 3  * * *  Curriculum.offline_judge(since_hours: 24, limit: 40)
-# -> curriculum_train_weekly       0 4  * * 0  Curriculum.train_and_gate(dry_run: true)  # false only with trainer+GPU
-# -> learning_consolidate_nightly  0 5  * * *  Learning.consolidate
+# -> session_cleanup  45 3 * * *  SessionCleanup.coordinate(dry_run: false)
 ```
 
-`install_defaults` treats the legacy name `offline_judge_nightly` as an alias of
-`curriculum_offline_judge` and will not double-seed the same slot.
+Curriculum practice, judge and training are explicit opt-ins, not seeded jobs.
+Select a template from `PWN::Cron::CURRICULUM_JOBS` and explicitly create it only
+when wanted (see [Cron](Cron.md)). Deletion survives repeated default installation
+and migration. Existing jobs and legacy aliases remain unchanged.
 `pwn setup` also starts the background cron worker so these YAML jobs fire
 without a per-job crontab line.