samagotchi 0.61.0 → 0.63.0

data/lib/samagotchi/kernel_loop.rb

@@ -18,6 +18,7 @@ require_relative "thinking"
 require_relative "hooks"
 require_relative "pending_input_queue"
 require_relative "steer"
+require_relative "reasoning_history"
 require_relative "thought_stream_splitter"
 require_relative "tools/builtins"
 require_relative "muted_memories"
@@ -172,6 +173,10 @@ module Samagotchi
     #   too); the thinking level is its own field, since the native path
     #   sends the sampling as is.
     attr_accessor :turn_settings
+    # The session's working directory (a callable → String or nil), which
+    # a plugin tool's row refs resolve their files against (ToolRunner,
+    # RowRefs); the Engine sets it. nil: the process's own (Dir.pwd).
+    attr_accessor :session_cwd
     # Tools::Peers (or the Engine's live view of it): the session
     # list_sessions and send_note speak for; nil outside a session.
     attr_accessor :peers
@@ -291,7 +296,7 @@ module Samagotchi
     private_constant :Turn, :Request, :Generation
 
     def start_turn(messages, on_stream_event:, cancel_controller:, pending_input:, cap:, reasoning_since: nil)
-      conversation = prepare_conversation(messages, keep_thought_from: thought_floor(messages, reasoning_since))
+      conversation = prepare_conversation(messages, keep_thought_from: ReasoningHistory.run_start(messages, reasoning_since))
       context = ContextStatus.new(conversation: conversation, llm_context: @turn_settings.llm_context)
       emit = ->(event) { emit_stream_event(on_stream_event, event) }
       @llm_context_turn = LLMContextForget::Turn.new(conversation: conversation, context: context, emit: emit)
@@ -1017,24 +1022,10 @@ module Samagotchi
     end
 
     # Standard multi-turn compliance: never pass prior raw thought blocks,
-    # but a resumed run's (+keep_thought_from+, #thought_floor): the same
+    # but a resumed run's (+keep_thought_from+, ReasoningHistory.run_start): the same
     # run going on after a step-limit Continue.
     def prepare_conversation(messages, keep_thought_from: nil) = sanitize_history(messages, keep_thought_from: keep_thought_from)
 
-    # Where a resumed run's thought blocks start: its start (+since+). Inside
-    # one native run nothing re-sanitizes, so a user entry the run merged (a
-    # steer, a delegate report, the Qwen recovery prompt) left the thoughts
-    # before it in the prompt: they stay. Only a user or turn_start entry
-    # added after the run ended (after its last model message: a !cmd's
-    # output) starts them again past itself. nil without +since+.
-    def thought_floor(messages, since)
-      return nil if since.nil?
-
-      last_reply = messages.rindex { |m| m[:role].to_s == "model" } || -1
-      query = messages.rindex { |m| m[:role].to_s == "user" || m[:turn_start] == true }
-      query && query > last_reply ? [query + 1, since].max : since
-    end
-
     def duplicate_conversation(messages)
       messages.map(&:dup)
     end

data/lib/samagotchi/llm/chat_loop.rb

@@ -24,6 +24,7 @@ require_relative "../vision_context"
 require_relative "../log"
 require_relative "../empty_answer_retry"
 require_relative "../steer"
+require_relative "../reasoning_history"
 require_relative "../turn_note"
 require_relative "../thinking"
 
@@ -70,7 +71,7 @@ module Samagotchi
       def provider = :chat
 
       # +reasoning_since+ (ModelBackend#complete): the resumed run's start,
-      # the Run's own start then (#reasoning_boundary).
+      # the Run's own start then (Run#initialize, #reasoning_boundary).
       def complete(messages:, max_iterations: IterationLimit::DEFAULT, on_stream_event: nil, cancel_controller: nil,
                    model_name: nil, max_tool_output_chars: nil, pending_input: nil, reasoning_since: nil)
         raise ArgumentError, "ChatLoop has no adapter" unless @adapter
@@ -137,7 +138,8 @@ module Samagotchi
       # A model turn carries its saved reasoning as reasoning_content when
       # +reasoning+ (a ReasoningHistory level; the turn's by default) says
       # so: under turn the running turn's only (#reasoning_boundary, with
