pwn 0.5.783 → 0.5.784

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

@@ -3572,16 +3572,15 @@ module PWN
             [true, log]
           when :festival
             # Use plugin if text file available
-            tmp = File.join(Dir.tmpdir, "pwn_tts_#{Process.pid}.txt")
-            File.write(tmp, text)
+            require_relative '../../../../etc/default_cron/session_cleanup' unless defined?(PWN::SessionCleanup)
             begin
-              require 'pwn/plugins/voice' unless defined?(PWN::Plugins::Voice)
-              PWN::Plugins::Voice.text_to_speech(text_path: tmp)
-              [true, 'festival via PWN::Plugins::Voice']
+              PWN::SessionCleanup.temporary(bytes: text) do |tmp|
+                require 'pwn/plugins/voice' unless defined?(PWN::Plugins::Voice)
+                PWN::Plugins::Voice.text_to_speech(text_path: tmp)
+                [true, 'festival via PWN::Plugins::Voice']
+              end
             rescue StandardError => e
               [false, "#{e.class}: #{e.message}"]
-            ensure
-              FileUtils.rm_f(tmp)
             end
           else
             [false, "unsupported TTS engine: #{engine}"]

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

@@ -101,7 +101,14 @@ module PWN
         # Plan by default; no provider calls, vault reads, transcript logging or deletion.
         public_class_method def self.migrate_evidence(opts = {})
           dry = opts[:dry_run] != false
-          lock = learning_lock unless dry
+          max_sessions = opts[:max_sessions]
+          stop = opts[:stop]
+          raise ArgumentError, 'max_sessions must be positive' if max_sessions && (!max_sessions.is_a?(Integer) || max_sessions <= 0)
+
+          leases = []
+          lock = learning_lock(nonblocking: opts[:nonblocking]) unless dry
+          return { dry_run: false, deferred: 'learning_writer_active', migrated_rows: 0 } if lock == :busy
+
           original = File.exist?(LEARNING_FILE) ? evidence_read(path: LEARNING_FILE) : ''
           malformed = 0
           rows = original.lines.filter_map do |line|
@@ -116,9 +123,13 @@ module PWN
 
           report = { dry_run: dry, rows: rows.length, malformed_rows: malformed, session_refs: 0, migratable_sessions: 0,
                      missing_sessions: 0, malformed_sessions: 0, malformed_refs: 0, verified_rows: 0,
-                     estimated_source_bytes: 0, migrated_rows: 0 }
+                     estimated_source_bytes: 0, migrated_rows: 0, deferred_active_sessions: 0 }
           snapshots = {}
           rows.each do |row|
+            if stop&.call || (max_sessions && report[:migratable_sessions] >= max_sessions)
+              report[:bounded] = true
+              break
+            end
             sid = row[:session_id]
             next if sid.nil? || sid == ''
 
@@ -140,6 +151,22 @@ module PWN
               next
             end
             begin
+              # Keep the permanent exclusive lease through index publication;
+              # a point-in-time active? check alone races subsequent activation.
+              if dry
+                if PWN::Sessions.active?(session_id: sid)
+                  report[:deferred_active_sessions] += 1
+                  next
+                end
+              else
+                lease = File.open(PWN::Sessions.support_path(kind: :lease, session_id: sid), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) # rubocop:disable Style/FileOpen -- released together after commit
+                leases << lease
+                unless lease.flock(File::LOCK_EX | File::LOCK_NB)
+                  lease.close
+                  report[:deferred_active_sessions] += 1
+                  next
+                end
+              end
               body = evidence_read(path: path)
               transcript = body.lines.map { |line| JSON.parse(line, symbolize_names: true) }
               raise IOError, 'Malformed source transcript' if transcript.empty? || !transcript.all?(Hash)
@@ -179,7 +206,8 @@ module PWN
 
           evidence_commit(rows: rows, original: original, snapshots: snapshots, report: report)
         ensure
