asgard 0.4.1 → 0.5.1

data/examples/watcher_examples/README.md

@@ -0,0 +1,112 @@
+# Watcher example
+
+A small project whose tasks run when its files change. The `.loki` here
+declares four watches; `lib/`, `bin/`, `docs/` and `data/` hold one
+placeholder file each so the watcher has something to watch right away.
+
+## Before you start
+
+The watcher runs its daemon and every triggered task as separate `asgard`
+processes. If you are running asgard from a git checkout of this
+repository rather than an installed gem, install the checkout as the gem
+first, from the repository root:
+
+```bash
+asgard install        # builds pkg/asgard-<version>.gem and gem-installs it
+gem list asgard       # the checkout's version should be listed
+```
+
+Otherwise an older asgard gem already on the machine can be the one the
+spawned processes run, and it will not understand `watch`.
+
+## Walkthrough
+
+From this directory:
+
+```bash
+asgard watcher start
+```
+
+```
+started watcher for watcher_examples (pid 12345); log: ~/.local/state/asgard/watch/watcher-examples/watcher.log
+```
+
+Now make some changes and watch the log fill up:
+
+```bash
+echo '# a change' >> lib/greeter.rb         # lint runs, with the path in changes.modified
+echo 'more' >> docs/index.md               # docs runs; BUILD_ENV=demo comes from env:
+echo 'more' >> docs/drafts/ideas.md        # nothing: drafts/ is ignored
+echo '{}' > data/new.json                  # reindex runs: a file was added
+echo '{"edited": true}' > data/new.json    # nothing: events: is added and removed only
+rm data/new.json                           # reindex runs again: a file was removed
+asgard watcher log
+```
+
+```
+2026-10-18 23:40:01 trigger lint task=lint lib/greeter.rb
+2026-10-18 23:40:01 spawn lint task=lint pid=12351 lib/greeter.rb
+lint: lib/greeter.rb (7 lines) triggered by lint
+2026-10-18 23:40:02 exit lint task=lint pid=12351 status=0 seconds=0.41
+2026-10-18 23:40:05 trigger docs task=docs docs/index.md
+2026-10-18 23:40:05 spawn docs task=docs pid=12360 docs/index.md
+docs: building for demo; changed: docs/index.md
+2026-10-18 23:40:06 exit docs task=docs pid=12360 status=0 seconds=0.40
+2026-10-18 23:40:09 trigger reindex task=reindex data/new.json
+2026-10-18 23:40:09 spawn reindex task=reindex pid=12371 data/new.json
+reindex: 1 added, 0 removed; 2 data file(s) now
+2026-10-18 23:40:10 exit reindex task=reindex pid=12371 status=0 seconds=0.40
+...
+```
+
+Each trigger line names the entry and the changed paths. Each spawn and
+exit line carries the task's pid, so the lines of overlapping tasks can be
+told apart; a task's own output sits between its spawn and its exit. Save
+`lib/greeter.rb` twice in quick succession and the second trigger says
+`(queued behind pid N)`: the same task never overlaps itself, while
+different tasks run at the same time.
+
+```bash
+asgard watcher list
+```
+
+```
+┌──────────┬────────────────┬──────────────────────────────────────┬──────────┬────────────────────────────────┐
+│ NAME     │ TASK           │ WATCHES                              │ DAEMON   │ LAST RUN                       │
+├──────────┼────────────────┼──────────────────────────────────────┼──────────┼────────────────────────────────┤
+│ lint     │ asgard lint    │ lib/**/*.rb                          │ running  │ 0 (0.4s, 2026-10-18 23:40:02)  │
+│ docs     │ asgard docs    │ docs                                 │ running  │ 0 (0.4s, 2026-10-18 23:40:06)  │
+│ reindex  │ asgard reindex │ data/**/*.json [added, removed]      │ running  │ 0 (0.4s, 2026-10-18 23:40:14)  │
+│ lint-bin │ asgard lint    │ bin/**/*                             │ running  │ never                          │
+└──────────┴────────────────┴──────────────────────────────────────┴──────────┴────────────────────────────────┘
+```
+
+```bash
+asgard watcher stop
+```
+
+A task that is still running finishes first; `stop` names it while it
+waits.
+
+## Running the tasks by hand
+
+Every task works without the watcher too. `changes` is then empty, which
+`lint` turns into "lint everything":
+
+```bash
+asgard lint
+asgard docs
+asgard reindex
+```
+
+## What the watcher restricts
+
+A triggered task does not inherit the shell the watcher was started from.
+It sees `PATH`, `HOME`, `USER`, `LANG` and a few other basics, the entry's
+`env:`, a project `.envrc` through `direnv`, and the trigger variables
+`ASGARD_WATCH`, `ASGARD_WATCH_ROOT`, `ASGARD_MODIFIED`, `ASGARD_ADDED` and
+`ASGARD_REMOVED`. `asgard watcher preview` prints the exact command and
+environment each entry would run.
+
+Edit `.loki` while the watcher runs and it restarts itself with the new
+declarations.

