samagotchi 0.102.0 → 0.103.0

data/lib/samagotchi/send_command.rb

@@ -25,6 +25,8 @@ require_relative "cli/flags"
 require_relative "cli/parent_wait"
 require_relative "send_command/parent_gate"
 require_relative "send_command/wait_target"
+require_relative "send_command/busy"
+require_relative "session_access/local"
 
 module Samagotchi
   # `chi send`: put text into sessions as the user's message, the same as
@@ -67,7 +69,8 @@ module Samagotchi
         --new       start a new session with the message instead, as the
                     web does, and print its id
         --dir DIR   (--new) its folder, the project it belongs to; default
-                    the current one
+                    the current one (with --remote: required, that
+                    machine's absolute path)
         --continues ID
                     (--new) start the next link of that session's chain:
                     in its folder, on its model (or --model's; one whose
@@ -145,8 +148,9 @@ module Samagotchi
                     queue), with --cut also cut (now, waits, off)
         Exit with --wait: 0 answered, 1 failed or gone, 2 usage, 3 a
         question waits, 4 still running (--timeout), 130 Ctrl-C.
-        Only sessions on this machine. Answers show in the attached TUI
-        or web page, not here.
+        Sessions on this machine, or another's: chi --remote NAME send …
+        (chi remote). Answers show in the attached TUI or web page, not
+        here.
         Find ids with: chi sessions list --live [--scope=all] [--format tsv]
     TEXT
 
@@ -206,18 +210,44 @@ module Samagotchi
 
     UNKNOWN_VISION = VisionSupport::Answer.new(value: nil, reason: nil)
 
+    # What to say when +answer+ (.vision_answer's for +model_name+) is a
+    # no, or nil: the words chi send and chi web's turn and create routes
+    # refuse images with.
+    def self.vision_refusal(model_name, answer)
+      return nil unless answer.no?
+
+      name = model_name.to_s.strip
+      name = Samagotchi::Config.get("default.model").to_s.strip if name.empty?
+      name = "the model" if name.empty?
+      "#{name} can't take images (#{answer.reason}); send text only or switch the model (/model)"
+    end
+
+    # The model a --continues link of +previous+ runs, for the images
+    # check: +model+'s (blank: the previous link's, else the default it
+    # falls back to; SessionContinue.model_for).
+    # @return [Array(String, String)] [model_name, model_typed]
+    # @raise [ModelProfile::MissingModel] a model it can't start on
+    def self.continued_model(previous, model)
+      choice = SessionContinue.model_for(previous, model)
+      inherited = model.to_s.strip.empty? && choice.warning.nil?
+      inherited ? [previous.model_name, previous.model_typed] : [choice.model, nil]
+    end
+
     # A no from the config (models: / hosts: vision: false) holds without
     # the server.
     def self.configured_no?(answer) = answer.reason.to_s.include?("sets vision: false")
     private_class_method :configured_no?
 
     # @param argv [Array<String>] the arguments after "send"
-    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil)
+    # @param access [SessionAccess::Local, nil] where the sessions are;
+    #   default this machine's, in +state_dir+
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, access: nil)
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
       @stderr = stderr
       @state_dir = state_dir || Session.default_state_dir
+      @access = access || SessionAccess::Local.new(state_dir: @state_dir)
     end
 
     private
@@ -259,17 +289,24 @@ module Samagotchi
 
       # A parent agent's /continue yes held to guardrails.parent_answers,
       # and a /parent-answers that loosens: refused before anything is sent.
