Skip to content

Bind current managed claims to their worktree - #9091

Open
loopx-agent wants to merge 3 commits into
mainfrom
codex/verify-active-claim-worktree-20261119
Open

loopx-agent wants to merge 3 commits into
mainfrom
codex/verify-active-claim-worktree-20261119

Conversation

@loopx-agent

@loopx-agent loopx-agent commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

The canonical lease stores a physical Git worktree identity. Checking actor ownership and a retained claim receipt alone can admit the same actor in a sibling worktree. Worktree discovery can also inherit Git settings from a parent checkout, as it does when invoked inside a Git hook. This can bind a fresh lease to the wrong checkout, reject later execution in the real checkout, or record a delivery snapshot with the parent repository's origin and revision.

Changes

  • Managed claim replay, execution readiness, and claim-based updates and completion verify the checkout bound to the active lease. Subdirectories and physical aliases of the same checkout continue to work. Historical receipts stay readable. To move active execution, release the lease and claim from the destination with a new operation ID.
  • The TypeScript worktree observer checks initial scope and current identity. Checks against an active lease avoid a scope directory scan. Python worktree, origin and delivery facts use the checkout named by the caller. Both paths ignore the parent Git command's repository selectors and temporary config.

Validation

  • The caller-worktree regressions fail before the fix. On 4a636c57005c, 156 File and SQLite CLI cases and 70 Python workspace and lifecycle cases pass, including the inherited Git environment, sibling refusal and delivery snapshot cases. The isolated installed wheel passes all 4 caller-worktree variants.
  • 884 TypeScript tests and the control-plane type check pass. The local suite skips one live PostgreSQL test.
  • Standard premerge passes all 6 direct checks and 18 of 19 selected checks. The peer-runtime canary fails on the same release-guide line on both revisions because the hierarchy scan matches the documented benchmark controller. Release guide on the tested base
  • The strict quality gate reports the same required mypy and Ruff diagnostics on main b927e20bfbe6 and the candidate. Adding Restore Python static checks on main #9082 at be17fad48c4d to this head passes both checks. The hosted kernel-static job stops at the same Ruff finding. Static-check repair #9082 Hosted static check
  • The strict documentation build fails on the existing Turn Envelope runtime-guide link. Adding Fix the Turn Envelope benchmark guide link in MkDocs #9032 at 1254f7598cf9 to this exact head passes the strict site build and both Developer Book editions. The rendered link points to the published runtime guide. Documentation fix #9032 Hosted site check

Hosted PostgreSQL 16.15 passed on the PR's trial merge with main at b927e20bfbe6. It passed 398 authority conformance cases with zero skips, 11 service cases, and 53 authenticated remote-command cases. PostgreSQL integration

Release preparation stops at the existing C1 runtime-default qualification requirement. Current release check · Earlier main snapshot with the same C1 failure

Independent review for this head and the remaining merge checks are pending.

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>

@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 · gpt-6.2-sol · OpenAI (runtime_reported, max)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

动机 / Motivation

使用多个独立 Git worktree 的 Agent,需要让 managed claim 的实际工作区与租约记录对齐。此前已保存物理 checkout 指纹。新头在执行准备和领取、回写时观察来源,按当前租约判断能否继续。同一 checkout 的别名与子目录继续有效,重放和历史读回各有明确路径。验证范围是本地实际 provider 和 CLI。正式安装及部署采用由单独入口验收。

改动思路 / Approach

原 TypeScript observer 继续持有物理 worktree 判断。新授权时校验路径范围,已有授权只比较身份。Python guard 传入工作区给同一 typed owner。普通 Todo 和没绑定 worktree 的租约继续走原路径。读取历史经原 provider;换 checkout 通过带版本释放以及新 operation 完成。 这保留了历史回执的独立读回,也让当前工作区更换通过已有的 release 和新 claim 留下新一代租约。

具体改动 / Changes

精确 head 1fd35e98d617ce71b2311bf44cc83f98cbc5c3fd,diff base 9e066cd3ddd4ae3e76188573933bbafe08f5b0f7,15 个文件 +210/-42。逐项复核 physical-binding、lossless-rebind、preserve-ordinary。验收约定

关键代码讲解

  • 选中 Todo 后由原 typed owner 读取 canonical lease 和当前 checkout。身份不符会返回明确的 lease_workspace_divergence,同一物理目录的别名与子目录继续有效。源码
  • 当前领取、续租、引用领取的进度或完成都复用观测。验证拒绝分支的 provider 状态和 operation receipt 未发生变化。源码
  • File 与 SQLite 实测按原版本释放和新 operation 获取另一 checkout,确认新工作树标识和 epoch,同时能读回原历史 receipt。源码

