maf 0.1.0

data/assets/harness-hooks/board-watch.rb

@@ -0,0 +1,286 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# board-watch.rb - background board watcher for Claude Code sessions.
+#
+# Claude Code runs this script as an asyncRewake hook on SessionStart and on
+# Stop. The hook process runs in the background. When the script exits with
+# code 2, Claude Code shows its stderr to the model and starts a new turn,
+# also in an idle session.
+#
+# Each interval, the script checks the session and the board:
+# - If the session transcript changed in the last BOARD_WATCH_IDLE seconds,
+#   the agent is running. The script does nothing.
+# - If the agent is idle and the board has work for the role, the script
+#   pokes the agent (stderr + exit 2) and ends.
+# Work is: unclaimed tasks for the role, tasks that this worker claimed, and
+# unread inbox messages. An unchanged poke repeats with a doubling delay.
+#
+# One watcher runs per worker (lock: .maf/coordination/locks/board-watch-<worker>.d).
+# The script ends when its Claude Code process ends.
+#
+# Claude Code (.claude/settings.json), on SessionStart and on Stop:
+#   {"type":"command","command":"ruby .maf/coordination/harness-hooks/board-watch.rb",
+#    "async":true,"asyncRewake":true,"timeout":604800}
+#
+# Required env: COORD_ROLE (set by maf start). COORD_DIR and TASKRC optional.
+# Env: BOARD_WATCH_INTERVAL (default 60), BOARD_WATCH_IDLE (default 120),
+# BOARD_WATCH_BATCH (default 120).
+# The script does nothing if COORD_DISPATCHED is set: the dispatcher owns
+# the loop for dispatched agents.
+#
+# With --once, the script checks the board one time and does not wait. If
+# the board has work that is due, the script prints the poke to stdout and
+# exits 2. The opencode plugin (board-watch-opencode.js) uses this mode.
+require "digest"
+require "fileutils"
+require "json"
+require "rbconfig"
+require_relative "session-guard"
+
+module BoardWatch
+  UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/
+  MAX_BACKOFF = 3600
+  PROMPT = "Board watcher: the task board has work for role %<role>s.\n%<summary>s\n" \
+           "Run coord inbox, then coord next --mine, then coord next. " \
+           "Finish claimed tasks first. Claim the next task and complete it. When no work remains, stop."
+
+  # Work is one snapshot of the board for one worker.
+  Work = Struct.new(:unclaimed, :claimed, :messages) do
+    def any? = to_a.any? { |list| !list.empty? }
+    def digest = Digest::SHA256.hexdigest(to_a.inspect)
+
+    def summary
+      { "unclaimed tasks" => unclaimed, "your claimed tasks" => claimed, "unread messages" => messages }
+        .reject { |_label, list| list.empty? }.map { |label, list| "- #{label}: #{list.size}" }.join("\n")
+    end
+  end
+
+  # Board reads work for one role and worker through the coord CLI.
+  class Board
+    def initialize(coord, env)
+      @coord = coord
+      @env = env
+    end
+
+    def work
+      Work.new(task_ids("next", @env["COORD_ROLE"]), task_ids("next", "--mine"), messages)
+    end
+
+    # Messages often come in a group: each done task sends one. A poke for
+    # messages only waits until the oldest message is BATCH seconds old, so
+    # one turn reads the whole group. Each turn sends the whole context again.
+    def settled?(work, batch)
+      !(work.unclaimed + work.claimed).empty? || oldest_message_age >= batch
+    end
+
+    private
+
+    def task_ids(*args)
+      output = IO.popen(@env, [RbConfig.ruby, @coord, *args], err: File::NULL, &:read).to_s
+      output.lines.map(&:strip).grep(UUID).map { |line| line[UUID] }
+    end
+
+    def messages = message_paths.map { |path| File.basename(path) }
+
+    # An FYI message (coord msg --fyi) wakes no one. NOTE: assets/coord writes the mark.
+    def message_paths
+      Dir.glob(File.join(@env["COORD_DIR"], "inbox", @env["COORD_ROLE"], "*.md")).reject { |path| path.include?(".fyi.") }
+    end
+    def oldest_message_age = message_paths.map { |path| Time.now - File.mtime(path) }.max.to_i
+  end
+
+  # Session tells if the agent is running: Claude Code appends to the
+  # transcript while a turn runs.
+  class Session
+    def initialize(transcript, idle)
+      @transcript = transcript.to_s
+      @idle = idle
+    end
+
+    def running?
+      File.exist?(@transcript) && Time.now - File.mtime(@transcript) < @idle
+    end
+  end
+
+  # Owner is the Claude Code process that started the hook. A shell wrapper
+  # between the two is skipped.
+  class Owner
+    SHELLS = %w[sh bash zsh dash].freeze
+
+    def initialize(pid = Process.ppid)
+      @pid = SHELLS.include?(command(pid)) ? parent(pid) : pid
+    end
+
+    def alive?
+      @pid > 1 && Process.kill(0, @pid) && true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    private
+
+    def command(pid) = File.basename(`ps -o comm= -p #{pid}`.strip)
+    def parent(pid) = `ps -o ppid= -p #{pid}`.strip.to_i
+  end
+
+  # Lock makes sure only one watcher runs per worker. A lock whose process
+  # is gone is stale and is taken over.
+  class Lock
+    def initialize(dir)
+      @dir = dir
+      @pid_file = File.join(dir, "pid")
+    end
+
+    def acquire
+      take || (stale? && FileUtils.rm_rf(@dir) && take)
+    end
+
+    def release
+      FileUtils.rm_rf(@dir) if File.exist?(@pid_file) && File.read(@pid_file).to_i == Process.pid
+    end
+
+    private
+
+    def take
+      FileUtils.mkdir_p(File.dirname(@dir))
+      Dir.mkdir(@dir) && File.write(@pid_file, Process.pid) && true
+    rescue Errno::EEXIST
+      false
+    end
+
+    def stale?
+      pid = File.exist?(@pid_file) ? File.read(@pid_file).to_i : 0
+      pid <= 0 || !Process.kill(0, pid)
+    rescue Errno::ESRCH
+      true
+    end
+  end
+
+  # Backoff stores the last poke of a worker. An unchanged poke repeats only
+  # after a delay that doubles each time, up to MAX_BACKOFF.
+  class Backoff
+    def initialize(path, interval)
+      @path = path
+      @interval = interval
+    end
+
+    def due?(work)
+      last = state
+      last["digest"] != work.digest || Time.now.to_i - last["at"].to_i >= last["delay"].to_i
+    end
+
+    def record(work)
+      last = state
+      delay = last["digest"] == work.digest ? [last["delay"].to_i * 2, @interval].max : @interval
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, JSON.generate(digest: work.digest, at: Time.now.to_i, delay: [delay, MAX_BACKOFF].min))
+    end
+
+    private
+
+    def state
+      File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+    rescue JSON::ParserError
+      {}
+    end
+  end
+
+  Parts = Struct.new(:board, :session, :owner, :backoff, :batch, keyword_init: true)
+
+  # Watcher sleeps one interval per check. It returns the work to poke
+  # about, or nil if the owner process is gone.
+  class Watcher
+    def initialize(parts, interval)
+      @parts = parts
+      @interval = interval
+    end
+
+    def wait_for_work
+      work = nil
+      work = pokeable while work.nil? && @parts.owner.alive? && sleep(@interval)
+      work
+    end
+
+    private
+
+    def pokeable
+      return nil if @parts.session.running?
+
+      work = @parts.board.work
+      work if work.any? && @parts.board.settled?(work, @parts.batch) && @parts.backoff.due?(work)
+    end
+  end
+
+  # Main reads the environment and the hook input, runs one watcher, and
+  # returns the exit code: 2 to poke the agent, 0 otherwise.
+  class Main
+    def initialize(env, input)
+      @env = env
+      @input = input
+    end
+
+    def run
+      return 0 unless active? && lock.acquire
+
+      work = watcher.wait_for_work
+      lock.release
+      work ? poke(work) : 0
+    end
+
+    def run_once
+      return 0 unless active?
+      return 0 if @input["hook_event_name"] == "SessionStart"
+
+      board = Board.new(coord, board_env)
+      work = board.work
+      work.any? && board.settled?(work, batch) && backoff.due?(work) ? poke(work, $stdout) : 0
+    end
+
+    private
+
+    def active? = !@env["COORD_DISPATCHED"] && guard.authorized?
+    def role = @env["COORD_ROLE"].to_s
+    def worker = @env.fetch("COORD_WORKER", role)
+    def coord_dir = guard.coord_dir
+    def guard = @guard ||= MafSession::Guard.new(@env, @input)
+    def lock = @lock ||= Lock.new(File.join(coord_dir, "locks", "board-watch-#{worker}.d"))
+    def backoff = @backoff ||= Backoff.new(File.join(coord_dir, "sessions", "#{worker}.watch.json"), interval)
+    def interval = seconds("BOARD_WATCH_INTERVAL", 60)
+    def batch = seconds("BOARD_WATCH_BATCH", 120)
+    def seconds(name, default) = Integer(@env.fetch(name, default.to_s), exception: false) || default
+
+    def coord
+      guard.coord
+    end
+
+    def watcher
+      session = Session.new(@input["transcript_path"], seconds("BOARD_WATCH_IDLE", 120))
+      parts = Parts.new(board: Board.new(coord, board_env), session: session, owner: Owner.new, backoff: backoff,
+                        batch: batch)
+      Watcher.new(parts, interval)
+    end
+
+    def board_env
+      @env.to_h.merge("COORD_DIR" => coord_dir, "COORD_ROLE" => role, "COORD_WORKER" => worker,
+                      "TASKRC" => @env.fetch("TASKRC", File.join(coord_dir, "taskrc")))
+    end
+
+    def poke(work, out = $stderr)
+      backoff.record(work)
+      out.puts format(PROMPT, role: role, summary: work.summary)
+      2
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  once = ARGV.include?("--once")
+  input = begin
+    JSON.parse($stdin.read.to_s)
+  rescue JSON::ParserError
+    {}
+  end
+  main = BoardWatch::Main.new(ENV, input)
+  exit once ? main.run_once : main.run
+end

