maf 0.1.0 → 0.3.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]
@@ -19,20 +19,24 @@
 #                     [--no-poll-tasks]
 #                     [--full-harness] [--once] [--verbose]
 #
-#   dispatcher tester                            # hermes (default)
+#   dispatcher tester --harness hermes
 #   dispatcher reviewer --harness claude --model sonnet
 #   dispatcher backend-developer --harness opencode --model openrouter/qwen3-coder
 #   dispatcher reviewer --harness codex
-#   dispatcher reviewer --once                   # one poll cycle, then exit
+#   dispatcher reviewer --harness cursor --model gpt-5
+#   dispatcher reviewer --harness claude --once  # one poll cycle, then exit
 #
 # Flags:
-#   --harness NAME     Built-in adapter: hermes (default), claude, codex, or
-#                      opencode. Each one resumes sessions.
+#   --harness NAME     A built-in harness: one file in .maf/lib/maf/shared/harnesses/
+#                      (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.
@@ -53,7 +57,8 @@
 #   --abort-signal TEXT  The agent prints TEXT when it gives up. The run is a
 #                      failure. Default: off.
 #   --cache-window S   Resume a session only if its last run ended less than
-#                      S seconds ago. Default: 300 for codex, else 3300
+#                      S seconds ago. Default: the cache window of the harness
+#                      (codex: 300), else 3300
 #                      (55 minutes). 0 means never resume.
 #   --max-session-runs N  Start a fresh session after N runs in one session
 #                      (default: 5). Each resume sends the whole old context
@@ -96,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
@@ -136,6 +143,8 @@ begin
   require_relative "../lib/maf/shared/roles"
   require_relative "../lib/maf/shared/peak_rate"
   require_relative "../lib/maf/shared/git_identity"
+  require_relative "../lib/maf/shared/harness"
+  require_relative "../lib/maf/shared/sandbox"
 rescue LoadError
   abort "dispatcher: the maf shared library is missing. Run maf update."
 end
@@ -146,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,29 +180,6 @@ module Dispatcher
   Project = Maf::Shared::Project
   LEADS = Maf::Shared::Roles::LEADS
 
-  # FlowConfig finds the MCP config of the flow in .maf/mcp/ (next to the
-  # coordination folder). The project's .mcp.json and opencode.json stay as
-  # they are. NOTE: lib/maf/setup_agent/launcher.rb passes the same files.
-  module FlowConfig
-    def self.path(config, name) = File.join(File.dirname(config.coord_dir), "mcp", name)
-    def self.claude_mcp(config) = File.exist?(file = path(config, "claude.json")) ? ["--mcp-config", file] : []
-
-    def self.opencode_env(config)
-      file = path(config, "opencode.json")
-      File.exist?(file) ? { "OPENCODE_CONFIG" => file } : {}
-    end
-  end
-
-  # EditGrant reads each agent's can_edit from .maf/config.json. On Hermes,
-  # a role with can_edit false starts without the file-writing toolsets.
-  module EditGrant
-    READ_ONLY_TOOLSETS = Maf::Shared::Roles::READ_ONLY_TOOLSETS
-
-    def self.read_only?(role)
-      Project.manifest.fetch("agents", []).any? { |agent| agent["role"] == role && agent["can_edit"] == false }
-    end
-  end
-
   # Presence writes .maf/coordination/presence/<worker>.json once per cycle, so
   # `coord who` shows the dispatcher as live while its pid runs.
   module Presence
@@ -210,17 +196,6 @@ module Dispatcher
     end
   end
 
-  # HermesSkill resolves the skill flow.rb generated for a role: the name is
-  # <project>-<role>, and the dir is the manifest's hermes_dir (set by
-  # `flow.rb --hermes-dir`) or flow.rb's default ~/.hermes/skills.
-  module HermesSkill
-    DEFAULT_DIR = File.join(Dir.home, ".hermes", "skills")
-
-    def self.name(role) = "#{File.basename(Project.root)}-#{role}"
-    def self.dir = Project.manifest.fetch("hermes_dir", DEFAULT_DIR)
-    def self.installed?(role) = File.exist?(File.join(dir, name(role), "SKILL.md"))
-  end
-
   # Session persists the agent's session ID across runs, per worker: two
   # dispatchers for one role (different COORD_WORKER values) never share a
   # session or a handoff note. The session file's mtime is the time of the
