fix(coordination): allow isolated worktree edits with integration advisories

[huangruiteng]

Parallel agents editing independent Git worktrees were blocked by repository-relative scope leases: a broad tests/** lease excluded an unrelated branch as if both agents shared one working directory.

Add explicit task-lease acquire --write-worktree PATH for canonical File/SQLite code-edit leases. The caller anchors relative paths before RPC; the TypeScript entrypoint requires absolute paths and verifies an independent Git root, origin, machine and filesystem identity. Overlapping scopes in verified sibling worktrees become integration advisories; the same worktree, unknown grants, other machines/clones and the same Todo retain exclusion. Existing leases are never silently reclassified. Shared runtime state and Git administration are outside this code-edit mode.

Renewal and retries retain the frozen identity; changing worktrees cannot reuse an acquisition receipt. Conflict payloads identify the holder and explain safe coordination. The existing authority transaction, scope matcher and lease lifecycle remain the owners; Python transports the explicit option. Two adjacent imports now use their actual owners rather than facades.

Complete within this coordination boundary. This does not resolve Git merge conflicts or authorize merging. macOS/Linux machine verification is supported; other hosts retain ordinary leases. No frontend change is required: this is the standalone lease CLI and shared internal decision, with JSON and Markdown feedback updated. The canonical lease reference documents activation, limits and release/reacquire rollback.

Validation uses synthetic data only:

• Production CLI against real File/SQLite with two actual Git worktrees: aliases, redirected paths, old exclusive grants, original receipt replay, renewal and release. Ten focused existing/new cases passed; the final two provider scenarios were rerun after the last diagnostic change.
• Mixed-release lifecycle: the new code acquires a worktree lease, the previous installed CLI reads/renews/releases it, and the new code replays its original receipt. Both real File and SQLite cases passed with the frozen workspace preserved.
• Final native lease validation: 197 cases passed with zero skips, including the real PostgreSQL workspace reload. Caller-relative . and ../b CLI cases failed on both providers before the transport fix and passed afterward.
• Real isolated PostgreSQL: 308 provider integration cases passed before the caller-path refinement; the final four focused observer/decision/reload cases also passed. That refinement did not change storage code.
• TypeScript typecheck, focused Python Mypy/Ruff, semantic census/drift, structural ratchet, exact-scope change quality and diff/private-boundary checks passed. Final-scope risk-based premerge passed all 10 catalog checks, all 8 risk checks and the public-boundary check after the ignored-path refinement. Exact-scope quality receipt is valid.

Primary risk: code-edit declarations must not be mistaken for shared-state fencing. Worktree mode is explicit, does not alter old grants, rejects redirected paths/Git administration, and preserves same-Todo ownership. Leases store opaque local identities; raw machine identifiers and filesystem paths are not persisted.

Review refinement: Git ignore rules cannot prove physical isolation. Scope-directed filesystem traversal now rejects ignored scope-root symlinks, redirected ancestors of nonexistent exact leaves and dangling links, while allowing unrelated ignored links. Both real-provider regressions failed before this fix and passed after; all 197 native lease tests and the full control-plane typecheck pass again.

[huangruiteng]

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

Reviewed exact head: 98206c661068f58ed2100c9c7617b5b6e930a3c8; immutable base: 67930ab6af78491f10ca3de4ff74ef7a39954a51. 依据 capability policy revision 12，重审完整 12 文件 +392/-23 diff，并分别核对先前 cf69db1、c628e106 至当前 head 的修复。当前无阻塞发现；一项非阻塞简化建议见下。

动机

相同仓库相对路径在两个真正独立 Git worktree 中编辑，旧 canonical lease 把它们当作同一 checkout 而拒绝，容易使调用者放弃声明 scope。需求不是消除排他保护，而是在显式、可核实的代码编辑边界内把路径相交转成 integration advisory，同时保持真实共享状态和普通租约排他。

不声明 scope 虽能让单次 acquire 成功，却丢失碰撞信息；仅按 Todo、cwd 字符串或 caller 提供的 worktree key 区分会产生别名/伪造豁免。因此选择现有 acquire owner 上的窄观察和 shared decision 分支，比新增能力、第二套 lease 或迁移全体记录更小且可撤销。此 PR 闭合 standalone canonical File/SQLite CLI 代码编辑场景，不宣称完整 frontend/Lark 协作产品旅程。

改动思路

入口是 task-lease acquire --write-scope ... --write-worktree PATH。Python 将相对 PATH 锚定到调用者 cwd，TS 验证 Git root、origin/canonical Todo repository、同机 common-directory/worktree 的真实物理身份，并检查 scoped 物理目录。只在两个已验证 lease 同机、同仓库、同 Git common dir、不同 worktree 时，把“跨 Todo 的代码路径相交”转为 advisory；same Todo、owner、key、版本、TTL、claim 等已有门不绕过。

正向实际走通：A 用相对 . 获取 src scope → B 用 ../b 在 sibling worktree 获取相交 scope → 返回对方 Todo/path advisory → alias 同 identity 重试幂等 → 续租、独立 inspect、release 保留身份。负向：primary checkout、同 checkout alias、无 verified workspace 的同仓库 lease、改变 retry worktree、Git admin scope、ignored/scoped symlink、dangling/redirected ancestor 均保持拒绝；无关 ignored symlink 不误挡。新增 subject 不自动获得已有豁免，拒绝后经原 holder 正常释放能够重新推进。

具体改动

• task_lease.py CLI 增加 acquire-only opt-in 参数与 JSON/Markdown integration advisory；文档给出精确启用、release/reacquire 的退出/迁移路线以及不授权的范围。
• task_lease_acquire_adapter.py 只做路径锚定/transport，改正两处已有类型导入；不创建 Python 决策 owner。
• task_lease_workspace.ts 是最近的 acquire owning boundary 中的真实 IO observer，不是新 capability/provider。旧基于 Git inventory 的实现遗漏 ignored paths；当前改为按 scope 重叠窄遍历实际 opendir/lstat/realpath，拒绝 scoped redirect，不遍历无关 subtree。存储的是 opaque host/common/worktree digests 与既有 repository identity，不保存本机路径或机器标识原值。
• task_lease_acquire_decision.ts 与两个 acquire caller、canonical task_lease_state.ts、lease_acquisition_proof.ts 将可选身份接入同一 typed admission、CAS 和 durable replay；renew 保留已冻结身份，旧 receipt/旧 lease 不自动扩权。IO manifest 更新归属行；75 行 native tests 与 102 行 production CLI tests 覆盖持久化及公开入口。

相关简化 pass：已有 write-scope matcher、eligibility、repository codec、proof 与 lifecycle 均复用，避免第二个 scope authority。一个可选清理是删除 execute_native_task_lease_lifecycle 在 adapter 第 597 行新增但未读取/无 caller 的 write_worktree 参数；该参数只属于 acquire。当前 CLI 已对非 acquire 明确拒绝、renew 只保留旧 identity，因此这是维护清晰度建议，不是本轮阻塞，也不要求为它扩大迁移。

对主干的风险

最强实际反例是“ignored src symlink 指向公共目录，两个 worktree 看起来不同却被错误豁免”。我在 c628e106 的公开 File/SQLite CLI 路径上独立复现两项失败；同一探针在当前 head 两项通过。当前完整 CLI fixture 还覆盖 ignored root、未创建叶子的 redirected ancestor、dangling link、无关 ignored link 的相反方向，不能只以最后一个缺陷修复作为全 PR 证明。

独立验证：当前 head 505 项 native + 隔离真实 PostgreSQL 16 integration tests 全过、0 skip；control-plane typecheck、changed-file Ruff、focused Mypy 通过。公开 CLI fixture 两 provider 通过；8 项 reviewer probes 通过，包含 omitted-mode 基线/head 对照、真实新增 Todo、普通排他拒绝后的恢复、同一旧 baseline CLI 对新 identity 的 inspect/renew/release。这不是只在两个新 provider 之间互相验证。未启用时既有 lease 字段、版本/key、claim、effects 和排他规则不变；新 help/冲突恢复提示只是说明显式 opt-in 选项，不自动激活或重新分类旧 grants。

最终 premerge：10 catalog + 8 risk + public-boundary 全过，无 manual hold。完整导入 mypy 未全绿：完全同命令在 base 4246 errors，head 4243；按 path/diagnostic/message 归一仅去掉行号后，head 没有新增错误，三条消失的诊断正是本 PR 修正的导入/泛型。我独立记录的 exact-scope change-quality receipt 仍为 non-passing：完整导入类型检查的失败被如实保留，没有豁免。这个 quality/merge hold 与按 baseline 归因给出 APPROVE 是不同判断，不授权交付或合并。其余既有全树类型债务不应变成本 PR 的 REQUEST_CHANGES；focused changed-source typecheck 和 changed invariant 独立通过。初次 pytest 混用 importlib 导致 fixture collection error，按各自真实入口拆开后均通过；保留错误及归因，不冒充产品修复。wait_for_ci=false，未获取/等待远端 CI。

边界仍是 cooperative code-edit coordination，不是 filesystem ACL：不能阻止受信进程在 acquire 后重新替换 symlink；不能授权共享 runtime、Git administration、remote branch 或 merge。macOS/Linux observation 路径可用，未验证 Windows；PostgreSQL 共享 codec/事务实际验证不等于服务认证/权限发布或 provider promotion。broad scope 的实际目录扫描成本随其 covered subtree 增长，当前实现窄过滤且限于显式 acquire；不宣称长期 soak。

我的整体评价

APPROVE，保留上述非阻塞参数清理建议。当前机制与原问题相称，明确区分 integration advisory 和强制 owner/CAS/exclusive 门；新增 state 是由真实 IO 产生并冻结的不可推导执行身份，不是手工同步的第二套事实。参数省略、旧 lease、同 checkout 和后来新建 Todo 不偷偷扩权；真实拒绝经过正常 release/reacquire 可恢复到 useful work。

按仓库控制面政策留给维护者合并，本结论不授权自合并、admin bypass、安装升级或忽略独立质量门。整体 Goal/长期 provider acceptance 保持开放。

English verdict: APPROVE - exact head 98206c6; ignored-symlink regression fixed and independently falsified, ordinary/future/mixed-version CLI contracts verified on real File/SQLite, 505 native/real PostgreSQL tests and final premerge pass. Remaining full-import Mypy debt is unchanged pre-existing; unused lifecycle parameter cleanup is non-blocking, and maintainer merge authority remains required.