fix(todo): preserve error_code and actionable recovery contract for hard-lease claim failures

Signed-off-by: mac <bishopapril850965@yahoo.com>

Author: mac

loopx/cli_commands/todo_event.py

@@ -4,6 +4,9 @@
 from collections.abc import Callable
 from pathlib import Path
 
+from ..control_plane.coordination.local_authority import (
+    LocalCoordinationAuthorityRejection,
+)
 from ..control_plane.todos.external_wait_contract import TodoExternalWaitAuthoringError
 from ..control_plane.todos.handoff_mode import HandoffModeError
 from ..control_plane.todos.contract import decision_scope_metadata_value
@@ -43,12 +46,25 @@ def todo_error_payload(args: argparse.Namespace, exc: Exception) -> dict[str, ob
     if isinstance(exc, (TaskLeaseError, HandoffModeError)):
         payload["error_code"] = exc.code
         payload.update(exc.payload)
+    elif isinstance(exc, LocalCoordinationAuthorityRejection):
+        payload["error_code"] = exc.code
+        payload["code"] = exc.code
+        for key, value in exc.payload.items():
+            if key not in {
+                "schema_version",
+                "status",
+                "failure_kind",
+                "reason_code",
+                "reason",
+            }:
+                payload[key] = value
     elif isinstance(exc, TodoExternalWaitAuthoringError):
         payload["error_code"] = exc.code
         if exc.authoring_contract is not None:
             payload["authoring_contract"] = exc.authoring_contract
     return payload
 
+
 def append_todo_rollout_event(
     payload: dict[str, object],
     *,

loopx/control_plane/coordination/todo_claim.ts

@@ -577,10 +577,28 @@ export async function executeCoordinationTodoClaim(
       }
     } else if (handoffMode === "hard_lease" &&
         !activeLeaseForOwner(currentLease, authority.owner, input.now)) {
+      const existingVersion = currentLease !== undefined
+        ? (leaseInteger(currentLease, "version") ?? 0)
+        : null;
+      const expectedVersionGuidance = existingVersion !== null
+        ? `; specify --task-lease-expected-version ${existingVersion} to match the existing canonical lease version`
+        : "; provide --task-lease-expected-version if a canonical lease already exists";
       return failure(
         "handoff_mode_requires_lease",
-        "hard_lease Todo claim requires an active canonical lease held by the claiming agent",
-        { todo_id: input.todo_id, actor_agent_id: authority.owner },
+        `hard_lease Todo claim requires an active canonical lease held by the claiming agent; ` +
+          `retry with \`loopx todo claim --task-lease-idempotency-key <key>\`${expectedVersionGuidance}`,
+        {
+          todo_id: input.todo_id,
+          actor_agent_id: authority.owner,
+          handoff_mode: handoffMode,
+          recovery: {
+            command: "loopx todo claim",
+            requires_flags: ["--task-lease-idempotency-key"],
+            optional_flags: ["--task-lease-expected-version"],
+            expected_version: existingVersion,
+            expected_version_required: existingVersion !== null,
+          },
+        },
         "decision_rejection",
       );
     }

tests/control_plane/test_local_coordination_authority.py

@@ -819,7 +819,7 @@ def test_promoted_hard_lease_claim_cli_atomically_acquires_ownership(
     )
     state_file.unlink()
 
-    command = [
+    base_command = [
         sys.executable,
         "-m",
         "loopx.cli",
@@ -839,6 +839,27 @@ def test_promoted_hard_lease_claim_cli_atomically_acquires_ownership(
         "agent-a",
         "--claim-operation-id",
         "atomic-cli-claim",
+    ]
+    initial_failure = subprocess.run(
+        base_command,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    assert initial_failure.returncode == 1
+    failure_payload = json.loads(initial_failure.stdout)
+    assert failure_payload["ok"] is False
+    assert failure_payload["error_code"] == "handoff_mode_requires_lease"
+    assert failure_payload["handoff_mode"] == "hard_lease"
+    assert "loopx todo claim --task-lease-idempotency-key" in failure_payload["error"]
+    assert "--task-lease-expected-version" in failure_payload["error"]
+    recovery = failure_payload.get("recovery") or {}
+    assert recovery.get("command") == "loopx todo claim"
+    assert recovery.get("requires_flags") == ["--task-lease-idempotency-key"]
+    assert "--task-lease-expected-version" in (recovery.get("optional_flags") or [])
+
+    command = [
+        *base_command,
         "--task-lease-idempotency-key",
         "turn:atomic-cli-claim",
         "--task-lease-expected-version",
@@ -1398,8 +1419,14 @@ def test_hard_lease_eligibility_rejection_is_valueerror(
     assert isinstance(exc_info.value, LocalCoordinationAuthorityRejection)
     assert exc_info.value.code == "handoff_mode_requires_lease"
     assert (
-        str(exc_info.value)
-        == "hard_lease Todo claim requires an active canonical lease held by the claiming agent"
+        "hard_lease Todo claim requires an active canonical lease held by the claiming agent"
+        in str(exc_info.value)
+    )
+    assert "loopx todo claim --task-lease-idempotency-key" in str(exc_info.value)
+    assert "--task-lease-expected-version" in str(exc_info.value)
+    assert (
+        exc_info.value.payload.get("recovery", {}).get("requires_flags")
+        == ["--task-lease-idempotency-key"]
     )
     store_after = json.loads(
         (

tests/control_plane_ts/local_authority_runtime.test.ts

@@ -926,6 +926,22 @@ test("provider-first Todo claim validates authority and hard-lease ownership", a
     claimed_by: "agent-a",
   });
   assert.equal(missingLease.reason_code, "handoff_mode_requires_lease");
+  assert.match(
+    String(missingLease.reason),
+    /loopx todo claim --task-lease-idempotency-key/,
+  );
+  assert.match(
+    String(missingLease.reason),
+    /--task-lease-expected-version/,
+  );
+  assert.equal(
+    (missingLease.recovery as Record<string, unknown> | undefined)?.command,
+    "loopx todo claim",
+  );
+  assert.deepEqual(
+    (missingLease.recovery as Record<string, unknown> | undefined)?.requires_flags,
+    ["--task-lease-idempotency-key"],
+  );
 
   const dryRun = await claimLocalCoordinationTodo({
     ...base,