samagotchi 0.152.0 → 0.154.0

data/lib/samagotchi/child_move.rb

@@ -47,7 +47,7 @@ module Samagotchi
     # What a continue does with the previous link's children: +move+ the
     # direct children whose subtree has an open node (they go to the new
     # link, their subtrees with them), +refuse+ the open ones it can't move
-    # (SessionContinue::OpenChild, why: an older chi worker or a chi REPL).
+    # (SessionContinue::OpenChild, why: an older chi worker or a one-turn chi run).
     Plan = Data.define(:move, :refuse)
     # A move under way: from the session, the children moved, and those
     # already sent their note (so a move finished again notes no one twice).
@@ -87,14 +87,14 @@ module Samagotchi
       Plan.new(move: move, refuse: refuse)
     end
 
-    # Why a child's live owner keeps it from moving: a chi REPL holds its
+    # Why a child's live owner keeps it from moving: a one-turn chi run holds its
     # own Session and never reads the override; a worker on an older chi
     # neither. A worker with no sidecar yet is starting, on the newest chi
     # installed (SessionManager.worker_command): it moves.
     # @return [String, nil]
     def unmovable(child_id, state_dir:)
       link = WorkerLink.resolve(Session.session_dir(child_id, state_dir: state_dir), unlink: false)
-      return "open in a chi REPL; close it there" if link.owner&.tui?
+      return "#{OwnerLock::TUI_BUSY}; let it finish" if link.owner&.tui?
       return nil if !link.live? || link.features.include?(FEATURE)
 
       "older chi worker#{" #{link.version}" if link.version}; restart it"

data/lib/samagotchi/commands/registry.rb

@@ -29,9 +29,9 @@ module Samagotchi
       # @!attribute mid_turn [Symbol, #call] what a line of it does while a
       #   turn runs (MID_TURN): a symbol, or a lambda line (stripped) → one
       # @!attribute local [Boolean] the UI runs it; completion and help only
-      # @!attribute uis [Array<Symbol>, nil] a local entry's UIs (:repl,
-      #   :attached, :web) for completion and /help; nil means every UI
-      #   (for a local entry, every terminal)
+      # @!attribute uis [Array<Symbol>, nil] a local entry's UIs (:attached,
+      #   :web) for completion and /help; nil means every UI (for a local
+      #   entry, the terminal)
       # @!attribute match [#call] line (stripped) → whether it is this command
       # @!attribute handler [Proc, nil] runs it; SessionCommands instance_execs
       #   a built-in's with the line, and calls a bundle's with the text
@@ -165,8 +165,8 @@ module Samagotchi
       end
 
       # @return [Entry, nil] the first entry the UI runs itself (local) that
-      #   matches +line+, whatever its uis (a UI answers the others' too:
-      #   the REPL's /detach note)
+      #   matches +line+, whatever its uis (a UI answers the others' too,
+      #   with a note)
       def lookup_local(line)
         text = line.to_s.strip
         @entries.find { |entry| entry.local && entry.match?(text) }
@@ -190,7 +190,7 @@ module Samagotchi
         end
       end
 
-      # @param ui [Symbol] :repl or :attached
+      # @param ui [Symbol] :attached
       # @return [Array<String>] the /names Tab offers in +ui+, sorted
       def completions(ui)
         @entries.select { |entry| entry.slash? && entry.in_ui?(ui) }.map(&:name).uniq.sort

data/lib/samagotchi/composer_route.rb

@@ -3,11 +3,10 @@
 require_relative "delivery"
 
 module Samagotchi
-  # Where a line typed at a terminal's prompt goes, for both terminals (the
-  # REPL's TerminalUI#steer_line / #run_input_line, the attached
-  # AttachedLoop#submit). It only classifies; each UI keeps what it does
-  # with the answer (the REPL's mid-turn command policy and image lines, the
-  # attached TUI's continue offer and question). The web's composer.js
+  # Where a line typed at a terminal's prompt goes (AttachedLoop#submit; a
+  # -p prompt's /cut or /queue: TerminalUI#run). It only classifies; each
+  # UI keeps what it does with the answer (the attached TUI's continue
+  # offer and question). The web's composer.js
   # routeComposerLine decides the same; spec/fixtures/composer_routes.json
   # holds the cases both answer (docs/testing.md).
   #

data/lib/samagotchi/config.rb

