maf 0.1.0 → 0.3.0

data/lib/maf/retire.rb

@@ -7,7 +7,12 @@ require_relative "shared/processes"
 
 module Maf
   class Retire
-    RUNTIME_PREFIXES = %w[.maf/ .claude/ .opencode/ .codex/].freeze
+    NOT_OURS = "maf: pid %<pid>s is not the dispatcher of %<worker>s: another process has the pid now. " \
+               "maf does not stop it."
+    DISPATCHER_COMMAND = %r{(\A|[\s/])\.maf/bin/dispatcher(\s|\z)}
+
+    # Changes in these folders belong to the flow, not to the work of the worker.
+    def self.runtime_prefixes = [".maf/"] + Maf::Shared::Harness.all.filter_map(&:home_dir).map { |dir| "#{dir}/" }
 
     def initialize(root, spec)
       @root = root
@@ -38,12 +43,42 @@ module Maf
     def stop_dispatcher
       pid = Workers.at(@root).find(@worker)&.fetch("pid", nil)
       return unless pid && Shared::Processes.alive?(pid)
+      return warn(format(NOT_OURS, pid: pid, worker: @worker)) unless dispatcher?(pid)
 
       puts "Stopping the dispatcher of #{@worker} (pid #{pid}). A running agent finishes first."
       RunningProcesses.terminate(pid)
       abort "maf: pid #{pid} did not stop. Stop it with: kill #{pid}" unless RunningProcesses.wait_for_exit(pid)
     end
 
+    def dispatcher?(pid)
+      workers = Workers.at(@root)
+      return workers.dispatcher?(@worker) unless workers.started(@worker).to_s.empty?
+      return true if legacy_dispatcher?(pid)
+
+      abort "maf: maf cannot check pid #{pid}. Stop it with: kill #{pid}, then run this again." if beating?(pid)
+      false
+    end
+
+    def legacy_dispatcher?(pid)
+      command = IO.popen(["ps", "-o", "command=", "-p", pid.to_s], err: File::NULL, &:read).to_s.strip
+      command.match?(DISPATCHER_COMMAND) && RunningProcesses.in(@dir).include?(pid.to_i)
+    rescue SystemCallError
+      false
+    end
+
+    def beating?(pid)
+      presence = read_presence
+      presence["pid"].to_i == pid.to_i && Shared::Processes.recent?(presence["seen_at"])
+    end
+
+    def read_presence
+      JSON.parse(File.read(presence_path))
+    rescue SystemCallError, JSON::ParserError
+      {}
+    end
+
+    def presence_path = File.join(@root, ".maf", "coordination", "presence", "#{@worker}.json")
+
     def release_tasks
       env = { "COORD_ROLE" => role, "COORD_WORKER" => @worker }
       ids = Team.coord(@root, "next", "--mine", env: env).scan(/^[0-9a-f-]{36}/)
@@ -56,10 +91,7 @@ module Maf
       Team.coord(@root, "annotate", id, "Worker #{@worker} was retired. Continue on the existing task branch.")
     end
 
-    def remove_presence
-      coord_dir = File.join(@root, ".maf", "coordination")
-      FileUtils.rm_f(File.join(coord_dir, "presence", "#{@worker}.json"))
-    end
+    def remove_presence = FileUtils.rm_f(presence_path)
 
     def remove_worker
       remove_worktree
@@ -72,7 +104,11 @@ module Maf
       return false unless Dir.exist?(@dir)
 
       lines = IO.popen(["git", "-C", @dir, "status", "--porcelain"], err: File::NULL, &:readlines)
-      lines.map { |line| line[3..].strip }.any? { |path| RUNTIME_PREFIXES.none? { |prefix| path.start_with?(prefix) } }
+      lines.map { |line| line[3..].strip }.any? do |path|
+        Retire.runtime_prefixes.none? do |prefix|
+          path.start_with?(prefix)
+        end
+      end
     end
 
     def remove_worktree

data/lib/maf/setup_agent/args.rb

@@ -3,18 +3,23 @@
 module Maf
   module SetupAgent
     # Args reads the positional arguments (HARNESS ROLE[_WORKER] [model:M]),