data/examples/watcher_examples/bin/hello

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Edit this file while the watcher runs: the lint-bin entry picks it up.
+echo "hello from bin/"

data/examples/watcher_examples/data/records.json

@@ -0,0 +1 @@
+{ "records": ["one", "two"] }

data/examples/watcher_examples/docs/drafts/ideas.md

@@ -0,0 +1,5 @@
+# Drafts are ignored
+
+Editing this file never triggers the docs entry: its declaration has
+`ignore: %r{\Adrafts/}`.
+more

data/examples/watcher_examples/docs/index.md

@@ -0,0 +1,4 @@
+# Watcher example
+
+Edit this file while the watcher runs: the docs entry picks it up.
+more

data/examples/watcher_examples/lib/greeter.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Edit this file while the watcher runs: the lint entry picks it up.
+module Greeter
+  def self.greet(name) = "Hello, #{name}!"
+end
+# a change

data/lib/asgard/base.rb

@@ -18,6 +18,10 @@ module Asgard
     include Dispatch
 
     class << self
+      # A usage error (missing argument, unknown command or option) exits 1,
+      # so CI and `asgard do` sequences see the failure. Thor's default is 0.
+      def exit_on_failure? = true
+
       def header(text = nil)
         return @_header if text.nil?
         (@_header ||= []) << text

data/lib/asgard/kernel_methods.rb

@@ -16,6 +16,12 @@ module Kernel
   end
   module_function :env
 
+  # The files the watcher saw change when it triggered this task, as an
+  # Asgard::Changes (modified, added, removed, all). Every list is empty
+  # when the task is run by hand.
+  def changes = Asgard::Changes.current
+  module_function :changes
+
   def loki_up(name = ".loki")
     dir = Pathname.new(Dir.pwd)
     loop do

data/lib/asgard/schedule/table.rb

@@ -23,16 +23,17 @@ module Asgard
       end
 
       # rows rendered for the terminal, under title when given: colored when io
-      # is a tty and NO_COLOR is unset.
-      def self.draw(rows, title: nil, io: $stdout)
-        table = new(rows, color: io.tty? && !ENV.key?("NO_COLOR"), width: terminal_width(io)).render
+      # is a tty and NO_COLOR is unset. headers: relabels the five columns.
+      def self.draw(rows, title: nil, io: $stdout, headers: HEADERS)
+        table = new(rows, color: io.tty? && !ENV.key?("NO_COLOR"), width: terminal_width(io), headers:).render
         [title, table].compact.join("\n")
       end
 
       # color: styles the header, state and last exit with ANSI codes.
-      def initialize(rows, color:, width:)
+      def initialize(rows, color:, width:, headers: HEADERS)
         require "pastel"
 
+        @headers = headers
         @cells  = rows.map { |row| row.values_at(:name, :command, :schedule, :state, :last_exit) }
         @pastel = Pastel.new(enabled: color)
         @width  = width
@@ -43,7 +44,7 @@ module Asgard
       def render
         require "tty-table"
 
-        grid = TTY::Table.new(header: HEADERS.map { |text| @pastel.bold(text) }, rows: @cells.map { |cells| styled(cells) })
+        grid = TTY::Table.new(header: @headers.map { |text| @pastel.bold(text) }, rows: @cells.map { |cells| styled(cells) })
         grid.render(:unicode, multiline: true, resize: true, width: total_width, column_widths:, padding: [0, 1]).to_s
       end
 
@@ -57,7 +58,7 @@ module Asgard
 
       private
 
-      def natural_widths = [HEADERS, *@cells].transpose.map { |column| column.max_by(&:length).length + EXTRA }
+      def natural_widths = [@headers, *@cells].transpose.map { |column| column.max_by(&:length).length + EXTRA }
 
       def overflowing? = total_width > @width
 
