maf 0.1.0

data/lib/maf/retire.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "setup_agent"
+require_relative "workers"
+require_relative "worker_archive"
+require_relative "shared/processes"
+
+module Maf
+  class Retire
+    RUNTIME_PREFIXES = %w[.maf/ .claude/ .opencode/ .codex/].freeze
+
+    def initialize(root, spec)
+      @root = root
+      @worker = Workers.id(spec)
+      @dir = SetupAgent::Worktree.dir_for(root, @worker)
+    end
+
+    def check!
+      abort "maf: no worker #{@worker}" unless Workers.at(@root).find(@worker) || Dir.exist?(@dir)
+      stop_dispatcher
+      pids = RunningProcesses.in(@dir)
+      abort "maf: #{@worker} still runs (pid #{pids.join(", ")}). Stop its session, then run this again." if pids.any?
+      abort "maf: #{@dir} has uncommitted work. Commit it on the task branch, then run this again." if dirty?
+    end
+
+    def run
+      check!
+      released = release_tasks
+      remove_worker
+      Team.notify(@root, "Team change: worker #{@worker} left. #{released} task(s) returned to the pool.")
+      puts "Worker #{@worker} retired. #{released} task(s) returned to the pool."
+    end
+
+    private
+
+    def role = Workers.at(@root).find(@worker)&.fetch("role") || @worker.sub(/-[^-]+\z/, "")
+
+    def stop_dispatcher
+      pid = Workers.at(@root).find(@worker)&.fetch("pid", nil)
+      return unless pid && Shared::Processes.alive?(pid)
+
+      puts "Stopping the dispatcher of #{@worker} (pid #{pid}). A running agent finishes first."
+      RunningProcesses.terminate(pid)
+      abort "maf: pid #{pid} did not stop. Stop it with: kill #{pid}" unless RunningProcesses.wait_for_exit(pid)
+    end
+
+    def release_tasks
+      env = { "COORD_ROLE" => role, "COORD_WORKER" => @worker }
+      ids = Team.coord(@root, "next", "--mine", env: env).scan(/^[0-9a-f-]{36}/)
+      ids.each { |id| release(id) }
+      ids.size
+    end
+
+    def release(id)
+      Team.coord(@root, "unclaim", id)
+      Team.coord(@root, "annotate", id, "Worker #{@worker} was retired. Continue on the existing task branch.")
+    end
+
+    def remove_presence
+      coord_dir = File.join(@root, ".maf", "coordination")
+      FileUtils.rm_f(File.join(coord_dir, "presence", "#{@worker}.json"))
+    end
+
+    def remove_worker
+      remove_worktree
+      WorkerArchive.new(@root, @worker).run
+      remove_presence
+      Workers.at(@root).remove(@worker)
+    end
+
+    def dirty?
+      return false unless Dir.exist?(@dir)
+
+      lines = IO.popen(["git", "-C", @dir, "status", "--porcelain"], err: File::NULL, &:readlines)
+      lines.map { |line| line[3..].strip }.any? { |path| RUNTIME_PREFIXES.none? { |prefix| path.start_with?(prefix) } }
+    end
+
+    def remove_worktree
+      return unless Dir.exist?(@dir)
+
+      system("git", "-C", @root, "worktree", "remove", "--force", @dir, out: File::NULL) ||
+        warn("maf: could not remove #{@dir}. Remove it with: git worktree remove #{@dir}")
+    end
+  end
+
+  # RunningProcesses finds processes whose working directory is inside DIR.
+  # A harness session or a dispatcher runs in its worktree.
+  module RunningProcesses
+    def self.in(dir)
+      out = IO.popen(%w[lsof -a -d cwd -Fpn], err: File::NULL, &:read)
+      pairs(out).select { |_pid, path| path == dir || path.start_with?("#{dir}/") }.map(&:first) - [Process.pid]
+    rescue Errno::ENOENT
+      warn "maf: lsof not found. Cannot check if the worker still runs."
+      []
+    end
+
+    # TERM lets a running agent finish its run first.
+    def self.terminate(pid)
+      Process.kill("TERM", pid)
+    rescue Errno::EPERM
+      abort "maf: pid #{pid} belongs to another user. Stop it with: sudo kill #{pid}"
+    end
+
+    # A dispatcher run can take up to its --timeout (default 1500 seconds).
+    def self.wait_for_exit(pid, timeout: Integer(ENV.fetch("MAF_STOP_TIMEOUT", "1800")))
+      deadline = Time.now + timeout
+      sleep 0.5 while Shared::Processes.alive?(pid) && Time.now < deadline
+      !Shared::Processes.alive?(pid)
+    end
+
+    def self.pairs(out)
+      out.lines(chomp: true).slice_before { |line| line.start_with?("p") }
+         .map { |group| [group.first[1..].to_i, group.find { |line| line.start_with?("n") }.to_s[1..].to_s] }
+    end
+  end
+end

