samagotchi 0.155.0 → 0.156.0

data/lib/samagotchi/session_manager/lifecycle.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require_relative "../worker_idle_exit"
+
+module Samagotchi
+  class SessionManager
+    # A restart that can't happen now. reason: :not_running (no live worker:
+    # the next prompt starts one on the newest chi anyway), :unsupported (a
+    # worker from before restarts, running +version+: stop it instead), a
+    # WorkerIdleExit#hold_for_restart hold (:turn_running, :reminders, ...),
+    # :fallback_held (disk-visible work blocks an unresponsive-worker restart),
+    # :stopped (its worker, +pid+, is SIGSTOPped: neither the ask nor a TERM
+    # reaches it until it is continued), or :failed (the worker answered something else or didn't release).
+    class RestartRefused < StandardError
+      attr_reader :session_id, :reason, :version, :holds, :pid
+
+      def initialize(session_id, reason, version: nil, holds: [], pid: nil, via: ChiInvocation::HERE)
+        @session_id = session_id
+        @reason = reason.to_sym
+        @version = version
+        @holds = Array(holds).map(&:to_sym).freeze
+        @pid = pid
+        super(RestartRefused.words(session_id, @reason, version, @holds, pid: pid, via: via))
+      end
+
+      HOLDS = {
+        starting: "its worker is still starting",
+        turn_running: "a turn is running",
+        input_queued: "a prompt is queued",
+        continue_offered: "the step-limit question waits for an answer",
+        question_pending: "a question or approval waits for an answer",
+        # Only a worker from before ReminderCarry still holds a restart for its reminders.
+        reminders: "it has reminders, which its worker's older chi can't carry over a restart",
+        command_running: "a /btw (or another command) is still running",
+        relays_open: "a delegate's approval relayed here is open or just answered",
+        background_tasks: "background tasks it started are still running",
+        scratch: "a chi scratch session's worker ends with its terminal"
+      }.merge(WorkerIdleExit::LEAVING_WORDS).freeze
+
+      # What the CLI and the web say.
+      def self.words(session_id, reason, version = nil, holds = [], pid: nil, via: ChiInvocation::HERE)
+        stop = via.command("sessions stop #{session_id}")
+        case reason
+        when :stopped
+          where = via.remote? ? " on #{via.remote}" : ""
+          "session #{session_id}'s worker#{" (pid #{pid})" if pid} is stopped (SIGSTOP or Ctrl-Z) and can't take " \
+            "a restart: continue it#{" with `kill -CONT #{pid}`" if pid}#{where}, then restart again"
+        when :not_running
+          "session #{session_id} has no running worker; the next prompt starts one on the newest chi"
+        when :unsupported
+          "session #{session_id}'s worker runs chi #{version || "(older)"}, which can't restart: " \
+            "#{stop}, then any prompt starts it on the newest chi"
+        when :fallback_held
+          why = holds.map { |hold| HOLDS.fetch(hold, hold.to_s.tr("_", " ")) }.join("; ")
+          "session #{session_id} has disk-visible work that a restart might lose#{": #{why}" unless why.empty?}; " \
+            "run `#{stop}`, then any prompt starts it on the newest chi"
+        when :failed then "session #{session_id}'s worker didn't take the restart"
+        else "not now: #{HOLDS.fetch(reason, reason.to_s.tr("_", " "))}"
+        end
+      end
+    end
+
+    # What a restart did: the worker's version before and after (nil when
+    # the new worker hadn't published its Bridge within the wait).
+    Restarted = Struct.new(:session_id, :from_version, :version, keyword_init: true)
+
+    RESTART_WAIT = 10.0
+    # A TERMed worker writes its recap on leave (an LLM call) while it still
+    # holds the lock: STOP_WAIT plus the recap's own wait (SessionContinue::RECAP_WAIT).
+    FALLBACK_STOP_WAIT = 40
+
+    STOP_CANCEL_WAIT = 3.0
+    # How long a stop from the CLI (chi sessions stop, delete, a continue's
+    # orphan) waits for the worker to let go of the session, here or
+    # through chi web (POST …/stop's wait, capped at it).
+    STOP_WAIT = 10
+    # The cancel reason of a turn a session stop cancels (Bridge::CANCEL_REASONS):
+    # not the user's Stop, which only ends the turn ("user").
+    STOP_CANCEL_REASON = "session_stopped"
+
+    # Lifecycle: stop a session's worker (TERM, then CONT) and restart it on
+    # the newest chi (its Bridge's POST /exit, else the fallback). Calls
+    # SpawnPart's resume_session and the facade's ownership checks. Meant to
+    # be loaded through samagotchi/session_manager.
+    module LifecyclePart
+      # Hand a session to a new worker on the newest chi installed: ask its
+      # worker (POST /exit restart: true), which leaves only when nothing would
+      # be lost and starts its successor. If the worker cannot be asked, stop
+      # it without a stop marker and resume only when disk shows no work to lose.
+      # @return [Restarted]
+      # @raise [OwnedByTUI] a one-turn chi run owns the session
+      # @raise [RestartRefused]
+      # @raise [ArgumentError] no such session
+      def restart_session(session_id, state_dir: nil, wait: RESTART_WAIT, client_id: ClientId::CLI_RESTART)
+        sd = state_dir || Session.default_state_dir
+        Session.load(session_id, state_dir: sd) # ArgumentError for none
+        owner = refuse_tui!(session_id, state_dir: sd)
+        # A stopped worker answers neither the ask (READ_TIMEOUT) nor the
+        # fallback's TERM (FALLBACK_STOP_WAIT): say so now, not after ~70 s.
+        raise RestartRefused.new(session_id, :stopped, pid: owner.pid) if owner&.worker? && ProcessGroup.stopped?(owner.pid)
+
+        dir = Session.session_dir(session_id, state_dir: sd)
+        link = WorkerLink.resolve(dir, unlink: false, owner: owner)
+        if link.is_a?(WorkerLink::Skew)
+          return restart_fallback(session_id, owner: owner, sidecar: link.sidecar, state_dir: sd, wait: wait, why: :skew)
+        end
+
+        if link.is_a?(WorkerLink::Starting)
+          return restart_fallback(session_id, owner: owner, sidecar: nil, state_dir: sd, wait: wait, why: :starting_stuck) if link.stuck
+
+          raise RestartRefused.new(session_id, :starting)
+        end
+        raise RestartRefused.new(session_id, :not_running) unless link.live?
+
+        sidecar = link.sidecar
+        unless sidecar.features.include?("restart")
+          raise RestartRefused.new(session_id, :unsupported, version: sidecar.version)
+        end
+
+        begin
+          reply = BridgeClient.for_sidecar(session_id, sidecar).request_exit(client_id: client_id, restart: true)
+        rescue SystemCallError, IOError => e
+          return restart_fallback(session_id, owner: owner, sidecar: sidecar, state_dir: sd, wait: wait, why: :unreachable,
+                                                                          error: e)
+        end
+        raise RestartRefused.new(session_id, reply.json&.fetch("reason", nil) || :failed) if reply.status == 409
+        if reply.secret_refused?
+          return restart_fallback(session_id, owner: owner, sidecar: sidecar, state_dir: sd, wait: wait, why: :bridge_secret)
+        end
+        raise RestartRefused.new(session_id, :failed) unless reply.status == 200
+
+        Log.info(:worker, "restart", sid: session_id, from: sidecar.version, by: client_id)
+        fresh = WorkerLink.await(session_id, session_dir: dir, timeout: wait, unlink: false, interval: 0.1,
+                                 until: ->(live) { live.epoch != sidecar.epoch || live.started_at != sidecar.started_at })
+        # Timed out: the last outcome, the old worker's Live too, is no successor.
+        changed = fresh.live? && (fresh.epoch != sidecar.epoch || fresh.started_at != sidecar.started_at)
+        version = fresh.version if changed
+        Restarted.new(session_id: session_id, from_version: sidecar.version, version: version)
+      end
+
+      private def restart_fallback(session_id, owner:, sidecar:, state_dir:, wait:, why:, error: nil)
+        Log.info(:worker, "restart_fallback", sid: session_id, why: why, error: error&.class&.name, msg: error&.message)
+        dir = Session.session_dir(session_id, state_dir: state_dir)
+        session = Session.load(session_id, state_dir: state_dir)
+        holds = restart_fallback_holds(session, dir)
+        raise RestartRefused.new(session_id, :fallback_held, holds: holds) unless holds.empty?
+        raise RestartRefused.new(session_id, :failed, version: sidecar&.version) unless (owner&.pid || 0).to_i.positive?
+
+        # The ask may have taken READ_TIMEOUT: TERM only the owner read at the
+        # start; a successor that took the lock meanwhile is awaited, not killed.
+        current = session_owner(session_id, state_dir: state_dir)
+        if current.nil?
+          resume_session(session_id, state_dir: state_dir)
+        elsif current.pid == owner.pid && current.started_at == owner.started_at
+          begin
+            Process.kill("TERM", owner.pid)
+          rescue Errno::ESRCH
+            nil
+          rescue SystemCallError => e
+            Log.warn(:worker, "restart_fallback_failed", sid: session_id, why: why, error: e.class.name, msg: e.message)
+            raise RestartRefused.new(session_id, :failed, version: sidecar&.version)
+          end
+          unless wait_for_owner_release(session_id, timeout: FALLBACK_STOP_WAIT, state_dir: state_dir)
+            raise RestartRefused.new(session_id, :failed, version: sidecar&.version)
+          end
+
+          resume_session(session_id, state_dir: state_dir)
+        end
+        previous_epoch = sidecar&.epoch
+        previous_started_at = sidecar&.started_at
+        fresh = WorkerLink.await(session_id, session_dir: dir, timeout: wait, unlink: false, interval: 0.1,
+                                 until: ->(live) { live.epoch != previous_epoch || live.started_at != previous_started_at })
+        changed = fresh.live? && (fresh.epoch != previous_epoch || fresh.started_at != previous_started_at)
+        Restarted.new(session_id: session_id, from_version: sidecar&.version, version: (fresh.version if changed))
+      end
+
+      private def restart_fallback_holds(session, session_dir)
+        holds = []
+        holds << :turn_running if session.status == Session::STATUS_RUNNING
+        holds << :question_pending if session.pending_question
+        holds << :input_queued unless SessionInbox.find_new_input_files(session_dir).empty?
+        holds << :background_tasks if running_created_task?(session)
+        holds
+      end
+
+      private def running_created_task?(session)
+        root = session.working_directory.to_s
+        return false if root.empty?
+
+        Tools::TaskRuntime.created_ids_in(session.messages).any? do |id|
+          next false unless Tools::TaskRuntime::TASK_ID.match?(id)
+
+          path = File.join(root, Tools::TaskRuntime::TASKS_DIR, id, Tools::TaskRuntime::METADATA_FILENAME)
+          next false unless File.file?(path)
+
+          Tools::TaskRecord.from_file(JSON.parse(File.read(path)))&.running?
+        rescue JSON::ParserError, SystemCallError => e
+          Log.warn(:worker, "restart_task_check_failed", sid: session.id, task_id: id,
+                                                             error: e.class.name, msg: e.message)
+          true
+        end
+      end
+
+      # Stop a session by sending TERM (then CONT, for a stopped one) to its process.
+      # With +wait+ (seconds), also wait for the owner to let go of the session,
+      # so a resume right after spawns a fresh worker instead of finding the
+      # dying one.
+      # A turn still running is canceled first (STOP_CANCEL_WAIT), as the
+      # web's Cancel does, with reason STOP_CANCEL_REASON: its worker saves it. The TERM stops (and saves)
+      # what still runs (WorkerSignals), with a short grace after the marker.
+      # @return [Boolean, nil] with +wait+: whether the owner was gone in time
+      # @raise [OwnedByTUI] when the interactive TUI owns the session
+      def stop_session(session_id, state_dir: nil, wait: nil)
+        sd = state_dir || Session.default_state_dir
+        owner = refuse_tui!(session_id, state_dir: sd)
+
+        cancel_running_turn(session_id, state_dir: sd)
+        # Mark first: a worker that has not taken the lock yet sees it and exits.
+        Session.mark_stopped(session_id, state_dir: sd)
+        # A stop drops the reminders: a restart's hand-off no successor took
+        # yet must not bring them back on the next resume.
+        ReminderCarry.remove(Session.session_dir(session_id, state_dir: sd))
+        pid = owner&.pid.to_i
+        begin
+          Process.kill("TERM", pid) if pid && pid > 0
+        rescue Errno::ESRCH
+          nil # already exited
+        end
+        continue_stopped(pid)
+        wait_for_owner_release(session_id, timeout: wait, state_dir: sd) if wait
+      end
+
+      # A stopped worker (SIGSTOP, Ctrl-Z) runs its TERM handler only once
+      # continued: CONT it after the TERM (as ProcessGroup.stop does), so it
+      # leaves now rather than outliving the stop's wait. Best effort: one the
+      # TERM ended may be gone already.
+      private def continue_stopped(pid)
+        Process.kill("CONT", pid) if pid && pid > 0
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      end
+
+      # Cancel the session's running turn over its Bridge and wait (up to
+      # STOP_CANCEL_WAIT) for the worker to save it. Best effort: without a
+      # live Bridge, or when it doesn't answer, the stop goes on as before.
+      private def cancel_running_turn(session_id, state_dir:)
+        return unless Session.load(session_id, state_dir: state_dir).status == Session::STATUS_RUNNING
+
+        client = WorkerLink.client(session_id, session_dir: Session.session_dir(session_id, state_dir: state_dir))
+        return unless client && client.cancel(reason: STOP_CANCEL_REASON).status == 202
+
+        BridgeClient.poll(STOP_CANCEL_WAIT) do
+          Session.load(session_id, state_dir: state_dir).status != Session::STATUS_RUNNING
+        end
+      rescue StandardError => e
+        Log.info(:worker, "stop_cancel_failed", sid: session_id, error: e.class.name, msg: e.message)
+        nil
+      end
+
+      # @return [Boolean] whether the session had no owner within +timeout+ seconds
+      def wait_for_owner_release(session_id, timeout:, state_dir:)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout.to_f
+        while session_owner(session_id, state_dir: state_dir)
+          return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          sleep(OwnerLock::RETRY_INTERVAL)
+        end
+        true
+      end
+    end
+
+    extend LifecyclePart
+  end
+end

data/lib/samagotchi/session_manager/listing.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class SessionManager
+    SUMMARY_DESC_LIMIT = 60
+
+    SUMMARY_PREVIEW_LIMIT = 120
+
+    # 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 (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<Hash>] {id:, short_id:, desc:, preview:, cwd:, project:,
+      #   updated_at:, status:, saved_status:, live:, busy:, owner:, recap:, auto_title:, parent_id:,
+      #   parent_short_id:, continues:, continues_short_id:, delegate:, archived:, scratch:, test_run:, waiting:,
+      #   waiting_id:, stopped_by:}; status = Session#displayed_status (a dead
+      #   worker's "running" is idle, as chi web shows it), saved_status = the
+      #   file's (a "running" with no owner yet is also a worker on its way:
+      #   Tools::Delegate.running?), busy =
+      #   live with a turn running, delegate = started by the delegate tool
+      #   (Session#delegate?; a fork has a parent_id but isn't one), continues = the session it continues (the
+      #   previous link of its chain, Session#continues), recap = the saved recap's first sentence, auto_title =
+      #   the auto title its reply led with (RecapTitle) or nil, project =
+      #   Session#project_root, waiting = the kind of question it waits on
+      #   ("question", "approval", "hook"; Session#waiting_question) or nil,
+      #   waiting_id = that question's id or nil, relayed_to = the parent
+      #   whose card it waits in too (the approval relay), its short id, or nil,
+      #   stopped_by = the hook that stopped the last turn (Session#stopped_by)
+      def session_summaries(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 = listing_budgets
+        summaries = 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|
+          owner = session_owner(s.id, state_dir: sd)
+          owned = !!owner&.worker?
+          next if live && !owned
+
+          { id: s.id, short_id: s.id[0, 8], desc: summary_desc(s), preview: summary_preview(s), title: s.title, cwd: s.working_directory,
+            project: s.project_root(cache: roots), updated_at: s.updated_at, status: s.displayed_status(owner: owner), saved_status: s.status, live: owned, busy: owned && s.status == Session::STATUS_RUNNING,
+            owner: owner&.kind, **recap_fields(Session.session_dir(s.id, state_dir: sd)),
+            ctx_pct: SessionMetrics.saved_context_pct(Session.session_dir(s.id, state_dir: sd),
+                                                      budget_tokens: -> { budgets.call(s) })&.round(1),
+            parent_id: s.parent_id, parent_short_id: s.parent_id&.[](0, 8), continues: s.continues,
+            continues_short_id: s.continues&.[](0, 8), delegate: s.delegate?, archived: s.archived,
+            scratch: s.scratch, test_run: s.test_run, stopped_by: s.stopped_by }.merge(waiting_fields(s.waiting_question(live: owned)))
+        end
+        (limit ? summaries.first(limit) : summaries.to_a)
+      end
+
+      # waiting: the question's kind, waiting_id: its id (what chi answer
+      # --question takes); both nil with none.
+      private def waiting_fields(waiting)
+        { waiting: waiting&.dig(:kind), waiting_id: waiting&.dig(:id), relayed_to: waiting&.dig(:relayed_to) }
+      end
+
+      # One HostRegistry for a whole listing, built on the first row that
+      # needs it (a saved context to count) and kept for the rest: resolving a
+      # session's llm_context budget reads config.yml (mtime-cached), so not
+      # one registry per row.
+      # @return [#call] (session) -> the session's budget in tokens or nil
+      private def listing_budgets
+        registry = nil
+        ->(session) { LLMContextStrategy.session_budget(session, registry: registry ||= HostRegistry.new) }
+      end
+
+      # The sessions delegated by +parent_id+ (the `delegate` tool), newest
+      # first, as .session_summaries rows. A running one (busy) counts against
+      # session.max_children. Archived ones too.
+      def children_of(parent_id, state_dir: nil)
+        return [] if parent_id.to_s.empty?
+
+        session_summaries(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
+
+      # "<cwd basename> · <last prompt, or the first preview>", one line.
+      private def summary_desc(session)
+        desc = [File.basename(session.working_directory.to_s), summary_text(session)].reject(&:empty?).join(" · ")
+        cut(desc, SUMMARY_DESC_LIMIT)
+      end
+
+      # A session row's recap: and auto_title: (RecapStore.card, one read).
+      private def recap_fields(session_dir)
+        card = RecapStore.card(session_dir)
+        { recap: card.preview, auto_title: card.title }
+      end
+
+      private def summary_preview(session)
+        cut(summary_text(session), SUMMARY_PREVIEW_LIMIT)
+      end
+
+      # A session as one line of text for the lists: its title (/title), else
+      # its last prompt, else the first message it was started with (a session
+      # command like `/model x`, or a first turn not saved yet).
+      def summary_text(session)
+        return one_line(session.title) unless session.title.to_s.strip.empty?
+
+        one_line(session.last_prompt.to_s.strip.empty? ? session.first_preview.to_s : session.last_prompt.to_s)
+      end
+
+      # A prompt as one line for a session list: whitespace collapsed, and a
+      # quoted or annotated message (ContextQuote, the web's annotations)
+      # without its "> " markers, so the words show.
+      def one_line(text)
+        text.to_s.gsub(/^[ \t]*(?:>[ \t]?)+/, "").gsub(/\s+/, " ").strip
+      end
+
+      private def cut(text, limit)
+        text.length > limit ? "#{text[0, limit - 1]}…" : text
+      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