samagotchi 0.129.0 → 0.130.0

data/lib/samagotchi/guardrails/protected_paths.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "path_resolve"
+
 module Samagotchi
   module Guardrails
     # Core checks on what the file tools (write, edit, memory_write) touch,
     # after the hooks and before the rules. Paths are compared with
     # symlinks resolved (on the longest existing parent, `..` taken
-    # physically, a dangling symlink followed: .reals, the lexical answer
-    # and where the write lands, a vote when either is protected).
+    # physically, a dangling symlink followed: PathResolve.reals, the
+    # lexical answer and where the write lands, a vote when either is
+    # protected).
     #   deny: the approval store's dir, installed bundles (.bundles/:
     #         hooks, rules, manifests) and attached context (a source's
     #         command runs later, outside the gate; chi context writes
@@ -43,131 +46,29 @@ module Samagotchi
         targets = verdict.targets
         return verdict unless targets && FILE_TOOLS.include?(targets.tool)
 
-        paths = targets.paths.flat_map { |p| self.class.reals(p) }
+        paths = targets.paths.flat_map { |p| PathResolve.reals(p) }
         @deny.each do |rule, root, reason|
-          next unless paths.any? { |p| self.class.within?(p, root) }
+          next unless paths.any? { |p| PathResolve.within?(p, root) }
 
           verdict.deny!(reason, rule: rule, source: SOURCE, decided_by: "core")
         end
         @ask.each do |rule, root, reason|
-          next unless paths.any? { |p| self.class.within?(p, root) }
+          next unless paths.any? { |p| PathResolve.within?(p, root) }
 
           verdict.ask!(reason, scopes: %w[once session], rule: rule, source: SOURCE, decided_by: "core")
         end
         verdict
       end
 
-      # +path+ as an absolute path the way the kernel opens it: ~ expanded,
-      # relative to +base+, and each `..` taken from where the dir before it
-      # really is (a `..` after a symlinked dir climbs out of its target,
-      # not back to the link's parent as File.expand_path has it). It
-      # differs from File.expand_path only for such a climb; the parts
-      # after the last `..` are kept as given (symlinks not resolved).
-      # A shell's cd may land at either (ShellPaths::Walk keeps both); a file
-      # argument and a tool's path go through this.
-      # @param path [String]
-      # @param base [String, nil] for a relative path (Dir.pwd when nil)
-      def self.expand(path, base = nil)
-        path = path.to_s
-        head, sep, tail = path.partition("/")
-        path = "#{File.expand_path(head)}#{sep}#{tail}" if head.start_with?("~")
-        path = File.join(File.expand_path(base || Dir.pwd), path) unless path.start_with?("/")
-        parts = []
-        path.split("/").each do |part|
-          next if part.empty? || part == "."
-
-          part == ".." ? parts = climb(parts) : parts << part
-        end
-        "/#{parts.join("/")}"
-      end
-
-      # The parts of +parts+'s parent dir: the lexical one unless the dir
-      # is (or goes through) a symlink whose target's parent is elsewhere.
-      def self.climb(parts)
-        lexical = parts[0...-1]
-        dir = "/#{parts.join("/")}"
-        return lexical unless parts.any? && File.directory?(dir)
-
-        physical = File.dirname(File.realpath(dir))
-        return lexical if File.realpath("/#{lexical.join("/")}") == physical
-
-        physical.split("/").reject(&:empty?)
-      rescue SystemCallError
-        lexical
-      end
-      private_class_method :climb
-
-      # How many symlinks .real follows on a path that doesn't exist
-      # (about the kernel's own ELOOP limit).
-      MAX_LINKS = 40
-
-      # +path+ (.expand) with symlinks resolved on its longest existing
-      # parent: where the kernel lands for it. A part that is a dangling
-      # symlink is followed to its target (a write there creates the
-      # target), up to MAX_LINKS times; the missing tail is kept as given.
-      def self.real(path)
-        path = expand(path)
-        MAX_LINKS.times do
-          resolved = existing_prefix_real(path)
-          return resolved unless resolved.is_a?(Array)
-
-          path = resolved.first
-        end
-        path
-      rescue SystemCallError
-        path
-      end
-
-      # The old, lexical answer: File.expand_path (lexical `..`), then
-      # realpath of the longest existing prefix, stopping at a dangling
-      # symlink. .reals keeps it beside .real.
-      def self.lexical_real(path)
-        path = File.expand_path(path)
-        rest = []
-        current = path
-        until File.exist?(current) || current == File.dirname(current)
-          rest.unshift(File.basename(current))
-          current = File.dirname(current)
-        end
-        File.join(File.realpath(current), *rest)
-      rescue SystemCallError
-        path
-      end
-
-      # Every place +path+ may be judged as: .lexical_real (what these
-      # checks always looked at) and .real (where the kernel lands), one
-      # entry when they agree. A check that holds for any of them (a
-      # protected dir, a secret) or refuses unless all of them are inside
-      # (the project, tmp) refuses at least what it did with the lexical
-      # answer alone.
-      # @return [Array<String>]
-      def self.reals(path) = [lexical_real(path), real(path)].uniq
-
-      # realpath of +path+'s longest existing prefix with the rest
-      # appended (a String), or [the path with the first dangling symlink
-      # on the way replaced by its target] to resolve again.
-      def self.existing_prefix_real(path)
-        rest = []
-        current = path
-        until File.exist?(current) || current == File.dirname(current)
-          if File.symlink?(current)
-            target = expand(File.readlink(current), File.dirname(current))
-            return [expand(File.join(target, *rest))]
-          end
-          rest.unshift(File.basename(current))
-          current = File.dirname(current)
-        end
-        File.join(File.realpath(current), *rest)
-      end
-      private_class_method :existing_prefix_real
-
-      # Whether +path+ (resolved) is +root+ or in it, +root+ resolved
-      # either way (.reals).
-      def self.within?(path, root)
-        return false if root.nil? || root.to_s.empty?
-
-        reals(root.to_s.chomp("/")).any? { |dir| path == dir || path.start_with?(File.join(dir, "")) }
-      end
+      # The path primitives (PathResolve) as this class has long named
+      # them; specs and older callers reach them here.
+      def self.expand(path, base = nil) = PathResolve.expand(path, base)
+      def self.real(path) = PathResolve.real(path)
+      def self.lexical_real(path) = PathResolve.lexical_real(path)
+      def self.reals(path) = PathResolve.reals(path)
+      def self.within?(path, root) = PathResolve.within?(path, root)
+      def self.under?(path, dir) = PathResolve.under?(path, dir)
+      def self.folds_case?(path) = PathResolve.folds_case?(path)
     end
   end
 end

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 ||= PathResolve.real(base)
+              forms += PathResolve.reals(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.
@@ -386,8 +384,8 @@ module Samagotchi
       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 +433,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