samagotchi 0.16.0 → 0.18.0

data/lib/samagotchi/engine.rb

@@ -6,6 +6,7 @@ require "securerandom"
 require "time"
 require "yaml"
 
+require_relative "iteration_limit"
 require_relative "config"
 require_relative "context_note"
 require_relative "context_status"
@@ -27,6 +28,7 @@ require_relative "llm/backend"
 require_relative "llm/openai_chat"
 require_relative "llm/turn_settings"
 require_relative "session"
+require_relative "answer_tail"
 require_relative "archive_store"
 require_relative "session_observer"
 require_relative "tool_declarations"
@@ -83,7 +85,7 @@ module Samagotchi
     # @param profile            [ModelProfile, Symbol, String, nil]
     # @param session_id         [String, nil] resume an existing session
     # @param no_interrupt       [Boolean] --no-interrupt: every turn runs with
-    #   NO_INTERRUPT_MAX_ITERATIONS, whichever loop runs it
+    #   IterationLimit.for(no_interrupt: true), whichever loop runs it
     # @param model_name         [String, nil] defaults from SAMAGOTCHI_DEFAULT_MODEL
     # @param model_typed        [String, nil] the name the model was given as (a session's
     #   model_typed: an alias), for the models: lookup; model_name by default
@@ -92,10 +94,6 @@ module Samagotchi
     #   prompt's index, dropped from the preloads, refused by memory_read); a mute wins over a preload
     # What memory_write answers in a scratch session.
     SCRATCH_MEMORY_WRITE = "Error: scratch session: nothing is saved"
-    # A turn's iteration limit with no_interrupt (the worker's own
-    # --no-interrupt turns pass the same).
-    NO_INTERRUPT_MAX_ITERATIONS = 1000
-
     # @param plugins            [Boolean] false: load no bundle plugins (a throwaway Engine for a prompt)
     # @param scratch            [Boolean] a `chi scratch` session: memory writes are refused, and there is no
     #   delegate (a child would outlive it) nor plugin fork
@@ -243,7 +241,7 @@ module Samagotchi
       Log.debug(:model, "backend", provider: backend.provider) if Log.level?(:debug)
       @resume_session = session_id ? Session.load(session_id) : nil
       @prompt_builder = SystemPrompt.new(profile: -> { self.profile }, tools: -> { @tools }, session: -> { @session },
-                                         thinking: -> { turn_thinking }, memories: memories,
+                                         thinking: -> { turn_thinking }, model: -> { model_identity }, memories: memories,
                                          muted_memory_names: @muted_memory_names)
       @session = nil
       @session_observer = SessionObserver.new
@@ -411,6 +409,18 @@ module Samagotchi
       model_ref_for(@effective_model_name)
     end
 
+    # The effective model as the system prompt names it (SystemPrompt::ModelIdentity):
+    # the ref, its host, the overlay key and, for a local llama.cpp host
+    # only, the model its /props names when that differs. Never a new
+    # request: only the /props answer profile resolution already cached.
+    def model_identity
+      target = @host_registry.resolve(@effective_model_name)
+      entry = target.entry
+      host = entry && "host #{entry.name}, #{entry.url || "#{entry.host}:#{entry.port}"}"
+      SystemPrompt::ModelIdentity.new(ref: effective_model_ref, host: host, key: @model_key,
+                                      served: prompt_served_model(target), fallback_key: @fallback_model_key)
+    end
+
     # +name+'s resolved ref (ModelRef#ref).
     def model_ref_for(name)
       @host_registry.model_ref(name).ref
@@ -463,8 +473,8 @@ module Samagotchi
     def sync_model_key!
       @model_key = ModelOverlay.key_for(bare_model_name(@effective_model_name))
       typed_key = ModelOverlay.key_for(@host_registry.parse_qualified_model(@typed_model_name).last)
-      fallback = typed_key == @model_key ? nil : typed_key
-      @kernel.sync_model_key!(@model_key, fallback: fallback)
+      @fallback_model_key = typed_key == @model_key ? nil : typed_key
+      @kernel.sync_model_key!(@model_key, fallback: @fallback_model_key)
     end
     private :sync_model_key!
 
