maf 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2844c9f128a0b025a9a1c933091642b9e885f069d3bfe7daff77f2fe3659c56
-  data.tar.gz: c464cfff417c58d40add531944b4ec12a93a5251510dc01d7f2d81a0a7905997
+  metadata.gz: 9d59c62e5b37a338b1da8b57db74bfb670bb735ca4fa90059d6b874a18ffd25e
+  data.tar.gz: 2c33e35cec6ad395fc539a4bc5ef3813a2e73fdcdb17464a247dbfdf1111ec0d
 SHA512:
-  metadata.gz: d906ee9673550164f3c61c195eee88a41173f80443176c5be7809a89d2da32036f8c6ad03620ca8ddadb8994a345a565602b660e0a150563d4411c6c0e896fae
-  data.tar.gz: 3fe01e2df87c0676ced712531aa44ec1935d8a5d5982d1521e765a3d846a4d9fd524485076738ba1c35927f8eb2cb00fea6db174d3fb570ada0565b19ebdeff1
+  metadata.gz: 1fe86c50be42049d5dedef7e561c6e042469d7686828bc7932931d63cece3f6fcb54e516e08c2fef48792d5fd86aa4e16932d7e5d3e7e7ae72dd1bc9f6a0f72b
+  data.tar.gz: 19f1244d7243c253c6f1852fd1376028e25c9e67d0bd249cb0e3fc44f25dd88b7b293ab466eb670d5040faec8e48c87fe00a8cb1a1cc02a81677a0eff37f9742

data/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-22
+
+- Fix: in the macOS sandbox, headless Chrome aborted at start, and macOS showed a crash dialog
+  for each try. New `.maf/sandbox.json` key `launch_services` lists the apps that can use
+  LaunchServices. After each run, the dispatcher reports apps that the run started and that
+  crashed, and LaunchServices denials, once for each app to the project manager.
+- Fix: after Ctrl+C or SIGHUP, the dispatcher stopped, but the agent run continued in its own
+  session. The dispatcher now stops the process group of the agent first.
+- New: `steward`, a daemon outside the sandbox that runs a fixed list of host operations for the
+  leads: `worker-restart`, `worker-retire`, `worktree-sync`, `goal-sync`, `runtime-restore`. An
+  agent asks with `coord op request OPERATION [ARGUMENT]`. steward checks each argument, runs no
+  shell, allows 3 runs per hour for one argument, and sends the result to the inbox of the role
+  that asked. `maf start` starts steward. The project manager and the architect prompts list the
+  operations. `maf update` installs `.maf/bin/steward`.
+- New: operations that wait for the user: `worker-start`, `worker-model WORKER MODEL`, and
+  `bundle-install` (frozen to `Gemfile.lock`). `maf op list|approve ID|deny ID` handles them.
+  `.maf/sandbox.json` key `ops` sets the level of each operation: `auto`, `approve`, or `off`.
+- After `maf untrack`, maf moves the old branches. `maf start` fast-forwards a worker branch
+  also when the only changes are in flow files that the base branch no longer tracks: maf
+  discards them first. `maf update` runs the new `coord goal migrate`, which merges the base
+  branch into each goal branch that still tracks the flow files. Before, the user did these
+  steps by hand, because the sandbox blocks an agent from deleting the flow files.
+- Fix: `maf worker stop` did nothing for a session that `maf worker list` showed as running.
+  `stop` read only the presence file, and that file can name an older session. `stop`, `start`,
+  and `status` now find the session from the records of `maf start`, as `list` does.
+- `maf worker stop` reports a session that does not stop after TERM, and prints the `kill -9`
+  command. A session in a closed terminal can ignore TERM.
+
 ## [0.4.0] - 2026-10-21
 
 - Fix: in the macOS sandbox, a worker that the project manager started failed on each run with

data/assets/coord

@@ -25,6 +25,7 @@ begin
   require_relative "../lib/maf/shared/git_exclude"
   require_relative "../lib/maf/shared/git_identity"
   require_relative "../lib/maf/shared/harness"
