pwn 0.5.782 → 0.5.784

data/lib/pwn/migrate.rb

@@ -4,6 +4,9 @@ require 'json'
 require 'yaml'
 require 'fileutils'
 require 'time'
+require 'digest'
+require 'find'
+require 'securerandom'
 
 module PWN
   # PWN::Migrate — the ~/.pwn state **doctor** and **auto-migrator**.
@@ -49,7 +52,7 @@ module PWN
     # Bump this whenever the shape of any file under ~/.pwn changes in a
     # way that requires a one-time transform.  Add the transform as an
     # entry in MIGRATIONS keyed by the NEW schema number.
-    SCHEMA_VERSION = 10
+    SCHEMA_VERSION = 11
 
     OK   = "\e[32mok\e[0m"
     BAD  = "\e[31mFAIL\e[0m"
@@ -269,6 +272,10 @@ module PWN
       10 => lambda { |_root, io|
         io.puts '    · pwn.yaml ai reasoning_effort for anthropic, gemini, ollama, openwebui'
         PWN::Migrate.backfill_vault(io: io)
+      },
+      11 => lambda { |_root, io|
+        io.puts '    · versioned housekeeping policy and managed session_cleanup helper'
+        PWN::Cron.install_defaults
       }
     }.freeze
 
@@ -383,14 +390,17 @@ module PWN
       backup  = opts.fetch(:backup, true)
       io      = opts[:io] || $stdout
 
-      FileUtils.mkdir_p(PWN_ROOT)
+      FileUtils.mkdir_p(PWN_ROOT) unless dry_run
       before = status
       io.puts "PWN::Migrate — pwn #{before[:pwn_version]} · ~/.pwn schema " \
               "#{before[:schema_installed]} → #{before[:schema_current]}" \
               "#{'  (dry-run)' if dry_run}"
 
+      drift = fix ? vault_drift(key: opts[:key], iv: opts[:iv]) : nil
+      changes = before[:schema_installed] < SCHEMA_VERSION ||
+                (fix && (!before[:incompatible].empty? || (drift && !drift[:missing].empty?)))
       bpath = nil
-      if backup && !dry_run && File.directory?(PWN_ROOT)
+      if backup && changes && !dry_run && File.directory?(PWN_ROOT)
         bpath = backup!
         io.puts "  backup   : #{bpath}"
       end
@@ -422,7 +432,7 @@ module PWN
         fixed << vd if vd && vd[:added].to_i.positive?
       end
 
-      stamp! unless dry_run
+      stamp! if !dry_run && changes
 
       after = status
       io.puts
@@ -612,19 +622,277 @@ module PWN
       "dropped #{bad} bad line(s), kept #{good.length}"
     end
 
-    private_class_method def self.backup!
-      ts  = Time.now.utc.strftime('%Y%m%d_%H%M%S')
-      dst = File.join(BACKUP_ROOT, ts)
-      FileUtils.mkdir_p(dst)
-      Dir.children(PWN_ROOT).each do |c|
-        next if %w[backup quarantine sessions swarm].include?(c) # large / regenerable
+    # Supported Method Parameters::
+    # PWN::Migrate.prune_backups(dry_run: true, keep: 3, limit: 10, admission: nil)
+    # Default duplicate-only pruning is nondestructive to unique history.
+    # Explicit expire_history policy bounds recovery generations instead.
+    public_class_method def self.prune_backups(opts = {})
+      return expire_backup_generations(opts) if opts[:expire_history] || backup_retention_policy['expire_history']
+
+      dry_run = opts.fetch(:dry_run, true)
+      keep = [Integer(opts.fetch(:keep, 3)), 3].max
+      limit = Integer(opts.fetch(:limit, 10))
+      admission = opts[:admission]
+      result = { eligible: [], deleted: [], retained: [], incomplete: false }
+      return result unless File.directory?(BACKUP_ROOT)
+      raise IOError, 'Unsafe backup root' unless File.realpath(BACKUP_ROOT) == BACKUP_ROOT && File.stat(BACKUP_ROOT).uid == Process.uid
+
+      work = lambda do
+        names = Dir.children(BACKUP_ROOT).grep(/\A\d{8}_\d{6}(?:_[a-f0-9]{8})?\z/).sort
+        retained = names.last(keep)
+        manifests = retained.to_h { |name| [name, backup_inventory(path: File.join(BACKUP_ROOT, name), admission: admission)] }
+        names[0...-keep].to_a.last(limit).reverse_each do |name|
+          path = File.join(BACKUP_ROOT, name)
+          inventory = backup_inventory(path: path, admission: admission)
+          match = manifests.find { |_other, rows| rows == inventory }
+          unless match
+            result[:retained] << name
+            next
+          end
+          result[:eligible] << name
+          next if dry_run
 
