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
8 changes: 8 additions & 0 deletions docs/reference/required-work-context.md
Original file line number Diff line number Diff line change
Expand Up @@ -553,6 +553,14 @@ 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. This read reports what the claim observed and remains
available after a lease changes. 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
33 changes: 32 additions & 1 deletion loopx/cli_commands/todo.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
from operator import itemgetter
from pathlib import Path

from ..cli_runtime import report_json_text
from ..command_invocation import cli_option_args, loopx_cli_argv
from ..control_plane.agents.workspace_guard import capture_delivery_workspace
from ..control_plane.capability_hooks import PostWritebackHookRegistration
Expand Down Expand Up @@ -151,6 +152,34 @@ def _thin_claim_projection(payload: dict[str, object], route: Sequence[str]) ->
}


def _thin_claim_overlap_advisories(payload: dict[str, object], route: Sequence[str]) -> None:
"""Link long peer scope lists to the immutable claim receipt."""
advisories = payload.get("integration_overlap_advisories")
goal_id = payload.get("goal_id")
operation_id = payload.get("claim_operation_id")
if (
not isinstance(goal_id, str) or not goal_id
or not isinstance(operation_id, str) or not operation_id
or not isinstance(advisories, list) or not advisories
or any(not isinstance(row, dict) or not isinstance(row.get("write_scopes"), list)
for row in advisories)
):
return
compact = {
"integration_overlap_advisories": [
{**{key: value for key, value in row.items() if key != "write_scopes"},
"write_scope_count": len(row["write_scopes"])}
for row in advisories
],
"integration_overlap_detail_command": shlex.join([
*route, "todo", "receipt", "--goal-id", goal_id, "--operation-id", operation_id,
]),
}
original = {"integration_overlap_advisories": advisories}
if len(report_json_text(compact).encode("utf-8")) < len(report_json_text(original).encode("utf-8")):
payload.update(compact)


def handle_todo_command(
args: argparse.Namespace,
*,
Expand All @@ -174,6 +203,7 @@ def handle_todo_command(
format_name=format_name,
list_reader=list_goal_todos,
)
output_format = format_name or str(getattr(args, "format", None) or "markdown")
renderer = render_todo_markdown
if args.todo_command == "plan":
renderer = render_task_planning_packet
Expand Down Expand Up @@ -506,6 +536,8 @@ def handle_todo_command(
payload.pop(internal, None)
if args.todo_thin:
_thin_claim_projection(payload, route)
if output_format == "json":
_thin_claim_overlap_advisories(payload, route)
elif args.todo_command == "update":
validate_todo_update_options(args)
update_operation = partial(
Expand Down Expand Up @@ -872,7 +904,6 @@ def handle_todo_command(
post_writeback_projection_builder=post_writeback_projection_builder,
admission_factory=FirstPartyHostGoalAdmission,
)
output_format = format_name or str(getattr(args, "format", None) or "markdown")
print_payload(
payload,
output_format,
Expand Down
53 changes: 42 additions & 11 deletions tests/test_task_lease_worktree.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
"""Real sibling Git worktrees and the public lease CLI on both canonical providers."""
import json
import shlex
import subprocess
import sys
from pathlib import Path
Expand Down Expand Up @@ -121,7 +122,8 @@ def acquire(key, path, expected=0, scope="src/**"):

@pytest.mark.skipif(sys.platform not in {"darwin", "linux"}, reason="worktree fixture requires symlinks")
@pytest.mark.parametrize("provider", ["file", "sqlite"])
def test_ordinary_claim_uses_its_independent_worktree(tmp_path, monkeypatch, capsys, provider):
@pytest.mark.parametrize("large_peer_scope", [False, True], ids=["small-scope", "large-scope"])
def test_ordinary_claim_uses_its_independent_worktree(tmp_path, monkeypatch, capsys, provider, large_peer_scope):
"""Normal claims admit sibling edits without weakening physical collisions."""
isolate_sqlite_runtime(tmp_path, monkeypatch)
project = tmp_path / "repo"
Expand All @@ -145,11 +147,14 @@ def git(*args):
"id": goal, "repo": str(project), "state_file": str(state),
"coordination": {"registered_agents": ["agent-a", "agent-b"]},
}]}))
peer_scopes = ["src/**"]
if large_peer_scope:
peer_scopes.extend(f"tests/fixtures/peer-scope/module_{i:03}.py" for i in range(92))
projection = build_todo_runtime_shadow_projection(goal_id=goal, handoff_mode="hard_lease", leases=[], todos=[{
"schema_version": "todo_item_v0", "todo_id": f"todo_ordinary_{key}", "role": "agent", "status": "open", "done": False,
"text": "Edit isolated source", "archive_state": "active", "source_section": "Agent Todo", "index": i,
"task_class": "advancement_task", "task_domain": "code", "task_repository": "git:github.com/example/project",
"required_write_scopes": ["src/**"],
"required_write_scopes": peer_scopes if key == "a" else ["src/**"],
} for i, key in enumerate(("a", "b"), 1)])
initialize_canonical_authority(runtime, goal, projection, state_path=state, provider=provider)