+  require_relative "../lib/maf/shared/flow_files"
 rescue LoadError
   abort "coord: the maf shared library is missing. Run maf update."
 end
@@ -72,6 +73,7 @@ module Coord
         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 migrate                   sync each goal branch that still tracks the flow files (after maf untrack)
         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]
@@ -97,6 +99,10 @@ module Coord
         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 op request OPERATION [ARGUMENT...]  ask steward for a host operation; the result comes to your inbox.
+                                             auto: worker-restart W, worker-retire W, worktree-sync W, goal-sync ID,
+                                             runtime-restore. The user approves: worker-start W, worker-model W MODEL,
+                                             bundle-install
         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.
@@ -134,7 +140,7 @@ module Coord
     "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
+    "who" => :cmd_who, "op" => :cmd_op, "help" => :cmd_help
   }.freeze
 
   ADD_OPTS = { "--role" => :role, "--scope" => :scope, "--ref" => :ref,
@@ -1260,8 +1266,10 @@ end
       goal
     end
 
+    def open = @tasks.pending.select { |task| task["role"] == ROLE }
+
     def list
-      goals = @tasks.pending.select { |task| task["role"] == ROLE }
+      goals = open
       return puts("no open goals") if goals.empty?
 
       goals.each { |goal| puts goal_line(goal) }
@@ -1332,7 +1340,7 @@ end
       paths = Git.changed(@dir)
       return if paths.empty?
 
-      flow = paths.all? { |path| path.start_with?(".maf/") || Worktree::RUNTIME_FILES.include?(path) }
+      flow = paths.all? { |path| Maf::Shared::FlowFiles.path?(path) || Worktree::RUNTIME_FILES.include?(path) }
       raise Error, ["uncommitted changes in #{@dir}: #{paths.first(5).join(", ")}#{" ..." if paths.size > 5}.",
                     flow ? FLOW_FILES : "Commit or stash them first."].join(" ")
     end
@@ -1496,11 +1504,13 @@ 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 untracked_upstream? = Dir.exist?(@dir) && Maf::Shared::FlowFiles.tracked?(@dir) && !flow_in_ref?
+    def flow_in_ref? = !Git.out(@root, "ls-tree", "--name-only", ref, "--", ".maf").empty?
     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)
+      raise Error, "uncommitted changes in #{@dir}. Commit or stash them first." unless clean?
 
       merge
       puts "merged #{ref} into #{@branch}"
@@ -1508,6 +1518,8 @@ end
 
     private
 
+    def clean? = Maf::Shared::FlowFiles.discard(@dir, ref) && Git.clean?(@dir)
+
     def merge
       return if Git.run(@dir, "merge", "-q", "--no-edit", ref)
 
@@ -1945,14 +1957,18 @@ end
 
     private
 
-    def checks
+    # The flow files are discarded last, only when the fast-forward can run.
+    def checks = ready_checks + [[-> { clean? }, "the worktree has uncommitted changes"]]
+
+    def ready_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 clean? = Maf::Shared::FlowFiles.discard(@dir, target) && Git.clean?(@dir)
+
     def merge
       return if rev("HEAD") == rev(target)
 
@@ -2183,6 +2199,7 @@ end
     def shift = @argv.shift
     def first = @argv.first
     def empty? = @argv.empty?
+    def rest = @argv.shift(@argv.size)
     def join = @argv.join(" ")
 
     # Splits argv at the first literal "--" and returns the words after it,
@@ -2669,11 +2686,11 @@ 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
+                      "sync" => :goal_sync, "migrate" => :goal_migrate, "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)
+      abort "usage: coord goal add|list|show|sync|migrate|pr|done" unless GOAL_COMMANDS.key?(sub)
 
       send(GOAL_COMMANDS[sub])
     end
@@ -2713,6 +2730,20 @@ end
       event_log.append("goal-sync", @worker, goal["description"])
     end
 
