samagotchi 0.155.0 → 0.157.0

data/lib/samagotchi/session_manager/delivery.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class SessionManager
+    # How long a turn waits for the Bridge of a worker a resume just spawned.
+    TURN_BRIDGE_WAIT = 5.0
+
+    # What #deliver_turn did with a message.
+    # +status+ :accepted; :refused (the Bridge refused it, or a queue would
+    # reach a worker that doesn't queue); :timeout (the Bridge took it and
+    # never answered); :failed (the input file couldn't be written).
+    # +via+ :bridge (the worker's Bridge answered) or :file (the input-file
+    # fallback); nil when nothing went in.
+    # +ack+ the Bridge's reply body, or the file's {"status", "enqueued_id",
+    # "session_id"}: string keys either way, {} for none.
+    # +code+ a refusal's HTTP status.
+    DeliverResult = Data.define(:status, :via, :ack, :code) do
+      def initialize(status:, via: nil, ack: {}, code: nil) = super(status:, via:, ack: ack || {}, code:)
+
+      def accepted? = status == :accepted
+
+      # Sent as an input file (no Bridge): its turn and outcome carry the
+      # file's enqueued_id, which a wait follows (chi send --wait).
+      def file? = via == :file
+
+      # @return [String, nil] the id the message's turn will carry
+      def enqueued_id
+        id = ack["enqueued_id"].to_s
+        id.empty? ? nil : id
+      end
+
+      # Whether the worker took the line as a session command (a POST /turn
+      # answered with its command_id).
+      def command? = !ack["command_id"].to_s.empty?
+
+      def error = ack["error"]
+
+      def detail = ack["detail"]
+
+      # What the worker applied (a Bridge ack only): the delivery asked for,
+      # or next_step for a --queue that found no turn running; nil from the
+      # input file or a worker older than delivery.
+      def delivery = ack["delivery"]
+
+      # A --cut's outcome ("now", "waits", "off"), nil when nothing was cut.
+      def cut = ack["cut"]
+
+      # The steer cut-after seconds, with a cut that waits only.
+      def cut_after = ack["cut_after"]
+    end
+
+    # The unclaimed input files +author+ wrote.
+    PARTICIPANT_QUEUE_LOCK = "participants.lock"
+
+    # Delivery: a user message into a session, the way a UI sends one (its
+    # Bridge, else the input file). Calls SpawnPart's resume_session and the
+    # facade's session_owner through +manager+ (this class by default).
+    # Meant to be loaded through samagotchi/session_manager.
+    module DeliveryPart
+      # Write a user turn into a session's input directory via the same file IPC
+      # the worker polls. Reused by the bridge's POST surface so a turn is
+      # fire-and-forget and never calls run_turn across the thread/process
+      # boundary. The file is JSON carrying the sender's ids.
+      # @param client_id [String, nil] the sending UI
+      # @param enqueued_id [String, nil] the id its ACK / :turn_enqueued carry
+      # @param delivery [String, nil] the wire value: "next_step" (default),
+      #   "cut" or "queue"
+      # @param images [Array<Hash>] image refs ({file:, name:}) in the
+      #   session's images/
+      # @return [String, false] the input file's path, or false.
+      def write_turn_input(session_id, prompt:, client_id: nil, enqueued_id: nil, no_interrupt: false, state_dir: nil,
+                           images: [], delivery: nil, author: nil, anchors: nil)
+        session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
+        SessionInbox.write_input(session_dir, prompt: prompt, client_id: client_id, enqueued_id: enqueued_id,
+                                              no_interrupt: no_interrupt, images: images, delivery: delivery, author: author,
+                                              anchors: anchors)
+      end
+
+      # Hand a user message to the session the way a UI does, for the web
+      # composer and `chi send` alike: wakes the worker when none runs, posts
+      # through its Bridge so every live UI sees :turn_enqueued, and falls back
+      # to the input file when the Bridge is gone (a worker closing it on idle
+      # exit). Race-safe against a TUI taking the session, or the worker
+      # exiting, between the resume and the write.
+      # @param images [Array<Hash>] refs ({file:, name:}) already in images/
+      # @param delivery [String, nil] what the message asks the running turn
+      #   for: "next_step" (default), "cut" or "queue"
+      # @param no_interrupt [Boolean] the turn runs with the raised iteration
+      #   limit (an attached TUI's --no-interrupt), through the Bridge or the
+      #   file; sent only when true, so older callees see no new field
+      # @param author [String, nil] who wrote it when it isn't the session's
+      #   owner (Web::Principal#author: chi web stamps it, never the body);
+      #   to the Bridge or the file only when given, so an owner's turn is
+      #   sent and saved as before
+      # @param pending_limit [Integer, nil] with +author+: how many of their
+      #   turns may be running or waiting (the Bridge counts them; with no
+      #   worker, their waiting files): :refused 429 too_many_turns past it
+      # @param anchors [TurnAnchors, Hash, nil] a Verify turn's claim, a Revise
+      #   turn's draft: each refused (409, its UNAVAILABLE) by a worker without
+      #   its feature
+      # @param manager [#resume_session, #write_turn_input] this class, or a
+      #   stand-in (the web's specs); #session_owner is optional
+      # @param bridge [#call, nil] returns the BridgeClient or nil; defaults to
+      #   the session's sidecar, waiting TURN_BRIDGE_WAIT for a new worker's
+      # @return [DeliverResult] :accepted (via the Bridge or a file),
+      #   :refused when the Bridge refused the request (any 4xx with an
+      #   error: bad images, a delivery it doesn't run) or a queue would reach
+      #   a worker that doesn't queue (no file then: it would steer), :timeout
+      #   when it took the request but never answered (no file then), or
+      #   :failed when the input file couldn't be written
+      # @raise [OwnedByTUI] a one-turn chi run owns the session
+      # @raise [ArgumentError] no such session
+      def deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, no_interrupt: false,
+                       author: nil, pending_limit: nil, anchors: nil, state_dir: nil, manager: self, bridge: nil)
+        anchors = TurnAnchors.from(anchors)
+        session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
+        bridge ||= lambda do
+          link = WorkerLink.await(session_id, session_dir: session_dir, timeout: TURN_BRIDGE_WAIT)
+          link.live? ? link.client(session_id) : nil
+        end
+        manager.resume_session(session_id, state_dir: state_dir)
+        if (client = bridge.call)
+          if (missing = anchors.present.find { |anchor| !worker_has?(client, anchor.class::FEATURE) })
+            return DeliverResult.new(status: :refused, code: 409, ack: missing.class::UNAVAILABLE)
+          end
+          # A worker from before queueing (no "delivery" feature) ignores the
+          # field or refuses it; either way a file would steer the running turn.
+          return queue_unavailable if Delivery.queue?(delivery) && !worker_has?(client, Delivery::QUEUE_FEATURE)
+          # A participant's turn only to a worker with the review boundary.
+          return review_unavailable if Steer.participant_author?(author) && !worker_has?(client, Delivery::REVIEW_FEATURE)
+
+          begin
+            options = { prompt: prompt, client_id: client_id }
+            options[:images] = images unless images.empty?
+            # An old worker ignores the field: it cuts anyway (its own default).
+            options[:delivery] = delivery unless Delivery.next_step?(delivery)
+            options[:no_interrupt] = true if no_interrupt
+            options[:author] = author if author
+            options[:pending_limit] = pending_limit if author && pending_limit
+            options[:anchors] = anchors unless anchors.empty?
+            reply = client.post_turn(**options)
+            ack = reply.json
+            return DeliverResult.new(status: :accepted, via: :bridge, ack: ack) if reply.status == 202 && ack.is_a?(Hash)
+            # Read after its deadline and dropped: a file would run it after all.
+            return turn_timeout if ack.is_a?(Hash) && ack["error"] == "deadline_passed"
+            # Any other 4xx with an error is a refusal (bad images, a delivery
+            # it doesn't run, a client bug): a file would bypass it, and a
+            # refused queue would steer. A 413 (a body over the Bridge's
+            # limit, a big piped chi send) and a 5xx keep the file fallback
+            # below, which carries the delivery (a queue too).
+            if (400..499).cover?(reply.status) && reply.status != 413 && ack.is_a?(Hash) && ack["error"]
+              return DeliverResult.new(status: :refused, via: :bridge, code: reply.status, ack: ack)
+            end
+          rescue Errno::ETIMEDOUT
+            # The Bridge drops a turn it reads after the request's deadline
+            # (BridgeClient#post_turn), so a worker that wakes later won't run
+            # it; a file would.
+            return turn_timeout
+          rescue SystemCallError, IOError
+            nil # the worker closed its Bridge on the way out: queue the file
+          end
+        end
+        # A participant's file only for a worker started after it: a worker
+        # still holding the session with its Bridge gone (exiting) may be an
+        # older one, which would run it without the review boundary.
+        # (A one-turn chi run holding it is refused as for anyone, below.)
+        if Steer.participant_author?(author) && (holder = delivery_owner(manager, session_id, state_dir)) && !holder.tui?
+          return DeliverResult.new(status: :timeout, via: :file,
+                                   ack: { "error" => "worker_timeout",
+                                          "detail" => "the session's worker is exiting, so the message was not sent; send it again" })
+        end
+        enqueued_id = SecureRandom.uuid
+        input = { prompt: prompt, client_id: client_id, enqueued_id: enqueued_id, state_dir: state_dir }
+        input[:images] = images unless images.empty?
+        input[:delivery] = delivery unless Delivery.next_step?(delivery)
+        input[:no_interrupt] = true if no_interrupt
+        input[:author] = author if author
+        input[:anchors] = anchors unless anchors.empty?
+        path = participant_queue_lock(session_dir, author && pending_limit) do
+          # No worker: the participant's waiting files are all their turns,
+          # counted and written under one lock (the Bridge counts under its).
+          next :too_many if author && pending_limit && pending_files(session_dir, author) >= pending_limit
+
+          manager.write_turn_input(session_id, **input)
+        end
+        if path == :too_many
+          return DeliverResult.new(status: :refused, code: 429,
+                                   ack: { "error" => "too_many_turns", "detail" => ParticipantMessages::TOO_MANY_TURNS })
+        end
+        return DeliverResult.new(status: :failed) unless path
+
+        owner = delivery_owner(manager, session_id, state_dir)
+        # A TUI that took the session between the resume and the write never
+        # reads input files; a later worker would replay this one.
+        if owner&.tui?
+          FileUtils.rm_f(path) if path.is_a?(String)
+          raise OwnedByTUI, session_id
+        end
+        # A worker that idle-exited since the resume never reads it either:
+        # wake a new one. (The exiting worker also looks for input it left;
+        # one the first resume spawned that is still starting is left be.)
+        manager.resume_session(session_id, state_dir: state_dir) if owner.nil?
+        DeliverResult.new(status: :accepted, via: :file,
+                          ack: { "status" => "accepted", "enqueued_id" => enqueued_id, "session_id" => session_id })
+      end
+
+      # Whether the worker +client+ talks to names +feature+: the features of
+      # the sidecar the client was made from (the Live link WorkerLink.await
+      # found), not a second read of bridge.json.
+      private def worker_has?(client, feature) = client.features.include?(feature)
+
+      # The block under the session's participant queue lock (a file lock:
+      # chi web's threads, and another chi web), when +locked+; else as is.
+      private def participant_queue_lock(session_dir, locked)
+        return yield unless locked
+
+        FileUtils.mkdir_p(session_dir)
+        File.open(File.join(session_dir, PARTICIPANT_QUEUE_LOCK), File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      private def pending_files(session_dir, author)
+        SessionInbox.find_new_input_files(session_dir).count do |file|
+          data = JSON.parse(File.read(file))
+          data.is_a?(Hash) && data["author"] == author
+        rescue JSON::ParserError, SystemCallError
+          false
+        end
+      end
+
+      private def queue_unavailable
+        DeliverResult.new(status: :refused, code: 409, ack: Delivery::QUEUE_UNAVAILABLE)
+      end
+
+      private def review_unavailable
+        DeliverResult.new(status: :refused, code: 409, ack: Delivery::REVIEW_UNAVAILABLE)
+      end
+
+      private def turn_timeout
+        DeliverResult.new(status: :timeout, via: :bridge,
+                          ack: { "error" => "worker_timeout",
+                                 "detail" => "the session's worker did not answer, so the message was not sent" })
+      end
+
+      private def delivery_owner(manager, session_id, state_dir)
+        Degrade.call(:worker, "owner_unreadable", sid: session_id) { manager.session_owner(session_id, state_dir: state_dir) }
+      end
+    end
+
+    extend DeliveryPart
+  end
+end

data/lib/samagotchi/session_manager/emptiness.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "../analytics_file"
+require_relative "../session_inbox"
+require_relative "../worker_link"
+
+module Samagotchi
+  class SessionManager
+    # What a session's directory holds before anything happened in it. Any
+    # other entry (or a file in one of the EMPTY_DIRS) is something the
+    # session keeps. "pid" is the pid file workers wrote until 2026-10-01:
+    # nothing writes or reads it now, but a folder from before still has one
+    # and is still empty. A turn's drawing (Bridge::TurnDrawings::FILE)
+    # exists only after a turn that kept messages: never a skeleton file.
+    EMPTY_SKELETON_FILES = ["pid", "owner.lock", WorkerLink::FILE, AnalyticsFile::NAME].freeze
+    EMPTY_DIRS = [SessionInbox::INPUT_DIR, SessionInbox::NOTES_DIR, "images"].freeze
+    EMPTY_SKELETON_DIRS = (EMPTY_DIRS + [SessionInbox::OUTPUT_DIR]).freeze
+
+    # Emptiness: whether nothing happened in a session (pure predicates over
+    # its file and directory) and whether one being left is deleted, asked by
+    # WorkerCommandPart and the retention sweep. Calls no other part. Meant
+    # to be loaded through samagotchi/session_manager.
+    module EmptinessPart
+      # session.keep_empty off: sessions left with nothing in them are deleted
+      # (the worker as it exits, the retention sweep).
+      def discard_empty?
+        Degrade.call(:config, "keep_empty_unreadable", fallback: false) { Samagotchi::Config.get("session.keep_empty") != true }
+      end
+
+      # Whether a session being left (or found left) is deleted: session.keep_empty
+      # is off and nothing happened in it (#empty_session?). The worker as it
+      # leaves and the retention sweep both ask this.
+      # @param default_model [String, nil] what a new session starts on
+      # @param used_memory_names [Array<String>] memory its owner's Engine used
+      #   before any save
+      def discardable?(session_id, default_model:, state_dir: nil, used_memory_names: [])
+        return false unless discard_empty? && Array(used_memory_names).empty?
+
+        empty_session?(session_id, state_dir: state_dir || Session.default_state_dir, default_model: default_model)
+      end
+
+      # A session nothing happened in: no conversation, no turn tried (a failed
+      # one leaves no messages but a last_prompt and analytics turns), nothing
+      # queued or attached, and the model and mode a new session gets. A
+      # session prepared for later (/model, --model, a note, an image, memory)
+      # is not empty. Anything unreadable or unknown counts as not empty.
+      # @param default_model [String, nil] what a new session starts on
+      def empty_session?(session_id, state_dir: nil, default_model: nil)
+        sd = state_dir || Session.default_state_dir
+        session = Session.load(session_id, state_dir: sd)
+        return false unless no_conversation?(session.messages) && session.pending_question.nil? && session.used_memory_names.empty?
+        return false unless session.last_prompt.to_s.strip.empty? && session.first_preview.to_s.strip.empty?
+        return false unless session.mode.to_s == "assist" && !default_model.nil? && same_model?(session.model_name, default_model)
+
+        empty_session_dir?(Session.session_dir(session_id, state_dir: sd))
+      rescue ArgumentError, SystemCallError, JSON::ParserError
+        false
+      end
+
+      # Whether two model names resolve to the same ref (ModelRef#ref): a
+      # session stores the resolved ref, the default may be an alias.
+      def same_model?(one, other)
+        return true if one.to_s == other.to_s
+        return false if one.nil? || other.nil?
+
+        Degrade.call(:config, "model_ref_unresolved", fallback: false) do
+          HostConfig.model_ref(one).ref == HostConfig.model_ref(other).ref
+        end
+      end
+
+      # Only the system prompt (an Engine seeds one, a saved session keeps
+      # it); a context note is a system message too, but with its kind.
+      # A turn note (the tail system message after a failed, cancelled or empty
+      # turn) is not a conversation either: a session whose only turn failed
+      # before any answer is still empty.
+      def no_conversation?(messages)
+        Array(messages).all? do |msg|
+          (msg[:role] || msg["role"]).to_s == "system" &&
+            ((msg[:kind] || msg["kind"]).nil? || TurnNote.note?(msg))
+        end
+      end
+
+      # @return [Boolean] whether a session's directory holds only the skeleton
+      def empty_session_dir?(dir)
+        return true unless Dir.exist?(dir)
+
+        Dir.children(dir).all? do |name|
+          path = File.join(dir, name)
+          if EMPTY_SKELETON_DIRS.include?(name)
+            File.directory?(path) && (!EMPTY_DIRS.include?(name) || Dir.empty?(path))
+          elsif name == AnalyticsFile::NAME
+            analytics_empty?(path)
+          # Cards and notices from before any turn (Bridge::CardStore).
+          elsif name == "cards.json"
+            cards_empty?(path)
+          else
+            EMPTY_SKELETON_FILES.include?(name)
+          end
+        end
+      end
+
+      # A folder's analytics.json is empty only when it is a JSON object with
+      # an empty turn_records array. Anything unreadable, not JSON, not an
+      # object, the wrong type, or turn_records the wrong shape reads as
+      # "not empty": a broken analytics keeps the folder instead of crashing
+      # the retention sweep (or of a wrong-shape one reading as empty).
+      def analytics_empty?(path)
+        data = read_json(path)
+        turns = data.is_a?(Hash) ? data["turn_records"] : nil
+        turns.is_a?(Array) && turns.empty?
+      end
+
+      # A folder's cards.json is empty only when it is a JSON object with no
+      # turn in it: an empty turn_log, or an older file's (Bridge::CardStore
+      # version 1) turns an integer zero. Anything unreadable, not JSON, not an
+      # object, the wrong type, or neither of those reads as "not empty": a
+      # broken or wrong-shape cards file keeps the folder instead of raising
+      # (Array#/Hash#to_i) or reading as empty.
+      def cards_empty?(path)
+        data = read_json(path)
+        return false unless data.is_a?(Hash)
+
+        turns = data["turns"]
+        data["turn_log"] == [] || (turns.is_a?(Integer) && turns.zero?)
+      end
+
+      # A session-dir JSON file's contents, or nil when it is missing,
+      # unreadable, not JSON or not an object (mirrors AnalyticsFile#read): a
+      # broken file reads as none, so its folder is kept, not deleted.
+      def read_json(path)
+        JSON.parse(File.read(path))
+      rescue JSON::ParserError, SystemCallError
+        nil
+      end
+    end
+
+    extend EmptinessPart
+  end
+end

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