samagotchi 0.7.0 → 0.8.0

data/lib/samagotchi/memory_bundle/shipped_update.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
-require "digest"
-require "json"
 require_relative "installer"
 require_relative "listing"
 require_relative "manifest"
 require_relative "merger"
+require_relative "profile"
 require_relative "provenance"
 require_relative "source"
 require_relative "status"
@@ -26,13 +25,18 @@ module Samagotchi
     # user's file (kept). Hooks, rules and the plugin are replaced; an
     # edited one (which didn't load: its sha no longer matched) is listed
     # in replaced.
+    #
+    # A profile (a shipped meta bundle) is updated through Profile: its row
+    # is :would_update when the shipped version is newer or it has members
+    # to install (Profile.to_install, less the ones this chi can't load),
+    # even at the same version, so a member that failed is retried. adds
+    # names them.
     module ShippedUpdate
       # status: :would_update (plan), :updated, :up_to_date, :skipped,
       # :failed. note says why for skipped/failed. kept and replaced are
       # file names; under plan they are what apply would keep or replace.
-      Row = Struct.new(:name, :from, :to, :status, :note, :kept, :replaced, :source_dir, :scope, keyword_init: true)
-
-      SHIPPED_SOURCE = %r{/lib/samagotchi/bundles/[^/]+/?\z}
+      # adds is nil but for a profile: the members it installs.
+      Row = Struct.new(:name, :from, :to, :status, :note, :kept, :replaced, :source_dir, :scope, :adds, keyword_init: true)
 
       module_function
 
@@ -40,16 +44,16 @@ module Samagotchi
       # @return [Array<Row>] by name
       def plan(shipped_dir: SourceNormalizer::SHIPPED_DIR, chi_version: Samagotchi::VERSION)
         shipped = Listing.shipped(dir: shipped_dir).to_h { |s| [s.name, s] }
-        installed_names.map do |name|
-          plan_row(name, shipped[name], shipped_dir, chi_version)
+        installed.map do |name, data|
+          plan_row(name, data, shipped[name], shipped_dir, chi_version)
         end
       end
 
-      # The shipped bundles not installed (what the footer lists).
+      # The shipped bundles not installed (what the footer lists), a
+      # profile's members folded into it (Listing.grouped).
       # @return [Array<Listing::Shipped>]
       def not_installed(shipped_dir: SourceNormalizer::SHIPPED_DIR)
-        names = installed_names
-        Listing.shipped(dir: shipped_dir).reject { |s| names.include?(s.name) }
+        Listing.grouped(Listing.shipped(dir: shipped_dir), installed.map(&:first))
       end
 
       # Runs the Installer for each :would_update row; the others pass
@@ -58,6 +62,7 @@ module Samagotchi
       def apply(rows)
         rows.map do |row|
           next row unless row.status == :would_update
+          next apply_profile(row) if row.adds
 
           installer = Installer.new(source: row.source_dir, name: row.name, scope: row.scope, strict: true, upgrade: true)
           installer.run
@@ -73,32 +78,35 @@ module Samagotchi
         end
       end
 
-      def installed_names
-        dir = Provenance.bundles_dir
-        return [] unless File.directory?(dir)
+      def apply_profile(row)
+        result = Profile.install(row.source_dir, shipped_dir: File.dirname(row.source_dir))
+        row.dup.tap do |r|
+          r.adds = result.installed
+          r.status = result.failed? ? :failed : :updated
+          r.note = result.failed.map { |member, why| "#{member}: #{why}" }.join("; ") if result.failed?
+        end
+      end
 
-        Dir.children(dir).reject { |e| e.start_with?(".") || e == SystemBundle::BUNDLE_NAME }
-           .select { |e| File.file?(File.join(dir, e, "manifest.json")) }.sort
+      # [name, data] for each installed bundle but the system one, by name.
+      def installed
+        Provenance.each_installed.reject { |name, _| name == SystemBundle::BUNDLE_NAME }
       end
 