+    def goal_migrate = goals.open.each { |goal| migrate_goal(goal) }
+
+    def migrate_goal(goal)
+      sync = goal_sync_for(goal)
+      sync.untracked_upstream? && run_migration(sync, goal)
+    end
+
+    def run_migration(sync, goal)
+      sync.run
+      event_log.append("goal-sync", @worker, goal["description"])
+    rescue Error => e
+      warn "coord: #{e.message}"
+    end
+
     def goal_sync_for(goal) = GoalSync.new(main_root, goal["uuid"], Git.base_branch(main_root, manifest))
 
     def goal_done
@@ -2890,6 +2921,26 @@ end
     end
   end
 
+  # OpCommands writes a request for steward. steward validates and runs it on the host.
+  module OpCommands
+    OP_USAGE = "usage: coord op request OPERATION [ARGUMENT...]"
+
+    def cmd_op
+      abort OP_USAGE unless @args.shift == "request" && (op = @args.shift)
+
+      id = "#{Time.now.utc.strftime("%Y%m%dT%H%M%SZ")}-#{format("%06x", rand(0xffffff))}"
+      write_op(id, "id" => id, "op" => op, "args" => @args.rest, "role" => @role, "worker" => @worker)
+      puts "op #{id} requested. steward sends the result to the #{@role} inbox."
+    end
+
+    def write_op(id, request)
+      dir = File.join(paths.coord_dir, "ops", "requests")
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "#{id}.json"), JSON.generate(request.merge("at" => Time.now.utc.iso8601)))
+      event_log.append("op-request", @worker, [request["op"], *request["args"]].join(" "))
+    end
+  end
+
   # Upkeep commands handle locks, the event log, worktrees, and cleanup.
   module UpkeepCommands
     def cmd_lock
@@ -3029,6 +3080,7 @@ end
     include GoalCommands
     include ReviewCommands
     include UpkeepCommands
+    include OpCommands
     include CommandHelpers
     include Wiring
 

data/assets/dispatcher

@@ -137,6 +137,7 @@ require "fileutils"
 require "optparse"
 require "rbconfig"
 require "shellwords"
+require "time"
 begin
   require_relative "../lib/maf/shared/processes"
   require_relative "../lib/maf/shared/project"
@@ -690,8 +691,10 @@ module Dispatcher
 
   # Spawn runs a command in its own process group. Any end reason except a
   # normal exit kills the whole group (TERM, then KILL), which also stops the
-  # children of an `sh -c` template. A completion signal is success even when
-  # the process must be killed. An abort signal is failure.
+  # children of an `sh -c` template. An exception in the dispatcher (Ctrl+C,
+  # SIGHUP) also kills the group, so no agent run outlives the dispatcher.
+  # A completion signal is success even when the process must be killed.
+  # An abort signal is failure.
   module Spawn
     GRACE = 5
     TIMEOUTS = %i[timeout idle].freeze
@@ -724,6 +727,8 @@ module Dispatcher
       reason = watch.wait(waiter, stream)
       stop(pid, waiter) unless reason == :exit
       result(stream.close(watch.grace), waiter, watch, reason)
+    ensure
+      stop(pid, waiter) if waiter&.alive?
     end
 
     def self.result(output, waiter, watch, reason)
@@ -741,6 +746,71 @@ module Dispatcher
     end
   end
 
