pwn 0.5.722 → 0.5.724

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31f54d1cd6a7bfbc4cef3bcc989650930b1b31bbf2bbc47654b20d6f20158775
-  data.tar.gz: 50bfda31eecd4b99d17324a8c4c548f14b8df10561c183f27bc9e7157c8f88bf
+  metadata.gz: b1c409d6b05e3c061837ef187c74d22ff5e24d361aee4531be0943714a8f713b
+  data.tar.gz: dacfce51246aee0f02c84b5a8eae1651fe2853db2e0f192343c5fc8cfbc5462b
 SHA512:
-  metadata.gz: 3a43118f36da1f9712dbfb908b5f0c9d4650d3bfde63239240d7c9cefcc50d29d78468e14e9cd9bf44f9fdba5df971b48659b348619dc79a7e17667028930025
-  data.tar.gz: 867d72ec34f85caaf18fa5abeb38b466d5663c1361becf17cb4af87115dd0d45411527b0f5616dd54874c241544416fb0b9427f16476248ed38a864b3951daef
+  metadata.gz: 6c29fd2cde7775f1923249f166af195dcc99ed0614c86536d3aeb56bcc7a3d29a28a3483b1b2c25bb736b2b78b28ab92a0906d690cd71d002ff335c41e1e5d78
+  data.tar.gz: cbcf28e1681df68a21a1da6f247bf645de861ee2a752af2f3735f09f2a59501bdd9d5fb5bf238dcc39ae2734ea173a3d515ddb3df1de2d7548de4fbbb67c5ea7

data/Gemfile

@@ -49,7 +49,7 @@ gem 'jwt', '3.2.0'
 gem 'libusb', '0.8.0'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
-gem 'mcp', '1.4.0'
+gem 'mcp', '1.5.0'
 gem 'meshtastic', '0.0.175'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.25.0'
@@ -77,7 +77,7 @@ gem 'rbvmomi2', '3.10.0'
 gem 'rdoc', '7.0.4'
 gem 'rest-client', '2.1.0'
 gem 'rex', '2.0.13'
-gem 'rmagick', '7.1.3'
+gem 'rmagick', '7.1.4'
 gem 'rqrcode', '3.2.0'
 gem 'rspec', '3.13.2'
 gem 'rtesseract', '3.1.4'

data/bin/pwn_setup

