samagotchi 0.129.0 → 0.130.1

data/lib/samagotchi/guardrails/review_paths.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require_relative "protected_paths"
+require_relative "chi_dirs"
+require_relative "path_resolve"
 require_relative "shell_paths"
 require_relative "../paths"
 
@@ -11,7 +12,7 @@ module Samagotchi
     # (chi's state and config dirs, home secret dirs, project secret files),
     # checked on the path as given and as it resolves (a symlink in the
     # project to ~/.ssh is ~/.ssh; a `..` after a symlinked dir climbs out
-    # of its target, as the kernel opens it: ProtectedPaths.reals).
+    # of its target, as the kernel opens it: PathResolve.reals).
     # ReviewBoundary asks it for every read of a participant's turn; a
     # review session's subjects (chi review, the participant page's Plan)
     # go through the same check.
@@ -45,8 +46,9 @@ module Samagotchi
       SECRET = :secret
       HOME_ROOT = :home_root
 
-      # chi's state dir and config dir, as Paths has them now.
-      def self.chi_dirs = [Paths.state_dir, File.join(Paths.config_home, Paths::APP_DIR)]
+      # chi's state dir, config dir and a hooks dir configured outside it
+      # (ChiDirs.review).
+      def self.chi_dirs = ChiDirs.review
 
       # Whether +root+ is the home folder or a folder above it (symlinks
       # resolved on both): no project to keep a participant's turn in. A
@@ -56,7 +58,7 @@ module Samagotchi
       def self.home_root?(root, home)
         return false if home.to_s.empty? || root.to_s.empty?
 
-        ShellPaths.within?(ProtectedPaths.real(home.to_s), ProtectedPaths.real(root.to_s))
+        PathResolve.under?(PathResolve.real(home.to_s), PathResolve.real(root.to_s))
       end
 
       # @param root [String, nil] the session's project root (the work tree
@@ -81,12 +83,12 @@ module Samagotchi
 
         return HOME_ROOT if ReviewPaths.home_root?(@root, @home)
 
-        real_root = ProtectedPaths.real(@root)
+        real_root = PathResolve.real(@root)
 
         paths.each do |path|
           given = File.expand_path(path)
-          reals = ProtectedPaths.reals(path)
-          return OUTSIDE unless reals.all? { |real| ShellPaths.within?(real, real_root) }
+          reals = PathResolve.reals(path)
+          return OUTSIDE unless reals.all? { |real| PathResolve.under?(real, real_root) }
           return SECRET if secret?(given) || reals.any? { |real| secret?(real) }
         end
         nil
@@ -100,7 +102,7 @@ module Samagotchi
       def secret_refusal(paths)
         paths.each do |path|
           given = File.expand_path(path)
-          return SECRET if secret?(given) || ProtectedPaths.reals(path).any? { |real| secret?(real) }
+          return SECRET if secret?(given) || PathResolve.reals(path).any? { |real| secret?(real) }
         end
         nil
       end
@@ -113,13 +115,13 @@ module Samagotchi
         @denied_roots ||= begin
           roots = @denied_dirs.compact.map { |dir| File.expand_path(dir) }
           roots += (HOME_SECRET_DIRS + HOME_SECRET_FILES).map { |name| File.join(@home, name) } unless @home.empty?
-          (roots + roots.map { |root| ProtectedPaths.real(root) }).uniq
+          (roots + roots.map { |root| PathResolve.real(root) }).uniq
         end
       end
 
       # Whether +path+ (absolute) is on the read denylist.
       def secret?(path)
-        return true if denied_roots.any? { |root| ShellPaths.within?(path, root) }
+        return true if denied_roots.any? { |root| PathResolve.under?(path, root) }
 
         parts = path.split(File::SEPARATOR)
         return true if parts.any? { |part| SECRET_FILE.match?(part) }

data/lib/samagotchi/guardrails/rm_targets.rb

@@ -2,7 +2,7 @@
 
 require_relative "shell_lex"
 require_relative "shell_paths"
-require_relative "protected_paths"
+require_relative "path_resolve"
 
 module Samagotchi
   module Guardrails
