claw-code 可靠 Worker 启动与会话控制：G003 boot/session/preflight 验证地图全解

claw-code 可靠 Worker 启动与会话控制：G003 boot/session/preflight 验证地图全解

【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code

导读

本文基于 claw-code 仓库的docs/g003-boot-session-verification-map.md审计/集成地图，系统梳理 Stream 1 可靠 Worker 启动（boot）与会话控制（session control）的实现面：从 Worker 生命周期状态机、信任门禁（trust gate）与启动无证据分类器，到会话按工作区指纹隔离、CLI/status/sandbox/doctor与预检守卫。读完本文，你将掌握 G003 验证地图对应的 Rust 源码结构、可用测试命令与已知缺口，并理解如何在rust/下按推荐顺序做增量集成验证。

一、文档定位：一份只审计不修改的集成验证地图

G003 验证地图由worker-1为 OMX 团队 task 2 生成（生成日期 2026-05-14），其边界非常明确：它是一份audit/integration map（审计/集成映射），不会修改.omx/ultragoal，也不改动共享实现或测试。这意味着本文档的作用是给 Leader 集成阶段提供"哪些代码属于哪条 lane、应该跑哪些测试、存在哪些缺口"的导航。

文档记录的多 worker 任务分工如下：

• worker-1：task 1 worker boot / prompt SLA，以及本 task 2 审计地图；
• worker-2：默认可信根（default trusted roots）/ trust resolver；
• worker-3：启动无证据（startup-no-evidence）分类器；
• worker-4：会话控制，以及 preflight/doctor JSON 输出面。

一个值得注意的细节：Task 2 期间曾尝试原生子代理探测（test probe与debug/root-cause probe），但两者都在返回结果前以429 Too Many Requests失败，因此地图内容基于直接仓库检查完成。这解释了为什么文中几乎所有结论都能回溯到具体源码文件。

二、Worker 启动生命周期与 Prompt SLA

2.1 核心状态类型（源码实测）

rust/crates/runtime/src/worker_boot.rs是 worker-boot 状态机与内存控制注册表的实现主体。文件头注释明确其定位：在原始终端传输（raw terminal transport）之上提供可信的 worker 启动控制面，包括信任门禁检测、ready-for-prompt 握手、prompt 误投递检测与恢复。

源码定义的核心状态类型包括：

WorkerStatus枚举（serde(rename_all = "snake_case")）覆盖的六种生命周期状态与文档一致：spawning、trust_required、tool_permission_required、ready_for_prompt、running、finished、failed。

2.2 控制面 API 与状态转换

WorkerRegistry是控制平面入口，底层以Arc<Mutex<WorkerRegistryInner>>保存HashMap<String, Worker>与自增计数器，worker_id 形如worker_{timestamp}_{counter}。文档列出的控制面方法全部可在源码中一一对应：

• create(cwd, trusted_roots, auto_recover_prompt_misdelivery)：创建 worker 时即根据trusted_roots判定trust_auto_resolve，并发出Spawning事件；
• observe(worker_id, screen_text)：屏幕文本观测是状态机推进的核心——按优先级检测工具权限提示（ToolPermissionRequired）、信任提示（TrustRequired，若 allowlist 命中则自动TrustResolved）、prompt 误投递（PromptMisdelivery，可自动 armedPromptReplayArmed）、运行提示（Running）与就绪提示（ReadyForPrompt）；
• resolve_trust(worker_id)：仅在TrustRequired状态下手动放行信任门禁；
• send_prompt(worker_id, prompt, task_receipt)：仅在ReadyForPrompt状态下发 prompt，递增prompt_delivery_attempts、置prompt_in_flight并进入Running；
• await_ready(worker_id)：返回WorkerReadySnapshot（ready、blocked、replay_prompt_ready、last_error）；
• restart(worker_id)/terminate(worker_id)：重置到Spawning/ 置为Finished；
• observe_completion(worker_id, finish_reason, tokens_output)：对finish="unknown"且tokens=0或finish="error"归类为 Provider 失败并进入Failed，否则正常Finished；
• observe_startup_timeout(worker_id, pane_command, transport_healthy, mcp_healthy)：构建StartupEvidenceBundle并调用分类器。

2.3 启动无证据分类器的判定逻辑

observe_startup_timeout收集证据包（最后生命周期状态、pane 命令与观测时间、prompt 发送时间、prompt 接受状态、信任/工具权限提示检测结果、transport/MCP 健康占位摘要、elapsed_seconds），随后classify_startup_failure按优先级判定：

1. transport 不健康 →TransportDead；
2. 检测到信任提示且停在TrustRequired→TrustRequired；
3. 检测到工具权限提示且停在ToolPermissionRequired→ToolPermissionRequired；
4. 已发送 prompt 但未接受且停在Running→PromptAcceptanceTimeout；
5. 已发送 prompt 未接受且 elapsed > 30s →PromptMisdelivery；
6. MCP 不健康但 transport 正常 →WorkerCrashed；
7. 兜底 →Unknown。