-          learning_unlock(lock: lock) if lock
+          leases&.each { |lease| lease.close unless lease.closed? }
+          learning_unlock(lock: lock) if lock && lock != :busy
         end
 
         private_class_method def self.evidence_read(opts = {})
@@ -253,6 +281,8 @@ module PWN
 
             raise IOError, 'Restore source sessions before rollback' unless evidence_complete?(row: row) && File.file?(File.join(PWN::Sessions::SESSIONS_DIR, "#{sid}.jsonl"))
           end
+          return { dry_run: true, restored: false } if opts[:dry_run] == true
+
           evidence_write(path: LEARNING_FILE, body: backup)
           evidence_write(path: path, body: JSON.generate(record.merge(state: 'rolled_back')))
           { restored: true }
@@ -332,7 +362,7 @@ module PWN
         end
 
         # Reentrant across note_outcome -> pruning; flock serializes cooperating processes.
-        private_class_method def self.learning_lock
+        private_class_method def self.learning_lock(opts = {})
           key = :pwn_learning_write_lock
           owner = Thread.current[key]
           return nil if owner.is_a?(Hash) && owner[:pid] == Process.pid && owner[:thread] == Thread.current && !owner[:file].closed?
@@ -344,7 +374,10 @@ module PWN
 
           # Ownership transfers to the caller's ensure/learning_unlock.
           file = File.open(path, File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) # rubocop:disable Style/FileOpen
-          file.flock(File::LOCK_EX)
+          unless file.flock(File::LOCK_EX | (opts[:nonblocking] ? File::LOCK_NB : 0))
+            file.close
+            return :busy
+          end
           Thread.current[key] = { pid: Process.pid, thread: Thread.current, file: file }
           file
         end
@@ -2388,10 +2421,18 @@ module PWN
         public_class_method def self.help
           puts "
             # Plan a full-snapshot evidence migration, or explicitly apply it.
-            #{self}.migrate_evidence(dry_run: 'optional - Boolean; defaults true, false writes evidence and references')
+            #{self}.migrate_evidence(
+              dry_run: 'optional - Boolean; defaults true, false writes evidence and references',
+              max_sessions: 'optional - Positive maximum source snapshots per transaction',
+              nonblocking: 'optional - Boolean; defer instead of waiting for a cooperating learning writer',
+              stop: 'optional - Cooperative stop callable checked between source snapshots'
+            )
 
             # Restore an unchanged learning ledger before any source-session cleanup.
-            #{self}.rollback_evidence(migration: 'required - SHA-256 migration ID from the ledger filename')
+            #{self}.rollback_evidence(
+              migration: 'required - SHA-256 migration ID from the ledger filename',
+              dry_run: 'optional - validate rollback without replacing learning bytes; defaults to false'
+            )
 
             # Persist derived PRM rewards without rewriting immutable supporting content.
             #{self}.annotate_evidence(

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

@@ -4,6 +4,7 @@ require 'json'
 require 'fileutils'
 require 'time'
 require 'digest'
+require_relative '../../memory'
 
 module PWN
   module AI
@@ -696,6 +697,8 @@ module PWN
 
         public_class_method def self.lean!(opts = {})
           dry = opts[:dry_run] ? true : false
+          return PWN::Memory.transaction(path: TRAJECTORY_FILE) { lean!(opts) } unless dry || PWN::Memory.transaction_owned?(path: TRAJECTORY_FILE)
+
           return { skipped: true } unless File.exist?(TRAJECTORY_FILE)
 
           rows = File.readlines(TRAJECTORY_FILE)
@@ -1385,6 +1388,8 @@ module PWN
         end
 
         private_class_method def self.persist_episode!(opts = {})
+          return PWN::Memory.transaction(path: TRAJECTORY_FILE) { persist_episode!(opts) } unless PWN::Memory.transaction_owned?(path: TRAJECTORY_FILE)
+
           ep = opts[:episode]
           return unless ep.is_a?(Hash)
 

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

