codex-master

The Hive（旧名称：codex-master、codex-master-mcp 和 Masterjet）是 本地 MCP 控制平面，用于管理一个休眠/可扩展的 Codex Agentinnen 舰队。 Fleet Registry 对活动系列具有权威性；旧版池规范仅为兼容性而保留。

版本化的本地 Wiki 源从 docs/wiki/Home.md 开始。 它们在此仓库中保持权威性；不暗示任何 GitHub Wiki 发布。 Fleet-Overview、G-Serie 和 Goddess-Reporting 契约：docs/operations/goddess-reporting.md。

资源监视器 H4 操作员生命周期

codex-master-resource-monitor.service 运行无参数的 %h/.local/bin/codex-master-resource-monitor 入口点。它仅接收 集中组合的 Hive 状态存储，并在其固定的 resources 子树下发布完整的一赫兹生成。 H4 生命周期与主安装分离。

默认情况下，codex-master-resource-monitor.service 会被交付但不会安装或激活。没有安装程序、MCP 工具或标准测试会隐式启用或启动此单元；只有以下显式操作员命令才会这样做：

./bin/codex-master-mcp install-resource-monitor --force
./bin/codex-master-mcp resource-monitor-status

安装程序在变更前验证两个有界常规仓库单元和两个目标单元。一个协作进程锁（install_lock()/flock）覆盖源验证、暂存、事务、守护进程重载、激活和回滚。它序列化协作安装进程；此边界之外的相同 UID/root 或 User-Systemd 命名空间操作不属于 H4 覆盖的对抗性互斥威胁。 源读取使用无跟随 FD，并在有界读取前后进行身份/类型/大小/模式/mtime 检查。目标目录链仅为缺失的后缀安全创建，然后通过 FD 加 (dev, ino) 固定；不安全的祖先、符号链接或组/全局可写的现有目录会安全失败。允许共享粘滞位祖先；最终 ~/.config/systemd/user 必须由用户拥有且非组/全局可写。

两个单元在首次变更前都经过暂存和验证。现有单元通过 FD 相对方式移动到唯一的已检查备份。暂存单元使用无替换 link 安装；EEXIST 保留外部目标。每个单元的日志记录原始/暂存身份、持久性、移动、恢复和清理。回滚仅移除已记录日志的已安装身份，无覆盖地恢复备份，保留外部文件/备份，并在需要时报告手动恢复。回滚期间不推断任何字节或模式。

在两个单元变更持久化后，安装程序以无跟随方式重新打开原始目标路径，并在守护进程重载前以及 enable --now 前重新验证固定的 (dev, ino)、持有的规范锁身份以及两个已记录日志的已安装单元身份。任何不匹配都会禁止下一个外部操作，包括回滚重载/状态猜测；文件回滚仅使用固定的 FD。父级重新绑定意味着不进行主重载，并通过原始 FD 进行回滚。守护进程重载在启用/启动之前运行，且仅启用/启动 codex-master-resource-monitor.service；切片永远不会被单独启用/启动。

这不是原子配对替换。每个操作按文件/名称是原子的，但两次重命名之间的崩溃可能留下混合配对。进程日志在内存中，崩溃时丢失。恢复仅使用文件系统证据、单元/systemd 状态、resource-monitor-status 以及手动检查/恢复。状态检测到混合或外部状态时，操作员必须手动恢复。回滚独立尝试两个单元、临时/备份清理、守护进程重载、UnitFileState 恢复和 ActiveState 恢复。未知状态不进行猜测。初始 not-found 仅在 LoadState=not-found 非活动时有效；否则 UnitFileState 必须为 disabled、enabled 或 enabled-runtime，且 ActiveState 必须为 active/inactive。状态恢复使用精确的持久与运行时标志，并且永远不会在 UnitFileState 失败后跳过 ActiveState 恢复。公共错误仅包含代码/返回码，绝不包含路径或原始输出。

清单存在不等于钩子信任。缺失、格式错误、非规范或过时的 V2 原生覆盖报告 manual_hook_trust_or_new_session_required；只有在用户显式 /hooks 信任后的新常规 Codex 会话才会创建新的 V2 覆盖。没有命令自动化信任或编辑合成原生状态。

非活动的无子进程 codex-master.slice 仅在具有真实 FragmentPath 和物化单元时才符合预期。缺失或合成的 FragmentPath 是阻塞项，而非已安装状态。就绪状态要求两个单元都有真实片段、活动监视器子进程以及新鲜有效的快照。仅当 resource-monitor-status 为绿色时才提供实时生成。主 install 行为不变。ProtectHome=tmpfs 和 PrivatePIDs=yes 隐藏无关的 Home 和进程数据。BindReadOnlyPaths 仅暴露已安装的监视器布局、固定目录和中央 Hive 状态；D8 将写访问限制为 resources 和现有锁。

• /home/teladi/.codex-agents/a1 至 /home/teladi/.codex-agents/a100

• /home/teladi/.codex-agents/b1 至 /home/teladi/.codex-agents/b100

• /home/teladi/.codex-agents/c1 至 /home/teladi/.codex-agents/c100

旧版选择器 a 和 b 映射到 a1 和 b1；both 映射到 a1,b1。 系列选择器 a-series、b-series、c-series 和 all 可用于 状态、技能、能力、租约状态、启动/停止和看门狗调用。 选择器不区分大小写，因此 A1、a1、A-Series 和 a-series 解析结果相同。数字单 Agentin 选择器使用当前选择器策略。默认策略是 A/B 交替：1=a1、2=b1、3=a2、 4=b2，依此类推。使用以下命令更改：

./bin/codex-master-mcp selector-policy --series a,b,c
./bin/codex-master-mcp selector-preview --series a,b,c --limit 6

该策略存储在私有 MCP 状态中，也可以通过 CODEX_MASTER_AGENT_SELECTOR_SERIES=a,b,c 为进程覆盖。 Teamleiterinnen 可以通过 Masterjet 直接生成 fremde Bienen，使用 agent_start、agent_claim 和结构化的 agent_assign* 工具。租约、 认证检查和写入范围是协调边界；它们不是避免使用可用 fremde Bienen 的理由。 原始认证的 home 保留为 a1 和 b1。其他 home 有意保持精简且默认休眠；它们有自己的 CODEX_HOME、包装器、配置、tmux 会话名称、租约和元数据，而 大型只读为主的技能/插件/模型缓存文件可以从系列模板符号链接。C 系列 home 在另一个 账户可用之前有意保持未认证状态。

包装器通过每个 home 的 codex 启动器文件启动实例。 在中央解析提供有效元组之前，其基础默认值为 gpt-5.6-luna，推理级别为中等：

--model gpt-5.6-luna -c 'model="gpt-5.6-luna"' -c 'model_reasoning_effort="medium"' --yolo -s danger-full-access --search

它使用 tmux 作为 PTY 后端。完整终端输出仅写入 ~/.local/state/codex-master-mcp/raw/ 下的本地状态文件。新的原始日志默认限制为每个文件 5 MiB，受管理的原始日志目录默认最多保留 20 个文件。准备好的原始日志文件以无跟随独占语义创建。直接原始日志写入器还要求受管理的状态目录及其父链是真实目录而非符号链接，并且当旧版原始日志目录是符号链接时会被忽略。Agentin 运行器必须是常规可执行文件，而非符号链接。分配日志读取要求常规文件、有大小上限，并使用通用错误。私有状态文件和目录错误是通用的，避免返回本地状态路径。Agentin 元数据存在性检查不跟随符号链接，元数据读取拒绝符号链接和超大文件，元数据读取错误使用通用标记而非本地文件路径。安全尾部日志读取忽略非常规原始日志目标。Tmux 控制错误在返回或抛出前会被脱敏并限制大小。MCP 工具响应默认不返回原始输出，并仅暴露原始日志存在性而不返回本地原始日志路径。文本通过 tmux 粘贴到 Codex TUI 中，并以普通 Enter 提交。多行提示使用括号粘贴标记，因此完整提示在提交前保持为一条 composer 条目。