transport 与 MCP 的健康摘要目前是占位字符串（{name}_{healthy|unhealthy}_placeholder），源码注释明确说明"直到更深的 transport 与 MCP 探测接入为止"，这正对应文档中"完整终端/传输集成仍需验证"的缺口描述。

2.4 文件级可观测面：.claw/worker-state.json

emit_state_file在每次状态转换（push_event）时，将快照原子写入 worker cwd 下的.claw/worker-state.json（先写.tmp再rename）。快照字段包括worker_id、status、is_ready、trust_gate_cleared、prompt_in_flight、last_event、updated_at，以及关键的seconds_since_update——源码注释说明外部观察者（如 clawhip、orchestrator）轮询该文件即可检测停滞 worker，无需在二进制上暴露 HTTP 路由。

三、信任解析器与默认可信根

3.1 信任模型与事件

rust/crates/runtime/src/trust_resolver.rs定义了信任解析三件套：

• TrustConfig：allowlisted（TrustAllowlistEntry列表）、denied（PathBuf列表）、emit_events（默认true）；
• TrustPolicy：AutoTrust/RequireApproval/Deny；
• TrustEvent：TrustRequired（携带 cwd、可选 repo/worktree）、TrustResolved（携带 policy 与TrustResolution）、TrustDenied（携带 reason）。

TrustAllowlistEntry支持pattern、可选worktree_pattern与description，并提供with_worktree_pattern、with_description等构建器。

源码中内置的信任提示检测线索（TRUST_PROMPT_CUES）包括："do you trust the files in this folder"、"trust the files in this folder"、"trust this folder"、"allow and continue"、"yes, proceed" 等，是observe中detect_trust_prompt的匹配依据。

3.2 前缀匹配的已知隐患