+  # SandboxCrashes reports, once per app, a program that a run started in the
+  # macOS sandbox and that crashed, or that the sandbox refused LaunchServices.
+  # macOS shows a crash dialog for each crash, so the user must learn the cause.
+  module SandboxCrashes
+    REPORTS = File.expand_path("~/Library/Logs/DiagnosticReports")
+    DENIAL = /Sandbox: (.+?)\(\d+\) deny\(\d+\) mach-lookup com\.apple\.coreservices\.launchservicesd/
+    PREDICATE = 'sender == "Sandbox" AND eventMessage CONTAINS "com.apple.coreservices.launchservicesd"'
+    NOTICE = "Dispatcher of %<worker>s: in the macOS sandbox, %<found>s. If the project needs the app, " \
+             "the user adds it to \"launch_services\" in .maf/sandbox.json. Then the app can start other " \
+             "apps outside the sandbox. An app with its own sandbox (Chrome) also needs it off (--no-sandbox), " \
+             "because macOS cannot start a sandbox in a sandbox. Tell the user."
+
+    @seen = []
+
+    def self.guard(harness, config, env, &block)
+      Maf::Shared::Sandbox.keeping_links(harness, coord_dir: config.coord_dir) { watch(config, env, &block) }
+    end
+
+    def self.watch(config, env, reports: REPORTS)
+      return yield unless Maf::Shared::Sandbox.mode == "seatbelt"
+
+      start = Time.now
+      yield.tap { report(config, env, crashes(start, reports), denials(start)) }
+    end
+
+    def self.report(config, env, crashes, denied)
+      crashes = crashes.except(*@seen)
+      denied -= @seen
+      return if crashes.empty? && denied.empty?
+
+      @seen.concat(crashes.keys, denied)
+      text = format(NOTICE, worker: config.worker, found: found(crashes, denied))
+      Log.line(text)
+      CoordCall.run(env, "escalate", text)
+    end
+
+    def self.found(crashes, denied)
+      parts = []
+      parts << "these apps crashed: #{crashes.map { |app, count| "#{app} (#{count}x)" }.join(", ")}" if crashes.any?
+      parts << "the sandbox refused LaunchServices to #{denied.join(", ")}" if denied.any?
+      parts.join("; ")
+    end
+
+    def self.crashes(start, reports)
+      files = Dir.glob(File.join(reports, "*.ips")).select { |path| File.mtime(path) >= start - 1 }
+      files.filter_map { |path| crashed_app(path, start) }.tally
+    end
+
+    def self.crashed_app(path, start)
+      body = JSON.parse(File.read(path).split("\n", 2).last.to_s)
+      return unless body["procPath"] && Time.parse(body["procLaunch"].to_s) >= start - 1
+
+      body["procPath"][%r{\A.*?\.app(?=/)}] || body["procPath"]
+    rescue SystemCallError, JSON::ParserError, ArgumentError
+      nil
+    end
+
+    def self.denials(start)
+      args = ["show", "--start", start.strftime("%Y-%m-%d %H:%M:%S"), "--style", "compact", "--predicate", PREDICATE]
+      IO.popen(["/usr/bin/log", *args], err: File::NULL, &:read).scan(DENIAL).flatten.uniq
+    rescue SystemCallError
+      []
+    end
+  end
+
   Events = Maf::Shared::Harness::Events
 
   # TokenUsage adds the token usage of one run to the totals of the worker in
@@ -893,9 +963,8 @@ module Dispatcher
       command = Project.manifest["verify"].to_s
       return true if command.empty? || LEADS.include?(config.role)
 
-      sandbox = Maf::Shared::Sandbox
       run = -> { Spawn.run(sandboxed(command, config), env: env, timeout: config.timeout) }
-      check(sandbox.keeping_links(Harness::Generic, coord_dir: config.coord_dir, &run), command)
+      check(SandboxCrashes.guard(Harness::Generic, config, env, &run), command)
     end
 
     def self.sandboxed(command, config)
@@ -1096,7 +1165,7 @@ module Dispatcher
     end
 
     def sandboxed(cmd) = Maf::Shared::Sandbox.wrap(cmd, @harness, coord_dir: @config.coord_dir)
-    def keeping_links(&block) = Maf::Shared::Sandbox.keeping_links(@harness, coord_dir: @config.coord_dir, &block)
+    def keeping_links(&block) = SandboxCrashes.guard(@harness, @config, @env, &block)
 
     def session_label(id) = id ? "#{id}, idle #{(@session.idle_seconds / 60).round}m" : "new"
 

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/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/cli.rb

