samagotchi 0.2.0

data/lib/samagotchi/session_metrics.rb

@@ -0,0 +1,466 @@
+# frozen_string_literal: true
+
+require "json"
+require "monitor"
+require "time"
+require "fileutils"
+require "securerandom"
+require_relative "session"
+
+module Samagotchi
+  # SessionMetrics is a persistent, error-isolated collector of per-session
+  # analytics. It implements the same #call(event) sink contract as
+  # SessionObserver subscribers, so Engine#run_turn feeds it (it forwards every
+  # event to its SessionObserver): the REPL, the -p/--non-interactive/--resume
+  # paths and SessionManager background workers.
+  #
+  # Collected dimensions:
+  #   - tokens (input/output/total), with a provenance flag (:server|:estimate)
+  #   - turn count, tool calls (total / per-tool / error count)
+  #   - iterations (tool-call rounds) per turn, aggregated
+  #   - generation latency (monotonic clock across generation_* events)
+  #   - cancellations and network retries
+  #   - session wall-clock (first activity -> last activity)
+  #
+  # A snapshot is surfaced via Engine#session_state_snapshot and (optionally)
+  # persisted to a sibling analytics.json next to the session file. The event
+  # trail itself goes to the debug log (LogSubscriber).
+  class SessionMetrics
+    # Per-turn transient state, reset on each turn_started.
+    TurnState = Struct.new(
+      :session_id,
+      :iteration_count,
+      :gen_started_at,
+      :gen_latency_accum,
+      :tool_calls,
+      :tool_errors,
+      # Per-generation completion-token tracking. A turn may contain several
+      # generations (one per tool-call iteration); each generation's predicted_n
+      # is cumulative within that generation and resets afterwards, so totals
+      # must be summed per-generation (not taken as a global max).
+      :gen_completion_max,
+      :gen_had_server,
+      # Buffered chars/4 estimate for the current generation; committed to the
+      # turn total only if the generation ends with no server token data.
+      :gen_estimate_sum,
+      :id,
+      :started_at,
+      :started_monotonic,
+      :tool_calls_by_id,
+      keyword_init: true
+    )
+
+    def initialize(clock: nil, wall_clock: nil)
+      @mutex = Monitor.new
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @wall_clock = wall_clock || -> { Time.now }
+      @session_id = nil
+      @turns = 0
+      @tokens_in = 0
+      @tokens_out = 0
+      @tokens_total = 0
+      @token_source = nil # :server | :estimate
+      @tool_calls_total = 0
+      @tool_calls_by_tool = Hash.new(0)
+      @tool_errors = 0
+      @iterations_total = 0
+      @gen_latency_ms = 0
+      @cancellations = 0
+      @retries = 0
+      @started_at = nil
+      @last_activity_at = nil
+      @turn = nil
+      @turn_records = []
+      @tool_records = []
+    end
+
+    # /model: the window and prompt profile a turn reported were the old
+    # model's; /stats resolves the new one's until its first turn reports.
+    def forget_model_reports!
+      @mutex.synchronize do
+        @context_window_tokens = @context_window_source = nil
+        @profile = @profile_source = nil
+      end
+    end
+
+    # Set the session id the collector is aggregating for. Safe to call multiple
+    # times; the first non-empty id wins so later turns don't clobber it.
+    # @param id [String, nil]
+    # @return [void]
+    def session_id=(id)
+      return if id.nil? || id.to_s.empty?
+
+      @mutex.synchronize { @session_id ||= id.to_s }
+    end
+
+    # Event sink. Safe to call from any thread; errors are isolated by the
+    # caller (SessionObserver / TerminalUI) but we still guard internally.
+    # @param event [Hash]
+    # @return [void]
+    def call(event)
+      return unless event.is_a?(Hash)
+
+      type = event[:type]
+      case type
+      when :turn_started
+        begin_turn(event)
+      when :generation_chunk
+        accumulate_tokens(event)
+      when :tool_dispatch_started
+        @mutex.synchronize { @turn&.iteration_count += 1 }
+      when :tool_call_started
+        record_tool_call_start(event)
+      when :tool_call_completed
+        record_tool_call_completed(event)
+      when :generation_started
+        @mutex.synchronize do
+          if event[:context_window_tokens]
+            @context_window_tokens = event[:context_window_tokens]
+            @context_window_source = event[:context_window_source]
+          end
+          if event[:profile]
+            @profile = event[:profile]
+            @profile_source = event[:profile_source]
+          end
+          if @turn
+            @turn.gen_started_at = monotonic_time
+            @turn.gen_completion_max = 0
+            @turn.gen_had_server = false
+            @turn.gen_estimate_sum = 0
+          end
+        end
+      when :generation_completed, :generation_cancelled
+        record_served_model(event)
+        record_generation_completed
+      when :generation_retrying
+        @mutex.synchronize { @retries += 1 }
+      when :turn_completed
+        end_turn(status: "completed")
+      when :turn_canceled
+        @mutex.synchronize { @cancellations += 1 }
+        end_turn(status: "canceled", reason: event[:cancellation_reason])
+      when :turn_failed
+        end_turn(status: "failed")
+      end
+
+      @mutex.synchronize { @last_activity_at = now.iso8601(3) }
+    rescue StandardError
+      nil
+    end
+
+    # @return [Hash] the current summary snapshot
+    def snapshot
+      @mutex.synchronize do
+        {
+          session_id: @session_id,
+          turns: @turns,
+          tokens_in: @tokens_in,
+          tokens_out: @tokens_out,
+          tokens_total: @tokens_total,
+          token_source: @token_source,
+          context_window_tokens: @context_window_tokens,
+          context_window_source: @context_window_source,
+          profile: @profile,
+          profile_source: @profile_source,
+          served_model: @served_model,
+          served_model_for: @served_model_for,
+          # The running turn's calls, iterations and finished generations
+          # count at once (the per-tool counts do too), so /stats agrees
+          # mid-turn; end_turn moves them into the totals.
+          tool_calls_total: @tool_calls_total + (@turn&.tool_calls || 0),
+          tool_calls_by_tool: @tool_calls_by_tool.dup,
+          tool_errors: @tool_errors + (@turn&.tool_errors || 0),
+          iterations_total: @iterations_total + (@turn&.iteration_count || 0),
+          gen_latency_ms: @gen_latency_ms + (@turn&.gen_latency_accum || 0),
+          cancellations: @cancellations,
+          retries: @retries,
+          started_at: @started_at,
+          last_activity_at: @last_activity_at,
+          session_duration_ms: elapsed_ms(@session_started_monotonic),
+          turn_records: @turn_records.map(&:dup),
+          tool_records: @tool_records.map(&:dup),
+          active_turn: active_turn_snapshot,
+          active_tools: active_tool_snapshots
+        }
+      end
+    end
+
+    # Persist the summary snapshot to a sibling analytics.json in the session
+    # directory. Atomic write; failures are swallowed (analytics must never
+    # break the running session).
+    # @param state_dir [String, nil]
+    # @return [Boolean] true on success
+    def persist(state_dir: nil)
+      sid = @mutex.synchronize { @session_id }
+      return false if sid.nil? || sid.to_s.empty?
+
+      # Omitting state_dir lets Session.session_dir fall back to the default
+      # (XDG) location; passing an explicit nil would override it and break
+      # File.join.
+      dir = state_dir ? Session.session_dir(sid, state_dir: state_dir) : Session.session_dir(sid)
+      FileUtils.mkdir_p(dir)
+      path = File.join(dir, "analytics.json")
+      temp_path = "#{path}.tmp"
+      File.write(temp_path, JSON.pretty_generate(merged_persisted_snapshot(path)) + "\n")
+      File.rename(temp_path, path)
+      true
+    rescue StandardError
+      false
+    end
+
+    private
+
+    def begin_turn(event)
+      @mutex.synchronize do
+        @session_id ||= event[:session_id].to_s if event[:session_id]
+        @started_at ||= now.iso8601(3)
+        @session_started_monotonic ||= monotonic_time
+        @turns += 1
+        @turn = TurnState.new(
+          session_id: @session_id,
+          iteration_count: 0,
+          gen_started_at: nil,
+          gen_latency_accum: 0,
+          tool_calls: 0,
+          tool_errors: 0,
+          gen_completion_max: 0,
+          gen_had_server: false,
+          gen_estimate_sum: 0,
+          id: SecureRandom.uuid,
+          started_at: now.iso8601(3),
+          started_monotonic: monotonic_time,
+          tool_calls_by_id: {}
+        )
+      end
+    end
+
+    # A canceled turn's record keeps why (+reason+: "user", "ctrl_c", ...), so
+    # a reloaded web history can show the cancel line the live one did.
+    def end_turn(status: "completed", reason: nil)
+      @mutex.synchronize do
+        if @turn
+          finished_at = now
+          record = {
+            id: @turn.id,
+            status: status,
+            started_at: @turn.started_at,
+            completed_at: finished_at.iso8601(3),
+            duration_ms: elapsed_ms(@turn.started_monotonic)
+          }
+          record[:cancellation_reason] = reason.to_s unless reason.nil? || reason.to_s.empty?
+          @turn_records << record
+        end
+        @iterations_total += @turn.iteration_count if @turn
+        @gen_latency_ms += @turn.gen_latency_accum if @turn
+        @tool_calls_total += @turn.tool_calls if @turn
+        @tool_errors += @turn.tool_errors if @turn
+        @turn = nil
+      end
+    end
+
+    # The model the server says answered, and the name asked for then (a
+    # /model switch makes it stale until the next generation reports).
+    def record_served_model(event)
+      return unless event[:served_model]
+
+      @mutex.synchronize do
+        @served_model = event[:served_model]
+        @served_model_for = event[:requested_model]
+      end
+    end
+
+    def record_generation_completed
+      # Finalize this generation's completion tokens. Server timings are
+      # cumulative per generation; we sum the per-generation max into the turn
+      # total. If the generation reported no server tokens we commit the buffered
+      # chars/4 estimate instead. The two paths are mutually exclusive per
+      # generation, so a final chunk carrying timings while earlier chunks did
+      # not will not double count.
+      @mutex.synchronize do
+        return unless @turn
+
+        if @turn.gen_had_server
+          @tokens_out += @turn.gen_completion_max
+        else
+          @tokens_out += @turn.gen_estimate_sum
+        end
+        @tokens_total = @tokens_in + @tokens_out
+        started = @turn.gen_started_at
+        if started
+          elapsed_ms = (monotonic_time - started) * 1000.0
+          @turn.gen_latency_accum += elapsed_ms if elapsed_ms > 0
+          @turn.gen_started_at = nil
+        end
+      end
+    end
+
+    def record_tool_call_start(event)
+      @mutex.synchronize do
+        return unless @turn
+
+        @turn.tool_calls += 1
+        tool = event[:tool].to_s
+        @tool_calls_by_tool[tool] += 1 unless tool.empty?
+        iteration = event[:iteration].to_i
+        call_index = event[:call_index].to_i
+        key = tool_key(iteration, call_index)
+        @turn.tool_calls_by_id[key] = {
+          id: "#{@turn.id}:#{key}",
+          turn_id: @turn.id,
+          iteration: iteration,
+          call_index: call_index,
+          tool: tool,
+          started_at: now.iso8601(3),
+          started_monotonic: monotonic_time
+        }
+      end
+    end
+
+    def record_tool_call_completed(event)
+      @mutex.synchronize do
+        return unless @turn
+
+        status = event.dig(:activity, :status).to_s
+        status = event[:status].to_s if status.empty?
+        @turn.tool_errors += 1 if status == "error"
+        key = tool_key(event[:iteration].to_i, event[:call_index].to_i)
+        active = @turn.tool_calls_by_id.delete(key)
+        return unless active
+
+        finished_at = now
+        @tool_records << active.slice(
+          :id, :turn_id, :iteration, :call_index, :tool, :started_at
+        ).merge(
+          status: status.empty? ? "ok" : status,
+          completed_at: finished_at.iso8601(3),
+          duration_ms: elapsed_ms(active[:started_monotonic])
+        )
+      end
+    end
+
+    # Accumulate token counts from a streamed generation_chunk payload.
+    # Server-first: prefer real timings/usage. Input tokens keep a running MAX
+    # (the prompt grows across tool-call iterations); completion tokens are
+    # tracked as a per-generation MAX and summed at generation_completed so
+    # multi-generation turns count every generation. When a generation reports
+    # no server tokens at all we fall back to the chars/4 estimate summed across
+    # its chunks (mutually exclusive with server counting to avoid double
+    # counting a final chunk that carries timings while earlier chunks do not).
+    def accumulate_tokens(event)
+      payload = event[:payload]
+      payload = {} unless payload.is_a?(Hash)
+
+      usage = TokenUsage.from_payload(payload)
+      if usage
+        @mutex.synchronize do
+          @token_source = :server
+          @tokens_in = [@tokens_in, usage[:prompt_tokens].to_i].max
+          if @turn
+            @turn.gen_completion_max = [@turn.gen_completion_max, usage[:completion_tokens].to_i].max
+            @turn.gen_had_server = true
+          end
+          @tokens_total = @tokens_in + @tokens_out
+        end
+      else
+        @mutex.synchronize do
+          chars = event_content_chars(payload, event)
+          return unless chars && chars.positive?
+          return if @turn && @turn.gen_had_server
+
+          @token_source ||= :estimate
+          @turn.gen_estimate_sum += TokenUsage.estimate(payload_content(payload, event)) if @turn
+          @tokens_total = @tokens_in + @tokens_out
+        end
+      end
+    end
+
+    def event_content_chars(payload, event)
+      len = payload_content(payload, event).length
+      len.positive? ? len : nil
+    end
+
+    def payload_content(payload, event = nil)
+      content = payload["content"] || payload[:content]
+      return content if content.is_a?(String)
+
+      event_content = event && event[:content]
+      event_content.is_a?(String) ? event_content : ""
+    end
+
+    def monotonic_time
+      @clock.call
+    end
+
+    def now
+      @wall_clock.call
+    end
+
+    def elapsed_ms(started)
+      return 0 unless started
+
+      [((monotonic_time - started) * 1000.0).round, 0].max
+    end
+
+    def tool_key(iteration, call_index)
+      "#{iteration}:#{call_index}"
+    end
+
+    def active_turn_snapshot
+      return nil unless @turn
+
+      {
+        id: @turn.id,
+        started_at: @turn.started_at,
+        duration_ms: elapsed_ms(@turn.started_monotonic)
+      }
+    end
+
+    def active_tool_snapshots
+      return [] unless @turn
+
+      @turn.tool_calls_by_id.values.map do |tool|
+        tool.slice(:id, :turn_id, :iteration, :call_index, :tool, :started_at).merge(
+          duration_ms: elapsed_ms(tool[:started_monotonic])
+        )
+      end
+    end
+
+    def merged_persisted_snapshot(path)
+      current = snapshot.merge(active_turn: nil, active_tools: [])
+      return current unless File.file?(path)
+
+      prior = JSON.parse(File.read(path))
+      return current unless prior.is_a?(Hash)
+
+      current.merge(
+        started_at: earliest_timestamp(prior["started_at"], current[:started_at]),
+        last_activity_at: latest_timestamp(prior["last_activity_at"], current[:last_activity_at]),
+        turn_records: merge_records(prior["turn_records"], current[:turn_records]),
+        tool_records: merge_records(prior["tool_records"], current[:tool_records])
+      )
+    rescue JSON::ParserError
+      current
+    end
+
+    def merge_records(prior, current)
+      (Array(prior) + Array(current)).each_with_object({}) do |record, by_id|
+        next unless record.is_a?(Hash)
+
+        id = record["id"] || record[:id]
+        by_id[id] = record if id
+      end.values
+    end
+
+    def earliest_timestamp(*timestamps)
+      timestamps.compact.min_by { |value| Time.iso8601(value.to_s) }
+    rescue ArgumentError
+      timestamps.compact.first
+    end
+
+    def latest_timestamp(*timestamps)
+      timestamps.compact.max_by { |value| Time.iso8601(value.to_s) }
+    rescue ArgumentError
+      timestamps.compact.last
+    end
+  end
+end

