feat(role): the operator lock becomes a record of who coordinates where (#285)

[localai-bot]

Closes #285. User-directed.

The repo-wide exclusive operator lock becomes a record of who coordinates
where. It never refuses.

"I dont want push force main, never. the operator have at max the way to merge
directly PRs and heavily dispatch sub-agents with separate worktrees
( == coordinator )" … "let's keep it as a record for who is working where"

Why the exclusivity was wrong

The lock's own rationale was "the shared case is the operator's primary checkout,
where one role is the correct answer anyway." That premise no longer holds: every
task takes its own worktree and lands by merge, so there is no shared checkout to
protect. An operator is a coordinator — its maximum powers are merging PRs and
dispatching sub-agents into worktrees. It never rewrites shared history, so a plain
git push refuses any non-fast-forward and git itself is the interlock.

The exclusivity cost real time: with a 2-hour TTL, a session killed mid-flight — as
one was, by a disk cleanup, leaving a dead pid and a frozen heartbeat — blocked all
coordination for up to two hours, with no remedy but hand-deleting a file in
.git/.

Design

<git-common-dir>/vllm-cpp-operators/<sha256(worktree)[:16]>.json, one file per
worktree. A writer only ever touches the path derived from its own worktree, so
concurrent claimants use disjoint paths and there is no read-modify-write of a
shared file anywhere — which a JSON array or an append log would have needed for
release and prune. Publish is temp + os.replace in the same directory.
O_CREAT|O_EXCL is gone; its only job was to fail the second claimant.

claim operator prunes stale peers, publishes its own record and exits 0 whoever
else is recorded. show prints other coordinators recorded: N with worktree,
session, host, pid and heartbeat age. release and downgrade remove only the
caller's record. Ownership still keys on the worktree. The 2-hour TTL is kept — it
was never the problem.

A pre-#285 vllm-cpp-operator.lock is still read as one record so a live
pre-change operator does not silently go UNDECLARED, and is healed away on its next
claim.

Policy

AGENTS.md:108 and :241 now state the rule that motivated all of this:
main is never force-pushed. No --force, no --force-with-lease, by anyone,
ever. A rejected push means fetch, re-merge, re-gate, push again. The operator is
defined as a coordinator, several may run concurrently, and boot step 2 says the
claim is never refused. .agents/workflow.md, .agents/NOW.md, docs/USAGE.md
follow; three dated design specs carry superseded notes rather than edits.

Three review rounds, findings 4 → 2 → 2 LOW + 1 nit

Round 1 found the live snapshot still asserting the lock, and that the atomic
publish was pinned by nothing — a mutation replacing os.replace with
byte-at-a-time in-place writes left all suites green.

Round 2 found the repair's own comment falsified by the function twelve lines
above it: prune_stale_records() unlinks any stale record, ours included, so a
re-claim on a stale-but-healthy record manufactured the orphaned-marker state
this change exists to remove — exit=3 role=UNDECLARED out of a state that
resolved fine.

Round 3 fixed that with the same scoping drop_our_record already had, and pinned
the publish NAME. The final reviewer designed four of its own mutations; MINE-4
proved the two test legs are complementary rather than redundant (the fresh leg
catches round 2's repair, the stale leg round 3's, neither carries the other), and
MINE-2 proved the new scoping did not silently disable peer pruning.

keep_canonical=True was verified safe rather than argued: with two real worktrees
and the owner's record backdated past the TTL, the aged record appears in no
peer list (show, probe --json, agent-start), and garbage collection survives
through two independent paths — a peer's claim still prunes it, and a downgrade
still removes it.

Gates, verified by the operator rather than taken on report

test_agent_role 59, test_agent_onboard 39, test_agent_start 20 =
118. scripts/agent-preflight.sh --quiet --no-require-role: all gates
green, including both committed-range gates. --no-require-role because a
session that never claims sees role-undeclared as its own state, not the tree's.

Rebase conflict in the intake table (#287 and #285 both first row) resolved by
union and independently checked: a pure one-line insertion, #287 byte-identical
to main, no duplicate or lost row.

Two known limitations, recorded not fixed

Both LOW, both judged by the final reviewer as not worth another round, and a
follow-up issue tracks them.

1. scripts/agent-role.py:107-108's TTL comment still says a stale record is
   "unlinked by the next claim", which is now false for our own record — it is
   replaced. The spec's copy of the same sentence was corrected; the source copy
   was missed.
2. The publish-NAME test watches Path.write_text and three unlink primitives, so
   an os.rename + open() publish escapes it — demonstrated, with a real
   concurrent show returning rc 3. The shipped publish is correct; this is
   coverage. As the reviewer put it, each round has fixed one publish-coverage
   residual and created the next escape; the robust pin is an outside observer, not
   a wider watcher list.

FOLLOWING_AGENTS_PROTOCOL