samagotchi 0.102.0 → 0.104.0

data/lib/samagotchi/cli/parent_wait.rb

@@ -4,6 +4,7 @@ require_relative "../session"
 require_relative "../reply_wait"
 require_relative "../parent_report"
 require_relative "exit"
+require_relative "../session_access"
 
 module Samagotchi
   module CLI
@@ -12,8 +13,8 @@ module Samagotchi
     # for it, and the wait for what comes next, reported the ParentReport
     # way (Ctrl-C included). The including class (a CLI::Command) defines
     # #parse (options, or an exit status) and #run_parsed(options), sets
-    # @stdout, @stderr and @state_dir, and may override the constants
-    # (specs stub them on the class).
+    # @stdout, @stderr and @access (a SessionAccess backend), and may
+    # override the constants (specs stub them on the class).
     module ParentWait
       POLL_INTERVAL = ReplyWait::POLL_INTERVAL
       # No live worker this long while waiting: it died before it could mark
@@ -30,7 +31,14 @@ module Samagotchi
         # With --format json stdout is one JSON object, whatever the end: a
         # failure before the wait is reported from stderr's last line.
         @stderr = ParentReport::LastLine.new(@stderr) if @json
-        status = run_parsed(options)
+        status = begin
+          run_parsed(options)
+        rescue SessionAccess::RemoteFailed => e
+          # A remote that went away mid-run: the command's line, and with
+          # --format json its object.
+          error_line("#{command_name}: #{e.message}")
+          Exit::FAILED
+        end
         if @json && !@reported && status == 1
           detail = @stderr.last.to_s.delete_prefix("#{command_name}: ")
           @stdout.puts(ParentReport.error_line(detail, session_id: @session_id))
@@ -45,9 +53,7 @@ module Samagotchi
       # error line; nil after the error line.
       # @return [String, nil]
       def resolve(given)
-        id = Session.resolve_id(given, state_dir: @state_dir)
-        Session.load(id, state_dir: @state_dir)
-        @session_id = id
+        @session_id = @access.resolve(given)
       rescue ArgumentError => e
         error_line("#{command_name}: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
         nil
@@ -70,16 +76,19 @@ module Samagotchi
       # @return [Integer] the exit status
       def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: self.class::WORKER_GONE_AFTER, turn: nil,
                          queued: false, ended_before: false, report_turn_id: turn)
-        result = ReplyWait.call(id, state_dir: @state_dir, cursor: cursor, timeout: timeout, baseline: baseline,
-                                    owner_grace: owner_grace, poll_interval: self.class::POLL_INTERVAL, turn: turn,
-                                    queued: queued, ended_before: ended_before)
+        result = @access.wait_reply(id, cursor: cursor, timeout: timeout, baseline: baseline, owner_grace: owner_grace,
+                                        poll_interval: self.class::POLL_INTERVAL, turn: turn, queued: queued,
+                                        ended_before: ended_before)
         result.turn_id = report_turn_id if report_turn_id && !report_turn_id.to_s.empty?
         result.text = result.text&.dup&.force_encoding(Encoding::UTF_8)&.scrub
         @reported = true
-        # What a parent may pick there: config.yml tightened by the session's own.
-        strategy = ParentReport.strategy_for(id, state_dir: @state_dir)
+        # What a parent may pick there: config.yml tightened by the session's
+        # own. Machine-local (this machine's config.yml): remotely the
+        # server's (P2's wait route).
+        strategy = @access.parent_strategy(id)
         ParentReport.report(result, session_id: id, stdout: @stdout, stderr: @stderr, command: command_name,
-                                    json: @json, timeout: timeout, extra: report_extra, strategy: strategy)
+                                    json: @json, timeout: timeout, extra: report_extra, strategy: strategy,
+                                    via: @access.invocation)
       rescue Interrupt
         if @json
           @stdout.puts(ParentReport.json_line(ReplyWait::Result.new(status: :canceled, turn_id: report_turn_id), session_id: id,
@@ -87,7 +96,7 @@ module Samagotchi
           @stdout.flush
           @reported = true
         end
-        error_line("#{command_name}: still running: chi --attach #{id}")
+        error_line("#{command_name}: still running: #{@access.invocation.shows(id)}")
         Exit::INTERRUPTED
       rescue ArgumentError
         error_line("#{command_name}: the session is gone (deleted while waiting)")

data/lib/samagotchi/context_command.rb

@@ -11,6 +11,7 @@ require_relative "cli/command"
 require_relative "cli/exit"
 require_relative "cli/flags"
 require_relative "redacted_inspect"
+require_relative "session_access/local"
 
 module Samagotchi
   # `chi context`: attach live external text to sessions (ContextSources).
@@ -76,10 +77,16 @@ module Samagotchi
       def project? = session_id.nil?
     end
 
+    # Why chi context rm NAME ID (and chi web's DELETE …/context/NAME?own=1)
+    # leaves a source the session's project has.
+    def self.project_source_message(name) = "#{name} is the project's: chi context rm #{name} --project, or mute it for this session"
+
     # @param argv [Array<String>] the arguments after "context"
     # @param clock [#call] now, for ls's ages ("4s ago")
+    # @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, env: ENV, cwd: Dir.pwd,
-                   clock: -> { Time.now })
+                   clock: -> { Time.now }, access: nil)
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
@@ -88,6 +95,7 @@ module Samagotchi
       @env = env
       @cwd = cwd
       @clock = clock
