Make CLI action help and lease argument recovery actionable

[loopx-agent]

Todo and task-lease action help currently exposes options from unrelated actions, and lease argument failures require callers to discover missing inputs one at a time. This change scopes help to five lease actions and six existing strict Todo grammars, and returns reviewable lease repair arguments with all missing/unsupported flags together.

The CLI transport owns argument shape and presentation; existing TypeScript lease owners still decide identity, CAS, claim, capability and mutation admission. The shared action field maps remove duplicated CLI grammar knowledge. No new capability, provider, setting or shared state vocabulary is introduced. Existing frontend/Lark authority paths are unaffected; this is the existing CLI's help/error journey.

Behavior change: irrelevant lease flags that were previously ignored now fail before runtime resolution, including explicit zero on inspect. Repairs preserve permitted routing, identities, keys, scopes and versions; they neither execute nor grant work. Parent and complex Todo lifecycle help keep their full option lists. Conditional requirements remain enforced at execution.

Validation:

• 41 focused help/recovery/claim tests passed; the expanded real lease recovery suite subsequently passed 13 tests (three additional transfer cases; overlapping earlier coverage).
• 149 existing CLI diagnostics, lease and worktree tests passed.
• Real Legacy/File/SQLite CLI checks cover no-write refusal, exact retry, stale CAS, wrong owner, atomic claim transfer and unavailable legacy transfer. Help works with a missing registry and preserves reused-parser behavior.
• Scoped Ruff, diff hygiene and semantic advisory passed. Premerge passed all 19 selected checks, including full semantic validation and CLI output budgets. The first attempt failed because npm development dependencies were absent; installing locked dependencies resolved it.
• Selected action-help output versus parent help: Todo list 2,945 versus 26,049 bytes; lease inspect 635 versus 2,414 bytes. These are CLI output measurements, not task-level effectiveness claims.

The bounded refactor centralizes only the active CLI grammar/presentation seam. No authority-store refactor or PostgreSQL change is included. Core behavior remains for maintainer merge after exact-head review.

[loopx-agent]

Reviewer: model_agent; gpt-6.1-sol; OpenAI; runtime_reported; reasoning_effort=xhigh

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

Reviewed exact head 005ff70d9172b96656ec6fb4e0e93f39c6f396e7 against base 55254bdceb89f8c1fff0aeefd110102afb911ccb. No CI was fetched, polled or awaited.

动机

经 CLI 获取、续租或转交任务执行权的用户和 Agent。旧版本把其他动作的选项也放进帮助，缺失参数往往要逐次报错、逐次补填；本次帮助只显示当前动作，普通租约错误一次列出缺失与无关参数。但合法的 -execution 执行 key 被恢复参数拆成两个 token，直接重试会再次失败。

11 个动作帮助逐项对照原合法参数均无遗漏，普通恢复、转交 claim 与 CAS 拒绝有效；带前导连字符的合法执行 key 尚不能可靠恢复。范围是现有 CLI 的帮助和参数恢复，不新增 capability、provider、前端设置或权限，不宣称完整产品路线、安装采用或长期完成率已经验收。

改动思路

CLI grammar 与呈现属于现有 Python transport，执行资格和状态转移继续复用 TS owner；不需要为动作帮助再增加状态、配置或第二套租约权威。保留共享动作字段和现有权威边界，在本 PR 修正参数 token 编码并补真实 CLI 回归；无需扩张到调度器、存储迁移或新增 UI。

不改租约资格、领取归属和并发版本规则，是合理的归属边界。动作字段表同时驱动帮助与已有语法检查，避免两份选项列表漂移；没有必要为了格式化改写 TS 权威或新增配置。相比完全改成子命令解析器，这个范围更容易验证和回退。最强的反对理由不是代码量，而是提示“可重试”的参数实际上不能完成一次真实恢复，必须先修这个当前边界。

具体改动

规范依据是修改前 docs/reference/canonical-lease-renew.md，固定 revision 55254bdceb89f8c1fff0aeefd110102afb911ccb。文档没有编号，下列使用原节标题作定位：