在粘贴之前，send、assign-* 和 report-request 会短暂等待当前可见窗格尾部出现可识别的 Codex TUI 输入提示标记。如果 Agentin 仍处于启动警告状态、仅显示起始文本，或没有可见的输入提示，则变更以可重试的 agent_input_not_ready、paste_attempted: false 和 raw_output: not_returned 失败关闭，而不是将提示丢失到启动屏幕中。

旧 codex-agent-mcp 状态目录下的现有元数据仍会作为迁移回退被读取。外部 tmux、git 和 codex mcp 子进程都有超时限制，因此 MCP 调用会失败关闭而不是无限挂起。MCP 注册检查比较 codex mcp get 中的精确 command: 字段，而不是命令输出中的宽泛子字符串。

对 tmux 会话进行变更或发送的 Agentin 生命周期操作按 Agentin 使用私有无跟随锁文件进行串行化，因此不同的 Agentinnen 仍可独立运行，而同一 Agentin 的并发启动/停止/发送不会交错。如果 tmux new-session 在此进程创建会话之前失败，清理仅移除准备好的原始日志，不会杀死可能属于另一个 MCP 进程的现有会话。

变更工具还使用每 Agentin 租约，因此两个 Codex-CLI 实例不能同时静默分配或发送到同一 Agentin。租约冲突返回结构化重试元数据（error_code、retryable、retry_after_seconds 和剩余租约秒数），而不暴露客户端身份。agent_claim 在 fremde Biene 忙碌时默认无限重试；有限的 wait_seconds 值仍然可用，但不会被限制在 600 秒。使用 --no-wait 进行单次立即声明尝试。默认轮询间隔为 30 秒，最大轮询间隔为 900 秒。

显式声明还会在 Agentin 不再运行、没有进程使用该 Agentin 主目录且本地空闲证据至少 120 秒旧时，恢复外部持有的租约。这种停止孤儿恢复可通过 --no-recover-stopped 禁用；它不适用于隐式发送/报告/中断变更，也绝不会覆盖运行中的外部 Agentin。

短生命周期 CLI 调用在 Codex 提供 CODEX_THREAD_ID 时从中派生稳定的隐藏所有者，因此同一 Schwesterinstanz 可以在单独的 CLI 调用中声明、分配、请求报告和释放。CODEX_MASTER_MCP_INSTANCE_ID 仍作为受控会话的显式覆盖。派生身份永远不会在公共响应中返回。

agent_start 仅使用瞬态的新租约，并在成功启动后释放它，因此短生命周期的本地 CLI 命令不会阻塞下一个操作员命令。当连接的 Codex-CLI 实例应在启动后保留 Agentin 时，请显式使用 agent_claim。

解析到超过 6 个 Agentinnen 的变更启动/停止选择器会失败关闭，除非传入 allow_broad_selector=true。这防止意外的 all/系列操作启动或停止池的大部分。工作变更默认要求每个 Agentin 有常规的 auth.json：agent_start、agent_claim、agent_send、agent_interrupt、agent_assign、agent_assign_readonly、agent_assign_live_data、agent_assign_write 和 agent_report_request 在认证缺失、是符号链接、不是常规文件、不可读或过大时失败关闭。状态/技能/能力/租约/池/停止/释放仍可用于诊断和清理。仅对显式登录/引导流程使用 --allow-unauthenticated。

对于 ChatGPT 认证，状态还会在存在时检查 JWT 访问令牌过期。过期的访问令牌报告为 access_token_expired，并阻止新的变更，直到该 Agentin 重新登录。将同一个轮换的 ChatGPT 刷新令牌复制到多个 Agentinnen 不受支持；每个 Agentin 需要自己的登录。

agent_status 分类有界窗格/日志文本而不返回它，因此调用者可以区分可能的每日、每周、令牌、配额或速率限制与普通的"尚无响应"状态。分类保持默认 Agentinnen 模型限制与 Spark 写入模型限制分开，并仅报告元数据加上 evidence: not_returned。限制元数据区分正在运行的会话模型、最新分配模型和为检测到的限制推断的模型。它还将已知的 Codex TUI 起始/占位符上下文分类而不返回窗格文本，因此调用者可以判断 Agentin 是否未将分配作为生产性输入接收。

公共 status、skills、capabilities、app-bridge-status、plugin-status、namespace-status、release-status、watchdog-status、timeout-policy 和 doctor 响应不返回本地 Agentin 主目录、运行器、仓库、清单或工作目录路径；它们返回状态/类别元数据，如 path_state、home_kind 和 cwd_state。

公共范围检查、工作树状态、命令摘录和分配审计读取也会脱敏绝对本地路径；分配提示仍接收 Teamleiterin 分配的显式路径。

agent_wait 允许调用者等待活动、进程退出或分类限制，而不会自动接收 Agentin 输出。它默认为 120 秒，每次调用上限为 10 分钟。其轮询间隔默认为 30 秒，上限为 900 秒。

分配是异步的。agent_wait 和 agent_report_request 在顶层暴露相关的 assignment_id。使用该 ID 调用 agent_assignment_report 以接收一小段去除 ANSI、脱敏的终端摘录。这是显式输出边界；分配元数据和等待结果保持数据稀疏。

fleet_watchdog 检查空闲 Agentinnen 而不读取原始输出。它默认为 60 秒空闲阈值，并在任何升级前要求 Agentin 提供简明报告。报告宽限期默认为 15 秒，因此下一次 systemd 定时器传递只能在 Agentin 有一个间隔报告后才能升级。安装的 systemd 监督器使用 --action stop，因此未使用的 Agentinnen 被放回睡眠状态而不是保持活动。默认情况下，看门狗仅变更当前服务器租用的 Agentinnen；systemd 监督器使用 --manage-unclaimed --quiet 处理未声明或过期的租约，同时跳过其他客户端持有的活动租约，并避免在用户日志中产生成功的 JSON 噪音。

每次舰队看门狗运行都会为受管理的进程主目录和 tmux 会话创建一个不可变的内存舰队快照。Agent 评估重用该快照；独立的 agent_status 调用保留旧版实时查询回退。租约释放路径在释放前立即重新验证实时会话/进程身份。不可用的 tmux 观察报告为未知并跳过看门狗操作；它永远不会被解释为已停止的会话。

usage-watchdog 消费 codex-usage 快照状态，写入本地 codex-usage 块标记，并停止其账户具有未来已验证重置的运行中 Agentinnen。已过去的已验证重置清除块；未知重置保持失败关闭。agent_start、声明、发送和报告请求流程拒绝使用被阻止的 Agentin，直到看门狗再次释放它。

Related MCP server: claude-code-mcp

舰队账户、系列和 Gemini 无头作业

舰队注册表是每个提供商支持的系列和原生 A/B/C 物化的真相来源。该项目规范名称为 The Hive；上述旧名称仍是有效别名。首先使用只读账户/系列视图，然后通过仅标准输入的 CLI 流程在本地同步凭据：

python3 -m codex_master.server fleet account list
python3 -m codex_master.server fleet series list
python3 -m codex_master.server fleet provider-models --provider ollama_local
python3 -m codex_master.server fleet account sync-env --first-key 1 --last-key 30

密钥可在控制中心或标准输入流程中临时输入，但绝不会显示、持久化在 UI 状态中，或由 UI 或正常 MCP 输出返回。它们仅存储在私有 sidecar 中，绝不是注册表、分配或 shell 历史的一部分。账户门禁要求配置的密钥和成功的准入检查。过时或未知的 Gemini 探测在调用时检查一次，因此相邻项目不会使此项目过时。Gemini RPM/TPM/RPD 观察是项目范围的；计费层级和支出上限仍可能由计费账户共享。提供的 AI Studio 导出确认 the-hive-1 和 the-hive-2 为 Tier 1，the-hive-3、the-hive-4、the-hive-6 和 the-hive-10 为 Tier 0。这是项目范围的证据；本地账户组不用于推断项目的层级。精确的 RPM/TPM/RPD 限制仍是模型和项目特定的；已知值仅为在提供的快照中具有速率限制表的项目导入，未知值永远不会在本地猜测。Tier 1 的文档化支出保护为每滚动 10 分钟 $10，其计费账户上限为每月 $250。本地使用计算器报告观察到的 RPM/TPM/RPD，现在对已知项目/模型对使用提供的 AI Studio 快照。它保持限制为模型特定，并在不存在适用快照时返回 model_required 或 limits_unknown_dashboard_required。支出利用率仍为 billing_export_required，因为仅 API 密钥不暴露计费支出。