data/lib/samagotchi/session_observer.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Samagotchi
+  # SessionObserver is a small persistent subscriber registry.
+  #
+  # Unlike the turn-scoped `Engine#run_turn` `on_event:` sink (passed once per
+  # turn and gone when the turn ends), a subscriber registered here keeps
+  # receiving events across every `run_turn` call on the same Engine instance.
+  #
+  # Each delivery carries a locally-monotonic `event_seq` so a subscriber can
+  # track ordering and how far behind it is. Subscribers are error-isolated:
+  # a subscriber that raises does not stop other subscribers from receiving the
+  # same event, and does not break the running turn.
+  #
+  # Documented event vocabulary (subscribers match on `:type`):
+  #   * turn_started / turn_completed / turn_canceled / turn_failed — turn
+  #     boundaries (turn_completed also carries a JSON-safe `turn_summary:`)
+  #   * generation_* / tool_call_* / tool_dispatch_* — raw kernel-loop events
+  #   * session_activity — an activity tick was recorded (see Engine#record_activity)
+  #   * recap_ready — an idle session-recap finished generating
+  #     (`recap:` prose, `generation:` id). Purely additive: it never mutates
+  #     session.messages; each UI renders it (or not) however it likes.
+  class SessionObserver
+    # Handle returned by #subscribe. Holds the observer reference and carries
+    # #unsubscribe so a caller can deregister without keeping the registry.
+    class SubscribedObserver
+      # @return [#call] the wrapped observer
+      attr_reader :observer
+
+      def initialize(observer, registry)
+        @observer = observer
+        @registry = registry
+      end
+
+      # @return [Boolean, nil] true when this handle has unsubscribed, otherwise nil
+      def unsubscribed?
+        @unsubscribed
+      end
+
+      # Deregister this subscriber. Idempotent and safe to call multiple times.
+      # @return [Boolean] true if it was removed, false if already gone
+      def unsubscribe
+        return false if @unsubscribed
+
+        @unsubscribed = true
+        @registry&.unsubscribe(handle: self)
+      end
+    end
+
+    def initialize
+      @mutex = Monitor.new
+      @observers = [] # Array<SubscribedObserver>
+      @seq = 0
+    end
+
+    # Register a persistent subscriber (any object responding to #call(event)).
+    # @param observer [#call] the sink
+    # @return [SubscribedObserver] handle usable with #unsubscribe
+    def subscribe(observer:)
+      handle = SubscribedObserver.new(observer, self)
+      @mutex.synchronize { @observers << handle }
+      handle
+    end
+
+    # Remove a previously-registered subscriber.
+    # @param handle [SubscribedObserver, nil]
+    # @return [Boolean] true if it was removed, false otherwise (nil/unknown/
+    #   already-unsubscribed never raises)
+    def unsubscribe(handle:)
+      return false unless handle.is_a?(SubscribedObserver)
+      @mutex.synchronize { !!@observers.delete(handle) }
+    end
+
+    # Assign a monotonic event_seq and fan out to every current subscriber.
+    # @param event [Hash] the raw emitted event (delivered to observers as a
+    #   copy with `event_seq:` merged in; never mutated in place)
+    # @return [void]
+    def notify(event)
+      # Number AND deliver under one lock. Events arrive from several threads
+      # (turn, idle scheduler, bridge HTTP); delivering outside the lock let
+      # seq N reach a subscriber after N+1 (the SSE writer then dropped it as
+      # below its high-water mark) and let a numbered event fall between a
+      # new connection's replay snapshot and its live queue. Subscribers must
+      # stay non-blocking (enqueue-only), so holding the lock is cheap. The
+      # Monitor is reentrant, so a subscriber that emits on the same thread
+      # does not deadlock.
+      @mutex.synchronize do
+        payload = event.merge(event_seq: @seq += 1)
+
+        @observers.dup.each do |handle|
+          next if handle.unsubscribed?
+
+          begin
+            handle.observer.call(payload)
+          rescue StandardError
+            # Error-isolate: a throwing subscriber must not stop others or break
+            # the running turn.
+          end
+        end
+      end
+    end
+
+    # @return [Integer] total events emitted so far (Engine-local sequence)
+    def event_count
+      @mutex.synchronize { @seq }
+    end
+
+    # Run the block while no event is being numbered or delivered, so it sees
+    # (and can change) state consistently with the event log. Reentrant: the
+    # block may notify. Keep it short; every emitter waits for it.
+    def synchronize(&block)
+      @mutex.synchronize(&block)
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../config"
+require_relative "../model_profile"
+require_relative "../session_manager"
+require_relative "../bridge_client"
+require_relative "live_region"
+require_relative "plain_surface"
+require_relative "attached_loop"
+
+module Samagotchi
+  class TerminalUI
+    # `chi --attach ID` and `chi --shared [--resume ID]`: find or start the
+    # session's worker, then run the TUI as a client of its Bridge
+    # (AttachedLoop). It takes no OwnerLock and builds no Engine: the worker
+    # owns the session, and any number of UIs can attach to it.
+    module AttachLauncher
+      # Why attaching failed, worded for the terminal.
+      class Error < StandardError; end
+
+      BRIDGE_WAIT = 10.0
+
+      module_function
+
+      # Attach until the user detaches or the worker goes away.
+      # @param prompt [String, nil] sent as the first prompt once attached (`-p`)
+      # @param model [String, nil] --model: a new session starts on it; a
+      #   resumed or attached one's worker gets a /model before the prompt
+      # @param no_interrupt [Boolean] --no-interrupt: every turn this TUI
+      #   posts runs with the raised iteration limit
+      # @param default_input [Boolean] a new session with no -p gets
+      #   SAMAGOTCHI_DEFAULT_INPUT in its first read (--no-default-input: no)
+      # @param memories [Array<String>] --memory: a new session's worker
+      #   preloads them (an existing session keeps its own list)
+      # @param muted_memories [Array<String>] --mute: hidden from a new session
+      # @return [Symbol] :detached, :closed when the worker went away, or
+      #   :failed when the --model switch didn't go through
+      def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
+              memories: [], muted_memories: [])
+        client = connect(attach: attach, shared: shared, resume: resume, model: model,
+                         memories: memories, muted_memories: muted_memories)
+        first_command = model && (attach || resume) ? "/model #{model}" : nil
+        surface = open_surface
+        begin
+          AttachedLoop.new(client: client, screen: surface, client_id: "tui:#{Process.pid}", first_prompt: prompt,
+                           first_command: first_command, no_interrupt: no_interrupt,
+                           default_input: default_input && !prompt && !attach && !resume).run
+        ensure
+          close_surface(surface)
+        end
+      end
+
+      # A live region (Screen, with Reline drawing into it) on a terminal
+      # that can show one, else plain append-only output.
+      # @return [Screen, PlainSurface]
+      def open_surface(out: $stdout, input: $stdin, env: ENV)
+        LiveRegion.open(out: out, input: input, env: env) || PlainSurface.new(out: out)
+      end
+
+      def close_surface(surface)
+        LiveRegion.close(surface)
+      end
+
+      # @return [BridgeClient] a client for the live Bridge of the session
+      # @raise [Error]
+      def connect(attach: nil, shared: false, resume: nil, model: nil, state_dir: nil, wait: BRIDGE_WAIT,
+                  memories: [], muted_memories: [], err: $stderr)
+        sd = state_dir || Session.default_state_dir
+        warn_memory_flags_ignored(attach || resume, memories, muted_memories, err) if attach || resume
+        if attach
+          live = connect_existing(attach, sd)
+          return live if live
+
+          # Its worker exited when nobody used it (or never ran): wake one.
+          resume = attach
+        end
+
+        session = if resume
+                    SessionManager.resume_session(resume, state_dir: sd)
+                  else
+                    SessionManager.spawn_session(prompt: nil, model_name: model && model_ref(model), state_dir: sd,
+                                                 memories: memories, muted_memories: muted_memories)
+                  end
+        client = BridgeClient.wait_for(session.id, session_dir: Session.session_dir(session.id, state_dir: sd), timeout: wait)
+        client || raise(Error, "the worker for session #{session.id} did not start its Bridge in time")
+      rescue SessionManager::OwnedByTUI
+        raise Error, "session #{resume} is open in a chi REPL; close it there first"
+      rescue ArgumentError => e
+        raise Error, e.message
+      end
+
+      # --model as the REPL reads it: an alias resolved, a host prefix kept.
+      def model_ref(model)
+        ModelProfile.required_model_name(ConfigFile.resolve_model_alias(model))
+      end
+
+      # An existing session's prompt is built from its own session fields:
+      # --memory/--mute given with --attach or --resume are ignored, with a
+      # line saying so (printed before the live region opens).
+      def warn_memory_flags_ignored(session_id, memories, muted_memories, err)
+        flags = []
+        flags << "--memory" unless Array(memories).empty?
+        flags << "--mute" unless Array(muted_memories).empty?
+        return if flags.empty?
+
+        verb = flags.size == 1 ? "applies" : "apply"
+        err.puts "(#{flags.join(' and ')} #{verb} to a new session; #{session_id}'s prompt is already built)"
+      end
+
+      # @return [BridgeClient, nil] the running worker's, or nil when none runs
+      def connect_existing(session_id, state_dir)
+        Session.load(session_id, state_dir: state_dir)
+        BridgeClient.discover(session_id, session_dir: Session.session_dir(session_id, state_dir: state_dir))
+      end
+    end
+  end
+end