samagotchi 0.139.1 → 0.141.0

data/lib/samagotchi/engine.rb

@@ -46,6 +46,12 @@ require_relative "llm/turn_settings"
 require_relative "session"
 require_relative "toolkit_binding"
 require_relative "participant_mode"
+require_relative "context_candidates"
+require_relative "context_candidates_log"
+require_relative "context_candidate_choice"
+require_relative "context_judge"
+require_relative "owner_prompt"
+require_relative "side_judgments"
 require_relative "toolkit_suggest"
 require_relative "tool_loads"
 require_relative "answer_tail"
@@ -162,7 +168,12 @@ module Samagotchi
       @no_interrupt = no_interrupt
       @chat_backend = nil
       @chat_backend_mutex = Mutex.new
-      @toolkit_audit_thread = nil
+      @side_judgments = SideJudgments.new
+      @context_judge_after_turn = nil
+      # On mode's cards an answer brought while a turn ran: shown once it
+      # has ended (#show_context_cards_after_turn).
+      @context_cards_after_turn = []
+      @context_cards_mutex = Mutex.new
       @toolkit_warmup_thread = nil
       @host_registry = host_registry || HostRegistry.new
       # A model given here (a worker's session model) is the one it runs,
@@ -1123,10 +1134,10 @@ module Samagotchi
 
     # How long #shutdown waits for the running anytime commands, in all.
     SHUTDOWN_JOIN_SECONDS = 3.0
-    # How long #shutdown waits for a running toolkit audit ask (a one-shot
-    # -p --non-interactive exits right after its turn); a slower ask goes
-    # unlogged.
-    TOOLKIT_AUDIT_JOIN_SECONDS = 1.0
+    # How long #shutdown waits for the running side judgments (System 1
+    # asks: SideJudgments; a one-shot -p --non-interactive exits right
+    # after its turn), in all; a slower ask goes unlogged.
+    SIDE_JUDGMENTS_JOIN_SECONDS = 1.0
 
     # The REPL or the session's worker is leaving (/exit, an idle exit, a
     # crash, TERM): stop the idle jobs, give the running anytime commands
@@ -1152,7 +1163,7 @@ module Samagotchi
 
         thread.join([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max)
       end
-      @toolkit_audit_thread&.join(TOOLKIT_AUDIT_JOIN_SECONDS)
+      @side_judgments.join(SIDE_JUDGMENTS_JOIN_SECONDS)
       # The warm-up's answer is dropped anyway.
       stop_toolkit_warmup
       left = threads.count(&:alive?)
@@ -2305,7 +2316,10 @@ module Samagotchi
                                 pending_input: pending_input)
         publish_used_memories(session, on_event)
         complete_turn(turn, result)
-        warm_up_next_turn(turn, result)
+        # The candidate judge's asks a shared local server kept for the
+        # turn's end go first; the warm-up follows them and re-warms the
+        # prefix they evicted.
+        warm_up_next_turn(turn, result, after: run_context_judge_after_turn)
         result
       rescue Interrupt => e
         # After the end event (in the after_turn/session_end hooks) the
@@ -2332,6 +2346,8 @@ module Samagotchi
         raise
       ensure
         release_turn(probe_cancel_before)
+        show_context_cards_after_turn
+        run_context_judge_after_turn
       end
     end
 
@@ -2432,6 +2448,10 @@ module Samagotchi
       # On mode: the suggested kit, before anything is declared (a Stop
       # during the wait is caught by the check below).
       settle_toolkit_suggestion(turn, toolkit_suggestion)
+      # The candidate judge: its asks run beside the turn on a remote
+      # System 1 host, after it on the model's own local one; on mode's
+      # attaches reach the model at the next between-turn delivery.
+      start_context_judge(turn)
       apply_toolkit!(session, turn.on_event)
       refresh_participants!(session)
       # A Stop during the waits above: the turn ends here,
@@ -2509,7 +2529,7 @@ module Samagotchi
     # start differs anyway or starts at once: a reminder due, a continue
     # offer (the turn ran out of steps), a carried steer or queued input.
     # Never fails the turn.
-    def warm_up_next_turn(turn, result)
+    def warm_up_next_turn(turn, result, after: nil)
       return if result.canceled? || result.resumable?
 
       model = effective_model