data/assets/harness-hooks/context-watch.rb

@@ -0,0 +1,268 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# context-watch.rb - status, usage, and context limit hook for interactive
+# Claude Code and Codex sessions.
+#
+# Stop: the script reads the new part of the session transcript. It writes
+# the model and the context size to .maf/coordination/status/<worker>.json,
+# and adds the token usage to .maf/coordination/usage/<worker>.json. If the
+# context is over the limit, it asks the agent one time for a handoff note.
+# Then it tells the user to type /clear. Each model call sends the whole
+# context again, so a fresh session with the note costs less.
+#
+# SessionStart: after /clear or a new start, the script gives the new session
+# the handoff note as context.
+#
+# Limit: MAF_CONTEXT_LIMIT, else team.context_limit in .maf/config.json, else
+# DEFAULT_LIMIT tokens. Only a registered maf start session runs the script.
+# Dispatched agents (COORD_DISPATCHED) are skipped: the dispatcher owns them.
+require "json"
+require "fileutils"
+require "time"
+require_relative "session-guard"
+
+module ContextWatch
+  DEFAULT_LIMIT = 150_000
+  ASK = "Your context has %<tokens>d tokens, over the limit of %<limit>d. Each model call sends the whole " \
+        "context again. Overwrite %<path>s with a handoff note for your next session. Write at most 300 " \
+        "words: current state, decisions, open questions, and the next step. Then stop."
+  TELL = "Context: %<tokens>dk tokens (limit %<limit>dk). The handoff note is in %<path>s. " \
+         "Type /clear to restart. The new session loads the note."
+
+  # Reading is the new part of one transcript: model, context size, and usage.
+  Reading = Struct.new(:model, :context, :window, :usage, :offset, :total)
+
+  # Transcript reads the lines after OFFSET. Claude Code writes one line per
+  # content block, with the same message id and usage, so ids are counted once.
+  # Codex writes cumulative totals, so the usage is the change of the total.
+  class Transcript
+    USAGE_KEYS = %w[input_tokens cached_input_tokens cache_write_input_tokens output_tokens].freeze
+    CLAUDE_KEYS = { "cached_input_tokens" => "cache_read_input_tokens",
+                    "cache_write_input_tokens" => "cache_creation_input_tokens", "output_tokens" => "output_tokens" }.freeze
+
+    def initialize(path, offset, seen_total)
+      @path, @offset, @seen_total = path, offset, seen_total
+    end
+
+    def read
+      reading = Reading.new(nil, nil, nil, Hash.new(0), @offset, nil)
+      lines { |event| claude(reading, event) || codex(reading, event) }
+      reading.offset = File.size(@path)
+      reading
+    end
+
+    private
+
+    def lines
+      File.open(@path) do |file|
+        file.seek(@offset)
+        file.each_line { |line| (event = parse(line)) && yield(event) }
+      end
+    end
+
+    def parse(line)
+      event = JSON.parse(line)
+      event.is_a?(Hash) ? event : nil
+    rescue JSON::ParserError
+      nil
+    end
+
+    def claude(reading, event)
+      usage = event.dig("message", "usage")
+      return false unless event["type"] == "assistant" && usage && !event["isSidechain"]
+
+      reading.model = event.dig("message", "model")
+      reading.context = %w[input_tokens cache_read_input_tokens cache_creation_input_tokens].sum { |k| usage[k].to_i }
+      add_claude(reading, event.dig("message", "id"), usage)
+    end
+
+    def add_claude(reading, id, usage)
+      return true if (@ids ||= {}).key?(id)
+
+      @ids[id] = true
+      reading.usage["input_tokens"] += reading.context
+      CLAUDE_KEYS.each { |key, name| reading.usage[key] += usage[name].to_i }
+    end
+
+    def codex(reading, event)
+      payload = event["payload"] || {}
+      reading.model = payload["model"] if event["type"] == "turn_context"
+      info = payload["info"] if payload["type"] == "token_count"
+      info && codex_tokens(reading, info)
+    end
+
+    def codex_tokens(reading, info)
+      reading.context = info.dig("last_token_usage", "input_tokens")
+      reading.window = info["model_context_window"]
+      reading.total = (info["total_token_usage"] || {}).slice(*USAGE_KEYS)
+      USAGE_KEYS.each { |key| reading.usage[key] = reading.total[key].to_i - @seen_total[key].to_i }
+    end
+  end
+
+  # Store reads and writes the status and the usage files of one worker.
+  class Store
+    def initialize(coord_dir, worker)
+      @status = File.join(coord_dir, "status", "#{worker}.json")
+      @usage = File.join(coord_dir, "usage", "#{worker}.json")
+      @handoff = File.join(coord_dir, "sessions", "#{worker}.handoff.md")
+    end
+
+    attr_reader :handoff
+
+    def status = read(@status)
+    def save(data) = write(@status, status.merge(data))
+    def note = File.exist?(@handoff) ? File.read(@handoff).strip : ""
+
+    def add_usage(delta)
+      return if delta.values.all?(&:zero?)
+
+      totals = read(@usage)
+      sums = delta.to_h { |key, value| [key, totals[key].to_i + value] }
+      write(@usage, totals.merge(sums).merge("runs" => totals["runs"].to_i + 1))
+    end
+
+    private
+
+    def read(path)
+      File.exist?(path) ? JSON.parse(File.read(path)) : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def write(path, data)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write("#{path}.tmp", JSON.generate(data))
+      File.rename("#{path}.tmp", path)
+    end
+  end
+
+  # Hook handles one hook event and returns the JSON output, or nil.
+  class Hook
+    def initialize(input, env)
+      @input, @env = input, env
+      @store = Store.new(env.fetch("COORD_DIR"), env.fetch("COORD_WORKER"))
+    end
+
+    def run = @input["hook_event_name"] == "SessionStart" ? session_start : stop
+
+    private
+
+    # maf start gives the role file in the first prompt, not as a system
+    # prompt. /clear drops it, so a cleared session gets the role file again.
+    # The hook puts the file text in the context: a Read costs one model call.
+    ROLE_FILES = { "claude" => ".maf/agents/claude/%s.md", "codex" => ".codex/prompts/%s.md" }.freeze
+
+    def session_start
+      @store.save("session_id" => @input["session_id"], "asked" => nil)
+      context = [role_line, note_text].compact.join("\n\n")
+      context.empty? ? nil : { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } }
+    end
+
+    def role_line
+      return nil unless @input["source"] == "clear"
+
+      file = role_file
+      intro = "You are worker #{@env["COORD_WORKER"]}."
+      return "#{intro} Read #{file} and follow it exactly. Start your work loop now." unless File.exist?(file)
+
+      "#{intro} Follow your role file #{file} exactly. Start your work loop now.\n\n#{File.read(file)}"
+    end
+
+    # The harness guess comes first. The file that exists in the worktree wins.
+    def role_file
+      names = ROLE_FILES.keys.sort_by { |name| name == harness ? 0 : 1 }
+      paths = names.map { |name| format(ROLE_FILES[name], @env["COORD_ROLE"]) }
+      paths.find { |file| File.exist?(file) } || paths.first
+    end
+
+    def note_text
+      note = @store.note
+      return nil if note.empty?
+
+      "Handoff note from your previous session (#{File.mtime(@store.handoff).utc.iso8601}):\n#{note}"
+    end
+
+    def stop
+      path = @input["transcript_path"].to_s
+      return nil unless File.exist?(path)
+
+      record(path, read_transcript(path))
+      limit_output(@store.status["context_tokens"].to_i)
+    end
+
+    # A new transcript (after /clear) is read from its start.
+    def read_transcript(path)
+      status = @store.status
+      return Transcript.new(path, 0, {}).read unless status["transcript"] == path
+
+      Transcript.new(path, status["offset"].to_i, status["seen_total"] || {}).read
+    end
+
+    def record(path, reading)
+      @store.add_usage(reading.usage)
+      @store.save(status_fields(path, reading))
+    end
+
+    # A value that this read did not find keeps its last known value.
+    def status_fields(path, reading)
+      found = { "model" => reading.model, "context_tokens" => reading.context, "context_window" => reading.window,
+                "seen_total" => reading.total }.compact
+      { "mode" => "interactive", "role" => @env["COORD_ROLE"], "harness" => harness, "context_limit" => limit,
+        "pid" => @env["COORD_SESSION_PID"]&.to_i, "transcript" => path, "offset" => reading.offset,
+        "updated_at" => Time.now.utc.iso8601 }.merge(found)
+    end
+
+    # Codex keeps its transcripts in ~/.codex/sessions.
+    def harness = @input["transcript_path"].to_s.include?("/.codex/") ? "codex" : "claude"
+
+    def limit_output(tokens)
+      return nil if tokens < limit
+      return { systemMessage: format(TELL, tokens: tokens / 1000, limit: limit / 1000, path: @store.handoff) } if asked?
+
+      @store.save("asked" => @input["session_id"])
+      { decision: "block", reason: format(ASK, tokens: tokens, limit: limit, path: @store.handoff) }
+    end
+
+    def asked? = @store.status["asked"] == @input["session_id"]
+
+    def limit
+      value = @env["MAF_CONTEXT_LIMIT"] || manifest_limit || DEFAULT_LIMIT
+      @limit ||= Integer(value, exception: false) || DEFAULT_LIMIT
+    end
+
+    def manifest_limit
+      JSON.parse(File.read(File.join(@env.fetch("COORD_DIR"), "..", "config.json"))).dig("team", "context_limit")
+    rescue Errno::ENOENT, JSON::ParserError
+      nil
+    end
+  end
+end
+
+module ContextWatch
+  # A failed hook shows an error in each turn of the session. The watch is
+  # optional, so an error is logged and the session goes on.
+  def self.main(input, env)
+    Hook.new(input, env).run if active?(input, env)
+  rescue StandardError => e
+    warn "context-watch: #{e.class}: #{e.message}"
+    nil
+  end
+
+  # Only a registered maf start session runs the hook. The dispatcher owns dispatched agents.
+  def self.active?(input, env)
+    return false if !input.is_a?(Hash) || env["COORD_DISPATCHED"] || !env["COORD_DIR"] || !env["COORD_WORKER"]
+
+    MafSession::Guard.new(env, input).authorized?
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  input = begin
+    JSON.parse($stdin.read)
+  rescue JSON::ParserError
+    {}
+  end
+  output = ContextWatch.main(input, ENV)
+  $stdout.print(JSON.generate(output)) if output
+end