-      def plan_row(name, ship, shipped_dir, chi_version)
+      def plan_row(name, data, ship, shipped_dir, chi_version)
         row = Row.new(name: name, kept: [], replaced: [])
-        data = begin
-          Provenance.new(name: name).read
-        rescue JSON::ParserError, SystemCallError
-          nil
-        end
-        return skip(row, "manifest.json unreadable") unless data.is_a?(Hash)
+        return skip(row, "manifest.json unreadable") if data[:error]
 
         row.from = data[:version].to_s
         row.scope = data[:scope].to_s.empty? ? "system" : data[:scope].to_s
-        return skip(row, "not from chi") unless ship && data[:source].to_s.match?(SHIPPED_SOURCE)
+        return skip(row, "not from chi") unless ship && data[:source].to_s.match?(SourceNormalizer::SHIPPED_SOURCE)
 
         row.to = ship.version.to_s
         return skip(row, "newer than shipped: left") if Listing.newer?(row.from, row.to)
-        return row.tap { |r| r.status = :up_to_date; r.to = nil } unless Listing.newer?(row.to, row.from)
 
         row.source_dir = File.join(shipped_dir, ship.source)
+        return profile_row(row, data, shipped_dir, chi_version) if Profile.shipped_meta?(row.source_dir, shipped_dir: shipped_dir)
+        return row.tap { |r| r.status = :up_to_date; r.to = nil } unless Listing.newer?(row.to, row.from)
+
         manifest = Manifest.read(dir: row.source_dir)
         if Manifest.requires_chi_failure(manifest.requires_chi, chi_version)
           return skip(row, "needs chi #{manifest.requires_chi}", keep_to: true)
@@ -111,6 +119,23 @@ module Samagotchi
         row
       end
 
+      def profile_row(row, data, shipped_dir, chi_version)
+        manifest = Manifest.read(dir: row.source_dir)
+        newer = Listing.newer?(row.to, row.from)
+        if newer && Manifest.requires_chi_failure(manifest.requires_chi, chi_version)
+          return skip(row, "needs chi #{manifest.requires_chi}", keep_to: true)
+        end
+
+        row.adds = Profile.to_install(manifest, data).reject do |member|
+          Manifest.requires_chi_failure(Manifest.read(dir: File.join(shipped_dir, member)).requires_chi, chi_version)
+        rescue Manifest::ValidationError, Psych::Exception
+          false # apply reports it failing
+        end
+        row.to = nil unless newer
+        row.status = newer || row.adds.any? ? :would_update : :up_to_date
+        row
+      end
+
       def skip(row, note, keep_to: false)
         row.to = nil unless keep_to
         row.status = :skipped
@@ -147,10 +172,10 @@ module Samagotchi
       end
 
       def edited?(path, meta)
-        recorded = meta.is_a?(Hash) ? meta[:sha256].to_s.delete_prefix("sha256:") : ""
-        return false if recorded.empty? || !File.file?(path)
+        recorded = meta.is_a?(Hash) ? meta[:sha256] : nil
+        return false if Provenance.recorded_sha(recorded).empty? || !File.file?(path)
 
-        Digest::SHA256.hexdigest(File.binread(path)) != recorded
+        !Provenance.sha_matches?(path, recorded)
       end
     end
   end

data/lib/samagotchi/memory_bundle/source.rb

@@ -38,6 +38,8 @@ module Samagotchi
 
       # The bundles shipped with chi (lib/samagotchi/bundles/<name>).
       SHIPPED_DIR = File.expand_path("../bundles", __dir__)
+      # A provenance source that is a shipped dir (in a gem or a checkout).
+      SHIPPED_SOURCE = %r{/lib/samagotchi/bundles/[^/]+/?\z}
 
       # A bare name (no path separator) that isn't a path here names a
       # shipped bundle: `chi bundle install guardrails`. A directory or file

data/lib/samagotchi/memory_bundle/status.rb