导入的速率限制快照：

快照来源是提供的 Tier 0 (kostenlos).mhtml 和 Tier 1 (Billing).html；当 AI Studio 更改活动项目限制时刷新它。

fleet_gemini_bootstrap_plan 仅作为无密钥的兼容性干计划辅助工具。它不创建已退役的 D/E/F 系列；运行时激活来自私有令牌文件中填充的 The_Hive_N 条目。密钥 1–10 属于一个计费账户，每个密钥一个项目；密钥 11–20 和 21–30 保留给接下来的两个账户，仅在其值存在时激活。可选安装程序仅使用官方稳定包通道：

NPM_CONFIG_PREFIX="$HOME/.local" ./scripts/install-gemini-cli
"$HOME/.local/bin/gemini" --version

安装程序拒绝不可写的系统 NPM 前缀，而不是提升权限；如上所述设置显式的用户拥有的 NPM_CONFIG_PREFIX。

Gemini 任务使用代理私有的 HOME/GEMINI_CLI_HOME、仅标准输入的任务输入、有界的 stream-json 标准输出/标准错误、进程组取消，以及按角色区分的审批（Exploriererinnen 使用 plan，Arbeitsbienen 使用 auto_edit）。CLI 被显式置于无头模式，并带有空的 --prompt；实际任务仍仅通过标准输入提供。它们不使用 yolo、-p - 或 Codex TUI 标记。分配响应是有界的并被解析。提示词、凭据、工具事件和原始输出不会进入持久化元数据；进程输出保持有界。

生产性无头分配每次调用最多接受 7200 秒（120 分钟）；默认值仍为 600 秒。

对于注册表模型为 auto 的 Gemini 系列，Masterjet 将无头 CLI 固定为 gemini-3.1-flash-lite，这是结构化 Bauplan 审计的低成本/高 RPM 默认模型。仅当某个系列显式配置了更重的模型时，才会使用该模型。

每个 Gemini API 探测或无头任务还会占用一个持久的按项目请求预留。预留仅允许一个活动请求，跨进程和重启强制 60 秒的最小间隔，并在验证到 429 后应用指数退避（从 15 分钟开始，上限为 24 小时）。私有状态存储在 fleet/rate-limits.json 中；格式错误的状态会失败关闭并被隔离，而不是允许另一个请求。

无 GTK 的 fleet_control 视图模型和 control_center 控制器强制执行与服务器相同的边界和生成检查；可选的 GTK3 页面被延迟加载，因此无头导入保持无显示。Cinnamon 适配器使用快照模式 v3，每个系列页最多 26 个系列和 25 个可见行；受限行仅包含状态。真实提供商凭据、账户探测、Ollama 资源准入和桌面会话接受仍然是显式的本地门控。Ollama 系列保持 simple_only，并拒绝复杂或更改仓库的任务。它们配置的独立双代理资源上限和主机压力门控被强制执行；全局十 Bee 上限仍然是一个额外的上界。

工具

• agent_start：启动选定的 Agentinnen；当 all/系列选择器解析到超过 6 个 Agentinnen 时，需要 allow_broad_selector=true

• agent_status：结构化状态、响应状态和限制分类，不包含原始输出

• agent_lease_status：选定 Agentinnen 的数据稀疏租约状态

• agent_status、agent_lease_status、agent_skills、agent_skill_match 和 agent_capabilities 上的宽泛只读选择器使用 agents_limit/agents_offset 分页；默认页面大小为 30 个 Agentinnen，响应包含 total_count 和 truncated 元数据。

• agent_claim：认领或续订一个 Agentin，当她忙时默认无限重试；显式认领可以在宽限期后恢复已停止的孤儿租约

• agent_release：释放此 MCP 客户端的 Agentin 认领；仅在检查状态后强制释放

• agent_wait：等待活动/停止/限制元数据，不包含原始输出，默认 120 秒，每次调用上限 10 分钟

• fleet_watchdog：请求空闲 Agentinnen 的报告，等待宽限窗口，然后可选地中断、停止或释放，不包含原始输出

• usage_watchdog：将 codex-usage 限制块与本地 Agentin 状态同步，停止被阻止的运行中 Agentinnen，并在 codex-usage 看门狗释放它们后清除本地块标记

• agent_send：向一个运行中的 Agentin 发送文本

• agent_interrupt：向一个运行中的 Agentin 发送 Ctrl-C

• agent_stop：停止选定的 Agentinnen；当 all/系列选择器解析到超过 6 个 Agentinnen 时，需要 allow_broad_selector=true

• agent_safe_tail：显式有上限、去除 ANSI、经过编辑的摘录；在读取窗格或日志输出之前，拒绝其他客户端持有的活动租约；日志源仅读取常规原始日志文件

• agent_skills：数据稀疏的技能清单，不包含文件内容

• agent_skill_match：检查一个或所有 Agentinnen 是否具有指定技能

• agent_capabilities：汇总的模型、技能和策略能力，带有有界的插件页面

• agent_scope_check：验证写入路径保持在分配范围内

• agent_assign：结构化、技能感知的分配，带有显式边界

• agent_assign_readonly：只读 Exploriererin 分配的快捷方式

• agent_assign_live_data：只读 Web-/Live-Daten 分配的快捷方式，需要当前来源或显式的工具/访问限制报告

• agent_assign_write：Arbeitsbiene 写入分配的快捷方式

• agent_assignments：数据稀疏的分配审计日志

• agent_last_assignment_status：一个 Agentin 的最新分配元数据

• agent_report_request：请求一个 Agentin 提供简明报告

• agent_assignment_report：读取已知分配的有上限、经过编辑的摘录

• agent_selector_policy：显示或设置序数选择器策略，例如 a,b 或 a,b,c

• agent_selector_preview：预览数字选择器映射，不改变状态

• agent_selection_preview：通过只读的 Selection-/Admission-Kern 预览真实舰队候选；Shadow 仅计划但从不执行。在提供权威 Hive 回调和特定于操作的执行器之前，Enforced 保持关闭；ServerAdmissionRuntime 提供失败关闭边界，但不执行操作

本地 codex_master.admission 模块现在以进程内、失败关闭的契约提供该预留边界：不可变记录绑定工作版本、授权/范围摘要、租约期望和所选资源；状态更改使用修订 CAS，预留 TTL 限制在 30–120 秒，public() 移除账户密钥、范围路径和其他私有绑定。范围重叠、代理/账户/账户模型容量以及读/读与写重叠被原子检查。FileAdmissionStore 添加了私有锁和原子状态替换，用于新进程恢复；格式错误、过大或符号链接的状态会失败关闭。它不执行提供商、生命周期、租约或网络变更，并且尚未接入 Enforced 执行。

codex_master.selection_service.SelectionService 是下一个本地编排层。它将预览委托给相同的确定性规划器，在注入的运行时调用之前重新验证，以 50/100/200 毫秒的退避最多重试三次，补偿失败的尝试，并在不重新执行的情况下协调崩溃证据。codex_master.admission_runtime.ServerAdmissionRuntime 现在提供失败关闭的服务器边界：权威、仓库和规范范围回调必须来自权威 Hive 记录；现有的 Fleet 账户、模型、Usage、租约、进程身份、认证和运行器配置检查按固定顺序附加。缺少 Hive 绑定、过期的准入、格式错误的门控证据或回调错误会拒绝运行时，并且成功的重新验证对每个准入修订是单次使用的。适配器本身从不认领、启动、分配或调用提供商。当自动执行路径显式请求 current_admission_store() 时，其私有跨进程存储以状态本地的 admission-state.json/锁对为根；生产性 Enforced 执行保持关闭，直到提供权威 Hive 回调和特定于操作的执行器。

当只读来源不可用时，Applet 状态会暴露有界的 fleet_snapshot_degraded 和 watchdog_snapshot_degraded 标志。已耗尽的 Usage-v2 窗口，如果其已验证的重置时间已过，则不再阻止账户；未来或未知的重置保持失败关闭。

