samagotchi 0.159.0 → 0.161.0

data/lib/samagotchi/session_manager/spawn.rb

@@ -1,19 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "../worker_link"
+require_relative "../starting_marker"
 
 module Samagotchi
   class SessionManager
-    # How long after a spawn a resume trusts that worker to take the
-    # session, while it runs (and the session wasn't stopped since).
+    # How long a worker's starter waits for it to take the session
+    # (WorkerBoot.detach_from_spawner): the starting marker naming the
+    # starter holds that long at most.
     WORKER_START_GRACE = WorkerLink::START_LIMIT
 
-    @spawns = {}
-    @spawns_mutex = Mutex.new
+    # The starters this process spawned (their Process.detach waiters), for
+    # chi web's restart to adopt (#live_spawn_pids). Decides nothing: the
+    # starting marker is what holds a second spawn off.
+    @starters = []
+    @starters_mutex = Mutex.new
 
     # Spawn: deciding to start a session's worker (a new session, a resume, a
-    # delegate's report waking its parent) and the spawns this process
-    # remembers. Calls WorkerCommandPart's spawn_options and worker_command and
+    # delegate's report waking its parent) and the starters this process
+    # spawned. Calls WorkerCommandPart's spawn_options and worker_command and
     # the facade's ownership checks. Meant to be loaded through samagotchi/session_manager.
     module SpawnPart
       # Spawn a new background session that processes the given prompt (or,
@@ -22,9 +27,6 @@ module Samagotchi
       # Returns the session object with its ID. Every worker always starts its
       # per-session Bridge (the single live client transport), so external
       # clients can reach it once the sidecar is published.
-      # @param memories [Array<String>] --memory: preloaded into the worker's prompt
-      # @param muted_memories [Array<String>] --mute: hidden from the session
-      #   (both are session fields, so a respawn keeps them)
       # @param parent_id [String, nil] the session that delegates this one (the
       #   `delegate` tool) or was forked from; a session field too
       # @param messages [Array<Hash>] a conversation to start from (a plugin's
@@ -35,9 +37,9 @@ module Samagotchi
       # @param title [String, nil] the session's own name (Session#title; a
       #   continue's link inherits its previous link's), saved before the
       #   worker starts: the worker owns the file from then on
-      # @param setup [SessionSetup] the session's own settings (chi
-      #   --llm-context; a fork and a continue copy their session's; a delegate
-      #   child the toolkit its delegate call named); without a toolkit the
+      # @param setup [SessionSetup] the session's own settings (chi --memory,
+      #   --mute, --llm-context; a fork and a continue copy their session's;
+      #   a delegate child the memory and toolkit its delegate call named); without a toolkit the
       #   session is stored on config's toolkit.default, a delegate child on
       #   toolkit.child (Toolkit.configured)
       # @param continues [String, nil] the session this one continues (a
@@ -54,13 +56,20 @@ module Samagotchi
       # @param scratch [Boolean] a `chi scratch` session (its terminal's
       #   AttachLauncher): its worker runs a scratch Engine and deletes it
       #   once its last client is gone
+      # @param client_id [String, nil] who sent +prompt+ (a ClientId); required
+      #   even when nil is intentional for a session with no initial prompt
+      # @param session_id [String, nil] an id reserved by a durable operation
       # @return [Session] with #seed_images_dropped: refs whose file was gone,
       #   and #model_warning: an id its host's saved list doesn't have
-      def spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
-                        memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
-                        preview: nil, title: nil, delegate: false, setup: SessionSetup.new, continues: nil, note: nil,
-                        note_source: "chi", before_spawn: nil, review: nil, verify_fresh: nil, scratch: false)
+      def spawn_session(prompt:, client_id:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
+                        parent_id: nil, messages: [], images_from: nil, preview: nil, title: nil, delegate: false,
+                        setup: SessionSetup.new, continues: nil, note: nil, note_source: "chi", before_spawn: nil,
+                        review: nil, verify_fresh: nil, scratch: false, session_id: nil)
         sd = state_dir || Session.default_state_dir
+        if session_id && (!Session.valid_id?(session_id) || Session.exist?(session_id, state_dir: sd))
+          raise ArgumentError, "invalid or existing session id #{session_id.inspect}"
+        end
+
         # The resolved ref is stored (a resumed session keeps its model when an
         # alias is retargeted), with the name as typed beside it. A wrong host
         # refuses here, before anything is saved or spawned; a model id the