@@ -38,8 +38,8 @@ module Samagotchi
         code = ShellLex.code_text(command.to_s)
         return true if tokens.any? { |_, value| value.include?(ShellLex::SUBST) } && code.match?(/\brm\b/)
 
-        session = ProtectedPaths.real(session_root.to_s)
-        roots = tmp_roots.reject { |tmp| ShellPaths.within?(session, tmp) }
+        session = PathResolve.real(session_root.to_s)
+        roots = PathResolve.tmp_roots(session: session, roots: tmp_roots)
         walk = ShellPaths::Walk.new(cwd, home, env)
         ShellLex.simple_commands(tokens).any? do |words|
           wide = words.is_a?(Array) && words.any?(&RM_WORD) && wide?(words, walk, roots)
@@ -62,8 +62,8 @@ module Samagotchi
 
         targets.empty? || targets.any? do |target|
           paths = walk.paths(target)
-          paths.empty? || paths.flat_map { |path| ProtectedPaths.reals(path) }.any? do |real|
-            roots.none? { |tmp| real.start_with?(File.join(tmp, "")) }
+          paths.empty? || paths.flat_map { |path| PathResolve.reals(path) }.any? do |real|
+            roots.none? { |tmp| PathResolve.strictly_under?(real, tmp, fold: File.exist?(tmp)) }
           end
         end
       end

data/lib/samagotchi/guardrails/rules.rb

@@ -16,9 +16,12 @@ module Samagotchi
     #   command: a Ruby regex on a shell tool's command, the body of a
     #            heredoc its command only reads as data left out
     #            (Targets#rule_command, ShellLex.code_text)
-    #   path:    "outside_repo", or a glob on the resolved paths (absolute
-    #            or "**/…" globs match the absolute path; others the path
-    #            relative to the repo root, the cwd outside one)
+    #   path:    "outside_repo", or a glob on the paths (absolute or "**/…"
+    #            globs match the absolute path; others the path relative
+    #            to the repo root, the cwd outside one): as typed
+    #            (Targets#paths) and, for an ask or deny, as they resolve
+    #            (PathResolve.reals, relative to the root as it resolves),
+    #            so a symlink into .git/hooks doesn't slip past a hooks rule
     #   git:     "outside_repo": a shell call runs a mutating git
     #            subcommand outside the session's repo (ShellGitDirs)
     #   models:  "small" (Guardrails::ModelSize, guardrails.small_models),
@@ -102,12 +105,27 @@ module Samagotchi
 
           base = targets.repo_root || targets.cwd
           glob = path.start_with?("~") ? File.expand_path(path) : path
+          absolute = glob.start_with?("/", "**")
+          real_base = nil
           targets.paths.any? do |p|
-            candidate = glob.start_with?("/", "**") ? p : relative(p, base)
-            candidate && File.fnmatch(glob, candidate, GLOB_FLAGS)
+            forms = [[p, base]]
+            # A resolved match only adds an ask or a deny; were a verdict
+            # ever to let a call through, a symlink into its glob must not.
+            if resolved_match?
+              real_base ||= targets.real_rule_base
+              forms += targets.real_forms(p).map { |real| [real, real_base] }
+            end
+            forms.any? do |form, from|
+              candidate = absolute ? form : relative(form, from)
+              candidate && File.fnmatch(glob, candidate, GLOB_FLAGS)
+            end
           end
         end
 
+        # Whether a path: glob also matches the paths as they resolve: for
+        # an ask or a deny only.
+        def resolved_match? = VERDICTS.include?(verdict.to_s)
+
         def relative(path, base)
           prefix = File.join(base, "")
           path.start_with?(prefix) ? path.delete_prefix(prefix) : nil

data/lib/samagotchi/guardrails/scratch_writes.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "path_resolve"
 require_relative "protected_paths"
 require_relative "../memory_paths"
 
@@ -33,8 +34,8 @@ module Samagotchi
         targets = verdict.targets
         return false unless targets && %w[write edit].include?(targets.tool)
 