@@ -25,8 +25,10 @@ pwn_driver = PWN::Driver::Parser.new do |options|
   end
 
   options.on('-l', '--list-profiles',
-             '<Optional - List capability profiles and exit>') do |o|
-    opts[:list] = o
+             '<Optional - List capability profiles and exit>') do
+    # Public metadata, like --help: no environment decryption or bootstrap.
+    PWN::Setup.list_profiles
+    exit 0
   end
 
   options.on('-m', '--migrate',
@@ -66,9 +68,7 @@ pwn_driver.parse!
 begin
   status = 0
 
-  if opts[:list]
-    PWN::Setup.list_profiles
-  elsif opts[:migrate]
+  if opts[:migrate]
     r = PWN::Setup.migrate(
       fix: opts[:fix] || opts[:yes],
       dry_run: opts[:dry_run]

data/documentation/AI-Integration.md

@@ -10,7 +10,7 @@ agent code never cares which model is behind it.
 
 | Engine | Client | Auth | Notes |
 |---|---|---|---|
-| `openai` | `PWN::AI::OpenAI` | `key:` | function-calling native |
+| `openai` | `PWN::AI::OpenAI` | ChatGPT/Codex `oauth:` or `key:` | OAuth preferred when configured; subscription chat uses the Codex Responses backend, API keys use the Platform API |
 | `anthropic` | `PWN::AI::Anthropic` | `key:` | tool-use native |
 | `grok` | `PWN::AI::Grok` | `key:` **or** `oauth: true` | OAuth = RFC-8628 device-code flow using xAI's public Grok-CLI client id (no secret) - see skill `xai_grok_oauth_device_flow` |
 | `gemini` | `PWN::AI::Gemini` | `key:` | function-calling native |
@@ -38,6 +38,39 @@ ai:
 PWN::Env[:ai][:active] = :ollama
 ```
 
+## OpenAI OAuth enrollment and persistence
+
+To prefer subscription OAuth, set `ai.openai.oauth.enroll: true` through
+`pwn-vault`, then restart `pwn-ai` and follow the device-code consent prompt.
+An existing bearer or refresh token is preferred over `ai.openai.key`.
+The account must have access to the requested model through Codex; OAuth
+does not grant all Platform API permissions or bypass subscription limits.
+
+You can also enroll explicitly from a PWN Ruby console:
+
+```ruby
+PWN::AI::OpenAI.obtain_oauth_bearer_token; nil
+```
+
+The trailing `nil` prevents the console from echoing the returned bearer.
+Successful enrollment updates the live environment and calls the private
+`persist_oauth_to_vault` helper, as token refresh does. It uses the configured
+`driver_opts.pwn_env_path` and `pwn_dec_path`, defaulting to
+`~/.pwn/pwn.yaml` and its `.decryptor` file. Existing decryption artifacts are
+required; missing artifacts leave tokens in the session only and produce a
+notice. Tokens are not printed by the enrollment success message.
+
+Persistence retains unrelated settings and the existing key/IV, encrypts a
+private temporary file, and replaces the vault only after encryption succeeds.
+The resulting vault has mode `0600`. The original vault remains unchanged on
+a persistence failure; the helper does not create or rotate decryptor secrets.
+
+Subscription OAuth requests must not go to the default Platform
+`/v1/responses` endpoint: that mismatch can produce `Missing scopes:
+api.responses.write`. OAuth chat uses
+`https://chatgpt.com/backend-api/codex/responses` instead. An actual Platform
+API key still needs the relevant project and endpoint permissions.
+
 ## Engine-aware behavior
 
 The harness adapts to the *class* of engine, not the model name:

data/documentation/Policy-Benchmark.md

@@ -0,0 +1,296 @@
+# Independent local Policy/Registry benchmark
+
+This is a **deterministic controller benchmark, not proof of live LLM improvement**.
+It executes real local file tasks and trains the actual tabular
+`PWN::AI::Agent::Policy` implementation, then selects actions through the actual
+`Registry.rank`. No model responses, provider usage, or benchmark gains are
+simulated. The action handlers are explicitly hand-written local algorithms,
+not a simulated language model.
+
+## Run from a source checkout
+
+```sh
+ruby scripts/benchmark_policy.rb --self-check
+ruby scripts/benchmark_policy.rb --output /tmp/pwn-policy-benchmark.json
+bundle exec rubocop scripts/benchmark_policy.rb
+```
+
+The experiment uses Ruby and its standard libraries; it does not require the
+full application boot sequence. Use a fresh Ruby process, not the live agent
+console. JSON is printed to stdout and optionally written to `--output`.
+`--self-check` runs independent scorer tests, both complete experimental arms,
+and two fresh snapshot workers; it prints short pass messages instead of a
+report. Use the options separately.
+The benchmark exits nonzero if persistence changes during evaluation, splits
+overlap, a negative control succeeds, or a positive control fails. Self-checks
+also require actual training updates in the on arm and none in the off arm.
+They deliberately do **not** require an improvement of a predetermined size.
+
+## Relation to existing evaluation
+
+`lib/pwn/ai/agent/curriculum.rb` provides live self-play, judge-based practice,
+mistake-derived evaluation prompts, and adapter training/promotion gates. This
+standalone script does not invoke those paths. It provides a small, independently
+scored experiment where the training labels come from actual task achievement,
+not `Reward.judge`, model prose, or a previously assigned reward. It calls
+`Policy.begin_episode`, `observe_step`, and `finish` with those labels during
+training. This is not a test of Reward's verification-record binding, the live
+Loop, Metrics learning, memory retrieval, or adapter training.
+
+The experimental driver remains in `scripts/`. The opt-in `PolicyEvaluation`
+module launches only this fixed runner; it does not load the live agent in its
+workers. Its module autoload does not enable evaluation or promotion.
+
+## Protocol
+
+1. **Isolation.** Create a private `/tmp/pwn-policy-benchmark-*` directory. Clear
+   the process environment, set `HOME` and `TMPDIR` to that directory, then load
+   only Policy and Registry. Assert their persistence constants resolve below
+   the temporary `HOME/.pwn`. Do not load user configuration, credentials,
+   registered application tools, providers, or network libraries. Delete the
+   entire temporary directory on normal completion or Ruby exception and restore
+   the process environment. A force-killed process may leave its temporary files.
+   This is isolation for trusted fixed handlers, not a sandbox for untrusted code.
+2. **Paired arms.** Run `off`, then `on`, resetting Policy between them. Both arms
+   start empty and execute the identical training schedule. The only learning
+   switch is `PWN::Env[:ai][:agent][:policy]`. No Q entries, visits, episode counts,
+   or rewards are seeded directly. Other learning modules are not loaded.
+3. **Training only.** There are four training fixtures: two numeric sorting tasks
+   and two active-inventory filtering tasks. Six fixed exploration rounds execute
+   every one of the three candidate actions for each fixture: 72 real handler
+   calls per arm. Every action gets equal exposure; the scheduler does not use
+   answer keys to choose actions. Each call writes into a fresh task directory.
+   Exact artifact correctness supplies a binary training label to Policy; the
+   off arm executes the same work but Policy declines to update.
+   Each call has an explicit action ID. Only after the independent artifact
+   check, `finish` receives a `controlled_comparison` attribution receipt naming
+   that ID. This is a one-action isolated experiment, not a claim that the last
+   action in an arbitrary live trace caused the outcome.
+4. **Held-out evaluation.** Only after training, materialize eight distinct
+   held-out inputs with literal answer keys: four numeric and four inventory
+   tasks. Assert no training input appears in evaluation. Task families and
+   request wording are intentionally shared with training. The held-out units
+   are **input instances, not unseen families, prompts, or tools**. This is
+   in-distribution transfer within a small public fixture set, not a blind test
+   or a generalization claim about arbitrary operator requests.
+5. **Frozen controller.** Rank the task family's three entries using
+   `Registry.rank(query: ..., entries: ..., preference: [])`. There are no
+   evaluation `begin_episode`, `observe_step`, or `finish` calls. The policy uses
+   Registry's normal fallback state rather than a fabricated state/table. Allow
+   at most three attempts, stopping only when the independent artifact checker
+   passes. The controller does not get corrective feedback or adapt between
+   attempts. Hash all persisted `.pwn` files before evaluation and after controls;
+   abort if they changed.
+6. **Separate controls.** For each held-out input, force a claim-only handler and
+   a handler that writes a wrong JSON object. Both return convincing
+   `PASS: completed successfully...verified` prose and `ok: true`. All 16 forced
+   negative controls must fail objective scoring. Also execute the correct
+   algorithm on each input; all eight positive controls must pass. Controls are
+   reported separately and never trained on or included in evaluation rates.
+
+## Real task behavior and independent scoring
+
+Numeric candidates perform lexical sorting, numeric sorting, or no artifact
+write. Inventory candidates filter active rows, include every row, or write
+nothing. Handlers receive only input/output paths; the literal expected values
+are not passed to them. All handlers claim success, intentionally making textual
+claims unreliable. The checker ignores their prose and action names. It accepts
+only a regular non-symlink output whose parsed JSON exactly equals the answer key,
+with the source input unchanged. Missing output, invalid JSON, a plausible wrong
+artifact, or an altered input is failure. Self-checks separately test missing,
+wrong, prose-only, symlink, and correct artifacts.
+
+Each family has equal keyword-fit descriptions, with preference disabled. The
+unlearned deterministic tie-break favors lexical sort in one family and the
+correct active filter in the other; it is not configured to lose every task.
+Lexical sorting can genuinely solve some numeric fixtures and receives credit
+when it does. The learned controller can change these tied rankings from
+observed outcomes. This construction deliberately isolates the learning-to-router
+connection; it does not measure natural-language tool-selection quality.
+
+The answer keys and algorithms live in the same public script but do not call
+one another. Independence here means scoring actual artifact/task achievement
+without trusting action claims or training rewards, not process-level secrecy or
+an external audit. Extending the task set requires reviewing literal answer keys
+and adding both positive and negative controls before interpreting new results.
+
+## Report definitions
+
+Each arm contains full training/evaluation traces, fixture inputs and answer keys,
+control traces, Policy statistics, persistence fingerprints, and split/freeze
+checks. Source hashes identify the Policy, Registry, and harness revisions used.
+No fixed gains are embedded in the report.
+
+- **Completion:** tasks with at least one objectively successful attempt divided
+  by evaluated tasks. A failed attempt does not count as task completion.
+- **Artifact check score:** each attempt earns 1.0 only for an exact correct
+  artifact with unchanged input, otherwise 0.0; phase score is its mean across
+  attempts. Report rows retain the actual artifact body as well as its hash.
+- **False-success count/rate:** attempts claiming `ok: true` without achieving the
+  task; rate denominator is executed attempts, not tasks. This is false reporting
+  by the handler, not acceptance of that report by the independent checker.
+- **Repeated mistakes:** every failed attempt after the first occurrence of the
+  same `(family, action, checker failure)` signature within that phase and arm.
+  This includes both repeated attempts on one task and recurrence on later
+  held-out inputs. It is not the production Mistakes store's count.
+- **Calls:** `tool_calls` counts actual local handler invocations. Evaluation makes
+  one Registry ranking decision per attempted handler call. Training invokes
+  begin/observe/finish once per training call; the returned update reports are
+  preserved. Each separately listed control row is one additional handler call.
+- **Elapsed:** monotonic measured seconds. Row elapsed time measures the handler;
+  phase elapsed time also includes setup, ranking/checking, and training updates
+  as applicable. Evaluation phase time excludes separately listed controls;
+  top-level elapsed includes both arms and controls but not final JSON output or
+  temporary-directory teardown. Tiny timings vary with caching and filesystem
+  load; fixed arm order is not a timing-performance study.
+- **Cost:** zero LLM calls and zero provider tokens because no provider is invoked.
+  Monetary cost is `null` (not estimated), not a claim that local computing is
+  economically free. No token-price or electricity estimates are invented.
+
+Training completion is descriptive coverage under forced exploration, not a
+learned-policy score. Only the held-out evaluation rates compare the controllers.
+Repeated executions should reproduce actions, counts, fixture hashes, and update
+counts for the same source revisions. Wall times, temporary paths, timestamps,
+and timestamp-bearing persistence hashes are expected to differ.
+
+There is deliberately no external-runner plug-in: accepting arbitrary commands
+would undermine the no-network/no-credentials guarantee. A future live-model
+study should use a separately reviewed runner, identical model/tool budgets,
+external objective verifiers, frozen held-out evaluation, and actual provider
+usage records. Do not present this controller experiment as that study.
+
+## Opt-in independent snapshot evaluation (R5)
+
+The original commands and `off`/`on` report shape still work. To additionally
+export snapshots and run repeated evaluations in **fresh subprocesses**, use:
+
+```sh
+ruby scripts/benchmark_policy.rb --heldout \
+  --snapshot-dir /tmp/pwn-policy-snapshots \
+  --output /tmp/pwn-policy-heldout.json
+```
+
+The snapshot directory must be **new**, below `/tmp`, with no symlink parents.
+`off.json` and `on.json` are genuine Policy JSON tables after the same real
+training schedule. Exported `updated_at` metadata is normalized to `null` for
+reproducible snapshot digests; no Q entries or rewards are fabricated. Export
+happens before that arm's evaluation. Neither `--heldout` nor `--snapshot-dir`
+promotes anything or discovers/reads a real home-directory policy.
+
+The added `heldout` array contains protocol `pwn-policy-heldout-v2`, for suite
+indices 0 and 1. Each worker runs three frozen arms: `off` (baseline snapshot,
+policy disabled), `baseline` (baseline enabled), and `candidate` (candidate
+enabled). Workers never call begin/observe/finish, warmup, or reset the caller's
+policy. Resets and snapshot installation occur only inside temporary HOME.
+Only fixed local handlers are registered; no provider, shell tool, credential,
+user config, or network client is loaded. Environment variables, including Ruby
+startup hooks, are removed before spawning Ruby. Workers have a 30-second
+deadline; stalled children are killed and reaped. Snapshot inputs must be regular
+non-symlink files, at most 4 MiB, with valid numeric `q`, `h`, `visits`, `returns`,
+`n_updates`, and `td_abs_sum` fields. Parent directories cannot be symlinks.
+
+Suite indices 0..7 are bounded deterministic variations, **not random trials**.
+Numeric inputs and separate literal answer keys are scaled by `seed + 1`;
+inventory IDs and separate answer keys are offset by `100 * seed`. This does not
+call a candidate algorithm to construct its answer key. Even indices use flat
+paths and compact JSON; odd indices use nested paths containing spaces, pretty
+JSON, and read-only inputs. Every arm runs eight tasks, 16 negative controls and
+eight positive controls. Training fixtures remain unchanged and disjoint.
+These are two task families and two filesystem configurations, not unseen tools
+or broad environment generalization. Both environment types are required for
+promotion eligibility.
+For externally supplied snapshots, `disjoint_inputs` describes the harness's
+fixture sets, not proof of the snapshot's training history; that history is not
+attested by this runner.
+
+Explicit snapshots from another controlled experiment can be evaluated without
+booting the application:
+
+```ruby
+require './lib/pwn/ai/agent/policy_evaluation'
+evaluator = PWN::AI::Agent::PolicyEvaluation
+reports = [0, 1].map do |seed|
+  evaluator.evaluate(baseline: '/tmp/baseline.json',
+                     candidate: '/tmp/candidate.json', seed: seed)
+end
+```
+
+With fixed source revisions and snapshot bytes, snapshot reports reproduce all
+fields except `elapsed_seconds`. They contain no wall-clock timestamps, random
+IDs or temporary paths. The original training report still contains the timing
+and metadata variability described above.
+
+## Explicit promotion and rollback
+
+This is an **operator-invoked local eligibility gate**, not automatic online
+policy promotion. `Policy.finish` and Loop do not call it. The existing online
+learning behavior is not redirected or promoted by this module. No live policy
+path is defaulted, and writes require `enabled: true` **and** `quiescent: true`.
+The latter is an operator assertion: **stop all agent processes and policy
+writers first**. The existing Policy writer does not share a transaction lock
+with this module; concurrent live learning or concurrent promotions are not
+supported. Restart writers only after the operation and readback complete.
+
+Promotion requires 2..8 reports with distinct valid suite indices covering both
+filesystem configurations. It then **reruns each suite in a fresh worker** using
+the specified snapshot bytes. Every non-timing report field must match the fresh
+execution, including source/harness digests, snapshot digests, input hashes,
+artifact bodies and hashes, action choices, scores, controls, and frozen-policy
+checks. Hashes alone are not signatures or evidence of trusted authorship;
+re-execution is the authority. Model-written `passed: true`, edited scores,
+invented artifact bodies, stale source revisions, or copied duplicate reports
+cannot substitute for those executions. Supplied elapsed times are discarded;
+only newly measured times enter the gate.
+
+For **every** repeated suite, compared with both baseline-on and off:
+
+- completion and mean artifact-check score must not decrease;
+- no previously solved individual task may become unsolved (aggregate gains
+  cannot hide a task/family regression);
+- false-success count **and rate**, repeated mistakes and tool calls must not rise;
+- elapsed time must be at most `baseline_seconds * 1.25 + 0.02`, a fixed local
+  jitter allowance rather than evidence of a statistically established speedup.
+
+Each suite must also improve completion, false-success count, repeated mistakes,
+or calls relative to baseline-on. Better training returns, more updates, or a
+timing-only change cannot qualify. The gate fails closed when verification fails.
+Snapshots, source digests and live-baseline bytes must still match. An explicit
+live target must already exist and equal the evaluated baseline byte-for-byte.
+The previous policy is saved beside it as a digest-named rollback JSON before a
+same-directory atomic replacement and exact readback. No trajectory file is
+modified. Preserve the returned receipt for rollback.
+
+A disposable demonstration using the opt-in benchmark output above:
+
+```ruby
+require './lib/pwn/ai/agent/policy_evaluation'
+evaluator = PWN::AI::Agent::PolicyEvaluation
+baseline = '/tmp/pwn-policy-snapshots/off.json'
+candidate = '/tmp/pwn-policy-snapshots/on.json'
+reports = JSON.parse(File.read('/tmp/pwn-policy-heldout.json'), symbolize_names: true).fetch(:heldout)
+live = '/tmp/pwn-policy-demo-live.json' # NOT the real online policy
+File.open(live, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |f| f.write(File.binread(baseline)) }
+receipt = evaluator.promote(enabled: true, quiescent: true,
+                            baseline: baseline, candidate: candidate,
+                            reports: reports, live_path: live)
+raise receipt.inspect unless receipt[:promoted]
+restored = evaluator.rollback(enabled: true, quiescent: true,
+                              live_path: live, receipt: receipt)
+raise restored.inspect unless restored[:rolled_back]
+```
+
+Rollback verifies the receipt's explicit target, backup path and prior digest,
+validates the backup schema, and refuses if the live file no longer matches the
+promoted candidate digest. Missing, altered or symlink backups/targets fail
+closed. Both methods default to a disabled result; rejected operations return
+`promoted: false` or `rolled_back: false` with a reason. `evaluate` raises on an
+invalid snapshot, worker failure, or deadline. Force-killing a worker can leave
+its temporary directory; this is not an OS sandbox for untrusted code.
+
+**Limit:** this gate measures only the fixed benchmark action vocabulary and
+public task families. A real online policy containing unrelated tools may show
+no gain and be rejected; passing does not validate those unrelated routes or
+establish live LLM gains. A production rollout still needs separately reviewed,
+representative objective tasks and operator judgment. Do not interpret this
+small public held-out set as a secret test or optimize repeatedly against it
+and then claim independent generalization.

data/documentation/Reinforcement-Learning.md

@@ -47,10 +47,10 @@ This is the live numeric controller. It does not replace planning.
 
 | Piece | What it is |
 |---|---|
-| State | request kind, task family, plan quality, answer completeness, usable-result, last action, fail bin, and engine |
+| State | request kind, task family, plan quality, answer completeness, usable-result, last action, fail bin, engine, and sanitized host-observed capability/verification scope |
 | Action | tool name, or `final` |
 | Step reward | 0; −0.01 per tool after 8 |
-| Terminal reward | `Reward.judge` × confidence (sole large R). `plan_coverage` is a tag, not the score. |
+| Terminal reward | Resolved training score mapped to −1..1 × confidence (sole large R), attributed only to independently linked actions. `plan_coverage` is a tag, not the score. |
 | Updates | Q-learning (`alpha=0.15`, `gamma=0.85`) and REINFORCE (`alpha=0.05`). Stored trajectories replay twice on warmup so a short table is not empty advice. |
 | Budget | Eight finished episodes (live or warmup-credited) unlock greedy suggestions. Until then the prompt omits them. |
 | Steer | Q-advantage in `Registry.rank` once the episode budget is met; keyword fit and CORE_TOOLS still come first. Suggested actions follow `Registry.preference_order` (`ai.agent.tool_preference`). |
@@ -65,6 +65,84 @@ high-return / high-score episodes.
 
 ## Reward signal (`PWN::AI::Agent::Reward`)
 
+`Reward.resolve_outcome` is the shared decision used by live learning and
+offline practice. The ledger retains the raw judge score, source, confidence,
+verdict, and verification evidence. Heuristic guesses, evaluator errors, and
+unresolved high-score/critic disagreements are unverified, with a nil
+`training_score`; they do not become policy updates, failures, or supervised
+success examples. Requeuing a disputed result rejudges its original session
+instead of raising its score automatically.
+
+Writing “PASS” in an answer, returning exit zero, or confirming one claim does
+not establish completion. A trusted host verifier can call
+`Reward.record_verification` after checking every original-request criterion,
+providing actual boolean check results and evidence. Records are bound to the
+current session request and invalidated by subsequent tool execution. The API
+trusts the host verifier to cover the complete request; it cannot infer missing
+criteria or automatically verify arbitrary tasks. LLM judgments remain fallible.
+
+### Executed acceptance checks and artifact attribution
+
+For stronger verification, pass a host-owned `verification_contract` to
+`Loop.run`, or use `Reward.run_verification(request:, session_id:, contract:)`.
+The contract contains `root`, `requirements` (distinct verbatim clauses of the
+original request), and `checks`. Each check names its `requirement` and kind:
+
+- `file`: an in-root regular `path` whose bytes equal `expected`.
+- `json`: an in-root regular `path` whose parsed JSON equals `expected`.
+- `command`: a literal `argv`, expected `exit_code` (default zero), and optional
+  expected stdout. Requires `allow_commands: true`.
+- `http`: an exact `url` listed in `allowed_urls`, expected response bytes, and
+  expected `status` (default 200). GET only, with no redirects.
+
+Check failures are negative evidence. Missing requirements, unavailable checks,
+and timeouts stay unknown even if the LLM judge awards a high score. Later tool
+execution invalidates a runner report without falling back to presumed success.
+The runner records output digests, not raw command output or expected values.
+Artifact reads use no-follow descriptors, validate their actual location through
+Linux `/proc/self/fd`, and enforce the byte limit while reading. If descriptor
+location validation is unavailable, the check stays unknown rather than using
+an unsafe pathname fallback.
+The caller must supply the complete acceptance checklist: matching clauses to
+the original text is not semantic proof that the checklist covers every intent.
+
+Commands have a cleared environment, private HOME set to the selected root,
+bounded output and timeout, and process-group cleanup. This is **not an OS
+sandbox**: opt-in commands retain the process's filesystem/network permissions.
+Only run trusted checks, using an external sandbox for untrusted programs.
+
+At the final boundary, Loop executes the contract and publishes a verification
+event through `on_tool`. Around dispatched actions it snapshots declared
+artifact digests. Matching the final checked digest to its last observed writer
+produces an `independent_verifier` attribution receipt. This establishes artifact
+provenance, not universal causal proof. Controlled comparisons in isolated
+evaluation can supply a separate `controlled_comparison` receipt.
+
+Policy distributes the existing terminal reward across uniquely linked action
+IDs. Unlinked actions receive no positive training credit; an accounting-only
+final row retains unattributed terminal reward. Adding successful no-op commands
+does not create more reward. Known per-step cost remains; unknown task outcomes
+still do not train. Ordinary model-judged runs without attribution may retain
+outcome/lesson records, but do not positively reinforce guessed tool contributions.
+
+`Loop.run(trusted_context:)` accepts host observations, not model arguments.
+Policy stores only fixed environment/capability/failure/verification categories;
+state backoff stays within that observed scope. Registry checks declared tool
+prerequisites before ranking, including core tools, so a known absent prerequisite
+cannot be outweighed by a historical success score. Unknown availability is not
+treated as absence. Default local scope observes the Ruby runtime and `/bin/sh`;
+callers must supply observations for remote/container-specific capabilities.
+
+Policy observations also capture allowlisted operation, argument-role/type
+features, and result classification, without retaining raw argument values.
+These condition next-tool ranking only after enough contextual samples exist,
+with backoff to broad tool scores. Ranking remains advisory.
+
+For an independently checked learning-on/off experiment, see
+[Policy-Benchmark.md](Policy-Benchmark.md). It exercises real local handlers and
+controller updates on separate training and held-out inputs; it does not prove
+that a live language model performs better.
+
 | Method | What it does |
 |--------|--------------|
 | **R1** `.judge` | Cheap LLM outcome score on `(request, final)` -> `{score:0..1, verdict:, rationale:, key_step:, source:}`. Calls the active engine `.chat` with a short timeout (default 12s). `Reflect.on` is used only when `module_reflection` is on. Fallback scores completeness, plan cover, claims, and tool-trace echo. Token overlap is only a small on-topic gate. |
@@ -147,7 +225,7 @@ This is the live control list. Track the outcomes, not source comments.
 |-------|------|
 | **E1** `Metrics.changepoints` + `Loop.attribute_cause` | Env-drift-attributed failures get `cause: :env_drift` and do not inflate `[REPEATING]`. |
 | **E2** `Extrospection.correlate` | Lead-lag style joins ("tool X started failing after toolchain Y changed"). |
-| **E3** `Reward.verify_as_reward` | Browser-backed claim checks can floor/cap the outcome score. |
+| **E3** `Reward.verify_as_reward` | Browser-backed claim checks provide diagnostics and refutation caps; one confirmed claim cannot promote whole-request success. |
 
 ## Config (`PWN::Env[:ai][:agent]`)
 

data/etc/default_skills/pwn/ai/agent/engagement/SKILL.md

@@ -39,6 +39,7 @@ PWN::AI::Agent::Engagement.open(opts)
 - `current_name`
 - `in_scope`
 - `deny_if_out_of_scope`
+- `load_roe`
 - `authors`
 - `help`
 - `in_scope?`

data/etc/default_skills/pwn/ai/agent/metrics/SKILL.md

@@ -39,6 +39,9 @@ PWN::AI::Agent::Metrics.load(opts)
 - `append_jsonl`
 - `summary`
 - `snapshot`
+- `record_tokens`
+- `usage`
+- `routing`
 - `to_context`
 - `proxy_trust`
 - `ucb`

data/etc/default_skills/pwn/ai/agent/policy/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 # PWN::AI::Agent::Policy
 
-PWN::AI::Agent::Policy is the LIVE tabular RL controller that pwn-ai did not have before R5. Everything else in the harness is retrieval-plus-policy: scores are written to disk and re-injected as prose, or exported later for optional LoRA. This module is the missing MDP: state s — discretized (kind, task, plan, completeness, usable, last, fail) action a — tool name, or "final" reward r — step: 0 (spam cost −0.01 after 8 tools); terminal: judge × confidence next s' — state after the tool result Each Loop turn is one episode. Transitions land in ~/.pwn/policy_traj.jsonl. Q(s,a) and REINFORCE logits H(s,a) are updated from those tuples and persisted in ~/.pwn/policy.json. The learned Q values are an ADVISORY term in Registry.rank. They never replace TaskSummarizer planning, plan_first, or CORE_TOOLS. Disable with PWN::Env[:ai][:agent][:policy] = false.
+PWN::AI::Agent::Policy is the LIVE tabular RL controller that pwn-ai did not have before R5. Everything else in the harness is retrieval-plus-policy: scores are written to disk and re-injected as prose, or exported later for optional LoRA. This module is the missing MDP: state s — discretized (kind, task, plan, completeness, usable, last, fail) action a — tool name, or "final" reward r — step: 0 (spam cost −0.01 after 8 tools); terminal: judge × confidence next s' — state after the tool result Each Loop turn is one episode. Trusted environment/prerequisite bins scope fallback history; independently evidenced terminal attribution uses isolated action targets, not future-return credit for busywork. Transitions land in ~/.pwn/policy_traj.jsonl. Q(s,a) and REINFORCE logits H(s,a) are updated from those tuples and persisted in ~/.pwn/policy.json. The learned Q values are an ADVISORY term in Registry.rank. They never replace TaskSummarizer planning, plan_first, or CORE_TOOLS. Disable with PWN::Env[:ai][:agent][:policy] = false.
 
 ## When to use
 
@@ -34,6 +34,8 @@ PWN::AI::Agent::Policy.state(opts)
 ## Public methods
 
 - `state`
+- `observed_state`
+- `observed_context`
 - `cold`
 - `warm`
 - `episode_budget_met`
@@ -48,6 +50,7 @@ PWN::AI::Agent::Policy.state(opts)
 - `recommend`
 - `current_state`
 - `current_episode`
+- `current_context_state`
 - `detach_episode`
 - `attach_episode`
 - `load`

data/etc/default_skills/pwn/ai/agent/policy_evaluation/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pwn-ai-agent-policyevaluation
+description: Drive PWN::AI::Agent::PolicyEvaluation from pwn_eval.
+license: MIT
+allowed-tools: [pwn, pwn_eval]
+metadata:
+  bundled: true
+  generated: true
+  module: PWN::AI::Agent::PolicyEvaluation
+  source: pwn/ai/agent/policy_evaluation.rb
+---
+
+# PWN::AI::Agent::PolicyEvaluation
+
+Opt-in, fixed local held-out evaluation. Never loaded by the online loop.
+
+## When to use
+
+Call `PWN::AI::Agent::PolicyEvaluation` from `pwn_eval` when the task needs this module.
+Do not reimplement it in shell.
+
+## Methodologies
+
+Generated from `pwn/ai/agent/policy_evaluation.rb`. Prefer the public class methods below.
+Class methods take `(opts = {})` and read `opts`.
+
+## How to call
+
+```ruby
+PWN::AI::Agent::PolicyEvaluation.help
+PWN::AI::Agent::PolicyEvaluation.evaluate(opts)
+```
+
+## Public methods
+
+- `evaluate`
+- `authors`
+- `promote`
+- `rollback`
+- `help`
+
+## Source
+
+`pwn/ai/agent/policy_evaluation.rb`
+
+## Verification
+
+`PWN::AI::Agent::PolicyEvaluation.respond_to?(:evaluate)` after the
+module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/ai/agent/registry/SKILL.md

@@ -44,8 +44,10 @@ PWN::AI::Agent::Registry.register(opts)
 - `discover`
 - `eager_load`
 - `selftest`
+- `available`
 - `authors`
 - `help`
+- `available?`
 - `eager_load!`
 
 ## Source

data/etc/default_skills/pwn/ai/agent/reward/SKILL.md

@@ -34,6 +34,9 @@ PWN::AI::Agent::Reward.judge(opts)
 ## Public methods
 
 - `judge`
+- `resolve_outcome`
+- `run_verification`
+- `record_verification`
 - `promote_to_success`
 - `prm`
 - `plan_coverage`

data/etc/default_skills/pwn/ai/agent/swarm/SKILL.md

@@ -47,6 +47,12 @@ PWN::AI::Agent::Swarm.personas(opts)
 - `fact_record`
 - `facts_prompt`
 - `claim`
+- `pack_specialist`
+- `child_inbox`
+- `child_honesty`
+- `honesty_unmet`
+- `view_graph`
+- `migrate_personas`
 - `authors`
 - `help`