samagotchi 0.46.1 → 0.48.0

data/lib/samagotchi/session_chain.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "session"
+require_relative "recap_store"
+
+module Samagotchi
+  # Session chains: a session that continues an earlier one (Session#continues),
+  # "the next day of the same routine". The chain is derived, never stored:
+  # follow +continues+ back for the earlier links, forward (the session whose
+  # +continues+ names this one) for the later ones. A link is continued at
+  # most once (SessionManager.continue_session refuses a second), so the
+  # chain's latest link is the one nobody continues.
+  module SessionChain
+    # `--continues last:<id>`: the latest link of the chain <id> is in.
+    LAST_PREFIX = "last:"
+    # Who the carry note is from (ContextNote's label: "note from session chain").
+    NOTE_SOURCE = "session chain"
+    # The most of the previous link's recap the carry note takes; a recap is
+    # a few sentences, this only keeps a runaway one under the note's 16 KiB.
+    RECAP_CHARS = 8000
+
+    module_function
+
+    # The session that continues +id+, else nil. Archived ones count: an
+    # archived link is still a link.
+    # @return [String, nil]
+    def next_of(id, state_dir:)
+      Session.list(state_dir: state_dir, sort: "created_at", order: "asc", include_archived: true)
+             .find { |s| s.continues == id }&.id
+    end
+
+    # The chain's latest link from +id+ on: +id+ itself when nobody
+    # continues it. One listing, walked forward (a loop a hand-edited file
+    # could make ends where it started).
+    # @return [String]
+    def latest(id, state_dir:)
+      nexts = {}
+      Session.list(state_dir: state_dir, sort: "created_at", order: "asc", include_archived: true).each do |s|
+        nexts[s.continues] ||= s.id if s.continues
+      end
+      seen = [id]
+      while (following = nexts[seen.last]) && !seen.include?(following)
+        seen << following
+      end
+      seen.last
+    end
+
+    # A session to continue as the CLI and the web name it: an id, a unique
+    # prefix, or `last:<id or prefix>` for that chain's latest link.
+    # @return [String] the full id of an existing session
+    # @raise [ArgumentError] none such (Session::AmbiguousId for a prefix of several)
+    def resolve(ref, state_dir:)
+      given = ref.to_s.strip
+      last = given.start_with?(LAST_PREFIX)
+      given = given.delete_prefix(LAST_PREFIX) if last
+      raise ArgumentError, "no session #{ref}" unless Session.valid_id?(given)
+
+      id = Session.resolve_id(given, state_dir: state_dir)
+      raise ArgumentError, "no session #{ref}" unless Session.exist?(id, state_dir: state_dir)
+
+      last ? latest(id, state_dir: state_dir) : id
+    end
+
+    # The context note a new link starts with: which session it continues,
+    # from when, and that session's recap with its time, when it has one.
+    # Never more than the recap: no transcript.
+    # @param previous [Session]
+    # @param recap [Hash, nil] RecapStore.read's
+    # @return [String]
+    def note_text(previous, recap:)
+      head = "This session continues #{previous.id[0, 8]} (#{day(previous.created_at)}), the previous link of its chain."
+      text = recap && recap[:text].to_s.strip
+      return "#{head} It left no recap." if text.nil? || text.empty?
+
+      text = "#{text[0, RECAP_CHARS - 1]}…" if text.length > RECAP_CHARS
+      as_of = clock(recap[:created_at])
+      "#{head} Its recap#{", as of #{as_of}" if as_of}:\n#{text}"
+    end
+
+    def day(iso)
+      Time.iso8601(iso.to_s).localtime.strftime("%Y-%m-%d")
+    rescue ArgumentError
+      iso.to_s
+    end
+
+    def clock(iso)
+      iso && Time.iso8601(iso.to_s).localtime.strftime("%Y-%m-%d %H:%M")
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/samagotchi/session_manager.rb

@@ -30,6 +30,8 @@ require_relative "continue_offer"
 require_relative "image_store"
 require_relative "plugin_session_state"
 require_relative "context_sources"