-    # then the flags. --dispatch and --model M are setup_agent's own flags; all
-    # other flags go to the dispatcher and need --dispatch.
+    # then the flags. --dispatch, --model M, and --effort L are setup_agent's own
+    # flags; all other flags go to the dispatcher and need --dispatch.
     class Args
-      Parsed = Struct.new(:harness, :role, :worker_id, :worker, :model, :dispatch, :detach, :dispatcher_args,
-                          keyword_init: true)
+      Parsed = Struct.new(:harness, :role, :worker_id, :worker, :model, :effort, :dispatch, :detach,
+                          :dispatcher_args, keyword_init: true)
 
       def self.parse(argv)
         dispatch, detach, positional, flags = split(argv)
-        model = take_model(flags)
+        model, effort = %w[--model --effort].map { |flag| take_value(flags, flag) }
+        check_flags(flags, dispatch, detach)
+        Parsed.new(**identity(positional, model, dispatch), effort: effort, dispatch: dispatch, detach: detach,
+                                                            dispatcher_args: flags)
+      end
+
+      def self.check_flags(flags, dispatch, detach)
         reject_stray(flags, dispatch)
         abort "setup_agent: --detach works only with --dispatch" if detach && !dispatch
-        Parsed.new(**identity(positional, model, dispatch), dispatch: dispatch, detach: detach, dispatcher_args: flags)
       end
 
       def self.split(argv)
@@ -31,10 +36,10 @@ module Maf
           model: model || model_arg&.sub(/\Amodel:/, "") }
       end
 
-      def self.take_model(flags)
-        index = flags.index("--model")
+      def self.take_value(flags, flag)
+        index = flags.index(flag)
         value = index && flags.slice!(index, 2)[1]
-        abort "setup_agent: --model needs a value" if index && (value.nil? || value.start_with?("--"))
+        abort "setup_agent: #{flag} needs a value" if index && (value.nil? || value.start_with?("--"))
         value
       end
 
@@ -50,7 +55,8 @@ module Maf
       end
 
       def self.abort_usage
-        abort "usage: maf start HARNESS ROLE[_WORKER] [model:MODEL] [--model MODEL] [--dispatch [FLAGS...]]"
+        abort "usage: maf start HARNESS ROLE[_WORKER] [model:MODEL] [--model MODEL] [--effort LEVEL] " \
+              "[--dispatch [FLAGS...]]"
       end
     end
   end

data/lib/maf/setup_agent/dispatch.rb

@@ -9,11 +9,11 @@ module Maf
     module Dispatch
       DISPATCHER = ".maf/bin/dispatcher"
 
-      def self.launch(args, model)
+      def self.launch(args)
         dispatcher = File.join(Project.root, DISPATCHER)
         require_dispatcher!(dispatcher)
         cmd = [RbConfig.ruby, dispatcher, args.role, "--harness", args.harness]
-        cmd += ["--model", model] if model
+        cmd += { "--model" => args.model, "--effort" => args.effort }.compact.flatten
         cmd += args.dispatcher_args
         args.detach ? detach(cmd, args.worker) : Launcher.exec_or_die(cmd)
       end
@@ -23,7 +23,7 @@ module Maf
       def self.detach(cmd, worker)
         log = File.join(ENV.fetch("COORD_DIR"), "sessions", "#{worker}.log")
         pid = spawn_detached(cmd, log)
-        Maf::Workers.at(Project.root).update(worker, "pid" => pid)
+        Maf::Workers.at(Project.root).update(worker, "pid" => pid, "started" => Maf::Shared::Processes.started_at(pid))
         puts "Started #{worker} in the background (pid #{pid}). Log: #{log}"
       end
 

data/lib/maf/setup_agent/launcher.rb

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
+require_relative "../shared/sandbox"
+require_relative "pty_relay"
+
 module Maf
   module SetupAgent
+    # Launcher replaces this process with the interactive session of a harness.
+    # The harness file builds the command (Maf::Shared::Harnesses).
     module Launcher
-      REGISTRY = {}
+      def self.launch(harness, role, model, effort = nil)
+        ENV.update(harness.launch_env)
+        return exec_or_die(harness.launch(role, model, effort)) if Maf::Shared::Sandbox.mode == "off"
 