@@ -11,6 +11,7 @@ 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"
@@ -57,6 +58,7 @@ 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)",
@@ -118,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")
 
@@ -131,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

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,
@@ -259,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

data/lib/maf/op_command.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# op_command.rb - list, approve, or deny the host operations that wait for the user.
+#
+#   maf op list | approve ID | deny ID
+require "rbconfig"
+require_relative "team"
+
+module Maf
+  # OpCommand passes the command to .maf/bin/steward. Only the user runs it:
+  # an approved operation runs on the host, outside the sandbox.
+  class OpCommand
+    USAGE = "usage: maf op list | approve ID | deny ID"
+    AGENT = "maf: only the user approves host operations. Ask the user to run this command in a terminal."
+
+    def initialize(argv, root)
+      @argv = argv
+      @root = root
+    end
+
+    def run
+      abort AGENT if Team.agent?
+      abort USAGE unless %w[list approve deny].include?(@argv.first)
+
+      exec(RbConfig.ruby, File.join(@root, ".maf", "bin", "steward"), *@argv)
+    end
+  end
+end

data/lib/maf/session_records.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# session_records.rb - the live sessions that maf start registered.
+require "json"
+require "time"
+require_relative "shared/processes"
+
+module Maf
+  # SessionRecords reads .maf/coordination/sessions/*.maf.json. The session
+  # guard writes one record for each maf start. A record is live while its pid
+  # runs and the process started before the record was written, so a reused
+  # pid does not count.
+  class SessionRecords
+    LSTART = "%a %b %d %H:%M:%S %Y %z"
+
+    def initialize(coord_dir)
+      @dir = File.join(coord_dir, "sessions")
+    end
+
+    def live = Dir.glob(File.join(@dir, "*.maf.json")).filter_map { |path| entry(path) }
+    def find(worker) = live.find { |record| record["worker"] == worker }
+
+    private
+
+    def entry(path)
+      record = JSON.parse(File.read(path))
+      started = Shared::Processes.started_at(record["pid"])
+      record.merge("started" => started) if live?(record["pid"], started, File.mtime(path))
+    rescue JSON::ParserError, SystemCallError
+      nil
+    end
+
+    def live?(pid, started, registered)
+      Shared::Processes.alive?(pid) && !started.empty? && Time.strptime("#{started} +0000", LSTART) <= registered
+    rescue ArgumentError
+      false
+    end
+  end
+end

data/lib/maf/setup_agent/steward.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module Maf
+  module SetupAgent
+    # Steward starts the steward daemon of the project. It runs before the
+    # agent variables are set, so steward does not run as an agent.
+    module Steward
+      def self.ensure(root)
+        script = File.join(root, ".maf", "bin", "steward")
+        return if ENV["STEWARD_SKIP"] || !File.exist?(script)
+
+        system(RbConfig.ruby, script, chdir: root, out: File::NULL, err: File::NULL)
+      end
+    end
+  end
+end

data/lib/maf/setup_agent.rb

@@ -81,6 +81,7 @@ module Maf
     end
 
     def self.launch(args, _worktree)
+      Steward.ensure(Project.root)
       identify(args)
       return Dispatch.launch(args) if args.dispatch
 
@@ -106,4 +107,5 @@ require_relative "setup_agent/worktree"
 require_relative "setup_agent/launcher"
 require_relative "setup_agent/project"
 require_relative "setup_agent/runtime_hooks"
+require_relative "setup_agent/steward"
 require_relative "../../assets/harness-hooks/session-guard"

