Skip to content

control_plane: add bounded --ttl-seconds on todo claim and clarify source.ref diagnostics - #9225

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/todo-claim-ttl-ergonomics-20261122
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/todo-claim-ttl-ergonomics-20261122

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Implements a focused, zero-conflict Wave-3 control-plane ergonomics slice:

  1. Bounded --ttl-seconds (1..86400) on loopx todo claim + compact lease visibility:

    • Preserves default 2700s (45m) and schema invariants when --ttl-seconds is omitted.
    • Registers --ttl-seconds (int) in loopx/cli_commands/todo_registration.py and enforces 1..86400 (bool-safe), claim-only scoping, and managed-or-explicit-lease gating in loopx/cli_commands/todo_argument_validation.py (including the exact TodoClaimArgumentError allowlist).
    • Forwards ttl_seconds through loopx/control_plane/todos/mutation_api.py (update_goal_todo) and loopx/control_plane/coordination/local_authority.py (claim_canonical_todo_if_promoted) to TS authority (claimLocalCoordinationTodo, executeCoordinationTodoClaim, prepareClaimExecution).
    • Validates 1..86400, rejects ttl_seconds on claim request v0/v1 or unmanaged claims, binds ttl_seconds into request identity (coordination_operation_identity_mismatch on mismatched replay), and honors the custom lease duration in renewal scheduling.
    • Surfaces compact lease_expires_at and lease_ttl_seconds on execution_managed non-dry-run claim outputs (loopx/cli_commands/todo.py), renders them cleanly via _render_execution_managed_claim_lines in loopx/control_plane/todos/markdown.py, and expands claim instruction to note --ttl-seconds, loopx task-lease renew before lease_expires_at, and omitting --next-action on completed-Todo semantic_closeout refresh-state.
  2. Self-correcting source.ref opaque-identifier diagnostic:

    • Updates id(...) in loopx/control_plane/goals/outcome_requirements.ts to explain permitted identifier syntax: `${label} must be an opaque identifier (ASCII letters/digits and . _ : @ -, no '/' paths or spaces)`, alongside docs/reference/goal-acceptance-observations.md and tests/control_plane/test_goal_outcome_diagnostics.py.
  3. Prompt-budget preservation (task_body.py intentionally untouched):

    • heartbeat_prompt_thin enforces tight byte and differential growth limits (+32 Markdown chars / +64 JSON chars vs origin/main), so actionable recovery guidance lives at the CLI diagnostic and todo claim surfaces 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 files
  • python3 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 optional postgresql capacity tests in goal_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 (0 failures).
  • 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 including cli-output-budget-regression-smoke.py and semantic-vocabulary-drift-smoke.py, 8/8 risk-profile smokes, and 1/1 loopx check public/private boundary scan across all 16 files).

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"]
Loading

说明:以上流程图依据精确提交 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 编号)。

关键代码讲解

  1. 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 与差量回归全数通过。
  2. 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。
  3. 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。
  4. 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 的轻量观察:

  1. 错误结构一致性(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 时是否提供结构化引导”。
  2. 错误提示精确度(outcome_requirements.ts:44-46):正则要求首字符必须为 [A-Za-z0-9],新文案只说明了合法字符集及禁用 / 与空格,未额外指出首字符不能为 . _ : @ -;对常见路径或空格误填已能明确自纠。
  3. 指引文案跨命令耦合(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/1 across 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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant