maf 0.2.0 → 0.4.0

data/assets/dispatcher

@@ -11,7 +11,7 @@
 #    dispatcher polls the inbox and the task board on a fixed interval.
 #
 # Usage:
-#   dispatcher ROLE (--harness NAME | --command TEMPLATE) [--model M]
+#   dispatcher ROLE (--harness NAME | --command TEMPLATE) [--model M] [--effort L]
 #                     [--skill NAME | --no-skill] [--interval S] [--max-turns N]
 #                     [--timeout S] [--idle-timeout S] [--grace S]
 #                     [--completion-signal TEXT] [--abort-signal TEXT]
@@ -31,10 +31,12 @@
 #                      (claude, codex, cursor, hermes, opencode). Each one
 #                      resumes sessions. --harness or --command is required.
 #   --command TEMPLATE Any other harness. A shell command with %{prompt},
-#                      %{role}, %{skill}, and %{model} placeholders, each
+#                      %{role}, %{skill}, %{model}, and %{effort} placeholders, each
 #                      shell-escaped. The command must exit when done.
 #                      Sessions are not resumed for custom commands.
 #   --model M          Model for the agent, in the harness CLI's own format.
+#   --effort L         Effort level of the model, in the harness CLI's own
+#                      format (for example high). Default: the harness default.
 #   --skill NAME       Hermes skill to preload. Default: <project>-<role> when
 #                      flow.rb generated it.
 #   --no-skill         Do not preload a skill.
@@ -99,7 +101,9 @@
 # atomic, so a run never starts for a task that another worker took. If the
 # same task set is still unclaimed afterwards, it waits with a doubling
 # backoff (capped at MAX_BACKOFF) before it tries again. A changed task set
-# dispatches at once.
+# dispatches at once. After MAX_ATTEMPTS runs in a row that leave a task
+# claimed and not done, the dispatcher blocks the task (`coord block --kind
+# failing`), which escalates it. A usage limit or an unknown model counts no run.
 #
 # Sessions and the prompt cache: the session ID is saved to
 # .maf/coordination/sessions/<worker>.session and resumed on the next run, so the
@@ -151,7 +155,7 @@ module Dispatcher
   MAX_BACKOFF = 3600
   REPORT_RETRIES = 1
 