对主干的风险 / Risks

关键是拒绝发生在继续执行和写入之前,并能按原工作区恢复。File/SQLite 的实际调用检验了拒绝及原租约、回执未变。独立补验覆盖明确释放后换 checkout、新 epoch、原历史读回和新的 ready。

语义与 CI 对齐

独立复验在 File/SQLite 比较基线 97 与 head 99 个 CLI 用例,补验两项换 checkout,另有 36 项共享 conformance 通过。隔离的实际 PostgreSQL 16.15 跑完 398 项,零跳过。改动范围的 Ruff、TypeScript 检查和 diff 通过。相同的全库 mypy/Ruff 既有诊断仍可复现。

我的整体评价 / Verdict

通过这个精确提交的代码评审。现有租约、工作区身份与回执均由原 owner 负责,拒绝、重放及显式换 checkout 的路径已有实际复验。正式安装与采用仍需对应证据。

English verdict: APPROVE. Current managed execution uses the original physical worktree, exact historical receipts remain readable, and authorized rebind passes. File, SQLite and PostgreSQL evidence supports this exact head.

@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)

动机 / Motivation

在同一台机器上使用多个独立 Git worktree 并行开发、且通过受管 todo claim 与 quota should-run 推进任务的 Agent 与操作员(包括在 Git hook 继承环境变量下调用 LoopX 的场景)。改动前受管认领虽在租约中保存了物理 worktree 指纹,但执行准备、认领重放、同一代理后续认领以及携带 claim-operation-id 的进度更新/完成未核对调用方当前所在 checkout,同一 Agent 切到兄弟 worktree 后仍能放行或写回,且父 Git 命令注入的 GIT_DIR/GIT_WORK_TREE/GIT_CONFIG_* 环境变量会误导工作区与 origin 探测;改动后上述受管路径统一要求校验当前物理 worktree 匹配(允许原 checkout 的软链接别名与子目录,历史 todo receipt 仍可跨目录只读查询,显式释放后换目录并用新 operation ID 重新认领),不一致或不可验证目录一律返回 lease_workspace_divergence。

受管执行准备、认领(含重放/恢复与活动租约复核)及带 claim-operation-id 的 update/complete 在原 worktree(含子目录与符号链接别名)正常放行,在兄弟 worktree 或非 worktree 目录返回 lease_workspace_divergence 且不改写租约或回执;Git 工作区/origin 探测忽略父进程继承的 GIT_* 仓库与配置覆盖变量。本 PR 不修改普通非 worktree 租约(write_workspace 为空)与 soft_claim 的行为,不赋予兄弟 worktree 自动接管活动租约的能力,也不改动远程权限、合并权限或 Todo 排他规则。

改动思路 / Approach

整体将“当前 checkout 是否匹配活动租约”的判定收口到既有 TypeScript worktree 身份边界(task_lease_workspace.ts 与 claim_execution.ts),并补齐 Python 到 TypeScript 的工作区路径透传与 Git 环境隔离:

  1. 按需轻量化观测:observeLeaseWorktree(path, overlaps?) 将 overlaps 设为可选——新授权认领或 task-lease acquire 传入 overlaps 时仍严格校验处于 worktree 根目录并扫描写入范围防重定向;而执行准备(readExecutionPreparationSource)、认领重放/恢复及 todo update/complete 校验活动租约时传入 undefined,既放行原 worktree 的子目录与别名,又避免无谓扫描目录。
  2. 统一失配守卫:matchesObservedLeaseWorkspace 对未绑定 worktree 的租约(retained == null)直接返回 true 以保留普通路径;对已绑定租约则在缺失观测者、探测失败或物理指纹不等时返回 false,并由各调用方映射为标准 lease_workspace_divergence 拒绝。
  3. 跨层 Git 环境隔离:repository_identity.py 的 workspace_git_environment() 与 task_lease_workspace.ts 的 WORKSPACE_GIT_OVERRIDES 统一剥离 GIT_DIR、GIT_WORK_TREE、GIT_COMMON_DIR、GIT_INDEX_FILE、GIT_IMPLICIT_WORK_TREE、GIT_CONFIG、GIT_CONFIG_COUNT、GIT_CONFIG_PARAMETERS,并让 doctor_git.py 直接复用该 helper 消除重复,同时在 workspace_guard.py 增加 _is_same_or_child_path(path, root) 保护。