@@ -75,8 +84,6 @@ module Samagotchi
           model_name: ref,
           model_typed: typed == ref ? nil : typed,
           working_directory: working_directory || Dir.pwd,
-          preloaded_memory_names: memories,
-          muted_memory_names: muted_memories,
           parent_id: parent_id,
           messages: messages,
           delegate: delegate,
@@ -85,6 +92,7 @@ module Samagotchi
           review: review,
           scratch: scratch
         )
+        session.id = session_id if session_id
         session.toolkit = Toolkit.configured(delegate: delegate) if session.toolkit.nil?
         session.toolkit_origin = setup.toolkit_origin || "default"
         # Saved before the worker starts: its first turn is already the requester's.
@@ -98,92 +106,117 @@ module Samagotchi
         # for it can name it (chi send --new --wait, chi web's create): the
         # worker runs it with that origin, and its reply file and last_turn
         # carry the id.
-        session.first_turn_id = SecureRandom.uuid unless prompt.to_s.strip.empty?
+        unless prompt.to_s.strip.empty?
+          session.first_turn_id = SecureRandom.uuid
+          session.first_turn_client_id = client_id unless ClientId.human?(client_id)
+        end
         # The worker takes last_prompt and clears it, and messages are saved at
         # the turn's end: until then this is the only preview a list has.
         session.first_preview = Session.preview_of(preview.to_s.strip.empty? ? prompt : preview)
         session.title = title
         session_dir = Session.session_dir(session.id, state_dir: sd)
-        unless session.messages.empty?
-          session.messages, dropped = ImageStore.copy_refs(session.messages, from: images_from, to: session_dir)
-          session.seed_images_dropped = dropped
+        # Starting before its file exists: the file is never there unowned and
+        # unmarked (a sweep would take a scratch session from under its
+        # worker). spawn_worker_for_session hands it to the starter.
+        StartingMarker.mark(session.id, state_dir: sd)
+        begin
+          unless session.messages.empty?
+            session.messages, dropped = ImageStore.copy_refs(session.messages, from: images_from, to: session_dir)
+            session.seed_images_dropped = dropped
+          end
+          setup_session_directory(session_dir, session, state_dir: sd)
+          SessionInbox.write_note(session.id, text: note, source: note_source, state_dir: sd) if note
+          before_spawn&.call(session)
+          spawn_worker_for_session(session, state_dir: sd)
+        rescue StandardError
+          # Nothing is starting: a caller's cleanup (a continue's failed link) may delete it.
+          StartingMarker.clear(session.id, state_dir: sd)
+          raise
         end
-        setup_session_directory(session_dir, session, state_dir: sd)
-        SessionInbox.write_note(session.id, text: note, source: note_source, state_dir: sd) if note
-        before_spawn&.call(session)
-        spawn_worker_for_session(session, state_dir: sd)
         session
       end
 
       # Ensure an existing session has a live worker process.
       # Returns the loaded session after state reconciliation.
       # @raise [OwnedByTUI] when the interactive TUI owns the session
+      # @yieldparam outcome [Symbol] what it did, when a block is given:
+      #   :woken (it spawned the worker), :live (a worker holds the session,
+      #   or took it since the first read) or :starting (another start is
+      #   pending, or won the claim)
       def resume_session(session_id, state_dir: nil)
+        session, outcome = resume(session_id, state_dir: state_dir)
+        yield outcome if block_given?
+        session
+      end
+
+      # resume_session's work, with its outcome.
+      # @return [Array(Session, Symbol)]
+      private def resume(session_id, state_dir:)
         sd = state_dir || Session.default_state_dir
         session = Session.load(session_id, state_dir: sd)
         # Its terminal's worker came from spawn_session; nothing wakes another.
         raise ScratchSession, session.id if session.scratch
-        return session if refuse_tui!(session.id, state_dir: sd)
 
-        # status is turn state, not liveness: a new worker runs no turn yet,
-        # and must not find the session stopped (it would exit): neither the
-        # marker nor a status field from before it.
-        # One this process just spawned may not hold the lock yet (a slow
-        # start, deliver_turn's second resume): it would only lose it.
-        return session if still_starting?(session.id, state_dir: sd)
-        # A continue moving delegates to it spawns its worker once they are
-        # moved; one spawned now (a moved child's ring) would race the move.
-        return session if StartingMarker.fresh?(session.id, state_dir: sd)
+        presence = WorkerPresence.read(session.id, state_dir: sd, owner: session_owner(session.id, state_dir: sd))
+        raise OwnedByTUI, session.id if presence.tui_owned?
+        return [session, :live] if presence.owned?
 