@@ -347,6 +322,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
@@ -532,10 +550,7 @@ module Dispatcher
   # CoordCall runs coord with this Ruby, so an old system Ruby on the
   # shebang path never parses it.
   module CoordCall
-    def self.command
-      local = File.expand_path(COORD_BIN)
-      [RbConfig.ruby, File.executable?(local) ? local : File.join(Project.root, COORD_BIN)]
-    end
+    def self.command = [RbConfig.ruby, File.join(Project.root, COORD_BIN)]
 
     # Returns true when the command succeeds.
     def self.run(env, *args)
@@ -676,10 +691,25 @@ module Dispatcher
 
     def self.run(cmd, env:, timeout:, limits: Limits.new(0, GRACE))
       reader, writer = IO.pipe
-      pid = Process.spawn(env, *cmd, in: File::NULL, out: writer, err: writer, pgroup: true)
+      pid = start(env, cmd, writer)
       collect(pid, Stream.new(reader.tap { writer.close }), Watch.new(timeout, limits))
-    rescue Errno::ENOENT => e
-      Result.new(e.message, false, false, :missing)
+    end
+
+    def self.start(env, cmd, writer)
+      ready, done = IO.pipe
+      pid = fork { session_exec(env, cmd, writer, done) }
+      done.close
+      ready.read && ready.close
+      pid
+    end
+
+    def self.session_exec(env, cmd, writer, done)
+      Process.setsid
+      done.close
+      exec(env, *cmd, in: File::NULL, out: writer, err: writer)
+    rescue StandardError => e
+      writer.write(e.message)
+      exit!(127)
     end
 
     def self.collect(pid, stream, watch)
@@ -704,55 +734,16 @@ module Dispatcher
     end
   end
 
-  # Events reads the JSON event lines of a harness run. Each adapter takes
-  # its session ID from one specific event, never from free text, so a
-  # prompt or a handoff note that the agent echoes cannot supply a false ID.
-  module Events
-    def self.all(output) = output.lines.filter_map { |line| parse(line.strip) }
-
-    def self.last(output, &match) = all(output).reverse.find(&match) || {}
+  Events = Maf::Shared::Harness::Events
 
-    def self.parse(line)
-      event = line.start_with?("{") ? JSON.parse(line) : nil
-      event.is_a?(Hash) ? event : nil
-    rescue JSON::ParserError
-      nil
-    end
-  end
-
-  # TokenUsage reads the token usage of one run and adds it to the totals of
-  # the worker in .maf/coordination/usage/<worker>.json. Claude Code, Hermes,
-  # Codex, and opencode report usage. A run without usage data adds nothing. A usage error
-  # never fails a run.
-  #
-  # input_tokens counts every input token, cache reads included.
-  # cached_input_tokens counts the cache reads, which cost a fraction of the
-  # input price. cache_write_input_tokens counts the cache writes, which cost
-  # more than the input price. A resume with a large cache write found a cold
-  # cache: the --cache-window is too long for the harness. Claude Code reports
-  # cache reads and cache writes outside its input_tokens, so they are added.
-  # Codex reports them inside.
+  # TokenUsage adds the token usage of one run to the totals of the worker in
+  # .maf/coordination/usage/<worker>.json. Each harness reads the usage of its
+  # run (Maf::Shared::Harness::Usage gives it one shape). A run without usage
+  # data adds nothing. A usage error never fails a run. A resume with a large
+  # cache write found a cold cache: the --cache-window is too long for the harness.
   class TokenUsage
-    def self.normalize(data)
-      return nil unless data.is_a?(Hash)
-
-      { "input_tokens" => input(data),
-        "cached_input_tokens" => int(data, "cached_input_tokens", "cache_read_input_tokens"),
-        "cache_write_input_tokens" => int(data, "cache_write_input_tokens", "cache_creation_input_tokens"),
-        "output_tokens" => int(data, "output_tokens", "completion_tokens") }
-    end
-
-    def self.input(data)
-      int(data, "input_tokens", "prompt_tokens") + int(data, "cache_read_input_tokens") +
-        int(data, "cache_creation_input_tokens")
-    end
-
-    def self.int(data, *names) = data.values_at(*names).compact.first.to_i
-
     def self.label(usage) = usage.map { |key, value| "#{key.delete_suffix("_tokens")}=#{value}" }.join(" ")
 
