pwn 0.5.763 → 0.5.771

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fec3b367c44874a819aa4892a5b3c507cf858ed4649eb31d295b0509e8747c83
-  data.tar.gz: d8a004b8eee5f7bd996ae8c9208f895d93354b09f9149050cb3e93d8632fda8c
+  metadata.gz: 4a5ecce60b421a59e80f691710dd5ae25cd79d083b59207b25baccf8fe8e5b35
+  data.tar.gz: 725ceb379d5436565b707e29d26e61e9cc10262b31e7cec537aec0e210d77fea
 SHA512:
-  metadata.gz: 7490168d3e50c940ff771fe6788f7373e89b15f96541a8d0cec29bd13b1cccdce7c377799a415628fcd899a0e912928bf3aeb5fef68c0cf0fda2217871f60d95
-  data.tar.gz: eb50e5646ee60e9394f92139b61c38901303fc6167b06f95cf559a413d88a09dbfa21eadeb1e46e8e9418295d348e53f81a62d4d4f25956ebb0284f7e9c2e572
+  metadata.gz: b94c6d9ca4ebb2cf3835ed1f6951a15eae48e3484966e272861105a1c361964fd90235731e8c9ccfd10cfa03af736b42d69edb990b17aed37cd1c1504954ed11
+  data.tar.gz: 39dd6eac404a8f55906c56f9dda74836bd9b934374eea9a8168d556b383ccfd69722b1a16debc893d20a0e58f37adfce54da11fef999a0666bf4f9a4f2258863

data/Gemfile

@@ -20,7 +20,7 @@ gem 'base32', '0.3.4'
 gem 'bitcoin-ruby', '0.0.20'
 gem 'brakeman', '8.1.0'
 gem 'bson', '5.2.0'
-gem 'bundler', '>=4.0.22'
+gem 'bundler', '>=4.0.23'
 gem 'bundler-audit', '>=0.9.3'
 gem 'bunny', '3.4.0'
 gem 'colorize', '1.1.0'
@@ -50,19 +50,19 @@ gem 'libusb', '0.8.0'
 gem 'luhn', '3.0.0'
 gem 'mail', '2.9.1'
 gem 'mcp', '1.7.0'
-gem 'meshtastic', '0.0.186'
+gem 'meshtastic', '0.0.188'
 gem 'metasm', '1.0.6'
 gem 'mongo', '2.26.0'
 gem 'msfrpc-client', '1.1.2'
 gem 'netaddr', '2.0.6'
-gem 'net-ldap', '0.20.0'
+gem 'net-ldap', '0.21.0'
 gem 'net-openvpn', '0.8.7'
 gem 'net-smtp', '0.5.2'
 gem 'nexpose', '7.3.0'
 gem 'nokogiri', '1.19.4'
 gem 'nokogiri-diff', '0.3.0'
 gem 'oily_png', '1.2.1'
-gem 'open3', '0.2.1'
+gem 'open3', '0.3.0'
 gem 'os', '1.1.4'
 gem 'ostruct', '0.6.3'
 gem 'packetfu', '2.0.0'
@@ -73,15 +73,15 @@ gem 'pry', '0.16.0'
 gem 'pry-doc', '1.7.0'
 gem 'rake', '13.4.2'
 gem 'rb-readline', '0.5.5'
-gem 'rbvmomi2', '3.10.0'
+gem 'rbvmomi2', '3.11.0'
 gem 'rdoc', '7.0.4'
 gem 'rest-client', '2.1.0'
 gem 'rex', '2.0.13'
-gem 'rmagick', '7.1.7'
+gem 'rmagick', '7.2.0'
 gem 'rqrcode', '3.2.0'
 gem 'rspec', '3.13.2'
 gem 'rtesseract', '3.1.4'
-gem 'rubocop', '1.91.0'
+gem 'rubocop', '1.92.0'
 gem 'rubocop-rake', '0.7.1'
 gem 'rubocop-rspec', '3.10.2'
 gem 'ruby-audio', '1.6.1'
@@ -89,12 +89,12 @@ gem 'ruby-nmap', '1.0.3'
 gem 'ruby-saml', '1.18.1'
 gem 'rvm', '1.11.3.9'
 gem 'savon', '2.17.5'
-gem 'selenium-devtools', '0.154.0'
-gem 'selenium-webdriver', '4.50.0'
-gem 'slack-ruby-client', '3.2.0'
+gem 'selenium-devtools', '0.155.0'
+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.9.6'
+gem 'sqlite3', '2.10.0'
 gem 'thin', '2.0.1'
 gem 'tty-prompt', '0.23.1'
 gem 'tty-spinner', '0.9.3'