-        src = File.join(PWN_ROOT, c)
-        FileUtils.cp_r(src, dst)
-      rescue StandardError
-        next
+          canonical = File.join(BACKUP_ROOT, match.first)
+          raise IOError, 'Backup changed before pruning' unless backup_inventory(path: canonical, admission: admission) == inventory && backup_inventory(path: path, admission: admission) == inventory
+
+          FileUtils.remove_entry_secure(path)
+          raise IOError, 'Backup pruning failed' if File.exist?(path)
+
+          result[:deleted] << name
+        end
+        result
+      end
+      return work.call if dry_run
+
+      File.open(File.join(BACKUP_ROOT, '.retention.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+        raise IOError, 'Backup maintenance active' unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+        work.call
+      end
+    rescue IOError => e
+      result[:incomplete] = true
+      result[:error] = e.message
+      result
+    end
+
+    # Explicit opt-in expires historical versions, not merely duplicate bytes.
+    private_class_method def self.backup_retention_policy
+      path = File.join(BACKUP_ROOT, '.retention-policy.json')
+      return { 'keep' => 3, 'pins' => [], 'expire_history' => false } unless File.exist?(path) || File.symlink?(path)
+      raise IOError, 'Unsafe retention policy' unless File.realpath(path) == path && File.stat(path).uid == Process.uid
+
+      value = JSON.parse(File.binread(path))
+      valid = value['version'] == 1 && [true, false].include?(value['expire_history']) && value['keep'].is_a?(Integer) && value['keep'] >= 3 && value['pins'].is_a?(Array)
+      valid &&= value['pins'].all? { |name| name.is_a?(String) && name.match?(/\A\d{8}_\d{6}(?:_[a-f0-9]{8})?\z/) }
+      raise IOError, 'Invalid retention policy' unless valid
+
+      value
+    end
+
+    private_class_method def self.backup_input_names
+      (STATE_FILES.keys.map { |rel| rel.delete_suffix('/') } + %w[.schema pwn.yaml.decryptor]).uniq.reject { |rel| %w[sessions swarm].include?(rel.split('/').first) }
+    end
+
+    # Conservative literal-path protection in current evidence/continuation stores.
+    # Historical log/history/metrics copies are not operational dependencies.
+    private_class_method def self.backup_reference_pins(opts = {})
+      admission = opts[:admission]
+      pins = []
+      roots = %w[learning learning.jsonl memory.json mistakes.json policy.json policy_traj.jsonl preferences.jsonl engagements artifacts sessions swarm jobs runs open_goals open_goal.json curriculum finetune extrospection skill_review.jsonl maintenance]
+      roots.each do |name|
+        path = File.join(PWN_ROOT, name)
+        next unless File.exist?(path) || File.symlink?(path)
+
+        Find.find(path) do |file|
+          stat = File.lstat(file)
+          raise IOError, 'Unsafe current evidence entry' unless stat.file? || stat.directory?
+          next unless stat.file? && file.match?(/\.jsonl?\z/)
+          raise IOError, 'Backup work budget exhausted' if admission && !admission.call(stat.size + 1)
+
+          documents = file.end_with?('.jsonl') ? File.foreach(file).reject { |line| line.strip.empty? }.map { |line| JSON.parse(line) } : [JSON.parse(File.binread(file))]
+          documents.select! { |row| row.is_a?(Hash) && (%w[prepared interrupted].include?(row['state']) || row['pinned'] == true) } if name == 'maintenance'
+          until documents.empty?
+            value = documents.pop
+            case value
+            when Hash then documents.concat(value.values)
+            when Array then documents.concat(value)
+            when String
+              match = value.match(%r{\A(?:#{Regexp.escape(BACKUP_ROOT)}/|backup/)(\d{8}_\d{6}(?:_[a-f0-9]{8})?)(?:/|\z)})
+              pins << match[1] if match
+            end
+          end
+        end
+      end
+      pins.uniq
+    end
+
+    private_class_method def self.expire_backup_generations(opts = {})
+      require 'zlib'
+      result = { eligible: [], deleted: [], retained: [], incomplete: false, permanent_history_expiry: true }
+      return result unless File.directory?(BACKUP_ROOT)
+      raise IOError, 'Unsafe backup root' unless File.realpath(PWN_ROOT) == PWN_ROOT && File.realpath(BACKUP_ROOT) == BACKUP_ROOT && File.stat(BACKUP_ROOT).uid == Process.uid
+
+      dry_run = opts.fetch(:dry_run, true)
+      admission = opts[:admission]
+      policy = backup_retention_policy
+      keep = [Integer(opts.fetch(:keep, policy['keep'])), 3].max
+      limit = Integer(opts.fetch(:limit, 10))
+      raise ArgumentError, 'Invalid retention limit' unless limit.positive?
+
+      operation = lambda do
+        names = Dir.children(BACKUP_ROOT).grep(/\A\d{8}_\d{6}(?:_[a-f0-9]{8})?\z/).sort
+        raise IOError, 'Pinned backup missing' unless (policy['pins'] - names).empty?
+
+        if (names - (names.last(keep) + policy['pins'])).empty?
+          result[:retained] = names
+          result[:pins] = policy['pins']
+          result[:evidence_scan] = 'not_needed_no_expiry'
+          return result
+        end
+
+        pins = (policy['pins'] + backup_reference_pins(admission: admission)).uniq
+        raise IOError, 'Pinned backup missing' unless (pins - names).empty?
+
+        retained = (names.last(keep) + pins).uniq.sort
+        result[:retained] = retained
+        result[:pins] = pins
+        return result if (names - retained).empty?
+        raise IOError, 'Insufficient recovery generations' if retained.length < keep
+
+        current = backup_inventory(path: PWN_ROOT, names: backup_input_names, admission: admission)
+        inventories = retained.to_h { |name| [name, backup_inventory(path: File.join(BACKUP_ROOT, name), admission: admission)] }
+        newest = inventories.fetch(names.last)
+        raise IOError, 'Current migration input coverage missing' unless current.all? { |path, row| newest[path] && newest[path].first == row.first }
+
+        %w[pwn.yaml pwn.yaml.decryptor].each do |name|
+          raise IOError, 'Current encrypted configuration recovery missing' if current.key?(name) && newest[name] != current[name]
+        end
+        result[:coverage] = { current_paths: current.length, newest: names.last, legacy_completeness_certified: false, restore: 'copy migration-owned paths only; never overlay entire legacy trees or edit shared inodes' }
+        candidates = (names - retained).first(limit)
+        expired = candidates.to_h { |name| [name, backup_inventory(path: File.join(BACKUP_ROOT, name), admission: admission)] }
+        result[:eligible] = candidates
+        return result if dry_run
+
+        # Recheck everything before publishing the single private metadata ledger.
+        raise IOError, 'Current migration input changed' unless current == backup_inventory(path: PWN_ROOT, names: backup_input_names, admission: admission)
+        raise IOError, 'Backup references changed' unless pins == (policy['pins'] + backup_reference_pins(admission: admission)).uniq
+
+        inventories.merge(expired).each do |name, rows|
+          raise IOError, 'Backup changed before expiry' unless rows == backup_inventory(path: File.join(BACKUP_ROOT, name), admission: admission)
+        end
+        ledger = File.join(BACKUP_ROOT, '.retention-manifest.json.gz')
+        raise IOError, 'Unsafe retention manifest' if File.symlink?(ledger)
+
+        record = { version: 1, state: 'prepared', policy: policy, coverage: result[:coverage], retained: inventories, expiring: expired, deleted: [] }
+        verification_bytes = inventories.values.sum { |rows| rows.values.sum { |row| row.first == 'file' ? row[4] + 1 : 0 } }
+        reserved_bytes = (JSON.generate(record).bytesize * 2) + verification_bytes
+        raise IOError, 'Backup commit budget exhausted' if admission && !admission.call(reserved_bytes)
+
+        publish_backup_retention(path: ledger, record: record)
+        candidates.each do |name|
+          FileUtils.remove_entry_secure(File.join(BACKUP_ROOT, name))
+          raise IOError, 'Backup expiry failed' if File.exist?(File.join(BACKUP_ROOT, name))
+
+          result[:deleted] << name
+          record[:deleted] << name
+        end
+        inventories.each do |name, rows|
+          raise IOError, 'Retained backup changed' unless rows == backup_inventory(path: File.join(BACKUP_ROOT, name))
+        end
+        record[:state] = 'committed'
+        publish_backup_retention(path: ledger, record: record)
+        result
+      end
+      return operation.call if dry_run
+
+      File.open(File.join(BACKUP_ROOT, '.retention.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+        raise IOError, 'Backup maintenance active' unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+        operation.call
+      end
+    rescue IOError => e
+      result[:incomplete] = true
+      result[:error] = e.message
+      result
+    end
+
+    private_class_method def self.publish_backup_retention(opts = {})
+      path = opts[:path]
+      temporary = "#{path}.#{SecureRandom.hex(8)}"
+      File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+        writer = Zlib::GzipWriter.new(file)
+        writer.write(JSON.generate(opts[:record]))
+        writer.finish
+        file.flush
+        file.fsync
+      end
+      File.rename(temporary, path)
+      File.open(BACKUP_ROOT, File::RDONLY, &:fsync)
+    end
+
+    private_class_method def self.backup_inventory(opts = {})
+      path = opts[:path]
+      admission = opts[:admission]
+      names = opts[:names]
+      raise IOError, 'Unsafe backup directory' unless File.realpath(path) == path && File.directory?(path)
+
+      rows = {}
+      Find.find(path) do |file|
+        next if file == path
+
+        rel = file.delete_prefix("#{path}/")
+        Find.prune if names && names.none? { |name| rel == name || rel.start_with?("#{name}/") || name.start_with?("#{rel}/") }
+        stat = File.lstat(file)
+        raise IOError, 'Unsafe backup entry' unless (stat.file? || stat.directory?) && stat.uid == Process.uid
+        next if names && names.none? { |name| rel == name || rel.start_with?("#{name}/") }
+        raise IOError, 'Backup work budget exhausted' if admission && !admission.call(stat.file? ? stat.size + 1 : 0)
+
+        row = [stat.ftype, stat.mode, stat.uid, stat.gid]
+        if stat.file?
+          row += [stat.size, Digest::SHA256.file(file).hexdigest]
+          after = File.lstat(file)
+          raise IOError, 'Backup changed while hashing' unless [stat.ino, stat.size, stat.mtime, stat.ctime] == [after.ino, after.size, after.mtime, after.ctime]
+        end
+        rows[rel] = row
+      end
+      rows
+    end
+
+    private_class_method def self.backup!
+      FileUtils.mkdir_p(BACKUP_ROOT, mode: 0o700)
+      raise IOError, 'Unsafe backup root' unless File.realpath(BACKUP_ROOT) == BACKUP_ROOT
+
+      File.open(File.join(BACKUP_ROOT, '.retention.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        ts = "#{Time.now.utc.strftime('%Y%m%d_%H%M%S')}_#{SecureRandom.hex(4)}"
+        dst = File.join(BACKUP_ROOT, ts)
+        partial = File.join(BACKUP_ROOT, ".partial-#{ts}")
+        Dir.mkdir(partial, 0o700)
+        # Only state owned by the migration registry. Logs, caches, artifacts,
+        # jobs and prior maintenance archives are not schema migration inputs.
+        names = backup_input_names
+        inventory = backup_inventory(path: PWN_ROOT, names: names)
+        names.each do |name|
+          src = File.join(PWN_ROOT, name)
+          next unless File.exist?(src)
+
+          target = File.join(partial, name)
+          FileUtils.mkdir_p(File.dirname(target), mode: 0o700)
+          FileUtils.cp_r(src, target, preserve: true)
+        end
+        raise IOError, 'Migration input changed during backup' unless inventory == backup_inventory(path: PWN_ROOT, names: names)
+        raise IOError, 'Backup verification failed' unless inventory == backup_inventory(path: partial, names: names)
+
+        manifest = JSON.generate(version: 1, complete: true, scope: names.sort, files: inventory)
+        File.open(File.join(partial, '.snapshot-manifest.json'), File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+          file.write(manifest)
+          file.flush
+          file.fsync
+        end
+        File.rename(partial, dst)
+        File.open(BACKUP_ROOT, File::RDONLY, &:fsync)
+        dst
       end
-      dst
     end
 
     private_class_method def self.stamp!
@@ -773,6 +1041,15 @@ module PWN
           iv: 'optional - iv value consumed by #backfill_vault'
         )
 
+        # Prune duplicate trees, or explicitly expire historical generations.
+        #{self}.prune_backups(
+          expire_history: 'optional - permanently expire old unpinned history after current recovery coverage verification; default reads backup/.retention-policy.json',
+          dry_run: 'optional - preview without writes, default true',
+          keep: 'optional - recent recovery points to retain, minimum three',
+          limit: 'optional - maximum older snapshots examined per invocation, default ten',
+          admission: 'optional - callable byte/work budget admission guard'
+        )
+
         # Run env template and return its result
         #{self}.env_template
 

data/lib/pwn/plugins/binary_parser.rb

@@ -101,16 +101,17 @@ module PWN
         sha = Digest::SHA256.file(path).hexdigest
         sid = (opts[:session_id] || 'triage').to_s
         cache_dir = File.join(Dir.home, '.pwn', 'cache', 'triage')
-        FileUtils.mkdir_p(cache_dir)
         cache = File.join(cache_dir, "#{sha}.json")
-        if File.file?(cache)
-          cached = JSON.parse(File.read(cache), symbolize_names: true)
+        require File.expand_path('../../../etc/default_cron/session_cleanup', __dir__)
+        cached_bytes = PWN::SessionCleanup.cache(path: cache)
+        if cached_bytes
+          cached = JSON.parse(cached_bytes, symbolize_names: true)
           spilled = persist_triage(body: cached, session_id: sid)
           return cached.merge(cached: true, handle: spilled[:handle], artifact: spilled)
         end
 
         body = inspect_binary(opts.merge(path: path, sha256: sha))
-        File.write(cache, JSON.pretty_generate(body))
+        PWN::SessionCleanup.cache(path: cache, bytes: JSON.pretty_generate(body))
         facts_dir = File.join(Dir.home, '.pwn', 'engagements', 'default', 'binaries', sha)
         FileUtils.mkdir_p(facts_dir)
         File.write(File.join(facts_dir, 'facts.json'), JSON.pretty_generate(body))

data/lib/pwn/plugins/ghidra.rb

@@ -37,13 +37,14 @@ module PWN
 
         sha = Digest::SHA256.file(path).hexdigest if File.file?(path)
         cache = File.join(Dir.home, '.pwn', 'cache', 'decompile', "#{sha}.json") if sha
-        return JSON.parse(File.read(cache), symbolize_names: true).merge(cached: true) if cache && File.file?(cache)
+        require File.expand_path('../../../etc/default_cron/session_cleanup', __dir__)
+        cached = PWN::SessionCleanup.cache(path: cache) if cache
+        return JSON.parse(cached, symbolize_names: true).merge(cached: true) if cached
 
         row = analyze(opts)
         fn = opts[:function].to_s
         row[:function] = fn unless fn.empty?
-        FileUtils.mkdir_p(File.dirname(cache)) if cache
-        File.write(cache, JSON.generate(row)) if cache
+        PWN::SessionCleanup.cache(path: cache, bytes: JSON.generate(row)) if cache
         row
       end
 

data/lib/pwn/plugins/log.rb

@@ -60,8 +60,9 @@ module PWN
           log_file_path = "/tmp/pwn-ai-#{session}.json" if level == :learning
           log_file = File.open(log_file_path, 'w')
         else
-          log_file_path = '/tmp/pwn.log'
-          log_file = File.open(log_file_path, 'a')
+          require 'stringio'
+          log_file_path = File.join(Dir.home, '.pwn', 'logs', 'pwn.log')
+          log_file = StringIO.new
         end
 
         # Leave 10 "old" log files where
@@ -124,6 +125,10 @@ module PWN
         end
 
         logger.add(logger.level, PWN::Redaction.redact(value: log_event), PWN::Redaction.redact(value: which_self))
+        unless level == :learning
+          require File.expand_path('../../../etc/default_cron/session_cleanup', __dir__)
+          PWN::SessionCleanup.append_log(path: log_file_path, bytes: log_file.string)
+        end
         logger.close
       rescue Interrupt
         note_interrupt!(where: 'CTRL+C', which_self: self) if debug_enabled?
@@ -424,9 +429,18 @@ module PWN
           unless @debug_file.nil? || @debug_file.closed?
             @debug_file.puts(PWN::Redaction.token(kind: 'stream', value: @stderr_redaction_buffer)) unless @stderr_redaction_buffer.to_s.empty?
             @debug_file.close
+            @debug_lease&.close
+            @debug_lease = nil
+            if @debug_path.to_s.start_with?("#{File.join(Dir.home, '.pwn', 'logs')}/")
+              require File.expand_path('../../../etc/default_cron/session_cleanup', __dir__)
+              PWN::SessionCleanup.register_disposable(path: @debug_path, category: 'logs')
+            end
           end
         rescue StandardError
           nil
+        ensure
+          @debug_lease&.close
+          @debug_lease = nil
         end
         @debug_file = nil
         @stderr_redaction_buffer = ''
@@ -439,6 +453,8 @@ module PWN
 
         close_debug_file!
         FileUtils.mkdir_p(File.dirname(path))
+        @debug_lease = File.open("#{path}.lease", File::RDWR | File::CREAT | File::NOFOLLOW, 0o600)
+        @debug_lease.flock(File::LOCK_EX)
         io = File.open(path, 'a', 0o600)
         io.chmod(0o600)
         io.sync = true

data/lib/pwn/plugins/repl/ai.rb

@@ -129,7 +129,9 @@ module PWN
               case cmd
               when 'list', nil
                 output.puts('Session dependencies: referenced by these files; text mentions are not links.')
-                PWN::Plugins::REPL.pwn_ai_print_result(value: PWN::Sessions.list, output: output)
+                PWN::Plugins::REPL.pwn_ai_print_result(value: PWN::Sessions.catalog(offset: args[1], limit: args[2] || 25, current_session_id: pry_instance.config.pwn_ai_session_id), output: output)
+              when 'cleanup'
+                PWN::Plugins::REPL.pwn_ai_run_sessions(args: args)
               when 'resume'
                 sid = args[1]
                 hist = PWN::Sessions.to_response_history(session_id: sid)
@@ -248,7 +250,7 @@ module PWN
           end
         end
         PWN_AI_SLASH_COMMANDS = %w[
-          /back /cron /debug /delegate /help /learning /memory /mcp /model /sessions /skills /steer /swarm /system-role /trace /vault
+          /back /cron /debug /delegate /help /learning /maintenance /memory /mcp /model /sessions /skills /steer /swarm /system-role /trace /vault
         ].freeze
 
         PWN_AI_SLASH_SUBCOMMANDS = {
@@ -262,7 +264,8 @@ module PWN
           '/mcp' => %w[list backends use current connect disconnect ping tools call status help],
           '/model' => %w[list],
           '/swarm' => %w[mission agents status create use spawn retire dm debate broadcast tail steer pause resume cancel help],
-          '/sessions' => %w[list resume delete stats],
+          '/sessions' => %w[list resume delete stats cleanup],
+          '/maintenance' => %w[status run dry-run],
 
           '/skills' => %w[list recall],
           '/learning' => %w[list requeue]
@@ -578,6 +581,16 @@ module PWN
               end
             when '/cron'
               pwn_ai_run_cron(args: args)
+            when '/maintenance'
+              require File.expand_path('../../../../etc/default_cron/session_cleanup', __dir__)
+              raise ArgumentError, 'usage: /maintenance [status|run|dry-run]' unless args.empty? || (args.length == 1 && %w[status run dry-run].include?(args.first))
+
+              result = if args.empty? || args.first == 'status'
+                         PWN::SessionCleanup.status
+                       else
+                         PWN::SessionCleanup.maintain(dry_run: args.first == 'dry-run', current_session_id: pi&.config&.pwn_ai_session_id)
+                       end
+              pwn_ai_print_result(value: result)
             when '/sessions'
               identifier = request.sub(%r{\A/sessions[[:space:]]+resume(?:[[:space:]]+|$)}, '') if args.first == 'resume'
               pwn_ai_run_sessions(args: args, identifier: identifier, pry: pi)
@@ -599,6 +612,8 @@ module PWN
             end
             true
           rescue StandardError => e
+            raise if opts[:raise_errors]
+
             warn "[pwn-ai] #{cmd}: #{e.class}: #{e.message}"
             true
           end
@@ -1038,7 +1053,13 @@ module PWN
             case sub
             when 'list'
               puts('Session dependencies: referenced by these files; text mentions are not links.')
-              pwn_ai_print_result(value: PWN::Sessions.list)
+              pwn_ai_print_result(value: PWN::Sessions.catalog(offset: args[1], limit: args[2] || 25, current_session_id: opts[:pry]&.config&.pwn_ai_session_id))
+            when 'cleanup'
+              raise ArgumentError, 'usage: /sessions cleanup [--dry-run]' unless args.drop(1).empty? || args.drop(1) == ['--dry-run']
+
+              require File.expand_path('../../../../etc/default_cron/session_cleanup', __dir__)
+              result = PWN::SessionCleanup.maintain(dry_run: args.include?('--dry-run'), current_session_id: opts[:pry]&.config&.pwn_ai_session_id)
+              pwn_ai_print_result(value: PWN::SessionCleanup.summary(result))
             when 'resume'
               sid = PWN::Sessions.resolve(identifier: opts[:identifier] || args.drop(1).join(' '))
               lease = PWN::Sessions.activate(session_id: sid)