Expand All @@ -160,9 +165,9 @@ def cli(command, key, *args, expected=0):
assert rc == expected, output
return json.loads(output)

def claim(key, operation, expected=0):
def claim(key, operation, *options, expected=0):
return cli(["todo", "claim"], key, "--agent-id", f"agent-{key}", "--claimed-by", f"agent-{key}",
"--claim-operation-id", operation, expected=expected)
"--claim-operation-id", operation, *options, expected=expected)

monkeypatch.chdir(a)
assert claim("a", "claim-a")["execution_managed"]
Expand All @@ -179,22 +184,48 @@ def claim(key, operation, expected=0):
git("remote", "set-url", "origin", "https://github.com/example/project.git")
(b / "nested").mkdir()
monkeypatch.chdir(b / "nested")
accepted = claim("b", "claim-b")
assert accepted["execution_managed"]
assert accepted["integration_overlap_advisories"] == [{
"todo_id": "todo_ordinary_a", "owner": "agent-a", "write_scopes": ["src/**"],
overlap = {
"todo_id": "todo_ordinary_a", "owner": "agent-a", "write_scopes": peer_scopes,
"reason": "independent_worktree_integration_overlap",
}]
}
if large_peer_scope:
preview = claim("b", "preview-b", "--thin", "--dry-run")
assert preview["integration_overlap_advisories"] == [overlap]
assert "integration_overlap_detail_command" not in preview
accepted = claim("b", "claim-b", "--thin")
assert accepted["execution_managed"]
if large_peer_scope:
assert accepted["integration_overlap_advisories"] == [{
"todo_id": "todo_ordinary_a", "owner": "agent-a", "write_scope_count": len(peer_scopes),
"reason": "independent_worktree_integration_overlap",
}]
command = shlex.split(accepted["integration_overlap_detail_command"])
assert command[-6:] == ["todo", "receipt", "--goal-id", goal, "--operation-id", "claim-b"]
observed = subprocess.run(command, capture_output=True, text=True, timeout=30, check=True)
detail = json.loads(observed.stdout)
assert detail["ok"] and detail["status"] == "found"
assert detail["provider_revision"] == accepted["provider_revision"]
assert detail["receipts"][0]["result"]["integration_overlap_advisories"] == [overlap]
else:
assert accepted["integration_overlap_advisories"] == [overlap]
assert "integration_overlap_detail_command" not in accepted
second = cli(["task-lease", "inspect"], "b")["lease"]
assert "write_workspace" in first
assert first["write_workspace"] != second["write_workspace"]
assert str(tmp_path) not in json.dumps(second)
assert cli(["todo", "list"], "b")["todo"]["claimed_by"] == "agent-b"
replay = claim("b", "claim-b")
assert replay["status"] == "replayed"
assert replay["integration_overlap_advisories"] == [overlap]
assert cli(["task-lease", "inspect"], "b")["lease"] == second
cli(["task-lease", "release"], "b", "--owner", "agent-b", "--idempotency-key", second["idempotency_key"],
"--expected-version", str(second["version"]))
released = cli(["task-lease", "release"], "b", "--owner", "agent-b",
"--idempotency-key", second["idempotency_key"], "--expected-version", str(second["version"]))
assert released["released"]
if large_peer_scope:
observed = subprocess.run(command, capture_output=True, text=True, timeout=30, check=True)
late = json.loads(observed.stdout)
assert released["provider_revision"] != detail["provider_revision"]
assert late == detail
assert claim("b", "claim-b", expected=1)["ok"] is False
assert not cli(["task-lease", "inspect"], "b")["active"]

Expand Down
Loading