maf 0.3.0 → 0.5.0

data/assets/steward

@@ -0,0 +1,398 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# steward - run the host operations that the leads request.
+#
+# Usage: steward [start|stop|status|daemon]
+#   steward          # start the daemon; no-op if it already runs
+#   steward stop
+#   steward status
+#
+# An agent runs `coord op request OPERATION [ARGUMENT]`. coord writes the
+# request to .maf/coordination/ops/requests/. The daemon runs only the
+# operations in Steward::Ops::TABLE, outside the sandbox, and sends the
+# result to the inbox of the role that asked.
+require "json"
+require "fileutils"
+require "rbconfig"
+require "time"
+begin
+  require_relative "../lib/maf/shared/project"
+  require_relative "../lib/maf/shared/processes"
+  require_relative "../lib/maf/shared/sandbox"
+rescue LoadError
+  abort "steward: the maf shared library is missing. Run maf update."
+end
+
+# Steward runs the operations of Steward::Ops::TABLE for the leads.
+module Steward
+  COORD_DIR = File.join(".maf", "coordination")
+  OPS_DIR = File.join(COORD_DIR, "ops")
+  PID_FILE = File.join(COORD_DIR, "steward.pid")
+  LOG_FILE = File.join(COORD_DIR, "steward.log")
+  POLL = 3
+
+  COMMANDS = { "stop" => :stop, "status" => :status, "daemon" => :loop_forever }.freeze
+
+  def self.run(argv)
+    Dir.chdir(Maf::Shared::Project.root)
+    return Approvals.run(argv) if Approvals::COMMANDS.include?(argv.first)
+
+    Daemon.public_send(COMMANDS.fetch(argv.first, :start))
+  end
+
+  def self.coord = [RbConfig.ruby, File.join(".maf", "bin", "coord")]
+
+  # Daemon starts, stops, and runs the poll loop. It exits when the pid file is gone.
+  module Daemon
+    NESTED = "steward: this process runs in the sandbox. Start steward from a terminal."
+    LOG = { out: LOG_FILE, err: LOG_FILE, pgroup: true }.freeze
+
+    def self.start
+      abort NESTED if inside_sandbox?
+      return puts("steward: already running (pid #{Pid.read})") if Pid.running?
+
+      spawn_daemon
+    end
+
+    def self.inside_sandbox? = Maf::Shared::Sandbox::Seatbelt.inside? || ENV["MAF_BWRAP"] == "1"
+
+    def self.spawn_daemon
+      FileUtils.mkdir_p(COORD_DIR)
+      pid = Process.spawn(RbConfig.ruby, File.expand_path(__FILE__), "daemon", **LOG)
+      Process.detach(pid) && Pid.write(pid)
+      puts "steward: started (pid #{pid}), log at #{LOG_FILE}"
+    end
+
+    def self.stop
+      return puts("steward: not running") unless Pid.running?
+
+      Process.kill("TERM", Pid.read)
+      Pid.clear
+      puts "steward: stopped"
+    end
+
+    def self.status = puts(Pid.running? ? "steward: running (pid #{Pid.read})" : "steward: not running")
+
+    def self.loop_forever
+      Pid.write(Process.pid)
+      Signal.trap("TERM") { exit }
+      tick while File.exist?(PID_FILE)
+    end
+
+    def self.tick
+      Queue.new(OPS_DIR).each_request { |request| Handler.new(request).run }
+      sleep POLL
+    end
+  end
+
+  # Pid reads and writes the pid file. A non-positive pid is not a process.
+  module Pid
+    def self.running? = read.positive? && Maf::Shared::Processes.alive?(read)
+    def self.read = File.exist?(PID_FILE) ? File.read(PID_FILE).to_i : 0
+    def self.write(pid) = File.write(PID_FILE, pid)
+    def self.clear = FileUtils.rm_f(PID_FILE)
+  end
+
+  # Queue moves each request file to done/ before the handler runs it, so a
+  # restart of the daemon never runs a request twice.
+  class Queue
+    def initialize(dir)
+      @dir = dir
+    end
+
+    def each_request
+      Dir.glob(File.join(@dir, "requests", "*.json")).each do |path|
+        request = take(path)
+        yield request if request
+      end
+    end
+
+    private
+
+    def take(path)
+      done = done_path(path)
+      File.rename(path, done)
+      JSON.parse(File.read(done)).merge("path" => done)
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    def done_path(path)
+      File.join(@dir, "done", File.basename(path)).tap { |done| FileUtils.mkdir_p(File.dirname(done)) }
+    end
+  end
+
+  # Ops holds the fixed list of operations. Each one maps validated
+  # arguments to an argument list. No request text reaches a shell.
+  module Ops
+    TABLE = {
+      "worker-restart" => { args: %i[worker], level: "auto", argv: ->(w) { ["maf", "worker", "restart", w["id"]] } },
+      "worker-retire" => { args: %i[worker], level: "auto", argv: ->(w) { ["maf", "retire", w["id"]] } },
+      "worktree-sync" => { args: %i[worker], level: "auto",
+                           argv: ->(w) { [*Steward.coord, "worktree", w["role"], w["worker_id"]] } },
+      "goal-sync" => { args: %i[goal], level: "auto", argv: ->(g) { [*Steward.coord, "goal", "sync", g] } },
+      "runtime-restore" => { args: [], level: "auto", argv: -> { %w[maf update] } },
+      "worker-start" => { args: %i[worker], level: "approve", argv: ->(w) { ["maf", "worker", "start", w["id"]] } },
+      "worker-model" => { args: %i[worker model], level: "approve", argv: ->(w, m) { Ops.replace(w, m) } },
+      "bundle-install" => { args: [], level: "approve",
+                            argv: -> { Validate.lockfile && [{ "BUNDLE_FROZEN" => "true" }, "bundle", "install"] } }
+    }.freeze
+
+    def self.spec(name) = TABLE.fetch(name) { raise Refused, "unknown operation #{name}. Known: #{known}" }
+    def self.known = TABLE.keys.join(" ")
+    def self.level(name) = Levels.read.fetch(name, spec(name)[:level])
+
+    def self.argv(name, args)
+      kinds = spec(name)[:args]
+      raise Refused, "#{name} takes #{kinds.size} argument(s): #{kinds.join(" ")}" unless args.size == kinds.size
+
+      spec(name)[:argv].call(*kinds.zip(args).map { |kind, arg| Validate.public_send(kind, arg) })
+    end
+
+    def self.replace(worker, model)
+      id = "#{worker["role"]}_#{worker["worker_id"]}"
+      ["maf", "prepare", worker["harness"], id, "--model", model, "--replace", id,
+       worker["dispatch"] ? "--dispatch" : "--interactive"]
+    end
+  end
+
+  # Levels reads the key ops of .maf/sandbox.json. The sandbox protects that file.
+  module Levels
+    VALUES = %w[auto approve off].freeze
+
+    def self.read
+      data = JSON.parse(File.read(File.join(".maf", "sandbox.json"))).fetch("ops", {})
+      data.is_a?(Hash) ? data.select { |_, level| VALUES.include?(level) } : {}
+    rescue JSON::ParserError, SystemCallError, TypeError, NoMethodError
+      {}
+    end
+  end
+
+  class Refused < StandardError; end
+
+  # Validate checks each argument against the project state, not against the request.
+  module Validate
+    WORKTREES = File.join(".maf", "worktrees")
+
+    def self.model(arg)
+      return arg if arg.to_s.match?(%r{\A[A-Za-z0-9][A-Za-z0-9._:/@-]{0,99}\z})
+
+      raise Refused, "a model is letters, digits, and . _ : / @ -"
+    end
+
+    def self.lockfile = File.exist?("Gemfile.lock") || raise(Refused, "the project has no Gemfile.lock")
+
+    def self.worker(arg)
+      entry = workers.fetch(arg.to_s) { raise Refused, "no worker #{arg}" }
+      raise Refused, "worker #{arg} is outside #{WORKTREES}" unless inside_worktrees?(entry["dir"].to_s)
+
+      entry.merge("id" => arg.to_s)
+    end
+
+    def self.goal(arg)
+      raise Refused, "a goal id is 8 hex characters" unless arg.to_s.match?(/\A\h{8}\z/)
+      raise Refused, "no goal branch goal/#{arg}" unless system("git", "rev-parse", "-q", "--verify",
+                                                                "refs/heads/goal/#{arg}", out: File::NULL)
+
+      arg
+    end
+
+    def self.workers
+      JSON.parse(File.read(File.join(COORD_DIR, "workers.json")))
+    rescue JSON::ParserError, SystemCallError
+      {}
+    end
+
+    def self.inside_worktrees?(dir)
+      root = File.realpath(WORKTREES)
+      File.realpath(dir).start_with?("#{root}/")
+    rescue SystemCallError
+      false
+    end
+  end
+
+  # Limit allows each operation 3 runs per hour for one argument. A loop of
+  # restarts then stops, and the project manager hears about it.
+  class Limit
+    MAX = 3
+    WINDOW = 3600
+
+    def initialize(path) = @path = path
+
+    def allow?(key) = recent.count(key) < MAX
+    def record(key) = File.open(@path, "a") { |file| file.puts(JSON.generate("at" => Time.now.to_i, "key" => key)) }
+
+    private
+
+    def recent
+      return [] unless File.exist?(@path)
+
+      File.readlines(@path).filter_map { |line| entry(line) }
+    end
+
+    def entry(line)
+      data = JSON.parse(line)
+      data["key"] if Time.now.to_i - data["at"].to_i < WINDOW
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  # Handler runs one request and reports the result to the role that asked.
+  class Handler
+    TIMEOUT = 2000
+
+    def initialize(request, runner: Runner, limit: Limit.new(File.join(OPS_DIR, "history.jsonl")), approved: false)
+      @request = request
+      @runner = runner
+      @limit = limit
+      @approved = approved
+    end
+
+    def run
+      route(Ops.argv(name, args), Ops.level(name))
+    rescue Refused => e
+      report(false, "refused: #{e.message}")
+    end
+
+    def route(argv, level)
+      raise Refused, "#{name} is off in .maf/sandbox.json" if level == "off"
+      return park if level == "approve" && !@approved
+
+      execute(argv)
+    end
+
+    def execute(argv)
+      return over_limit unless @limit.allow?(key)
+
+      @limit.record(key)
+      report(*@runner.call(argv, TIMEOUT))
+    end
+
+    private
+
+    def name = @request["op"].to_s
+    def args = Array(@request["args"]).map(&:to_s)
+    def key = [name, *args].join(" ")
+
+    def park
+      File.rename(@request["path"], Approvals.pending_path(@request["id"]))
+      text = "op #{@request["id"]} #{key}: waits for the user. The user runs: maf op approve #{@request["id"]}"
+      Reply.event(text)
+      [@request["role"].to_s, "project-manager"].uniq.each { |role| Reply.deliver(role, text) }
+    end
+
+    def over_limit
+      report(false, "refused: #{key} ran #{Limit::MAX} times in the last hour")
+      Reply.deliver("project-manager", "ESCALATION from steward: #{key} ran #{Limit::MAX} times in an hour. " \
+                                       "Check the cause before a new request.")
+    end
+
+    def report(success, output)
+      text = "op #{@request["id"]} #{key}: #{success ? "done" : "failed"}. #{output.to_s.lines.last(5).join.strip}"
+      File.write(@request["path"], JSON.generate(@request.merge("ok" => success, "output" => output.to_s)))
+      Reply.event(text)
+      Reply.deliver(@request["role"].to_s, text)
+    end
+  end
+
+  # Approvals lists, approves, and denies the waiting requests. The user runs
+  # them through maf op, outside the sandbox.
+  module Approvals
+    COMMANDS = %w[list approve deny].freeze
+    ID = /\A\d{8}T\d{6}Z-\h{6}\z/
+    REFUSED = "steward: only the user approves, from a terminal outside the sandbox."
+
+    def self.run(argv)
+      abort REFUSED if Daemon.inside_sandbox? || !ENV["COORD_ROLE"].to_s.empty?
+      argv.first == "list" ? list : public_send(argv.first, argv[1].to_s)
+    rescue Refused => e
+      abort "steward: #{e.message}"
+    end
+
+    def self.list
+      files = Dir.glob(File.join(OPS_DIR, "pending", "*.json"))
+      puts "No request waits." if files.empty?
+      files.each { |path| puts line(JSON.parse(File.read(path))) }
+    end
+
+    def self.line(req) = [req["id"], [req["op"], *req["args"]].join(" "), "from #{req["worker"]}"].join("  ")
+
+    def self.approve(id)
+      done = File.join(OPS_DIR, "done", "#{id}.json")
+      File.rename(waiting(id), done)
+      Handler.new(JSON.parse(File.read(done)).merge("path" => done), approved: true).run
+      puts File.read(done)
+    end
+
+    def self.deny(id)
+      request = JSON.parse(File.read(waiting(id)))
+      File.delete(waiting(id))
+      notify(request, "op #{id} #{[request["op"], *request["args"]].join(" ")}: denied by the user.")
+    end
+
+    def self.notify(request, text)
+      Reply.event(text)
+      Reply.deliver(request["role"].to_s, text)
+      puts text
+    end
+
+    def self.waiting(id) = pending_path(id).tap { |path| File.exist?(path) || raise(Refused, "no request #{id}") }
+
+    def self.pending_path(id)
+      raise Refused, "a request id looks like 20261021T120000Z-a1b2c3" unless id.to_s.match?(ID)
+
+      File.join(OPS_DIR, "pending", "#{id}.json").tap { |path| FileUtils.mkdir_p(File.dirname(path)) }
+    end
+  end
+
+  # Runner runs an argument list without a shell and stops it at the timeout.
+  module Runner
+    def self.call(argv, timeout)
+      reader, writer = IO.pipe
+      pid = start(argv, writer)
+      writer.close
+      pid ? collect(pid, reader, timeout) : [false, "cannot start #{argv.first}"]
+    end
+
+    def self.start(argv, writer)
+      Process.spawn(*argv, out: writer, err: writer, pgroup: true)
+    rescue SystemCallError
+      nil
+    end
+
+    def self.collect(pid, reader, timeout)
+      output = Thread.new { reader.read }
+      [succeeded?(pid, timeout), output.value]
+    end
+
+    def self.succeeded?(pid, timeout)
+      deadline = Time.now + timeout
+      sleep 0.2 until (status = Process.waitpid2(pid, Process::WNOHANG)&.last) || Time.now > deadline
+      kill(pid) unless status
+      status&.success? || false
+    end
+
+    def self.kill(pid)
+      Process.kill("KILL", -pid)
+      Process.wait(pid)
+    end
+  end
+
+  # Reply writes the event log line and the inbox message.
+  module Reply
+    def self.event(text)
+      line = [Time.now.utc.iso8601, "op", "steward", text.tr("\t\n", "  ")].join("\t")
+      File.open(File.join(COORD_DIR, "events.log"), "a") { |file| file.puts(line) }
+    end
+
+    def self.deliver(role, text)
+      return if role.empty?
+
+      system(*Steward.coord, "msg", "--from", "steward", role, text, out: File::NULL, err: File::NULL)
+    end
+  end
+end
+
+Steward.run(ARGV) if __FILE__ == $PROGRAM_NAME