data/assets/harness-hooks/next-task-hermes.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# next-task-hermes.sh - on_session_end hook for Hermes Agent.
+# Only a registered MAF session can resume the work loop.
+require "json"
+require "rbconfig"
+require_relative "session-guard"
+
+module HermesNextTask
+  def self.run(input)
+    return unless input.is_a?(Hash)
+
+    guard = MafSession::Guard.new(ENV, input.merge("hook_event_name" => "SessionStart"))
+    resume(guard, input) if !ENV["COORD_DISPATCHED"] && guard.authorized? && work?(guard)
+  end
+
+  def self.work?(guard)
+    output = IO.popen(ENV.to_h, [RbConfig.ruby, guard.coord, "next", ENV.fetch("COORD_ROLE")],
+                      err: File::NULL, &:read)
+    output.match?(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/)
+  end
+
+  def self.resume(guard, input)
+    Process.detach(fork { start(guard, input) })
+  end
+
+  def self.start(guard, input)
+    Process.setsid
+    MafSession.register(File.dirname(File.dirname(guard.coord_dir)), "hermes")
+    exec({ "HERMES_ACCEPT_HOOKS" => "1" }, *command(input), in: File::NULL, out: File::NULL, err: File::NULL)
+  end
+
+  def self.command(input)
+    ["hermes", "chat", "--oneshot", "--yolo", "--accept-hooks", "--resume", input.fetch("session_id"), "-q", prompt]
+  end
+
+  def self.prompt
+    "Unclaimed tasks exist for role #{ENV.fetch('COORD_ROLE')}. Run coord inbox, then coord next. " \
+      "Claim and complete the next task. When no tasks remain, stop."
+  end
+end
+
+begin
+  HermesNextTask.run(JSON.parse($stdin.read))
+rescue JSON::ParserError
+  exit 0
+end