+require_relative "session_chain"
+require_relative "child_move"
 require_relative "terminal_ui"
 
 module Samagotchi
@@ -115,6 +117,35 @@ module Samagotchi
       end
     end
 
+    # A continue that can't happen (#continue_session). reason: :continued
+    # (another session continues it already: +ids+ names it), :open_children
+    # (open children it can't move to the new link: on an older chi's
+    # worker or open in a chi REPL; +ids+ names them) or :folder_gone (its
+    # folder isn't there).
+    class ContinueRefused < StandardError
+      attr_reader :session_id, :reason, :ids
+
+      def initialize(session_id, reason, ids: [], detail: nil)
+        @session_id = session_id
+        @reason = reason
+        @ids = ids
+        super(continue_refused_message(detail))
+      end
+
+      private
+
+      def continue_refused_message(detail)
+        short = @session_id[0, 8]
+        case @reason
+        when :continued then "#{short} is continued already, by #{@ids.first[0, 8]}; continue that one (or last:#{short})"
+        when :open_children
+          "#{short} has delegates still open that can't move to the next link: #{detail}; " \
+          "then continue (or wait for them, stop them or archive them)"
+        else "#{short}'s folder #{detail} is gone"
+        end
+      end
+    end
+
     # Spawn a new background session that processes the given prompt (or,
     # with none, waits idle for input).
     #
@@ -133,11 +164,19 @@ module Samagotchi
     #   (the prompt's preview by default, else the seed's first user message)
     # @param llm_context [LLMContextOverride, nil] the session's own
     #   llm_context values (chi --llm-context; a fork copies its parent's)
+    # @param continues [String, nil] the session this one continues (a
+    #   session field; #continue_session)
+    # @param note [String, nil] a context note the session starts with,
+    #   from +note_source+: queued before its worker spawns, so its first
+    #   turn sees it
+    # @param before_spawn [#call, nil] (session) runs once the session and
+    #   its note are saved, before its worker spawns
     # @return [Session] with #seed_images_dropped: refs whose file was gone,
     #   and #model_warning: an id its host's saved list doesn't have
     def self.spawn_session(prompt:, mode: "assist", working_directory: nil, model_name: nil, state_dir: nil,
                            memories: [], muted_memories: [], parent_id: nil, messages: [], images_from: nil,
-                           title: nil, delegate: false, llm_context: nil)
+                           title: nil, delegate: false, llm_context: nil, continues: nil, note: nil,
+                           note_source: "chi", before_spawn: nil)
       sd = state_dir || Session.default_state_dir
       # The resolved ref is stored (a resumed session keeps its model when an
       # alias is retargeted), with the name as typed beside it. A wrong host
@@ -158,7 +197,8 @@ module Samagotchi
         parent_id: parent_id,
         messages: messages,
         delegate: delegate,
-        llm_context: llm_context
+        llm_context: llm_context,
+        continues: continues
       )
       session.model_warning = model_warning
       # With no prompt there is no first turn to run (an attaching UI sends
@@ -174,10 +214,234 @@ module Samagotchi
         session.seed_images_dropped = dropped
       end
       setup_session_directory(session_dir, session, state_dir: sd)
+      SessionInbox.write_note(session.id, text: note, source: note_source, state_dir: sd) if note
+      before_spawn&.call(session)
       spawn_worker_for_session(session, state_dir: sd)
       session
     end
 