Hive 控制平面

codex_master.hive 包现在包含有界的控制平面基础：严格公共配置、私有状态、主体和执行绑定、仓库/权威检查、类型化消息和调度状态机、仅追加决策、来源感知内存、DP 工作队列和单一准入边界。codex_master.selection 包是围绕现有确定性规划器的兼容边界，并添加类型化模型策略、任务分类、来源、公平状态和被动锚点契约，而不引入第二个选择器。

Hive 状态、验证、迁移和 Selection 诊断作为只读 MCP 工具暴露。缺少权威的 Work-/Grant-/Repository-/Scope- 和 Lease 证据保持失败关闭；没有 Hive 诊断工具会认领、启动、分配或调用提供商。

操作细节记录在 docs/account-aware-selection.md、docs/operations/hive-operations.md、docs/operations/selection-operations.md、docs/security/hive-security.md、docs/security/selection-privacy.md 和 docs/migration/hive-selection-migration.md 中。公共、无秘密的配置示例位于 examples/ 中：代理类、Hive 模式和模型策略。

• worktree_create_for_agent：为一个 Agentin 创建隔离的 git worktree

• worktree_status：有上限的 git 状态和 worktree 元数据

• integration_status：仓库状态、差异统计和最近的分配元数据

• commit_ready_check：集成/提交的固定就绪检查

• master_app_bridge_status：App Bridge 清单和连接器 ID 状态

• master_plugin_status：插件打包、插件缓存漂移、App Bridge 和 MCP 注册状态

• master_namespace_status：诊断 codex-master-mcp 注册、启动、插件缓存漂移和新客户端的 tools/list 可见性

• master_release_status：诊断包版本、插件清单版本、本地标签和 GitHub 发布之间的发布漂移

• master_watchdog_status：诊断 systemd Fleetwatchdog 健康、已安装单元加固和聚合安全评分状态

• master_timeout_policy：报告 MCP 启动、Agentin 认领重试、Agentin 等待、生产性无头分配、看门狗监督和隐藏 CLI 租约身份来源的有效超时和轮询策略

• master_applet_status：1–6 个具体 Agentinnen 的有界只读快照；由 Cinnamon applet 使用，并可在 CLI 中作为 applet-status 使用

• agent_pool_validate：验证机器可读的 Agentinnen 池规范

• agent_pool_install：从规范安装或刷新休眠 Agentinnen 主目录

• agent_pool_status：检查数据稀疏的池安装计数

• agent_pool_copy_auth：显式将一个来源 auth.json 复制到多个已安装的 Agentinnen，默认试运行

• agent_pool_destroy_pool：受保护的已安装 Agentinnen 主目录移除

• agent_doctor：结构化诊断，不包含原始输出

• agent_selection_options：账户和权威过滤的第一轮提供，仅包含有效的类/生命周期/模型/推理组合

• fleet_account_list、fleet_gemini_bootstrap_plan、fleet_series_list、fleet_account_upsert、fleet_account_set_secret、fleet_account_disable、fleet_account_probe、fleet_account_delete、fleet_provider_models、fleet_series_plan、fleet_series_apply、fleet_series_disable 和 fleet_series_delete：有界的 Fleet 账户/提供商/系列管理；秘密输入仅通过标准输入，变更使用生成 CAS

/mcp 应仅在 Teamleiterin/主 Codex 实例中显示 codex-master-mcp。受管 Agentinnen 有意不接收 Masterjet MCP 工具；它们由外部控制，且仅当任务明确允许时，才可使用原生 Subagentinnen。 tool_search 对本地 stdio MCP 命名空间不具有权威性；请在受影响的 Codex 客户端中使用 /mcp，或使用本仓库中的 namespace-status。 plugin-status 和 namespace-status 还会报告仓库插件清单版本是否已安装到本地插件缓存中，但不返回缓存路径。 对于 namespace-status，顶层 ok 表示 MCP 服务器、本地插件缓存、活动 Codex 客户端配置以及活动 CODEX_HOME 上下文均已就绪。 mcp_server_ready、plugin_cache_ready、client_config_ready 和 active_home_ready 保持独立，以便将服务器启动问题与过期的客户端/插件状态、不匹配的配置或受管 Agentin 主目录区分开来。 running_process_summary.namespace_visibility 仅报告聚合的客户端主目录类别，以便同级 Codex 会话能够识别自定义主目录何时需要自己的 MCP 配置，或受管 Agentin 主目录何时预期不暴露 Master MCP 工具。

本地 CLI

中央类/生命周期/模型解析器

在首次启动或分配一个系列之前，请求模型会针对具体的目标 Agentin 查询 agent_selection_options。响应仅包含当前允许的类、生命周期、模型、推理级别及其有效组合。该提供是建议性的，不保留任何内容。其 generation 可在后续调用中作为 known_generation 传入；options_changed 报告因账户或目录引起的变更。首次为 Teamleiterin 提供时，必须恰好显示一个合法的元组：class=teamleiterin、lifecycle=persistent、model=gpt-5.6-terra、reasoning=xhigh。对于该策略，xhigh 同时是最低值和最高值。不得提供其他 Teamleiterin 元组。

agent_start、agent_assign 以及分配快捷方式会将其可选字段 class、lifecycle、model、reasoning_effort 和 complexity 传递给同一解析器。此后不再应用第二套选择策略。公开的生命周期为 ephemeral、binding 和 persistent；invocation 仍可作为输入别名使用，并作为 ephemeral 返回。

兼容的显式指定将予以保留。类配置文件、生命周期、模型能力、账户相关可用性以及推理最低值和最高值均为硬性限制。若缺少类，则选择合适的可委派非领导类；领导类永远不会被自动提升。若缺少生命周期，则适用类配置文件。Workerinnen 的默认值：

• 简单写入任务加 ephemeral：gpt-5.3-codex-spark/low

• 只读或非简单写入任务加 ephemeral：gpt-5.6-luna/medium

• binding：gpt-5.6-luna/high

• persistent：gpt-5.6-luna/xhigh；此处 xhigh 同时为最低值

若 Spark 对账户不可用，或任务检查将其拒绝，则默认值回退到 Luna。Spark 仅是简单写入任务且无模型指定时的默认值。为 Workerin 显式请求的未知或不可用模型将安全回退到 gpt-5.6-luna，绝不会回退到 Spark；兼容的显式 effort 将保留，或被钳制到替代模型以及类/生命周期边界。与类不符或过弱的指定也将在硬性限制内被替换；Gottbiene 和 Koenigin 保持 Sol 绑定。selection.fallback、请求值和有效值以及稳定的 reason_codes 提供清晰的错误/回退消息。请求模型之后可以中止，或使用另一个提供的组合重新请求。Spark -> Luna -> Terra -> Sol 的有效升级在类和 effort 限制内仍然可能。ultra 永不允许。

Teamleiterin 固定为 persistent，且恰好使用 gpt-5.6-terra 搭配 xhigh；xhigh 对她而言同时是最低值和最高值。必需的模型或 effort 不可用属于硬性错误，无回退。required_model_unavailable:gpt-5.6-terra 或 required_model_effort_unavailable:gpt-5.6-terra:xhigh。这尤其适用于 Teamleiterin：启动和分配共享中央解析器，绝不允许回退到 Sol、Luna、Spark 或其他 effort。

领导类固定为 persistent，并在首次真实用户接触时以名称自我介绍：Gottbiene 使用 gpt-5.6-sol/max，Koenigin 使用 gpt-5.6-sol/xhigh，Teamleiterin 恰好使用 gpt-5.6-terra/xhigh。对于 Koenigin、Teamleiterin 及所有 Worker 类，xhigh 是绝对上限；只有 Gottbiene 可以使用 max。

规范操作流程见 Selection Operations。带版本号的目录 codex-agent-classes.json 和 codex-model-policy.json 保持权威性；README 和 skill 不定义第二套选择策略。

资源感知的 Spawn 提供

agent_spawn_offers 是一个只读 MCP 提示，用于指示可能的本地容量。MCP tools/call 示例：

{"name":"agent_spawn_offers","arguments":{"required_slots":1}}

来自此 worktree 的相同 CLI 命令：

