maf 0.3.0 → 0.5.0

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

@@ -11,18 +11,23 @@ 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")'
         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)
-          [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).")
 
@@ -48,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

@@ -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
@@ -68,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/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/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,6 +24,21 @@ 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
       steps = plan
       return puts("maf: git tracks no file of the flow in #{@root}.") if steps.empty?
@@ -55,7 +71,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.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.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Dominik Alberski
@@ -53,12 +53,14 @@ 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
 - 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
@@ -114,9 +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
@@ -126,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