pwn 0.5.783 → 0.5.785

data/etc/default_cron/session_cleanup.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# PWN managed default: session_cleanup v9
+# PWN managed default: session_cleanup v10
 # No provider calls or broad store GC. Unsummarized candidates are backed up first.
 require 'pwn'
 require 'json'
@@ -12,7 +12,1046 @@ require 'securerandom'
 module PWN
   # Provenance-based session cleanup, shared by seeded cron payloads.
   module SessionCleanup
-    VERSION = 9
+    VERSION = 10
+
+    # Logical categories deliberately preserve existing literal evidence paths.
+    STORAGE = {
+      'sessions' => %w[sessions],
+      'learning' => %w[learning.jsonl learning lessons.json memory.json memory.archive.json memory.idx mistakes.json policy policy.json policy_traj.jsonl curriculum curriculum_kpi.jsonl extrospection.json finetune preferences.jsonl reward_sentinel.json skill_review.jsonl operator-learning-review.jsonl],
+      'artifacts' => %w[artifacts exports findings.jsonl engagements corpora binws redb ghidra sandbox_snapshots],
+      'state' => %w[swarm cron agents.yml open_goal.json jobs missions runs metrics metrics.json capabilities.json],
+      'logs' => %w[logs], 'cache' => %w[cache], 'tmp' => %w[workspaces/runtime],
+      'maintenance' => %w[maintenance session_cleanup_archive],
+      'backups' => %w[backup]
+    }.freeze
+    POLICY = { 'version' => 1, 'batch_size' => 100, 'scan_limit' => 100_000, 'work_items' => 100_000, 'work_seconds' => 30, 'work_bytes' => 67_108_864,
+               'retention_days' => { 'sessions' => 0, 'learning' => nil, 'artifacts' => nil, 'state' => nil,
+                                     'logs' => 30, 'cache' => 7, 'tmp' => 1, 'maintenance' => 90 },
+               'budget_bytes' => { 'logs' => 268_435_456, 'cache' => 536_870_912, 'tmp' => 268_435_456, 'maintenance' => 1_073_741_824 } }.freeze
+
+    # Versioned additive setup: no old path moves or permission rewrites.
+    def self.install(root: File.join(Dir.home, '.pwn'))
+      directory = private_directory(File.join(root, 'maintenance'))
+      File.open(File.join(directory, '.setup.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        path = File.join(directory, 'policy.json')
+        raise IOError, 'Symlinked maintenance policy' if File.symlink?(path)
+
+        publish(path, JSON.pretty_generate(POLICY)) unless File.exist?(path)
+        private_directory(File.join(root, 'cache')) unless File.exist?(File.join(root, 'cache'))
+        private_directory(File.join(root, 'workspaces', 'runtime')) unless File.exist?(File.join(root, 'workspaces', 'runtime'))
+        layout = File.join(directory, 'layout.json')
+        raise IOError, 'Unsafe maintenance inventory' if File.symlink?(layout)
+
+        previous = File.file?(layout) ? JSON.parse(File.binread(layout)) : nil
+        raise IOError, 'Unknown maintenance inventory version' if previous && ![1, 2, 3].include?(previous['version'])
+
+        publish(layout, JSON.generate(version: 3, categories: STORAGE)) unless previous && previous['version'] == 3
+      end
+      { version: 3, root: directory }
+    end
+
+    # Startup performs only fixed-path checks and one coalesced request write.
+    # The existing cron worker owns all scanning, migration and deletion.
+    def self.request_background(root: File.join(Dir.home, '.pwn'))
+      directory = File.join(root, 'maintenance')
+      return { state: 'not_installed' } unless File.directory?(directory)
+      raise IOError, 'Unsafe maintenance directory' unless File.realpath(directory) == directory
+
+      File.open(File.join(directory, '.schedule.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+        return { state: 'coalesced' } unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+        path = File.join(directory, 'background.json')
+        raise IOError, 'Unsafe background request' if File.symlink?(path)
+
+        if File.file?(path)
+          prior = JSON.parse(File.binread(path))
+          return { state: 'coalesced' } if prior['state'] == 'pending' || prior.fetch('requested_at', 0) > Time.now.to_i - 86_400
+        end
+        publish(path, JSON.generate(version: 1, state: 'pending', requested_at: Time.now.to_i))
+        { state: 'queued', path: path }
+      end
+    rescue StandardError => e
+      { state: 'unhealthy', error: e.class.name }
+    end
+
+    def self.background_request(root: File.join(Dir.home, '.pwn'))
+      directory = File.join(root, 'maintenance')
+      path = File.join(directory, 'background.json')
+      return unless File.file?(path)
+      raise IOError, 'Unsafe background request' unless File.realpath(path) == path
+
+      File.open(File.join(directory, '.schedule.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+        next unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+        row = JSON.parse(File.binread(path))
+        next unless row['version'] == 1 && row['state'] == 'pending'
+
+        result = yield
+        next unless result
+
+        row['state'] = result[:status] == 'success' ? 'completed' : 'interrupted'
+        row['completed_at'] = Time.now.to_i
+        publish(path, JSON.generate(row))
+        result
+      end
+    end
+
+    def self.policy
+      path = File.join(Dir.home, '.pwn', 'maintenance', 'policy.json')
+      return Marshal.load(Marshal.dump(POLICY)) unless File.exist?(path) || File.symlink?(path)
+
+      raise IOError, 'Unsafe maintenance policy' if File.symlink?(path)
+
+      value = JSON.parse(File.binread(path))
+      raise ArgumentError, 'Unknown maintenance policy' unless value.is_a?(Hash) && value['version'] == 1 && (value.keys - POLICY.keys).empty?
+
+      result = Marshal.load(Marshal.dump(POLICY)).merge(value)
+      %w[retention_days budget_bytes].each do |key|
+        raise ArgumentError, "Invalid #{key}" unless result[key].is_a?(Hash) && (result[key].keys - STORAGE.keys).empty? && result[key].values.all? { |n| n.nil? || (n.is_a?(Integer) && n >= 0) }
+
+        result[key] = POLICY[key].merge(result[key])
+      end
+      raise ArgumentError, 'Invalid read budget' unless result['work_bytes'].is_a?(Integer) && result['work_bytes'].positive?
+      raise ArgumentError, 'Invalid maintenance bounds' unless %w[batch_size scan_limit work_items work_seconds].all? { |key| result[key].is_a?(Integer) && result[key].between?(1, 100_000) }
+
+      result
+    end
+
+    # No mkdir, locks, provider access, metadata rewrites or repair in status.
+    def self.status
+      config = policy
+      root = File.join(Dir.home, '.pwn')
+      errors = []
+      remaining = config['scan_limit']
+      categories = STORAGE.to_h do |category, names|
+        paths = names.map { |name| name == 'sessions' ? PWN::Sessions::SESSIONS_DIR : File.join(root, name) }
+        row = { paths: paths, files: 0, bytes: 0, unique_bytes: 0, symlinks: 0, retention_days: config['retention_days'][category], budget_bytes: config['budget_bytes'][category] }
+        inodes = {}
+        pending = paths.dup
+        until pending.empty? || remaining.zero? || stopping?
+          begin
+            entry = pending.pop
+            if entry.is_a?(Array)
+              begin
+                path = File.join(entry[0], entry[1].next)
+                pending << entry
+              rescue StopIteration
+                next
+              end
+            else
+              path = entry
+            end
+            next unless File.exist?(path) || File.symlink?(path)
+
+            remaining -= 1
+            stat = File.lstat(path)
+            if stat.symlink?
+              row[:symlinks] += 1
+            elsif stat.directory?
+              pending << [path, Dir.each_child(path)]
+            elsif stat.file?
+              row[:files] += 1
+              row[:bytes] += stat.size
+              key = [stat.dev, stat.ino]
+              row[:unique_bytes] += stat.size unless inodes[key]
+              inodes[key] = true
+            end
+          rescue SystemCallError => e
+            errors << { path: path, error: e.class.name }
+          end
+        end
+        row[:incomplete] = !pending.empty?
+        row[:over_budget] = row[:budget_bytes] && row[:bytes] > row[:budget_bytes]
+        row[:policy_mode] = %w[learning artifacts state backups].include?(category) ? 'protected_evidence_no_automatic_deletion' : 'verified_disposable_only'
+        [category, row]
+      end
+      transactions = Dir.glob(File.join(root, 'maintenance', 'runs', '*.json')).last(config['batch_size']).map do |path|
+        raise IOError, 'Unsafe transaction ledger' unless File.realpath(path) == path
+
+        row = JSON.parse(admitted_bytes(path))
+        { ledger: path, state: row['state'], recovery: %w[prepared interrupted].include?(row['state']) ? 'inspect_child_ledgers_before_retry' : nil }
+      rescue StandardError => e
+        { ledger: path, state: 'unknown', error: e.class.name }
+      end
+      { version: VERSION, operation: 'status', categories: categories, errors: errors, transactions: transactions,
+        policy: config, reasons: ['Unknown files and immutable evidence are retained; budgets do not override evidence or leases.',
+                                  'Historical backup expiry requires explicit retention policy and verified current recovery coverage; pinned evidence remains.'] }
+    end
+
+    # Explicit legacy expiry, not broad GC. No payload quarantine or new per-file
+    # leases: old producers do not honor those. Permanent maintenance locking,
+    # closed-stream markers, process descriptors and exact byte identities fence
+    # adoption. References are conservatively matched even in retained transcripts.
+    def self.expire_legacy(dry_run: true, manifest: nil)
+      require 'zlib'
+      root = File.join(Dir.home, '.pwn')
+      raise IOError, 'Unsafe root' unless File.realpath(root) == root
+      raise ArgumentError, 'New external metadata manifest required' if !dry_run && (manifest.nil? || File.expand_path(manifest).start_with?("#{root}/") || File.exist?(manifest))
+
+      result = { removed: [], retained: [], candidates: [] }
+      File.open(File.join(root, 'sessions', '.maintenance.lock'), File::RDWR | File::NOFOLLOW) do |lock|
+        raise IOError, 'Maintenance active' unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+        candidates = legacy_candidates(root) + legacy_recovery_candidates(root) + legacy_cache_candidates(root)
+        pins = legacy_references(root, candidates)
+        opened = legacy_open_files
+        candidates.each do |row|
+          reason = pins[row[:path]] ? 'evidence_reference' : nil
+          reason ||= 'open_descriptor' if opened.include?([row[:dev], row[:ino]])
+          (reason ? result[:retained] : result[:candidates]) << row.merge(reason: reason, references: pins[row[:path]])
+        end
+        return result if dry_run
+
+        # Publish metadata before irreversible expiry. An interrupted manifest is
+        # an intent ledger, never a claim that every planned removal completed.
+        result[:state] = 'prepared'
+        legacy_manifest(manifest, result)
+        raise IOError, 'Evidence references changed' unless pins == legacy_references(root, candidates)
+
+        result[:candidates].each do |row|
+          path = row[:path]
+          File.open(path, File::RDONLY | File::NOFOLLOW) do |file|
+            raise IOError, 'Candidate locked' unless file.flock(File::LOCK_EX | File::LOCK_NB)
+
+            lease = File.open("#{path}.lease", File::RDWR | File::NOFOLLOW) if File.exist?("#{path}.lease") || File.symlink?("#{path}.lease") # rubocop:disable Style/FileOpen -- closed in ensure while optional producer lease is held
+            raise IOError, 'Producer lease active' if lease && !lease.flock(File::LOCK_EX | File::LOCK_NB)
+            raise IOError, 'Candidate changed' unless legacy_identity(path) == row.except(:category, :reason, :references, :proofs)
+
+            Array(row[:proofs]).each do |proof|
+              raise IOError, 'Recovery proof changed' unless legacy_identity(proof[:path]) == proof
+            end
+            raise IOError, 'Candidate became active' if legacy_open_files(except_fd: file.fileno).include?([row[:dev], row[:ino]])
+
+            File.unlink(path)
+            result[:removed] << row
+          ensure
+            lease&.close
+          end
+        end
+        result[:state] = 'completed'
+        legacy_manifest(manifest, result)
+      end
+      result
+    end
+
+    def self.legacy_manifest(path, result)
+      File.open(path, File::WRONLY | File::CREAT | File::TRUNC | File::NOFOLLOW, 0o600) do |file|
+        gzip = Zlib::GzipWriter.new(file)
+        gzip.write(JSON.generate(result))
+        gzip.finish
+        file.flush
+        file.fsync
+      end
+    end
+
+    def self.legacy_identity(path)
+      stat = File.lstat(path)
+      raise IOError, 'Unsafe legacy file' unless stat.file? && stat.uid == File.stat(File.join(Dir.home, '.pwn')).uid && stat.nlink == 1 && File.realpath(path) == path
+
+      { path: path, dev: stat.dev, ino: stat.ino, size: stat.size, mtime: stat.mtime.to_r.to_s,
+        ctime: stat.ctime.to_r.to_s, sha256: Digest::SHA256.file(path).hexdigest }
+    end
+
+    def self.legacy_candidates(root)
+      days = policy['retention_days']['logs']
+      return [] unless days.is_a?(Numeric) && days.positive?
+
+      Dir.glob(File.join(root, 'logs', '*.log')).filter_map do |path|
+        next unless File.basename(path).match?(/\Apwn-ai-DEBUG-[a-zA-Z0-9_-]+-R[1-9]\d*\.log\z/)
+
+        row = legacy_identity(path)
+        next unless File.lstat(path).mtime < Time.now - (days * 86_400)
+
+        bytes = File.binread(path)
+        next unless bytes.include?('debug session stop') || bytes.include?('footer iter=')
+
+        row.merge(category: 'logs')
+      end
+    end
+
+    # Historical learning/reward recovery is explicitly bounded to at least
+    # three parseable copies per exact producer family, plus all reference pins.
+    # A thirty-day floor excludes files an older daily producer might still use.
+    def self.legacy_recovery_candidates(root)
+      families = { 'learning.jsonl' => /\Alearning\.jsonl\.bak-lean-\d{8}\z/,
+                   'preferences.jsonl' => /\Apreferences\.jsonl\.bak-p15-\d{14}\z/ }
+      families.flat_map do |source, pattern|
+        current = File.join(root, source)
+        next [] unless File.file?(current)
+
+        legacy_identity(current)
+        File.foreach(current) { |line| JSON.parse(line) unless line.strip.empty? }
+        copies = Dir.children(root).grep(pattern).sort.map { |name| File.join(root, name) }
+        valid = copies.select do |path|
+          legacy_identity(path)
+          File.foreach(path) { |line| JSON.parse(line) unless line.strip.empty? }
+          File.size(path).positive?
+        rescue JSON::ParserError
+          false
+        end
+        (valid - valid.last(3)).filter_map do |path|
+          next unless File.mtime(path) < Time.now - (30 * 86_400)
+
+          legacy_identity(path).merge(category: 'root_recovery', proofs: valid.last(3).map { |copy| legacy_identity(copy) })
+        end
+      end
+    end
+
+    # BinaryParser persists exactly these cache bytes to ArtifactRegistry. Missing
+    # source binaries prevent recomputation; require a surviving byte-exact copy
+    # instead, never classify arbitrary decompiler stdout as reproducible.
+    def self.legacy_cache_candidates(root)
+      days = policy['retention_days']['cache']
+      return [] unless days.is_a?(Numeric) && days.positive?
+
+      copies = Dir.glob(File.join(root, 'artifacts', '**', '*')).select { |path| File.file?(path) && !File.symlink?(path) }
+      Dir.glob(File.join(root, 'cache', 'triage', '*.json')).filter_map do |path|
+        next unless File.basename(path).match?(/\A[a-f0-9]{64}\.json\z/) && File.mtime(path) < Time.now - (days * 86_400)
+
+        row = legacy_identity(path)
+        body = JSON.parse(File.binread(path))
+        next unless body['sha256'] == File.basename(path, '.json') && body['path'].is_a?(String)
+
+        copy = copies.find { |candidate| File.size(candidate) == row[:size] && Digest::SHA256.file(candidate).hexdigest == row[:sha256] }
+        next unless copy
+
+        row.merge(category: 'cache', proofs: [legacy_identity(copy)])
+      end
+    end
+
+    def self.legacy_references(root, candidates)
+      names = candidates.to_h { |row| [File.basename(row[:path]), row[:path]] }
+      return {} if names.empty?
+
+      pattern = Regexp.union(names.keys)
+      references = {}
+      # Recovery generations are historical copies, not live evidence pins.
+      # Candidate payloads cannot pin themselves. Everything else is scanned
+      # without interpreting or displaying credential/transcript contents.
+      Dir.glob(File.join(root, '**', '*'), File::FNM_DOTMATCH).sort.each do |path|
+        relative = path.delete_prefix("#{root}/")
+        next if %w[backup logs cache].include?(relative.split('/').first)
+        next if names.value?(path) || !File.file?(path)
+        raise IOError, 'Symlink in reference scope' if File.symlink?(path)
+
+        File.binread(path).scan(pattern).uniq.each do |name|
+          (references[names.fetch(name)] ||= []) << path
+        end
+      end
+      references
+    end
+
+    def self.legacy_open_files(except_fd: nil)
+      raise IOError, 'Process inventory unavailable' unless File.directory?('/proc/self/fd')
+
+      opened = []
+      Dir.glob('/proc/[0-9]*').each do |process|
+        next unless Process.uid.zero? || File.stat(process).uid == Process.uid
+
+        Dir.children("#{process}/fd").each do |fd|
+          next if File.basename(process).to_i == Process.pid && fd.to_i == except_fd
+
+          stat = File.stat("#{process}/fd/#{fd}")
+          opened << [stat.dev, stat.ino] if stat.file?
+        rescue Errno::ENOENT, Errno::ESRCH
+          next
+        end
+      rescue Errno::ENOENT, Errno::ESRCH
+        next
+      end
+      opened.uniq
+    end
+
+    # A producer registers only reproducible/disposable bytes, never evidence.
+    # Writers hold the permanent .lease exclusively while changing a file;
+    # consumers hold it shared for the whole read/use lifetime.
+    def self.register_disposable(path:, category:, expires_at: nil)
+      raise ArgumentError, 'Not a disposable category' unless %w[cache tmp logs].include?(category)
+
+      root = disposable_directory(category)
+      path = File.expand_path(path)
+      raise IOError, 'Disposable path escapes its category' unless path.start_with?("#{root}/") && File.realpath(path) == path
+      raise IOError, 'Disposable must be an owned regular file' unless File.file?(path) && File.stat(path).uid == Process.uid
+
+      days = policy['retention_days'][category]
+      raise ArgumentError, 'Retention disabled for category' if days.nil?
+
+      File.open("#{path}.lease", File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lease|
+        raise IOError, 'Disposable is active' unless lease.flock(File::LOCK_EX | File::LOCK_NB)
+
+        record_disposable(path: path, category: category, expires_at: expires_at || (Time.now.to_i + (days * 86_400)))
+      end
+    end
+
+    # Caller holds the permanent exclusive producer lease through publication.
+    def self.record_disposable(path:, category:, expires_at:)
+      directory = private_directory(File.join(Dir.home, '.pwn', 'maintenance', 'disposable'))
+      record = { version: 1, path: path, category: category, expires_at: expires_at,
+                 sha256: Digest::SHA256.file(path).hexdigest, bytes: File.size(path), inode: File.stat(path).ino }
+      publish(File.join(directory, "#{Digest::SHA256.hexdigest(path)}.json"), JSON.generate(record))
+      record
+    end
+
+    # Cache consumers use the same permanent inode as publication and eviction.
+    def self.cache(path:, bytes: nil)
+      root = File.join(Dir.home, '.pwn', 'cache')
+      raise IOError, 'Unsafe cache path' unless File.expand_path(path) == path && path.start_with?("#{root}/")
+
+      private_directory(File.dirname(path)) unless File.directory?(File.dirname(path))
+      raise IOError, 'Unsafe cache directory' unless File.realpath(File.dirname(path)) == File.dirname(path)
+
+      File.open("#{path}.lease", File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lease|
+        lease.flock(bytes ? File::LOCK_EX : File::LOCK_SH)
+        if bytes
+          publish(path, bytes)
+          days = policy['retention_days']['cache']
+          if days
+            directory = private_directory(File.join(Dir.home, '.pwn', 'maintenance', 'disposable'))
+            row = { version: 1, path: path, category: 'cache', expires_at: Time.now.to_i + (days * 86_400),
+                    sha256: Digest::SHA256.file(path).hexdigest, bytes: File.size(path), inode: File.stat(path).ino }
+            publish(File.join(directory, "#{Digest::SHA256.hexdigest(path)}.json"), JSON.generate(row))
+          end
+          bytes
+        elsif File.file?(path) && !File.symlink?(path)
+          File.binread(path)
+        end
+      end
+    end
+
+    # Known disposable input producer. The permanent lease covers publication,
+    # consumption and unlink; a killed consumer leaves a registered exact file.
+    def self.temporary(bytes:)
+      directory = private_directory(disposable_directory('tmp'))
+      path = File.join(directory, "input-#{SecureRandom.hex(12)}.txt")
+      File.open("#{path}.lease", File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lease|
+        lease.flock(File::LOCK_EX)
+        begin
+          publish(path, bytes)
+          days = policy['retention_days']['tmp']
+          record_disposable(path: path, category: 'tmp', expires_at: Time.now.to_i + (days * 86_400)) if days
+          yield path
+        ensure
+          File.unlink(path) if File.file?(path) && !File.symlink?(path)
+        end
+      end
+    end
+
+    # Rotate ordinary diagnostics under the same lease as append and eviction.
+    # Request debug streams rotate at request boundaries and hold a lifetime lease.
+    def self.append_log(path:, bytes:, rotate_bytes: 1_024_000)
+      root = File.join(Dir.home, '.pwn', 'logs')
+      raise IOError, 'Unsafe log path' unless File.expand_path(path) == path && path.start_with?("#{root}/")
+
+      private_directory(File.dirname(path)) unless File.directory?(File.dirname(path))
+      raise IOError, 'Unsafe log directory' unless File.realpath(File.dirname(path)) == File.dirname(path)
+
+      File.open("#{path}.lease", File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lease|
+        lease.flock(File::LOCK_EX)
+        raise IOError, 'Symlinked log' if File.symlink?(path)
+
+        if File.file?(path) && File.size(path) >= rotate_bytes
+          rotated = "#{path}.#{SecureRandom.hex(12)}"
+          File.rename(path, rotated)
+          register_disposable(path: rotated, category: 'logs') unless policy['retention_days']['logs'].nil?
+        end
+        File.open(path, File::WRONLY | File::CREAT | File::APPEND | File::NOFOLLOW, 0o600) do |file|
+          file.write(bytes)
+          file.flush
+          file.fsync
+        end
+        days = policy['retention_days']['logs']
+        record_disposable(path: path, category: 'logs', expires_at: Time.now.to_i + (days * 86_400)) if days
+      end
+      path
+    end
+
+    # Disposable category tmp lives in the runtime workspace, not ~/.pwn/tmp.
+    def self.disposable_directory(category)
+      raise ArgumentError, 'Not a disposable category' unless %w[cache tmp logs].include?(category)
+
+      base = File.join(Dir.home, '.pwn')
+      category == 'tmp' ? File.join(base, 'workspaces', 'runtime') : File.join(base, category)
+    end
+
+    def self.private_directory(path)
+      ancestor = File.expand_path(path)
+      loop do
+        raise IOError, 'Symlinked maintenance directory' if File.symlink?(ancestor)
+        break if ancestor == File.dirname(ancestor)
+
+        ancestor = File.dirname(ancestor)
+      end
+      FileUtils.mkdir_p(path, mode: 0o700)
+      stat = File.stat(path)
+      raise IOError, 'Unsafe maintenance directory permissions' unless stat.uid == Process.uid && stat.mode.nobits?(0o077)
+
+      path
+    end
+
+    # Exact-size reads cannot grow without bound if an uncooperative writer appends.
+    def self.exact_bytes(path, size)
+      bytes = File.binread(path, size + 1)
+      raise IOError, 'File size changed' unless bytes.bytesize == size
+
+      bytes
+    end
+
+    def self.admitted_bytes(path)
+      size = File.size(path)
+      raise IOError, 'Maintenance read budget exhausted' unless admit?(size + 1)
+
+      exact_bytes(path, size)
+    end
+
+    def self.disposable_reason(row, pressure: false, verify: true)
+      return 'unknown_schema' unless row.is_a?(Hash) && row['version'] == 1 && %w[cache tmp logs].include?(row['category']) && row['expires_at'].is_a?(Integer)
+
+      path = row['path']
+      root = disposable_directory(row['category'])
+      return 'unsafe_path' unless path.is_a?(String) && path.start_with?("#{root}/") && File.expand_path(path) == path
+      return 'missing' unless File.exist?(path)
+      return 'unsafe_path' unless File.realpath(path) == path && File.file?(path) && File.stat(path).uid == Process.uid
+      return 'changed' unless File.stat(path).ino == row['inode'] && File.size(path) == row['bytes']
+      return 'changed' if verify && Digest::SHA256.hexdigest(exact_bytes(path, row['bytes'])) != row['sha256']
+      return 'retention_disabled' if policy['retention_days'][row['category']].nil?
+      return 'not_expired' if !pressure && row['expires_at'] > Time.now.to_i
+      return 'missing_lease' unless File.file?("#{path}.lease") && !File.symlink?("#{path}.lease")
+
+      nil
+    end
+
+    def self.clean_disposables(dry_run: true, stop: nil)
+      with_maintenance_lock(dry_run: dry_run) do
+        result = { operation: 'routine', state: 'planned', dry_run: dry_run, eligible: [], deleted: [], retained: [], records: [] }
+        root = File.join(Dir.home, '.pwn', 'maintenance')
+        usage = status[:categories]
+        # A lexical round-robin cursor is only scheduling state, never deletion
+        # authority. Manifests stay put, so concurrent re-registration cannot
+        # be removed or overwritten by cleanup completion.
+        cursor_path = File.join(root, 'disposable.cursor')
+        cursor = File.file?(cursor_path) && !File.symlink?(cursor_path) ? File.binread(cursor_path, 70) : ''
+        cursor = '' unless cursor.match?(/\A[a-f0-9]{64}\.json\z/)
+        files = Dir.glob(File.join(root, 'disposable', '*.json'))
+        after, before = files.partition { |file| File.basename(file) > cursor }
+        files = after + before
+        result[:incomplete] = true if files.length > policy['scan_limit']
+        files = files.first(policy['scan_limit'])
+        files.each do |manifest|
+          if !admit? || stop&.call || result[:deleted].length >= policy['batch_size']
+            result[:incomplete] = true
+            break
+          end
+
+          publish(cursor_path, File.basename(manifest)) unless dry_run
+          raise IOError, 'Unsafe disposable manifest' unless File.realpath(manifest) == manifest
+
+          manifest_size = File.size(manifest)
+          break unless admit?((manifest_size + 1) * 2)
+
+          manifest_bytes = exact_bytes(manifest, manifest_size)
+          row = JSON.parse(manifest_bytes)
+          category_usage = usage[row['category']] || {}
+          budget = category_usage[:budget_bytes]
+          pressure = budget && category_usage[:bytes] > budget
+          reason = disposable_reason(row, pressure: pressure, verify: false)
+          if reason
+            result[:retained] << { manifest: manifest, reason: reason }
+            next
+          end
+          path = row['path']
+          File.open("#{path}.lease", File::RDWR | File::NOFOLLOW) do |lease|
+            unless lease.flock(File::LOCK_EX | File::LOCK_NB)
+              result[:retained] << { path: path, reason: 'active' }
+              next
+            end
+            if exact_bytes(manifest, manifest_size) != manifest_bytes
+              result[:retained] << { path: path, reason: 'registration_changed' }
+              next
+            end
+            # Reserve all payload reads, backup write and verification before commit.
+            unless admit?((row['bytes'] + 1) * (dry_run ? 1 : 5))
+              result[:retained] << { path: path, reason: 'work_budget' }
+              next
+            end
+            if (reason = disposable_reason(row, pressure: pressure))
+              result[:retained] << { path: path, reason: reason }
+              next
+            end
+            result[:eligible] << path
+            category_usage[:bytes] -= row['bytes']
+            next if dry_run
+
+            unless result[:ledger]
+              directory = PWN::Backups.directory(label: 'disposable')
+              result[:ledger] = File.join(directory, 'ledger.json')
+            end
+            backup_path = File.join(File.dirname(result[:ledger]), "#{Digest::SHA256.hexdigest(path)}.bin")
+            publish(backup_path, exact_bytes(path, row['bytes']))
+            raise IOError, 'Disposable backup mismatch' unless Digest::SHA256.hexdigest(exact_bytes(backup_path, row['bytes'])) == row['sha256']
+
+            record = row.merge('backup' => backup_path, 'state' => 'prepared')
+            result[:records] << record
+            result[:state] = 'prepared'
+            publish(result[:ledger], JSON.pretty_generate(result))
+            raise IOError, 'Disposable changed after backup' if disposable_reason(row, pressure: pressure)
+
+            File.unlink(path)
+            File.open(File.dirname(path), File::RDONLY, &:fsync)
+            result[:deleted] << path
+            record['state'] = 'committed'
+            publish(result[:ledger], JSON.pretty_generate(result))
+            # Keep permanent lease inode and manifest for audit/recovery.
+          end
+        rescue StandardError => e
+          result[:retained] << { manifest: manifest, reason: e.class.name }
+        end
+        unless dry_run
+          result[:state] = stopping? || stop&.call ? 'stopped' : 'committed'
+          result[:state] = 'interrupted' if result[:records].any? { |row| row['state'] == 'prepared' }
+        end
+        publish(result[:ledger], JSON.pretty_generate(result)) if result[:ledger]
+        result
+      end
+    end
+
+    # Only disposable quarantine expires. Learning/session/retirement backups
+    # are evidence, and are deliberately outside this pruning protocol.
+    def self.prune_quarantine(dry_run: true)
+      config = policy
+      result = { eligible: [], deleted: [], retained: [] }
+      days = config['retention_days']['maintenance']
+      return result if days.nil?
+
+      with_maintenance_lock(dry_run: dry_run) do
+        remaining_bytes = status[:categories]['maintenance'][:unique_bytes]
+        budget = config['budget_bytes']['maintenance']
+        Dir.glob(File.join(Dir.home, '.pwn', 'maintenance', 'quarantine', '*', 'ledger.json')).each do |ledger|
+          break if stopping? || result[:deleted].length >= config['batch_size']
+
+          raise IOError, 'Unsafe quarantine ledger' unless File.realpath(ledger) == ledger
+
+          data = JSON.parse(admitted_bytes(ledger))
+          next if data['state'] == 'expired'
+          next if data['state'] != 'expiry_prepared' && File.mtime(ledger) > Time.now - (days * 86_400) && !(budget && remaining_bytes > budget)
+          raise IOError, 'Uncommitted quarantine retained' unless data['operation'] == 'routine' && %w[committed expiry_prepared].include?(data['state']) && data['records'].is_a?(Array) && data['records'].all? { |row| row['state'] == 'committed' }
+
+          backups = data['records'].filter_map do |row|
+            path = row.fetch('backup')
+            raise IOError, 'Unsafe quarantine backup' unless File.dirname(path) == File.dirname(ledger) && File.expand_path(path) == path
+            next if data['state'] == 'expiry_prepared' && !File.exist?(path) && !File.symlink?(path)
+
+            raise IOError, 'Unknown quarantine bytes' unless File.dirname(path) == File.dirname(ledger) && File.realpath(path) == path && Digest::SHA256.hexdigest(admitted_bytes(path)) == row['sha256']
+
+            path
+          end
+          raise IOError, 'Unknown quarantine contents' unless (Dir.children(File.dirname(ledger)) - ['ledger.json', *backups.map { |path| File.basename(path) }]).empty?
+
+          result[:eligible].concat(backups)
+          remaining_bytes -= backups.sum { |path| File.size(path) }
+          next if dry_run
+
+          data['state'] = 'expiry_prepared'
+          publish(ledger, JSON.pretty_generate(data))
+          backups.each do |path|
+            break if !admit? || result[:deleted].length >= config['batch_size']
+
+            File.unlink(path)
+            result[:deleted] << path
+          end
+          File.open(File.dirname(ledger), File::RDONLY, &:fsync)
+          data['state'] = backups.any? { |path| File.exist?(path) } ? 'expiry_prepared' : 'expired'
+          publish(ledger, JSON.pretty_generate(data))
+        rescue StandardError => e
+          result[:retained] << { ledger: ledger, reason: e.class.name }
+        end
+      end
+      result
+    end
+
+    # Prune duplicate physical bytes, not recovery names: hardlink replacement
+    # preserves every store-specific rollback API and never loses the last copy.
+    # Only committed writer-defined backup rows enter this inventory.
+    def self.legacy_backups
+      root = File.join(Dir.home, '.pwn')
+      patterns = ['session_cleanup_archive/*/ledger.json', 'learning/migrations/*.json', 'maintenance/retirements/*/ledger.json']
+      rows = []
+      patterns.each do |pattern|
+        Dir.glob(File.join(root, pattern)).first(policy['scan_limit']).each do |ledger|
+          break unless admit?
+          next unless File.realpath(ledger) == ledger
+
+          data = JSON.parse(admitted_bytes(ledger))
+          candidates = []
+          if ledger.start_with?("#{File.join(root, 'learning', 'migrations')}/")
+            hash = File.basename(ledger, '.json')
+            next unless data['version'] == 1 && data['state'] == 'committed' && data['before_sha256'] == hash && hash.match?(/\A[a-f0-9]{64}\z/)
+
+            candidates << [File.join(File.dirname(ledger), "#{hash}.backup.jsonl"), hash]
+          elsif ledger.start_with?("#{File.join(root, 'maintenance', 'retirements')}/")
+            next unless data['state'] == 'committed' && data['session_id'].to_s.match?(PWN::Sessions::SESSION_ID)
+
+            candidates << [data['backup'], data['sha256']]
+          elsif data['dry_run'] == false && data['records'].is_a?(Array) && data['deleted_ids'].is_a?(Array)
+            data['records'].each do |row|
+              next unless row['deleted'] == true && data['deleted_ids'].include?(row['id']) && row['id'].to_s.match?(PWN::Sessions::SESSION_ID)
+
+              row.fetch('files', {}).each do |name, info|
+                next unless info && ["#{row['id']}.jsonl", "#{row['id']}.meta.json"].include?(name)
+
+                candidates << [File.join(File.dirname(ledger), name), info['sha256']]
+              end
+            end
+            Array(data['dependency_removals']).each do |row|
+              candidates << [row['backup'], row['sha256']] if row['state'] == 'committed'
+            end
+          end
+          candidates.each do |path, hash|
+            next unless path.is_a?(String) && File.dirname(path) == File.dirname(ledger)
+            next unless verified_backup?(path, hash)
+
+            rows << { path: path, sha256: hash, ledger: ledger }
+          end
+        rescue StandardError
+          # Unknown, partial and unreadable ledgers remain untouched.
+          next
+        end
+      end
+      rows.uniq { |row| row[:path] }
+    end
+
+    def self.verified_backup?(path, hash, admitted: false, size: nil)
+      hash.is_a?(String) && hash.match?(/\A[a-f0-9]{64}\z/) && File.file?(path) &&
+        File.realpath(path) == path && File.stat(path).uid == Process.uid &&
+        Digest::SHA256.hexdigest(admitted ? exact_bytes(path, size || File.size(path)) : admitted_bytes(path)) == hash
+    end
+
+    def self.prune_legacy_backups(dry_run: true)
+      result = { operation: 'backup_compaction', state: 'planned', compacted: [], retained: [], records: [] }
+      days = policy['retention_days']['maintenance']
+      return result if days.nil?
+
+      with_maintenance_lock(dry_run: dry_run) do
+        # Learning and continuation producers also serialize with these locks.
+        with_dependency_lock(nil, dry_run: dry_run) do
+          groups = legacy_backups.group_by { |row| row[:sha256] }
+          usage = status[:categories]['maintenance'][:unique_bytes]
+          budget = policy['budget_bytes']['maintenance']
+          groups.each_value do |rows|
+            canonical = rows.first
+            rows.drop(1).each do |row|
+              break unless admit?
+              break if result[:compacted].length >= policy['batch_size']
+              next if File.identical?(canonical[:path], row[:path])
+              next if File.mtime(row[:ledger]) > Time.now - (days * 86_400) && !(budget && usage > budget)
+
+              size = File.size(row[:path])
+              break unless admit?((size + 1) * 5)
+
+              usage -= size
+              record = row.merge(canonical: canonical[:path], bytes: size, state: 'prepared')
+              result[:records] << record
+              next if dry_run
+
+              unless result[:ledger]
+                directory = private_directory(File.join(Dir.home, '.pwn', 'maintenance', 'compactions'))
+                result[:ledger] = File.join(directory, "#{SecureRandom.hex(12)}.json")
+              end
+              result[:state] = 'prepared'
+              publish(result[:ledger], JSON.generate(result))
+              compact_backup(record)
+              record[:state] = 'committed'
+              result[:compacted] << row[:path]
+              publish(result[:ledger], JSON.generate(result))
+            rescue StandardError => e
+              result[:retained] << { path: row[:path], reason: e.class.name }
+            end
+          end
+          result[:state] = stopping? || result[:records].any? { |row| row[:state] == 'prepared' } ? 'interrupted' : 'committed' unless dry_run
+          publish(result[:ledger], JSON.generate(result)) if result[:ledger]
+        end
+      end
+      result
+    end
+
+    def self.compact_backup(row)
+      path, canonical, hash = row.values_at(:path, :canonical, :sha256)
+      size = row[:bytes] || File.size(path)
+      raise IOError, 'Changed backup' unless verified_backup?(path, hash, admitted: true, size: size) && verified_backup?(canonical, hash, admitted: true, size: size)
+      return if File.identical?(path, canonical)
+
+      temporary = "#{path}.compact-#{SecureRandom.hex(12)}"
+      begin
+        File.link(canonical, temporary)
+        raise IOError, 'Backup readback mismatch' unless exact_bytes(temporary, size) == exact_bytes(path, size)
+
+        File.rename(temporary, path)
+        File.open(File.dirname(path), File::RDONLY, &:fsync)
+        raise IOError, 'Compacted backup mismatch' unless verified_backup?(path, hash, admitted: true, size: size)
+      ensure
+        File.unlink(temporary) if temporary && File.exist?(temporary)
+      end
+    end
+
+    # Status is not rollback: broad maintenance has independently committed
+    # children. Restoring a ledger alone never undoes deletion or migration.
+    def self.recovery_status(ledger:)
+      root = File.join(Dir.home, '.pwn')
+      prefixes = %w[backup maintenance session_cleanup_archive learning/migrations].map { |name| "#{File.join(root, name)}/" }
+      raise IOError, 'Unsafe recovery ledger' unless prefixes.any? { |prefix| ledger.start_with?(prefix) } && File.realpath(ledger) == ledger
+
+      data = JSON.parse(File.binread(ledger))
+      operation = data['operation']
+      operation = 'session_cleanup' if ledger.include?('/backup/') && data['records'].is_a?(Array) && data['deleted_ids'].is_a?(Array)
+      operation = 'continuation_retirement' if ledger.include?('/backup/') && data['backup'] == File.join(File.dirname(ledger), 'personas.json')
+      operation = 'session_layout' if ledger.include?('/backup/') && File.basename(ledger) == 'layout.json'
+      operation = 'session_layout' if File.basename(ledger) == 'layout.json' && ledger.start_with?("#{File.join(root, 'session_cleanup_archive')}/") && data['records'].is_a?(Array)
+      operation = 'learning_migration' if ledger.start_with?("#{File.join(root, 'learning', 'migrations')}/") && data['version'] == 1 && data['before_sha256'] == File.basename(ledger, '.json')
+      operation = 'session_cleanup' if ledger.start_with?("#{File.join(root, 'session_cleanup_archive')}/") && data['dry_run'] == false && data['records'].is_a?(Array) && data['deleted_ids'].is_a?(Array)
+      operation = 'continuation_retirement' if ledger.start_with?("#{File.join(root, 'maintenance', 'retirements')}/") && %w[prepared committed rolled_back].include?(data['state']) && data['backup'] == File.join(File.dirname(ledger), 'personas.json')
+      actions = { 'session_layout' => ['resume'], 'session_cleanup' => ['restore'], 'continuation_retirement' => ['rollback'], 'backup_compaction' => ['resume'], 'maintenance' => ['resume'], 'learning_migration' => ['rollback'], 'routine' => ['restore'] }.fetch(operation, ['inspect_store_specific_recovery'])
+      actions << 'rollback_dependencies' if operation == 'session_cleanup' && data['dependency_removals'].is_a?(Array)
+      { ledger: ledger, state: data['state'] || 'legacy_per_record', operation: operation,
+        actions: actions,
+        data: data, warning: 'Ledger restoration does not undo data changes; restore source sessions before learning rollback.' }
+    end
+
+    # Recovery is explicit repair, never startup/cron behavior. Both prepared
+    # and committed rows retain exact backups; an existing destination wins.
+    def self.recover(ledger:, dry_run: true, action: 'restore', writers_stopped: false)
+      report = recovery_status(ledger: ledger)
+      raise ArgumentError, 'Unsupported recovery action; inspect recovery_status' unless report[:actions].include?(action)
+
+      return reorganize(dry_run: dry_run, writers_stopped: writers_stopped) if report[:operation] == 'session_layout'
+
+      return recover_dependencies(ledger: ledger, data: report[:data], dry_run: dry_run) if action == 'rollback_dependencies'
+      return recover_sessions(ledger: ledger, data: report[:data], dry_run: dry_run) if report[:operation] == 'session_cleanup'
+      return recover_continuation(ledger: ledger, data: report[:data], dry_run: dry_run) if report[:operation] == 'continuation_retirement'
+      if report[:operation] == 'learning_migration'
+        return with_maintenance_lock(dry_run: dry_run) do
+          PWN::AI::Agent::Learning.rollback_evidence(migration: File.basename(ledger, '.json'), dry_run: dry_run)
+        end
+      end
+      return dry_run ? report.merge(dry_run: true) : maintain(dry_run: false) if report[:operation] == 'maintenance'
+      if report[:operation] == 'backup_compaction'
+        return with_maintenance_lock(dry_run: dry_run) do
+          with_dependency_lock(nil, dry_run: dry_run) do
+            known = legacy_backups.to_h { |row| [row[:path], row[:sha256]] }
+            data = report[:data]
+            data.fetch('records').each do |row|
+              raise IOError, 'Unknown compaction source' unless [row['path'], row['canonical']].all? { |path| known[path] == row['sha256'] }
+              next if dry_run
+
+              compact_backup(row.transform_keys(&:to_sym))
+              row['state'] = 'committed'
+              publish(ledger, JSON.generate(data))
+            end
+            data['state'] = 'committed' unless dry_run
+            publish(ledger, JSON.generate(data)) unless dry_run
+            { dry_run: dry_run, state: data['state'], operation: 'backup_compaction' }
+          end
+        end
+      end
+      root = File.join(Dir.home, '.pwn', 'maintenance', 'quarantine')
+      raise IOError, 'Unsafe recovery ledger' unless [root, File.join(Dir.home, '.pwn', 'backup')].any? { |base| ledger.start_with?("#{base}/") } && File.realpath(ledger) == ledger
+
+      data = JSON.parse(File.binread(ledger))
+      raise IOError, 'Unknown recovery ledger' unless data['operation'] == 'routine' && data['records'].is_a?(Array)
+
+      result = { operation: 'repair', dry_run: dry_run, restored: [] }
+      with_maintenance_lock(dry_run: dry_run) do
+        data['records'].each do |row|
+          path = row.fetch('path')
+          category = row.fetch('category')
+          target_root = disposable_directory(category)
+          backup_path = row.fetch('backup')
+          raise IOError, 'Unsafe recovery path' unless %w[cache tmp logs].include?(category) && path.start_with?("#{target_root}/") && File.expand_path(path) == path && File.realpath(File.dirname(path)) == File.dirname(path)
+          raise IOError, 'Unsafe recovery backup' unless File.dirname(backup_path) == File.dirname(ledger) && File.realpath(backup_path) == backup_path && Digest::SHA256.file(backup_path).hexdigest == row['sha256']
+          raise IOError, 'Refusing existing recovery destination' if File.exist?(path) || File.symlink?(path)
+          next if dry_run
+
+          File.open("#{path}.lease", File::RDWR | File::NOFOLLOW) do |lease|
+            raise IOError, 'Recovery destination active' unless lease.flock(File::LOCK_EX | File::LOCK_NB)
+
+            temporary = "#{path}.restore-#{SecureRandom.hex(12)}"
+            begin
+              publish(temporary, File.binread(backup_path))
+              File.link(temporary, path) # atomic no-clobber; never replace a reader's new file
+              File.open(File.dirname(path), File::RDONLY, &:fsync)
+              result[:restored] << path
+              row['recovered_at'] = Time.now.utc.iso8601
+              publish(ledger, JSON.pretty_generate(data))
+            ensure
+              File.unlink(temporary) if temporary && File.exist?(temporary)
+            end
+          end
+        end
+      end
+      result
+    end
+
+    def self.recover_dependencies(ledger:, data:, dry_run:)
+      result = { dry_run: dry_run, restored: [] }
+      root = File.join(Dir.home, '.pwn')
+      allowed = %w[learning.jsonl memory.json memory.archive.json mistakes.json].map { |name| File.join(root, name) }
+      with_maintenance_lock(dry_run: dry_run) do
+        with_dependency_lock(nil, dry_run: dry_run) do
+          data.fetch('dependency_removals').reverse_each do |row|
+            path, backup_path, id = row.values_at('path', 'backup', 'session_id')
+            raise IOError, 'Unsafe dependency recovery target' unless allowed.include?(path) && File.realpath(path) == path
+            raise IOError, 'Invalid dependency recovery backup' unless File.dirname(backup_path) == File.dirname(ledger) && verified_backup?(backup_path, row['sha256'])
+            raise IOError, 'Restore source session before dependency rollback' unless id.is_a?(String) && id.match?(PWN::Sessions::SESSION_ID) && File.file?(File.join(PWN::Sessions.sessions_dir, "#{id}.jsonl"))
+
+            current = Digest::SHA256.file(path).hexdigest
+            next if current == row['sha256']
+            raise IOError, 'Dependency store changed since removal' unless current == row['updated_sha256']
+            next if dry_run
+
+            publish(path, File.binread(backup_path))
+            raise IOError, 'Dependency restore mismatch' unless Digest::SHA256.file(path).hexdigest == row['sha256']
+
+            row['state'] = 'rolled_back'
+            publish(ledger, JSON.generate(data))
+            result[:restored] << path
+          end
+        end
+      end
+      result
+    end
+
+    def self.restore_copy(backup_path, path, hash)
+      raise IOError, 'Invalid recovery backup' unless verified_backup?(backup_path, hash)
+      raise IOError, 'Refusing existing recovery destination' if File.exist?(path) || File.symlink?(path)
+      raise IOError, 'Unsafe recovery parent' unless File.realpath(File.dirname(path)) == File.dirname(path)
+
+      temporary = "#{path}.restore-#{SecureRandom.hex(12)}"
+      begin
+        publish(temporary, File.binread(backup_path))
+        raise IOError, 'Restore readback mismatch' unless Digest::SHA256.file(temporary).hexdigest == hash
+
+        File.link(temporary, path)
+        File.open(File.dirname(path), File::RDONLY, &:fsync)
+      ensure
+        File.unlink(temporary) if temporary && File.exist?(temporary)
+      end
+    end
+
+    def self.recover_sessions(ledger:, data:, dry_run:)
+      result = { dry_run: dry_run, restored: [], warning: 'Session bytes only; dependency remediations and learning migration are separate transactions.' }
+      with_maintenance_lock(dry_run: dry_run) do
+        data.fetch('records').each do |row|
+          id = row['id']
+          next unless id.is_a?(String) && id.match?(PWN::Sessions::SESSION_ID)
+
+          # A crash can follow unlink before deleted_ids was journaled. The
+          # exact prepared snapshot is also eligible, but never replaces data.
+          next unless row['files'].is_a?(Hash)
+
+          row['files'].each do |name, info|
+            next unless info && ["#{id}.jsonl", "#{id}.meta.json"].include?(name)
+
+            backup_path = File.join(File.dirname(ledger), name)
+            next unless File.file?(backup_path)
+            raise IOError, 'Invalid session recovery backup' unless verified_backup?(backup_path, info['sha256'])
+
+            path = name.end_with?('.meta.json') ? PWN::Sessions.support_path(kind: :metadata, session_id: id) : File.join(PWN::Sessions.sessions_dir, name)
+            next if verified_backup?(path, info['sha256'])
+            raise IOError, 'Refusing existing recovery destination' if File.exist?(path) || File.symlink?(path)
+            next if dry_run
+
+            File.open(PWN::Sessions.support_path(kind: :lease, session_id: id), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+              raise IOError, 'Session recovery active' unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+              restore_copy(backup_path, path, info['sha256'])
+              result[:restored] << path
+              (data['restored_paths'] ||= []) << path
+              publish(ledger, JSON.generate(data))
+            end
+          end
+        end
+      end
+      result
+    end
+
+    def self.recover_continuation(ledger:, data:, dry_run:)
+      root = File.join(Dir.home, '.pwn')
+      path, id = data.values_at('path', 'session_id')
+      raise IOError, 'Unsafe continuation recovery path' unless path.is_a?(String) && path.match?(%r{\A#{Regexp.escape(root)}/swarm/\d{8}_\d{6}_[a-f0-9]{6}/personas\.json\z}) && File.realpath(path) == path
+      raise IOError, 'Invalid continuation recovery identity' unless id.is_a?(String) && id.match?(PWN::Sessions::SESSION_ID)
+      raise IOError, 'Invalid continuation backup' unless verified_backup?(data['backup'], data['sha256'])
+
+      before = File.binread(data['backup'])
+      map = JSON.parse(before)
+      raise IOError, 'Invalid continuation backup schema' unless map.is_a?(Hash) && map[data['name']] == id
+
+      expected = map.reject { |name, _| name == data['name'] }
+      result = { dry_run: dry_run, restored: [] }
+      with_maintenance_lock(dry_run: dry_run) do
+        with_dependency_lock(nil, dry_run: dry_run) do
+          current = JSON.parse(File.binread(path))
+          raise IOError, 'Continuation map changed after retirement' unless current == expected || current == map
+          next if dry_run || current == map
+
+          File.open(PWN::Sessions.support_path(kind: :lease, session_id: id), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lease|
+            raise IOError, 'Continuation recovery active' unless lease.flock(File::LOCK_EX | File::LOCK_NB)
+            raise IOError, 'Restore source session before continuation' unless File.file?(File.join(PWN::Sessions.sessions_dir, "#{id}.jsonl"))
+
+            publish(path, before)
+            raise IOError, 'Continuation restore readback mismatch' unless File.binread(path) == before
+
+            data['state'] = 'rolled_back'
+            publish(ledger, JSON.generate(data))
+            result[:restored] << path
+          end
+        end
+      end
+      result
+    end
+
+    def self.with_continuation_lock(root: File.join(Dir.home, '.pwn'))
+      File.open(File.join(root, '.swarm-continuations.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    def self.retire_continuation(root:, swarm_id:, name:)
+      raise ArgumentError, 'Invalid swarm identifier' unless swarm_id.match?(/\A\d{8}_\d{6}_[a-f0-9]{6}\z/)
+
+      path = File.join(root, swarm_id, 'personas.json')
+      with_maintenance_lock(dry_run: false) do
+        with_continuation_lock(root: File.dirname(root)) do
+          raise IOError, 'Unsafe continuation map' unless File.realpath(path) == path
+
+          bytes = File.binread(path)
+          map = JSON.parse(bytes)
+          raise IOError, 'Unknown continuation map' unless map.is_a?(Hash) && map.values.all? { |id| id.is_a?(String) && id.match?(/\A\d{8}_\d{6}_[a-f0-9]{8}\z/) }
+
+          id = map[name]
+          next { state: 'absent' } unless id
+
+          File.open(PWN::Sessions.support_path(kind: :lease, session_id: id), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lease|
+            raise IOError, 'Swarm continuation active' unless lease.flock(File::LOCK_EX | File::LOCK_NB)
+
+            directory = PWN::Backups.directory(label: 'continuation')
+            backup_path = File.join(directory, 'personas.json')
+            publish(backup_path, bytes)
+            raise IOError, 'Continuation backup mismatch' unless File.binread(backup_path) == bytes
+
+            result = { state: 'prepared', session_id: id, path: path, name: name, backup: backup_path, sha256: Digest::SHA256.hexdigest(bytes) }
+            ledger = File.join(directory, 'ledger.json')
+            publish(ledger, JSON.pretty_generate(result))
+            map.delete(name)
+            publish(path, JSON.pretty_generate(map))
+            raise IOError, 'Continuation retirement mismatch' unless JSON.parse(File.binread(path)) == map
+
+            result[:state] = 'committed'
+            publish(ledger, JSON.pretty_generate(result))
+            result
+          end
+        end
+      end
+    end
 
     def self.classify(path, id)
       return :unknown unless path == File.join(PWN::Sessions.sessions_dir, "#{id}.jsonl")
@@ -113,28 +1152,77 @@ module PWN
 
     def self.publish(path, bytes)
       temporary = "#{path}.#{SecureRandom.hex(8)}.tmp"
+      root = File.join(Dir.home, '.pwn')
+      category = %w[cache tmp].find { |name| path.start_with?("#{disposable_directory(name)}/") }
+      if category
+        directory = private_directory(File.join(root, 'maintenance', 'atomic'))
+        journal = File.join(directory, "#{SecureRandom.hex(12)}.json")
+      end
       File.open(temporary, File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW, 0o600) do |file|
+        file.flock(File::LOCK_EX)
+        if journal
+          row = { version: 1, operation: 'atomic_disposable', category: category, path: temporary, target: path,
+                  inode: file.stat.ino, device: file.stat.dev, sha256: Digest::SHA256.hexdigest(bytes), created_at: Time.now.to_i }
+          publish(journal, JSON.generate(row))
+        end
         file.write(bytes)
         file.flush
         file.fsync
+        File.rename(temporary, path)
+        File.open(File.dirname(path), File::RDONLY, &:fsync)
       end
-      File.rename(temporary, path)
-      File.open(File.dirname(path), File::RDONLY, &:fsync)
     ensure
       File.unlink(temporary) if temporary && File.exist?(temporary)
+      File.unlink(journal) if journal && File.exist?(journal)
     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)
+    # Only registered disposable atomic outputs are recoverable automatically.
+    # Missing journals, partial bytes, wrong inode, active writers and evidence
+    # atomic outputs are preserved, regardless of filename or apparent age.
+    def self.recover_atomic_temps(dry_run: true, expired_only: false)
+      result = { deleted: [], retained: [] }
+      root = File.join(Dir.home, '.pwn')
+      with_maintenance_lock(dry_run: dry_run) do
+        Dir.glob(File.join(root, 'maintenance', 'atomic', '*.json')).first(policy['scan_limit']).each do |ledger|
+          break unless admit?
+          break if result[:deleted].length >= policy['batch_size']
+          raise IOError, 'Unsafe atomic ledger' unless File.realpath(ledger) == ledger
+
+          row = JSON.parse(admitted_bytes(ledger))
+          raise IOError, 'Unknown atomic owner' unless row['version'] == 1 && row['operation'] == 'atomic_disposable' && %w[cache tmp].include?(row['category'])
+
+          days = policy['retention_days'][row['category']]
+          next if days.nil? || (expired_only && row.fetch('created_at') > Time.now.to_i - (days * 86_400))
+
+          path, target = row.values_at('path', 'target')
+          base = "#{disposable_directory(row['category'])}/"
+          raise IOError, 'Unsafe atomic path' unless [path, target].all? { |name| name.is_a?(String) && name.start_with?(base) && File.expand_path(name) == name } && File.dirname(path) == File.dirname(target) && path.match?(/\A#{Regexp.escape(target)}\.[a-f0-9]{16}\.tmp\z/)
+          next unless File.exist?(path) || File.symlink?(path)
+          raise IOError, 'Changed atomic bytes' unless verified_backup?(path, row['sha256']) && File.stat(path).ino == row['inode'] && File.stat(path).dev == row['device']
+
+          File.open("#{target}.lease", File::RDWR | File::NOFOLLOW) do |lease|
+            raise IOError, 'Atomic producer active' unless lease.flock(File::LOCK_EX | File::LOCK_NB)
+
+            File.open(path, File::RDONLY | File::NOFOLLOW) do |file|
+              raise IOError, 'Atomic file active or changed' unless file.flock(File::LOCK_EX | File::LOCK_NB) && File.identical?(file, path) && file.stat.ino == row['inode'] && Digest::SHA256.hexdigest(admitted_bytes(path)) == row['sha256']
+              next if dry_run
+
+              File.unlink(path)
+              File.open(File.dirname(path), File::RDONLY, &:fsync)
+              row['state'] = 'recovered'
+              publish(ledger, JSON.generate(row))
+              result[:deleted] << path
+            end
+          end
+        rescue StandardError => e
+          result[:retained] << { ledger: ledger, reason: e.class.name }
+        end
       end
+      result
+    end
+
+    def self.backup(path, expected, result)
+      result[:archive_dir] ||= PWN::Backups.directory(label: 'session-cleanup')
       expected.each do |name, record|
         next unless record
 
@@ -175,17 +1263,22 @@ module PWN
       state
     end
 
-    def self.with_dependency_lock(id)
+    def self.with_dependency_lock(id, dry_run: false)
+      return yield if dry_run
+
       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
+      paths = %w[.learning-write.lock .swarm-continuations.lock memory.json.write.lock mistakes.json.write.lock].map { |name| File.join(root, name) }.sort
       locks = []
       begin
         paths.each do |path|
+          owner = Thread.current[:pwn_learning_write_lock]
+          next if File.basename(path) == '.learning-write.lock' && owner && owner[:pid] == Process.pid && owner[:thread] == Thread.current
+
           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)
@@ -240,7 +1333,7 @@ module PWN
     # 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:)
+    def self.with_maintenance_lock(dry_run:, &block)
       return yield if dry_run
 
       root = PWN::Sessions.sessions_dir
@@ -255,22 +1348,127 @@ module PWN
 
         begin
           Thread.current[:pwn_session_maintenance_lock] = { pid: Process.pid, thread: Thread.current, path: path, file: file }
-          yield
+          learning = PWN::AI::Agent::Learning.send(:learning_lock, nonblocking: true)
+          if learning == :busy
+            Thread.current[:pwn_backup_learning_busy] = true
+            yield
+          else
+            PWN::Backups.transaction(&block)
+          end
         ensure
+          PWN::AI::Agent::Learning.send(:learning_unlock, lock: learning) unless learning == :busy
+          Thread.current[:pwn_backup_learning_busy] = nil
           Thread.current[:pwn_session_maintenance_lock] = owner
         end
       end
     end
 
+    def self.stopping?
+      control = Thread.current[:pwn_steering_input]
+      budget = Thread.current[:pwn_maintenance_budget]
+      (control.respond_to?(:stopping?) && control.stopping?) || (budget && (budget[:remaining] <= 0 || budget[:bytes] <= 0 || Process.clock_gettime(Process::CLOCK_MONOTONIC) >= budget[:deadline]))
+    end
+
+    # Fresh schedules use one coordinator. Existing split jobs keep maintain
+    # until an operator explicitly replaces their schedules after deployment.
+    # Preserve evidence before retention can remove its last source edge.
+    def self.coordinate(dry_run: false, current_session_id: nil, proc_root: '/proc')
+      with_maintenance_lock(dry_run: dry_run) do
+        result = { state: 'prepared', dry_run: dry_run, phases: {} }
+        unless dry_run
+          directory = private_directory(File.join(Dir.home, '.pwn', 'maintenance', 'runs'))
+          ledger = File.join(directory, "coordinator-#{SecureRandom.hex(12)}.json")
+          publish(ledger, JSON.generate(result))
+        end
+        begin
+          maintenance = maintain(dry_run: dry_run, current_session_id: current_session_id, proc_root: proc_root)
+          result[:phases][:maintenance] = maintenance
+          if maintenance[:apply_blocked] || maintenance[:incomplete] || stopping?
+            result[:state] = maintenance[:apply_blocked] ? 'blocked' : 'interrupted'
+          else
+            result[:phases][:memory_consolidation] = dry_run ? { planned: true } : PWN::AI::Agent::Learning.consolidate
+            result[:phases][:learning_retention] = PWN::AI::Agent::Learning.prune_outcomes!(dry_run: dry_run)
+            result[:phases][:mistakes_retention] = PWN::AI::Agent::Mistakes.lean!(dry_run: dry_run)
+            result[:phases][:policy_retention] = PWN::AI::Agent::Policy.lean!(dry_run: dry_run)
+            result[:state] = dry_run ? 'planned' : 'committed'
+          end
+          result[:transaction_ledger] = ledger if ledger
+          publish(ledger, JSON.generate(result)) if ledger
+          result
+        rescue StandardError, Interrupt, SystemExit => e
+          result[:state] = 'interrupted'
+          publish(ledger, JSON.generate(result.merge(error: e.class.name))) if ledger
+          raise
+        end
+      end
+    end
+
     def self.maintain(dry_run: false, current_session_id: nil, proc_root: '/proc')
+      config = policy # validate policy before any mutation or migration
+      prior_budget = Thread.current[:pwn_maintenance_budget]
+      prior_admission = Thread.current[:pwn_maintenance_admission]
+      Thread.current[:pwn_maintenance_budget] = { remaining: config['work_items'], bytes: config['work_bytes'], deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + config['work_seconds'] }
+      Thread.current[:pwn_maintenance_admission] = method(:admit?)
       with_maintenance_lock(dry_run: dry_run) do
-        maintenance_transaction(dry_run: dry_run, current_session_id: current_session_id, proc_root: proc_root)
+        unless dry_run
+          directory = private_directory(File.join(Dir.home, '.pwn', 'maintenance', 'runs'))
+          ledger = File.join(directory, "#{Time.now.utc.strftime('%Y%m%dT%H%M%S')}-#{SecureRandom.hex(8)}.json")
+          publish(ledger, JSON.generate(version: 1, state: 'prepared', operation: 'maintenance'))
+        end
+        begin
+          result = maintenance_transaction(dry_run: dry_run, current_session_id: current_session_id, proc_root: proc_root)
+          result[:storage] = clean_disposables(dry_run: dry_run || result[:apply_blocked] == true)
+          result[:quarantine] = prune_quarantine(dry_run: dry_run || result[:apply_blocked] == true)
+          unless stopping?
+            result[:atomic_temps] = recover_atomic_temps(dry_run: dry_run || result[:apply_blocked] == true, expired_only: true)
+            result[:legacy_backups] = prune_legacy_backups(dry_run: dry_run || result[:apply_blocked] == true)
+          end
+          result[:migration_backups] = PWN::Migrate.prune_backups(dry_run: dry_run || result[:apply_blocked] == true, admission: method(:admit?)) unless stopping?
+          result[:usage] = status unless stopping?
+          result[:incomplete] = true if stopping? || result[:storage][:incomplete]
+          result[:state] = if dry_run
+                             'planned'
+                           elsif result[:incomplete] || result[:storage][:state] == 'interrupted'
+                             'interrupted'
+                           elsif result[:apply_blocked]
+                             'blocked'
+                           else
+                             'committed'
+                           end
+          result[:transaction_ledger] = ledger if ledger
+          publish(ledger, JSON.generate(version: 1, state: result[:state], operation: 'maintenance', result: result)) if ledger
+          result
+        rescue StandardError, Interrupt, SystemExit => e
+          publish(ledger, JSON.generate(version: 1, state: 'interrupted', operation: 'maintenance', error: e.class.name, result: result)) if ledger
+          raise
+        end
       end
+    ensure
+      Thread.current[:pwn_maintenance_budget] = prior_budget
+      Thread.current[:pwn_maintenance_admission] = prior_admission
+    end
+
+    # Admission is cooperative: an admitted atomic write is never interrupted.
+    def self.admit?(bytes = 0)
+      return false if stopping?
+
+      budget = Thread.current[:pwn_maintenance_budget]
+      if budget
+        budget[:remaining] -= 1
+        if bytes > budget[:bytes]
+          budget[:bytes] = 0
+          return false
+        end
+        budget[:bytes] -= bytes
+      end
+      true
     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?
+      return preflight.merge(apply_blocked: true, evidence_migration: { deferred: 'learning_writer_active', migrated_rows: 0 }) if Thread.current[:pwn_backup_learning_busy] && !dry_run
+
+      blocked = stopping? || !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)
@@ -278,7 +1476,10 @@ module PWN
         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)
+      return preflight.merge(incomplete: true, apply_blocked: true) if stopping?
+
+      migration = PWN::AI::Agent::Learning.migrate_evidence(dry_run: dry_run || blocked, max_sessions: policy['batch_size'], stop: method(:stopping?), nonblocking: true)
+      blocked = true if migration[:deferred]
       result = if dry_run || blocked
                  preflight
                else
@@ -404,7 +1605,7 @@ module PWN
       { 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],
+        evidence_migration: result[:evidence_migration], archive_dir: result[:archive_dir], storage: result[:storage], usage: result[:usage], quarantine: result[:quarantine],
         unresolved_dependency_stores: result[:dependency_errors] || [], legacy_owners: result[:legacy_owners] }
     end
 
@@ -430,6 +1631,7 @@ module PWN
       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 }
       references = PWN::Sessions.dependency_index
+      result[:incomplete] = true if references[:errors].include?('incomplete_dependency_index')
       unless references[:errors].empty?
         result[:skipped][:unknown_pins] = 1
         result[:dependency_errors] = references[:errors]
@@ -439,6 +1641,10 @@ module PWN
       dependencies = references[:dependencies]
       pins = dependencies.keys
       Dir.glob(File.join(root, '*.jsonl')).each do |path|
+        unless admit?
+          result[:incomplete] = true
+          break
+        end
         id = File.basename(path, '.jsonl')
         result[:scanned] += 1
         state = cleanup_state(path, id, references)
@@ -457,6 +1663,12 @@ module PWN
           result[:skipped][:unresolved_dependency_remediation] += 1
           next
         end
+        days = policy['retention_days']['sessions']
+        if days.nil? || File.mtime(path) > Time.now - (days * 86_400)
+          record[:skip] = :retention
+          result[:skipped][:retention] += 1
+          next
+        end
         expected = snapshot(path)
         expected_dependencies = invalid_dependencies(id, references)
         record[:dependency_records] = expected_dependencies
@@ -484,6 +1696,17 @@ module PWN
         record[:apply_blocked_by] = :unknown_legacy_ownership unless legacy.empty?
         next if dry_run
 
+        if stopping?
+          record[:skip] = :stopped
+          result[:skipped][:stopped] += 1
+          next
+        end
+        if result[:deleted_ids].length >= policy['batch_size']
+          record[:skip] = :batch_limit
+          result[:skipped][:batch_limit] += 1
+          next
+        end
+
         unless legacy.empty? && legacy_owners(proc_root).empty?
           record[:skip] = :unknown_legacy_ownership
           result[:skipped][:unknown_legacy_ownership] += 1