maf 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cdbedeaf3c68e4b2aa40939c8f006f846d0d044531f2c6d53e01cddf4d9e45d
-  data.tar.gz: e90a24b66c78fd7cc493e493f722b25a5803430967b2cae0de46202befaf12b2
+  metadata.gz: 1d92abf8bbcca7ba5044ac6185534e883a55a1387e05460ac4142e1d89f3d13e
+  data.tar.gz: 25eaa46e4ed438fef70a08841137fc87c7ede35dfe9c09ff4d053a351e11e9ef
 SHA512:
-  metadata.gz: ee79aa5c928c7be62ed39cdcf2904f7905b6e33189c31f19b7badd522cd0600431d6b39faebf72c7f60caf951ddbb577efc6d2a1fc167145f4f2503665ffe256
-  data.tar.gz: 0aa9875967605035e251dab51a6ad097dc80c428cda40a8db8abfad99d0cb5381d92da1c5b7e9dc5b4daa5d7263e670655150100a40f70fb0ec9369b35f868fe
+  metadata.gz: 96324cff6b379cb0ec71cbe0d8a15d127a950ddfb7e3997012f4f9b6c4759508a34668fc06a7702d04030ebf65875335c05a6a5836f7959422cbaf107d6abe92
+  data.tar.gz: 9faa6836a004d143d9bcdfc7852d4479b2f9b43f40d09efcab44c32343607b9bcf73949c7e62235b772f817d37845e0e2a5955deefab1c576477a962798e8aa2

data/CHANGELOG.md

@@ -2,6 +2,180 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-21
+
+- Fix: each dispatched Hermes run failed. Hermes 0.22 refuses `--run-budget` with `--format
+  stream-json`. maf no longer passes `--run-budget`. The `--timeout` of the dispatcher still
+  stops a run.
+- Fix: in a Hermes run, `coord` did not get `COORD_WORKER` and the other flow variables, so
+  `coord done` refused to close the task. Hermes runs each session in a shared gateway and
+  passes only the names in `terminal.client_env_passthrough`. `maf add` and `maf update` print
+  the `hermes config set` command that adds the flow names to that list.
+- `maf worker stop|start|restart|status ROLE` finds the worker when the role has one worker,
+  for example `tester-bot`.
+- `maf worker list` names the stopped workers also when no worker runs.
+- A worker does not start a team of its own. `.maf/claude/settings.json` sets
+  `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0`, so a subagent that Claude names in a `maf start`
+  session does not start as a teammate. `maf update` adds the setting.
+- Hermes: each role gets a toolset list. A role that edits no longer gets `kanban`,
+  `delegation`, `cronjob`, `computer_use`, and the other toolsets outside the list.
+- Fix: a Hermes role with `can_edit: false` did not get the graph MCP server, because its
+  toolset list did not name `mcp-graphify-<project>`.
+- The dispatcher blocks a task after 3 runs in a row that leave it claimed and not done, and
+  escalates it to the project manager. Before, it resumed such a task each hour without end.
+  New commands: `coord block ID [--kind K] TEXT` holds a task out of `coord next`, and
+  `coord unblock ID` returns it. `coord status` and `coord board` show blocked tasks.
+- A worker that cannot finish a task blocks it with a kind: `needs_input`, `dependency`, or
+  `capability`. coord tells the architect (dependency) or the project manager (the other kinds).
+  Before, the worker kept the claim, and the dispatcher resumed the task each hour.
+- `maf worker list` shows each running worker: its role, harness, mode (session or dispatch),
+  pid, and start time. A worker that runs twice, for example as a session and as a
+  dispatcher, gets a warning. The last line names the registered workers that do not run.
+- Effort levels per role (#44): `maf add --effort ROLE=LEVEL`, `maf start` and `maf prepare
+  --effort LEVEL`, and `dispatcher --effort LEVEL`. maf passes the level to the harness in its
+  own form: `--effort` (Claude Code), `model_reasoning_effort` (Codex), `--reasoning` (Hermes),
+  `--variant` (opencode), and the model name for Cursor (`gpt-5.3-codex` + `high` =
+  `gpt-5.3-codex-high`). Each role has a default level in `roles.yml` (`effort:`), used when the
+  harness lists it. After `maf update`, the claude, codex, hermes, and cursor agents get the
+  default of their role. The interactive mode shows the levels of each model and asks for one.
+- Fix: Codex 0.163 ran the commands of a worker in its shared background server. The commands
+  got the environment of the shell that started the server, not of the worker: no `.maf/bin` on
+  PATH, no `COORD_ROLE` and `COORD_WORKER`. maf now starts Codex with `--no-daemon`.
+- Fix: after a message run, the dispatcher counted the unclaimed tasks as dispatched and backed
+  off: 2 minutes, then 4, then more. A message run must not claim a task, so the task waited
+  without a reason. The task now runs in the next cycle.
+
+## [0.2.0] - 2026-10-14
+
+- The sandbox also protects the flow config in `.maf/claude/` and `.maf/mcp/`, and each script
+  that it names. `maf start` and the dispatcher give these files to the harness on the host.
+- Fix: `maf start` of a Codex worker in the sandbox stopped with `Errno::EPERM` on the protected
+  `.codex/hooks.json`. maf now writes the file only on a change.
+- The sandbox also protects `.maf/coordination/taskdata/hooks/`: Taskwarrior runs each script
+  in it, also on the host.
+- Fix: on Linux, a protected file in `/tmp` (for example a hook script in a harness config)
+  made bwrap bind the host `/tmp`, with the sockets of host services. bwrap now binds a parent
+  folder only in an allowed folder.
+- Fix: `coord worktree` in the sandbox stopped with an error on the protected `.maf/env.sh` of a
+  worktree. coord now writes the file only on a change, and it shows a warning if it cannot.
+- Fix: `maf retire` did not stop a dispatcher of an older maf during a run longer than one
+  hour. maf now also finds the dispatcher from its command in the worktree.
+- `maf vm create` installs the maf version of the host, not the newest maf.
+- The sandbox also protects `.maf/coordination/harness-hooks` of the main checkout.
+- On Linux, maf no longer creates an empty `~/.codex/packages` or a `{}` `~/.cursor/cli-config.json`.
+- Fix: `maf team` showed a running dispatcher of an older maf as stopped.
+- maf does not take `bwrap` from a folder of the `write` list.
+- Fix: a broken `.maf/sandbox.json` turned the sandbox off. maf now stops with an error.
+- Fix: maf ran `sandbox-exec` and `bwrap` from `PATH`. maf now runs `/usr/bin/sandbox-exec`,
+  and it does not take `bwrap` from the project or a temporary folder.
+- On Linux, each sandboxed run gets a private `/dev/shm`.
+- The analyst command starts in a new session without a terminal.
+- Fix: an empty start time in `workers.json` made a running dispatcher look stopped.
+- The sandbox also protects a hook script that `$CLAUDE_PROJECT_DIR` names, the scripts that
+  the harness config of a worktree names, and `config` and `hooks/` of each submodule.
+- Fix: `maf retire` stopped for good when another process had the pid of an old dispatcher.
+  For a record without a start time, maf now uses the heartbeat.
+- In a worktree, maf checks the Codex hook trust of the main checkout, because Codex uses
+  the hooks of the main checkout there. The warning tells you to trust the hooks on the host.
+- Fix: on Linux, a `TMPDIR` in `/run/user` (or a `write` path in or above a masked folder)
+  opened the session bus again. bwrap now skips such a path.
+- Fix: `maf retire` and `maf worker restart` went on when maf could not check the pid of a
+  worker from an older maf. They now stop and show the `kill` command.
+- Fix: in the dispatcher, a failed start of a run could run the exit handlers of the
+  dispatcher in the child process.
+- Fix: `printf task | maf start` (input without a final newline) waited forever in the sandbox.
+- Fix: on macOS, a run could take the temporary folder of another project from `TMPDIR`.
+- `maf vm login` says "this computer" instead of "this Mac", because it also runs on Linux.
+- Fix: the dashboard ran the analyst command of `.maf/config.json` on the host. The agent
+  can change that file, so the command now runs in the sandbox.
+- The sandbox also protects `.maf/coordination/harness-hooks` in each worktree, and
+  `.git/config.worktree` of the project and of each worktree.
+- Fix: a relative path in the `write` list of `.maf/sandbox.json` started at the current
+  folder. It now starts at the project root.
+- Fix: on Linux, a home folder with its own overlay made maf think that it already ran in the
+  sandbox, so it did not wrap the agent. The sandbox now also sets `MAF_BWRAP=1`.
+- Fix: `echo task | maf start` with the sandbox on waited forever. The terminal relay now
+  sends ^D when the input ends.
+- Fix: `maf vm` stopped with an error for a VM without mounts.
+- Fix: `maf start` could start a second dispatcher for a worker whose presence record has no
+  start time. Such a record now counts as live while its heartbeat is recent. `maf stop` then
+  shows the `kill` command instead of a signal to an unknown pid.
+- Fix: in the sandbox, `maf stop` of an interactive worker stopped only the terminal relay.
+  The relay now passes TERM, HUP, and INT to the harness, and waits for it.
+- On Linux, maf puts back a protected symlink (for example `~/.claude/CLAUDE.md` into your
+  dotfiles) that the agent changed during a run, and shows a warning.
+- The sandbox also protects the harness config in each worktree.
+- Fix: on Linux, a worker that a lead starts failed when the home folder has a space in its path.
+- `docs/sandbox.md` has a new section: what the sandbox protects against.
+- The sandbox uses an allowlist in the folder of each harness: the agent can write only
+  the state paths, for example `~/.claude/projects` and `~/.codex/sessions`. Each other
+  path is protected, also a new name in an update of the harness. On Linux, each existing
+  path that is not state is bound read-only.
+- Fix: the dispatcher ran the verify command of `.maf/config.json` on the host. The agent
+  can change that file, so the command now runs in the sandbox.
+- Fix: a dispatched run could push a command into the terminal of the dispatcher (TIOCSTI).
+  Each run now starts in a new session without a terminal.
+- Fix: the dispatcher ran `coord` from the worktree, where the agent can change it. It now
+  runs `coord` of the main checkout.
+- Fix: a sandboxed run of a worker with `--command` stopped with `NoMethodError`.
+- The sandbox protects the config of each harness in the project (`.mcp.json`,
+  `.claude/settings.json`, `.codex/config.toml`, `.opencode/`, and more), and `.maf/bin`,
+  `.maf/lib`, and `.maf/env.sh` in each worktree.
+- The sandbox no longer opens `~/.cache` and `~/Library/Caches`. On macOS, `XDG_CACHE_HOME`
+  is a private folder of the project.
+- The sandbox also protects a file that a config names with a relative path, and a named file of
+  1 MB or more. In a Markdown file, maf follows only the imports, so the text of a skill does not
+  protect the files of the project.
+- `maf vm create` finds the agents of the project also in a subfolder or in a worktree.
+- Fix: an agent in the sandbox could push a command into the terminal of an interactive
+  `maf start` (TIOCSTI). The shell ran the command outside the sandbox after the harness stopped.
+  With the sandbox on, the harness now gets its own terminal.
+- The sandbox also protects each file that the config of a harness names: hook scripts,
+  status line scripts, and imports in `CLAUDE.md`. It also protects `~/.claude/rules`, and
+  `prompts`, `packages`, and `AGENTS.override.md` in `~/.codex`.
+- On Linux, maf creates each missing config file of a harness before each run, so bwrap can protect it.
+- `maf uninstall` removes `.maf/vm/` and tells you if the VM of the project still exists.
+- `maf vm create` checks the checksum of the Taskwarrior download, and accepts only sizes above 0.
+- The sandbox also protects `.maf/coordination/taskrc`, `.maf/coordination/worktree-env.rb`,
+  `.git/commondir`, the git links of each worktree, and the config, hooks, and plugins of each harness.
+  If a protected path is a symlink, the link is protected too. On Linux, maf creates the missing
+  protected folders before each run.
+- On macOS, the sandbox blocks LaunchServices (`open`) and Apple Events: they started apps outside the sandbox.
+- `maf vm` with a missing or unknown action, or an unknown flag, shows the usage.
+- A VM boot no longer installs the harness CLIs again. `maf vm create` makes a smaller VM by default:
+  4 GiB of memory and a 20 GiB disk.
+- Fix: `maf retire` could stop an unrelated process that got the pid of an ended dispatcher.
+  maf now signals a pid only if its start time matches the recorded one. `maf start --detach`
+  records the start time. `maf team`, `maf worker`, and the dashboard use the same check.
+- The sandbox policy moved to `.maf/sandbox.json`. The agent cannot change it, the flow scripts,
+  the message hooks, the git hooks, or `.git/config`. On macOS, each run gets a private `TMPDIR`,
+  and the agent can connect only to the sockets of its own folders.
+- `maf vm shell` loads `.maf/env.sh`, so `coord` is on PATH.
+- The sandbox blocks host service sockets (tmux, Docker, systemd --user, D-Bus, SSH agent).
+  On Linux, `/tmp` is private to the run, and bwrap keeps the Claude Code state file.
+- `maf vm`: the VM name holds a hash of the project path, and each command checks that the VM
+  mounts the project. The VM runs Ubuntu 26.04 and needs Lima 2.2.0 or later. The copied logins are always mode 600.
+- Sandbox mode `bwrap` needs bubblewrap 0.10 or later. maf stops with an older bubblewrap.
+- Linux support: sandbox mode `bwrap` (bubblewrap) and mode `auto` (seatbelt on macOS, bwrap on Linux).
+  `maf vm` also runs on a Linux host with QEMU, and copies the claude login from `~/.claude/.credentials.json`.
+- New command `maf vm`: run the whole team in a Lima VM on macOS. `maf vm create` makes a VM that
+  sees only the project folder, at the same path as on the host. It installs Ruby, git, tmux,
+  Taskwarrior 3, maf, and the CLI of each harness of the project. Then it asks for each harness
+  if it can copy the login from this Mac into the VM (`--copy-logins`, `--no-copy-logins`, `maf vm login`).
+- New sandbox for the agents on macOS: `{"mode": "seatbelt"}` in `.maf/sandbox.json`
+  or `MAF_SANDBOX=seatbelt`. `maf start` and the dispatcher run the harness in `sandbox-exec`.
+  The agent can write only to the project, the board, the temporary folders, and the folders of its harness.
+- Each harness is one file in `lib/maf/shared/harnesses/`. To add a harness, add one
+  file, one test file, and one row in the Harnesses table of the user manual.
+  `test/harnesses/contract_test.rb` checks every harness file.
+- The dispatcher has no default harness. Give `--harness NAME` or `--command TEMPLATE`.
+  `maf start` gives the harness, so `maf start` does not change.
+- A dispatched run gets `OPENCODE_CONFIG` only on the `opencode` harness.
+- `maf untrack` untracks only the role links in `.cursor/agents/`, not the whole folder.
+- New harness `cursor` (the Cursor CLI, `agent`): `maf add cursor:ROLE`, `maf start cursor ROLE`,
+  and `dispatcher ROLE --harness cursor`. Role files go to `.cursor/agents/` as Cursor subagents.
+  Cursor has no wake-up hook yet, so its agents wait with `coord next --wait`.
+
 ## [0.1.0] - 2026-10-08
 
 - First release as a gem: `gem install maf`.

data/README.md

@@ -1,7 +1,7 @@
 # multi_agent_flow
 
 Coordination layer for running several AI coding agents (opencode, Claude Code,
-Hermes, Codex) in parallel on one repository, each in its own terminal.
+Hermes, Codex, Cursor) in parallel on one repository, each in its own terminal.
 
 Three pillars:
 
@@ -25,7 +25,7 @@ The `maf` gem holds the flow. Install these tools yourself:
 | Ruby 3.0+ | runs `maf`, `coord`, and the other scripts | macOS: `brew install mise && mise install ruby`. Linux: your package manager or [mise](https://mise.jdx.dev) |
 | git | worktrees, hooks, the local exclude file | macOS: `xcode-select --install` or `brew install git`. Linux: `apt install git` |
 | Taskwarrior | the task board | macOS: `brew install task`. Linux: `apt install taskwarrior` |
-| One or more harnesses | the agents | [Claude Code](https://docs.claude.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [opencode](https://opencode.ai), [Hermes](https://github.com/NousResearch/hermes-agent) |
+| One or more harnesses | the agents | [Claude Code](https://docs.claude.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [opencode](https://opencode.ai), [Cursor CLI](https://cursor.com/cli), [Hermes](https://github.com/NousResearch/hermes-agent) |
 | graphify (optional) | the shared knowledge graph | `uv tool install graphifyy` |
 
 Install the gem:
@@ -83,7 +83,7 @@ lives in `graphify-out/` at the project root, where graphify looks by default.
   lib/maf/shared/ code that the scripts in bin/ load (maf update replaces it)
   coordination/   task board, inbox, locks, presence, sessions, hooks, logs
   worktrees/      one git worktree per worker
-  agents/         role files: claude/, opencode/, codex/
+  agents/         role files: claude/, opencode/, codex/, cursor/
   claude/         settings.json: the Claude Code hooks (maf start passes --settings)
   mcp/            the graphify MCP server for Claude Code and opencode
   config.json     the agents and settings of the project
@@ -113,7 +113,7 @@ Local files that a harness or git reads outside `.maf/`:
 |---|---|
 | `.git/hooks/*` | Git reads them there. |
 | `.git/info/exclude` | Keeps the flow out of git in this clone. |
-| `.claude/agents/`, `.opencode/agents/`, `.codex/prompts/` | Symlinks into `.maf/agents/<harness>/`. |
+| `.claude/agents/`, `.opencode/agents/`, `.codex/prompts/`, `.cursor/agents/` | Symlinks into `.maf/agents/<harness>/`. |
 | `.opencode/plugins/board-watch.js` | opencode reads it there. |
 | `.codex/hooks.json` | Codex reads it there. Excluded when the project does not track it. |
 | `~/.hermes/skills/<project>-<role>/SKILL.md` | Hermes reads it there. |
@@ -145,6 +145,8 @@ section of [USER_MANUAL.md](USER_MANUAL.md).
 | **[GETTING_STARTED.md](GETTING_STARTED.md)** | First-time user | Concepts, prerequisites, manual install, basic workflow |
 | **[USER_MANUAL.md](USER_MANUAL.md)** | Setting up a real team | Full install (maf), all harnesses, dispatcher, monitoring |
 | **[install.md](install.md)** | An AI coding agent | Interactive wizard: asks the user for harnesses/roles, runs `maf add` |
+| **[docs/sandbox.md](docs/sandbox.md)** | Running agents without approvals | Sandbox mode (macOS and Linux), the protected files, the limits, and the Lima VM |
+| **[docs/releasing.md](docs/releasing.md)** | Maintainer | Release a new gem version: version bump, tag, the release workflow, fixes |
 | **[docs/out-of-scope.md](docs/out-of-scope.md)** | Contributor | Requests that the project rejects on purpose, with the reason |
 | **[SKILL.md](SKILL.md)** | Agent skill loader | Self-contained portable skill (frontmatter + full API reference) |
 
@@ -162,7 +164,7 @@ multi_agent_flow/
   GETTING_STARTED.md          # first-time walkthrough (concepts + manual setup)
   USER_MANUAL.md              # full team setup reference
   maf.gemspec                 # the gem: files, version, the webrick dependency
-  Gemfile                     # development gems: rake, minitest, rubocop
+  Gemfile                     # development gems: rake, minitest, rubocop, mutant
   CHANGELOG.md                # changes per version
   exe/
     maf                       # the maf command line tool (gem install maf puts it on PATH)
@@ -185,22 +187,21 @@ multi_agent_flow/
     team_command.rb           # maf team: shows the team, or sets its budget
     retire.rb                 # maf retire: removes one worker and archives its state
     worker_control.rb         # maf worker: stops, starts, or restarts one worker
+    worker_list.rb            # maf worker list: shows the sessions and dispatchers that run
     flow/role_catalog.rb      # merges .maf/roles.yml over the built-in roles
     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
     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
+    shared/harnesses/         # one file per harness: commands, role file template, quirks
   scripts/
     check.rb                  # repo consistency check (UDA sync, markers, script signatures)
   templates/
     roles.yml                 # role definitions + model hints
     role-stub.yml.erb         # stub that maf role add writes
     workflows/                # default workflows: simple, plan-review, tdd, panel
-    opencode.md.erb           # role file templates per harness
-    claude.md.erb
-    codex.md.erb
-    hermes.md.erb
   assets/
     coord                     # coordination CLI (Ruby)
     dispatcher                # polls task board + inbox, starts one-shot agents (Ruby)
@@ -219,6 +220,7 @@ multi_agent_flow/
     maf_test.rb               # tests for the maf command
     dashboard_test.rb         # tests for the dashboard data
     dispatcher_test.rb        # tests for the dispatcher
+    harnesses/                # one test file per harness, and the contract test for all harnesses
     uninstaller_test.rb       # tests for uninstall.rb
     migrate_test.rb           # tests for migrate.rb
     roles_workflow_test.rb    # tests for project roles and the workflow
@@ -230,6 +232,7 @@ multi_agent_flow/
     hook_session_test.rb      # tests for session isolation
     hook_config_test.rb       # tests for project hooks
     worker_control_test.rb    # tests for maf worker
+    worker_list_test.rb       # tests for maf worker list
     untrack_test.rb           # tests for maf untrack
     analyst_test.rb           # tests for the analyst
     shared_test.rb            # tests for lib/maf/shared/
@@ -316,8 +319,8 @@ bundle exec rake build             # writes pkg/maf-VERSION.gem
 bundle exec rake install           # builds and installs the gem
 ```
 
-To release, change `Maf::VERSION` in `lib/maf/version.rb` and add a
-`CHANGELOG.md` entry.
+To release, bump `Maf::VERSION`, merge, then tag `main` with `vX.Y.Z` and push the tag.
+See **[docs/releasing.md](docs/releasing.md)** for the full steps, the one-time setup, and the fixes for a failed release.
 
 RuboCop (pinned in the `Gemfile`) uses `.rubocop.yml`. It sets the
 size rules: a class at most 100 lines, a method at most 5 lines and 4
@@ -335,6 +338,20 @@ them when you run a test file directly, so a test never writes to that board:
 env -u TASKRC -u COORD_DIR -u COORD_ROLE -u COORD_WORKER ruby test/coord_test.rb
 ```
 
+`rake mutant` runs the mutation tests with [mutant](https://github.com/mbj/mutant).
+Mutant changes the code in `lib/` and runs the tests again. A change that no test
+finds is an alive mutation: add a test for it. Mutant needs Ruby 3.3 or later.
+It is free for open source projects (`usage: opensource` in `.mutant.yml`).
+
+```sh
+bundle exec rake mutant                          # the subjects in .mutant.yml
+bundle exec rake mutant SUBJECT='Maf::Budget*'   # other subjects
+```
+
+Mutant runs only the test classes that name their code with `cover`. To add a
+subject, require `test/mutant_cover.rb` in the test file, add `cover "Maf::X*"` to
+the test class, and add `Maf::X*` to `matcher.subjects` in `.mutant.yml`.
+
 ```sh
 ruby test/coord_test.rb      # covers the coord CLI
 ruby test/installer_test.rb  # covers bootstrap.rb, flow.rb, setup_agent.rb
@@ -352,6 +369,7 @@ ruby test/dispatcher_test.rb         # covers the dispatcher
 ruby test/board_watch_test.rb        # covers the board watcher
 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/analyst_test.rb            # covers the analyst
 ruby test/shared_test.rb             # covers lib/maf/shared/

data/assets/agents-contract.md

@@ -31,6 +31,8 @@ coord claim ID | start-task ID | done ID     # take a task, check out its branch
 coord annotate ID TEXT                       # add a note to a task
 coord lesson ID dead_end|corrected TEXT      # an approach that failed, or the right way: the graph keeps it
 coord escalate [--task ID] TEXT              # a problem you cannot fix: the project manager asks the user
+coord block ID --kind K TEXT                 # you cannot finish: K is needs_input, dependency, or capability
+coord unblock ID                             # lead roles: the blocker is gone; the task returns to coord next
 coord msg --from A [--task ID] [--fyi] TO TEXT   # message a role or a worker; --task also notes the task
                                              # --fyi: no run starts; the next run of TO reads it
 coord broadcast --from A [--to workers|leads|all] TEXT

data/assets/analyst

@@ -20,9 +20,16 @@
 require "json"
 require "fileutils"
 require "open3"
+require "rbconfig"
 require "optparse"
 require "tmpdir"
 require "time"
+begin
+  require_relative "../lib/maf/shared/harness"
+  require_relative "../lib/maf/shared/sandbox"
+rescue LoadError
+  abort "analyst: the maf shared library is missing. Run maf update."
+end
 
 module Analyst
   HISTORY = 20
@@ -71,57 +78,14 @@ module Analyst
     Call.new(kind || command.sub(SETUP, "").split.first.to_s, text, size.to_i)
   end
 
-  # Transcripts reads the tool calls of one session from the files of the harness.
+  # Transcripts reads the tool calls of one session from the files of the
+  # harness (Harness#transcript_calls).
   module Transcripts
     def self.calls(harness, id)
       return [] if id.to_s.empty?
 
-      { "claude" => -> { claude(id) }, "codex" => -> { codex(id) }, "opencode" => -> { opencode(id) } }
-        .fetch(harness, -> { [] }).call
-    end
-
-    def self.lines(path) = path ? File.foreach(path).filter_map { |line| JSON.parse(line) rescue nil } : []
-
-    # Claude Code: a tool_use block, then a tool_result block with the same ID.
-    def self.claude(id)
-      events = lines(Dir.glob(File.join(Dir.home, ".claude", "projects", "*", "#{id}.jsonl")).first)
-      blocks = events.flat_map { |event| Array(event.dig("message", "content")).select { |block| block.is_a?(Hash) } }
-      sizes = blocks.select { |block| block["type"] == "tool_result" }
-                    .to_h { |block| [block["tool_use_id"], block["content"].to_s.size] }
-      blocks.select { |block| block["type"] == "tool_use" }
-            .map { |block| Analyst.call(block["name"], block.dig("input", "command"), sizes[block["id"]]) }
-    end
-
-    # Codex: a custom_tool_call or function_call, then its output with the same call_id.
-    def self.codex(id)
-      events = lines(Dir.glob(File.join(Dir.home, ".codex", "sessions", "**", "rollout-*#{id}.jsonl")).first)
-      payloads = events.map { |event| event["payload"] || {} }
-      sizes = payloads.select { |p| p["type"].to_s.end_with?("_output") }
-                      .to_h { |p| [p["call_id"], p["output"].to_s.size] }
-      payloads.select { |p| %w[custom_tool_call function_call].include?(p["type"]) }
-              .map { |p| Analyst.call(p["name"], codex_command(p), sizes[p["call_id"]]) }
-    end
-
-    def self.codex_command(payload)
-      text = (payload["input"] || payload["arguments"]).to_s
-      text[/cmd["']?\s*:\s*["']((?:[^"'\\]|\\.)*)/, 1] || text
-    end
-
-    # opencode keeps its sessions in a SQLite database. The sqlite3 CLI reads it.
-    def self.opencode(id)
-      db = File.join(Dir.home, ".local", "share", "opencode", "opencode.db")
-      return [] unless File.exist?(db) && id.match?(/\A[\w-]+\z/)
-
-      out, status = Open3.capture2("sqlite3", "-readonly", "-json", db, opencode_query(id))
-      status.success? ? JSON.parse(out.empty? ? "[]" : out).map { |row| Analyst.call(*row.values) } : []
-    rescue SystemCallError, JSON::ParserError
-      []
-    end
-
-    def self.opencode_query(id)
-      "select json_extract(data,'$.tool') tool, json_extract(data,'$.state.input.command') command, " \
-        "length(json_extract(data,'$.state.output')) size from part where session_id = '#{id}' " \
-        "and json_extract(data,'$.type') = 'tool'"
+      calls = Maf::Shared::Harness[harness]&.transcript_calls(id) || []
+      calls.map { |name, command, size| Analyst.call(name, command, size) }
     end
   end
 
@@ -169,8 +133,10 @@ module Analyst
 
   # Model sends the prompt to the analyst command and reads the hints.
   module Model
-    def self.ask(command, prompt)
-      out, err, status = Open3.capture3(MODEL_ENV, *command, stdin_data: prompt, chdir: Dir.tmpdir)
+    NEW_SESSION = [RbConfig.ruby, "-e", "Process.setsid; exec(*ARGV)"].freeze
+
+    def self.ask(command, prompt, coord)
+      out, err, status = run(command, prompt, coord)
       raise "#{command.first} failed: #{(err.empty? ? out : err).strip[0, 200]}" unless status.success?
 
       reply = JSON.parse(out) rescue nil
@@ -178,6 +144,18 @@ module Analyst
       [hints(reply["result"] || out), reply["total_cost_usd"]]
     end
 
+    def self.run(command, prompt, coord)
+      sandbox = Maf::Shared::Sandbox
+      wrapped = [*NEW_SESSION, *sandbox.wrap(command, harness(command), coord_dir: coord)]
+      run = -> { Open3.capture3(MODEL_ENV, *wrapped, stdin_data: prompt, chdir: Dir.tmpdir) }
+      sandbox.keeping_links(harness(command), coord_dir: coord, &run)
+    end
+
+    def self.harness(command)
+      name = File.basename(command.first.to_s)
+      Maf::Shared::Harness.all.find { |harness| harness.command == name } || Maf::Shared::Harness::Base.new
+    end
+
     def self.hints(text)
       data = JSON.parse(text.to_s[/\{\s*"hints".*\}/m].to_s)
       Array(data["hints"]).first(3).filter_map { |hint| clean(hint) }
@@ -214,9 +192,9 @@ module Analyst
       return puts(prompt) if @print
 
       write("running" => true)
-      hints, cost = Model.ask(command, prompt)
+      hints, cost = Model.ask(command, prompt, @coord)
       write("hints" => hints, "cost_usd" => cost)
-    rescue StandardError => e
+    rescue StandardError, SystemExit => e
       write("error" => e.message)
     end