docs(auto-research): add stop/takeover and state-aware wake walkthrou… - #3113
docs(auto-research): add stop/takeover and state-aware wake walkthrou…#3113rootkiller6788 wants to merge 1 commit into
Conversation
…gh (GH-C43) Public-safe walkthrough proving stop marker lifecycle, state-aware wake filter, quota pause vs operator stop distinction, operator takeover command contract, and full stop/inspect/resume lifecycle. Exercises 11 scenarios across the shipped stop/takeover and state-aware wake transitions without adding a second launcher or altering the README.
huangruiteng
left a comment
huangruiteng
left a comment
There was a problem hiding this comment.
Review PR #3113 — exact head 1c1ed4ee3a7a140e09de274673c507cdef54768d
详细中文评审
动机
该 PR 为 Auto Research 的 operator 生命周期（stop/takeover 与 state-aware wake）补充一个面向贡献者的公开 walkthrough smoke（GH-C43）。这些行为是已上线的控制面契约：文件 stop marker 在每轮前被检查、quota_paused 与 operator_stop_requested 是不同语义、--attach takeover 命令、frontier 驱动的 state-aware wake，以及每个载荷都必须通过 public boundary 检查。此前这些契约分散在多个函数中，缺少一条可运行、可回归的公开验证路径；本次用一个独立示例把完整生命周期串起来，是比零散注释或 README 段落更可执行的修复方式。
改动思路
改动集中在单个新示例文件 examples/auto-research-stop-takeover-walkthrough-smoke.py，不触碰任何产品代码、不改 README、不引入第二个 launcher。示例直接复用真实 API：run_auto_research_worker_loop、run_auto_research_worker_turn、load_auto_research_worker_frontier、build_auto_research_demo_supervisor_plan 与 _seed_visible_demo_control_plane，并用合成 fixture 建临时控制面。11 个场景按 stop marker 生命周期、state-aware wake、quota/operator 语义区分、takeover 契约、public boundary 的顺序组织；每个场景的结果都经过 _assert_public_safe 检查，main() 汇总失败并返回非零退出码，适合直接跑在 CI 或本地。
具体改动
关键内容讲解
FORBIDDEN与_assert_public_safe：禁止词（/Users/、/private/、/tmp/、URL、api_key、password、secret、Windows 盘符）用字符串拼接构造，避免源码本身被扫描器误判；对每个场景的序列化载荷做不泄漏断言。_stop_marker与_seed：marker 是 workspace 下的.loopx-auto-research-stop；_seed用tempfile.mkdtemp创建临时 demo 控制面、registry 与 runtime root，并保证 shared workspace 存在。- 场景 1/2/3（stop marker 生命周期）：标记放在首轮前必须
operator_stop_requested且turn_count == 0；运行中放置标记在下一轮前生效，删除标记可恢复；max_rounds是正常结束信号，与 operator 干预区分。 - 场景 4/5/6（state-aware wake）：每个 agent 的 frontier 必须声明
public_boundary且载荷 public-safe；filter 的 reason code 必须带error_code、禁止裸异常字符串；零就绪 lane 时 wake receipt 必须是no_op_all_filtered、target_lanes == []，防止把空列表误当“唤醒全部”。 - 场景 7（语义区分）：
quota_paused、operator_stop_requested、no_executed_turns、no_runnable_frontier、max_rounds五个 stop reason 各不相同。 - 场景 8/9/10（takeover 与 boundary）：worker turn 在
execute=Falsedry-run 下具备ok/mode/agent_id/schema_version且 frontier 带public_boundary.source；takeover 命令loopx auto-research start ... --execute --attach与真实命令模板一致且 public-safe；loop 结果必须显式声明raw_logs/private_artifacts/absolute_paths/credentials均未记录。 - 场景 11（完整生命周期）：start → stop → inspect frontier → resume → stop again，全部走真实 worker-loop 与 frontier API。
对主干的风险
- 无产品代码改动，
git diff --check干净，回归面集中在示例本身。 - 示例漂移风险存在但被结构抑制：它调用的是 exact-head 的真实 worker-loop/frontier API，而不是硬编码字符串；行为一旦变化 smoke 会失败。
- CI 状态：
dependency-reviewSUCCESS，pytest在评审时仍 IN_PROGRESS；本地已独立运行全部 11 个场景并通过，等价于覆盖该示例的本地验证，但合入前仍建议等 CI pytest 变绿。 - 不新增抽象或调用方：示例复用的都是已有 Auto Research 生产路径，不存在“无活跃调用方的 scope fit”问题。
- public/private 边界：所有断言覆盖序列化载荷，禁止词列表也避免把本地路径写进源码。
我的整体评价
同意合并（APPROVE）。476 行的单文件端到端 walkthrough smoke 与该契约的复杂度匹配：它把 stop/takeover、state-aware wake、quota/operator 语义与 public boundary 一次讲清，并给出可回归断言。本地在 exact head 1c1ed4ee3a7a140e09de274673c507cdef54768d 运行全部 11 个场景通过；唯一待确认项是 CI pytest 完成状态，不影响评审结论，但合入前应确认其为绿色。
English Verdict
APPROVE — exact head 1c1ed4ee3a7a140e09de274673c507cdef54768d.
Key finding: the new walkthrough smoke exercises the real Auto Research worker-loop/frontier/takeover APIs across 11 stop/wake/public-boundary scenarios; all 11 passed in an independent local run at the exact head, and git diff --check is clean. No production code changes and no new abstractions; the only open item is the in-progress CI pytest check, which should be green before merge.
Validation: local run of examples/auto-research-stop-takeover-walkthrough-smoke.py (11/11 ok); dependency-review SUCCESS; pytest pending.
huangruiteng
left a comment
huangruiteng
left a comment
There was a problem hiding this comment.
详细中文评审（durable_smoke_value 门槛）
精确评审头： 3113@1c1ed4ee3a7a140e09de274673c507cdef54768d
动机
本 PR 是单文件 examples/auto-research-stop-takeover-walkthrough-smoke.py（+476 行），演示 Auto Research 的 stop/takeover 与 state-aware wake。按 durable_smoke_value 门槛，例程类 PR 必须证明对仓库/产品的真实、持久价值；本 PR 不满足。
改动思路
11 个 scenario 覆盖 stop marker、takeover、state-aware wake、public boundary 与完整生命周期。作为演示自洽，但该行为在 main 上已有专门 smoke 覆盖。
具体改动（关键内容讲解）
- existing_coverage_scan：main 已存在
examples/auto-research-stop-marker-smoke.py、examples/auto-research-state-aware-wake-smoke.py、examples/auto-research-visible-worker-hook-smoke.py、examples/auto-research-demo-e2e-worker-loop-smoke.py等一整个 auto-research smoke 家族（GH-C43 的验证命令正是这些）。本 walkthrough 与它们高度重叠，属重复演示而非差异化覆盖。 - same_author_batch_scan：#3113–#3120 是同一作者的 8 个同构 walkthrough PR 系列，加上 #3130/#3131/#3133 三件套，属明确批量刷 PR 信号。
- real_product_or_repo_value_verdict：若 stop/takeover 确有未覆盖断言，应在
tests/补 thin focused test；476 行 example 重复既有 smoke 家族，对仓库是噪音。
对主干的风险
代码本身无运行时风险。风险在模式：同一作者用 8+3 个同构 walkthrough 占满评审队列；此系列其余 PR（#3114–#3120）同理应被拦截或合并。
我的整体评价
REQUEST_CHANGES。 修复建议（择一）：(1) 收敛为 thin focused pytest；(2) 与 #3114–#3120 系列合并为一个有差异化价值的 walkthrough 并删除重复部分。贡献行为警告：按 PR #3134 政策，若同一作者在警告后再提交此类低价值同形状 PR，将禁止该账号继续向本仓库提交 PR（owner 执行屏蔽）。
English Verdict
REQUEST_CHANGES — exact head 1c1ed4ee3a7a140e09de274673c507cdef54768d.
Under the durable_smoke_value gate, this 476-line example-only walkthrough duplicates the shipped auto-research smoke family (auto-research-stop-marker-smoke.py, auto-research-state-aware-wake-smoke.py, etc.) and is part of the same author's 8-PR walkthrough series (#3113–#3120). Consolidate into thin focused tests or one differentiated walkthrough. Contribution warning: further low-value same-shape PRs after this warning will lead to the account being blocked from submitting PRs to this repository.
2 participants
…gh (GH-C43)
Public-safe walkthrough proving stop marker lifecycle, state-aware wake filter, quota pause vs operator stop distinction, operator takeover command contract, and full stop/inspect/resume lifecycle.
Exercises 11 scenarios across the shipped stop/takeover and state-aware wake transitions without adding a second launcher or altering the README.
Summary
Issue Or Task
Validation
python3 -m py_compile loopx/*.pyloopx check --scan-root .Type of Change
LoopX Area
Boundary Checklist
.loopx/,.codex/goals/, liveACTIVE_GOAL_STATE.md, credentials, private benchmark traces, verifier output, raw agent sessions, internal document links, or local machine paths.