@@ -2524,7 +2544,7 @@ module Samagotchi
       return unless prompt
 
       started = @prompt_warmup.start(client: client, prompt: prompt, model: @kernel.turn_settings.model_name,
-                                     slot: @kernel.last_slot, images: images)
+                                     slot: @kernel.last_slot, images: images, after: after)
       @kernel.warmed_up! if started
     rescue StandardError => e
       Log.warn(:model, "warmup_skipped", error: e.class.name, msg: e.message.to_s[0, 200])
@@ -3030,7 +3050,7 @@ module Samagotchi
 
       # One ask at a time: an eligible turn while the last one still runs
       # goes unasked, and says so.
-      if @toolkit_audit_thread&.alive?
+      if @side_judgments.in_flight?(:toolkit)
         Log.info(:toolkit, "toolkit_suggest_in_flight_skipped", session_id: session.id)
         return
       end
@@ -3042,7 +3062,7 @@ module Samagotchi
       # with the turn's prefill, and any ask evicts the session's cached
       # prefix: on mode asks only on a first turn there (nothing is cached
       # yet worth keeping), never on the deferred path.
-      if (!joined || ToolkitSuggest.model_reply?(session.messages)) && toolkit_judge_shares_local_host?(client.host)
+      if (!joined || ToolkitSuggest.model_reply?(session.messages)) && system_one_shares_local_host?(client.host)
         Log.info(:toolkit, "toolkit_suggest_shared_host_skipped", session_id: session.id, host: client.host)
         return
       end
@@ -3076,18 +3096,9 @@ module Samagotchi
       # On mode: cut by a Stop while the turn waits (Pending#wait), not
       # by one after it went on; audit's ask is never cut.
       controller = joined ? pending.cancel_controller : nil
-      @toolkit_audit_thread = Thread.new do
-        judged = nil
-        begin
-          judged = ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
-                                        cancel_controller: controller)
-        rescue LLM::RequestCancelled
-          nil
-        rescue StandardError => e
-          ToolkitSuggest.warn(e)
-        ensure
-          pending.finish(judged)
-        end
+      @side_judgments.start(:toolkit, warn: ToolkitSuggest.method(:warn), finish: pending.method(:finish)) do
+        ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
+                             cancel_controller: controller)
       end
       joined ? pending : nil
     rescue StandardError => e
@@ -3174,7 +3185,7 @@ module Samagotchi
       return unless client
       # D7: on the model's own single-slot server it would evict the
       # session's cached prefix for a question that may never come.
-      return if toolkit_judge_shares_local_host?(client.host)
+      return if system_one_shares_local_host?(client.host)
 
       project = File.basename(session.project_root.to_s)
       @toolkit_warmup_thread = Thread.new do
@@ -3195,18 +3206,14 @@ module Samagotchi
     private :stop_toolkit_warmup
 
     def toolkit_suggestion_log
-      path = ToolkitSuggest.log_path(session_state_dir)
-      SystemOne::Log.new(dir: File.dirname(path), file: File.basename(path),
-                         warn: lambda { |reason|
-                           Log.warn(:toolkit, "toolkit_suggest_log_failed", echo: "[samagotchi:toolkit] #{reason}")
-                         })
+      SideJudgments.log(ToolkitSuggest.log_path(session_state_dir), tag: :toolkit, event: "toolkit_suggest_log_failed")
     end
     private :toolkit_suggestion_log
 
     # D7: System 1's host is the session's model server, and a local one
     # (a single-slot Splash or llama.cpp): the same name, or two hosts:
     # entries for one server root (scheme, host, port).
-    def toolkit_judge_shares_local_host?(judge_name)
+    def system_one_shares_local_host?(judge_name)
       model_host, = @host_registry.host_for_model(effective_model_name)
       return false if model_host.nil? || model_host.remote?
       return true if judge_name.to_s.strip.casecmp?(model_host.name.to_s)
@@ -3214,7 +3221,156 @@ module Samagotchi
       judge = @host_registry.find_entry(judge_name)
       !judge.nil? && judge.root_url.downcase == model_host.root_url.downcase
     end