PYTHONPATH=src python -m codex_master.server spawn-offers --required-slots 1
./bin/codex-master-mcp spawn-offers --required-slots 1

PYTHONPATH=src 对于此 worktree 的 Python 调用是必需的：本地可编辑安装可能指向不同的源代码状态。

提供是建议性的，有效期为 5 秒，不保留任何内容（reservation: "none"）。start 在 admission 锁下启动新的 tmux 之前，会重新检查空闲的总槽位。若没有可靠的总数，提供将保持为空；数据稀疏的响应仅包含 reason 代码，不包含 /proc 内容、tmux 输出、本地路径或环境文本。该响应可重试，并带有 15 秒的等待提示。

新启动的临时限制：

• 资源压力限制保持其现有值配置并处于活动状态：CPU、负载、I/O 等待和 RAM 可能以 fail-closed 方式阻止 spawn。

• 配置的 Ollama 双实例限制保持不变，并在全局十实例限制之前强制执行

• 总共最多 10 只 Bienen；正在运行的 Masterjet 会话以及活动且未确认的本地 Subagentinnen 一并计入

• 从 10 只 Bienen 起，任何额外的 Biene 将被硬性拒绝

• required_slots 介于 1 和 10 之间

被拒绝的 admission 响应除稳定的 reason_codes 外，还包含结构化的 errors 表。每个条目提供 code、title、explanation、rule 和 action；不包含原始指标或本地状态数据。

CODEX_MASTER_SPAWN_PRIORITY 是唯一的 spawn 环境配置。它是一个逗号分隔的优先级列表（默认 mcp_host），仅作为数据读取、去重，绝不被执行为 shell 命令或网络目标。其文本不会在响应中回显。目前，只有精确的本地路由值 mcp_host 才能生成提供。developer_vm 和 sandbox 即使出现在此列表中也不会被提供；此版本中没有远程执行。

提供不会生成 lease、元文件或 assignment audit 条目。Auth、scope、routing、model、usage 和现有 admission 门控在实际启动或分配时仍然有效。干净的 tmux 状态（无服务器或会话）计为零个正在运行的 Agentinnen。测量错误、/proc 错误以及所有其他 tmux 错误均 fail-closed；其公开错误保持有限且经过编辑。

本地 Subagentinnen 向 Masterjet 报告启动和停止。因此，活动且未确认的条目会计入后续的每次槽位决策。Assignment prompt 策略要求在每次进一步 spawn 之前进行全新的总体检查。绕过此 MCP 路径的模型，Masterjet 在没有 Codex 自身的 pre-spawn hook 的情况下，仍然无法在技术上拦截。developer_vm 只有在满足以下所有前提条件后，才可变为可提供：

• 针对实际 VM 的真实可达性/健康探测

• 经过身份验证的传输和主机密钥验证/固定

• 跨主机的分布式 lease/预留

• 有界远程执行（超时和有界输出）

• 针对真实目标的端到端集成测试

在此之前，VM 后端将完全省略。

cd /home/teladi/codex-master
python3 -m codex_master.server install          # create ~/.local/bin/codex-master-mcp + codex mcp add
python3 -m codex_master.server doctor          # smoke check (codex, tmux, state path, JSON result)
python3 -m codex_master.server uninstall       # remove mcp registration and local symlink
python3 scripts/codex-master-cinnamon-applet install --dry-run
python3 scripts/codex-master-cinnamon-applet install --no-reload
python3 scripts/codex-master-cinnamon-applet verify

python3 -m codex_master.server start both --cwd /home/teladi/codex-master
python3 -m codex_master.server status
python3 -m codex_master.server selector-policy
python3 -m codex_master.server selector-policy --series a,b,c
python3 -m codex_master.server selector-preview --limit 6
python3 -m codex_master.server selection-preview --series d --task-kind simple --admission-mode shadow --sp1a --limit 8
python3 -m codex_master.server lease-status all --agents-limit 30
python3 -m codex_master.server claim b --forever --poll-interval-seconds 30
python3 -m codex_master.server claim b --no-wait
python3 -m codex_master.server claim b --no-recover-stopped
python3 -m codex_master.server wait a --timeout-seconds 120 --poll-interval-seconds 30
python3 -m codex_master.server watchdog active --idle-seconds 60 --poll-interval-seconds 15 --report-grace-seconds 15 --action stop --manage-unclaimed --quiet
python3 -m codex_master.server capabilities all --agents-limit 30
python3 -m codex_master.server skills all --agents-limit 30
python3 -m codex_master.server skills a --include-names --limit 20 --names-offset 20 --plugins-offset 20 --plugins-limit 20
python3 -m codex_master.server skill-match all codex-security:security-scan --agents-limit 30
python3 -m codex_master.server scope-check --scope src/codex_master --write-path src/codex_master/server.py
python3 -m codex_master.server assign-readonly a --skill codex-security:security-scan --scope src/codex_master/server.py --task "Pruefe nur lesend und berichte knapp."
python3 -m codex_master.server assign-live-data a --task "Wie ist das Wetter gerade in Berlin?" --live-data-topic "Wetter Berlin heute"
python3 -m codex_master.server assign-write b --scope .github/workflows --write-path .github/workflows/ci.yml --task "Haerte nur die CI-Datei."
python3 -m codex_master.server assignments all --limit 20
python3 -m codex_master.server last-assignment a
python3 -m codex_master.server assignment-report a ASSIGNMENT_ID --source pane --lines 40 --chars 4000
python3 -m codex_master.server integration-status
python3 -m codex_master.server commit-ready-check
python3 -m codex_master.server app-bridge-status
python3 -m codex_master.server plugin-status
python3 -m codex_master.server namespace-status
python3 -m codex_master.server release-status
python3 -m codex_master.server watchdog-status
python3 -m codex_master.server timeout-policy
python3 -m codex_master.server fleet-recovery-status
python3 -m codex_master.server fleet-recovery-retry
python3 -m codex_master.server pool validate --spec codex-agent-pool.json
python3 -m codex_master.server pool install --spec codex-agent-pool.json --target-dir "$HOME/.codex-agents" --codex-bin /usr/local/bin/codex
python3 -m codex_master.server pool status --spec codex-agent-pool.json
python3 -m codex_master.server pool copy_auth --spec codex-agent-pool.json --from-agent a1 --to a-series
python3 -m codex_master.server pool destroy_pool --spec codex-agent-pool.json --yes
python3 -m codex_master.server send a "Kurzer Auftrag"
python3 -m codex_master.server release b
python3 -m codex_master.server tail a --source pane --lines 20 --chars 2000
python3 -m codex_master.server stop both

Agentinnen 池规范

该仓库包含一个通用的、机器可读的 codex-agent-pool.json 以及 schemas/codex-agent-pool.schema.json。当前安装的本地池使用五个 A 主目录、三个 B 主目录和三个 C 主目录。a1 和 b1 仍是经过身份验证的源主目录；b92 是一个单独保留的活动主目录，并显示在合并的 fleet 清单中。Gemini 系列通过 Fleet 注册表管理，不属于此本地池规范的一部分。 池规范读取仅接受常规 UTF-8 JSON 文件，拒绝符号链接或过大的规范文件，并将规范路径排除在公开错误响应之外。 池验证仅返回系列、别名和经过身份验证的 Agentinnen 的计数和状态标记；不回显具体名称。 池安装还会将生成的 codex 包装器和 config.toml 文件保留为每个 Agentin 的常规文件，替换符号链接条目而不触及它们的目标，将运行时目录验证为真实目录，并写入常规的已安装池标记。池状态仅在标记、所有预期主目录、包装器、配置和必需的共享资产链接均存在且有效时报告 ok。共享资产诊断仅为计数；不返回本地链接目标和池路径。池状态还会返回系列计数，而不回显具体的系列名称。

该规范只是映射。实际的身份验证材料仍是每个主目录的 auth.json，例如 ~/.codex-agents/a1/auth.json。正常安装从不复制身份验证材料。

支持两种安装路径：

./bin/codex-master-mcp pool install --spec codex-agent-pool.json --target-dir "$HOME/.codex-agents"
./scripts/install-agent-pool --spec codex-agent-pool.json --target-dir "$HOME/.codex-agents"

