samagotchi 0.2.0 → 0.4.0

data/lib/samagotchi/session.rb

@@ -8,6 +8,9 @@ require "time"
 require_relative "project_scope"
 
 module Samagotchi
+  # archive_store requires this file.
+  autoload :ArchiveStore, File.expand_path("archive_store", __dir__)
+
   class Session
     METADATA_VERSION = 3
     STATE_SUBDIR = File.join("samagotchi", "sessions")
@@ -44,6 +47,17 @@ module Samagotchi
     # plugin forked it from (ctx.sessions.fork), else nil.
     # Set before the spawn and kept on respawns, like preloaded_memory_names.
     attr_accessor :parent_id
+    # A `chi scratch` session: deleted when its REPL ends, and by the next
+    # sweep (or `chi sessions clean`) when the process died first.
+    attr_accessor :scratch
+    # How the last turn ended, for the web's notifications (the hub sends
+    # it in the summary): {"outcome" => "completed"|"failed"|"canceled",
+    # "ended_at" => iso8601, "seconds" => Float, "origin" =>
+    # "client"|"reminder"|"delegate"}; nil before the first turn.
+    attr_accessor :last_turn
+    # Archived (ArchiveStore): hidden from the lists. Set by .list (with
+    # include_archived); not saved in session.json.
+    attr_accessor :archived
 
     # How many image refs a fork's seed lost (SessionManager.spawn_session
     # sets it); not saved.
@@ -53,7 +67,8 @@ module Samagotchi
                    metadata_version: METADATA_VERSION, status: STATUS_IDLE, last_prompt: "",
                    first_preview: "", test_run: false, pending_question: nil,
                    used_memory_names: [], project_root: nil,
-                   preloaded_memory_names: [], muted_memory_names: [], parent_id: nil)
+                   preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
+                   last_turn: nil)
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -72,6 +87,9 @@ module Samagotchi
       @muted_memory_names = self.class.name_list(muted_memory_names)
       @project_root = project_root
       @parent_id = parent_id&.to_s
+      @scratch = !!scratch
+      @last_turn = last_turn
+      @archived = false
     end
 
     # The stored project root, else (a file from before the field) the
@@ -92,7 +110,8 @@ module Samagotchi
     # @param messages [Array<Hash>] a conversation to start from (a fork's
     #   seed); [] by default
     def self.new_session(mode:, model_name:, working_directory:, test_run: nil,
-                         preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, messages: [])
+                         preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, messages: [],
+                         scratch: false)
       now = Time.now.iso8601(3)
       resolved_test = if test_run.nil?
                         test_session_env?
@@ -113,7 +132,8 @@ module Samagotchi
         project_root: ProjectScope.root_for(working_directory),
         preloaded_memory_names: preloaded_memory_names,
         muted_memory_names: muted_memory_names,
-        parent_id: parent_id
+        parent_id: parent_id,
+        scratch: scratch
       )
     end
 
@@ -154,7 +174,9 @@ module Samagotchi
         project_root: data["project_root"],
         preloaded_memory_names: Array(data["preloaded_memory_names"]),
         muted_memory_names: Array(data["muted_memory_names"]),
-        parent_id: data["parent_id"]
+        parent_id: data["parent_id"],
+        scratch: data.fetch("scratch", false),
+        last_turn: data["last_turn"]
       )
     rescue JSON::ParserError => e
       raise ArgumentError, "Session file corrupted (#{session_id}): #{e.message}"
@@ -186,14 +208,19 @@ module Samagotchi
     # Supports sort: created_at|updated_at and order: asc|desc.
     # +project_root+ keeps only that project's sessions (Session#project_root),
     # before offset/limit so pages count within the project.
+    # Archived sessions (ArchiveStore) are left out unless +include_archived+;
+    # everything built on .list follows (the lists, the summaries, the
+    # retention prune, which then neither deletes nor counts them).
     def self.list(state_dir: default_state_dir, sort: "updated_at", order: "desc", limit: nil, offset: 0,
-                  project_root: nil)
+                  project_root: nil, include_archived: false)
       return [] unless Dir.exist?(state_dir)
 
       sort_key = SORT_KEYS.include?(sort.to_s) ? sort.to_s : "updated_at"
       sort_order = SORT_ORDERS.include?(order.to_s) ? order.to_s : "desc"
 
       sessions = Dir.glob(File.join(state_dir, "*#{FILE_EXT}")).filter_map { |path| summary_from_file(path) }