+    # How long #continue_session waits for the previous link's worker to
+    # write its recap (IdleRecap's own request timeout).
+    CONTINUE_RECAP_WAIT = 30.0
+    # In the previous link's folder: one continue of a session at a time.
+    CONTINUE_LOCK = "continue.lock"
+    # How often a last:<id> continue looks again when another continue
+    # moved the chain's end while it waited for the lock.
+    CONTINUE_TRIES = 3
+
+    # Start the next link of a chain: a new session that continues
+    # +id_or_ref+ (Session#continues) in its folder, on its model (the name
+    # it was typed as, so an alias holds) and with its own llm_context,
+    # starting with a context note from chi: the link and the previous
+    # link's recap (SessionChain.note_text). The previous link is archived
+    # first, with its finished delegates (archive_session's rules: a turn
+    # running, a prompt queued or the step-limit question refuse; an idle
+    # worker is stopped), so a refusal starts nothing. Its open delegates
+    # (running, waiting, live, an unreported reply, at any depth below them)
+    # move to the new link instead (ChildMove): their reports reach it.
+    # Before that its live worker is asked for a recap and given up to
+    # +recap_wait+ seconds to write it.
+    # One continue of a session at a time (a lock in its folder): a double
+    # click finds the first one's link and is refused; a last:<id> one
+    # follows the chain to its new end instead.
+    # @param id_or_ref [String] an id, a prefix, or last:<id> (SessionChain.resolve)
+    # @param prompt [String, nil] its first message (nil: it starts idle)
+    # @param title [String, nil] what the lists show before the first turn;
+    #   by default the prompt, else the previous link's preview
+    # @return [Session] the new link (#model_warning as spawn_session's,
+    #   #moved_children: the delegates it took over)
+    # @raise [ArgumentError] no such session (Session::AmbiguousId for a prefix of several)
+    # @raise [ContinueRefused] continued already, delegates open that can't
+    #   move, or its folder is gone
+    # @raise [ArchiveRefused, OwnedByTUI] as archive_session
+    def self.continue_session(id_or_ref, prompt: nil, title: nil, state_dir: nil, recap_wait: CONTINUE_RECAP_WAIT,
+                              archive_wait: 5)
+      sd = state_dir || Session.default_state_dir
+      CONTINUE_TRIES.times do |try|
+        id = SessionChain.resolve(id_or_ref, state_dir: sd)
+        result = with_continue_lock(id, sd) do
+          follow = id_or_ref.to_s.strip.start_with?(SessionChain::LAST_PREFIX) && try < CONTINUE_TRIES - 1
+          next :moved if follow && SessionChain.next_of(id, state_dir: sd)
+
+          continue_locked(id, prompt: prompt, title: title, state_dir: sd, recap_wait: recap_wait,
+                              archive_wait: archive_wait)
+        end
+        return result unless result == :moved
+      end
+    end
+
+    private_class_method def self.with_continue_lock(id, state_dir, &)
+      dir = Session.session_dir(id, state_dir: state_dir)
+      FileUtils.mkdir_p(dir)
+      File.open(File.join(dir, CONTINUE_LOCK), File::RDWR | File::CREAT, 0o600) do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    private_class_method def self.continue_locked(id, prompt:, title:, state_dir:, recap_wait:, archive_wait:)
+      previous = Session.load(id, state_dir: state_dir)
+      plan = check_continue!(previous, state_dir)
+      # archive_session's refusals that can be known now, before the wait.
+      archivable!(id, state_dir, except: plan.move)
+      recap_before_archive(id, state_dir, wait: recap_wait)
+      # Again: a turn sent to it during the wait may have delegated (they
+      # move too), or a delegate finished.
+      plan = move_plan!(id, state_dir)
+      already = [id, *descendant_ids(id, state_dir, except: plan.move)].select do |sid|
+        ArchiveStore.archived?(Session.session_dir(sid, state_dir: state_dir))
+      end
+      archived = archive_session(id, state_dir: state_dir, wait: archive_wait, except: plan.move)[:archived] - already
+      begin
+        spawn_continuation(previous, prompt: prompt, title: title, state_dir: state_dir, move: plan.move)
+      rescue StandardError
+        # Nothing started: the delegates go back, what this archived goes
+        # back to the lists, and a new link saved before its worker failed
+        # to spawn goes (left, it would hold the chain: "continued already",
+        # last: to it).
+        undo_move(id, state_dir, moved: plan.move)
+        begin
+          discard_failed_link(id, state_dir)
+        ensure
+          archived.each { |sid| ArchiveStore.unarchive(sid, state_dir: state_dir) }
+          wake_for_rings(id, state_dir) unless plan.move.empty?
+        end
+        raise
+      end
+    end
+
+    # The delegates a failed #continue_session moved, or began to (its
+    # intent names them), go back to +id+.
+    private_class_method def self.undo_move(id, state_dir, moved:)
+      link = SessionChain.next_of(id, state_dir: state_dir) or return
+      ids = ChildMove.read_intent(link, state_dir: state_dir)&.ids || moved
+      ChildMove.apply(ids, from: link, to: id, state_dir: state_dir, undo: true)
+      ChildMove.clear_intent(link, state_dir: state_dir)
+    rescue StandardError => e
+      Log.warn(:worker, "continue_undo_move_failed", sid: id, error: e.class.name, msg: e.message)
+    end
+
+    # The link a failed #continue_session saved (no other continues +id+:
+    # check_continue! made sure under the lock): its worker stopped if one
+    # started, then the rings a moved delegate wrote into it just before
+    # the undo go back to +id+, then the link goes. A worker that outlives
+    # the stop is raised (DeleteRefused): the link stays, and the caller
+    # hears it.
+    private_class_method def self.discard_failed_link(id, state_dir)
+      orphan = SessionChain.next_of(id, state_dir: state_dir) or return
+      if refuse_tui!(orphan, state_dir: state_dir) && !stop_session(orphan, state_dir: state_dir, wait: 10)
+        raise DeleteRefused.new(orphan, :still_stopping)
+      end
+
+      ChildMove.return_rings(from: orphan, to: id, state_dir: state_dir)
+      delete_session(orphan, state_dir: state_dir)
+    rescue DeleteRefused
+      raise
+    rescue StandardError => e
+      Log.warn(:worker, "continue_cleanup_failed", sid: id, error: e.class.name, msg: e.message)
+    end
+
+    # A failed continue's previous link, back in the lists, with rings that
+    # came in meanwhile: wake it for them, as the ring's own wake would have.
+    private_class_method def self.wake_for_rings(id, state_dir)
+      return if SessionInbox.find_ring_files(Session.session_dir(id, state_dir: state_dir)).empty?
+
+      wake_for_report(id, state_dir: state_dir)
+    rescue StandardError => e
+      Log.warn(:worker, "continue_wake_failed", sid: id, error: e.class.name, msg: e.message)
+    end
+
+    # The new link, holding off any worker but its own (ChildMove.starting?)
+    # while +move+ goes to it.
+    private_class_method def self.spawn_continuation(previous, prompt:, title:, state_dir:, move:)
+      recap = RecapStore.read(Session.session_dir(previous.id, state_dir: state_dir))
+      start = prompt.to_s.strip.empty? ? nil : prompt
+      title = previous.first_preview if title.to_s.strip.empty? && start.nil?
+      before_spawn = lambda do |link|
+        ChildMove.mark_starting(link.id, state_dir: state_dir)
+        ChildMove.apply(move, from: previous.id, to: link.id, state_dir: state_dir)
+      end
+      link = spawn_session(prompt: start, title: title, working_directory: previous.working_directory,
+                           model_name: previous.model_typed || previous.model_name, llm_context: previous.llm_context,
+                           continues: previous.id, note: SessionChain.note_text(previous, recap: recap),
+                           note_source: SessionChain::NOTE_SOURCE, state_dir: state_dir, before_spawn: before_spawn)
+      link.moved_children = move
+      link
+    end
+
+    # The refusals that come before anything changes: continued already (no
+    # forks in a chain), an open delegate that can't move to the new link
+    # (ChildMove.plan), the folder gone (the worker would run elsewhere), a
+    # model whose host config.yml no longer has.
+    # @return [ChildMove::Plan]
+    # @raise [ContinueRefused, ModelProfile::MissingModel]
+    private_class_method def self.check_continue!(previous, state_dir)
+      if (following = SessionChain.next_of(previous.id, state_dir: state_dir))
+        raise ContinueRefused.new(previous.id, :continued, ids: [following])
+      end
+
+      plan = move_plan!(previous.id, state_dir)
+      # Its model's host, as spawn_session checks it: before the archive
+      # stops the previous link's worker.
+      ModelProfile.check_host!(ModelProfile.required_model_name(previous.model_typed || previous.model_name))
+      dir = previous.working_directory.to_s
+      raise ContinueRefused.new(previous.id, :folder_gone, detail: dir) unless File.directory?(dir)
+
+      plan
+    end
+
+    # A child still open below a session (#open_children); why: running,
+    # waiting, live, unreported reply, or why it can't move (ChildMove).
+    OpenChild = Data.define(:id, :short_id, :why)
+
+    # The delegates a continue of +id+ moves (ChildMove.plan).
+    # @return [ChildMove::Plan]
+    # @raise [ContinueRefused] for open ones it can't move
+    private_class_method def self.move_plan!(id, state_dir)
+      plan = ChildMove.plan(id, open: open_children(id, state_dir), state_dir: state_dir)
+      return plan if plan.refuse.empty?
+
+      raise ContinueRefused.new(id, :open_children, ids: plan.refuse.map(&:id),
+                                                    detail: plan.refuse.map { |c| "#{c.short_id} (#{c.why})" }.join(", "))
+    end
+
+    # The unarchived children, at any depth (the archive's cascade), of the
+    # session still running, waiting for an answer, with a live worker, or
+    # (a delegate) with a reply its parent wasn't given (ChildrenStatus).
+    # @return [Array<OpenChild>]
+    def self.open_children(id, state_dir)
+      require_relative "children_status"
+      [id, *descendant_ids(id, state_dir)].flat_map { |node| ChildrenStatus.of(node, state_dir: state_dir) }.uniq(&:id)
+                                          .filter_map do |child|
+        why = if %w[waiting running].include?(child.state) then child.state
+              elsif child.live then "live"
+              elsif child.delegate && child.last_reply && !child.reported then "unreported reply"
+              end
+        why && OpenChild.new(id: child.id, short_id: child.short_id, why: why)
+      end
+    end
+
+    # Ask the session's live worker for a recap now (Bridge POST /recap:
+    # IdleRecap#request_now) and wait, up to +wait+ seconds, for recap.json
+    # to change. A worker that is gone wrote its recap when it left; one
+    # that has nothing new to say, too short a conversation, or recaps off
+    # answers at once. Best effort: the continue goes on without.
+    private_class_method def self.recap_before_archive(id, state_dir, wait:)
+      return unless worker_live?(id, state_dir: state_dir)
+
+      dir = Session.session_dir(id, state_dir: state_dir)
+      client = BridgeClient.discover(id, session_dir: dir) or return
+      before = RecapStore.read(dir)
+      reply = client.request_recap
+      asked = reply.status == 200 && reply.json.is_a?(Hash) ? reply.json["request"] : nil
+      return unless %w[started in_flight].include?(asked)
+
+      BridgeClient.poll(wait, interval: 0.2) { RecapStore.read(dir) != before }
+    rescue StandardError => e
+      Log.info(:worker, "continue_recap_failed", sid: id, error: e.class.name, msg: e.message)
+      nil
+    end
+
     # Build the opts hash passed to Process.spawn for a forked worker. The
     # child inherits this process's ENV and reads config.yml itself (as it
     # is when the worker starts); opts[:env] adds to it (merged, not