pattern_matches支持精确匹配、目录前缀包含、/*尾通配、路径组件匹配、子串匹配以及基于递归回溯的 glob 匹配。文档明确标记的 hazard 是：前缀匹配必须避免意外命中兄弟目录，例如/tmp/work不得匹配/tmp/work-evil。从源码看，目录前缀分支要求剩余部分为空或以/开头，正是为了规避该问题；文档同时声明这块属于 worker-2 的变更范围。

3.3 配置侧的 trustedRoots

rust/crates/runtime/src/config.rs中：

• parse_optional_trusted_roots从 settings JSON 解析trustedRoots；
• RuntimeConfig::trusted_roots()与 feature config accessor 暴露解析结果；
• trusted_roots_with_overrides通过merge_trusted_roots将配置根与每次调用的根合并（去重），tools/src/lib.rs的run_worker_create正是用该合并结果调用WorkerRegistry::create；
• 当前默认：未设置时为空（trusted_roots_default_is_empty_when_unset测试锁定该行为），任何项目级默认根变更归 worker-2。

四、会话控制：按工作区指纹隔离

rust/crates/runtime/src/session_control.rs的SessionStore将托管会话命名空间按**规范工作区指纹（canonical workspace fingerprint）**隔离。其关键设计（源码中引用 issue #151）：

• from_cwd/from_data_dir先fs::canonicalize工作区路径，确保符号链接、相对路径等等价路径得到一致的指纹（workspace_fingerprint生成稳定 hex 摘要），再落盘到.claw/sessions/{fingerprint}/；
• 会话既有全局根（~/.claw/sessions/）也有项目本地根（<cwd>/.claw/sessions/）两个扫描路径；
• resolve_reference、resolve_managed_path、list_sessions、latest_session、load_session、fork_session等 API 构成完整会话管理面；
• 关键 guardrail：validate_loaded_session拒绝跨工作区会话，遗留会话仅当其路径仍位于当前工作区内部时才被允许（canonicalize_for_compare(path).starts_with(canonicalize_for_compare(workspace_root))）。

五、CLI doctor/status/preflight 与引导相邻面

5.1 Slash 命令与 JSON 渲染

rust/crates/commands/src/lib.rs定义并渲染/status（"Show current session status"）、/sandbox（"Show sandbox isolation status"）、/doctor等斜杠命令，并在同一模块内提供 JSON 渲染的 handler 与测试（如"status": "ok"/"degraded"的报告结构）。/status、/sandbox同时出现在 REPL 的 help 建议与handle_slash_command测试中。

5.2 Bash/PowerShell 工具的预检守卫

rust/crates/tools/src/lib.rs的 Bash/PowerShell 工具执行前调用workspace_test_branch_preflight：当"broad workspace tests"（全工作区测试）在落后于 main 的分支上执行时，返回结构化输出return_code_interpretation: preflight_blocked:branch_divergence；而定向/针对性测试（targeted tests）则跳过该预检。对应测试包括bash_workspace_tests_are_blocked_when_branch_is_behind_main与bash_targeted_tests_skip_branch_preflight。

5.3 工具面暴露的 Worker 控制平面

tools/src/lib.rs将WorkerRegistry控制面暴露为工具 API：WorkerCreate、WorkerGet、WorkerObserve、WorkerResolveTrust、WorkerAwaitReady、WorkerSendPrompt、WorkerRestart、WorkerTerminate、WorkerObserveCompletion。工具级测试覆盖 create/observe/send/restart/terminate/completion 与状态文件转换，其中WorkerCreate在未传 per-calltrusted_roots时会从配置供给（trusted_roots_with_overrides），并在创建后断言.claw/worker-state.json已写入。

六、现有聚焦验证命令

以下命令均在rust/目录下运行（文档原样保留，按 crate 分门别类）：

# Worker boot 运行时契约 cargo test -p runtime worker_boot -- --nocapture # Worker 工具 API 契约 cargo test -p tools worker_ -- --nocapture # 会话控制契约 cargo test -p runtime session_control -- --nocapture # 信任解析器 / 配置可信根 cargo test -p runtime trust_resolver -- --nocapture cargo test -p runtime config::tests::parses_trusted_roots_from_settings config::tests::trusted_roots_default_is_empty_when_unset -- --nocapture # Preflight / 工具分支守卫 cargo test -p tools bash_workspace_tests_are_blocked_when_branch_is_behind_main bash_targeted_tests_skip_branch_preflight -- --nocapture # 格式化 / 类型 / lint 基线 ../scripts/fmt.sh --check cargo check -p runtime -p tools -p commands cargo clippy -p runtime -p tools -p commands --all-targets --no-deps -- -D warnings

这些命令与源码中的测试模块一一对应（例如worker_boot.rs内的restart_and_terminate_reset_or_finish_worker、observe_completion_classifies_provider_failure_on_unknown_finish_zero_tokens、emit_state_file_writes_worker_status_on_transition、await_ready_surfaces_blocked_or_ready_worker_state等）。

七、已知缺口与集成注意点

文档为 Leader 集成列出四项明确缺口，与源码行为完全吻合：

1. Prompt SLA 事件命名部分隐式：send_prompt只发出WorkerEventKind::Running，未暴露独立的prompt.sent/prompt.accepted/prompt.acceptance_delayed/prompt.acceptance_timeout事件名；当前等价证据是prompt_in_flight、Running、observe_completion与启动超时分类。
2. PromptAcceptanceTimeout的端到端验证：该分类已有worker_boot单元测试覆盖，但若真实 pane watcher 存在于内存注册表之外，仍需 Leader 或 worker-3 做完整终端/传输集成验证。
3. 默认可信根：trustedRoots已解析并合并进WorkerCreate，但未设置时默认无根；默认根选择变更归 worker-2。
4. 会话控制的守卫范围：工作区指纹在 load/fork 时受保护，而 CLI/doctor/preflight 的 JSON 契约变更归 worker-4。

另外注意：task 1 验证期间全工作区 clippy 存在已知且无关的 runtime 发现，本文档不阻塞该 docs-only 地图，除非 Leader 重新界定清理范围。

八、推荐的安全集成顺序

文档给出的五步集成顺序（每个步骤都对应具体验证命令）如下：

1. 先集成 worker boot / prompt SLA：运行cargo test -p runtime worker_boot -- --nocapture与cargo test -p tools worker_ -- --nocapture；
2. 集成信任根变更：重跑 trust/config 测试与 worker create 配置合并测试（config::tests::trusted_roots_with_overrides_*相关用例）；
3. 集成启动无证据分类器变更：重跑cargo test -p runtime worker_boot -- --nocapture；
4. 集成会话控制 / preflight / doctor JSON 变更：重跑 session-control、commands JSON 与 preflight 测试；
5. 收尾：运行格式化、定向 cargo check/clippy，再跑更广的工作区测试，将已知的全工作区失败单独记录。

九、给集成者的最小行动清单

• 只读理解路径：先读docs/g003-boot-session-verification-map.md作为导航，再对照rust/crates/runtime/src/worker_boot.rs（状态机）、rust/crates/runtime/src/trust_resolver.rs（信任策略）、rust/crates/runtime/src/session_control.rs（会话指纹）逐层印证；
• 验证入口：在rust/下按第六节命令跑每一条 lane 的契约测试；
• 观察出口：状态转换期间检查 worker cwd 下的.claw/worker-state.json，确认seconds_since_update可用于停滞检测；
• 边界意识：任何对默认信任根、事件命名、会话/doctor JSON 契约的修改，分别归属 worker-2 / worker-3 / worker-4 的 lane，集成时不要越界。

结语

G003 验证地图的价值不在于罗列文件，而在于它把"可靠 worker 启动 + 会话控制"这条 Stream 1 主线拆成了可独立验证的 lane：启动状态机（worker-1）、信任解析（worker-2）、无证据分类（worker-3）、会话与输出面（worker-4）。配合本文从源码中补充的实现细节（分类器判定顺序、allowlist 前缀匹配规则、指纹规范化、状态文件原子写入、工具面合并可信根），读者可以在rust/下按推荐顺序逐步验证，并在已知缺口处保留明确的验证记录。

【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code