当 Codex CLI 二进制文件不是 /usr/local/bin/codex 时，请使用 --codex-bin。正常安装从不复制身份验证材料。对于批量身份验证传播，请先不带 --yes 运行 pool copy_auth 以检查计数，然后在有意时使用 --yes 重复运行。copy_auth 仅复制 auth.json，当源 Agentin 属于目标选择器的一部分时跳过该源 Agentin，要求源 Agentin 主目录是真实目录，并且绝不返回身份验证内容、源 Agentin ID 或请求的目标选择器。

不要对普通池模型中的 auth.json 使用符号链接或硬链接。 认证文件很小；副本能让每个 Agentin 保持隔离。符号链接会跨越 no-follow 信任边界，而硬链接会让多个 Agentinnen 共享同一个 inode。

完整的命令集见 docs/agent-pool.md，auth-copy 安全模型见 docs/auth-copy.md。

Cinnamon 安装程序会将小程序复制到每用户 Xlet 目录，采用原子交换、一个经过验证的回滚树、一把私有操作锁，以及有界的源/目标验证。install --dry-run 不执行任何文件系统或 D-Bus 变更；--no-reload 适用于 CI 和临时主目录冒烟测试。verify 在桌面会话可用时还会检查正在运行的 Cinnamon Xlet。

Cinnamon 小程序：Flottenmanagement

codex-master@H234598 是 P3/P3a 只读状态小程序。其可见面板标题始终为 Flottenmanagement。它显式请求小程序状态 schema v4；schema v1 到 v3 对旧调用方保持不变。

每次 schema-v4 刷新使用一次有界的 tmux 会话清单。每个已知正在运行的 codex-master Agentin 都会被自动发现并显示，最多到固定的六行上限。外部 tmux 会话会被忽略。tracked-agents 不再定义可见机群：它只把休眠的 Agentinnen 固定到活动 Agentinnen 空出的行中。因此其 a1,b1 默认值不会限制自动发现。超过六个活动受管 Agentinnen 会产生有界的溢出标记，而不是无界菜单。

原生 Codex-Subagentinnen 不会与受管 tmux Agentinnen 混在一起。官方的 SessionStart、SubagentStart、SubagentStop 和 SessionEnd 钩子维护一个私有的有界寄存器。小程序只在单独的 Native Bienen (N) 子菜单中渲染该寄存器，使用六个固定的、非响应式子行。原生行仅用于状态，不包含任何操作或上下文令牌。

小程序最多启动一个有界的 codex-master-mcp applet-status 子进程，并且从不读取资源快照或启动资源监视器。Schema v4 只增加有界的资源门状态、瓶颈、趋势、置信度、配置文件提示和快照代次。无效或回退的资源代次渲染为不可用。小程序从不调用 shell。

状态模型将三个关注点分开：

• activity_state：running、sleeping、mixed 或 unknown；

• backend_state：ok、degraded 或 unavailable；

• control_state：ready、blocked、mixed 或 unknown。

休眠的 Agentin 是正常的，本身不会降低后端健康状态。失败的刷新会保留最后一个有效快照并将其标记为过期。响应只包含固定的状态字段和计数；提示、日志、进程 ID、路径、租约所有者、租约 ID 和原始输出不会返回。

resource-status --format compact|json|markdown 是本地操作员 CLI，不是 MCP 工具。它只渲染经过验证的 ResourceOperatorStatus 投影；传感器标签、cgroup 作用域 ID、路径、PID、原始历史、stdout、stderr、凭据和绝对可用内存证据永远不会返回。

四个小程序设置是：

• tracked-agents：逗号分隔的 a1 到 c100；1–6 个具体 ID，用于在自动活动发现留下容量时固定为休眠行，大小写归一化并去重；默认 a1,b1；

• refresh-on-open：打开菜单时刷新；默认开启；

• background-refresh：可选的后台刷新；默认关闭；

• refresh-interval-seconds：15–3600 秒；默认 60。

格式错误的 agent、switch 或 interval 值会显示配置错误，回退到安全默认值，禁用后台工作，并且永远不会进入进程 argv。超出允许范围的有限刷新间隔会被限制在 15–3600 秒。菜单包含手动刷新、小程序管理、一个摘要、最多六个受管行，以及单独有界的 Native-Bienen 子菜单。

只有 Koenigin 可以重启或重新加载 Masterjet、安装它或同步插件缓存。其他角色可以检查并验证状态，并向 Koenigin 推荐这些操作，但不得执行它们。

使用仓库自带的安装程序安装 MCP/插件和小程序：

./bin/codex-master-mcp install
./scripts/codex-master-cinnamon-applet install --dry-run
./scripts/codex-master-cinnamon-applet install
./scripts/codex-master-cinnamon-applet verify

完整的 CLI 参考是仓库手册页 codex-master-mcp(1)。构建确定性的压缩输出而不安装它，或直接渲染源文件：

./scripts/codex-master-manpage build --output-dir /tmp/codex-master-man
groff -man -Tutf8 man/man1/codex-master-mcp.1

codex-master-mcp install 将插件（包括常规的 hooks/hooks.json、hooks/native_spawn_admission.py 和 hooks/native_bee_event.py 文件）同步到个人插件缓存中。它不会也不得更改 Codex 钩子信任状态。在当前父级 Codex 会话中，打开 /hooks，检查五个 codex-master 定义，并显式信任它们：一个阻塞的 PreToolUse 准入钩子加上四个生命周期钩子。然后在仓库中启动一个全新的父级 Codex 会话。MCP 重连、状态或 agent 启动不会替代该新会话。在该手动步骤成功之前，不要声称原生生成准入或 Native-Bienen 生命周期覆盖已激活。

回滚活动小程序树：

./scripts/codex-master-cinnamon-applet rollback

install 会暂存并哈希常规的非硬链接源文件，拒绝符号链接的源/目标路径，仅通过 Cinnamon 的 ReloadXlet 重新加载此 UUID，并在部署失败时恢复并重新加载之前的树。verify 要求已安装文件字节相同，并且 GetRunningXletUUIDs applet 返回正在运行的 UUID。rollback 要求经过验证的已安装树和回滚树，但不要求完整的仓库源。当所需树缺失或意外时，它会失败关闭。安装、验证和回滚由一把私有的每-UUID 锁串行化。--no-reload 可用于受控的离线安装/回滚测试。没有命令使用 Eval 或全局重启 Cinnamon。

有用的诊断：

./bin/codex-master-mcp resource-status --format compact
./bin/codex-master-mcp resource-status --format json
./bin/codex-master-mcp resource-status --format markdown
./bin/codex-master-mcp applet-status --schema-version 4
gdbus call --session --dest org.Cinnamon --object-path /org/Cinnamon \
  --method org.Cinnamon.GetRunningXletUUIDs applet
journalctl --user -b | grep -F codex-master@H234598

unavailable 或过期的小程序状态意味着有界的只读刷新失败。首先验证已安装的文件和 CLI；不要将普通的 sleeping 活动解释为后端故障。

安装契约（CLI）

install

• 创建 ~/.local/bin/codex-master-mcp 作为指向 bin/codex-master-mcp 的符号链接

• 在注册到 Codex 之前，验证仓库包装器能回答 MCP initialize 探测

• 验证已安装的命令路径在注册前也能回答相同的探测

• 通过 codex mcp add codex-master-mcp -- <link> 注册命令

• 确保活动的 Codex MCP 配置具有 startup_timeout_sec = 120

• 从运行时允许列表（.codex-plugin、.app.json、.mcp.json、bin、docs、examples、schemas、scripts、skills、src、systemd、README、codex-agent-pool.json 和包元数据）同步个人 codex-master 插件缓存，同时排除 .git、测试、字节码、测试缓存、隐藏文件、编辑器交换文件和备份/补丁残留

• 拒绝硬链接的插件源文件，只保留当前版本和最近的有效缓存插件版本，而不修剪无效或符号链接的缓存条目

• 通过 no-follow 文件描述符复制常规插件缓存源文件，并在打开后验证源身份，因此源交换不能重定向缓存内容

• 创建带 nonce 后缀的插件缓存临时目录，并且绝不删除此同步未创建的预先存在的临时目录

