samagotchi 0.128.0 → 0.130.0

data/lib/samagotchi/guardrails/path_resolve.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module Samagotchi
+  module Guardrails
+    # The guardrails' path primitives: how a path is expanded, resolved and
+    # compared, shared by every surface that judges one (ProtectedPaths,
+    # Outside, ShellPaths, RmTargets, ReviewPaths, PairCommand, Targets,
+    # ParentApprovals, System 1's SelfProtect). Each surface keeps its own
+    # predicate; this only says where a path lands and whether it is in a
+    # dir. docs/internals/tool-guardrails.md maps which surface uses which.
+    module PathResolve
+      # How many symlinks .real follows on a path that doesn't exist
+      # (about the kernel's own ELOOP limit).
+      MAX_LINKS = 40
+
+      # $HOME, ${HOME} and the XDG dirs at a word's start (.expand_word).
+      EXPANSION = /\A\$(?:\{(HOME|XDG_[A-Z_]+|TMPDIR)\}|(HOME|XDG_[A-Z_]+|TMPDIR)\b)/
+      # 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
+
+      # The tmp dirs besides Dir.tmpdir (.tmp_roots).
+      TMP_DIRS = %w[/tmp /var/tmp].freeze
+
+      # A dir's disk answer (.folds_case?), asked once per dir.
+      FOLDS = {}
+      FOLDS_MUTEX = Mutex.new
+
+      module_function
+
+      # +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 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 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
+
+      # +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 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 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 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 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 :climb, :existing_prefix_real
+
+      # Whether +path+ (resolved) is +root+ or in it, +root+ resolved
+      # either way (.reals).
+      def within?(path, root)
+        return false if root.nil? || root.to_s.empty?
+
+        reals(root.to_s.chomp("/")).any? { |dir| under?(path, dir) }
+      end
+
+      # Whether +path+ is +dir+ or in it (both absolute, resolved): by their
+      # text, or on a disk that folds case (macOS) by their text cased alike.
+      # realpath gives an existing part its on-disk case, but a missing
+      # tail keeps the case it was typed in (<state>/CONTEXT/x before
+      # <state>/context exists), and the kernel will create it in the
+      # folder that later answers to either. With +fold+ false, by their
+      # text alone.
+      def under?(path, dir, fold: true)
+        return true if path == dir || path.start_with?(File.join(dir, ""))
+        return false unless fold
+
+        low = path.downcase
+        low_dir = dir.downcase
+        (low == low_dir || low.start_with?(File.join(low_dir, ""))) && folds_case?(dir)
+      end
+
+      # Whether +path+ is in +dir+, not +dir+ itself (.under?'s terms).
+      def strictly_under?(path, dir, fold: true)
+        return true if path.start_with?(File.join(dir, ""))
+        return false unless fold
+
+        path.downcase.start_with?(File.join(dir.downcase, "")) && folds_case?(dir)
+      end
+
+      # The tmp dirs that exist (Dir.tmpdir, /tmp, /var/tmp), resolved; read
+      # each time (specs and a call's env: change TMPDIR). With +session+
+      # (a resolved session root) only those it isn't in, by their text
+      # (exact case): a session rooted in tmp gets no tmp dir of its own.
+      # @param roots [Array<String>, nil] the tmp dirs to filter (these by
+      #   default)
+      def tmp_roots(session: nil, roots: nil)
+        roots ||= [Dir.tmpdir, *TMP_DIRS].filter_map do |dir|
+          File.realpath(dir) if File.directory?(dir)
+        rescue SystemCallError
+          nil
+        end.uniq
+        session ? roots.reject { |tmp| under?(session, tmp, fold: false) } : roots
+      end
+
+      # A shell word with a leading ~, $HOME/${HOME}, an XDG dir or $TMPDIR
+      # expanded (+env+'s value, an unset XDG dir its default under +home+);
+      # nil when a $ or ~ is left. ShellPaths::Walk (cd and file words) and
+      # ShellGitDirs (git -C and the like) expand this way.
+      def expand_word(word, home:, env:)
+        word = expand_head(word, home: home, env: env)
+        return nil if word.include?("$") || word.start_with?("~")
+
+        word
+      end
+
+      # +word+ with its leading ~, $HOME/${HOME}, XDG dir or $TMPDIR
+      # expanded as .expand_word does, the rest kept as it is ($ and globs
+      # included); an unset variable without a default leaves a "$".
+      def expand_head(word, home:, env:)
+        word = word.sub(%r{\A~(?=/|\z)}) { home }
+        word.sub(EXPANSION) { variable(Regexp.last_match(1) || Regexp.last_match(2), home, env) || "$" }
+      end
+
+      def variable(name, home, env)
+        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
+      private_class_method :variable
+
+      # Whether the disk +path+'s deepest existing dir is on folds case: that
+      # dir (or the first one above it with a letter in its name) answers to
+      # its name with the case swapped. Asked once per dir. A relative or
+      # blank path has no disk to ask: false.
+      def folds_case?(path)
+        return false unless path.to_s.start_with?("/")
+
+        probe = path
+        probe = File.dirname(probe) until probe == "/" || File.directory?(probe)
+        probe = File.dirname(probe) until probe == "/" || File.basename(probe).swapcase != File.basename(probe)
+        return false if probe == "/"
+
+        FOLDS_MUTEX.synchronize do
+          FOLDS.fetch(probe) do
+            other = File.join(File.dirname(probe), File.basename(probe).swapcase)
+            FOLDS[probe] = File.exist?(other) && File.identical?(probe, other)
+          end
+        end
+      rescue SystemCallError
+        false
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/protected_paths.rb