-        targets.paths.flat_map { |path| ProtectedPaths.reals(path) }.any? do |real|
-          ProtectedPaths.within?(real, @memories_dir.call)
+        targets.paths.flat_map { |path| PathResolve.reals(path) }.any? do |real|
+          PathResolve.within?(real, @memories_dir.call)
         end
       end
     end

data/lib/samagotchi/guardrails/shell_git_dirs.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "shell_lex"
-require_relative "protected_paths"
+require_relative "path_resolve"
+require_relative "shell_paths"
 
 module Samagotchi
   module Guardrails
@@ -11,11 +12,13 @@ module Samagotchi
     # it follows cd/pushd/popd, ( … ) subshells, git -C/--git-dir/--work-tree
     # and GIT_DIR/GIT_WORK_TREE. Where a `..` climbs out of a symlinked
     # dir's target, its lexical path and its physical one
-    # (ProtectedPaths.expand, the only look at the disk) both count: a cd
+    # (PathResolve.expand, the only look at the disk) both count: a cd
     # may land at either (the shell's logical cd chdirs to the physical
     # path when the logical one doesn't exist, and always with -P), so the
     # walk keeps every dir the command may be in, and git's -C and dir
-    # options are opened the kernel's way; such a git counts from each. It
+    # options are opened the kernel's way; such a git counts from each. A
+    # leading ~, $HOME, XDG dir or $TMPDIR is expanded as ShellPaths::Walk
+    # expands it (PathResolve.expand_word). It
     # catches honest mistakes (cd into another checkout and commit
     # there); sh -c, scripts, aliases and $(…) bodies get through. Never
     # raises on odd input.
@@ -32,9 +35,11 @@ module Samagotchi
       # @param home [String] for ~, $HOME, ${HOME} and a bare cd
       # @param env [Hash{String=>String}] the call's env: (task_create's):
       #   its GIT_DIR / GIT_WORK_TREE hold for each git unless it sets its own
+      # @param vars [Hash{String=>String}] the shell's variables a word's
+      #   $XDG_* / $TMPDIR expand from (ENV, with the call's env: over it)
       # @return [Array<String, Symbol>] absolute dirs and :unknown, unique
-      def self.for(command, cwd:, home: Dir.home, env: {})
-        Walk.new(cwd, home, env).run(ShellLex.simple_commands(ShellLex.lex(command.to_s)))
+      def self.for(command, cwd:, home: Dir.home, env: {}, vars: ENV)
+        Walk.new(cwd, home, env, vars).run(ShellLex.simple_commands(ShellLex.lex(command.to_s)))
       rescue ArgumentError, EncodingError
         [] # a NUL byte, invalid UTF-8: the shell would refuse it too
       end
@@ -45,9 +50,10 @@ module Samagotchi
         # More dirs than this after a cd: the dir is unknown.
         MAX_DIRS = 8
 
-        def initialize(cwd, home, env = {})
+        def initialize(cwd, home, env = {}, vars = ENV)
           @dirs = [cwd]
           @home = home
+          @vars = vars
           @env = env.slice("GIT_DIR", "GIT_WORK_TREE")
           @subshells = []
           @pushed = []
@@ -149,17 +155,16 @@ module Samagotchi
         end
 
         # An absolute path for +arg+ against +dir+ (`..` lexical, or
-        # +physical+: ProtectedPaths.expand); nil when it can't
-        # be told from the text (a variable, a substitution, a relative path
-        # against an unknown dir).
+        # +physical+: PathResolve.expand); nil when it can't
+        # be told from the text (a variable but those PathResolve.expand_word
+        # expands, a substitution, a relative path against an unknown dir).
         def expand(arg, dir, physical: false)
           return nil if arg.include?(ShellLex::SUBST)
 
-          arg = arg.sub(%r{\A(~|\$HOME|\$\{HOME\})(?=/|\z)}) { @home }
-          return nil if arg.include?("$") || arg.start_with?("~")
+          arg = PathResolve.expand_word(arg, home: @home, env: @vars) or return nil
           return nil unless arg.start_with?("/") || dir
 