data/lib/maf/role_limits.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# role_limits.rb - save the session limits of a role in .maf/config.json.
+#
+#   maf worker restart frontend-developer_bot --max-context 80000
+require "json"
+
+module Maf
+  # RoleLimits reads the limit flags of `maf worker start|restart` and saves
+  # them under team.limits.<role> in .maf/config.json. The dispatcher reads
+  # them when it starts, so a restart applies them. A flag of
+  # `maf start --dispatch` still wins over a saved limit.
+  class RoleLimits
+    FLAGS = { "--max-context" => "max_context", "--max-session-runs" => "max_session_runs",
+              "--cache-window" => "cache_window" }.freeze
+
+    def self.parse(args) = FLAGS.filter_map { |flag, key| pair(args, flag, key) }.to_h
+    def self.pair(args, flag, key) = (index = args.index(flag)) && [key, number(flag, args[index + 1])]
+
+    def self.number(flag, text)
+      value = Integer(text.to_s, exception: false)
+      value && value >= 0 ? value : abort("maf: #{flag} needs a number of 0 or more")
+    end
+
+    def initialize(root) = @path = File.join(root, ".maf", "config.json")
+
+    def save(role, limits)
+      return if limits.empty?
+
+      File.write(@path, JSON.pretty_generate(merged(manifest, role, limits)))
+      puts "Saved limits of #{role}: #{limits.map { |key, value| "#{key}=#{value}" }.join(" ")}"
+    end
+
+    private
+
+    def merged(data, role, limits)
+      saved = data.dig("team", "limits").to_h
+      team = data.fetch("team", {}).merge("limits" => saved.merge(role => saved[role].to_h.merge(limits)))
+      data.merge("team" => team)
+    end
+
+    # A corrupt manifest must not be overwritten. Stop with a clear message instead.
+    def manifest
+      File.exist?(@path) ? JSON.parse(File.read(@path)) : {}
+    rescue JSON::ParserError
+      abort "maf: #{@path} is not valid JSON. Fix it, then run this command again."
+    end
+  end
+end