-    private :toolkit_judge_shares_local_host?
+    private :system_one_shares_local_host?
+
+    # The candidate judge (ContextJudge) at an owner turn's start, after
+    # the toolkit's ask settled: the session's candidates' status changes
+    # are logged (ContextCandidatesLog#look) and, unless
+    # context.candidates.mode is off, the proposed candidates due an ask
+    # are asked about the owner's prompts so far, this one included. Never
+    # a participant's turn, a review session or a Continue (no new prompt).
+    def start_context_judge(turn)
+      session = turn.session
+      return unless turn.prompt.is_a?(String) && OwnerPrompt.turn?(session: session, author: turn.origin.author)
+
+      context_judge_pass(session, ContextCandidates.owner_texts(session.messages) + [turn.prompt], phase: "turn")
+    end
+    private :start_context_judge
+
+    # A late proposal no owner prompt mentions (Plugin::Host
+    # #candidate_proposed: github-pr's init task runs beside the first
+    # turn): judged on the owner's prompts so far, the running turn's too.
+    def judge_late_candidates
+      session = @session
+      return if session.nil? || session.review?
+
+      texts = ContextCandidates.owner_texts(plugin_messages)
+      context_judge_pass(session, texts, phase: "late") unless texts.empty?
+    end
+    private :judge_late_candidates
+
+    # One look at +session+'s candidates; the asks go to SideJudgments'
+    # :context kind, one thread asking each due candidate in turn. On the
+    # model's own local server (#system_one_shares_local_host?) the asks
+    # wait for the running turn's end (#run_context_judge_after_turn),
+    # never competing with its prefill; any other host is asked now.
+    def context_judge_pass(session, texts, phase:)
+      return if session.id.nil? || session.scratch
+
+      rows = ContextCandidates.with_status(session.id, project_root: session.project_root, state_dir: session_state_dir)
+      return if rows.empty?
+
+      log = ContextCandidatesLog.log_for(session_state_dir)
+      records = ContextCandidatesLog.records_for(log, session.id)
+      ContextCandidatesLog.look(log, session.id, rows, records) if phase == "turn"
+      settings = ContextJudge::Settings.from_config
+      return if settings.mode == "off"
+
+      jobs = ContextJudge.jobs(rows, records, session_id: session.id, texts: texts, settings: settings, phase: phase,
+                                              parent_attached: context_parent_attached(session))
+      return if jobs.empty?
+
+      client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context)
+      return unless client
+
+      choice = context_choice(session, log, settings)
+      ask = -> { start_context_asks(client, jobs, log, settings, choice) }
+      if turn_running? && system_one_shares_local_host?(client.host)
+        Log.info(:context, "context_judge_after_turn", session_id: session.id, host: client.host)
+        @context_judge_after_turn = ask
+      else
+        ask.call
+      end
+    rescue StandardError => e
+      ContextJudge.warn(e)
+    end
+    private :context_judge_pass
+
+    # @return [Thread, nil] the asks' thread, nil when none started
+    def start_context_asks(client, jobs, log, settings, choice)
+      if @side_judgments.in_flight?(:context)
+        Log.info(:context, "context_judge_in_flight_skipped", session_id: jobs.first.session_id)
+        return nil
+      end
+
+      @side_judgments.start(:context, warn: ContextJudge.method(:warn)) do
+        jobs.each { |job| choice.call(job, ContextJudge.ask(client: client, job: job, log: log, settings: settings)) }
+      end
+    end
+    private :start_context_asks
+
+    # What an answer does on the asks' thread (ContextCandidateChoice
+    # #after_judged: on mode attaches or cards; audit nothing). Taken on
+    # the caller's thread. The attach only writes the session's folder: its
+    # note comes with the next between-turn delivery, never into a running
+    # turn. A card shows only while this Engine is still on that session,
+    # and not in a running turn (it isn't the turn's: no "waiting for you"
+    # on it), but once it has ended.
+    # @return [#call] (job, fields)
+    def context_choice(session, log, settings)
+      session_id = session.id
+      project_root = session.project_root
+      state_dir = session_state_dir
+      show = lambda do |**card|
+        current = @session
+        next nil unless current.nil? || current.id == session_id
+
+        @context_cards_mutex.synchronize do
+          next @context_cards_after_turn << card if turn_running?
+
+          show_card(**card)
+        end
+      end
+      lambda do |job, fields|
+        ContextCandidateChoice.after_judged(job: job, fields: fields, settings: settings, project_root: project_root,
+                                            state_dir: state_dir, log: log, show_card: show)
+      end
+    end
+    private :context_choice
+
+    # The cards #context_choice held while a turn ran (#run_turn's ensure,
+    # after the turn flag is released).
+    def show_context_cards_after_turn
+      cards = @context_cards_mutex.synchronize { @context_cards_after_turn.slice!(0..) }
+      cards.each { |card| show_card(**card) }
+    rescue StandardError => e
+      ContextJudge.warn(e)
+    end
+    private :show_context_cards_after_turn
+
+    # The asks a shared local host kept for the turn's end: a completed
+    # turn starts them before its warm-up (which waits for them,
+    # PromptWarmup#start's after:); a turn that ended otherwise, from
+    # #run_turn's ensure.
+    # @return [Thread, nil] the asks' thread
+    def run_context_judge_after_turn
+      ask = @context_judge_after_turn or return nil
+      @context_judge_after_turn = nil
+      ask.call
+    rescue StandardError => e
+      ContextJudge.warn(e)
+      nil
+    end
+    private :run_context_judge_after_turn
+
+    # A delegate child's parent's sources, by title (else name): the
+    # judge's started_from. nil for any other session (a chi send --new
+    # session has no parent; a fork isn't a delegate).
+    def context_parent_attached(session)
+      return nil unless session.delegate? && session.parent_id
+
+      parent_root = if Session.exist?(session.parent_id, state_dir: session_state_dir)
+                      Session.load(session.parent_id, state_dir: session_state_dir).project_root
+                    else
+                      session.project_root
+                    end
+      ContextSources.attached(session.parent_id, project_root: parent_root, state_dir: session_state_dir)
+                    .map { |attached| attached.source.title || attached.name }
+    rescue StandardError => e
+      Log.warn(:context, "context_parent_attached_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+      []
+    end
+    private :context_parent_attached
 
     # The session's toolkit (see #initialize for when).
     def build_toolkit_binding
@@ -3294,7 +3450,8 @@ module Samagotchi
         usage: -> { @metrics.usage },
         turn_author: -> { turn_author },
         # A plugin's prompt section is in the stable part: a full re-read.
-        cache_confirm: ->(line, changed) { CacheConfirm.ask(line: line, cost: :full, changed: changed, engine: self) }
+        cache_confirm: ->(line, changed) { CacheConfirm.ask(line: line, cost: :full, changed: changed, engine: self) },
+        candidate_proposed: ->(_candidate) { judge_late_candidates }
       )
     end
 