@@ -119,7 +119,7 @@ module Samagotchi
                 check: ->(value) { "N or N-M (1-#{IdleRecap::RecapPrompt::MAX_SENTENCES})" unless IdleRecap::RecapPrompt.sentences_range(value) }),
 
       # chi broadcast (Broadcast::Recipients, Broadcast::Tags): a session that ended no turn in this many hours (and
-      # no worker or REPL runs) gets no broadcast; a ticket id in the note and in a session's branch or prompts
+      # no worker runs) gets no broadcast; a ticket id in the note and in a session's branch or prompts
       # delivers it there without triage.
       Entry.new(key: "broadcast.active_hours",   yaml_path: %w[broadcast active_hours],   type: :float,   default: 8.0,             expose: %i[env config], lifecycle: :next_broadcast),
       Entry.new(key: "broadcast.ticket_pattern", yaml_path: %w[broadcast ticket_pattern], type: :string,  default: '\b[A-Z][A-Z0-9]+-\d+\b', expose: %i[env config], lifecycle: :next_broadcast),
@@ -140,8 +140,6 @@ module Samagotchi
       Entry.new(key: "session.idle_exit_minutes",     yaml_path: %w[session idle_exit_minutes],     type: :float,   default: 30.0, expose: %i[env config cli], lifecycle: :worker_start),
       # Tools follow the project: a worker applies its folder's `mise env` at start (ProjectEnv); off keeps the spawner's env.
       Entry.new(key: "session.project_env",           yaml_path: %w[session project_env],           type: :enum,    default: "mise", expose: %i[env config], enum_values: %w[mise off], lifecycle: :worker_start),
-      # Plain `chi` runs like `chi --shared` (bin/chi, LaunchMode); false, or --no-shared per run, keeps the plain REPL. No CLI flag: that would duplicate --shared.
-      Entry.new(key: "session.shared",                yaml_path: %w[session shared],                type: :bool,    default: true,  expose: %i[env config], lifecycle: :next_invocation),
       # false: a continue's carry note holds the previous link's recap only (SessionChain.note_text), not its last answer too.
       Entry.new(key: "session.carry_last_answer",     yaml_path: %w[session carry_last_answer],     type: :bool,    default: true,  expose: %i[env config], lifecycle: :next_lifecycle_decision),
       # false: a session nothing happened in is deleted when it is left (SessionManager.discardable?).
@@ -698,7 +696,7 @@ module Samagotchi
         # Live resolve so ENV changes (as in specs) are reflected without explicit reload
         # Use current ENV and file (via ConfigFile's cached reader), plus any CLI
         # overrides captured via reload!
-        path = Samagotchi::ConfigFile.global_path rescue nil
+        path = Samagotchi::ConfigFile.global_path rescue nil # degrade-ok: Config↔Log: Log resolves its file and level through Config
         file_data = Samagotchi::ConfigFile.read_yaml(path: path) if path
         resolve_with_origin(entry.key, file_data: file_data, env: ENV, cli_overrides: cli_overrides, session: session)
       end
@@ -817,7 +815,7 @@ module Samagotchi
       end
 
       # Keys replaced by another, and what the warning adds: it names the new
-      # one (no alias).
+      # one (no alias). A key removed with nothing in its place has nil.
       PARENT_ANSWERS_HINT = "hard, standard or soft; see docs/guardrails.md"
       SYSTEM_ONE_MOVED_HINT = "it has moved: until all of host, model and timeout_ms have, nothing is judged or " \
                               "auto-allowed, and every ask goes to you; see docs/configuration.md"
@@ -826,14 +824,18 @@ module Samagotchi
         "turn.parent_continue" => ["guardrails.parent_answers", PARENT_ANSWERS_HINT],
         "guardrails.system_one.host" => ["system_one.host", SYSTEM_ONE_MOVED_HINT],
         "guardrails.system_one.model" => ["system_one.model", SYSTEM_ONE_MOVED_HINT],
-        "guardrails.system_one.timeout_ms" => ["system_one.timeout_ms", SYSTEM_ONE_MOVED_HINT]
+        "guardrails.system_one.timeout_ms" => ["system_one.timeout_ms", SYSTEM_ONE_MOVED_HINT],
+        "session.shared" => [nil, "chi always runs attached"]
       }.freeze
 
       # nil when +dotted+ is a key the file may hold.
       def key_problem(dotted)
         return nil if known_config_keys.include?(dotted)
         return "config: #{ConfigFile.removed_transport_problem("'#{dotted}'")}" if dotted == "server.transport"
+
         if (replaced = REPLACED_KEYS[dotted])