data/lib/maf/setup_agent/args.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Maf
+  module SetupAgent
+    # Args reads the positional arguments (HARNESS ROLE[_WORKER] [model:M]),
+    # then the flags. --dispatch and --model M are setup_agent's own flags; all
+    # other flags go to the dispatcher and need --dispatch.
+    class Args
+      Parsed = Struct.new(:harness, :role, :worker_id, :worker, :model, :dispatch, :detach, :dispatcher_args,
+                          keyword_init: true)
+
+      def self.parse(argv)
+        dispatch, detach, positional, flags = split(argv)
+        model = take_model(flags)
+        reject_stray(flags, dispatch)
+        abort "setup_agent: --detach works only with --dispatch" if detach && !dispatch
+        Parsed.new(**identity(positional, model, dispatch), dispatch: dispatch, detach: detach, dispatcher_args: flags)
+      end
+
+      def self.split(argv)
+        rest = argv - %w[--dispatch --detach]
+        index = rest.index { |arg| arg.start_with?("--") } || rest.size
+        [argv.include?("--dispatch"), argv.include?("--detach"), rest[0...index], rest[index..-1]]
+      end
+
+      def self.identity(positional, model, dispatch)
+        harness, role_spec, model_arg = positional
+        abort_usage if harness.nil? || role_spec.nil?
+        role, worker_id = split_role(role_spec, dispatch ? "bot" : "1")
+        { harness: harness, role: role, worker_id: worker_id, worker: "#{role}-#{worker_id}",
+          model: model || model_arg&.sub(/\Amodel:/, "") }
+      end
+
+      def self.take_model(flags)
+        index = flags.index("--model")
+        value = index && flags.slice!(index, 2)[1]
+        abort "setup_agent: --model needs a value" if index && (value.nil? || value.start_with?("--"))
+        value
+      end
+
+      def self.reject_stray(flags, dispatch)
+        return if flags.empty? || dispatch
+
+        abort "setup_agent: #{flags.join(" ")} works only with --dispatch"
+      end
+
+      def self.split_role(spec, default_id = "1")
+        role, _sep, worker_id = spec.rpartition("_")
+        role.empty? ? [spec, default_id] : [role, worker_id]
+      end
+
+      def self.abort_usage
+        abort "usage: maf start HARNESS ROLE[_WORKER] [model:MODEL] [--model MODEL] [--dispatch [FLAGS...]]"
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/dispatch.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Maf
+  module SetupAgent
+    # Dispatch runs dispatcher in the worktree instead of an interactive
+    # session. The dispatcher of the main checkout is used: maf update
+    # refreshes that copy, not the copy in a worktree. The current Ruby runs
+    # it, so an old system Ruby on the shebang path never parses it.
+    module Dispatch
+      DISPATCHER = ".maf/bin/dispatcher"
+
+      def self.launch(args, model)
+        dispatcher = File.join(Project.root, DISPATCHER)
+        require_dispatcher!(dispatcher)
+        cmd = [RbConfig.ruby, dispatcher, args.role, "--harness", args.harness]
+        cmd += ["--model", model] if model
+        cmd += args.dispatcher_args
+        args.detach ? detach(cmd, args.worker) : Launcher.exec_or_die(cmd)
+      end
+
+      # setsid gives the dispatcher its own session, so it keeps running when
+      # the terminal or the harness session that started it ends.
+      def self.detach(cmd, worker)
+        log = File.join(ENV.fetch("COORD_DIR"), "sessions", "#{worker}.log")
+        pid = spawn_detached(cmd, log)
+        Maf::Workers.at(Project.root).update(worker, "pid" => pid)
+        puts "Started #{worker} in the background (pid #{pid}). Log: #{log}"
+      end
+
+      def self.spawn_detached(cmd, log)
+        FileUtils.mkdir_p(File.dirname(log))
+        io = { in: File::NULL, out: [log, "a"], err: %i[child out] }
+        pid = fork { Process.setsid && exec({ "DISPATCHER_LOG" => log, "PWD" => Dir.pwd }, *cmd, **io) }
+        Process.detach(pid) && pid
+      end
+
+      def self.require_dispatcher!(dispatcher)
+        return if File.exist?(dispatcher)
+
+        abort "setup_agent: #{dispatcher} is missing. Run maf update in the main project, then start again."
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/hermes_launcher.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Maf
+  module SetupAgent
+    module Launcher
+      # Hermes loads role files as skills from <hermes_dir>/<project>-<role>/.
+      # flow.rb writes the skill there; --skills <project>-<role> loads it.
+      # Hermes has no --agent flag; the skill's SKILL.md is the role definition.
+      # `-q` on a TTY seeds an interactive session with the prompt.
+      # A lead role owns no task, so it gets an inbox prompt. A role with
+      # can_edit false starts without the file-writing toolsets.
+      module Hermes
+        PROMPT = "Follow the coordination rules of your role skill as role %<role>s. " \
+                 "Run coord inbox, then coord next --wait. Claim a task, do the work, finish it. Repeat."
+        LEAD_PROMPT = "Follow your role skill and its coordination rules as role %<role>s. " \
+                      "You are a lead role. Never claim a task. Run coord inbox --wait and handle each message."
+
+        def self.launch(role, _worker, model)
+          cmd = %w[hermes chat]
+          cmd += ["--skills", HermesSkill.name(role)] if HermesSkill.installed?(role)
+          cmd += ["--model", model] if model
+          cmd += ["-t", Flow::READ_ONLY_TOOLSETS] if read_only?(role)
+          Launcher.exec_or_die(cmd + ["-q", prompt(role)])
+        end
+
+        def self.prompt(role) = format(Flow::LEADS.include?(role) ? LEAD_PROMPT : PROMPT, role: role)
+
+        def self.read_only?(role)
+          Project.manifest.fetch("agents", []).any? { |agent| agent["role"] == role && agent["can_edit"] == false }
+        end
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/hermes_skill.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Maf
+  module SetupAgent
+    # HermesSkill resolves the skill flow.rb generated for a role: the name is
+    # <project>-<role>, and the dir is the manifest's hermes_dir (set by
+    # `flow.rb --hermes-dir`) or flow.rb's default ~/.hermes/skills.
+    module HermesSkill
+      DEFAULT_DIR = File.join(Dir.home, ".hermes", "skills")
+
+      # Plain defs, not endless ones: this file must still parse on Ruby 2.x so
+      # the version check above can print its message.
+      def self.name(role)
+        "#{File.basename(Project.root)}-#{role}"
+      end
+
+      def self.dir
+        Project.manifest.fetch("hermes_dir", DEFAULT_DIR)
+      end
+
+      def self.installed?(role)
+        File.exist?(File.join(dir, name(role), "SKILL.md"))
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/launcher.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Maf
+  module SetupAgent
+    module Launcher
+      REGISTRY = {}
+
+      def self.for(harness)
+        register_defaults if REGISTRY.empty?
+        REGISTRY.fetch(harness) { abort "setup_agent: no launcher for harness '#{harness}' yet." }
+      end
+
+      def self.register_defaults
+        REGISTRY["claude"] = Claude
+        REGISTRY["opencode"] = Opencode
+        REGISTRY["codex"] = Codex
+        REGISTRY["hermes"] = Hermes
+      end
+
+      def self.exec_or_die(cmd)
+        Kernel.exec(*cmd)
+      rescue Errno::ENOENT
+        abort "setup_agent: '#{cmd.first}' not found on PATH."
+      end
+
+      # FlowFiles finds the files of the flow in .maf/ of the main project. The
+      # project's own harness config stays as it is: each file of the flow is
+      # passed to the harness at the start.
+      module FlowFiles
+        def self.path(*parts) = File.join(Project.root, ".maf", *parts)
+        def self.flag(name, *parts) = File.exist?(path(*parts)) ? [name, path(*parts)] : []
+      end
+
+      # --settings adds the hooks of the flow, --mcp-config adds the graph server.
+      # --mcp-config takes many values, so `--` ends the options before the prompt.
+      module Claude
+        def self.launch(role, _worker, model)
+          prompt = "Read .maf/agents/claude/#{role}.md and follow it exactly. Start your work loop now."
+          cmd = ["claude", *FlowFiles.flag("--settings", "claude", "settings.json"),
+                 *FlowFiles.flag("--mcp-config", "mcp", "claude.json")]
+          Launcher.exec_or_die(cmd + (model ? ["--model", model] : []) + ["--", prompt])
+        end
+      end
+
+      # opencode merges the file in OPENCODE_CONFIG with the project's opencode.json.
+      module Opencode
+        def self.launch(role, _worker, model)
+          config = FlowFiles.path("mcp", "opencode.json")
+          ENV["OPENCODE_CONFIG"] = config if File.exist?(config)
+          cmd = ["opencode", ".", "--agent", role, "--prompt", "Start your work loop now."]
+          Launcher.exec_or_die(cmd + (model ? ["--model", model] : []))
+        end
+      end
+
+      module Codex
+        def self.launch(role, _worker, model)
+          prompt_file = ".codex/prompts/#{role}.md"
+          abort "setup_agent: #{prompt_file} missing." unless File.exist?(prompt_file)
+
+          cmd = ["codex", *writable_dirs]
+          cmd += ["--model", model] if model
+          warn_untrusted
+          Launcher.exec_or_die(cmd + [File.read(prompt_file)])
+        end
+
+        UNTRUSTED = "maf: Codex does not trust the hooks in %<file>s yet. Trust them when Codex asks. " \
+                    "Without the hooks, the session records no token usage, and coord await cannot wake it."
+
+        # Codex runs the hooks of a project only after the user trusts them, and
+        # a worktree is a new project for Codex. Codex records the trust in its config.toml.
+        def self.warn_untrusted
+          hooks = File.join(File.realpath(Dir.pwd), ".codex", "hooks.json")
+          config = File.join(ENV.fetch("CODEX_HOME", File.join(Dir.home, ".codex")), "config.toml")
+          trusted = File.exist?(config) && File.read(config).include?("#{hooks}:stop:")
+          warn format(UNTRUSTED, file: hooks) if File.exist?(hooks) && !trusted
+        end
+
+        # The worktree is the only writable root of the Codex sandbox. coord
+        # writes the board and the artifacts in .maf/coordination of the main
+        # project, so Codex would ask for approval at each coord command.
+        def self.writable_dirs = ["--add-dir", File.join(SetupAgent::Project.root, ".maf", "coordination")]
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/manifest.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Maf
+  module SetupAgent
+    class Manifest
+      def self.load(path)
+        abort_missing(path) unless File.exist?(path)
+
+        new(JSON.parse(File.read(path))["agents"])
+      end
+
+      def self.abort_missing(path)
+        abort "setup_agent: #{path} missing. Fix: maf add HARNESS:ROLE"
+      end
+
+      def initialize(agents)
+        @agents = agents
+      end
+
+      def verify!(harness, role)
+        return if @agents.any? { |a| a["harness"] == harness && a["role"] == role }
+
+        abort "setup_agent: no #{harness}:#{role} in .maf/config.json.\n#{add_hint("#{harness}:#{role}")}"
+      end
+
+      # maf add keeps the current agents, so the hint names only the missing agent.
+      def add_hint(missing) = "  Fix: maf add #{missing}"
+
+      def model_for(harness, role)
+        entry = @agents.find { |a| a["harness"] == harness && a["role"] == role }
+        entry && entry["model"]
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/project.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../shared/project"
+
+module Maf
+  module SetupAgent
+    Project = Maf::Shared::Project
+  end
+end

