Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 42 additions & 45 deletions docs/reference/canonical-lease-renew.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,61 +93,59 @@ loopx --registry registry.json task-lease acquire \
```

The TypeScript entrypoint verifies the caller's Git root, origin against the
Todo's repository, machine identity and filesystem identity. This selects
cooperative code editing: overlapping relative file scopes return
`integration_overlap_advisories` identifying the other Todo and paths, so their
owners can coordinate and validate the combined changes before merge. The
other grant may describe a different checkout or omit workspace identity; an
unknown legacy grant no longer blocks the verified code editor. The advisory
does not attest the other editor's isolation or rewrite its grant. This is
cooperative code-edit coordination, not a filesystem access-control mechanism.
Todo's repository, machine identity and filesystem identity. Lease acquisition
enforces Todo execution ownership (`todo_lease_conflict`) and same physical
checkout/worktree exclusivity (`workspace_lease_conflict`); per-path
`write_scope_conflict` blocks and `integration_overlap_advisories` are retired.
Independent worktrees on separate checkouts may execute different Todos
concurrently without blocking on declared path globs, while shared checkouts
are serialized. This selects cooperative code-edit coordination, not a
filesystem access-control mechanism.
It does not authorize changing shared runtime data, Git administration, remote
branches, or merging. Use ordinary exclusive leases for those operations.
branches, or merging.

Accepted origin URLs use the same repository identity rules as Todo declarations:
explicit default transport ports (including SSH `:22` and Git `:9418`) do not
create another repository, while nondefault ports remain distinct. Origins with
passwords or unsafe path segments are rejected before lease acquisition.

Known same-checkout aliases and the same Todo retain existing exclusion, even
Known same-checkout aliases and the same Todo retain execution exclusion, even
if retained repository metadata differs for that physical checkout.
Requests without a verified caller workspace retain ordinary exclusive scope
checks, including against unknown legacy grants. Repository mismatch,
Repository mismatch,
redirected paths and a non-worktree root fail closed. Verified machine discovery
currently supports macOS, Linux and Windows; other hosts retain ordinary
currently supports macOS, Linux and Windows; other hosts retain Todo-level
leases. No workspace path or machine identifier is stored directly: only
opaque digests and the existing public repository identity enter the private
authority record.

Renewal preserves this identity. Acquire retries must use the same worktree,
scopes and execution key; an alias resolving to the same worktree is valid.
To change directories or return to ordinary exclusion, release your current
lease with its version and acquire a new execution key without
`--write-worktree`. Other holders need not release their grants to admit an
To change directories or reset workspace identity, release your current
lease with its version and acquire a new execution key with the updated flags.
Other holders in distinct worktrees need not release their grants to admit an
isolated code editor. Existing records and historical receipts are retained;
no foreign ownership, shared-runtime permission or merge authority changes.

**Behavior change:** worktree mode no longer requires both holders to have
verified sibling-worktree identities. File overlap is an integration advisory
unless the retained identity positively identifies the same physical checkout.
The Todo lease still fences the execution instance, exact retries, renewal and
lifecycle writes; code-file exclusivity is not that instance fence.
**Behavior change:** lease conflict checks enforce Todo ownership and same
physical checkout exclusivity (`workspace_lease_conflict`). Per-path
`write_scopes` conflict blocking and `integration_overlap_advisories` have been
retired. The Todo lease still fences the execution instance, exact retries,
renewal and lifecycle writes; path-glob overlap is not a cross-worktree blocker.

## 仓库相对路径的冲突边界

新的 canonical 租约从权威 Todo 的 `task_repository` 冻结
`lease.write_repository`,不接受调用者覆盖,也不从 CLI 当前目录猜测。同一 Goal
内,普通独占模式只有双方都是已知且不同的仓库,才隔离同名相对路径;大小写别名仍互斥。
完整 head 扫描、owner 资格、TTL、generation、CAS 与回执身份保持原规则,空 scope
仍不产生写冲突。旧记录缺少该字段或为 null 时保持未知,普通独占模式保守互斥,读回和续租不
回填;合法退役后的新执行才冻结当前仓库。损坏身份拒绝执行,续租、转交和释放
保留冻结值与原历史回执。当前执行证明、领取重放与 inspect 拒绝已知仓库漂移
(`lease_repository_divergence`);清理仍凭精确 owner/key/version,不能借 metadata
编辑替换已有执行契约。

JSON 与 Markdown 读回同一仓库字段或未知状态。这只是 Goal 内逻辑仓库互斥,
不识别物理目录、软链接别名,也不是跨 Goal 锁;不新增配置、promotion 或自动
委派。CLI 与 native provider 检查已覆盖该边界,完整前端/Lark 协作旅程仍需单独交付。
`lease.write_repository`,不接受调用者覆盖,也不从 CLI 当前目录猜测。
同一 Goal 内,租约互斥以 Todo 归属(`todo_lease_conflict`)与同一物理
checkout / Git worktree 独占(`workspace_lease_conflict`)为准,不再按静态路径
glob 重叠阻塞不同 Todo 或跨 worktree 的并发执行。
完整 head 扫描、owner 资格、TTL、generation、CAS 与回执身份保持原规则。
损坏仓库身份拒绝执行,续租、转交和释放保留冻结值与原历史回执;当前执行证明、
领取重放与 `inspect` 拒绝已知仓库漂移(`lease_repository_divergence`);
清理仍凭精确 owner/key/version,不能借 metadata 编辑替换已有执行契约。

JSON 与 Markdown 读回同一仓库字段或未知状态。这是物理 checkout 与 Todo 级协调,
不作为 OS 级文件系统沙盒,也不是跨 Goal 锁。CLI 与 native provider 检查已覆盖该边界,完整前端/Lark 协作旅程仍需单独交付。

独立 worktree 的 origin URL 与 Todo 声明使用同一仓库身份规则:显式默认端口
(包括 SSH `:22` 和 Git `:9418`)不产生另一个仓库身份,非默认端口仍须匹配。
Expand All @@ -156,18 +154,17 @@ JSON 与 Markdown 读回同一仓库字段或未知状态。这只是 Goal 内
### 独立 worktree 的协作代码编辑

在独立 Git worktree 根目录使用上方 `--write-worktree "$PWD"`。TS 入口验证
调用者的仓库、物理目录和主机身份;代码文件的 scope 重叠只返回
`integration_overlap_advisories`,供集成、评审与合并时协调。对方旧 lease
缺少 worktree 身份也不阻塞,且不会被改写或被推断成已隔离。已确认同一物理
checkout 的冲突、同一 Todo 的执行归属仍拒绝;软链接、Git 管理目录和仓库不匹配
仍在入口拒绝。

这是 worktree 模式的行为变更:文件范围从跨 checkout 的执行锁改为集成提示,
不再要求双方都先释放、重新绑定 worktree。Todo 实例 lease、CAS、TTL、重放、
续租及生命周期写入仍按原规则保护。共享运行状态、远端分支和合并权限不由
此模式授予;未提供经验证的调用者 worktree 时,普通独占规则保持不变。
如需恢复普通独占,按读回版本释放自己的 lease,再用新的执行 key、不带
`--write-worktree` 重新取得;无需修改其他角色的 lease。
调用者的仓库、物理目录和主机身份;已确认同一物理 checkout 的冲突仍返回
`workspace_lease_conflict` 并拒绝获取,不同 Git worktree 之间的不同 Todo 可并发获取,
不再生成逐路径 `write_scope_conflict` 或 `integration_overlap_advisories`。
软链接、Git 管理目录和仓库不匹配仍在入口拒绝。

这是并发租约模型的行为简化:将写锁收敛回 Todo 归属 + 物理 worktree 独占,
不再要求独立 worktree 为静态 path glob 做跨 checkout 阻塞或生成集成提示列表。
Todo 实例 lease、CAS、TTL、重放、续租及生命周期写入仍按原规则保护;共享运行状态、
远端分支和合并权限不由工作区隔离本身授予。
如需变更目录或切换 worktree,按读回版本释放自己的 lease,再用新的执行 key
重新取得;无需干扰其他 worktree 的持有人。

## Operate the current lease

Expand Down
34 changes: 10 additions & 24 deletions docs/reference/required-work-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -208,14 +208,10 @@ whole Goal/Todo narrative, source availability/revisions and read routes. Detail
history and optional authoring recipes remain expandable from the same capture.
Current narrative sources and their provenance precede other sources, including
large scoped preferences; both retain their complete selected values.
During an unbound Todo choice, including during workspace repair, the initial
read keeps the candidate identities and selection command. It points to long
candidate write scopes in the original capture when those scopes matter to the
choice. The guard for the same Turn supplies the current scopes before delivery.
When a selected Todo needs an ordinary managed claim, the initial read keeps
the claim and continuation instructions. Read long requested scopes at
`/selected_todo/required_write_scopes` when needed for preparation. Use the
same-Turn guard's complete current scopes after the claim and before delivery.
Todo `required_write_scopes` are omitted from default quota summaries,
capability gates, action portfolios, and `selected_todo` projections so initial
decision context stays compact without truncation pointers. Canonical Todo
reads (`todo list`) retain the full declared scopes when explicitly inspected.
The preference source's complete `current` view also stays in the initial read:
corrections, retirement/expiry and empty replacements retain their provenance,
revision and advisory authority. This captured pre-work view does not replace the
Expand Down Expand Up @@ -339,13 +335,14 @@ large for one page, the linked remainder contains its full details and the
suggested alternatives. The selection commands use the original Turn identity.

Native ready decisions from `quota should-run` and saved `quota context-project`
can link two reads when Goal or Todo scope details push controls past the serialized
can link two reads when boundary detail pushes controls past the serialized
first page budget. When those controls fit, the ordinary reader keeps its cursor.
Read `first_read_command` for the decision, stop conditions and required reads.
If `remaining_read_command` is present, follow it and its cursor before work,
even when the opening reports EOF. The remainder supplies deferred Goal write
scopes, checkpointed approval entries and the selected Todo's requested write
scopes. The opening shows the current approval counts and active scope summary.
scopes, checkpointed `active_write_scope`, and checkpointed approval entries.
The opening keeps only the current approval counts (`active_count` and
`inactive_count`), while Goal wildcard subpaths fold automatically.
The remainder can refer to other fully observed, unchanged fields. If the
observation is lost, its same-capture fallback restores the full remainder.

Expand Down Expand Up @@ -380,8 +377,8 @@ presentation changes neither admission nor the explicit off view.
控制信息超出序列化后的首页预算,导航可给出两段读取。控制信息能放进首页时,沿用普通游标。
先用 `first_read_command` 取得决策、停止条件和必读项。如果给出
`remaining_read_command`,即使首段已到 EOF,也要在开工前沿该命令及其游标读完。
续读提供延后交付的 Goal 写入范围、已记录的审批条目及选中 Todo 的请求写入范围。
两段绑定同一份捕获。首段保留当前审批数量和生效范围摘要。
续读提供延后交付的 Goal 写入范围、checkpointed `active_write_scope` 与已记录的
审批条目。两段绑定同一份捕获;首段仅保留当前审批数量摘要,并自动折叠 Goal 通配符子路径。
续读可引用其他已完整送达且未变化的字段。观察失效时,从同一捕获恢复完整续段。

准入检查要求先切换到独立工作树时,首读保留迁移指引和当前决策控制信息。
Expand Down Expand Up @@ -561,17 +558,6 @@ The native hook executes only a preparation bound to a captured Turn. An
ordinary claim recommendation remains available to its caller; reading one
or reading an original receipt does not trigger an automatic claim.

A successful managed `todo claim --thin` JSON reply can show peer worktree
overlap advice with `write_scope_count` in place of long path lists. It keeps
the other Todo, owner and overlap reason. Run `integration_overlap_detail_command`
to read the complete advice under `receipts[].result.integration_overlap_advisories`
for that claim operation. The command uses `todo receipt --thin --format json`
to return the receipt identity and historical advice without copying the
claimant's lease. The response includes `thin: true`. This read remains
available after a lease changes. Omit `--thin` to read the entire receipt.
Use `task-lease inspect` for a current grant. An ordinary claim reply retains
the full path lists.

For a selected Todo, preparation reads the canonical Todo and leases at one
checked provider revision. The internal read returns only that Todo's status,
assignment and lease facts. Unrelated Todo bodies stay with the provider
Expand Down
8 changes: 6 additions & 2 deletions examples/control_plane/task-lease-runtime-smoke.py
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,14 @@ def write_fixture(root: Path, provider: str) -> tuple[Path, Path]:
encoding="utf-8",
)
worker = project.parent / "worker"
worker_b = project.parent / "worker-b"
for args in [
("init", "--initial-branch", "main"),
("remote", "add", "origin", "https://example.invalid/loopx/lease-fixture.git"),
("-c", "user.name=LoopX Fixture", "-c", "user.email=fixture@example.invalid",
"commit", "--allow-empty", "-m", "fixture"),
("worktree", "add", "-b", "worker", str(worker)),
("worktree", "add", "-b", "worker-b", str(worker_b)),
]:
subprocess.run(["git", "-C", str(project), *args], check=True, capture_output=True, text=True)
projection = build_todo_runtime_shadow_projection(
Expand Down Expand Up @@ -132,7 +134,7 @@ def command(
def cli(
registry_path: Path, *args: str, check: bool = True
) -> subprocess.CompletedProcess[str]:
if args[0] == "acquire":
if args[0] == "acquire" and "--write-worktree" not in args:
args = (*args, "--write-worktree", str(registry_path.parents[2] / "worker"))
return command(registry_path, "task-lease", *args, check=check)

Expand Down Expand Up @@ -241,6 +243,8 @@ def exercise_provider(provider: str) -> None:
"120",
"--write-scope",
"docs/**",
"--write-worktree",
str(registry_path.parents[2] / "worker-b"),
)
)
assert same_goal_different_scope["ok"] is True, same_goal_different_scope
Expand All @@ -264,7 +268,7 @@ def exercise_provider(provider: str) -> None:
)
assert conflict.returncode == 1, conflict.stdout
conflict_payload = payload(conflict)
assert conflict_payload["error_code"] == "write_scope_conflict", (
assert conflict_payload["error_code"] == "workspace_lease_conflict", (
conflict_payload
)
assert conflict_payload["conflicts"][0]["todo_id"] == TODO_A, conflict_payload
Expand Down
28 changes: 24 additions & 4 deletions loopx/boundary_authority.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
from __future__ import annotations

from datetime import datetime, timezone
from pathlib import Path
from typing import Any

from .control_plane.runtime.time import parse_timestamp as _parse_timestamp
Expand Down Expand Up @@ -161,17 +162,26 @@ def normalize_checkpointed_boundary_authority_entries(
return entries


def _compact_checkpointed_boundary_authority_summary(value: Any) -> dict[str, Any] | None:
def _compact_checkpointed_boundary_authority_summary(
value: Any,
*,
goal_repo: str | Path | None = None,
) -> dict[str, Any] | None:
if not isinstance(value, dict):
return None

from .control_plane.coordination.configuration import fold_write_scope_subpaths

def _count(raw: Any) -> int:
try:
return max(0, int(raw or 0))
except (TypeError, ValueError):
return 0

active_scopes = normalize_required_write_scopes(value.get("active_write_scope"))
active_scopes = fold_write_scope_subpaths(
normalize_required_write_scopes(value.get("active_write_scope")),
goal_repo=goal_repo,
)
if not active_scopes and "active_count" not in value and "inactive_count" not in value:
return None
return {
Expand All @@ -182,12 +192,21 @@ def _count(raw: Any) -> int:
}


def checkpointed_boundary_authority_summary(coordination: dict[str, Any] | None) -> dict[str, Any] | None:
def checkpointed_boundary_authority_summary(
coordination: dict[str, Any] | None,
*,
goal_repo: str | Path | None = None,
) -> dict[str, Any] | None:
if not isinstance(coordination, dict):
return None
from .control_plane.coordination.configuration import fold_write_scope_subpaths

checkpointed_authority = coordination.get("checkpointed_boundary_authority")
if isinstance(checkpointed_authority, dict):
compact_summary = _compact_checkpointed_boundary_authority_summary(checkpointed_authority)
compact_summary = _compact_checkpointed_boundary_authority_summary(
checkpointed_authority,
goal_repo=goal_repo,
)
if compact_summary is not None and "entries" not in checkpointed_authority:
return compact_summary
checkpointed_authority = checkpointed_authority.get("entries")
Expand All @@ -202,6 +221,7 @@ def checkpointed_boundary_authority_summary(coordination: dict[str, Any] | None)
for scope in normalize_required_write_scopes(entry.get("write_scope")):
if scope not in active_scopes:
active_scopes.append(scope)
active_scopes = fold_write_scope_subpaths(active_scopes, goal_repo=goal_repo)
return {
"schema_version": CHECKPOINTED_BOUNDARY_AUTHORITY_SCHEMA_VERSION,
"active_count": len(active_entries),
Expand Down
10 changes: 2 additions & 8 deletions loopx/capabilities/explore/todo_branch_plan.py
Original file line number Diff line number Diff line change
Expand Up @@ -445,13 +445,7 @@ def build_explore_todo_branch_plan(
scopes = _required_write_scopes(candidate)
resource_lane = str(candidate.get("resource_lane") or "")
conflict_with = ""
if scopes:
for selected_todo_id, existing_scopes in selected_scopes:
if _scopes_overlap(scopes, existing_scopes):
conflict_with = selected_todo_id
hazards.append(f"write_scope_conflict:{selected_todo_id}")
break
elif not allow_unscoped_parallel and selected:
if not scopes and not allow_unscoped_parallel and selected:
conflict_with = selected[0]["todo_id"]
hazards.append("unscoped_parallel_disabled")

Expand Down Expand Up @@ -586,7 +580,7 @@ def build_explore_todo_branch_plan(
"rejected_candidates": rejected[: max(0, normalized_width * 3)],
"resource_portfolio": resource_portfolio_with_selection(resource_portfolio, selected),
"hazard_model": {
"write_scope_conflicts": "skip speculative branch when declared write scopes overlap",
"write_scope_conflicts": "retired from hard scheduling exclusion; leases isolate by Todo ownership and workspace checkout",
"shared_dependencies": (
"shared_artifact:* and shared_implementation:* capabilities are read-only "
"dependency labels, not write mutexes; mutable shared builds must remain in "
Expand Down
Loading
Loading