-      # +since+ the Run's start), under all every one.
+      # +since+ where the Run's reasoning starts; a steer it merged doesn't
+      # move that), under all every one.
       #
       # The conversation goes through the kernel's LLMContextView first,
       # as the native prompt does (it keeps every entry in place).
@@ -194,19 +196,24 @@ module Samagotchi
       TOOL_IMAGES_TEXT = "[images from tool results]"
 
       # The first index whose model entries carry their reasoning (nil:
-      # none do) under +level+. Under turn: past both the last query (a
-      # user message: a prompt, a steer, merged input, the chat template's
-      # last query; or an entry that starts a turn, turn_start) and +since+
-      # (the Run's start, so a continue turn -- a reminder, a context wake,
-      # a delegate report's wake -- sends none of the run before it; a
-      # step-limit Continue's Run starts where the run it resumes did).
+      # none do) under +level+. Under turn: +since+ when given, where a
+      # Run's reasoning starts (ReasoningHistory.run_start, the native
+      # loop's rule: an entry the run merged -- a person's line, a plugin's
+      # steer, a Continue's text -- keeps the reasoning before it, so the
+      # request after it extends the one before; a continue turn -- a
+      # reminder, a context wake, a delegate report's wake -- starts a Run
+      # of its own and sends none of the run before it). Without +since+,
+      # past the last query (a user message or an entry that starts a turn,
+      # turn_start).
       # @return [Integer, nil]
       def reasoning_boundary(conversation, since: nil, level: reasoning_history)
         case level
         when :all then 0
         when :turn
+          return since if since
+
           query = conversation.rindex { |entry| entry[:role].to_s == "user" || entry[:turn_start] == true }
-          [query ? query + 1 : 0, since.to_i].max
+          query ? query + 1 : 0
         end
       end
 
@@ -417,9 +424,10 @@ module Samagotchi
           @cancel_controller = cancel_controller
           @model_name = model_name
           @pending_input = pending_input
-          # Where this run's entries start: the reasoning it sends back
-          # (ChatLoop#reasoning_boundary) is its own, a resumed run's too.
-          @start = start || conversation.length
+          # Where the reasoning this run sends back starts
+          # (ChatLoop#reasoning_boundary): its own replies', a resumed run's
+          # too, fixed for the run; a steer it merges doesn't move it.
+          @reasoning_start = ReasoningHistory.run_start(conversation, start || conversation.length)
           @tool_activity = []
           @empty_retry = EmptyAnswerRetry.new
           # The empty generations, never saved: the UIs draw the turn's
