pwn 0.5.763 → 0.5.771

data/documentation/Reinforcement-Learning.md

@@ -1,5 +1,85 @@
 # Reinforcement Learning in pwn-ai
 
+## Retained learning evidence and session cleanup
+
+Learning outcomes can retain a versioned `evidence_ref` (`version`, `id`,
+`sha256`) pointing to `~/.pwn/learning/evidence/<sha256>.json`. The existing
+`session_id` remains provenance. It ceases to pin a source transcript only
+after the artifact is readable, hash-valid, schema-valid, and its complete
+redacted transcript matches the unchanged source. A marker alone is not enough.
+Missing, modified, malformed or conflicting evidence does not authorize cleanup.
+Other stores, including mistakes, reflection memory and disputed learning,
+continue to pin their source sessions. Evidence files are never session-cleanup
+candidates; the dependency index exposes their referenced-by edges separately.
+
+No reliable turn-to-outcome boundary exists in legacy learning rows. Migration
+therefore preserves **every persisted transcript row**, including requests,
+tool actions, observations, results, timestamps and extra fields, with source
+session provenance and a SHA-256 of the original bytes. It uses the existing
+credential-pattern redactor, not a model or Vault, and does not summarize.
+Already compacted source content cannot be reconstructed; external artifact
+references stay references, and those artifacts must still be retained.
+
+Use the existing `learning_gc_stores` tool with
+`{"operation":"evidence_plan","dry_run":true}` for a read-only count/size
+report. This operation does not invoke store GC. The equivalent Ruby API in
+the existing `pwn` console is:
+
+```ruby
+PWN::AI::Agent::Learning.migrate_evidence(dry_run: true)
+```
+
+After reviewing the plan and explicitly approving writes, stop old installed
+PWN processes, scheduled maintenance and external editors first. Deploy the
+matching source before restarting: legacy installed writers do not participate
+in the new lock. Then use `learning_gc_stores` with
+`{"operation":"evidence_apply","dry_run":false}`, or
+`PWN::AI::Agent::Learning.migrate_evidence(dry_run: false)`.
+**Neither operation deletes sessions.** Review a separate session-cleanup
+dry run afterward; named/active/uncertain sessions remain protected by that
+cleanup policy. Do not infer session-count reduction from an evidence migration.
+
+Artifacts deduplicate by content hash. Files use 0600 and new directories 0700.
+Atomic, fsynced writes/readback precede the learning-index replacement. Original
+learning bytes and prepared/committed ledgers live under
+`~/.pwn/learning/migrations/`, outside legacy backup pruning. Core learning
+writers share a reentrant advisory lock; optimistic byte checks additionally
+reject observed source/index changes. These locks cannot coordinate arbitrary
+external editors or old installed versions: apply requires a quiescent store.
+Interrupted precommit runs leave original references intact and can be retried;
+an interruption after index replacement can leave a prepared ledger with a
+fully usable verified index. No partial artifact or staging file releases a pin.
+
+Before any source deletion, an unchanged migration can be rolled back with
+`PWN::AI::Agent::Learning.rollback_evidence(migration: '<ledger SHA-256 ID>')`,
+or tool operation `evidence_rollback` with the same `migration` field. Rollback
+verifies backup/index hashes and refuses later edits or absent/changed sources;
+it never overwrites concurrent learning. Keep recovery files private. They
+retain the exact original learning bytes, which can include legacy sensitive
+data. This is not an evidence garbage collector or a credential-store migration.
+
+Consumer audit: `Sessions.load` supplies verified evidence only when the legacy
+source is absent, keeping all existing ID-only consumers compatible. This covers
+`Learning` export_finetune, reflect, fold_judge_into_metrics,
+recover_predicted_from_session, infer_success, compress_exemplar,
+build_skill_from_session and requeue_conflicted; `Reward` run_verification,
+record_verification, request_verification and load_trace; `Curriculum`
+offline_judge and self_play; `Mistakes` previous_user/previous_assistant;
+`Memory.session_turns`; `tools/sessions.rb`; and REPL session-goal lookup.
+`Sessions.export` now uses that resolver too. `Curriculum.offline_judge` also
+discovers retained evidence outcomes after directory cleanup (outcome timestamp
+is its archived-session age). Invalid evidence raises at the resolver rather
+than masquerading as an empty transcript; existing consumer error/drop reporting
+continues to apply, with a metadata-only diagnostic when evidence cannot resolve.
+Reward's PRM annotation writer uses `Learning.annotate_evidence` when the source
+is absent: integer step rewards create a new content-hashed snapshot and replace
+references under the same backup/ledger/lock protocol. Supporting content and the
+old artifact remain unchanged; no session is recreated. Annotation rollback can
+restore verified prior evidence references even after original-session cleanup.
+DPO export already consumes self-contained preference
+pairs, not session files. New module/autoload/gemspec entries are unnecessary:
+the implementation extends existing paired modules.
+
 pwn-ai learns while you work. Most of that learning stays **in context**: the
 agent writes what happened to disk and puts the useful bits back into the next
 prompt. On a host **with a trainer and a GPU**, the same data can also train a