-        Session.clear_stopped(session.id, state_dir: sd)
-        session.status = Session::STATUS_IDLE
-        session.save(state_dir: sd)
-        spawn_worker_for_session(session, state_dir: sd)
-        session
-      end
+        # A worker being started for it, by this process or another (chi web,
+        # a `chi send`, a child's ring; a continue moving delegates to its new
+        # link), may not hold the lock yet: a second one would only lose it,
+        # or race the move (#resume_held_off?).
+        return [session, :starting] if presence.resume_held_off?
 
-      # A delegate child rang a parent that has no worker (ChildRing): start
-      # one, which runs a turn for the report. Not for a parent that is gone,
-      # stopped, archived, a scratch session, a one-turn run's, or a
-      # continue's new link still taking its delegates (its own spawn comes):
-      # the ring waits on disk for whoever runs it next (#resume_session
-      # itself would clear the stop). A stop landing between the check and
-      # the resume is a small window, left as is. An archived parent with a
-      # later link in its chain wakes that link instead: a ring a moved child
-      # wrote just as the continue moved it reaches the new link that way
-      # (ChildReports reads its predecessor's rings).
-      # @return [Symbol] :woken, or why not (:gone, :stopped, :archived,
-      #   :scratch, :owned, :starting)
-      def wake_for_report(session_id, state_dir: nil, forward: true)
-        wake_existing_session(session_id, state_dir: state_dir || Session.default_state_dir, forward: forward,
-                              event: :delegate_woke_parent)
+        claimed = claim_start(session.id, state_dir: sd, stopped: presence.stop_marked?)
+        return [session, claimed] unless claimed == :claimed
+
+        # The new worker must not find the session stopped (it would exit).
+        # Nothing else is written: the file is the worker's, which turns a
+        # status from before it idle under the lock (Worker#settle_stale_status).
+        begin
+          Session.clear_stopped(session.id, state_dir: sd)
+          spawn_worker_for_session(session, state_dir: sd)
+        rescue StandardError
+          # Its claim holds nothing now (a command or the options failed
+          # before Process.spawn): no 60 s hold-off.
+          StartingMarker.clear(session.id, state_dir: sd)
+          raise
+        end
+        [session, :woken]
       end
 
-      # A pushed context source asked for a wake: start an idle-exited
-      # session, but never clear a stop or forward an archived link.
+      # A ring waits in a parent's children/ (a failed continue's previous
+      # link got rings back): wake it as the ring's own delivery would
+      # (SessionInbox.wake :ring, its WakePolicy). Not for a parent that is
+      # gone, stopped (the stop marker; the file's status never decides),
+      # archived, a scratch session, a one-turn run's or owned, or a
+      # continue's new link still taking its delegates (its own spawn
+      # comes): the ring waits on disk for whoever runs it next. A stop
+      # landing between the check and the resume is a small window, left as
+      # is. An archived parent with a later link wakes that link (one hop:
+      # ChildReports reads its predecessor's rings, no further).
       # @return [Symbol] :woken, or why not (:gone, :stopped, :archived,
       #   :scratch, :owned, :starting)
-      def wake_for_context(session_id, state_dir: nil)
-        wake_existing_session(session_id, state_dir: state_dir || Session.default_state_dir, forward: false,
-                              event: :context_woke_session)
+      def wake_for_report(session_id, state_dir: nil)
+        sd = state_dir || Session.default_state_dir
+        outcome = SessionInbox.wake(:ring, session_id, state_dir: sd, owner: ->(id) { session_owner(id, state_dir: sd) }).wake
+        outcome == :live ? :owned : outcome
       end
 