-      def self.for(harness)
-        register_defaults if REGISTRY.empty?
-        REGISTRY.fetch(harness) { abort "setup_agent: no launcher for harness '#{harness}' yet." }
+        warn "maf: sandbox: #{Maf::Shared::Sandbox.describe(harness)}"
+        exit Maf::Shared::Sandbox.keeping_links(harness) { relay_or_die(sandboxed(harness, role, model, effort)) }
       end
 
-      def self.register_defaults
-        REGISTRY["claude"] = Claude
-        REGISTRY["opencode"] = Opencode
-        REGISTRY["codex"] = Codex
-        REGISTRY["hermes"] = Hermes
+      def self.sandboxed(harness, role, model, effort)
+        Maf::Shared::Sandbox.wrap(harness.launch(role, model, effort), harness)
       end
 
       def self.exec_or_die(cmd)
@@ -23,62 +26,10 @@ module Maf
         abort "setup_agent: '#{cmd.first}' not found on PATH."
       end
 
-      # FlowFiles finds the files of the flow in .maf/ of the main project. The
-      # project's own harness config stays as it is: each file of the flow is
-      # passed to the harness at the start.
-      module FlowFiles
-        def self.path(*parts) = File.join(Project.root, ".maf", *parts)
-        def self.flag(name, *parts) = File.exist?(path(*parts)) ? [name, path(*parts)] : []
-      end
-
-      # --settings adds the hooks of the flow, --mcp-config adds the graph server.
-      # --mcp-config takes many values, so `--` ends the options before the prompt.
-      module Claude
-        def self.launch(role, _worker, model)
-          prompt = "Read .maf/agents/claude/#{role}.md and follow it exactly. Start your work loop now."
-          cmd = ["claude", *FlowFiles.flag("--settings", "claude", "settings.json"),
-                 *FlowFiles.flag("--mcp-config", "mcp", "claude.json")]
-          Launcher.exec_or_die(cmd + (model ? ["--model", model] : []) + ["--", prompt])
-        end
-      end
-
-      # opencode merges the file in OPENCODE_CONFIG with the project's opencode.json.
-      module Opencode
-        def self.launch(role, _worker, model)
-          config = FlowFiles.path("mcp", "opencode.json")
-          ENV["OPENCODE_CONFIG"] = config if File.exist?(config)
-          cmd = ["opencode", ".", "--agent", role, "--prompt", "Start your work loop now."]
-          Launcher.exec_or_die(cmd + (model ? ["--model", model] : []))
-        end
-      end
-
-      module Codex
-        def self.launch(role, _worker, model)
-          prompt_file = ".codex/prompts/#{role}.md"
-          abort "setup_agent: #{prompt_file} missing." unless File.exist?(prompt_file)
-
-          cmd = ["codex", *writable_dirs]
-          cmd += ["--model", model] if model
-          warn_untrusted
-          Launcher.exec_or_die(cmd + [File.read(prompt_file)])
-        end
-
-        UNTRUSTED = "maf: Codex does not trust the hooks in %<file>s yet. Trust them when Codex asks. " \
-                    "Without the hooks, the session records no token usage, and coord await cannot wake it."
-
-        # Codex runs the hooks of a project only after the user trusts them, and
-        # a worktree is a new project for Codex. Codex records the trust in its config.toml.
-        def self.warn_untrusted
-          hooks = File.join(File.realpath(Dir.pwd), ".codex", "hooks.json")
-          config = File.join(ENV.fetch("CODEX_HOME", File.join(Dir.home, ".codex")), "config.toml")
-          trusted = File.exist?(config) && File.read(config).include?("#{hooks}:stop:")
-          warn format(UNTRUSTED, file: hooks) if File.exist?(hooks) && !trusted
-        end
-
-        # The worktree is the only writable root of the Codex sandbox. coord
-        # writes the board and the artifacts in .maf/coordination of the main
-        # project, so Codex would ask for approval at each coord command.
-        def self.writable_dirs = ["--add-dir", File.join(SetupAgent::Project.root, ".maf", "coordination")]
+      def self.relay_or_die(cmd)
+        PtyRelay.new(cmd).run
+      rescue Errno::ENOENT
+        abort "setup_agent: '#{cmd.first}' not found on PATH."
       end
     end
   end