data/lib/maf/shared/flow_files.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# maf shared library - code that the maf CLI and the scripts in .maf/bin share.
+# The installer copies this folder to .maf/lib/maf/shared/. maf update replaces it.
+# Use the Ruby stdlib only: a script loads this file without a gem bundle.
+require_relative "harness"
+
+module Maf
+  module Shared
+    # FlowFiles finds the files of the flow in a worktree. A branch from before
+    # maf untrack still tracks them, and maf rewrites them in each worktree.
+    module FlowFiles
+      def self.path?(path) = path.start_with?(".maf/") || Harness.all.flat_map(&:runtime_files).include?(path)
+
+      # Only a change that a merge of TARGET deletes is discarded. Returns true when no change is left.
+      def self.discard(dir, target)
+        paths = changed(dir)
+        return true if paths.empty?
+        return false unless discardable?(dir, target, paths)
+
+        system("git", "-C", dir, "checkout", "-q", "HEAD", "--", *paths)
+      end
+
+      def self.discardable?(dir, target, paths)
+        paths.all? { |path| path?(path) } && git(dir, "ls-tree", "-r", "--name-only", target, "--", *paths).empty?
+      end
+
+      def self.tracked?(dir) = !git(dir, "ls-files", "--", ".maf").empty?
+      def self.changed(dir) = git(dir, "diff", "--name-only", "HEAD")
+      def self.git(dir, *args) = IO.popen(["git", "-C", dir, *args], err: File::NULL, &:readlines).map(&:chomp)
+    end
+  end
+end

data/lib/maf/shared/sandbox/paths.rb

@@ -24,11 +24,12 @@ module Maf
 
         attr_reader :root
 
-        def initialize(harnesses, root, coord_dir, extra)
+        def initialize(harnesses, root, coord_dir, policy)
           @harness = HarnessFiles.new(harnesses, ->(paths) { real(paths) })
           @root = root
           @coord_dir = coord_dir || File.join(root, ".maf", "coordination")
-          @extra = extra.map { |path| File.expand_path(path, root) }
+          @extra = Array(policy["write"]).map { |path| File.expand_path(path, root) }
+          @app_paths = Array(policy["launch_services"]).map { |path| File.expand_path(path, root) }
         end
 
         def dirs = @dirs ||= real([@root, @coord_dir, *@extra, ENV.fetch("TMPDIR", nil), *COMMON])
@@ -45,6 +46,13 @@ module Maf
         end
 
         def existing = dirs.select { |dir| File.exist?(dir) }
+
+        def apps = @apps ||= real(@app_paths).select { |path| File.exist?(path) }.each { |path| fixed_app!(path) }
+
+        def fixed_app!(path)
+          writable?(path) && abort("maf: #{path} in launch_services is in a folder that the agent can change.")
+        end
+
         def sockets = real([@root, @coord_dir])
 
         def protected

data/lib/maf/shared/sandbox/seatbelt.rb

@@ -18,6 +18,7 @@ module Maf
         TMP_PREFIX = "maf-sandbox-"
         SERVICES = "(deny mach-lookup (global-name-regex #\"^com\\.apple\\.(coreservices|lsd)\\.\"))\n" \
                    "(deny appleevent-send)\n"
+        LAUNCH_SERVICES = "com.apple.coreservices.launchservicesd"
 
         def self.wrap(cmd, paths)
           tmp = private_tmp(paths.root)
@@ -52,7 +53,23 @@ module Maf
 
         def self.profile(paths, tmp)
           "(version 1)\n(allow default)\n(deny file-write*)\n#{writes(paths)}#{protects(paths)}" \
-            "#{sockets([*paths.sockets, tmp])}#{SERVICES}"
+            "#{sockets([*paths.sockets, tmp])}#{SERVICES}#{launch_services(paths.apps)}"
+        end
+
+        # A later rule wins, so this exception comes after the denial.
+        def self.launch_services(apps)
+          programs = apps.flat_map { |app| programs(app) }.uniq
+          return "" if programs.empty?
+
+          filters = programs.map { |path| "(process-path #{quote(path)})" }
+          "(allow mach-lookup (require-all (global-name \"#{LAUNCH_SERVICES}\")\n  " \
+            "(require-any #{filters.join("\n    ")})))\n"
+        end
+
+        def self.programs(app)
+          return [app] unless File.directory?(app)
+
+          Dir.glob(File.join(app, "**", "Contents", "MacOS", "*")).select { |path| File.file?(path) }
         end
 
         def self.writes(paths)