-          physical ? ProtectedPaths.expand(arg, dir) : File.expand_path(arg, dir)
+          physical ? PathResolve.expand(arg, dir) : File.expand_path(arg, dir)
         end
       end
     end

data/lib/samagotchi/guardrails/shell_paths.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "shell_lex"
-require_relative "protected_paths"
+require_relative "path_resolve"
 require_relative "../redacted_inspect"
 
 module Samagotchi
@@ -24,11 +24,10 @@ module Samagotchi
       SCRIPT = /[\s;&|<>()'"`]/
       GLOB = /[*?\[\]{}]/
       HOOKS_PART = %r{(?:\A|/)\.git/hooks(?:/|\z)}
-      # $HOME, ${HOME} and the XDG dirs at a word's start.
-      EXPANSION = /\A\$(?:\{(HOME|XDG_[A-Z_]+|TMPDIR)\}|(HOME|XDG_[A-Z_]+|TMPDIR)\b)/
+      # $HOME, ${HOME} and the XDG dirs at a word's start (PathResolve's).
+      EXPANSION = PathResolve::EXPANSION
       # Where XDG dirs default when unset.
-      XDG_DEFAULTS = { "XDG_CONFIG_HOME" => ".config", "XDG_STATE_HOME" => ".local/state",
-                       "XDG_DATA_HOME" => ".local/share", "XDG_CACHE_HOME" => ".cache" }.freeze
+      XDG_DEFAULTS = PathResolve::XDG_DEFAULTS
       # A redirection's operator at a word's start (>>file, 2>file, <file).
       REDIRECT_PREFIX = /\A\d*(?:&>>?|>>?&?|<)/
 
@@ -40,7 +39,7 @@ module Samagotchi
       # @param cwd [String, nil] where the command starts
       # @param tmp_roots [Array<String>] where a .git/hooks part doesn't count
       def touches?(command, dirs:, text:, cwd:, home: Dir.home, env: ENV, tmp_roots: [])
-        roots = dirs.compact.map { |dir| ProtectedPaths.real(dir.to_s.chomp("/")) }.reject(&:empty?).uniq
+        roots = dirs.compact.map { |dir| PathResolve.real(dir.to_s.chomp("/")) }.reject(&:empty?).uniq
         any_path?(command, text: text, cwd: cwd, home: home, env: env) { |path| names?(path, roots, tmp_roots) }
       end
 
@@ -64,20 +63,22 @@ module Samagotchi
       end
 
       def names?(path, roots, tmp_roots)
-        ProtectedPaths.reals(path).any? do |real|
-          next true if roots.any? { |root| within?(real, root) }
+        PathResolve.reals(path).any? do |real|
+          next true if roots.any? { |root| PathResolve.under?(real, root) }
 
-          real.match?(HOOKS_PART) && tmp_roots.none? { |tmp| within?(real, tmp) }
+          real.match?(HOOKS_PART) && tmp_roots.none? { |tmp| PathResolve.under?(real, tmp) }
         end
       end
 
-      def within?(path, root) = path == root || path.start_with?(File.join(root, ""))
+      # Whether +path+ is +root+ or in it, cased alike on a disk that folds
+      # case (PathResolve.under?).
+      def within?(path, root) = PathResolve.under?(path, root)
 
       # Follows the current dir and gives, per simple command, each word
       # with its path (nil when it can't be resolved). A word is opened the
       # kernel's way, so a `..` after a symlinked dir climbs out of its
       # target: such a word comes twice, with its lexical path and its
-      # physical one (ProtectedPaths.expand), and a check reads both. A cd
+      # physical one (PathResolve.expand), and a check reads both. A cd
       # or pushd to such a word may land at either (the shell's logical cd
       # chdirs to the physical path when the logical one doesn't exist, and
       # always with -P, set -P or zsh's chase_links/chase_dots), so the walk
@@ -165,12 +166,12 @@ module Samagotchi
 
         # +word+ as a file argument against +dir+: its lexical path, and its
         # physical one when a `..` in it climbs out of a symlinked dir's
-        # target (ProtectedPaths.expand); [] when it can't be resolved.
+        # target (PathResolve.expand); [] when it can't be resolved.
         def paths_for(word, dir)
           lexical = resolve(word, dir) or return []
           return [lexical] unless word.include?("..")
 
-          [lexical, ProtectedPaths.expand(expand(word), dir)].uniq
+          [lexical, PathResolve.expand(expand(word), dir)].uniq
         end
 
         # An absolute path for +word+ against +dir+ with `..` taken
@@ -185,23 +186,11 @@ module Samagotchi
           dir && File.expand_path(word, dir)
         end
 
-        def expand(word)
-          word = word.sub(%r{\A~(?=/|\z)}) { @home }
-          word = word.sub(EXPANSION) { value(Regexp.last_match(1) || Regexp.last_match(2)) || "$" }
-          return nil if word.include?("$") || word.start_with?("~")
-
-          word
-        end
-
-        def value(name)
-          return @home if name == "HOME"
-
-          set = @env[name].to_s
-          return set unless set.empty?
-
-          XDG_DEFAULTS[name] && File.join(@home, XDG_DEFAULTS[name])
-        end
+        def expand(word) = PathResolve.expand_word(word, home: @home, env: @env)
       end
+
+      # PathResolve.expand_word, as this module has long named it.
+      def expand_word(word, home:, env:) = PathResolve.expand_word(word, home: home, env: env)
     end
   end
 end

data/lib/samagotchi/guardrails/targets.rb

@@ -13,7 +13,8 @@ require_relative "shell_lex"
 require_relative "read_only_shell"
 require_relative "shell_paths"
 require_relative "rm_targets"
-require_relative "protected_paths"
+require_relative "chi_dirs"
+require_relative "path_resolve"
 require_relative "../memory_paths"
 require_relative "../redacted_inspect"
 
@@ -234,11 +235,8 @@ module Samagotchi
       end
 
       # chi's own dirs (ParentApprovals.chi_dirs) and the session repo's
-      # git hooks dir.
-      def self.chi_dirs(context, base)
-        require_relative "parent_approvals"
-        ParentApprovals.chi_dirs + [context.hooks_dir(base)].compact
-      end
+      # git hooks dir (ChiDirs.touches).
+      def self.chi_dirs(context, base) = ChiDirs.touches(context, base)
 
       # A shell call's env: as the tool reads it (an object, or JSON text
       # for one): {} for none, and for one the tool would refuse (it then
@@ -260,13 +258,13 @@ module Samagotchi
       # +path+ (a file tool's, as Tools::ToolPath has it) absolute against
       # +base+: its lexical path (File.expand_path), and the one the kernel
       # opens when a `..` in it climbs out of a symlinked dir's target
-      # (ProtectedPaths.expand) after it; [] for a blank path. Every check
+      # (PathResolve.expand) after it; [] for a blank path. Every check
       # reads all of #paths, so it judges both.
       def self.absolutes(path, base)
         path = Tools::ToolPath.normalize(path)
         return [] if path.empty?
 
-        [File.expand_path(path, base), ProtectedPaths.expand(path, base)].uniq
+        [File.expand_path(path, base), PathResolve.expand(path, base)].uniq
       end
 
       # The file memory_write would write; nil when the call is invalid.
@@ -381,13 +379,26 @@ module Samagotchi
         @paths.any? { |p| Outside.outside?(p, root: @session_root) }
       end
 
+      # The resolved forms used by rules' path: globs, once per target path.
+      def real_forms(path)
+        @real_forms ||= {}
+        @real_forms[path] ||= PathResolve.reals(path)
+      end
+
+      # The resolved base used by rules' path: globs.
+      def real_rule_base
+        return @real_rule_base if defined?(@real_rule_base)
+
+        @real_rule_base = PathResolve.real(@repo_root || @cwd)
+      end
+
       # Where a shell call runs mutating git (ShellGitDirs: dirs, and
       # :unknown for one the text doesn't tell); [] for other tools.
       def git_dirs
         @git_dirs ||= if shell?
                         # chi's own GIT_DIR is not the command's concern
-                        shell_envs.each_with_index.flat_map do |(home, _), i|
-                          ShellGitDirs.for(@command, cwd: @cwd, home: home, env: i.zero? ? {} : @env)
+                        shell_envs.each_with_index.flat_map do |(home, vars), i|
+                          ShellGitDirs.for(@command, cwd: @cwd, home: home, env: i.zero? ? {} : @env, vars: vars)
                         end.uniq
                       else
                         []
@@ -435,12 +446,12 @@ module Samagotchi
       # disk MODEL_NOTES_x.md in Samagotchi/Memories is the same file chi
       # loads.
       def self.prompt_memory_path?(path)
-        ProtectedPaths.reals(path).any? do |real|
+        PathResolve.reals(path).any? do |real|
           next false unless File.basename(real).downcase.match?(PROMPT_MEMORY)
 
           dir = File.dirname(real)
-          dir.casecmp?(ProtectedPaths.real(MemoryPaths.system_dir)) ||
-            File.dirname(dir).casecmp?(ProtectedPaths.real(MemoryPaths.projects_dir))
+          dir.casecmp?(PathResolve.real(MemoryPaths.system_dir)) ||
+            File.dirname(dir).casecmp?(PathResolve.real(MemoryPaths.projects_dir))
         end
       rescue StandardError
         false

data/lib/samagotchi/remote_command.rb

@@ -122,8 +122,9 @@ module Samagotchi
       0
     end
 
-    # The token from its file or stdin; nil for none (a loopback chi web
-    # needs none), false after the error line.
+    # The token from its file or stdin; nil for none (a chi web on
+    # loopback only, no LAN mode or proxy, needs none), false after the
+    # error line.
     def read_token(options)
       text = if options[:token_file]
                begin
@@ -145,17 +146,26 @@ module Samagotchi
     end
 
     # GET /api/info with the token: the answer, or nil after the line that
-    # says why it can't be used.
+    # says why it can't be used. With no token, a chi web on the LAN or
+    # behind a proxy reached on its loopback (an SSH tunnel) answers chi's
+    # probe (its checked fields, no cwd) and every other route 401: it
+    # needs the token.
     def check(entry)
       reply = @transport.call(entry).call(:get, "/api/info")
       problem = SessionAccess::Remote.info_problem(entry, reply)
       return fail_line(problem.message) if problem
+      return fail_line(token_needed(entry)) unless reply.json.key?("cwd")
 
       reply.json
     rescue SessionAccess::RemoteFailed => e
       fail_line("#{e.message}: start chi web on #{entry.host} with web.host: lan")
     end
 
+    def token_needed(entry)
+      "#{entry.label}: its chi web needs its access token (its LAN link carries it, after ?token=; or its " \
+        "web-token file): chi remote add #{entry.name} #{entry.url} --token-file FILE"
+    end
+
     def lan_words(found, entry)
       return "loopback only" unless found["lan"]
 

data/lib/samagotchi/remotes.rb

@@ -25,8 +25,9 @@ module Samagotchi
     NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]{0,39}\z/
 
     # One remote: its +name+, chi web's +url+ (scheme, host and port, no