data/lib/samagotchi/owner_prompt.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "message_time"
+require_relative "steer"
+
+module Samagotchi
+  # The session owner's own words: the one rule for what may act on a
+  # session's conversation by itself (toolkit suggest, attached context's
+  # candidates). A participant's turn and a review session never do.
+  module OwnerPrompt
+    module_function
+
+    # The owner's own prompt: a user line the Engine kept for a turn (it
+    # carries the turn's id), or TurnCheckpoint's line for a turn killed
+    # before its first boundary (stamped, no id). A !command's output, a
+    # declined continue's reason and KernelLoop's recovery prompt are
+    # neither; steers, notes and reminders carry their kind.
+    def message?(message)
+      field(message, :role).to_s == "user" &&
+        !Steer.participant_author?(field(message, :author)) &&
+        !%w[input steer note reminder].include?(field(message, :kind).to_s) &&
+        !field(message, :preserve_literals) &&
+        !(field(message, :turn_id) || field(message, MessageTime::KEY)).nil?
+    end
+
+    # Whether a turn by +author+ in +session+ is the owner's own: not a
+    # participant's, not in a review session.
+    def turn?(session:, author:)
+      !session&.review? && !Steer.participant_author?(author)
+    end
+
+    def field(hash, key)
+      return nil unless hash.is_a?(Hash)
+
+      hash.key?(key) ? hash[key] : hash[key.to_s]
+    end
+    private_class_method :field
+  end
+end

data/lib/samagotchi/plugin/api.rb

@@ -49,6 +49,7 @@ module Samagotchi
         "chi.toolkit(prompt:)" => "0.72.0", "ctx.ask_model(model:)" => "0.80.0", "chi.toolkit(groups:)" => "0.121.0",
         "chi.prompt_section" => "0.132.0", "chi.prompt_changed" => "0.132.0", "ctx.cache_confirm" => "0.132.0",
         "ctx.model_names" => "0.132.0"
+        # Unreleased: "ctx.context.propose", "ctx.context.candidates", "ctx.context.withdraw", "ctx.review".
       }.freeze
 
       # @param bundle [String]

