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-1task 1 worker boot / prompt SLA以及本 task 2 审计地图worker-2默认可信根default trusted roots/ trust resolverworker-3启动无证据startup-no-evidence分类器worker-4会话控制以及 preflight/doctor JSON 输出面。一个值得注意的细节Task 2 期间曾尝试原生子代理探测test probe与debug/root-cause probe但两者都在返回结果前以429 Too Many Requests失败因此地图内容基于直接仓库检查完成。这解释了为什么文中几乎所有结论都能回溯到具体源码文件。二、Worker 启动生命周期与 Prompt SLA2.1 核心状态类型源码实测rust/crates/runtime/src/worker_boot.rs是 worker-boot 状态机与内存控制注册表的实现主体。文件头注释明确其定位在原始终端传输raw terminal transport之上提供可信的 worker 启动控制面包括信任门禁检测、ready-for-prompt 握手、prompt 误投递检测与恢复。源码定义的核心状态类型包括类型作用WorkerStatus生命周期状态枚举WorkerFailureKind失败归类信任门禁/工具权限门禁/Prompt 投递/协议/Provider/启动无证据WorkerEventKind事件种类含StartupPreflightWarning、PromptMisdelivery、PromptReplayArmed、StartupNoEvidence等WorkerEventPayload事件负载trust/tool-permission/prompt-delivery/startup-no-evidence 等结构化数据StartupFailureClassification启动失败分类无证据时的推断结果StartupEvidenceBundle启动超时时收集的证据包WorkerTaskReceipt任务回执repo、task_kind、source_surface、expected_artifacts、objective_previewWorkerReadySnapshotawait_ready返回的就绪快照WorkerStatus枚举serde(rename_all snake_case)覆盖的六种生命周期状态与文档一致spawning、trust_required、tool_permission_required、ready_for_prompt、running、finished、failed。2.2 控制面 API 与状态转换WorkerRegistry是控制平面入口底层以ArcMutexWorkerRegistryInner保存HashMapString, 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与就绪提示ReadyForPromptresolve_trust(worker_id)仅在TrustRequired状态下手动放行信任门禁send_prompt(worker_id, prompt, task_receipt)仅在ReadyForPrompt状态下发 prompt递增prompt_delivery_attempts、置prompt_in_flight并进入Runningawait_ready(worker_id)返回WorkerReadySnapshotready、blocked、replay_prompt_ready、last_errorrestart(worker_id)/terminate(worker_id)重置到Spawning/ 置为Finishedobserve_completion(worker_id, finish_reason, tokens_output)对finishunknown且tokens0或finisherror归类为 Provider 失败并进入Failed否则正常Finishedobserve_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按优先级判定transport 不健康 →TransportDead检测到信任提示且停在TrustRequired→TrustRequired检测到工具权限提示且停在ToolPermissionRequired→ToolPermissionRequired已发送 prompt 但未接受且停在Running→PromptAcceptanceTimeout已发送 prompt 未接受且 elapsed 30s →PromptMisdeliveryMCP 不健康但 transport 正常 →WorkerCrashed兜底 →Unknown。transport 与 MCP 的健康摘要目前是占位字符串{name}_{healthy|unhealthy}_placeholder源码注释明确说明直到更深的 transport 与 MCP 探测接入为止这正对应文档中完整终端/传输集成仍需验证的缺口描述。2.4 文件级可观测面.claw/worker-state.jsonemit_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定义了信任解析三件套TrustConfigallowlistedTrustAllowlistEntry列表、deniedPathBuf列表、emit_events默认trueTrustPolicyAutoTrust/RequireApproval/DenyTrustEventTrustRequired携带 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 配置侧的 trustedRootsrust/crates/runtime/src/config.rs中parse_optional_trusted_roots从 settings JSON 解析trustedRootsRuntimeConfig::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 #151from_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 构成完整会话管理面关键 guardrailvalidate_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定义并渲染/statusShow current session status、/sandboxShow 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控制面暴露为工具 APIWorkerCreate、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 集成列出四项明确缺口与源码行为完全吻合Prompt SLA 事件命名部分隐式send_prompt只发出WorkerEventKind::Running未暴露独立的prompt.sent/prompt.accepted/prompt.acceptance_delayed/prompt.acceptance_timeout事件名当前等价证据是prompt_in_flight、Running、observe_completion与启动超时分类。PromptAcceptanceTimeout的端到端验证该分类已有worker_boot单元测试覆盖但若真实 pane watcher 存在于内存注册表之外仍需 Leader 或 worker-3 做完整终端/传输集成验证。默认可信根trustedRoots已解析并合并进WorkerCreate但未设置时默认无根默认根选择变更归 worker-2。会话控制的守卫范围工作区指纹在 load/fork 时受保护而 CLI/doctor/preflight 的 JSON 契约变更归 worker-4。另外注意task 1 验证期间全工作区 clippy 存在已知且无关的 runtime 发现本文档不阻塞该 docs-only 地图除非 Leader 重新界定清理范围。八、推荐的安全集成顺序文档给出的五步集成顺序每个步骤都对应具体验证命令如下先集成 worker boot / prompt SLA运行cargo test -p runtime worker_boot -- --nocapture与cargo test -p tools worker_ -- --nocapture集成信任根变更重跑 trust/config 测试与 worker create 配置合并测试config::tests::trusted_roots_with_overrides_*相关用例集成启动无证据分类器变更重跑cargo test -p runtime worker_boot -- --nocapture集成会话控制 / preflight / doctor JSON 变更重跑 session-control、commands JSON 与 preflight 测试收尾运行格式化、定向 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考