-      private def wake_existing_session(session_id, state_dir:, forward:, event:)
-        return :gone unless Session.exist?(session_id, state_dir: state_dir)
-        return :owned if session_owner(session_id, state_dir: state_dir)
-        return :stopped if Session.stopped_marker?(session_id, state_dir: state_dir)
-
-        if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: state_dir))
-          following = forward && SessionChain.next_of(session_id, state_dir: state_dir)
-          return following ? wake_existing_session(following, state_dir: state_dir, forward: false, event: event) : :archived
-        end
-        return :starting if StartingMarker.fresh?(session_id, state_dir: state_dir)
-
-        session = Session.load(session_id, state_dir: state_dir)
-        return :stopped if session.status == Session::STATUS_STOPPED
-        return :scratch if session.scratch
+      # Start a worker for a delivery whose WakePolicy decided :start
+      # (SessionInbox.deliver): resume_session, which keeps its own checks
+      # (a claim on the starting marker: of starts racing, one spawns),
+      # logged as +event+.
+      # @param event [Symbol] :delegate_woke_parent (a ring) or :context_woke_session (a push)
+      # @return [Symbol] :woken (this start spawned it), :starting (another
+      #   start won the claim, or is pending), :live (a worker took it since)
+      #   or :owned (a one-turn chi run or its terminal's scratch session did)
+      def start_for_inbox(session_id, state_dir:, event:)
+        # A stand-in resume_session that yields nothing counts as a start.
+        outcome = :woken
+        resume_session(session_id, state_dir: state_dir) { |done| outcome = done }
+        return outcome unless outcome == :woken
 
-        resume_session(session_id, state_dir: state_dir)
         details = event == :delegate_woke_parent ? { parent: session_id[0, 8] } : { sid: session_id[0, 8] }
         Log.info(:worker, event, **details)
         :woken
@@ -191,37 +224,46 @@ module Samagotchi
         :owned
       end
 
-      # A worker this process spawned for the session within
-      # WORKER_START_GRACE is still running, and no stop came since.
-      private def still_starting?(session_id, state_dir:)
-        return false if Session.stopped_marker?(session_id, state_dir: state_dir)
-
-        at, waiter = @spawns_mutex.synchronize { @spawns[[state_dir, session_id]] }
-        return false unless at && waiter.respond_to?(:alive?) && waiter.alive?
+      # Take the start for resume_session: the marker claimed (of resumes
+      # racing from any processes, one claims it), then the owner read
+      # again: a worker that took the lock since the first read cleared an
+      # earlier start's marker, and keeps the session. After a stop, a start
+      # marked before it is taken over (a stop cancels the hold-off), one a
+      # resume made after it holds (two sends after a stop start one worker).
+      # @return [Symbol] :claimed (this resume spawns), :starting (another
+      #   start holds the claim) or :live (a worker took the lock since)
+      private def claim_start(session_id, state_dir:, stopped:)
+        over_before = stopped ? stopped_at(session_id, state_dir) : nil
+        return :starting unless StartingMarker.claim(session_id, state_dir: state_dir, over_before: over_before)
+        return :claimed unless session_owner(session_id, state_dir: state_dir)
 
-        Process.clock_gettime(Process::CLOCK_MONOTONIC) - at < WORKER_START_GRACE
+        StartingMarker.clear(session_id, state_dir: state_dir)
+        :live
       end
 
-      private def note_spawn(session_id, state_dir:, waiter:)
-        @spawns_mutex.synchronize do
-          @spawns.delete_if { |_, (_, w)| !(w.respond_to?(:alive?) && w.alive?) }
-          @spawns[[state_dir, session_id]] = [Process.clock_gettime(Process::CLOCK_MONOTONIC), waiter]
+      # When the stop marker was written (Session.stopped_at); nil when it
+      # is gone (another resume cleared it: its start came after the stop,
+      # and holds).
+      private def stopped_at(session_id, state_dir) = Session.stopped_at(session_id, state_dir: state_dir)
+
+      private def note_starter(waiter)
+        @starters_mutex.synchronize do
+          @starters.select! { |w| w.respond_to?(:alive?) && w.alive? }
+          @starters << waiter
         end
       end
 
-      # Forget the spawns #still_starting? remembers (specs).
+      # Forget the starters this process spawned (specs).
       def forget_spawns
-        @spawns_mutex.synchronize { @spawns.clear }
+        @starters_mutex.synchronize { @starters.clear }
       end
 
       # Starter processes are children of chi web, unlike the detached workers
       # they launch; the web restart adopts these pids before replacing itself.
       def live_spawn_pids