@@ -279,9 +543,11 @@ module Samagotchi
     # @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:, delegate:, archived:, scratch:, test_run:, waiting:, waiting_id:, stopped_by:}; busy =
+    #   parent_short_id:, continues:, continues_short_id:, delegate:, archived:, scratch:, test_run:, waiting:,
+    #   waiting_id:, stopped_by:}; busy =
     #   live with a turn running, delegate = started by the delegate tool
-    #   (Session#delegate?; a fork has a parent_id but isn't one), recap = the saved recap's first sentence, project =
+    #   (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, 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
@@ -310,7 +576,8 @@ module Samagotchi
           owner: owner&.kind, recap: RecapStore.preview(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), delegate: s.delegate?, archived: s.archived,
+          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)
@@ -354,24 +621,34 @@ module Samagotchi
     # @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
-    def self.archive_session(id_or_prefix, state_dir: nil, wait: 5)
+    # @param except [Array<String>] descendants left alone with their own
+    #   subtrees (delegates a continue moves to the chain's new link)
+    def self.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)
-      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|
-        refusal = archive_refusal(sid, owners[sid], sd)
-        raise ArchiveRefused.new(id, sid == id ? refusal : :"#{refusal}_child", busy_id: sid) if refusal
-      end
-
+      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) }
       { 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.
+    # @return [Array(Array<String>, Hash)] the ids, and id => OwnerLock::Owner or nil
+    # @raise [ArchiveRefused, OwnedByTUI]
+    private_class_method def self.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
@@ -409,13 +686,13 @@ module Samagotchi
     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)