data/lib/maf/shared/sandbox.rb

@@ -74,7 +74,7 @@ module Maf
 
       def self.paths(harness, policy, coord_dir)
         protect_policy
-        Paths.new([harness, *project_harnesses].uniq, Project.root, coord_dir, Array(policy["write"]))
+        Paths.new([harness, *project_harnesses].uniq, Project.root, coord_dir, policy)
       end
 
       def self.project_harnesses = Project.manifest.fetch("agents", []).filter_map { |a| Harness[a["harness"]] }

data/lib/maf/uninstall/scripts.rb

@@ -9,6 +9,7 @@ module Maf
                      ".maf/bin/dashboard.html" => Bootstrap::DASHBOARD_PAGE_SIGNATURE,
                      ".maf/bin/analyst" => Bootstrap::ANALYST_SIGNATURE,
                      ".maf/bin/vault" => Bootstrap::VAULT_SIGNATURE,
+                     ".maf/bin/steward" => Bootstrap::STEWARD_SIGNATURE,
                      ".maf/bin/doc-graph-refresh" => Bootstrap::DOC_GRAPH_SIGNATURE,
                      ".maf/env.sh" => Bootstrap::ENV_SIGNATURE,
                      Bootstrap::OPENCODE_PLUGIN => Bootstrap::OPENCODE_BOARD_WATCH_SIGNATURE }.freeze

data/lib/maf/untrack.rb

@@ -2,6 +2,7 @@
 
 # untrack.rb - move an install that git tracks to the local layout.
 require "json"
+require "rbconfig"
 require_relative "uninstall"
 
 module Maf
@@ -23,8 +24,19 @@ module Maf
 
     def self.warn_tracked(root) = (warn TRACKED unless new(root, []).tracked.empty?)
 
+    def self.after_update(root)
+      warn_tracked(root)
+      migrate_goals(root)
+    end
+
+    def self.migrate_goals(root)
+      coord = File.join(root, ".maf", "bin", "coord")
+      system(RbConfig.ruby, coord, "goal", "migrate", chdir: root) if File.exist?(coord)
+    end
+
     DONE = ["", "The flow left git. Review the change with `git status`, then commit it.",
             "A branch that still tracks the flow files can delete them in a checkout or a merge.",
+            "After you push the commit, maf start fast-forwards each worker, and maf update syncs each goal.",
             "maf keeps a backup of the flow config in .git/maf/backup. Run `maf restore` to put it back."].freeze
 
     def run

data/lib/maf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Maf
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/maf/worker_control.rb

@@ -8,6 +8,7 @@ require_relative "workers"
 require_relative "retire"
 require_relative "role_limits"
 require_relative "shared/processes"
+require_relative "session_records"
 
 module Maf
   # WorkerControl stops, starts, or restarts one worker. Each action is
@@ -17,8 +18,12 @@ module Maf
   # only when the session is idle. maf then prints the start command.
   class WorkerControl
     ACTIONS = %w[status stop start restart].freeze
+    USAGE = "usage: maf worker list | #{ACTIONS.join("|")} ROLE[_WORKER] [--force] " \
+            "[--max-context N] [--max-session-runs N] [--cache-window S]".freeze
     MAF = File.expand_path("../../exe/maf", __dir__)
     IDLE = 60
+    STUCK = "maf: %<worker>s did not stop after TERM. Its terminal may be closed. " \
+            "Stop it with: pkill -9 -P %<pid>s; kill -9 %<pid>s"
 
     # force stops an interactive session also when maf cannot tell if it is idle.
     # limits are session limits of the role. start and restart save them first.
@@ -83,8 +88,12 @@ module Maf
       abort "maf: #{@worker} is in a turn. Try again when the session is idle." if busy?
       abort "maf: maf cannot tell if #{@worker} is idle. Stop it in its terminal, or add --force." if unknown?
 