@@ -120,12 +120,19 @@ module PWN
         public_class_method def self.retire(opts = {})
           name = opts[:name].to_s
           sid = opts[:swarm_id].to_s
+          continuation = nil
+          if opts[:continuation]
+            raise ArgumentError, 'Continuation retirement requires local and swarm_id' unless opts[:local] == true && !sid.empty?
+
+            require File.expand_path('../../../../etc/default_cron/session_cleanup', __dir__)
+            continuation = PWN::SessionCleanup.retire_continuation(root: SWARM_ROOT, swarm_id: sid, name: name)
+          end
           if opts[:local] == true && !sid.empty?
             path = File.join(SWARM_ROOT, sid, 'agents.yml')
             all = load_personas_file(path: path)
             gone = all.delete(name.to_sym)
             File.write(path, YAML.dump(deep_stringify(hash: all))) if gone
-            return { name: name, removed: !gone.nil?, scope: :swarm }
+            return { name: name, removed: !gone.nil?, scope: :swarm, continuation: continuation }
           end
 
           all  = personas
@@ -414,21 +421,28 @@ module PWN
           sid  = opts[:swarm_id].to_s
           name = opts[:name].to_s
           map_path = File.join(SWARM_ROOT, sid, 'personas.json')
-          map = File.exist?(map_path) ? JSON.parse(File.read(map_path)) : {}
-          if map[name]
-            opts[:leases] << PWN::Sessions.activate(session_id: map[name]) if opts[:leases]
-            return map[name]
-          end
+          require File.expand_path('../../../../etc/default_cron/session_cleanup', __dir__)
+          PWN::SessionCleanup.with_continuation_lock(root: File.dirname(SWARM_ROOT)) do
+            raise IOError, 'Unsafe continuation map' if File.symlink?(map_path)
 
-          sess = PWN::Sessions.create(
-            title: "swarm:#{sid} persona:#{name}",
-            source: 'pwn-ai-swarm',
-            active: !opts[:leases].nil?
-          )
-          opts[:leases] << sess[:lease] if opts[:leases]
-          map[name] = sess[:id]
-          File.write(map_path, JSON.pretty_generate(map))
-          sess[:id]
+            map = File.exist?(map_path) ? JSON.parse(File.read(map_path)) : {}
+            raise IOError, 'Unknown continuation map' unless map.is_a?(Hash)
+
+            if map[name]
+              opts[:leases] << PWN::Sessions.activate(session_id: map[name]) if opts[:leases]
+              next map[name]
+            end
+
+            sess = PWN::Sessions.create(
+              title: "swarm:#{sid} persona:#{name}",
+              source: 'pwn-ai-swarm',
+              active: !opts[:leases].nil?
+            )
+            opts[:leases] << sess[:lease] if opts[:leases]
+            map[name] = sess[:id]
+            PWN::SessionCleanup.publish(map_path, JSON.pretty_generate(map))
+            sess[:id]
+          end
         end
 
         private_class_method def self.build_persona_prompt(opts = {})
@@ -759,7 +773,8 @@ module PWN
             #{self}.retire(
               name: 'required - persona name',
               swarm_id: 'optional - swarm directory when local is true',
-              local: 'optional - true retires only that swarm registry'
+              local: 'optional - true retires only that swarm registry',
+              continuation: 'optional - explicitly retire the inactive saved conversation association; requires local and swarm_id'
             )
 
             # Swarm lifecycle & bus

data/lib/pwn/ai/router.rb

@@ -59,7 +59,7 @@ module PWN
 
         extractive(text: text)
       rescue StandardError
-        return '' if session
+        raise if session
 
         extractive(text: text)
       end
@@ -163,14 +163,57 @@ module PWN
         return nil unless mod.respond_to?(:chat)
 
         resp = mod.chat(request: opts[:request], model: endpoint[:model], spinner: false, quiet: true, timeout: 8)