data/lib/maf/setup_agent/role_file.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Maf
+  module SetupAgent
+    # A role file that is not committed yet is missing in a new worktree, and
+    # the harness then starts without its role. Copy the main checkout's file.
+    # The worktree also needs the symlink from the harness folder to the file.
+    # A harness folder with the project's own files gets one link per role file.
+    module RoleFile
+      def self.copy(root, dir, harness, role)
+        relative = Flow.role_path(harness, role)
+        return unless relative
+
+        copy_missing(File.join(root, relative), File.join(dir, relative))
+        link(Flow::AgentLinks.new(dir), harness)
+      end
+
+      def self.link(links, harness)
+        links.link_files(harness) if links.link(harness) == :refuse
+      end
+
+      def self.copy_missing(source, dest)
+        return unless File.exist?(source) && !File.exist?(dest)
+
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(source, dest)
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/runtime_hooks.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../bootstrap"
+
+module Maf
+  module SetupAgent
+    # Refresh owned hooks before the harness starts in an existing worktree.
+    module RuntimeHooks
+      def self.install(dir, harness)
+        %w[next-task.rb board-watch.rb session-guard.rb context-watch.rb].each { |name| copy(dir, name) }
+        configure(dir, harness)
+        copy(dir, "board-watch-opencode.js", ".opencode/plugins/board-watch.js") if harness == "opencode"
+      end
+
+      # Claude Code reads the hooks from the settings file of the main project
+      # (`maf start` passes it with --settings). The hook commands run in the
+      # worktree, where the copies above live.
+      def self.configure(dir, harness)
+        root = Project.root
+        settings = File.join(root, Bootstrap::CLAUDE_SETTINGS)
+        Bootstrap::ClaudeSettings.new(Bootstrap::Project.new(root, false)).configure(settings) if harness == "claude"
+        Flow::CodexHooks.new(dir).install if harness == "codex"
+      end
+
+      def self.copy(dir, name, relative = ".maf/coordination/harness-hooks/#{name}")
+        path = File.join(dir, relative)
+        abort "maf: #{path} is a foreign hook; the worker was not started" if foreign?(path, name)
+
+        Flow::HookFiles.copy(File.join(Flow::ASSETS, "harness-hooks", name), path)
+      end
+
+      def self.foreign?(path, name)
+        File.exist?(path) && !File.read(path).include?("#{name} -")
+      end
+    end
+  end
+end