@@ -904,7 +914,7 @@ module Samagotchi
     # else [nil, nil].
     # @return [Array(String, String), Array(nil, nil)]
     def served_model(probe: true)
-      served_model_for(@metrics.snapshot, target: probe ? @host_registry.resolve(@effective_model_name) : nil)
+      served_model_for(@metrics.served_report, target: probe ? @host_registry.resolve(@effective_model_name) : nil)
     end
 
     # Read-only snapshot of the engine's view of the current session plus the
@@ -1069,7 +1079,10 @@ module Samagotchi
 
     # How the turn ended, on the session (Session#last_turn): the caller's
     # save puts it in the file the session hub watches.
-    def record_last_turn(session, outcome, seconds, origin)
+    # @param limit [Integer, nil] the turn ran out of iterations at this
+    #   limit: "exhausted" => true, "limit" => N, so a wait with nobody to
+    #   answer the continue offer says so (ReplyWait, ParentReport "limit")
+    def record_last_turn(session, outcome, seconds, origin, limit: nil)
       client_id = origin.is_a?(Hash) ? origin[:client_id].to_s : ""
       source = if client_id.start_with?("#{Tools::Delegate::CLIENT_PREFIX}:") then "delegate"
                elsif client_id == SessionManager::REMINDER_CLIENT_ID then "reminder"
@@ -1077,6 +1090,7 @@ module Samagotchi
                end
       session.last_turn = { "outcome" => outcome, "ended_at" => Time.now.iso8601(3),
                             "seconds" => seconds.round(1), "origin" => source }
+      session.last_turn.merge!("exhausted" => true, "limit" => limit) if limit
     end
     private :record_last_turn
 
@@ -1089,14 +1103,15 @@ module Samagotchi
     # returns [the messages to keep (nil: leave the session's), the end
     # event]. +save:+ also saves the session (a failed turn: a worker exits
     # after it). The disk writes come after the step: every emitter waits
-    # for the event lock.
-    def end_turn(turn, outcome, save: false)
+    # for the event lock. +exhausted:+ the turn ran out of iterations
+    # (its limit goes in last_turn).
+    def end_turn(turn, outcome, save: false, exhausted: false)
       seconds = turn.elapsed
       synchronize_events do
         kept, event = yield(seconds)
         replace_session_messages(turn.session, kept) if kept
         turn.session.status = Session::STATUS_IDLE
-        record_last_turn(turn.session, outcome, seconds, turn.origin)
+        record_last_turn(turn.session, outcome, seconds, turn.origin, limit: exhausted ? turn.limit : nil)
         emit_event(turn.on_event, turn.tag(event))
       end
       turn.ended = true
@@ -1242,6 +1257,19 @@ module Samagotchi
       @question_desk.open_question({ **fields.to_h, **more }, watch: watch)
     end
 
+    # Publish a standing question that blocks nobody (QuestionDesk#post: a
+    # worker's step-limit question).
+    # @return [Hash, nil] the pending question, nil while another is open
+    def post_question(fields, on_answer:, on_superseded_close: nil)
+      @question_desk.post(fields, on_answer: on_answer, on_superseded_close: on_superseded_close)
+    end
+
+    # Withdraw the standing question (QuestionDesk#withdraw).
+    # @return [Boolean]
+    def withdraw_question(reason, id: nil)
+      @question_desk.withdraw(reason, id: id)
+    end
+
     # Answer the pending question (called from UI thread; QuestionDesk#answer).
     # @return [Hash] normalized answer
     def answer_question(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
@@ -1262,6 +1290,7 @@ module Samagotchi
 
     # Cancel the pending question (QuestionDesk#cancel).
     # @return [Boolean] whether it was cancelled
+    # @raise [QuestionDesk::NotDismissable] +id+ names a standing question
     def cancel_question(reason = "user", id: nil)
       @question_desk.cancel(reason, id: id)
     end
@@ -1307,6 +1336,7 @@ module Samagotchi
       def state_dir = engine.peer_state_dir
       def cancelled? = !!engine.active_cancel_controller&.cancelled?
       def relay = engine.relay_peer
+      def model_ref = engine.effective_model_ref
     end
 
     # What the approval relay needs from the parent's Engine (Peers#relay):
@@ -1401,8 +1431,9 @@ module Samagotchi
     # set on the kernel in #generate.
     # +id+: names the turn on :turn_started (its metrics record's id) and on
     # its saved prompt, so a UI pairs the two whatever left the conversation.
+    # +limit+: the iteration limit #generate ran it with.
     Turn = Struct.new(:session, :prompt, :continue, :on_event, :controller, :origin, :started_at, :messages, :ended,
-                      :settings, :id) do
+                      :settings, :id, :limit) do
       # The turn's boundary events carry the origin only when there is one,
       # so payloads stay unchanged for callers that don't pass it.
       def tag(event) = origin ? event.merge(origin: origin) : event