@@ -1,10 +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).
+    # symlinks resolved (on the longest existing parent, `..` taken
+    # 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
@@ -41,40 +46,29 @@ module Samagotchi
         targets = verdict.targets
         return verdict unless targets && FILE_TOOLS.include?(targets.tool)
 
-        paths = targets.paths.map { |p| self.class.real(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+ with symlinks resolved on its longest existing parent.
-      def self.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
-
-      def self.within?(path, root)
-        return false if root.nil? || root.to_s.empty?
-
-        root = real(root.to_s.chomp("/"))
-        path == root || path.start_with?(File.join(root, ""))
-      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/read_only_shell.rb

@@ -2,6 +2,7 @@
 
 require "strscan"
 require_relative "shell_lex"
+require_relative "shell_paths"
 
 module Samagotchi
   module Guardrails
@@ -17,6 +18,17 @@ module Samagotchi
     # $HOME / the XDG dirs / $TMPDIR / $PWD at a word's start, a brace
     # expansion, a < or << redirection, a path to a verb (/bin/ls), and
     # less/more/vim (they run commands) are all not read-only.
+    #
+    # .read_only_but_writes? (the child boundary's) also lets through the
+    # writes it can name: a > or >> target, cp's destination and tee's
+    # files, each resolved against the dir the command is in by then
+    # (ShellPaths::Walk) and accepted by the caller's block. It trusts
+    # Walk's dir only where the shell's can't differ: a cd or pushd takes
+    # one existing dir, spelt /…, . or .. (no option, +N, -, $, ~ or
+    # CDPATH name), and joins beside it are && only (a failed or skipped
+    # cd can't be followed by a command that still runs); popd is never
+    # accepted, nor is a $ or ~ in a write's target (the call's env may
+    # set it).
     module ReadOnlyShell
       # Operators that join read-only commands (no &, no ;;).
       JOINS = ["&&", "||", ";", "|", "|&", "\n", "(", ")"].freeze
@@ -29,6 +41,49 @@ module Samagotchi
       # target follows).
       NULL_REDIRECT = %r{\A\d*>>?/dev/null\z}
       BARE_REDIRECT = /\A\d*>>?\z/
+      # A redirection with its target in the same word (>out, 2>>out); not
+      # >&file (it is &> spelt the other way).
+      REDIRECT_TO = /\A\d*>>?([^&>].*)\z/m
+      # Pipe operators: each side runs in a subshell.
+      PIPES = ["|", "|&"].freeze
+      # Verbs that change the dir ShellPaths::Walk follows.
+      DIR_VERBS = %w[cd pushd popd].freeze
+      # The joins a group (or the whole command) holding a cd or pushd may
+      # use in write mode: after any other a command can run in a dir the
+      # cd didn't reach (cd failed, or was skipped by ||).
+      DIR_JOINS = ["&&", "|", "|&"].freeze
+      # A dir verb's operand the shell resolves as Walk does: absolute, or
+      # ./ ../ (CDPATH is not searched for these).
+      DIR_OPERAND = %r{\A(?:/|\.\.?(?:/|\z))}
+
+      # The write side of .read_only_but_writes?: the Walk that follows the
+      # command's dir and the caller's test for an absolute path it writes.
+      Writes = Data.define(:walk, :writable) do
+        # +word+ as absolute paths against the current dir (ShellPaths::Walk:
+        # its lexical one, and its physical one when they differ, last); []
+        # when it can't be resolved, or has a $ or ~ (the shell may expand
+        # them from an env Walk doesn't see, as task_create's env: sets).
+        def paths(word) = word.include?("$") || word.start_with?("~") ? [] : walk.paths(word)
+
+        # Whether a cd or pushd with +args+ lands where Walk says: one
+        # operand (DIR_OPERAND) naming an existing dir every way it
+        # resolves. popd never does.
+        def dir_step?(verb, args)
+          return false unless verb != "popd" && args.size == 1 && args.first.match?(DIR_OPERAND)
+
+          dirs = paths(args.first)
+          !dirs.empty? && dirs.all? { |dir| File.directory?(dir) }
+        end
+
+        def ok?(path) = path ? writable.call(path) == true : false
+
+        # Whether +word+ names a file the command may write, every way it
+        # resolves.
+        def file?(word)
+          paths = paths(word)
+          !paths.empty? && paths.all? { |path| ok?(path) }
+        end
+      end
 
       # Verbs that only read whatever their options: → nil. The others
       # check their arguments.
@@ -49,29 +104,104 @@ module Samagotchi
         false
       end
 
+      # Whether the command only reads but for writes whose resolved paths
+      # the block accepts: > and >> targets, cp's destination (and the
+      # files it makes in it) and tee's files. Paths resolve against +cwd+
+      # and the dir an earlier cd, pushd or popd moved to; a cd beside a pipe
+      # (a subshell's) isn't one Walk can follow, so it is not.
+      # @param command [String, nil]
+      # @param cwd [String, nil] where the command starts
+      # @yieldparam path [String] an absolute path, symlinks not resolved
+      # @return [Boolean]
+      def read_only_but_writes?(command, cwd:, home: Dir.home, env: ENV, &writable)
+        text = command.to_s
+        return false if text.strip.empty?
+
+        tokens = ShellLex.lex(text)
+        commands = split(tokens, marks: true) or return false
+        return false if commands.none?(Array) || !dir_joins_ok?(tokens)
+
+        writes = Writes.new(walk: ShellPaths::Walk.new(cwd, home, env), writable: writable)
+        commands.all? { |words| words.is_a?(Symbol) ? writes.walk.step(words) : simple_read_only?(words, writes) }
+      rescue ArgumentError, EncodingError
+        false
+      end
+
       # The simple commands as [text, specials] word lists; nil when an
-      # operator isn't one read-only commands may be joined with.
-      def split(tokens)
+      # operator isn't one read-only commands may be joined with. With
+      # +marks+, ( and ) stay as :open / :close, and a cd, pushd or popd
+      # beside a pipe is nil.
+      def split(tokens, marks: false)
         commands = [[]]
+        piped = false
         tokens.each do |kind, value, specials|
           if kind == :op
             return nil unless JOINS.include?(value)
 
+            pipe = PIPES.include?(value)
+            return nil if marks && (piped || pipe) && dir_verb?(commands.last)
+
+            piped = pipe
+            commands << (value == "(" ? :open : :close) if marks && ["(", ")"].include?(value)
             commands << []
           else
             commands.last << [value, specials]
           end
         end
-        commands.reject(&:empty?)
+        return nil if marks && piped && dir_verb?(commands.last)
+
+        commands.reject { |words| words.is_a?(Array) && words.empty? }
+      end
+
+      def dir_verb?(words) = words.is_a?(Array) && DIR_VERBS.include?(verb_of(words))
+
+      # Whether each group holding a dir verb itself (the whole command,
+      # or a ( … ): nested ones are their own) joins with DIR_JOINS only.
+      def dir_joins_ok?(tokens)
+        scopes = [[false, false]] # [holds a dir verb, has another join]
+        words = []
+        tokens.each do |kind, value, specials|
+          next words << [value, specials] unless kind == :op
+
+          scopes.last[0] ||= dir_verb?(words)
+          words = []
+          case value
+          when "(" then scopes << [false, false]
+          when ")"
+            dir, other = scopes.pop
+            return false if scopes.empty? || (dir && other)
+          else scopes.last[1] ||= !DIR_JOINS.include?(value)
+          end
+        end
+        scopes.last[0] ||= dir_verb?(words)
+        scopes.none? { |dir, other| dir && other }
       end
 
-      def simple_read_only?(words)
+      # The first word that is no redirection or its target.
+      def verb_of(words)
+        target = false
+        words.each do |text, specials|
+          if target then target = false
+          elsif specials.include?(">") then target = text.match?(BARE_REDIRECT)
+          else return text
+          end
+        end
+        nil
+      end
+
+      # With +writes+ (.read_only_but_writes?) its redirections may write
+      # what it accepts, cp and tee count, and the walk takes the command.
+      def simple_read_only?(words, writes = nil)
         return false if words.any? { |text, specials| text.include?(ShellLex::SUBST) || !expansion_ok?(text, specials) }
 
-        args = strip_redirects(words) or return false
+        args = strip_redirects(words, writes) or return false
+        return false if writes && DIR_VERBS.include?(args.first) && !writes.dir_step?(args.first, args.drop(1))
+
+        writes&.walk&.step(args)
         verb = args.shift
         return false unless verb&.match?(/\A[a-z][\w.-]*\z/)
         return true if PLAIN.include?(verb)
+        return WRITE_CHECKS[verb].call(args, writes) if writes && WRITE_CHECKS[verb]
 
         check = CHECKS[verb] or return false
         check.call(args)
@@ -85,19 +215,20 @@ module Samagotchi
       end
 
       # The words with their redirections taken out; nil when one isn't an
-      # fd dup or to /dev/null.
-      def strip_redirects(words)
+      # fd dup, to /dev/null, or (with +writes+) to a file it accepts.
+      def strip_redirects(words, writes = nil)
         out = []
         pending = false
         words.each do |text, specials|
           if pending
-            return nil unless text == "/dev/null"
+            return nil unless text == "/dev/null" || (writes && specials.delete("$").empty? && writes.file?(text))
 
             pending = false
           elsif specials.include?("<")
             return nil
           elsif specials.include?(">")
             next if text.match?(FD_DUP) || text.match?(NULL_REDIRECT)
+            next if writes && (m = text.match(REDIRECT_TO)) && !m[1].match?(/[<>]/) && writes.file?(m[1])
             return nil unless text.match?(BARE_REDIRECT)
 
             pending = true
@@ -272,6 +403,58 @@ module Samagotchi
         names.zero? || options.any? { |a| GIT_BRANCH_LISTING.any? { |listing| a == listing || a.start_with?("#{listing}=") } }
       end
 
+      CP_SHORT = "afinpvrRPLHxT"
+      CP_LONG = %w[--archive --force --interactive --no-clobber --recursive --verbose --dereference
+                   --no-dereference --one-file-system --no-target-directory].freeze
+      CP_PRESERVE = /\A--(?:no-)?preserve(?:=[\w,]+)?\z/
+
+      # cp whose destination (the last argument, or -t / --target-directory)
+      # and the files it makes in it, when it is a dir, the caller accepts.
+      # Only options that copy: no -l/-s (links into the source), --parents
+      # or --backup; anything unknown is not.
+      def cp(args, writes)
+        target = nil
+        no_target = false
+        positional = []
+        rest = args.dup
+        until rest.empty?
+          arg = rest.shift
+          if !arg.start_with?("-") || arg == "-" then positional << arg
+          elsif arg == "--" then positional.concat(rest.shift(rest.size))
+          elsif (m = arg.match(/\A-([#{CP_SHORT}]*)t(.*)\z/m))
+            no_target ||= m[1].include?("T")
+            target = m[2].empty? ? rest.shift : m[2]
+            return false unless target
+          elsif arg == "--target-directory" then target = rest.shift or return false
+          elsif (m = arg.match(/\A--target-directory=(.+)\z/m)) then target = m[1]
+          elsif arg.match?(/\A-[#{CP_SHORT}]+\z/) then no_target ||= arg.include?("T")
+          elsif CP_LONG.include?(arg) || arg.match?(CP_PRESERVE) then no_target ||= arg == "--no-target-directory"
+          else return false
+          end
+        end
+        into = !target.nil?
+        target ||= positional.pop
+        return false if positional.empty? || (into && no_target)
+
+        dests = writes.paths(target)
+        return false if dests.empty?
+
+        into ||= !no_target && File.directory?(dests.last)
+        made = into ? dests.product(positional).map { |dest, src| File.join(dest, File.basename(src)) } : []
+        [*dests, *made].all? { |path| writes.ok?(path) }
+      end
+
+      TEE_OPTIONS = %w[-a --append -i --ignore-interrupts -p].freeze
+
+      # tee whose every file the caller accepts.
+      def tee(args, writes)
+        files = args.reject { |arg| TEE_OPTIONS.include?(arg) }
+        files.all? { |file| !file.start_with?("-") && writes.file?(file) }
+      end
+
+      # The verbs that write, for .read_only_but_writes? only: → (args, writes).
+      WRITE_CHECKS = { "cp" => method(:cp), "tee" => method(:tee) }.freeze
+
       CHECKS = {
         "rg" => method(:rg), "find" => method(:find), "tree" => method(:tree), "file" => method(:file),
         "sort" => method(:sort), "uniq" => method(:uniq), "sed" => method(:sed), "awk" => method(:awk),

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"
 
@@ -10,9 +11,11 @@ module Samagotchi
     # under the session's project root that isn't on the read denylist
     # (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). 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.
+    # project to ~/.ssh is ~/.ssh; a `..` after a symlinked dir climbs out
+    # 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.
     class ReviewPaths
       # Home folders that hold keys and tokens, never read in a review turn
       # (nor read or written in a pair turn).
@@ -43,8 +46,20 @@ 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
+      # review turn reads nothing there (#refusal: HOME_ROOT); a pair turn
+      # asks the owner before every write (PairBoundary).
+      # @param root [String] @param home [String, nil]
+      def self.home_root?(root, home)
+        return false if home.to_s.empty? || root.to_s.empty?
+
+        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
       #   top of its folder); nil or blank refuses every path
@@ -66,14 +81,15 @@ module Samagotchi
       def refusal(paths)
         return OUTSIDE if paths.empty? || @root.empty?
 
-        real_root = ProtectedPaths.real(@root)
-        return HOME_ROOT if !@home.empty? && ShellPaths.within?(ProtectedPaths.real(@home), real_root)
+        return HOME_ROOT if ReviewPaths.home_root?(@root, @home)
+
+        real_root = PathResolve.real(@root)
 
         paths.each do |path|
           given = File.expand_path(path)
-          real = ProtectedPaths.real(given)
-          return OUTSIDE unless ShellPaths.within?(real, real_root)
-          return SECRET if secret?(given) || secret?(real)
+          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
       end
@@ -86,7 +102,7 @@ module Samagotchi
       def secret_refusal(paths)
         paths.each do |path|
           given = File.expand_path(path)
-          return SECRET if secret?(given) || secret?(ProtectedPaths.real(given))
+          return SECRET if secret?(given) || PathResolve.reals(path).any? { |real| secret?(real) }
         end
         nil
       end
@@ -99,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) }