+          return "config: unknown key '#{dotted}': removed: #{replaced.last}" unless replaced.first
+
           return "config: unknown key '#{dotted}': replaced by '#{replaced.first}' (#{replaced.last})"
         end
 
@@ -1231,7 +1233,7 @@ module Samagotchi
       return [] unless raw.is_a?(Hash)
 
       raw.filter_map { |name, cfg| name.to_s.strip.downcase if cfg.is_a?(Hash) && HostConfig.disabled?(cfg) }
-    rescue StandardError
+    rescue StandardError # degrade-ok: Config↔Log: Log resolves its file and level through Config
       []
     end
 
@@ -1277,7 +1279,7 @@ module Samagotchi
 
       items = raw.is_a?(Array) ? raw : [raw]
       items.flat_map { |v| v.to_s.split(",") }.map(&:strip).reject(&:empty?)
-    rescue StandardError
+    rescue StandardError # degrade-ok: Config↔Log: Log resolves its file and level through Config
       []
     end
 
@@ -1296,7 +1298,7 @@ module Samagotchi
               else []
               end
       items.select { |v| v.is_a?(String) }.map(&:strip).reject(&:empty?).filter_map { |v| expand_appended_entry(v) }
-    rescue StandardError
+    rescue StandardError # degrade-ok: Config↔Log: Log resolves its file and level through Config
       []
     end
 
@@ -1355,7 +1357,7 @@ module Samagotchi
       end
 
       raw.each_with_object({}) { |(name, value), acc| acc[name.to_s] = value.is_a?(Hash) ? value : {} }
-    rescue StandardError
+    rescue StandardError # degrade-ok: Config↔Log: Log resolves its file and level through Config
       {}
     end
 
@@ -1414,7 +1416,7 @@ module Samagotchi
 
         result[key.downcase] = val
       end
-    rescue StandardError
+    rescue StandardError # degrade-ok: Config↔Log: Log resolves its file and level through Config
       {}
     end
 
@@ -1432,7 +1434,7 @@ module Samagotchi
         settings = ModelSettings.parse(key, v)
         result[key] = settings if settings
       end
-    rescue StandardError
+    rescue StandardError # degrade-ok: Config↔Log: Log resolves its file and level through Config
       {}
     end
 

data/lib/samagotchi/context_candidate_choice.rb

@@ -117,7 +117,7 @@ module Samagotchi
     # @param show_card [#call] (**card) → replaces the card
     # @return [Array(Symbol, String)] :ok or :error, and the answer
     def choose(action, name, session:, state_dir:, show_card:)
-      return [:error, "no session yet"] unless session&.id
+      return [:error, Session::NONE_YET] unless session&.id
       return [:error, "a review session takes no context candidates"] if session.review?
       return [:error, USAGE] if name.to_s.empty?
 

data/lib/samagotchi/context_candidates.rb

@@ -176,7 +176,7 @@ module Samagotchi
         .filter_map { |candidate, state| candidate if state == "proposed" }
     end
 
-    # Turn start (Worker#run_prompt before its absorb; the REPL's turn):
+    # Turn start (Worker#run_prompt before its absorb; a one-shot's turn):
     # the proposed candidates +prompt+ (or an earlier owner prompt: a late
     # proposal) mentions are attached, then each gets one first fetch
     # (together within +seconds+), so the note reaches this turn. Only an
@@ -192,7 +192,7 @@ module Samagotchi
       return [] if own.candidates.empty? || !OwnerPrompt.turn?(session: session, author: author)
 
       # The earlier owner prompts too: a proposal that came while one ran
-      # (the REPL's plugins never see a running turn's prompt).
+      # (a one-shot's plugins never see a running turn's prompt).
       texts = owner_texts(session.messages) + (prompt.is_a?(String) ? [prompt] : [])
       found = hits(texts, proposed(session.id, project_root: session.project_root, state_dir: state_dir))
       names = found.filter_map { |hit| attach(hit, own: own, state_dir: state_dir) }
@@ -203,7 +203,8 @@ module Samagotchi
       []
     end
 
-    # The REPL's turn start (it has no ContextAbsorber running): the notes
+    # A --non-interactive one-shot's turn start (it has no ContextAbsorber
+    # running, TerminalUI#attach_mentioned_context): the notes
     # of the sources attached from candidates, as the worker's absorb gives
     # them, added to +engine+'s session and marked delivered.
     # @return [Integer] how many notes were added

data/lib/samagotchi/continue_offer.rb

