samagotchi 0.156.0 → 0.158.0

data/lib/samagotchi/session_access/contract.rb

@@ -26,7 +26,7 @@ module Samagotchi
       # bin/chi subcommands that act on this machine: never sessions. chi
       # remote (this machine's list of remotes) runs here under a remote too
       # (Dispatch); the others are refused there.
-      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit judgments remote home].freeze
+      MACHINE = %w[bootstrap update models desktop memory bundle guardrails toolkit judgments remote home project].freeze
 
       # "command", "command sub" or either with a flag (its long name) →
       # SUPPORTED or LOCAL_ONLY. A LOCAL_ONLY command or subcommand lists

data/lib/samagotchi/session_access/local.rb

@@ -81,12 +81,11 @@ module Samagotchi
       # @return [OwnerLock::Owner, nil] the worker or one-turn chi run that owns it
       def owner(id) = SessionManager.session_owner(id, **dir)
 
-      # SessionManager.list_sessions: Session objects, for chi sessions list.
-      def list(**filters) = SessionManager.list_sessions(**filters, **dir)
-
-      # SessionManager.session_summaries: the summary hashes (chi sessions
-      # list --live/--format, chi note --all).
-      def summaries(**filters) = SessionManager.session_summaries(**filters, **dir)
+      # SessionManager.session_rows: the SessionRows chi sessions list
+      # prints and chi note --all reaches (chi web's summaries route answers
+      # their #to_summary_h).
+      # @return [Array<SessionRow>]
+      def summaries(**filters) = SessionManager.session_rows(**filters, **dir)
 
       # The session's worker for an attach: the live one as is, else
       # resumed and waited for up to +wait+ seconds (chi --attach on this

data/lib/samagotchi/session_access/remote.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../session"
+require_relative "../session_row"
 require_relative "../session_access"
 require_relative "../remotes"
 require_relative "../reply_wait"
@@ -158,8 +159,9 @@ module Samagotchi
       # @return [OwnerLock::Owner, nil]
       def owner(id) = show(id).owner
 