+      @access = access || SessionAccess::Local.new(state_dir: @state_dir)
     end
 
     # @return [Integer] exit status: 0 done, 1 refused or failed, 2 usage
@@ -127,11 +135,10 @@ module Samagotchi
         name: name, cmd: options[:cmd], every_seconds: ContextSources.check_every!(options[:every]),
         why: ContextSources.one_line(options[:why], ContextSources::LINE_MAX_CHARS),
         hint: ContextSources.one_line(options[:hint], ContextSources::LINE_MAX_CHARS),
-        scope: nil, added_by: inside_session ? "agent" : "cli", created_at: Time.now.utc.iso8601
+        scope: nil, added_by: added_by, created_at: Time.now.utc.iso8601
       )
       each_target(options, args) do |target|
-        location = location_of(target)
-        location.add(source.with(scope: location.scope))
+        @access.context_add(target, source)
         @stdout.puts("#{target.label}  attached #{name}")
         true
       end
@@ -144,6 +151,7 @@ module Samagotchi
       if options[:cmd] || options[:push] || options[:every]
         return usage_error("a URL's command comes from its provider: give no --cmd, --push or --every")
       end
+      return add_remote_url(url, options, args) if @access.remote?
 
       resolved = ContextProviders.resolve(url)
       return fail_line("no installed bundle resolves #{url} (chi bundle install github-pr for GitHub PRs)") unless resolved
@@ -152,11 +160,10 @@ module Samagotchi
         name: resolved.name, cmd: resolved.cmd, every_seconds: resolved.every_seconds,
         why: ContextSources.one_line(options[:why] || resolved.why, ContextSources::LINE_MAX_CHARS),
         hint: ContextSources.one_line(options[:hint] || resolved.hint, ContextSources::LINE_MAX_CHARS),
-        scope: nil, added_by: inside_session ? "agent" : "cli", created_at: Time.now.utc.iso8601, provider: resolved.bundle
+        scope: nil, added_by: added_by, created_at: Time.now.utc.iso8601, provider: resolved.bundle
       )
       each_target(options, args) do |target|
-        location = location_of(target)
-        location.add(source.with(scope: location.scope))
+        @access.context_add(target, source)
         @stdout.puts("#{target.label}  attached #{source.name}")
         true
       end
@@ -164,6 +171,19 @@ module Samagotchi
       fail_line(e.message)
     end
 
+    # A URL on a remote: its installed bundles' providers resolve it there.
+    def add_remote_url(url, options, args)
+      why = ContextSources.one_line(options[:why], ContextSources::LINE_MAX_CHARS)
+      hint = ContextSources.one_line(options[:hint], ContextSources::LINE_MAX_CHARS)
+      each_target(options, args) do |target|
+        name = @access.context_add_url(target, url, why: why, hint: hint, added_by: added_by)
+        @stdout.puts("#{target.label}  attached #{name}")
+        true
+      end
+    rescue ContextProviders::Invalid => e
+      fail_line(e.message)
+    end
+
     def run_push(options, args)
       name = args.shift
       return usage_error("give the source's NAME") unless name
@@ -173,18 +193,20 @@ module Samagotchi
 
       fetched = ContextSources.parse_output(text)
       each_target(options, args) do |target|