-    # path) and its access +token+ (nil for a loopback chi web, which needs
-    # none). #inspect leaves the token out.
+    # path) and its access +token+ (nil for a chi web on loopback only, no
+    # LAN mode or proxy: it alone needs none, its loopback reached through
+    # an SSH tunnel). #inspect leaves the token out.
     Entry = Data.define(:name, :url, :token) do
       # The host as an address, an IPv6 one bare (::1, not [::1]).
       def host = URI(url).hostname

data/lib/samagotchi/review_start.rb

@@ -6,6 +6,7 @@ require_relative "session_setup"
 require_relative "session_chain"
 require_relative "recap_store"
 require_relative "guardrails/context"
+require_relative "guardrails/path_resolve"
 require_relative "guardrails/review_paths"
 require_relative "participant_mode"
 
@@ -185,8 +186,8 @@ module Samagotchi
                            "only reads."
 
     def relative(full, root)
-      real_root = Guardrails::ProtectedPaths.real(root)
-      real = Guardrails::ProtectedPaths.real(full)
+      real_root = Guardrails::PathResolve.real(root)
+      real = Guardrails::PathResolve.real(full)
       real.delete_prefix(File.join(real_root, ""))
     end
   end

data/lib/samagotchi/session.rb

@@ -14,6 +14,7 @@ require_relative "session_setup"
 require_relative "prompt_note"
 require_relative "working_set_pin"
 require_relative "session_review"