-      # The rows chi sessions list prints, as SessionManager.session_summaries
-      # gives them (symbol keys).
+      # The rows chi sessions list prints: chi web's summaries
+      # (SessionRow#to_summary_h) read back as SessionRows.
+      # @return [Array<SessionRow>]
       def summaries(live: false, cwd: nil, limit: nil, include_tests: true, project_root: nil, include_archived: false,
                     sort: nil, order: nil)
         query = { live: (1 if live), cwd: cwd, limit: limit, tests: (0 unless include_tests), dir: project_root,
@@ -167,7 +169,7 @@ module Samagotchi
         reply = request(:get, "/api/sessions/summaries", query: query)
         raise_refusal(reply) unless reply.status == 200
 
-        Array(reply.json).map { |row| symbolize(row) }
+        Array(reply.json).map { |row| SessionRow.from_summary_h(symbolize(row)) }
       end
 
       # --- create and send

data/lib/samagotchi/session_field.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # One key of a session file (a Session::FIELDS row): +key+ the file's
+  # key, +attr+ Session's attribute and keyword (nil for a key only the
+  # file has: the settings pair, written from Session's +from+), +default+
+  # the value of a file without the key (REQUIRED for one it must have),
+  # +fresh+ a new Session's when it isn't given (it differs only for
+  # metadata_version and messages), +optional+ a key written only when set,
+  # +cast+ what a value is read as (Session.new, .from_h and the writers),
+  # +write+ what the file gets from the attribute (the value as is without
+  # one). +unread+ and +keep+ are the Unread rule's (.level): what of a
+  # value the field couldn't read the session keeps, and how the file gets
+  # it back. A leaf: the types a row names are named in session.rb, in a
+  # block its lambdas call (`type.call`, not `yield`: never while the
+  # constructor runs, so Performance/RedundantBlockCall is off for them).
+  SessionField = Data.define(:key, :attr, :from, :default, :fresh, :optional, :cast, :write, :unread, :keep) do
+    # A field read as given, or through +cast+; +unread+ and +keep+ give
+    # it the Unread rule (see .level).
+    def self.plain(key, default, cast: nil, write: nil, fresh: default, optional: false, unread: nil, keep: nil)
+      new(key: key, attr: key.to_sym, from: nil, default: default, fresh: fresh, optional: optional, cast: cast,
+          write: write, unread: unread, keep: keep)
+    end
+
+    # rubocop:disable Performance/RedundantBlockCall
+    # A value object's field (nil for none): a value that is already one
+    # is taken as it is, nil is nil (the type isn't loaded for it: an
+    # autoloaded one stays unloaded), anything else is read with the type's
+    # +reader+ (from_file, of); the file gets its #to_file, through
+    # .scrub_utf8 with +scrub+. +type+ is a block, so the row names its type
+    # without loading it.
+    def self.value(key, reader, optional: false, scrub: false, &type)
+      cast = lambda do |value|
+        next nil if value.nil?
+
+        klass = type.call
+        value.is_a?(klass) ? value : klass.public_send(reader, value)
+      end
+      write = scrub ? ->(value) { value && scrub_utf8(value.to_file) } : ->(value) { value&.to_file }
+      new(key: key, attr: key.to_sym, from: nil, default: nil, fresh: nil, optional: optional, cast: cast,
+          write: write, unread: nil, keep: nil)
+    end
+
+    # A list of value objects ([] for none): read with the type's .list, each
+    # written with its #to_file.
+    def self.list(key, &type)
+      new(key: key, attr: key.to_sym, from: nil, default: [], fresh: [], optional: false,
+          cast: ->(value) { type.call.list(value) }, write: ->(values) { values.map(&:to_file) }, unread: nil,
+          keep: nil)
+    end
+
+    # A session's own level (nil for none), with the Unread rule: a value
+    # that isn't one reads as nil, and the session keeps it as written (a
+    # newer chi's level, a hand edit) and saves it back so, until it sets
+    # its own. A level is the type's .session_level of the value; a String
+    # that doesn't read as one, other than the +unset+ word (any case and
+    # spaces), is the one kept. With +merge_unread+ the field is a value
+    # object of several parts (LLMContextOverride: .from_file, .unread):
+    # the parts it couldn't read are kept, and the file gets them under the
+    # parts it has (nil when there is none).
+    def self.level(key, unset: nil, merge_unread: false, &type)
+      if merge_unread
+        cast = ->(value) { type.call.from_file(value) }
+        unread = ->(value) { type.call.unread(value) }
+        write = ->(value) { value&.to_file }
+        keep = lambda do |written, kept|
+          saved = kept.merge(written || {})
+          saved.empty? ? nil : saved
+        end
+      else
+        cast = ->(value) { type.call.session_level(value) }
+        unread = lambda do |value|
+          value if value.is_a?(String) && type.call.session_level(value).nil? && !value.strip.casecmp?(unset)
+        end
+        write = ->(value) { value&.to_s }
+        keep = ->(written, kept) { written || kept }
+      end
+      new(key: key, attr: key.to_sym, from: nil, default: nil, fresh: nil, optional: false, cast: cast, write: write,
+          unread: unread, keep: keep)
+    end
+    # rubocop:enable Performance/RedundantBlockCall
+
+    # A key only the file has: +write+ takes Session's +from+ attribute.
+    def self.file_only(key, default, from:, write:)
+      new(key: key, attr: nil, from: from, default: default, fresh: nil, optional: false, cast: nil, write: write,
+          unread: nil, keep: nil)
+    end
+
+    def required? = default.equal?(SessionField::REQUIRED)
+
+    def fresh_required? = fresh.equal?(SessionField::REQUIRED)
+
+    # A new Session's value when it isn't given: a fresh copy of a list or
+    # a Hash, never one shared with another session.
+    def fresh_value = fresh.is_a?(Array) || fresh.is_a?(Hash) ? fresh.dup : fresh
+
+    # The instance variable #to_h reads (never the reader: project_root's
+    # and verdicts' have logic of their own).
+    def ivar = :"@#{attr || from}"
+
+    # +value+ as the attribute holds it.
+    def cast_value(value) = cast ? cast.call(value) : value
+
+    # The attribute's +value+ as the file holds it, with what the session
+    # kept of a value it couldn't read (+kept+, .level's).
+    def dump(value, kept = nil)
+      written = write ? write.call(value) : value
+      keep ? keep.call(written, kept) : written
+    end
+
+    # The last guard before JSON.generate, which raises on bytes that
+    # aren't UTF-8: a save that raised would lose the whole conversation.
+    # ToolRunner already scrubs tool output; this covers any other source.
+    def self.scrub_utf8(obj)
+      case obj
+      when String
+        str = obj.encoding == Encoding::UTF_8 ? obj : obj.dup.force_encoding(Encoding::UTF_8)
+        str.valid_encoding? ? str : str.scrub("?")
+      when Array then obj.map { |element| scrub_utf8(element) }
+      when Hash then obj.to_h { |key, value| [key, scrub_utf8(value)] }
+      else obj
+      end
+    end
+
+    # A Hash with String keys (one level).
+    def self.stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+  end
+
+  # A field a session file must have (KeyError without it, ArgumentError
+  # from Session.new).
+  SessionField::REQUIRED = Object.new.freeze
+end

data/lib/samagotchi/session_inbox.rb

@@ -442,7 +442,7 @@ module Samagotchi
     private_class_method :unmark_removed
 
     # How old a per-input tombstone (input/removed/, TurnCheckpoint's
-    # input/settled/) gets before a worker's start prunes it (#prune_old).
+    # input/settled/, a merge record in input/merged/) gets before a worker's start prunes it (#prune_old).
     # A wait reads one at its next poll (ReplyWait::POLL_INTERVAL) and a
     # later `chi send --wait --turn` reads a settled one at its start, so
     # only a wait whose process slept (a closed laptop) or one started long
@@ -470,6 +470,54 @@ module Samagotchi
     # The removed tombstones past +max_age+ (#prune_old).
     def self.prune_removed(session_dir, max_age: TOMBSTONE_MAX_AGE) = prune_old(session_dir, REMOVED_DIR, max_age: max_age)
 
+    # Where a running turn's drain records an input it merged as a steer:
+    # input/merged/<enqueued_id> = {"into": the turn's enqueued_id, "at"}.
+    # Its own directory: a file in input/settled/ reads as worker_stopped to
+    # a chi before it, and no *.json glob sees a subdirectory.
+    MERGED_DIR = "merged"
+
+    # Records that the input +id+ went into the turn +into+ (both
+    # enqueued_ids) as a steer, before the drain deletes its claimed file
+    # (Worker#pending_input_drain): a wait for it (ReplyWait's turn:) then
+    # waits for that turn (Poll#follow_merge). Nothing for an id that
+    # can't name a file, nor for a turn with none; a failed write only
+    # logs (the wait infers the merge, as for a worker before this).
+    def self.mark_merged(session_dir, id, into:, now: Time.now)
+      return unless ENQUEUED_ID_NAME.match?(id.to_s) && ENQUEUED_ID_NAME.match?(into.to_s)
+
+      dir = File.join(session_dir, INPUT_DIR, MERGED_DIR)
+      FileUtils.mkdir_p(dir)
+      AtomicFile.write(File.join(dir, id), JSON.generate("into" => into, "at" => now.iso8601(3)))
+    rescue SystemCallError, IOError => e
+      Log.warn(:worker, "merge_record_write_failed", error: e.class.name, msg: e.message, enqueued_id: id)
+    end
+
+    # A merge record (#mark_merged): the enqueued_id of the turn an input
+    # went into, and when (a Time, nil when unreadable).
+    Merge = Data.define(:into, :at)
+
+    # @return [Merge, nil] the turn the input +id+ was merged into
+    #   (#mark_merged), nil without a readable record
+    def self.merged_into(session_dir, id)
+      return nil unless ENQUEUED_ID_NAME.match?(id.to_s)
+
+      raw = JSON.parse(File.read(File.join(session_dir, INPUT_DIR, MERGED_DIR, id.to_s)))
+      into = raw["into"]
+      return nil unless ENQUEUED_ID_NAME.match?(into.to_s)
+
+      at = begin
+        Time.iso8601(raw["at"].to_s)
+      rescue ArgumentError
+        nil
+      end
+      Merge.new(into: into, at: at)
+    rescue JSON::ParserError, SystemCallError, TypeError, NoMethodError
+      nil
+    end
+
+    # The merge records past +max_age+ (#prune_old).
+    def self.prune_merged(session_dir, max_age: TOMBSTONE_MAX_AGE) = prune_old(session_dir, MERGED_DIR, max_age: max_age)
+
     # @return [Boolean] whether the queued input +enqueued_id+ was removed
     #   before it ran (#take_queued_input's tombstone), or is being removed:
     #   the tombstone goes first, so while its claimed file is still there

data/lib/samagotchi/session_manager/emptiness.rb

@@ -10,7 +10,8 @@ module Samagotchi
     # other entry (or a file in one of the EMPTY_DIRS) is something the
     # session keeps. "pid" is the pid file workers wrote until 2026-10-01:
     # nothing writes or reads it now, but a folder from before still has one
-    # and is still empty.
+    # and is still empty. A turn's drawing (Bridge::TurnDrawings::FILE)
+    # exists only after a turn that kept messages: never a skeleton file.
     EMPTY_SKELETON_FILES = ["pid", "owner.lock", WorkerLink::FILE, AnalyticsFile::NAME].freeze
     EMPTY_DIRS = [SessionInbox::INPUT_DIR, SessionInbox::NOTES_DIR, "images"].freeze
     EMPTY_SKELETON_DIRS = (EMPTY_DIRS + [SessionInbox::OUTPUT_DIR]).freeze

data/lib/samagotchi/session_manager/listing.rb

@@ -2,10 +2,6 @@
 
 module Samagotchi
   class SessionManager
-    SUMMARY_DESC_LIMIT = 60
-
-    SUMMARY_PREVIEW_LIMIT = 120
-
     # Listing: read-only queries over the saved sessions (the lists, their
     # summary rows, a parent's delegates, a session's replies). Calls the
     # facade's session_owner. Meant to be loaded through samagotchi/session_manager.
@@ -23,10 +19,10 @@ module Samagotchi
       # `chi sessions list --live --format json|tsv` (chi note from a script)
       # and the agent's list_sessions tool; both pass the current project as
       # +project_root+ unless asked for every project.
-      # @param live [Boolean] only sessions a worker owns now (the owner lock,
-      #   not the saved status, which a dead worker leaves at "running"); a
-      #   session a one-shot (or an older chi's REPL) owns is left out: it
-      #   can't take notes
+      # @param live [Boolean] only sessions a worker owns now (WorkerLink's
+      #   worker_owned?: the owner lock, not the saved status, which a dead
+      #   worker leaves at "running"); a session a one-shot (or an older
+      #   chi's REPL) owns is left out: it can't take notes
       # @param cwd [String, nil] only sessions in this folder or below it
       # @param project_root [String, nil] only this project's sessions
       #   (Session#project_root)
@@ -34,76 +30,45 @@ module Samagotchi
       # @param include_tests [Boolean] false leaves out test runs
       # @param exclude [String, nil] a session id to leave out (the asker)
       # @param include_archived [Boolean] archived sessions too
-      # @return [Array<Hash>] {id:, short_id:, desc:, preview:, cwd:, project:,
-      #   updated_at:, status:, saved_status:, live:, busy:, owner:, recap:, auto_title:, parent_id:,
-      #   parent_short_id:, continues:, continues_short_id:, delegate:, archived:, scratch:, test_run:, waiting:,
-      #   waiting_id:, stopped_by:}; status = Session#displayed_status (a dead
-      #   worker's "running" is idle, as chi web shows it), saved_status = the
-      #   file's (a "running" with no owner yet is also a worker on its way:
-      #   Tools::Delegate.running?), busy =
-      #   live with a turn running, delegate = started by the delegate tool
-      #   (Session#delegate?; a fork has a parent_id but isn't one), continues = the session it continues (the
-      #   previous link of its chain, Session#continues), recap = the saved recap's first sentence, auto_title =
-      #   the auto title its reply led with (RecapTitle) or nil, project =
-      #   Session#project_root, waiting = the kind of question it waits on
-      #   ("question", "approval", "hook"; Session#waiting_question) or nil,
-      #   waiting_id = that question's id or nil, relayed_to = the parent
-      #   whose card it waits in too (the approval relay), its short id, or nil,
-      #   stopped_by = the hook that stopped the last turn (Session#stopped_by)
-      def session_summaries(live: false, cwd: nil, limit: nil, include_tests: true, exclude: nil, state_dir: nil,
-                            project_root: nil, include_archived: false, sort: nil, order: nil)
+      # @return [Array<SessionRow>] see SessionRow for the fields
+      def session_rows(live: false, cwd: nil, limit: nil, include_tests: true, exclude: nil, state_dir: nil,
+                       project_root: nil, include_archived: false, sort: nil, order: nil)
         sd = state_dir || Session.default_state_dir
         root = cwd && folder_path(cwd)
         roots = {}
         # One registry per listing, built only when a row has a saved context
         # to count: its session's llm_context budget is what ctx_pct counts
         # against (SessionMetrics.saved_context_pct).
-        budgets = listing_budgets
-        summaries = Session.list(state_dir: sd, sort: sort || "updated_at", order: order || "desc", project_root: project_root,
-                                 include_archived: include_archived).lazy
-                           .reject { |s| (!include_tests && s.test_run) || s.id == exclude }
-                           .select { |s| root.nil? || in_folder?(s.working_directory, root) }
-                           .filter_map do |s|
+        budgets = SessionRow.budgets
+        rows = Session.list(state_dir: sd, sort: sort || "updated_at", order: order || "desc", project_root: project_root,
+                            include_archived: include_archived).lazy
+                      .reject { |s| (!include_tests && s.test_run) || s.id == exclude }
+                      .select { |s| root.nil? || in_folder?(s.working_directory, root) }
+                      .filter_map do |s|
+          dir = Session.session_dir(s.id, state_dir: sd)
           owner = session_owner(s.id, state_dir: sd)
-          owned = !!owner&.worker?
-          next if live && !owned
+          link = WorkerLink.resolve(dir, unlink: false, owner: owner)
+          next if live && !link.worker_owned?
 
-          { id: s.id, short_id: s.id[0, 8], desc: summary_desc(s), preview: summary_preview(s), title: s.title, cwd: s.working_directory,
-            project: s.project_root(cache: roots), updated_at: s.updated_at, status: s.displayed_status(owner: owner), saved_status: s.status, live: owned, busy: owned && s.status == Session::STATUS_RUNNING,
-            owner: owner&.kind, **recap_fields(Session.session_dir(s.id, state_dir: sd)),
-            ctx_pct: SessionMetrics.saved_context_pct(Session.session_dir(s.id, state_dir: sd),
-                                                      budget_tokens: -> { budgets.call(s) })&.round(1),
-            parent_id: s.parent_id, parent_short_id: s.parent_id&.[](0, 8), continues: s.continues,
-            continues_short_id: s.continues&.[](0, 8), delegate: s.delegate?, archived: s.archived,
-            scratch: s.scratch, test_run: s.test_run, stopped_by: s.stopped_by }.merge(waiting_fields(s.waiting_question(live: owned)))
+          SessionRow.build(s, session_dir: dir, owner: owner, link: link, roots: roots, budgets: budgets)
         end
-        (limit ? summaries.first(limit) : summaries.to_a)
+        (limit ? rows.first(limit) : rows.to_a)
       end
 
-      # waiting: the question's kind, waiting_id: its id (what chi answer
-      # --question takes); both nil with none.
-      private def waiting_fields(waiting)
-        { waiting: waiting&.dig(:kind), waiting_id: waiting&.dig(:id), relayed_to: waiting&.dig(:relayed_to) }
-      end
-
-      # One HostRegistry for a whole listing, built on the first row that
-      # needs it (a saved context to count) and kept for the rest: resolving a
-      # session's llm_context budget reads config.yml (mtime-cached), so not
-      # one registry per row.
-      # @return [#call] (session) -> the session's budget in tokens or nil
-      private def listing_budgets
-        registry = nil
-        ->(session) { LLMContextStrategy.session_budget(session, registry: registry ||= HostRegistry.new) }
-      end
+      # .session_rows as the summaries route's hashes (SessionRow#to_summary_h,
+      # its 28 keys in order): chi web's GET /api/sessions/summaries.
+      # @return [Array<Hash>]
+      def session_summaries(**filters) = session_rows(**filters).map(&:to_summary_h)
 
       # The sessions delegated by +parent_id+ (the `delegate` tool), newest
-      # first, as .session_summaries rows. A running one (busy) counts against
+      # first, as .session_rows. A running one (busy) counts against
       # session.max_children. Archived ones too.
+      # @return [Array<SessionRow>]
       def children_of(parent_id, state_dir: nil)
         return [] if parent_id.to_s.empty?
 
-        session_summaries(state_dir: state_dir, include_tests: true, include_archived: true)
-          .select { |s| s[:parent_id] == parent_id.to_s }
+        session_rows(state_dir: state_dir, include_tests: true, include_archived: true)
+          .select { |s| s.parent_id == parent_id.to_s }
       end
 
       # Children, their children, …: a delegated session doesn't delegate
@@ -113,51 +78,15 @@ module Samagotchi
         queue = [id]
         until queue.empty?
           children_of(queue.shift, state_dir: state_dir).each do |child|
-            next if seen.include?(child[:id]) || except.include?(child[:id])
+            next if seen.include?(child.id) || except.include?(child.id)
 
-            seen << child[:id]
-            queue << child[:id]
+            seen << child.id
+            queue << child.id
           end
         end
         seen.drop(1)
       end
 
-      # "<cwd basename> · <last prompt, or the first preview>", one line.
-      private def summary_desc(session)
-        desc = [File.basename(session.working_directory.to_s), summary_text(session)].reject(&:empty?).join(" · ")
-        cut(desc, SUMMARY_DESC_LIMIT)
-      end
-
-      # A session row's recap: and auto_title: (RecapStore.card, one read).
-      private def recap_fields(session_dir)
-        card = RecapStore.card(session_dir)
-        { recap: card.preview, auto_title: card.title }
-      end
-
-      private def summary_preview(session)
-        cut(summary_text(session), SUMMARY_PREVIEW_LIMIT)
-      end
-
-      # A session as one line of text for the lists: its title (/title), else
-      # its last prompt, else the first message it was started with (a session
-      # command like `/model x`, or a first turn not saved yet).
-      def summary_text(session)
-        return one_line(session.title) unless session.title.to_s.strip.empty?
-
-        one_line(session.last_prompt.to_s.strip.empty? ? session.first_preview.to_s : session.last_prompt.to_s)
-      end
-
-      # A prompt as one line for a session list: whitespace collapsed, and a
-      # quoted or annotated message (ContextQuote, the web's annotations)
-      # without its "> " markers, so the words show.
-      def one_line(text)
-        text.to_s.gsub(/^[ \t]*(?:>[ \t]?)+/, "").gsub(/\s+/, " ").strip
-      end
-
-      private def cut(text, limit)
-        text.length > limit ? "#{text[0, limit - 1]}…" : text
-      end
-
       private def folder_path(path)
         File.realpath(path)
       rescue SystemCallError

data/lib/samagotchi/session_manager.rb

@@ -26,7 +26,7 @@ require_relative "participant_messages"
 require_relative "session"
 require_relative "session_inbox"
 require_relative "session_metrics"
-require_relative "llm_context_strategy"
+require_relative "effective_model"
 require_relative "session_setup"
 require_relative "host_registry"
 require_relative "utf8_default"
@@ -48,6 +48,7 @@ require_relative "model_profile"
 require_relative "installed_gem"
 require_relative "installed_versions"
 require_relative "recap_store"
+require_relative "session_row"
 require_relative "reminder_carry"
 require_relative "archive_store"
 require_relative "continue_offer"

data/lib/samagotchi/session_metrics.rb

@@ -1112,19 +1112,22 @@ module Samagotchi
         if guardrail.is_a?(Hash) && guardrail[:decided_by] == "system one"
           active[:guardrail] = { rule: guardrail[:rule], p: guardrail[:p], judgment_id: guardrail[:judgment_id] }.compact
         end
-        finish_tool_record(active, status.empty? ? "ok" : status, waited_ms: event[:waited_ms].to_i)
+        finish_tool_record(active, status.empty? ? "ok" : status, waited_ms: event[:waited_ms].to_i,
+                                                                  duration_ms: event[:duration_ms])
       end
     end
 
-    # Caller holds the mutex.
-    def finish_tool_record(active, status, waited_ms: 0)
+    # Caller holds the mutex. +duration_ms+: the event's (ToolRunner's,
+    # the figure every UI shows live); without one (a test kernel's
+    # events), timed here.
+    def finish_tool_record(active, status, waited_ms: 0, duration_ms: nil)
       record = active.slice(
         :id, :turn_id, :iteration, :call_index, :tool, :called_as, :via, :no_match, :guardrail, :started_at
       ).merge(
         status: status,
         completed_at: now.iso8601(3),
         # Less a guardrail approval wait (ToolRunner's waited_ms).
-        duration_ms: [elapsed_ms(active[:started_monotonic]) - waited_ms, 0].max
+        duration_ms: duration_ms.is_a?(Integer) ? duration_ms : [elapsed_ms(active[:started_monotonic]) - waited_ms, 0].max
       )
       @tool_records << record
       count_tool(record)

data/lib/samagotchi/session_paths.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "paths"
+
+module Samagotchi
+  # Where a session's files are and which ids name one: the sessions dir,
+  # a session's <id>.json and <id>/ dir, and the id rule every id from
+  # outside meets before it becomes a path. A leaf (Paths only), so a file
+  # that needs a session's path needs no Session: Session extends it, so
+  # Session.session_dir and the rest answer the same. `extend self`, not
+  # module_function: Session's copies must stay public.
+  module SessionPaths
+    extend self # rubocop:disable Style/ModuleFunction -- module_function would make Session's copies private
+
+    STATE_SUBDIR = File.join("samagotchi", "sessions")
+    FILE_EXT = ".json"
+
+    # An id that is not a session id: it could name a path outside the
+    # sessions dir ("../x", "/etc", "a/b", a NUL), or is empty.
+    class InvalidId < ArgumentError; end
+
+    # Ids are SecureRandom.uuid; anything made of letters, digits, "-" and
+    # "_" (up to 128, not starting with "-") is taken, so a UUID prefix the
+    # CLI resolves passes too. This is the one check every id from outside
+    # (the bridge, the web routes, chi send/note, delegate) meets before it
+    # becomes a path: session_dir and the session file path refuse others.
+    VALID_ID = /\A[A-Za-z0-9_][A-Za-z0-9_-]{0,127}\z/
+
+    def valid_id?(session_id)
+      session_id.is_a?(String) && VALID_ID.match?(session_id)
+    end
+
+    # @raise [InvalidId] unless valid_id?(session_id)
+    def check_id!(session_id)
+      return session_id if valid_id?(session_id)
+
+      raise InvalidId, "invalid session id: #{session_id.to_s[0, 80].inspect}"
+    end
+
+    # Directory for a specific session (holds IPC files alongside session.json).
+    # @raise [InvalidId] for an id that isn't one (valid_id?)
+    def session_dir(session_id, state_dir: default_state_dir)
+      File.join(state_dir, check_id!(session_id))
+    end
+
+    # A session's <id>.json.
+    # @raise [InvalidId] for an id that isn't one (valid_id?)
+    def session_file(session_id, state_dir: default_state_dir)
+      File.join(state_dir, "#{check_id!(session_id)}#{FILE_EXT}")
+    end
+
+    # XDG-aware sessions directory.
+    def default_state_dir(env: ENV)
+      File.join(Paths.state_home(env: env), STATE_SUBDIR)
+    end
+  end
+end

data/lib/samagotchi/session_retention.rb

@@ -78,7 +78,7 @@ module Samagotchi
       Dir.children(state_dir).filter_map do |name|
         dir = File.join(state_dir, name)
         next unless Session.valid_id?(name) && File.directory?(dir)
-        next if File.exist?(File.join(state_dir, "#{name}#{Session::FILE_EXT}"))
+        next if File.exist?(File.join(state_dir, "#{name}#{SessionPaths::FILE_EXT}"))
         next unless Time.now - File.mtime(dir) > EMPTY_GRACE_SECONDS && SessionManager.empty_session_dir?(dir)
         next if SessionManager.session_owner(name, state_dir: state_dir)
 
@@ -203,7 +203,7 @@ module Samagotchi
       passed_over = 0
 
       all.each_with_index do |session, idx|
-        path = File.join(state_dir, "#{session.id}#{Session::FILE_EXT}")
+        path = File.join(state_dir, "#{session.id}#{SessionPaths::FILE_EXT}")
         # Only when json present
         unless File.exist?(path)
           skipped << session.id