OmX 团队启动分发延迟契约tmux 窗格创建到首次 inbox 触发的时间窗口治理【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex导读本文解析 OmXoh-my-codex团队模式下 worker 启动分发的核心性能与正确性契约聚焦「tmux worker 窗格创建完成」到「worker 收到首条 inbox 触发指令」之间的启动窗口。通过阅读本文你将掌握该窗口内的完整调用链、必须插桩的 8 个延迟阶段标记、启动期直连触发快速路径的安全边界以及如何用针对性回归测试验证每个延迟阶段是否回退。一、契约背景与范围延迟不在任务分配而在三道闸门docs/contracts/team-startup-dispatch-latency.md记录了针对团队启动分配延迟修复的评审契约。首先要澄清一个关键事实该问题的本质不是任务分配。在启动通知尝试开始之前任务task JSON、worker 身份identity JSON和 worker inbox 文件已经全部落盘为持久化状态。真正的延迟风险集中在窗格创建与首次触发之间依次排列的三道闸门就绪闸门readiness gate交互式 worker 需要等待其 CLI 进入可交互状态分发闸门dispatch gate默认策略要求 inbox 分发先进入 notify hook 队列并等待回执启动证据闸门startup-evidence gate触发结果被认定为「已结算」前还需观察到 worker 的启动证据。契约的目标是让第一道触发指令尽快到达 worker同时不破坏 worker 的身份权威、信任提示安全语义与后续 mailbox 分发行为。二、受审的当前启动路径五步调用链拆解契约明确定义了当前被评审的启动路径以下每一步都可以在仓库源码中找到对应实现第 1 步创建窗格。tmux-session.ts 中的createTeamSession()分割 leader/worker 窗格并返回具体的workerPaneIds形如%12、%13的 tmux pane id。调用方随后通过applyCreatedInteractiveSessionToConfig()将这些 pane id 写回config.workers[i].pane_id与pid为后续的精确窗格校验readExactPaneProofSync奠定基础。第 2 步落盘持久化状态。runtime.ts 中的startTeam()为每个 worker 写入身份与 inbox 文件保存团队配置然后以扇出fan-out方式对每个 worker 调用runWorkerStartupAttempt()。源码在 runtime.ts 处明确注释了关键设计在任何单 worker 的就绪等待或启动证据闸门可能阻塞后续 worker 之前必须先把所有 worker 的持久化启动状态物化完毕并随即打点identity_inbox_written标记。第 3 步就绪轮询。没有initialPrompt的交互式 worker 会先调用waitForWorkerReadyAsync()或更细粒度的waitForWorkerReadyDetailedAsync()再进入dispatchCriticalInboxInstruction()。这两个异步实现位于 tmux-session.ts默认超时 30 秒被设计为同步版本的「异步孪生」在轮询之间主动让出事件循环确保一个慢速 worker 窗格不会阻塞后续 worker 的启动尝试。第 4 步默认分发策略。默认策略是hook_preferred_with_fallback启动期 inbox 分发先进入 notify hook 队列等待回执若回执失败或超时再回退到直接 tmux 发送。实现上queueInboxInstruction()见 mcp-comm.ts依次完成writeWorkerInbox→enqueueDispatchRequest→ 调用 notify 回调 →markDispatchRequestNotified最终dispatchCriticalInboxInstruction()通过waitForDispatchReceipt()以dispatch_ack_timeout_ms为超时、50ms 为轮询间隔等待回执见 runtime.ts。第 5 步启动证据确认。分发可额外等待waitForWorkerStartupEvidence()只有观察到证据后才将首次触发视为「已结算」。证据类型包括task_claim任务认领、worker_progressworker 进度、leader_ackleader 确认与none。三、必须插桩的延迟阶段8 个相位标记与运维视图契约要求启动计时日志使用单调时钟增量源码中startTeam用performance.now()计算elapsed_ms并且至少为每个 worker 记录下表全部相位标记标记含义pane_id_capturedcreateTeamSession()已返回 worker pane ididentity_inbox_writtenworker 身份与 inbox 状态已写入ready_wait_start交互式就绪轮询开始ready_wait_end就绪轮询返回 ready、超时或命中提示守卫dispatch_queued启动期 inbox 分发请求已持久化hook_receipthook 优先路径观察到notified、delivered、failed或超时direct_trigger_attempt已尝试直接 tmux 触发注入direct_trigger_result已记录直接注入结果startup_evidence观察到 worker 启动证据task_claim/worker_progress/leader_ack/none从源码结构看相位类型在 runtime.ts 中被建模为StartupTimingPhase联合类型实际包含startup_direct_bypass、split_returned、identity_inbox_written、ready_wait_start、ready_wait_end、dispatch_queued、hook_receipt、direct_fallback、startup_evidence等成员每个事件带有at时间戳与elapsed_ms自起点毫秒数。打点结果通过logStartupTiming()runtime.ts写入团队投递日志appendTeamDeliveryLogForCwd事件类型为startup_timing字段包含startup_event、pane_id、elapsed_ms、reason、request_id与transport。契约还定义了常量STARTUP_TIMING_LOG_VERSION 1runtime.ts便于日志格式演进。对运维最有价值的摘要视图是每个 worker 从pane_id_captured到首次触发尝试的 delta再加上最终启动结算来自哪条路径——hook 投递、直接回退、还是异步证据。四、快速路径安全契约直连触发仅限启动期契约允许实现「仅限启动期的直连触发快速路径」startup-only direct-trigger fast path但必须同时满足以下全部条件缺一不可仅用于团队启动期间的首次 worker inbox 触发不可被后续流程复用持久化分配状态已写入task JSON、identity JSON、inbox、manifest/config 中的 pane id以及分发请求元数据不得替代或绕过后续 worker 消息的 mailbox 分发不得透过可见的 Codex trust 提示发送不得透过可见的 Claude bypass-permissions 提示发送除非现有显式 auto-accept 路径已先处理过该提示不得因为直接触发被尝试过就把 hook 投递标记为成功当 worker 窗格存活时缺少启动证据应作为可恢复的可观测性问题上报且不得阻止兄弟 worker 收到各自的启动触发。在实现层面这一快速路径由attemptStartupDirectTrigger()承载runtime.ts交互式启动且无initialPrompt时它会在就绪等待之前先尝试直接触发但前提是通过evaluateStartupDirectTriggerSafety()的安全性评估。该评估函数tmux-session.ts会抓取窗格可见内容并依次判定Codex bypass-MDM 不兼容、paneHasTrustPrompt信任提示、claude_bypass_prompt、bootstrapping、not_agent_viewport等不安全情形任何一项命中都返回{ safe: false }并打点startup_direct_bypass从而把「可见提示注入」从快速路径中彻底排除。五、审查清单六项验收标准实现评审时应逐项核对以下清单源自契约原文启动计时插桩记录了上文全部相位标记且不把 hook/证据确认纳入首次触发关键路径直连触发快速路径仅限启动期一般 mailbox 或后续分发无法触达信任提示与 bypass 提示守卫复用waitForWorkerReadyAsync()/ notify-hook 分发相同的窗格捕获安全语义分发请求状态仍以pending、notified、delivered、failed为权威计时日志仅作佐证非启动消息的既有hook_preferred_with_fallbackmailbox 行为保持不变测试将就绪延迟、hook 回执/证据延迟、启动快速路径分别隔离失败时能定位到具体回退的阶段。六、预期回归测试五个必须覆盖的场景契约列出了五类必须覆盖的回归测试仓库的 runtime.test.ts 已出现与之一一对应的用例可作为验收锚点慢就绪不再拖延首次分发运行时测试证明慢速waitForWorkerReadyAsync()过去会把首次启动分发拖延到配置的就绪超时上限。对应用例如startTeam rejects ready-prompt timeout when dispatch never produces startup evidenceruntime.test.ts。hook 优先启动分发不再等待证据才尝试首次安全触发对应interactive startup should wait for slow Codex evidence与startTeam treats a confirmed ready prompt as startup evidence after hook notificationruntime.test.ts。无可见提示直连触发tmux/session 或 notify-hook 守卫测试证明启动期直连触发不会透过可见的信任或 bypass 提示发送。mailbox 回归证明启动之外普通 mailbox 分发仍走既有 hook 优先/回退行为。多 worker 启动隔离证明 worker-1 的证据延迟不会阻塞 worker-2 收到首次触发。对应用例为startTeam materializes all worker identity/inbox files before worker-1 startup evidence can block later workersruntime.test.ts该测试断言 worker-2 的持久化状态在 worker-1 的启动证据失败拒绝启动之前就已存在。此外waitForClaudeStartupEvidence requires first-start ACK/task progress before startup dispatch is treated as settledruntime.test.ts与startTeam rejects tmux fallback when worker startup evidence stays missingruntime.test.ts共同覆盖了证据判定与回退路径的失败语义。七、已知审查风险改动时必须保留的三条红线契约明确警示了三个高风险点评审与实现都应格外小心就绪函数里藏着安全逻辑waitForWorkerReadyAsync()当前包含有用的提示处理安全逻辑。把触发提前时必须保留其提示守卫而不是从启动故事中删除它们。源码佐证waitForWorkerReadyDetailedAsync会检查信任/授权提示并调用dismissTrustPromptIfPresent()可通过环境变量OMX_TEAM_AUTO_TRUST0关闭自动解除见 tmux-session.ts同时shouldSkipWorkerReadyWait()支持OMX_TEAM_SKIP_READY_WAIT1跳过就绪等待但只应在受控环境使用。确认与证据语义必须分离notify-hook 的注入后验证在窗格未就绪时会刻意拒绝确认 worker 分发。启动快速路径可以提前尝试触发但必须把「确认」与「证据」两套语义分开。实现中waitForDispatchReceipt只负责回执而waitForWorkerStartupEvidence的默认超时STARTUP_EVIDENCE_TIMEOUT_MS 15_000、轮询STARTUP_EVIDENCE_POLL_MS 100、启动窗口上限STARTUP_EVIDENCE_LAUNCH_TIMEOUT_MS 45_000runtime.ts构成独立的证据判定层。不同 CLI 的证据口径不同Codex 的 ACK-only 消息不足以结算启动而 Claude 的 leader ACK 可作为证据。源码中doesStartupEvidenceSettle()明确编码了这一差异evidence leader_ack workerCli codex时返回 falseruntime.ts。评审者在解读计时日志时必须保持这一区分。八、落地建议如何验证与观测要观察这套契约在真实环境中的表现可参考以下路径查看团队状态omx team status team-name具体命令以 cli/team.ts 实现为准定位启动时序日志startup_timing事件写入团队投递日志appendTeamDeliveryLogForCwd实现见 delivery-log.ts按startup_event字段过滤即可还原单个 worker 的完整启动时间线对照权威状态分发请求状态机pending/notified/delivered/failed的实现与迁移逻辑见 state/dispatch.ts 与teamTransitionDispatchRequest计时日志只应作为佐证而非状态权威复现边界场景直接运行npm test -- runtime以 package.json 脚本为准中的启动相关用例重点观察runtime.test.ts里证据缺失、提示超时、多 worker 物化顺序三类场景的断言输出。总结OmX 团队启动分发延迟契约的实质是在「尽快触发」与「绝不越界」之间划定一条清晰的边界——用单调时序把启动窗口切成可观测的相位用快速路径把首次触发的等待从就绪/证据闸门中剥离同时用安全守卫、状态权威与隔离测试确保 mailbox 语义、提示安全与多 worker 并发不受侵蚀。任何对该窗口的改动都应回到这份契约的清单逐项验收。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OmX 团队启动分发延迟契约：tmux 窗格创建到首次 inbox 触发的时间窗口治理
OmX 团队启动分发延迟契约tmux 窗格创建到首次 inbox 触发的时间窗口治理【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex导读本文解析 OmXoh-my-codex团队模式下 worker 启动分发的核心性能与正确性契约聚焦「tmux worker 窗格创建完成」到「worker 收到首条 inbox 触发指令」之间的启动窗口。通过阅读本文你将掌握该窗口内的完整调用链、必须插桩的 8 个延迟阶段标记、启动期直连触发快速路径的安全边界以及如何用针对性回归测试验证每个延迟阶段是否回退。一、契约背景与范围延迟不在任务分配而在三道闸门docs/contracts/team-startup-dispatch-latency.md记录了针对团队启动分配延迟修复的评审契约。首先要澄清一个关键事实该问题的本质不是任务分配。在启动通知尝试开始之前任务task JSON、worker 身份identity JSON和 worker inbox 文件已经全部落盘为持久化状态。真正的延迟风险集中在窗格创建与首次触发之间依次排列的三道闸门就绪闸门readiness gate交互式 worker 需要等待其 CLI 进入可交互状态分发闸门dispatch gate默认策略要求 inbox 分发先进入 notify hook 队列并等待回执启动证据闸门startup-evidence gate触发结果被认定为「已结算」前还需观察到 worker 的启动证据。契约的目标是让第一道触发指令尽快到达 worker同时不破坏 worker 的身份权威、信任提示安全语义与后续 mailbox 分发行为。二、受审的当前启动路径五步调用链拆解契约明确定义了当前被评审的启动路径以下每一步都可以在仓库源码中找到对应实现第 1 步创建窗格。tmux-session.ts 中的createTeamSession()分割 leader/worker 窗格并返回具体的workerPaneIds形如%12、%13的 tmux pane id。调用方随后通过applyCreatedInteractiveSessionToConfig()将这些 pane id 写回config.workers[i].pane_id与pid为后续的精确窗格校验readExactPaneProofSync奠定基础。第 2 步落盘持久化状态。runtime.ts 中的startTeam()为每个 worker 写入身份与 inbox 文件保存团队配置然后以扇出fan-out方式对每个 worker 调用runWorkerStartupAttempt()。源码在 runtime.ts 处明确注释了关键设计在任何单 worker 的就绪等待或启动证据闸门可能阻塞后续 worker 之前必须先把所有 worker 的持久化启动状态物化完毕并随即打点identity_inbox_written标记。第 3 步就绪轮询。没有initialPrompt的交互式 worker 会先调用waitForWorkerReadyAsync()或更细粒度的waitForWorkerReadyDetailedAsync()再进入dispatchCriticalInboxInstruction()。这两个异步实现位于 tmux-session.ts默认超时 30 秒被设计为同步版本的「异步孪生」在轮询之间主动让出事件循环确保一个慢速 worker 窗格不会阻塞后续 worker 的启动尝试。第 4 步默认分发策略。默认策略是hook_preferred_with_fallback启动期 inbox 分发先进入 notify hook 队列等待回执若回执失败或超时再回退到直接 tmux 发送。实现上queueInboxInstruction()见 mcp-comm.ts依次完成writeWorkerInbox→enqueueDispatchRequest→ 调用 notify 回调 →markDispatchRequestNotified最终dispatchCriticalInboxInstruction()通过waitForDispatchReceipt()以dispatch_ack_timeout_ms为超时、50ms 为轮询间隔等待回执见 runtime.ts。第 5 步启动证据确认。分发可额外等待waitForWorkerStartupEvidence()只有观察到证据后才将首次触发视为「已结算」。证据类型包括task_claim任务认领、worker_progressworker 进度、leader_ackleader 确认与none。三、必须插桩的延迟阶段8 个相位标记与运维视图契约要求启动计时日志使用单调时钟增量源码中startTeam用performance.now()计算elapsed_ms并且至少为每个 worker 记录下表全部相位标记标记含义pane_id_capturedcreateTeamSession()已返回 worker pane ididentity_inbox_writtenworker 身份与 inbox 状态已写入ready_wait_start交互式就绪轮询开始ready_wait_end就绪轮询返回 ready、超时或命中提示守卫dispatch_queued启动期 inbox 分发请求已持久化hook_receipthook 优先路径观察到notified、delivered、failed或超时direct_trigger_attempt已尝试直接 tmux 触发注入direct_trigger_result已记录直接注入结果startup_evidence观察到 worker 启动证据task_claim/worker_progress/leader_ack/none从源码结构看相位类型在 runtime.ts 中被建模为StartupTimingPhase联合类型实际包含startup_direct_bypass、split_returned、identity_inbox_written、ready_wait_start、ready_wait_end、dispatch_queued、hook_receipt、direct_fallback、startup_evidence等成员每个事件带有at时间戳与elapsed_ms自起点毫秒数。打点结果通过logStartupTiming()runtime.ts写入团队投递日志appendTeamDeliveryLogForCwd事件类型为startup_timing字段包含startup_event、pane_id、elapsed_ms、reason、request_id与transport。契约还定义了常量STARTUP_TIMING_LOG_VERSION 1runtime.ts便于日志格式演进。对运维最有价值的摘要视图是每个 worker 从pane_id_captured到首次触发尝试的 delta再加上最终启动结算来自哪条路径——hook 投递、直接回退、还是异步证据。四、快速路径安全契约直连触发仅限启动期契约允许实现「仅限启动期的直连触发快速路径」startup-only direct-trigger fast path但必须同时满足以下全部条件缺一不可仅用于团队启动期间的首次 worker inbox 触发不可被后续流程复用持久化分配状态已写入task JSON、identity JSON、inbox、manifest/config 中的 pane id以及分发请求元数据不得替代或绕过后续 worker 消息的 mailbox 分发不得透过可见的 Codex trust 提示发送不得透过可见的 Claude bypass-permissions 提示发送除非现有显式 auto-accept 路径已先处理过该提示不得因为直接触发被尝试过就把 hook 投递标记为成功当 worker 窗格存活时缺少启动证据应作为可恢复的可观测性问题上报且不得阻止兄弟 worker 收到各自的启动触发。在实现层面这一快速路径由attemptStartupDirectTrigger()承载runtime.ts交互式启动且无initialPrompt时它会在就绪等待之前先尝试直接触发但前提是通过evaluateStartupDirectTriggerSafety()的安全性评估。该评估函数tmux-session.ts会抓取窗格可见内容并依次判定Codex bypass-MDM 不兼容、paneHasTrustPrompt信任提示、claude_bypass_prompt、bootstrapping、not_agent_viewport等不安全情形任何一项命中都返回{ safe: false }并打点startup_direct_bypass从而把「可见提示注入」从快速路径中彻底排除。五、审查清单六项验收标准实现评审时应逐项核对以下清单源自契约原文启动计时插桩记录了上文全部相位标记且不把 hook/证据确认纳入首次触发关键路径直连触发快速路径仅限启动期一般 mailbox 或后续分发无法触达信任提示与 bypass 提示守卫复用waitForWorkerReadyAsync()/ notify-hook 分发相同的窗格捕获安全语义分发请求状态仍以pending、notified、delivered、failed为权威计时日志仅作佐证非启动消息的既有hook_preferred_with_fallbackmailbox 行为保持不变测试将就绪延迟、hook 回执/证据延迟、启动快速路径分别隔离失败时能定位到具体回退的阶段。六、预期回归测试五个必须覆盖的场景契约列出了五类必须覆盖的回归测试仓库的 runtime.test.ts 已出现与之一一对应的用例可作为验收锚点慢就绪不再拖延首次分发运行时测试证明慢速waitForWorkerReadyAsync()过去会把首次启动分发拖延到配置的就绪超时上限。对应用例如startTeam rejects ready-prompt timeout when dispatch never produces startup evidenceruntime.test.ts。hook 优先启动分发不再等待证据才尝试首次安全触发对应interactive startup should wait for slow Codex evidence与startTeam treats a confirmed ready prompt as startup evidence after hook notificationruntime.test.ts。无可见提示直连触发tmux/session 或 notify-hook 守卫测试证明启动期直连触发不会透过可见的信任或 bypass 提示发送。mailbox 回归证明启动之外普通 mailbox 分发仍走既有 hook 优先/回退行为。多 worker 启动隔离证明 worker-1 的证据延迟不会阻塞 worker-2 收到首次触发。对应用例为startTeam materializes all worker identity/inbox files before worker-1 startup evidence can block later workersruntime.test.ts该测试断言 worker-2 的持久化状态在 worker-1 的启动证据失败拒绝启动之前就已存在。此外waitForClaudeStartupEvidence requires first-start ACK/task progress before startup dispatch is treated as settledruntime.test.ts与startTeam rejects tmux fallback when worker startup evidence stays missingruntime.test.ts共同覆盖了证据判定与回退路径的失败语义。七、已知审查风险改动时必须保留的三条红线契约明确警示了三个高风险点评审与实现都应格外小心就绪函数里藏着安全逻辑waitForWorkerReadyAsync()当前包含有用的提示处理安全逻辑。把触发提前时必须保留其提示守卫而不是从启动故事中删除它们。源码佐证waitForWorkerReadyDetailedAsync会检查信任/授权提示并调用dismissTrustPromptIfPresent()可通过环境变量OMX_TEAM_AUTO_TRUST0关闭自动解除见 tmux-session.ts同时shouldSkipWorkerReadyWait()支持OMX_TEAM_SKIP_READY_WAIT1跳过就绪等待但只应在受控环境使用。确认与证据语义必须分离notify-hook 的注入后验证在窗格未就绪时会刻意拒绝确认 worker 分发。启动快速路径可以提前尝试触发但必须把「确认」与「证据」两套语义分开。实现中waitForDispatchReceipt只负责回执而waitForWorkerStartupEvidence的默认超时STARTUP_EVIDENCE_TIMEOUT_MS 15_000、轮询STARTUP_EVIDENCE_POLL_MS 100、启动窗口上限STARTUP_EVIDENCE_LAUNCH_TIMEOUT_MS 45_000runtime.ts构成独立的证据判定层。不同 CLI 的证据口径不同Codex 的 ACK-only 消息不足以结算启动而 Claude 的 leader ACK 可作为证据。源码中doesStartupEvidenceSettle()明确编码了这一差异evidence leader_ack workerCli codex时返回 falseruntime.ts。评审者在解读计时日志时必须保持这一区分。八、落地建议如何验证与观测要观察这套契约在真实环境中的表现可参考以下路径查看团队状态omx team status team-name具体命令以 cli/team.ts 实现为准定位启动时序日志startup_timing事件写入团队投递日志appendTeamDeliveryLogForCwd实现见 delivery-log.ts按startup_event字段过滤即可还原单个 worker 的完整启动时间线对照权威状态分发请求状态机pending/notified/delivered/failed的实现与迁移逻辑见 state/dispatch.ts 与teamTransitionDispatchRequest计时日志只应作为佐证而非状态权威复现边界场景直接运行npm test -- runtime以 package.json 脚本为准中的启动相关用例重点观察runtime.test.ts里证据缺失、提示超时、多 worker 物化顺序三类场景的断言输出。总结OmX 团队启动分发延迟契约的实质是在「尽快触发」与「绝不越界」之间划定一条清晰的边界——用单调时序把启动窗口切成可观测的相位用快速路径把首次触发的等待从就绪/证据闸门中剥离同时用安全守卫、状态权威与隔离测试确保 mailbox 语义、提示安全与多 worker 并发不受侵蚀。任何对该窗口的改动都应回到这份契约的清单逐项验收。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考