maf 0.1.0

data/assets/coord

@@ -0,0 +1,2936 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# coord - shared coordination layer for multi-agent development.
+#
+# Storage:  .maf/coordination/ (Taskwarrior board, inbox, locks, exports)
+# Locking:  mkdir-based (portable on macOS and Linux; no flock required)
+# Deps:     task (Taskwarrior). Ruby parses the JSON itself; no jq needed.
+# Ruby:     3.0+ (uses endless method defs: `def x = expr`). This file will
+#           not parse under Ruby 2.x; ensure `ruby` on PATH is 3.0+.
+#
+# Agents should use this wrapper, not raw `task`, so the protocol stays stable.
+require "json"
+require "fileutils"
+require "time"
+require "shellwords"
+require "rbconfig"
+require "optparse"
+require "open3"
+require "pathname"
+begin
+  require_relative "../lib/maf/shared/processes"
+  require_relative "../lib/maf/shared/project"
+  require_relative "../lib/maf/shared/roles"
+  require_relative "../lib/maf/shared/git_exclude"
+  require_relative "../lib/maf/shared/git_identity"
+rescue LoadError
+  abort "coord: the maf shared library is missing. Run maf update."
+end
+
+module Coord
+  class Error < StandardError; end
+
+  # NOTE: MARKER is duplicated in bootstrap.rb on purpose. Both scripts run
+  # standalone (coord is copied into projects), so they share no load path.
+  MARKER = ">>> multi-agent-flow >>>"
+  # The one folder that holds every file of the flow in a project.
+  MAF_DIR = ".maf"
+  UUID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/
+
+  TASKRC_BLOCK = <<~BLOCK
+    # >>> multi-agent-flow >>>
+    uda.role.type=string
+    uda.worker.type=string
+    uda.scope.type=string
+    uda.taskref.type=string
+    uda.goalid.type=string
+    # Hide the "TASKRC override" footnote. coord always sets TASKRC.
+    verbose=blank,header,footnote,label,new-id,affected,edit,special,project,sync,filter,recur
+    # <<< multi-agent-flow <<<
+  BLOCK
+
+  # 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
+  DEFAULT_POLL_INTERVAL = 60
+
+  # Lead roles plan and talk to the user. They never own a task, so they wait
+  # on their inbox, not on the task board.
+  LEADS = Maf::Shared::Roles::LEADS
+
+  # Usage holds the help text of coord.
+  module Usage
+    TEXT = <<~TEXT
+      coord - multi-agent coordination
+
+        coord init
+        coord add --role R --scope S --title T [--project P] [--ref R] [--goal ID]
+        coord goal add --title T [--ref R] [--base BRANCH]   create a goal, its branch and its worktree
+        coord goal list                      list open goals
+        coord goal show ID                   show a goal and its tasks
+        coord goal sync ID                   merge the base branch into the goal branch
+        coord goal done ID                   close a goal (refused while a task is open or the goal lacks the base head)
+        coord goal pr ID                     push the goal branch as the GitHub bot and open or update its pull request
+        coord review-watch [--once] [--interval S]
+                                             send new reviews of goal pull requests to the architect;
+                                             close a goal and run gc --yes after its pull request merges
+        coord land ID [--subject TEXT]       squash a done task branch into its goal branch, then delete the task branch
+        coord reap [--minutes N]             release the claims of workers not seen for N minutes
+                                             (default: team.reap_minutes, else 90; a live dispatcher is never released)
+        coord gc [--yes]                     list (or with --yes delete) merged flow branches and finished goal worktrees
+        coord show ID                        show one task: its fields and its annotations
+        coord start-task ID                  check out branch task/<id> from its goal branch
+        coord next [ROLE] [--mine] [--wait [--interval S] [--timeout S]]
+        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 done ID [--force]              complete (refused while the task branch lacks the goal head,
+                                             or while the verify command fails)
+        coord annotate ID TEXT...
+        coord lesson ID dead_end|corrected TEXT...
+                                             save a lesson of a task to the graph memory: an approach that
+                                             failed (dead_end), or the right way (corrected)
+        coord msg [--from A] [--task ID] [--fyi] TO TEXT...
+                                             TO is a role or a worker; a worker's mail goes to its role inbox.
+                                             --task also saves the text as a note on the task.
+                                             --fyi wakes no one: the next run of TO reads the message.
+        coord escalate [--task ID] TEXT...   report a problem you cannot fix to the project manager
+                                             (copy to the architect)
+        coord broadcast [--from A] [--to workers|leads|all] TEXT...
+                                             send to a group of roles (default: workers)
+        coord inbox [ROLE] [--peek] [--all] [--wait [--interval S] [--timeout S]]
+        coord await [--timeout S]            interactive session: arm the stop hook, then end the turn.
+                                             The hook waits for work without model calls (default: 3000s)
+        coord hooks [ROLE]                          show message hooks for a role or all
+        coord log [N]                               show last N coordination events
+        coord lock NAME [--ttl SECONDS] [--worker W]
+        coord unlock NAME
+        coord with-lock NAME [--ttl SECONDS] -- CMD...
+        coord worktree ROLE [WORKER]          create a git worktree + branch for a role
+        coord status
+        coord who                            list workers with their presence (live or gone)
+        coord board
+        coord export
+        coord help
+    TEXT
+  end
+
+  COMMANDS = {
+      "init" => :cmd_init, "add" => :cmd_add, "next" => :cmd_next,
+      "conflicts" => :cmd_conflicts,
+      "claim" => :cmd_claim, "unclaim" => :cmd_unclaim,
+      "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,
+    "lock" => :cmd_lock, "unlock" => :cmd_unlock, "with-lock" => :cmd_with_lock,
+    "worktree" => :cmd_worktree, "goal" => :cmd_goal, "start-task" => :cmd_start_task,
+    "land" => :cmd_land, "gc" => :cmd_gc, "reap" => :cmd_reap, "review-watch" => :cmd_review_watch,
+    "show" => :cmd_show, "escalate" => :cmd_escalate,
+    "status" => :cmd_status, "board" => :cmd_board, "export" => :cmd_export,
+    "who" => :cmd_who, "help" => :cmd_help
+  }.freeze
+
+  ADD_OPTS = { "--role" => :role, "--scope" => :scope, "--ref" => :ref,
+               "--project" => :project, "--title" => :title, "--goal" => :goal }.freeze
+  GOAL_OPTS = { "--title" => :title, "--ref" => :ref, "--base" => :base }.freeze
+
+  # Wiring lazily builds the collaborators the CLI needs.
+  module Wiring
+    def paths = @paths ||= Paths.new(@coord_dir)
+    def setup = @setup ||= Setup.new(paths, @taskrc)
+    def tasks = @tasks ||= Tasks.new
+    def conflicts = @conflicts ||= Conflicts.new(tasks)
+    def locks = @locks ||= Locks.new(paths)
+    def messages = @messages ||= Messages.new(paths, @role)
+    def board = @board ||= Board.new(tasks, paths)
+    def event_log = @event_log ||= EventLog.new(paths)
+    def hooks = @hooks ||= Hooks.new(paths)
+    def presence = @presence ||= Presence.new(paths)
+  end
+
+  # Paths resolves every coordination path from one root.
+  class Paths
+    attr_reader :coord_dir
+
+    def initialize(coord_dir)
+      @coord_dir = coord_dir
+    end
+
+    def inbox_dir(role) = File.join(coord_dir, "inbox", role.to_s)
+
+    # Folders named <role>-<n>, written by older versions for one worker.
+    def worker_inbox_dirs(role)
+      pattern = /\A#{Regexp.escape(role.to_s)}-\d+\z/
+      Dir.glob(File.join(coord_dir, "inbox", "#{role}-*")).select { |dir| File.basename(dir).match?(pattern) }
+    end
+    def message_hooks_dir = File.join(coord_dir, "message-hooks")
+    def hook_path(role) = File.join(message_hooks_dir, "#{role}.sh")
+    def locks_dir = File.join(coord_dir, "locks")
+    def exports_dir = File.join(coord_dir, "exports")
+    def lock_dir(name) = File.join(locks_dir, "#{name}.d")
+    def lock_meta(name) = File.join(lock_dir(name), "meta.json")
+    def export_path = File.join(exports_dir, "tasks.json")
+    def board_path = File.join(exports_dir, "board.md")
+    def taskdata_dir = File.join(coord_dir, "taskdata")
+    def log_path = File.join(coord_dir, "events.log")
+    def hook_log(role) = File.join(message_hooks_dir, "#{role}.log")
+    def presence_dir = File.join(coord_dir, "presence")
+    def usage_dir = File.join(coord_dir, "usage")
+    def manifest_path = File.join(File.dirname(File.expand_path(coord_dir)), "config.json")
+    def vault_path = File.join(File.dirname(File.expand_path(coord_dir)), "bin", "vault")
+  end
+
+  # Setup creates the coordination directories and the Taskwarrior UDAs.
+  # The Taskwarrior database is project-local (.maf/coordination/taskdata), not the
+  # user's global ~/.task, so two projects never share one board. An explicit
+  # TASKRC env var still overrides this (see CLI#initialize).
+  class Setup
+    SUBDIRS = %w[inbox locks exports message-hooks].freeze
+
+    def initialize(paths, taskrc)
+      @paths = paths
+      @taskrc = taskrc
+    end
+
+    def ensure_dirs
+      SUBDIRS.each { |sub| FileUtils.mkdir_p(File.join(@paths.coord_dir, sub)) }
+    end
+
+    def ensure_taskrc
+      had_marker = File.exist?(@taskrc) && File.read(@taskrc).include?(MARKER)
+      FileUtils.mkdir_p(File.dirname(@taskrc))
+      FileUtils.touch(@taskrc)
+      ensure_data_location(warn_when_external: !had_marker)
+      had_marker ? add_missing_udas : append_uda_block
+    end
+
+    private
+
+    # An explicit TASKRC pointed outside coord_dir (e.g. a user's own
+    # ~/.taskrc) is a deliberate choice to use their own database. Only touch
+    # data.location in the taskrc this tool created and owns, never redirect
+    # someone else's existing Taskwarrior config to a project-local database.
+    def project_local?
+      File.expand_path(File.dirname(@taskrc)) == File.expand_path(@paths.coord_dir)
+    end
+
+    # Never redirect an external taskrc (e.g. a personal ~/.taskrc), and warn
+    # once that it is used as-is. A project-local taskrc this tool owns but
+    # that predates the project-local database (marker present, no
+    # data.location) would otherwise fall back to the global ~/.task; add the
+    # missing data.location in place.
+    def ensure_data_location(warn_when_external:)
+      return warn_external if warn_when_external && !project_local?
+
+      write_data_location if project_local? && !has_data_location?
+    end
+
+    def warn_external
+      warn "coord: TASKRC=#{@taskrc} is outside .maf/coordination/; using its existing database as-is, " \
+           "not redirecting it."
+    end
+
+    def write_data_location
+      FileUtils.mkdir_p(@paths.taskdata_dir)
+      File.open(@taskrc, "a") do |file|
+        file.puts unless file.size.zero?
+        file.puts("data.location=#{File.expand_path(@paths.taskdata_dir)}")
+      end
+    end
+
+    def append_uda_block
+      File.open(@taskrc, "a") do |file|
+        file.puts unless file.size.zero?
+        file.puts(TASKRC_BLOCK)
+      end
+    end
+
+    # A taskrc from an older coord lacks UDAs and settings added later. Taskwarrior reads an
+    # unknown NAME:VALUE as description text, so add each missing line.
+    def add_missing_udas
+      text = File.read(@taskrc)
+      missing = TASKRC_BLOCK.lines.grep(/\A(uda\.|verbose=)/).reject { |line| text.include?(line) }
+      File.write(@taskrc, text.sub(/^# <<< multi-agent-flow <<<$/) { missing.join + $& }) unless missing.empty?
+    end
+
+    def has_data_location?
+      File.exist?(@taskrc) && File.read(@taskrc).match?(/^data\.location=/)
+    end
+  end
+
+  # Scopes compares path scopes with a component-prefix heuristic.
+  # It understands "dir/**" and exact paths, not {} alternation or mid-globs.
+  module Scopes
+    GLOB = /[*?\[\{]/
+
+    def self.overlap?(left, right)
+      patterns(left).product(patterns(right)).any? { |a, b| pair_overlap?(a, b) }
+    end
+
+    def self.pair_overlap?(left, right)
+      # A top-level glob ("*.rb") has an empty base: an empty prefix matches
+      # any path, so treating it like a normal prefix would flag it as
+      # overlapping every other scope. Only count it as overlap when the
+      # pattern is literally the same.
+      return left == right if base(left).empty? || base(right).empty?
+
+      prefix?(base(left), base(right)) || prefix?(base(right), base(left))
+    end
+
+    def self.base(scope)
+      scope.split("/").take_while { |part| part !~ GLOB }
+    end
+
+    def self.prefix?(short, long)
+      short == long.first(short.size)
+    end
+
+    def self.patterns(scope)
+      scope.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+  end
+
+  # Conflicts finds overlapping scopes among pending tasks and reports them.
+  class Conflicts
+    def initialize(tasks)
+      @tasks = tasks
+    end
+
+    def with(scope, exclude: nil)
+      candidates(exclude).select { |task| Scopes.overlap?(task["scope"], scope) }
+    end
+
+    def warn_with(scope, exclude:)
+      with(scope, exclude: exclude).each { |task| warn warning(scope, task) }
+    end
+
+    def report
+      pairs = all
+      return puts("no scope conflicts") if pairs.empty?
+
+      pairs.each { |a, b| puts line(a, b) }
+    end
+
+    private
+
+    def all
+      @tasks.pending.combination(2).select { |a, b| Scopes.overlap?(a["scope"], b["scope"]) }
+    end
+
+    def candidates(exclude)
+      @tasks.pending.reject { |task| task["uuid"] == exclude }
+    end
+
+    def warning(scope, task)
+      "coord: scope '#{scope}' overlaps task #{task["uuid"]} " \
+        "owned by #{task["role"]} (#{task["scope"]})"
+    end
+
+    def line(a, b)
+      "#{a["role"]} #{a["scope"]} (#{a["uuid"]}) <> #{b["role"]} #{b["scope"]} (#{b["uuid"]})"
+    end
+  end
+
+  # Tasks wraps the Taskwarrior CLI. Every query is scoped to one task.
+  # Schedule interprets Taskwarrior date fields.
+  module Schedule
+    # Taskwarrior keeps the `wait` field after the date elapses; it only stops
+    # filtering the task out of default reports. Compare the date, not presence.
+    def self.waiting?(task)
+      wait = task["wait"].to_s
+      return false if wait.empty?
+
+      Time.parse(wait) > Time.now
+    rescue ArgumentError
+      false
+    end
+  end
+
+  # TaskCli runs Taskwarrior and parses its output. No domain logic here.
+  class TaskCli
+    def available?
+      @available = system("task", "--version", out: File::NULL, err: File::NULL) if @available.nil?
+      @available
+    end
+
+    def require!
+      raise Error, "Taskwarrior ('task') is not installed. See README (brew install task)." unless available?
+    end
+
+    # `--` forces every following word into the description, even one that
+    # reads like an attribute ("due:tomorrow", "scope:x"). Without it, a title
+    # or annotation matching NAME:VALUE for a built-in or registered UDA is
+    # parsed as that attribute and the text is silently lost.
+    def create(args)
+      require!
+      output = capture(args)
+      extract_uuid(output) || add_failed(output)
+    end
+
+    # The add may have succeeded even when the uuid could not be read back
+    # (extract_uuid queries the created task again). Distinguish the two so a
+    # caller does not retry and create a duplicate.
+    def add_failed(output)
+      id = created_id(output)
+      raise Error, "task #{id} was created but its uuid could not be read" if id
+
+      raise Error, "task add failed: #{last_line(output)}"
+    end
+
+    def modify(id, *args)
+      run(id, "modify", *args) || raise(Error, "task modify failed")
+    end
+
+    def done(id)
+      require!
+      run(id, "done") || raise(Error, "task done failed")
+    end
+
+    def stop(id)
+      run(id, "stop") || raise(Error, "task stop failed")
+    end
+
+    def annotate(id, text)
+      require!
+      run(id, "annotate", "--", text) || raise(Error, "annotate failed")
+    end
+
+    # `status:pending` hides waited tasks; include them so the board can show
+    # a Waiting column. Waited tasks still export status "pending"; the `wait`
+    # field is the discriminator.
+    def pending
+      export(["(", "status:pending", "or", "status:waiting", ")", "export"])
+    end
+
+    def task(id)
+      export([id, "export"]).first || {}
+    end
+
+    private
+
+    def run(*args)
+      system("task", *args, out: File::NULL, err: File::NULL)
+    end
+
+    def capture(args)
+      `task #{Shellwords.join(args)} 2>&1`
+    end
+
+    def export(args)
+      raw = `task #{Shellwords.join(args)} 2>/dev/null`
+      raw.strip.empty? ? [] : JSON.parse(raw)
+    rescue JSON::ParserError
+      []
+    end
+
+    # Prefer a UUID printed by Taskwarrior; otherwise read the id from
+    # "Created task N" and export that one task. Never query the whole database.
+    def extract_uuid(output)
+      output[UUID_PATTERN] || uuid_from_created(output)
+    end
+
+    def uuid_from_created(output)
+      id = created_id(output)
+      id && task(id)["uuid"]
+    end
+
+    def created_id(output)
+      output[/Created task (\d+)/, 1]
+    end
+
+    def last_line(output)
+      output.lines.map(&:strip).reject(&:empty?).last || "no task id returned"
+    end
+  end
+
+  # Lease interprets how long a claim is honored without renewal. A claim
+  # older than the lease is presumed abandoned (the worker crashed) and
+  # becomes claimable again without --force.
+  module Lease
+    @warned = {}
+
+    # An unset, empty, non-numeric, or non-positive COORD_LEASE_TTL falls back
+    # to the default instead of collapsing to 0 (which would make every claim
+    # look instantly expired). Warn once per distinct bad value.
+    def self.ttl
+      raw = ENV["COORD_LEASE_TTL"].to_s
+      return DEFAULT_LEASE_TTL if raw.empty?
+
+      value = Integer(raw, exception: false)
+      value&.positive? ? value : invalid_ttl(raw)
+    end
+
+    def self.invalid_ttl(raw)
+      warn "coord: invalid COORD_LEASE_TTL=#{raw.inspect}; using default #{DEFAULT_LEASE_TTL}s" unless @warned[raw]
+      @warned[raw] = true
+      DEFAULT_LEASE_TTL
+    end
+
+    def self.expired?(task)
+      start = task["start"].to_s
+      return false if start.empty?
+
+      Time.parse(start) + ttl <= Time.now
+    rescue ArgumentError
+      false
+    end
+  end
+
+  # TaskView formats one task with its annotations. An agent reads the task
+  # spec through `coord show`, never through raw `task`.
+  module TaskView
+    FIELDS = %w[uuid description role scope goalid worker status start].freeze
+
+    def self.lines(task)
+      FIELDS.filter_map { |field| "#{field}: #{task[field]}" if task[field] } + notes(task)
+    end
+
+    def self.notes(task)
+      (task["annotations"] || []).map { |note| "note #{note["entry"]}: #{note["description"]}" }
+    end
+  end
+
+  # Tasks exposes the task operations the flow needs.
+  class Tasks
+    # The previous owner of a task, split so a steal notice can go to the
+    # role's inbox (what agents poll) while still naming the exact worker.
+    Holder = Struct.new(:role, :worker)
+
+    # The goal attribute is `goalid`, not `goal`: Taskwarrior drops the value
+    # `role:goal` when a UDA has the same name as the value.
+    ATTRIBUTES = { role: "role", scope: "scope", ref: "taskref", project: "project", goal: "goalid" }.freeze
+
+    def initialize
+      @cli = TaskCli.new
+    end
+
+    def available? = @cli.available?
+
+    def add(title:, **opts)
+      @cli.create(add_args(title, opts))
+    end
+
+    def next_for(role, worker = nil)
+      pending.select { |task| task["role"] == role && claimable?(task) && actionable?(task) && !held_by?(task, worker) }
+    end
+
+    def mine(role, worker)
+      pending.select { |task| task["role"] == role && task["worker"] == worker && task["start"] }
+    end
+
+    # Returns the prior holder (nil if there was none) so the caller can warn
+    # or notify them. Refuses only an active (non-expired) claim by someone
+    # else, unless --force.
+    def claim(id, worker, force: false)
+      @cli.require!
+      task = @cli.task(id)
+      holder = task["worker"].to_s
+      refuse_steal(id, holder) if active_claim?(task, holder, worker) && !force
+      @cli.modify(id, "worker:#{worker}", "start:now") && (Holder.new(task["role"].to_s, holder) unless holder.empty?)
+    end
+
+    def unclaim(id)
+      @cli.require!
+      @cli.stop(id)
+      @cli.modify(id, "worker:")
+    end
+
+    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 done(id) = @cli.done(id)
+    def annotate(id, text) = @cli.annotate(id, text)
+    def pending = @pending ||= @cli.pending
+    def export_to(path) = File.write(path, JSON.pretty_generate(pending))
+
+    private
+
+    def actionable?(task) = !Schedule.waiting?(task)
+
+    def held_by?(task, worker) = !worker.to_s.empty? && task["worker"] == worker
+
+    def claimable?(task) = task["worker"].to_s.empty? || Lease.expired?(task)
+
+    def active_claim?(task, holder, worker)
+      !holder.empty? && holder != worker && !Lease.expired?(task)
+    end
+
+    def refuse_steal(id, holder)
+      raise Error, "task #{id} is already claimed by #{holder} (use --force to steal)"
+    end
+
+    def add_args(title, opts)
+      ["add"] + attribute_args(opts) + ["--", title]
+    end
+
+    def attribute_args(opts)
+      ATTRIBUTES.filter_map { |key, attr| "#{attr}:#{opts[key]}" if opts[key] }
+    end
+  end
+
+  # Locks provides mkdir-based mutual exclusion with TTL metadata.
+  class Locks
+    def initialize(paths)
+      @paths = paths
+    end
+
+    def lock(name, ttl:, worker:)
+      acquire!(name, ttl: ttl, worker: worker)
+      puts "locked #{name} by #{worker} (ttl #{ttl}s)"
+    end
+
+    def unlock(name)
+      release(name)
+      puts "unlocked #{name}"
+    end
+
+    def with_lock(name, ttl:, command:, worker:)
+      acquire!(name, ttl: ttl, worker: worker)
+      run_locked(name, command)
+    end
+
+    # Short critical section (e.g. claiming a task). Retries briefly instead of
+    # failing when two workers contend.
+    def with_mutex(name, worker:, &block)
+      acquire_with_retry(name, worker)
+      locked(name, &block)
+    end
+
+    # The lock is released only after it was taken.
+    def locked(name)
+      yield
+    ensure
+      release(name)
+    end
+
+    def acquire!(name, ttl:, worker:)
+      reclaim_if_stale(name)
+      Dir.mkdir(@paths.lock_dir(name))
+      write_meta(name, ttl, worker)
+    rescue Errno::EEXIST
+      raise Error, "lock #{name} busy"
+    end
+
+    def release(name)
+      FileUtils.rm_rf(@paths.lock_dir(name))
+    end
+
+    private
+
+    def acquire_with_retry(name, worker, attempts: 20)
+      attempts.times { return true if try_acquire(name, worker) }
+      raise Error, "could not lock #{name}"
+    end
+
+    def try_acquire(name, worker)
+      acquire!(name, ttl: 30, worker: worker) || true
+    rescue Error
+      sleep 0.05
+      false
+    end
+
+    def run_locked(name, command)
+      system(*command)
+    ensure
+      release(name)
+    end
+
+    def reclaim_if_stale(name)
+      return unless Dir.exist?(@paths.lock_dir(name))
+      raise Error, "locked by #{holder(name)} (coord unlock #{name})" unless stale?(name)
+
+      evict(name)
+    end
+
+    # Rename is atomic: of several processes that see the same stale lock, one
+    # renames it away. The others get ENOENT and never delete a fresh lock.
+    # Metadata lives inside the lock dir, so it moves with the rename.
+    def evict(name)
+      tomb = "#{@paths.lock_dir(name)}.stale-#{Process.pid}-#{Time.now.to_f}"
+      File.rename(@paths.lock_dir(name), tomb)
+      FileUtils.rm_rf(tomb)
+    rescue Errno::ENOENT
+      nil
+    end
+
+    # A lock whose metadata is missing is either a crashed writer or a
+    # concurrent writer between mkdir and write_meta. Treat it as stale only
+    # after a short grace period, so a racing acquire cannot delete a lock
+    # that was just created.
+    GRACE_PERIOD = 5
+
+    def stale?(name)
+      meta = read_meta(name)
+      return meta["ts"].to_i + meta["ttl"].to_i <= Time.now.to_i unless meta.empty?
+
+      lock_age(name) > GRACE_PERIOD
+    end
+
+    def lock_age(name)
+      Time.now - File.mtime(@paths.lock_dir(name))
+    rescue Errno::ENOENT
+      Float::INFINITY
+    end
+
+    def holder(name)
+      read_meta(name)["worker"] || "unknown"
+    end
+
+    def read_meta(name)
+      JSON.parse(File.read(@paths.lock_meta(name)))
+    rescue Errno::ENOENT, JSON::ParserError
+      {}
+    end
+
+    def write_meta(name, ttl, worker)
+      File.write(@paths.lock_meta(name), JSON.generate(worker: worker, ts: Time.now.to_i, ttl: ttl))
+    end
+  end
+
+  # Messages writes inbox files and archives them when read.
+  class Messages
+    def initialize(paths, default_from)
+      @paths = paths
+      @from = default_from
+    end
+
+    # A message for one worker goes to the inbox of its role. The header
+    # names the worker, so the reader knows who the message is for.
+    # An FYI message (fyi: true) waits in the inbox and wakes no one. The
+    # next run of the role reads it together with the next waking message.
+    def send_message(to, from, text, worker: nil, fyi: false)
+      path = new_message_path(to, fyi)
+      File.write(path, body(to, from, text, worker))
+      puts "msg -> #{path}"
+      path
+    end
+
+    def inbox(role, peek: false, all: false)
+      files = files(role, all: all)
+      return puts("no messages for #{role}") if files.empty?
+
+      files.each { |file| read_message(file, peek) }
+    end
+
+    # Paths of the agent's message files, oldest first. Shared with the
+    # `--wait` poller so "is there mail yet" tests exactly what `inbox` reads.
+    def files(role, all: false)
+      fold_worker_inboxes(role)
+      dir = @paths.inbox_dir(role)
+      Dir.glob(File.join(dir, all ? "**" : "", "*.md")).sort
+    end
+
+    # The unread messages that justify a model call: every message except FYI.
+    def wake_files(role) = files(role).reject { |file| Messages.fyi?(file) }
+
+    # NOTE: assets/dispatcher and board-watch.rb read the same name mark.
+    def self.fyi?(path) = File.basename(path).include?(".fyi.")
+
+    # Broadcast sends one message to each role in ROLES. Returns the list of
+    # [role, path] pairs so the caller can fire hooks for each.
+    def broadcast(from, text, roles)
+      results = roles.map { |role| [role, send_message(role, from, text)] }
+      puts "broadcast -> #{roles.size} role#{"s" if roles.size != 1}"
+      results
+    end
+
+    private
+
+    def new_message_path(to, fyi)
+      dir = @paths.inbox_dir(to)
+      FileUtils.mkdir_p(dir)
+      File.join(dir, "#{stamp}-#{Process.pid}#{".fyi" if fyi}.md")
+    end
+
+    def body(to, from, text, worker)
+      worker_line = worker ? "# for: #{worker}\n" : ""
+      "# to: #{to}\n#{worker_line}# from: #{from}\n# at: #{Time.now.utc.iso8601}\n\n#{text}\n"
+    end
+
+    # Older versions wrote a message for a worker to inbox/<worker>/. No
+    # session reads that folder. Move its unread messages to the role inbox.
+    def fold_worker_inboxes(role)
+      @paths.worker_inbox_dirs(role).each do |dir|
+        Dir.glob(File.join(dir, "*.md")).each { |file| move_to_role(file, role) }
+      end
+    end
+
+    def move_to_role(file, role)
+      FileUtils.mkdir_p(@paths.inbox_dir(role))
+      FileUtils.mv(file, File.join(@paths.inbox_dir(role), File.basename(file)))
+    end
+
+    def stamp
+      Time.now.utc.strftime("%Y%m%dT%H%M%SZ")
+    end
+
+    def read_message(file, peek)
+      puts "== #{file} =="
+      puts File.read(file)
+      puts
+      archive(file) unless peek || file.include?("/read/")
+    end
+
+    def archive(file)
+      dir = File.join(File.dirname(file), "read")
+      FileUtils.mkdir_p(dir)
+      FileUtils.mv(file, File.join(dir, File.basename(file)))
+    end
+  end
+
+  # Hooks runs a per-role shell script when a message is delivered. The hook
+  # is a plain user-authored script at .maf/coordination/message-hooks/<role>.sh — coord
+  # does not know or care what harness the agent runs in. It starts a fresh
+  # one-shot, sends a notification, or does nothing at all. The hook receives
+  # COORD_ROLE, COORD_FROM, and COORD_MSG_FILE in its environment, and the
+  # message file path as $1. If the hook is absent, coord is silent — it just
+  # writes the inbox file, and the agent picks it up on its next `coord inbox`.
+  #
+  # The hook runs detached in its own process group, so a slow hook (one that
+  # starts a whole agent run) never blocks the sender. Its stdout and stderr
+  # go to .maf/coordination/message-hooks/<role>.log.
+  class Hooks
+    def initialize(paths)
+      @paths = paths
+    end
+
+    def run(role, from:, message_path:)
+      hook = @paths.hook_path(role)
+      return false unless File.executable?(hook)
+
+      Process.detach(spawn_hook(hook, role, from, message_path))
+      true
+    end
+
+    private
+
+    def spawn_hook(hook, role, from, message_path)
+      env = { "COORD_ROLE" => role.to_s, "COORD_FROM" => from.to_s, "COORD_MSG_FILE" => message_path }
+      log = @paths.hook_log(role)
+      Process.spawn(env, hook, message_path, out: [log, "a"], err: [:child, :out], pgroup: true)
+    end
+  end
+
+  # Presence records which workers run now, in .maf/coordination/presence/<worker>.json.
+  # `maf start` exports COORD_SESSION_PID (the harness pid, kept across exec),
+  # so every coord call from that session can record it. The dispatcher writes
+  # its own file (mode "dispatch"); a dispatched run (COORD_DISPATCHED) writes
+  # none. A worker is live while its pid runs. A session in a container shows
+  # as gone, because the host cannot see its pid.
+  class Presence
+    def initialize(paths)
+      @paths = paths
+    end
+
+    def touch(role, worker, env)
+      pid = env["COORD_SESSION_PID"].to_i
+      return unless pid.positive? && recordable?(role, worker, env)
+
+      write(worker, "role" => role, "worker" => worker, "mode" => "session", "pid" => pid,
+                     "started" => Maf::Shared::Processes.started_at(pid))
+    end
+
+    def live?(role) = entries.any? { |entry| entry["role"] == role && self.class.live_entry?(entry) }
+
+    def report
+      return puts("no presence records") if entries.empty?
+
+      entries.each { |entry| puts line(entry) }
+    end
+
+    LEGACY_LIVE_WINDOW = 3600
+
+    def self.live_entry?(entry)
+      return false unless Maf::Shared::Processes.alive?(entry["pid"])
+
+      recorded = entry["started"].to_s
+      recorded.empty? ? legacy_live?(entry) : recorded == Maf::Shared::Processes.started_at(entry["pid"])
+    end
+
+    def self.legacy_live?(entry)
+      Time.now - Time.parse(entry["seen_at"].to_s) < LEGACY_LIVE_WINDOW
+    rescue ArgumentError
+      false
+    end
+
+    private
+
+    def recordable?(role, worker, env)
+      !env["COORD_DISPATCHED"] && ([role, worker] & ["unknown", ""]).empty? && Dir.exist?(@paths.coord_dir)
+    end
+
+    def write(worker, data)
+      FileUtils.mkdir_p(@paths.presence_dir)
+      path = File.join(@paths.presence_dir, "#{worker}.json")
+      File.write(path, JSON.generate(data.merge("seen_at" => Time.now.utc.iso8601)))
+    end
+
+    def entries = Dir.glob(File.join(@paths.presence_dir, "*.json")).sort.filter_map { |path| read(path) }
+
+    def read(path)
+      JSON.parse(File.read(path))
+    rescue JSON::ParserError, Errno::ENOENT
+      nil
+    end
+
+    def line(entry)
+      state = self.class.live_entry?(entry) ? "live" : "gone"
+      fields = entry.values_at("worker", "role", "mode") + [state, "pid=#{entry["pid"]}", "seen=#{entry["seen_at"]}"]
+      fields.join("\t")
+    end
+  end
+
+  # EventLog is a shared, append-only log in .maf/coordination/events.log. Every
+  # claim, completion, unclaim, message, and broadcast appends one line so any
+  # agent can see the history of coordination without reading individual inbox
+  # files. The log is not the source of truth (Taskwarrior is); it is a
+  # convenience projection for "what happened while I was working."
+  class EventLog
+    DETAIL_LIMIT = 80
+
+    def initialize(paths)
+      @paths = paths
+    end
+
+    def append(action, worker, detail)
+      FileUtils.mkdir_p(@paths.coord_dir)
+      line = [Time.now.utc.iso8601, action, worker, clean(detail)].join("\t")
+      File.open(@paths.log_path, "a") { |file| file.puts(line) }
+    end
+
+    def read(lines = nil)
+      path = @paths.log_path
+      return puts("no events yet") unless File.exist?(path)
+
+      all = File.readlines(path)
+      recent = lines ? all.last(lines) : all
+      recent.each { |line| print line }
+    end
+
+    private
+
+    # Tabs separate fields and newlines separate events, so neither may
+    # appear inside a field.
+    def clean(detail)
+      detail.to_s.gsub(/\s+/, " ").strip.slice(0, DETAIL_LIMIT)
+    end
+  end
+
+  # Roster lists every role coord knows about: roles that own a pending task,
+  # plus roles declared in the project's .maf/config.json (written by
+  # maf add). The manifest sits next to .maf/coordination/, so a worktree
+  # that points COORD_DIR at the main checkout still finds it.
+  class Roster
+    def initialize(paths, tasks)
+      @paths = paths
+      @tasks = tasks
+    end
+
+    def roles
+      (task_roles + manifest_roles).uniq.sort
+    end
+
+    private
+
+    def task_roles
+      @tasks.pending.map { |task| task["role"] }.compact - [Goals::ROLE]
+    end
+
+    def manifest_roles = Manifest.new(@paths.manifest_path).agents.map { |entry| entry["role"] }.compact
+  end
+
+  # Manifest reads .maf/config.json, which `maf add` writes. A project
+  # without maf has no manifest; every reader then gets empty defaults.
+  class Manifest
+    def initialize(path)
+      @data = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+    rescue JSON::ParserError
+      @data = {}
+    end
+
+    def agents = @data.fetch("agents", [])
+    def base_branch = @data["base_branch"]
+    def verify = @data["verify"].to_s
+    def copy_to_worktree = Array(@data["copy_to_worktree"]).map(&:to_s)
+    def github = @data.fetch("github", {})
+    def reap_minutes = Integer(@data.dig("team", "reap_minutes").to_s, exception: false) || Reaper::DEFAULT_MINUTES
+    def harnesses = agents.map { |entry| entry["harness"] }.compact.uniq
+
+    def harnesses_for(role) = agents.select { |entry| entry["role"] == role }.map { |entry| entry["harness"] }
+  end
+
+  # Audiences names the role groups that `coord broadcast --to` accepts.
+  # Leads plan and talk to the user. Workers do the tasks. A notice about
+  # ports or test databases is for workers only.
+  module Audiences
+    PICK = {
+      "workers" => ->(role) { !LEADS.include?(role) },
+      "leads" => ->(role) { LEADS.include?(role) },
+      "all" => ->(_role) { true }
+    }.freeze
+
+    def self.pick(name)
+      PICK.fetch(name) { raise Error, "unknown audience '#{name}' (use #{PICK.keys.join(", ")})" }
+    end
+  end
+
+  # TokenTotals reads the token usage that the dispatcher adds up per worker
+  # in .maf/coordination/usage/<worker>.json. A broken file is skipped.
+  class TokenTotals
+    def initialize(paths)
+      @paths = paths
+    end
+
+    def lines = Dir.glob(File.join(@paths.usage_dir, "*.json")).sort.filter_map { |path| line(path) }
+
+    private
+
+    def line(path)
+      data = JSON.parse(File.read(path))
+      "tokens #{File.basename(path, ".json")}: input=#{data["input_tokens"].to_i} " \
+        "cached=#{data["cached_input_tokens"].to_i} output=#{data["output_tokens"].to_i} runs=#{data["runs"].to_i}"
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+# GraphAge asks `vault age --json` for the graph age: the commits since the
+# graph build. Without the vault script or on a failure it gives no line.
+class GraphAge
+  def initialize(paths)
+    @paths = paths
+  end
+
+  def line
+    output = IO.popen([RbConfig.ruby, @paths.vault_path, "age", "--json"], chdir: root, err: File::NULL, &:read)
+    data = JSON.parse(output)
+    data["commits"] ? "graph age: #{data["commits"]} commits (#{data["state"]})" : "graph age: #{data["state"]}"
+  rescue SystemCallError, JSON::ParserError
+    nil
+  end
+
+  private
+
+  def root = File.dirname(File.dirname(File.expand_path(@paths.coord_dir)))
+end
+
+# WorkMemory keeps what the team learned after a task closes. `graphify
+# save-result` writes one note to graphify-out/memory/. The note cites the graph
+# nodes of the files that the task branch changed. `graphify reflect` then
+# rebuilds graphify-out/reflections/LESSONS.md from all notes, and the
+# dispatcher puts its dead ends and corrections into each task prompt.
+# Without a graph, it saves nothing.
+class WorkMemory
+  BRANCH = "maf/memory"
+  ANSWER_LIMIT = 2000
+  NODE_LIMIT = 20
+
+  def self.notes(task)
+    texts = (task["annotations"] || []).map { |note| note["description"].to_s }
+    texts.reject { |text| text.start_with?("LANDED:") }.join("\n")
+  end
+
+  def initialize(root)
+    @root = root
+  end
+
+  # Returns false when there is no graph or graphify fails.
+  def save(task, outcome, answer, correction = nil)
+    return false unless File.exist?(graph)
+    return false unless write_note(task, outcome, answer.to_s[0, ANSWER_LIMIT], correction)
+
+    commit("memory: #{outcome}: #{task["description"]}")
+    reflect
+  end
+
+  private
+
+  def write_note(task, outcome, answer, correction)
+    graphify("save-result", "--question", question(task, outcome, answer), "--outcome", outcome, "--answer", answer,
+             "--memory-dir", folder("memory"), *correction_args(correction), *nodes_args(task))
+  end
+
+  # graphify-out/memory/ can be a worktree of the branch maf/memory (ADR 0006).
+  # Each note is one commit there. A commit fails while another one runs. The
+  # note then stays, and the next commit takes it.
+  def commit(message)
+    dir = folder("memory")
+    Git.run(dir, "add", "-A") && Git.run(dir, "commit", "-q", "-m", message) if File.exist?(File.join(dir, ".git"))
+  end
+
+  def reflect
+    graphify("reflect", "--graph", graph, "--memory-dir", folder("memory"), "--out", folder("reflections/LESSONS.md"))
+  end
+
+  # LESSONS.md lists a dead end by its question only. The question keeps the
+  # reason, so the reason reaches the prompts.
+  def question(task, outcome, answer)
+    outcome == "dead_end" ? "#{task["description"]}: #{answer}" : task["description"].to_s
+  end
+
+  def correction_args(text) = text ? ["--correction", text] : []
+  def graph = folder("graph.json")
+  def folder(name) = File.join(@root, "graphify-out", name)
+
+  # graphify takes paths from the arguments, never from GRAPHIFY_OUT.
+  def graphify(*args)
+    system({ "GRAPHIFY_OUT" => nil }, "graphify", *args, chdir: @root, out: File::NULL, err: File::NULL)
+  end
+
+  # --nodes takes the rest of the arguments, so it comes last.
+  def nodes_args(task)
+    ids = node_ids(changed_files(task)).first(NODE_LIMIT)
+    ids.empty? ? [] : ["--nodes", *ids]
+  end
+
+  def changed_files(task)
+    return [] if task["goalid"].to_s.empty?
+
+    range = "#{Goals.branch(task["goalid"])}...task/#{Goals.short(task["uuid"])}"
+    Git.out(@root, "diff", "--name-only", range).lines(chomp: true)
+  end
+
+  def node_ids(files)
+    nodes = files.empty? ? [] : JSON.parse(File.read(graph))["nodes"] || []
+    files.filter_map { |file| nodes.find { |node| file_node?(node, file) }&.fetch("id", nil) }
+  rescue JSON::ParserError
+    []
+  end
+
+  # A file node has the file name as label. graphify may store the source path
+  # relative to the project or absolute.
+  def file_node?(node, file)
+    node["label"] == File.basename(file) && [file, File.join(@root, file)].include?(node["source_file"])
+  end
+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) }
+    }.freeze
+
+    def initialize(tasks, paths)
+      @tasks = tasks
+      @paths = paths
+    end
+
+    def status
+      rows = grouped
+      rows.empty? ? puts("no tasks") : rows.each { |role, list| puts summary_line(role, list) }
+      TokenTotals.new(@paths).lines.each { |line| puts line }
+      GraphAge.new(@paths).line&.then { |line| puts line }
+    end
+
+    def next_tasks(role, worker = nil)
+      list = @tasks.next_for(role, worker)
+      return puts("no unclaimed tasks for #{role}") if list.empty?
+
+      list.each { |task| puts task_line(task) }
+    end
+
+    def mine_tasks(role, worker)
+      list = @tasks.mine(role, worker)
+      return puts("no in-progress tasks for #{worker}") if list.empty?
+
+      list.each { |task| puts task_line(task) }
+    end
+
+    def board
+      File.write(@paths.board_path, board_body)
+      puts "board -> #{@paths.board_path}"
+    end
+
+    private
+
+    def summary_line(role, list)
+      counts = list.group_by { |task| bucket(task) }.transform_values(&:size)
+      "#{role}: #{counts.map { |key, value| "#{key}=#{value}" }.join(" ")}"
+    end
+
+    def task_line(task)
+      [task["uuid"], task["description"], task["scope"], task["worker"]].compact.join("\t")
+    end
+
+    def grouped
+      @tasks.pending.group_by { |task| task["role"] || "unassigned" }.sort.to_h
+    end
+
+    def bucket(task)
+      return "waiting" if Schedule.waiting?(task)
+
+      task["start"] ? "in-progress" : "backlog"
+    end
+
+    # The `kanban-plugin: basic` frontmatter is what the Obsidian Kanban
+    # community plugin (mgmeyers/obsidian-kanban) checks for to render this
+    # file as a board instead of a plain markdown note. Without it, `##`
+    # headings and `- [ ]` items still read fine as an outline, but Obsidian
+    # never offers the drag-and-drop board view for the file.
+    def board_body
+      frontmatter = "---\nkanban-plugin: basic\n---\n\n"
+      frontmatter + SECTIONS.map { |title, pick| section(title, @tasks.pending.select(&pick)) }.join
+    end
+
+    def section(title, list)
+      "## #{title}\n\n#{list.map { |task| card(task) }.join("\n")}\n\n"
+    end
+
+    def card(task)
+      scope = task["scope"].to_s
+      scope_part = scope.empty? ? "" : " `#{scope}`"
+      "- [ ] #{owner_label(task)} \u2014 #{task["description"]}#{scope_part}"
+    end
+
+    def owner_label(task)
+      worker = task["worker"].to_s
+      worker.empty? ? (task["role"] || "unassigned") : "#{task["role"]}/#{worker}"
+    end
+  end
+
+  # Git wraps the few git calls that goals and task branches need.
+  module Git
+    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.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?
+    def self.branches(dir, pattern)
+      out(dir, "branch", "--list", pattern, "--format=%(refname:short)").lines(chomp: true)
+    end
+
+    # With an origin, the remote base branch is the truth: a merged pull
+    # request lands there first. Without an origin, the local branch counts.
+    def self.base_ref(dir, base) = run(dir, "fetch", "-q", "origin", base) ? "origin/#{base}" : base
+
+    # Maps each checked-out branch to the worktree that holds it.
+    def self.checked_out(dir)
+      blocks = out(dir, "worktree", "list", "--porcelain").split("\n\n")
+      blocks.filter_map do |block|
+        branch = block[%r{^branch refs/heads/(.+)$}, 1]
+        [branch, block[/^worktree (.+)$/, 1]] if branch
+      end.to_h
+    end
+
+    # The base branch is where each goal starts: the manifest's base_branch,
+    # else the branch that origin/HEAD names, else main.
+    def self.base_branch(dir, manifest)
+      configured = manifest.base_branch
+      return configured unless configured.to_s.empty?
+
+      remote = `git -C #{Shellwords.escape(dir)} symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null`.strip
+      remote.delete_prefix("origin/").then { |name| name.empty? ? "main" : name }
+    end
+  end
+
+  # Goals tracks user-visible outcomes above tasks. A goal is a task with
+  # role "goal". Its tasks store the goal's uuid in the `goal` attribute.
+  # Each goal has its own branch goal/<short id> from the base branch, so
+  # one goal never builds on top of another goal.
+  class Goals
+    ROLE = "goal"
+
+    def self.short(uuid) = uuid.to_s[0, 8]
+    def self.branch(uuid) = "goal/#{short(uuid)}"
+    def self.slug(uuid) = "goal-#{short(uuid)}"
+
+    def initialize(tasks)
+      @tasks = tasks
+    end
+
+    def find!(id)
+      goal = @tasks.find(id)
+      raise Error, "no goal #{id}" unless goal["role"] == ROLE
+
+      goal
+    end
+
+    def list
+      goals = @tasks.pending.select { |task| task["role"] == ROLE }
+      return puts("no open goals") if goals.empty?
+
+      goals.each { |goal| puts goal_line(goal) }
+    end
+
+    def show(id)
+      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) }
+    end
+
+    def done(id)
+      goal = find!(id)
+      refuse_open!(goal)
+      @tasks.done(goal["uuid"])
+      goal
+    end
+
+    def refuse_open!(goal)
+      open = @tasks.for_goal(goal["uuid"]).size
+      raise Error, "goal #{goal["uuid"]} has #{open} open task#{"s" if open != 1}" if open.positive?
+    end
+
+    private
+
+    def goal_line(goal)
+      open = @tasks.for_goal(goal["uuid"]).size
+      [goal["uuid"], goal["description"], self.class.branch(goal["uuid"]), "open=#{open}"].join("\t")
+    end
+
+    def task_line(task)
+      state = task["start"] ? "in-progress" : "backlog"
+      "  " + [task["uuid"], task["role"], state, task["worker"], task["description"]].compact.join("\t")
+    end
+  end
+
+  # TaskBranch checks out one branch per task in the worker's worktree. The
+  # branch starts from the task's goal branch, so each task builds on its own
+  # goal only. A task without a goal starts from the base branch.
+  class TaskBranch
+    def initialize(dir)
+      @dir = dir
+    end
+
+    def start(uuid, base)
+      raise Error, "uncommitted changes in #{@dir}. Commit or stash them first." unless Git.clean?(@dir)
+
+      branch = "task/#{Goals.short(uuid)}"
+      raise Error, "git checkout #{branch} failed" unless checkout(branch, base)
+
+      puts "on branch #{branch} (from #{base})"
+    end
+
+    private
+
+    def checkout(branch, base)
+      return Git.run(@dir, "checkout", "-q", branch) if Git.branch?(@dir, branch)
+
+      Git.run(@dir, "checkout", "-q", "-b", branch, base)
+    end
+  end
+
+  # TaskSync checks that a task branch contains the head of its goal branch.
+  # Task tests on a branch without the merged sibling tasks miss semantic
+  # conflicts, so `coord done` refuses a stale branch. A task branch without
+  # own commits (a review task) has nothing to integrate and passes.
+  class TaskSync
+    def initialize(dir)
+      @dir = dir
+    end
+
+    def stale(task)
+      goal = task["goalid"]
+      return nil if goal.to_s.empty?
+
+      pair = [Goals.branch(goal), "task/#{Goals.short(task["uuid"])}"]
+      pair if pair.all? { |name| Git.branch?(@dir, name) } && behind?(*pair)
+    end
+
+    private
+
+    def behind?(goal, branch)
+      own = `git -C #{Shellwords.escape(@dir)} rev-list --count #{goal}..#{branch} 2>/dev/null`.to_i
+      own.positive? && !Git.run(@dir, "merge-base", "--is-ancestor", goal, branch)
+    end
+  end
+
+  # SquashMessage builds the commit message of one landed task. The trailers
+  # keep the trace to the task after the squash.
+  module SquashMessage
+    SUBJECT_LIMIT = 72
+
+    def self.for(task, subject)
+      head = (subject || task["description"]).to_s.strip.slice(0, SUBJECT_LIMIT)
+      trailers = { "Task" => task["uuid"], "Goal" => task["goalid"], "Worker" => task["worker"],
+                   "Tests" => tests(task) }
+      "#{head}\n\n#{trailers.filter_map { |key, value| "#{key}: #{value}" unless value.to_s.empty? }.join("\n")}\n"
+    end
+
+    # The worker report holds "TESTS: <result>. NOTES: ...". The last report counts.
+    def self.tests(task)
+      notes = (task["annotations"] || []).map { |note| note["description"].to_s }
+      notes.reverse.find { |text| text.include?("TESTS:") }.to_s[/TESTS:\s*(.+?)(?:\s+NOTES:|\z)/m, 1]
+    end
+  end
+
+  # Land squashes the branch of one done task into its goal branch as one
+  # 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
+    end
+
+    def run(subject)
+      check!
+      commit = squash(subject)
+      release_branch
+      commit
+    end
+
+    def goal_branch = Goals.branch(@task["goalid"])
+    def branch = "task/#{Goals.short(@task["uuid"])}"
+
+    private
+
+    def goal_dir = Worktree.dir_for(@root, Goals.slug(@task["goalid"]))
+
+    def check!
+      raise Error, "task #{@task["uuid"]} has no goal. coord land needs a goal branch." if @task["goalid"].to_s.empty?
+      raise Error, "task #{@task["uuid"]} is not done. Run coord done first." unless @task["status"] == "completed"
+      raise Error, "branch #{branch} does not exist" unless Git.branch?(@root, branch)
+      raise Error, "uncommitted changes in #{goal_dir}. Commit or stash them first." unless Git.clean?(goal_dir)
+    end
+
+    # A branch without own commits (a review task) lands nothing.
+    def squash(subject)
+      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)
+
+      merge_squash
+      commit(SquashMessage.for(@task, subject))
+    end
+
+    STALE = "branch %<branch>s lacks the head of %<goal>s. Open a fix task: merge %<goal>s into %<branch>s."
+
+    def merge_squash
+      return if Git.run(goal_dir, "merge", "--squash", "-q", branch)
+
+      Git.run(goal_dir, "reset", "-q", "--merge")
+      raise Error, "the squash of #{branch} into #{goal_branch} conflicts. Open a fix task."
+    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")
+
+      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?
+
+      Git.out(goal_dir, "rev-parse", "--short", "HEAD")
+    end
+
+    def release_branch
+      holder = Git.checked_out(@root)[branch]
+      return warn("coord: kept #{branch}. #{holder} has uncommitted changes.") if holder && !leave(holder)
+
+      Git.run(@root, "branch", "-D", branch)
+    end
+
+    # A worker worktree goes back to worker/<slug>. Without that branch, it detaches at the goal head.
+    def leave(dir)
+      return false unless Git.clean?(dir)
+
+      worker = "worker/#{File.basename(dir)}"
+      target = Git.branch?(@root, worker) ? [worker] : ["--detach", goal_branch]
+      Git.run(dir, "switch", "-q", *target)
+    end
+  end
+
+  # GoalSync merges the base branch into a goal branch, so the pull request
+  # of the goal has no conflict and the merge suite tests the merged result.
+  class GoalSync
+    def initialize(root, goal_uuid, base)
+      @root, @base = root, base
+      @branch = Goals.branch(goal_uuid)
+      @dir = Worktree.dir_for(root, Goals.slug(goal_uuid))
+    end
+
+    # A missing base ref has no head to lack.
+    def behind? = Git.run(@root, "rev-parse", "-q", "--verify", ref) && !Git.ancestor?(@root, ref, @branch)
+    def ref = @ref ||= Git.base_ref(@root, @base)
+
+    def run
+      return puts("#{@branch} already contains #{ref}") unless behind?
+      raise Error, "uncommitted changes in #{@dir}. Commit or stash them first." unless Git.clean?(@dir)
+
+      merge
+      puts "merged #{ref} into #{@branch}"
+    end
+
+    private
+
+    def merge
+      return if Git.run(@dir, "merge", "-q", "--no-edit", ref)
+
+      Git.run(@dir, "merge", "--abort")
+      raise Error, "the merge of #{ref} into #{@branch} conflicts. Open a fix task to merge #{ref} into #{@branch}."
+    end
+  end
+
+  # Sweep finds flow branches and worktrees that finished their work. It
+  # deletes only what git or the task board proves is merged or landed.
+  # Everything else stays and gets a reason.
+  class Sweep
+    Item = Struct.new(:label, :action, :reason)
+
+    def initialize(root, tasks, base)
+      @root, @tasks, @base = root, tasks, base
+    end
+
+    def items = task_items + goal_items + worker_items
+
+    private
+
+    def ref = @ref ||= Git.base_ref(@root, @base)
+    def held = @held ||= Git.checked_out(@root)
+
+    def task_items
+      Git.branches(@root, "task/*").map { |name| item("branch #{name}", task_reason(name)) { delete(name) } }
+    end
+
+    def goal_items
+      Git.branches(@root, "goal/*").map do |name|
+        item("goal #{name} and its worktree", goal_reason(name)) { drop_goal(name) }
+      end
+    end
+
+    def worker_items
+      Git.branches(@root, "worker/*").map { |name| item("branch #{name}", worker_reason(name)) { delete(name) } }
+    end
+
+    # A nil reason means: safe to delete.
+    def item(label, reason, &action) = Item.new(label, reason ? nil : action, reason)
+
+    def task_reason(name)
+      return "checked out in #{held[name]}" if held[name]
+      return nil if Git.ancestor?(@root, name, ref)
+
+      task = @tasks.find_short(name.delete_prefix("task/"))
+      return "task is not done" unless task["status"] == "completed"
+
+      landed?(task) ? nil : "task is done but not landed (coord land)"
+    end
+
+    def landed?(task) = (task["annotations"] || []).any? { |note| note["description"].to_s.start_with?("LANDED:") }
+
+    def goal_reason(name)
+      goal = @tasks.find_short(name.delete_prefix("goal/"))
+      return "goal is not done" unless goal["status"] == "completed"
+
+      Git.ancestor?(@root, name, ref) ? nil : "not merged into #{ref}"
+    end
+
+    def worker_reason(name)
+      return "checked out in #{held[name]}" if held[name]
+
+      Git.ancestor?(@root, name, ref) ? nil : "has commits that #{ref} lacks"
+    end
+
+    def delete(name) = Git.run(@root, "branch", "-D", name)
+
+    # Untracked runtime copies would block `worktree remove`. Git.clean? has
+    # already checked the tracked files, so --force removes only those copies.
+    def drop_goal(name)
+      dir = held[name]
+      return false if dir && !(Git.clean?(dir) && Git.run(@root, "worktree", "remove", "--force", dir))
+
+      delete(name)
+    end
+  end
+
+  # Await arms the stop hook of an interactive session. The agent ends its
+  # turn, and the hook (harness-hooks/next-task.rb) waits for work outside the
+  # model. A wait in a tool call costs one model call per return; this wait
+  # costs none. NOTE: next-task.rb reads the same file.
+  class Await
+    DEFAULT_SECONDS = 3000
+
+    def initialize(paths, worker)
+      @path = File.join(paths.locks_dir, "await-#{worker}.json")
+    end
+
+    def arm(role, seconds)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, JSON.generate("role" => role, "until" => Time.now.to_i + seconds))
+    end
+  end
+
+  # InboxWaiter allows one `coord inbox --wait` for each role. Two waiters on
+  # one inbox split the messages between two agents. The pid file of a waiter
+  # that exited without cleanup counts as free.
+  class InboxWaiter
+    def initialize(paths, role)
+      @role = role
+      @path = File.join(paths.locks_dir, "inbox-wait-#{role}.pid")
+    end
+
+    def hold
+      refuse_other!
+      write_pid
+      yield
+    ensure
+      File.delete(@path) if own?
+    end
+
+    def write_pid
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, Process.pid.to_s)
+    end
+
+    def own? = File.exist?(@path) && File.read(@path).to_i == Process.pid
+
+    private
+
+    def refuse_other!
+      pid = File.exist?(@path) ? File.read(@path).to_i : 0
+      return unless pid.positive? && pid != Process.pid && Maf::Shared::Processes.alive?(pid)
+
+      raise Error, "another coord inbox --wait for #{@role} runs (pid #{pid}). Read the messages in that session."
+    end
+  end
+
+  # Reaper finds claims of workers that were not seen for a while. A worker
+  # counts as seen at its claim, at each change of the task, at each event
+  # it logs, and at each coord call of its session (presence).
+  # A live dispatcher is never stale: a run can take hours on a local model,
+  # and the dispatcher resumes the claims of its worker by itself.
+  class Reaper
+    DEFAULT_MINUTES = 90
+
+    def initialize(tasks, paths, minutes)
+      @tasks, @paths, @limit = tasks, paths, minutes * 60
+    end
+
+    def stale = @tasks.pending.select { |task| claimed?(task) && !dispatched?(task) && quiet?(task) }
+    def quiet?(task) = Time.now - last_seen(task) >= @limit
+
+    def last_seen(task)
+      times = [task["start"], task["modified"], presence(task["worker"]), last_event(task["worker"])]
+      times.filter_map { |value| parse(value) }.max || Time.now
+    end
+
+    private
+
+    def claimed?(task) = task["start"] && !task["worker"].to_s.empty?
+
+    def parse(value)
+      value && Time.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+
+    def dispatched?(task)
+      entry = entry(task["worker"])
+      entry["mode"] == "dispatch" && Presence.live_entry?(entry)
+    end
+
+    def presence(worker) = entry(worker)["seen_at"]
+
+    def entry(worker)
+      JSON.parse(File.read(File.join(@paths.presence_dir, "#{worker}.json")))
+    rescue Errno::ENOENT, JSON::ParserError
+      {}
+    end
+
+    def last_event(worker) = events.reverse.find { |line| line.split("\t")[2] == worker }&.split("\t")&.first
+    def events = @events ||= File.exist?(@paths.log_path) ? File.readlines(@paths.log_path).last(2000) : []
+  end
+
+  # GitHub runs `gh` as the bot account of the github section in
+  # .maf/config.json. The bot opens the pull request, so the reviewer can
+  # approve it or request changes. Your own `gh` login stays active.
+  class GitHub
+    def initialize(root, settings)
+      @root, @settings = root, settings
+    end
+
+    def bot = @settings["bot_user"].to_s
+    def reviewer = @settings["reviewer"].to_s
+    def configured? = !bot.empty? && !reviewer.empty?
+
+    def repo
+      @repo ||= @settings["repo"] || origin_repo ||
+                raise(Error, "no GitHub repository. Set github.repo in .maf/config.json.")
+    end
+
+    # ssh_host is a Host alias of ~/.ssh/config with the key of the bot.
+    def remote = @settings["ssh_host"] ? "git@#{@settings["ssh_host"]}:#{repo}.git" : "origin"
+
+    def push(branch)
+      return if Git.run(@root, "push", "-q", remote, "#{branch}:#{branch}")
+
+      raise Error, "git push of #{branch} to #{remote} failed"
+    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
+    end
+
+    def request_review(url) = gh("pr", "edit", url, "--add-reviewer", reviewer)
+    def comment(url, text) = gh("pr", "comment", url, "--body-file", "-", input: text)
+    def view(url) = JSON.parse(gh("pr", "view", url, "--json", "state,reviews,comments"))
+    def inline_comments(url) = JSON.parse(gh("api", "repos/#{repo}/pulls/#{url[%r{/pull/(\d+)}, 1]}/comments"))
+
+    private
+
+    # The origin URL can use an ssh Host alias such as github.com-maf-bot.
+    ORIGIN = %r{github\.com[^:/]*[:/]([^/]+/[^/]+?)(?:\.git)?\z}
+
+    def origin_repo = Git.out(@root, "remote", "get-url", "origin")[ORIGIN, 1]
+
+    def gh(*args, input: nil)
+      out, err, status = Open3.capture3(env, "gh", *args, stdin_data: input.to_s)
+      raise Error, "gh #{args.first(2).join(" ")} failed: #{err.strip}" unless status.success?
+
+      out
+    rescue Errno::ENOENT
+      raise Error, "gh is not installed. See https://cli.github.com"
+    end
+
+    def env = @env ||= { "GH_TOKEN" => token }
+
+    def token
+      out, _err, status = Open3.capture3("gh", "auth", "token", "--user", bot)
+      raise Error, "gh has no login for #{bot}. Run: gh auth login (as #{bot})" unless status.success?
+
+      out.strip
+    end
+  end
+
+  # ReviewState keeps the pull request of each goal and the review items that
+  # coord already forwarded, in .maf/coordination/reviews.json.
+  class ReviewState
+    def initialize(paths)
+      @path = File.join(paths.coord_dir, "reviews.json")
+      @locks = Locks.new(paths)
+    end
+
+    def all = File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+    def get(uuid) = all[uuid]
+    def put(uuid, entry) = change { |data| data.merge(uuid => entry) }
+    def drop(uuid) = change { |data| data.reject { |key, _| key == uuid } }
+
+    private
+
+    def change
+      @locks.with_mutex("reviews", worker: "coord") { File.write(@path, JSON.pretty_generate(yield(all))) }
+    end
+  end
+
+  # ReviewFeed reads one pull request and lists the review items that coord
+  # has not forwarded yet. It ignores every author except the reviewer.
+  class ReviewFeed
+    def initialize(github, entry)
+      @github, @entry = github, entry
+      @seen = entry.fetch("seen", [])
+    end
+
+    def state = view["state"]
+    def items = @items ||= (review_items + inline_items + comment_items).reject { |id, _| @seen.include?(id) }
+    def seen_after = @seen + items.map(&:first)
+    def changes_requested? = new_reviews.any? { |review| review["state"] == "CHANGES_REQUESTED" }
+
+    private
+
+    def view = @view ||= @github.view(@entry["url"])
+    def by_reviewer?(item, key = "author") = item.dig(key, "login") == @github.reviewer
+    def new_reviews = (view["reviews"] || []).select { |r| by_reviewer?(r) && !@seen.include?("review-#{r["id"]}") }
+    def review_items = new_reviews.map { |r| ["review-#{r["id"]}", "#{r["state"]}: #{r["body"]}".strip] }
+    def comment_items
+      (view["comments"] || []).select { |c| by_reviewer?(c) }.map { |c| ["comment-#{c["id"]}", c["body"]] }
+    end
+
+    # Inline comments come with a review, so only a new review needs the extra call.
+    def inline_items
+      return [] if new_reviews.empty?
+
+      list = @github.inline_comments(@entry["url"]).select { |c| by_reviewer?(c, "user") }
+      list.map { |c| ["inline-#{c["id"]}", "#{c["path"]}:#{c["line"] || c["original_line"]}: #{c["body"]}"] }
+    end
+  end
+
+  # PrBody describes a goal pull request: one line for each landed task.
+  module PrBody
+    def self.for(root, goal, base_ref)
+      range = "#{base_ref}..#{Goals.branch(goal["uuid"])}"
+      commits = Git.out(root, "log", "--first-parent", "--reverse", "--format=- %h %s", range)
+      "Goal: #{goal["description"]}\nGoal id: #{goal["uuid"]}\n\nCommits (one for each task):\n#{commits}\n\n" \
+        "Review with Approve or Request changes. Coord sends your review to the architect.\n" \
+        "Merge with a merge commit. Do not squash.\n"
+    end
+  end
+
+  # Notify shows a desktop notification on macOS. MAF_NOTIFY=0 turns it off.
+  module Notify
+    def self.user(title, text)
+      return if ENV["MAF_NOTIFY"] == "0" || !system("command -v osascript >/dev/null 2>&1")
+
+      clean = ->(value) { value.to_s.delete("\"\\") }
+      system("osascript", "-e", %(display notification "#{clean.(text)}" with title "#{clean.(title)}"),
+             out: File::NULL, err: File::NULL)
+    end
+  end
+
+  # Slots gives each worktree a stable number. Parallel worktrees use the
+  # number to derive unique test databases and server ports. The main
+  # worktree has no .maf/env.sh and counts as slot 0.
+  class Slots
+    def initialize(coord_dir)
+      @coord_dir = coord_dir
+      @path = File.join(coord_dir, "slots.json")
+      @paths = Paths.new(coord_dir)
+    end
+
+    def assign(slug)
+      FileUtils.mkdir_p(@paths.locks_dir)
+      Locks.new(@paths).with_mutex("slots", worker: "coord") { write(slot_for(live, slug))[slug] }
+    end
+
+    private
+
+    def slot_for(slots, slug)
+      slots[slug] ||= (slots.values.max || 0) + 1
+      slots
+    end
+
+    def read = File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+
+    # A worktree that is gone frees its slot, so a retired worker does not
+    # push every later worker's port higher. Retire and a manual
+    # `git worktree remove` both free the slot on the next assign.
+    def live = read.select { |slug, _slot| Dir.exist?(worktree_dir(slug)) }
+
+    def worktree_dir(slug) = Worktree.dir_for(project_root, slug)
+    def project_root = File.dirname(File.dirname(File.expand_path(@coord_dir)))
+
+    def write(slots)
+      File.write(@path, JSON.pretty_generate(slots))
+      slots
+    end
+  end
+
+  # WorktreeEnv writes a worktree's .maf/env.sh: the shared board paths, the
+  # worktree's slot, and the output of the optional project hook
+  # .maf/coordination/worktree-env.rb. The hook gets COORD_SLOT and COORD_WORKTREE
+  # and prints `export NAME=VALUE` lines (see assets/worktree-env.example.rb).
+  class WorktreeEnv
+    FILE = ".maf/env.sh"
+    HOOK = "worktree-env.rb"
+
+    def initialize(coord_dir)
+      @coord_dir = coord_dir
+    end
+
+    def write(dir, slug)
+      slot = Slots.new(@coord_dir).assign(slug)
+      FileUtils.mkdir_p(File.join(dir, MAF_DIR))
+      File.write(File.join(dir, FILE), base_lines(slot) + hook_lines(dir, slot))
+    end
+
+    private
+
+    def base_lines(slot)
+      "export COORD_DIR=#{@coord_dir}\nexport TASKRC=#{File.join(@coord_dir, "taskrc")}\n" \
+        "export COORD_SLOT=#{slot}\n#{bin_lines}"
+    end
+
+    # Same two lines as the env.sh of the main project: MAF_BIN and PATH.
+    def bin_lines
+      "export MAF_BIN=#{File.join(File.dirname(@coord_dir), "bin")}\n" \
+        "case \":$PATH:\" in *\":$MAF_BIN:\"*) ;; *) export PATH=\"$MAF_BIN:$PATH\" ;; esac\n"
+    end
+
+    def hook_lines(dir, slot)
+      hook = File.join(@coord_dir, HOOK)
+      return "" unless File.exist?(hook)
+
+      run_hook(hook, { "COORD_SLOT" => slot.to_s, "COORD_WORKTREE" => dir })
+    end
+
+    # Keep only `export NAME=VALUE` lines. A shell that sources .maf/env.sh
+    # then runs nothing else the hook prints.
+    def run_hook(hook, env)
+      output = IO.popen(env, [RbConfig.ruby, hook], &:read)
+      return output.lines.grep(/\Aexport \w+=/).join if $?.success?
+
+      warn "coord: #{hook} failed. .maf/env.sh has no project variables."
+      ""
+    end
+  end
+
+  # FastForward moves a reused worker branch to origin/<base branch>, so a
+  # long-lived worktree does not drift. It acts only on a worker/ branch that
+  # is checked out in a clean worktree, and only for a fast-forward.
+  # Otherwise it skips and logs the reason. A project without origin is skipped
+  # without a log line.
+  class FastForward
+    def initialize(dir, branch, base)
+      @dir, @branch, @base = dir, branch, base
+    end
+
+    def run
+      return unless @branch.start_with?("worker/") && Git.run(@dir, "remote", "get-url", "origin")
+
+      reason = checks.find { |check, _| !check.call }&.last
+      reason ? warn("coord: no fast-forward of #{@branch}: #{reason}") : merge
+    end
+
+    private
+
+    def checks
+      [[-> { head == @branch }, "#{@branch} is not checked out"],
+       [-> { Git.clean?(@dir) }, "the worktree has uncommitted changes"],
+       [-> { Git.run(@dir, "fetch", "-q", "origin", @base) }, "git fetch origin #{@base} failed"],
+       [-> { Git.run(@dir, "merge-base", "--is-ancestor", "HEAD", target) },
+        "#{@branch} has commits that #{target} lacks"]]
+    end
+
+    def merge
+      return if rev("HEAD") == rev(target)
+
+      Git.run(@dir, "merge", "-q", "--ff-only", target) && puts("fast-forwarded #{@branch} to #{target}")
+    end
+
+    def target = "origin/#{@base}"
+    def head = git_out("branch", "--show-current")
+    def rev(name) = git_out("rev-parse", "-q", "--verify", name)
+    def git_out(*args) = IO.popen(["git", "-C", @dir, *args], err: File::NULL, &:read).strip
+  end
+
+  # Worktree creates a per-worker git worktree and branch, so "one branch or
+  # worktree per worker" (the contract's own rule) is a command, not a manual
+  # step. The worktree shares the main project's .maf/coordination/ dir and task
+  # board through COORD_DIR/TASKRC exported by an untracked .maf/env.sh, not
+  # by symlinking tracked paths (a symlink would dirty the worktree and, if
+  # committed, break the coordination dir on merge).
+  #
+  # All worktrees live inside the project under .maf/worktrees/<slug>.
+  # .maf/worktrees/ is gitignored, so agents stay within the project directory
+  # and need no cross-directory file access permissions. maf start finds the
+  # worktree with the same shared formula.
+  class Worktree
+    ENV_FILE = WorktreeEnv::FILE
+    # The graph folder at the project root. The exclude line has no trailing
+    # slash, so it also matches the symlink.
+    GRAPH_DIR = "graphify-out"
+    LOCAL_EXCLUDES = [ENV_FILE, "/#{GRAPH_DIR}"].freeze
+    RUNTIME_FILES = %w[.maf/bin/coord .maf/coordination/harness-hooks/next-task.rb
+                       .maf/coordination/harness-hooks/board-watch.rb .maf/coordination/harness-hooks/session-guard.rb
+                       .maf/coordination/harness-hooks/context-watch.rb .codex/hooks.json
+                       .opencode/plugins/board-watch.js].freeze
+
+    def self.dir_for(root, slug) = Maf::Shared::Project.worktree_dir(root, slug)
+
+    def initialize(project_root)
+      @root = project_root
+    end
+
+    # Idempotent: a repeat call must not abort just because a previous call
+    # (or a `git worktree remove` that left the branch behind) already did
+    # part of the work.
+    def create(role, worker)
+      slug = self.class.slug(role, worker)
+      checkout(slug, "worker/#{slug}", base_branch)
+    end
+
+    # A new worker branch starts on the base branch, not on the HEAD of the
+    # main checkout. That HEAD can be a task branch of another role.
+    def base_branch
+      name = Git.base_branch(@root, Manifest.new(File.join(@root, ".maf/config.json")))
+      name if Git.branch?(@root, name)
+    end
+
+    # BASE is the start point of a new branch. Without BASE, git uses HEAD.
+    def checkout(slug, branch, base = nil)
+      dir = self.class.dir_for(@root, slug)
+      return reuse(dir, branch) if Dir.exist?(dir)
+
+      add_worktree(dir, branch, base)
+      finish(dir, branch, "worktree #{dir} on branch #{branch}")
+    end
+
+    def add_worktree(dir, branch, base)
+      FileUtils.mkdir_p(File.dirname(dir))
+      ok = system("git", "-C", @root, "worktree", "add", *add_args(dir, branch, base))
+      abort "coord: git worktree add failed" unless ok
+    end
+
+    # A WORKER that already starts with the role ("frontend-developer-2") is
+    # the full name. Joining it with the role again repeats the role.
+    def self.slug(role, worker)
+      return worker if worker&.start_with?("#{role}-")
+
+      [role, worker].compact.join("-")
+    end
+
+    private
+
+    # No `-b` when the branch already exists (e.g. its worktree was removed
+    # without deleting the branch) -- `git worktree add -b` refuses to reuse
+    # a branch name, `git worktree add` without `-b` checks it out instead.
+    def add_args(dir, branch, base)
+      Git.branch?(@root, branch) ? [dir, branch] : [dir, "-b", branch, *base]
+    end
+
+    def reuse(dir, branch)
+      unless worktree?(dir)
+        abort "coord: #{dir} exists but is not a git worktree. Remove it or choose a different slug."
+      end
+
+      FastForward.new(dir, branch, Git.base_branch(@root, Manifest.new(File.join(@root, ".maf/config.json")))).run
+      finish(dir, branch, "worktree #{dir} already exists, reusing (branch #{branch})")
+    end
+
+    def worktree?(dir)
+      system("git", "-C", dir, "rev-parse", "--is-inside-work-tree", out: File::NULL, err: File::NULL)
+    end
+
+    def finish(dir, branch, message)
+      ensure_runtime_files(dir)
+      link_graph(dir)
+      exclude_local_files(dir)
+      WorktreeEnv.new(File.join(@root, MAF_DIR, "coordination")).write(dir, File.basename(dir))
+      puts message, SOURCE_HINT
+    end
+
+    SOURCE_HINT = "In that worktree, run: source #{ENV_FILE}   (shares this project's .maf/coordination/ " \
+                  "and task board)"
+
+    # The flow is not committed: it is a tool, not a part of the project. So
+    # a fresh worktree checks out none of these files. Copy the main
+    # worktree's copy of each missing file. A reused worktree
+    # gets files that were added after it was created. An existing file is
+    # never overwritten, so a change by the agent stays.
+    def ensure_runtime_files(dir)
+      paths = (RUNTIME_FILES + bin_files + copy_list).uniq
+      paths.each { |path| copy_missing(File.join(@root, path), File.join(dir, path)) }
+    end
+
+    # Every script of .maf/bin, not only coord: dispatch mode needs the dispatcher.
+    # The scripts load the shared library from .maf/lib.
+    def bin_files
+      Dir.glob("#{MAF_DIR}/{bin/*,lib/**/*.rb}", base: @root).select { |path| File.file?(File.join(@root, path)) }
+    end
+
+    # copy_to_worktree in .maf/config.json lists more host files for each
+    # worktree, for example .env. Only paths inside the project are copied.
+    def copy_list
+      list = Manifest.new(File.join(@root, ".maf/config.json")).copy_to_worktree
+      outside = list.select { |path| path.start_with?("/") || path.split("/").include?("..") }
+      warn "coord: copy_to_worktree skips paths outside the project: #{outside.join(", ")}" unless outside.empty?
+      list - outside
+    end
+
+    def copy_missing(src, dest)
+      return if File.exist?(dest) || !File.exist?(src)
+
+      FileUtils.mkdir_p(File.dirname(dest))
+      FileUtils.cp(src, dest, preserve: true)
+    end
+
+    # The graph is not committed. A relative symlink gives the worktree the
+    # graph of the main checkout at the default path of graphify, so a query
+    # or a saved note in the worktree uses the main graph.
+    def link_graph(dir)
+      link = File.join(dir, GRAPH_DIR)
+      return if File.exist?(link) || File.symlink?(link)
+
+      FileUtils.mkdir_p(File.join(@root, GRAPH_DIR))
+      File.symlink(Pathname.new(File.join(@root, GRAPH_DIR)).relative_path_from(Pathname.new(dir)).to_s, link)
+    end
+
+    # .maf/env.sh holds absolute host paths, and the graph link points into
+    # the main checkout. Neither may be committed. Git has no per-worktree
+    # exclude, and .gitignore may not be committed yet, so add both to the
+    # repository's shared local exclude instead. bootstrap excludes the graph
+    # too; an install from before the graph link lacks that line.
+    def exclude_local_files(dir)
+      exclude = Maf::Shared::GitExclude.path(dir)
+      missing = exclude && unlisted(exclude)
+      return if missing.nil? || missing.empty?
+
+      FileUtils.mkdir_p(File.dirname(exclude))
+      File.open(exclude, "a") { |file| file.puts(missing) }
+    end
+
+    def unlisted(exclude) = LOCAL_EXCLUDES - (File.exist?(exclude) ? File.read(exclude).lines.map(&:strip) : [])
+  end
+
+  # CLI dispatches commands. Keep methods small; collaborators do the work.
+  # Args wraps the argument list with small parsing helpers.
+  class Args
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def flag?(name)
+      index = @argv.index(name)
+      return false unless index
+
+      @argv.delete_at(index)
+      true
+    end
+
+    def value_of(name)
+      index = @argv.index(name)
+      return nil unless index
+
+      @argv.delete_at(index)
+      @argv.delete_at(index)
+    end
+
+    def ttl = (value_of("--ttl") || 3600).to_i
+    def interval = (value_of("--interval") || DEFAULT_POLL_INTERVAL).to_i
+    def timeout = (v = value_of("--timeout")) && v.to_i
+
+    def require_arg(command, name)
+      shift || abort("usage: coord #{command} #{name}")
+    end
+
+    def require_text(command)
+      text = @argv.join(" ")
+      abort "usage: coord #{command} ... TEXT" if text.empty?
+
+      text
+    end
+
+    def parse_options(spec)
+      opts = {}
+      OptionParser.new { |o| spec.each { |flag, key| o.on("#{flag} VALUE") { |v| opts[key] = v } } }.parse!(@argv)
+      opts
+    end
+
+    def shift = @argv.shift
+    def first = @argv.first
+    def empty? = @argv.empty?
+    def join = @argv.join(" ")
+
+    # Splits argv at the first literal "--" and returns the words after it,
+    # leaving only the option part in @argv. This keeps a wrapped command's own
+    # flags (e.g. "--ttl") out of coord's option parsing.
+    def take_command
+      index = @argv.index("--")
+      return nil unless index
+
+      command = @argv[(index + 1)..]
+      @argv.replace(@argv[0...index])
+      command
+    end
+  end
+
+  # Each *Commands module implements coord subcommands. State lives on the CLI instance.
+  # Task commands add, list, show, and export tasks.
+  module TaskCommands
+    def cmd_init
+      setup.ensure_dirs
+      setup.ensure_taskrc
+      puts ".maf/coordination/ ready (#{@coord_dir})"
+    end
+
+    def cmd_add
+      opts = add_options
+      id = tasks.add(**opts)
+      event_log.append("add", @worker, "#{id} #{opts[:title]}")
+      after_add(opts, id)
+    end
+
+    def after_add(opts, id)
+      conflicts.warn_with(opts[:scope], exclude: id)
+      report_unstaffed(opts[:role], id)
+      puts id
+    end
+
+    def add_options
+      opts = @args.parse_options(ADD_OPTS)
+      opts[:title] ||= @args.join unless @args.empty?
+      abort "usage: coord add --role R --scope S --title T" if opts[:title].to_s.empty?
+      opts[:goal] &&= goal_uuid(opts[:goal])
+      opts
+    end
+
+    def cmd_next
+      flags = next_flags
+      role = require_role!(@args.shift || @role, "next ROLE, or export COORD_ROLE")
+      refuse_lead!(role, "has no tasks to wait for") if flags[:wait]
+      return board.mine_tasks(role, @worker) if flags[:mine]
+
+      flags[:wait] ? wait_next(role, flags) : board.next_tasks(role, @worker)
+    end
+
+    # Every flag must be parsed out before the positional `shift`: `shift`
+    # takes whatever token is first, flag or not, so a flag left unparsed
+    # (e.g. --timeout) would be swallowed as the ROLE argument.
+    def next_flags
+      { mine: @args.flag?("--mine"), wait: @args.flag?("--wait"), interval: @args.interval, timeout: @args.timeout }
+    end
+
+    # A fresh Tasks instance per check: Tasks#pending memoizes (so one
+    # `coord board` run only shells out to `task` once), but reusing the
+    # single Wiring-memoized instance across poll iterations would freeze
+    # the result at the first, possibly-empty, snapshot forever.
+    # A message ends the wait too: an agent blocked here must not miss it.
+    def wait_next(role, flags)
+      wait_for(flags[:interval], flags[:timeout], -> { Tasks.new.next_for(role, @worker) + messages.files(role) }) do
+        board.next_tasks(role, @worker)
+        announce_messages(role)
+      end
+    end
+
+    def announce_messages(role)
+      count = messages.files(role).size
+      puts "#{count} unread message#{"s" if count != 1}. Run coord inbox." if count.positive?
+    end
+
+    def cmd_conflicts = conflicts.report
+
+    def cmd_show
+      puts TaskView.lines(find_task!(@args.require_arg("show", "ID")))
+    end
+
+    def cmd_start_task
+      task = find_task!(@args.require_arg("start-task", "ID"))
+      base = task["goalid"] ? Goals.branch(task["goalid"]) : Git.base_branch(@project_root, manifest)
+      TaskBranch.new(@project_root).start(task["uuid"], base)
+      event_log.append("start-task", @worker, task["uuid"])
+    end
+
+    def cmd_status = board.status
+    def cmd_who = presence.report
+    def cmd_board = board.board
+
+    def cmd_export
+      tasks.export_to(paths.export_path)
+      puts "export -> #{paths.export_path}"
+    end
+
+    def cmd_help = puts(Usage::TEXT)
+
+    private
+
+    UNSTAFFED = "No worker runs role %s."
+
+    # With a worker registry (.maf/coordination/workers.json), a task for a role
+    # without a worker waits forever. Tell the project manager once per role.
+    def report_unstaffed(role, id)
+      return if role.nil? || staffed?(role) || unstaffed_notice?(role)
+
+      event_log.append("unstaffed", @worker, role)
+      text = "#{format(UNSTAFFED, role)} Task #{id} waits. Add a worker: maf prepare HARNESS #{role}_1 --dispatch"
+      return warn("coord: #{text}") unless manifest.agents.any? { |a| a["role"] == "project-manager" }
+
+      deliver("project-manager", "coord", text)
+    end
+
+    def staffed?(role)
+      path = File.join(paths.coord_dir, "workers.json")
+      !File.exist?(path) || JSON.parse(File.read(path)).values.any? { |entry| entry["role"] == role }
+    end
+
+    # The event log records each notice. A message in the inbox is not enough:
+    # a project without a project-manager role gets no message at all, and the
+    # log is the only place the notice is remembered.
+    def unstaffed_notice?(role)
+      path = paths.log_path
+      return false unless File.exist?(path)
+
+      File.readlines(path).any? { |line| unstaffed_line?(line, role) }
+    end
+
+    def unstaffed_line?(line, role)
+      _time, action, _worker, detail = line.split("\t")
+      action == "unstaffed" && detail.to_s.strip == role
+    end
+  end
+
+  # Claim commands take, release, note, and finish a task.
+  module ClaimCommands
+    def cmd_claim
+      id = @args.require_arg("claim", "ID")
+      force = @args.flag?("--force")
+      require_worker!(@worker, "claim ID (needs COORD_WORKER or COORD_ROLE)")
+      refuse_lead!(@role, "never claims a task")
+      claimed(id, locks.with_mutex("task-#{id}", worker: @worker) { tasks.claim(id, @worker, force: force) })
+    end
+
+    def claimed(id, holder)
+      notify_prior_holder(id, holder) if holder && holder.worker != @worker
+      event_log.append("claim", @worker, id)
+      puts "claimed #{id} by #{@worker}"
+    end
+
+    def cmd_unclaim
+      id = @args.require_arg("unclaim", "ID")
+      tasks.unclaim(id)
+      event_log.append("unclaim", @worker, id)
+      puts "unclaimed #{id}"
+    end
+
+    def cmd_done
+      force = @args.flag?("--force")
+      id = @args.require_arg("done", "ID")
+      task = tasks.find(id)
+      refuse_done!(task, force)
+      finish_task(id, task)
+    end
+
+    def refuse_done!(task, force)
+      refuse_foreign!(task, force)
+      refuse_stale!(task) unless force
+      refuse_unverified!
+    end
+
+    def finish_task(id, task)
+      tasks.done(id)
+      event_log.append("done", @worker, id)
+      report_done(task)
+      WorkMemory.new(main_root).save(task, "useful", WorkMemory.notes(task))
+      puts "done #{id}"
+    end
+
+    # A dispatched architect starts only on a message. Without this notice,
+    # the architect never learns that a task is ready for its check.
+    def report_done(task)
+      return if [nil, "architect", Goals::ROLE].include?(task["role"]) || @role == "architect"
+
+      text = "Task #{task["uuid"]} is done: #{task["description"]}. Check the diff and the TESTS line."
+      deliver("architect", @worker, text)
+    end
+
+    def cmd_annotate
+      id = @args.require_arg("annotate", "ID")
+      tasks.annotate(id, @args.require_text("annotate"))
+      event_log.append("annotate", @worker, id)
+      puts "annotated #{id}"
+    end
+
+    LESSON_USAGE = "usage: coord lesson ID dead_end|corrected TEXT..."
+    LESSON_FAILED = "coord: no graph in graphify-out/, or graphify failed. The lesson is not saved."
+
+    # A dead end saves the text as the answer. A correction saves the task
+    # notes as the answer and the text as the right way.
+    def cmd_lesson
+      id = @args.require_arg("lesson", "ID")
+      outcome = @args.shift
+      abort LESSON_USAGE unless %w[dead_end corrected].include?(outcome)
+
+      save_lesson(find_task!(id), outcome, @args.require_text("lesson"))
+    end
+
+    def save_lesson(task, outcome, text)
+      memory = WorkMemory.new(main_root)
+      answer, correction = outcome == "dead_end" ? [text, nil] : [WorkMemory.notes(task), text]
+      abort LESSON_FAILED unless memory.save(task, outcome, answer, correction)
+
+      event_log.append("lesson", @worker, "#{task["uuid"]} #{outcome}")
+      puts "lesson saved for #{task["uuid"]}"
+    end
+
+    def find_task!(id)
+      task = tasks.find(id)
+      raise Error, "no task found" if task["uuid"].nil?
+
+      task
+    end
+
+    private
+
+    STALE = "coord: branch %<task>s lacks the head of %<goal>s. In your worktree, run `git merge %<goal>s`. " \
+            "Run the task tests again. Then run coord done again. Use --force only if the merge is not wanted."
+
+    # A stalled run can wake up after its claim was released. It must not close
+    # a task that is closed or that another worker holds now.
+    def refuse_foreign!(task, force)
+      status = task["status"]
+      raise Error, "task #{task["uuid"]} is already #{status}. Stop work on it." if status && status != "pending"
+
+      holder = task["worker"].to_s
+      return if force || holder.empty? || holder == @worker
+
+      raise Error, "task #{task["uuid"]} belongs to #{holder} now. Stop work on it (use --force to close it anyway)."
+    end
+
+    def refuse_stale!(task)
+      goal, branch = TaskSync.new(@project_root).stale(task)
+      abort format(STALE, task: branch, goal: goal) if goal
+    end
+
+    VERIFY_FAILED = "coord: the verify command failed: %<command>s\n%<tail>s\n" \
+                    "Fix the failures. Then run coord done again. --force does not skip this check."
+
+    # The verify command in .maf/config.json is a mechanical gate for done.
+    # It runs in the current worktree. No key means no check.
+    def refuse_unverified!
+      command = manifest.verify
+      return if command.empty?
+
+      output = IO.popen(["sh", "-c", command], err: %i[child out], &:read)
+      abort format(VERIFY_FAILED, command: command, tail: output.lines.last(20).join.strip) unless $?.success?
+    end
+
+    def notify_prior_holder(id, holder)
+      warn "coord: task #{id} was claimed from #{holder.worker} by #{@worker}"
+      # Send to the role's inbox (what agents poll with `coord inbox`), not the
+      # worker id, which no agent reads. Name the exact worker in the body.
+      to = holder.role.empty? ? holder.worker : holder.role
+      messages.send_message(to, @worker, "task #{id} was claimed from worker #{holder.worker} by #{@worker}")
+    end
+  end
+
+  # Message commands send messages and push them to a role.
+  module MessageCommands
+    def cmd_msg
+      from = require_role!(@args.value_of("--from") || @role, "msg --from A, or export COORD_ROLE")
+      task = @args.value_of("--task")&.then { |id| find_task!(id) }
+      fyi = @args.flag?("--fyi")
+      name = @args.require_arg("msg", "TO")
+      deliver_to(name, from, task_message(task, from, @args.require_text("msg")), fyi: fyi)
+    end
+
+    # An FYI message wakes no one, so it needs no push.
+    def deliver_to(name, from, text, fyi: false)
+      role, worker = recipient(name)
+      path = messages.send_message(role, from, text, worker: worker, fyi: fyi)
+      push(role, from, path) unless fyi
+      event_log.append("msg", @worker, "to #{name}#{" (fyi)" if fyi}: #{text}")
+    end
+
+    # A worker can stop before it reads its mail. The note on the task stays
+    # for the worker that continues the task.
+    def task_message(task, from, text)
+      return text unless task
+
+      tasks.annotate(task["uuid"], "MSG from #{from}: #{text}")
+      "Task #{task["uuid"]}: #{text}\nThis text is also a note on the task (coord show #{task["uuid"]})."
+    end
+
+    # Returns [role, worker]. A worker has no inbox of its own: its mail goes
+    # to its role inbox. A name that is no role and no worker is a typo.
+    def recipient(name)
+      roles = Roster.new(paths, tasks).roles | LEADS
+      return [name, nil] if roles.include?(name) || roles == LEADS
+
+      role = roles.find { |known| name.match?(/\A#{Regexp.escape(known)}-\d+\z/) }
+      role ? [role, name] : raise(Error, "unknown recipient '#{name}'. Use a role or a worker: #{roles.join(", ")}")
+    end
+
+    # Broadcast sends a message to every known role except the sender (see
+    # Roster). The architect uses this for scope changes or blockers that
+    # affect everyone, instead of messaging each role individually.
+    def cmd_broadcast
+      from = require_role!(@args.value_of("--from") || @role, "broadcast --from A, or export COORD_ROLE")
+      audience = Audiences.pick(@args.value_of("--to") || "workers")
+      text = @args.require_text("broadcast")
+      deliver_broadcast(from, text, broadcast_roles(from, audience))
+    end
+
+    def broadcast_roles(from, audience)
+      roles = Roster.new(paths, tasks).roles.select(&audience) - [from]
+      abort "coord: no other roles to broadcast to" if roles.empty?
+
+      roles
+    end
+
+    # Hooks shows which role hooks are installed. With a ROLE argument, shows
+    # just that role's hook. The hooks themselves are plain shell scripts at
+    # .maf/coordination/message-hooks/<role>.sh, fired by `coord msg` and `coord broadcast`.
+    def cmd_hooks
+      return puts("no message hooks directory (run coord init)") unless Dir.exist?(paths.message_hooks_dir)
+
+      found = hook_files(@args.shift)
+      return puts("no hooks installed") if found.empty?
+
+      found.each { |path| puts hook_line(path) }
+    end
+
+    private
+
+    def deliver(to, from, text)
+      path = messages.send_message(to, from, text)
+      push(to, from, path)
+    end
+
+    def deliver_broadcast(from, text, roles)
+      results = messages.broadcast(from, text, roles)
+      results.each { |role, path| push(role, from, path) }
+      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, " \
+              "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,
+    # it waits unseen. Say so at send time, not hours later.
+    def push(role, from, path)
+      return if hooks.run(role, from: from, message_path: path) || presence.live?(role)
+
+      warn format(NO_PUSH, role: role)
+    end
+
+    def hook_files(role)
+      found = Dir.glob(File.join(paths.message_hooks_dir, "*.sh")).sort
+      role ? found.select { |path| File.basename(path, ".sh") == role } : found
+    end
+
+    def hook_line(path)
+      status = File.executable?(path) ? "active" : "inactive (chmod +x)"
+      "#{File.basename(path)}\t#{status}\t#{path}"
+    end
+  end
+
+  # Inbox commands escalate problems and wait for messages.
+  module InboxCommands
+    ESCALATE_PM = "project-manager"
+
+    # A worker cannot fix a problem outside its task, such as a missing tool
+    # or a refused guard. The project manager asks the user. The architect
+    # gets a copy, because the task waits.
+    def cmd_escalate
+      task = @args.value_of("--task")
+      text = @args.require_text("escalate")
+      abort "coord: the project manager cannot escalate to itself. Ask the user." if @role == ESCALATE_PM
+      tasks.annotate(find_task!(task)["uuid"], "ESCALATED: #{text}") if task
+      escalate(task, text)
+    end
+
+    def escalate(task, text)
+      send_escalation(task, text)
+      event_log.append("escalate", @worker, "#{task} #{text}".strip)
+    end
+
+    def send_escalation(task, text)
+      targets = escalation_targets
+      abort "coord: no project manager and no other lead to receive the escalation. Ask the user." if targets.empty?
+      targets.each { |to| deliver(to, @role, escalation_text(task, text)) }
+    end
+
+    def escalation_text(task, text)
+      where = task ? " (task #{task})" : ""
+      "ESCALATION from #{@worker}#{where}: #{text}"
+    end
+
+    # Without a project manager in the project, the architect is the only receiver.
+    def escalation_targets
+      pm = manifest.agents.any? { |agent| agent["role"] == ESCALATE_PM }
+      [(ESCALATE_PM if pm), ("architect" unless @role == "architect")].compact
+    end
+
+    AWAIT_ARMED = "coord: the stop hook waits up to %<minutes>d minutes for work for %<role>s. " \
+                  "Tell the user that you wait and that Esc ends the wait. Then end your turn."
+    AWAIT_DISPATCHED = "coord: a dispatched run cannot wait. Stop: the dispatcher starts a run on new work."
+
+    def cmd_await
+      abort AWAIT_DISPATCHED if @env["COORD_DISPATCHED"]
+      role = require_role!(@role, "await, export COORD_ROLE")
+      seconds = @args.timeout || Await::DEFAULT_SECONDS
+      Await.new(paths, require_worker!(@worker, "await, export COORD_WORKER")).arm(role, seconds)
+      puts format(AWAIT_ARMED, minutes: seconds / 60, role: role)
+    end
+
+    def cmd_inbox
+      flags = inbox_flags
+      role = require_role!(@args.shift || @role, "inbox ROLE, or export COORD_ROLE")
+      return messages.inbox(role, peek: flags[:peek], all: flags[:all]) unless flags[:wait]
+
+      InboxWaiter.new(paths, role).hold { wait_inbox(role, flags) }
+    end
+
+    # Same ordering requirement as cmd_next: parse every flag before the
+    # positional `shift`, or an unparsed flag gets read as the ROLE.
+    def inbox_flags
+      { wait: @args.flag?("--wait"), interval: @args.interval, timeout: @args.timeout,
+        peek: @args.flag?("--peek"), all: @args.flag?("--all") }
+    end
+
+    def wait_inbox(role, flags)
+      wait_for(flags[:interval], flags[:timeout], -> { messages.wake_files(role) }) do
+        messages.inbox(role, peek: flags[:peek], all: flags[:all])
+      end
+    end
+  end
+
+  # Goal commands create, sync, land, and close goals.
+  module GoalCommands
+    GOAL_COMMANDS = { "add" => :goal_add, "list" => :goal_list, "show" => :goal_show, "done" => :goal_done,
+                      "sync" => :goal_sync, "pr" => :goal_pr }.freeze
+
+    def cmd_goal
+      sub = @args.shift
+      abort "usage: coord goal add|list|show|sync|pr|done" unless GOAL_COMMANDS.key?(sub)
+
+      send(GOAL_COMMANDS[sub])
+    end
+
+    # Only the architect lands, one squash at a time for each goal.
+    def cmd_land
+      subject = @args.value_of("--subject")
+      task = find_task!(@args.require_arg("land", "ID"))
+      land = Land.new(main_root, task)
+      commit = locks.with_mutex("land-#{Goals.short(task["goalid"])}", worker: @worker) { land.run(subject) }
+      record_landing(task, commit, land)
+    end
+
+    def record_landing(task, commit, land)
+      where = commit ? "#{commit} on #{land.goal_branch}" : "no changes"
+      tasks.annotate(task["uuid"], "LANDED: #{where}")
+      event_log.append("land", @worker, "#{task["uuid"]} #{where}")
+      puts "landed #{land.branch}: #{where}"
+    end
+
+    private
+
+    def goals = @goals ||= Goals.new(tasks)
+
+    def goal_list = goals.list
+
+    # Older taskrc files lack the `goal` UDA. Add it before the first use.
+    def goal_uuid(id)
+      setup.ensure_taskrc
+      goals.find!(id)["uuid"]
+    end
+    def goal_show = goals.show(@args.require_arg("goal show", "ID"))
+
+    def goal_sync
+      goal = goals.find!(@args.require_arg("goal sync", "ID"))
+      goal_sync_for(goal).run
+      event_log.append("goal-sync", @worker, goal["description"])
+    end
+
+    def goal_sync_for(goal) = GoalSync.new(main_root, goal["uuid"], Git.base_branch(main_root, manifest))
+
+    def goal_done
+      id = @args.require_arg("goal done", "ID")
+      refuse_unsynced!(goals.find!(id))
+      goal = goals.done(id)
+      event_log.append("goal-done", @worker, goal["description"])
+      puts "goal #{id} done. The goal branch is #{Goals.branch(goal["uuid"])}."
+    end
+
+    def goal_add
+      opts = @args.parse_options(GOAL_OPTS)
+      opts[:title] ||= @args.join unless @args.empty?
+      abort "usage: coord goal add --title T [--ref R] [--base BRANCH]" if opts[:title].to_s.empty?
+      setup.ensure_taskrc
+      create_goal(opts, opts[:base] || Git.base_branch(main_root, manifest))
+    end
+
+    def create_goal(opts, base)
+      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)
+      event_log.append("goal", @worker, opts[:title])
+      puts uuid
+    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."
+
+    # A goal without its branch (an old goal) has nothing to check.
+    def refuse_unsynced!(goal)
+      sync = goal_sync_for(goal)
+      branch = Goals.branch(goal["uuid"])
+      return unless Git.branch?(main_root, branch) && sync.behind?
+
+      abort format(UNSYNCED, branch: branch, ref: sync.ref, id: goal["uuid"])
+    end
+  end
+
+  # Review commands open goal pull requests and forward their reviews.
+  module ReviewCommands
+    # The architect dispatcher runs `coord review-watch --once` on a timer.
+    def cmd_review_watch
+      once = @args.flag?("--once")
+      interval = @args.interval
+      require_github!
+      watch_reviews(once, interval)
+    end
+
+    def watch_reviews(once, interval)
+      review_all
+      loop { sleep(interval).then { review_all } } unless once
+    end
+
+    def review_all = review_state.all.each { |uuid, entry| review_goal(uuid, entry) }
+
+    # One failing pull request must not stop the watch of the others.
+    def record_review(uuid, entry, feed)
+      review_state.put(uuid, entry.merge("seen" => feed.seen_after))
+      finish_review(uuid, feed.state) if %w[MERGED CLOSED].include?(feed.state)
+    end
+
+    def review_goal(uuid, entry)
+      feed = ReviewFeed.new(github, entry)
+      forward_review(uuid, entry["url"], feed) unless feed.items.empty?
+      record_review(uuid, entry, feed)
+    rescue Error, JSON::ParserError => e
+      warn "coord: review-watch of goal #{uuid}: #{e.message}"
+    end
+
+    REVIEW_FIX = "Create a fix task for each point. Land the fixes. Run coord goal sync %<id>s. " \
+                 "Then run coord goal pr %<id>s."
+
+    def forward_review(uuid, url, feed)
+      text = "Review of goal #{uuid} (#{url}):\n#{feed.items.map { |_, body| "- #{body}" }.join("\n")}\n"
+      text += format(REVIEW_FIX, id: uuid) if feed.changes_requested?
+      tasks.annotate(uuid, "REVIEW: changes requested") if feed.changes_requested?
+      deliver("architect", "coord", text)
+      event_log.append("review", @worker, "#{uuid} #{feed.items.size} item(s)")
+    end
+
+    def finish_review(uuid, state)
+      review_state.drop(uuid)
+      state == "CLOSED" ? deliver("architect", "coord", format(PR_CLOSED, id: uuid)) : close_merged_goal(uuid)
+    end
+
+    PR_CLOSED = "The pull request of goal %<id>s was closed without a merge. Ask the project manager what to do."
+    PR_MERGED = "The pull request of goal %<id>s was merged. coord closed the goal and ran coord gc."
+
+    def close_merged_goal(uuid)
+      tasks.done(uuid) if tasks.find(uuid)["status"] == "pending"
+      event_log.append("goal-merged", @worker, uuid)
+      sweep(true)
+      deliver("architect", "coord", format(PR_MERGED, id: uuid))
+      Notify.user("Goal merged", tasks.find(uuid)["description"])
+    end
+
+    private
+
+    def github = @github ||= GitHub.new(main_root, manifest.github)
+    def review_state = @review_state ||= ReviewState.new(paths)
+
+    def require_github!
+      return if github.configured?
+
+      raise Error, "no github section in .maf/config.json. Set bot_user, bot_email and reviewer."
+    end
+
+    # The first call opens the pull request. A later call pushes the fixes and asks for a new review.
+    def goal_pr
+      require_github!
+      goal = goals.find!(@args.require_arg("goal pr", "ID"))
+      goals.refuse_open!(goal)
+      refuse_unsynced!(goal)
+      publish_goal(goal, review_state.get(goal["uuid"]))
+    end
+
+    def publish_goal(goal, entry)
+      branch = Goals.branch(goal["uuid"])
+      github.push(branch)
+      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)))
+    end
+
+    # The notes go to the remote with each goal pull request. Another clone may
+    # have pushed notes first. Each note has its own file name, so the merge has
+    # no conflicts. A failed push only warns: the notes stay in the local branch.
+    def push_memory
+      return unless Git.branch?(main_root, WorkMemory::BRANCH)
+
+      merge_remote_memory(File.join(main_root, "graphify-out", "memory"))
+      github.push(WorkMemory::BRANCH)
+    rescue Error => e
+      warn "coord: #{e.message}. The notes stay in the local branch #{WorkMemory::BRANCH}."
+    end
+
+    def merge_remote_memory(dir)
+      fetched = File.exist?(File.join(dir, ".git")) && Git.run(dir, "fetch", "-q", github.remote, WorkMemory::BRANCH)
+      fetched && Git.run(dir, "merge", "-q", "--no-edit", "--allow-unrelated-histories", "FETCH_HEAD")
+    end
+
+    def create_pr(goal, branch)
+      body = PrBody.for(main_root, goal, goal_sync_for(goal).ref)
+      github.create_pr(head: branch, base: Git.base_branch(main_root, manifest), title: goal["description"], body: body)
+    end
+
+    def open_pr(goal, branch)
+      url = create_pr(goal, branch)
+      tasks.annotate(goal["uuid"], "PR: #{url}")
+      announce_pr("Pull request ready for your review", goal, url)
+      url
+    end
+
+    def update_pr(goal, entry, branch)
+      commits = Git.out(main_root, "log", "--reverse", "--format=- %h %s", "#{entry["head"]}..#{branch}")
+      github.comment(entry["url"], "Coord pushed new commits. Please review again.\n\n#{commits}\n")
+      github.request_review(entry["url"])
+      announce_pr("Pull request updated for your review", goal, entry["url"])
+      entry
+    end
+
+    def announce_pr(title, goal, url)
+      Notify.user(title, goal["description"])
+      event_log.append("goal-pr", @worker, url)
+      puts "#{title}: #{url}"
+    end
+  end
+
+  # Upkeep commands handle locks, the event log, worktrees, and cleanup.
+  module UpkeepCommands
+    def cmd_lock
+      name = @args.require_arg("lock", "NAME")
+      worker = require_worker!(@args.value_of("--worker") || @worker, "lock NAME --worker W, or export COORD_WORKER")
+      locks.lock(name, ttl: @args.ttl, worker: worker)
+    end
+
+    def cmd_unlock = locks.unlock(@args.require_arg("unlock", "NAME"))
+
+    def cmd_with_lock
+      name = @args.require_arg("with-lock", "NAME")
+      command = @args.take_command
+      abort "usage: coord with-lock NAME [--ttl SECONDS] -- CMD..." if command.nil? || command.empty?
+
+      exit(run_with_lock(name, command) ? 0 : 1)
+    end
+
+    def run_with_lock(name, command)
+      started = Time.now
+      ok = locks.with_lock(name, ttl: @args.ttl, command: command, worker: @worker)
+      event_log.append("with-lock", @worker, "#{name} #{ok ? "ok" : "failed"} #{(Time.now - started).round}s")
+      ok
+    end
+
+    # Log shows the shared coordination history: claims, completions, unclaims,
+    # and broadcasts, newest last. Optional N limits to the last N entries.
+    def cmd_log
+      raw = @args.shift
+      count = raw && Integer(raw, exception: false)
+      abort "coord: log N (positive integer)" if raw && (count.nil? || count < 1)
+      event_log.read(count)
+    end
+
+    def cmd_worktree
+      role = @args.require_arg("worktree", "ROLE")
+      worker = @args.shift
+      warn_missing_role_files(role)
+      Worktree.new(@project_root).create(role, worker)
+    end
+
+    def cmd_gc = sweep(@args.flag?("--yes"))
+
+    REAPED = "Released the claim of task %<id>s. Worker %<worker>s was not seen for %<minutes>s minutes. " \
+             "Check the task branch before the next worker continues."
+
+    def cmd_reap
+      minutes = Integer(@args.value_of("--minutes") || manifest.reap_minutes)
+      stale = Reaper.new(tasks, paths, minutes).stale
+      return puts("no stale claims") if stale.empty?
+
+      stale.each { |task| reap(task, format(REAPED, id: task["uuid"], worker: task["worker"], minutes: minutes)) }
+    end
+
+    def reap(task, text)
+      tasks.unclaim(task["uuid"])
+      tasks.annotate(task["uuid"], "RELEASED: #{text}")
+      event_log.append("reap", @worker, "#{task["uuid"]} #{task["worker"]}")
+      deliver("architect", "coord", text)
+    end
+
+    def sweep(apply)
+      items = Sweep.new(main_root, tasks, Git.base_branch(main_root, manifest)).items
+      return puts("nothing to clean") if items.empty?
+
+      items.each { |item| puts sweep_line(item, apply) }
+      apply ? Git.run(main_root, "worktree", "prune") : puts("Dry run. Run coord gc --yes to delete.")
+    end
+
+    def sweep_line(item, apply)
+      return "keep    #{item.label}: #{item.reason}" if item.reason
+      return "delete  #{item.label}" unless apply
+
+      item.action.call ? "deleted #{item.label}" : "failed  #{item.label}"
+    end
+
+    private
+
+    # A worker started in a harness that has no file for its role runs
+    # without its duties. Name each harness that lacks the role file. maf sets
+    # MAF_HARNESS, because maf knows the harness that starts the worker.
+    def warn_missing_role_files(role)
+      harnesses = ENV["MAF_HARNESS"] ? [ENV["MAF_HARNESS"]] : manifest.harnesses
+      missing = harnesses - manifest.harnesses_for(role)
+      return if missing.empty?
+
+      warn "coord: #{role} has no role file for #{missing.join(", ")}. " \
+           "Fix: maf add #{missing.map { |harness| "#{harness}:#{role}" }.join(" ")}"
+    end
+  end
+
+  # CommandHelpers holds the guards and lookups that many commands share.
+  module CommandHelpers
+    private
+
+    def manifest = @manifest ||= Manifest.new(paths.manifest_path)
+    def main_root = File.dirname(File.dirname(File.expand_path(@coord_dir)))
+
+    def require_role!(value, usage) = require_set!(value, "role", "COORD_ROLE", usage)
+    def require_worker!(value, usage) = require_set!(value, "worker", "COORD_WORKER", usage)
+
+    def require_set!(value, term, env_name, usage)
+      return value unless value.nil? || value.empty? || value == "unknown"
+
+      abort "coord: no #{term} set. Pass one explicitly or `export #{env_name}=<#{term}>` (usage: #{usage})"
+    end
+
+    LEAD_HINT = "coord: role %<role>s is a lead role and %<what>s. Wait for messages with coord inbox --wait."
+
+    def refuse_lead!(role, what)
+      abort format(LEAD_HINT, role: role, what: what) if LEADS.include?(role)
+    end
+
+    # Polls at `interval` seconds until `check` returns a non-empty result, then
+    # runs the given block once. Matches the documented "wait 60s, do not spin"
+    # rule in code instead of leaving it to agent self-discipline.
+    def wait_for(interval, timeout, check)
+      deadline = Time.now + timeout if timeout
+      sleep interval while check.call.empty? && !timed_out!(deadline, timeout)
+      yield
+    end
+
+    def timed_out!(deadline, timeout)
+      abort "coord: timed out after #{timeout}s waiting" if deadline && Time.now >= deadline
+      false
+    end
+  end
+
+  # CLI parses arguments and dispatches to a command.
+  class CLI
+    include TaskCommands
+    include ClaimCommands
+    include MessageCommands
+    include InboxCommands
+    include GoalCommands
+    include ReviewCommands
+    include UpkeepCommands
+    include CommandHelpers
+    include Wiring
+
+    def initialize(argv, env: ENV)
+      @args, @env, @project_root = Args.new(argv), env, Dir.pwd
+      @coord_dir = env.fetch("COORD_DIR", File.join(MAF_DIR, "coordination"))
+      @role = env.fetch("COORD_ROLE", "unknown")
+      @worker = env.fetch("COORD_WORKER", @role)
+      ENV["TASKRC"] = @taskrc = env.fetch("TASKRC", File.join(@coord_dir, "taskrc"))
+    end
+
+    # Each commit of coord, as each commit of an agent, uses the git persona of the agents.
+    def run
+      Maf::Shared::GitIdentity.apply(Maf::Shared::GitIdentity.read(paths.manifest_path))
+      presence.touch(@role, @worker, @env)
+      dispatch(@args.shift || "help")
+    rescue Error => e
+      abort "coord: #{e.message}"
+    end
+
+    private
+
+    def dispatch(command)
+      method = COMMANDS[command]
+      abort "coord: unknown command '#{command}'\n\n#{Usage::TEXT}" unless method
+
+      send(method)
+    end
+  end
+end
+
+Coord::CLI.new(ARGV).run if __FILE__ == $PROGRAM_NAME