-      gate = ParentGate.new(options, state_dir: @state_dir)
-      if prompt && (refusal = gate.continue_refusal(prompt))
-        @stderr.puts("chi send: #{refusal}")
-        return CLI::Exit::FAILED
-      end
-      if prompt && gate.loosens?(prompt)
-        error_line("chi send: refused: #{ParentAnswersCommand::REFUSED}")
-        return CLI::Exit::FAILED
+      # Machine-local (the targets' session files, this machine's
+      # config.yml): remotely the server's (its /turn and create routes
+      # check the line chi send's client_id marks; the worker checks a
+      # CLI_ANSWER /continue again).
+      unless @access.remote?
+        gate = ParentGate.new(options, state_dir: @state_dir)
+        if prompt && (refusal = gate.continue_refusal(prompt))
+          @stderr.puts("chi send: #{refusal}")
+          return CLI::Exit::FAILED
+        end
+        if prompt && gate.loosens?(prompt)
+          error_line("chi send: refused: #{ParentAnswersCommand::REFUSED}")
+          return CLI::Exit::FAILED
+        end
       end
       # A file that is not there or not an image: a run-time failure (1),
       # reported in the --format json line too; --image itself was fine.
+      # Client-side on any backend: the files are this machine's.
       return CLI::Exit::FAILED unless ingest_images(options[:images])
 
       return run_new(prompt, options) if options[:new]
@@ -372,6 +409,8 @@ module Samagotchi
 
         options[:parent_answers] = level
       end
+      return remote_new_options(options, words) if @access.remote?
+
       toolkit = Toolkit.from_flags(name: options[:toolkit], add: options[:tools], remove: options[:no_tools])
       options[:toolkit_value] = toolkit if toolkit
       begin
@@ -387,6 +426,35 @@ module Samagotchi
       options
     end
 
+    # --new against a remote: its folder is given, as that machine's
+    # absolute path (D4: none is guessed from this one's), and the setup
+    # flags go as typed (SetupWords): the toolkit's default, the bundles a
+    # --set names and the folder are the remote's to check.
+    def remote_new_options(options, llm_words)
+      unless options[:continues]
+        # One line: the fix is in it, the whole usage would bury it.
+        return usage_error("--new on #{remote_name} needs --dir: a folder there", usage: nil) unless options[:dir]
+        unless options[:dir].start_with?("/")
+          return usage_error("--dir is a folder on #{remote_name}: give its absolute path", usage: nil)
+        end
+      end
+
+      settings = Array(options[:sets]).to_h do |pair|
+        key, sep, value = pair.partition("=")
+        return usage_error("--set takes KEY=VALUE, not #{pair}") if sep.empty? || key.strip.empty?
+
+        [key.strip, value]
+      end
+      options[:setup_words] = SessionAccess::SetupWords.new(
+        llm_context: (llm_words unless llm_words.empty?), thinking: options[:thinking]&.to_s,
+        toolkit: options[:toolkit], tools: Array(options[:tools]), no_tools: Array(options[:no_tools]),
+        settings: (settings unless settings.empty?), parent_answers: options[:parent_answers]
+      )
+      options
+    end
+
+    def remote_name = @access.respond_to?(:name) ? @access.name : "the remote"
+
     # With both, stdin is the context quoted above the message; with one,
     # it goes in as is. nil when both are blank.
     def compose(context, message)
@@ -409,6 +477,8 @@ module Samagotchi
       model, typed = continued_model(options)
       return 1 if model == false
 
+      # Machine-local (this machine's model registry): remotely the
+      # server's (P2: the create route checks vision).
       if images && (refusal = vision_refusal(model, typed: typed))
         error_line("chi send: refused: #{refusal}")
         return 1
@@ -419,21 +489,11 @@ module Samagotchi
       # says whether it ran as one.
       through_worker = images || command_like?(prompt)
       begin
