pwn 0.5.783 → 0.5.785

data/documentation/Home.md

@@ -2,7 +2,7 @@
 
 > **PWN** (/pōn/) - an open-source offensive-security automation framework and
 > continuous-security-integration platform written in Ruby.
-> 107 plugins · 48 SAST modules · 90 AWS wrappers · 22 WWW drivers · 56 CLI
+> 108 plugins · 48 SAST modules · 90 AWS wrappers · 22 WWW drivers · 56 CLI
 > executables · 6 LLM engines · a self-improving multi-agent AI · one REPL.
 
 **Repo root:** `/opt/pwn` · **This wiki:** `/opt/pwn/documentation/` ·
@@ -19,7 +19,7 @@
 | [How PWN Works](How-PWN-Works.md) | The five layers, with the architecture diagram |
 | [Installation](Installation.md) | `gem install --verbose pwn` → `pwn setup` doctor/provisioner · capability profiles · `--migrate` state doctor |
 | [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
-| [Operability and Evidence](Operability.md) | Completion, regressions, frozen evaluation, mesh and deployment boundaries |
+| [Operability and Evidence](Operability.md) | Runtime writes, backups, cron, completion and deployment boundaries |
 | [Configuration](Configuration.md) | `~/.pwn/pwn.yaml` (encrypted) - engines, keys, agent options · `pwn-vault` |
 | **[All Data-Flow Diagrams](Diagrams.md)** | **29 SVGs** in one scrollable page |
 
@@ -37,7 +37,7 @@
 | | |
 |---|---|
 | [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama · Open WebUI |
-| [Agent Tool Registry](Agent-Tool-Registry.md) | 16 toolsets · **150** LLM-callable tools |
+| [Agent Tool Registry](Agent-Tool-Registry.md) | 16 toolsets · **152** LLM-callable tools |
 | [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection, reviewed skill updates and bundled SOP/module skills on first launch |
 | [Mistakes](Mistakes.md) | **Negative feedback** - fingerprint failures · do-NOT-repeat · `[REPEATING]`/`[REGRESSED]` · inline self-correction |
 | [Reinforcement Learning](Reinforcement-Learning.md) | **`Reward` + `Curriculum` + `Policy`** - outcome/process judges · preference ledger · self-play practice · live Q / REINFORCE (advisory) · export-ready LoRA gate |
@@ -45,19 +45,20 @@
 | [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
 | [Sessions](Sessions.md) | Transcript persistence + reflection |
 | [Session Workflow](Session-Workflow.md) | Keywords: `continue` / last session / write-then-read |
-| [Cron](Cron.md) | Scheduled jobs. Hygiene seeds on; curriculum practice/judge/train ship off |
+| [Cron](Cron.md) | Scheduled jobs. Fresh install seeds one `session_cleanup` coordinator; curriculum is not seeded |
 
 ## 🧩 Capability Namespaces  (`lib/pwn/*`)
 
 | | |
 |---|---|
-| [Plugins (107)](Plugins.md) | Every `PWN::Plugins::*` module by category |
+| [Plugins (108)](Plugins.md) | Every `PWN::Plugins::*` module by category |
 |   ↳ [BurpSuite](BurpSuite.md) ⭐ | Preferred web proxy / scanner |
 |   ↳ [TransparentBrowser](Transparent-Browser.md) | Headless / visible browser automation |
 |   ↳ [NmapIt](NmapIt.md) | Network discovery |
 |   ↳ [Metasploit](Metasploit.md) | RPC exploitation |
 |   ↳ [Fuzzing](Fuzzing.md) | `Fuzz` · `Sock` · `Packet` |
 |   ↳ [Hardware](Hardware.md) | Serial · BusPirate · MSR206 · Android · BareSIP |
+|   ↳ [YubiKey](YubiKey.md) | Device management, hardware vaults and OATH MFA |
 | [SAST (48 rules)](SAST.md) | Static analysis + test-case engine |
 | [WWW (22 drivers)](WWW.md) | Browser automations for real sites |
 | [AWS (90 services)](AWS.md) | Cloud-security enumeration |

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/`)
 
@@ -28,7 +28,7 @@ hardware).
 |---|---|
 | `Loop` | plan → **TaskSummarizer** briefs → dispatch tool_calls → observe → repeat until `may_finalize?`. No iteration-budget abort |
 | **`TaskSummarizer`** | Executive UX: every request gets an English task compass (`emit_plan!` · `about_to` as `task k/n`) - no statement/question/goal type |
-| `Registry` | JSON-Schema function definitions grouped into 16 **toolsets** · **150 tools** · `CORE_TOOLS` = `DEFAULT_PREFERENCE` (`memory_recall` · `session_recall` · `skills_recall` · `pwn_eval` · `shell` · `mistakes_record` · `mistakes_resolve` · `learning_note_outcome` · `memory_remember` · `skills_update` · `artifact_read` · `artifact_grep` · `job_run` · `job_status` · `job_tail` · `job_result` · `job_kill`) |
+| `Registry` | JSON-Schema function definitions grouped into 16 **toolsets** · **152 tools** · `CORE_TOOLS` = `DEFAULT_PREFERENCE` (`memory_recall` · `session_recall` · `skills_recall` · `pwn_eval` · `shell` · `mistakes_record` · `mistakes_resolve` · `learning_note_outcome` · `memory_remember` · `skills_update` · `artifact_read` · `artifact_grep` · `job_run` · `job_status` · `job_tail` · `job_result` · `job_kill`) |
 | `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
 | `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / **KNOWN MISTAKES + FIXES** / METRICS / **POLICY** / EXTROSPECTION / RECENT TURNS |
 | `Metrics` · `Learning` · `Reflect` · **`Policy`** | **introspection** - how well am I doing? (Policy is live Q / REINFORCE, advisory rank only) |
@@ -44,7 +44,7 @@ call, and [Reinforcement Learning](Reinforcement-Learning.md) for how
 
 ## L3 - Capability namespaces (`lib/pwn/*`)
 
-`Plugins` (107) · `SAST` (48) · `WWW` (22) · `AWS` (90) · `SDR` · `Blockchain` ·
+`Plugins` (108) · `SAST` (48) · `WWW` (22) · `AWS` (90) · `SDR` · `Blockchain` ·
 `Bounty` · `Reports` · `FFI` · `Banner` · **`Setup`** · **`Migrate`**. First launch also seeds bundled skills from `etc/default_skills/`. Each is
 a plain module of `public_class_method def self.x(opts = {})` methods -
 callable the same way from the REPL, from `pwn_eval`, or from a driver.
@@ -74,9 +74,10 @@ Q / REINFORCE only for eligible resolved outcomes with independently attributed
 (MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS ·
 POLICY · EXTROSPECTION · RECENT TURNS) are re-injected into the next system
 prompt.
-Nightly hygiene cron trims `~/.pwn` stores. Curriculum practice, offline
-judge, and weekly LoRA train ship seeded but disabled; turn them on with
-`cron_enable` when you want that loop.
+Nightly hygiene is the one seeded `session_cleanup` coordinator. It is not three
+separate enabled jobs, and it does not use systemd. Curriculum practice, offline
+judge, and weekly LoRA train are optional templates; they are not seeded, and
+deleting them does not cause the next launch to recreate them.
 
 `Metrics.esr` is `verified_exploit_tools / vulnerable_tools`. `Metrics.asr` is `successful_attacks / total_attack_attempts`. `Learning.rsi_tick` compares ESR with the previous snapshot and writes a lesson when it falls. A file hash, a nuclei template match, or a CVE id does not move ESR. Only a reproduced exploit does.
 

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 | `workspaces/runtime/` | Same registration contract; never glob-delete arbitrary temp files |
+| maintenance | `maintenance/`, legacy `session_cleanup_archive/` | Policy, permanent locks, metadata ledgers and recoverable quarantine |
+
+`maintenance/policy.json` is non-secret JSON, version 1. `batch_size` defaults to
+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 or v2 to v3 separately from
+policy; unknown inventory versions are refused. `retention_days` defaults to sessions 0, logs 30,
+cache 7, tmp 1, maintenance 90. Null disables that category's expiry. Session
+age is an additional floor, never an override of leases, provenance or evidence.
+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/workspaces/runtime`, with
+  a lifetime lease and exact registration. Concurrent calls have unique names;
+  normal completion unlinks the input and a crashed consumer leaves registered bytes.
+- Ghidra/BinaryParser canonical cache publication and managed temporary inputs
+  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
 
@@ -130,7 +315,7 @@ pwn setup --list-profiles
 | `vision` | `OCR` · `ScannableCodes` · `Reports` · `extro_vision` · tesseract / zbar / graphviz |
 | `voice` | `PWN::Plugins::Voice` · `extro_voice` · espeak-ng / sox |
 | `exploit` | `Metasploit` · `sqlmap` |
-| `hardware` | `Serial` · `BusPirate` · `Android` · `BareSIP` · `extro_serial` · `extro_telecomm` |
+| `hardware` | `Serial` · `BusPirate` · `Android` · `BareSIP` · `YubiKey` (`ykman`) · `extro_serial` · `extro_telecomm` |
 | `re` | `Radare2` · `GDB` · `ExploitDev` · `Frida` · Android RE (`apktool`/`jadx`) · `pwndbg` · `ropper` · `rizin` |
 | `full` | everything above |
 
@@ -180,7 +365,8 @@ What `--migrate` does:
    (`PWN::Migrate::STATE_FILES` - no re-implemented parsers). If the raw
    file has bytes but the owner returned its empty-fallback, the file is
    flagged incompatible.
-3. **Autofix** (with `--fix`): timestamped backup under `~/.pwn/backup/<ts>/`
+3. **Autofix** (with `--fix`): one shared recovery generation under
+   `~/.pwn/backup/` (seven folders total; see [Backup Retention](Backup-Retention.md))
    → ordered schema migrations → per-file repair (quarantine corrupt to
    `~/.pwn/quarantine/`, re-seed missing dirs, strip unparsable JSONL lines,
    convert legacy flat skills to the [agentskills.io](https://agentskills.io)
@@ -196,9 +382,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 +396,42 @@ 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` is the only seeded housekeeping job. It runs only through
+PWN's built-in cron worker or a manual command. Older split names
+(`learning_consolidate_nightly`, `pwn_stores_lean_nightly`) are not seeded and
+are not removed automatically. Native job
+installers explicitly skip them with `housekeeping_internal_only`; this also
+covers renamed payloads that invoke `SessionCleanup` or `session_cleanup.rb`.
+Generic scheduler APIs remain available for unrelated custom jobs. Native
+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 +543,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 +582,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`.
@@ -439,7 +683,7 @@ row as `MISSING` until a key is set.
 Everything above is a thin CLI over two autoloaded modules:
 
 ```ruby
-PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, state:, pkg_manager:, os:, arch: }
+PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, state:, pkg_manager:, os:, arch:, native_libraries_missing: }
 PWN::Setup.deps(profile: :web, yes: true) # install, then re-check
 PWN::Setup.list_profiles
 PWN::Setup.migrate(fix: true)             # thin wrapper → PWN::Migrate.run
@@ -474,7 +718,7 @@ Vagrant, CI) picks it up automatically.
 ```ruby
 pwn[CURRENT_VERSION]:001 >>> PWN::Setup.check[:ok]          # => true
 pwn[CURRENT_VERSION]:002 >>> PWN::Migrate.needed?           # => false
-pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 107
+pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 108
 pwn[CURRENT_VERSION]:004 >>> PWN::SAST.constants.count      # => 48
 pwn[CURRENT_VERSION]:005 >>> pwn-ai                         # launches agent TUI
 ```

data/documentation/Mission-Cancellation.md

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

data/documentation/Operability.md

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

data/documentation/Persistence.md

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