-        text = resp.is_a?(Hash) ? (resp[:content] || resp['content'] || resp.dig(:choices, -1, :content)).to_s : resp.to_s
+        text = response_text(response: resp)
         text.strip.empty? ? nil : text
       rescue StandardError
+        raise if opts[:session]
+
         nil
       ensure
         Thread.current[:pwn_session_title] = previous_title_worker
       end
 
+      # Only decode documented assistant-content locations, never container inspect
+      # strings, reasoning blocks, tool arguments or echoed user messages.
+      private_class_method def self.response_text(opts = {})
+        response = opts[:response]
+        return response if response.is_a?(String)
+        return '' unless response.is_a?(Hash)
+
+        row = response.transform_keys(&:to_s)
+        return JSON.generate(row) if row['title'].is_a?(String) && row['summary'].is_a?(String)
+        return content_text(content: row['content']) if row.key?('content')
+
+        choice = Array(row['choices']).last
+        if choice.is_a?(Hash)
+          choice = choice.transform_keys(&:to_s)
+          message = choice['message'] || choice
+          if message.is_a?(Hash)
+            message = message.transform_keys(&:to_s)
+            return '' if message['role'] && message['role'] != 'assistant'
+
+            return content_text(content: message['content'])
+          end
+        end
+        message = row['message']
+        return content_text(content: message[:content] || message['content']) if message.is_a?(Hash)
+
+        ''
+      end
+
+      private_class_method def self.content_text(opts = {})
+        content = opts[:content]
+        return content if content.is_a?(String)
+        return '' unless content.is_a?(Array)
+
+        content.filter_map do |block|
+          next unless block.is_a?(Hash)
+
+          block = block.transform_keys(&:to_s)
+          block['text'] if %w[text output_text].include?(block['type']) && block['text'].is_a?(String)
+        end.join
+      end
+
       private_class_method def self.active_session_endpoint
         engine = env_dig(keys: %i[ai active]).to_s.downcase
         { engine: engine, model: env_dig(keys: [:ai, engine.to_sym, :model]) }

data/lib/pwn/cron.rb

@@ -48,6 +48,8 @@ module PWN
     #     enabled: true
     #   )
     public_class_method def self.create(opts = {})
+      return with_registry_lock { create(opts) } unless registry_owned?
+
       jobs = load_jobs
       id = SecureRandom.hex(6)
       name = opts[:name] || "job-#{id}"
@@ -69,7 +71,7 @@ module PWN
 
       # Optionally install a crontab entry (user must have permission)
       install_crontab_entry(job: job) if opts[:install_crontab]
-      sync_one_job(job: job) if cron_enabled? && !opts[:install_crontab]
+      sync_one_job(job: job) if cron_enabled? && !opts[:install_crontab] && opts.fetch(:sync_native, true)
 
       job
     end
@@ -83,6 +85,7 @@ module PWN
       jobs = load_jobs
       job = jobs[id] || jobs.values.find { |j| j[:name] == id || j[:id] == id }
       raise "Job #{id} not found" unless job
+      return { skipped: true, reason: :housekeeping_internal_only, status: 'skipped' } if native_execution? && housekeeping_job?(job: job)
 
       start = Time.now
       result = nil
@@ -133,20 +136,28 @@ module PWN
 
       job[:last_run] = Time.now.utc.iso8601
       job[:last_status] = status
-      jobs[job[:id]] = job
-      save_jobs(jobs: jobs)
+      with_registry_lock do
+        current = load_jobs
+        if current.key?(job[:id])
+          current[job[:id]][:last_run] = job[:last_run]
+          current[job[:id]][:last_status] = status
+          save_jobs(jobs: current)
+        end
+      end
 
       { job: job, result: result, duration: Time.now - start, status: status }
     end
 
     # Supported Method Parameters::