-        start = through_worker ? { prompt: nil, preview: prompt } : { prompt: prompt }
-        session = if options[:continues]
-                    SessionManager.continue_session(options[:continues], **start, model: options[:model],
-                                                                             state_dir: @state_dir)
-                  else
-                    SessionManager.spawn_session(**start, working_directory: options[:dir],
-                                                          model_name: options[:model],
-                                                          setup: SessionSetup.new(llm_context: options[:llm_context],
-                                                                                  thinking: options[:thinking],
-                                                                                  toolkit: options[:toolkit_value],
-                                                                                  settings: options[:settings],
-                                                                                  parent_answers: options[:parent_answers]),
-                                                          state_dir: @state_dir)
-                  end
-      rescue SessionContinue::Refused, SessionManager::ArchiveRefused, SessionManager::OwnedByTUI => e
+        session = @access.create(new_session_spec(prompt, options, through_worker: through_worker))
+      rescue SessionAccess::BadRequest => e
+        return usage_error(e.message)
+      rescue SessionContinue::Refused, SessionManager::ArchiveRefused, SessionManager::OwnedByTUI,
+             SessionAccess::Refused => e
         error_line("chi send: refused: #{e.message}")
         return 1
       rescue StandardError => e
@@ -441,9 +501,13 @@ module Samagotchi
         return 1
       end
       error_line("chi send: warning: #{session.model_warning}") if session.model_warning
-      if (capped = Guardrails::ParentPolicy.capped_note(options[:parent_answers]))
-        error_line("chi send: warning: --parent-answers #{capped}")
-      end
+      # Remotely the server's config.yml caps it (its create's warning).
+      capped = if @access.remote?
+                 session.parent_answers_warning
+               else
+                 Guardrails::ParentPolicy.capped_note(options[:parent_answers])
+               end
+      error_line("chi send: warning: --parent-answers #{capped}") if capped
       if through_worker
         return 1 unless deliver_new(session, prompt)
       else
@@ -453,23 +517,45 @@ module Samagotchi
       return 0 unless options[:wait]
       return report_command(session.id) if @sent_command
 