data/lib/maf/setup_agent/worktree.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../shared/project"
+
+module Maf
+  module SetupAgent
+    class Worktree
+      COORD = ".maf/bin/coord"
+
+      # coord creates the worktree with the same shared formula.
+      def self.dir_for(root, slug) = Maf::Shared::Project.worktree_dir(root, slug)
+
+      # `coord worktree` is idempotent. Run it also for an existing worktree,
+      # so the worktree gets runtime files that were added after it was created.
+      # MAF_HARNESS tells coord which harness starts the worker, so coord checks
+      # the role file of that harness only.
+      def self.ensure(role, worker_id, harness)
+        dir = dir_for(Dir.pwd, "#{role}-#{worker_id}")
+        abort "setup_agent: coord worktree failed" unless coord_worktree(role, worker_id, harness)
+        new(dir)
+      end
+
+      def self.coord_worktree(role, worker_id, harness)
+        system({ "MAF_HARNESS" => harness }, RbConfig.ruby, COORD, "worktree", role, worker_id)
+      end
+
+      def initialize(dir)
+        @dir = dir
+      end
+
+      def dir
+        @dir
+      end
+
+      def export_env!
+        path = File.join(@dir, ".maf/env.sh")
+        File.readlines(path).each { |line| set_env(line) } if File.exist?(path)
+        ENV["PATH"] = [ENV["MAF_BIN"], ENV["PATH"]].compact.join(File::PATH_SEPARATOR)
+      end
+
+      private
+
+      def set_env(line)
+        return unless line.chomp =~ /\Aexport (\w+)=(.+)\z/
+
+        ENV[Regexp.last_match(1)] = Regexp.last_match(2)
+      end
+    end
+  end
+end