data/lib/maf/backup.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# backup.rb - copies of the flow config in the git directory, and maf restore.
+require "fileutils"
+require "open3"
+require "time"
+
+module Maf
+  # Backup keeps copies of the files in .maf/ that maf update cannot make again.
+  # Each copy is a folder in .git/maf/backup/, so no checkout, merge, or reset
+  # changes it. A copy is made only when config.json exists and the files differ
+  # from the newest copy.
+  class Backup
+    FILES = %w[config.json roles.yml workflow.md sandbox.json].freeze
+    KEEP = 10
+    MISSING = "maf: .maf/config.json is missing. A backup from %<time>s has it. Run: maf restore"
+
+    def initialize(root)
+      @root = root
+      @dir = git_dir&.then { |dir| File.join(dir, "maf", "backup") }
+    end
+
+    def save
+      files = current
+      return if @dir.nil? || !files.key?("config.json") || files == read(latest)
+
+      write(File.join(@dir, Time.now.utc.strftime("%Y%m%dT%H%M%SZ")), files)
+      prune
+    end
+
+    def snapshots = @dir ? Dir.glob(File.join(@dir, "*")).select { |path| File.directory?(path) }.sort : []
+    def latest = snapshots.last
+    def find(name) = snapshots.find { |path| File.basename(path) == name }
+    def read(dir) = dir ? FILES.to_h { |name| [name, file(dir, name)] }.compact : {}
+    def time(dir) = Time.strptime(File.basename(dir), "%Y%m%dT%H%M%S%z").localtime.strftime("%Y-%m-%d %H:%M")
+
+    def warn_missing
+      maf = File.join(@root, ".maf")
+      return if !Dir.exist?(maf) || File.exist?(File.join(maf, "config.json")) || !read(latest).key?("config.json")
+
+      warn format(MISSING, time: time(latest))
+    end
+
+    private
+
+    def current = read(File.join(@root, ".maf"))
+    def file(dir, name) = File.file?(File.join(dir, name)) ? File.read(File.join(dir, name)) : nil
+
+    def write(dir, files)
+      FileUtils.mkdir_p(dir)
+      files.each { |name, text| File.write(File.join(dir, name), text) }
+    end
+
+    def prune = snapshots[0...-KEEP].each { |dir| FileUtils.rm_rf(dir) }
+
+    def git_dir
+      out, status = Open3.capture2("git", "-C", @root, "rev-parse", "--git-common-dir", err: File::NULL)
+      status.success? ? File.expand_path(out.strip, @root) : nil
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end