@@ -69,8 +70,8 @@ module Asgard
 
       def styled(cells)
         *lead, state, last_exit = cells
-        state_color = { "active" => :green, "stopped" => :yellow }.fetch(state, :red)
-        exit_color  = last_exit.match?(/\A[1-9]\d*\z/) ? :red : :dim
+        state_color = { "active" => :green, "running" => :green, "stopped" => :yellow }.fetch(state, :red)
+        exit_color  = last_exit.match?(/\A[1-9]\d*\b/) ? :red : :dim
         [*lead, @pastel.decorate(state, state_color), @pastel.decorate(last_exit, exit_color)]
       end
     end

data/lib/asgard/tasks.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "schedule"
+require_relative "watch"
 
 # Tasks is the single conventional entry point for all .loki files.
 # It is pre-defined by the gem so .loki files never need to declare a class.
@@ -38,10 +39,18 @@ class Tasks < Asgard::Base
   # Class-level `schedule :task, at: "HH:MM"` declarations (see Asgard::Schedule).
   extend Asgard::Schedule::DSL
 
+  # Class-level `watch :task, paths: "lib"` declarations (see Asgard::Watch).
+  extend Asgard::Watch::DSL
+
   # Gem-owned, so the command is _schedule; the map keeps `asgard schedule`
   # as the name users type, and ancestor_name keeps it in subcommand help.
   desc "schedule SUBCOMMAND", "Manage schedules declared with `schedule :task, ...` (launchd on macOS, systemd on Linux)"
   subcommand "_schedule", Asgard::Schedule::Commands
   map "schedule" => :_schedule
   Asgard::Schedule::Commands.commands.each_value { |command| command.ancestor_name = "schedule" }
+
+  desc "watcher SUBCOMMAND", "Run and manage the file watcher declared with `watch :task, paths: ...`"
+  subcommand "_watcher", Asgard::Watch::Commands
+  map "watcher" => :_watcher
+  Asgard::Watch::Commands.commands.each_value { |command| command.ancestor_name = "watcher" }
 end

data/lib/asgard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Asgard
-  VERSION = "0.4.1"
+  VERSION = "0.5.1"
 end

data/lib/asgard/watch/changes.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Asgard
+  # The files a watcher trigger saw change, as three lists of paths relative
+  # to the project root. The watcher hands them to the task through three
+  # environment variables (newline-separated, since paths may hold spaces
+  # or colons); the `changes` Kernel method reads them back. Every list is
+  # empty when the task is run by hand, so one task body serves both.
+  class Changes < Data.define(:modified, :added, :removed)
+    VARIABLES = { modified: "ASGARD_MODIFIED", added: "ASGARD_ADDED", removed: "ASGARD_REMOVED" }.freeze
+
+    class << self
+      # The changes behind this process, read once from ENV. Tests and a
+      # watcher-run task that re-execs call forget to read them again.
+      def current = @current ||= from_env
+
+      def forget = @current = nil
+
+      # Parses the trigger variables; a missing one is an empty list.
+      def from_env(env = ENV) = new(**VARIABLES.to_h { |member, variable| [member, env[variable].to_s.split("\n")] })
+    end
+
+    def initialize(modified: [], added: [], removed: [])
+      super(modified: modified.map(&:to_s).freeze, added: added.map(&:to_s).freeze, removed: removed.map(&:to_s).freeze)
+    end
+
+    # Every changed path once, in modified, added, removed order.
+    def all = (modified + added + removed).uniq
+
+    def empty? = modified.empty? && added.empty? && removed.empty?
+
+    # The trigger variables that reproduce this object through from_env.
+    def to_env = VARIABLES.to_h { |member, variable| [variable, public_send(member).join("\n")] }
+  end
+
+  module Watch
+    # Which Changes member each events: kind fills. Listen reports the first
+    # kind as "modified".
+    EVENT_MEMBERS = { changed: :modified, added: :added, removed: :removed }.freeze
+
+    module_function
+
+    # A listener batch ({ modified:, added:, removed: }) narrowed to the
+    # kinds in events (a Set from normalize_events), as a Changes; nil
+    # when nothing is left, so the dispatcher skips the trigger.
+    def filter_events(batch, events)
+      kept    = EVENT_MEMBERS.to_h { |event, member| [member, events.include?(event) ? Array(batch[member]) : []] }
+      changes = Changes.new(**kept)
+      changes.empty? ? nil : changes
+    end
+  end
+end