data/documentation/pwn-REPL.md

@@ -16,6 +16,46 @@ commands.
 
 ## Custom commands
 
+### pwn-ai session titles
+
+`/sessions list` shows stable IDs and titles of at most seven
+whitespace-separated words, matching the SESSION pane. The first request seeds
+a provisional title; the currently active LLM provider and selected model produce a concise conversation title
+after completed turns, with a deterministic seven-word fallback cap. The limit
+also applies to explicit titles. It does not shorten requests or apply to the
+rolling conversation summary.
+
+Title generation runs asynchronously after completed turns, never during drawing
+or keystrokes. It uses the previous overall summary plus new conversation turns,
+without changing the active provider or falling back to a different model. Missing
+credentials or failed/invalid responses retain the prior or provisional title;
+background title work never starts interactive authentication. Artifact summaries
+retain their separate local-only routing policy.
+
+Existing overlong titles are normalized when read, without rewriting transcripts
+or metadata merely to list them. `/sessions resume <title-or-id>`
+accepts the exact displayed title, optionally quoted. Internal quotes
+and Unicode whitespace are supported. If shortened titles collide, use the
+stable ID shown in the ambiguity message; IDs and transcript filenames do not
+change.
+Previously displayed titles remain resume aliases when a background summary
+renames the session, so a name copied from the list does not expire while typing.
+Aliases shared by multiple sessions are ambiguous too; use a stable ID.
+
+`dependencies` means **referenced by**: files containing defined structural
+references to that session. Transcript prose, prompts, tool results and quoted
+JSON—including previous `/sessions list` output—are not dependencies. An empty
+array means no known structural references; `dependency_errors` separately
+reports uncertainty and blocks scheduled cleanup. Dependency-backed sessions
+stay visible and resumable. See Installation's session-cleanup schema table.
+`title_source`, `is_summarized`, `classification` and `title_reason` expose the
+same strict provenance used by cleanup. Only persisted `summary` provenance with
+a nonblank summary/title and positive integer summary cursor counts as named.
+Provisional, manual, persona, historical and alias titles do not prove LLM work;
+legacy records explicitly report missing provenance. Unknown/malformed metadata
+is protected without being called summarized. Neither listing nor cleanup calls
+the LLM to manufacture provenance.
+
 | Command | Implemented in | Purpose |
 |---|---|---|
 | `pwn-ai` | `Agent::Loop` | Enter the AI agent TUI |
@@ -60,6 +100,40 @@ History includes messages and slash commands, skips blank lines and consecutive
 duplicates, and keeps the latest 100 entries in memory for the current pwn-mesh
 session only; it is not written to disk.
 
