Repository navigation
control_plane: add bounded --ttl-seconds on todo claim and clarify source.ref diagnostics - #9225
loopx-agent wants to merge 1 commit into
Conversation
…gnostics Signed-off-by: LoopX Agent <[email protected]>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google · self_reported
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
本次对 loopx-project/loopx#9225 的精确提交 e1f1d6607b2cb704c076e4a1e30d8f63955b62af(merge-base b4e1ded37d4ecf1d43b788cf9d870d3e1020d3ab)进行独立代码审阅与本地验证(依据 wait_for_ci: false 本地先行校验策略);本 PR 为 loopx-agent 自提交(author-owned PR),仅发布基于独立证据的 COMMENTED 审阅结论并保持 PR 处于开启状态。
动机 / Motivation
针对长耗时执行任务调用方与成果声明提交者,此前使用 loopx todo claim 领用并托管执行租约时只能固定获得 2700 秒默认租期,且返回载荷主动剥离内部 lease 对象而不输出任何租约过期时间或生效时长字段,调用方容易在超过 45 分钟唤醒后遭遇静默租约过期并被迫额外发起补救性续租,或因 goal-acceptance 的 source.ref 仅提示 source ref must be an opaque identifier 而反复试错。该 PR 通过为 loopx todo claim 开放 1..86400 秒的有界 --ttl-seconds 参数、在托管申领的 JSON 与 Markdown 输出中补充紧凑的 lease_expires_at 与 lease_ttl_seconds、同步丰富引导文案,并将 outcome_requirements.ts 的标识校验错误说明细化为包含允许字符集和禁用斜杠与空格提示的固定文本,实现参数直达规范租约并在错误返回后可一次修正重试。本 PR 明确不修改热路径 heartbeat_prompt_thin 提示词体积,也不引入新版本 claim 协议或放宽租约续期与请求身份冻结边界。
改动思路 / Approach
作者没有新增 v4 claim 协议或改动高频心跳提示载体,而是选择在既有的 v2/v3 托管申领与显式 lease_request 通道上透传可选 ttl_seconds,由 TypeScript 控制面 normalizeTtl 统一校验并写入请求身份哈希与租约记录,比新增 v4 claim 协议或改动高频心跳提示载体更贴合现有所有权边界且回归风险更低。同时缺省租期仍为 2700、合法范围限制为 1..86400,Python CLI 层仅补充 --ttl-seconds 参数注册与边界守卫,并在剥离内部 lease 字段前提取 lease_expires_at 与 lease_ttl_seconds。对于 outcome_requirements.ts 的 id() 错误提示,作者仅扩展固定静态提示字符串并同步文档示例,保持拒绝零写入且不回显调用方原始输入值。当前 PR 边界仅覆盖 CLI todo claim 可选租期、托管输出可见性与 id() 自修正错误文本;热路径心跳指令与非 claim 子命令保持隔离,可独立审阅与回退。
flowchart LR
CLI["todo claim [--ttl-seconds N]"] --> Val{"1..86400 且属托管或显式 lease?"}
Val -- 否 --> FailPy["ValueError 零写入拒绝"]
Val -- 是 --> AuthPy["claim_canonical_todo_if_promoted"]
AuthPy -- 托管路径 --> TopTtl["payload.ttl_seconds -> executeClaimAttempt(v2/v3)"]
AuthPy -- 显式 lease --> LeaseReq["lease_request.ttl_seconds -> normalizeLeaseRequest"]
TopTtl --> Hash["计入 requestIdentity SHA256 (重放不同 TTL 返回 mismatch)"]
Hash --> Exec["prepareClaimExecution (仅新建/reclaim生效)"]
Exec --> Out["todo.py 提取 lease_expires_at / lease_ttl_seconds 后剥离内部 lease"]
说明:以上流程图依据精确提交 e1f1d6607b2cb704c076e4a1e30d8f63955b62af 源码绘制,用于说明控制流而非替代测试执行证据。
具体改动 / Changes
全部 16 个变更文件共 +281 / -15 行,集中在产品运行时代码(10 个文件,+99 / -11)、参考文档(1 个文件,+4 / -2)与测试覆盖(5 个文件,+178 / -2)。依据规范 docs/reference/goal-acceptance-observations.md(审阅基线 b4e1ded37d4ecf1d43b788cf9d870d3e1020d3ab),既有 error_detail 约束 GAO-ERR-DETAIL 已完整落实:即知名校验规则输出固定规则文本、不回显被拒值且拒绝不写入权威状态(本 PR 同步更新了该文档中的示例文本以反映新规则提示;--ttl-seconds 属于基于现有 v2/v3 租约契约的 CLI 易用性增量,无独立先行 RFC 编号)。
关键代码讲解
handle_todo_command(loopx/cli_commands/todo.py:521-588)
在向update_goal_todo透传ttl_seconds=args.ttl_seconds后,针对非--dry-run且execution_managed=True的申领结果,先从规范权限返回对象payload["lease"]中严格校验并提取expires_at(非空字符串)与acquire_ttl_seconds(非布尔整数)为lease_expires_at与lease_ttl_seconds,随后再按原设计弹出内部lease、lease_changed、lease_idempotent与original_receipt,并更新instruction说明(提醒可通过--ttl-seconds设定1..86400秒租期或到期前执行loopx task-lease renew,以及完成 Todo 时的refresh-state不带--next-action)。在--thin模式(_thin_claim_projection)下这两个标量同样保留,且实测cli-output-budget-regression-smoke.py与差量回归全数通过。validate_todo_claim_options与claim_canonical_todo_if_promoted
CLI 层通过TODO_OPTION_FIELDS、TODO_ACTION_FIELDS["claim"]与validate_shared_todo_options限定--ttl-seconds仅可用于todo claim,拦截非1..86400范围、布尔误传或未启用托管且未传--task-lease-idempotency-key的调用;Python/TS 桥接层local_authority.py复验同一前置条件后,将无显式 lease key 的ttl_seconds作为顶层字段发送,而显式--task-lease-idempotency-key调用则将其填入lease_request.ttl_seconds。executeClaimAttempt与prepareClaimExecution
TS 运行时claimLocalCoordinationTodo拒绝在< v2请求体传入顶层ttl_seconds;executeClaimAttempt使用现有normalizeTtl校验并强制顶层ttl_seconds仅在manage_execution=true且无lease_request时生效,最关键的是将ttl_seconds纳入requestIdentity的 SHA-256 摘要计算,确保复用同一--claim-operation-id但篡改 TTL 的重放会在提交前被判定为coordination_operation_identity_mismatch。prepareClaimExecution仅在无现存活跃租约(首次获取或过期回收)时采用normalizeTtl(input.ttl_seconds),活跃同属主续领仍沿用原租约状态与原始acquire_ttl_seconds。id与_render_execution_managed_claim_lines
id()保持既有正则/^[A-Za-z0-9][A-Za-z0-9_.:@-]*$/不变,仅把错误信息扩展为`${label} must be an opaque identifier (ASCII letters/digits and . _ : @ -, no '/' paths or spaces)`,与docs/reference/goal-acceptance-observations.md同步并经 SQLite/File 端到端验证零泄露与原子拒绝。Markdown 渲染器仅在非错误托管结果输出紧凑的- lease_expires_at与- lease_ttl_seconds行,未影响失败或旧格式展示。
对主干的风险 / Risks
经代码审查、对照基线 b4e1ded37d4ecf1d43b788cf9d870d3e1020d3ab 的真实 CLI 双后端反事实执行,以及 12 个 TS 测试文件、9 个 Python 测试套件和完整 premerge canary 门禁验证,未发现阻塞合并的正确性、协议语义、数据一致性或安全边界缺陷(no blocking finding)。
从主干长期演进视角仍可记录三项无需阻塞当前 PR 的轻量观察:
- 错误结构一致性(
todo_argument_validation.py:449-458):当todo claim传入越界--ttl-seconds或缺少对应--agent-id时,校验函数抛出普通ValueError(仅返回error,不含error_code: "todo_claim_invalid_arguments"与结构化recovery),与同文件第 426–446 行的TodoClaimArgumentError略有差异。但鉴于TodoClaimArgumentError.recovery()会原样保留_TODO_CLAIM_FIELDS中的全部参数,对越界--ttl-seconds抛出ValueError反而避免了生成继续携带非法值的重试命令;后续仅需按需细化“缺失--agent-id时是否提供结构化引导”。 - 错误提示精确度(
outcome_requirements.ts:44-46):正则要求首字符必须为[A-Za-z0-9],新文案只说明了合法字符集及禁用/与空格,未额外指出首字符不能为. _ : @ -;对常见路径或空格误填已能明确自纠。 - 指引文案跨命令耦合(
todo.py:561-569):todo claim的instruction内嵌入了已完成 Todo 结算阶段refresh-state省略--next-action的提醒,语义与project_lifecycle_refresh_state.py一致且不超 CLI 输出预算,只是职责上略跨出 claim 本身;且若通过外部命令执行loopx task-lease renew,调用方需先配合task-lease inspect获取托管生成 lease 的内部idempotency_key与version(当然常规工作流由同源todo update --claim-operation-id在最后三分之一周期自动续期)。
当前真实隔离工作区针对精确提交 e1f1d6607b2cb704c076e4a1e30d8f63955b62af 的验证清单如下:
- TypeScript 权威与控制面套件:
PASS(12 个文件共555项测试:550 pass, 0 fail, 5 skipped;全部 5 项跳过均为需独立 PostgreSQL URL 的goal_outcome_capacity.test.ts与leased_continuation.test.ts用例,File 与 SQLite 全量通过,含managed_claim_execution_conformance.ts)。 - Python pytest 套件:
PASS(9 个关联及预算回归文件共557 passed, 2 skipped, 0 failed;2 项跳过为非本机环境适用的 PowerShell 7 差量检查与深度 12 Windows 临时路径检查)。 - Pre-merge Canary Gate:
PASS(以项目.venv执行canary premerge --from-git-diff --git-diff-base b4e1ded37d4ecf1d43b788cf9d870d3e1020d3ab:direct_checks 4/4、py_compile 1/1、catalog_canaries 10/10含cli-output-budget-regression-smoke.py与semantic-vocabulary-drift-smoke.py、risk_profile_smokes 8/8、public_boundary 1/1across 16 files,0 failures;control-plane-maintainability-ratchet-smoke.py返回ok: true,unreviewed: 0)。注:脱离.venv直接调用全局入口运行 canary 会因宿主缺pytest包而在预算脚本处报错,非本 PR 代码缺陷。 - 静态检查与双端真实 CLI 反事实对比:
PASS(ruff与核心 4 个类型声明模块的mypy --follow-imports=silent零报错;基线与 HEAD 对比确认默认2700s向后兼容、--ttl-seconds 600写入及跨操作 ID 修改 TTL 触发coordination_operation_identity_mismatch、--dry-run零持久化、todo update --ttl-seconds拒绝,以及goal-acceptance refine非法source.ref原样拒绝且不回显输入值)。 - GitHub 远端 CI:
UNVERIFIED(11 pending, 2 success,Goal 策略设为wait_for_ci: false,不阻塞技术结论)。
我的整体评价 / Verdict
综合评估精确提交 e1f1d6607b2cb704c076e4a1e30d8f63955b62af:在 long_horizon 维度表现为 improved(长时执行任务可在 todo claim 入口一次性声明合法租期并获知精确到期时间,同时重放请求仍被摘要锁死,不会引入暗中延长租约风险);在 user_experience 维度表现为 improved(错误输入如带 / 或空格的 source.ref、越界 TTL、非托管使用均有清晰的零写入自修正反馈,CLI 视觉展示方面属于不涉及前端 UI 渲染层的 not_applicable,已核验 markdown.py 紧凑输出符合结构预期)。代码体量 necessary,复用既有 v2/v3 租约状态机与 normalizeTtl 规则而非叠加新协议,默认缺省输入保持 2700s 行为兼容,无域绑定文本或架构越权问题。
残余风险仅限上述本地未启用的独立 PostgreSQL 集成测试(5 项跳过)及跨平台 Windows/PowerShell 检查(2 项跳过),均不构成回归证据缺口。结合全量 TS/Python/Canary 与端到端对照实测,建议合入,本次按 author-owned PR 规则发布 COMMENTED 审批结论并保持 PR 开启。
English verdict: APPROVE
Summary
Implements a focused, zero-conflict Wave-3 control-plane ergonomics slice:
Bounded
--ttl-seconds(1..86400) onloopx todo claim+ compact lease visibility:2700s(45m) and schema invariants when--ttl-secondsis omitted.--ttl-seconds(int) inloopx/cli_commands/todo_registration.pyand enforces1..86400(bool-safe), claim-only scoping, and managed-or-explicit-lease gating inloopx/cli_commands/todo_argument_validation.py(including the exactTodoClaimArgumentErrorallowlist).ttl_secondsthroughloopx/control_plane/todos/mutation_api.py(update_goal_todo) andloopx/control_plane/coordination/local_authority.py(claim_canonical_todo_if_promoted) to TS authority (claimLocalCoordinationTodo,executeCoordinationTodoClaim,prepareClaimExecution).1..86400, rejectsttl_secondson claim requestv0/v1or unmanaged claims, bindsttl_secondsinto request identity (coordination_operation_identity_mismatchon mismatched replay), and honors the custom lease duration in renewal scheduling.lease_expires_atandlease_ttl_secondsonexecution_managednon-dry-run claim outputs (loopx/cli_commands/todo.py), renders them cleanly via_render_execution_managed_claim_linesinloopx/control_plane/todos/markdown.py, and expands claiminstructionto note--ttl-seconds,loopx task-lease renewbeforelease_expires_at, and omitting--next-actionon completed-Todosemantic_closeoutrefresh-state.Self-correcting
source.refopaque-identifier diagnostic:id(...)inloopx/control_plane/goals/outcome_requirements.tsto explain permitted identifier syntax:`${label} must be an opaque identifier (ASCII letters/digits and . _ : @ -, no '/' paths or spaces)`, alongsidedocs/reference/goal-acceptance-observations.mdandtests/control_plane/test_goal_outcome_diagnostics.py.Prompt-budget preservation (
task_body.pyintentionally untouched):heartbeat_prompt_thinenforces tight byte and differential growth limits (+32Markdown chars /+64JSON chars vsorigin/main), so actionable recovery guidance lives at the CLI diagnostic andtodo claimsurfaces rather than expanding hot-path prompt bodies.Verification
All checks ran at the exact pushed diff against
origin/main(e1f1d6607b2cb704c076e4a1e30d8f63955b62af):git diff --check origin/main&ruff check(changed Python files):All checks passed!mypy --follow-imports=silent(todo_argument_validation.py,mutation_api.py,markdown.py,local_authority.py):Success: no issues found in 4 source filespython3 examples/control_plane/control-plane-maintainability-ratchet-smoke.py --format=json:ok(unreviewed: 0,stale_exceptions: 0,magnitude_regressions: 0)node --no-warnings --experimental-strip-types --test(8 TS suites:file_authority_store.test.ts,sqlite_authority_store.test.ts,local_authority_runtime.test.ts,authority_source.test.ts,goal_outcome_refinement.test.ts,goal_outcome_capacity.test.ts,goal_outcome_review_work_basis.test.ts,refresh_recommendation.test.ts):tests 529, pass 526, fail 0, cancelled 0, skipped 3(the 3 skipped cases are the optionalpostgresqlcapacity tests ingoal_outcome_capacity.test.ts).pytest -n 4(9 focused + regression suites:test_goal_outcome_diagnostics.py,test_todo_claim_argument_recovery.py,test_canonical_claim_execution_proof.py,test_cli_argument_diagnostics.py,test_local_coordination_authority.py,test_todo_list_thin.py,test_todo_mutation_authority.py,test_cli_output_differential.py,test_cli_output_budget.py):557 passed, 2 skipped(0failures).loopx canary premerge --from-git-diff --git-diff-base origin/main:gate.status: "passed",merge_gate_passed: true,direct_failure_count: 0,run_failure_count: 0,manual_hold_count: 0(4/4 direct checks,py_compile, 10/10 catalog canaries includingcli-output-budget-regression-smoke.pyandsemantic-vocabulary-drift-smoke.py, 8/8 risk-profile smokes, and 1/1loopx checkpublic/private boundary scan across all 16 files).