复用既有 TypeScript worktree 身份模型与 Python workspace_git_environment helper:由 read_transaction 与 claim_execution 在不变更租约持久化 schema 的前提下按需只读观测物理 checkout(身份核对跳过写入范围目录扫描),普通与历史无绑定租约在 retained == null 时自然保底放行,决策权仍集中在原 TypeScript owner。覆盖活动 worktree 受管认领的准入准备、认领、claim 引用更新/完成校验与父 Git 环境变量隔离及双语参考文档更新;保留已释放闭环重放(retainedCloseout)与 todo receipt 跨目录历史读回。

具体改动 / Changes

本次 exact head 4a636c57005c8edd655b0b04a5c144ff401670ba(含在早先 1fd35e98 评审之后追加的 242b9bda 与 4a636c57 提交)相对基线 b927e20bfbe60817570bceb8654e2bfbc96abadf 共修改 20 个文件(+295 / -54):TypeScript 控制面 9 文件、Python 运行时/护栏 7 文件、公开文档 1 文件、测试 4 文件(合计 20 文件,其中 docs 1、TS/Py 运行时 15、测试 4)。

依据租约与独立 worktree 契约 docs/reference/canonical-lease-renew.md(固定修订 b927e20bfbe60817570bceb8654e2bfbc96abadf)逐项核对验收标准:

  • REQ-WORKTREE-BIND-1(physical-binding:受管执行准备、认领及引用的 update/complete 须校验当前 checkout 与活动 worktree 租约一致,子目录/别名放行,分歧返回 lease_workspace_divergence 且不改写权威状态)-> implemented:matchesObservedLeaseWorkspace、claimExecutionProof、projectExecutionPreparation 及 test_quota_execution_preparation.py / managed_claim_execution_conformance.ts / CLI todo complete 端到端反事实验证。
  • REQ-WORKTREE-BIND-2(lossless-rebind:历史 todo receipt 跨目录可读,释放旧租约后可在新 worktree 用新 operation_id 重新认领,已释放闭环重放不被阻塞)-> implemented:claimExecutionProof(active 分支限定)与 test_quota_execution_preparation.py#L654-L660。
  • REQ-WORKTREE-BIND-3(preserve-ordinary:普通无绑定租约与 soft_claim 保留既有行为;worktree/origin 探测忽略父 Git 命令注入的仓库与配置环境变量)-> implemented:observeLeaseWorktree、workspace_git_environment 与 test_workspace_git_fact_reads.py#L69-L84 / task_lease_workspace.test.ts#L51-L71。

关键代码讲解

  • observeLeaseWorktree 与 matchesObservedLeaseWorkspace:在 TS 观测边界过滤 WORKSPACE_GIT_OVERRIDES;overlaps === undefined 时放行子目录且免扫作用域,仅校验属于独立 Git worktree 与物理/仓库指纹匹配;retained == null 保留普通租约路径。
  • readExecutionPreparationSource 与 projectExecutionPreparation:通过 execution_preparation.py 传入调用方 workspace_path,仅对 status === "active" 且带有 write_workspace 的租约计算 workspace_matches,失配时在 should-run 阶段即阻断并给出 lease_workspace_divergence。
  • claimExecutionProof、prepareClaimExecution 与 executeClaimAttempt:分别在受管 todo update/complete、活动租约下的重复认领、以及 replayed/recovered 回执重放三条入口校验工作区一致性,并将 ClaimWorkspaceMismatch 转为 lease_workspace_divergence 决策拒绝,同时对 retainedCloseout(已释放闭环)放行。
  • workspace_git_environment 与 _git_worktree_root:为 Python Git 探测提供统一净化环境(doctor_git.py 同步移除冗余 _source_git_environment),并验证 rev-parse --show-toplevel 解析结果确为传入路径自身或祖先目录。

对主干的风险 / Risks

经独立逐行审查、多后端自动化套件与真实 CLI 端到端反事实验证,本精确提交无阻塞性问题(no blocking finding)。scope_fit 活跃调用链覆盖 quota should-run(should_run.py -> execution_preparation.py -> read_transaction.ts)、todo claim(local_authority.py -> todo_claim.ts)与 todo update/complete(provider_update.py/provider_terminal_lifecycle.py -> todo_update.ts/todo_terminal_lifecycle.ts)。authority_semantics 清晰:子目录与物理别名继续可用,跨 checkout 拒绝不写入状态,更换目录需显式版本化 task-lease release 后重新认领,不扩大任何租约或合并权限。default_off_isolation 不适用新功能开关,原有无 write_workspace 租约与 soft_claim 语义均保持不变。