data/documentation/Configuration.md

@@ -234,6 +234,7 @@ plugins:
         topic: 2/e/#               # MQTT topic filter to subscribe/publish for this channel.
         channel_num: 8             # Meshtastic channel index (slot number on the device).
         from: '!deadbeef'          # Sender node id used on outbound packets. Optional - defaults to !<mqtt client_id>.
+        short_name:                # Optional display name for that from node. When set, it replaces the last four bytes of from.
       PWN:                         # Example second (private) channel definition.
         psk: ...                     # Private channel pre-shared key (base64). Redacted.
         region: US/UT              # LoRa region tag for this channel.
@@ -403,6 +404,7 @@ PWN::Config.refresh_env
 | `plugins.meshtastic.channel.<NAME>.topic` | String | - | `pwn-mesh` | MQTT topic filter to subscribe/publish (e.g. `2/e/#`). |
 | `plugins.meshtastic.channel.<NAME>.channel_num` | Integer | - | `pwn-mesh` | Meshtastic channel index. |
 | `plugins.meshtastic.channel.<NAME>.from` | String | `!<mqtt client_id>` | `pwn-mesh` | Sender node id used on outbound packets. |
+| `plugins.meshtastic.channel.<NAME>.short_name` | String | - | `pwn-mesh` | Optional short name for that `from` node. A non-empty value is shown instead of the last four bytes of `from`. |
 | `plugins.shodan.api_key` | String | - | `PWN::Plugins::Shodan` | Shodan API key (passed as `api_key:` to `Shodan.*`). |
 
 ### `memory` / `sessions` / `cron`

data/documentation/General-PWN-Usage.md

@@ -51,6 +51,74 @@ history                             # what you've typed → copy into a driver
 | `welcome-banner` | Redraw a random `PWN::Banner` |
 | `toggle-pager` | Pry pager on/off |
 