data/lib/asgard/watch/commands.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "shellwords"
+require "time"
+
+# warn is silent when $VERBOSE is nil and bypasses $stderr in Ruby 4.0 (see
+# base/task_dsl.rb); these messages are for the user, so they always print.
+# rubocop:disable Style/StderrPuts
+
+module Asgard
+  module Watch
+    # `asgard watcher SUBCOMMAND` — runs and manages the watcher for the
+    # entries declared with `watch :task, paths: ...` in a .loki file.
+    # Subclasses Asgard::Base rather than Tasks so `asgard watcher help`
+    # lists only these subcommands, not every project task.
+    class Commands < Asgard::Base
+      namespace "watcher"
+
+      HEADERS   = ["NAME", "TASK", "WATCHES", "DAEMON", "LAST RUN"].freeze
+      STOP_WAIT = 1.0
+
+      class << self
+        # The WATCHES column: the declared paths and, unless every kind of
+        # change counts, the kinds that do.
+        def describe(spec)
+          events = spec[:events].to_a.map(&:to_s)
+          kinds  = events.size == EVENTS.size ? "" : " [#{events.join(', ')}]"
+          "#{spec[:paths].join(' ')}#{kinds}"
+        end
+
+        # The LAST RUN column from an entry's record: never, still running,
+        # or its exit status with duration and finish time.
+        def last_run(entry)
+          return "never" unless entry
+          return "running (pid #{entry[:pid]})" unless entry.key?(:finished)
+
+          finished = Time.iso8601(entry[:finished]).strftime("%Y-%m-%d %H:%M:%S")
+          "#{entry[:status]} (#{format('%.1fs', entry[:seconds])}, #{finished})"
+        end
+      end
+
+      desc "tree", "Print a tree of the watcher subcommands", hide: true
+      # Redefined only to re-register tree as hidden in this namespace.
+      def tree = super # rubocop:disable Lint/UselessMethodDefinition
+
+      no_commands do
+        def watches = Watch.declarations
+
+        def watch_root = @watch_root ||= File.realpath((Asgard.find_task_file&.dirname || Pathname.pwd).to_s)
+
+        def watch_project = File.basename(watch_root)
+
+        def state = @state ||= State.new(project: watch_project, root: watch_root)
+
+        def declared_watches
+          abort "No watches declared. Add `watch :task, paths: \"lib\"` inside class Tasks in #{watch_root}/.loki." if watches.empty?
+
+          unknown = Daemon.unknown_tasks(watches, Tasks.all_commands.keys)
+          abort "watcher: no such task(s): #{unknown.join(', ')}" unless unknown.empty?
+
+          watches
+        end
+
+        def watch_direnv
+          return unless File.exist?(File.join(watch_root, ".envrc"))
+
+          Schedule.which("direnv", ENV.fetch("PATH", nil)) or
+            $stderr.puts "watcher: .envrc found but direnv is not on PATH; its variables will not be loaded"
+        end
+
+        def watch_asgard = Spawn.executable || abort("watcher: asgard is not on PATH")
+
+        def spawn_context
+          Spawn::Context.new(root: watch_root, log: state.log_path, base: Spawn.base_env, asgard: watch_asgard, direnv: watch_direnv)
+        end
+
+        def refuse_if_running
+          pid = state.running_pid
+          abort "watcher is already running for #{watch_project} (pid #{pid}); `asgard watcher stop` first." if pid
+        end
+
+        # `start` records the child's pid before the child reaches here, so a
+        # pidfile naming this very process is ours, not another daemon's.
+        def refuse_if_another_running
+          pid = state.running_pid
+          abort "watcher is already running for #{watch_project} (pid #{pid}); `asgard watcher stop` first." if pid && pid != Process.pid
+        end
+      end
+
+      # Thor reserves `run` as a method name, so the command is `daemon`
+      # with `run` as its usage and mapped name, as --version is _version.
+      desc "run", "Watch in the foreground until INT or TERM (what `start` runs detached)"
+      map "run" => :daemon
+      def daemon
+        specs = declared_watches
+        refuse_if_another_running
+        config = Daemon::Config.new(declarations: specs, root: watch_root, state:, context: spawn_context, tasks: Tasks.all_commands.keys)
+        Daemon.new(config).run
+      end
+
+      desc "start", "Start the watcher for this project in the background"
+      def start
+        specs = declared_watches
+        refuse_if_running
+        log = state.log_path
+        state.prepare.write_declarations(specs.values)
+        pid = Process.spawn(watch_asgard, "watcher", "run", chdir: watch_root, pgroup: true, out: [log, "a"], err: %i[child out])
+        Process.detach(pid)
+        state.write_pid(pid)
+        puts "started watcher for #{watch_project} (pid #{pid}); log: #{log}"
+      end
+
+      desc "stop", "Stop the watcher; a task already running finishes first"
+      def stop
+        pid = state.running_pid or abort("watcher is not running for #{watch_project}.")
+        Process.kill("TERM", pid)
+        while Reporter.alive?(pid)
+          running = state.running_entries.map { |entry| "#{entry[:entry]} (pid #{entry[:pid]})" }
+          puts "watcher: waiting for #{running.join(', ')}" unless running.empty?
+          sleep STOP_WAIT
+        end
+        state.clear
+        puts "stopped watcher for #{watch_project}"
+      end
+
+      no_commands do
+        # True when list should cover every project: asked for with --all, or
+        # there is no .loki here, so no single project to scope to.
+        def list_all? = options[:all] || Asgard.find_task_file.nil?
+
+        def no_watches_message
+          return "No watchers have been started on this machine." if list_all?
+
+          "No watches declared for #{watch_project}. Add `watch :task, paths: \"lib\"` inside class Tasks in #{watch_root}/.loki.\n" \
+            "Use `asgard watcher list --all` to see every project's watches."
+        end
+
+        # { title => rows } for every project, or { nil => rows } for this one; empty groups drop out.
+        def list_groups
+          groups = list_all? ? all_groups : { nil => Commands.project_rows(state, declared_records) }
+          groups.reject { |_, rows| rows.empty? }
+        end
+
+        def declared_records = watches.values.map { |spec| State.declaration_record(spec) }
+
+        # Every project with watcher state, titled "Project: slug (/root)". This
+        # project's rows come from its live declarations; the others' from what
+        # `start` recorded, since their .loki files are not loaded.
+        def all_groups
+          State.all.to_h do |slug, root|
+            other = State.new(project: slug, root:)
+            own   = Asgard.find_task_file && root == watch_root
+            ["Project: #{slug} (#{root})", Commands.project_rows(other, own ? declared_records : other.read_declarations)]
+          end
+        end
+      end
+
+      class << self
+        # One `list` row per declaration record, with the project's daemon
+        # state and each entry's last run.
+        def project_rows(project_state, records)
+          daemon  = project_state.running_pid ? "running" : "stopped"
+          entries = project_state.entries
+          records.map { |record| watch_row(record, daemon, entries[record[:name]]) }
+        end
+
+        def watch_row(record, daemon, entry)
+          { name: record[:name], command: "asgard #{record[:task]}", schedule: describe(record),
+            state: daemon, last_exit: last_run(entry) }
+        end
+      end
+
+      desc "list", "Show this project's watches, whether the watcher is running, and each entry's last run (--all: every project's)"
+      method_option :all, aliases: "-a", type: :boolean, desc: "List every project's watches, not just this one's"
+      def list
+        groups = list_groups
+        return puts(no_watches_message) if groups.empty?
+
+        puts groups.map { |title, rows| Schedule::Table.draw(rows, title:, headers: HEADERS) }.join("\n\n")
+        puts "\nLogs: #{State.base_dir}  (asgard watcher log)"
+      end
+
+      desc "preview", "Show the command and environment each watch would run, without running anything"
+      def preview
+        context = spawn_context
+        declared_watches.each_value { |spec| print_preview(spec, context) }
+      end
+
+      no_commands do
+        def print_preview(spec, context)
+          description = Spawn.description(spec, Changes.new, context)
+          puts "# #{spec[:name]}: #{Shellwords.join(description[:argv])}  (#{Commands.describe(spec)})"
+          description[:env].sort.each { |key, value| puts "#{key}=#{value}" }
+          puts
+        end
+      end
+
+      desc "log", "Print this project's watcher log to STDOUT"
+      method_option :follow, aliases: "-f", type: :boolean, desc: "Keep printing new output as it arrives (tail -f)"
+      def log
+        path = state.log_path
+        return $stderr.puts "#{watch_project} has no watcher log yet (#{path}); it is created on the first start." unless File.exist?(path)
+        return sh("tail -n +1 -f #{path.shellescape}", silent: true, exec: true) if options[:follow]
+
+        IO.copy_stream(path, $stdout)
+      end
+    end
+  end
+end
+# rubocop:enable Style/StderrPuts