-      wait_for_reply(session.id, cursor: nil, baseline: baseline_of(session, question_id: nil),
+      start = @access.prepare_wait(session.id, session: session, created: true)
+      wait_for_reply(session.id, cursor: start.cursor, baseline: start.baseline,
                                  timeout: options[:timeout], **WaitTarget.first_message(@delivered).to_h)
     end
 
+    # What chi send --new asks to create: through the worker (images, a
+    # session command), it starts idle with the message as its preview.
+    # Without --dir its folder is the current one (spawn_session's
+    # default): machine-local, so remotely --dir is required (D4).
+    # @return [SessionAccess::NewSession]
+    def new_session_spec(prompt, options, through_worker:)
+      start = through_worker ? { prompt: nil, preview: prompt } : { prompt: prompt }
+      # For a remote's create route, which checks them as this machine does
+      # before it creates (the first line's client_id, the images' model).
+      start = start.merge(client_id: client_id_for(prompt), images: !@images.empty?)
+      if options[:continues]
+        return SessionAccess::NewSession.new(**start, continues: options[:continues], model_name: options[:model])
+      end
+
+      setup = options[:setup_words] || SessionSetup.new(llm_context: options[:llm_context], thinking: options[:thinking],
+                                                        toolkit: options[:toolkit_value], settings: options[:settings],
+                                                        parent_answers: options[:parent_answers])
+      SessionAccess::NewSession.new(**start, working_directory: options[:dir], model_name: options[:model], setup: setup)
+    end
+
     # The model the new session will run, for the images check: --model
     # (nil: the default), or with --continues the one the new link will run
     # (SessionContinue.model_for: --model's, else the previous link's, else
-    # the default it falls back to).
+    # the default it falls back to). Machine-local (the previous link's
+    # file, this machine's models): remotely the server's, with the vision
+    # check (P2).
     # @return [Array, false] [model_name, model_typed], or false after the
     #   error line (no such session, a model it can't start on)
     def continued_model(options)
-      return [options[:model], nil] unless options[:continues]
+      # Remotely the server reads the previous link (its vision check).
+      return [options[:model], nil] unless options[:continues] && !@access.remote?
 
       previous = Session.load(SessionChain.resolve(options[:continues], state_dir: @state_dir), state_dir: @state_dir)
-      choice = SessionContinue.model_for(previous, options[:model])
-      inherited = options[:model].to_s.strip.empty? && choice.warning.nil?
-      inherited ? [previous.model_name, previous.model_typed] : [choice.model, nil]
+      self.class.continued_model(previous, options[:model])
     rescue ModelProfile::MissingModel => e
       error_line("chi send: could not start a session: #{e.message}")
       false
@@ -495,40 +581,21 @@ module Samagotchi
     # @return [Integer] the exit status
     def run_wait(prompt, options)
       id = resolve(options[:ids].first) or return 1
-      session = Session.load(id, state_dir: @state_dir)
-      if session.status == Session::STATUS_RUNNING && (owner = SessionManager.session_owner(id, state_dir: @state_dir)) &&
-         (!@queue || session.waiting_question(live: owner.worker?))
-        # The turn waits on a question: the message would only queue
-        # behind it, and the answer goes in with chi answer.
-        if (waiting = session.waiting_question(live: owner.worker?))
-          # The whole question (its options, its tags) for what a parent may
-          # give: config.yml tightened by the session's own parent_answers.
-          strategy = Guardrails::ParentPolicy.for_session(session)
-          question = ParentReport.question(session.pending_question, strategy: strategy)
-          if ParentReport.approval?(waiting)
-            error_line("#{id[0, 8]}  waiting for an approval: #{ParentReport.approval_advice(question, strategy: strategy)} " \
-                       "(#{ParentReport.answer_with(id, question)})")
-          else
-            error_line("#{id[0, 8]}  waiting for an answer: #{ParentReport.answer_with(id, question)} (or --text); " \
-                       "chi --attach #{id} shows it")
-          end
-        else
-          error_line("#{id[0, 8]}  busy: a turn is running; wait or attach")
-        end
+      # Local: one read for the check and the baseline; remotely the
+      # server's wait prepare route reads both (Busy's words).
+      session = @access.show(id) unless @access.remote?
+      if (busy = @access.busy(id, queue: @queue, session: session))
+        error_line("#{id[0, 8]}  #{busy.message(via: @access.invocation)}")
         return 1
       end
 
-      cursor = ReplyWait.newest_reply(id, state_dir: @state_dir)
-      baseline = baseline_of(session)
-      running_turn = if session.status == Session::STATUS_RUNNING
-                       ReplyWait.own_turn(session, session_dir: Session.session_dir(id, state_dir: @state_dir))
-                     end
+      start = @access.prepare_wait(id, session: session)
       return 1 unless deliver(id, prompt)
       return report_command(id) if @sent_command
 
-      target = WaitTarget.message(@delivered, queue: @queue, running: session.status == Session::STATUS_RUNNING,
-                                              running_turn: running_turn)
-      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout], **target.to_h)
+      target = WaitTarget.message(@delivered, queue: @queue, running: start.running,
+                                              running_turn: (start.own_turn if start.running))
+      wait_for_reply(id, cursor: start.cursor, baseline: start.baseline, timeout: options[:timeout], **target.to_h)
     end
 
     # --wait with no message: the session's next reply, sending nothing,
@@ -546,24 +613,15 @@ module Samagotchi
     # @return [Integer] the exit status
     def run_wait_only(options)
       id = resolve(options[:ids].first) or return 1
-      session = Session.load(id, state_dir: @state_dir)
-      session_dir = Session.session_dir(id, state_dir: @state_dir)
       requested_turn = options[:turn]&.to_s
-      if requested_turn && !ReplyWait.known_turn?(session, session_dir: session_dir, turn: requested_turn)
+      start = @access.prepare_wait(id, turn: requested_turn)
+      if requested_turn && !start.known_turn
         error_line("chi send: turn #{requested_turn} is not a running, queued, or last ended turn")
         return 1
       end
