samagotchi 0.155.0 → 0.157.0

data/lib/samagotchi/session_manager/listing.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class SessionManager
+    # Listing: read-only queries over the saved sessions (the lists, their
+    # summary rows, a parent's delegates, a session's replies). Calls the
+    # facade's session_owner. Meant to be loaded through samagotchi/session_manager.
+    module ListingPart
+      # List all sessions, reading status from persisted session.json files.
+      # +project_root+: only that project's sessions (nil: every session).
+      # +include_archived+: archived sessions too (Session#archived says which).
+      def list_sessions(state_dir: nil, sort: "updated_at", order: "desc", limit: nil, offset: 0, project_root: nil,
+                        include_archived: false)
+        Session.list(state_dir: state_dir || Session.default_state_dir, sort: sort, order: order, limit: limit,
+                     offset: offset, project_root: project_root, include_archived: include_archived)
+      end
+
+      # Short summaries of sessions, newest first: the picker behind
+      # `chi sessions list --live --format json|tsv` (chi note from a script)
+      # and the agent's list_sessions tool; both pass the current project as
+      # +project_root+ unless asked for every project.
+      # @param live [Boolean] only sessions a worker owns now (WorkerLink's
+      #   worker_owned?: the owner lock, not the saved status, which a dead
+      #   worker leaves at "running"); a session a one-shot (or an older
+      #   chi's REPL) owns is left out: it can't take notes
+      # @param cwd [String, nil] only sessions in this folder or below it
+      # @param project_root [String, nil] only this project's sessions
+      #   (Session#project_root)
+      # @param limit [Integer, nil] taken after the filters
+      # @param include_tests [Boolean] false leaves out test runs
+      # @param exclude [String, nil] a session id to leave out (the asker)
+      # @param include_archived [Boolean] archived sessions too
+      # @return [Array<SessionRow>] see SessionRow for the fields
+      def session_rows(live: false, cwd: nil, limit: nil, include_tests: true, exclude: nil, state_dir: nil,
+                       project_root: nil, include_archived: false, sort: nil, order: nil)
+        sd = state_dir || Session.default_state_dir
+        root = cwd && folder_path(cwd)
+        roots = {}
+        # One registry per listing, built only when a row has a saved context
+        # to count: its session's llm_context budget is what ctx_pct counts
+        # against (SessionMetrics.saved_context_pct).
+        budgets = SessionRow.budgets
+        rows = Session.list(state_dir: sd, sort: sort || "updated_at", order: order || "desc", project_root: project_root,
+                            include_archived: include_archived).lazy
+                      .reject { |s| (!include_tests && s.test_run) || s.id == exclude }
+                      .select { |s| root.nil? || in_folder?(s.working_directory, root) }
+                      .filter_map do |s|
+          dir = Session.session_dir(s.id, state_dir: sd)
+          owner = session_owner(s.id, state_dir: sd)
+          link = WorkerLink.resolve(dir, unlink: false, owner: owner)
+          next if live && !link.worker_owned?
+
+          SessionRow.build(s, session_dir: dir, owner: owner, link: link, roots: roots, budgets: budgets)
+        end
+        (limit ? rows.first(limit) : rows.to_a)
+      end
+
+      # .session_rows as the summaries route's hashes (SessionRow#to_summary_h,
+      # its 28 keys in order): chi web's GET /api/sessions/summaries.
+      # @return [Array<Hash>]
+      def session_summaries(**filters) = session_rows(**filters).map(&:to_summary_h)
+
+      # The sessions delegated by +parent_id+ (the `delegate` tool), newest
+      # first, as .session_rows. A running one (busy) counts against
+      # session.max_children. Archived ones too.
+      # @return [Array<SessionRow>]
+      def children_of(parent_id, state_dir: nil)
+        return [] if parent_id.to_s.empty?
+
+        session_rows(state_dir: state_dir, include_tests: true, include_archived: true)
+          .select { |s| s.parent_id == parent_id.to_s }
+      end
+
+      # Children, their children, …: a delegated session doesn't delegate
+      # further today, a plugin's fork may. The walk doesn't enter +except+.
+      def descendant_ids(id, state_dir, except: [])
+        seen = [id]
+        queue = [id]
+        until queue.empty?
+          children_of(queue.shift, state_dir: state_dir).each do |child|
+            next if seen.include?(child.id) || except.include?(child.id)
+
+            seen << child.id
+            queue << child.id
+          end
+        end
+        seen.drop(1)
+      end
+
+      private def folder_path(path)
+        File.realpath(path)
+      rescue SystemCallError
+        File.expand_path(path)
+      end
+
+      private def in_folder?(dir, root)
+        dir = dir.to_s.chomp("/")
+        root = root.chomp("/")
+        dir == root || dir.start_with?("#{root}/")
+      end
+
+      # Read any new output files from a session directory.
+      # Optionally filters to only files newer than `since_time`.
+      def read_responses(session_id, since_time: nil, state_dir: nil)
+        SessionInbox.read_outputs(Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir),
+                                  since_time: since_time)
+      end
+
+      def stopped_on_disk?(session_id, state_dir:)
+        Session.load(session_id, state_dir: state_dir).status == Session::STATUS_STOPPED
+      rescue ArgumentError
+        false
+      end
+    end
+
+    extend ListingPart
+  end
+end

