tools/test-run.sh's per-worktree lock has no cooperative entry point, so format-sweep.sh reverse-engineers its internals (fd flock, owner files) and will drift with them

[lukstafi]

What the work ran into

ocannl-staging#385 added tools/format-sweep.sh, which must never rewrite sources under a live dune run. The only mutual-exclusion primitive available was test-run.sh's per-worktree lock, and participating in it from outside took four review rounds of successively deeper coupling to test-run's INTERNALS:

• probing the flock the way its private lock_held does (round 3);
• holding the lock across rewrites via the exec-then-flock(STDIN) fd-inheritance pattern copied from take_lock (round 7);
• clearing .test-run.lock.owner/.launcher under the held flock, because otherwise test-run's own 'stop' attributes the held lock to a finished run and TERMs its recorded process group — which the sweep shares (round 11);
• making the blocking wait interruptible and bounding it just above test-run's cap (round 12).

Every one of these re-implements or pokes an implementation detail that test-run.sh is free to change; nothing fails at that point except the sweep, at 6am, unattended.

Why it is worth fixing

The lock protocol is now load-bearing for two tools with only convention keeping them compatible. Any third tool that must not race dune (a future benchmark runner, a promotion helper) faces the same reverse-engineering.

What a fix would touch

tools/test-run.sh: expose a small cooperative surface — e.g. 'test-run.sh with-lock [--wait BOUND] <cmd...>' that takes the worktree lock with ownership metadata published correctly, runs the command, and releases; plus a documented 'lock-status' probe. tools/format-sweep.sh then shrinks by the whole hold_test_run_lock/owner-clearing apparatus, and the coupling becomes an interface instead of shared folklore.

[lukstafi]

Second sighting, same shape, different consumer: lukstafi#505 (stop-wording legs for tools/test-test-run.sh).

To test stop's behaviour, the harness now reverse-engineers three of test-run.sh's internals:

• group_alive — sed-extracted from the working-tree script and sourced (this one predates the PR);
• ps_token — same, newly, because the fixture has to forge a run directory's leader token in the exact spelling the script recomputes, or group_verified refuses it and every leg falls through to "nothing left to signal" — failing nothing while testing nothing;
• wt_key= — the line is extracted and eval'd with the cwd the script gives itself (its own repo root, not the caller's), because there is no way to ask test-run.sh which run directory last resolves to for a given worktree.

The mitigation is the same one the sweep reached for: each extraction is asserted structurally before use (header prefix, closing brace, minimum body length; the wt_key derivation is checked to produce a non-empty key, and a wrong key was confirmed to fail all four legs loudly with no runs recorded for this worktree rather than passing vacuously). That converts silent drift into a red leg — but only for the one harness that thought to do it, and only when someone runs it, which per gh-ocannl-795 is no machine in the loop.

Two of the three would be closed by a read-only cooperative entry point, which is a much smaller ask than the lock protocol this issue is really about: something like tools/test-run.sh path [RUN|last] printing the resolved run directory (the wt_key extraction goes away), and any way to ask a liveness question about a recorded run without sourcing the predicate (the group_alive/ps_token extractions go away for consumers that only need the answer — a harness deliberately testing the predicate would still extract it, and should).

Worth noting for prioritisation: this is the third tool coupled to test-run.sh's internals (format-sweep.sh, and now both hand-run harnesses), and the coupling arrived here through testing the script rather than cooperating with it — which is the direction that tends to be discovered last.

[lukstafi]

Another cost of the lock's file-level design, for whichever cooperative entry point this lands — this one is paid by every session, not only by a second tool participating in the lock.

take_lock writes .test-run.lock, .test-run.lock.owner and .test-run.lock.launcher at the worktree root, and they persist after the run. They are gitignored, so nothing complains — until the worktree is torn down: post-merge-cleanup.sh refuses a session worktree carrying ignored local data (deliberately, since ignored files can be the user's), so after landing staging#655 the merge was followed by hand-deleting three lock files, one judgement per file, at a worktree root that also holds a .claude/ which must never be deleted. Any session that ran a single suite through the harness ends this way.

Two things the entry point could settle at the same time: whether the sidecars have to live in the tree at all ($RUNS is already a per-worktree-keyed directory outside it — though stop's cross-worktree census reads $w/.test-run.lock.owner by path today, so moving them is an interface change, which is exactly what this issue is about), and whether releasing the lock should remove the two owner/launcher files it wrote, leaving only the flock target behind.

Grounded in staging#655; brainstorm at lukstafi#655 (comment)

[lukstafi]

The one consumer this issue was written for is gone: lukstafi#669 (merged as 70ca58b) retired tools/format-sweep.sh in favour of a per-PR @fmt CI gate (gh-ocannl-938), and with it the whole hold_test_run_lock / owner-clearing apparatus described above. Nothing outside tools/test-run.sh (and its own harness tools/test-test-run.sh) touches .test-run.lock now.

The "third tool that must not race dune" case is hypothetical for now, so this can close as consumer-less; the interface sketched above (with-lock, lock-status) is still the right shape if such a tool appears.