automaton/tasks/complete/add-claim-loop-task/IMPLEMENTATION.md

Implementation: add-claim-loop-task

What was implemented

--claim-loop-task subcommand (status.py)

New --claim-loop-task <name> --task <taskname> [--project P] command. Uses _loop_lock for serialization. Implementation steps:

1. Checks .state.loop exists (untracked → exit 2)
2. Scans all loops via _all_loop_dirs() — if another running/paused loop owns the task → exit 2 with task_already_claimed:{other}
3. If self owns the task → exit 0 (idempotent, no re-write)
4. If nobody owns it → sets state["current_task"] = taskname, writes .state.loop, exit 0

Runner claim integration (loop-runner.py)

Step 3.5: After _find_work returns a candidate different from state.current_task, spawns status.py --claim-loop-task as a subprocess with $AUTOMATON_NO_LOOP_LOCK=1 (same bypass as _gate). Non-zero exit → skip tick with task_claimed_by_other_loop.

Step 9.5: After orchestrator subprocess, re-reads task .state. If complete or human_intervention → state["current_task"] = None (releases claim).

Files changed

• scripts/status.py — added _claim_loop_task_impl, cmd_claim_loop_task, --claim-loop-task arg + dispatch
• scripts/loop-runner.py — added step 3.5 (claim) and step 9.5 (release) in cmd_tick

Tests

10 tests in tests/test_claim_loop_task.py covering:

• Claim succeeds (no owner), claim refused (other owner), claim idempotent (self owner)
• Untracked loop, missing task arg
• Paused loop's claim blocks new claim
• Self-healing race (refuse, release, re-claim succeeds)
• Release on complete and human_intervention, no release on implement