-      live = session.status == Session::STATUS_RUNNING || SessionManager.session_owner(id, state_dir: @state_dir)
-      target = WaitTarget.wait_only(session, session_dir: session_dir, requested: requested_turn)
-      wait_for_reply(id, cursor: ReplyWait.newest_reply(id, state_dir: @state_dir),
-                         baseline: baseline_of(session),
-                         timeout: options[:timeout], owner_grace: live ? self.class::WORKER_GONE_AFTER : nil, **target.to_h)
-    end
-
-    # The session as it was before the message went in (ReplyWait's
-    # baseline).
-    def baseline_of(session, **)
-      ReplyWait.baseline_of(session, **)
+      target = WaitTarget.after(start, requested: requested_turn)
+      wait_for_reply(id, cursor: start.cursor, baseline: start.baseline,
+                         timeout: options[:timeout], owner_grace: start.live ? self.class::WORKER_GONE_AFTER : nil, **target.to_h)
     end
 
     # A new idle session's first turn, with the images. Its worker's Bridge
@@ -571,14 +629,15 @@ module Samagotchi
     # and the spawned one takes its lock only once it runs.
     # @return [Boolean] whether the message was queued
     def deliver_new(session, prompt)
-      dir = Session.session_dir(session.id, state_dir: @state_dir)
       result = nil
       begin
-        refs = copy_images(dir)
-        if BridgeClient.wait_for(session.id, session_dir: dir, timeout: SessionManager::TURN_BRIDGE_WAIT)
-          result = SessionManager.deliver_turn(session.id, prompt: prompt, client_id: client_id_for(prompt), images: refs,
-                                                           state_dir: @state_dir)
+        refs = upload_images(session.id)
+        if @access.await_worker(session.id, timeout: SessionManager::TURN_BRIDGE_WAIT)
+          result = @access.deliver_turn(session.id, prompt: prompt, client_id: client_id_for(prompt), images: refs)
         end
+      rescue SessionAccess::Refused => e
+        @info.puts("#{session.id}  refused: #{e.message}")
+        return false
       rescue StandardError => e
         @info.puts("#{session.id}  failed: #{e.message}")
         return false
@@ -586,11 +645,12 @@ module Samagotchi
       # Kept, not deleted: it holds the images, and the message shows as
       # its preview; the user can attach and send it again.
       unless result