-    #   PWN::Cron.remove(id:)
-    public_class_method def self.remove(opts = {}) # rubocop:disable Naming/PredicateMethod
+    #   PWN::Cron.remove(id:, sync_native: false)
+    public_class_method def self.remove(opts = {})
+      return with_registry_lock { remove(opts) } unless registry_owned?
+
       id = opts[:id].to_s
       jobs = load_jobs
       gone = jobs.delete(id)
       save_jobs(jobs: jobs)
-      remove_native_job(job: gone) if gone
+      remove_native_job(job: gone) if gone && opts.fetch(:sync_native, true)
       true
     end
 
@@ -181,16 +192,48 @@ module PWN
       # and break jobs[id] / jobs.delete(id) / toggle lookups).
       raw.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
     rescue StandardError => e
-      warn("[PWN::Cron] load_jobs failed: #{e.class}: #{e.message}")
-      {}
+      raise IOError, "Cron registry unreadable (#{e.class}); refusing an empty replacement"
+    end
+
+    # A permanent inode coordinates registry writers, never job execution.
+    private_class_method def self.with_registry_lock
+      return yield if registry_owned?
+
+      owner = Thread.current[:pwn_cron_registry_owner]
+      File.open(File.join(cron_dir, '.jobs.write.lock'), File::RDWR | File::CREAT | File::NOFOLLOW, 0o600) do |file|
+        file.flock(File::LOCK_EX)
+        begin
+          Thread.current[:pwn_cron_registry_owner] = [Process.pid, Thread.current, jobs_file]
+          yield
+        ensure
+          Thread.current[:pwn_cron_registry_owner] = owner
+        end
+      end
+    end
+
+    private_class_method def self.registry_owned?
+      Thread.current[:pwn_cron_registry_owner] == [Process.pid, Thread.current, jobs_file]
     end
 
     private_class_method def self.save_jobs(opts = {})
       jobs = opts[:jobs] ||= {}
-      File.write(jobs_file, YAML.dump(jobs))
+      temporary = "#{jobs_file}.#{SecureRandom.hex(8)}.tmp"
+      begin
+        File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+          file.write(YAML.dump(jobs))
+          file.flush
+          file.fsync
+        end
+        File.rename(temporary, jobs_file)
+        File.open(cron_dir, File::RDONLY, &:fsync)
+      ensure
+        FileUtils.rm_f(temporary)
+      end
     end
 
     private_class_method def self.toggle(opts = {})
+      return with_registry_lock { toggle(opts) } unless registry_owned?
+
       id = opts[:id].to_s
       enabled = opts[:enabled]
       jobs = load_jobs
@@ -202,9 +245,29 @@ module PWN
       jobs[id]
     end
 
+    private_class_method def self.native_execution?
+      return true if ENV['PWN_CRON_NATIVE'] == '1'
+
+      # An interactive terminal may inherit INVOCATION_ID; only PWN scheduler
+      # cgroups identify legacy units that predate the explicit marker.
+      File.read('/proc/self/cgroup').match?(%r{/pwn-cron-(?:worker|j[^/]+)\.service(?:/|$)})
+    rescue Errno::ENOENT, Errno::EACCES
+      false
+    end
+
+    # Housekeeping is owned exclusively by the portable worker/manual commands.
+    private_class_method def self.housekeeping_job?(opts = {})
+      job = opts[:job]
+      return false unless job.is_a?(Hash)
+
+      %w[session_cleanup learning_consolidate_nightly pwn_stores_lean_nightly].include?(job[:name].to_s) ||
+        [job[:ruby], job[:script]].any? { |payload| payload.to_s.match?(/SessionCleanup|session_cleanup\.rb/) }
+    end
+
     private_class_method def self.sync_one_job(opts = {})
       job = opts[:job]
       return unless job.is_a?(Hash)
+      return if housekeeping_job?(job: job)
 
       if job[:enabled] && cron_enabled?
         install_native_job(job: job)
@@ -218,15 +281,11 @@ module PWN
 
     # Supported Method Parameters::
     #   PWN::Cron.install_defaults