data/lib/samagotchi/plugin/attached_context.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "../context_candidates"
+require_relative "../context_candidates_log"
 require_relative "../context_sources"
 require_relative "../context_providers"
 require_relative "../session"
@@ -29,12 +31,15 @@ module Samagotchi
       # session (its name, or its URL) isn't attached again (#declined?)
       # until the user adds it again, or +force+: the user's own explicit
       # choice (a click), which clears the declined marker (by the name,
-      # and by the URL).
+      # and by the URL). +movable+: whether a continue or a fork takes it
+      # to the new session (nil: the default, a command source moves;
+      # ContextSources::Source#movable?).
       # @return [String, nil] the source's name; nil when declined
       # @raise [Error]
-      def attach(url: nil, name: nil, cmd: nil, why: nil, hint: nil, every_seconds: nil, force: false)
+      def attach(url: nil, name: nil, cmd: nil, why: nil, hint: nil, every_seconds: nil, force: false, movable: nil)
         own = own_location!
         source = url ? from_url(url, name: name, why: why) : from_cmd(name: name, cmd: cmd, why: why, hint: hint, every_seconds: every_seconds)
+        source = source.with(movable: movable ? true : false) unless movable.nil?
         if force
           own.undecline(source.name, hint: url && source.hint)
         elsif own.declined?(source.name) || (url && own.declined_hints.include?(source.hint))
@@ -76,22 +81,65 @@ module Samagotchi
         name_declined?(own, name) || (!url.to_s.empty? && own.declined_hints.include?(url))
       end
 
-      # Records that this plugin offered +name+ (+hint+: its URL; +why+: the
-      # reason an attach from the offer gives) here, so a worker restart
-      # doesn't offer it again.
-      # @return [ContextSources::Offer]
+      # Proposes a source for this session without attaching it: +url+
+      # (through an installed bundle's provider; +name+ replaces the
+      # provider's) or +name+ and +cmd+. +title+ is what a person (or a
+      # judge) reads, +describe+ more of it, +mentions+ the words an owner
+      # prompt names it by (ContextCandidates.mention_in). Idempotent by
+      # name: a candidate of that name stays as first proposed. Nothing is
+      # proposed in a review session, for a source attached already (by its
+      # name or URL, at any scope) or for one the user removed from the
+      # session (its name, or its URL). A new candidate an owner prompt
+      # already in the session mentions is attached at once (its note comes
+      # with the next turn).
+      # @return [ContextSources::Candidate, nil] nil when nothing was proposed
       # @raise [Error]
-      def mark_offered(name, hint, why: nil)
-        own_location!.mark_offered(name, hint, why: why)
-      rescue ContextSources::Invalid => e
+      def propose(title:, url: nil, name: nil, cmd: nil, describe: nil, mentions: [])
+        own = own_location!
+        candidate = new_candidate(url: url, name: name, cmd: cmd, title: title, describe: describe, mentions: mentions)
+        return nil if own.declined?(candidate.name) || (url && own.declined_hints.include?(candidate.url))
+
+        session = saved_session
+        return nil if session&.review? || attached?(candidate, session)
+
+        recorded = own.add_candidate(candidate)
+        if recorded.equal?(candidate)
+          ContextCandidatesLog.event("proposed", session_id: own.key, name: candidate.name, state_dir: state_dir,
+                                                 title: candidate.title, by: candidate.proposed_by)
+          late_match(recorded, own)
+        end
+        recorded
+      rescue ContextSources::Invalid, ContextProviders::Invalid => e
         raise Error, e.message
       end
 
-      # @return [ContextSources::Offer, nil] the offer #mark_offered recorded
-      def offered(name)
-        location&.offered(name)
+      # This session's candidates (#propose), by name; none before the
+      # session has an id.
+      # @return [Array<ContextSources::Candidate>]
+      def candidates
+        location&.candidates || []
+      end
+
+      # What the continue that started this session left with the previous
+      # link (pushed sources, a peer's pairing among them): each one's name,
+      # hint (its last pushed one, else the source's) and the session it
+      # stayed in. Read-only; none for a session that isn't a continue's.
+      # @return [Array<ContextSources::Left>]
+      def left_behind
+        location&.left || []
+      end
+
+      # Takes back this session's candidate +name+. A source attached from
+      # it stays attached (chi context rm removes that).
+      # @return [Boolean] whether there was one
+      def withdraw(name)
+        own = location or return false
+        return false unless own.remove_candidate(name)
+
+        ContextCandidatesLog.event("withdrawn", session_id: own.key, name: name, state_dir: state_dir)
+        true
       rescue ContextSources::Invalid
