From 170cd0194c42245229a3a76e9b68acdf8c07292e Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Fri, 20 Nov 2026 00:32:10 +0800 Subject: [PATCH 1/2] Link long thin-claim overlap lists to their receipts Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- docs/reference/required-work-context.md | 8 ++++ loopx/cli_commands/todo.py | 33 ++++++++++++++- tests/test_task_lease_worktree.py | 53 ++++++++++++++++++++----- 3 files changed, 82 insertions(+), 12 deletions(-) diff --git a/docs/reference/required-work-context.md b/docs/reference/required-work-context.md index 7ccc94349b..9aef42af9a 100644 --- a/docs/reference/required-work-context.md +++ b/docs/reference/required-work-context.md @@ -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 diff --git a/loopx/cli_commands/todo.py b/loopx/cli_commands/todo.py index ea55679ebc..4ac82a5244 100644 --- a/loopx/cli_commands/todo.py +++ b/loopx/cli_commands/todo.py @@ -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 @@ -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, *, @@ -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 @@ -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( @@ -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, diff --git a/tests/test_task_lease_worktree.py b/tests/test_task_lease_worktree.py index 1c081219c5..b452c0b2da 100644 --- a/tests/test_task_lease_worktree.py +++ b/tests/test_task_lease_worktree.py @@ -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 @@ -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" @@ -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) @@ -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"] @@ -179,12 +184,31 @@ 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"] @@ -192,9 +216,16 @@ def claim(key, operation, expected=0): 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"] From 16b4cfb8685ea46666e8556ff468082b866882a7 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Fri, 20 Nov 2026 08:00:22 +0800 Subject: [PATCH 2/2] Read claim overlap details without copying the lease Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- docs/reference/required-work-context.md | 9 +++-- loopx/cli_commands/todo.py | 39 ++++++++++++++++++- .../cli_commands/todo_argument_validation.py | 11 ++++-- tests/test_task_lease_worktree.py | 33 +++++++++++++++- 4 files changed, 82 insertions(+), 10 deletions(-) diff --git a/docs/reference/required-work-context.md b/docs/reference/required-work-context.md index 9aef42af9a..ed0631e0af 100644 --- a/docs/reference/required-work-context.md +++ b/docs/reference/required-work-context.md @@ -557,9 +557,12 @@ 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 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, diff --git a/loopx/cli_commands/todo.py b/loopx/cli_commands/todo.py index 4ac82a5244..dd46614ffb 100644 --- a/loopx/cli_commands/todo.py +++ b/loopx/cli_commands/todo.py @@ -172,7 +172,7 @@ def _thin_claim_overlap_advisories(payload: dict[str, object], route: Sequence[s for row in advisories ], "integration_overlap_detail_command": shlex.join([ - *route, "todo", "receipt", "--goal-id", goal_id, "--operation-id", operation_id, + *route, "todo", "receipt", "--goal-id", goal_id, "--operation-id", operation_id, "--thin", ]), } original = {"integration_overlap_advisories": advisories} @@ -180,6 +180,39 @@ def _thin_claim_overlap_advisories(payload: dict[str, object], route: Sequence[s payload.update(compact) +def _thin_claim_receipt(payload: dict[str, object], goal_id: str, operation_id: str) -> None: + """Project historical overlap advice from the exact canonical claim receipt.""" + if payload.get("status") == "found": + records = payload.get("receipts") + receipt = records[0] if isinstance(records, list) and len(records) == 1 else None + result = receipt.get("result") if isinstance(receipt, dict) else None + if ( + not isinstance(receipt, dict) + or receipt.get("schema_version") != "loopx_coordination_todo_claim_receipt_v0" + or receipt.get("goal_id") != goal_id + or receipt.get("operation_id") != operation_id + or not isinstance(result, dict) + or result.get("claim_operation_id") != operation_id + or result.get("execution_managed") is not True + or not isinstance(result.get("todo_id"), str) + or not result["todo_id"] + or not isinstance(result.get("integration_overlap_advisories"), list) + ): + raise ValueError( + "todo receipt --thin requires an exact managed claim receipt with overlap advice. " + "Omit --thin for the full receipt." + ) + payload["receipts"] = [{ + **receipt, + "result": { + "claim_operation_id": operation_id, + "todo_id": result["todo_id"], + "integration_overlap_advisories": result["integration_overlap_advisories"], + }, + }] + payload["thin"] = True + + def handle_todo_command( args: argparse.Namespace, *, @@ -249,6 +282,8 @@ def handle_todo_command( ) elif args.todo_command == "receipt": validate_todo_receipt_options(args) + if args.todo_thin and output_format != "json": + raise ValueError("todo receipt --thin requires --format json") runtime_root = resolve_runtime_root( load_registry(registry_path), runtime_root_arg ) @@ -275,6 +310,8 @@ def handle_todo_command( "command": "receipt", **result, } + if args.todo_thin: + _thin_claim_receipt(payload, args.goal_id, args.operation_id) elif args.todo_command == "result-read": validate_todo_result_read_options(args) registry = load_registry(registry_path) diff --git a/loopx/cli_commands/todo_argument_validation.py b/loopx/cli_commands/todo_argument_validation.py index 89a5bd766f..469b20f582 100644 --- a/loopx/cli_commands/todo_argument_validation.py +++ b/loopx/cli_commands/todo_argument_validation.py @@ -148,7 +148,7 @@ # field owner; other lifecycle commands retain full help until centralized. TODO_ACTION_FIELDS = { "list": frozenset({"role", "todo_id", "status", "agent_id", "todo_limit", "todo_thin", "todo_summary", "include_archived", "state_file", "project", "dry_run"}), - "receipt": frozenset({"operation_id"}), + "receipt": frozenset({"operation_id", "todo_thin"}), "result-read": frozenset({"todo_id"}), "plan": frozenset({"text", "agent_id", "project"}), "project-markdown": frozenset({"state_file", "execute", "provider_revision", "project"}), @@ -324,7 +324,7 @@ def validate_todo_list_options(args: argparse.Namespace) -> None: def validate_todo_receipt_options(args: argparse.Namespace) -> None: _validate_todo_option_subset( args, TODO_ACTION_FIELDS["receipt"], - "todo receipt only accepts --goal-id, --operation-id, and --format; unsupported: ", + "todo receipt only accepts --goal-id, --operation-id, --thin, and --format; unsupported: ", ) if not args.operation_id: raise ValueError("todo receipt requires --operation-id") @@ -766,8 +766,11 @@ def validate_shared_todo_options(args: argparse.Namespace) -> None: raise ValueError( "--limit is supported only by todo list" ) - if args.todo_thin and args.todo_command not in {"list", "claim"}: - raise ValueError("--thin is supported only by todo list and todo claim") + if args.todo_thin and "todo_thin" not in TODO_ACTION_FIELDS.get(args.todo_command, ()): + supported = ", ".join( + f"todo {action}" for action, fields in TODO_ACTION_FIELDS.items() if "todo_thin" in fields + ) + raise ValueError(f"--thin is supported only by {supported}") if getattr(args, "todo_summary", False): if args.todo_command != "list": raise ValueError("--summary is supported only by todo list") diff --git a/tests/test_task_lease_worktree.py b/tests/test_task_lease_worktree.py index b452c0b2da..e41a032fbe 100644 --- a/tests/test_task_lease_worktree.py +++ b/tests/test_task_lease_worktree.py @@ -200,12 +200,22 @@ def claim(key, operation, *options, expected=0): "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"] + assert command[-7:] == ["todo", "receipt", "--goal-id", goal, "--operation-id", "claim-b", "--thin"] 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["thin"] is True assert detail["provider_revision"] == accepted["provider_revision"] - assert detail["receipts"][0]["result"]["integration_overlap_advisories"] == [overlap] + original = subprocess.run(command[:-1], capture_output=True, text=True, timeout=30, check=True) + full_receipt = json.loads(original.stdout)["receipts"][0] + detail_receipt = detail["receipts"][0] + assert detail_receipt == {**full_receipt, "result": { + "claim_operation_id": "claim-b", + "todo_id": "todo_ordinary_b", + "integration_overlap_advisories": [overlap], + }} + assert full_receipt["result"]["lease"]["owner"] == "agent-b" + assert len(observed.stdout.encode("utf-8")) < len(original.stdout.encode("utf-8")) else: assert accepted["integration_overlap_advisories"] == [overlap] assert "integration_overlap_detail_command" not in accepted @@ -226,6 +236,25 @@ def claim(key, operation, *options, expected=0): late = json.loads(observed.stdout) assert released["provider_revision"] != detail["provider_revision"] assert late == detail + original = subprocess.run(command[:-1], capture_output=True, text=True, timeout=30, check=True) + assert json.loads(original.stdout)["receipts"][0] == full_receipt + missing = subprocess.run( + [*command[:-2], "missing-claim", "--thin"], capture_output=True, text=True, timeout=30, check=True, + ) + assert json.loads(missing.stdout)["status"] == "missing" + subprocess.run([ + *command[:-7], "todo", "add", "--goal-id", goal, "--role", "agent", + "--text", "A different operation", "--operation-id", "add-task", + ], capture_output=True, text=True, timeout=30, check=True) + original_add = subprocess.run( + [*command[:-2], "add-task"], capture_output=True, text=True, timeout=30, check=True, + ) + assert json.loads(original_add.stdout)["status"] == "found" + rejected = subprocess.run( + [*command[:-2], "add-task", "--thin"], capture_output=True, text=True, timeout=30, + ) + assert rejected.returncode == 1 + assert "requires an exact managed claim receipt" in json.loads(rejected.stdout)["error"] assert claim("b", "claim-b", expected=1)["ok"] is False assert not cli(["task-lease", "inspect"], "b")["active"]