pwn 0.5.782 → 0.5.783

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15a843d292cc4872961ee750110b60f259e14c1f50185522ee9a219f8dabf75d
-  data.tar.gz: 00c12b64346f6e35d8f6d44b638c1e9e0edb856390db76834fb72a65471d0ac7
+  metadata.gz: 43f675e7e241c2f9c2ac2b96c52b43259b337871bc3227fb2cbac832457f7f23
+  data.tar.gz: c053c15cff377d88ee43b25103203928eaa037c3bca976fd6d6483d5543ad5fd
 SHA512:
-  metadata.gz: cb8ac9969959a5403b761a906497337852619dcbeef1c9f5a12956eb062963409426feaba0a188c3d10a278a422364c602fb30947ea28ef63b8f49d477e49b63
-  data.tar.gz: 0c79e7ce4c8f77974f25574bf309ce72e5b46ad40e562de334d653765b66f130959a65a157d567242f1756ed493a5e7c8d6febf435579ef1243ea969d8a57f9e
+  metadata.gz: eca4d79da6a33b24ec42cbc39c7c07afd0cfec053f98a49655b2bd6ef3c93bbba32f91aa90e755fe88eb8ec7bb13db892f87ade9e6b715b2d14f0b867415e576
+  data.tar.gz: 8c8dad0dd07d97a0b4941fadf03683dd14cfe7fe045c06431d7f725c39ea4dadaac76988a722efaa9186abe71fa4ba731b95c8ae0fa58b1efd0d7baa367f45b1

data/documentation/Installation.md

@@ -221,12 +221,18 @@ 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.
+Version 7 backs up unreferenced unsummarized sessions before a guarded `Sessions.delete`
+call that bypasses the ordinary age pin. `/sessions list` shows only valid
+LLM-summary-title or valid dependency-backed sessions, excluding sessions with
+attributed dependency errors. Active leases protect bytes even when a session
+is hidden. Explicit resume and `Sessions.list(include_hidden: true)` still reach
+hidden records. `dependencies` lists files **referencing this session**, not
+files it depends on. Per-session `dependency_errors` contains only safely
+attributed errors; `unresolved_dependency_stores` reports global uncertainty.
+The index's `errors` remains the unattributed store list: it blocks apply and is
+reported as `unresolved_store_remediation`, never copied onto every session.
+Parsed rows are validated independently so an invalid shared row does not
+invalidate unrelated good records.
 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.
@@ -242,9 +248,27 @@ 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.
+verified archive-aware lookup policy exists. Invalid learning evidence rows with
+one proven session owner can be removed with their inactive session under the
+Learning writer lock. The entire original shared store is backed up; only the
+invalid row is removed, keeping unrelated rows byte-for-byte. Prepared/committed
+`dependency_removals` ledger entries record hashes, row locators and backup paths.
+Approval and locked rechecks bind both transcript and dependency fingerprints.
+Valid references still protect a session; conflicting valid/invalid references,
+multiple owners, and attributed stores without a cooperating permanent writer
+lock report `unresolved_dependency_remediation` and remain physically untouched.
+Memory, its archive, and Mistakes now use permanent reentrant store transactions
+covering complete read-modify-write operations, including Learning consolidation
+and noise purging. Single-owner invalid map entries can be removed under those
+locks with whole-store backups and prepared/committed ledgers; unrelated map
+entries retain their values (JSON formatting may change). Stale expiry snapshots
+cannot remove refreshed memory. Corrupt Mistakes input raises rather than
+falling back to an empty map. Other stores (including disputed learning, findings,
+policy trajectories and event logs) remain unresolved when no safe targeted writer
+protocol exists. Deploy all cooperating writers before enabling remediation; old
+installed writers do not honor the new locks. No shared store is wiped. 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

data/documentation/pwn-REPL.md

