with-device: an EACCES reported as CLAIMED — fix both halves (jess#280, AFD-133)

[avrabe]

Fixes #280 — filed by relay against jess's own interlock, with a clean reproduction and a control. It is a real defect: a permission failure was reported as a claim.

The defect

try_claim ended its open with .ok()?, so every open failure collapsed into None — and None means "held by another" at every call site. On fourpi.local (the vehicle host) the lockdir is pi:pi drwxrwxr-x and the standard account r is not in group pi. An exclusive flock(2) needs the file writable, so the open failed EACCES and every device read busy, permanently. --self-test failed 3 of 5 in a pattern that reads as "locks are never released", and DEVICE BUSY named a holder pid that was not running.

It failed closed, which is the right direction. But a safety tool rendering absence as data is the exact failure this repo keeps finding, and this repo's own rule is that "could not run" is not "answered no". It sent the reporter hunting a phantom holder.

Structural cause: Option could not express three outcomes, and scan_status carried a bool. There was nowhere for the third state to go — which is why it was reported as the second.

Half one — the third state exists

• Outcome is Got / Held / Undetermined(why); State is Free / Claimed / Unknown(why). Each carries the cause.
• claim_all bails immediately on Undetermined instead of spinning until --wait expires and then reporting BUSY.
• New exit code 4 (EXIT_UNDETERMINED), distinct from 3. A caller retrying on 3 would spin forever on an EACCES; one treating 3 as "another agent is working" blames a phantom.
• --status prints UNKNOWN — <cause> and emits "state":"unknown" with a why, instead of CLAIMED with an empty holder as the only hint.
• --self-test checks writability first and refuses with PRECONDITION FAIL / CANNOT RUN, explicitly exonerating the locking.
• try_claim stays as a wrapper that still collapses to None, so any not-yet-updated caller keeps failing closed.

Half two — it could never have worked cross-account

Nothing ever set a mode, so the lockdir and lock files inherited the creating user's umask: the first account to claim a device silently owned the interlock for everyone. Now the /tmp pattern — 1777 on the directory (sticky, so accounts cannot delete each other's locks) and 0666 on lock and holder files, because an exclusive flock needs write access.

Safe because the lock file carries no data: the lock lives on the fd, the file is a zero-byte rendezvous point, and anyone who can write it could already take the lock by running the tool. Widening is best-effort and never narrows, so running this cannot lock out an account already using the directory.

Verification

63 tests (30 lib + 33 behavioural), clippy -D warnings clean, coverage 92.4% against a 90 floor. Six new tests, including the one that makes the others mean something — a genuinely held device must still exit 3 with its holder named. Without it, exiting 4 on everything would pass the EACCES test; the two must refuse differently, which is the whole point.

Mutation test: reverting the fix to return Outcome::Held on open failure makes the EACCES test fail with DEVICE BUSY: 'dev-a' is claimed — {} — the reported symptom verbatim, empty holder and all. The test pins this bug, not something near it.

A test of mine that was the wrong model. The first EACCES test chmod'd the lockdir to 0500 and failed, because half two legitimately widens a directory the test user owns. The test was wrong, not the fix: the real scenario is a lock file another account created that we cannot chmod, and a read-only lock file models it exactly without needing a second user.

Verified on fourpi.local — and the first version of this PR was wrong about that

Retraction. This PR originally said the fix could not be verified on fourpi.local because "there is no Rust toolchain on any of the three Pis and this Mac has no aarch64-linux cross-linker." The second half was wrong — a claim about a toolchain that was never tested, only assumed. with-device has zero dependencies and no build.rs, so it cross-builds statically with no external linker at all:

rustup target add aarch64-unknown-linux-musl
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=rust-lld \
  cargo build --release --target aarch64-unknown-linux-musl

rust-lld ships inside the toolchain and the musl libc.a ships with rust-std. 487 KB static aarch64 ELF. An untested blocker is a hypothesis, not a finding — writing one into a safety artifact as a limitation is the same error class as a vacuous pass pointing the other way.

The reproduction, on the reported host as the reported account, before repairing anything (lockdir still pi:pi drwxrwxr-x):

	now	before
--status	all 6 UNKNOWN — Permission denied, json "state":"unknown" + why	CLAIMED, empty holder
a claim	exit 4, CANNOT DETERMINE, "Nothing was run. This is NOT 'the device is busy'"	exit 3 BUSY
--self-test	PRECONDITION FAIL + CANNOT RUN (this says nothing about the locking)	3 of 5 failures accusing the locking

Negative control — same binary, same host, same account, one variable changed (a writable lockdir): status exit 0, claim exit 0, wrapped command ran, modes came out drwxrwxrwt / -rw-rw-rw-. Half two's modes measured, not asserted.

After repair, as r: status all free exit 0; --self-test PASS 7/7 including contender-while-held, after-holder-CRASHED and the opposite-order deadlock pair; a real claim with --require-claim satisfied inside it; a second agent refused exit 3 with a live holder record {"pid":7628,"purpose":"holder"} — the property the defect destroyed, BUSY meaning busy again; lock file still pi:pi 0666, so pi is not locked out.

The execution half is fixed too, not just diagnosed. Installed at /usr/local/bin/with-device (0755) on all three hosts, so the exit-126 failure — r could not traverse /home/pi to even execute the old copy — cannot recur. gale.local and wohl.local both self-test PASS as r. The interlock is live on the whole bench for the standard account, which also unblocks AFD-113's F100 re-run on gale.

A second defect of the same class, found by that verification

On fourpi the fixed --status printed UNKNOWN for all six devices and exited 0. That is #280 again in the exit code, and unlike the original it fails open: a caller that branches on the status, or greps for CLAIMED and finds none, reads "the board is clear" out of "nothing could be read".

--status now exits 4 when any device is unreadable, with N of M device(s) could not be read — this listing is INCOMPLETE, not a clean board on stderr. Exit 0 now means the scan answered for every device, free or claimed. The help text's exit-code table said "0 … or success for --status" and is corrected.

Mutation test: changing that branch back to exit(0) fails the new test on the exit code while UNKNOWN still prints — the test pins the code, not the message. Its control (--status over a genuinely claimed device must still exit 0) is insensitive to the same mutation, which is what stops "exit 4 on anything" from passing both. Re-measured on fourpi after the change: broken lockdir → 4, writable lockdir → 0.

The pattern, stated because it will recur: the tri-state was added to the return value and the exit code was left behind. Fixing a could-not-run/answered-no conflation in one channel does not fix it in the others — and only running the fixed tool on the real host surfaced the one that was missed.

Totals

65 tests (30 lib + 35 behavioural), clippy -D warnings clean, fmt clean, coverage 92.56% against the 90 floor, CLI baseline checks mirrored locally. Version 0.5.0 — an exit code is part of the interface. rivet validate PASS (586 warnings).

Recorded as AFD-133.

🤖 Generated with Claude Code

https://claude.ai/code/session_017EKh2onUHpWSUiAEqWxfy2