-    def self.sum(list) = list.empty? ? nil : list.reduce { |total, usage| total.merge(usage) { |_, a, b| a + b } }
-
     def initialize(coord_dir, worker)
       @path = File.join(coord_dir, "usage", "#{worker}.json")
     end
@@ -802,205 +793,40 @@ module Dispatcher
                    "cache_window" => @config.cache_window }
   end
 
-  # PeakRate tells when a dispatched opencode run uses DeepSeek at the peak
-  # rate (Maf::Shared::PeakRate). The notice can show on a Chinese holiday.
+  # PeakRate tells when a dispatched run uses a model at its peak rate
+  # (Maf::Shared::PeakRate). The notice can show on a Chinese holiday.
   module PeakRate
-    def self.deepseek?(config) = config.harness == "opencode" && OpencodeModel.for(config).to_s.include?("deepseek")
-
     def self.notice(config, time = Time.now.utc)
-      return unless Maf::Shared::PeakRate.peak?(time) && deepseek?(config)
+      return unless Maf::Shared::PeakRate.peak?(time) && Harness.for(config).peak_rate?(config)
 
       "info: DeepSeek peak hours (#{time.strftime("%H:%M")} UTC): this run costs 2x the off-peak rate"
     end
   end
 
-  # OpencodeModel finds the model of an opencode run in the opencode order:
-  # --model, the agent file, the project config, the user config.
-  module OpencodeModel
-    CONFIG_MODEL = /^\s*"model"\s*:\s*"([^"]+)"/
-    AGENT_MODEL = /\A---\n(?:(?!^---$).)*?^model:\s*(\S+)/m
-
-    def self.for(config) = config.model || agent(config.role) || configured
-    def self.agent(role) = find(File.join(".opencode", "agents", "#{role}.md"), AGENT_MODEL)
-    def self.configured = config_paths.lazy.filter_map { |path| find(path, CONFIG_MODEL) }.first
-    def self.config_paths = %w[opencode.json opencode.jsonc] + user_paths
-    def self.user_paths = %w[opencode.jsonc opencode.json].map { |name| File.join(home, name) }
-    def self.home = File.join(ENV.fetch("XDG_CONFIG_HOME", File.join(Dir.home, ".config")), "opencode")
-    def self.find(path, pattern) = File.exist?(path) ? File.read(path)[pattern, 1] : nil
-  end
-
+  # Harness picks the harness of a run. Each built-in harness is one file in
+  # lib/maf/shared/harnesses/ (installed in .maf/lib/maf/shared/harnesses/).
+  # Generic runs a user-provided shell template.
   module Harness