-        attached = find(target, name) or next false
-        # A command source's text is its command's (R2): a push between
-        # two fetches would read as a change and then vanish.
-        unless attached.source.push?
-          error_line("#{command_name}: #{name} runs a command, which writes its text: push goes to a --push source")
+        pushed = @access.context_push(target, name, fetched)
+        case pushed.status
+        when :missing
+          no_source(target, name)
+          next false
+        when :not_push
+          # A command source's text is its command's (R2): a push between
+          # two fetches would read as a change and then vanish.
+          error_line("#{command_name}: #{SessionAccess::ContextPush.not_push_message(name)}")
           next false
         end
 
-        before, written = attached.location.locked(name) do
-          [attached.location.snapshot(name).revision, attached.location.record_text(name, fetched)]
-        end
-        @stdout.puts("#{target.label}  #{name}: #{written.revision == before ? "unchanged" : "new text"} (#{written.revision[0, 12]})")
+        @stdout.puts("#{target.label}  #{name}: #{pushed.revision == pushed.before ? "unchanged" : "new text"} " \
+                     "(#{pushed.revision[0, 12]})")
         true
       end
     end
@@ -194,7 +216,7 @@ module Samagotchi
       return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
 
       targets = targets(options, args) or return CLI::Exit::FAILED
-      rows = targets.flat_map { |target| rows_for(target) }
+      rows = targets.flat_map { |target| @access.context_entries(target).map { |entry| row(target, entry) } }
       if format == "json"
         @stdout.puts(JSON.pretty_generate(rows))
       elsif rows.empty?
@@ -212,10 +234,10 @@ module Samagotchi
       targets = targets(options, args) or return CLI::Exit::FAILED
       return usage_error("show takes one target") if targets.size > 1
 
-      attached = find(targets.first, name) or return CLI::Exit::FAILED
-      snapshot = attached.snapshot
+      entry = @access.context_entry(targets.first, name) or return no_source(targets.first, name)
+      snapshot = entry.snapshot
       if options[:json]
-        @stdout.puts(JSON.pretty_generate({ "source" => attached.source.to_h, "snapshot" => snapshot.to_h }))
+        @stdout.puts(JSON.pretty_generate({ "source" => entry.source.to_h, "snapshot" => snapshot.to_h }))
         return 0
       end
       unless snapshot.text?
@@ -229,7 +251,8 @@ module Samagotchi
 
     # Runs the command in this process, not the worker's: the result shows
     # here, and the worker sees the new snapshot on its next loop. The
-    # source's lock keeps the two from running it at once.
+    # source's lock keeps the two from running it at once. Local only
+    # (SessionAccess::Contract): it runs the command on this machine.
     def run_refresh(options, args)
       name = args.shift
       return usage_error("give the source's NAME") unless name
@@ -271,15 +294,12 @@ module Samagotchi
 
       ContextSources.check_name!(name)
       each_target(options, args) do |target|
-        location = location_of(target)
-        if location.remove(name)
+        case @access.context_remove(target, name)
+        when :removed
           @stdout.puts("#{target.label}  detached #{name}")
           next true
-        end
-
-        project = !target.project? && ContextSources.project_location_for(target.project_root, state_dir: @state_dir)
-        if project&.source(name)
-          error_line("#{command_name}: #{name} is the project's: chi context rm #{name} --project, or mute it for this session")
+        when :project
+          error_line("#{command_name}: #{self.class.project_source_message(name)}")
         else
           error_line("#{command_name}: no source #{name} for #{target.label}")
         end
@@ -287,6 +307,7 @@ module Samagotchi
       end
     end
 
+    # Local only (SessionAccess::Contract): the session's muted/ files here.
     def run_mute(options, args) = mute_or_unmute(options, args, mute: true)
     def run_unmute(options, args) = mute_or_unmute(options, args, mute: false)
 
@@ -327,10 +348,11 @@ module Samagotchi
         return [target]
       end
       if args.empty?
-        own = inside_session
+        own = inside_session unless @access.remote?
         unless own