-        @spawns_mutex.synchronize do
-          @spawns.delete_if { |_, (_, waiter)| !(waiter.respond_to?(:alive?) && waiter.alive?) }
-          @spawns.values.filter_map do |_, waiter|
-            waiter.pid if waiter.respond_to?(:pid) && waiter.alive?
-          end.uniq.sort
+        @starters_mutex.synchronize do
+          @starters.select! { |waiter| waiter.respond_to?(:alive?) && waiter.alive? }
+          @starters.filter_map { |waiter| waiter.pid if waiter.respond_to?(:pid) }.uniq.sort
         end
       end
 
@@ -241,14 +283,39 @@ module Samagotchi
         opts = spawn_options(session)
         env = opts.delete(:env)
         command = worker_command(session.id, state_dir: state_dir)
-        pid = env ? Process.spawn(env, *command, **opts) : Process.spawn(*command, **opts)
-        # Reaped when it exits: a long-lived spawner (chi web) keeps no zombies.
+        # Starting from here (WorkerPresence#starting?), for as long as this
+        # process runs, until the spawn below names its starter.
+        StartingMarker.mark(session.id, state_dir: state_dir)
+        begin
+          pid = env ? Process.spawn(env, *command, **opts) : Process.spawn(*command, **opts)
+        rescue StandardError
+          StartingMarker.clear(session.id, state_dir: state_dir)
+          raise
+        end
         # +pid+ is the worker's starter, which exits once the worker it forked
-        # holds the lock (WorkerBoot.detach_from_spawner): the lock's pid is the worker's.
-        note_spawn(session.id, state_dir: state_dir, waiter: Process.detach(pid))
+        # holds the lock (WorkerBoot.detach_from_spawner): the lock's pid is
+        # the worker's, and the marker holds exactly while the starter runs
+        # (most spawners exit right after this). The worker removes it once it
+        # holds the lock (Worker#start).
+        if starter_running?(pid)
+          StartingMarker.mark(session.id, state_dir: state_dir, pid: pid)
+          # Reaped when it exits: a long-lived spawner (chi web) keeps no zombies.
+          note_starter(Process.detach(pid))
+        else
+          # It failed to exec or boot: nothing is starting.
+          StartingMarker.clear(session.id, state_dir: state_dir)
+        end
         Log.info(:worker, "spawn", sid: session.id, child_pid: pid)
         pid
       end
+
+      # Whether the starter just spawned still runs (reaped here if it
+      # already exited). Not a child of this process: nothing to wait for.
+      private def starter_running?(pid)
+        Process.waitpid(pid, Process::WNOHANG).nil?
+      rescue Errno::ECHILD
+        false
+      end
     end
 
     extend SpawnPart

data/lib/samagotchi/session_manager/worker_command.rb

@@ -3,10 +3,10 @@
 module Samagotchi
   class SessionManager
     # CROSS-VERSION CONTRACT: this boot string, the entry it names
-    # (WorkerBoot.run_session_loop(id, state_dir:)), the legacy forwarder
-    # below, the env keys spawn_options sets and the input/ file
-    # format are read by a NEWER chi than the one writing them. Change them
-    # only additively (spec/worker_contract_spec.rb).
+    # (WorkerBoot.run_session_loop(id, state_dir:)), the env keys
+    # spawn_options sets and the input/ file format are read by a NEWER chi
+    # than the one writing them. Change them only additively
+    # (spec/worker_contract_spec.rb).
     BOOT_FALLBACK_ENV = "SAMAGOTCHI_BOOT_FALLBACK"
     # "1" in a worker spawn_options started: it traps signals (WorkerSignals).
     # WorkerBoot.run_session_loop deletes it from ENV as it reads it.
@@ -28,9 +28,9 @@ module Samagotchi
 
     # WorkerCommand: the worker's command line and env (CROSS-VERSION
     # CONTRACT: spec/worker_contract_spec.rb); the worker process itself is
-    # WorkerBoot (worker_boot.rb). The boot command loads it directly; the
-    # forwarder (run_session_loop) remains for older boot strings. Calls no
-    # other part. Meant to be loaded through samagotchi/session_manager.
+    # WorkerBoot (worker_boot.rb), which the boot command loads directly.
+    # Calls no other part. Meant to be loaded through
+    # samagotchi/session_manager.
     module WorkerCommandPart
       # Build the opts hash passed to Process.spawn for a forked worker. The
       # child inherits this process's ENV and reads config.yml itself (as it
@@ -94,18 +94,6 @@ module Samagotchi
         opts
       end
 