-    # Adapter is the part every built-in adapter shares. Each adapter sets
-    # STALE_SESSION to the error its CLI prints for an unknown session ID.
-    module Adapter
-      def stale_session?(output) = output.include?(self::STALE_SESSION)
-      def resume(session_id, *flag) = session_id ? [*flag, session_id] : []
-      def present(value) = value.to_s.empty? ? nil : value
-      def usage(_output) = nil
-      def context(_output) = nil
-      def model(_output) = nil
-    end
-
-    # Hermes: `hermes chat --oneshot`, JSONL output, skill preload.
-    module Hermes
-      extend Adapter
-      STALE_SESSION = "Session not found"
-
-      def self.build_command(config, prompt, session_id)
-        cmd = %w[hermes chat --oneshot --yolo --format stream-json -Q] + options(config)
-        cmd += ["--max-turns", config.max_turns.to_s, "--run-budget", run_budget(config).to_s]
-        cmd + resume(session_id, "--resume") + ["-q", prompt]
-      end
-
-      def self.options(config)
-        tools = EditGrant.read_only?(config.role) ? ["-t", EditGrant::READ_ONLY_TOOLSETS] : []
-        [*(["--skills", config.skill] if config.skill), *(["--model", config.model] if config.model), *tools]
-      end
-
-      # Stop Hermes before the dispatcher's kill, so it can still write its result event.
-      def self.run_budget(config) = [config.timeout - Spawn::GRACE, 1].max
-      def self.result_event(output) = Events.last(output) { |event| event["type"] == "result" }
-      def self.result_text(output) = result_event(output)["text"]
-      def self.session_id(output) = present(result_event(output)["session_id"])
-      def self.usage(output) = TokenUsage.normalize(result_event(output)["usage"])
-    end
-
-    # Claude Code: `claude -p` prints one JSON object with session_id and
-    # result. `--agent` loads .claude/agents/<role>.md as the session's role.
-    # `--mcp-config` takes many values. Put `--` before the prompt, or claude
-    # reads the prompt as one more config file and exits.
-    module Claude
-      extend Adapter
-      STALE_SESSION = "No conversation found with session ID"
-
-      # LEAN starts no MCP server outside --mcp-config and lists no skill.
-      # The user's CLAUDE.md and hooks stay.
-      LEAN = %w[--strict-mcp-config --disable-slash-commands].freeze
-
-      def self.build_command(config, prompt, session_id)
-        cmd = %w[claude -p --output-format json --permission-mode bypassPermissions --agent] + [config.role]
-        cmd += ["--model", config.model] if config.model
-        cmd += LEAN if config.lean
-        cmd + FlowConfig.claude_mcp(config) + resume(session_id, "--resume") + ["--", prompt]
-      end
-
-      def self.result_event(output) = Events.last(output) { |event| event.key?("result") }
-      def self.result_text(output) = result_event(output)["result"]
-      def self.session_id(output) = present(result_event(output)["session_id"])
-      def self.usage(output) = TokenUsage.normalize(result_event(output)["usage"])
-      # The result names each model that the run used. The main model comes first.
-      def self.model(output) = result_event(output)["modelUsage"]&.keys&.first
-    end
-
-    # Codex: `codex exec` (or `codex exec resume ID`) with JSONL events. Codex
-    # has no agent flag, so a fresh session gets .codex/prompts/<role>.md
-    # in front of the prompt. A resumed session already has it.
-    module Codex
-      extend Adapter
-      STALE_SESSION = "no rollout found for thread id"
-
-      def self.build_command(config, prompt, session_id)
-        cmd = %w[codex exec] + (session_id ? ["resume"] : [])
-        cmd += %w[--json --skip-git-repo-check --dangerously-bypass-approvals-and-sandbox]
-        cmd += ["-m", config.model] if config.model
-        cmd += Lean.flags if config.lean
-        cmd + resume(session_id) + [session_id ? prompt : role_prompt(config.role) + prompt]
-      end
-
-      # Lean drops the parts of the user's Codex setup that a one-shot run
-      # does not use. Each one adds tool schemas, skill lists, or MCP calls
-      # to every model call. Only the graphify server of this project stays.
-      module Lean
-        FEATURES = %w[plugins apps browser_use computer_use multi_agent].freeze
-        SERVER = /^\[mcp_servers\.([\w-]+)\]\s*$/
-
-        def self.flags = FEATURES.flat_map { |name| ["--disable", name] } + servers.flat_map { |name| off(name) }
-        def self.off(name) = ["-c", "mcp_servers.#{name}.enabled=false"]
-        def self.servers = File.exist?(config_path) ? File.read(config_path).scan(SERVER).flatten.uniq - [keep] : []
-        def self.keep = "graphify-#{File.basename(Project.root)}"
-        def self.config_path = File.join(ENV.fetch("CODEX_HOME", File.join(Dir.home, ".codex")), "config.toml")
-      end
-
-      def self.role_prompt(role)
-        path = File.join(".codex", "prompts", "#{role}.md")
-        File.exist?(path) ? "#{File.read(path)}\n\n" : ""
-      end
-
-      def self.result_text(output)
-        Events.last(output) { |event| event.dig("item", "type") == "agent_message" }.dig("item", "text")
-      end
-
-      def self.session_id(output)
-        present(Events.last(output) { |event| event["type"] == "thread.started" }["thread_id"])
-      end
-
-      # Codex reports the usage of each turn in a turn.completed event.
-      def self.usage(output)
-        turns = Events.all(output).select { |event| event["type"] == "turn.completed" }
-        TokenUsage.sum(turns.filter_map { |event| TokenUsage.normalize(event["usage"]) })
-      end
-    end
-
-    # opencode: `opencode run --format json`. `--agent` loads
-    # .opencode/agents/<role>.md. The result event shape is not verified, so
-    # the log shows no result text. opencode prints terminal escape codes and
-    # can glue two JSON objects onto one line, so the session ID is matched on
-    # the start of an event object (captured from a real run), not by parsing
-    # whole lines.
-    module Opencode
-      extend Adapter
-      STALE_SESSION = "Session not found"
-      EVENT_SESSION = /\{"type":"[\w.-]+","timestamp":\d+,"sessionID":"([^"]+)"/
-
-      def self.session_id(output) = output.scan(EVENT_SESSION).flatten.last
-
-      def self.build_command(config, prompt, session_id)
-        cmd = %w[opencode run --format json --agent] + [config.role]
-        cmd += ["-m", config.model] if config.model
-        cmd + resume(session_id, "--session") + [prompt]
-      end
-
-      def self.result_text(_output) = nil
-
-      # Each model call ends with a step_finish event. Its tokens.input
-      # excludes the cache reads and writes; reasoning is billed as output.
-      STEP_FINISH = /\{"type":"step_finish".*/
-
-      def self.steps(output) = output.scan(STEP_FINISH).filter_map { |json| Events.parse(json)&.dig("part", "tokens") }
-      def self.usage(output) = TokenUsage.sum(steps(output).map { |tokens| TokenUsage.normalize(flat(tokens)) })
-      def self.context(output) = steps(output).last&.then { |tokens| TokenUsage.input(flat(tokens)) }
-
-      def self.flat(tokens)
-        { "input_tokens" => tokens["input"].to_i, "cache_read_input_tokens" => tokens.dig("cache", "read").to_i,
-          "cache_creation_input_tokens" => tokens.dig("cache", "write").to_i,
-          "output_tokens" => tokens["output"].to_i + tokens["reasoning"].to_i }
-      end
-    end
-
     # Generic: a user-provided shell template. No session resume, no parsing.
     module Generic
-      PLACEHOLDERS = %i[prompt role skill model].freeze
+      extend Maf::Shared::Harness::Run
+
+      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
-
-      def self.stale_session?(_output) = false
-      def self.session_id(_output) = nil
-      def self.result_text(_output) = nil
-      def self.usage(_output) = nil
-      def self.context(_output) = nil
-      def self.model(_output) = nil
     end
 
-    REGISTRY = { "hermes" => Hermes, "claude" => Claude, "codex" => Codex, "opencode" => Opencode }.freeze
-
     def self.for(config)
       return Generic if config.command
 
-      REGISTRY.fetch(config.harness) { abort "dispatcher: unknown harness '#{config.harness}'. Use --command." }
+      Maf::Shared::Harness[config.harness] ||
+        abort("dispatcher: unknown harness '#{config.harness}' (use #{Maf::Shared::Harness.names.join(", ")}). " \
+              "For another harness, use --command.")
     end
   end
 
@@ -1060,7 +886,13 @@ module Dispatcher
       command = Project.manifest["verify"].to_s
       return true if command.empty? || LEADS.include?(config.role)
 
-      check(Spawn.run(["sh", "-c", command], env: env, timeout: config.timeout), command)
+      sandbox = Maf::Shared::Sandbox
+      run = -> { Spawn.run(sandboxed(command, config), env: env, timeout: config.timeout) }
+      check(sandbox.keeping_links(Harness::Generic, coord_dir: config.coord_dir, &run), command)
+    end
+
+    def self.sandboxed(command, config)
+      Maf::Shared::Sandbox.wrap(["sh", "-c", command], Harness::Generic, coord_dir: config.coord_dir)
     end
 
     def self.check(result, command)
@@ -1122,7 +954,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)
@@ -1256,10 +1088,14 @@ module Dispatcher
       spawn(@harness.build_command(@config, text, session_id))
     end
 