-          error_line("#{command_name}: give session ids (or unique prefixes), or --project; " \
-                     "inside a chi session it's that session")
+          # Remotely no default: the session chi runs in is this machine's.
+          error_line("#{command_name}: give session ids (or unique prefixes)" \
+                     "#{", or --project; inside a chi session it's that session" unless @access.remote?}")
           return nil
         end
         args = [own]
@@ -340,6 +362,8 @@ module Samagotchi
       resolved.all? ? resolved.uniq : nil
     end
 
+    # A project's sources: local only (SessionAccess::Contract), this
+    # machine's checkout.
     def project_target
       unless MemoryPaths.in_repo?(@cwd)
         error_line("#{command_name}: --project needs a git repository, and #{@cwd} is in none")
@@ -354,8 +378,8 @@ module Samagotchi
     end
 
     def session_target(given)
-      id = Session.resolve_id(given, state_dir: @state_dir)
-      session = Session.load(id, state_dir: @state_dir)
+      id = @access.resolve_id(given)
+      session = @access.show(id)
       Target.new(session_id: id, project_root: session.project_root, cwd: session.working_directory, label: id[0, 8])
     rescue ArgumentError => e
       message = e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"
@@ -363,64 +387,47 @@ module Samagotchi
       nil
     end
 
+    # Who adds a source: an agent (chi's execute runs this in a session)
+    # or the user's cli.
+    def added_by = inside_session ? "agent" : "cli"
+
     # The session chi's execute runs this in (SAMAGOTCHI_PARENT_SESSION;
-    # "chi" is a run with no session).
+    # "chi" is a run with no session). Machine-local (a session on this
+    # machine): remotely it is no default target (#targets), the ids are
+    # given.
     def inside_session
       id = @env.fetch("SAMAGOTCHI_PARENT_SESSION", "").to_s.strip
       id.empty? || id == "chi" ? nil : id
     end
 
-    # The folder a target's own sources live in.
-    def location_of(target)
-      if target.project?
-        ContextSources.project_location_for(target.project_root, state_dir: @state_dir)
-      else
-        ContextSources.session_location(target.session_id, state_dir: @state_dir)
-      end
-    end
+    # The folder a target's own sources live in (refresh, mute: local only).
+    def location_of(target) = @access.context_location(target)
 
-    # A source as the target sees it (a session: its own, then its project's).
+    # A source as the target sees it (a session: its own, then its
+    # project's), for refresh and mute (local only).
     # @return [ContextSources::Attached, nil] nil after an error line
     def find(target, name)
-      ContextSources.check_name!(name)
-      found = if target.project?
-                location = location_of(target)
-                source = location.source(name)
-                source && ContextSources::Attached.new(source: source, location: location, shadowed: false)
-              else
-                attached_to(target).find { |a| a.name == name }
-              end
-      error_line("#{command_name}: no source #{name} for #{target.label}") unless found
+      found = @access.context_attached(target, name)
+      no_source(target, name) unless found
       found
     end
 
-    def attached_to(target, shadowed: false)
-      ContextSources.attached(target.session_id, project_root: target.project_root, state_dir: @state_dir,
-                                                 shadowed: shadowed)
-    end
-
-    def rows_for(target)
-      if target.project?
-        location = location_of(target)
-        return location.sources.map { |source| row(target, source, location.snapshot(source.name)) }
-      end
-
-      own = ContextSources.session_location(target.session_id, state_dir: @state_dir)
-      subs = own.subscriptions
-      attached_to(target, shadowed: true).map do |a|
-        snapshot = a.snapshot
-        read = subs[a.name]&.read
-        row(target, a.source, snapshot, muted: own.muted?(a.name), shadowed: a.shadowed,
-                                        unread: snapshot.text? && read != snapshot.revision)
-      end
+    # @return [Integer] 1, after the line
+    def no_source(target, name)
+      error_line("#{command_name}: no source #{name} for #{target.label}")
+      CLI::Exit::FAILED
     end
 
-    def row(target, source, snapshot, muted: nil, shadowed: nil, unread: nil)
+    # One line of ls (its --format json object).
+    # @param entry [SessionAccess::ContextEntry]
+    def row(target, entry)
+      source = entry.source
+      snapshot = entry.snapshot
       { "target" => target.label, "session_id" => target.session_id, "name" => source.name, "scope" => source.scope,
         "cmd" => source.cmd, "every_seconds" => source.every_seconds, "why" => source.why, "hint" => source.hint,
         "added_by" => source.added_by, "created_at" => source.created_at, "fetched_at" => snapshot.fetched_at,
         "revision" => snapshot.revision, "summary" => snapshot.summary, "error" => snapshot.error,
-        "muted" => muted, "shadowed" => shadowed, "unread" => unread }.compact
+        "muted" => entry.muted, "shadowed" => entry.shadowed, "unread" => entry.unread }.compact
     end
 
     def print_rows(rows, labels:)