-        nil
+        false
       end
 
       # This session's sources (its own, then its project's); none before
@@ -136,6 +184,30 @@ module Samagotchi
 
       def own_location! = location || raise(Error, "this session has no id yet")
 
+      # The session's saved file, nil before it has one.
+      def saved_session
+        id = @host.session_id.call
+        id && Session.exist?(id, state_dir: state_dir) ? Session.load(id, state_dir: state_dir) : nil
+      end
+
+      def attached?(candidate, session)
+        ContextSources.attached(session&.id || @host.session_id.call, project_root: session&.project_root,
+                                                                      state_dir: state_dir, shadowed: true)
+                      .any? { |a| a.name == candidate.name || (candidate.url && a.source.hint == candidate.url) }
+      end
+
+      # A late proposal: the owner's prompts so far may name it already;
+      # one that none names goes to the candidate judge (the Engine's
+      # #judge_late_candidates, when the host has one).
+      def late_match(candidate, own)
+        messages = @host.messages&.call or return
+        return if ContextCandidates.after_propose(candidate, own: own, messages: messages, state_dir: state_dir)
+
+        @host.candidate_proposed&.call(candidate)
+      rescue StandardError => e
+        Samagotchi::Log.warn(:context, "candidate_late_match_failed", name: candidate.name, error: e.class.name)
+      end
+
       def location
         id = @host.session_id.call
         id && ContextSources.session_location(id, state_dir: state_dir)
@@ -147,6 +219,26 @@ module Samagotchi
                hint: resolved.hint, every_seconds: resolved.every_seconds, provider: resolved.bundle)
       end
 
+      def new_candidate(url:, name:, cmd:, title:, describe:, mentions:)
+        if url
+          resolved = ContextProviders.resolve(url) or raise Error, "no installed bundle resolves #{url}"
+          name = name ? ContextSources.check_name!(name) : resolved.name
+          cmd = nil
+        else
+          raise Error, "give url: or cmd: (with name:)" if cmd.to_s.strip.empty?
+
+          name = ContextSources.check_name!(name)
+        end
+        title = ContextSources.one_line(title, ContextSources::LINE_MAX_CHARS) or raise Error, "give title:"
+        ContextSources::Candidate.new(
+          name: name, url: url&.to_s, cmd: cmd&.to_s, title: title,
+          describe: ContextSources.one_line(describe, ContextSources::DESCRIBE_MAX_CHARS),
+          mentions: Array(mentions).filter_map { |word| ContextSources.one_line(word.to_s, ContextSources::LINE_MAX_CHARS) }
+                                   .uniq.first(ContextSources::MENTIONS_MAX),
+          proposed_by: "plugin:#{@bundle}", at: Time.now.utc.iso8601
+        )
+      end
+
       def from_cmd(name:, cmd:, why:, hint:, every_seconds:)
         raise Error, "give url: or cmd: (with name:)" if cmd.to_s.strip.empty?
 

data/lib/samagotchi/plugin/context.rb

@@ -63,11 +63,13 @@ module Samagotchi
     # CacheConfirm::Confirm when the change must ask first (CacheConfirm.ask
     # with cost :full), else nil. +model_names+ returns the names the
     # session's model is looked up under (EffectiveModel#names).
+    # +candidate_proposed+ takes (candidate): a late proposal no owner
+    # prompt mentions, for the candidate judge (Engine#judge_late_candidates).
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit, :load_tools,
                       :cancel_controller, :cost, :usage, :turn_author, :cache_confirm, :model_names,
-                      keyword_init: true)
+                      :candidate_proposed, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -265,6 +267,15 @@ module Samagotchi
       # another session handed over, not the user's own.
       def delegate? = !!saved_session&.delegate?
 
+      # Whether the session is a review session (`chi review`, Session#review?):
+      # one its participants read, not the owner's working session.
+      def review? = !!saved_session&.review?
+
+      # The id of the session this one continues (a continue's new link,
+      # Session#continues), else nil.
+      # @return [String, nil]
+      def continues = saved_session&.continues
+
       # Whether the session is a fork (ctx.sessions.fork: /btw keep, a
       # plugin's): it has a parent and isn't a delegate child, and it
       # started from a conversation, so its first prompt isn't its first