• 拒绝从受管 Agentinnen 的 CODEX_HOME 注册 Master MCP

• 要求安装路径的父链是真实目录，而不是符号链接

• 通过同目录临时符号链接和目录 fd 绑定的 rename 原子地创建或替换安装符号链接

• 将损坏、循环或不可读的安装符号链接视为不匹配，而不是在解析它们时崩溃

• 返回 JSON，不包含 agent 输出、安装路径、仓库包装器目标路径或插件缓存路径

• 仅对显式诊断安装接受 --no-plugin-cache，这些安装应保持个人插件缓存不变

uninstall

• 从 codex mcp remove codex-master-mcp 注销

• 移除 ~/.local/bin/codex-master-mcp

• 移除时要求安装路径的父链是真实目录

• 通过已验证的父目录 fd 移除安装符号链接，因此验证后的父目录交换不能重定向 unlink

• 保留损坏、循环或不可读的安装符号链接，除非它们解析到仓库包装器

• 返回 JSON，不包含原始秘密材料

doctor

• 检查所需工具（codex、tmux）和 MCP 状态目录的可用性

• 报告结构化的 checks 对象

• 使用数据稀疏的 initialize 探测验证已安装的 MCP 命令

• 报告活动的 Codex MCP 注册是否具有 startup_timeout_sec >= 120

• 报告活动的 CODEX_HOME 看起来像主默认主目录、受管 Agentinnen 主目录还是自定义主目录，而不返回路径

• 将本地包装器、安装、Agentin 主目录和 Agentin 运行器路径隐藏在状态/类别字段后面，同时保留存在性和健康检查

• 报告原始日志保留计数和大小，而不返回受管原始日志目录路径

• 当已安装的 MCP 指向此仓库而工作树有已跟踪或未跟踪的更改时，发出警告而不返回文件路径

• 将损坏、循环或不可读的安装符号链接报告为失败的 installed_symlink 检查，并带有不可读目标标记

• 将停止的 Agentinnen 视为信息性会话状态，而不是失败的健康检查

• 在输出中编辑已知的秘密形状

watchdog

• 仅从结构化的 status 元数据和原始日志元数据分类空闲状态；它不调用 tail 或返回 Agentin 输出

• 默认为 idle_seconds=60、poll_interval_seconds=15、report_grace_seconds=15 和 action=interrupt

• 在 interrupt、stop 或 release 之前总是要求 Agentin 提供简明报告

• 只存储带有请求时间、分配 ID、计划操作和原始日志计数器的元数据标记；标记中不存储提示文本、响应或原始日志

• 跳过其他客户端持有的活动租约；--manage-unclaimed 除了此服务器自己的租约外，还可以监督未认领或过期的租约

• 支持 --quiet 用于 systemd 运行；成功的 watchdog 通过不产生 JSON 输出，而失败仍使用正常的 CLI 错误路径

• 通过 systemd/user/codex-master-watchdog.service 和 systemd/user/codex-master-watchdog.timer 作为可选的 systemd --user 顶层安装

• 用户服务以保守的加固指令运行：空的 CapabilityBoundingSet、私有 keyring/tmp/devices、用户 tmux 套接字目录的只读绑定、内核和时钟保护、只读系统层次结构、仅对受管状态和用户运行时目录的显式写访问、无 IP 套接字、无命名空间、NoNewPrivileges、MemoryDenyWriteExecute、原生系统调用架构和 UMask=0077；它有意保持正常的用户主目录读访问，因为 watchdog 需要 Codex 配置、tmux IPC 和受管状态文件

• codex-usage 默认将其当前快照存储在 ~/.local/share/codex-usage/current/<account>.json 下；读取器仅在当前文件不存在时接受旧的 snapshots/ 布局，并在现有当前文件格式错误时失败关闭。usage_watchdog 将当前的 5 小时/每周窗口规范化为无秘密的 Usage-v2 数据，写入本地 codex-usage 块标记，并在未来重置窗口仍处于活动状态时拒绝新的 agent_start/claim 流程；过去已验证的重置清除块，未知重置保持失败关闭

watchdog-status

• 报告 systemd 定时器是否处于活动状态，以及上次服务运行是否成功，而不返回原始的 systemctl 输出

• 检查已安装的看门狗服务和定时器是否与仓库副本一致，并确认服务仍包含所需的安全加固指令和看门狗标志

• 仅解析 systemd-analyze security 的汇总暴露评分和级别；不返回原始分析器输出和本地单元路径

goddess report run 按时间顺序处理所有符合条件的 UTC 报告桶，最多回填 24 小时，并重试未最终确定的桶。对于每小时运行，请启用加固的可选用户定时器：

systemctl --user daemon-reload
systemctl --user enable --now codex-master-goddess-report.timer

timeout-policy

• 报告 agent_claim 在默认情况下对繁忙的 fremde Bienen 无限重试，而有限等待的声明仍然被接受，且没有 600 秒的上限

• 报告声明轮询默认为 30 秒，上限为 900 秒

• 报告显式声明的停止外部租约恢复默认值：仅限已停止的 Agentinnen，无托管主目录进程，且有足够的空闲证据

• 将 agent_wait 保持为独立的有界活动等待：默认 120 秒，最大 600 秒

• 报告有生产力的无头分配，默认 600 秒，最大 7200 秒（120 分钟）

• 报告 send/assign-*/report-request TUI 输入就绪门控：默认 15 秒，0.5 秒轮询，需要可见的输入提示，无粘贴时通过可重试的 agent_input_not_ready 故障关闭

• 报告当前 CLI/MCP 所有者身份在多次调用之间是否稳定，而不返回身份本身

skills

• 扫描每个 Agentin 主目录中的 skills/、plugins/cache/ 和 .tmp/plugins/ 下的 SKILL.md 文件

• 忽略符号链接的技能根目录和符号链接的 SKILL.md 文件，而不是跟随它们

• 返回计数、根目录、系统技能名称以及有界的插件/名称分页

• 报告 plugin_count、plugins_offset、plugins_limit 和 plugins_truncated，而不是在安装大量插件时转储每个插件名称

• 支持通过 plugins_offset/plugins_limit 进行有意的枚举，并在使用 include_names 时支持 names_offset/limit

• 不返回技能文件内容，也不返回 Agentin 终端输出

capabilities

• 返回模型策略、技能总数、系统技能名称以及有界的第一页插件列表

• 报告 plugin_count、plugin_page_count、plugins_limit 和 plugins_truncated，而不是在安装大量插件时转储每个插件名称

应用桥接

该插件包含 .app.json，并通过 .codex-plugin/plugin.json 声明它：

{
  "apps": {
    "codex-master": {
      "id": "connector_26697a678b7ec999dc005131eb5c087c"
    }
  }
}

这是 codex-master 插件的本地应用桥接身份。它保持现有的数据稀疏型 MCP 工具表面，并让 Codex 将插件与稳定的连接器 ID 关联。该 ID 有意不作为机密。

对于 ChatGPT 开发者模式连接器，ChatGPT 仍然需要针对可达的公共 HTTPS /mcp 端点创建或刷新连接器。当前的 Masterjet MCP 作为本地 stdio MCP 为 Codex 运行，因此 .app.json 组织插件侧的桥接身份；它不会将仓库发布到 Marketplace，也不会自行将本地 stdio 命令转换为托管的 HTTP 连接器。

在不暴露本地路径的情况下检查桥接状态：

python3 -m codex_master.server app-bridge-status

引导技能

技能不会作为独立的 MCP 函数被调用。它们是指令包，当任务提到该技能或明显匹配其领域时，Codex Agentin 会使用这些指令包。

python3 -m codex_master.server skills all --agents-limit 30
python3 -m codex_master.server send a "Nutze codex-security:security-scan. Pruefe src/codex_master/server.py nur lesend und berichte knapp."
python3 -m codex_master.server send b "Nutze github:gh-fix-ci. Pruefe die CI-Konfiguration nur lesend und berichte knapp."
python3 -m codex_master.server tail a --source pane --lines 20 --chars 2000

为了更安全的委派，优先使用 assign-readonly、assign-live-data 和 assign-write，而不是自由形式的 send：