+      sessions.each { |s| s.archived = ArchiveStore.archived?(session_dir(s.id, state_dir: state_dir)) }
+      sessions.reject!(&:archived) unless include_archived
       if project_root
         roots = {}
         sessions.select! { |s| s.project_root(cache: roots) == project_root }
@@ -225,6 +252,7 @@ module Samagotchi
     def self.summary_from_file(path)
       data = JSON.parse(File.read(path))
       used_mems = data["used_memory_names"] || data["used_memories"] || []
+      pending = data["pending_question"]
       new(
         id: data.fetch("id"),
         metadata_version: data.fetch("metadata_version", 1),
@@ -238,11 +266,14 @@ module Samagotchi
         last_prompt: data.fetch("last_prompt", ""),
         first_preview: data.fetch("first_preview", ""),
         test_run: data.fetch("test_run", false),
+        pending_question: pending.is_a?(Hash) ? symbolize_message_keys(pending) : nil,
         used_memory_names: Array(used_mems),
         project_root: data["project_root"],
         preloaded_memory_names: Array(data["preloaded_memory_names"]),
         muted_memory_names: Array(data["muted_memory_names"]),
-        parent_id: data["parent_id"]
+        parent_id: data["parent_id"],
+        scratch: data.fetch("scratch", false),
+        last_turn: data["last_turn"]
       )
     rescue JSON::ParserError, KeyError, SystemCallError
       nil
@@ -261,6 +292,12 @@ module Samagotchi
     # +any_age+ makes every session eligible, whatever its age and the
     # count (`chi sessions clean` with no --days: test runs are throwaway).
     #
+    # A scratch session nobody owns (its REPL was killed) goes whatever its
+    # age, its status and the count; +test_only+ takes it too.
+    #
+    # Archived sessions are not in .list, so they are neither deleted nor
+    # counted. One unarchived is aged from when it was unarchived, if later.
+    #
     # @return [Hash] { deleted: [ids], kept: [ids], skipped: [ids] }
     def self.prune(state_dir: 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,
@@ -270,7 +307,7 @@ module Samagotchi
       all = list(state_dir: state_dir, sort: "updated_at", order: "desc")
       # Filter test_only if requested
       if test_only
-        all = all.select(&:test_run)
+        all = all.select { |session| session.test_run || session.scratch }
       end
 
       now = Time.now
@@ -290,7 +327,7 @@ module Samagotchi
         end
 
         # Protected by keep_status
-        if keep_status.include?(session.status.to_s)
+        if keep_status.include?(session.status.to_s) && !session.scratch
           kept << session.id
           next
         end
@@ -321,19 +358,21 @@ module Samagotchi
           rescue ArgumentError
             updated = File.mtime(path) rescue now
           end
+          unarchived = ArchiveStore.unarchived_at(session_dir(session.id, state_dir: state_dir))
+          updated = unarchived if unarchived && unarchived > updated
           expired = updated < cutoff
         end
 
         overflow = max.positive? && idx >= max
 
         # retain forever when both disabled
-        if max.zero? && cutoff.nil? && !left_empty && !any_age
+        if max.zero? && cutoff.nil? && !left_empty && !any_age && !session.scratch
           kept << session.id
           next
         end
 
         # If neither expired nor overflow, keep
-        unless expired || overflow || left_empty || any_age
+        unless expired || overflow || left_empty || any_age || session.scratch
           kept << session.id
           next
         end
@@ -387,7 +426,9 @@ module Samagotchi
         "project_root" => @project_root,
         "preloaded_memory_names" => Array(@preloaded_memory_names),
         "muted_memory_names" => Array(@muted_memory_names),
-        "parent_id" => @parent_id
+        "parent_id" => @parent_id,
+        "scratch" => @scratch,
+        "last_turn" => @last_turn
       }
 
       File.write(temp_path, JSON.pretty_generate(record) + "\n")