+### Concurrent mesh reception and reply routing
+
+`pwn-mesh` keeps the selected primary transport for manual TX and RX. A
+nonempty `plugins.meshtastic.mqtt` configuration also opens an independent
+MQTT receiver when the primary is Serial, Bluetooth, or TCP. Missing/empty
+MQTT configuration makes no additional connection attempt; primary MQTT uses
+only one subscription. MQTT connection failures leave the primary usable and
+are reported in the UI. `/transport` reconnects both subscriptions; `/back`
+closes them. Ctrl+T switches the active pane between COMPOSE and
+CONVERSATION. COMPOSE keeps Up/Down history. CONVERSATION scrolls with
+Up/Down one row, PgUp/PgDn a page, Home to the top, and End to the live
+bottom. The live bottom is not row 0, so PgDn there stays put. Typing or
+Enter returns to COMPOSE; Enter does not send while CONVERSATION is active.
+The active title is reversed and marked active.
+
+There is **no dual TX or automatic bridging**. Compose and `/msg` use only the
+selected primary, including explicit node/channel targets. The implicit `/msg`
+target remains the primary's last sender/channel; secondary MQTT arrivals do
+not change it. Automatic AI replies instead use only the connection that
+received the triggering message. A duplicate arriving over both links is
+displayed once. If that packet is also seen on Serial, Bluetooth, or TCP, the
+row is relabeled to that primary transport even when MQTT arrived first.
+MQTT remains the label only when it is the sole observation. Automatic AI
+replies still use the first owning connection, not the display label. Dedup
+uses sender, packet ID, network/channel path, destination and payload (not
+text alone), retaining at most 1000 packets for five minutes. No-ID packets
+cannot be safely merged.
+
+Each header ends with the sender's last known position. A valid fix is
+`lat,lon >> https://maps.google.com/?q=lat,lon` on that same header. The pane
+wraps on ` · `, and only at ` >> ` if the GPS field itself does not fit, so
+the coordinate is not split. This is the compact Maps URL; a maps.app.goo.gl
+code cannot be minted without a Google share request. Unknown, unset, or
+out-of-range positions display `GPS N/A` and omit the URL. `0,0` is kept when
+a real location source is present and omitted when the source is unset. The
+value is the last position recorded for that sender, not a freshness guarantee.
+
+MQTT TX uses `channel.<name>.from` when set, otherwise the connected radio's
+node number, otherwise a node-shaped `mqtt.client_id`. It does not publish the
+Meshtastic library default `!00000b0b` when one of those identities exists.
+When that `from` value is not empty, the short name for that node is its last
+four bytes, unless the same channel sets a non-empty `short_name`. Other
+senders keep their own short names.
+
+AI dispatch still requires the toggle, a private channel PSK, `ai_whitelist`,
+and leading `@ai`. MQTT-origin shared-channel replies publish through that
+MQTT connection only; radio-origin replies use that radio only. MQTT PKI DMs
+remain unsupported: no AI DM dispatch, no radio fallback, and no plaintext or
+legacy-PSK DM fallback. Closing/replacing the origin while AI is running leaves
+its reply unsent. Host submission and local conversation display are not proof
+of RF or peer delivery.
+
+MQTT TX selects the resolved channel name explicitly as `channel_id` (for
+example, `LongFast`); the Meshtastic encoder calculates its wire channel hash.
+That name is not the radio's numeric slot or the legacy `channel_num` setting.
+Multiple configured names may share a PSK without changing the reply channel.
+Radio replies retain the received slot; an unnamed slot with an ambiguous PSK
+needs an explicit `radio_index` mapping rather than choosing the first key.
+
+AI conversations use durable `PWN::Sessions` transcripts scoped to the sender,
+network/channel, private channel key and destination. Reconnecting or receiving
+the same scope on another transport keeps that history; ordinary non-`@ai` RX
+does not create an AI session. Session/runtime/provider errors are reported as
+`AI failed`, separately from `TX failed` after a reply has been generated.
+Broker EOF/protocol errors appear as bounded, generation-scoped UI notices;
+they close the failed receiver without a Ruby thread crash dump. Use
+`/transport` to open fresh subscriptions rather than replaying failed AI sends.
+
 ## A 60-second attack chain
 
 ```ruby

data/documentation/Harness-Evaluation.md

@@ -0,0 +1,312 @@
+# Deployment fingerprints and fair harness evaluation
+
+## Deployment diagnosis
+
+`PWN::RuntimeFingerprint.report(expected_root: '/intended/gem/lib')` is read-only.
+The existing pwn-ai `/status` prints the report. The observer starts from `pwn.rb`,
+before version/config loading. It reports PID, Linux boot ID/process start ticks
+(or unavailable), observer timestamp, loaded version, activated gem root, actual
+loaded Ruby source paths, SHA-256 observed on disk at compilation, and current
+on-disk SHA-256. Changed or missing observed source and expected-root mismatches
+require restart. Unknown pre-observer bytes are **not** reported as a match.
+
+These are disk observations at compilation, **not VM bytecode attestation**.
+Concurrent replacement during compilation, native extensions, evaluated strings,
+and later monkey patches cannot be attested. `restart_required: false` means no
+known mismatch, not proof every component is current. `pwn.rb` and the observer
+itself were compiled before observation and intentionally remain unknown.
+
+Preserve the original request, session ID, request checkpoint and evidence first.
+Rebuild/install the intended tree, restart the process, and recheck the report.
+Do not hot-reload an active request or equate restoring a checkpoint with safely
+replaying a side effect. No automatic deployment or recovery mutation occurs.
+
+## Offline acceptance (no credentials or provider calls)
+
+```sh
+HOME=$(mktemp -d /tmp/pwn-rspec-home.XXXXXX) bundle exec rspec \
+  spec/integration/harness_evaluation_spec.rb \
+  spec/integration/harness_package_spec.rb \
+  spec/integration/harness_layout_spec.rb
+```
+
+RSpec owns acceptance and is included in the default offline `bundle exec rake`
+gate. Callable execution/grading helpers and subprocess-only preloads live in
+`spec/support/harness`; locked JSON manifests, independent gold and SHA-256 files
+live in `spec/fixtures/harness`. Helpers are explicitly required, not recursively
+loaded into the test process: the provider preloads must only run in isolated
+children. There is no separate script-suite CLI. The package example builds and
+executes the installed gem, not a mocked packaging check.
+
+The package lane copies current tracked and nonignored untracked working files
+into a temporary checkout, records every copied SHA-256, builds the actual gem,
+installs it using `--local --ignore-dependencies` into a temporary GEM_HOME, and
+runs that installation's **actual pwn-ai executable → CLI → Loop → provider →
+Dispatch → shell**. It never stages the source checkout or modifies its installed
+gem. Dependencies are read from existing gem paths; this is **not** proof of a
+clean dependency installation. Source edits concurrent with snapshot creation
+are represented by the copied-byte ledger, not an atomic Git revision claim.
+
+Each subprocess gets an isolated temporary HOME and cleared environment. The
+configuration loader and provider methods are replaced in a test-only preload;
+transparent observers forward to real Dispatch, Learning and Swarm methods.
+Fault stimuli supply public Loop runtime/steering options without replacing its
+implementation. Loop, Dispatch, the verifier and tools remain real. The commands are local
+file operations. HTTP/TCP provider access is rejected, and no credentials are
+passed. This is not a general OS-level sandbox for arbitrary untrusted fixtures.
+The preload is never selected by production configuration.
+
+The fixed public tasks cover exact-file output, structured extraction, safe Ruby
+coding and a nonexecuted parameterized-SQL toy classification. Grading reads
+actual artifact bytes against authored literal expectations, separately from
+provider text. An intentionally wrong artifact with a success claim must remain
+FAIL with CLI exit 1 and `false_success: false`. The arbiter checks the explicit
+`containing exactly ... followed by newline` literal against the observed digest;
+this deliberately narrow grammar is not a general natural-language content judge.
+The CLI now derives its exit code from the persisted outcome, not answer prose.
+A detected false success is a defect and fails the evaluator itself. Fixture
+outcomes are not evidence of live model competence.
+
+`runtime_faults.rb` retains the older, explicitly labeled component fixtures.
+`cli_faults.rb` adds actual executable → Loop → runtime → real shell fault lanes:
+
+- **Compaction plus additive steering:** real writes/reads generate long context,
+  a small runtime window forces EngagementMemory, a public Steering submission
+  adds a second deliverable, and independent checks require both actual files.
+- **Provider retry after a successful effect:** the fake provider raises EOFError,
+  the real retry path recovers, and the effect log must still contain one write.
+- **Cancel during a blocked provider:** after one real write, Steering cancels
+  the sleeping provider; the runtime must be cancelled, no final claim released,
+  and the CLI nonzero. This is not a native-terminal Ctrl+C test.
+- **Checkpoint restart:** one real mutation times out, the process exits abruptly,
+  then a new CLI process restores the same request and refuses duplicate replay.
+- **Hard resource cap and restart:** after at most 35 seconds of bounded executable
+  startup, an observed provider-fault readiness marker arms a four-second hard
+  process-group cap. The supervisor records INCOMPLETE, restores the real checkpoint
+  and proves that the uncertain mutation is not repeated. Missing readiness cannot
+  pass this lane. This separates cold gem activation from the injected blocked
+  provider: killing a still-booting executable proves neither effect nor recovery.
+
+The fault preload supplies public request/session/runtime/steering objects.
+These are real CLI integration tests with injected controls; the separate
+`session_acceptance.rb` exercises public session selection and replacement approval
+without injected runtime objects. They cover finite stimuli, not every provider HTTP
+retry implementation. Package acceptance runs these same lanes against installed
+gem code and checks deployment fingerprints. No live provider is contacted.
+
+The additional baseline `timeout-replay` task executes one append before timeout,
+refuses the second mutation, and must exit nonzero. The evaluator now reports
+INCOMPLETE when a real observed Dispatch timeout prevents success; it does not
+mistake an incomplete task for model-quality failure or hide it from results.
+
+## Request-lifetime integration boundary
+
+RequestRuntime persists tool start/end events and uncertain mutation fingerprints
+before releasing results. An interrupted write is not automatically replayed,
+including after checkpoint restore. Changing the action ID or timeout does not
+change that fingerprint. This is conservative uncertainty handling, not proof of
+remote exactly-once execution; spelling changes can still change the fingerprint.
+Explicit caller timeouts are not increased by Dispatch on runtime-owned requests.
+Legacy standalone Dispatch budgeting remains separate. Runtime-owned inference
+has one total provider/profile attempt allowance; all six provider adapters use
+private configuration snapshots and one transport attempt under that owner.
+
+Runtime-bound OpenGoal files are session/request-keyed, private atomic JSON, with
+a session pointer for bare `continue` in the same session. Legacy global records
+are read only for their matching session. Checkpoint generations reject stale
+writers. Loop also holds an exclusive per-session execution flock for the entire
+request, acquired before runtime loading/checkpointing and released on return,
+exception or process death. This is separate from Sessions' shared cleanup lease;
+both apply to real CLI/TUI requests. Distinct sessions remain independent. The
+session execution lock serializes OpenGoal pointer updates on production Loop
+paths; individual atomic file writes are not a general multi-file transaction.
+A new one-shot CLI session is not an automatic cross-session resume.
+
+Explicit operator entry points:
+
+```sh
+pwn-ai --resume-session EXACT_SESSION_ID
+pwn-ai --ai 'New objective' --verification-contract /path/to/authored.json
+pwn-ai --replace-session EXACT_SESSION_ID --ai 'Replacement objective' \
+  --verification-contract /path/to/replacement.json --approve-replacement
+```
+
+`--resume-session` rejects a replacement prompt/contract, selects the saved request
+identity, and preserves its original objective, permissions and authored checks.
+The existing TUI Sessions workspace and `/sessions resume ID` select exact stable
+session IDs; a subsequent `continue` uses the same core restore path. A replacement
+requires explicit approval, creates a **new** request identity and contract, and
+retains the old checkpoint unchanged. It never edits the immutable original
+objective or weakens an existing request's contract. `--resume RUN_ID` still means
+TaskDAG resume and is not repurposed. Bare steering `replace:` remains an explicit
+operator instruction; an existing authored contract is not replaced by steering.
+
+Nested Loop turns now bind their own runtime artifact contract. Completed child
+host receipts cross the enclosing Loop boundary only for a parent-required exact
+path, matching child turn, current stat/readback/SHA-256 and a child started during
+the parent request. Parent receipts retain child request/turn/action provenance.
+The parent reruns its own literal/authored integration checks; child prose is never
+proof. `swarm_acceptance.rb` executes agent_spawn → agent_ask → nested Loop and
+real shell operations for correct, lying, preexisting/stale, missing and later
+tampered artifacts. Negative task outcomes remain blocked/nonzero; PASS there
+means the rejection invariant held, not that the requested work succeeded.
+
+For nonreasoning OpenAI requests, explicit or configured temperature `0` is now
+preserved in the actual serialized HTTP payload. The adapter regression intercepts
+RestClient at the transport boundary rather than checking declared settings alone.
+This is offline payload evidence, not a paired live reference-provider comparison.
+
+Host-supplied verification contracts and tool permissions survive checkpoint
+reload. Dispatch checks runtime permissions in addition to existing boundaries.
+Additive steering verification binds the ordered original/amendment transcript,
+not merely the last user line. Verifier events include original/effective request
+and amendment digests, and report requirement character spans. An explicit
+`answer` check compares actual final text and, when supplied, quoted/cited source
+files through the bounded in-root verifier. No assistant PASS string is evidence.
+These authored checks do not imply arbitrary research-answer semantic coverage.
+
+These fixtures do not by themselves certify universal retry ownership, every
+provider configuration, general semantic verification or scheduler correctness.
+Those production requirements need their own acceptance evidence. An executable
+arm which exposes a production defect remains FAIL and fails the aggregate
+acceptance; actual correct artifact bytes do not override a nonzero CLI exit.
+
+Results preserve stdout, stderr, exit/signal status, observed provider calls,
+fingerprints, artifact hashes, wall latency, fixture-marked repeated effects and
+interventions. Distinct effect IDs are distinct writes, not duplication: only
+repeated observed IDs contribute to repeated_effects. Tool attempts alone do not.
+Unknown usage/cost and uninstrumented all-learning activity remain null. The
+parent supervisor kills the process group on wall cap and records INCOMPLETE,
+never success. A generic child error is not silently converted into a pass.
+
+## Recorded offline integration acceptance
+
+Final integration artifacts are retained under `/tmp/pwn-harness-final-acceptance`.
+These are local execution results, not live provider scores:
+
+- `HOME=/tmp/pwn-harness-final-acceptance/home bundle exec rake`:
+  **4369 examples, 0 failures**, then **1150 files, no RuboCop offenses**, exit 0
+  (`rake-post-package-fix.log`). The process was awaited through actual exit.
+- The focused Loop/runtime/Dispatch/Swarm/verifier/CLI/OpenAI/console/evaluator
+  suite: **423 examples, 0 failures**, exit 0 (`focused-post-package-fix.log`).
+- `HOME=/tmp/pwn-harness-final-acceptance/home bundle exec rubocop`:
+  **1150 files, no offenses**, exit 0 (`rubocop-post-package-fix.log`).
+- Historical offline evaluator run (before the RSpec layout migration):
+  exit 0. Four baseline tasks PASS; artifact-lie remains FAIL/exit1, and
+  timeout-replay remains INCOMPLETE/exit1 with no repeated effect. All five
+  executable fault acceptance lanes, eight frozen task/arm trials, five Swarm
+  evidence acceptance lanes and two public session-selection lanes passed.
+  Negative task outcomes were not relabeled successful work.
+- Reusing `offline-final/experiments` as the frozen source via
+  `HarnessExperiments.run(output: '/tmp/pwn-harness-final-acceptance/frozen-replay',
+  frozen: '/tmp/pwn-harness-final-acceptance/offline-final/experiments')` returned
+  exit 0 with equal snapshot digest, schedule, input hashes and graded outcomes.
+- Historical packaged acceptance output: `package-verified` beneath the artifact root above.
+  Current entry point: `bundle exec rspec spec/integration/harness_package_spec.rb`.
+  Its `acceptance.json` is the authority for installed execution and source-byte
+  equality, not the earlier source-only counts above.
+
+The initial real evaluator's two Swarm failures, temperature-zero red regression,
+cold-gem cap-before-readiness package failure and corrected lint failures remain
+in the acceptance ledger rather than being hidden. Natural-language truth requires
+authored checks; all live/private model
+comparison, quality and superiority claims remain **NOT_RUN**.
+
+## Live comparison protocol — NOT_RUN
+
+`manifest.json` and `adapters.json` have SHA-256 lock files. The runner rejects
+manifest drift. Adapter metadata pins the inspected reference source revision
+`601b550b4b5addecc0b6dacf9a472a54dd8c6799` and relevant source hashes. It documents
+real inspected entry points and constructor fields rather than invented CLI
+flags. The reference API is `run_agent.AIAgent(...).run_conversation(...)`.
+No reference agent or live provider is launched by the offline evaluator.
+`reference_adapter.py` is a separate optional Python-library boundary. It checks
+the source revision/hashes and real constructor signature, then invokes the
+public API with explicit provider, endpoint, model, reasoning, temperature via
+`request_overrides`, toolsets, token/iteration/wall budgets, fresh history, and
+disabled context files/memory/background review. It requires `--approve-live`,
+an explicitly supplied key, temporary HOME/cwd, a locked same-model parity
+manifest, reviewed sandbox/tool parity, and an operator-attested provider-side
+hard cost cap. Unknown or unequal provider/model/revision values reject execution.
+Raw returned data stays UNVERIFIED until an independent artifact checker grades
+it. Aggregate unobserved usage/cost remain null rather than fabricated zeros.
+
+The optional `spec/integration/harness_live_spec.rb` is tagged `:harness_live`
+and excluded unless `PWN_TEST_HARNESS_LIVE=1`. It never adds pending examples to
+the default gate. Explicit opt-in also requires `PWN_HARNESS_REFERENCE_SOURCE`,
+`PWN_HARNESS_LIVE_MANIFEST`, `PWN_HARNESS_PROMPT_FILE`, and `PWN_EVAL_API_KEY`;
+missing prerequisites fail rather than skip. The adapter's approval, locked
+parity, pinned-source, temporary HOME/cwd and cost-cap checks remain mandatory.
+This optional example observes only the reference API response; it does not
+establish a paired comparison or model-quality gain. No live lane was run for
+the layout migration.
+
+Safe static inspection (does not import the agent or read credentials):
+
+```sh
+python3 spec/support/harness/reference_adapter.py --inspect-source /path/to/pinned/reference/source
+```
+
+`live_comparison.json` deliberately has unselected provider/model/revision fields
+and unapproved budget/parity. It is not runnable until an operator supplies and
+locks those choices. Static API validation is not live provider validation or
+proof that both providers honor all parity settings on the wire.
+
+Before any comparison, fill and freeze the **same immutable model/version,
+reasoning setting, temperature, tools/permissions, task inputs, environment,
+iteration/token/wall/cost budget and learned snapshot** for both adapters. These
+fields are deliberately unselected, not guessed. Audit equivalent sandbox and
+sidecar behavior, instrument all provider calls and billable usage, and enforce
+operator-approved cost caps outside both agents. Missing parity means NOT_RUN.
+
+Use paired repeated seeds and randomized arm order. Freeze independently authored
+heldout tasks before tuning; these public scripted regression examples are not a
+private holdout. Keep raw transcripts and independent artifact checks. Report
+success, false-success, repeated effects, interventions, latency and observed
+usage/cost, including failures and caps; do not drop incomplete runs. Confidence
+intervals and claims of improvement require actual paired live trials.
+
+## Frozen split execution and scoped ablations
+
+`experiments.rb` executes separate train, validation and heldout task identities.
+`experiment_tasks.json` and separately authored `experiment_gold.json` are locked
+before execution. The checker reads actual bytes; gold is not included in provider
+fixtures or task workspaces. Duplicate task IDs, prompts or input bytes across
+splits are rejected. This checks explicit leakage, not semantic dataset similarity.
+The supplied public corpus and scripted provider are infrastructure regressions,
+**not a secret holdout, a live intelligence benchmark, or evidence of learning gains**.
+
+Training uses the real CLI and real Policy paths. After host byte checks succeed,
+the real Learning.note_outcome API records a labeled synthetic result without an
+invented reward score. The entire isolated training state is copied and frozen
+with a per-file hash ledger. Every evaluation trial clones it into a fresh HOME;
+no heldout writes flow back into the source snapshot or another trial. The runner
+checks the source ledger again after evaluation. Per-trial policy episode counts
+exclude episodes inherited from the snapshot. A seeded randomized schedule is
+recorded verbatim; reusing a frozen snapshot preserves the input state, not elapsed
+times or model randomness.
+
+All offered arms execute real PWN paths:
+
+| Arm | Executed path |
+| --- | --- |
+| `single-cold` | CLI → Loop, empty HOME, policy disabled |
+| `single-snapshot` | CLI → Loop → real learning retrieval, frozen training stores, policy disabled |
+| `single-policy` | CLI → Loop → Policy begin/observe/finish, same snapshot, per-trial writes |
+| `swarm-snapshot` | CLI → Dispatch agent_spawn/agent_ask → Swarm.ask → nested Loop → real shell; parent readback |
+
+Cold HOME is **not** an all-learning-off switch. The fixture disables automatic
+introspection/extrospection in every arm, but ordinary metrics and retrieval are
+real. No unimplemented all-learning-off/on arm is offered. Swarm provider calls,
+learning-context invocations and policy episodes are observed rather than inferred.
+These unequal fixture call counts are wiring evidence, not fair budget-normalized
+model superiority. Model quality remains NOT_RUN.
+
+For a diagnostic replay of a previously retained frozen training state, require
+`spec/support/harness/experiments` and call `HarnessExperiments.run(output: ...,
+frozen: ...)` from Ruby. Use a fresh `/tmp` output directory. This returns raw
+observations; the integration specs own acceptance, not a helper's exit status.
+Custom locked manifests and gold use the `manifest:` and `gold:` options. They
+are trusted local executable fixtures, not untrusted code; the HTTP guard is not
+an OS sandbox for arbitrary shell commands. Keep private benchmark gold outside
+any live agent sandbox. Do not tune on heldout outcomes.

data/documentation/Installation.md

@@ -202,6 +202,110 @@ without a per-job crontab line. Live Policy files (`policy.json`,
 `policy_traj.jsonl`) are created on first agent turn when `ai.agent.policy`
 is on.
 
+Schema `v8` seeds the enabled `session_cleanup` hygiene job, daily at 03:45
+in the scheduler's local timezone. First launch also seeds it through
+`PWN::Cron.install_defaults`. The bundled `etc/default_cron/session_cleanup.rb`
+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.
+
+Cleanup calls a session named only when its persisted metadata has
+`title_source: summary`, a nonblank title and summary, and a positive integer
+`summary_turns` cursor: the fields published after validated LLM title generation.
+Provisional first-request titles, manual titles, persona labels, aliases and
+historical embedded titles are not evidence of LLM summarization. Legacy records
+without provenance are unsummarized with `missing_summary_provenance`; invalid or
+incomplete metadata is unknown, never named. `/sessions list` and cleanup share
+`title_source`, `is_summarized`, `classification` and `title_reason`. Classification
+does not establish deletion safety: malformed records, symlinks and uncertain pin
+stores remain protected. Age alone does not preserve an unsummarized session.
+Version 5 backs up unreferenced unsummarized sessions before a guarded `Sessions.delete`
+call that bypasses the ordinary age pin. Current sessions and every known
+learning/mistake/memory reference remain protected. `/sessions list` exposes
+`dependencies` as an array of files **referencing this session** (empty when
+none), not files this session depends on. `dependency_errors` lists unknown,
+malformed or unsafe stores; cleanup fails closed when it is nonempty.
+The shared index follows defined structural fields, not ID-looking text.
+Dependency-backed sessions remain visible and resumable, not archived away.
+Vault/config/credential payloads and historical backups are not scanned.
+Same-user interactive PWN
+processes defer deletion because existing writers have no lifetime leases; this is a
+conservative guard, not a cross-process session lease. Inspect without deleting:
+`ruby ~/.pwn/cron/session_cleanup.rb --dry-run`.
+
+`--apply` backs up eligible transcript/metadata bytes under
+`~/.pwn/session_cleanup_archive/<run>/` (directories 0700, files 0600), outside
+`/sessions list`. Atomic, fsynced backups are SHA-256 verified before deletion;
+file identities/hashes, title classification, reference stores and process state
+are rechecked under per-ID/transcript locks. `ledger.json` records exact IDs,
+hashes, skips and completed deletions; dry-run JSON contains metadata only and
+creates no archive. Backups are for recovery, not an automatic reference
+resolver: referenced placeholders remain in the active list until a separately
+verified archive-aware lookup policy exists. No memory, learning or mistake
+records are rewritten. The process checks and advisory locks do not claim a
+transactional guarantee against arbitrary non-cooperating external writers.
+
+The cleanup-specific pins additionally preserve every session ID referenced in
+retained learning, mistake and durable memory stores, including non-gold learning
+and old resolved mistakes. References are schema-aware:
+
+| Store / writer | Session reference |
+| --- | --- |
+| `learning.jsonl` / Learning; `policy_traj.jsonl` / Policy; `open_goal.json` / OpenGoal | Top-level `session_id` |
+| `mistakes.json` / Mistakes | Each signature record's `sessions[]` and `verified_sessions[]`; signature keys are not session IDs |
+| `memory.json`, `memory.archive.json` / Learning.reflect, Memory | Exact `reflect_<session ID>_<8-hex lesson digest>` keys; arbitrary memory keys, values and source strings are not links |
+| `jobs/<12-hex job ID>.json` / Jobs | Top-level `session_id`; command, environment and job ID are not links |
+| `swarm/*/personas.json` / Swarm | Persona-to-session map values, not persona names or swarm IDs |
+| `curriculum/log.jsonl` / Curriculum | `practice` event's `data[].runs[].session_id`; other events' prose is not traversed |
+| `extrospection.json` / Extrospection | `auto_extrospect` observations' second tag in `['drift', session ID]`; manual/other tags and observation data are not links |
+| `engagements/*/facts.jsonl` / Swarm | Top-level `source_session` |
+| `findings.jsonl` / Findings | Top-level `session_id`; exact transcript/sidecar paths in `evidence_paths[]` and `poc_artifacts[]` |
+| Engagement evidence and recon ledgers / Findings, Recon | Exact transcript/sidecar paths in `path` or `evidence_path`; includes the legacy root `engagements/evidence.jsonl` |
+| `artifacts/manifest.jsonl` / ArtifactRegistry | Top-level `session` and exact transcript/sidecar `source_path`; `kind: swarm-bus` uses `session` for a swarm ID, not session provenance |
+| `artifacts/<session ID>/index.jsonl`, `engagement-memory.json` | Session ownership from that exact directory; index `src` may also reference a transcript/sidecar |
+| `embeddings/<session ID>.db`, `sessions/<session ID>/trace.jsonl` | Ownership from that exact filename/directory, not database contents or trace tool payloads |
+
+IDs must be complete canonical values, not substrings or whitespace-normalized
+tokens. Only known evidence/source path fields pointing directly into the
+configured sessions directory are path references. There is currently no
+cross-session link field in transcript or title metadata schemas: listing,
+recalling, quoting JSON, or mentioning a session never pins it, including when
+`sessions_list` output is saved repeatedly. Self listings do not create pins.
+
+The index also validates the JSON containers in policy, preference, sentinel,
+skill-review and KPI stores, run checkpoints, mission ledgers, swarm bus/solve
+records, curriculum model/cooldown maps, engagement descriptors/hosts/scans and
+binary facts. These writers do **not** persist session ownership links; their
+arbitrary payloads, prompts, run/job IDs and user-selected labels must not be
+interpreted as such. Unknown JSON stores within the indexed directories are
+reported as uncertainty rather than silently ignored. Adding a new reference
+schema requires auditing its writer/callers and adding positive and negative
+fixtures, not a recursive key-name or text search. Vaults, loot payloads, arbitrary
+artifact content and backups remain outside this index.
+
+Native scalar tool `step_reward` fields are recognized;
+unknown transcript fields remain protected.
+
+`/sessions list` reads all transcript files afresh, not just cleanup candidates.
+In cleanup output, `unnamed` includes protected sessions; `candidate_ids` excludes
+them. Active sessions hold shared OS locks on permanent per-ID cleanup lock
+files; cleanup takes an exclusive nonblocking lock on the same inode before
+rechecking, backing up and deleting. An active A does not retain inactive B.
+CLI/REPL activation and resume transfer ownership, exit releases it, nested
+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.
+
+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,
+not that every session is active. Ask the operator to identify/quiesce those
+writers and restart using the updated source or deployed version before deleting
+ambiguous candidates. Do not infer active IDs from mtimes, titles or process-name
+matches, and do not bypass reference/summary guards. No config migration is needed.
+
 From a checkout:
 
 ```bash