maf 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d92abf8bbcca7ba5044ac6185534e883a55a1387e05460ac4142e1d89f3d13e
-  data.tar.gz: 25eaa46e4ed438fef70a08841137fc87c7ede35dfe9c09ff4d053a351e11e9ef
+  metadata.gz: 9d59c62e5b37a338b1da8b57db74bfb670bb735ca4fa90059d6b874a18ffd25e
+  data.tar.gz: 2c33e35cec6ad395fc539a4bc5ef3813a2e73fdcdb17464a247dbfdf1111ec0d
 SHA512:
-  metadata.gz: 96324cff6b379cb0ec71cbe0d8a15d127a950ddfb7e3997012f4f9b6c4759508a34668fc06a7702d04030ebf65875335c05a6a5836f7959422cbaf107d6abe92
-  data.tar.gz: 9faa6836a004d143d9bcdfc7852d4479b2f9b43f40d09efcab44c32343607b9bcf73949c7e62235b772f817d37845e0e2a5955deefab1c576477a962798e8aa2
+  metadata.gz: 1fe86c50be42049d5dedef7e561c6e042469d7686828bc7932931d63cece3f6fcb54e516e08c2fef48792d5fd86aa4e16932d7e5d3e7e7ae72dd1bc9f6a0f72b
+  data.tar.gz: 19f1244d7243c253c6f1852fd1376028e25c9e67d0bd249cb0e3fc44f25dd88b7b293ab466eb670d5040faec8e48c87fe00a8cb1a1cc02a81677a0eff37f9742

data/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## [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
+  `sandbox_apply: Operation not permitted`. macOS cannot start a sandbox inside a sandbox. The
+  sandbox now sets `MAF_SEATBELT=1`. In the sandbox, `maf prepare --dispatch` prepares the worker
+  and prints the start commands, and a dispatcher stops at once with the reason in its log.
+- The project manager no longer adds workers on its own. Without a team budget, `maf prepare`
+  refuses when an agent runs it. Only the user sets the budget: `maf team set` refuses when an
+  agent runs it.
+- Backup of the flow config. Each maf command copies `.maf/config.json`, `roles.yml`,
+  `workflow.md`, and `sandbox.json` to `.git/maf/backup/` when they changed, and keeps 10
+  copies. New command `maf restore [--list] [BACKUP] [--force]` puts them back and runs
+  `maf update`. When `.maf/` exists without `config.json`, maf names the backup. Before, a
+  merge of the `maf untrack` commit into a branch that still tracked the flow deleted the
+  config, and the agents, `base_branch`, and `github` settings were lost.
+
 ## [0.3.0] - 2026-10-21
 
 - Fix: each dispatched Hermes run failed. Hermes 0.22 refuses `--run-budget` with `--format

data/README.md

@@ -192,6 +192,8 @@ multi_agent_flow/
     flow/workflow.rb          # reads .maf/workflow.md for the architect prompt
     flow/mcp_config.rb        # writes the graphify MCP server into .maf/mcp/
     untrack.rb                # maf untrack: removes an older install from git
+    backup.rb                 # copies of the flow config in .git/maf/backup
+    restore.rb                # maf restore: puts the flow config back from a backup
     local_exclude.rb          # the flow block in .git/info/exclude
     shared/                   # stdlib-only code that the maf CLI and the scripts share (installed as .maf/lib/maf/shared/)
     shared/harness/           # the harness registry, the default of each harness method, shared modules
@@ -234,6 +236,7 @@ multi_agent_flow/
     worker_control_test.rb    # tests for maf worker
     worker_list_test.rb       # tests for maf worker list
     untrack_test.rb           # tests for maf untrack
+    backup_test.rb            # tests for the backup and maf restore
     analyst_test.rb           # tests for the analyst
     shared_test.rb            # tests for lib/maf/shared/
     gemspec_test.rb           # tests that the gem holds every runtime file
@@ -371,6 +374,7 @@ ruby test/context_watch_test.rb      # covers the context-watch hook
 ruby test/worker_control_test.rb     # covers maf worker
 ruby test/worker_list_test.rb        # covers maf worker list
 ruby test/untrack_test.rb            # covers maf untrack
+ruby test/backup_test.rb             # covers the backup and maf restore
 ruby test/analyst_test.rb            # covers the analyst
 ruby test/shared_test.rb             # covers lib/maf/shared/
 ```

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"
@@ -175,6 +176,13 @@ module Dispatcher
     end
   end
 
+  def self.refuse_nested
+    return unless Maf::Shared::Sandbox.nested?
+
+    Log.line(Maf::Shared::Sandbox::NESTED.delete_prefix("maf: "))
+    exit 1
+  end
+
   # Project finds the main checkout from any worktree. Lead roles own no
   # tasks: they get an inbox prompt and no task polling.
   Project = Maf::Shared::Project
@@ -683,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
@@ -717,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)
@@ -734,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
@@ -886,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)
@@ -1089,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"
 
@@ -1512,5 +1588,6 @@ if __FILE__ == $PROGRAM_NAME
   ENV["PATH"] = [File.dirname(File.expand_path(__FILE__)), ENV["PATH"]].compact.join(File::PATH_SEPARATOR)
   # Each run inherits the git persona of the agents.
   Maf::Shared::GitIdentity.apply(Dispatcher::Project.manifest)
+  Dispatcher.refuse_nested
   Dispatcher::Main.new(Dispatcher::Options.parse(ARGV)).run
 end