+    def sandboxed(cmd) = Maf::Shared::Sandbox.wrap(cmd, @harness, coord_dir: @config.coord_dir)
+    def keeping_links(&block) = Maf::Shared::Sandbox.keeping_links(@harness, coord_dir: @config.coord_dir, &block)
+
     def session_label(id) = id ? "#{id}, idle #{(@session.idle_seconds / 60).round}m" : "new"
 
     def spawn(cmd)
-      result = Spawn.run(cmd, env: @env, timeout: @config.timeout, limits: Limits.from(@config))
+      limits = Limits.from(@config)
+      result = keeping_links { Spawn.run(sandboxed(cmd), env: @env, timeout: @config.timeout, limits: limits) }
       record(@harness.usage(result.output), result.output)
       @model = @harness.model(result.output) || @model
       result
@@ -1458,7 +1294,7 @@ module Dispatcher
       env = { "COORD_DIR" => config.coord_dir, "COORD_ROLE" => config.role, "COORD_WORKER" => config.worker,
               "COORD_DISPATCHED" => "1", "PWD" => Dir.pwd }
       taskrc = File.join(config.coord_dir, "taskrc")
-      env.merge(File.exist?(taskrc) ? { "TASKRC" => taskrc } : {}, FlowConfig.opencode_env(config))
+      env.merge(File.exist?(taskrc) ? { "TASKRC" => taskrc } : {}, Harness.for(config).run_env(config))
     end
 
     def run