data/lib/samagotchi/session_manager/removal.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class SessionManager
+    # A delete that would pull the session from under its live worker.
+    # reason: :worker_running (not asked to stop it) or :still_stopping
+    # (stopped, but the worker outlived the wait).
+    class DeleteRefused < StandardError
+      attr_reader :session_id, :reason
+
+      def initialize(session_id, reason)
+        @session_id = session_id
+        @reason = reason
+        super(reason == :still_stopping ? "session #{session_id}'s worker is still shutting down" : "session #{session_id}'s worker is running")
+      end
+    end
+
+    # An archive that can't happen now: a turn runs in the session or in one
+    # of its children (+busy_id+ names which), or it is a scratch session.
+    class ArchiveRefused < StandardError
+      attr_reader :session_id, :reason, :busy_id
+
+      def initialize(session_id, reason, busy_id: nil)
+        @session_id = session_id
+        @reason = reason
+        @busy_id = busy_id
+        super(archive_refused_message)
+      end
+
+      private
+
+      def archive_refused_message
+        case @reason
+        when :scratch then "a scratch session is deleted when you leave; nothing to archive"
+        when :busy_child then "its delegate #{@busy_id[0, 8]} is running a turn; wait for it or stop it first"
+        when :queued then "a prompt is queued, which a resume would run; let it run first"
+        when :queued_child then "its delegate #{@busy_id[0, 8]} has a prompt queued, which a resume would run; let it run first"
+        when :offer then "the step-limit question waits for an answer; answer Continue or Stop first"
+        when :offer_child then "its delegate #{@busy_id[0, 8]} waits for an answer to its step-limit question; answer it first"
+        else "a turn is running; wait for it or cancel it first"
+        end
+      end
+    end
+
+    # What one archive did: id: the session it was asked for; archived: the
+    # ids (it and its delegates) now hidden for good; stopped: the live
+    # workers stopped first; discarded: empty sessions its stopping worker deleted.
+    ArchiveResult = Data.define(:id, :archived, :stopped, :discarded)
+
+    # Removal: archive, unarchive and delete a session (an archive takes its
+    # delegates too), and the retention sweep's entry. Calls LifecyclePart's
+    # stop_session, ListingPart's descendant_ids and the facade's ownership
+    # checks. Meant to be loaded through samagotchi/session_manager.
+    module RemovalPart
+      # Archive a session and its delegated children (ArchiveStore): hidden
+      # from every list, kept by the retention sweep. A live idle worker is
+      # stopped first; the marker is written even while it shuts down.
+      # @return [ArchiveResult]
+      # @raise [ArgumentError] unknown id (Session::AmbiguousId for a prefix of several)
+      # @raise [OwnedByTUI] a one-turn chi run owns it or one of its children
+      # @raise [ArchiveRefused] a turn runs in it or in a child, a prompt is
+      #   queued in one (a later resume would run it), a live one offers to
+      #   continue past the step limit, or it is a scratch session
+      # @param except [Array<String>] descendants left alone with their own
+      #   subtrees (delegates a continue moves to the chain's new link)
+      def archive_session(id_or_prefix, state_dir: nil, wait: 5, except: [])
+        sd = state_dir || Session.default_state_dir
+        id = archive_target(id_or_prefix, sd)
+        tree, owners = archivable!(id, sd, except: except)
+        stopped = tree.select { |sid| owners[sid] }
+        stopped.each { |sid| stop_session(sid, state_dir: sd, wait: wait) }
+        archived, discarded = tree.partition { |sid| ArchiveStore.archive(sid, state_dir: sd) }
+        # A restart's reminders hand-off no successor took (the stop above
+        # removes a live one's): archived sessions keep no reminders.
+        archived.each { |sid| ReminderCarry.remove(Session.session_dir(sid, state_dir: sd)) }
+        # D8: an archive ends the review (unarchiving doesn't restore it).
+        Participants.end_sessions(archived, by: "archive", state_dir: sd)
+        ArchiveResult.new(id: id, archived: archived, stopped: stopped, discarded: discarded)
+      end
+
+      # The session and its descendants, with their owners, when they can be
+      # archived now (#archive_refusal for each), else the refusal. Public for
+      # SessionContinue, which checks before its recap wait.
+      # @return [Array(Array<String>, Hash)] the ids, and id => OwnerLock::Owner or nil
+      # @raise [ArchiveRefused, OwnedByTUI]
+      def archivable!(id, state_dir, except: [])
+        raise ArchiveRefused.new(id, :scratch) if Session.load(id, state_dir: state_dir).scratch
+
+        tree = [id, *descendant_ids(id, state_dir, except: except)]
+        owners = tree.to_h { |sid| [sid, session_owner(sid, state_dir: state_dir)] }
+        tree.each do |sid|
+          refusal = archive_refusal(sid, owners[sid], state_dir)
+          raise ArchiveRefused.new(id, sid == id ? refusal : :"#{refusal}_child", busy_id: sid) if refusal
+        end
+        [tree, owners]
+      end
+
+      # What keeps +sid+ (in an archive's tree) from being archived: :busy (a
+      # turn runs), :queued (input/ holds a prompt, which outlives the stop and
+      # runs on a resume, live worker or not), :offer (a live worker's continue
+      # offer, which the stop would drop), or nil.
+      # @raise [OwnedByTUI] a one-turn chi run owns it
+      private def archive_refusal(sid, owner, state_dir)
+        raise OwnedByTUI, sid if owner&.tui?
+
+        session = owner && Session.load(sid, state_dir: state_dir)
+        return :busy if session&.status == Session::STATUS_RUNNING
+        return :queued unless SessionInbox.find_new_input_files(Session.session_dir(sid, state_dir: state_dir)).empty?
+
+        :offer if session&.waiting_question(live: true)&.dig(:kind) == ContinueOffer::KIND
+      end
+
+      # Unarchive a session and its delegated children.
+      # @return [Hash] {id:, unarchived: [ids that were archived]}
+      # @raise [ArgumentError] unknown id
+      def unarchive_session(id_or_prefix, state_dir: nil)
+        sd = state_dir || Session.default_state_dir
+        id = archive_target(id_or_prefix, sd)
+        unarchived = [id, *descendant_ids(id, sd)].select { |sid| ArchiveStore.unarchive(sid, state_dir: sd) }
+        { id: id, unarchived: unarchived }
+      end
+
+      private def archive_target(id_or_prefix, state_dir) = Session.resolve!(id_or_prefix.to_s, state_dir: state_dir)
+
+      # The retention sweep (SessionRetention.sweep_if_due), here for the web
+      # app and hub, which take this class as their manager.
+      def retention_sweep_if_due(state_dir: nil) = SessionRetention.sweep_if_due(state_dir: state_dir)
+
+      # Delete one session: its <id>.json, the whole <id>/ directory
+      # (history sidecars, input, output, notes, images) and its attached
+      # context (ContextSources: its sources, subscriptions, mute markers). The CLI, the TUI's
+      # /exit --delete and the web all come here.
+      # @param id_or_prefix [String] a session id or a unique prefix of one
+      # @param stop [Boolean] stop a live worker first (waits +wait+ seconds)
+      # @return [Hash] {id:, removed: [paths], stopped: whether a worker was stopped}
+      # @raise [ArgumentError] unknown id (Session::AmbiguousId for a prefix of several)
+      # @raise [OwnedByTUI] a one-turn chi run owns it (never stopped from here)
+      # @raise [DeleteRefused] a worker owns it and +stop+ is false, or it
+      #   outlived the wait
+      # @param purge_runs [Boolean] also delete System 1's saved runs of it and
+      #   its candidate-log lines; a session a worker left empty has none worth
+      #   the read
+      def delete_session(id_or_prefix, state_dir: nil, stop: false, wait: STOP_WAIT, purge_runs: true)
+        sd = state_dir || Session.default_state_dir
+        given = id_or_prefix.to_s
+        # Only a plain id: anything else could name a path outside the state dir.
+        raise Session::NotFound, given unless Session.valid_id?(given)
+
+        id = Session.resolve_id(given, state_dir: sd)
+        path = Session.session_file(id, state_dir: sd)
+        dir = Session.session_dir(id, state_dir: sd)
+        # A folder with no file left is still deleted (not resolve!).
+        raise Session::NotFound, given unless File.exist?(path) || Dir.exist?(dir)
+
+        owner = refuse_tui!(id, state_dir: sd)
+        if owner
+          raise DeleteRefused.new(id, :worker_running) unless stop
+          raise DeleteRefused.new(id, :still_stopping) unless stop_session(id, state_dir: sd, wait: wait)
+        end
+
+        removed = []
+        if File.exist?(path)
+          FileUtils.rm_f(path)
+          removed << path
+        end
+        if Dir.exist?(dir)
+          FileUtils.rm_rf(dir)
+          removed << dir
+        end
+        PluginSessionState.remove(id)
+        removed.concat(ContextSources.remove_session(id, state_dir: sd))
+        Participants.end_sessions([id], by: "delete", state_dir: sd)
+        if purge_runs
+          purge_session_runs(id, sd)
+          ContextCandidatesLog.purge_session(id, state_dir: sd)
+        end
+        { id: id, removed: removed, stopped: !owner.nil? }
+      end
+
+      # Never a reason a delete fails: one warn, and the sweep ages them out.
+      private def purge_session_runs(id, state_dir)
+        SystemOne::Runs.purge_session(id, sessions_dir: state_dir)
+      rescue StandardError => e
+        Log.warn(:worker, "session_runs_purge_failed", sid: id, error: e.class.name, msg: e.message.to_s[0, 200])
+      end
+    end
+
+    extend RemovalPart
+  end
+end