-      # The worker's legacy entry for boot strings written by older chi
-      # (CROSS-VERSION CONTRACT: spec/worker_contract_spec.rb): it forwards to
-      # WorkerBoot.run_session_loop, which runs the worker process. Looked up
-      # by name on purpose: a constant reference here would put SessionManager
-      # back into one cycle with Worker, Engine and Bridge (the class map).
-      # REMOVE in the next release: boot strings name WorkerBoot since this
-      # one (see ~/.claude/plans/arch-worker-boot.md).
-      def run_session_loop(session_id, state_dir: nil, **)
-        require_relative "../worker_boot"
-        Samagotchi.const_get(:WorkerBoot).run_session_loop(session_id, state_dir: state_dir, **)
-      end
-
       # The worker's command line. Run from an installed gem, the worker
       # activates the newest installed samagotchi (`>= 0.a`, prereleases
       # count), whoever spawns it: an old chi web, chi send or --attach then

data/lib/samagotchi/session_manager.rb

@@ -59,6 +59,7 @@ require_relative "context_candidates_log"
 require_relative "session_chain"
 require_relative "child_move"
 require_relative "starting_marker"
+require_relative "worker_presence"
 require_relative "tools/task_runtime"
 
 module Samagotchi

data/lib/samagotchi/session_retention.rb

@@ -4,6 +4,8 @@ require "fileutils"
 require "time"
 require_relative "session"
 require_relative "archive_store"
+require_relative "worker_presence"
+require_relative "starting_marker"
 require_relative "config"
 require_relative "log"
 require_relative "model_profile"
@@ -18,8 +20,8 @@ module Samagotchi
   # (session.retention_days), count (session.max_count, counting only the
   # sessions that stay), statuses kept (session.keep_status), sessions left
   # empty (SessionManager.discardable?, an hour on), leftover scratch
-  # sessions (once past SCRATCH_START_GRACE) and skeleton-only directories; a session with a live owner
-  # always stays.
+  # sessions and skeleton-only directories; a session with a live owner, or
+  # whose worker is being started (StartingMarker), always stays.
   module SessionRetention
     # The session.retention_days / max_count / keep_status defaults.
     DEFAULT_RETENTION_DAYS = 14
@@ -53,13 +55,19 @@ module Samagotchi
         dry_run: dry_run,
         test_only: test_only,
         any_age: any_age,
-        alive_check: ->(sid) { !SessionManager.session_owner(sid, state_dir: sd).nil? },
+        alive_check: ->(sid) { owned?(sid, sd) },
         empty_check: discard ? ->(sid) { left_empty?(sid, state_dir: sd, default_model: default_model) } : nil
       )
       result[:deleted].concat(prune_orphan_dirs(sd, dry_run: dry_run)) if discard && !test_only
       result
     end
 
+    # Someone holds the session's owner lock (a worker, a one-turn run).
+    private_class_method def self.owned?(session_id, state_dir)
+      WorkerPresence.read(session_id, state_dir: state_dir,
+                                      owner: SessionManager.session_owner(session_id, state_dir: state_dir)).owned?
+    end
+
     private_class_method def self.left_empty?(session_id, state_dir:, default_model:)
       path = Session.session_file(session_id, state_dir: state_dir)
       Time.now - File.mtime(path) > EMPTY_GRACE_SECONDS &&
@@ -80,7 +88,7 @@ module Samagotchi
         next unless Session.valid_id?(name) && File.directory?(dir)
         next if File.exist?(File.join(state_dir, "#{name}#{SessionPaths::FILE_EXT}"))
         next unless Time.now - File.mtime(dir) > EMPTY_GRACE_SECONDS && SessionManager.empty_session_dir?(dir)
-        next if SessionManager.session_owner(name, state_dir: state_dir)
+        next if owned?(name, state_dir) || starting?(name, state_dir)
 
         unless dry_run
           FileUtils.rm_rf(dir)
@@ -93,14 +101,18 @@ module Samagotchi
       end
     end
 
-    # How long after its save an unowned scratch session may still be
-    # waiting for the worker just spawned for it to take its owner lock.
-    SCRATCH_START_GRACE = SessionManager::WORKER_START_GRACE
+    # A worker is being started for it (every spawn marks it, a new
+    # session's before its file is saved): no owner yet doesn't mean nobody
+    # runs it.
+    private_class_method def self.starting?(session_id, state_dir)
+      StartingMarker.fresh?(session_id, state_dir: state_dir)
+    end
 
