maf 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d92abf8bbcca7ba5044ac6185534e883a55a1387e05460ac4142e1d89f3d13e
-  data.tar.gz: 25eaa46e4ed438fef70a08841137fc87c7ede35dfe9c09ff4d053a351e11e9ef
+  metadata.gz: a2844c9f128a0b025a9a1c933091642b9e885f069d3bfe7daff77f2fe3659c56
+  data.tar.gz: c464cfff417c58d40add531944b4ec12a93a5251510dc01d7f2d81a0a7905997
 SHA512:
-  metadata.gz: 96324cff6b379cb0ec71cbe0d8a15d127a950ddfb7e3997012f4f9b6c4759508a34668fc06a7702d04030ebf65875335c05a6a5836f7959422cbaf107d6abe92
-  data.tar.gz: 9faa6836a004d143d9bcdfc7852d4479b2f9b43f40d09efcab44c32343607b9bcf73949c7e62235b772f817d37845e0e2a5955deefab1c576477a962798e8aa2
+  metadata.gz: d906ee9673550164f3c61c195eee88a41173f80443176c5be7809a89d2da32036f8c6ad03620ca8ddadb8994a345a565602b660e0a150563d4411c6c0e896fae
+  data.tar.gz: 3fe01e2df87c0676ced712531aa44ec1935d8a5d5982d1521e765a3d846a4d9fd524485076738ba1c35927f8eb2cb00fea6db174d3fb570ada0565b19ebdeff1

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [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/dispatcher

@@ -175,6 +175,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
@@ -1512,5 +1519,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

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/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

@@ -14,6 +14,7 @@ require_relative "team_command"
 require_relative "worker_control"
 require_relative "worker_list"
 require_relative "untrack"
+require_relative "restore"
 require_relative "vm"
 require_relative "version"
 
@@ -59,6 +60,7 @@ module Maf
       "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 +78,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?
@@ -132,6 +149,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

@@ -212,13 +212,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 +245,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>`.

data/lib/maf/restore.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# restore.rb - maf restore: put the flow config back from a backup.
+require "fileutils"
+require_relative "backup"
+
+module Maf
+  # Restore copies the files of a backup into .maf/. It keeps a file that
+  # exists, unless --force is given. Then it runs maf update.
+  class Restore
+    USAGE = "usage: maf restore [--list] [BACKUP] [--force]"
+
+    def initialize(root, argv)
+      @root = root
+      @backup = Backup.new(root)
+      @list = argv.include?("--list")
+      @force = argv.include?("--force")
+      @name = argv.find { |arg| !arg.start_with?("-") }
+    end
+
+    def run
+      return list if @list
+
+      dir = @name ? @backup.find(@name) : @backup.latest
+      abort(@name ? "maf: no backup #{@name}. Run: maf restore --list" : "maf: no backup in #{@root}") unless dir
+      restore(dir)
+    end
+
+    private
+
+    def list
+      return puts("No backup yet. maf makes one when a maf command runs.") if @backup.snapshots.empty?
+
+      @backup.snapshots.reverse_each { |dir| puts line(dir) }
+    end
+
+    def line(dir)
+      files = @backup.read(dir)
+      agents = JSON.parse(files.fetch("config.json", "{}")).fetch("agents", []).size
+      "#{File.basename(dir)}  #{@backup.time(dir)}  #{agents} agents  #{files.keys.join(", ")}"
+    rescue JSON::ParserError
+      "#{File.basename(dir)}  #{@backup.time(dir)}  #{files.keys.join(", ")}"
+    end
+
+    def restore(dir)
+      puts "Backup #{File.basename(dir)} (#{@backup.time(dir)}):"
+      written = @backup.read(dir).select { |name, text| put(name, text) }
+      return puts("Nothing to restore. --force replaces the files that exist.") if written.empty?
+
+      Dir.chdir(@root) { Maf.flow } if written.key?("config.json")
+    end
+
+    def put(name, text)
+      path = File.join(@root, ".maf", name)
+      return puts("  keep     .maf/#{name} (exists; --force replaces it)") || false if File.exist?(path) && !@force
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, text)
+      puts("  restore  .maf/#{name}") || true
+    end
+  end
+end

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

@@ -11,6 +11,7 @@ module Maf
       # Seatbelt runs a command in a macOS sandbox-exec profile.
       module Seatbelt
         COMMAND = "/usr/bin/sandbox-exec"
+        MARKER = "MAF_SEATBELT"
         DEVICES = '(literal "/dev/null") (literal "/dev/zero") (literal "/dev/dtracehelper") ' \
                   '(regex #"^/dev/tty") (regex #"^/dev/fd/") (regex #"^/dev/ptmx")'
         DNS = '(path-literal "/private/var/run/mDNSResponder")'
@@ -20,9 +21,12 @@ module Maf
 
         def self.wrap(cmd, paths)
           tmp = private_tmp(paths.root)
-          [COMMAND, "-p", profile(paths, tmp), "env", "TMPDIR=#{tmp}/", "XDG_CACHE_HOME=#{tmp}/cache", *cmd]
+          [COMMAND, "-p", profile(paths, tmp), "env", "#{MARKER}=1", "TMPDIR=#{tmp}/", "XDG_CACHE_HOME=#{tmp}/cache",
+           *cmd]
         end
 
+        def self.inside? = ENV[MARKER] == "1"
+
         def self.available? = File.executable?(COMMAND)
         def self.require! = available? || abort("maf: sandbox mode seatbelt needs #{COMMAND} (macOS only).")
 

data/lib/maf/shared/sandbox.rb

@@ -18,6 +18,8 @@ module Maf
       BACKENDS = { "seatbelt" => Seatbelt, "bwrap" => Bwrap }.freeze
       MODES = ["off", "auto", *BACKENDS.keys].freeze
       POLICY = File.join(".maf", "sandbox.json")
+      NESTED = "maf: this process runs in the macOS sandbox, and macOS cannot start a second sandbox in it. " \
+               "Start the worker from your terminal: cd <worktree> && maf start"
 
       def self.policy
         path = File.join(Project.root, POLICY)
@@ -40,9 +42,13 @@ module Maf
       def self.wrap(cmd, harness, coord_dir: ENV.fetch("COORD_DIR", nil))
         policy = self.policy
         mode = mode(policy)
+        refuse_nested!(mode)
         mode == "off" ? cmd : BACKENDS[mode].wrap(harness.sandboxed(cmd), paths(harness, policy, coord_dir))
       end
 
+      def self.nested?(mode = self.mode) = mode == "seatbelt" && Seatbelt.inside?
+      def self.refuse_nested!(mode = self.mode) = nested?(mode) && abort(NESTED)
+
       def self.keeping_links(harness, coord_dir: ENV.fetch("COORD_DIR", nil))
         links = protected_links(harness, coord_dir)
         yield

data/lib/maf/team.rb

@@ -24,6 +24,7 @@ module Maf
     end
 
     def self.notify(root, text) = coord(root, "msg", "--from", "maf", "architect", text)
+    def self.agent? = !ENV["COORD_ROLE"].to_s.empty?
   end
 
   # Prepare makes a worker ready to start. With --replace, it retires the
@@ -35,6 +36,8 @@ module Maf
     # The architect never talks to the user. A dispatched architect gets fresh
     # sessions with a handoff note, so its context stays small.
     DISPATCH_DEFAULT = %w[architect].freeze
+    NO_BUDGET = "maf: an agent cannot change the team without a budget. Ask the user to set one " \
+                "(maf team set --max N), or to run this command in a terminal."
 
     def self.mode_args(argv)
       return argv - ["--interactive"] if argv.include?("--interactive")
@@ -52,7 +55,7 @@ module Maf
     end
 
     def run
-      @budget.check!(@args.harness, @args.model, @budget.count(workers_after))
+      check_budget
       retire = (Retire.new(@root, @replace).tap(&:check!) if @replace)
       Dir.chdir(@root) { prepare }
       retire.run if retire && Workers.id(@replace) != @args.worker
@@ -61,11 +64,16 @@ module Maf
 
     def announce
       Team.notify(@root, "Team change: worker #{@args.worker} (#{@args.harness}) joined as #{@args.role}.")
-      @args.dispatch ? start_dispatcher : print_next_steps
+      @args.dispatch && !Shared::Sandbox.nested? ? start_dispatcher : print_next_steps
     end
 
     private
 
+    def check_budget
+      abort NO_BUDGET if Team.agent? && !@budget.limited?
+      @budget.check!(@args.harness, @args.model, @budget.count(workers_after))
+    end
+
     def take_replace(argv)
       index = argv.index("--replace") or return nil
       argv.slice!(index, 2)[1] || abort("maf: --replace needs a worker, for example backend-developer_2")

data/lib/maf/team_command.rb

@@ -18,7 +18,14 @@ module Maf
       @root = root
     end
 
-    def run = @argv.first == "set" ? set(@argv.drop(1)) : show
+    AGENT_SET = "maf: only the user sets the team budget. Give the user this command to run in a terminal."
+
+    def run
+      return show unless @argv.first == "set"
+
+      abort AGENT_SET if Team.agent?
+      set(@argv.drop(1))
+    end
 
     private
 

data/lib/maf/untrack.rb

@@ -23,6 +23,10 @@ module Maf
 
     def self.warn_tracked(root) = (warn TRACKED unless new(root, []).tracked.empty?)
 
+    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.",
+            "maf keeps a backup of the flow config in .git/maf/backup. Run `maf restore` to put it back."].freeze
+
     def run
       steps = plan
       return puts("maf: git tracks no file of the flow in #{@root}.") if steps.empty?
@@ -55,7 +59,7 @@ module Maf
       abort "maf: cancelled" unless @yes || confirmed?
       steps.each(&:run)
       Dir.chdir(@root) { Maf.flow }
-      puts "", "The flow left git. Review the change with `git status`, then commit it."
+      puts DONE
     end
 
     def confirmed?

data/lib/maf/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: maf
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Dominik Alberski
@@ -59,6 +59,7 @@ files:
 - exe/maf
 - install.md
 - lib/maf.rb
+- lib/maf/backup.rb
 - lib/maf/bootstrap.rb
 - lib/maf/bootstrap/claude_settings.rb
 - lib/maf/bootstrap/dependencies.rb
@@ -115,6 +116,7 @@ files:
 - lib/maf/migrate/runner.rb
 - lib/maf/migrate/worktrees.rb
 - lib/maf/prompt.rb
+- lib/maf/restore.rb
 - lib/maf/retire.rb
 - lib/maf/role_limits.rb
 - lib/maf/setup_agent.rb