data/lib/maf/bootstrap/installer.rb

@@ -8,8 +8,8 @@ module Maf
       # Each step is [planner, method]. The order is the order of the output.
       PLAN_STEPS = [
         %i[layout dirs], %i[scripts shared], %i[scripts coord], %i[scripts dispatcher], %i[scripts vault],
-        %i[scripts dashboard], %i[scripts analyst], %i[scripts env], %i[text taskrc], %i[text exclude],
-        %i[scripts hooks], %i[scripts opencode_plugin], %i[claude plan], %i[git commit_guard],
+        %i[scripts steward], %i[scripts dashboard], %i[scripts analyst], %i[scripts env], %i[text taskrc],
+        %i[text exclude], %i[scripts hooks], %i[scripts opencode_plugin], %i[claude plan], %i[git commit_guard],
         %i[scripts doc_graph], %i[git doc_graph_hooks]
       ].freeze
       PLANNERS = { layout: LayoutPlanner, scripts: ScriptPlanner, text: TextPlanner, claude: ClaudeSettings,

data/lib/maf/bootstrap/script_planner.rb

@@ -46,6 +46,10 @@ module Maf
         script("vault", VAULT_SIGNATURE)
       end
 
+      def steward
+        script("steward", STEWARD_SIGNATURE)
+      end
+
       # env.sh puts .maf/bin on PATH. A worker runs `source .maf/env.sh`.
       def env
         script("env.sh", ENV_SIGNATURE, @project.path(MAF_DIR, "env.sh"))

data/lib/maf/bootstrap.rb

@@ -29,6 +29,7 @@ module Maf
     SETUP_AGENT_SIGNATURE = "setup_agent - create a worktree for one agent and launch its harness session."
     DISPATCHER_SIGNATURE = "dispatcher - task board and inbox monitor that starts one-shot agents."
     VAULT_SIGNATURE = "vault - shared knowledge base watcher (graphify + Obsidian + MCP)."
+    STEWARD_SIGNATURE = "steward - run the host operations that the leads request."
     DASHBOARD_SIGNATURE = "dashboard - local observability web UI for multi-agent coordination."
     DASHBOARD_PAGE_SIGNATURE = "dashboard.html - page of the maf dashboard."
     ANALYST_SIGNATURE = "analyst - ask a small model for token hints about one dispatched worker."

data/lib/maf/budget.rb

@@ -44,6 +44,8 @@ module Maf
         if @max && count > @max
     end
 
+    def limited? = !@max.nil?
+
     def allowed?(harness, model)
       @allow.empty? || @allow.any? { |spec| [harness, "#{harness}:#{model}"].include?(spec) }
     end

data/lib/maf/cli.rb

@@ -11,9 +11,11 @@ require_relative "setup_agent"
 require_relative "menu"
 require_relative "team"
 require_relative "team_command"
+require_relative "op_command"
 require_relative "worker_control"
 require_relative "worker_list"
 require_relative "untrack"
+require_relative "restore"
 require_relative "vm"
 require_relative "version"
 
@@ -56,9 +58,11 @@ module Maf
                   "[--max-session-runs N] [--cache-window S]  list the running workers, or control one worker; " \
                   "start and restart save the session limits of the role",
       "team" => "[set --max N --allow HARNESS[:MODEL]]   show the team, or set its budget",
+      "op" => "list | approve ID | deny ID              the host operations that wait for you (steward)",
       "uninstall" => "[--check] [--yes] [--force]             remove the flow from the project",
       "migrate" => "[--check] [--yes]                       move an old-layout install into .maf/",
       "untrack" => "[--check] [--yes]                       remove the flow from git; the files stay (then commit)",
+      "restore" => "[--list] [BACKUP] [--force]             put the flow config back from a backup in .git/maf/backup",
       "vm" => "create|login|start|stop|delete|status|shell [ARGS]  run the team in a Lima VM (macOS, Linux)",
       "menu" => "                                        interactive mode (also: maf without a command)",
       "guide" => "                                        print the setup guide for an AI agent (install.md)",
@@ -76,11 +80,26 @@ module Maf
       abort "maf: unknown command '#{@command}'. Run: maf help" unless COMMANDS.key?(@command)
       abort "maf: #{Migrate::HINT}" if old_layout?
 
-      send("run_#{@command}")
+      backed_up { send("run_#{@command}") }
     end
 
+    NO_BACKUP = %w[version guide roles].freeze
+
     private
 
+    def backed_up
+      backup = checked_backup unless NO_BACKUP.include?(@command)
+      yield
+    ensure
+      backup&.save
+    end
+
+    def checked_backup
+      backup = Backup.new(SetupAgent::Project.root)
+      backup.warn_missing unless @command == "restore"
+      backup.tap(&:save)
+    end
+
     # Every command except these needs the new layout.
     # maf uninstall --check previews the migration on an old layout.
     def old_layout?
@@ -101,7 +120,7 @@ module Maf
     def run_remove = Maf.flow(*AgentArgs.convert(@args, "--remove"))
     def run_update
       Maf.flow(*@args)
-      Untrack.warn_tracked(SetupAgent::Project.root)
+      Untrack.after_update(SetupAgent::Project.root)
     end
     def run_roles = Maf.flow("--list-roles")
 
@@ -114,17 +133,16 @@ module Maf
     def run_start = @args.empty? ? SetupAgent.run_here : SetupAgent.run(@args)
     def run_prepare = Prepare.new(@args).run
     def run_team = TeamCommand.new(@args, SetupAgent::Project.root).run
+    def run_op = OpCommand.new(@args, SetupAgent::Project.root).run
     def run_worker
       return WorkerList.new(SetupAgent::Project.root).run if @args.first == "list"
 
-      spec = @args[1] || abort(worker_usage)
+      spec = @args[1] || abort(WorkerControl::USAGE)
       limits = RoleLimits.parse(@args)
       WorkerControl.new(SetupAgent::Project.root, spec, force: @args.include?("--force"), limits: limits)
         .run(@args[0].to_s)
     end
 
-    def worker_usage = "usage: maf worker list | #{WorkerControl::ACTIONS.join("|")} ROLE[_WORKER] [--force] " \
-                       "[--max-context N] [--max-session-runs N] [--cache-window S]"
     def run_retire = Retire.new(SetupAgent::Project.root, @args.first || abort("usage: maf retire ROLE[_WORKER]")).run
     def run_uninstall = Uninstall::Runner.new(["--project", Dir.pwd, *@args]).run
     def run_menu = Menu.new.run
@@ -132,6 +150,7 @@ module Maf
     def run_guide = puts(File.read(File.join(Flow::ROOT, "install.md")))
     def run_version = puts("maf #{VERSION}")
     def run_untrack = Untrack.new(SetupAgent::Project.root, @args).run
+    def run_restore = Restore.new(SetupAgent::Project.root, @args).run
     def run_migrate = Migrate::Runner.new(["--project", Dir.pwd, *@args]).run
 
     def run_agents

data/lib/maf/flow/prompt_text.rb

@@ -149,6 +149,18 @@ module Maf
          A goal pull request uses a merge commit, never a squash.
     TEXT
 
+    HOST_OPS_RULE = <<~TEXT.strip
+      - The sandbox blocks some repairs. Request them from steward: `coord op request <operation> [<argument>]`.
+        `worker-restart <worker>`, `worker-retire <worker>`: a worker that is stuck or not seen.
+        `worktree-sync <worker>`: a worker branch behind the base branch, or flow files that block it.
+        `goal-sync <goal-short-id>`: `coord goal sync` fails with "Operation not permitted".
+        `runtime-restore`: the files of `.maf/` are missing in a worktree.
+        These wait for the user: `worker-start <worker>`, `worker-model <worker> <model>`,
+        `bundle-install` (gems are missing after a Gemfile.lock change).
+        steward sends the result to your inbox. Tell the user only if steward refuses or the operation fails.
+        If an operation waits, tell the user the `maf op approve <id>` command once. Do not request it again.
+    TEXT
+
     ARCHITECT_RULES = <<~TEXT.strip
       - Never edit files directly. Dispatch work.
       - Change a goal branch only with `coord land` and `coord goal sync`. Never run `git merge` or `git commit` on it.
@@ -164,6 +176,7 @@ module Maf
       - Before you revise an artifact that a reviewer read, copy it to `<name>.r<round>.md`. Name both files
         in the review task. The reviewer reads `diff -u` of the two files and checks the open findings only.
       #{GRAPH_RULE}
+      #{HOST_OPS_RULE}
     TEXT
 
     # The architect takes goals from the project manager when that role exists,
@@ -212,13 +225,16 @@ module Maf
     # run the team. Dispatched workers cost no tokens while idle, so the rules
     # scale on backlog, not on cost.
     TEAM_RULES = <<~TEXT.strip
-      - If the user gives you a team budget, record it: `maf team set --max <n> --allow <harness[:model]> ...`.
-        Then manage the team yourself in dispatch mode. `maf prepare ... --dispatch` starts the worker in the background.
+      - Only the user sets the team budget: `maf team set --max <n> --allow <harness[:model]> ...`.
+        If the user gives you a budget in words, give the user that command.
+        With a budget, manage the team yourself in dispatch mode. `maf prepare ... --dispatch` starts the worker in the background.
+        In the macOS sandbox, maf cannot start it. Give the user the two commands that it prints.
       - Check the team with `maf team`. It shows the budget, each worker, and the tasks by role.
       - Staff the architect first, with `--dispatch`. A goal needs the architect before any other worker.
         A dispatched architect starts on each message. An idle interactive architect reads nothing.
       - Check who runs with `coord who`. A role without a live worker does not read its messages.
-      - If coord reports "No worker runs role <role>", add a worker for that role.
+      - If coord reports "No worker runs role <role>", add a worker for that role if the budget has a free slot.
+        Without a budget, tell the user.
       - If a role has more than three backlog tasks and the budget has a free slot, add a worker for that role.
       - If a role has no tasks and no open goal needs it, retire its extra workers.
         Keep one worker per role that an open goal needs.
@@ -242,7 +258,8 @@ module Maf
 
       Rules:
       - Never edit source files. Never create tasks; only the architect creates tasks.
-      - Change the team when the user asks. Do not ask the user to run setup steps.
+      - Change the team only when the user asks, or within the team budget. Without a budget, `maf prepare` refuses.
+        Then give the user the command, or ask the user for a budget.
         Add a worker: `maf prepare <harness> <role>_<n>`.
         Replace a worker: `maf prepare <harness> <role>_<n> --replace <old-role>_<n>`.
         Remove a worker: `maf retire <role>_<n>`.
@@ -255,6 +272,7 @@ module Maf
       - Do not read the project docs in full. Each file that you read stays in your context for the whole session.
         Ask the architect, or start one subagent that returns a summary of at most 300 words.
       - If no report has arrived yet, tell the user and check again with `coord inbox project-manager`.
+      #{HOST_OPS_RULE}
       #{STE_RULE}
       #{SUBAGENT_RULE}
     LOOP