data/lib/samagotchi/session_manager/spawn.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative "../worker_link"
+
+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).
+    WORKER_START_GRACE = WorkerLink::START_LIMIT
+
+    @spawns = {}
+    @spawns_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
+    # 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,
+      # with none, waits idle for input).
+      #
+      # 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
+      #   ctx.sessions.fork); its image refs are copied from +images_from+
+      # @param images_from [String, nil] the session dir the seed's images are in
+      # @param preview [String, nil] what the lists show before the first turn
+      #   (the prompt's preview by default, else the seed's first user message)
+      # @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
+      #   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
+      #   session field; SessionContinue)
+      # @param note [String, nil] a context note the session starts with,
+      #   from +note_source+: queued before its worker spawns, so its first
+      #   turn sees it
+      # @param review [SessionReview, nil] a review session's (ReviewStart; a
+      #   continue keeps its previous link's)
+      # @param verify_fresh [VerifyFreshOrigin, nil] a Verify fresh child's
+      #   requester, rules and claim (VerifyFresh.start)
+      # @param before_spawn [#call, nil] (session) runs once the session and
+      #   its note are saved, before its worker spawns
+      # @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
+      # @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)
+        sd = state_dir || Session.default_state_dir
+        # 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
+        # host's saved list doesn't have (ModelListStore) only warns
+        # (#model_warning on the session), as some hosts serve ids they don't
+        # list.
+        typed = Samagotchi::ModelProfile.check_host!(Samagotchi::ModelProfile.required_model_name(model_name))
+        model_warning = Samagotchi::ModelProfile.model_warning(typed)
+        ref = HostConfig.model_ref(typed).ref
+        session = Session.new_session(
+          mode: mode,
+          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,
+          setup: setup,
+          continues: continues,
+          review: review,
+          scratch: scratch
+        )
+        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.
+        session.verify_fresh = verify_fresh
+        session.model_warning = model_warning
+        # With no prompt there is no first turn to run (an attaching UI sends
+        # the prompts), so the session starts idle.
+        session.status = prompt.to_s.strip.empty? ? Session::STATUS_IDLE : Session::STATUS_RUNNING
+        session.last_prompt = prompt
+        # The first prompt's turn gets an id like a sent message's, so a wait
+        # 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?
+        # 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
+        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
+      def resume_session(session_id, state_dir: nil)
+        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)
+
+        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 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)
+        sd = state_dir || Session.default_state_dir
+        return :gone unless Session.exist?(session_id, state_dir: sd)
+        return :owned if session_owner(session_id, state_dir: sd)
+        return :stopped if Session.stopped_marker?(session_id, state_dir: sd)
+
+        if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: sd))
+          following = forward && SessionChain.next_of(session_id, state_dir: sd)
+          return following ? wake_for_report(following, state_dir: sd, forward: false) : :archived
+        end
+        return :starting if StartingMarker.fresh?(session_id, state_dir: sd)
+
+        session = Session.load(session_id, state_dir: sd)
+        return :stopped if session.status == Session::STATUS_STOPPED
+        return :scratch if session.scratch
+
+        resume_session(session_id, state_dir: sd)
+        Log.info(:worker, "delegate_woke_parent", parent: session_id[0, 8])
+        :woken
+      rescue OwnedByTUI
+        :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?
+
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - at < WORKER_START_GRACE
+      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]
+        end
+      end
+
+      # Forget the spawns #still_starting? remembers (specs).
+      def forget_spawns
+        @spawns_mutex.synchronize { @spawns.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
+        end
+      end
+
+      private def setup_session_directory(session_dir, session, state_dir:)
+        FileUtils.mkdir_p(session_dir)
+        FileUtils.mkdir_p(File.join(session_dir, SessionInbox::INPUT_DIR))
+        FileUtils.mkdir_p(File.join(session_dir, SessionInbox::OUTPUT_DIR))
+        session.save(state_dir: state_dir)
+      end
+
+      private def spawn_worker_for_session(session, state_dir:)
+        session_dir = Session.session_dir(session.id, state_dir: state_dir)
+        FileUtils.mkdir_p(session_dir)
+        FileUtils.mkdir_p(File.join(session_dir, SessionInbox::INPUT_DIR))
+        FileUtils.mkdir_p(File.join(session_dir, SessionInbox::OUTPUT_DIR))
+
+        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.
+        # +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))
+        Log.info(:worker, "spawn", sid: session.id, child_pid: pid)
+        pid
+      end
+    end
+
+    extend SpawnPart
+  end
+end