samagotchi 0.46.1 → 0.47.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,7 @@ require_relative "continue_offer"
 require_relative "image_store"
 require_relative "plugin_session_state"
 require_relative "context_sources"
+require_relative "session_chain"
 require_relative "terminal_ui"
 
 module Samagotchi
@@ -115,6 +116,33 @@ module Samagotchi
       end
     end
 
+    # A continue that can't happen (#continue_session). reason: :continued
+    # (another session continues it already: +ids+ names it), :open_children
+    # (children still running, waiting, live or with a reply it wasn't given:
+    # +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: #{detail}; wait for them, stop them or archive them, then continue"
+        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 +161,17 @@ 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
     # @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")
       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 +192,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 +209,175 @@ 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
       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 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. 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)
+    # @raise [ArgumentError] no such session (Session::AmbiguousId for a prefix of several)
+    # @raise [ContinueRefused] continued already, delegates still open, 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)
+      check_continue!(previous, state_dir)
+      # archive_session's refusals that can be known now, before the wait.
+      archivable!(id, state_dir)
+      recap_before_archive(id, state_dir, wait: recap_wait)
+      # Again: a turn sent to it during the wait may have delegated.
+      check_open_children!(id, state_dir)
+      already = [id, *descendant_ids(id, state_dir)].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)[:archived] - already
+      begin
+        spawn_continuation(previous, prompt: prompt, title: title, state_dir: state_dir)
+      rescue StandardError
+        # Nothing started: 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).
+        discard_failed_link(id, state_dir)
+        archived.each { |sid| ArchiveStore.unarchive(sid, state_dir: state_dir) }
+        raise
+      end
+    end
+
+    # The link a failed #continue_session saved (no other continues +id+:
+    # check_continue! made sure under the lock).
+    private_class_method def self.discard_failed_link(id, state_dir)
+      orphan = SessionChain.next_of(id, state_dir: state_dir) or return
+      delete_session(orphan, state_dir: state_dir)
+    rescue StandardError => e
+      Log.warn(:worker, "continue_cleanup_failed", sid: id, error: e.class.name, msg: e.message)
+    end
+
+    private_class_method def self.spawn_continuation(previous, prompt:, title:, state_dir:)
+      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?
+      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)
+    end
+
+    # The refusals that come before anything changes: continued already (no
+    # forks in a chain), a delegate still open (its report would go to the
+    # archived link), the folder gone (the worker would run elsewhere), a
+    # model whose host config.yml no longer has.
+    # @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
+
+      check_open_children!(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)
+    end
+
+    # A child the next link couldn't follow once its parent is archived.
+    OpenChild = Data.define(:id, :short_id, :why)
+
+    # @raise [ContinueRefused] while #open_children has any
+    private_class_method def self.check_open_children!(id, state_dir)
+      open = open_children(id, state_dir)
+      return if open.empty?
+
+      raise ContinueRefused.new(id, :open_children, ids: open.map(&:id),
+                                                    detail: open.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>]
+    private_class_method 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 +479,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 +512,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)
@@ -357,21 +560,29 @@ module Samagotchi
     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|
-        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)
       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)
+      raise ArchiveRefused.new(id, :scratch) if Session.load(id, state_dir: state_dir).scratch
+
+      tree = [id, *descendant_ids(id, state_dir)]
+      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

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/version.rb

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

data/lib/samagotchi/web/app.rb

@@ -594,6 +594,7 @@ module Samagotchi
         if prompt.to_s.strip.empty? && !idle
           return error_response(400, "missing_fields", "prompt is required")
         end
+        return handle_continue(body, prompt, idle) if body.key?("continues")
 
         # dir: the folder the chat starts in (the page's scope); without it,
         # the server's own cwd.
@@ -632,6 +633,53 @@ module Samagotchi
         json_response(201, session_to_json(session).merge(bridge_port: port))
       end
 
+      # POST /api/sessions with continues: <id, prefix or last:id>: the next
+      # link of that session's chain (SessionManager.continue_session), in its
+      # folder, on its model and with its llm_context, so dir, model and
+      # llm_context are refused beside it. 409 continued (with next_id, the
+      # link that continues it already: the page opens that one),
+      # open_children (ids), folder_gone, busy, scratch or owned_by_tui.
+      def handle_continue(body, prompt, idle)
+        given = body["continues"]
+        unless given.is_a?(String) && !given.strip.empty?
+          return error_response(400, "invalid_continues", "continues is a session id")
+        end
+        if (fields = %w[dir model model_name llm_context].select { |key| body.key?(key) }).any?
+          return error_response(400, "invalid_continues",
+                                "continues takes the previous session's folder, model and llm_context; " \
+                                "leave out #{fields.join(", ")}")
+        end
+
+        preview = idle ? body["preview"].to_s.strip : ""
+        session, error = continue_from(given, prompt: idle ? nil : prompt.to_s, title: preview.empty? ? nil : preview)
+        return error if error
+
+        port = await_bridge_port(session.id)
+        [session.continues, session.id].each { |sid| @hub&.touch(sid) }
+        record_history(body, prompt) if !idle && PromptHistory.shell_line?(prompt.to_s.strip)
+        json_response(201, session_to_json(session).merge(bridge_port: port))
+      end
+
+      # SessionManager.continue_session, its refusals as responses: [session,
+      # nil] or [nil, the response]. Only its own errors: what fails after
+      # the new link started is not a refusal of it.
+      def continue_from(given, prompt:, title:)
+        [@manager.continue_session(given, prompt: prompt, title: title, state_dir: @state_dir), nil]
+      rescue SessionManager::ContinueRefused => e
+        extra = e.reason == :continued ? { next_id: e.ids.first } : { ids: e.ids }
+        [nil, json_response(409, { error: e.reason.to_s, detail: e.message, **extra })]
+      rescue SessionManager::ArchiveRefused => e
+        [nil, error_response(409, e.reason == :scratch ? "scratch" : "busy", e.message)]
+      rescue SessionManager::OwnedByTUI
+        [nil, error_response(409, "owned_by_tui", "session #{given} is open in a chi REPL; close it there first")]
+      rescue ModelProfile::MissingModel => e
+        [nil, error_response(400, "invalid_model", e.message)]
+      rescue Session::AmbiguousId => e
+        [nil, error_response(400, "ambiguous_id", e.message)]
+      rescue ArgumentError => e
+        [nil, error_response(404, "not_found", e.message)]
+      end
+
       # The create request's "llm_context" ({strategy:, apply:, budget:},
       # each a word as /llm-context takes it, "default" for unset) as an
       # override: [override, nil] (nil when absent or all default), or