@@ -71,9 +71,8 @@ module Samagotchi
         path = provenance.plugin_path(data)
         return nil unless path
 
-        recorded = data[:plugin][:sha256].to_s.delete_prefix("sha256:")
         state = if !File.file?(path) then "missing"
-                elsif Digest::SHA256.hexdigest(File.binread(path)) == recorded then "ok"
+                elsif Provenance.sha_matches?(path, data[:plugin][:sha256]) then "ok"
                 else "modified"
                 end
         { file: File.basename(path), path: path, state: state, requires_chi: data[:requires_chi],

data/lib/samagotchi/memory_bundle.rb

@@ -11,6 +11,7 @@ require_relative "memory_bundle/status"
 require_relative "memory_bundle/system_bundle"
 require_relative "memory_bundle/builder"
 require_relative "memory_bundle/listing"
+require_relative "memory_bundle/profile"
 module Samagotchi
   # Namespace for shareable memory bundle functionality.
   module MemoryBundle; end

data/lib/samagotchi/note_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "session"
+require_relative "session_inbox"
 require_relative "session_manager"
 
 module Samagotchi
@@ -40,8 +41,8 @@ module Samagotchi
         return 2
       end
       begin
-        text = SessionManager.checked_text(text)
-      rescue SessionManager::NoteRejected => e
+        text = SessionInbox.checked_text(text)
+      rescue SessionInbox::NoteRejected => e
         @stderr.puts("chi note: #{e.message}")
         return 1
       end
@@ -131,11 +132,11 @@ module Samagotchi
         return false
       end
 
-      path = SessionManager.write_note(id, text: text, source: source, state_dir: @state_dir)
+      path = SessionInbox.write_note(id, text: text, source: source, state_dir: @state_dir)
       if owner
         @stdout.puts("#{short}  queued: its worker adds it within a few seconds")
       else
-        queued = SessionManager.find_new_note_files(File.dirname(File.dirname(path))).size
+        queued = SessionInbox.find_new_note_files(File.dirname(File.dirname(path))).size
         @stdout.puts("#{short}  waits for the session's next start (#{queued} #{queued == 1 ? "note" : "notes"} queued)")
       end
       true

data/lib/samagotchi/owner_lock.rb

@@ -65,12 +65,6 @@ module Samagotchi
       nil
     end
 
-    # @return [Boolean] whether this session has ever had a lock-taking owner
-    #   (workers from before the lock only left a pid file)
-    def self.lock_file?(session_dir)
-      File.exist?(path(session_dir))
-    end
-
     def self.path(session_dir)
       File.join(session_dir, FILE)
     end

data/lib/samagotchi/paths.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The XDG base directories chi keeps its files under, read from +env+ on
+  # every call (specs and smoke runs point XDG_* elsewhere after load):
+  #   state:  $XDG_STATE_HOME  or ~/.local/state  (sessions, logs, history, plugin data)
+  #   config: $XDG_CONFIG_HOME or ~/.config       (config.yml, memories, hooks)
+  # A blank variable counts as unset. The samagotchi folder inside each is
+  # #state_dir / ConfigFile.config_dir.
+  module Paths
+    APP_DIR = "samagotchi"
+
+    module_function
+
+    # @return [String] $XDG_STATE_HOME, else ~/.local/state
+    def state_home(env: ENV)
+      xdg = env.fetch("XDG_STATE_HOME", "").to_s.strip
+      xdg.empty? ? File.join(Dir.home, ".local", "state") : xdg
+    end
+
+    # @return [String] <state home>/samagotchi
+    def state_dir(env: ENV)
+      File.join(state_home(env: env), APP_DIR)
+    end
+
+    # @return [String] $XDG_CONFIG_HOME, else ~/.config
+    def config_home(env: ENV)
+      xdg = env.fetch("XDG_CONFIG_HOME", "").to_s.strip
+      xdg.empty? ? File.expand_path("~/.config") : xdg
+    end
+  end
+end

data/lib/samagotchi/plugin/api.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../log"
+require_relative "../hooks/registry"
 require_relative "../tools/args"
 require_relative "service"
 require_relative "tool_result"
@@ -14,7 +15,6 @@ module Samagotchi
       COMMAND_NAME = %r{\A/[a-z][a-z0-9_-]{0,31}\z}
       TOOL_NAME = /\A[a-z][a-z0-9_]{0,47}\z/
       PARAM_NAME = /\A[a-z_][a-z0-9_]*\z/i
-      FAILED_STREAM_HOOK_LOG_SECONDS = 60
 
       # @param bundle [String]
       # @param label [String] "<file> (bundle <name>)": what hooks and
@@ -224,16 +224,13 @@ module Samagotchi
           block = hook[:block]
           context = @context
           # A stream hook fires ~once a second: a broken one logs once a minute.
-          quiet_for = hook[:event] == :generation_progress ? FAILED_STREAM_HOOK_LOG_SECONDS : 0
-          logged_at = nil
+          log_failure = Hooks.failure_log_gate(hook[:event])
           @registries.hooks.register_bundle(bundle, hook[:event], hook_name: label.split(" ").first,
                                                                   priority: hook[:priority]) do |event|
             block.call(event, context)
           rescue StandardError => e
-            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-            next if logged_at && now - logged_at < quiet_for
+            next unless log_failure.call
 
-            logged_at = now
             # Logged only: a turn's live region is on screen.
             Log.warn(:plugins, "plugin_hook_failed", bundle: bundle, event: hook[:event].to_s, error: e.class.name,
                                                      msg: "#{label} #{hook[:event]} hook failed: #{e.message}")

data/lib/samagotchi/plugin/context.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require_relative "../log"
+require_relative "../paths"
 require_relative "../guardrails/context"
 require_relative "../idle_client"
 require_relative "side_question"
@@ -85,9 +86,7 @@ module Samagotchi
       # @return [String]
       def data_dir
         @data_dir ||= begin
-          xdg = @env.fetch("XDG_STATE_HOME", "").to_s.strip
-          base = xdg.empty? ? File.join(Dir.home, ".local", "state") : xdg
-          File.join(base, "samagotchi", "plugins", @bundle).tap { |dir| FileUtils.mkdir_p(dir) }
+          File.join(Paths.state_dir(env: @env), "plugins", @bundle).tap { |dir| FileUtils.mkdir_p(dir) }
         end
       end
 

data/lib/samagotchi/plugin/loader.rb

@@ -44,7 +44,7 @@ module Samagotchi
       # @return [Array<String>] the bundles whose plugin loaded
       def load_installed(registries, failures: nil, settings: {})
         loaded = []
-        MemoryBundle::Provenance.each_installed_with_plugin do |bundle_name, data|
+        MemoryBundle::Provenance.each_installed(holding: :plugin) do |bundle_name, data|
           ok = load_bundle(bundle_name, data, registries, failures: failures, settings: settings[bundle_name.to_s] || {})
           loaded << bundle_name if ok
         end

data/lib/samagotchi/question_desk.rb

@@ -21,8 +21,9 @@ module Samagotchi
     # of ArgumentError for existing callers; transports map it to 409 Conflict.
     class NotPending < ArgumentError; end
 
-    DISMISSED_NOTE = "The user dismissed the question without answering. Go on with your best judgement, " \
-                     "or ask in your reply if you can't."
+    DISMISSED_NOTE = "The user dismissed the question without answering. Don't do what you asked about, " \
+                     "or anything else that changes files or state. Finish your reply with what you found " \
+                     "and what you would do, and wait."
 
     # @param session           [#call] → Session, nil
     # @param state_dir         [#call] → String, the session's state dir

data/lib/samagotchi/recap_store.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "fileutils"
+require_relative "atomic_file"
 
 require_relative "session"
 
@@ -54,8 +55,7 @@ module Samagotchi
       dir = Session.session_dir(id, state_dir: state_dir)
       FileUtils.mkdir_p(dir)
       path = File.join(dir, FILE)
-      File.write("#{path}.tmp", JSON.generate(state))
-      File.rename("#{path}.tmp", path)
+      AtomicFile.write(path, JSON.generate(state))
     end
 
     # Remove the saved recap (it no longer describes the session).

data/lib/samagotchi/reply_wait.rb

@@ -2,6 +2,7 @@
 
 require_relative "session"
 require_relative "turn_note"
+require_relative "session_inbox"
 
 module Samagotchi
   # Loaded on first use: session_manager requires terminal_ui, which
@@ -165,7 +166,7 @@ module Samagotchi
     end
 
     def reply_dir(id, state_dir:)
-      File.join(Session.session_dir(id, state_dir: state_dir), SessionManager::OUTPUT_DIR)
+      File.join(Session.session_dir(id, state_dir: state_dir), SessionInbox::OUTPUT_DIR)
     end
 
     def newer?(file, cursor)

data/lib/samagotchi/self_report.rb

@@ -215,9 +215,8 @@ module Samagotchi
     # "samagotchi-system 0.1.5 (shipped 0.1.5), other 1.0.0"
     def bundles_summary
       shipped = MemoryBundle::Manifest.read(dir: MemoryBundle::SystemBundle::GEM_BUNDLE_DIR).version rescue nil
-      installed = Dir[File.join(MemoryBundle::Provenance.bundles_dir, "*", "manifest.json")].sort.map do |path|
-        name = File.basename(File.dirname(path))
-        version = (JSON.parse(File.read(path))["version"] rescue nil) || "?"
+      installed = MemoryBundle::Provenance.each_installed.map do |name, data|
+        version = data[:version] || "?"
         label = "#{name} #{version}"
         label += " (shipped #{shipped})" if name == MemoryBundle::SystemBundle::BUNDLE_NAME
         label

data/lib/samagotchi/send_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "session"
+require_relative "session_inbox"
 require_relative "session_manager"
 require_relative "context_quote"
 require_relative "reply_wait"
@@ -122,8 +123,8 @@ module Samagotchi
         return 2
       end
       begin
-        prompt = SessionManager.checked_text(prompt, noun: "message")
-      rescue SessionManager::NoteRejected => e
+        prompt = SessionInbox.checked_text(prompt, noun: "message")
+      rescue SessionInbox::NoteRejected => e
         @stderr.puts("chi send: #{e.message}")
         return 1
       end

data/lib/samagotchi/session.rb

@@ -4,7 +4,9 @@ require "fileutils"
 require "json"
 require "securerandom"
 require "time"
+require_relative "atomic_file"
 
+require_relative "paths"
 require_relative "project_scope"
 
 module Samagotchi
@@ -22,14 +24,6 @@ module Samagotchi
     STATUS_ERROR = "error"
     STATUS_STOPPED = "stopped"
 
-    # Retention defaults, the session.retention_days / max_count /
-    # keep_status defaults (SessionManager resolves the settings).
-    DEFAULT_RETENTION_DAYS = 14
-    DEFAULT_MAX_COUNT = 500
-    # status is turn state; a live owner (the prune alive_check) is what
-    # protects a session in use, so no status is kept by default: a
-    # "running" left by a crashed worker must not keep it forever.
-    DEFAULT_KEEP_STATUS = [].freeze
     SORT_KEYS = %w[created_at updated_at].freeze
     SORT_ORDERS = %w[asc desc].freeze
 
@@ -146,7 +140,7 @@ module Samagotchi
     # Load a persisted session by its UUID.
     # Whether +session_id+ has a saved session.
     def self.exist?(session_id, state_dir: default_state_dir)
-      File.exist?(session_path(session_id, state_dir: state_dir))
+      valid_id?(session_id) && File.exist?(session_path(session_id, state_dir: state_dir))
     end
 
     def self.load(session_id, state_dir: default_state_dir)
@@ -192,7 +186,7 @@ module Samagotchi
     # names several sessions raises AmbiguousId, which lists them.
     def self.resolve_id(id_or_prefix, state_dir: default_state_dir)
       id = id_or_prefix.to_s
-      return id unless id.match?(/\A[\w-]+\z/) && !File.exist?(session_path(id, state_dir: state_dir))
+      return id unless valid_id?(id) && !File.exist?(session_path(id, state_dir: state_dir))
 
       matches = Dir.glob(File.join(state_dir, "#{id}*#{FILE_EXT}")).map { |path| File.basename(path, FILE_EXT) }.sort
       return matches.fetch(0, id) if matches.size <= 1
@@ -253,6 +247,9 @@ module Samagotchi
     #   required field, or gone
     def self.summary_from_file(path)
       data = JSON.parse(File.read(path))
+      # An id that isn't one (hand-edited, or not ours) would be a path.
+      return nil unless valid_id?(data["id"])
+
       used_mems = data["used_memory_names"] || data["used_memories"] || []
       pending = data["pending_question"]
       new(
@@ -281,130 +278,6 @@ module Samagotchi
       nil
     end
 
-    # Prune old sessions according to retention policy.
-    #
-    # Only deletes when the json file exists — orphan dirs without json are never removed.
-    # Honors keep_status and live-worker guard.
-    # A session is kept only if it is NOT expired by age AND within max_count;
-    # either expiry or overflow triggers deletion (unless protected).
-    #
-    # +empty_check+ (id → Boolean) marks a session left empty: it goes
-    # whatever its age and the count (SessionManager.prune_sessions).
-    #
-    # +any_age+ makes every session eligible, whatever its age and the
-    # count (`chi sessions clean` with no --days: test runs are throwaway).
-    #
-    # A scratch session nobody owns (its REPL was killed) goes whatever its
-    # age, its status and the count; +test_only+ takes it too.
-    #
-    # +max_count+ counts the sessions that stay: one deleted whatever its
-    # place (scratch, left empty, expired, +any_age+) takes no slot.
-    #
-    # Archived sessions are not in .list, so they are neither deleted nor
-    # counted. One unarchived is aged from when it was unarchived, if later.
-    #
-    # @return [Hash] { deleted: [ids], kept: [ids], skipped: [ids] }
-    def self.prune(state_dir: default_state_dir, days: DEFAULT_RETENTION_DAYS, max_count: DEFAULT_MAX_COUNT,
-                   keep_status: DEFAULT_KEEP_STATUS, dry_run: false, test_only: false, alive_check: nil,
-                   empty_check: nil, any_age: false)
-      keep_status = Array(keep_status).map(&:to_s)
-      # Fetch all sessions sorted newest-first for count logic
-      all = list(state_dir: state_dir, sort: "updated_at", order: "desc")
-      # Filter test_only if requested
-      if test_only
-        all = all.select { |session| session.test_run || session.scratch }
-      end
-
-      now = Time.now
-      cutoff = days.to_i.positive? ? now - days.to_i * 86_400 : nil
-      max = max_count.to_i
-
-      deleted = []
-      kept = []
-      skipped = []
-      passed_over = 0
-
-      all.each_with_index do |session, idx|
-        path = File.join(state_dir, "#{session.id}#{FILE_EXT}")
-        # Only when json present
-        unless File.exist?(path)
-          skipped << session.id
-          next
-        end
-
-        # Protected by keep_status
-        if keep_status.include?(session.status.to_s) && !session.scratch
-          kept << session.id
-          next
-        end
-
-        # Protected by live worker
-        if alive_check
-          begin
-            if alive_check.call(session.id)
-              kept << session.id
-              next
-            end
-          rescue StandardError
-            nil
-          end
-        end
-
-        left_empty = begin
-          empty_check&.call(session.id)
-        rescue StandardError
-          false
-        end
-
-        # Determine expiry and overflow
-        expired = false
-        if cutoff
-          begin
-            updated = Time.iso8601(session.updated_at.to_s)
-          rescue ArgumentError
-            updated = File.mtime(path) rescue now
-          end
-          unarchived = ArchiveStore.unarchived_at(session_dir(session.id, state_dir: state_dir))
-          updated = unarchived if unarchived && unarchived > updated
-          expired = updated < cutoff
-        end
-
-        # A session deleted whatever its place (scratch, left empty,
-        # expired, any_age) takes no max_count slot: the count is of the
-        # sessions ahead that stay.
-        overflow = max.positive? && idx - passed_over >= max
-        passed_over += 1 if expired || left_empty || any_age || session.scratch
-
-        # retain forever when both disabled
-        if max.zero? && cutoff.nil? && !left_empty && !any_age && !session.scratch
-          kept << session.id
-          next
-        end
-
-        # If neither expired nor overflow, keep
-        unless expired || overflow || left_empty || any_age || session.scratch
-          kept << session.id
-          next
-        end
-
-        # Eligible for deletion
-        if dry_run
-          deleted << session.id
-        else
-          begin
-            FileUtils.rm_f(path)
-            sidecar = File.join(state_dir, session.id)
-            FileUtils.rm_rf(sidecar) if File.exist?(sidecar)
-            deleted << session.id
-          rescue StandardError
-            skipped << session.id
-          end
-        end
-      end
-
-      { deleted: deleted, kept: kept, skipped: skipped }
-    end
-
     # Persist the session atomically. Updates +updated_at+ in place.
     def save(state_dir: self.class.default_state_dir)
       @updated_at = Time.now.iso8601(3)
@@ -412,8 +285,7 @@ module Samagotchi
       @metadata_version = METADATA_VERSION
       FileUtils.mkdir_p(state_dir)
 
-      path = File.join(state_dir, "#{@id}#{FILE_EXT}")
-      temp_path = "#{path}.tmp"
+      path = self.class.session_file(@id, state_dir: state_dir)
 
       # Auto-compute first_preview if not yet cached and messages contain a user entry.
       compute_first_preview!
@@ -441,8 +313,7 @@ module Samagotchi
         "last_turn" => @last_turn
       }
 
-      File.write(temp_path, JSON.pretty_generate(record) + "\n")
-      File.rename(temp_path, path)
+      AtomicFile.write(path, JSON.pretty_generate(record) + "\n")
       self
     end
 
@@ -475,9 +346,38 @@ module Samagotchi
       session.save(state_dir: state_dir)
     end
 
+    # 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 self.valid_id?(session_id)
+      session_id.is_a?(String) && VALID_ID.match?(session_id)
+    end
+
+    # @raise [InvalidId] unless valid_id?(session_id)
+    def self.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 self.session_dir(session_id, state_dir: default_state_dir)
-      File.join(state_dir, session_id)
+      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 self.session_file(session_id, state_dir: default_state_dir)
+      File.join(state_dir, "#{check_id!(session_id)}#{FILE_EXT}")
     end
 
     # Default sessions directory path.
@@ -487,9 +387,7 @@ module Samagotchi
 
     # XDG-aware sessions directory.
     def self.default_state_dir(env: ENV)
-      xdg = env.fetch("XDG_STATE_HOME", "").to_s.strip
-      base = xdg.empty? ? File.join(Dir.home, ".local", "state") : xdg
-      File.join(base, STATE_SUBDIR)
+      File.join(Paths.state_home(env: env), STATE_SUBDIR)
     end
 
     # Derive and cache the first user-message preview in the session record.
@@ -552,7 +450,7 @@ module Samagotchi
       end
 
       def session_path(session_id, state_dir:)
-        File.join(state_dir, "#{session_id}#{FILE_EXT}")
+        session_file(session_id, state_dir: state_dir)
       end
     end
   end