data/assets/harness-hooks/next-task.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# next-task.rb - Stop hook for Claude Code and Codex.
+#
+# Fires each time the supervised agent stops. If unclaimed tasks exist for the
+# agent's role, outputs a JSON block decision that injects a work prompt so the
+# agent continues without a human turn. Exits 0 with no output when no tasks
+# are available, letting the session end normally.
+#
+# After `coord await`, the hook first waits for work: see AwaitWork.
+#
+# Claude Code (.claude/settings.json):
+#   {"hooks":{"Stop":[{"matcher":"","hooks":[{"type":"command",
+#     "command":"ruby .maf/coordination/harness-hooks/next-task.rb"}]}]}}
+# Codex uses the project .codex/hooks.json file.
+#
+# Only a registered maf start session can read the board.
+require "json"
+require "rbconfig"
+require_relative "session-guard"
+
+UUID_LINE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/
+
+def unclaimed_tasks?(guard, role)
+  IO.popen(ENV.to_h, [RbConfig.ruby, guard.coord, "next", role], err: File::NULL, &:read).to_s.match?(UUID_LINE)
+end
+
+# AwaitWork serves `coord await`. The agent arms the hook and ends its turn.
+# The hook then waits here, outside the model, until a waking message or a
+# task arrives, or the wait ends. Codex has no watcher that wakes an idle
+# session, and a wait inside a tool call returns to the model about every
+# 30 seconds. This wait costs one model call at the end.
+# NOTE: assets/coord writes the arm file and the FYI name mark.
+class AwaitWork
+  LEADS = %w[project-manager architect].freeze
+  # Stay below the hook timeout that flow.rb sets for Codex (3600 seconds).
+  MAX_SECONDS = 3300
+  WOKE = "Work arrived for role %<role>s. Run coord inbox %<role>s. Then run coord next."
+  QUIET = "No work arrived for role %<role>s in %<minutes>d minutes. Tell the user. " \
+          "To wait again, run coord await and end your turn."
+
+  def initialize(guard, role, worker)
+    @guard, @role = guard, role
+    @path = File.join(guard.coord_dir, "locks", "await-#{worker}.json")
+  end
+
+  def armed? = File.exist?(@path)
+
+  def wait
+    started, deadline = Time.now, disarm
+    sleep tick until work? || Time.now >= deadline
+    format(work? ? WOKE : QUIET, role: @role, minutes: ((Time.now - started) / 60).round)
+  end
+
+  private
+
+  def disarm
+    limit = JSON.parse(File.read(@path)).fetch("until", 0).to_i
+    File.delete(@path)
+    Time.at([limit, Time.now.to_i + MAX_SECONDS].min)
+  rescue JSON::ParserError, SystemCallError
+    Time.now
+  end
+
+  def tick = ENV.fetch("MAF_AWAIT_TICK", "10").to_f
+  def work? = messages? || (!LEADS.include?(@role) && unclaimed_tasks?(@guard, @role))
+
+  def messages?
+    Dir.glob(File.join(@guard.coord_dir, "inbox", @role, "*.md")).any? { |path| !path.include?(".fyi.") }
+  end
+end
+
+input = begin
+  JSON.parse($stdin.read)
+rescue JSON::ParserError
+  {}
+end
+exit 0 unless input.is_a?(Hash)
+guard = MafSession::Guard.new(ENV, input)
+exit 0 unless guard.authorized?
+exit 0 if input["hook_event_name"] == "SessionStart" || ENV["COORD_DISPATCHED"]
+
+role = ENV.fetch("COORD_ROLE")
+await = AwaitWork.new(guard, role, ENV.fetch("COORD_WORKER", role))
+if await.armed?
+  $stdout.print JSON.generate(decision: "block", reason: await.wait)
+  exit 0
+end
+exit 0 unless unclaimed_tasks?(guard, role)
+
+$stdout.print JSON.generate(
+  decision: "block",
+  reason: "Unclaimed tasks exist for role #{role}. " \
+          "Run coord inbox to read messages, then coord next to list tasks. " \
+          "Claim the next task and complete it. When no tasks remain, stop."
+)