data/lib/samagotchi/context_status.rb

@@ -116,13 +116,20 @@ module Samagotchi
     #   last status line's bucket is where rises count from)
     # @param llm_context [LLMContextStrategy::Resolved, nil] the turn's
     #   strategy (its budget)
-    def initialize(conversation: [], llm_context: nil)
+    # @param counted_chars_per_token [Float, nil] the last turn's
+    #   #counted_chars_per_token: the turn's estimate before its first count
+    #   uses it instead of the configured ratio, so the value doesn't dip at
+    #   a turn's start (the chat loop's chars leave out the tool schemas the
+    #   server counts)
+    def initialize(conversation: [], llm_context: nil, counted_chars_per_token: nil)
       @budget = llm_context&.budget_tokens
       @forget = llm_context&.forget? || false
       @offered = self.class.last_line(conversation).to_s.include?(OFFER_TOOL)
       @enabled = self.class.enabled?
       chars_per_token = Config.get("context.chars_per_token").to_f
       @chars_per_token = chars_per_token.positive? ? chars_per_token : DEFAULT_CHARS_PER_TOKEN
+      @estimate_chars_per_token = counted_chars_per_token.to_f.positive? ? counted_chars_per_token.to_f : @chars_per_token
+      @counted_chars_per_token = nil
       parsed = Config.get("context.status_thresholds").to_s.split(",").map { |value| value.strip.to_i }
                      .select { |value| value.between?(1, 99) }.uniq.sort
       @thresholds = parsed.empty? ? DEFAULT_THRESHOLDS : parsed
@@ -137,6 +144,10 @@ module Samagotchi
     # @return [Hash, nil] the status line's value ({est_pct:, bucket:});
     #   nil with context.status off or before the first request
     attr_reader :display
+    # @return [Float, nil] the chars per token of the last request the
+    #   server counted (its prompt chars over its prompt tokens, images
+    #   aside), for the next turn's tracker; nil before a count
+    attr_reader :counted_chars_per_token
 
     def enabled? = @enabled
 
@@ -212,6 +223,8 @@ module Samagotchi
 
       @counted = { chars: prompt_chars, image_tokens: image_tokens }
       @edited = false
+      text_tokens = usage[:prompt_tokens].to_i - image_tokens.to_i
+      @counted_chars_per_token = prompt_chars.to_f / text_tokens if prompt_chars.positive? && text_tokens.positive?
       value = display_for(used_tokens: usage[:total_tokens], window_tokens: usage[:context_window_tokens] || window&.tokens)
       @display = value if value
     end
@@ -243,7 +256,7 @@ module Samagotchi
         source = "server"
       else
         window_tokens = counted_against(window.tokens)
-        used_tokens = (prompt_chars / @chars_per_token).ceil + image_tokens
+        used_tokens = (prompt_chars / @estimate_chars_per_token).ceil + image_tokens
         source = "estimate"
       end
 

data/lib/samagotchi/engine.rb

@@ -347,6 +347,8 @@ module Samagotchi
       # A plugin tool's row refs resolve against the session's folder, as
       # answer refs do (AnswerRefs), not the process's.
       @kernel.session_cwd = -> { @session&.working_directory }
+      # forget_outputs refuses what the user pinned in the working set.
+      @kernel.working_set_pins = -> { @session&.working_set_pins || [] }
       # A cut tool output is saved whole in the session's folder.
       @kernel.session_dir = -> { @session&.id && Session.session_dir(@session.id, state_dir: session_state_dir) }
       @kernel.guardrail_gate = @guardrail_wiring.gate
@@ -1856,6 +1858,11 @@ module Samagotchi
       @recap&.write_now(on_start: on_start)
     end
 
+    # The longest #write_recap_now waits (recap.timeout), nil when no recap
+    # is set up.
+    # @return [Float, nil]
+    def recap_timeout = @recap&.timeout
+
     # Ask for a recap now (/recap), without waiting for the idle window.
     # @return [Symbol] IdleRecap#request_now's answer, or :off
     def request_recap
@@ -1885,9 +1892,12 @@ module Samagotchi
       self
     end
 