-    private_class_method def self.scratch_starting?(path, now)
-      now - File.mtime(path) < SCRATCH_START_GRACE
-    rescue SystemCallError
-      false
+    # Being started or owned now (+alive_check+, when given, reads the owner).
+    private_class_method def self.held?(session_id, state_dir, alive_check)
+      starting?(session_id, state_dir) || alive_check&.call(session_id) == true
+    rescue StandardError
+      true
     end
 
     # Lazy sweep guard: runs prune at most once per SWEEP_INTERVAL_HOURS
@@ -172,9 +184,11 @@ module Samagotchi
     # count (`chi sessions clean` with no --days: test runs are throwaway).
     #
     # A scratch session nobody owns (its terminal and worker were killed) goes whatever its
-    # age, its status and the count; +test_only+ takes it too. One saved
-    # within SCRATCH_START_GRACE (its file's mtime, against +now+) stays: its
-    # worker may not have taken the owner lock yet.
+    # age, its status and the count; +test_only+ takes it too.
+    #
+    # A session whose worker is being started (StartingMarker, fresh) stays,
+    # whatever it is, and takes no count slot: its worker may not have taken
+    # the owner lock yet.
     #
     # +max_count+ counts the sessions that stay: one deleted whatever its
     # place (scratch, left empty, expired, +any_age+) takes no slot.
@@ -186,6 +200,9 @@ module Samagotchi
     def self.apply(state_dir: Session.default_state_dir, days: DEFAULT_RETENTION_DAYS, max_count: DEFAULT_MAX_COUNT,
                    keep_status: DEFAULT_KEEP_STATUS, dry_run: false, test_only: false, alive_check: nil,
                    empty_check: nil, any_age: false, now: Time.now)
+      require_relative "schedules"
+      schedules = Schedules.new(state_dir: state_dir)
+      scheduled_targets = schedules.protected_session_ids
       keep_status = Array(keep_status).map(&:to_s)
       # Fetch all sessions sorted newest-first for count logic
       all = Session.list(state_dir: state_dir, sort: "updated_at", order: "desc")
@@ -200,6 +217,7 @@ module Samagotchi
       deleted = []
       kept = []
       skipped = []
+      purge_ids = []
       passed_over = 0
 
       all.each_with_index do |session, idx|
@@ -210,6 +228,11 @@ module Samagotchi
           next
         end
 
+        if scheduled_targets.include?(session.id)
+          kept << session.id
+          next
+        end
+
         # Protected by keep_status
         if keep_status.include?(session.status.to_s) && !session.scratch
           kept << session.id
@@ -228,10 +251,9 @@ module Samagotchi
           end
         end
 
-        # A scratch session saved within SCRATCH_START_GRACE: `chi scratch`
-        # saves it, then spawns the worker that takes its owner lock, so no
-        # owner yet doesn't mean a leftover. Kept, it takes no count slot.
-        if session.scratch && scratch_starting?(path, now)
+        # Being started (a resume, a new or scratch session): its worker
+        # takes the owner lock in a moment. Kept, it takes no count slot.
+        if starting?(session.id, state_dir)
           kept << session.id
           passed_over += 1
           next
@@ -277,20 +299,28 @@ module Samagotchi
         # Eligible for deletion
         if dry_run
           deleted << session.id
+        # Looked at again right before its files go (the list was read
+        # once, at the start): resumed or taken by a worker since, it stays.
+        elsif held?(session.id, state_dir, alive_check)
+          kept << session.id
+        elsif scheduled_targets.include?(session.id)
+          kept << session.id
         else
           begin
-            FileUtils.rm_f(path)
-            sidecar = File.join(state_dir, session.id)
-            FileUtils.rm_rf(sidecar)
-            PluginSessionState.remove(session.id)
-            ContextSources.remove_session(session.id, state_dir: state_dir)
+            # Under the owner lock, the start read again (as a delete).
+            SessionManager.remove_files(session.id, path, File.join(state_dir, session.id), state_dir: state_dir,
+                                        purge_runs: false)
             deleted << session.id
+            purge_ids << session.id
+          rescue SessionManager::DeleteRefused
+            kept << session.id
           rescue StandardError
             skipped << session.id
           end
         end
       end
 
+      SessionManager.purge_removal_stores(purge_ids, state_dir: state_dir)
       { deleted: deleted, kept: kept, skipped: skipped }
     end
   end