@@ -596,7 +604,7 @@ module Samagotchi
 
         def request(iteration, retry_generation, streamed, thought, generation_controller, streamed_any = nil)
           @loop.adapter.chat(
-            messages: @loop.wire_messages(@conversation, since: @start, reasoning: reasoning_level), tools: @loop.tool_definitions, model: @model_name,
+            messages: @loop.wire_messages(@conversation, since: @reasoning_start, reasoning: reasoning_level), tools: @loop.tool_definitions, model: @model_name,
             cancel_controller: generation_controller || @cancel_controller, session_id: @loop.session_id,
             options: @loop.request_options(retry_generation: retry_generation, model: @model_name),
             on_delta: lambda { |content:, reasoning:, payload:|
@@ -670,7 +678,7 @@ module Samagotchi
 
         # Whether this step's request sends reasoning back.
         def reasoning_sent?
-          !@without_reasoning && @loop.reasoning_chars(@conversation, since: @start, reasoning: reasoning_level).positive?
+          !@without_reasoning && @loop.reasoning_chars(@conversation, since: @reasoning_start, reasoning: reasoning_level).positive?
         end
 
         # The level this step's request sends reasoning back under: none
@@ -733,7 +741,7 @@ module Samagotchi
         # names and arguments, and the reasoning sent back.
         def prompt_chars
           LLMContextView.chars(@loop.llm_context_view.messages(@conversation)) +
-            @loop.reasoning_chars(@conversation, since: @start, reasoning: reasoning_level)
+            @loop.reasoning_chars(@conversation, since: @reasoning_start, reasoning: reasoning_level)
         end
 
         # The server's counts for this request (prompt + answer): the status

data/lib/samagotchi/plugin/api.rb

@@ -79,9 +79,11 @@ module Samagotchi
       # @param targets [#call, nil] args → what guardrail rules match: a Hash
       #   with paths: (absolute or relative to the cwd), command: (a shell
       #   command) and cwd:, each optional
-      def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &)
-        spec = Api.tool_spec(name, description, params: params, schema: schema, label: label, preview: preview,
-                                                targets: targets, &)
+      # @param refs [#call, nil] args → the call's row's refs, display only:
+      #   a list of {kind:, target:, label:, actions:} (RowRefs, Ref). Run
+      #   once per call on the tool path, so it must be cheap (no I/O)
+      def tool(name, description, **, &)
+        spec = Api.tool_spec(name, description, **, &)
         if (taken = @registries.tools[spec[:name]])
           raise ArgumentError, "tool #{spec[:name]} is already registered (#{taken.source})"
         end
@@ -125,9 +127,8 @@ module Samagotchi
         end
 
         # As Api#tool.
-        def tool(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &)
-          spec = Api.tool_spec(name, description, params: params, schema: schema, label: label, preview: preview,
-                                                  targets: targets, &)
+        def tool(name, description, **, &)
+          spec = Api.tool_spec(name, description, **, &)
           raise ArgumentError, "tool #{spec[:name]} is registered twice" if @specs.any? { |s| s[:name] == spec[:name] }
 
           @specs << spec
@@ -249,34 +250,44 @@ module Samagotchi
       def counts = { commands: @commands.size, tools: @tools.size, hooks: @hooks.size, services: @services.size,
                      inits: @inits.size }
 
-      # A checked tool declaration (#tool's arguments).
-      # @return [Hash] {name:, schema:, label:, preview:, targets:, block:}
-      def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, &block)
+      # A checked tool declaration (#tool's arguments: Api#tool and
+      # ToolSet#tool pass theirs on, so a new keyword is added here).
+      # @return [Hash] {name:, schema:, label:, preview:, targets:, refs:, block:}
+      def self.tool_spec(name, description, params: {}, schema: nil, label: nil, preview: nil, targets: nil, refs: nil,
+                         &block)
         raise ArgumentError, "tool #{name.inspect} needs a block" unless block
 
         name = name.to_s
         raise ArgumentError, "tool name #{name.inspect} must be a-z, 0-9 and _ (at most 48)" unless name.match?(TOOL_NAME)
         raise ArgumentError, "tool #{name}: preview must respond to #call" if preview && !preview.respond_to?(:call)
         raise ArgumentError, "tool #{name}: targets must respond to #call" if targets && !targets.respond_to?(:call)
+        raise ArgumentError, "tool #{name}: refs must respond to #call" if refs && !refs.respond_to?(:call)
 
         parameters = schema ? schema_parameters(name, schema) : params_schema(name, params)
         { name: name, schema: { name: name, description: description.to_s, parameters: parameters },
-          label: label&.to_s, preview: preview, targets: targets, block: block }
+          label: label&.to_s, preview: preview, targets: targets, refs: refs, block: block }
       end
 
       # Make +bundle+'s tools in +registry+ the +specs+: its tools not in
       # them go; a new one, or one whose schema or label changed, is
       # registered (a changed one again, in its place: Tools::Registry
       # orders bundle tools by bundle and name); an unchanged one is kept
-      # as it is. A name another source has is left out. Called on
-      # the turn thread (Engine#apply_staged_tools!).
+      # as it is, but for its block, preview:, targets: and refs:, swapped
+      # in place: none of them reaches the prompt, so not a change (that
+      # would build the prompts again). A name
+      # another source has is left out. Called on the turn thread
+      # (Engine#apply_staged_tools!).
       # @return [Hash] {changed: Boolean, skipped: [String] (why)}
       def self.apply_tools(registry, bundle, specs, context)
         wanted = specs.to_h { |spec| [spec[:name], spec] }
         changed = false
         registry.entries.each do |entry|
           next unless entry.source == bundle