-    # Stop the shared idle scheduler (TerminalUI calls this when the REPL exits).
-    def stop_idle
-      @idle_scheduler&.stop
+    # Stop the shared idle scheduler (TerminalUI calls this when the REPL
+    # exits). +join+: wait for a tick under way (IdleScheduler#stop); a
+    # caller holding #synchronize_events passes false, since a recap's emit
+    # in that tick waits for the same lock.
+    def stop_idle(join: true)
+      @idle_scheduler&.stop(join: join)
       self
     end
 
@@ -1945,9 +1955,11 @@ module Samagotchi
     #   run it resumes started (ModelResult#run_start, kept in the offer by
     #   TurnFlow), so it keeps that run's reasoning; nil starts cold (a
     #   model change while the offer stood, every other turn).
-    # @param origin [Hash, nil] who queued the turn ({client_id:, enqueued_id:});
-    #   when given, the turn's boundary events (:turn_started, :turn_completed,
-    #   :turn_canceled, :turn_failed) carry it as `origin:`
+    # @param origin [Hash, nil] who queued the turn ({client_id:, enqueued_id:},
+    #   and author: when someone other than the session's owner wrote it, from
+    #   its input file; absent for the owner); when given, the turn's boundary
+    #   events (:turn_started, :turn_completed, :turn_canceled, :turn_failed)
+    #   carry it as `origin:`, and GuardrailWiring#begin_turn gets it
     # @param images [Array<Hash>] the prompt's images: {path:} (a file on this
     #   machine; in-process and attached-TUI callers only) or {file:, name:}
     #   (already in the session's images/, e.g. a web upload). They are
@@ -2943,7 +2955,8 @@ module Samagotchi
     end
 
     # The working set (WorkingSet) as the model has it, as a
-    # :working_set_updated event ({items:, at:}): at each request (the
+    # :working_set_updated event ({items:, at:}, adds: while the user's
+    # adds are pending): at each request (the
     # stream handler's :generation_started, from the running turn's
     # conversation) and at turn end (#end_turn, from the session's kept
     # messages). Only when it differs from the last one emitted for this
@@ -2958,18 +2971,19 @@ module Samagotchi
     def emit_working_set(on_event, session, conversation)
       return unless session && conversation
 
-      snapshot = WorkingSet.build(conversation, cwd: session.working_directory, strategy: working_set_strategy)
+      snapshot = WorkingSet.build(conversation, cwd: session.working_directory, strategy: working_set_strategy,
+                                  pins: session.working_set_pins)
 
-      items = snapshot.items.map(&:to_h)
+      shown = snapshot.to_h.except(:at)
       last = @working_set_emitted
-      if items.empty?
-        return unless last && last[0] == session.id && !last[1].empty?
-      elsif last == [session.id, items]
+      if snapshot.empty?
+        return unless last && last[0] == session.id && last[1] != { items: [] }
+      elsif last == [session.id, shown]
         return
       end
 
-      @working_set_emitted = [session.id, items]
-      event = { type: :working_set_updated, items: items, at: snapshot.at }
+      @working_set_emitted = [session.id, shown]
+      event = { type: :working_set_updated, **shown, at: snapshot.at }
       on_event ? emit_event(on_event, event) : announce_or_hold(event)
     rescue StandardError => e
       Log.warn(:turn, "working_set_failed", error: e.class.name, msg: e.message.to_s[0, 200])

data/lib/samagotchi/guardrail_wiring.rb

@@ -83,12 +83,18 @@ module Samagotchi
       @protected = nil
     end
 
-    # A turn starts: its origin, and the git facts read afresh.
+    # A turn starts: its origin (Engine#run_turn's: {client_id:,
+    # enqueued_id:, author:}, each optional), and the git facts read afresh.
     def begin_turn(origin)
       @origin = origin
       @git = Guardrails::GitInfo.new
     end
 
+    # Who wrote the running turn when it isn't the session's owner (its
+    # origin's author); nil for the owner's turns and every other origin.
+    # @return [String, nil]
+    def turn_author = @origin.is_a?(Hash) ? @origin[:author] : nil
+
     # The gate every tool call asks first.
     # @return [Guardrails::Gate]
     def gate

data/lib/samagotchi/idle_recap.rb

@@ -254,7 +254,7 @@ module Samagotchi
     end
 
     # @return [Array(Integer, Integer)] the recap length range, e.g. [2, 4]
