herdr-mesh-safe

一个用于在 Herdr 中协调编码智能体的安全作用域 MCP 桥接器。

本仓库是 runchr-works/herdr-mesh 的一个分支。它保留了上游的 MCP/Herdr 集成，并将不受限制的终端生命周期替换为语义等待和租约作用域的评审者与写入者。

当前包版本：0.1.0-safe.13。

该分支存在的原因

编排智能体需要检查工作进程、发送任务、等待结果，并回收已完成的能力。让该智能体拥有任意的终端命令、原始的按键注入或未作作用域划分的窗格删除，会带来不必要的权限。

该桥接器只暴露协调器所需的操作，同时保留以下不变式：

• 不接受调用方提供的 shell 命令或不受限制的终端执行；

• 没有原始的 send-keys；

• 没有未作作用域划分的窗格、标签页、工作区或会话删除；

• 控制器凭据在桥接器提示和生命周期请求之前立即检查；

• 每次向保留智能体发出的提示，都仅在所有生命周期和交接回执存储被锁定后才被允许；

• 结果收集绑定到确切租用的窗格和所接受的提示游标；

• 自动关闭要求观察到一个空闲/完成状态，并且在输出捕获期间状态游标不变；

• 评审者只能通过与其创建的租约一起关闭；

• 写入者只能在链接的 Git 工作树中的非受保护分支上启动；

• 并发的写入者不能租用重叠的路径作用域；

• 释放写入者时保留其分支、工作树和字节。

该桥接器是一个技术安全边界。它不决定 GitHub Issue、规范、所有权声明、提交、合并、迁移或部署是否被授权。协调器和目标仓库约定仍然具有权威性。

Related MCP server: MCP Files

架构

MCP client
   │ stdio
   ▼
herdr-mesh-safe
   ├── semantic Herdr waits and prompts
   ├── exclusive controller lease and fence
   ├── reviewer leases
   ├── writer lane leases
   ├── content-free handoff receipts
   └── read-only Git preflight
          │
          ▼
      Herdr CLI → Herdr socket → managed panes and agents

租约记录以模式 0600 存储在 Git 之外，路径为：

