maf 0.1.0

data/assets/dispatcher

@@ -0,0 +1,1687 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# dispatcher - task board and inbox monitor that starts one-shot agents.
+#
+# The dispatcher solves two problems:
+# 1. A long-lived interactive agent session burns tokens while idle. The
+#    dispatcher starts an agent only when there is work, and the agent exits
+#    when the work is done (one-shot mode).
+# 2. An agent that stops has no external watcher to restart it. The
+#    dispatcher polls the inbox and the task board on a fixed interval.
+#
+# Usage:
+#   dispatcher ROLE [--harness NAME | --command TEMPLATE] [--model M]
+#                     [--skill NAME | --no-skill] [--interval S] [--max-turns N]
+#                     [--timeout S] [--idle-timeout S] [--grace S]
+#                     [--completion-signal TEXT] [--abort-signal TEXT]
+#                     [--cache-window S] [--max-session-runs N] [--max-context N]
+#                     [--no-poll-tasks]
+#                     [--full-harness] [--once] [--verbose]
+#
+#   dispatcher tester                            # hermes (default)
+#   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
+#
+# Flags:
+#   --harness NAME     Built-in adapter: hermes (default), claude, codex, or
+#                      opencode. Each one resumes sessions.
+#   --command TEMPLATE Any other harness. A shell command with %{prompt},
+#                      %{role}, %{skill}, and %{model} 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.
+#   --skill NAME       Hermes skill to preload. Default: <project>-<role> when
+#                      flow.rb generated it.
+#   --no-skill         Do not preload a skill.
+#   --interval S       Poll interval in seconds (default: 60).
+#   --max-turns N      Hermes max tool-calling turns per run (default: 50).
+#   --timeout S        Max wall-clock seconds per run. Default: team.timeouts.<role>
+#                      in .maf/config.json, else 1500. The
+#                      dispatcher kills the agent's process group after it.
+#   --idle-timeout S   Fail a run that prints no output for S seconds
+#                      (default: 0, off). Claude Code prints its JSON only at
+#                      the end, so keep this off for --harness claude.
+#   --grace S          Seconds to wait for the agent to exit after the
+#                      completion signal, and for a child that holds stdout
+#                      (default: 5).
+#   --completion-signal TEXT  The agent prints TEXT when the work is complete.
+#                      The run is a success, and the dispatcher stops the
+#                      agent after the grace window. Default: off.
+#   --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
+#                      (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
+#                      again, so a long session costs more on every call.
+#                      0 means no limit.
+#   --max-context N    Start a fresh session when the last model call of the
+#                      session had N or more context tokens (default:
+#                      150000). Each task in a resumed session adds to the
+#                      context. Only opencode reports the size. 0 means no limit.
+#   --no-poll-tasks    Dispatch on inbox messages only.
+#   --full-harness     Codex and Claude Code: keep the user's full setup. By
+#                      default a dispatched Codex run starts without plugins,
+#                      apps, browser and computer tools, subagents, and MCP
+#                      servers. A dispatched Claude Code run starts without
+#                      skills and without MCP servers. Both keep only the
+#                      graphify server of this project: no person reads the
+#                      run, and each extra tool or skill adds context to
+#                      every model call of the run.
+#   --once             Run one poll cycle, then exit (tests, cron).
+#   --verbose          Log idle cycles too.
+#
+# Messages: the dispatcher owns the role's inbox. It moves each unread
+# message into inbox/<role>/processing/ (an atomic rename, so two dispatchers
+# never take the same message), bundles all of them into one prompt, and runs
+# the agent once. On success the messages move to read/. On failure they go
+# back to the inbox, and after MAX_ATTEMPTS failures to failed/. An FYI
+# message (`coord msg --fyi`) starts no run. The next run takes it along.
+#
+# Usage limits: a run that fails on a provider usage or rate limit never
+# reached the model. The dispatcher returns its messages without an attempt
+# and pauses new runs: 15 minutes, then a doubling pause up to MAX_BACKOFF.
+#
+# Unknown model: a run that fails because the harness does not know the
+# model never reached the model, and a retry fails the same way. The
+# dispatcher returns its messages without an attempt, starts no new run until
+# it restarts, and escalates once to the project manager. The claims stay.
+#
+# Tasks: when `coord next ROLE` lists unclaimed tasks, the dispatcher claims
+# one task for its worker and runs the agent on that task only. The claim is
+# 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.
+#
+# Sessions and the prompt cache: the session ID is saved to
+# .maf/coordination/sessions/<worker>.session and resumed on the next run, so the
+# agent keeps its context without staying alive. LLM providers cache the
+# session prefix for a limited time after the last request (1 hour for
+# Claude Code, a few minutes for Codex). A resume after that time resends the whole context at full
+# price. So the dispatcher resumes only inside --cache-window, and for at
+# most --max-session-runs runs, below --max-context tokens. Otherwise the dispatcher starts a fresh
+# session. A run that changed the state of the work puts a short handoff note
+# in its final reply. The dispatcher writes the note to
+# .maf/coordination/sessions/<worker>.handoff.md, and a fresh session starts
+# with that note. If the harness reports an unknown session,
+# the dispatcher also starts fresh. Other failures keep the session.
+#
+# The agent runs with COORD_DIR, COORD_ROLE, COORD_WORKER (default:
+# <role>-bot), TASKRC, and COORD_DISPATCHED=1 set, and with stdin closed. Every built-in
+# adapter skips permission prompts (hermes --yolo, claude bypassPermissions,
+# codex --dangerously-bypass-approvals-and-sandbox): the agent runs every
+# tool call without approval. Run it only in a worktree or sandbox you trust
+# it with. Two dispatchers for one role need different COORD_WORKER values.
+#
+# Environment:
+#   COORD_DIR       Path to .maf/coordination/ (default: .maf/coordination).
+#   COORD_WORKER    Worker ID for the agent (default: <role>-bot).
+#   DISPATCHER_LOG  Append log lines to this file (default: stderr).
+#
+# Ruby: 3.0+ (endless method defs, same as coord).
+
+require "json"
+require "fileutils"
+require "optparse"
+require "rbconfig"
+require "shellwords"
+begin
+  require_relative "../lib/maf/shared/processes"
+  require_relative "../lib/maf/shared/project"
+  require_relative "../lib/maf/shared/roles"
+  require_relative "../lib/maf/shared/peak_rate"
+  require_relative "../lib/maf/shared/git_identity"
+rescue LoadError
+  abort "dispatcher: the maf shared library is missing. Run maf update."
+end
+
+module Dispatcher
+  COORD_BIN = ".maf/bin/coord"
+  MAX_ATTEMPTS = 3
+  MAX_BACKOFF = 3600
+  REPORT_RETRIES = 1
+
+  Config = Struct.new(:role, :harness, :command, :model, :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,
+                      keyword_init: true)
+
+  module Log
+    class << self
+      # The last message. The worker status shows it as the result of a run.
+      attr_reader :last
+    end
+
+    def self.line(message)
+      @last = message
+      text = "[#{Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")}] dispatcher: #{message}"
+      path = ENV["DISPATCHER_LOG"]
+      path ? File.open(path, "a") { |file| file.puts(text) } : warn(text)
+    end
+  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
+  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
+    def self.write(config)
+      dir = File.join(config.coord_dir, "presence")
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "#{config.worker}.json"), JSON.generate(record(config)))
+    end
+
+    def self.record(config)
+      { "role" => config.role, "worker" => config.worker, "mode" => "dispatch", "pid" => Process.pid,
+        "started" => Maf::Shared::Processes.started_at(Process.pid),
+        "seen_at" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ") }
+    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
+  # last successful run in that session, so it tells whether the LLM prompt
+  # cache is still warm. A failed run does not update it, so the next run
+  # treats the cache as colder than it may be. That errs on the cheap side.
+  class Session
+    attr_reader :path, :handoff_path
+
+    def initialize(coord_dir, worker)
+      dir = File.join(coord_dir, "sessions")
+      @path = File.join(dir, "#{worker}.session")
+      @handoff_path = File.join(dir, "#{worker}.handoff.md")
+    end
+
+    def id = lines.first.to_s.empty? ? nil : lines.first
+
+    # The second line counts the runs of the session. Each resume adds the old
+    # context again, so --max-session-runs caps the count.
+    def runs = lines[1].to_i
+
+    # The third line holds the context tokens of the last model call, if the
+    # harness reports them. --max-context caps the size.
+    def context_tokens = lines[2].to_i
+
+    def save(session_id, context = nil)
+      count = session_id == id ? runs + 1 : 1
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, "#{session_id}\n#{count}\n#{context}\n")
+    end
+
+    def lines = File.exist?(@path) ? File.read(@path).split("\n").map(&:strip) : []
+    def clear = FileUtils.rm_f(@path)
+    def idle_seconds = File.exist?(@path) ? Time.now - File.mtime(@path) : Float::INFINITY
+    def handoff = File.exist?(@handoff_path) ? File.read(@handoff_path).strip : ""
+    def write_handoff(text) = FileUtils.mkdir_p(File.dirname(@handoff_path)) && File.write(@handoff_path, text)
+  end
+
+  Message = Struct.new(:path, :from, :text, :worker)
+
+  # Mailbox owns a role's inbox: take moves unread messages into processing/,
+  # ack moves them to read/, release moves them back (or to failed/).
+  class Mailbox
+    def initialize(coord_dir, role)
+      @dir = File.join(coord_dir, "inbox", role)
+      @worker_dir = /\A#{Regexp.escape(role)}-\d+\z/
+    end
+
+    # A crash mid-run leaves messages in processing/. Return them to the inbox.
+    def recover = Dir.glob(File.join(@dir, "processing", "*.md")).each { |path| move(path, @dir) }
+
+    # FYI messages alone start no run. A waking message takes them along.
+    def take
+      fold_worker_inboxes
+      paths = Dir.glob(File.join(@dir, "*.md")).sort
+      paths.all? { |path| Mailbox.fyi?(path) } ? [] : paths.filter_map { |path| claim(path) }
+    end
+
+    # NOTE: assets/coord writes the same name mark (coord msg --fyi).
+    def self.fyi?(path) = File.basename(path).include?(".fyi.")
+
+    def ack(messages) = messages.each { |message| move(message.path, File.join(@dir, "read")) }
+
+    def release(messages) = messages.each { |message| move(message.path, *retry_target(message.path)) }
+
+    # A run that hit a usage limit never reached the model, so it uses no attempt.
+    def restore(messages) = messages.each { |message| move(message.path, @dir) }
+
+    private
+
+    def claim(path)
+      target = move(path, File.join(@dir, "processing"))
+      target && parse(target)
+    end
+
+    def parse(path)
+      header, _blank, body = File.read(path).partition(/\n\n/)
+      Message.new(path, header[/^# from: (.+)$/, 1].to_s.strip, body.strip, header[/^# for: (.+)$/, 1]&.strip)
+    end
+
+    # Older versions of coord wrote a message for a worker to inbox/<worker>/.
+    # No session reads that folder. Move its unread messages to the role inbox.
+    # NOTE: assets/coord folds the same folders.
+    def fold_worker_inboxes
+      dirs = Dir.glob("#{@dir}-*").select { |dir| File.basename(dir).match?(@worker_dir) }
+      dirs.flat_map { |dir| Dir.glob(File.join(dir, "*.md")) }.each { |path| move(path, @dir) }
+    end
+
+    # The attempt count lives in the file name (<stamp>.retry2.md), so it
+    # survives a dispatcher restart. The stamp prefix keeps the sort order.
+    def retry_target(path)
+      attempts = path[/\.retry(\d+)\.md\z/, 1].to_i + 1
+      name = File.basename(path).sub(/(\.retry\d+)?\.md\z/, ".retry#{attempts}.md")
+      [attempts >= MAX_ATTEMPTS ? File.join(@dir, "failed") : @dir, name]
+    end
+
+    # Returns the new path, or nil when another process moved the file first.
+    def move(path, dir, name = File.basename(path))
+      FileUtils.mkdir_p(dir)
+      target = File.join(dir, name)
+      File.rename(path, target) && target
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+
+  # TaskWatch decides when unclaimed tasks justify another agent run. A new
+  # task set dispatches at once; an unchanged one waits a doubling backoff.
+  # A set that vanishes and comes back unchanged keeps its old backoff.
+  class TaskWatch
+    def initialize(interval)
+      @interval = interval
+      @ids = []
+      @attempts = 0
+      @next_at = Time.at(0)
+    end
+
+    def due?(ids, now = Time.now) = !ids.empty? && (ids.sort != @ids || now >= @next_at)
+
+    def dispatched(ids, now = Time.now)
+      @attempts = ids.sort == @ids ? @attempts + 1 : 0
+      @ids = ids.sort
+      @next_at = now + [@interval * (2**(@attempts + 1)), MAX_BACKOFF].min
+    end
+  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
+  # a file that the graph query of the task found, or cites no known node.
+  # Without query output all lessons stay. LESSONS.md shows no nodes for a
+  # correction, so the nodes come from the notes in graphify-out/memory/.
+  module Lessons
+    HEADS = { "**Known dead ends**" => "dead end", "**Corrections**" => "correction" }.freeze
+    QUESTION = /\A[^:]+: "(.*?)"(?: — `| → |$)/
+    SOURCE = /\[src=(.+?)(?: loc=| community=|\])/
+
+    def self.for_task(out_dir, query)
+      file = File.join(out_dir, "reflections", "LESSONS.md")
+      lines = File.exist?(file) ? lines(File.read(file)) : []
+      files = query.to_s.scan(SOURCE).flatten.map { |src| relative(src, out_dir) }
+      (files.empty? ? lines : on_topic(lines, out_dir, files)).reverse
+    end
+
+    # Only the overall section counts. "## By topic" repeats the same lessons.
+    def self.lines(text)
+      kind = nil
+      text.split(/^## By topic/).first.lines.filter_map do |line|
+        kind = HEADS.find { |head, _| line.start_with?(head) }&.last if line.start_with?("**")
+        "#{kind}: #{line.delete_prefix("- ")}" if kind && line.start_with?("- ")
+      end
+    end
+
+    def self.on_topic(lines, out_dir, files)
+      nodes = cited_nodes(File.join(out_dir, "memory"))
+      where = node_files(out_dir, nodes.values.flatten.uniq)
+      lines.select { |line| topic?(nodes[line[QUESTION, 1]].to_a.filter_map { |id| where[id] }, files) }
+    end
+
+    def self.topic?(cited, files) = cited.empty? || !(cited & files).empty?
+
+    # The question of a note maps to the nodes that its notes cite.
+    def self.cited_nodes(dir)
+      Dir.glob(File.join(dir, "*.md")).each_with_object({}) do |path, map|
+        text = File.read(path)
+        question = quoted(text[/^question: (".*")$/, 1])
+        (map[question] ||= []).concat(Array(quoted(text[/^source_nodes: (\[.*\])$/, 1]))) if question
+      end
+    end
+
+    def self.quoted(text)
+      text && JSON.parse(text)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # graphify may store the source path relative to the project or absolute.
+    def self.node_files(out_dir, ids)
+      return {} if ids.empty?
+
+      nodes = JSON.parse(File.read(File.join(out_dir, "graph.json")))["nodes"] || []
+      nodes.select { |node| ids.include?(node["id"]) }
+           .to_h { |node| [node["id"], relative(node["source_file"], out_dir)] }
+    rescue JSON::ParserError, SystemCallError
+      {}
+    end
+
+    def self.relative(path, out_dir) = path.to_s.delete_prefix("#{File.dirname(out_dir)}/")
+  end
+
+  # Prefetch adds live context to a dispatch prompt: the spec of the task the
+  # run works on (`coord show ID`) and `git log --oneline -10`. Each part is
+  # cut to LIMIT characters. A failed command is logged and left out. A run
+  # without a task (a message run) gets only the git log. The agent queries
+  # the knowledge graph itself, with a question that fits the task.
+  # A lead run also gets the artifact list of the open goals, with sizes, so
+  # it reads single files by name instead of printing a whole folder.
+  module Prefetch
+    LIMIT = 2000
+    GRAPH_BUDGET = 500
+    ARTIFACTS = "artifacts of the open goals"
+
+    def self.context(poller, task_id = nil, lead: false)
+      sections = commands(poller, task_id, lead).filter_map { |label, run| section(label, run) }
+      sections.empty? ? "" : "\nLive context at dispatch time:\n\n#{sections.join("\n")}"
+    end
+
+    def self.commands(poller, task_id, lead)
+      log = { "git log --oneline -10" => -> { git_log } }
+      log = log.merge(ARTIFACTS => -> { artifacts(poller) }) if lead
+      task_id ? task_sections(poller, task_id).merge(log) : log
+    end
+
+    # A graph query on the task description names the code of the task. Some
+    # models skip the graph rule and grep instead, and each grep output stays in
+    # the context of the run. The query runs only when the graph exists.
+    def self.task_sections(poller, task_id)
+      spec = poller.show(task_id)
+      { "coord show #{task_id}" => -> { spec } }.merge(graph(poller.coord_dir, spec.to_s[/^description: (.+)$/, 1]))
+    end
+
+    # The lessons section runs after the graph query and keeps the lessons of
+    # the files that the query found.
+    def self.graph(coord_dir, words)
+      path = File.expand_path(File.join(coord_dir, "..", "..", "graphify-out", "graph.json"))
+      return {} unless words && File.exist?(path)
+
+      query = nil
+      { "graphify query <task description> --budget #{GRAPH_BUDGET}" => -> { query = graph_query(words, path) } }
+        .merge(lessons(File.dirname(path), -> { query }))
+    end
+
+    LESSONS = "dead ends and corrections from graphify-out/reflections/LESSONS.md"
+
+    # No lesson for the task adds no section.
+    def self.lessons(out_dir, query = -> {})
+      { LESSONS => -> { Lessons.for_task(out_dir, query.call).join } }
+    end
+
+    def self.graph_query(words, path)
+      output = IO.popen(["graphify", "query", words, "--budget", GRAPH_BUDGET.to_s, "--graph", path], err: File::NULL,
+                        &:read)
+      $?.success? ? output : nil
+    rescue SystemCallError
+      nil
+    end
+
+    def self.artifacts(poller)
+      files = poller.goal_ids&.flat_map { |id| Dir.glob(File.join(poller.coord_dir, "artifacts", id, "*")) }
+      files && (files.empty? ? "(none)" : files.sort.map { |path| artifact_line(path) }.join("\n"))
+    end
+
+    def self.artifact_line(path)
+      "#{File.basename(File.dirname(path))}/#{File.basename(path)} #{(File.size(path) / 1024.0).round(1)}k " \
+        "#{File.mtime(path).utc.strftime("%H:%M")}"
+    end
+
+    def self.section(label, run)
+      text = run.call
+      Log.line("prefetch failed: #{label}; the prompt goes out without it") unless text
+      text && !text.strip.empty? && "$ #{label}\n#{bound(text.strip)}\n"
+    end
+
+    def self.bound(text) = text.length > LIMIT ? "#{text[0, LIMIT]}\n[cut at #{LIMIT} characters]" : text
+
+    def self.git_log
+      output = IO.popen(%w[git log --oneline -10], err: File::NULL, &:read)
+      $?.success? ? output : nil
+    rescue SystemCallError
+      nil
+    end
+  end
+
+  # Poller reads the role's tasks through coord.
+  class Poller
+    TASK_ID = /^([0-9a-f-]{36})\b/
+
+    def initialize(env, role)
+      @env = env
+      @role = role
+    end
+
+    def unclaimed_task_ids = next_output.to_s.scan(TASK_ID).flatten
+
+    # The tasks that this worker claimed and did not finish.
+    def claimed_task_ids = read("next", @role, "--mine").to_s.scan(TASK_ID).flatten
+
+    # The first task that this worker can claim, or nil. `coord claim` is
+    # atomic, so two workers never get one task, and a run always has work.
+    def claim_first(ids) = ids.find { |id| coord("claim", id) }
+
+    def coord(*args) = CoordCall.run(@env, *args)
+    def next_output = read("next", @role)
+    def show(id) = read("show", id)
+    def goal_ids = read("goal", "list")&.scan(TASK_ID)&.flatten
+    def coord_dir = @env.fetch("COORD_DIR")
+
+    private
+
+    # The output of a coord command, or nil when the command fails.
+    def read(*args)
+      output = IO.popen(@env, CoordCall.command + args, err: File::NULL, &:read)
+      $?.success? ? output : nil
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+
+  # 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
+
+    # Returns true when the command succeeds.
+    def self.run(env, *args)
+      system(env, *command, *args, out: File::NULL, err: File::NULL)
+    rescue Errno::ENOENT
+      false
+    end
+  end
+
+  # LeadChores runs the periodic coord checks in the architect dispatcher, at
+  # most one time in EVERY seconds. `coord reap` releases the claims of
+  # stalled workers. `coord review-watch --once` reads new pull request
+  # reviews, only with a github section in .maf/config.json. Both commands
+  # write to the architect inbox, so the next cycle starts an architect run.
+  class LeadChores
+    EVERY = 300
+
+    def initialize(poller, role)
+      @poller, @role = poller, role
+    end
+
+    def run
+      return unless due?
+
+      @last = Time.now
+      commands.each { |args| @poller.coord(*args) || Log.line("coord #{args.first} failed") }
+    end
+
+    private
+
+    def commands = [["reap"], (%w[review-watch --once] if github?)].compact
+    def due? = @role == "architect" && (@last.nil? || Time.now - @last >= EVERY)
+    def github? = !Project.manifest.dig("github", "bot_user").to_s.empty?
+  end
+
+  Result = Struct.new(:output, :success, :timed_out, :reason)
+
+  # Limits are the run limits besides the hard --timeout. idle: seconds
+  # without output before the run fails (0 means off). grace: seconds to
+  # wait after a completion signal, and for a child that holds stdout.
+  # complete and abort: signal strings in the output (nil means off).
+  Limits = Struct.new(:idle, :grace, :complete, :abort) do
+    def self.from(config)
+      new(config.idle_timeout || 0, config.grace || Spawn::GRACE, config.completion_signal, config.abort_signal)
+    end
+  end
+
+  # Stream reads the output of a child in a thread and records the time of
+  # the last output.
+  class Stream
+    def initialize(reader)
+      @reader = reader
+      @lock, @text, @last_at = Mutex.new, String.new, Time.now
+      @thread = Thread.new { pump }
+    end
+
+    def idle_seconds = Time.now - @last_at
+    def include?(signal) = @lock.synchronize { @text.include?(signal.b) }
+
+    # A background grandchild can hold the pipe open after the agent exits.
+    # Then the reader thread is still blocked: kill it before closing the pipe,
+    # so it never dies with an IOError and never lingers.
+    def close(grace)
+      @thread.join(grace)
+      @thread.kill
+      @reader.close
+      @lock.synchronize { @text.dup.force_encoding(Encoding::UTF_8) }
+    end
+
+    private
+
+    def pump
+      loop { append(@reader.readpartial(4096)) }
+    rescue EOFError, IOError
+      nil
+    end
+
+    def append(chunk) = @lock.synchronize { (@text << chunk.b) && (@last_at = Time.now) }
+  end
+
+  # Watch decides why a run ends. :exit means the process exited. :complete
+  # and :abort mean a signal string appeared in the output. :idle means no
+  # output for limits.idle seconds. :timeout means the hard --timeout passed.
+  # After a completion signal, the process gets limits.grace seconds to exit.
+  class Watch
+    TICK = 0.2
+
+    def initialize(timeout, limits)
+      @deadline = Time.now + timeout
+      @limits = limits
+    end
+
+    def grace = @limits.grace
+
+    def wait(waiter, stream)
+      loop do
+        reason = signal(stream) || (waiter.join(TICK) ? :exit : limit(stream))
+        return settle(reason, waiter) if reason
+      end
+    end
+
+    # A signal in the last output chunk can arrive after the exit.
+    def final(reason, output)
+      return reason unless reason == :exit
+
+      signal(output) || :exit
+    end
+
+    private
+
+    def settle(reason, waiter)
+      waiter.join(grace) if reason == :complete
+      reason
+    end
+
+    def signal(text)
+      return :abort if seen?(text, @limits.abort)
+
+      :complete if seen?(text, @limits.complete)
+    end
+
+    def seen?(text, signal) = !signal.to_s.empty? && text.include?(signal)
+
+    def limit(stream)
+      return :timeout if Time.now >= @deadline
+
+      :idle if @limits.idle.positive? && stream.idle_seconds >= @limits.idle
+    end
+  end
+
+  # Spawn runs a command in its own process group. Any end reason except a
+  # normal exit kills the whole group (TERM, then KILL), which also stops the
+  # children of an `sh -c` template. A completion signal is success even when
+  # the process must be killed. An abort signal is failure.
+  module Spawn
+    GRACE = 5
+    TIMEOUTS = %i[timeout idle].freeze
+
+    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)
+      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.collect(pid, stream, watch)
+      waiter = Process.detach(pid)
+      reason = watch.wait(waiter, stream)
+      stop(pid, waiter) unless reason == :exit
+      result(stream.close(watch.grace), waiter, watch, reason)
+    end
+
+    def self.result(output, waiter, watch, reason)
+      reason = watch.final(reason, output)
+      success = reason == :complete || (reason == :exit && waiter.value.success?)
+      Result.new(output, success, TIMEOUTS.include?(reason), reason)
+    end
+
+    def self.stop(pid, waiter)
+      Process.kill("TERM", -pid)
+      Process.kill("KILL", -pid) unless waiter.join(GRACE)
+      true
+    rescue Errno::ESRCH
+      true
+    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) || {}
+
+    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.
+  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
+
+    def add(usage)
+      return unless usage
+
+      totals = read
+      write(usage.to_h { |key, value| [key, totals[key].to_i + value] }.merge("runs" => totals["runs"].to_i + 1))
+    rescue SystemCallError, JSON::ParserError => e
+      Log.line("token usage not saved: #{e.message}")
+    end
+
+    private
+
+    def read = File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+    def write(data) = FileUtils.mkdir_p(File.dirname(@path)) && File.write(@path, JSON.generate(data))
+  end
+
+  # RunHistory appends one line per run to .maf/coordination/usage/<worker>.runs.jsonl:
+  # the usage, the session run (1 is a fresh session), the context of the last
+  # model call, the peak rate, and the session limits of the run. The dashboard
+  # turns the history into hints. A run without usage data adds no line.
+  class RunHistory
+    def initialize(config)
+      @config = config
+      @path = File.join(config.coord_dir, "usage", "#{config.worker}.runs.jsonl")
+    end
+
+    def add(usage, session_run, context)
+      return unless usage
+
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, "#{JSON.generate(line(usage, session_run, context))}\n", mode: "a")
+    rescue SystemCallError => e
+      Log.line("run history not saved: #{e.message}")
+    end
+
+    private
+
+    def line(usage, session_run, context)
+      { "at" => Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"), "session_run" => session_run, "context" => context,
+        "peak" => PeakRate.notice(@config) ? true : nil, "limits" => limits }.compact.merge(usage)
+    end
+
+    def limits = { "max_context" => @config.max_context, "max_session_runs" => @config.max_session_runs,
+                   "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.
+  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)
+
+      "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
+
+  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
+
+      def self.build_command(config, prompt, _session_id)
+        values = { prompt: prompt, role: config.role, skill: config.skill, model: config.model }
+        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." }
+    end
+  end
+
+  # ReportBlock reads the typed result that an agent puts at the end of its
+  # final reply: <report>{"status":"done","tests":"pass","next":"..."}</report>.
+  # parse returns nil when no block is present. Otherwise it returns a Parsed
+  # with the data or with the validation error.
+  module ReportBlock
+    REPORT_FORMAT = '<report>{"status":"<done|blocked|needs_review>","tests":"<pass|fail>","next":"<next>"}</report>'
+    STATUSES = %w[done blocked needs_review].freeze
+    TESTS = %w[pass fail].freeze
+    PATTERN = %r{<report>(.*?)</report>}m
+    Parsed = Struct.new(:data, :error)
+
+    def self.parse(text) = text.to_s.scan(PATTERN).flatten.last&.then { |body| check(decode(body.strip)) }
+
+    # Raw harness output holds the block inside a JSON string, with escaped quotes.
+    def self.decode(body) = load(body) || load(load(%("#{body}")).to_s)
+
+    def self.load(text)
+      JSON.parse(text)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def self.check(value)
+      return Parsed.new(nil, "the report block is not a JSON object") unless value.is_a?(Hash)
+
+      error = errors(value).first
+      Parsed.new(error ? nil : value, error)
+    end
+
+    def self.errors(value)
+      [("status must be one of #{STATUSES.join(", ")}" unless STATUSES.include?(value["status"])),
+       ("tests must be pass or fail" unless value["tests"].nil? || TESTS.include?(value["tests"])),
+       ("status done needs tests pass, not fail" if value["status"] == "done" && value["tests"] == "fail")].compact
+    end
+  end
+
+  # HandoffBlock reads the handoff note that an agent puts in its final reply:
+  # <handoff>...</handoff>. The dispatcher writes the note to the handoff file,
+  # so the agent spends no tool call and no extra model call on the note.
+  module HandoffBlock
+    PATTERN = %r{<handoff>(.*?)</handoff>}m
+
+    def self.parse(text) = text.to_s.scan(PATTERN).flatten.last&.then { |body| decode(body).strip }
+
+    # Raw harness output holds the block inside a JSON string, with escapes.
+    def self.decode(body) = ReportBlock.load(%("#{body}")).then { |text| text.is_a?(String) ? text : body }
+  end
+
+  # Verify runs the verify command of .maf/config.json after a successful
+  # run, in the worktree. A non-zero exit makes the run no success. No key
+  # means no check. Lead roles own no task, so they get no check.
+  module Verify
+    def self.pass?(config, env)
+      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)
+    end
+
+    def self.check(result, command)
+      Log.line("verify command failed (#{command}): #{result.output.lines.last(5).join.strip}") unless result.success
+      result.success
+    end
+  end
+
+  # Outcome decides what a finished run means: :done, :waiting, or :failed.
+  # No report block keeps the old rule: exit 0 is done. Status done is done.
+  # Status blocked or needs_review is :waiting: the agent handled its input
+  # and now waits for someone else. An invalid block is :failed. The session
+  # stays, so the next run resumes it.
+  class Outcome
+    def initialize(session)
+      @session = session
+    end
+
+    def conclude(block, text)
+      keep_handoff(text)
+      return finished(text, block) if block.nil? || block.data&.fetch("status") == "done"
+
+      unfinished(block)
+    end
+
+    private
+
+    def finished(text, block)
+      Log.line("agent finished#{" (no report block)" unless block}: #{text.slice(0, 80)}")
+      :done
+    end
+
+    def unfinished(block)
+      reason = block.error ? "an invalid report block: #{block.error}" : "status #{block.data["status"]}"
+      Log.line("agent ended with #{reason}; next: #{block.data&.fetch("next", nil) || "-"}")
+      block.error ? :failed : :waiting
+    end
+
+    # Some models skip the handoff instruction. If no note exists, the agent's
+    # final reply becomes the note, so a later fresh session still gets some
+    # context. An existing note stays: a run that changed nothing keeps it.
+    def keep_handoff(text)
+      note = text.gsub(ReportBlock::PATTERN, "").gsub(HandoffBlock::PATTERN, "").strip
+      return if note.empty? || !@session.handoff.empty?
+
+      @session.write_handoff(note)
+    end
+  end
+
+  # WorkerStatus writes .maf/coordination/status/<worker>.json. The dashboard
+  # shows it. NOTE: assets/harness-hooks/context-watch.rb writes the same file
+  # for an interactive session; both run standalone.
+  class WorkerStatus
+    def initialize(config)
+      @config = config
+      @path = File.join(config.coord_dir, "status", "#{config.worker}.json")
+    end
+
+    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"])
+    end
+
+    def finished(outcome, detail, model)
+      run = { "finished_at" => now, "success" => outcome == :done, "outcome" => outcome.to_s,
+              "detail" => detail.to_s[0, 300] }
+      save({ "running" => false, "model" => model, "last_run" => run }.compact)
+    end
+
+    # The board shows a paused worker, not a live one that fails each cycle.
+    def paused(time) = save("paused_until" => time&.utc&.strftime("%Y-%m-%dT%H:%M:%SZ"))
+
+    # A halted worker starts no run until its dispatcher restarts.
+    def halted(reason) = save("halted" => reason.to_s[0, 300])
+
+    private
+
+    def now = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    def read
+      File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def save(data)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write("#{@path}.tmp", JSON.generate(read.merge(data)))
+      File.rename("#{@path}.tmp", @path)
+    rescue SystemCallError => e
+      Log.line("worker status not saved: #{e.message}")
+    end
+  end
+
+  # UsageLimit spots a provider usage or rate limit in the end of the output
+  # of a run that exited with an error. Such a run never reached the model.
+  # A timeout is never a limit: the output can be the agent's own text.
+  module UsageLimit
+    PATTERN = /usage limit|rate limit|hit your limit|limit reached|quota exceeded|too many requests/i
+
+    def self.hit?(result) = result.reason == :exit && result.output.lines.last(10).join.match?(PATTERN)
+  end
+
+  # ModelError spots a model name that the harness does not know, such as a
+  # typo in the roster. Such a run never reached the model, and each retry
+  # fails the same way. Only a fix of the model name helps.
+  module ModelError
+    PATTERN = /unrecognized_model|unknown\ model|model[_\ ]?not[_\ ]?found|invalid\ model|
+               model\b.{0,80}\b(?:does\ not\ exist|is\ not\ supported)/ix
+
+    def self.hit?(result) = result.reason == :exit && result.output.lines.last(10).join.match?(PATTERN)
+  end
+
+  # Pause holds new runs after a usage limit. Each limit in a row doubles the
+  # pause, up to MAX_BACKOFF. Any other outcome ends the series.
+  class Pause
+    FIRST = 900
+
+    def initialize
+      @seconds, @until = 0, Time.at(0)
+    end
+
+    attr_reader :until
+
+    def active?(now = Time.now) = now < @until
+
+    def start(now = Time.now)
+      @seconds = @seconds.zero? ? FIRST : [@seconds * 2, MAX_BACKOFF].min
+      @until = now + @seconds
+    end
+
+    # Returns true when a series of limits ended.
+    def clear = @seconds.positive?.tap { @seconds = 0 }
+  end
+
+  # Runner runs one agent dispatch. It resumes the saved session only while
+  # the LLM prompt cache is still warm (see --cache-window). A cold session
+  # would resend the whole context at full price, so the dispatcher starts a
+  # fresh session and hands it the handoff note instead. It also starts
+  # fresh when the harness reports that the saved session no longer exists.
+  class Runner
+    def initialize(config, harness, env)
+      @config = config
+      @harness = harness
+      @env = env
+      @session = Session.new(config.coord_dir, config.worker)
+      @status = WorkerStatus.new(config)
+    end
+
+    # Returns the outcome of the run: :done, :waiting, :failed, :limited, or :broken.
+    def dispatch(prompt) = run(prompt).tap { |outcome| @status.finished(outcome, Log.last, @model) }
+
+    private
+
+    def run(prompt)
+      session_id = warm_session_id
+      @session_run = session_id ? @session.runs + 1 : 1
+      @status.started(session_id, @session.runs)
+      result = attempt(prompt, session_id)
+      result = retry_fresh(prompt) if session_id && @harness.stale_session?(result.output)
+      report(result)
+    end
+
+    def warm_session_id
+      id = @session.id
+      return id unless id && (cold? || full? || large?)
+
+      expire(id)
+    end
+
+    def cold? = @session.idle_seconds > @config.cache_window
+    def full? = @config.max_session_runs.to_i.positive? && @session.runs >= @config.max_session_runs
+    def large? = @config.max_context.to_i.positive? && @session.context_tokens >= @config.max_context
+
+    def expire(id)
+      Log.line("session #{id} #{expire_reason}; starting fresh with the handoff note")
+      @session.clear
+      nil
+    end
+
+    def expire_reason
+      return "idle #{(@session.idle_seconds / 60).round}m, past the cache window" if cold?
+      return "has #{@session.runs} runs, the --max-session-runs limit" if full?
+
+      "has #{@session.context_tokens} context tokens, the --max-context limit"
+    end
+
+    def attempt(prompt, session_id)
+      Log.line("dispatching #{@config.role} (session: #{session_label(session_id)})")
+      PeakRate.notice(@config)&.then { |text| Log.line(text) }
+      text = Prompt.with_handoff(prompt, @session, session_id) + Prompt.signals(@config)
+      spawn(@harness.build_command(@config, text, session_id))
+    end
+
+    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))
+      record(@harness.usage(result.output), result.output)
+      @model = @harness.model(result.output) || @model
+      result
+    end
+
+    def record(usage, output)
+      usage && Log.line("tokens: #{TokenUsage.label(usage)}")
+      TokenUsage.new(@config.coord_dir, @config.worker).add(usage)
+      RunHistory.new(@config).add(usage, @session_run, @harness.context(output))
+    end
+
+    def retry_fresh(prompt)
+      Log.line("session #{@session.id} not found; starting a fresh session")
+      @session.clear
+      attempt(prompt, nil)
+    end
+
+    # A missing or invalid report block resumes the session with the error,
+    # at most REPORT_RETRIES times. A harness without a session gets no retry.
+    # The retry is part of the same run, so it does not count as a session run.
+    def report(result, retries = REPORT_RETRIES)
+      return failed(result) unless result.success
+
+      first_reply(result) if retries == REPORT_RETRIES
+      block = ReportBlock.parse(@harness.result_text(result.output) || result.output)
+      retry_report?(block, retries) ? report(ask_for_report(block), retries - 1) : conclude(block, result)
+    end
+
+    def first_reply(result)
+      @harness.session_id(result.output)&.then { |id| @session.save(id, @harness.context(result.output)) }
+      note = HandoffBlock.parse(@harness.result_text(result.output) || result.output)
+      @session.write_handoff(note) unless note.to_s.empty?
+    end
+
+    def retry_report?(block, retries) = retries.positive? && @session.id && (block.nil? || block.error)
+
+    def ask_for_report(block)
+      problem = block ? "Your report block is invalid: #{block.error}." : "Your final reply has no report block."
+      Log.line("#{problem} Resuming session #{@session.id} once for the report block")
+      spawn(@harness.build_command(@config, "#{problem}\n#{Prompt.report}", @session.id))
+    end
+
+    def conclude(block, result)
+      outcome = Outcome.new(@session).conclude(block, @harness.result_text(result.output).to_s)
+      outcome != :done || Verify.pass?(@config, @env) ? outcome : :failed
+    end
+
+    # Returns :broken for an unknown model, :limited for a usage limit, else :failed.
+    def failed(result)
+      Log.line("agent #{failure_label(result.reason)}: #{result.output.lines.last(5).join.strip}")
+      report_timeout if result.reason == :timeout
+      return :broken if ModelError.hit?(result)
+
+      UsageLimit.hit?(result) ? :limited : :failed
+    end
+
+    TIMEOUT_NOTICE = "Dispatcher run of %<worker>s timed out after %<seconds>ss. The claims stay. " \
+                     "If the task needs more time, raise team.timeouts.%<role>s in .maf/config.json."
+
+    # The architect cannot see a dispatcher log. Without this notice, a task waits without a sign.
+    def report_timeout
+      return if @config.role == "architect"
+
+      text = format(TIMEOUT_NOTICE, worker: @config.worker, seconds: @config.timeout, role: @config.role)
+      CoordCall.run(@env, "msg", "--from", @config.role, "architect", text)
+    end
+
+    def failure_label(reason)
+      { timeout: "timed out after #{@config.timeout}s", idle: "idle for #{@config.idle_timeout}s (no output)",
+        abort: "sent the abort signal" }.fetch(reason, "failed")
+    end
+  end
+
+  # Prompt builds the one-shot work prompt. The coordination rules live in
+  # the role prompt, so the prompt only adds what is specific to a dispatched run.
+  module Prompt
+    # Each tool output stays in the context for every later model call of
+    # the run. A skill or a file that the work does not need costs on each call.
+    ONE_SHOT = <<~TEXT
+      You run as role %<role>s in one-shot mode. Follow your role instructions. They hold the coordination rules.
+      Do not use --wait: nobody is waiting on this session.
+      No person reads this run. Skip session-start skills such as caveman. Read a skill file only if the work needs it.
+    TEXT
+
+    # The dispatcher claims each task. A worker that claims a task itself can
+    # take the task of a run that starts next.
+    MESSAGE_END = "Handle the messages above. Do not claim a task: the dispatcher claims tasks for you.\n" \
+                  "When every message is handled, stop.\n"
+    LEAD_END = <<~TEXT
+      You are a lead role. Never claim a task. Handle the messages above.
+      Start from your handoff note. Read only the artifacts that the messages or the note name.
+      Never print a whole artifact folder. For a revised artifact, read the diff against the reviewed copy.
+      Do not send a message only to acknowledge. Send a message only with a result, a question, or a decision.
+      When every message is handled, stop.
+    TEXT
+
+    def self.messages(messages, role)
+      bodies = messages.map { |message| "--- #{heading(message)} ---\n#{message.text}\n" }
+      ending = LEADS.include?(role) ? LEAD_END : MESSAGE_END
+      "The dispatcher took these messages from your inbox:\n\n#{bodies.join("\n")}\n#{rules(role)}#{ending}"
+    end
+
+    # A worker has no inbox of its own, so a message for one worker reaches
+    # any worker of the role.
+    def self.heading(message)
+      fyi = " (FYI: no reply needed)" if Mailbox.fyi?(message.path)
+      "message from #{message.from}#{" for worker #{message.worker}" if message.worker}#{fyi}"
+    end
+
+    TASK = <<~TEXT
+      The dispatcher claimed task %<id>s for you. Skip the claim step of your work loop.
+      Do this task only. Finish it with coord done. Then stop. Do not claim another task.
+    TEXT
+
+    def self.task(role, id) = "#{format(TASK, id: id)}#{rules(role)}"
+
+    RESUME = <<~TEXT
+      You hold claimed tasks that a previous run did not finish: %<ids>s.
+      For each task, run coord show <id> first. If the status is not pending, or the worker is not you, skip the task.
+      Otherwise continue the task on its task branch. Finish it with coord done.
+      Do not claim another task. When these tasks are done, stop.
+    TEXT
+
+    def self.resume(role, ids) = "#{format(RESUME, ids: ids.join(", "))}#{rules(role)}"
+    def self.rules(role) = format(ONE_SHOT, role: role)
+
+    HANDOFF = <<~TEXT
+      If this run changed the state of your work, put a handoff note for your next session in your final reply:
+      <handoff>At most 300 words: current state, decisions, open questions, and the next step.</handoff>
+      Do not write the note to a file. If this run changed nothing, leave out the handoff block.
+    TEXT
+
+    # A fresh session starts with the previous session's handoff note. A
+    # resumed session already has that context. Every run writes a new note
+    # while its cache is still warm, which is cheap.
+    REPORT = <<~TEXT
+      End your final reply with one report block on its own line:
+      %<format>s
+      Use status done only when the work is complete. Use blocked or needs_review otherwise.
+    TEXT
+
+    SIGNALS = <<~TEXT
+      When the work is complete, print %<complete>s on its own line as the last output.
+      If you give up, print %<abort>s on its own line instead.
+    TEXT
+
+    def self.signals(config)
+      return "" unless config.completion_signal || config.abort_signal
+
+      format(SIGNALS, complete: config.completion_signal || "-", abort: config.abort_signal || "-")
+    end
+
+    def self.report = format(REPORT, format: ReportBlock::REPORT_FORMAT)
+
+    def self.with_handoff(prompt, session, session_id)
+      note = session.handoff
+      intro = session_id || note.empty? ? "" : "Handoff note from your previous session:\n#{note}\n\n"
+      "#{intro}#{prompt}\n#{HANDOFF}#{report}"
+    end
+  end
+
+  # StopSignal ends the poll loop after the current agent run. `maf retire`
+  # sends TERM. The agent runs in its own process group, so TERM does not
+  # reach the agent, and the agent finishes its work first. The trap writes
+  # to a pipe, so a TERM also ends the wait between two cycles.
+  class StopSignal
+    def initialize
+      @reader, @writer = IO.pipe
+      trap("TERM") { signal }
+    end
+
+    # Returns true after the full interval, false when a stop was requested.
+    def wait(seconds) = IO.select([@reader], nil, nil, seconds).nil?
+
+    private
+
+    def signal
+      @writer.write_nonblock(".")
+    rescue IOError, IO::WaitWritable
+      nil
+    end
+  end
+
+  # Main runs the poll + dispatch loop.
+  class Main
+    def initialize(config)
+      @config = config
+      @runner = Runner.new(config, Harness.for(config), Main.run_env(config))
+      @mailbox = Mailbox.new(config.coord_dir, config.role)
+      @poller = Poller.new(Main.run_env(config), config.role)
+      @watch, @resume = Array.new(2) { TaskWatch.new(config.interval) }
+      @pause, @status = Pause.new, WorkerStatus.new(config)
+    end
+
+    def self.run_env(config)
+      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))
+    end
+
+    def run
+      start
+      cycle_forever
+      Log.line("stopped (TERM)") unless @config.once
+    rescue Interrupt
+      Log.line("stopped (interrupted)")
+    end
+
+    # At most one agent run per cycle. A message run comes first. The next
+    # cycle claims a task.
+    def cycle
+      Presence.write(@config)
+      chores.run
+      return held_cycle if held?
+
+      worked = dispatch_messages || (@config.poll_tasks && (dispatch_claimed || dispatch_tasks))
+      Log.line("no work this cycle") if @config.verbose && !worked
+    end
+
+    private
+
+    def context(task_id = nil) = Prefetch.context(@poller, task_id, lead: LEADS.include?(@config.role))
+
+    def dispatch(prompt) = @runner.dispatch(prompt).tap { |outcome| pace(outcome) }
+
+    def pace(outcome)
+      return halt if outcome == :broken
+
+      outcome == :limited ? pause : unpause
+    end
+
+    def unpause = @pause.clear && @status.paused(nil)
+    def held? = @halted || @pause.active?
+    def held_cycle = @config.verbose && Log.line(held_label)
+
+    def held_label
+      @halted ? "halted: the harness does not know the model" : "paused for a usage limit until #{@pause.until.utc}"
+    end
+
+    HALT_NOTICE = "Dispatcher of %<worker>s halted: the %<harness>s harness does not know model %<model>s. " \
+                  "Each retry fails the same way. Fix the model in the role file and in " \
+                  ".maf/coordination/workers.json, then run `maf worker restart %<worker>s`. The claims stay."
+
+    # An unknown model never fixes itself. The dispatcher stops new runs and
+    # escalates once, so the work does not wait without a sign.
+    def halt
+      @halted = true
+      @status.halted(Log.last)
+      Log.line("unknown model: no new run until the dispatcher restarts")
+      text = format(HALT_NOTICE, worker: @config.worker, harness: @config.harness,
+                                 model: @config.model || "(default)")
+      CoordCall.run(Main.run_env(@config), "escalate", text)
+    end
+
+    def pause
+      @pause.start
+      @status.paused(@pause.until)
+      Log.line("usage limit: no new run until #{@pause.until.utc}")
+    end
+    def chores = @chores ||= LeadChores.new(@poller, @config.role)
+
+    def start
+      Log.line("started: role=#{@config.role} #{harness_label} #{timing_label}")
+      @mailbox.recover
+      @stop = StopSignal.new
+    end
+    def timing_label = "interval=#{@config.interval}s cache_window=#{@config.cache_window}s " \
+                       "max_session_runs=#{@config.max_session_runs} max_context=#{@config.max_context}"
+    def harness_label = @config.command ? "command=#{@config.command.inspect}" : "harness=#{@config.harness}"
+
+    def cycle_forever
+      cycle
+      cycle while !@config.once && @stop.wait(@config.interval)
+    end
+
+    def dispatch_messages
+      messages = @mailbox.take
+      return false if messages.empty?
+
+      settle(messages, dispatch(Prompt.messages(messages, @config.role) + context))
+    end
+
+    # A run that waits for someone else handled its messages, so they are read.
+    # Only a failed run returns them for another try. A usage limit or an
+    # 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
+
+    # A run that timed out or crashed leaves its claims. Finish them before new work.
+    def dispatch_claimed
+      ids = @poller.claimed_task_ids
+      return false unless @resume.due?(ids)
+
+      dispatch(Prompt.resume(@config.role, ids) + context(ids.first))
+      @resume.dispatched(ids)
+      true
+    end
+
+    # The claim comes first, so the run never starts without work.
+    def dispatch_tasks
+      ids = @poller.unclaimed_task_ids
+      return false unless @watch.due?(ids)
+
+      id = @poller.claim_first(ids)
+      @watch.dispatched(ids)
+      id && run_task(id)
+    end
+
+    def run_task(id)
+      dispatch(Prompt.task(@config.role, id) + context(id))
+      true
+    end
+  end
+
+  # 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],
+               "--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],
+               "--idle-timeout S" => [:idle_timeout, Integer], "--grace S" => [:grace, Integer],
+               "--completion-signal TEXT" => [:completion_signal, String],
+               "--abort-signal TEXT" => [:abort_signal, String] }.freeze
+    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,
+                 poll_tasks: true, lean: true,
+                 no_skill: false, once: false, verbose: false }.freeze
+
+    DEFAULT_TIMEOUT = 1500
+    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
+    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)")
+      validate(finish(config, env))
+    end
+
+    # Reviews and data tasks need more time than code tasks. The team section
+    # of .maf/config.json sets a limit for each role: "team": { "timeouts": { "reviewer": 2400 } }.
+    def self.role_timeout(role)
+      value = Project.manifest.dig("team", "timeouts", role)
+      value && Integer(value, exception: false)
+    end
+
+    def self.validate(config)
+      abort "dispatcher: role must not be empty" if config.role.strip.empty?
+      positive = config.interval.positive? && config.timeout.positive?
+      abort "dispatcher: --interval and --timeout must be positive" unless positive
+      abort "dispatcher: --cache-window must be 0 or more" if config.cache_window.negative?
+      validate_limits(config)
+    end
+
+    def self.validate_limits(config)
+      limits = [config.idle_timeout, config.grace, config.max_session_runs, config.max_context]
+      abort "dispatcher: --idle-timeout, --grace, --max-session-runs, and --max-context must be 0 or more" if
+        limits.any?(&:negative?)
+      config
+    end
+
+    def self.parser(config)
+      OptionParser.new("Usage: dispatcher ROLE [options]") do |o|
+        VALUES.each { |flag, (key, type)| o.on(flag, type) { |v| config[key] = v } }
+        SWITCHES.each { |flag, (key, value)| o.on(flag) { config[key] = value } }
+        o.on("-h", "--help") { puts(o) || exit }
+      end
+    end
+
+    def self.finish(config, env)
+      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))
+    end
+
+    def self.limits(config)
+      config.timeout ||= role_timeout(config.role) || DEFAULT_TIMEOUT
+      session_limits(config, Project.manifest.dig("team", "limits", config.role) || {})
+    end
+
+    # The team section of .maf/config.json sets the session limits of a role:
+    # "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.session_limits(config, saved)
+      config.cache_window ||= saved["cache_window"] || CACHE_WINDOWS.fetch(config.harness, DEFAULT_CACHE_WINDOW)
+      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
+
+if __FILE__ == $PROGRAM_NAME
+  # The agents run `coord`. Put the folder of this script (.maf/bin) on PATH.
+  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::Main.new(Dispatcher::Options.parse(ARGV)).run
+end