data/lib/samagotchi/session_archive_command.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "session"
+require_relative "session_manager"
+
+module Samagotchi
+  # `chi sessions archive|unarchive`: hide sessions from every list and keep
+  # them for good, or bring them back (SessionManager.archive_session /
+  # unarchive_session), one line per id. Delegated children follow their
+  # parent.
+  class SessionArchiveCommand
+    USAGE = {
+      "archive" => <<~TEXT,
+        Usage: chi sessions archive (ID|PREFIX)...
+          Hides each session (and its delegates) from every list and keeps it
+          for good: the retention sweep never deletes it. A live worker is
+          stopped first; a session running a turn, or open in a chi REPL, is
+          refused. chi sessions list --archived shows them; a message you send
+          to one brings it back.
+      TEXT
+      "unarchive" => <<~TEXT
+        Usage: chi sessions unarchive (ID|PREFIX)...
+          Brings archived sessions (and their delegates) back to the lists.
+      TEXT
+    }.freeze
+
+    # @param action [String] "archive" or "unarchive"
+    # @param argv [Array<String>] the arguments after "sessions <action>"
+    def initialize(action, argv, stdout: $stdout, stderr: $stderr, state_dir: nil)
+      @action = action
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @state_dir = state_dir || Session.default_state_dir
+    end
+
+    # @return [Integer] exit status: 0 all done, 1 any refused or unknown, 2 usage
+    def run
+      if @argv.any? { |arg| %w[-h --help help].include?(arg) }
+        @stdout.puts(USAGE.fetch(@action))
+        return 0
+      end
+      bad = @argv.find { |arg| arg.start_with?("-") }
+      return usage_error(bad ? "unknown option #{bad}" : "give session ids") if bad || @argv.empty?
+
+      @argv.uniq.map { |given| @action == "archive" ? archive(given) : unarchive(given) }.all? ? 0 : 1
+    end
+
+    private
+
+    def archive(given)
+      id = Session.resolve_id(given, state_dir: @state_dir)
+      short = id[0, 8]
+      result = SessionManager.archive_session(id, state_dir: @state_dir)
+      if result[:archived].include?(id)
+        notes = []
+        notes << "stopped its worker" if result[:stopped].include?(id)
+        others = result[:archived].size - 1
+        notes << "and #{others} delegate#{"s" if others != 1}" if others.positive?
+        @stdout.puts("#{short}  archived#{" (#{notes.join(", ")})" unless notes.empty?}")
+      else
+        @stdout.puts("#{short}  empty session discarded")
+      end
+      true
+    rescue SessionManager::OwnedByTUI => e
+      where = e.session_id == id ? "it is" : "a delegate of it is"
+      @stdout.puts("#{short}  refused: #{where} open in a chi REPL; close it there first")
+      false
+    rescue SessionManager::ArchiveRefused => e
+      @stdout.puts("#{short}  refused: #{e.message}")
+      false
+    rescue ArgumentError => e
+      error_line("chi sessions archive: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      false
+    rescue SystemCallError => e
+      @stdout.puts("#{short}  failed: #{e.message}")
+      false
+    end
+
+    def unarchive(given)
+      id = Session.resolve_id(given, state_dir: @state_dir)
+      short = id[0, 8]
+      result = SessionManager.unarchive_session(id, state_dir: @state_dir)
+      @stdout.puts(result[:unarchived].empty? ? "#{short}  not archived" : "#{short}  unarchived")
+      true
+    rescue ArgumentError => e
+      error_line("chi sessions unarchive: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      false
+    rescue SystemCallError => e
+      @stdout.puts("#{short}  failed: #{e.message}")
+      false
+    end
+
+    # stdout is buffered when it's a pipe: flush the lines already printed,
+    # so the output keeps the order of the ids given.
+    def error_line(text)
+      @stdout.flush
+      @stderr.puts(text)
+    end
+
+    def usage_error(message)
+      error_line("chi sessions #{@action}: #{message}")
+      @stderr.puts(USAGE.fetch(@action))
+      2
+    end
+  end
+end

data/lib/samagotchi/session_commands.rb

@@ -15,8 +15,10 @@ module Samagotchi
   # the Engine and its TurnFlow; the host prints the result's output and
   # runs a continue turn when asked to (#run never runs a turn).
   #
-  # /stats, /recap and /exit are the UI's own: they are in the registry
-  # (local: for Tab and help) but #run never runs them.
+  # /stats, /recap, /exit, /quit, /archive and /detach are the terminal
+  # UIs' own: they are in the registry (local:) for Tab and help, and so
+  # both TUIs read the same words (Registry#lookup_local gives the entry,
+  # its id says what to do), but #run never runs them.
   class SessionCommands
     MODEL_COMMAND = "/model"
     MODELS_COMMAND = "/models"
@@ -30,6 +32,8 @@ module Samagotchi
     SHELL_BANG_PREFIX = "!"
     RESERVED_MODEL_ARGS = %w[clear default none off].freeze
     ALIAS_USAGE = "usage /model <model> --alias <name> [--default]"
+    # /exit --delete: delete the session on the way out.
+    EXIT_DELETE_FLAG = "--delete"
 
     # @!attribute status [Symbol] :ok, or :error when the line was refused
     # @!attribute output [String, nil] what to tell the user
@@ -66,12 +70,28 @@ module Samagotchi
       registry.register(HELP_COMMAND, "list the commands, the bundles' too", anytime: true) { |_text| reply(help_listing) }
       registry.register("/stats", "show the session's stats", local: true)
       registry.register("/recap", "show the session's recap", local: true)
-      registry.register("/exit", "leave (--delete also deletes the session)", local: true)
-      registry.register("/quit", "leave, like /exit", local: true, uis: [:attached])
-      registry.register("/detach", "leave and keep the worker running", local: true, uis: [:attached])
+      # Bare `exit` too; any case; --delete after it.
+      registry.register("/exit", "leave (--delete also deletes the session)", local: true,
+                                                                              match: exit_match("/?exit"))
+      registry.register("/quit", "leave, like /exit", id: :exit, local: true, match: exit_match("/quit"))
+      registry.register("/archive", "leave and archive the session: hidden from the lists, kept for good", local: true,
+                                                                                                          match: ->(text) { text.casecmp?("/archive") })
+      # The REPL owns its session: it answers /detach with a note, and doesn't offer it.
+      registry.register("/detach", "leave and keep the worker running", local: true, uis: [:attached],
+                                                                        match: ->(text) { text.casecmp?("/detach") })
       registry
     end
 
+    # @param word [String] the regexp source of the exit word
+    def self.exit_match(word)
+      pattern = /\A#{word}(?:\s+#{EXIT_DELETE_FLAG})?\z/i
+      ->(text) { text.match?(pattern) }
+    end
+    private_class_method :exit_match
+
+    # @return [Boolean] an exit line (/exit, /quit, exit) that deletes the session too
+    def self.delete_on_exit?(line) = line.to_s.split.last.to_s.casecmp?(EXIT_DELETE_FLAG)
+
     # The built-ins alone, for callers without an Engine (an attached TUI
     # before its snapshot names the session's commands, specs).
     # @return [Commands::Registry] frozen
@@ -276,15 +296,18 @@ module Samagotchi
     def model(text)
       output, switched = model_command(text)
       reply(output, changed: switched ? [:model] : [])
+    rescue ModelProfile::MissingModel => e
+      # A model qualified with an unknown host: nothing switched.
+      reply(e.message, status: :error)
     end
 
     # @return [Array(String, Boolean)] the message, and whether the model changed
     def model_command(input)
       suffix = input.delete_prefix(MODEL_COMMAND).strip
       if suffix.empty?
-        return ["runtime model: #{model_name}#{model_note}#{served_note}", false] if model_name == @default_model
+        return ["runtime model: #{model_name}#{model_note}#{served_note}#{sampling_note}#{thinking_note}", false] if model_name == @default_model
 
-        return ["runtime model: #{model_name}#{model_note("default: #{@default_model}")}#{served_note}", false]
+        return ["runtime model: #{model_name}#{model_note("default: #{@default_model}")}#{served_note}#{sampling_note}#{thinking_note}", false]
       end
 
       # Parse flags: --default and --alias <name> / --alias=<name> (tolerant order)
@@ -411,6 +434,22 @@ module Samagotchi
       ""
     end
 
+    # "; sampling: temperature=0.6 (hosts.work)" when the model has any.
+    def sampling_note
+      summary = @engine.respond_to?(:sampling_summary) ? @engine.sampling_summary : nil
+      summary ? "; sampling: #{summary}" : ""
+    rescue StandardError
+      ""
+    end
+
+    # "; thinking: off (models: qwen)" when the model has a level set.
+    def thinking_note
+      summary = @engine.respond_to?(:thinking_summary) ? @engine.thinking_summary : nil
+      summary ? "; thinking: #{summary}" : ""
+    rescue StandardError
+      ""
+    end
+
     # " (default: x, profile=qwen36, name)": +extra+ and the prompt profile,
     # which a chat host's model doesn't have (its loop uses none); "" when
     # there is neither.

data/lib/samagotchi/session_manager.rb

@@ -8,6 +8,7 @@ require "securerandom"
 require "rbconfig"
 
 require_relative "session"
+require_relative "session_metrics"
 require_relative "turn_note"
 require_relative "owner_lock"
 require_relative "bridge_client"
@@ -15,6 +16,7 @@ require_relative "log"
 require_relative "log_path"
 require_relative "installed_gem"
 require_relative "recap_store"
+require_relative "archive_store"
 require_relative "image_store"
 require_relative "terminal_ui"
 
@@ -73,7 +75,12 @@ module Samagotchi
     # Raised when the interactive TUI owns the session: it runs its own Engine
     # and reads no input files, so a worker must not be spawned or signalled.
     class OwnedByTUI < StandardError
+      # @return [String] the session the REPL owns (a delegate's, when an
+      #   archive met one)
+      attr_reader :session_id
+
       def initialize(session_id)
+        @session_id = session_id
         super("session #{session_id} is owned by an interactive TUI")
       end
     end
@@ -95,6 +102,29 @@ module Samagotchi
       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"
+        else "a turn is running; wait for it or cancel it first"
+        end
+      end
+    end
+
     # Spawn a new background session that processes the given prompt (or,
     # with none, waits idle for input).
     #
@@ -118,7 +148,7 @@ module Samagotchi
       sd = state_dir || Session.default_state_dir
       session = Session.new_session(
         mode: mode,
-        model_name: model_name || Samagotchi::ModelProfile.required_model_name,
+        model_name: Samagotchi::ModelProfile.check_host!(Samagotchi::ModelProfile.required_model_name(model_name)),
         working_directory: working_directory || Dir.pwd,
         preloaded_memory_names: memories,
         muted_memory_names: muted_memories,
@@ -190,9 +220,11 @@ module Samagotchi
 
     # List all sessions, reading status from persisted session.json files.
     # +project_root+: only that project's sessions (nil: every session).
-    def self.list_sessions(state_dir: nil, sort: "updated_at", order: "desc", limit: nil, offset: 0, project_root: nil)
+    # +include_archived+: archived sessions too (Session#archived says which).
+    def self.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)
+                   offset: offset, project_root: project_root, include_archived: include_archived)
     end
 
     # Prune sessions per retention policy. Delegates to Session.prune with live-worker guard.
@@ -211,17 +243,19 @@ module Samagotchi
     # @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:, live:, busy:, owner:, recap:, parent_id:,
-    #   parent_short_id:}; busy = live with
+    #   parent_short_id:, archived:, scratch:}; busy = live with
     #   a turn running, recap = the saved recap's first sentence, project =
     #   Session#project_root
     def self.session_summaries(live: false, cwd: nil, limit: nil, include_tests: true, exclude: nil, state_dir: nil,
-                               project_root: nil)
+                               project_root: nil, include_archived: false)
       sd = state_dir || Session.default_state_dir
       root = cwd && folder_path(cwd)
       roots = {}
-      summaries = Session.list(state_dir: sd, sort: "updated_at", order: "desc", project_root: project_root).lazy
+      summaries = Session.list(state_dir: sd, sort: "updated_at", 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|
@@ -232,18 +266,89 @@ module Samagotchi
         { id: s.id, short_id: s.id[0, 8], desc: summary_desc(s), preview: summary_preview(s), cwd: s.working_directory,
           project: s.project_root(cache: roots), updated_at: s.updated_at, status: s.status, live: owned, busy: owned && s.status == Session::STATUS_RUNNING,
           owner: owner, recap: RecapStore.preview(Session.session_dir(s.id, state_dir: sd)),
-          parent_id: s.parent_id, parent_short_id: s.parent_id&.[](0, 8) }
+          ctx_pct: SessionMetrics.saved_context_pct(Session.session_dir(s.id, state_dir: sd))&.round(1),
+          parent_id: s.parent_id, parent_short_id: s.parent_id&.[](0, 8), archived: s.archived,
+          scratch: s.scratch }
       end
       (limit ? summaries.first(limit) : summaries.to_a)
     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.
+    # session.max_children. Archived ones too.
     def self.children_of(parent_id, state_dir: nil)
       return [] if parent_id.to_s.empty?
 
-      session_summaries(state_dir: state_dir, include_tests: true).select { |s| s[:parent_id] == parent_id.to_s }
+      session_summaries(state_dir: state_dir, include_tests: true, include_archived: true)
+        .select { |s| s[:parent_id] == parent_id.to_s }
+    end
+
+    # 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 [Hash] {id:, archived: [ids], stopped: [ids], discarded: [ids]};
+    #   discarded: empty sessions their stopping worker deleted
+    # @raise [ArgumentError] unknown id (Session::AmbiguousId for a prefix of several)
+    # @raise [OwnedByTUI] a chi REPL owns it or one of its children
+    # @raise [ArchiveRefused] a turn runs in it or in a child, or it is a
+    #   scratch session
+    def self.archive_session(id_or_prefix, state_dir: nil, wait: 5)
+      sd = state_dir || Session.default_state_dir
+      id = archive_target(id_or_prefix, sd)
+      raise ArchiveRefused.new(id, :scratch) if Session.load(id, state_dir: sd).scratch
+
+      tree = [id, *descendant_ids(id, sd)]
+      owners = tree.to_h { |sid| [sid, session_owner(sid, state_dir: sd)] }
+      tree.each do |sid|
+        owner = owners[sid]
+        next unless owner
+
+        raise OwnedByTUI, sid if owner["kind"] == "tui"
+        next unless Session.load(sid, state_dir: sd).status == Session::STATUS_RUNNING
+
+        raise ArchiveRefused.new(id, sid == id ? :busy : :busy_child, busy_id: sid)
+      end
+
+      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) }
+      { id: id, archived: archived, stopped: stopped, discarded: discarded }
+    end
+
+    # Unarchive a session and its delegated children.
+    # @return [Hash] {id:, unarchived: [ids that were archived]}
+    # @raise [ArgumentError] unknown id
+    def self.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_class_method def self.archive_target(id_or_prefix, state_dir)
+      given = id_or_prefix.to_s
+      raise ArgumentError, "no session #{given}" unless given.match?(/\A[\w-]+\z/)
+
+      id = Session.resolve_id(given, state_dir: state_dir)
+      raise ArgumentError, "no session #{given}" unless Session.exist?(id, state_dir: state_dir)
+
+      id
+    end
+
+    # Children, their children, …: a delegated session doesn't delegate
+    # further today, a plugin's fork may.
+    private_class_method def self.descendant_ids(id, state_dir)
+      seen = [id]
+      queue = [id]
+      until queue.empty?
+        children_of(queue.shift, state_dir: state_dir).each do |child|
+          next if seen.include?(child[:id])
+
+          seen << child[:id]
+          queue << child[:id]
+        end
+      end
+      seen.drop(1)
     end
 
     SUMMARY_PREVIEW_LIMIT = 120
@@ -534,7 +639,7 @@ module Samagotchi
         if EMPTY_SKELETON_DIRS.include?(name)
           File.directory?(path) && (!EMPTY_DIRS.include?(name) || Dir.children(path).empty?)
         elsif name == "analytics.json"
-          JSON.parse(File.read(path))["turns"].to_i.zero?
+          Array(JSON.parse(File.read(path))["turn_records"]).empty?
         else
           EMPTY_SKELETON_FILES.include?(name)
         end
@@ -592,21 +697,6 @@ module Samagotchi
       true
     end
 
-    # Wait for a session to reach a terminal state (completed, error, stopped).
-    # Returns true if the session finished, false if the timeout elapsed.
-    def self.wait_for_session(session_id, timeout: 30, state_dir: nil)
-      sd = state_dir || Session.default_state_dir
-      elapsed = 0
-      while elapsed < timeout
-        session = Session.load(session_id, state_dir: sd)
-        return true if %w[completed error stopped].include?(session.status)
-
-        sleep(0.5)
-        elapsed += 0.5
-      end
-      false
-    end
-
     # Run the session loop inside the forked process.
     # This is the entry point called by Process.spawn.
     #