@@ -1420,7 +1451,7 @@ module Samagotchi
     # @param session  [Session] the session to operate on
     # @param prompt   [String] user input
     # @param on_event [Proc, nil] receives event hashes
-    # @param max_iterations [Integer] max kernel iterations
+    # @param max_iterations [Integer, nil] max kernel iterations (nil: IterationLimit.for)
     # @param cancel_controller [CancellationController, nil]
     # @param max_tool_output_chars [Integer, nil] per-output char cap for the
     #   :tool_call_completed event's `output:` (nil → max_tool_output_chars)
@@ -1449,7 +1480,7 @@ module Samagotchi
     # other error (e.g. an LLM::ProviderError) emits :turn_failed and
     # re-raises; a provider error adds error_kind:, retryable:, host: and a
     # one-line summary:.
-    def run_turn(session, prompt, on_event: nil, max_iterations: 100, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
+    def run_turn(session, prompt, on_event: nil, max_iterations: nil, cancel_controller: nil, max_tool_output_chars: nil, pending_input: nil, continue: false, origin: nil,
                  images: [])
       turn = begin_turn(session, prompt, on_event: on_event, cancel_controller: cancel_controller, origin: origin,
                                          continue: continue)
@@ -1653,9 +1684,10 @@ module Samagotchi
       # turn's model, not the last native one.
       @kernel.turn_settings = turn.settings.with(model_name: bare_for_backend, window_setting: turn_window_setting)
 
+      turn.limit = @no_interrupt ? IterationLimit.for(no_interrupt: true) : max_iterations || IterationLimit.for
       backend.complete(
         messages: turn.messages,
-        max_iterations: @no_interrupt ? NO_INTERRUPT_MAX_ITERATIONS : max_iterations,
+        max_iterations: turn.limit,
         on_stream_event: build_stream_event_handler(turn.on_event, cancel_controller: turn.controller),
         cancel_controller: turn.controller,
         model_name: bare_for_backend,
@@ -1692,7 +1724,7 @@ module Samagotchi
       # after_turn hooks run below and may present the answer (the web
       # holds its pop until it knows).
       display_pending = !canceled && @hooks.any?(:after_turn)
-      end_turn(turn, canceled ? "canceled" : "completed") do |seconds|
+      end_turn(turn, canceled ? "canceled" : "completed", exhausted: !canceled && result.exhausted?) do |seconds|
         kept = kept_messages(turn, result, seconds)
         if canceled
           [kept, { type: :turn_canceled, cancellation_reason: result.cancellation_reason,
@@ -1955,6 +1987,15 @@ module Samagotchi
     # rollback after Ctrl-C). Each replaces the array rather than mutating it,
     # so the recap's lock-free snapshot never sees a half-applied edit.
 
+    # The answer a UI shows last (AnswerTail), a copy of that one message
+    # only: walked back from the end, never a #messages_checkpoint of the
+    # whole conversation (the Bridge's GET tail). +turn_id+: that turn's
+    # answer (AnswerTail.find); unknown or nil: the newest.
+    # @return [Hash, nil]
+    def last_answer_message(turn_id: nil)
+      AnswerTail.find(@session&.messages, turn_id: turn_id)&.dup
+    end
+
     # @return [Array<Hash>] a copy of the current session's messages to hand
     #   back to #rollback_to later
     def messages_checkpoint
@@ -2125,7 +2166,8 @@ module Samagotchi
         ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
           ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller)
         },
-        model_name: -> { @session&.model_name || @effective_model_name },
+        model_name: -> { effective_model_ref },
+        model_key: -> { @model_key },
         state_dir: -> { session_state_dir },
         scratch: -> { @scratch }
       )
@@ -2320,6 +2362,18 @@ module Samagotchi
       [nil, nil]
     end
 
+    # What a local native host's cached /props names, when it isn't the
+    # model asked for; nil for a chat or remote host, or before any probe.
+    def prompt_served_model(target)
+      entry = target.entry
+      return nil if entry.nil? || entry.chat? || entry.remote? || !target.client.respond_to?(:cached_server_props)
+
+      served = ServedModel.from_props(target.client.cached_server_props(model: target.bare_model))
+      served if ServedModel.differs?(target.bare_model, served)
+    rescue StandardError
+      nil
+    end
+
     # ── Prompt profile ─────────────────────────────────────────────────────────
 
     def resolve_profile

data/lib/samagotchi/guardrails/outside.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "protected_paths"
+require_relative "../memory_bundle/index_sync"
+
+module Samagotchi
+  module Guardrails
+    # What `outside_repo` means (a rule's path: and git:): a path is outside
+    # when it isn't in the session's repo root (the cwd outside a repo),
+    # with symlinks resolved on both sides. Never outside:
+    # - a memory's file (MemoryBundle::IndexSync.memory_scope): write/edit
+    #   there is what memory_write does; index.md, the bundles dir and the
+    #   rest of chi's config dir still count;
+    # - a tmp dir (Dir.tmpdir, /tmp, /var/tmp), unless the session's root
+    #   is itself in that tmp dir (a sandbox there still gets the check
+    #   between its siblings).
+    # chi's state dir is not special: nothing there is the model's to write.
+    module Outside
+      TMP_DIRS = %w[/tmp /var/tmp].freeze
+
+      # @param path [String] absolute
+      # @param root [String] the session's repo root (or cwd)
+      def self.outside?(path, root:)
+        real = ProtectedPaths.real(path)
+        session = ProtectedPaths.real(root)
+        return false if within?(real, session)
+        return false if MemoryBundle::IndexSync.memory_scope(path)
+        return false if tmp_roots.any? { |tmp| within?(real, tmp) && !within?(session, tmp) }
+
+        true
+      end
+
+      # The tmp dirs that exist, resolved.
+      def self.tmp_roots
+        [Dir.tmpdir, *TMP_DIRS].filter_map do |dir|
+          File.realpath(dir) if File.directory?(dir)
+        rescue SystemCallError
+          nil
+        end.uniq
+      end
+
+      def self.within?(path, root) = path == root || path.start_with?(File.join(root, ""))
+    end
+  end
+end

data/lib/samagotchi/guardrails/parent_approvals.rb

@@ -5,6 +5,7 @@ require_relative "../paths"
 require_relative "../hooks/loader"
 require_relative "approval"
 require_relative "protected_paths"
+require_relative "parent_continue"
 
 module Samagotchi
   module Guardrails
@@ -115,6 +116,7 @@ module Samagotchi
       def message(reason, typed: false)
         deny = typed ? "deny it (n; WHY), and tell your user" : "deny it (--option Deny --text WHY), and tell your user"
         case reason
+        when :stop_only then ParentContinue.message
         when :protected then "this call changes chi's own config, hooks or guardrails, and only the user can allow it: #{deny}"
         when :off then "allowing a tool call is up to the user: #{deny}"
         else "only Allow once (#{KEY}: once) can be given here: #{deny}"

data/lib/samagotchi/guardrails/parent_continue.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "../config"
+
+module Samagotchi
+  module Guardrails
+    # Whether a parent agent may answer Continue to a session's step-limit
+    # question (kind "continue", ContinueOffer): turn.parent_continue,
+    # config.yml only, default true. Continue grants no permission (every
+    # tool call still meets the guardrails), it spends time and tokens;
+    # false makes parents stop-only. Checked by `chi answer` before it posts
+    # and by the worker's question desk for an answer marked as chi
+    # answer's, the way ParentApprovals is.
+    module ParentContinue
+      KEY = "turn.parent_continue"
+      KIND = "continue"
+      CONTINUE = "Continue"
+
+      module_function
+
+      # @return [Boolean] this process's setting
+      def allowed?
+        Config.get(KEY) != false
+      end
+
+      # Why a parent may not give this answer, or nil.
+      # @param pending [Hash] the pending question (symbol or string keys)
+      # @param selected [Array<String>] the selected labels
+      # @return [Symbol, nil] :stop_only
+      def refusal(pending, selected, allowed: allowed?)
+        return nil if allowed
+        return nil unless (pending[:kind] || pending["kind"]).to_s == KIND
+
+        Array(selected).map(&:to_s).include?(CONTINUE) ? :stop_only : nil
+      end
+
+      def message
+        "a parent agent may only stop this turn here (#{KEY}: false): answer Stop " \
+          "(--option Stop --text WHY), or tell your user it waits"
+      end
+    end
+  end
+end

data/lib/samagotchi/guardrails/rules.rb

@@ -14,6 +14,8 @@ module Samagotchi
     #   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)
+    #   git:     "outside_repo": a shell call runs a mutating git
+    #            subcommand outside the session's repo (ShellGitDirs)
     #   models:  "small" (Guardrails::ModelSize, guardrails.small_models),
     #            or a glob on the bare model name or the model key, or a
     #            list of them: the rule only votes for a model that matches
@@ -26,17 +28,19 @@ module Samagotchi
     class Rules
       class ParseError < StandardError; end
 
-      KEYS = %w[id tool command path models verdict reason scopes].freeze
+      KEYS = %w[id tool command path git models verdict reason scopes].freeze
+      MATCH_KEYS = %w[tool command path git].freeze
       VERDICTS = %w[ask deny].freeze
       GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_DOTMATCH | File::FNM_EXTGLOB
 
-      Rule = Struct.new(:id, :tools, :command, :path, :models, :verdict, :reason, :scopes, :source, keyword_init: true) do
+      Rule = Struct.new(:id, :tools, :command, :path, :git, :models, :verdict, :reason, :scopes, :source, keyword_init: true) do
         def matches?(targets)
           return false unless targets
           return false unless for_model?(targets.model_name, targets.model_key, -> { targets.small_model? })
           return false if tools && !tool_matches?(targets.tool)
           return false if command && !(targets.command && command.match?(targets.command))
           return false if path && !path_matches?(targets)
+          return false if git && !targets.git_outside_repo?
 
           true
         end
@@ -99,12 +103,12 @@ module Samagotchi
 
         verdict = raw["verdict"].to_s
         raise ParseError, "#{label}: verdict must be ask or deny (got #{verdict.inspect})" unless VERDICTS.include?(verdict)
-        unless %w[tool command path].any? { |k| raw.key?(k) }
-          raise ParseError, "#{label}: give at least one of tool, command, path"
+        unless MATCH_KEYS.any? { |k| raw.key?(k) }
+          raise ParseError, "#{label}: give at least one of #{MATCH_KEYS.join(", ")}"
         end
 
         Rule.new(id: id, tools: tools_of(raw["tool"], label), command: regex_of(raw["command"], label),
-                 path: path_of(raw["path"], label), models: models_of(raw["models"], label), verdict: verdict.to_sym,
+                 path: path_of(raw["path"], label), git: git_of(raw["git"], label), models: models_of(raw["models"], label), verdict: verdict.to_sym,
                  reason: (raw["reason"] || "rule #{id}").to_s, scopes: scopes_of(raw["scopes"], label), source: source)
       end
 
@@ -135,6 +139,14 @@ module Samagotchi
         value
       end
 
+      # Only "outside_repo" for now (room for globs later).
+      def self.git_of(value, label)
+        return nil if value.nil?
+        raise ParseError, "#{label}: git must be outside_repo" unless value == "outside_repo"
+
+        value
+      end
+
       def self.models_of(value, label)
         return nil if value.nil?
 

data/lib/samagotchi/guardrails/shell_git_dirs.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Guardrails
+    # Where a shell command runs a git subcommand that changes a checkout
+    # (commit, add, reset, …): the directories, or :unknown for one that
+    # can't be read from the text ($VAR, $(…), `cd -`). Pure text: it
+    # follows cd/pushd/popd, ( … ) subshells, git -C/--git-dir/--work-tree
+    # and GIT_DIR/GIT_WORK_TREE. It catches honest mistakes (cd into
+    # another checkout and commit there); sh -c, scripts, aliases and
+    # $(…) bodies get through. Never raises on odd input.
+    module ShellGitDirs
+      MUTATING = %w[commit add reset checkout switch rebase merge push stash rm mv
+                    cherry-pick revert pull restore am].freeze
+      STASH_READS = %w[list show].freeze
+      # Longest first: "&&" before "&", ";;" before ";".
+      OPERATORS = ["&&", "||", ";;", "|&", ";", "|", "&", "\n", "(", ")"].freeze
+      PREFIXES = %w[command builtin exec time nohup env ! { if then else elif do while until].freeze
+      # git global options that take the next word as their value.
+      VALUE_OPTIONS = %w[-C -c --git-dir --work-tree --namespace].freeze
+      SUBST = "\0SUBST"
+      REDIRECT = /\A\d*[<>]/
+
+      # @param command [String] the shell command
+      # @param cwd [String] where it starts (the call's cwd:, else the session's)
+      # @param home [String] for ~, $HOME, ${HOME} and a bare cd
+      # @return [Array<String, Symbol>] absolute dirs and :unknown, unique
+      def self.for(command, cwd:, home: Dir.home)
+        Walk.new(cwd, home).run(simple_commands(lex(command.to_s)))
+      rescue ArgumentError, EncodingError
+        [] # a NUL byte, invalid UTF-8: the shell would refuse it too
+      end
+
+      # Words and operators ([:word, "x"] / [:op, "&&"]).
+      def self.lex(text)
+        Lexer.new(text).tokens
+      end
+
+      # The token stream split at operators into word lists; ( and ) become
+      # :open / :close markers.
+      def self.simple_commands(tokens)
+        commands = [[]]
+        tokens.each do |kind, value|
+          if kind == :op
+            commands << :open if value == "("
+            commands << :close if value == ")"
+            commands << []
+          else
+            commands.last << value
+          end
+        end
+        commands.reject { |c| c.is_a?(Array) && c.empty? }
+      end
+
+      # A hand-written shell lexer: quotes, backslashes, comments, $(…) and
+      # backticks (an opaque marker inside the word), redirections kept in
+      # their word (2>&1 doesn't split on &), operators.
+      class Lexer
+        def initialize(text)
+          @s = text
+          @i = 0
+          @tokens = []
+          @word = +""
+          @in_word = false
+        end
+
+        def tokens
+          step while @i < @s.size
+          flush
+          @tokens
+        end
+
+        private
+
+        def step
+          c = @s[@i]
+          case c
+          when "\\" then add(@s[@i + 1].to_s, 2)
+          when "'" then single_quote
+          when '"' then double_quote
+          when "`" then backtick
+          when "$" then @s[@i + 1] == "(" ? substitution : add(c, 1)
+          when "#" then @in_word ? add(c, 1) : comment
+          when ">", "<" then redirection
+          when " ", "\t" then flush && (@i += 1)
+          else operator_or_char(c)
+          end
+        end
+
+        def add(text, advance)
+          @word << text
+          @in_word = true
+          @i += advance
+        end
+
+        def flush
+          @tokens << [:word, @word.dup] if @in_word
+          @word.clear
+          @in_word = false
+          true
+        end
+
+        def single_quote
+          close = @s.index("'", @i + 1) || @s.size
+          add(@s[(@i + 1)...close].to_s, close + 1 - @i)
+        end
+
+        def double_quote
+          @i += 1
+          @in_word = true
+          while @i < @s.size && @s[@i] != '"'
+            if @s[@i] == "\\" && @i + 1 < @s.size
+              @word << @s[@i + 1]
+              @i += 2
+            else
+              @word << @s[@i]
+              @i += 1
+            end
+          end
+          @i += 1
+        end
+
+        def backtick
+          close = @s.index("`", @i + 1) || @s.size
+          add(SUBST, close + 1 - @i)
+        end
+
+        def substitution
+          depth = 0
+          j = @i + 1
+          loop do
+            depth += 1 if @s[j] == "("
+            depth -= 1 if @s[j] == ")"
+            j += 1
+            break if depth.zero? || j >= @s.size
+          end
+          add(SUBST, j - @i)
+        end
+
+        def comment
+          @i = @s.index("\n", @i) || @s.size
+        end
+
+        # >, >>, 2>&1, &>, <, <<: kept in the word (the walk drops them).
+        def redirection
+          add(@s[@i], 1)
+          add(@s[@i], 1) while @i < @s.size && @s[@i].match?(/[&\d>-]/) && @word.match?(/>\z/)
+        end
+
+        def operator_or_char(char)
+          op = OPERATORS.find { |o| @s[@i, o.size] == o }
+          return add(char, 1) unless op
+
+          if op == "&" && @word.match?(/\d*>\z/)
+            add(op, 1)
+          else
+            flush
+            @tokens << [:op, op]
+            @i += op.size
+          end
+        end
+      end
+
+      # Follows the current dir through the simple commands and records
+      # where each mutating git runs.
+      class Walk
+        def initialize(cwd, home)
+          @dir = cwd
+          @home = home
+          @subshells = []
+          @pushed = []
+          @found = []
+        end
+
+        def run(commands)
+          commands.each do |words|
+            case words
+            when :open then @subshells << @dir
+            when :close then @dir = @subshells.pop || @dir
+            else simple(words.dup)
+            end
+          end
+          @found.uniq
+        end
+
+        private
+
+        def simple(words)
+          env = {}
+          while (word = words.first)
+            if word.match?(/\A[A-Za-z_]\w*=/)
+              key, value = word.split("=", 2)
+              env[key] = value
+            elsif !PREFIXES.include?(word)
+              break
+            end
+            words.shift
+          end
+          verb = words.shift or return
+          args = words.grep_v(REDIRECT)
+          case verb
+          when "cd" then cd(args)
+          when "pushd"
+            @pushed << @dir
+            @dir = args.first ? expand(args.first, @dir) : nil
+          when "popd" then @dir = @pushed.pop unless @pushed.empty?
+          else git(args, env) if verb == "git" || verb.end_with?("/git")
+          end
+        end
+
+        def cd(args)
+          target = args.reject { |a| %w[-P -L -e -@].include?(a) }.first
+          @dir = if target.nil? then @home
+                 elsif target == "-" then nil
+                 else expand(target, @dir)
+                 end
+        end
+
+        def git(args, env)
+          dir = @dir
+          work_tree = env["GIT_WORK_TREE"] && expand(env["GIT_WORK_TREE"], dir)
+          git_dir = env["GIT_DIR"] && expand(env["GIT_DIR"], dir)
+          sub = nil
+          until args.empty?
+            arg = args.shift
+            case arg
+            when *VALUE_OPTIONS
+              value = args.shift.to_s
+              dir = expand(value, dir) if arg == "-C"
+              git_dir = expand(value, dir) if arg == "--git-dir"
+              work_tree = expand(value, dir) if arg == "--work-tree"
+            when /\A--git-dir=(.*)\z/m then git_dir = expand(Regexp.last_match(1), dir)
+            when /\A--work-tree=(.*)\z/m then work_tree = expand(Regexp.last_match(1), dir)
+            when /\A-/ then next
+            else
+              sub = arg
+              break
+            end
+          end
+          return unless MUTATING.include?(sub)
+          return if sub == "stash" && STASH_READS.include?(args.first)
+
+          @found << (work_tree || repo_of(git_dir) || dir || :unknown)
+        end
+
+        def repo_of(git_dir)
+          return nil unless git_dir
+
+          File.basename(git_dir) == ".git" ? File.dirname(git_dir) : git_dir
+        end
+
+        # An absolute path for +arg+ against +dir+; nil when it can't be
+        # told from the text (a variable, a substitution, a relative path
+        # against an unknown dir).
+        def expand(arg, dir)
+          return nil if arg.include?(SUBST)
+
+          arg = arg.sub(/\A(~|\$HOME|\$\{HOME\})(?=\/|\z)/) { @home }
+          return nil if arg.include?("$") || arg.start_with?("~")
+          return File.expand_path(arg) if arg.start_with?("/")
+
+          dir && File.expand_path(arg, dir)
+        end
+      end
+    end
+  end
+end