-  Config = Struct.new(:role, :harness, :command, :model, :skill, :no_skill, :interval, :max_turns,
+  Config = Struct.new(:role, :harness, :command, :model, :effort, :skill, :no_skill, :interval, :max_turns,
                       :timeout, :idle_timeout, :grace, :completion_signal, :abort_signal,
                       :cache_window, :max_session_runs, :max_context, :once, :poll_tasks, :worker, :coord_dir,
                       :verbose, :lean,
@@ -171,6 +175,13 @@ module Dispatcher
     end
   end
 
+  def self.refuse_nested
+    return unless Maf::Shared::Sandbox.nested?
+
+    Log.line(Maf::Shared::Sandbox::NESTED.delete_prefix("maf: "))
+    exit 1
+  end
+
   # Project finds the main checkout from any worktree. Lead roles own no
   # tasks: they get an inbox prompt and no task polling.
   Project = Maf::Shared::Project
@@ -318,6 +329,49 @@ module Dispatcher
     end
   end
 
+  # FailureLimit counts the runs in a row that left a task claimed and not
+  # done. At MAX_ATTEMPTS it blocks the task, which escalates it. The count is in
+  # .maf/coordination/failures/<id>, so a restart keeps it.
+  class FailureLimit
+    NOTICE = "Task %<id>s is blocked: %<runs>d runs of %<worker>s in a row ended without coord done. " \
+             "Last result: %<last>s Fix the cause, then run `coord unblock %<id>s`."
+    UNCOUNTED = %i[limited broken].freeze
+
+    def initialize(config, poller, coord = ->(*args) { CoordCall.run(Main.run_env(config), *args) })
+      @config = config
+      @poller = poller
+      @coord = coord
+      @dir = File.join(config.coord_dir, "failures")
+    end
+
+    def track(ids, outcome)
+      return if UNCOUNTED.include?(outcome)
+
+      open = outcome == :waiting ? [] : @poller.claimed_task_ids
+      ids.each { |id| open.include?(id) ? count(id) : clear(id) }
+    end
+
+    def runs(id) = File.exist?(path(id)) ? File.read(path(id)).to_i : 0
+
+    private
+
+    def count(id)
+      runs = runs(id) + 1
+      runs >= MAX_ATTEMPTS ? block(id, runs) : save(id, runs)
+    end
+
+    def block(id, runs)
+      text = format(NOTICE, id: id, runs: runs, worker: @config.worker, last: Log.last.to_s[0, 200])
+      Log.line("task #{id}: #{runs} unfinished runs in a row; blocking it")
+      @coord.call("block", "--kind", "failing", id, text)
+      clear(id)
+    end
+
+    def save(id, runs) = FileUtils.mkdir_p(@dir) && File.write(path(id), runs.to_s)
+    def clear(id) = FileUtils.rm_f(path(id))
+    def path(id) = File.join(@dir, id)
+  end
+
   # Lessons reads the dead ends and corrections of graphify-out/reflections/
   # LESSONS.md for one task, newest first. coord done and coord lesson save the
   # notes that LESSONS.md sums up. A lesson stays when its note cites a node of
@@ -764,10 +818,11 @@ module Dispatcher
     module Generic
       extend Maf::Shared::Harness::Run
 
-      PLACEHOLDERS = %i[prompt role skill model].freeze
+      PLACEHOLDERS = %i[prompt role skill model effort].freeze
 
       def self.build_command(config, prompt, _session_id)
-        values = { prompt: prompt, role: config.role, skill: config.skill, model: config.model }
+        values = { prompt: prompt, role: config.role, skill: config.skill, model: config.model,
+                   effort: config.effort }
         line = PLACEHOLDERS.reduce(config.command) { |cmd, key| cmd.gsub("%{#{key}}") { values[key].to_s.shellescape } }
         ["sh", "-c", line]
       end
@@ -906,7 +961,7 @@ module Dispatcher
     def started(session_id, runs)
       save("mode" => "dispatch", "role" => @config.role, "harness" => @config.command ? "command" : @config.harness,
            "pid" => Process.pid, "running" => true, "run_started_at" => now, "session_id" => session_id,
-           "session_runs" => runs, "model" => @config.model || read["model"])
+           "session_runs" => runs, "model" => @config.model || read["model"], "effort" => @config.effort)
     end
 
     def finished(outcome, detail, model)
@@ -1309,6 +1364,7 @@ module Dispatcher
       Log.line("usage limit: no new run until #{@pause.until.utc}")
     end
     def chores = @chores ||= LeadChores.new(@poller, @config.role)
+    def failure_limit = @failure_limit ||= FailureLimit.new(@config, @poller)
 
     def start
       Log.line("started: role=#{@config.role} #{harness_label} #{timing_label}")
@@ -1337,11 +1393,8 @@ module Dispatcher
     # unknown model returns them without an attempt.
     SETTLE = { failed: :release, limited: :restore, broken: :restore }.freeze
 
-    # Tasks still unclaimed after a message run count as dispatched, so the
-    # next cycle backs off instead of starting another run for them.
     def settle(messages, outcome)
       @mailbox.public_send(SETTLE.fetch(outcome, :ack), messages)
-      @watch.dispatched(@poller.unclaimed_task_ids) if @config.poll_tasks
       true
     end
 
@@ -1350,7 +1403,7 @@ module Dispatcher
       ids = @poller.claimed_task_ids
       return false unless @resume.due?(ids)
 
-      dispatch(Prompt.resume(@config.role, ids) + context(ids.first))
+      failure_limit.track(ids, dispatch(Prompt.resume(@config.role, ids) + context(ids.first)))
       @resume.dispatched(ids)
       true
     end
@@ -1366,7 +1419,7 @@ module Dispatcher
     end
 
     def run_task(id)
-      dispatch(Prompt.task(@config.role, id) + context(id))
+      failure_limit.track([id], dispatch(Prompt.task(@config.role, id) + context(id)))
       true
     end
   end
@@ -1374,7 +1427,7 @@ module Dispatcher
   # Options parses the command line into a Config.
   module Options
     VALUES = { "--harness NAME" => [:harness, String], "--command TEMPLATE" => [:command, String],
-               "--model M" => [:model, String], "--skill NAME" => [:skill, String],
+               "--model M" => [:model, String], "--effort L" => [:effort, String], "--skill NAME" => [:skill, String],
                "--interval S" => [:interval, Integer], "--max-turns N" => [:max_turns, Integer],
                "--timeout S" => [:timeout, Integer], "--cache-window S" => [:cache_window, Integer],
                "--max-session-runs N" => [:max_session_runs, Integer], "--max-context N" => [:max_context, Integer],
@@ -1466,5 +1519,6 @@ if __FILE__ == $PROGRAM_NAME
   ENV["PATH"] = [File.dirname(File.expand_path(__FILE__)), ENV["PATH"]].compact.join(File::PATH_SEPARATOR)
   # Each run inherits the git persona of the agents.
   Maf::Shared::GitIdentity.apply(Dispatcher::Project.manifest)
+  Dispatcher.refuse_nested
   Dispatcher::Main.new(Dispatcher::Options.parse(ARGV)).run
 end

data/install.md

@@ -198,7 +198,12 @@ list with the existing entries plus the new entry.
 The second command approves the hook one time. Hermes stores the consent for this
 version of the script. A new script version needs a new approval.
 
-Confirm that every check from `hermes hooks doctor` passes. Then continue.
+Confirm that every check from `hermes hooks doctor` passes.
+
+Hermes gives the commands of an agent only the variables in
+`terminal.client_env_passthrough`. If `maf add` prints a `hermes config set
+terminal.client_env_passthrough` command, run it. It keeps the names that the
+list has now. Then continue.
 
 ## Step 5c - Set the Gemini key for the doc-graph refresh
 

data/lib/maf/backup.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# backup.rb - copies of the flow config in the git directory, and maf restore.
+require "fileutils"
+require "open3"
+require "time"
+
+module Maf
+  # Backup keeps copies of the files in .maf/ that maf update cannot make again.
+  # Each copy is a folder in .git/maf/backup/, so no checkout, merge, or reset
+  # changes it. A copy is made only when config.json exists and the files differ
+  # from the newest copy.
+  class Backup
+    FILES = %w[config.json roles.yml workflow.md sandbox.json].freeze
+    KEEP = 10
+    MISSING = "maf: .maf/config.json is missing. A backup from %<time>s has it. Run: maf restore"
+
+    def initialize(root)
+      @root = root
+      @dir = git_dir&.then { |dir| File.join(dir, "maf", "backup") }
+    end
+
+    def save
+      files = current
+      return if @dir.nil? || !files.key?("config.json") || files == read(latest)
+
+      write(File.join(@dir, Time.now.utc.strftime("%Y%m%dT%H%M%SZ")), files)
+      prune
+    end
+
+    def snapshots = @dir ? Dir.glob(File.join(@dir, "*")).select { |path| File.directory?(path) }.sort : []
+    def latest = snapshots.last
+    def find(name) = snapshots.find { |path| File.basename(path) == name }
+    def read(dir) = dir ? FILES.to_h { |name| [name, file(dir, name)] }.compact : {}
+    def time(dir) = Time.strptime(File.basename(dir), "%Y%m%dT%H%M%S%z").localtime.strftime("%Y-%m-%d %H:%M")
+
+    def warn_missing
+      maf = File.join(@root, ".maf")
+      return if !Dir.exist?(maf) || File.exist?(File.join(maf, "config.json")) || !read(latest).key?("config.json")
+
+      warn format(MISSING, time: time(latest))
+    end
+
+    private
+
+    def current = read(File.join(@root, ".maf"))
+    def file(dir, name) = File.file?(File.join(dir, name)) ? File.read(File.join(dir, name)) : nil
+
+    def write(dir, files)
+      FileUtils.mkdir_p(dir)
+      files.each { |name, text| File.write(File.join(dir, name), text) }
+    end
+
+    def prune = snapshots[0...-KEEP].each { |dir| FileUtils.rm_rf(dir) }
+
+    def git_dir
+      out, status = Open3.capture2("git", "-C", @root, "rev-parse", "--git-common-dir", err: File::NULL)
+      status.success? ? File.expand_path(out.strip, @root) : nil
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end

data/lib/maf/bootstrap/claude_settings.rb

@@ -2,9 +2,10 @@
 
 module Maf
   module Bootstrap
-    # ClaudeSettings plans and applies the Claude Code hooks in the settings
-    # file of the flow, .maf/claude/settings.json. `maf start` passes the file
-    # with --settings. Claude Code runs these hooks next to the project's own.
+    # ClaudeSettings plans and applies the Claude Code hooks and environment in
+    # the settings file of the flow, .maf/claude/settings.json. `maf start`
+    # passes the file with --settings. Claude Code runs these hooks next to the
+    # project's own. The --settings env wins over the env of the user settings.
     class ClaudeSettings
       def initialize(project)
         @project = project
@@ -12,23 +13,30 @@ module Maf
 
       def plan
         file = @project.path(CLAUDE_SETTINGS)
-        [@project.action(status(file), file, "#{file} (next-task + board-watch hooks)", :claude_stop_hook)]
+        [@project.action(status(file), file, "#{file} (next-task + board-watch hooks, env)", :claude_stop_hook)]
       end
 
       def configure(file)
         settings = read(file)
-        missing = missing_hooks(settings)
-        missing.each { |event, hook| add_hook(settings, event, hook) }
-        write(file, settings) unless missing.empty?
-        !missing.empty?
+        return false if current?(settings)
+
+        write(file, update(settings))
+        true
       end
 
       private
 
       def status(file)
-        File.exist?(file) && missing_hooks(read(file)).empty? ? :skip : :configure_claude_hook
+        File.exist?(file) && current?(read(file)) ? :skip : :configure_claude_hook
+      end
+
+      def update(settings)
+        missing_hooks(settings).each { |event, hook| add_hook(settings, event, hook) }
+        settings.merge("env" => (settings["env"] || {}).merge(CLAUDE_ENV))
       end
 
+      def current?(settings) = missing_hooks(settings).empty? && (settings["env"] || {}) >= CLAUDE_ENV
+
       def read(file)
         File.exist?(file) ? (JSON.parse(File.read(file)) rescue {}) : {}
       end

data/lib/maf/bootstrap.rb

@@ -64,6 +64,10 @@ module Maf
       end
     ].freeze
 
+    # Claude Code environment of a flow session. Agent teams stay off: with
+    # them on, a subagent that Claude names starts as a teammate.
+    CLAUDE_ENV = { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" => "0" }.freeze
+
     # The knowledge graph and the Obsidian vault, at the project root where graphify looks by default.
     GRAPH_DIR = "graphify-out"
 

data/lib/maf/budget.rb

@@ -44,6 +44,8 @@ module Maf
         if @max && count > @max
     end
 
+    def limited? = !@max.nil?
+
     def allowed?(harness, model)
       @allow.empty? || @allow.any? { |spec| [harness, "#{harness}:#{model}"].include?(spec) }
     end

data/lib/maf/cli.rb

@@ -12,7 +12,9 @@ require_relative "menu"
 require_relative "team"
 require_relative "team_command"
 require_relative "worker_control"
+require_relative "worker_list"
 require_relative "untrack"
+require_relative "restore"
 require_relative "vm"
 require_relative "version"
 
@@ -21,6 +23,7 @@ module Maf
 
   def self.flow(*args) = Flow::Generator.new(["--project", Dir.pwd, *args]).run
   def self.role_names = Flow::RoleCatalog.new(Dir.pwd).roles.keys
+  def self.role_effort(role) = Flow::RoleCatalog.new(Dir.pwd).roles.dig(role, "effort")
 
   def self.agents = File.exist?(MANIFEST) ? JSON.parse(File.read(MANIFEST)).fetch("agents") : []
   def self.agent_specs = agents.map { |a| "#{a["harness"]}:#{a["role"]}" }
@@ -38,23 +41,26 @@ module Maf
 
   class CLI
     COMMANDS = {
-      "add" => "[HARNESS:ROLE[:MODEL] ...] [--model ROLE=MODEL]  add agents and install the flow; " \
-               "without arguments it asks",
+      "add" => "[HARNESS:ROLE[:MODEL] ...] [--model ROLE=MODEL] [--effort ROLE=LEVEL]  add agents and install " \
+               "the flow; without arguments it asks",
       "remove" => "HARNESS:ROLE ...                        remove agents",
       "update" => "                                        regenerate the files of the current agents",
       "agents" => "                                        list the current agents",
       "roles" => "                                        list the built-in roles and the project roles",
       "role" => "add NAME                                add a stub role to .maf/roles.yml",
-      "start" => "[HARNESS ROLE[_WORKER]] [--dispatch [--detach]]  start one agent in its worktree",
-      "prepare" => "HARNESS ROLE[_WORKER] [--dispatch|--interactive] [--replace W]  prepare a worker; " \
+      "start" => "[HARNESS ROLE[_WORKER]] [--effort LEVEL] [--dispatch [--detach]]  start one agent in its worktree",
+      "prepare" => "HARNESS ROLE[_WORKER] [--effort LEVEL] [--dispatch|--interactive] [--replace W]  " \
+                   "prepare a worker; " \
                    "--dispatch starts it (default for the architect)",
       "retire" => "ROLE[_WORKER]                           remove a worker; its tasks return to the pool",
-      "worker" => "status|stop|start|restart ROLE[_WORKER] [--force] [--max-context N] [--max-session-runs N] " \
-                  "[--cache-window S]  control one worker; start and restart save the session limits of the role",
+      "worker" => "list | status|stop|start|restart ROLE[_WORKER] [--force] [--max-context N] " \
+                  "[--max-session-runs N] [--cache-window S]  list the running workers, or control one worker; " \
+                  "start and restart save the session limits of the role",
       "team" => "[set --max N --allow HARNESS[:MODEL]]   show the team, or set its budget",
       "uninstall" => "[--check] [--yes] [--force]             remove the flow from the project",
       "migrate" => "[--check] [--yes]                       move an old-layout install into .maf/",
       "untrack" => "[--check] [--yes]                       remove the flow from git; the files stay (then commit)",
+      "restore" => "[--list] [BACKUP] [--force]             put the flow config back from a backup in .git/maf/backup",
       "vm" => "create|login|start|stop|delete|status|shell [ARGS]  run the team in a Lima VM (macOS, Linux)",
       "menu" => "                                        interactive mode (also: maf without a command)",
       "guide" => "                                        print the setup guide for an AI agent (install.md)",
@@ -72,11 +78,26 @@ module Maf
       abort "maf: unknown command '#{@command}'. Run: maf help" unless COMMANDS.key?(@command)
       abort "maf: #{Migrate::HINT}" if old_layout?
 
-      send("run_#{@command}")
+      backed_up { send("run_#{@command}") }
     end
 
+    NO_BACKUP = %w[version guide roles].freeze
+
     private
 
+    def backed_up
+      backup = checked_backup unless NO_BACKUP.include?(@command)
+      yield
+    ensure
+      backup&.save
+    end
+
+    def checked_backup
+      backup = Backup.new(SetupAgent::Project.root)
+      backup.warn_missing unless @command == "restore"
+      backup.tap(&:save)
+    end
+
     # Every command except these needs the new layout.
     # maf uninstall --check previews the migration on an old layout.
     def old_layout?
@@ -95,7 +116,10 @@ module Maf
     # Without arguments on a terminal, maf add asks for the harness, the roles, and the models.
     def run_add = @args.empty? && $stdin.tty? ? Menu.new.add : Maf.flow(*AgentArgs.convert(@args, "--agent"))
     def run_remove = Maf.flow(*AgentArgs.convert(@args, "--remove"))
-    def run_update = Maf.flow(*@args)
+    def run_update
+      Maf.flow(*@args)
+      Untrack.warn_tracked(SetupAgent::Project.root)
+    end
     def run_roles = Maf.flow("--list-roles")
 
     def run_role
@@ -108,13 +132,15 @@ module Maf
     def run_prepare = Prepare.new(@args).run
     def run_team = TeamCommand.new(@args, SetupAgent::Project.root).run
     def run_worker
+      return WorkerList.new(SetupAgent::Project.root).run if @args.first == "list"
+
       spec = @args[1] || abort(worker_usage)
       limits = RoleLimits.parse(@args)
       WorkerControl.new(SetupAgent::Project.root, spec, force: @args.include?("--force"), limits: limits)
         .run(@args[0].to_s)
     end
 
-    def worker_usage = "usage: maf worker #{WorkerControl::ACTIONS.join("|")} ROLE[_WORKER] [--force] " \
+    def worker_usage = "usage: maf worker list | #{WorkerControl::ACTIONS.join("|")} ROLE[_WORKER] [--force] " \
                        "[--max-context N] [--max-session-runs N] [--cache-window S]"
     def run_retire = Retire.new(SetupAgent::Project.root, @args.first || abort("usage: maf retire ROLE[_WORKER]")).run
     def run_uninstall = Uninstall::Runner.new(["--project", Dir.pwd, *@args]).run
@@ -123,6 +149,7 @@ module Maf
     def run_guide = puts(File.read(File.join(Flow::ROOT, "install.md")))
     def run_version = puts("maf #{VERSION}")
     def run_untrack = Untrack.new(SetupAgent::Project.root, @args).run
+    def run_restore = Restore.new(SetupAgent::Project.root, @args).run
     def run_migrate = Migrate::Runner.new(["--project", Dir.pwd, *@args]).run
 
     def run_agents
@@ -132,7 +159,8 @@ module Maf
     end
 
     def agent_line(agent)
-      "#{agent["harness"]}:#{agent["role"]}".ljust(32) + agent["model"].to_s
+      effort = agent["effort"] && "effort=#{agent["effort"]}"
+      "#{agent["harness"]}:#{agent["role"]}".ljust(32) + [agent["model"], effort].compact.join(" ")
     end
   end
 end

data/lib/maf/flow/effort_report.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # EffortReport warns about an effort level that the harness does not list.
+    module EffortReport
+      def self.print(results)
+        list = results.select { |r| r[:effort] && !harness(r).known_effort?(r[:effort], r[:model]) }
+        return if list.empty?
+
+        puts "", "WARNING: the harness does not list these effort levels. Check the level for a typo:",
+             list.map { |r| "  #{name(r)} -> #{r[:effort]}" },
+             "  Fix one with: maf add HARNESS:ROLE --effort ROLE=LEVEL"
+      end
+
+      def self.harness(result) = Harness.fetch(result[:agent][:harness])
+      def self.name(result) = "#{result[:agent][:harness]}:#{result[:agent][:role]}"
+    end
+  end
+end

data/lib/maf/flow/generator.rb

@@ -26,6 +26,7 @@ module Maf
         Validator.project!(@options)
         @catalog = RoleCatalog.new(@options.project)
         @roles = @catalog.roles
+        @options.role_efforts = @roles.transform_values { |data| data["effort"] }
       end
 
       def generate_all
@@ -51,7 +52,7 @@ module Maf
 
       def print_role(key, data)
         puts "", "  #{key} (#{@catalog.source(key)})", "    #{data.fetch("description")}",
-             "    model hint: #{data.fetch("model_hint")}"
+             "    model hint: #{data.fetch("model_hint")}", *("    effort: #{data["effort"]}" if data["effort"])
       end
 
       def finish_without_agents

data/lib/maf/flow/hermes_env_setup.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Maf
+  module Flow
+    # HermesEnvSetup prints the step that lets Hermes give the flow variables to
+    # the commands of an agent. The flow never edits the Hermes config.
+    class HermesEnvSetup
+      KEY = "terminal.client_env_passthrough"
+      NAMES = %w[COORD_DIR COORD_ROLE COORD_WORKER COORD_DISPATCHED COORD_SLOT COORD_SESSION_PID TASKRC
+                 MAF_BIN].freeze
+
+      def initialize(config_yaml = File.join(Dir.home, ".hermes", "config.yaml"))
+        @config_yaml = config_yaml
+      end
+
+      # Returns true when the user has a step left.
+      def install
+        names = listed
+        return puts("  hermes env ready: #{KEY}") || false if (NAMES - names).empty?
+
+        print_step(names) || true
+      end
+
+      def command(names) = "hermes config set #{KEY} '#{JSON.generate((names + NAMES).uniq)}'"
+
+      def listed
+        list = config.dig("terminal", "client_env_passthrough")
+        list.is_a?(Array) ? list.map(&:to_s) : []
+      end
+
+      private
+
+      def print_step(names)
+        puts "", "  Hermes env: the commands of a Hermes agent get no COORD_* variables yet.",
+             "  Do this step one time. It keeps the names that the list has now.", "", "    #{command(names)}", ""
+      end
+
+      def config
+        data = YAML.safe_load_file(@config_yaml)
+        data.is_a?(Hash) ? data : {}
+      rescue SystemCallError, Psych::Exception
+        {}
+      end
+    end
+  end
+end

data/lib/maf/flow/manifest.rb

@@ -34,7 +34,7 @@ module Maf
       # a role without the role definitions.
       def entry(agent)
         { harness: agent[:harness], role: agent[:role], model: @options.model_for(agent),
-          can_edit: @roles.fetch(agent[:role]).fetch("can_edit") }
+          can_edit: @roles.fetch(agent[:role]).fetch("can_edit") }.merge({ effort: @options.effort_for(agent) }.compact)
       end
 
       # Other tools own other keys (maf team: "team"; users: "base_branch").

data/lib/maf/flow/models.rb

@@ -21,6 +21,17 @@ module Maf
 
       def self.known?(harness, model) = Harness[harness]&.known_model?(model, self.for(harness)) != false
       def self.default(harness) = Harness[harness]&.default_model
+      # Without a model, the levels of the default model of the harness.
+      def self.efforts(harness, model) = Harness[harness]&.efforts(model || default(harness))
+
+      # The level of the role if the harness lists it. A model that runs only
+      # with a level gets the lowest level instead.
+      def self.default_effort(harness, level, model)
+        levels = efforts(harness, model).to_a
+        return level if levels.include?(level)
+
+        levels.first if Harness[harness]&.effort_required?(model)
+      end
     end
   end
 end

data/lib/maf/flow/options.rb

@@ -4,8 +4,8 @@ module Maf
   module Flow
     # Options parses the command line and holds the settings of one run.
     class Options
-      attr_accessor :project, :agents
-      attr_reader :removed, :models, :hermes_dir, :list_roles
+      attr_accessor :project, :agents, :role_efforts
+      attr_reader :removed, :models, :efforts, :hermes_dir, :list_roles
 
       # Each flag: the OptionParser arguments, and a block that runs in the
       # Options instance with the flag value.
@@ -14,6 +14,7 @@ module Maf
         [["--agent SPEC", "HARNESS:ROLE[:MODEL]"], ->(v) { @agents << parse_agent(v) }],
         [["--remove SPEC", "HARNESS:ROLE"], ->(v) { @removed << parse_agent(v) }],
         [["--model PAIR", "ROLE=MODEL"], ->(v) { @models.store(*v.split("=", 2)) }],
+        [["--effort PAIR", "ROLE=LEVEL"], ->(v) { @efforts.store(*v.split("=", 2)) }],
         [["--hermes-dir DIR"], ->(v) { @hermes_dir = File.expand_path(v) }],
         [["--check"], ->(_) { @check = true }],
         [["--force"], ->(_) { @force = true }],
@@ -22,7 +23,8 @@ module Maf
       ].freeze
 
       def initialize(argv)
-        @argv, @agents, @removed, @models = argv, [], [], {}
+        @argv, @agents, @removed, @models, @efforts = argv, [], [], {}, {}
+        @role_efforts = {}
         @check = @force = @list_roles = false
         @bootstrap = true
       end
@@ -48,8 +50,32 @@ module Maf
         agent[:model] || @models[agent[:role]] || agent[:saved_model] || Harness[agent[:harness]]&.default_model
       end
 
+      # An empty --effort ROLE= clears the level: the harness default applies.
+      # A saved level belongs to the saved model, so a new model gets the role default.
+      def effort_for(agent)
+        flag = effort_flag(agent)
+        return (flag unless flag.empty?) if flag
+
+        (agent[:saved_effort] unless model_changed?(agent)) ||
+          Models.default_effort(agent[:harness], @role_efforts[agent[:role]], model_for(agent))
+      end
+
       private
 
+      # --effort ROLE=LEVEL applies to the agents of this run. Without one of
+      # the role, it applies to the saved agents of the role.
+      def effort_flag(agent)
+        role = agent[:role]
+        @efforts[role] if run_agent?(agent) || @agents.none? { |a| a[:role] == role && run_agent?(a) }
+      end
+
+      def run_agent?(agent) = agent.key?(:model)
+
+      def model_changed?(agent)
+        chosen = agent[:model] || @models[agent[:role]]
+        chosen && chosen != agent[:saved_model]
+      end
+
       def parser
         OptionParser.new do |o|
           o.banner = "Usage: maf add|remove|update [HARNESS:ROLE ...] [options]"