data/lib/maf/setup_agent/manifest.rb

@@ -26,10 +26,16 @@ module Maf
       # maf add keeps the current agents, so the hint names only the missing agent.
       def add_hint(missing) = "  Fix: maf add #{missing}"
 
-      def model_for(harness, role)
-        entry = @agents.find { |a| a["harness"] == harness && a["role"] == role }
-        entry && entry["model"]
+      # The saved model and effort of the agent, unless args already name them.
+      def fill(args)
+        verify!(args.harness, args.role)
+        saved = entry(args.harness, args.role)
+        args.model ||= saved["model"]
+        args.effort ||= saved["effort"]
+        args
       end
+
+      def entry(harness, role) = @agents.find { |a| a["harness"] == harness && a["role"] == role }
     end
   end
 end

data/lib/maf/setup_agent/pty_relay.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "pty"
+require "io/console"
+
+module Maf
+  module SetupAgent
+    # PtyRelay runs a command on its own pseudo terminal and copies the input and the output.
+    class PtyRelay
+      CHUNK = 4096
+      DRAIN = 0.5
+      SIGNALS = %w[TERM HUP INT].freeze
+      EOF = "\x04"
+
+      def initialize(cmd) = @cmd = cmd
+
+      def run
+        output, input, pid = PTY.spawn(*@cmd)
+        SIGNALS.each { |name| Signal.trap(name) { pass(name, pid) } }
+        relay(output, input, Process.detach(pid))
+      ensure
+        [output, input].compact.each(&:close)
+      end
+
+      private
+
+      def relay(output, input, waiter)
+        resize(input) && Signal.trap("WINCH") { resize(input) }
+        copiers = [Thread.new { copy_input(input) }, Thread.new { copy(output, $stdout) }]
+        raw { waiter.join }
+        stop(copiers)
+        waiter.value.exitstatus || 1
+      end
+
+      def stop(copiers)
+        copiers.last.join(DRAIN)
+        copiers.each(&:kill)
+      end
+
+      def copy(from, to)
+        loop { to.write(from.readpartial(CHUNK)) && to.flush }
+      rescue IOError, Errno::EIO
+        nil
+      end
+
+      # The end of the input is no end on a terminal, so the command gets ^D. Else `echo task | maf start` waits.
+      # After a line without a newline, the first ^D only sends the line, so the command gets a second one.
+      def copy_input(input)
+        last = send_input(input)
+        input.write(last.end_with?("\n") ? EOF : EOF * 2)
+      rescue IOError, Errno::EIO
+        nil
+      end
+
+      def send_input(input)
+        last = "\n"
+        loop { input.write(last = $stdin.readpartial(CHUNK)) && input.flush }
+      rescue EOFError
+        last
+      end
+
+      def pass(name, pid)
+        Process.kill(name, pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def raw(&block) = $stdin.tty? ? $stdin.raw(&block) : yield
+
+      def resize(input)
+        $stdout.tty? && (input.winsize = $stdout.winsize)
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/role_file.rb

@@ -8,7 +8,7 @@ module Maf
     # A harness folder with the project's own files gets one link per role file.
     module RoleFile
       def self.copy(root, dir, harness, role)
-        relative = Flow.role_path(harness, role)
+        relative = Maf::Shared::Harness.fetch(harness).role_path(role)
         return unless relative
 
         copy_missing(File.join(root, relative), File.join(dir, relative))

data/lib/maf/setup_agent/runtime_hooks.rb

@@ -8,18 +8,7 @@ module Maf
     module RuntimeHooks
       def self.install(dir, harness)
         %w[next-task.rb board-watch.rb session-guard.rb context-watch.rb].each { |name| copy(dir, name) }
-        configure(dir, harness)
-        copy(dir, "board-watch-opencode.js", ".opencode/plugins/board-watch.js") if harness == "opencode"
-      end
-
-      # Claude Code reads the hooks from the settings file of the main project
-      # (`maf start` passes it with --settings). The hook commands run in the
-      # worktree, where the copies above live.
-      def self.configure(dir, harness)
-        root = Project.root
-        settings = File.join(root, Bootstrap::CLAUDE_SETTINGS)
-        Bootstrap::ClaudeSettings.new(Bootstrap::Project.new(root, false)).configure(settings) if harness == "claude"
-        Flow::CodexHooks.new(dir).install if harness == "codex"
+        Maf::Shared::Harness.fetch(harness).runtime_hooks(dir)
       end
 
       def self.copy(dir, name, relative = ".maf/coordination/harness-hooks/#{name}")

data/lib/maf/setup_agent.rb

@@ -2,10 +2,11 @@
 
 # setup_agent.rb - create a worktree for one agent and launch its harness session.
 #
-# Usage: maf start HARNESS ROLE[_WORKER] [model:MODEL] [--model MODEL]
+# Usage: maf start HARNESS ROLE[_WORKER] [model:MODEL] [--model MODEL] [--effort LEVEL]
 #                  [--dispatch [DISPATCHER FLAGS...]]
 #   maf start claude backend-developer_1
 #   maf start opencode reviewer --model openrouter/deepseek-v3
+#   maf start claude architect --effort high
 #   maf start hermes tester --dispatch --model openrouter/deepseek-v3
 #   maf start claude reviewer --dispatch --cache-window 1500
 #
@@ -36,11 +37,10 @@ module Maf
     MANIFEST = ".maf/config.json"
 
     def self.run(argv)
-      args = Args.parse(argv)
-      manifest = Manifest.load(MANIFEST).tap { |m| m.verify!(args.harness, args.role) }
+      args = Manifest.load(MANIFEST).fill(Args.parse(argv))
       worktree = enter_worktree(args)
-      register(args, manifest.model_for(args.harness, args.role))
-      launch(args, manifest, worktree)
+      register(args)
+      launch(args, worktree)
     end
 
     # `maf start` without arguments, inside a worktree that `maf prepare` made.
@@ -56,12 +56,13 @@ module Maf
     def self.start_args(entry)
       args = [entry["harness"], "#{entry["role"]}_#{entry["worker_id"]}"]
       args += ["--model", entry["model"]] if entry["model"]
+      args += ["--effort", entry["effort"]] if entry["effort"]
       entry["dispatch"] ? args + ["--dispatch"] : args
     end
 
-    def self.register(args, saved_model)
+    def self.register(args)
       entry = { "role" => args.role, "worker_id" => args.worker_id, "harness" => args.harness,
-                "model" => args.model || saved_model, "dispatch" => args.dispatch, "dir" => Dir.pwd }
+                "model" => args.model, "effort" => args.effort, "dispatch" => args.dispatch, "dir" => Dir.pwd }
       Maf::Workers.at(Project.root).add(args.worker, entry.compact)
     end
 