${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/reviewer-leases
${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/writer-leases
${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/adopted-pane-leases
${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/controller-leases
${HERDR_MESH_STATE_DIR:-~/.local/state/herdr-mesh}/handoff-receipts

治理适配器

写入者工具要求一个外部治理流程接受工作、声明所有权并记录持久的检查点。在启用写入者之前，请阅读 governance integration contract。

GitHub 控制平面示例 展示了一个使用 Issues、GitHub Project、PR 和无内容检查点的实用适配器。GitHub 只是一个示例，不是桥接器的依赖。完整的工具输入可在 manifest.json 中找到。

可选的 agent-control-skills 包为该治理边界提供了可复用的协调器指令。桥接器不会安装这些技能，也不会从它们那里继承权限。

暴露的工具

控制器生命周期

在任何提示、评审者、写入者或清理变更之前，先获取或恢复项目控制器。返回的租约 ID 和栅栏令牌是短暂能力：将它们传递给变更工具，但不要在跟踪器、提交、日志或交接中发布它们。只读的库存和等待工具在没有控制器租约的情况下仍然可用。默认租约持续 15 分钟，在长时间协调轮转中必须续期。 herdr_bridge_status 还会将每个保留锁报告为 absent、active、stale 或 indeterminate，而不暴露其所有者 PID、锁 ID 或控制器凭据。外来主机锁被故意标记为 indeterminate；桥接器不会在基于超时猜测的情况下窃取它。

协调

稳定等待上的 after_seq 防止来自早期工作的终端状态满足新的等待。单个长 MCP 请求取代重复的客户端轮询；不需要 SSE 侧信道。 对于已租用的智能体，提示准入首先要求确切的稳定身份，然后在提交前记录交付前的游标。回执绑定窗格、名称、智能体类型、工作目录、生命周期租约和游标。中继仅在 Herdr 确认该确切身份在下一个游标处进入 working 后才返回。生成的回执是一个不透明的查找键；它不包含栅栏、提示或输出。在该回执完成、失败或被显式放弃之前，对该目标的任何后续提示都会被拒绝。已经处于 closing 或 releasing 状态的租约也会拒绝新提示。

批处理交接在提交任何提示之前，会在相同的控制器栅栏和生命周期保留下验证每个目标。每个批处理目标必须有一个有效的已保留租约；未租用的遗留目标会被拒绝。 mode=all 按请求顺序返回结果。mode=first 仅取消失败的 CLI 等待；其他智能体继续工作并作为 pendingReceipts 返回。收集需要这些令牌，严格等待所接受的 working 游标之后，并在输出捕获后重新读取身份和序列。因此，后续任务的输出会被拒绝而不是被错误标记。已完成的回执可以在调用方崩溃后仅在其确切稳定身份和游标仍然有效时重放。模糊的交付保持为一个阻塞的 reserved 回执。操作员只能使用 herdr_handoff_receipt_abandon、有效的控制器权限以及对确切租用智能体已稳定的新观察来释放它。

控制器 CLI

herdr-agent-control 是一个本地 CLI，用于已经持有活动控制器租约的命名协调器。启动器必须在被管理的协调器环境中将 AGENT_CONTROL_CONTROLLER_ID 设置为该控制器的稳定 ID。status 和 receipts 是只读的，不会加载栅栏。变更命令仅在匹配当前 Herdr 窗格、智能体名称、类型、工作目录以及 Linux 进程祖先与在获取/恢复时记录的控制器进程之后才加载租约。栅栏永远不会出现在参数或输出中。

herdr-agent-control status
herdr-agent-control receipts
herdr-agent-control ask TARGET -- MESSAGE
herdr-agent-control ask-many --request TARGET=MESSAGE --mode first
herdr-agent-control collect --receipt TOKEN
herdr-agent-control abandon --receipt TOKEN

ask 和 ask-many 使用回执绑定的批处理协议。collect 从不提交提示。abandon 不会停止进程；它只在确切目标被观察到稳定后释放准入屏障。在引入进程绑定之前创建的控制器租约必须被恢复一次，变更 CLI 才能使用它们。CLI 不会启动、关闭、停止、删除、提交或执行任意终端命令。

当前控制器租约故意绑定到被管理的 Herdr 窗格中的命名智能体。Herdr 之外的 MCP 客户端可以使用只读库存和等待工具，但在此版本中无法获取或行使协调权限。支持外部协调器需要单独的身份验证调用者身份；它绝不能冒充窗格或传递自声明的身份。 进程祖先是一种针对协作的单用户主机模型的失败关闭的调用者绑定，而不是对具有相同 Unix 账户且有权重写模式 0600 状态文件的恶意进程的隔离。

评审者生命周期

评审者身份包括控制器、智能体名称和类型、窗格以及工作目录。当观察到 working、blocked、未租用或身份漂移的窗格时，它们会被保留。新创建的标签页可以在其根 shell 接受智能体之前存在；桥接器仅在相同的已租用窗格中为确切的 agent_pane_busy 就绪条件重试一个有限窗口。其他启动错误会失败关闭。 对于 Claude 评审者，启动清单可能传递显式的 model 和 effort；这些值会在 -- 之后成为原生 Claude CLI 参数。其他智能体类型在有经过审查的提供者适配器之前会拒绝显式模型参数。

写入者生命周期

主机验证

验证配方是来自租赁仓库的代码。它们在 Linux Bubblewrap 沙箱中运行，使用固定参数且无网络。它们不是针对已拥有相同主机用户的代理的安全边界。可选 Web 引导使用已提交的锁文件，允许包下载，并禁用包生命周期脚本。Python 引导可以从显式命名的 requirements.lock 文件预热运行本地的 uv 缓存；每个锁必须是常规的非符号链接文件，其字节与接受的基线提交匹配，且其完整依赖图具有 SHA-256 哈希。桥接器以只读方式挂载基于基线的副本，忽略通道本地的 uv 配置，禁用源码构建，并在网络可用时使用 uv pip 而不启动 Python。最终门禁保持离线并使用相同的隔离缓存。当主机解析器是 /etc 外部的符号链接时，启用网络的引导仅以只读方式挂载其解析后的文件；离线门禁仍使用单独的网络命名空间。

旧版窗格租约

在桥接器之外创建的旧版代理保持无主状态，直到协调器通过仅清理租约采用它们。采用会验证确切的命名代理、窗格、类型、工作目录、已稳定状态游标、持久权限和受保护窗格。它不授予 Git 所有权或实现权限。

写入者准入要求：

• 持久的票据和权限引用以及接受的 SHA-256 摘要；

• 绝对链接的 Git 工作树，而非仓库的主检出；

• 确切的分支、基线提交、HEAD 和 Git 状态摘要；

• 至少一个受保护分支，通常是配置的默认分支；

• 字面意义上的仓库相对拥有的作用域，不含通配符或 ..；

• 显式锁定的作用域；

• 工作树中不存在现有的 Herdr 代理；

• 没有针对分支、工作树、重叠所有权或锁定作用域的保留租约。

预留和释放使用原子存储锁。崩溃可能故意留下需要检查的保留预留；它绝不能仅仅为了自动恢复而允许两个写入者。 在 Linux 上，新的预留锁包含启动 ID 和进程开始时间，因此重启或重用 PID 会被识别为过期。herdr_bridge_status 将模糊的旧版或外部主机锁暴露为 indeterminate；在手动恢复之前检查这些锁，而不是按年龄删除它们。

只读拓扑和发现

安全配置文件还暴露只读的会话、窗格、标签页、工作区和集成检查。原始生命周期工具仍由 src/server.ts 中的允许列表过滤。

要求

• Linux 或 macOS，Node.js 18 或更新；主机验证额外需要 Linux 和 Bubblewrap；

• Git；

• 已安装并运行的 Herdr；

• 你计划启动的每种代理类型的 Herdr 集成；

• 支持 MCP 的客户端，如 Codex、Claude Code 或 OpenCode。

安装前检查 Herdr：

herdr status
herdr integration status

安装缺失的集成，例如：

herdr integration install codex
herdr integration install claude

从源码安装

git clone https://github.com/nativestrider/herdr-mesh-safe.git
cd herdr-mesh-safe
npm ci
npm test
npm run build

编译后的 MCP 入口点是 dist/index.js。

Codex

将此添加到 ~/.codex/config.toml，使用绝对克隆路径：

[mcp_servers.herdr-mesh]
command = "node"
args = ["/absolute/path/to/herdr-mesh-safe/dist/index.js"]

Claude Code

claude mcp add -s user herdr-mesh node /absolute/path/to/herdr-mesh-safe/dist/index.js

OpenCode 或其他 MCP 客户端

注册一个名为 herdr-mesh 的本地 stdio MCP 服务器，使用：

command: node
arguments: /absolute/path/to/herdr-mesh-safe/dist/index.js

安装后或每次桥接器更新后重启 MCP 客户端。同一进程内的 /clear 或新对话不会重新加载已运行的 MCP 服务器。

可选环境

MCP 进程必须能够访问与受管理工作区相同的 Herdr 套接字。已在 Herdr 内运行的协调器可以使用 Herdr CLI，但桥接器仍提供更窄的权限、事件式等待和验证的生命周期。

如何使用

用户通常与协调器对话，而不是直接调用工具名称。

等待多个代理

Wait for the first active worker to become idle, done, or blocked. Use each
worker's last state-change sequence so an old idle state is not accepted.

协调器使用 herdr_agent_wait_any 并在一个结果中接收第一个终端状态以及可见输出。

运行只读外部审查

Create a leased Claude reviewer in a dedicated tab rooted at the ticket worktree, ask it to review the
exact PR head against Standards and Spec, wait for its result, then reclaim the
reviewer pane if it is idle or done.

预期顺序是：

1. herdr_controller_acquire 或 herdr_controller_resume

2. herdr_owned_reviewer_start 使用相同的控制器租约/围栏，对于 Claude，使用确切的模型/努力程度

3. herdr_relay 使用相同的控制器租约/围栏并保留其收据

4. herdr_collect_handoffs 使用该收据

5. herdr_owned_reviewer_close 使用相同的控制器租约/围栏

启动写入者通道

协调器首先根据持久项目状态验证接受的票据/规范、依赖项、所有权、锁和集成顺序。然后收集确切的本地证据，包括：

git -C /absolute/worktree rev-parse HEAD
git -C /absolute/worktree status --porcelain=v1 --untracked-files=all | sha256sum

它使用该证据调用 herdr_owned_worker_start。该工具独立重新读取 Git，预留所有权，创建专用的无焦点标签页，在其根窗格中启动代理，并在返回活动租约之前验证其身份。

桥接器不将文件系统写入限制在声明的作用域内。协调器仍必须将最终更改的路径和差异与租约、票据和仓库契约进行比较。

释放写入者

释放前，记录一个无内容的持久检查点，包含当前分支、HEAD、脏状态摘要、完成的证明、阻塞项和下一步操作。然后使用检查点引用和摘要以及新观察到的代理状态游标和 Git 值调用 herdr_owned_worker_release。

释放仅关闭租用的窗格。它不提交、暂存、重置、清理、删除或修改工作树。

Herdr 当前的 pane close 命令不接受预期的代理状态或游标。因此，桥接器在请求关闭之前立即检查身份、稳定状态、游标稳定性和控制器权限，但最终检查和 Herdr 关闭不是原子操作。关闭开始后，不要发送手动 Herdr 提示或以其他方式重用该窗格。条件关闭需要 Herdr 本身的支持。

刻意限制

• 独立克隆在此版本中不被接受为写入者通道；请使用链接的 Git 工作树。

• 在租约之前创建的现有工作代理不会自动采用。

• 桥接器无法证明 GitHub Issue 授予权限。

• 所有权在准入和最终协调期间检查；它不是操作系统文件系统沙箱。

• 控制器围栏和游标检查防止过时的桥接器操作，但 Herdr 不会将这些检查与提示传递或窗格关闭原子地组合。同用户直接 CLI 活动仍在此边界之外。

• 人工对话框和 blocked 代理仍是人工决策。

• 提交、推送、PR、合并、部署、迁移和运行时权限仍在此桥接器之外。

开发

npm ci
npm test
npm run build
npm audit --omit=dev

测试涵盖已安装的 Herdr CLI 参数契约、游标感知等待、控制器围栏和接管、批量租约身份、沙箱解析器绑定、审查者租约、写入者所有权冲突、受保护分支、Git 状态摘要和检查点释放。

构建的 dist/ 目录已提交，以便客户端无需 TypeScript 工具链即可运行桥接器。先更改源码，运行上述完整命令，并一起提交源码、测试、锁文件和生成的输出。

上游和许可证

基于 runchr-works/herdr-mesh，上游提交 54adef5。上游仍是通用 Herdr MCP 传输和安装程序的来源；此分支拥有安全允许列表、语义等待和租约生命周期。

根据 MIT 许可证授权。参见 LICENSE；保留上游版权声明。