本地独立验证结果如下:

  • npm run typecheck:control-plane:PASS(0 错误)
  • npm run test:control-plane:PASS(总计 6762 项:6671 PASS,0 FAIL,91 SKIPPED——全部为未配置 LOOPX_TEST_POSTGRES_URL 的 PostgreSQL 测试;file、NoKV single-envelope、NoKV JSON-lines 与 SQLite 四个后端的 managed_claim_execution_conformance 均通过,以及 task_lease_workspace.test.ts 32/33 通过、execution_preparation.test.ts 9/9 通过)
  • pytest -n 4 tests/control_plane/test_quota_execution_preparation.py tests/control_plane/test_workspace_git_fact_reads.py tests/test_task_lease_worktree.py tests/control_plane/test_todo_claim_argument_recovery.py tests/control_plane/test_canonical_claim_execution_proof.py tests/control_plane/test_todo_update_lease_recovery.py:PASS(214 项全过,含 Git hook 继承环境变量、子目录、别名、兄弟 worktree 拒绝、todo receipt 读回)
  • 独立 CLI todo complete --claim-operation-id 端到端反事实(SQLite:兄弟 worktree 触发 lease_workspace_divergence,原 worktree 成功完成):PASS
  • ruff check(8 个改动 Python 文件)与 mypy --strict --follow-imports=silent(6 个改动 Python 文件):PASS;仓库配置 python -m mypy 报错 1 处位于未改文件 interaction_contract.py:1004(pre_existing_unrelated)
  • loopx canary premerge --from-git-diff --git-diff-base b927e20bfbe60817570bceb8654e2bfbc96abadf(含 check_rfc_bilingual.py、semantic-vocabulary-drift-smoke.py、loopx check 公私边界扫描):18/19 PASS;peer-agent-runtime-v1-smoke.py 在 peer-agent-hard-cut-boundary-smoke.py 因未改文件 docs/product/releases/v2.4.0.md:207 失败(在基线 b927e20bfbe60817570bceb8654e2bfbc96abadf 复现完全相同行与报错,属 pre_existing_unrelated)。

残余风险与最强的待补验证:1) 本次本地环境未连接实时 PostgreSQL 服务,91 项 TS PostgreSQL 集成用例与 1 项 task_lease_workspace.test.ts PG 用例处于 UNVERIFIED(仅跳过,PR 说明引用了托管 CI PG 16.15);2) 携带 --task-lease-idempotency-key(不带 --claim-operation-id)的独立租约 todo update/complete 按设计未自动绑定当前目录探测,若后续需要为非受管独立租约也强制物理校验需另案明确语义;3) 既有基线 peer-agent-runtime-v1-smoke.py 与 interaction_contract.py mypy 失败在修复前仍会阻塞自动合并门。

我的整体评价 / Verdict

对 problem_context.outcome_impact 的评估:long_horizon 为 improved(阻断跨 worktree 静默续用或写回他人/异地工作区导致的上下文错乱,且保证父 Git hook 环境不污染工作区绑定与交付快照),user_experience 为 improved(同一 checkout 的子目录与别名无缝工作,跨目录失败直接给出清晰的 lease_workspace_divergence 与 release + 新 claim 恢复路径),visual_review 为 not_applicable(纯控制面与参考文档改动,无渲染 UI 变更,unverified_scope: none)。

基线与精确 head 4a636c57005c8edd655b0b04a5c144ff401670ba 的 observable_semantics 对比表明,普通无 worktree 绑定租约、soft_claim、已释放闭环与历史 todo receipt 读回均保持兼容,活动 worktree 受管认领在执行准备、认领及引用更新/完成处实现闭环校验;code_volume 判定为 necessary(doctor_git.py 并消除局部环境函数而复用 workspace_git_environment,无重复状态或兼容死分支);change_proportionality 为 proportionate;default_off_isolation 为 not_applicable(无新增 opt-in 开关,原有普通路径保持等价);authority_semantics 为 aligned;本次改动未新增共享状态枚举或词汇表(semantic_alignment 为 not_applicable,semantic-vocabulary-drift-smoke.py 已通过)。尽管基线未改文件的 peer-agent-runtime-v1-smoke 与 mypy 既有失败及本地未运行实时 PostgreSQL 仍需合并前门禁另行跟踪,本精确提交的变更范围、跨层一致性与独立本地验证均达到批准标准。

English verdict: APPROVE. On exact head 4a636c5, active worktree-bound managed claims enforce original-checkout alignment across quota should-run, todo claim, and claim-referenced todo update/complete (allowing aliases, subdirectories, historical todo receipt, and inherited Git hook isolation) with 6671 TS tests (91 PG skipped), 214 Python tests, CLI completion counterfactual, and changed-file Ruff/mypy passing; pre-existing base failures in peer-agent-runtime-v1-smoke and interaction_contract.py mypy are unrelated.

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