-        @info.puts("#{session.id}  failed: its worker did not start; the session is kept (chi --attach #{session.id})")
+        attach = @access.invocation.attach(session.id)
+        @info.puts("#{session.id}  failed: its worker did not start; the session is kept#{" (#{attach})" if attach}")
         return false
       end
       unless result.accepted?
-        @info.puts("#{session.id}  failed: #{result.detail || "could not queue it"}")
+        @info.puts("#{session.id}  #{refused_word(result)}: #{result.detail || "could not queue it"}")
         return false
       end
 
@@ -602,6 +662,19 @@ module Samagotchi
 
     SENT_COMMAND = "sent as a session command"
 
+    # A remote's refusals of what this machine checks before sending (a
+    # parent's /continue yes, a loosening /parent-answers, images to a
+    # model that can't see them): its turn route's error codes.
+    REMOTE_REFUSALS = %w[parent_answers_refused parent_continue_refused no_vision].freeze
+
+    # How a delivery that didn't go in reads: refused (a worker older than
+    # queueing would steer it; a remote refused it as chi send refuses it
+    # here) or failed.
+    def refused_word(result)
+      refused = result.error == Delivery::QUEUE_UNAVAILABLE["error"] || REMOTE_REFUSALS.include?(result.error)
+      refused ? "refused" : "failed"
+    end
+
     # chi send's client id, or chi answer's for a parent agent's /continue
     # yes (the worker holds that to its guardrails.parent_answers).
     def client_id_for(prompt) = ParentGate.parent_continue?(prompt) ? ClientId::CLI_ANSWER : CLIENT_ID
@@ -636,13 +709,13 @@ module Samagotchi
       CLI::Exit::FAILED
     end
 
-    def local_refusal(name, id) = SessionCommands.ui_only_refusal(name, id, runner: "chi send")
+    def local_refusal(name, id) = SessionCommands.ui_only_refusal(name, id, runner: "chi send", remote: @access.invocation.remote)
 
     # --wait after a message that ran as a session command: no reply comes
     # for it. Its output shows where the session is open.
     # @return [Integer] 0
     def report_command(id)
-      detail = "#{SENT_COMMAND}: no reply to wait for (its output shows in chi --attach #{id} or the web)"
+      detail = "#{SENT_COMMAND}: no reply to wait for (its output shows in #{@access.invocation.open_it(id)})"
       if @json
         @stdout.puts(JSON.generate({ status: "command", session_id: id, detail: detail }))
         @stdout.flush
@@ -656,14 +729,16 @@ module Samagotchi
     # @return [Boolean] whether the message was queued
     def deliver(id, prompt)
       short = id[0, 8]
-      session = Session.load(id, state_dir: @state_dir)
+      session = @access.show(id)
+      # Machine-local (this machine's model registry): remotely the
+      # server's (P2), as for --new.
       if !@images.empty? && (refusal = vision_refusal(session.model_name, typed: session.model_typed))
         @info.puts("#{short}  refused: #{refusal}")
         return false
       end
-      owner = SessionManager.session_owner(id, state_dir: @state_dir)
+      owner = @access.owner(id)
       running = owner && session.status == Session::STATUS_RUNNING
-      refs = copy_images(Session.session_dir(id, state_dir: @state_dir))
+      refs = upload_images(id)
       # --cut asks the running turn for a cut (to an idle session an
       # ordinary message: nothing to cut). --queue always goes as a queue,
       # idle or not: the Bridge acks next_step to an idle worker and the
@@ -673,12 +748,9 @@ module Samagotchi
       delivery = if @queue then Delivery::QUEUE
                  elsif @cut && running then Delivery::CUT
                  end
-      result = SessionManager.deliver_turn(id, prompt: prompt, client_id: client_id_for(prompt), images: refs, state_dir: @state_dir,
-                                               delivery: delivery)
+      result = @access.deliver_turn(id, prompt: prompt, client_id: client_id_for(prompt), images: refs, delivery: delivery)
       unless result.accepted?
-        # A worker older than queueing would steer it: refused, not sent.
-        word = result.error == Delivery::QUEUE_UNAVAILABLE["error"] ? "refused" : "failed"
-        @info.puts("#{short}  #{word}: #{result.detail || "could not queue it"}")
+        @info.puts("#{short}  #{refused_word(result)}: #{result.detail || "could not queue it"}")
         return false
       end
 
@@ -755,14 +827,12 @@ module Samagotchi
     # What to say when +model_name+ is known not to take images, or nil
     # (it does, or it is unknown: sent as before). Asked once per model.
     def vision_refusal(model_name, typed: nil)
+      # Remotely the server's (check_vision on its turn and create routes).
+      return nil if @access.remote?
+
       @vision ||= {}
       answer = @vision[[model_name.to_s, typed.to_s]] ||= self.class.vision_answer(model_name, typed: typed)
-      return nil unless answer.no?
-
-      name = model_name.to_s.strip
-      name = Samagotchi::Config.get("default.model").to_s.strip if name.empty?
-      name = "the model" if name.empty?
-      "#{name} can't take images (#{answer.reason}); send text only or switch the model (/model)"
+      self.class.vision_refusal(model_name, answer)
     end
 
     # Each --image read, converted and downscaled once, into a scratch
@@ -781,13 +851,8 @@ module Samagotchi
       false
     end
 
-    # The images' files copied into a session dir, as the refs a turn takes.
-    def copy_images(session_dir)
-      @images.map do |ref|
-        ImageStore.copy_file(ref, from: @image_dir, to: session_dir)
-        { file: ref[:file], name: ref[:name] }
-      end
-    end
+    # The images' files copied into the session, as the refs a turn takes.
+    def upload_images(id) = @access.upload_images(id, @images, from: @image_dir)
 
     def with_images
       case @images.size

data/lib/samagotchi/session.rb

@@ -12,6 +12,7 @@ require_relative "pending_question"
 require_relative "llm_context_override"
 require_relative "session_setup"
 require_relative "prompt_note"
+require_relative "working_set_pin"
 
 require_relative "paths"
 require_relative "project_scope"
@@ -249,6 +250,17 @@ module Samagotchi
                         end
     end
 
+    # The working set's items the user pinned (/working-set pin;
+    # WorkingSetPin), [] with none: the model's forget_outputs refuses
+    # their outputs. A respawn, a continue and a fork keep them
+    # (SessionSetup.of); a delegate child starts without.
+    attr_reader :working_set_pins
+
+    # @param value [Array<WorkingSetPin, Hash>] the session file's form too
+    def working_set_pins=(value)
+      @working_set_pins = WorkingSetPin.list(value)
+    end
+
     # The hook that stopped the last turn (stop_turn, or a cut with no retry
     # left), e.g. "loop-guard"; nil when it ended otherwise.
     def stopped_by
@@ -283,7 +295,8 @@ module Samagotchi
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
                    continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
-                   toolkit: nil, settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil)
+                   toolkit: nil, settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
+                   working_set_pins: [])
       @id = id
       @metadata_version = metadata_version
       @mode = mode