python3 -m codex_master.server assign-readonly a \
  --skill codex-security:security-scan \
  --scope src/codex_master/server.py \
  --task "Pruefe nur lesend und berichte knapp."

python3 -m codex_master.server assign-live-data a \
  --task "Wie ist das Wetter gerade in Berlin?" \
  --live-data-topic "Wetter Berlin heute"

python3 -m codex_master.server assign-write b \
  --skill github:gh-fix-ci \
  --scope .github/workflows \
  --write-path .github/workflows/ci.yml \
  --task "Haerte nur die CI-Datei und berichte Root Cause, Aenderung, Tests, Risiken."

assign 通过清单验证命名技能，拒绝 Exploriererinnen 的写入路径，并要求 Arbeitsbienen 提供明确的写入路径。它通过 tmux 发送生成的提示，但不返回提示或 Agentin 响应。

对于天气、新闻、价格、日程或任何其他当前数据任务，请使用 assign-live-data。它是只读的，使用与其他分配相同的认证和租约保护，并注入明确的要求：使用当前的搜索来源，或在无法猜测时报告工具/访问限制。具体的实时数据主题仅发送到 Agentin 提示中；公共响应和分配审计记录将主题和响应内容排除在返回的数据之外。

assign-write 还通过 agent_scope_check 门控写入路径；在向 Agentin 发送任何内容之前，声明范围之外的写入路径会被拒绝。工作树创建拒绝已存在的目标，包括损坏的符号链接，并要求目标路径中的每个父目录都是真实目录。工作树创建和状态是仓库范围的：相对路径逃逸和仓库之外的绝对目标在运行 git 之前被拒绝，创建响应最多返回仓库相对路径，绝不返回绝对本地路径。工作树状态还在运行 git status 之前拒绝符号链接和非目录目标。 分配和发送输入在 tmux 交互之前是有界的：自由发送和启动提示上限为 12,000 个字符，分配任务上限为 4,000 个字符，名称上限为 80 个字符，技能引用上限为 300 个字符，路径类字段上限为 1,000 个字符，分配列表上限为 50 项。MCP 布尔和整数参数经过类型检查；字符串化值被拒绝而不是被强制转换。传入的 MCP 帧在 JSON 解析之前上限为 1 MiB。工具和 RPC 错误文本在返回之前经过 ANSI 剥离、脱敏和长度限制。tools/call 在分派之前验证工具名称、对象形状的 params 和 arguments、未知参数名称、必填字段、值类型、枚举和声明的边界。本地 CLI 工具命令通过相同的模式验证，省略的可选参数在验证之前被移除。多行 send 和 assign-* 负载在 tmux 粘贴之前用括号粘贴标记包裹，以便 Codex TUI 将模板视为一个提示，而不是多个单独提交的行。

在修改一个 Agentin 之前，start、assign-*、send、report-request、interrupt 和 stop 会检查或续订每个 Agentin 的租约。第二个 MCP 客户端会收到结构化的可重试错误，而不是写入同一个 tmux 会话。新的 start 租约在成功启动后再次释放；这使本地 CLI 在多次独立调用之间保持可用，同时仍然序列化启动操作本身。同一已连接客户端持有的现有声明会被保留。 当 Codex-CLI 实例应等待繁忙的 Agentin 时，请使用 claim；它默认以有界的轮询间隔无限重试。使用 claim --no-wait 进行单次立即尝试，或使用 claim --wait-seconds ... 设置明确的有限限制。显式 claim 仅在停止宽限期（默认 120 秒）之后恢复已停止的外部租约，前提是 Agentin 未运行且没有进程使用该托管 Agentin 主目录。当操作员需要严格的仅 TTL 行为时，使用 claim --no-recover-stopped。租约状态仅为元数据，不返回客户端身份、提示文本、Agentin 输出或本地状态路径。

原始日志是本地调试工件，不是正常的 API 数据。tmux 管道通过有界的本地写入器写入，doctor 报告配置的原始日志策略，tail --source log 拒绝托管原始日志状态之外的元数据路径。托管原始日志必须是常规文件；符号链接不被跟随，并从原始日志目录中清除。隐藏的原始日志写入器在触及状态或路径之前，拒绝活动原始日志策略之外的 --max-bytes 值。仅在需要明确、有上限、ANSI 剥离、脱敏的摘录时使用 tail。失败的启动在返回错误之前会删除其准备好的原始日志文件。

模型策略通过上述中央类/生命周期/模型/努力解析器一次性解析。启动和分配响应暴露有效的选择、回退状态和原因代码；分配审计元数据记录有效模型，而不存储提示或响应。

仅当分配使用 --allow-subagents 时，Agentinnen 才能启动自己的原生 Subagentinnen。没有该标志，生成的分配明确禁止嵌套委派。即使有该标志，嵌套 Agentinnen 也保持在分配的范围内和写入路径内；它们不使用 codex-master-mcp，也不提交、推送或发布。

当 Masterjet 负责某个托管 Agentin 时，不要使用相同的 CODEX_HOME 手动启动她。当她的主目录已被外部 Codex 进程使用时，start 拒绝启动 Agentin，doctor 在它们变成 tmux 或锁竞争之前报告此类主目录冲突。如果第二个外部进程正在使用相同的主目录，start 也拒绝已运行的 Masterjet 会话。install 拒绝从托管的 Agentinnen 主目录注册 codex-master-mcp，以便 Masterjet 工具保留在 Teamleiterin/主实例中。

分配仅作为元数据追加到 ~/.local/state/codex-master-mcp/assignments.jsonl：分配 ID、Agentin、角色、所选模型、技能匹配状态、范围、写入路径、计数和标志。提示文本和 Agentin 响应不被存储或返回，分配查询响应不返回本地审计文件路径。审计文件作为有界的本地 JSONL 账本保留：保留最新的 500 条有效元数据记录，无效的旧行在修剪期间被丢弃，文件以 0600 权限重写。私有状态追加拒绝符号链接路径，Agentin 元数据以原子方式写入，带 nonce 后缀的临时替换文件以无跟随独占语义创建。托管状态目录及其父链必须是真实目录，而不是符号链接或常规文件。 外部进程调用有超时限制，并返回结构化的超时失败，而不是无限期阻塞 MCP 服务器。 agent_doctor 还报告活动的 CODEX_HOME 上下文而不返回路径，并检查 codex-master-mcp 在活动 Codex MCP 配置中是否具有至少 120 秒的 startup_timeout_sec。

仅在需要明确、有上限的摘录时使用 tail。正常的状态和发送操作不返回 Agentin 输出。当所选 Agentin 持有由另一个 MCP 客户端持有的活动租约时，tail 拒绝读取窗格或日志输出；请先声明该 Agentin 或等待租约过期。

插件

此仓库也是一个本地 Codex 插件：

• .codex-plugin/plugin.json：插件元数据和 Codex UI 信息

• .mcp.json：从此仓库启动 codex-master-mcp，无需包安装，并声明 startup_timeout_sec = 120

• skills/codex-master-fleet/SKILL.md：Masterjet 的 Teamleiterin 技能

该插件面向主/Teamleiterin Codex 实例。托管的 Agentinnen 应保留其单独的工作者技能，不应接收 Masterjet MCP 工具。

Marketplace 条目是可选的。仓库包含插件工件，现有的 codex-master-mcp 注册可以直接运行 MCP 服务器。仅当您希望 Codex 的插件 UI 发现并将其作为插件安装时，才添加个人/本地 Marketplace 条目。

检查

git diff --check
PYTHONPATH=src python3 -m compileall -q src tests
PYTHONPATH=src python3 -m unittest discover -s tests -v
./bin/codex-master-mcp tools

./bin/codex-master-mcp commit-ready-check 运行本地发布门禁，包括 git diff --check、compileall 和单元测试。

GitHub Actions 使用 .github/workflows/ci.yml 运行相同的源代码和单元测试门禁，外加插件/应用/MCP 清单验证、推送或拉取请求提交范围的已提交空白检查、CLI 包装器冒烟检查、外部工作流操作的完整 SHA 固定检查，以及针对 validate、install、status 和 destroy_pool 的临时代理池安装器冒烟测试。