+    # further today, a plugin's fork may. The walk doesn't enter +except+.
+    def self.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])
+          next if seen.include?(child[:id]) || except.include?(child[:id])
 
           seen << child[:id]
           queue << child[:id]
@@ -484,6 +761,9 @@ module Samagotchi
       # One this process just spawned may not hold the lock yet (a slow
       # start, deliver_turn's second resume): it would only lose it.
       return session if still_starting?(session.id, state_dir: sd)
+      # A continue moving delegates to it spawns its worker once they are
+      # moved; one spawned now (a moved child's ring) would race the move.
+      return session if ChildMove.starting?(session.id, state_dir: sd)
 
       Session.clear_stopped(session.id, state_dir: sd)
       session.status = Session::STATUS_IDLE
@@ -494,18 +774,27 @@ module Samagotchi
 
     # A delegate child rang a parent that has no worker (ChildRing): start
     # one, which runs a turn for the report. Not for a parent that is gone,
-    # stopped, archived, a scratch session, or open in a chi REPL: the ring
-    # waits on disk for whoever runs it next (#resume_session itself would
-    # clear the stop). A stop landing between the check and the resume is
-    # a small window, left as is.
+    # stopped, archived, a scratch session, open in a chi REPL, or a
+    # continue's new link still taking its delegates (its own spawn comes):
+    # the ring waits on disk for whoever runs it next (#resume_session
+    # itself would clear the stop). A stop landing between the check and
+    # the resume is a small window, left as is. An archived parent with a
+    # later link in its chain wakes that link instead: a ring a moved child
+    # wrote just as the continue moved it reaches the new link that way
+    # (ChildReports reads its predecessor's rings).
     # @return [Symbol] :woken, or why not (:gone, :stopped, :archived,