-    # Idempotently seed the RL feedback-loop cron jobs so a fresh install
-    # closes the loop by default (S1 practice + P3 offline_judge + W2 train dry-run + M1 consolidate).
-    # Re-running is a no-op if jobs with these names already exist.
-    # These are seeded to jobs.yml only — pass install_crontab: true to
-    # PWN::Cron.create yourself if you also want a system crontab entry.
-    # Hygiene jobs are enabled. Curriculum self-play / judge / LoRA are
-    # seeded disabled: practice runs Loop.run (real tools) overnight;
-    # offline_judge spends API tokens; train needs a GPU trainer.
-    DEFAULT_JOBS = [
+    # Fresh installs seed one internal housekeeping coordinator. Existing
+    # schedules are preserved, not automatically merged or re-enabled.
+    # Curriculum templates below require explicit create; installation and
+    # migration never seed them, including after operator deletion.
+    CURRICULUM_JOBS = [
       {
         name: 'curriculum_practice_nightly',
         schedule: '0 3 * * *',
@@ -245,29 +304,24 @@ module PWN
         ruby: 'PWN::AI::Agent::Curriculum.offline_judge(since_hours: 24) if defined?(PWN::AI::Agent::Curriculum)',
         aliases: %w[offline_judge_nightly],
         enabled: false
-      },
-      {
-        name: 'learning_consolidate_nightly',
-        schedule: '0 5 * * *',
-        ruby: 'PWN::AI::Agent::Learning.consolidate if defined?(PWN::AI::Agent::Learning)',
-        enabled: true
-      },
+      }
+    ].freeze
+
+    DEFAULT_JOBS = [
       {
         name: 'session_cleanup',
         schedule: '45 3 * * *',
-        ruby: "require File.join(PWN::Cron.cron_dir, 'session_cleanup.rb'); PWN::SessionCleanup.maintain(dry_run: false)",
-        enabled: true
-      },
-      {
-        name: 'pwn_stores_lean_nightly',
-        schedule: '15 5 * * *',
-        ruby: 'PWN::AI::Agent::Learning.gc_stores! if defined?(PWN::AI::Agent::Learning)',
+        ruby: "require File.join(PWN::Cron.cron_dir, 'session_cleanup.rb'); PWN::SessionCleanup.coordinate(dry_run: false)",
         enabled: true
       }
     ].freeze
 
     public_class_method def self.install_defaults
+      return with_registry_lock { install_defaults } unless registry_owned?
+
       install_default_payloads
+      require File.expand_path('../../etc/default_cron/session_cleanup', __dir__)
+      PWN::SessionCleanup.install(root: File.dirname(cron_dir))
       jobs = load_jobs
       names = jobs.values.map { |j| j[:name].to_s }
       seeded = []
@@ -282,21 +336,13 @@ module PWN
           schedule: spec[:schedule],
           ruby: default_payload(spec: spec),
           delivery: 'log',
+          sync_native: false,
           enabled: spec.fetch(:enabled, true)
         )
         names << spec[:name].to_s
       end
 
-      # P13 - disable the legacy alias when both occupy the 30 3 * * * slot.
-      if names.include?('curriculum_offline_judge') && names.include?('offline_judge_nightly')
-        begin
-          dup = jobs.values.find { |j| j[:name].to_s == 'offline_judge_nightly' }
-          disable(id: dup[:id]) if dup && dup[:enabled]
-        rescue StandardError
-          nil
-        end
-      end
-
+      PWN::SessionCleanup.request_background(root: File.dirname(cron_dir))
       seeded
     rescue StandardError => e
       warn("[PWN::Cron] install_defaults failed: #{e.class}: #{e.message}")
@@ -327,7 +373,9 @@ module PWN
 
       slot = Time.at(((Time.now.to_i / 60) + 1) * 60)
       slot += 60 until slot.hour == 3 && slot.min == 45