@@ -45,9 +45,37 @@ 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.
+array means no known structural references. `dependency_errors` contains only
+errors attributed to this session; `unresolved_dependency_stores` reports global
+uncertainty without assigning blame. Lists always include the current active
+session, even while its title is provisional or summary generation failed.
+Other rows require valid summary provenance or valid structural dependencies.
+This display exception does not confer summary provenance or bypass cleanup:
+activity leases still prevent physical deletion. Explicit resume remains available.
+`/sessions list [offset] [limit]` defaults to the newest page, ordered oldest-first
+within that page. An explicit offset starts at that oldest-first position.
+The current session is marked `active: true` and included once even outside the
+requested page (so at most limit + 1 rows). `total` counts unique visible sessions;
+`offset` and `has_more` describe the base page, not the extra active row.
+Global unresolved stores and specific diagnostics are reported once in the envelope.
+Title workers capture the active provider/model when the request starts, summarize
+only that session's persisted conversation, and retry on resume. Pending work is
+coalesced per session rather than dropping another session's update. Failed or
+invalid generation keeps the previous title and cursor, and reports a warning
+without exposing provider payloads. It never fabricates `title_source: summary`.
+`/sessions cleanup` applies the bundled cron maintenance operation; use
+`/sessions cleanup --dry-run` for a read-only preview. Migration preserves full
+redacted learning snapshots and their offline readers; it does not manufacture
+lossless migrations for other stores. Unknown global ownership blocks apply.
+Prepared/committed maintenance ledgers and recoverable backups live outside
+ordinary backup pruning. Old writers must be quiesced before live deployment;
+updating a helper alone does not update a running process.
+Request checkpoints use a version-1, hash-bound identity adapter: their session
+field is provenance because restore consumes the checkpoint itself. Unknown
+versions, fields and mismatched paths remain unresolved; checkpoint bytes are
+never rewritten by cleanup. Other unmigrated evidence edges remain retained.
+`Sessions.list(include_hidden: true)` is the diagnostic inventory. See
+Installation's session-cleanup schema table and remediation limitations.
 `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.

data/documentation/pwn-ai-Agent.md

@@ -39,8 +39,68 @@ The curses console exposes these local views through the command menu:
   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
+* `/sessions list [offset] [limit]` is a page, not a retention limit. The
+  envelope reports `returned`, visible `total`, `physical_sessions`,
+  `filtered_sessions`, `has_previous` and `has_more`, plus a disjoint root-entry
+  `storage` breakdown. Filtered transcripts remain physically retained and explicitly
+  resumable. Neither pagination nor layout migration deletes summarized sessions.
+* Offline housekeeping migration is separate from ordinary cleanup. After deploying
+  matching source and stopping **all** launchers, workers and cron schedulers, run
+  from the checkout:
+
+  ```ruby
+  require 'pwn'
+  require './etc/default_cron/session_cleanup'
+  PWN::SessionCleanup.reorganize # metadata-only plan; no changes
+  PWN::SessionCleanup.reorganize(dry_run: false, writers_stopped: true)
+  PWN::SessionCleanup.run(dry_run: true) # inspect remaining retention categories
+  # Only after reviewing the ledger and approving cleanup:
+  PWN::SessionCleanup.run(dry_run: false)
+  ```
+
+  Launch Ruby with `bundle exec ruby -Ilib` so this uses matching source, not an
+  older installed gem. `writers_stopped` is an operator assertion, not a way to
+  bypass held leases or unknown legacy owners. Backups and prepared/committed
+  ledgers live in private `~/.pwn/session_cleanup_archive` directories. The layout
+  migration moves unreferenced metadata and lease inodes under `sessions/support`;
+  new trace support also uses that layout. Existing trace paths and dependency-backed
+  metadata stay at their exact locations to preserve evidence anchors and are
+  reported in `retained_support`. Canonical transcripts stay at the root. Abandoned numeric-PID transcript temp
+  files are removed only after exact recoverable backups in this offline operation.
+  Held own-process capability markers stay in place; other active owners block.
+  Readers accept legacy and compact paths, including partially completed moves.
+  Do not restart old binaries after applying the layout. Unknown files, mesh
+  mappings and request checkpoints remain untouched. Complete policy trajectories
+  are self-contained training provenance, not transcript-retention edges; incomplete
+  legacy trajectories and other unresolved evidence consumers still retain sources.
+* Historical IDs are not automatically transcript dependencies. The shared index
+  validates self-contained Mistakes records (error/fix/counters), Memory reflection
+  values, Extrospection drift observations and Curriculum practice results before
+  treating their session IDs as provenance. These stores are not rewritten or
+  deleted by this classification. Incomplete records still pin their identified
+  source; malformed containers remain diagnostics. No summary or training label
+  is invented. Mistakes' previous-turn readers and Memory's session-turn reader
+  operate on the caller's current session, not historical occurrence IDs.
+  Curriculum's practice log is an audit log, not a replay/evaluation queue.
+* Actual Learning transcript consumers retain full redacted, content-addressed
+  evidence through the existing migration before transcript deletion. Sessions.load,
+  Curriculum.offline_judge discovery and Reward PRM copy-on-write annotation use
+  the verified evidence; source hashes and complete source equality are checked
+  before releasing a live transcript. Overlapping provenance records no longer
+  prevent that preservation/re-index/deletion transaction.
+* Swarm `personas.json` is different: `Swarm.ask` calls `persona_session`, which
+  reuses its ID and acquires a writable-session lease for `Loop.run`. `retire`
+  removes an agents.yml registration, not that association; an explicit persona
+  or later respawn can reuse it. There is no persisted association-completed or
+  retired-session marker. Neither old mtime, an absent registry name nor a
+  completed bus message proves a map obsolete. Such mappings remain protected,
+  even with a Learning snapshot, because a read-only training artifact is not a
+  writable continuation. Cleanup does not silently archive them or impose a cap.
+* `/sessions cleanup` runs the same maintenance operation as bundled cron:
+  validate, preserve supported learning evidence, remediate attributable invalid
+  records with recoverable backups, re-index, and remove eligible inactive sessions.
+  `/sessions cleanup --dry-run` previews without changing evidence or deleting
+  sessions. 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

data/etc/default_cron/session_cleanup.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# PWN managed default: session_cleanup v6
+# PWN managed default: session_cleanup v9
 # No provider calls or broad store GC. Unsummarized candidates are backed up first.
 require 'pwn'
 require 'json'
@@ -12,7 +12,7 @@ require 'securerandom'
 module PWN
   # Provenance-based session cleanup, shared by seeded cron payloads.
   module SessionCleanup
-    VERSION = 6
+    VERSION = 9
 
     def self.classify(path, id)
       return :unknown unless path == File.join(PWN::Sessions.sessions_dir, "#{id}.jsonl")
@@ -100,7 +100,7 @@ module PWN
 
     # Fingerprints include inode identity and nanosecond timestamps, not bodies.
     def self.snapshot(path)
-      [path, path.sub(/\.jsonl\z/, '.meta.json')].to_h do |file|
+      [path, PWN::Sessions.support_path(kind: :metadata, session_id: File.basename(path, '.jsonl'))].to_h do |file|
         raise 'Refusing symlink' if File.symlink?(file)
         next [File.basename(file), nil] unless File.exist?(file)
 
@@ -138,7 +138,7 @@ module PWN
       expected.each do |name, record|
         next unless record
 
-        source = File.join(File.dirname(path), name)
+        source = name.end_with?('.meta.json') ? PWN::Sessions.support_path(kind: :metadata, session_id: File.basename(name, '.meta.json')) : File.join(File.dirname(path), name)
         bytes = File.binread(source)
         raise 'Changed before backup' unless Digest::SHA256.hexdigest(bytes) == record[:sha256]
 
@@ -149,7 +149,278 @@ module PWN
       publish(File.join(result[:archive_dir], 'ledger.json'), JSON.pretty_generate(result))
     end
 
+    # Only stores with a cooperating permanent writer lock are auto-remediated.
+    # Other attributed errors remain explicit operator work, never broad GC.
+    def self.invalid_dependencies(id, references = nil)
+      (references || PWN::Sessions.dependency_index)[:invalid_records].select { |row| row[:owners].include?(id) }
+    end
+
+    def self.remediable?(id, references = nil)
+      rows = invalid_dependencies(id, references)
+      !rows.empty? && rows.all? do |row|
+        relative = row[:path].delete_prefix("#{File.join(Dir.home, '.pwn')}/")
+        supported = (relative == 'learning.jsonl' && row[:locator].is_a?(Integer)) ||
+                    (%w[memory.json memory.archive.json mistakes.json].include?(relative) && row[:locator].is_a?(String))
+        row[:owners] == [id] && supported
+      end
+    end
+
+    def self.cleanup_state(path, id, references = nil)
+      state = classify(path, id)
+      return state if state == :unknown
+
+      status = PWN::Sessions.retention_status(session_id: id, references: references)
+      return :invalid_dependency unless status[:dependency_errors].empty?
+
+      state
+    end
+
+    def self.with_dependency_lock(id)
+      rows = invalid_dependencies(id)
+      raise 'Unresolved dependency remediation' unless rows.empty? || remediable?(id)
+
+      # Lock even absent stores: a concurrent writer can introduce the first
+      # reference between the final index and unlink. These inodes are permanent.
+      root = File.join(Dir.home, '.pwn')
+      paths = %w[.learning-write.lock memory.json.write.lock mistakes.json.write.lock].map { |name| File.join(root, name) }.sort
+      locks = []
+      begin
+        paths.each do |path|
+          lock = File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) # rubocop:disable Style/FileOpen -- closed together in ensure
+          locks << lock
+          raise 'Dependency writer active' unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+        end
+        yield
+      ensure
+        locks.reverse_each(&:close)
+      end
+    end
+
+    def self.remove_invalid_dependencies(id, result)
+      rows = invalid_dependencies(id)
+      return if rows.empty?
+
+      raise 'Dependency remediation changed' unless remediable?(id)
+
+      rows.group_by { |row| row[:path] }.each do |path, entries|
+        bytes = File.binread(path)
+        hash = Digest::SHA256.hexdigest(bytes)
+        raise 'Dependency changed' unless entries.all? { |row| row[:sha256] == hash }
+
+        backup_path = File.join(result[:archive_dir], "dependency-#{SecureRandom.hex(8)}.jsonl")
+        publish(backup_path, bytes)
+        raise 'Dependency backup failed' unless Digest::SHA256.file(backup_path).hexdigest == hash
+
+        locators = entries.map { |row| row[:locator] }
+        updated = if path.end_with?('.jsonl')
+                    bytes.lines.each_with_index.reject { |_, index| locators.include?(index) }.map(&:first).join
+                  else
+                    map = JSON.parse(bytes)
+                    raise 'Dependency map changed' unless map.is_a?(Hash) && locators.all? { |key| map.key?(key) }
+
+                    locators.each { |key| map.delete(key) }
+                    JSON.pretty_generate(map)
+                  end
+        removal = { session_id: id, path: path, backup: backup_path, sha256: hash,
+                    updated_sha256: Digest::SHA256.hexdigest(updated), locators: locators, state: 'prepared' }
+        (result[:dependency_removals] ||= []) << removal
+        publish(File.join(result[:archive_dir], 'ledger.json'), JSON.pretty_generate(result))
+        raise 'Dependency changed after backup' unless File.binread(path) == bytes
+
+        publish(path, updated)
+        # Compare exact bytes even when JSON emits non-ASCII UTF-8 text.
+        raise 'Dependency write verification failed' unless File.binread(path) == updated.b
+
+        removal[:state] = 'committed'
+        publish(File.join(result[:archive_dir], 'ledger.json'), JSON.pretty_generate(result))
+      end
+    end
+
+    # The command and bundled cron use this exact maintenance transaction.
+    # Legacy writers block all mutations, including evidence migration.
+    # One permanent inode serializes CLI, curses and cron maintenance writers.
+    # Read-only previews never acquire a writer lock or create lock files.
+    def self.with_maintenance_lock(dry_run:)
+      return yield if dry_run
+
+      root = PWN::Sessions.sessions_dir
+      raise IOError, 'Unsafe session maintenance directory' unless File.realpath(root) == File.expand_path(root)
+
+      path = File.join(root, '.maintenance.lock')
+      owner = Thread.current[:pwn_session_maintenance_lock]
+      return yield if owner && owner[:pid] == Process.pid && owner[:thread] == Thread.current && owner[:path] == path && !owner[:file].closed?
+
+      File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |file|
+        raise IOError, 'Session maintenance already running; wait for its result before retrying' unless file.flock(File::LOCK_EX | File::LOCK_NB)
+
+        begin
+          Thread.current[:pwn_session_maintenance_lock] = { pid: Process.pid, thread: Thread.current, path: path, file: file }
+          yield
+        ensure
+          Thread.current[:pwn_session_maintenance_lock] = owner
+        end
+      end
+    end
+
+    def self.maintain(dry_run: false, current_session_id: nil, proc_root: '/proc')
+      with_maintenance_lock(dry_run: dry_run) do
+        maintenance_transaction(dry_run: dry_run, current_session_id: current_session_id, proc_root: proc_root)
+      end
+    end
+
+    def self.maintenance_transaction(dry_run:, current_session_id:, proc_root:)
+      preflight = sweep(dry_run: true, current_session_id: current_session_id, proc_root: proc_root)
+      blocked = !preflight[:legacy_owners].empty? || Array(preflight[:unresolved_store_remediation]).any?
+      unless dry_run || blocked
+        # Private metadata-only preflight survives an interrupted migration.
+        backup(File.join(PWN::Sessions.sessions_dir, 'inventory.jsonl'), {}, preflight)
+        ledger = File.join(preflight[:archive_dir], 'maintenance.json')
+        publish(ledger, JSON.pretty_generate(state: 'prepared', inventory: preflight))
+        blocked = !legacy_owners(proc_root).empty?
+      end
+      migration = PWN::AI::Agent::Learning.migrate_evidence(dry_run: dry_run || blocked)
+      result = if dry_run || blocked
+                 preflight
+               else
+                 sweep(dry_run: false, current_session_id: current_session_id, proc_root: proc_root)
+               end
+      result[:dry_run] = dry_run
+      result[:apply_blocked] = true if blocked
+      result[:evidence_migration] = migration
+      result[:remaining_sessions] = Dir.glob(File.join(PWN::Sessions.sessions_dir, '*.jsonl')).length
+      result[:visible_sessions] = PWN::Sessions.list.length
+      if ledger
+        result[:maintenance_ledger] = ledger
+        publish(ledger, JSON.pretty_generate(state: blocked ? 'blocked' : 'committed', inventory: preflight, result: result))
+      end
+      result
+    end
+
+    # Explicit offline layout migration: never a cron side effect. Stop schedulers
+    # and all writers first; old binaries cannot understand the new layout.
+    # Transcript files never move. Temporary writer remnants are recoverable.
+    def self.reorganize(dry_run: true, writers_stopped: false, proc_root: '/proc')
+      raise ArgumentError, 'All writers and schedulers must be stopped' unless dry_run || writers_stopped
+
+      with_maintenance_lock(dry_run: dry_run) do
+        root = PWN::Sessions.sessions_dir
+        plan = Dir.children(root).sort.filter_map do |name|
+          target = case name
+                   when /\A\d{8}_\d{6}_[a-f0-9]{8}\.meta\.json\z/ then File.join('support', 'metadata', name)
+                   when /\A\..+\.cleanup\.lock\z/ then File.join('support', 'leases', name)
+                   when /\A\.activity-owner-\d+-\d+\.lock\z/ then File.join('support', 'owners', name)
+                   when /\A\d{8}_\d{6}_[a-f0-9]{8}\.jsonl\.\d+\.tmp\z/ then nil
+                   else next
+                   end
+          source = File.join(root, name)
+          raise IOError, 'Unsafe layout source' unless File.file?(source) && !File.symlink?(source)
+
+          { source: source, target: target && File.join(root, target), sha256: Digest::SHA256.file(source).hexdigest,
+            inode: File.stat(source).ino, temporary: target.nil? }
+        end
+        # Existing trace paths may be immutable finding/artifact anchors. Keep
+        # those exact paths; new traces use compact storage after the marker.
+        retained_support = Dir.glob(File.join(root, '*', 'trace.jsonl'))
+        references = PWN::Sessions.dependency_index
+        raise IOError, 'Uncertain evidence anchors prevent layout migration' unless references[:errors].empty?
+
+        plan.reject! do |row|
+          next false unless row[:source].end_with?('.meta.json')
+
+          id = File.basename(row[:source], '.meta.json')
+          anchored = !references[:dependencies].fetch(id, []).empty? || !references[:session_errors].fetch(id, []).empty?
+          retained_support << row[:source] if anchored
+          anchored
+        end
+        result = { state: 'planned', records: plan, retained_support: retained_support, transcripts: Dir.glob(File.join(root, '*.jsonl')).length }
+        next result if dry_run
+
+        raise IOError, 'Legacy writers remain active' unless legacy_owners(proc_root).empty?
+
+        handles = []
+        begin
+          locks = Dir.glob(File.join(root, 'support', '{leases,owners}', '.*.lock'))
+          locks.each do |path|
+            file = File.open(path, File::RDWR | File::NOFOLLOW) # rubocop:disable Style/FileOpen -- transaction owns all handles
+            handles << file
+            locked = file.flock(File::LOCK_EX | File::LOCK_NB)
+            own_marker = File.basename(path).start_with?(".activity-owner-#{Process.pid}-")
+            raise IOError, 'Session writers are active' unless locked || own_marker
+          end
+          plan.reject! do |row|
+            next false unless row[:source].end_with?('.lock')
+
+            # The migration caller can own its capability marker; leave it in
+            # place, not a replacement inode. Other held markers block migration.
+            file = File.open(row[:source], File::RDWR | File::NOFOLLOW) # rubocop:disable Style/FileOpen -- transaction holds every lock through commit
+            handles << file
+            locked = file.flock(File::LOCK_EX | File::LOCK_NB)
+            own_marker = File.basename(row[:source]).start_with?(".activity-owner-#{Process.pid}-")
+            raise IOError, 'Session writers are active' unless locked || own_marker
+
+            !locked
+          end
+          backup(File.join(root, 'layout.jsonl'), {}, result)
+          ledger = File.join(result[:archive_dir], 'layout.json')
+          result[:state] = 'prepared'
+          publish(ledger, JSON.pretty_generate(result))
+          # Back up every byte before the first move, including abandoned temp
+          # output. Do not infer that a temp is safe merely from its age/PID.
+          plan.each_with_index do |row, index|
+            raise IOError, 'Layout source changed' unless File.stat(row[:source]).ino == row[:inode] && Digest::SHA256.file(row[:source]).hexdigest == row[:sha256]
+            raise IOError, 'Layout destination exists' if row[:target] && (File.exist?(row[:target]) || File.symlink?(row[:target]))
+
+            row[:backup] = File.join(result[:archive_dir], "layout-#{index}.bin")
+            publish(row[:backup], File.binread(row[:source]))
+            raise IOError, 'Layout backup mismatch' unless Digest::SHA256.file(row[:backup]).hexdigest == row[:sha256]
+          end
+          publish(ledger, JSON.pretty_generate(result))
+          plan.each do |row|
+            raise IOError, 'Layout source changed' unless Digest::SHA256.file(row[:source]).hexdigest == row[:sha256]
+
+            if row[:temporary]
+              File.unlink(row[:source])
+            else
+              FileUtils.mkdir_p(File.dirname(row[:target]), mode: 0o700)
+              raise IOError, 'Unsafe layout destination' unless File.realpath(File.dirname(row[:target])) == File.expand_path(File.dirname(row[:target]))
+
+              File.rename(row[:source], row[:target])
+              raise IOError, 'Layout move mismatch' unless File.stat(row[:target]).ino == row[:inode] && Digest::SHA256.file(row[:target]).hexdigest == row[:sha256]
+            end
+            row[:moved] = true
+            publish(ledger, JSON.pretty_generate(result))
+          end
+          publish(File.join(root, '.layout-v2'), "2\n")
+          result[:state] = 'committed'
+          publish(ledger, JSON.pretty_generate(result))
+          result
+        ensure
+          handles.each(&:close)
+        end
+      end
+    end
+
+    def self.summary(result)
+      { version: VERSION, dry_run: result[:dry_run], apply_blocked: result[:apply_blocked] == true,
+        scanned: result[:scanned], candidates: result[:candidate_ids].length, deleted: result[:deleted_ids].length,
+        remaining: result[:remaining_sessions], visible: result[:visible_sessions], skipped: result[:skipped],
+        evidence_migration: result[:evidence_migration], archive_dir: result[:archive_dir],
+        unresolved_dependency_stores: result[:dependency_errors] || [], legacy_owners: result[:legacy_owners] }
+    end
+
     def self.run(dry_run: true, current_session_id: nil, proc_root: '/proc', approved_candidates: nil)
+      return sweep(dry_run: dry_run, current_session_id: current_session_id, proc_root: proc_root, approved_candidates: approved_candidates) if approved_candidates
+
+      maintain(dry_run: dry_run, current_session_id: current_session_id, proc_root: proc_root)
+    end
+
+    def self.sweep(dry_run: true, current_session_id: nil, proc_root: '/proc', approved_candidates: nil)
+      with_maintenance_lock(dry_run: dry_run) do
+        sweep_transaction(dry_run: dry_run, current_session_id: current_session_id, proc_root: proc_root, approved_candidates: approved_candidates)
+      end
+    end
+
+    def self.sweep_transaction(dry_run:, current_session_id:, proc_root:, approved_candidates:)
       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
@@ -158,26 +429,41 @@ module PWN
       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?
+      references = PWN::Sessions.dependency_index
+      unless references[:errors].empty?
         result[:skipped][:unknown_pins] = 1
-        result[:dependency_errors] = PWN::Sessions.dependency_index[:errors]
-        return result
+        result[:dependency_errors] = references[:errors]
+        result[:unresolved_store_remediation] = references[:errors]
       end
-      dependencies = PWN::Sessions.dependency_index[:dependencies]
-      pins = referenced_session_ids
+      result[:diagnostics] = references.fetch(:diagnostics, [])
+      dependencies = references[:dependencies]
+      pins = dependencies.keys
       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, []))
+        state = cleanup_state(path, id, references)
+        record = PWN::Sessions.retention_status(session_id: id, references: references).merge(id: id, classification: state, dependencies: dependencies.fetch(id, []))
         result[:records] << record
-        unless state == :unnamed
+        unless references[:errors].empty?
+          record[:skip] = :unknown_pins
+          next
+        end
+        unless %i[unnamed invalid_dependency].include?(state)
           result[:skipped][state] += 1
           next
         end
+        if state == :invalid_dependency && (!remediable?(id, references) || pins.include?(id))
+          record[:skip] = :unresolved_dependency_remediation
+          result[:skipped][:unresolved_dependency_remediation] += 1
+          next
+        end
         expected = snapshot(path)
+        expected_dependencies = invalid_dependencies(id, references)
+        record[:dependency_records] = expected_dependencies
         record[:files] = expected
-        if approved_candidates && approved_candidates[id] != expected
+        approval = approved_candidates && approved_candidates[id]
+        approved = approval.is_a?(Hash) && approval.key?(:files) ? approval[:files] == expected && approval[:dependency_records] == expected_dependencies : approval == expected && expected_dependencies.empty?
+        if approved_candidates && !approved
           record[:skip] = :not_approved_or_changed
           result[:skipped][:not_approved_or_changed] += 1
           next
@@ -204,7 +490,7 @@ module PWN
           next
         end
         # Never unlink lock files: waiters must keep sharing the same inode.
-        lock_path = File.join(root, ".#{id}.cleanup.lock")
+        lock_path = PWN::Sessions.support_path(kind: :lease, session_id: id)
         raise 'Refusing symlinked cleanup lock' if File.symlink?(lock_path)
 
         File.open(lock_path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
@@ -213,34 +499,39 @@ module PWN
             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
+          with_dependency_lock(id) do
+            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) && cleanup_state(path, id) == state && invalid_dependencies(id) == expected_dependencies && 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 && cleanup_state(path, id) == state && invalid_dependencies(id) == expected_dependencies && 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.
+              remove_invalid_dependencies(id, result)
+              raise 'Dependencies changed after remediation' unless pins_known? && !referenced_session_ids.include?(id) && invalid_dependencies(id).empty? && snapshot(path) == expected
+
+              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?(PWN::Sessions.support_path(kind: :metadata, session_id: id))
+
+              result[:deleted_ids] << id
+              record[:deleted] = true
+              publish(File.join(result[:archive_dir], 'ledger.json'), JSON.pretty_generate(result))
             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
@@ -250,11 +541,13 @@ module PWN
       publish(File.join(result[:archive_dir], 'ledger.json'), JSON.pretty_generate(result)) if result[:archive_dir]
       result
     end
+
+    private_class_method :with_maintenance_lock, :maintenance_transaction, :sweep_transaction
   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'))
+  puts JSON.generate(PWN::SessionCleanup.summary(PWN::SessionCleanup.maintain(dry_run: ARGV.first == '--dry-run')))
 end

data/lib/pwn/ai/agent/curriculum.rb

@@ -229,9 +229,9 @@ module PWN
           commit  = opts.key?(:commit) ? opts[:commit] : true
           cutoff  = Time.now.utc - (since_h * 3_600)
 
-          # PWN::Sessions.list is arity-0 (no kwargs). Cap/sort after the call.
+          # Offline evidence discovery must include sessions hidden from operator lists.
           sids = if PWN::Sessions.respond_to?(:list)
-                   Array(PWN::Sessions.list)
+                   Array(PWN::Sessions.list(include_hidden: true))
                      .sort_by { |s| s.is_a?(Hash) ? s[:mtime].to_s : '' }
                      .reverse
                      .first(limit * 2)