-    #   :scratch, :owned)
-    def self.wake_for_report(session_id, state_dir: nil)
+    #   :scratch, :owned, :starting)
+    def self.wake_for_report(session_id, state_dir: nil, forward: true)
       sd = state_dir || Session.default_state_dir
       return :gone unless Session.exist?(session_id, state_dir: sd)
       return :owned if session_owner(session_id, state_dir: sd)
       return :stopped if Session.stopped_marker?(session_id, state_dir: sd)
-      return :archived if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: sd))
+
+      if ArchiveStore.archived?(Session.session_dir(session_id, state_dir: sd))
+        following = forward && SessionChain.next_of(session_id, state_dir: sd)
+        return following ? wake_for_report(following, state_dir: sd, forward: false) : :archived
+      end
+      return :starting if ChildMove.starting?(session_id, state_dir: sd)
 
       session = Session.load(session_id, state_dir: sd)
       return :stopped if session.status == Session::STATUS_STOPPED

data/lib/samagotchi/sessions_command.rb

@@ -170,6 +170,7 @@ module Samagotchi
         # its git project's root, or nil
         # parent_id: the session that delegated it (the delegate tool), or nil
         # delegate: started by the delegate tool (a fork has a parent_id too)
+        # continues: the session it continues (its chain's previous link), or nil
         # archived: hidden from the lists (only with --archived can it be true)
         # scratch: a `chi scratch` session (deleted when its REPL ends, a
         # leftover one at the next sweep)
@@ -178,7 +179,7 @@ module Samagotchi
         # hook: chi answer or the web answers it), or nil; waiting_id: its
         # id, for chi answer --question; relayed_to: the parent session (short
         # id) whose card it also waits in (the approval relay), or nil