• Operate the current lease：owner、执行 key 和读回版本必须保持；普通 key 与显式 claim 转交通过，合法前导连字符 key 的恢复不满足这个要求。
• What inspection proves：只读检查不授予执行权限；恢复提议也不自动执行，错误 owner、过期版本的新意图及 Legacy 不支持的 claim 转交仍拒绝。
• Repository-relative scope identity：续租与转交保留已有 scope；真实转交读回保留 src/**，原 provider 决策不变。

关键代码讲解

1. action_help.py:17 的 ActionHelp.__call__ 仅筛选帮助 formatter 的动作列表，不更改 parser；未映射的复杂 Todo 动作继续完整帮助。独立逐项对照五个 lease、六个 Todo 动作：固定 base 为 0/11 动作专属集合，head 为 11/11，所有合法选项均展示；缺失 registry 也能读取。
2. task_lease_arguments.py:67 的 validate_task_lease_arguments 一次收集缺失与无关参数，用显式存在判断保留零版本。原先静默忽略的额外参数现在拒绝，PR 与中英 reference 明确披露；这不是默认关闭的可选能力。
3. task_lease_arguments.py:43–57 的 TaskLeaseArgumentError.recovery 保留 registry/runtime 路由、Boolean claim 意图与数字 CAS，但第 57 行始终分拆字符串 option/value；这导致下面的真实恢复缺陷。
4. task_lease.py:141 的 handle_task_lease_command 在读取 runtime 前验证语法，只有这种错误生成 recovery；通过语法后仍进入既有 native/TS owner，权威拒绝不会被当成缺失参数“修好”。

对主干的风险

[P1] 恢复 argv 必须能表示现有合法执行 key

已有 TS/Python 公共安全 key 规则允许前导 -。在 Legacy、File、SQLite 三个隔离真实后端中，先用 --idempotency-key=-execution 正常取得租约，再用该 key 和当前版本续租，故意带无关 --write-scope other/**。错误回执正确要求移除 scope，却返回 --idempotency-key, -execution 两个 token。直接调用 recovery.cli_args 的结果均为 exit 2: argument --idempotency-key: expected one argument，尚未到达租约权威。

独立 inspect 证明失败未改变 lease；只把相同值编码为 --idempotency-key=-execution，续租便成功，版本从 2 到 3，精确重试返回同一结果且不重复续租。因此不能靠缩窄原 key 规则、改 owner 或刷新 CAS 掩盖。最小修复是对保留的字符串选项使用 --flag=value 或同等无歧义编码，重复字符串选项也处理；补 source/destination key 的真实 CLI 恢复、读回、精确重放用例。

本次独立执行 127 个帮助/恢复/诊断测试和 76 个租约/claim/worktree 回归全部通过；额外的真实 key 反例三项失败，保留红项。初版 reviewer probe 错把 release 当作递增版本；改为读取权威版本后才得到这里的有效反例，原失败保留且不当产品证据。Ruff、diff hygiene 和 semantic advisory 通过；首次 full semantic 因缺少锁定 npm 依赖失败，准备依赖后的同一检查通过。原生风险 canary 的直接检查与全部选中检查通过；它未覆盖这个合法 key 反例，不能替代该红项。没有运行付费模型、修改活动 Goal 进行测试或推断长期净收益。

语义与 CI 对齐

动作名称和 task_lease_v0 复用现有词汇，新增 lists 是 CLI 局部语法和派生诊断，没有新的持久状态分类，也没有第二个 Python 权威。已披露的无关参数拒绝是有意默认行为变更；本 finding 是未声明的合法输入重编码缺口。CI 按当前能力配置不查询；本地实际失败独立于远端检查，并足以阻止本 head 的批准。

我的整体评价

REQUEST_CHANGES。动作帮助和普通恢复有实际正向价值：减少需要阅读的无关选项，并让一次报错展示待修项；结构与代码规模相称。长程效果和整个用户恢复体验目前 not_yet_proven：支持的执行 key 仍会在推荐重试中卡住，恢复提示的可执行性不能以字段文本存在或 happy-path 测试通过替代。

CLI grammar 与呈现属于现有 Python transport，执行资格和状态转移继续复用 TS owner；不需要为动作帮助再增加状态、配置或第二套租约权威。保留共享动作字段和现有权威边界，在本 PR 修正参数 token 编码并补真实 CLI 回归；无需扩张到调度器、存储迁移或新增 UI。

不要求扩成新框架、调度改造或存储迁移。修复并在新精确 head 重跑真实参数往返后可重新判断；本评审不授予 merge、升级或其他 Agent 消息权限。

English verdict: REQUEST_CHANGES
The action-help design is appropriately scoped, but generated repair argv cannot round-trip supported leading-hyphen execution keys. Fix lossless option-value encoding and validate the real recovery/replay path before approval.