+### Message transport labels
+
+Each CONVERSATION header ends with its direction and the transport used for
+that individual message: `· RX via MQTT`, `· TX via Serial`, `· RX via Bluetooth`,
+or `· TX via TCP`. In `auto` mode this is the resolved connection, not the
+configured `auto` value. Received messages retain the subscribing transport's
+origin through queued rendering, even if the current transport changes.
+Missing origin metadata is shown as `Unknown`, not guessed from the current pin.
+
+Headers use `timestamp encryption · SHORT NAME · source path · destination path · direction via transport`,
+with exactly one space on either side of each `·`. RX uses the sender's
+`User.short_name` (`shortName` in JSON); TX uses the sending local node's User,
+never the destination's name. Device connections use their NodeInfo/NODEINFO
+inventory. MQTT learns NODEINFO announcements in a bounded, connection-local
+inventory (up to 1000 users), including the sending identity if advertised.
+Names are captured with each message, so later inventory or binding changes do
+not rename queued messages. Missing or blank short names omit that field and
+its separator; long names, node-ID fragments and gateway names are not substitutes.
+ANSI CSI sequences are removed, control/newline characters and literal `·` in
+names become spaces, and surrounding Unicode whitespace is trimmed. Other
+Unicode text and internal spaces are retained. Names are labels, not authenticated identities.
+
+For example (placeholder node IDs):
+
+```text
+2026-01-02 03:04:05+0000 🔍 · PEER · US/CA/2/e/LongFast/!aabbccdd · US/CA/2/e/LongFast/# · RX via MQTT
+2026-01-02 03:04:06+0000 🔍 · SELF · US/CA/2/e/LongFast/!bbccddee (ME) · US/CA/2/e/LongFast/# · TX via Serial
+```
+
+The timestamp, encryption indicator, source/destination paths, channel and
+`(ME)` marker keep their existing meaning. The suffix identifies the local
+client connection, not every RF or broker hop. A TX header means local transport
+submission; it does not confirm over-the-air delivery or peer receipt.
+
 ### Encrypted DMs and key discovery
 
 On serial, Bluetooth, or TCP, a DM checks the destination's public key in the

data/documentation/pwn-ai-Agent.md

@@ -9,6 +9,75 @@ so it doesn't repeat it**.
 
 ## Two ways to run it
 
