automaton/tasks/complete/add-state-loop-lock/VERDICT.md

Verdict: add-state-loop-lock

Status: PASS

Summary

Closed the TOCTOU read-modify-write race flagged in add-status-brakes/ADVERSARIAL_BUG_REPORT.md (A6) and add-loop-runner/ADVERSARIAL_BUG_REPORT.md (A2, A7) by wrapping the read-modify-write cycles on .state.loop in a cross-process file lock (_loop_lock). POSIX fcntl.flock(LOCK_EX), Windows msvcrt.locking(LK_LOCK, 1), per-loop granularity, blocking acquire, no timeout in v1.1. Stdlib only.

SPEC compliance

Requirement	Status
R1 — _loop_lock context manager (POSIX/Windows, blocking, finally-safe FD lifecycle)	✓
R2 — Wrap status.py cmd_pause_loop, cmd_resume_loop, cmd_approve_loop, cmd_check_gate (NOT --create-loop)	✓
R3 — Wrap cmd_tick's step-10 state write; lock covers _gate subprocess + state write	✓
R4 — Idempotence + early-return inside with releases cleanly (try/finally in the context manager, not caller)	✓
R5 — Lock file <loop_path>/.state.lock (per-loop granularity)	✓
R6 — Stdlib only (fcntl POSIX, msvcrt Windows, contextlib, sys, os)	✓
R7 — Existing atomic write (_write_state_loop tmp-then-replace) retained	✓
D-L1 — Blocking acquire, no timeout	✓
D-L2 — .state.lock per-loop, not GC'd	✓
D-L3 — --create-loop unwrapped	✓
D-L4 — Stdlib only, no filelock package	✓
D-L5 — Existing atomic write retained (defense-in-depth)	✓
D-L6 (new, necessary for SPEC R2+R3 consistency) — Env-var bypass ($AUTOMATON_NO_LOOP_LOCK=1) avoids self-deadlock when the runner spawns the --check-gate subprocess inside its held lock	✓

Bug reports

• BUG_REPORT: 5 non-blocking observations (O1-O5), all documented behaviors.
• ADVERSARIAL_BUG_REPORT: 8 attack vectors probed (A1-A8). One LOW finding (A4: harness calling loop-control command inside a tick would deadlock; deferred to harness-integration contract docs follow-up). All others verified safe.

Test results

• python3 -m py_compile scripts/status.py scripts/loop-runner.py ✓
• python3 -m pytest tests/test_state_loop_lock.py -v — 7 passed
• python3 -m pytest tests/ -q — 447 passed (was 440; +7 new; 0 regressions)
• Manual: --create-loop does NOT leave .state.lock (D-L3 ✓); first --check-gate does; AUTOMATON_NO_LOOP_LOCK=1 status.py --check-gate works (env var bypass exercised).
• Manual adversarial: 5 concurrent --approve --loop on a halted loop — only one wins (code 0, resumed_count=1); 4 re-read inside the lock and see status=running, exit 1. Race closed.
• Manual adversarial: 5 concurrent --pause-loop — all succeed (idempotent; pause is well-defined on already-paused); final state consistent.
• Manual adversarial: monkeypatch _gate to raise → exit exception → follow-up _loop_lock acquires immediately (lock released in finally).

D-items applied

• D-L1 to D-L6 all locked (see SPEC compliance table).

Subprocess-deadlock avoidance

The original SPEC's R2 and R3 contradict each other (both list --check-gate to acquire _loop_lock AND the runner to acquire the same lock across the --check-gate subprocess — would deadlock). Resolved via D-L6 (env-var bypass). The runner sets $AUTOMATON_NO_LOOP_LOCK=1 in the --check-gate subprocess's env ONLY (scoped via _run_json's env kwarg, propagated to _gate's subprocess.run). Harness subprocesses inherit os.environ unchanged (no env var) so their nested status.py calls lock normally and serialize against the runner's outer lock (intended for tasks; harness typically does status.py --transition only which doesn't touch .state.lock). Documented in _loop_lock's docstring + design doc.

Pipeline

research → research:awaiting_approval → research:approved → implement → code_review → code_review:awaiting_approval → code_review:approved → bug_find → adversarial_bug_find → doc_review → referee → complete

Pipeline driven end-to-end. Ready for --transition complete (relocates to tasks/complete/).