+require_relative "version"
 
 require_relative "paths"
 require_relative "project_scope"
@@ -351,17 +352,27 @@ module Samagotchi
     # saved.
     attr_accessor :opener
 
+    # The top-level keys of the session file this chi doesn't know (a newer
+    # chi's fields), frozen, string keys: #to_h writes them back after the
+    # FIELDS as they were. Never read by this chi.
+    attr_reader :extra_fields
+
+    # The chi version that last saved the loaded file (#to_h writes this
+    # chi's VERSION); nil for a file from 0.130.0 or older.
+    attr_reader :written_by
+
     def initialize(id:, mode:, model_name:, working_directory:, messages:, created_at:, updated_at:,
-                   metadata_version: METADATA_VERSION, status: STATUS_IDLE, last_prompt: "",
+                   metadata_version: METADATA_VERSION, written_by: nil, status: STATUS_IDLE, last_prompt: "",
                    first_preview: "", first_turn_id: nil, test_run: false, pending_question: nil,
                    used_memory_names: [], project_root: nil,
                    preloaded_memory_names: [], muted_memory_names: [], parent_id: nil, scratch: false,
                    last_turn: nil, model_typed: nil, delegate: false, llm_context: nil, prompt_notes: [],
                    continues: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [],
                    toolkit: nil, toolkit_origin: "chosen", settings: nil, interrupted_turn: nil, parent_answers: nil, title: nil,
-                   working_set_pins: [], review: nil, verdicts: nil, verify_fresh: nil)
+                   working_set_pins: [], review: nil, verdicts: nil, verify_fresh: nil, extra_fields: {})
       @id = id
       @metadata_version = metadata_version