@@ -134,7 +134,7 @@ module Samagotchi
     # The continue offer was answered yes: resume the conversation without a
     # user message, with the iteration limit the offer's turn had, from the
     # run that turn started (TurnFlow#resume_from: its reasoning stays). A failure
-    # keeps the offer, as the REPL does ("continue prompt preserved"), and
+    # keeps the offer ("continue prompt preserved"), and
     # asks again, one before the turn began too (logged, no :turn_failed).
     # The answer's text is carried into the turn as it begins; a turn that
     # never began leaves it to no other.

data/lib/samagotchi/debug_log.rb

@@ -101,7 +101,7 @@ module Samagotchi
 
     def close_io
       @io&.close
-    rescue StandardError
+    rescue StandardError # degrade-ok: the log writer itself: a failure here must not recurse into Log
       nil
     ensure
       @io = nil

data/lib/samagotchi/degrade.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "log"
+
+module Samagotchi
+  # A logged degradation: a piece of work whose failure has a fallback (a
+  # prompt section left out, an empty list, nil), with a record in the debug
+  # log instead of silence.
+  #
+  #   Degrade.call(:prompt, "model_notes_unreadable", fallback: nil, model: name) { read_notes }
+  #   Degrade.call(:bridge, "state_unreadable", fallback: {}, rescue: [SystemCallError, JSON::ParserError]) { … }
+  #
+  # Runs the block and returns its value. When it raises one of +rescue:+
+  # (StandardError by default; never Exception), returns +fallback+ and logs
+  # Log.warn(area, event, error:, msg:, **fields) the first time this
+  # process sees [area, event], Log.debug after: a hot path that fails on
+  # every call writes one WARN, and the happy path takes no lock. Nothing
+  # goes to stderr (a worker has none; a terminal line would be noise).
+  #
+  # A `return` in the block returns from the enclosing method as usual; a
+  # `next` or `break` would change what the site does, so a site that needs
+  # one logs by hand (Degrade.note) instead.
+  #
+  # Written Degrade.call (Style/LambdaCall turns Degrade.() into it).
+  #
+  # +area+ is a Log tag (LogLine::TAGS), +event+ a slug saying what was
+  # lost; with Log's strict mode on (the specs) both are checked on every
+  # call, the happy path's included.
+  module Degrade
+    MSG_CHARS = 500
+
+    @seen = Set.new
+    @mutex = Mutex.new
+
+    class << self
+      # @param area [Symbol] a Log tag
+      # @param event [String, Symbol] what was lost (agents_md_unreadable)
+      # @param fallback [Object] the value when the block raises
+      # @param fields [Hash] extra record fields; +rescue:+ (a class or an
+      #   array of them, default StandardError) is the one taken out
+      # @return the block's value, or +fallback+
+      def call(area, event, fallback: nil, **fields)
+        classes = Array(fields.delete(:rescue) || StandardError)
+        check!(area, event) if Log.strict
+        begin
+          yield
+        rescue *classes => e
+          note(area, event, e, **fields)
+          fallback
+        end
+      end
+
+      # Log a degradation the caller has already handled (its rescue keeps
+      # a next/break or a fallback of its own): the same once-per-process
+      # WARN, DEBUG after.
+      # @return nil
+      def note(area, event, error, **fields)
+        first = @mutex.synchronize { @seen.add?([area.to_sym, event.to_s]) }
+        record = { error: error.class.name, msg: error.message.to_s[0, MSG_CHARS], **fields }
+        first ? Log.warn(area, event.to_s, **record) : Log.debug(area, event.to_s, **record)
+        nil
+      end
+
+      # Forget what was logged (specs, with Log.reset!).
+      def reset! = @mutex.synchronize { @seen.clear }
+
+      private
+
+      def check!(area, event)
+        raise ArgumentError, "unknown log tag #{area}" unless LogLine::TAGS.include?(area.to_s)
+        raise ArgumentError, "bad log event #{event}" unless event.to_s.match?(LogLine::SLUG)
+      end
+    end
+  end
+end

data/lib/samagotchi/desktop/macos/ChiRunner.swift

