maf 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a374ca278aa9cd10c03f38a12fa6bc24956037e9be7d7f5cbc1b64ae5feb7649
-  data.tar.gz: 73a993337895a9981a134ffe7c95cf10c7134e6c314037168bf0b0e44f9c0f43
+  metadata.gz: 1d92abf8bbcca7ba5044ac6185534e883a55a1387e05460ac4142e1d89f3d13e
+  data.tar.gz: 25eaa46e4ed438fef70a08841137fc87c7ede35dfe9c09ff4d053a351e11e9ef
 SHA512:
-  metadata.gz: 84e490da67016e6a30344fc07645300ebbc81b37363161726ba29138d5108e2dc762a9cc022918e0e6b5bdfed8382bfda7236dd18690602e55c5e1d8a1155965
-  data.tar.gz: fb54b0eb031e1d42150a898c84cf6176490b92be13f0619c90fe0094cc67c84b045d2027abc6dbc7bd5a8217935208a748cfa29e769150b746fa210334ecab97
+  metadata.gz: 96324cff6b379cb0ec71cbe0d8a15d127a950ddfb7e3997012f4f9b6c4759508a34668fc06a7702d04030ebf65875335c05a6a5836f7959422cbaf107d6abe92
+  data.tar.gz: 9faa6836a004d143d9bcdfc7852d4479b2f9b43f40d09efcab44c32343607b9bcf73949c7e62235b772f817d37845e0e2a5955deefab1c576477a962798e8aa2

