asgard 0.5.1 → 0.6.0

data/lib/asgard/watch/declaration.rb

@@ -11,43 +11,77 @@ module Asgard
     EVENTS        = %i[changed added removed].freeze
     EVENT_ALIASES = { modified: :changed }.freeze
 
-    # Output and scratch directories a task may write inside the project;
-    # always ignored so a task never retriggers itself. Matched against the
-    # path relative to the watched directory, at any depth.
-    DEFAULT_IGNORES = %w[.git coverage pkg tmp log node_modules].map { |dir| %r{(?:\A|/)#{Regexp.escape(dir)}/} }.freeze
+    # Version-control and dependency directories, ignored at any depth.
+    # Each matches the bare directory too ("app/node_modules"), which is
+    # what Listen tests while it scans, so the tree beneath is never walked.
+    DEFAULT_IGNORES = %w[.git .hg .svn node_modules].map { |dir| %r{(?:\A|/)#{Regexp.escape(dir)}(?:/|\z)} }.freeze
 
-    GLOB_CHARS  = /[*?{]/
-    GLOB_TOKENS = %r!\*\*/|\*\*|\*|\?|\{[^}]*\}|\{|[^*?{]+!
+    # Output and scratch directories a task or Bundler writes in the
+    # project root, ignored so a task never retriggers itself. Only the
+    # root's own: an app/log/ of yours is watched like any directory.
+    ROOT_IGNORES = %w[coverage pkg tmp log .bundle bundle vendor/bundle vendor/ruby]
+                   .map { |dir| %r{\A#{Regexp.escape(dir)}(?:/|\z)} }.freeze
+
+    GLOB_CHARS  = /[*?{\[]/
+    BRACE_DEPTH = Hash.new(0).update("{" => 1, "}" => -1).freeze
+    GLOB_TOKENS = %r~\*\*/|\*\*|\*|\?|(?<brace>\{(?:[^{}]|\g<brace>)*\})|\[!?[^\]/]+\]|\{|\[|[^*?{\[]+~
 
     module_function
 
     # Validates a declaration and returns it as a plain Hash. paths: entries
     # are directories, files or globs relative to the project root; the
-    # Hash carries the directories Listen watches and one only: Regexp (or
-    # nil) that stands for every pattern. events: picks which kinds of
-    # change trigger the task; as: names the entry. Every ArgumentError
-    # from the helpers below comes back prefixed with the task.
+    # Hash carries the directories Listen watches, and per directory the
+    # only: Regexp (or nil) for its own patterns and its ignore: list.
+    # events: picks which kinds of change trigger the task; as: names the
+    # entry. Every ArgumentError from the helpers below comes back
+    # prefixed with the task.
     def normalize(task, paths:, only: nil, ignore: nil, events: :all, debounce: 0.5, env: {}, as: nil)
       task = task.to_s
       raise ArgumentError, "task name #{task.inspect} must be a single word" unless task.match?(/\A[\w:-]+\z/)
 
-      paths         = relative_paths(paths)
-      dirs, matched = watched(paths)
+      paths   = relative_paths(paths)
+      globs   = watched(paths)
+      filters = regexps(:only, only)
+      ignores = regexps(:ignore, ignore)
       {
         name:     entry_name(as || task),
         task:,
         paths:,
-        dirs:,
-        only:     combine_only(matched, regexps(:only, only)),
-        ignore:   [*regexps(:ignore, ignore), *DEFAULT_IGNORES],
+        dirs:     globs.keys,
+        only:     globs.to_h { |dir, patterns| [dir, combine_only(patterns.map { |pattern| glob_regexp(pattern) }, filters)] },
+        ignore:   globs.keys.to_h { |dir| [dir, ignores_for(dir, ignores)] },
         events:   normalize_events(events),
         debounce: non_negative_debounce(debounce),
-        env:      env.to_h { |key, value| [key.to_s, value.to_s] }
+        env:      environment(env)
       }
     rescue ArgumentError => e
       raise ArgumentError, "watch :#{task} #{e.message}"
     end
 
+    # The ignore: list Listen gets for one watched directory: the
+    # declared ones, DEFAULT_IGNORES, and ROOT_IGNORES when the directory
+    # is the project root.
+    def ignores_for(dir, declared) = [*declared, *DEFAULT_IGNORES, *(dir == "." ? ROOT_IGNORES : [])]
+
+    # env: as a Hash of String names to String values, refused here when
+    # Process.spawn would refuse it later: a name that is empty, not a
+    # String or Symbol, or holds = or a NUL byte; a value holding a NUL.
+    def environment(env)
+      raise ArgumentError, "env: expects a Hash (got #{env.inspect})" unless env.is_a?(Hash)
+
+      env.to_h { |key, value| env_pair(key, value) }
+    end
+
+    def env_pair(key, value)
+      name = key.to_s if key.is_a?(String) || key.is_a?(Symbol)
+      raise ArgumentError, "env: #{key.inspect} is not a variable name" if name.nil? || name.empty? || name.match?(/[=\0]/)
+
+      value = value.to_s
+      raise ArgumentError, "env: the value of #{name} holds a NUL byte" if value.include?("\0")
+
+      [name, value]
+    end
+
     # The entry name (as:, or the task), checked for the characters a file
     # or label can carry.
     def entry_name(name)
@@ -68,50 +102,92 @@ module Asgard
       paths
     end
 
-    # [directories, patterns] for a declaration's paths. A bare directory
-    # takes everything beneath it, so it cannot share a declaration with a
-    # pattern or a file: Listen applies one only: filter to every directory
-    # it watches, and the pattern would silently filter the directory too.
+    # { directory => its glob patterns } for a declaration's paths, each
+    # directory listened to on its own so its patterns never filter
+    # another's. A bare directory takes everything beneath it (no
+    # patterns), so it cannot share a declaration with a pattern or a
+    # file: the pattern would silently filter the directory too.
     def watched(paths)
-      splits   = paths.map { |path| split_glob(path) }
-      patterns = splits.filter_map(&:last)
-      if !patterns.empty? && patterns.size < splits.size
+      root   = declaration_root
+      splits = paths.map { |path| split_path(path, root:) }
+      globs  = splits.filter_map(&:last)
+      if !globs.empty? && globs.size < splits.size
         raise ArgumentError,
               "mixes a bare directory with patterns or files, which would filter the directory too; " \
               "declare them separately or write the directory as dir/**/*"
       end
 
-      [splits.map(&:first).uniq, patterns]
+      fold(splits)
     end
 
-    # [directory, Regexp or nil] for one paths: entry.
+    # Groups [directory, pattern or nil] pairs by directory. A directory
+    # inside another of the same declaration folds into the outer one,
+    # its pattern prefixed with the path between them, so a change is
+    # reported once rather than by two listeners.
+    def fold(splits)
+      dirs = splits.map(&:first).uniq
+      splits.each_with_object({}) do |(dir, pattern), grouped|
+        outer = dirs.select { |other| inside?(dir, other) }.min_by(&:size)
+        list  = grouped[outer] ||= []
+        list << rebase(pattern, dir, outer) if pattern
+      end
+    end
+
+    # Whether +dir+ is +other+ or lies beneath it.
+    def inside?(dir, other) = other == dir || other == "." || dir.start_with?("#{other}/")
+
+    # +pattern+ (relative to +dir+) made relative to +outer+, which holds dir.
+    def rebase(pattern, dir, outer)
+      return pattern if dir == outer
+
+      "#{outer == '.' ? dir : dir.delete_prefix("#{outer}/")}/#{pattern}"
+    end
+
+    # [directory, Regexp or nil] for one paths: entry (see split_path).
     #   "lib/**/*.rb"   => ["lib", /\A(?:.*\/)?[^\/]*\.rb\z/]
     #   "lib/asgard.rb" => ["lib", /\Aasgard\.rb\z/]
     #   "docs"          => ["docs", nil]
     # The Regexp is matched against the path relative to the directory,
-    # which is how Listen applies only:. A plain path names a file when
-    # stat (File, or a stand-in in tests) finds one there or when it has
-    # an extension, so a file that does not exist yet can be watched.
-    def split_glob(path, stat: File)
-      segments = path.delete_suffix("/").split("/")
+    # which is how Listen applies only:.
+    def split_glob(path, stat: File, root: Dir.pwd)
+      dir, pattern = split_path(path, stat:, root:)
+      [dir, pattern && glob_regexp(pattern)]
+    end
+
+    # [directory, glob pattern relative to it, or nil] for one paths:
+    # entry; "." and empty segments are dropped. A plain path is looked
+    # up under +root+ (the project root, wherever asgard runs from) with
+    # stat (File, or a stand-in in tests): a directory there is a
+    # directory, dots and all; otherwise it names a file when one is
+    # there, when it has an extension, or when it is a dotfile (.env), so
+    # a file that does not exist yet can be watched.
+    def split_path(path, stat: File, root: Dir.pwd)
+      segments = path.split("/").reject { |segment| segment.empty? || segment == "." }
       first    = segments.index { |segment| segment.match?(GLOB_CHARS) }
-      return [directory(segments[0...first]), glob_regexp(segments[first..].join("/"))] if first
+      return [directory(segments[0...first]), segments[first..].join("/")] if first
 
       *parents, last = segments
-      last = last.to_s
-      return [directory(segments), nil] unless stat.file?(path) || !File.extname(last).empty?
+      full = File.expand_path(path, root)
+      return [directory(segments), nil] if last.nil? || stat.directory?(full) || !file_name?(last, full, stat)
 
-      [directory(parents), /\A#{Regexp.escape(last)}\z/]
+      [directory(parents), last]
     end
 
+    def file_name?(name, full, stat) = stat.file?(full) || !File.extname(name).empty? || name.start_with?(".")
+
+    # Where plain paths are looked up: the directory of the nearest .loki,
+    # or the current directory without one.
+    def declaration_root = (loki_up&.dirname || Dir.pwd).to_s
+
     def directory(segments) = segments.empty? ? "." : segments.join("/")
 
     # The Regexp a glob matches, shell-style: ** spans directories, * and ?
-    # stay within one, {a,b} is an alternative. Anything else is literal.
-    def glob_regexp(pattern)
-      body = pattern.scan(GLOB_TOKENS).map { |token| glob_token(token) }.join
-      /\A#{body}\z/
-    end
+    # stay within one, {a,b} is an alternative (nested braces too), [ab]
+    # and [!ab] are character classes. Anything else, an unclosed { or [
+    # included, is literal.
+    def glob_regexp(pattern) = /\A#{glob_body(pattern)}\z/
+
+    def glob_body(pattern) = pattern.gsub(GLOB_TOKENS) { |token| glob_token(token) }
 
     def glob_token(token)
       case token
@@ -119,11 +195,30 @@ module Asgard
       when "**"  then ".*"
       when "*"   then "[^/]*"
       when "?"   then "[^/]"
-      when /\A\{(.*)\}\z/ then "(?:#{Regexp.last_match(1).split(',', -1).map { |alt| Regexp.escape(alt) }.join('|')})"
+      when /\A\{(.*)\}\z/m then "(?:#{brace_alternatives(Regexp.last_match(1)).map { |alt| glob_body(alt) }.join('|')})"
+      when /\A\[(.+)\]\z/m then char_class(Regexp.last_match(1))
       else Regexp.escape(token)
       end
     end
 
+    # The comma-separated alternatives of a brace's body, splitting only
+    # at commas outside any nested brace: "a,{b,c}" => ["a", "{b,c}"].
+    def brace_alternatives(body)
+      depth = 0
+      body.each_char.with_object([+""]) do |char, parts|
+        depth += BRACE_DEPTH[char]
+        char == "," && depth.zero? ? parts << +"" : parts.last << char
+      end
+    end
+
+    # A glob character class body ("ab", "!a", "a-c") as a Regexp class
+    # that never matches the directory separator.
+    def char_class(body)
+      negated = body.size > 1 && body.start_with?("!", "^")
+      body    = body[1..] if negated
+      "(?!/)[#{'^' if negated}#{body.gsub(/[\\\[\]^&]/) { |char| "\\#{char}" }}]"
+    end
+
     # One only: Regexp (or nil for no filter) from the patterns the paths
     # produced and the declared only:. Within each group any may match;
     # when both groups are present a path must satisfy one from each.

data/lib/asgard/watch/dispatcher.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+require "fileutils"
 require "ractor_queue"
 
 module Asgard
@@ -8,7 +10,8 @@ module Asgard
     # the declarations: a dispatch table from listener id (the entry name)
     # to its spec, and one worker per distinct task, so two declarations
     # for the same task share a worker and never overlap. Nothing here is
-    # mutated after construction, and the loop never blocks on a worker.
+    # mutated after construction but a spill counter, and the loop never
+    # blocks on a worker: a trigger for a full queue is dropped and reported.
     class Dispatcher
       # Triggers a busy task can have waiting. RactorQueue rounds this up.
       QUEUE_CAPACITY = 256
@@ -22,13 +25,24 @@ module Asgard
         @context  = context
         @reports  = reports
         @clock    = clock
+        @spills   = 0
         @dispatch = specs.to_h { |spec| [spec[:name], spec] }.freeze
         @workers  = specs.map { |spec| spec[:task] }.uniq.to_h do |task|
-          queue = RactorQueue.new(capacity: QUEUE_CAPACITY)
-          [task, { queue:, ractor: start.call(queue, reports) }.freeze]
+          queue  = RactorQueue.new(capacity: QUEUE_CAPACITY)
+          ractor = start.call(queue, reports)
+          [task, { queue:, ractor:, mailbox: Mailbox.new(queue, ractor) }.freeze]
         end.freeze
       end
 
+      # Every item waiting on +queue+, oldest first, leaving it empty.
+      def self.take_waiting(queue)
+        items = []
+        until (item = queue.try_pop).equal?(RactorQueue::EMPTY)
+          items << item
+        end
+        items
+      end
+
       # Pops [listener id, batch] pairs from inbox until it pops nil.
       def run(inbox)
         while (id, batch = inbox.pop)
@@ -38,17 +52,54 @@ module Asgard
 
       def start(inbox) = Thread.new { run(inbox) }
 
-      # One batch: drop the kinds the entry does not watch, build the frozen
-      # description, report the trigger, hand it to the task's worker. The
-      # description, or nil when nothing was left to run.
+      # One batch: drop the kinds the entry does not watch, report the
+      # trigger, and queue it for the task's worker, merged with any trigger
+      # of the same entry still waiting there, so a busy task runs once more
+      # with every change rather than once per save. The queued description,
+      # or nil when nothing was left to run or the queue was full.
       def route(id, batch)
         spec    = @dispatch.fetch(id)
         changes = Watch.filter_events(batch, spec[:events]) or return nil
         task    = spec[:task]
-        description = Spawn.description(spec, changes, @context)
-        @reports.push(Ractor.make_shareable({ kind: :trigger, entry: spec[:name], task:, at: @clock.now.to_f, changes: changes.to_h }))
-        @workers.fetch(task)[:queue].push(description)
-        description
+        report  = { entry: spec[:name], task:, at: @clock.now.to_f, changes: changes.to_h }
+        @reports.push(Ractor.make_shareable({ kind: :trigger, **report }))
+        enqueue(spec, changes, @workers.fetch(task)[:mailbox]) || drop(report)
+      end
+
+      private
+
+      # Takes back what is still waiting in +mailbox+, folds this entry's
+      # waiting triggers into the new one and queues the rest back first, in
+      # their order. A worker that took one meanwhile simply runs it.
+      def enqueue(spec, changes, mailbox)
+        same, others = Dispatcher.take_waiting(mailbox.queue).partition { |item| item.is_a?(Hash) && item[:entry] == spec[:name] }
+        same.each { |item| Worker.remove_changes_file(item[:changes_file]) }
+        merged = Watch.merge_changes([*same.map { |item| Changes.new(**item[:changes]) }, changes])
+        description = Spawn.description(spec, merged, @context, changes_file: next_changes_file(spec))
+        others.each { |item| mailbox.try_push(item) }
+        write_changes_file(description) # before the push: the worker may start it at once
+        return description if mailbox.try_push(description)
+
+        Worker.remove_changes_file(description[:changes_file])
+        nil
+      end
+
+      def drop(report)
+        @reports.push(Ractor.make_shareable({ kind: :dropped, **report }))
+        nil
+      end
+
+      # Where this trigger's change lists go if they are too big for the
+      # environment; the file is only written when Spawn spilled to it.
+      def next_changes_file(spec)
+        @spills += 1
+        Spawn.changes_file(@context, spec[:name], @spills)
+      end
+
+      def write_changes_file(description)
+        path = description[:changes_file] or return
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.generate(description[:changes]))
       end
     end
   end

data/lib/asgard/watch/mailbox.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "ractor_queue"
+
+module Asgard
+  module Watch
+    # A bounded RactorQueue whose consumer sleeps instead of spinning.
+    # RactorQueue#pop polls every 100µs, which an idle daemon with a few
+    # workers pays for as a constant few percent of a core. Here the
+    # consumer pops with try_pop and, when the queue is empty, blocks in
+    # Ractor.receive; every push sends the consumer's Ractor (+owner+) a
+    # wake-up. A wake-up sent after the push can never be missed, and an
+    # extra one only costs one more empty try_pop. Ractor.receive is
+    # Ruby 3.x and 4.x alike.
+    Mailbox = Data.define(:queue, :owner) do
+      def self.ring(ractor)
+        ractor << :ring if ractor.is_a?(Ractor)
+      rescue Ractor::ClosedError
+        nil # the consumer has ended; nothing is waiting
+      end
+
+      # Blocking push (RactorQueue#push spins only while the queue is full).
+      def push(item)
+        queue.push(item)
+        Mailbox.ring(owner)
+        self
+      end
+
+      # false when the queue is full. Named after RactorQueue#try_push.
+      def try_push(item) # rubocop:disable Naming/PredicateMethod
+        return false unless queue.try_push(item)
+
+        Mailbox.ring(owner)
+        true
+      end
+
+      # Must be called in +owner+, the Ractor the wake-ups go to.
+      def pop
+        loop do
+          item = queue.try_pop
+          return item unless item.equal?(RactorQueue::EMPTY)
+
+          Ractor.receive
+        end
+      end
+
+      def empty? = queue.empty?
+    end
+  end
+end

data/lib/asgard/watch/reporter.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "time"
+require_relative "../pid"
+require_relative "../state_dir"
 
 module Asgard
   module Watch
@@ -8,7 +10,8 @@ module Asgard
     # the dispatcher push frozen reports onto a shared queue; the reporter
     # drains it in a main-Ractor thread, appends a log line per report,
     # keeps the latest record per entry on disk through the state, and
-    # tracks which pids are in flight so shutdown can wait for them.
+    # tracks which pids are in flight so shutdown can say what it waits
+    # for.
     class Reporter
       class << self
         # One log line for a report. behind: is the pid a trigger is queued
@@ -20,40 +23,58 @@ module Asgard
           case kind
           when :trigger then "#{head} #{changed}#{" (queued behind pid #{behind})" if behind}"
           when :spawn   then "#{head} pid=#{pid} #{changed}"
-          else               "#{head} pid=#{pid} status=#{report[:status]} seconds=#{format('%.2f', report[:seconds])}"
+          when :dropped then "#{head} #{changed} (dropped: the task's queue is full)"
+          else               exit_line(head, report)
           end
         end
 
+        def exit_line(head, report)
+          line = "#{head} pid=#{report[:pid]} status=#{report[:status]} seconds=#{format('%.2f', report[:seconds])}"
+          report[:error] ? "#{line} error=#{report[:error]}" : line
+        end
+
         # The entry's record after this report: a spawn starts a new record
         # (no finished/status yet, which is how `list` shows "running"), an
-        # exit completes the previous one.
+        # exit completes the previous one when it is the same run (same
+        # pid). A failed spawn (no pid) is a record of its own, with the
+        # error, so it never wears the previous run's pid and start time.
         def entry_record(report, previous = nil)
           entry, task, pid, at = report.values_at(:entry, :task, :pid, :at)
           stamp = Time.at(at).iso8601
           return { entry:, task:, pid:, started: stamp, changes: report[:changes] } if report[:kind] == :spawn
 
-          { entry:, task:, pid:, **previous.to_h, finished: stamp, status: report[:status], seconds: report[:seconds] }
+          run    = previous.to_h[:pid] == pid ? previous.to_h : {}
+          record = { entry:, task:, pid:, **run, finished: stamp, status: report[:status], seconds: report[:seconds] }
+          report[:error] ? record.merge(error: report[:error]) : record
         end
 
         # The changed paths of a trigger or spawn report, space-separated; "" for an exit.
         def paths(report) = report.fetch(:changes) { {} }.values.flatten.join(" ")
 
         # Whether a process exists; one we may not signal still exists.
-        def alive?(pid)
-          Process.kill(0, pid)
-          true
-        rescue Errno::ESRCH
-          false
-        rescue Errno::EPERM
-          true
-        end
+        def alive?(pid) = Pid.alive?(pid)
+
+        # The command line of a live process, or nil (see Asgard::Pid).
+        def command_line(pid) = Pid.command_line(pid)
+
+        # Whether pid is alive and is an asgard process whose command line
+        # carries every word: ("watcher", "run") for a daemon, a task name
+        # for a trigger. The current process always counts. A pidfile left
+        # by a crash or a reboot can name a pid that an unrelated process
+        # now holds, which a bare liveness check would call ours.
+        def asgard_process?(pid, *words, command: nil) = Pid.matches?(pid, "asgard", *words, command:)
       end
 
-      # state: responds to write_entry(name, record).
-      def initialize(reports, log:, state:)
-        @reports = reports
-        @log     = log
-        @state   = state
+      # state: responds to write_entry(name, record). max_log: is the size
+      # past which the log is rotated (StateDir.rotate); on_rotate: is
+      # called after each rotation, so the daemon can move its own output
+      # to the new log.
+      def initialize(reports, log:, state:, max_log: StateDir.log_limit, on_rotate: nil)
+        @reports   = reports
+        @log       = log
+        @max_log   = max_log
+        @on_rotate = on_rotate
+        @state     = state
         @records = {}
         @running = {} # pid => task
         @mutex   = Mutex.new
@@ -68,30 +89,29 @@ module Asgard
 
       def start = Thread.new { run }
 
+      # Tracks the report, then logs it. A report that cannot be written
+      # (the state directory removed under a running daemon) is said so on
+      # stderr; the reporter goes on, since every worker waits on it.
       def handle(report)
-        trigger = report[:kind] == :trigger
+        kind    = report[:kind]
+        trigger = kind == :trigger
         line    = Reporter.log_line(report, behind: trigger ? running_for(report[:task]) : nil)
+        track(report) if %i[spawn exit].include?(kind)
+        @on_rotate&.call if StateDir.rotate(@log, max_bytes: @max_log)
         File.open(@log, "a") { |file| file.puts(line) }
-        track(report) unless trigger
+      rescue SystemCallError, IOError => e
+        $stderr.puts "watcher: could not write #{kind} report for #{report[:entry]}: #{e.message}" # rubocop:disable Style/StderrPuts
       end
 
       # Pids of tasks in flight, ascending.
       def running = @mutex.synchronize { @running.keys.sort }
 
+      # Tasks in flight, as { pid => task name }.
+      def running_tasks = @mutex.synchronize { @running.dup }
+
       # The in-flight pid of task, or nil.
       def running_for(task) = @mutex.synchronize { @running.key(task) }
 
-      # Blocks until no task is in flight, saying what it waits for once
-      # per interval. A pid that is gone without an exit report (a worker
-      # died between its reports) is forgotten rather than waited on.
-      def drain(interval: 1.0, out: $stdout)
-        until (pids = running).empty?
-          out.puts "watcher: waiting for pid #{pids.join(', ')}"
-          sleep interval
-          forget_dead
-        end
-      end
-
       private
 
       def track(report)
@@ -101,10 +121,6 @@ module Asgard
         @state.write_entry(entry, record)
         @mutex.synchronize { record.key?(:finished) ? @running.delete(pid) : @running[pid] = record[:task] }
       end
-
-      def forget_dead
-        @mutex.synchronize { @running.delete_if { |pid, _task| !Reporter.alive?(pid) } }
-      end
     end
   end
 end

data/lib/asgard/watch/spawn.rb

@@ -14,8 +14,18 @@ module Asgard
       # The only variables a task inherits from the daemon. Everything else
       # it sees comes from the declaration's env:, from .env and .envrc
       # loaded in the task's own process, or from the trigger itself.
-      BASE_ENV_KEYS    = %w[PATH HOME USER LOGNAME SHELL LANG TMPDIR SSH_AUTH_SOCK].freeze
-      BASE_ENV_PATTERN = /\ALC_/
+      # RUBYOPT, RUBYLIB, GEM_*, RUBY_*, RBENV_* and BUNDLE(R)_* carry the
+      # Ruby setup the daemon itself was started under (an rvm gemset,
+      # chruby's RUBY_ROOT, rbenv's RBENV_VERSION, a vendored bundle,
+      # `bundle exec`), without which the task's own asgard may not load.
+      BASE_ENV_KEYS    = %w[PATH HOME USER LOGNAME SHELL LANG TMPDIR SSH_AUTH_SOCK RUBYOPT RUBYLIB].freeze
+      BASE_ENV_PATTERN = /\A(?:LC_|BUNDLER?_|GEM_|RUBY_|RBENV_)/
+
+      # Bytes of change lists the environment carries; past this they go
+      # to a file named in ASGARD_CHANGES_FILE. Argument and environment
+      # space together is about 1 MB on macOS, and a branch switch under a
+      # ** watch can change thousands of files.
+      CHANGES_ENV_LIMIT = 128 * 1024
 
       # What every trigger of one daemon run shares: the real project root,
       # the log file tasks append to, the base environment captured at
@@ -29,10 +39,29 @@ module Asgard
 
       # The task's full environment, lowest precedence first: the context's
       # base, the declaration's env:, the trigger variables.
-      def environment(spec, changes, context)
-        context.base.merge(spec[:env], { "ASGARD_WATCH" => spec[:name], "ASGARD_WATCH_ROOT" => context.root }, changes.to_env)
+      def environment(spec, changes, context, changes_file: nil)
+        context.base.merge(spec[:env], { "ASGARD_WATCH" => spec[:name], "ASGARD_WATCH_ROOT" => context.root },
+                           change_env(changes, changes_file))
+      end
+
+      # The trigger variables for +changes+, or only the name of +file+
+      # when there is a file to use and they would pass +limit+ bytes or
+      # a path holds a newline, which the one-per-line variables cannot
+      # carry.
+      def change_env(changes, file, limit: CHANGES_ENV_LIMIT)
+        vars = changes.to_env
+        return vars if file.nil? || fits_env?(vars, changes, limit)
+
+        { Changes::FILE_VARIABLE => file }
       end
 
+      def fits_env?(vars, changes, limit)
+        vars.sum { |key, value| key.bytesize + value.bytesize } <= limit && changes.all.none? { |path| path.include?("\n") }
+      end
+
+      # The spill file for the +sequence+th trigger of +entry+, beside the log.
+      def changes_file(context, entry, sequence) = File.join(File.dirname(context.log), "changes", "#{entry}-#{sequence}.json")
+
       # The task's argv: the context's asgard executable by absolute path, so
       # a trigger runs the very asgard that started the watcher whatever PATH
       # says, wrapped in direnv exec when available so .envrc loads in the
@@ -57,18 +86,14 @@ module Asgard
 
       # Everything a worker needs to run one trigger, deep-frozen and
       # Ractor-shareable: Strings, Arrays and Hashes only.
-      def description(spec, changes, context)
-        Ractor.make_shareable(
-          {
-            entry:   spec[:name],
-            task:    spec[:task],
-            argv:    argv(spec, context),
-            env:     environment(spec, changes, context),
-            root:    context.root,
-            log:     context.log,
-            changes: changes.to_h
-          }
-        )
+      # +changes_file+ is where the lists may spill; the description names
+      # it as :changes_file only when they did.
+      def description(spec, changes, context, changes_file: nil)
+        env  = environment(spec, changes, context, changes_file:)
+        desc = { entry: spec[:name], task: spec[:task], argv: argv(spec, context), env:,
+                 root: context.root, log: context.log, changes: changes.to_h }
+        desc[:changes_file] = changes_file if env.key?(Changes::FILE_VARIABLE)
+        Ractor.make_shareable(desc)
       end
     end
   end