+      @written_by = written_by
       @mode = mode
       @model_name = model_name
       @model_typed = model_typed
@@ -399,12 +410,25 @@ module Samagotchi
       self.verdicts = verdicts
       self.verify_fresh = verify_fresh
       self.interrupted_turn = interrupted_turn
+      @extra_fields = extra_fields.to_h { |key, value| [key.to_s, value] }.freeze
       @turn_checkpoint = nil
       @archived = false
       # #save's lock: one snapshot-and-write at a time (see #save).
       @save_lock = Mutex.new
     end
 
+    # Whether a chi newer than this one saved the loaded file: its
+    # written_by is a later version, or it has keys this chi doesn't know
+    # (a hand-edited or future file). The worker logs it (newer_writer).
+    def newer_writer?
+      return true unless @extra_fields.empty?
+
+      # correct?(nil) is true (a 0 version): a file without the field is no newer.
+      return false unless @written_by.is_a?(String) && Gem::Version.correct?(@written_by)
+
+      Gem::Version.new(@written_by) > Gem::Version.new(VERSION)
+    end
+
     # A `delegate` child: its turns report to its parent (ChildReports). A
     # child saved before the field is known by the memory every delegate
     # starts with; a fork is neither.
@@ -543,8 +567,24 @@ module Samagotchi
     # the way (symbols in memory, strings on disk); last_turn, prompt_notes
     # and pending_question are value objects in memory (LastTurn,
     # PromptNote, PendingQuestion).