-          next if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
+
+          if (spec = wanted[entry.name]) && spec[:schema] == entry.schema && spec[:label] == entry.label
+            entry_fields(spec, context).slice(:handler, :preview, :targets, :refs).each { |key, value| entry[key] = value }
+            next
+          end
 
           registry.unregister(entry.name)
           changed = true
@@ -295,23 +306,30 @@ module Samagotchi
       end
 
       # Registry#register's keywords for a tool declaration: its block
-      # wrapped as a handler (typed args, the Context), preview, targets.
+      # wrapped as a handler (typed args, the Context), preview, targets, refs.
       def self.entry_fields(spec, context)
         block = spec[:block]
-        preview = spec[:preview]
-        targets = spec[:targets]
         parameters = spec[:schema][:parameters]
+        preview = per_call(spec[:preview], parameters)
         {
           schema: spec[:schema], label: spec[:label],
           handler: lambda { |call, _kctx|
             result = block.call(Api.args_of(call, parameters), context)
             Api.result_text(result)
           },
-          preview: preview && ->(call) { preview.call(Api.args_of(call, parameters))&.to_s },
-          targets: targets && ->(call) { targets.call(Api.args_of(call, parameters)) }
+          preview: preview && ->(call) { preview.call(call)&.to_s },
+          targets: per_call(spec[:targets], parameters),
+          refs: per_call(spec[:refs], parameters)
         }
       end
 
+      # A plugin's args → value lambda (+fn+) as call → value: it gets the
+      # call's typed args (Api.args_of), as the tool's block does. nil
+      # without one.
+      def self.per_call(fn, parameters)
+        fn && ->(call) { fn.call(Api.args_of(call, parameters)) }
+      end
+
       # A tool's result as the model reads it: a String (a ToolResult too,
       # with its images) as it is, a Hash or Array as JSON (its #to_s is
       # Hash#inspect, which changes with the Ruby version), else #to_s.

data/lib/samagotchi/plugin/attached_context.rb

@@ -94,18 +94,21 @@ module Samagotchi
         nil
       end
 
-      # This session's sources (its own, then its project's).
-      # @return [Array<Hash>] {name:, scope:, why:, hint:, fetched_at:, error:, provider:}
+      # This session's sources (its own, then its project's); none before
+      # the session has an id or a saved file.
+      # +summary+ is the last text's summary (nil before any text).
+      # @return [Array<Hash>] {name:, scope:, why:, hint:, fetched_at:, error:, provider:, summary:}
       def list
         id = @host.session_id.call
-        return [] unless id
+        # No id, or no saved file yet (a command before the first turn).
+        return [] unless id && Session.exist?(id, state_dir: state_dir)
 
         session = Session.load(id, state_dir: state_dir)
         ContextSources.attached(id, project_root: session.project_root, state_dir: state_dir).map do |attached|
           snapshot = attached.snapshot
           { name: attached.name, scope: attached.location.scope, why: attached.source.why,
             hint: snapshot.hint || attached.source.hint, fetched_at: snapshot.fetched_at, error: snapshot.error,
-            provider: attached.source.provider }
+            provider: attached.source.provider, summary: snapshot.summary }
         end
       end
 

data/lib/samagotchi/reasoning_history.rb

@@ -7,9 +7,9 @@ module Samagotchi
   # Which of its own reasoning a chat host's model gets back
   # (LLM::ChatLoop sends it as reasoning_content on its earlier replies):
   #
-  #   turn  the running turn's replies only (the tool-call rounds since the
-  #         last user message); what Qwen's, Gemma 4's and DeepSeek's
-  #         templates and the hosted APIs expect
+  #   turn  the running turn's replies only (since the turn's start; a
+  #         steer, a plugin's nudge or a Continue's text merged into the
+  #         turn doesn't reset it, as on a native host: .run_start)
   #   drop  none
   #   all   every reply that has reasoning, earlier turns too (a direct
   #         DeepSeek API with tools wants this)
@@ -17,7 +17,8 @@ module Samagotchi
   # Order (#resolve): the session's own level (/reasoning-history), then
   # SAMAGOTCHI_REASONING_HISTORY, models.<key>.reasoning_history,
   # hosts.<name>.reasoning_history, then turn. Native hosts ignore it:
-  # KernelLoop keeps the running turn's reasoning on its own.
+  # KernelLoop keeps the running turn's reasoning on its own, from the
+  # run's start (.run_start).
   module ReasoningHistory
     LEVELS = %i[drop turn all].freeze
     DEFAULT = :turn
@@ -118,6 +119,23 @@ module Samagotchi
       end
     end
 
+    # Where a run's own reasoning starts in +messages+: its start (+since+;
+    # nil without one). Inside one run nothing re-sanitizes, so an entry the
+    # run merged (a steer, a delegate report, the Qwen recovery prompt) left
+    # the reasoning before it in the prompt: it stays. Only a user or
+    # turn_start entry added after the run ended (after its last model
+    # message: a !cmd's output) starts it again past itself.
+    # @param messages [Array<Hash>] the conversation
+    # @param since [Integer, nil] the run's start
+    # @return [Integer, nil]
+    def run_start(messages, since)
+      return nil if since.nil?
+
+      last_reply = messages.rindex { |m| m[:role].to_s == "model" } || -1
+      query = messages.rindex { |m| m[:role].to_s == "user" || m[:turn_start] == true }
+      query && query > last_reply ? [query + 1, since].max : since
+    end
+
     # "drop (models: qwen)", "turn (default)".
     def label(level, source) = "#{level} (#{source || "default"})"
 

data/lib/samagotchi/recap_setup.rb

@@ -31,12 +31,12 @@ module Samagotchi
     # @return [IdleRecap, nil]
     def self.build(recap, engine:, host_registry:, session_target:, session_id:, state_dir:)
       return nil if recap == false
-      # The TUI passes the config file's section; a worker passes nothing, so
-      # read it here too (a scalar `recap: false` is only seen this way).
+      # The REPL and a worker pass nothing: the config is read here alone
+      # (a scalar `recap: false` is only seen this way).
       return nil if recap.nil? && ConfigFile.recap_config == false
       return nil if Samagotchi::Config.get("recap.enabled") == false
 
-      # Normalize kwarg (TerminalUI passes recap: recap_config hash or nil)
+      # An explicit kwarg (a spec, an embedder) over the registry.
       kwarg_config = recap.is_a?(Hash) ? recap : {}
 
       base_url = string_config(kwarg_config, :base_url) || registry_string("recap.base_url")