-        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id delegate archived scratch ctx_pct
+        keys = %i[id short_id desc cwd project updated_at live busy owner recap parent_id continues delegate archived scratch ctx_pct
                   waiting waiting_id relayed_to stopped_by]
         @stdout.puts JSON.generate(summaries.map { |summary| summary.slice(*keys) })
       when "tsv"
@@ -199,6 +200,8 @@ module Samagotchi
           end
           # A delegated session points at its parent.
           child = summary[:parent_short_id] ? "  ↳ #{summary[:parent_short_id]}" : ""
+          # A chain's link points at the one it continues.
+          child += "  ↪ #{summary[:continues_short_id]}" if summary[:continues_short_id]
           flag = session_flag(scratch: summary[:scratch], test_run: summary[:test_run], archived: summary[:archived],
                               stopped_by: summary[:stopped_by])
           ctx = Samagotchi::SessionMetrics.context_label(summary[:ctx_pct])
@@ -244,6 +247,7 @@ module Samagotchi
       row = lambda do |s|
         flag = session_flag(scratch: s.scratch, test_run: s.test_run, archived: s.archived, stopped_by: s.stopped_by)
         child = s.parent_id ? "  ↳ #{s.parent_id[0, 8]}" : ""
+        child += "  ↪ #{s.continues[0, 8]}" if s.continues
         # A question waits for an answer (chi answer, the web, chi --attach).
         live = s.pending_question && Samagotchi::SessionManager.worker_live?(s.id, state_dir: state_dir)
         waiting = s.waiting_question(live: !!live)

data/lib/samagotchi/tools/delegate_cursor.rb

@@ -33,10 +33,13 @@ module Samagotchi
     # The parent's cursors, one per child, in <parent dir>/delegates.json, so
     # a respawned worker (or a REPL resuming the session) doesn't hand the
     # model a reply it already had. Written by whoever owns the parent (its
-    # worker, or the REPL its kernel runs in), so a Mutex is enough for its
-    # turn thread vs its loop thread; the file is replaced whole.
+    # worker, or the REPL its kernel runs in), and by a continue moving
+    # delegates to the chain's new link (ChildMove, from another process):
+    # a Mutex for the owner's turn thread vs its loop thread, and a flock on
+    # LOCK_FILE between processes; the file is replaced whole.
     module DelegateCursors
       FILE = "delegates.json"
+      LOCK_FILE = "delegates.lock"
       LOCK = Mutex.new
 
       module_function
@@ -51,7 +54,7 @@ module Samagotchi
       # @yieldreturn [DelegateCursor]
       # @return [DelegateCursor] the new cursor
       def update(parent_id, child_id, state_dir:)
-        LOCK.synchronize do
+        locked(parent_id, state_dir: state_dir) do
           all = read(parent_id, state_dir: state_dir)
           cursor = yield get_from(all, child_id)
           all[child_id] = cursor.to_json_hash
@@ -60,6 +63,31 @@ module Samagotchi
         end
       end
 
+      # Add the cursors of +entries+ (child id → cursor fields, as #read
+      # gives them) that the parent has none for; one it has is kept.
+      # @return [Array<String>] the child ids added
+      def merge(parent_id, entries, state_dir:)
+        return [] if entries.empty?
+
+        locked(parent_id, state_dir: state_dir) do
+          all = read(parent_id, state_dir: state_dir)
+          added = entries.keys - all.keys
+          write(parent_id, all.merge(entries.slice(*added)), state_dir: state_dir) unless added.empty?
+          added
+        end
+      end
+
+      def locked(parent_id, state_dir:)
+        LOCK.synchronize do
+          dir = Session.session_dir(parent_id, state_dir: state_dir)
+          FileUtils.mkdir_p(dir)
+          File.open(File.join(dir, LOCK_FILE), File::RDWR | File::CREAT, 0o600) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          end
+        end
+      end
+
       def get_from(all, child_id)
         data = all[child_id]
         return DelegateCursor.empty unless data.is_a?(Hash)

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.46.1"
+  VERSION = "0.48.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end