-      "if Time.now.to_i < #{slot.to_i}; { deferred: true, deleted: 0 }; else; #{spec[:ruby]}; end"
+      payload = spec[:ruby]
+      payload = payload.sub('SessionCleanup.coordinate(', 'SessionCleanup.maintain(') if load_jobs.values.any? { |job| %w[learning_consolidate_nightly pwn_stores_lean_nightly].include?(job[:name]) }
+      "if Time.now.to_i < #{slot.to_i}; { deferred: true, deleted: 0 }; else; #{payload}; end"
     end
 
     # ------------------------------------------------------------------
@@ -410,6 +458,7 @@ module PWN
       load_jobs.each_with_object({}) do |(id, job), acc|
         next unless job.is_a?(Hash)
         next unless job[:enabled]
+        next if native_execution? && housekeeping_job?(job: job)
         next unless due?(schedule: job[:schedule], last_run: job[:last_run], now: now)
 
         acc[id] = job
@@ -533,7 +582,16 @@ module PWN
 
     # Single tick used by the loop AND by tests (no sleep).
     public_class_method def self.tick(opts = {})
-      run_due(now: opts[:now] || Time.now)
+      results = run_due(now: opts[:now] || Time.now)
+      return results if native_execution?
+
+      require File.expand_path('../../etc/default_cron/session_cleanup', __dir__)
+      background = PWN::SessionCleanup.background_request(root: File.dirname(cron_dir)) do
+        job = load_jobs.values.find { |entry| entry[:name] == 'session_cleanup' && entry[:enabled] }
+        results.find { |entry| entry[:id] == job[:id] } || run(id: job[:id]).merge(id: job[:id]) if job
+      end
+      results << background if background && results.none? { |entry| entry[:id] == background[:id] }
+      results
     end
 
     # Blocking poll loop. `once: true` runs a single tick then returns
@@ -1064,6 +1122,7 @@ module PWN
 
     public_class_method def self.install_native_job(opts = {})
       job = opts[:job]
+      return { skipped: true, reason: :housekeeping_internal_only } if housekeeping_job?(job: job)
       return nil unless job.is_a?(Hash) && job[:id]
 
       backend = (opts[:backend] || scheduler_backend).to_sym
@@ -1080,6 +1139,8 @@ module PWN
 
     public_class_method def self.remove_native_job(opts = {})
       job = opts[:job] || { id: opts[:id], name: opts[:name] }
+      return { skipped: true, reason: :housekeeping_internal_only } if housekeeping_job?(job: job)
+
       backend = (opts[:backend] || scheduler_backend).to_sym
       apply = apply_native?(opts)
       case backend
@@ -1110,7 +1171,7 @@ module PWN
     public_class_method def self.install_crontab_worker(opts = {})
       apply = apply_native?(opts)
       marker = 'PWN::Cron.ensure_worker'
-      line = "@reboot #{ruby_eval_shell(snippet: 'require "pwn"; PWN::Cron.ensure_worker(restart: false)', log: worker_log)}"
+      line = "@reboot #{ruby_eval_shell(snippet: 'ENV["PWN_CRON_NATIVE"] = "1"; require "pwn"; PWN::Cron.ensure_worker(restart: false)', log: worker_log)}"
       preview = "# pwn-cron worker\n#{line}\n"
       write_native_preview(name: 'worker.crontab', body: preview)
       return { backend: :crontab, apply: false, line: line } unless apply && crontab_available?
@@ -1124,6 +1185,8 @@ module PWN
 
     public_class_method def self.install_crontab_job(opts = {})
       job = opts[:job]
+      return { skipped: true, reason: :housekeeping_internal_only } if housekeeping_job?(job: job)
+
       apply = apply_native?(opts)
       snippet = "require \"pwn\"; PWN::Cron.run(id: #{job[:id].to_s.inspect})"
       line = "#{job[:schedule]} #{ruby_eval_shell(snippet: snippet, log: File.join(cron_dir, 'cron.log'))}"