+### Local operator workspace
+
+The curses console exposes these local views through the command menu:
+
+* `/sessions` (or `/sessions picker`) opens a searchable picker. Type to filter
+  titles or stable IDs, use Up/Down to select, Enter to inspect local activity,
+  held activity lease, summary provenance, referenced-by paths and any recorded
+  unfinished goal, then `r` to resume that exact ID. Duplicate titles are never
+  guessed. Tab refreshes while preserving the selected ID. Esc restores the draft.
+* `/readiness` previews the configured four-role routes, credential **presence**
+  (never credential values), local required tool paths, workspace and limits.
+  `w` toggles optional Git-worktree execution, `+`/`-` sets 1–10 repair rounds,
+  `t` cycles the bounded per-check timeout and `r` cycles the per-role timeout.
+  These console-lifetime options
+  feed the next mission without modifying the objective or encrypted config.
+  Navigation never logs in, installs dependencies or calls a provider. Readiness
+  is not a connectivity test; task-specific dependencies are not inferred.
+* `/evidence` lists retained mission records and current console mission snapshots.
+  Enter inspects the original requirements, candidate revision, artifacts,
+  executed checks, observations, blockers and recorded outcome. Tab reloads
+  persisted records. A canceled mission retains its evidence. On a worktree
+  result, `d` opens the checksum-verified changed/deleted-file patch; `a` then
+  requires typing `APPLY <tested-revision>`. The backend rechecks source,
+  candidate, patch and tested revision before applying; it never stages or commits.
+  `x` requests removal of an owned checkout after typing `DISCARD <revision>`
+  (or its displayed ownership token before a candidate exists). A changed checkout
+  is refused with recovery guidance; patch and evidence are retained.
+  Running phase checkpoints are atomically persisted before publication, including
+  actual check records, uncovered requirements and repair reasons.
+  Worktrees isolate edits, **not** arbitrary code execution or network access.
+* `/sessions cleanup` previews the same provenance/dependency policy as scheduled
+  cleanup. Inspect the exact IDs, paths, fingerprints, retention reasons and
+  uncertainty. `a`, then Enter confirms only the displayed candidate set.
+  Newly discovered or changed records are excluded. Apply rechecks activity,
+  references and source bytes under locks, backs up candidate bytes, and reports
+  actual deletions and skipped records. No deletion happens during preview.
+* `/learning inbox` lists learning outcomes and retained skill proposals.
+  Enter inspects the exact procedure, source fields and fingerprints; `e` inspects
+  retained execution evidence. `a` approves, `x` rejects and `u` rolls back, each
+  requiring Enter confirmation. For skills, approval appends the proposed procedure
+  to an existing non-generated skill; rollback restores its backup only if the
+  approved file is unchanged. Source changes, absent or failing independent proof,
+  conflicted outcomes, generated skills and legacy proposals without procedure
+  payload remain blocked. Creation of a new skill is not enabled by this approval
+  API. Outcome decisions remain audit records, never fabricated training labels.
+  SkillReview evidence references use `learning_id` and `learning_sha256` for an
+  immutable learning row with retained full-session evidence and passing host
+  Verification checks. A model's `fixture_passed` assertion alone is insufficient,
+  including in `auto-safe` mode. No provider is called during review.
+* `/guide` is a short dismissible guide. Its numbered examples insert editable
+  draft text without executing it; existing drafts are retained. `x` records
+  dismissal in a private local preference marker; Esc closes without writing it.
+
+All these overlays support scrollback with PgUp/PgDn/Home/End and preserve the
+mission draft. Requested cancellation and pause are not reported as completion:
+pause becomes observed only at a coordinator boundary. Local list/readiness scans
+run on a coalesced event worker; stale results cannot replace a newly opened view.
+Ordinary curses and legacy steerable requests and missions share canonical-workspace
+admission locks; a second writer receives
+an actionable busy error. Other applications and unupgraded clients do not honor
+these advisory locks.
+
+For Ruby callers, `PWN::AI::Agent::Swarm.solve(request: objective, workspace: root,
+worktree: true, rounds: 3, verification_timeout: 60, role_timeout: 300)` uses the
+same mission backend. Timeouts are 1–600 seconds; rounds are 1–10. Worktree mode
+requires a clean Git root (including ignored and untracked files). It does not
+stage, commit or automatically apply the candidate. Preserve `request` verbatim;
+options are separate from the objective.
+
 ```text
 # 1. Interactive curses console (inside the pwn REPL)
 pwn[CURRENT_VERSION]:001 >>> pwn-ai
@@ -164,6 +233,7 @@ changes only default values, not the configuration schema; no migration is neede
 | PgUp/PgDn | Scroll the timeline; new output does not pull a scrolled viewport to the bottom |
 | `/model`, `/sessions resume ID` | Show model settings / change the next request's model or session while idle |
 | `/system-role` | Open the active engine's multiline SYSTEM ROLE CONTENT editor while idle; Ctrl+S saves, Esc cancels |
+| `/vault edit [key ...]` | Privately edit encrypted configuration or one nested mapping scope; Ctrl+S saves, Esc/Ctrl+C cancels |
 | `/steer INSTRUCTION` | Redirect the active request at a safe boundary |
 | `/input TEXT` | Send one line to an ordinary tool stdin prompt; not retained in input recall |
 | Ctrl+C | Cancel the active request cooperatively, or clear an idle draft |
@@ -197,6 +267,58 @@ the new role immediately, and a new session loads it from the vault. Request or
 swarm activity blocks role changes. No schema migration is required. The legacy
 non-curses interface reports that this editor requires an interactive terminal.
 
+### Private vault editor
+
+`/vault edit` opens the complete **PRIVATE YAML** document; `/vault edit ai
+anthropic` opens that nested mapping, and `/vault edit ai anthropic model`
+opens a scalar. Tokens identify one nested key path, never filenames or multiple
+disjoint scopes. The target and decryptor are the same `driver_opts.pwn_env_path`
+and `driver_opts.pwn_dec_path` used by `pwn-vault`, defaulting to
+`~/.pwn/pwn.yaml` and its existing `.decryptor` sidecar. Unknown paths are rejected; edit the parent mapping
+to add a new key. Arrays are edited as a whole, not by numeric path indices.
+Existing non-null types must be retained; an existing null may remain null or
+be replaced by a YAML value. The root must retain an `ai` mapping, a supported
+`ai.active`, and its engine mapping. Mapping keys may be added or removed within
+the selected scope. Duplicate keys, aliases, object tags and multiple documents
+are rejected. Nesting is limited to 100 mappings/sequences, including the merged
+full document and decryptor parsing, before recursive YAML conversion. Invalid
+input leaves the encrypted file intact. YAML formatting/comments are normalized on save.
+
+Enter inserts a newline, arrows move, Home/End move to the document ends and
+Ctrl+U clears. **Ctrl+S** explicitly saves encrypted; **Esc/Ctrl+C** discards
+changes, and Ctrl+D leaves without saving. Save errors remain redacted inside
+the modal so the text can be corrected. No editor contents enter SESSION,
+history, completion suggestions, logs or provider requests. Completion suggests
+only shipped schema key names, never reads/decrypts the vault, and never offers
+configuration values; existing custom keys can be typed explicitly.
+
+Plaintext is decrypted/edited in memory. Only encrypted bytes enter the private
+temporary file, which is atomically renamed over the vault using the same
+AES-256-CBC format/key/IV as `pwn-vault`; the decryptor is not regenerated.
+Save re-reads the current document, preserves changes outside the selected scope,
+and refuses a changed selected scope (the whole document for unscoped edits).
+Editor instances serialize saves with a directory lock; a final ciphertext check
+also detects intervening changes from other writers. Configuration is updated
+locally without running authentication or `Config.refresh_env`. Editing is
+blocked while a request/swarm is active. The legacy non-curses interface explains
+that an interactive curses console is required and makes no changes.
+
+### Bounded nested data
+
+JSON-bound tool results, schema copies/normalization, MCP arguments, Swarm key
+conversion and persistence redaction reject cyclic or over-deep containers with
+`JSON::NestingError`, using the serializer's 100-container default. Credential
+collection for result redaction walks the environment by identity without Ruby
+recursion, so repeated or cyclic mappings do not prevent credential replacement.
+Redaction validates even sensitive-field containers before inspecting them;
+invalid input fails closed rather than returning a raw value. Valid shared
+branches remain independent output copies and inputs are not modified.
+
+Local XML ingestion preflights element depth (maximum 100) before recursive
+REXML XPath/formatting, and rejects excessive nesting with `ArgumentError`
+before database or embedding work. These bounds cover the named preprocessing
+paths, not arbitrary Ruby/plugin callbacks or all possible VM stack failures.
+
 ### Model and reasoning selection
 
 `/model` (also `show` or `status`) displays the current selection. Existing

data/etc/default_cron/session_cleanup.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+# PWN managed default: session_cleanup v6
+# No provider calls or broad store GC. Unsummarized candidates are backed up first.
+require 'pwn'
+require 'json'
+require 'fileutils'
+require 'time'
+require 'digest'
+require 'securerandom'
+
+module PWN
+  # Provenance-based session cleanup, shared by seeded cron payloads.
+  module SessionCleanup
+    VERSION = 6
+
+    def self.classify(path, id)
+      return :unknown unless path == File.join(PWN::Sessions.sessions_dir, "#{id}.jsonl")
+
+      PWN::Sessions.title_status(session_id: id)[:classification]
+    end
+
+    # Compatibility discovery only: upgraded launchers never block unrelated
+    # sessions. Legacy in-memory IDs cannot safely be inferred from recent mtimes.
+    def self.legacy_owners(proc_root)
+      return [{ error: 'process_inventory_unavailable' }] unless File.directory?(proc_root)
+
+      Dir.glob(File.join(proc_root, '[0-9]*')).filter_map do |dir|
+        next if File.basename(dir).to_i == Process.pid
+        next unless File.stat(dir).uid == Process.uid
+
+        argv = File.binread(File.join(dir, 'cmdline')).split("\0")
+        next unless pwn_launcher?(argv, dir)
+        next if tracked_owner?(dir)
+
+        { pid: File.basename(dir).to_i, reason: 'legacy_session_ownership_unknown' }
+      rescue Errno::ENOENT, Errno::ESRCH
+        nil
+      rescue IOError, SystemCallError
+        { pid: File.basename(dir).to_i, reason: 'ownership_unreadable' }
+      end
+    rescue IOError, SystemCallError
+      [{ error: 'process_inventory_unreadable' }]
+    end
+
+    def self.pwn_launcher?(argv, dir)
+      executable = %r{\A(?:[^\s]*/)?pwn(?:-[a-zA-Z0-9_-]+)?\z}
+      return true if argv.first.to_s.match?(executable)
+      return false unless argv.first.to_s.match?(%r{\A(?:[^\s]*/)?ruby[\d.]*(?:\s|\z)})
+      return false unless File.basename(File.readlink(File.join(dir, 'exe'))).match?(/\Aruby[\d.]*\z/)
+      return true if argv.first.to_s.match?(%r{\A\S*ruby[\d.]*\s+(?:[^\s]*/)?pwn(?:-[a-zA-Z0-9_-]+)?\z})
+
+      args = argv.drop(1)
+      while args.first&.start_with?('-')
+        option = args.shift
+        break if option == '--'
+        break args.clear if option.start_with?('-e')
+
+        args.shift if %w[-I -r -C -E -F].include?(option)
+      end
+      args.first.to_s.match?(executable)
+    end
+
+    def self.tracked_owner?(dir)
+      return false unless File.file?(File.join(dir, 'stat'))
+
+      start = File.read(File.join(dir, 'stat')).split(') ').last.split[19]
+      # fdinfo proves this process holds the locked open-file description, not
+      # merely an unlocked descriptor to another process's marker. Forked tool
+      # workers inherit that capability and the precise session leases; they
+      # must not be mistaken for untracked legacy launchers. A reused PID alone
+      # has neither descriptor. Marker filenames bind the original PID/start.
+      tracked = Dir.glob(File.join(dir, 'fd', '*')).any? do |fd|
+        marker = File.readlink(fd)
+        next false unless File.basename(marker).match?(/\A\.activity-owner-\d+-\d+\.lock\z/)
+
+        info = File.read(File.join(dir, 'fdinfo', File.basename(fd)))
+        info.match?(/^lock:\s+\d+:\s+FLOCK\s+ADVISORY\s+WRITE\s/)
+      rescue Errno::ENOENT
+        false
+      end
+      tracked && File.read(File.join(dir, 'stat')).split(') ').last.split[19] == start
+    end
+
+    def self.pins_known?
+      referenced_session_ids
+      true
+    rescue StandardError
+      false
+    end
+
+    # Cleanup preserves evidence referenced by all retained learning, mistake
+    # and durable memory records, not just the ordinary gold/open/hot pins.
+    def self.referenced_session_ids
+      references = PWN::Sessions.dependency_index
+      raise 'Uncertain dependency stores' unless references[:errors].empty?
+
+      references[:dependencies].keys
+    end
+
+    # Fingerprints include inode identity and nanosecond timestamps, not bodies.
+    def self.snapshot(path)
+      [path, path.sub(/\.jsonl\z/, '.meta.json')].to_h do |file|
+        raise 'Refusing symlink' if File.symlink?(file)
+        next [File.basename(file), nil] unless File.exist?(file)
+
+        stat = File.stat(file)
+        raise 'Not a regular file' unless stat.file?
+
+        [File.basename(file), { sha256: Digest::SHA256.file(file).hexdigest, size: stat.size, inode: stat.ino, device: stat.dev, mtime: stat.mtime.to_r.to_s, ctime: stat.ctime.to_r.to_s }]
+      end
+    end
+
+    def self.publish(path, bytes)
+      temporary = "#{path}.#{SecureRandom.hex(8)}.tmp"
+      File.open(temporary, File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW, 0o600) do |file|
+        file.write(bytes)
+        file.flush
+        file.fsync
+      end
+      File.rename(temporary, path)
+      File.open(File.dirname(path), File::RDONLY, &:fsync)
+    ensure
+      File.unlink(temporary) if temporary && File.exist?(temporary)
+    end
+
+    def self.backup(path, expected, result)
+      unless result[:archive_dir]
+        base = File.join(Dir.home, '.pwn', 'session_cleanup_archive')
+        raise 'Unsafe archive directory' if File.symlink?(base)
+
+        FileUtils.mkdir_p(base, mode: 0o700)
+        raise 'Unsafe archive permissions' unless File.stat(base).uid == Process.uid && (File.stat(base).mode & 0o777) == 0o700
+
+        result[:archive_dir] = File.join(base, "#{Time.now.utc.strftime('%Y%m%dT%H%M%S')}-#{SecureRandom.hex(8)}")
+        Dir.mkdir(result[:archive_dir], 0o700)
+      end
+      expected.each do |name, record|
+        next unless record
+
+        source = File.join(File.dirname(path), name)
+        bytes = File.binread(source)
+        raise 'Changed before backup' unless Digest::SHA256.hexdigest(bytes) == record[:sha256]
+
+        target = File.join(result[:archive_dir], name)
+        publish(target, bytes)
+        raise 'Backup verification failed' unless Digest::SHA256.file(target).hexdigest == record[:sha256]
+      end
+      publish(File.join(result[:archive_dir], 'ledger.json'), JSON.pretty_generate(result))
+    end
+
+    def self.run(dry_run: true, current_session_id: nil, proc_root: '/proc', approved_candidates: nil)
+      raise 'Session cleanup requires the updated Sessions activity API; load the updated source or deploy it before running this helper' unless PWN::Sessions.respond_to?(:activate)
+
+      root = PWN::Sessions.sessions_dir
+      raise 'Refusing symlinked session directory' if File.symlink?(root)
+
+      current = current_session_id || (PWN::Env.dig(:ai, :session_id) if defined?(PWN::Env))
+      legacy = legacy_owners(proc_root)
+      result = { version: VERSION, dry_run: dry_run, scanned: 0, unnamed: 0, candidate_ids: [], deleted_ids: [], records: [], skipped: Hash.new(0), legacy_owners: legacy }
+      unless pins_known?
+        result[:skipped][:unknown_pins] = 1
+        result[:dependency_errors] = PWN::Sessions.dependency_index[:errors]
+        return result
+      end
+      dependencies = PWN::Sessions.dependency_index[:dependencies]
+      pins = referenced_session_ids
+      Dir.glob(File.join(root, '*.jsonl')).each do |path|
+        id = File.basename(path, '.jsonl')
+        result[:scanned] += 1
+        state = classify(path, id)
+        record = PWN::Sessions.title_status(session_id: id).merge(id: id, classification: state, dependencies: dependencies.fetch(id, []))
+        result[:records] << record
+        unless state == :unnamed
+          result[:skipped][state] += 1
+          next
+        end
+        expected = snapshot(path)
+        record[:files] = expected
+        if approved_candidates && approved_candidates[id] != expected
+          record[:skip] = :not_approved_or_changed
+          result[:skipped][:not_approved_or_changed] += 1
+          next
+        end
+        result[:unnamed] += 1
+        if PWN::Sessions.active?(session_id: id)
+          record[:skip] = :active
+          result[:skipped][:active] += 1
+          next
+        end
+        if id == current || pins.include?(id)
+          reason = id == current ? :current : :referenced
+          record[:skip] = reason
+          result[:skipped][reason] += 1
+          next
+        end
+        result[:candidate_ids] << id
+        record[:apply_blocked_by] = :unknown_legacy_ownership unless legacy.empty?
+        next if dry_run
+
+        unless legacy.empty? && legacy_owners(proc_root).empty?
+          record[:skip] = :unknown_legacy_ownership
+          result[:skipped][:unknown_legacy_ownership] += 1
+          next
+        end
+        # Never unlink lock files: waiters must keep sharing the same inode.
+        lock_path = File.join(root, ".#{id}.cleanup.lock")
+        raise 'Refusing symlinked cleanup lock' if File.symlink?(lock_path)
+
+        File.open(lock_path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+          unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+            result[:skipped][:locked] += 1
+            record[:skip] = :locked
+            next
+          end
+          File.open(path, File::RDONLY | File::NOFOLLOW) do |transcript|
+            unless transcript.flock(File::LOCK_EX | File::LOCK_NB)
+              result[:skipped][:locked] += 1
+              record[:skip] = :locked
+              next
+            end
+            # Activation and deletion serialize on the same per-session inode.
+            # Legacy ownership uncertainty still requires operator migration.
+            unless File.identical?(transcript, path) && classify(path, id) == :unnamed && snapshot(path) == expected && legacy_owners(proc_root).empty? && pins_known? && !referenced_session_ids.include?(id)
+              result[:skipped][:changed] += 1
+              record[:skip] = :changed
+              next
+            end
+            backup(path, expected, result)
+            unless snapshot(path) == expected && classify(path, id) == :unnamed && legacy_owners(proc_root).empty? && pins_known? && !referenced_session_ids.include?(id)
+              result[:skipped][:changed] += 1
+              record[:skip] = :changed
+              next
+            end
+            # Only verified, archived, unreferenced unsummarized sessions;
+            # current and all known reference pins checked above.
+            # The normal delete API's age pin is deliberately bypassed here.
+            PWN::Sessions.delete(session_id: id, current_session_id: current, force: true, cleanup_lock: lock)
+            raise 'Deletion did not remove both session records' if File.exist?(path) || File.exist?(path.sub(/\.jsonl\z/, '.meta.json'))
+
+            result[:deleted_ids] << id
+            record[:deleted] = true
+            publish(File.join(result[:archive_dir], 'ledger.json'), JSON.pretty_generate(result))
+          end
+        end
+      rescue StandardError => e
+        result[:skipped][:error] += 1
+        record[:error] = e.class.name if record
+      end
+      publish(File.join(result[:archive_dir], 'ledger.json'), JSON.pretty_generate(result)) if result[:archive_dir]
+      result
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  raise 'Use --dry-run or --apply' unless ARGV.length == 1 && %w[--dry-run --apply].include?(ARGV.first)
+
+  puts JSON.generate(PWN::SessionCleanup.run(dry_run: ARGV.first == '--dry-run'))
+end

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

@@ -36,6 +36,7 @@ PWN::AI::Agent::Dispatch.call(opts)
 - `call`
 - `repair_name`
 - `tool_calls_from_text`
+- `scheduling`
 - `effect`
 - `authors`
 - `help`

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

@@ -28,11 +28,17 @@ Class methods take `(opts = {})` and read `opts`.
 
 ```ruby
 PWN::AI::Agent::Learning.help