+      terminate_session
+    end
+
+    def terminate_session
       RunningProcesses.terminate(pid)
-      RunningProcesses.wait_for_exit(pid, timeout: 10)
+      abort format(STUCK, worker: @worker, pid: pid) unless RunningProcesses.wait_for_exit(pid, timeout: 10)
       puts "Stopped #{@worker}. To start it again: #{start_hint}"
     end
 
@@ -95,7 +104,8 @@ module Maf
 
     def start_hint = "cd #{@entry["dir"]} && maf start"
     def coord_dir = File.join(@root, ".maf", "coordination")
-    def presence = read(File.join(coord_dir, "presence", "#{@worker}.json"))
+    def presence = @presence ||= SessionRecords.new(coord_dir).find(@worker) || presence_file
+    def presence_file = read(File.join(coord_dir, "presence", "#{@worker}.json"))
     def pid = presence["pid"].to_i
     def live? = Shared::Processes.live?(presence)
     def ours? = Shared::Processes.same?(pid, presence["started"])

data/lib/maf/worker_list.rb

@@ -5,6 +5,7 @@ require "json"
 require "time"
 require_relative "workers"
 require_relative "shared/processes"
+require_relative "session_records"
 
 module Maf
   # WorkerList shows each running worker process of the project. A worker
@@ -12,7 +13,6 @@ module Maf
   class WorkerList
     Row = Struct.new(:worker, :role, :harness, :mode, :pid, :started)
     HEADER = %w[WORKER ROLE HARNESS MODE PID STARTED].freeze
-    LSTART = "%a %b %d %H:%M:%S %Y %z"
 
     def initialize(root)
       @root = root
@@ -31,18 +31,7 @@ module Maf
     def coord_dir = File.join(@root, ".maf", "coordination")
     def records(dir, pattern) = Dir.glob(File.join(coord_dir, dir, pattern)).map { |path| [path, read(path)] }
 
-    def sessions
-      records("sessions", "*.maf.json").filter_map do |path, record|
-        row(record, "session") if session_live?(record["pid"], File.mtime(path))
-      end
-    end
-
-    def session_live?(pid, registered)
-      started = Shared::Processes.started_at(pid)
-      Shared::Processes.alive?(pid) && !started.empty? && Time.strptime("#{started} +0000", LSTART) <= registered
-    rescue ArgumentError
-      false
-    end
+    def sessions = SessionRecords.new(coord_dir).live.map { |record| row(record, "session") }
 
     def dispatchers
       records("presence", "*.json").filter_map do |_, entry|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: maf
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Dominik Alberski
@@ -53,6 +53,7 @@ files:
 - assets/harness-hooks/next-task.rb
 - assets/harness-hooks/session-guard.rb
 - assets/lima/maf.yaml.erb
+- assets/steward
 - assets/taskrc.append
 - assets/vault
 - assets/worktree-env.example.rb
@@ -115,10 +116,12 @@ files:
 - lib/maf/migrate/role_files.rb
 - lib/maf/migrate/runner.rb
 - lib/maf/migrate/worktrees.rb
+- lib/maf/op_command.rb
 - lib/maf/prompt.rb
 - lib/maf/restore.rb
 - lib/maf/retire.rb
 - lib/maf/role_limits.rb
+- lib/maf/session_records.rb
 - lib/maf/setup_agent.rb
 - lib/maf/setup_agent/args.rb
 - lib/maf/setup_agent/dispatch.rb
@@ -128,7 +131,9 @@ files:
 - lib/maf/setup_agent/pty_relay.rb
 - lib/maf/setup_agent/role_file.rb
 - lib/maf/setup_agent/runtime_hooks.rb
+- lib/maf/setup_agent/steward.rb
 - lib/maf/setup_agent/worktree.rb
+- lib/maf/shared/flow_files.rb
 - lib/maf/shared/git_exclude.rb
 - lib/maf/shared/git_identity.rb
 - lib/maf/shared/harness.rb