data/lib/samagotchi/plugin/peer.rb

@@ -40,6 +40,12 @@ module Samagotchi
     # quote. Such a text is titled by its first quoted line, not the quote's
     # `From your thinking:` label.
     #
+    # A continue leaves the pairing with the previous link (its inbox and
+    # outbox are pushed sources: ContextSources.move). The new link's quiet
+    # init task (#pair_again) posts the `moved` message to the inbox left
+    # behind, once, so the peer pairs again with the new id; its chi-peer
+    # skill knows how it paired.
+    #
     # A subclass (the bundle's Plugin) sets the strings, as constants:
     # INBOX, OUTBOX ("<peer>-inbox", "-outbox"), BUNDLE, NAME (the peer, as
     # the model and user call it: "Claude"), APP (its product: "Claude
@@ -62,6 +68,8 @@ module Samagotchi
       PAIR_PLACEHOLDER = "__CHI_PEER_PAIR__"
       PAYLOADS_PLACEHOLDER = "__CHI_PEER_PAYLOADS__"
       DIFF_LINES = 20
+      # Under the session's data dir: the moved message went (or was tried).
+      MOVED_MARKER = "moved-posted"
       # The label line a web quote starts with (annotations.js sourceLabel).
       QUOTE_LABEL = /\AFrom (?:your thinking|your earlier step|the .+ call|my earlier message):\z/
 
@@ -90,6 +98,7 @@ module Samagotchi
           run_command(args.to_s.strip, ctx)
         end
         chi.annotation "Confirm with #{peer::NAME}", command: "#{peer::COMMAND} validate"
+        chi.init("Asking #{peer::NAME} to pair again", quiet: true) { |ctx| pair_again(ctx) }
         # The outbox source is the peer's answers: its own wake budget and
         # line (context.peer_turns).
         chi.peer_source peer::OUTBOX, label: peer::NAME
@@ -130,8 +139,52 @@ module Samagotchi
         "sent to #{self.class::NAME}: #{kind} · #{title}#{" (the text in #{where})" unless where == "inline"}"
       end
 
+      # A continue's new link whose previous link kept this peer's INBOX
+      # (ctx.context.left_behind): posts the moved message to that inbox's
+      # hint, once (a marker under the session's data dir: a worker restart
+      # doesn't post again). A post that fails is logged and dropped: no
+      # retry, and the peer's next push to the old id is refused with the
+      # new one (its skill pairs again then).
+      # @return [String] what it did (the quiet init task's summary)
+      def pair_again(ctx)
+        peer = self.class
+        previous = ctx.continues or return "not a continue"
+        id = ctx.session_id or return "no session yet"
+        left = ctx.context.left_behind.find { |row| row.name == peer::INBOX }
+        hint = left&.hint.to_s.strip
+        return "no #{peer::INBOX} left behind" if hint.empty?
+        return "asked already" unless claim_moved(ctx, id)
+
+        check_hint!(hint)
+        post(hint, moved_message(previous, id))
+        "asked #{peer::NAME} to pair again with #{id[0, 8]}"
+      rescue SendError, SystemCallError, ArgumentError => e
+        ctx.log.warn("moved_not_posted", error: e.message)
+        "couldn't ask #{peer::NAME} to pair again: #{e.message}"
+      end
+
+      # What the peer gets when +previous+ was continued as +id+: the usual
+      # header, kind moved, and how to go on. Not a literal pair command:
+      # the skill knows how its peer paired (a remote, an ssh socket).
+      def moved_message(previous, id)
+        short = previous.to_s[0, 8]
+        "chi #{short} · moved · continued as #{id}\n" \
+          "This chi session was continued as #{id}. Pair with #{id} the way you paired with #{short}, then " \
+          "answer there (chi context push #{self.class::OUTBOX} #{id})."
+      end
+
       private
 
+      # Takes the moved marker for session +id+; false when it is there.
+      def claim_moved(ctx, id)
+        File.open(File.join(session_dir(ctx, id), MOVED_MARKER), File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+          file.write("#{Time.now.utc.iso8601}\n")
+        end
+        true
+      rescue Errno::EEXIST
+        false
+      end
+
       # The transport: sends +text+ to the peer at +hint+ (the inbox's hint).
       # @raise [SendError]
       def post(_hint, _text) = raise(NotImplementedError, "#{self.class} must define #post")