@@ -79,13 +80,12 @@ module Maf
       worktree
     end
 
-    def self.launch(args, manifest, _worktree)
+    def self.launch(args, _worktree)
       identify(args)
-      model = args.model || manifest.model_for(args.harness, args.role)
-      return Dispatch.launch(args, model) if args.dispatch
+      return Dispatch.launch(args) if args.dispatch
 
       MafSession.register(Project.root, args.harness)
-      Launcher.for(args.harness).launch(args.role, args.worker, model)
+      Launcher.launch(Maf::Shared::Harness.fetch(args.harness), args.role, args.model, args.effort)
     end
 
     # The session and the dispatcher pass the environment to each child, so
@@ -104,8 +104,6 @@ require_relative "setup_agent/role_file"
 require_relative "setup_agent/manifest"
 require_relative "setup_agent/worktree"
 require_relative "setup_agent/launcher"
-require_relative "setup_agent/hermes_launcher"
 require_relative "setup_agent/project"
-require_relative "setup_agent/hermes_skill"
 require_relative "setup_agent/runtime_hooks"
 require_relative "../../assets/harness-hooks/session-guard"

data/lib/maf/shared/harness/base.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+require "erb"
+require "json"
+require_relative "defaults"
+require_relative "output"
+
+module Maf
+  module Shared
+    # Harness is the registry of the agent harnesses. Each file in harnesses/
+    # defines one harness: a subclass of Base. The rest of maf asks the
+    # registry and never names a harness.
+    module Harness
+      def self.register(klass) = (@classes ||= []) << klass
+      def self.all = @all ||= @classes.map(&:new).sort_by(&:name)
+      def self.names = all.map(&:name)
+      def self.[](name) = all.find { |harness| harness.name == name }
+      def self.fetch(name) = self[name] || raise(KeyError, "unknown harness '#{name}' (use #{names.join(", ")})")
+      def self.known?(name) = !self[name].nil?
+
+      def self.on_path?(command)
+        ENV["PATH"].to_s.split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, command)) }
+      end
+
+      # Base is the interface of a harness. A harness file overrides the
+      # methods that its CLI needs. Every other method keeps the default here.
+      # The methods are grouped by the part of maf that calls them.
+      class Base
+        def self.inherited(klass)
+          super
+          Harness.register(klass)
+        end
+
+        # The harness name in `maf add HARNESS:ROLE`. It comes from the class name.
+        def name = self.class.name.split("::").last.downcase
+        def to_s = name
+
+        # The CLI of the harness. `maf add` offers only the installed harnesses.
+        def command = name
+        def installed? = Harness.on_path?(command)
+
+        include RoleFiles
+        include Setup
+        include Run
+
+        # The tool calls of one session, for the analyst: [[name, command, size], ...].
+        def transcript_calls(_session_id) = []
+
+        # The JSON objects of a transcript file, one per line. A broken line is skipped.
+        def jsonl(path) = path ? File.foreach(path).filter_map { |line| Events.parse(line.strip) } : []
+      end
+    end
+  end
+end