data/lib/asgard/watch/daemon.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Asgard
+  module Watch
+    # `asgard watcher run`: the whole watcher in one foreground process.
+    # One Listen listener per declaration pushes batches onto the inbox;
+    # the dispatcher routes them to worker Ractors; the reporter writes the
+    # log and the entry records. A change to any .loki file re-execs the
+    # process so declarations are never stale. INT or TERM stops listening,
+    # drops triggers that have not started, waits for running tasks to
+    # exit, removes the pidfile and returns.
+    class Daemon
+      # What a run is made of: the normalized declarations, the real
+      # project root, the State, the Spawn::Context, and the names of the
+      # tasks the project defines.
+      Config = Data.define(:declarations, :root, :state, :context, :tasks)
+
+      LOKI_DEBOUNCE = 0.5
+
+      attr_reader :inbox, :listeners
+
+      # listen: is the Listen module (loaded only when nothing else is
+      # given) or a stand-in; exec: replaces the process on reload; out:
+      # is where shutdown progress goes.
+      def initialize(config, listen: Daemon.listen_module, exec: Kernel.method(:exec), out: $stdout)
+        @config     = config
+        @listen     = listen
+        @exec       = exec
+        @out        = out
+        @inbox      = Queue.new
+        @listeners  = []
+        @stopping   = false
+        @reporter   = nil
+        @dispatcher = nil
+      end
+
+      class << self
+        # Listen, loaded only when a daemon is actually built.
+        def listen_module
+          require "listen"
+          Listen
+        end
+
+        # The Listen options for one declaration.
+        def listen_options(spec)
+          { only: spec[:only], ignore: spec[:ignore], wait_for_delay: spec[:debounce], relative: true }.compact
+        end
+
+        # The tasks declared by watch but not defined by the project.
+        def unknown_tasks(declarations, tasks) = declarations.values.map { |spec| spec[:task] }.uniq - tasks
+      end
+
+      def run
+        check_tasks!
+        Dir.chdir(@config.root)
+        state = @config.state.prepare
+        start_pipeline(state)
+        @listeners = build_listeners + [loki_listener]
+        @listeners.each(&:start)
+        state.write_pid(Process.pid)
+        trap_signals
+        sleep 0.2 until @stopping
+        shutdown(state)
+      end
+
+      # Asks run to stop; the trap handler calls this.
+      def stop = @stopping = true
+
+      # Stops listening and replaces the process with a fresh `watcher run`
+      # so new declarations take effect. Running tasks, in their own
+      # process groups, carry on; the new daemon does not know about them.
+      def reload
+        @listeners.each(&:stop)
+        @exec.call(@config.context.asgard, "watcher", "run")
+      end
+
+      private
+
+      def check_tasks!
+        unknown = Daemon.unknown_tasks(@config.declarations, @config.tasks)
+        raise Error, "watch declares tasks this project does not define: #{unknown.join(', ')}" unless unknown.empty?
+      end
+
+      def start_pipeline(state)
+        reports     = RactorQueue.new(capacity: 1024)
+        @reporter   = Reporter.new(reports, log: state.log_path, state:)
+        @dispatcher = Dispatcher.new(@config.declarations, @config.context, reports:)
+        @reporter.start
+        @dispatcher.start(@inbox)
+      end
+
+      def build_listeners = @config.declarations.values.map { |spec| listener_for(spec) }
+
+      # One Listen listener whose callback pushes [entry name, batch] onto the inbox.
+      def listener_for(spec)
+        name = spec[:name]
+        @listen.to(*spec[:dirs], **Daemon.listen_options(spec)) do |modified, added, removed|
+          @inbox.push([name, { modified:, added:, removed: }])
+        end
+      end
+
+      def loki_listener
+        @listen.to(@config.root, only: /\.loki\z/, ignore: DEFAULT_IGNORES, wait_for_delay: LOKI_DEBOUNCE, relative: true) { reload }
+      end
+
+      def trap_signals
+        %w[INT TERM].each { |signal| trap(signal) { stop } }
+      end
+
+      def shutdown(state)
+        @listeners.each(&:stop)
+        @inbox.push(nil)
+        @dispatcher.workers.each_value do |worker|
+          queue = worker[:queue]
+          queue.try_pop until queue.empty?
+        end
+        @reporter.drain(out: @out)
+        state.clear
+        @out.puts "watcher: stopped"
+      end
+    end
+  end
+end