data/lib/samagotchi/row_refs.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "log"
+require_relative "ref"
+
+module Samagotchi
+  # The refs a plugin tool gives its row (chi.tool's refs: lambda, traceable
+  # refs P5d): what the call traces to (a ticket, a PR, a file), each a Ref
+  # whose +to_h+ the row carries as +refs+ on tool_call_started and
+  # tool_call_completed (ToolRowFields::EVENT_KEYS), saved with the result
+  # as tool_refs (ToolResponse::SAVED_KEYS) for a reload, which has no
+  # plugins (Web::MessageParts). Display only: the model never sees them.
+  #
+  # A file ref is any file under the session's folder (plan D7): a relative
+  # path is resolved against it, a path outside it is dropped. The folder
+  # counts under its own spelling and its real path (macOS /tmp is
+  # /private/tmp), and a kept path is stored under the real one, so a
+  # reload under either spelling keeps it. The page
+  # shows the first ref on the row's title and the rest in its menu.
+  module RowRefs
+    # Per row, so a plugin can't bloat the events or session.json.
+    MAX_REFS = 20
+    # The row's refs' JSON; a ref that would cross it is left out.
+    MAX_BYTES = 64 * 1024
+
+    module_function
+
+    # Runs +fn+ (the tool's refs: lambda, as Api.per_call wraps it: call →
+    # a list of {kind:, target:, label:, actions:}) on +call+. Never
+    # raises: a lambda that raises or returns something other than a list
+    # gives none, and a bad ref is dropped; both are logged (warn, not
+    # echoed: the turn's live region is on screen).
+    # @param cwd [String, nil] the session's folder
+    # @return [Array<Hash>] Ref#to_h each, deduped, at most MAX_REFS
+    def for(fn, call, cwd:)
+      return [] unless fn
+
+      tool = call[:name].to_s
+      raw = fn.call(call)
+      return [] if raw.nil?
+      raise ArgumentError, "refs: returned #{raw.class}, not a list" unless raw.is_a?(Array)
+
+      build(raw, cwd) { |why| Log.warn(:plugins, "tool_refs_rejected", tool: tool, reason: why) }
+    rescue StandardError => e
+      Log.warn(:plugins, "tool_refs_failed", tool: tool, error: "#{e.class}: #{e.message}")
+      []
+    end
+
+    # Stored refs (+raw+, a saved tool_refs entry), each rebuilt and
+    # checked again as #for checks a lambda's: a stored file is never
+    # trusted. What isn't valid any more is dropped, a relative path too
+    # (it was stored absolute). Never raises: a reload must show the
+    # conversation.
+    # @return [Array<Hash>]
+    def for_display(raw, cwd:)
+      return [] unless raw.is_a?(Array)
+
+      build(raw, cwd, relative: false) { |_why| nil }
+    rescue StandardError
+      []
+    end
+
+    # +raw+'s valid refs as Ref#to_h; +rejected+ gets why each other one
+    # was dropped. +relative+: a relative file path is resolved against
+    # +cwd+ (else dropped).
+    def build(raw, cwd, relative: true, &)
+      roots = roots(cwd)
+      bytes = 2 # the list's []
+      raw.each_with_object([]) do |value, refs|
+        break refs if refs.length >= MAX_REFS
+
+        hash = inside(Ref.from(value), roots, relative).to_h
+        next if refs.include?(hash)
+
+        size = JSON.generate(hash).bytesize + (refs.empty? ? 0 : 1)
+        break refs if bytes + size > MAX_BYTES
+
+        bytes += size
+        refs << hash
+      # One junk ref ({1 => "x"}, a nil target) goes alone.
+      rescue ArgumentError, TypeError, NoMethodError => e
+        yield(e.message)
+      end
+    end
+    private_class_method :build
+
+    # +cwd+ as [its spelling, its real path] (one when they are the same,
+    # none without a +cwd+). absolute_path, not expand_path: a leading ~ is
+    # a name, never a home. One realpath per row: the lambda's refs are
+    # checked together. The answer's refs (AnswerRef) check against it too.
+    def roots(cwd)
+      return [] if cwd.to_s.empty?
+
+      given = File.absolute_path(cwd.to_s)
+      real = begin
+        File.realpath(given)
+      rescue SystemCallError
+        given
+      end
+      [given, real].uniq
+    end
+
+    # +ref+ with a file's path absolute, resolved against the folder
+    # (+roots+, #roots), under its real spelling: plan D7, for a plugin
+    # row's refs and an answer's (AnswerRef) alike.
+    # @raise [ArgumentError] a relative path with no folder (or not
+    #   +relative+), or a path outside the folder
+    def inside(ref, roots, relative)
+      return ref unless ref.kind == Ref::FILE
+
+      path = ref.target[:path]
+      unless File.absolute_path?(path) || (relative && roots.any?)
+        raise ArgumentError, "a file ref's relative path needs the session folder"
+      end
+      return ref if roots.empty?
+
+      path = File.absolute_path(path, roots.first)
+      root = roots.find { |dir| path == dir || path.start_with?(dir.end_with?("/") ? dir : "#{dir}/") }
+      raise ArgumentError, "a file ref outside the session folder (#{path})" unless root
+
+      ref.with(target: ref.target.merge(path: "#{roots.last}#{path.delete_prefix(root)}").freeze)
+    end
+  end
+end

data/lib/samagotchi/session.rb

@@ -275,6 +275,18 @@ module Samagotchi
       { id: pending[:id], kind: %w[approval hook continue].include?(kind) ? kind : "question", relayed_to: relayed_to }.compact
     end
 