@@ -182,8 +182,8 @@ final class ChiRunner {
   /// The live sessions, oldest started first, then up to +recentCount+
   /// stopped ones, newest first. The live order is by creation so ⌘1…⌘9
   /// stay on their sessions as turns update them; a new one comes last.
-  /// A session a chi REPL holds is in neither: it takes no notes or
-  /// messages. A failed second call just leaves "recent" empty. Calls
+  /// A session a one-turn chi --non-interactive run holds is in neither: it
+  /// takes no notes or messages. A failed second call just leaves "recent" empty. Calls
   /// back on +queue+ (a headless seam waits on another one).
   func sessions(recentCount: Int = 3, queue: DispatchQueue = .main,
                 completion: @escaping (Result<[LiveSession], ChiError>) -> Void) {

data/lib/samagotchi/engine/cards.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # Cards and anytime commands: #show_card (routed by EventRoutes), the
+    # anytime and session-command thread marks, the anytime threads #shutdown
+    # waits for. Reads @event_routes, @anytime_threads under @lifecycle_mutex.
+    module CardsPart
+      # ── Cards ───────────────────────────────────────────────────────────────
+
+      # Show a card in every UI (docs/plugins.md, Cards): {type: :card, id:,
+      # source:, title:, body:, level:, actions: [{label:, command:}], in_turn:}.
+      # Where it goes (held while the plugins load, an anytime command's, an
+      # init task's, a turn event, else announced) is EventRoutes#route's,
+      # marked in_turn: (CARD_MARKS). A card with the id of an earlier one
+      # replaces it (btw's "thinking…" → the answer).
+      # @param source [String] who shows it (a bundle's name)
+      # @param actions [Array<Hash>] {label:, command:}; a command is a line
+      #   the session runs, as typed (D3)
+      # @return [String] the card's id
+      # @raise [ArgumentError] a card without a title, or a bad action
+      def show_card(source:, title:, body: "", actions: [], level: :info, id: nil)
+        card = Plugin::Card.build(source: source, title: title, body: body, actions: actions, level: level, id: id)
+        command = Thread.current[running_command_key]
+        card[:command] = command if command
+        @event_routes.route(card, **EventRoutes::CARD_MARKS)
+        card[:id]
+      end
+
+      # Run an anytime command's block (D8): the cards and notices it shows on
+      # this thread are announced at once, marked anytime: true, and are
+      # never a running turn's events. They belong to the command, not the
+      # turn, and a UI shows them after the command's own line (a web
+      # command bubble drawn at its command_queued), even mid-turn.
+      # @return the block's value
+      def running_anytime
+        key = :"samagotchi_anytime_#{object_id}"
+        outer = Thread.current[key]
+        Thread.current[key] = true
+        yield
+      ensure
+        Thread.current[key] = outer
+      end
+
+      # Run a session command's dispatch: a card shown on this thread says
+      # it's that command's (:card's command:), for a reload that no longer has
+      # the command's line above it (Bridge::CardStore). A thread of its own
+      # isn't the command, nor a card shown after it.
+      # @param name [String] the command, "/short"
+      # @return the block's value
+      def running_command(name)
+        outer = Thread.current[running_command_key]
+        Thread.current[running_command_key] = name
+        yield
+      ensure
+        Thread.current[running_command_key] = outer
+      end
+
+      # Whether an anytime command (/btw) still runs on its thread.
+      def anytime_running?
+        @lifecycle_mutex.synchronize { @anytime_threads.any?(&:alive?) }
+      end
+
+      # Start an anytime command on its own thread (D8), one #shutdown waits
+      # for, so its command_ran is announced before the process leaves.
+      # @return [Thread]
+      def spawn_anytime(&)
+        thread = Thread.new(&)
+        @lifecycle_mutex.synchronize do
+          @anytime_threads.select!(&:alive?)
+          @anytime_threads << thread
+        end
+        thread
+      end
+
+      def anytime_thread? = Thread.current[:"samagotchi_anytime_#{object_id}"] == true
+      private :anytime_thread?
+
+      def announce_anytime(event)
+        event = event.merge(anytime: true)
+        announce(event)
+        event
+      end
+      private :announce_anytime
+    end
+  end
+end

data/lib/samagotchi/engine/context_judge.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The attached-context candidate judge (ContextJudge): its pass at an
+    # owner turn's start and for a late candidate, the asks it starts, and
+    # the cards it shows after the turn. Reads @context_cards_after_turn
+    # under @context_cards_mutex, @side_judgments, @host_registry, @session.
+    module ContextJudgePart
+      private
+
+      # 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.
+      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 = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :context),
+                                      ContextJudge::JUDGMENT, session, mode: settings.mode)
+        return unless client
+
+        start_context_asks(client, jobs, log, settings, context_choice(session, log, settings))
+      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
+
+      # 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
+    end
+  end
+end