+    #
+    # A new field: a chi older than it (from the release after 0.130.0)
+    # keeps the key as it was (#extra_fields) but doesn't honour it, and the
+    # next newer chi reads it again. So it must be safe to come back
+    # unchanged after an older chi ran turns on the session: static data, or
+    # append-only data the older chi never appends to (review, verify_fresh,
+    # first_turn_id, verdicts); a cursor into messages, which an older chi
+    # would have moved, needs a check against what it points at. Only
+    # top-level keys are kept: the value objects (SessionReview,
+    # VerifyFreshOrigin, Toolkit, LastTurn, PendingQuestion, InterruptedTurn,
+    # PromptNote, WorkingSetPin, LLMContextOverride) write their own members
+    # only, so an older chi still drops a new sub-key of one of them; add a
+    # top-level field when an older chi must keep it. A removed key would
+    # stay an extra forever: leave it out of the extras in .from_h then (no
+    # key was ever removed).
     FIELDS = {
       "metadata_version" => 1,
+      "written_by" => nil,
       "id" => REQUIRED,
       "mode" => REQUIRED,
       "model_name" => REQUIRED,
@@ -599,6 +639,7 @@ module Samagotchi
       end
       attrs[:settings] = SessionConfig::Settings.new(core: attrs.delete(:config_settings), bundles: attrs.delete(:bundle_settings))
       attrs[:messages] = messages ? Array(attrs[:messages]).map { |msg| symbolize_message_keys(msg) } : []
+      attrs[:extra_fields] = data.reject { |key, _| FIELDS.key?(key) }
       new(**attrs)
     end
 
@@ -720,8 +761,10 @@ module Samagotchi
       self
     end
 
-    # The session as #save writes it (FIELDS, in their order); a running
-    # turn's checkpoint (#turn_checkpoint) in place of its messages.
+    # The session as #save writes it: FIELDS, in their order, then the keys
+    # this chi doesn't know (#extra_fields, in the file's order; a FIELDS key
+    # wins); a running turn's checkpoint (#turn_checkpoint) in place of its
+    # messages.
     def to_h
       checkpoint = checkpointed
       FIELDS.keys.to_h do |key|
@@ -730,6 +773,7 @@ module Samagotchi
                   (checkpoint ? checkpoint[:messages] : @messages).map { |msg| scrub_utf8(stringify_message_keys(msg)) }
                 when "interrupted_turn" then (checkpoint ? checkpoint[:marker] : @interrupted_turn)&.to_file
                 when "pending_question" then @pending_question && scrub_utf8(@pending_question.to_file)
+                when "written_by" then VERSION
                 when "test_run" then !!@test_run
                 when "delegate" then @delegate
                 when "llm_context" then llm_context_file
@@ -755,6 +799,7 @@ module Samagotchi
                 end
         [key, value]
       end.reject { |key, value| value.nil? && OPTIONAL_FIELDS.include?(key) }
+        .merge(@extra_fields.reject { |key, _| FIELDS.key?(key) })
     end
 
     # The running turn's checkpoint, while the turn runs (#turn_checkpoint).

data/lib/samagotchi/session_inbox.rb

@@ -289,6 +289,23 @@ module Samagotchi
         data["verify"].is_a?(Hash)
     end
 
+    # Whether a message waits that a running turn's next boundary merges and
+    # that a person (or chi send, or a delegating parent) sent: an unclaimed
+    # input file not held for the turn's end (#turn_end_data?), with a
+    # prompt, from a sender that may cut (Steer.cuts?). A running task_wait
+    # ends on it (Worker#input_waiting?). It only peeks: nothing is claimed;
+    # a file the drain or a dequeue claims meanwhile (ENOENT) or one that
+    # doesn't parse is skipped.
+    def self.steer_waiting?(session_dir)
+      find_new_input_files(session_dir).any? do |file|
+        data = JSON.parse(File.read(file))
+        data.is_a?(Hash) && !turn_end_data?(data) && !data["prompt"].to_s.strip.empty? &&
+          Steer.cuts?(Steer.source_for_client(data["client_id"]))
+      rescue JSON::ParserError, SystemCallError
+        false
+      end
+    end
+
     # How the unclaimed input file carrying +enqueued_id+ waits: :turn_end
     # (a queue or an image message: it runs as a turn of its own, never
     # merged, #waits_for_turn_end?), :merges (a running turn's drain may