-PWN::AI::Agent::Learning.note_outcome(opts)
+PWN::AI::Agent::Learning.evidence_transcript(opts)
 ```
 
 ## Public methods
 
+- `evidence_transcript`
+- `session_evidence`
+- `evidence_complete`
+- `migrate_evidence`
+- `annotate_evidence`
+- `rollback_evidence`
 - `note_outcome`
 - `consistency_check`
 - `disputed_save`
@@ -63,6 +69,7 @@ PWN::AI::Agent::Learning.note_outcome(opts)
 - `authors`
 - `help`
 - `compact!`
+- `evidence_complete?`
 - `gc_stores!`
 - `lean!`
 - `prune_outcomes!`
@@ -74,5 +81,5 @@ PWN::AI::Agent::Learning.note_outcome(opts)
 
 ## Verification
 
-`PWN::AI::Agent::Learning.respond_to?(:note_outcome)` after the
+`PWN::AI::Agent::Learning.respond_to?(:evidence_transcript)` after the
 module is loaded. Read the source for parameter names.

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

@@ -35,6 +35,7 @@ PWN::AI::Agent::OpenGoal.goal_file(opts)
 
 - `goal_file`
 - `current`
+- `for_session`
 - `begin`
 - `clear`
 - `resume`

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

@@ -36,6 +36,8 @@ PWN::AI::Agent::SkillReview.review(opts)
 - `review`
 - `review_turn`
 - `note_reuse`
+- `decide`
+- `evidence_transcript`
 - `authors`
 - `help`
 

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

@@ -28,11 +28,13 @@ Class methods take `(opts = {})` and read `opts`.
 
 ```ruby
 PWN::AI::Agent::Solve.help
-PWN::AI::Agent::Solve.help(opts)
+PWN::AI::Agent::Solve.apply_patch(opts)
 ```
 
 ## Public methods
 
+- `apply_patch`
+- `cleanup_worktree`
 - `authors`
 - `help`
 
@@ -42,5 +44,5 @@ PWN::AI::Agent::Solve.help(opts)
 
 ## Verification
 
-`PWN::AI::Agent::Solve.respond_to?(:authors)` after the
+`PWN::AI::Agent::Solve.respond_to?(:apply_patch)` after the
 module is loaded. Read the source for parameter names.

data/etc/default_skills/pwn/ai/context_ingestion/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 
 # PWN::AI::Context
 
-Local evidence ingestion; unavailable embeddings never become synthetic vectors.
+Local evidence ingestion; XML is bounded to 100 element levels before XPath. Unavailable embeddings never become synthetic vectors.
 
 ## When to use