@@ -316,6 +329,7 @@ module Samagotchi
       self.toolkit = toolkit
       self.settings = settings
       self.parent_answers = parent_answers
+      self.working_set_pins = working_set_pins
       self.interrupted_turn = interrupted_turn
       @turn_checkpoint = nil
       @archived = false
@@ -415,6 +429,7 @@ module Samagotchi
         toolkit: setup.toolkit,
         settings: setup.settings,
         parent_answers: setup.parent_answers,
+        working_set_pins: setup.working_set_pins,
         continues: continues
       )
     end
@@ -484,7 +499,8 @@ module Samagotchi
       "bundle_settings" => {},
       "config_settings" => {},
       "interrupted_turn" => nil,
-      "parent_answers" => nil
+      "parent_answers" => nil,
+      "working_set_pins" => []
     }.freeze
 
     # A session from a parsed session file. +messages+ false leaves the
@@ -499,8 +515,16 @@ module Samagotchi
       new(**attrs)
     end
 
-    # A prefix that names more than one session.
-    class AmbiguousId < ArgumentError; end
+    # A prefix that names more than one session: +ids+ are the sessions it
+    # names (sorted), the message lists them with their first previews.
+    class AmbiguousId < ArgumentError
+      attr_reader :ids
+
+      def initialize(message = nil, ids: [])
+        @ids = ids
+        super(message)
+      end
+    end
 
     # A session id or a unique prefix of one (like git's): the full id. An
     # unknown one comes back as is, for the caller's own "not found"; one that
@@ -518,7 +542,7 @@ module Samagotchi
       rescue JSON::ParserError, SystemCallError
         "  #{match}"
       end
-      raise AmbiguousId, "session id #{id} matches #{matches.size} sessions:\n#{lines.join("\n")}"
+      raise AmbiguousId.new("session id #{id} matches #{matches.size} sessions:\n#{lines.join("\n")}", ids: matches)
     end
 
     # Return all saved sessions sorted by updated_at desc by default (newest first).
@@ -627,6 +651,7 @@ module Samagotchi
                 when "config_settings" then @settings.core
                 when "prompt_notes" then @prompt_notes.map(&:to_file)
                 when "last_turn" then @last_turn&.to_file
+                when "working_set_pins" then @working_set_pins.map(&:to_file)
                 when "used_memory_names", "preloaded_memory_names", "muted_memory_names", "appended_prompt_files"
                   Array(instance_variable_get(:"@#{key}"))
                 else instance_variable_get(:"@#{key}")