-    attr_reader :generation, :inactivity, :min_user_turns, :sentences
+    attr_reader :generation, :inactivity, :min_user_turns, :sentences, :timeout
 
     # @param callable [#call] true while a continue offer waits for an
     #   answer (the Worker's or the REPL's TurnFlow); read at each attempt
@@ -550,10 +550,16 @@ module Samagotchi
       @client
     end
 
+    # The summarize thread: its recap, or nil when it failed. A failure of
+    # any kind (a LoadError, a stack overflow too) ends it quietly, logged:
+    # no recap this time, and no dead thread's trace on the worker's
+    # stderr. A real exit or interrupt goes on as raised.
     def spawn_summarize(client, prompt)
       Thread.new do
         client.summarize(prompt, session_id: @session_id.call, on_usage: @on_usage)
-      rescue StandardError => e
+      rescue SystemExit, SignalException
+        raise
+      rescue Exception => e # rubocop:disable Lint/RescueException -- a recap's failure, whatever it is, is no recap
         # No recap this time (the next idle window tries again); say why.
         Log.exception(:recap, "summarize_failed", e)
         nil

data/lib/samagotchi/idle_scheduler.rb

@@ -18,23 +18,37 @@ module Samagotchi
   # raises is logged and isolated — the remaining jobs keep polling.
   class IdleScheduler
     POLL_INTERVAL_SECONDS = 0.5
+    # How long #stop waits for the thread to finish its tick before it
+    # kills it.
+    STOP_JOIN_SECONDS = 1.0
+    THREAD_NAME = "idle_scheduler"
 
-    attr_reader :engine, :jobs
+    attr_reader :engine, :jobs, :interval
 
-    def initialize(engine:, jobs: [])
+    # +interval+: the pause between ticks (a spec passes a long one, so its
+    # own #tick is the only one after the first).
+    def initialize(engine:, jobs: [], interval: POLL_INTERVAL_SECONDS)
       raise ArgumentError, "IdleScheduler requires an engine" unless engine
 
       @engine = engine
       @jobs = jobs.compact.freeze
+      @interval = interval
+      # The loop's pause: a pop with the interval as its timeout, which
+      # #stop ends at once by pushing.
+      @wake = Queue.new
       @thread = nil
+      # The thread a stop(join: false) left to finish its tick.
+      @unjoined = nil
       @stopped = false
     end
 
     # Spawn the polling thread (idempotent; no-op when there are no jobs).
+    # A stopped scheduler doesn't start again.
     def start
       return self if running? || @jobs.empty?
 
       @thread = Thread.new { run_loop }
+      @thread.name = THREAD_NAME
       self
     end
 
@@ -42,11 +56,24 @@ module Samagotchi
       !@thread.nil? && @thread.alive? && !@stopped
     end
 
-    # Stop the polling thread (idempotent).
-    def stop
+    # Stop the polling thread (idempotent): it ticks no more and its pause
+    # ends at once. +join+: wait up to STOP_JOIN_SECONDS for a tick under
+    # way to finish, then kill the thread. A caller holding a lock a tick
+    # may take (Worker#leave_idle holds the event log, which a recap's emit
+    # takes) passes join: false: the thread finishes its tick and exits by
+    # itself, and a later joining stop (Engine#shutdown, the worker's
+    # teardown) still joins it. From the scheduler's own thread (a job's
+    # tick) it never joins.
+    def stop(join: true)
       @stopped = true
-      @thread&.kill
+      @wake << :stop
+      thread = @thread || @unjoined
       @thread = nil
+      @unjoined = join ? nil : thread
+      return if thread.nil? || !join || thread == Thread.current
+
+      thread.kill unless thread.join(STOP_JOIN_SECONDS)
+      nil
     end
 
     # Swap the job +old+ for +new+ (Engine#session= rebuilding the recap):
@@ -78,11 +105,9 @@ module Samagotchi
     private
 
     def run_loop
-      loop do
-        break if @stopped
-
+      until @stopped
         tick
-        sleep(POLL_INTERVAL_SECONDS)
+        @wake.pop(timeout: @interval)
       end
     rescue StandardError => e
       Log.exception(:idle, "scheduler_crashed", e, echo: "[IdleScheduler] scheduler thread crashed: #{e.class}: #{e.message}")