@@ -1165,7 +1228,7 @@ module PWN
     public_class_method def self.install_systemd_user_worker(opts = {})
       apply = apply_native?(opts)
       exec_start = ruby_eval_shell(
-        snippet: 'require "pwn"; PWN::Cron.start_worker(restart: false, foreground: true)'
+        snippet: 'ENV["PWN_CRON_NATIVE"] = "1"; require "pwn"; PWN::Cron.start_worker(restart: false, foreground: true)'
       )
       body = <<~UNIT
         [Unit]
@@ -1194,6 +1257,8 @@ module PWN
 
     public_class_method def self.install_systemd_user_job(opts = {})
       job = opts[:job]
+      return { skipped: true, reason: :housekeeping_internal_only } if housekeeping_job?(job: job)
+
       apply = apply_native?(opts)
       cal = cron_to_calendar(schedule: job[:schedule])
       oncal = systemd_on_calendar(calendar: cal)
@@ -1272,7 +1337,7 @@ module PWN
       label = LAUNCHD_WORKER_LABEL
       plist = launchd_plist(
         label: label,
-        argv: ruby_eval_argv(snippet: 'require "pwn"; PWN::Cron.start_worker(restart: false, foreground: true)'),
+        argv: ruby_eval_argv(snippet: 'ENV["PWN_CRON_NATIVE"] = "1"; require "pwn"; PWN::Cron.start_worker(restart: false, foreground: true)'),
         keepalive: true,
         run_at_load: true
       )
@@ -1283,6 +1348,8 @@ module PWN
 
     public_class_method def self.install_launchd_job(opts = {})
       job = opts[:job]
+      return { skipped: true, reason: :housekeeping_internal_only } if housekeeping_job?(job: job)
+
       apply = apply_native?(opts)
       ints = launchd_calendar_interval(schedule: job[:schedule])
       return { backend: :launchd, id: job[:id], skipped: true, reason: :no_calendar } unless ints
@@ -1325,7 +1392,7 @@ module PWN
 
     public_class_method def self.install_schtasks_worker(opts = {})
       apply = apply_native?(opts)
-      tr = ruby_eval_shell(snippet: 'require "pwn"; PWN::Cron.ensure_worker(restart: false)')
+      tr = ruby_eval_shell(snippet: 'ENV["PWN_CRON_NATIVE"] = "1"; require "pwn"; PWN::Cron.ensure_worker(restart: false)')
       argv = ['schtasks', '/Create', '/F', '/TN', SCHTASKS_WORKER_NAME, '/SC', 'ONLOGON', '/RL', 'LIMITED', '/TR', tr]
       write_native_preview(name: 'worker.schtasks.txt', body: argv.inspect)
       run_argv(argv: argv) if apply && schtasks_available?
@@ -1334,6 +1401,8 @@ module PWN
 
     public_class_method def self.install_schtasks_job(opts = {})
       job = opts[:job]
+      return { skipped: true, reason: :housekeeping_internal_only } if housekeeping_job?(job: job)
+
       apply = apply_native?(opts)
       spec = schtasks_spec(schedule: job[:schedule])
       return { backend: :schtasks, id: job[:id], skipped: true, reason: :no_calendar } unless spec
@@ -1568,6 +1637,7 @@ module PWN
           script: 'optional - path to external script',
           delivery: 'optional - log|stdout (default log)',
           enabled: 'optional - enabled value consumed by #create',
+          sync_native: 'optional - synchronize generic native jobs (default true); defaults are internal only',
           install_crontab: 'optional - install crontab value consumed by #create'
         )
 
@@ -1578,7 +1648,8 @@ module PWN
 
         # Run remove and return its result
         #{self}.remove(
-          id: 'optional - id value consumed by #remove'
+          id: 'optional - id value consumed by #remove',
+          sync_native: 'optional - false deletes only the schedule, preserving native schedulers and evidence'
         )
 
         # Run enable and return its result