@@ -1521,9 +1357,11 @@ 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}")
+      Log.line("sandbox: #{Maf::Shared::Sandbox.describe(Harness.for(@config), coord_dir: @config.coord_dir)}")
       @mailbox.recover
       @stop = StopSignal.new
     end
@@ -1548,11 +1386,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
 
@@ -1561,7 +1396,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
@@ -1577,7 +1412,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
@@ -1585,7 +1420,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],
@@ -1595,7 +1430,7 @@ module Dispatcher
     SWITCHES = { "--no-skill" => [:no_skill, true], "--no-poll-tasks" => [:poll_tasks, false],
                  "--full-harness" => [:lean, false],
                  "--once" => [:once, true], "--verbose" => [:verbose, true] }.freeze
-    DEFAULTS = { harness: "hermes", interval: 60, max_turns: 50, idle_timeout: 0, grace: Spawn::GRACE,
+    DEFAULTS = { interval: 60, idle_timeout: 0, grace: Spawn::GRACE,
                  poll_tasks: true, lean: true,
                  no_skill: false, once: false, verbose: false }.freeze
 
@@ -1603,16 +1438,15 @@ module Dispatcher
     DEFAULT_SESSION_RUNS = 5
     DEFAULT_CONTEXT = 150_000
 
-    # Claude Code caches for 1 hour. The OpenAI cache of Codex is best effort:
-    # a probe missed it after 5 idle minutes. A cold resume costs more than a
-    # fresh session with the handoff note.
-    CACHE_WINDOWS = { "codex" => 300 }.freeze
+    # Claude Code caches for 1 hour. A harness with a shorter cache sets its
+    # cache_window. A cold resume costs more than a fresh session with the handoff note.
     DEFAULT_CACHE_WINDOW = 3300
 
     def self.parse(argv, env = ENV)
       config = Config.new(**DEFAULTS)
       parser(config).parse!(argv)
       config.role = argv.shift || abort("dispatcher: role is required (usage: dispatcher ROLE)")
+      abort "dispatcher: --harness NAME or --command TEMPLATE is required" unless config.harness || config.command
       validate(finish(config, env))
     end
 
@@ -1650,7 +1484,7 @@ module Dispatcher
       config.coord_dir = File.expand_path(env.fetch("COORD_DIR", ".maf/coordination"))
       config.worker = env.fetch("COORD_WORKER", "#{config.role}-bot")
       config.poll_tasks = false if LEADS.include?(config.role)
-      skill(limits(config))
+      Harness.for(config).prepare(limits(config))
     end
 
     def self.limits(config)
@@ -1662,19 +1496,14 @@ module Dispatcher
     # "team": { "limits": { "frontend-developer": { "max_context": 80000 } } }.
     # `maf worker restart ID --max-context N` writes them. A command-line flag wins.
     # NOTE: assets/dashboard reads the limits of each run from the run history.
+    def self.cache_window(config) = Harness.for(config).cache_window || DEFAULT_CACHE_WINDOW
+
     def self.session_limits(config, saved)
-      config.cache_window ||= saved["cache_window"] || CACHE_WINDOWS.fetch(config.harness, DEFAULT_CACHE_WINDOW)
+      config.cache_window ||= saved["cache_window"] || cache_window(config)
       config.max_session_runs ||= saved["max_session_runs"] || DEFAULT_SESSION_RUNS
       config.max_context ||= saved["max_context"] || DEFAULT_CONTEXT
       config
     end
-
-    # --no-skill drops a skill. Without --skill, the generated Hermes skill of the role loads.
-    def self.skill(config)
-      config.skill = nil if config.no_skill
-      config.skill ||= HermesSkill.name(config.role) if !config.no_skill && HermesSkill.installed?(config.role)
-      config
-    end
   end
 end