+    # A question saved by a process that no longer runs this session (the
+    # one that loads it now owns it): nobody waits on its answer, so it is
+    # dropped. Unsaved; the caller saves.
+    # @return [String, nil] the dropped question's id, nil with none
+    def drop_dead_question
+      pending = pending_question
+      return nil unless pending
+
+      @pending_question = nil
+      pending[:id].to_s
+    end
+
     # The stored project root, else (a file from before the field) the
     # project of the working directory now: nil when that is in no repo or
     # gone. +cache+ is ProjectScope.root_for's, shared across one listing.

data/lib/samagotchi/session_metrics.rb

@@ -416,10 +416,20 @@ module Samagotchi
     # analytics.json in the session directory. Atomic write; failures are
     # swallowed (analytics must never break the running session).
     # @param state_dir [String, nil]
+    # @param running_turn [Boolean] also save the running turn's record so
+    #   far (a worker's turn checkpoint): as the turn a worker killed now
+    #   would leave, canceled with reason worker_stopped (TurnNote's), up to
+    #   its completed_at. The next collector loads it with the others; the
+    #   turn's own end writes over it. Only the file has it.
     # @return [Boolean] true on success
-    def persist(state_dir: nil)
+    def persist(state_dir: nil, running_turn: false)
       sid, data, turn_count = @mutex.synchronize do
-        [@session_id, build_snapshot(:all).merge(active_turn: nil, active_tools: []), @turn_records.size]
+        data = build_snapshot(:all).merge(active_turn: nil, active_tools: [])
+        if running_turn && @turn
+          data[:turn_records] << running_turn_record
+          data[:cancellations] += 1
+        end
+        [@session_id, data, @turn_records.size]
       end
       return false if sid.nil? || sid.to_s.empty?
 
@@ -611,6 +621,18 @@ module Samagotchi
       end
     end
 
+    # The running turn's record so far, as end_turn would make it for a
+    # turn a worker died in (#persist's running_turn). Its open generation
+    # (none at an iteration boundary) and running tool calls are left out.
+    # Caller holds the mutex.
+    def running_turn_record
+      {
+        id: @turn.id, status: "canceled", started_at: @turn.started_at, completed_at: now.iso8601(3),
+        duration_ms: elapsed_ms(@turn.started_monotonic), cancellation_reason: "worker_stopped",
+        continue: @turn.continue, resumed: @turn.resumed
+      }.merge(turn_token_fields(@turn))
+    end
+
     # What turn_failed's line is made of (format.js failedTurnText): a
     # provider error's summary, else the message (capped: a server's error
     # page can be long) and class, and the steps that stayed (kept_steps).

data/lib/samagotchi/terminal_ui/attach_launcher.rb

@@ -46,12 +46,15 @@ module Samagotchi
       # @param thinking [String, nil] --thinking as typed: a new session
       #   starts with it as its own level; a resumed or attached one's
       #   worker gets a /thinking, after those
+      # @param state_dir [String, nil] where the sessions are (the default
+      #   state dir by default): the worker's, for the attached loop too
       # @return [Symbol] :detached, :closed when the worker went away,
       #   :failed when the --model switch didn't go through, or (input from a
       #   pipe) :turn_failed / :empty_answer / :unanswered (AttachedLoop#run)
       def run(attach: nil, shared: false, resume: nil, prompt: nil, model: nil, no_interrupt: false, default_input: true,
-              memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [])
-        client = connect(attach: attach, shared: shared, resume: resume, model: model,
+              memories: [], muted_memories: [], llm_context: {}, thinking: nil, appended_prompt_files: [], state_dir: nil)
+        state_dir ||= Session.default_state_dir
+        client = connect(attach: attach, shared: shared, resume: resume, model: model, state_dir: state_dir,
                          memories: memories, muted_memories: muted_memories, llm_context: llm_context, thinking: thinking,
                          appended_prompt_files: appended_prompt_files)
         commands = []
@@ -65,7 +68,7 @@ module Samagotchi
                                     first_command: first_command, no_interrupt: no_interrupt,
                                     default_input: default_input && !prompt && !attach && !resume,
                                     wait_at_eof: !$stdin.tty?,
-                                    parent_answers: Guardrails::ParentApprovals.parent_process?)
+                                    parent_answers: Guardrails::ParentApprovals.parent_process?, state_dir: state_dir)
         ended = begin
           attached.run
         ensure