data/lib/maf/shared/harness/defaults.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+require_relative "../project"
+require_relative "vm_credential"
+
+module Maf
+  module Shared
+    module Harness
+      AGENTS_DIR = File.join(".maf", "agents")
+      # The command of the graphify MCP server. It runs in the project folder.
+      VAULT_MCP = %w[ruby .maf/bin/vault mcp].freeze
+
+      # RoleFiles: maf add writes one role file per agent.
+      module RoleFiles
+        # The folder where the harness reads role files. maf links it to
+        # .maf/agents/<name>/. nil: the harness reads no role folder.
+        def role_dir = nil
+        def role_path(role) = role_dir && File.join(AGENTS_DIR, name, "#{role}.md")
+
+        # settings: the data of .maf/config.json. A harness that keeps role
+        # files outside the project reads its folder there.
+        def role_destination(project, role, _settings = {}) = role_path(role) && File.join(project, role_path(role))
+
+        # An ERB template. It gets role, title, description, can_edit, project, prompt, model, and effort.
+        def role_template = raise(NotImplementedError, "#{name}: role_template")
+        def render_role(values) = ERB.new(role_template, trim_mode: "-").result_with_hash(effort: nil, **values)
+
+        # nil: the harness lists no models, so every name counts as known.
+        def models = nil
+        # list: the models of the harness. A caller with a cached list passes it.
+        def known_model?(model, list = models) = list.nil? || list.include?(model)
+        def default_model = nil
+
+        # The command that sets the model, for a harness whose role file cannot set it.
+        def model_hint(_model) = nil
+
+        # nil: the harness lists no effort levels, so every level counts as known.
+        def efforts(_model = nil) = nil
+        def known_effort?(effort, model = nil) = efforts(model).nil? || efforts(model).include?(effort)
+        # true: the model runs only with a level.
+        def effort_required?(_model) = false
+
+        # How an idle agent waits for work. :watch - a watcher wakes the idle
+        # session. :await - the stop hook waits after `coord await`.
+        # :poll - the agent blocks in `coord next --wait`.
+        def wait = :poll
+
+        # One more rule line for the architect prompt, or nil.
+        def architect_rule = nil
+      end
+
+      # Setup: maf add, maf start, bootstrap, untrack, retire, and uninstall.
+      module Setup
+        # The graphify MCP server in a config file of the flow:
+        # { file: ".maf/mcp/x.json", key: "mcpServers", entry: {...} }. nil: no file.
+        def mcp = nil
+        # The command that adds the server to a global config of the harness, or nil.
+        def mcp_command(_server, _vault) = nil
+        # The project file where an older maf wrote the MCP server, or nil.
+        def legacy_mcp_file = nil
+
+        # maf add installs the hooks. A truthy result: the user has steps left.
+        def install_hooks(_project) = nil
+        # maf start refreshes the hooks in the worktree before the session starts.
+        def runtime_hooks(_worktree) = nil
+        # Bootstrap installs the hooks of the harness only if this folder exists.
+        def bootstrap_dir = nil
+
+        # Uninstall: objects with #steps that remove the files of the flow.
+        def cleaners(_project) = []
+        # Uninstall and untrack: objects with #steps that remove what an older
+        # maf wrote into the project's own files.
+        def legacy_cleaners(_project) = []
+        # Files outside the project that uninstall keeps: other projects can use them.
+        def global_files = []
+
+        def vm_install = nil
+        def vm_credentials = []
+        def vm_login_hint = "maf vm shell, then start #{command} and log in"
+
+        # The top folder of the harness. maf retire ignores changes in it.
+        def home_dir = role_dir&.split("/")&.first
+        # Files that the flow writes in a worktree. coord keeps them out of git.
+        def runtime_files = []
+        # Folders that uninstall removes when they are empty. Children come first.
+        def empty_dirs = [role_dir, home_dir].compact.uniq
+
+        # The paths that git tracks for the flow. tracked.call(path) lists the
+        # tracked files below path. By default, the links into .maf/agents/.
+        def untrack_paths(root, tracked)
+          return [] unless role_dir
+
+          tracked.call(role_dir).select do |path|
+            File.symlink?(File.join(root, path)) && File.readlink(File.join(root, path)).include?(AGENTS_DIR)
+          end
+        end
+      end
+
+      # Run: maf start (an interactive session) and the dispatcher (one run per task).
+      module Run
+        # The command of an interactive session.
+        def launch(_role, _model, _effort = nil) = raise(NotImplementedError, "#{name}: launch")
+        def launch_env = {}
+
+        def sandbox_dirs = []
+        def sandbox_state = []
+        def sandbox_prefixes = []
+        def sandbox_protected = []
+        def sandbox_project = []
+        def in_dir(dir, names) = names.map { |name| File.join(dir, name) }
+        def sandbox_placeholders = sandbox_protected.reject { |path| path.end_with?(".md", ".yaml") }
+        def sandboxed(cmd) = cmd
+
+        # The command of one dispatched run. session_id is nil for a fresh session.
+        def build_command(_config, _prompt, _session_id) = raise(NotImplementedError, "#{name}: build_command")
+        def run_env(_config) = {}
+        # The dispatcher calls it once after it parses the options.
+        def prepare(config) = config
+        # Seconds that the prompt cache of the harness stays warm, or nil for the default.
+        def cache_window = nil
+        def peak_rate?(_config) = false
+
+        # The parts of the run output. nil: the harness does not report it.
+        def stale_session?(_output) = false
+        def session_id(_output) = nil
+        def result_text(_output) = nil
+        def usage(_output) = nil
+        def context(_output) = nil
+        def model(_output) = nil
+
+        # A file of the flow in .maf/ of the main checkout. The dispatcher finds
+        # .maf/ next to its coordination folder, which COORD_DIR can move.
+        def flow_file(*parts) = File.join(Project.root, ".maf", *parts)
+        def run_file(config, *parts) = File.join(File.dirname(config.coord_dir), *parts)
+        def flag_if(flag, path) = File.exist?(path) ? [flag, path] : []
+
+        def present(value) = value.to_s.empty? ? nil : value
+        def model_flag(model, flag = "--model") = model ? [flag, model] : []
+        def effort_flag(effort, flag = "--effort") = effort ? [flag, effort] : []
+        def resume(session_id, *flag) = session_id ? [*flag, session_id] : []
+      end
+    end
+  end
+end