data/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-21
+
+- Fix: each dispatched Hermes run failed. Hermes 0.22 refuses `--run-budget` with `--format
+  stream-json`. maf no longer passes `--run-budget`. The `--timeout` of the dispatcher still
+  stops a run.
+- Fix: in a Hermes run, `coord` did not get `COORD_WORKER` and the other flow variables, so
+  `coord done` refused to close the task. Hermes runs each session in a shared gateway and
+  passes only the names in `terminal.client_env_passthrough`. `maf add` and `maf update` print
+  the `hermes config set` command that adds the flow names to that list.
+- `maf worker stop|start|restart|status ROLE` finds the worker when the role has one worker,
+  for example `tester-bot`.
+- `maf worker list` names the stopped workers also when no worker runs.
+- A worker does not start a team of its own. `.maf/claude/settings.json` sets
+  `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0`, so a subagent that Claude names in a `maf start`
+  session does not start as a teammate. `maf update` adds the setting.
+- Hermes: each role gets a toolset list. A role that edits no longer gets `kanban`,
+  `delegation`, `cronjob`, `computer_use`, and the other toolsets outside the list.
+- Fix: a Hermes role with `can_edit: false` did not get the graph MCP server, because its
+  toolset list did not name `mcp-graphify-<project>`.
+- The dispatcher blocks a task after 3 runs in a row that leave it claimed and not done, and
+  escalates it to the project manager. Before, it resumed such a task each hour without end.
+  New commands: `coord block ID [--kind K] TEXT` holds a task out of `coord next`, and
+  `coord unblock ID` returns it. `coord status` and `coord board` show blocked tasks.
+- A worker that cannot finish a task blocks it with a kind: `needs_input`, `dependency`, or
+  `capability`. coord tells the architect (dependency) or the project manager (the other kinds).
+  Before, the worker kept the claim, and the dispatcher resumed the task each hour.
+- `maf worker list` shows each running worker: its role, harness, mode (session or dispatch),
+  pid, and start time. A worker that runs twice, for example as a session and as a
+  dispatcher, gets a warning. The last line names the registered workers that do not run.
+- Effort levels per role (#44): `maf add --effort ROLE=LEVEL`, `maf start` and `maf prepare
+  --effort LEVEL`, and `dispatcher --effort LEVEL`. maf passes the level to the harness in its
+  own form: `--effort` (Claude Code), `model_reasoning_effort` (Codex), `--reasoning` (Hermes),
+  `--variant` (opencode), and the model name for Cursor (`gpt-5.3-codex` + `high` =
+  `gpt-5.3-codex-high`). Each role has a default level in `roles.yml` (`effort:`), used when the
+  harness lists it. After `maf update`, the claude, codex, hermes, and cursor agents get the
+  default of their role. The interactive mode shows the levels of each model and asks for one.
+- Fix: Codex 0.163 ran the commands of a worker in its shared background server. The commands
+  got the environment of the shell that started the server, not of the worker: no `.maf/bin` on
+  PATH, no `COORD_ROLE` and `COORD_WORKER`. maf now starts Codex with `--no-daemon`.
+- Fix: after a message run, the dispatcher counted the unclaimed tasks as dispatched and backed
+  off: 2 minutes, then 4, then more. A message run must not claim a task, so the task waited
+  without a reason. The task now runs in the next cycle.
+
 ## [0.2.0] - 2026-10-14
 
 - The sandbox also protects the flow config in `.maf/claude/` and `.maf/mcp/`, and each script

data/README.md

@@ -164,7 +164,7 @@ multi_agent_flow/
   GETTING_STARTED.md          # first-time walkthrough (concepts + manual setup)
   USER_MANUAL.md              # full team setup reference
   maf.gemspec                 # the gem: files, version, the webrick dependency
-  Gemfile                     # development gems: rake, minitest, rubocop
+  Gemfile                     # development gems: rake, minitest, rubocop, mutant
   CHANGELOG.md                # changes per version
   exe/
     maf                       # the maf command line tool (gem install maf puts it on PATH)
@@ -187,6 +187,7 @@ multi_agent_flow/
     team_command.rb           # maf team: shows the team, or sets its budget
     retire.rb                 # maf retire: removes one worker and archives its state
     worker_control.rb         # maf worker: stops, starts, or restarts one worker
+    worker_list.rb            # maf worker list: shows the sessions and dispatchers that run
     flow/role_catalog.rb      # merges .maf/roles.yml over the built-in roles
     flow/workflow.rb          # reads .maf/workflow.md for the architect prompt
     flow/mcp_config.rb        # writes the graphify MCP server into .maf/mcp/
@@ -231,6 +232,7 @@ multi_agent_flow/
     hook_session_test.rb      # tests for session isolation
     hook_config_test.rb       # tests for project hooks
     worker_control_test.rb    # tests for maf worker
+    worker_list_test.rb       # tests for maf worker list
     untrack_test.rb           # tests for maf untrack
     analyst_test.rb           # tests for the analyst
     shared_test.rb            # tests for lib/maf/shared/
@@ -336,6 +338,20 @@ them when you run a test file directly, so a test never writes to that board:
 env -u TASKRC -u COORD_DIR -u COORD_ROLE -u COORD_WORKER ruby test/coord_test.rb
 ```
 
+`rake mutant` runs the mutation tests with [mutant](https://github.com/mbj/mutant).
+Mutant changes the code in `lib/` and runs the tests again. A change that no test
+finds is an alive mutation: add a test for it. Mutant needs Ruby 3.3 or later.
+It is free for open source projects (`usage: opensource` in `.mutant.yml`).
+
+```sh
+bundle exec rake mutant                          # the subjects in .mutant.yml
+bundle exec rake mutant SUBJECT='Maf::Budget*'   # other subjects
+```
+
+Mutant runs only the test classes that name their code with `cover`. To add a
+subject, require `test/mutant_cover.rb` in the test file, add `cover "Maf::X*"` to
+the test class, and add `Maf::X*` to `matcher.subjects` in `.mutant.yml`.
+
 ```sh
 ruby test/coord_test.rb      # covers the coord CLI
 ruby test/installer_test.rb  # covers bootstrap.rb, flow.rb, setup_agent.rb
@@ -353,6 +369,7 @@ ruby test/dispatcher_test.rb         # covers the dispatcher
 ruby test/board_watch_test.rb        # covers the board watcher
 ruby test/context_watch_test.rb      # covers the context-watch hook
 ruby test/worker_control_test.rb     # covers maf worker
+ruby test/worker_list_test.rb        # covers maf worker list
 ruby test/untrack_test.rb            # covers maf untrack
 ruby test/analyst_test.rb            # covers the analyst
 ruby test/shared_test.rb             # covers lib/maf/shared/

data/assets/agents-contract.md

@@ -31,6 +31,8 @@ coord claim ID | start-task ID | done ID     # take a task, check out its branch
 coord annotate ID TEXT                       # add a note to a task
 coord lesson ID dead_end|corrected TEXT      # an approach that failed, or the right way: the graph keeps it
 coord escalate [--task ID] TEXT              # a problem you cannot fix: the project manager asks the user
+coord block ID --kind K TEXT                 # you cannot finish: K is needs_input, dependency, or capability
+coord unblock ID                             # lead roles: the blocker is gone; the task returns to coord next
 coord msg --from A [--task ID] [--fyi] TO TEXT   # message a role or a worker; --task also notes the task
                                              # --fyi: no run starts; the next run of TO reads it
 coord broadcast --from A [--to workers|leads|all] TEXT

data/assets/coord

@@ -54,6 +54,7 @@ module Coord
   # A claim older than this is presumed abandoned (crashed worker) and can be
   # taken over by `next`/`claim` without --force. Override with COORD_LEASE_TTL.
   DEFAULT_LEASE_TTL = 4 * 3600
+  BLOCKED_TAG = "blocked"
   DEFAULT_POLL_INTERVAL = 60
 
   # Lead roles plan and talk to the user. They never own a task, so they wait
@@ -86,6 +87,10 @@ module Coord
         coord conflicts                      list pending tasks with overlapping scopes
         coord claim ID [--force]             claim for COORD_WORKER (atomic; refused for lead roles)
         coord unclaim ID                     release a claim without finishing it
+        coord block ID [--kind K] TEXT...    release the claim, hold the task out of coord next, and tell
+                                             the architect (K=dependency) or the project manager
+                                             (K=needs_input, the default, capability, or failing)
+        coord unblock ID                     return a blocked task to the backlog
         coord done ID [--force]              complete (refused while the task branch lacks the goal head,
                                              or while the verify command fails)
         coord annotate ID TEXT...
@@ -120,7 +125,7 @@ module Coord
   COMMANDS = {
       "init" => :cmd_init, "add" => :cmd_add, "next" => :cmd_next,
       "conflicts" => :cmd_conflicts,
-      "claim" => :cmd_claim, "unclaim" => :cmd_unclaim,
+      "claim" => :cmd_claim, "unclaim" => :cmd_unclaim, "block" => :cmd_block, "unblock" => :cmd_unblock,
       "done" => :cmd_done, "annotate" => :cmd_annotate, "lesson" => :cmd_lesson,
     "msg" => :cmd_msg, "inbox" => :cmd_inbox, "await" => :cmd_await, "broadcast" => :cmd_broadcast,
     "log" => :cmd_log, "hooks" => :cmd_hooks,
@@ -346,6 +351,9 @@ module Coord
     rescue ArgumentError
       false
     end
+
+    def self.blocked?(task) = Array(task["tags"]).include?(BLOCKED_TAG)
+    def self.held?(task) = waiting?(task) || blocked?(task)
   end
 
   # TaskCli runs Taskwarrior and parses its output. No domain logic here.
@@ -408,6 +416,8 @@ module Coord
       export([id, "export"]).first || {}
     end
 
+    def with_goal(uuid) = export(["goalid:#{uuid}", "export"])
+
     private
 
     def run(*args)
@@ -517,7 +527,7 @@ module Coord
     end
 
     def mine(role, worker)
-      pending.select { |task| task["role"] == role && task["worker"] == worker && task["start"] }
+      pending.select { |task| task["role"] == role && task["worker"] == worker && task["start"] && actionable?(task) }
     end
 
     # Returns the prior holder (nil if there was none) so the caller can warn
@@ -537,10 +547,18 @@ module Coord
       @cli.modify(id, "worker:")
     end
 
+    def block(id)
+      unclaim(id) if @cli.task(id)["start"]
+      @cli.modify(id, "+#{BLOCKED_TAG}")
+    end
+
+    def unblock(id) = @cli.modify(id, "-#{BLOCKED_TAG}")
+
     def find(id) = @cli.task(id)
     # A short id of digits only would read as a task number. The filter avoids that.
     def find_short(short) = @cli.task("uuid.startswith:#{short}")
     def for_goal(uuid) = pending.select { |task| task["goalid"] == uuid }
+    def any_for_goal?(uuid) = @cli.with_goal(uuid).any?
     def done(id) = @cli.done(id)
     def annotate(id, text) = @cli.annotate(id, text)
     def pending = @pending ||= @cli.pending
@@ -548,7 +566,7 @@ module Coord
 
     private
 
-    def actionable?(task) = !Schedule.waiting?(task)
+    def actionable?(task) = !Schedule.held?(task)
 
     def held_by?(task, worker) = !worker.to_s.empty? && task["worker"] == worker
 
@@ -1097,9 +1115,10 @@ end
 # Board renders status summaries and the Obsidian kanban file.
   class Board
     SECTIONS = {
-      "Backlog" => ->(task) { !Schedule.waiting?(task) && !task["start"] },
-      "In progress" => ->(task) { !Schedule.waiting?(task) && task["start"] },
-      "Waiting" => ->(task) { Schedule.waiting?(task) }
+      "Backlog" => ->(task) { !Schedule.held?(task) && !task["start"] },
+      "In progress" => ->(task) { !Schedule.held?(task) && task["start"] },
+      "Waiting" => ->(task) { Schedule.waiting?(task) && !Schedule.blocked?(task) },
+      "Blocked" => ->(task) { Schedule.blocked?(task) }
     }.freeze
 
     def initialize(tasks, paths)
@@ -1149,6 +1168,7 @@ end
     end
 
     def bucket(task)
+      return "blocked" if Schedule.blocked?(task)
       return "waiting" if Schedule.waiting?(task)
 
       task["start"] ? "in-progress" : "backlog"
@@ -1185,6 +1205,8 @@ end
     def self.run(dir, *args) = system("git", "-C", dir, *args, out: File::NULL, err: File::NULL)
     def self.branch?(dir, name) = run(dir, "show-ref", "--verify", "--quiet", "refs/heads/#{name}")
     def self.clean?(dir) = `git -C #{Shellwords.escape(dir)} status --porcelain --untracked-files=no`.strip.empty?
+    def self.changed(dir) = out(dir, "diff", "HEAD", "--name-only").lines(chomp: true)
+    def self.remote_branch?(dir, remote, name) = run(dir, "ls-remote", "--exit-code", "--heads", remote, name)
     def self.out(dir, *args) = IO.popen(["git", "-C", dir, *args], err: File::NULL, &:read).strip
     def self.ancestor?(dir, older, newer) = run(dir, "merge-base", "--is-ancestor", older, newer)
     def self.own_commits?(dir, base, branch) = out(dir, "rev-list", "--count", "#{base}..#{branch}").to_i.positive?
@@ -1245,11 +1267,12 @@ end
       goals.each { |goal| puts goal_line(goal) }
     end
 
-    def show(id)
+    def show(id, artifacts_dir)
       goal = find!(id)
       puts goal_line(goal)
       list = @tasks.for_goal(goal["uuid"])
       list.empty? ? puts("  no open tasks") : list.each { |task| puts task_line(task) }
+      plan_hint(goal["uuid"], artifacts_dir)
     end
 
     def done(id)
@@ -1266,6 +1289,13 @@ end
 
     private
 
+    def plan_hint(uuid, artifacts_dir)
+      plan = File.join(artifacts_dir, uuid, "plan.md")
+      return unless File.exist?(plan) && !@tasks.any_for_goal?(uuid)
+
+      puts "  plan ready, no tasks: #{plan}. The plan waits for approval."
+    end
+
     def goal_line(goal)
       open = @tasks.for_goal(goal["uuid"]).size
       [goal["uuid"], goal["description"], self.class.branch(goal["uuid"]), "open=#{open}"].join("\t")
@@ -1286,7 +1316,7 @@ end
     end
 
     def start(uuid, base)
-      raise Error, "uncommitted changes in #{@dir}. Commit or stash them first." unless Git.clean?(@dir)
+      refuse_dirty!
 
       branch = "task/#{Goals.short(uuid)}"
       raise Error, "git checkout #{branch} failed" unless checkout(branch, base)
@@ -1296,6 +1326,17 @@ end
 
     private
 
+    FLOW_FILES = "These are files of the flow, and git tracks them. In the main checkout, run maf untrack and commit."
+
+    def refuse_dirty!
+      paths = Git.changed(@dir)
+      return if paths.empty?
+
+      flow = paths.all? { |path| path.start_with?(".maf/") || Worktree::RUNTIME_FILES.include?(path) }
+      raise Error, ["uncommitted changes in #{@dir}: #{paths.first(5).join(", ")}#{" ..." if paths.size > 5}.",
+                    flow ? FLOW_FILES : "Commit or stash them first."].join(" ")
+    end
+
     def checkout(branch, base)
       return Git.run(@dir, "checkout", "-q", branch) if Git.branch?(@dir, branch)
 
@@ -1351,8 +1392,8 @@ end
   # commit. The task branch is then deleted. A worker worktree that still has
   # the task branch checked out moves back to its worker branch first.
   class Land
-    def initialize(root, task)
-      @root, @task = root, task
+    def initialize(root, task, base)
+      @root, @task, @base = root, task, base
     end
 
     def run(subject)
@@ -1381,8 +1422,14 @@ end
       return nil unless Git.own_commits?(@root, goal_branch, branch)
       raise Error, STALE % { branch: branch, goal: goal_branch } unless Git.ancestor?(@root, goal_branch, branch)
 
+      parent = base_parent
       merge_squash
-      commit(SquashMessage.for(@task, subject))
+      commit(SquashMessage.for(@task, subject), parent)
+    end
+
+    def base_parent
+      held = Git.out(@root, "merge-base", Git.base_ref(@root, @base), branch)
+      held unless held.empty? || Git.ancestor?(@root, held, goal_branch)
     end
 
     STALE = "branch %<branch>s lacks the head of %<goal>s. Open a fix task: merge %<goal>s into %<branch>s."
@@ -1395,14 +1442,30 @@ end
     end
 
     # coord makes this commit, not the role, so the commit guard does not apply.
-    def commit(message)
-      return nil if Git.run(goal_dir, "diff", "--cached", "--quiet")
+    def commit(message, parent)
+      return nil if Git.run(goal_dir, "diff", "--cached", "--quiet") && parent.nil?
+
+      parent ? merge_commit(message, parent) : squash_commit(message)
+      Git.out(goal_dir, "rev-parse", "--short", "HEAD")
+    end
 
+    def squash_commit(message)
       args = ["git", "-C", goal_dir, "commit", "-q", "--no-verify", "-F", "-"]
       IO.popen(args, "w") { |io| io.write(message) }
       raise Error, "git commit on #{goal_branch} failed" unless $?.success?
+    end
 
-      Git.out(goal_dir, "rev-parse", "--short", "HEAD")
+    def merge_commit(message, parent)
+      head = Git.out(goal_dir, "rev-parse", "HEAD")
+      sha = commit_tree(message, head, parent)
+      moved = sha && Git.run(goal_dir, "update-ref", "HEAD", sha, head)
+      raise Error, "git commit on #{goal_branch} failed" unless moved
+    end
+
+    def commit_tree(message, *parents)
+      args = ["commit-tree", Git.out(goal_dir, "write-tree"), *parents.flat_map { |sha| ["-p", sha] }, "-F", "-"]
+      sha, status = Open3.capture2("git", "-C", goal_dir, *args, stdin_data: message)
+      sha.strip if status.success?
     end
 
     def release_branch
@@ -1648,6 +1711,18 @@ end
       raise Error, "git push of #{branch} to #{remote} failed"
     end
 
+    def push_with_base(branch, base)
+      push_missing(base)
+      push(branch)
+    end
+
+    def push_missing(branch)
+      return if !Git.branch?(@root, branch) || Git.remote_branch?(@root, remote, branch)
+
+      push(branch)
+      puts "pushed #{branch}: #{remote} had no branch #{branch}"
+    end
+
     def create_pr(head:, base:, title:, body:)
       args = ["--head", head, "--base", base, "--title", title, "--reviewer", reviewer, "--body-file", "-"]
       gh("pr", "create", "--repo", repo, *args, input: body).lines.last.to_s.strip
@@ -2086,7 +2161,10 @@ end
     def timeout = (v = value_of("--timeout")) && v.to_i
 
     def require_arg(command, name)
-      shift || abort("usage: coord #{command} #{name}")
+      value = shift
+      abort("usage: coord #{command} #{name}") if value.nil? || value.start_with?("-")
+
+      value
     end
 
     def require_text(command)
@@ -2244,6 +2322,42 @@ end
     end
   end
 
+  # Block commands hold a task out of coord next, tell the role that can
+  # remove the blocker, and return the task.
+  module BlockCommands
+    BLOCK_KINDS = %w[needs_input dependency capability failing].freeze
+    BLOCK_USAGE = "usage: coord block ID [--kind #{BLOCK_KINDS.join("|")}] TEXT...".freeze
+
+    def cmd_block
+      kind = block_kind(@args.value_of("--kind") || BLOCK_KINDS.first)
+      id = @args.require_arg("block", "ID")
+      block(id, kind, @args.require_text("block"))
+      puts "blocked #{id} (#{kind})"
+    end
+
+    def block(id, kind, text)
+      tasks.annotate(id, "BLOCKED (#{kind}): #{text}")
+      tasks.block(id)
+      event_log.append("block", @worker, "#{id} #{kind} #{text}")
+      notify_block(id, kind, text)
+    end
+
+    def block_kind(kind) = BLOCK_KINDS.include?(kind) ? kind : abort(BLOCK_USAGE)
+
+    def notify_block(id, kind, text)
+      return deliver("architect", @role, "BLOCKED task #{id} (dependency), #{@worker}: #{text}") if kind == "dependency"
+
+      send_escalation(id, "blocked (#{kind}): #{text}")
+    end
+
+    def cmd_unblock
+      id = @args.require_arg("unblock", "ID")
+      tasks.unblock(id)
+      event_log.append("unblock", @worker, id)
+      puts "unblocked #{id}"
+    end
+  end
+
   # Claim commands take, release, note, and finish a task.
   module ClaimCommands
     def cmd_claim
@@ -2457,8 +2571,9 @@ end
       event_log.append("broadcast", @worker, text)
     end
 
-    NO_PUSH = "coord: %<role>s has no live session and no message hook. The message waits until a %<role>s " \
-              "session starts. Fix: maf start HARNESS %<role>s --dispatch --detach, " \
+    NO_PUSH = "coord: %<role>s has no live session and no message hook. " \
+              "The message waits until a session of %<role>s starts. " \
+              "Fix: maf start HARNESS %<role>s --dispatch --detach, " \
               "or add an executable .maf/coordination/message-hooks/%<role>s.sh"
 
     # A message is pushed by a hook or read by a live session. Without both,
@@ -2567,7 +2682,7 @@ end
     def cmd_land
       subject = @args.value_of("--subject")
       task = find_task!(@args.require_arg("land", "ID"))
-      land = Land.new(main_root, task)
+      land = Land.new(main_root, task, Git.base_branch(main_root, manifest))
       commit = locks.with_mutex("land-#{Goals.short(task["goalid"])}", worker: @worker) { land.run(subject) }
       record_landing(task, commit, land)
     end
@@ -2590,7 +2705,7 @@ end
       setup.ensure_taskrc
       goals.find!(id)["uuid"]
     end
-    def goal_show = goals.show(@args.require_arg("goal show", "ID"))
+    def goal_show = goals.show(@args.require_arg("goal show", "ID"), File.join(paths.coord_dir, "artifacts"))
 
     def goal_sync
       goal = goals.find!(@args.require_arg("goal sync", "ID"))
@@ -2620,11 +2735,18 @@ end
       raise Error, "base branch #{base} does not exist" unless Git.branch?(main_root, base)
 
       uuid = tasks.add(title: opts[:title], role: Goals::ROLE, ref: opts[:ref])
-      Worktree.new(main_root).checkout(Goals.slug(uuid), Goals.branch(uuid), base)
+      open_goal_branch(uuid, base)
       event_log.append("goal", @worker, opts[:title])
       puts uuid
     end
 
+    def open_goal_branch(uuid, base)
+      Worktree.new(main_root).checkout(Goals.slug(uuid), Goals.branch(uuid), base)
+      return if !Git.run(main_root, "remote", "get-url", "origin") || Git.remote_branch?(main_root, "origin", base)
+
+      warn "coord: origin has no branch #{base}. coord goal pr pushes the local #{base} again."
+    end
+
     UNSYNCED = "coord: %<branch>s lacks the head of %<ref>s. Run coord goal sync %<id>s. " \
                "Run the merge suite again. Then run coord goal done again."
 
@@ -2718,7 +2840,7 @@ end
 
     def publish_goal(goal, entry)
       branch = Goals.branch(goal["uuid"])
-      github.push(branch)
+      github.push_with_base(branch, Git.base_branch(main_root, manifest))
       push_memory
       entry = entry ? update_pr(goal, entry, branch) : { "url" => open_pr(goal, branch), "seen" => [] }
       review_state.put(goal["uuid"], entry.merge("head" => Git.out(main_root, "rev-parse", branch)))
@@ -2805,6 +2927,7 @@ end
     def cmd_worktree
       role = @args.require_arg("worktree", "ROLE")
       worker = @args.shift
+      abort "usage: coord worktree ROLE [WORKER]" if worker&.start_with?("-")
       warn_missing_role_files(role)
       Worktree.new(@project_root).create(role, worker)
     end
@@ -2900,6 +3023,7 @@ end
   class CLI
     include TaskCommands
     include ClaimCommands
+    include BlockCommands
     include MessageCommands
     include InboxCommands
     include GoalCommands

data/assets/dispatcher

@@ -11,7 +11,7 @@
 #    dispatcher polls the inbox and the task board on a fixed interval.
 #
 # Usage:
-#   dispatcher ROLE (--harness NAME | --command TEMPLATE) [--model M]
+#   dispatcher ROLE (--harness NAME | --command TEMPLATE) [--model M] [--effort L]
 #                     [--skill NAME | --no-skill] [--interval S] [--max-turns N]
 #                     [--timeout S] [--idle-timeout S] [--grace S]
 #                     [--completion-signal TEXT] [--abort-signal TEXT]
@@ -31,10 +31,12 @@
 #                      (claude, codex, cursor, hermes, opencode). Each one
 #                      resumes sessions. --harness or --command is required.
 #   --command TEMPLATE Any other harness. A shell command with %{prompt},
-#                      %{role}, %{skill}, and %{model} placeholders, each
+#                      %{role}, %{skill}, %{model}, and %{effort} placeholders, each
 #                      shell-escaped. The command must exit when done.
 #                      Sessions are not resumed for custom commands.
 #   --model M          Model for the agent, in the harness CLI's own format.
+#   --effort L         Effort level of the model, in the harness CLI's own
+#                      format (for example high). Default: the harness default.
 #   --skill NAME       Hermes skill to preload. Default: <project>-<role> when
 #                      flow.rb generated it.
 #   --no-skill         Do not preload a skill.
@@ -99,7 +101,9 @@
 # atomic, so a run never starts for a task that another worker took. If the
 # same task set is still unclaimed afterwards, it waits with a doubling
 # backoff (capped at MAX_BACKOFF) before it tries again. A changed task set
-# dispatches at once.
+# dispatches at once. After MAX_ATTEMPTS runs in a row that leave a task
+# claimed and not done, the dispatcher blocks the task (`coord block --kind
+# failing`), which escalates it. A usage limit or an unknown model counts no run.
 #
 # Sessions and the prompt cache: the session ID is saved to
 # .maf/coordination/sessions/<worker>.session and resumed on the next run, so the
@@ -151,7 +155,7 @@ module Dispatcher
   MAX_BACKOFF = 3600
   REPORT_RETRIES = 1
 
-  Config = Struct.new(:role, :harness, :command, :model, :skill, :no_skill, :interval, :max_turns,
+  Config = Struct.new(:role, :harness, :command, :model, :effort, :skill, :no_skill, :interval, :max_turns,
                       :timeout, :idle_timeout, :grace, :completion_signal, :abort_signal,
                       :cache_window, :max_session_runs, :max_context, :once, :poll_tasks, :worker, :coord_dir,
                       :verbose, :lean,
@@ -318,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
@@ -764,10 +811,11 @@ module Dispatcher
     module Generic
       extend Maf::Shared::Harness::Run
 
-      PLACEHOLDERS = %i[prompt role skill model].freeze
+      PLACEHOLDERS = %i[prompt role skill model effort].freeze
 
       def self.build_command(config, prompt, _session_id)
-        values = { prompt: prompt, role: config.role, skill: config.skill, model: config.model }
+        values = { prompt: prompt, role: config.role, skill: config.skill, model: config.model,
+                   effort: config.effort }
         line = PLACEHOLDERS.reduce(config.command) { |cmd, key| cmd.gsub("%{#{key}}") { values[key].to_s.shellescape } }
         ["sh", "-c", line]
       end
@@ -906,7 +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)
@@ -1309,6 +1357,7 @@ module Dispatcher
       Log.line("usage limit: no new run until #{@pause.until.utc}")
     end
     def chores = @chores ||= LeadChores.new(@poller, @config.role)
+    def failure_limit = @failure_limit ||= FailureLimit.new(@config, @poller)
 
     def start
       Log.line("started: role=#{@config.role} #{harness_label} #{timing_label}")
@@ -1337,11 +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
 
@@ -1350,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
@@ -1366,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
@@ -1374,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],