agent tool description claims the write-contention refusal names `release`; it does not, and the liveness filter says it could not

[Hmbown]

Reported from a live session: a rerun into the same folder hit a write-scope contention refusal, and the remedy that actually cleared it (release) was not discoverable from the error — it had to be found by reading the agent tool description.

The confirmed mismatch

crates/tui/src/tools/subagent/mod.rs:9580 (the action enum description) says:

release clears write claims whose owner is no longer running — the remediation a write-scope contention refusal names; pass agent_id to clear one, omit it to sweep.

The refusal it refers to (crates/tui/src/tools/subagent/coord/ledger.rs:587) names four remedies, and release is not among them:

write-scope contention with {owner}: requested roots {..}, files {..}, contracts {..}
overlap its writable roots {..}, files {..}, contracts {..}.
Claim disjoint sibling write_roots (for example tmp/scan/worker-a and
tmp/scan/worker-b) or exact_files for each output. A read-only worker uses
write_authority=read_only without a write claim. Otherwise serialize the writers
or use worktree isolation; a nested path inside an existing writable root still
overlaps.

So the description asserts a property of an error message that the error message does not have. That is the minimum defect, and it is not in dispute.

The part that needs a repro before anyone writes a fix

The obvious fix — "have the refusal name release when the blocking owner is inactive" — may be unreachable, because the refusal already cannot fire for an inactive owner. register_claim filters the overlap search on liveness (ledger.rs:563-571):

.find(|existing| {
    !existing.isolated_worktree
        && existing.claim.owner != claim.owner
        && owner_is_active(&existing.claim.owner)     // <-- here
        && existing.claim.overlaps(&claim)
})

If owner_is_active is false, the stale claim is skipped and no refusal is raised at all. release_stale_claims (ledger.rs:625) clears exactly the complement — owners for which that predicate is false. On this reading the two sets are disjoint and release can never be the remedy for a contention refusal, which would make the description wrong in a stronger sense than "incomplete".

But the reporter observed the refusal and observed release clearing it. Both callers pass the same predicate, built by active_coordination_owners (mod.rs:5127):

self.agents.keys().chain(self.worker_records.keys())
    .filter(|id| self.is_live_coordination_owner(id))

That set is built from in-process maps. In a fresh session those maps do not contain owners persisted by a previous process, so a stale owner should read as inactive — which again predicts no refusal.

So one of these is true, and a repro should say which:

1. The refusal the reporter hit was raised somewhere other than ledger.rs:587 (there may be a second contention path — validate_write_scope, mod.rs:4214, is a candidate).
2. The stale owner was present in agents/worker_records and is_live_coordination_owner returned true for a process that no longer exists — a liveness bug, and the real defect.
3. The owner id is reconstructed identically on a rerun, so the blocking claim belonged to a live owner, and release clearing it was incidental rather than causal.

Acceptance

• A repro that names which of the three above actually happened, with the refusal text captured verbatim.
• Then either: the refusal names the sweep in the case where it is genuinely the remedy, or mod.rs:9580 stops asserting that it does.
• If (2) turns out to be the cause, that liveness bug is the headline and this text issue is a symptom.

Do not "fix" this by adding release to the refusal text unconditionally — that would point users at a sweep that, on the current liveness filter, cannot clear the claim that just blocked them.

Related: #5562 / SHA-6272 (stale write claims locking sub-agents out), release_stale_write_claims at mod.rs:4200.

[Hmbown]

One repro data point, tonight (live session): a worker whose claim conflicts with a dead owner's standing claim was admitted without refusal — spawn succeeded, no contention error. The dead owner (budget-exhausted child, held codewhale-ops/ledger) read as non-live through register_claim's owner_is_active filter exactly as designed. So in this instance the refusal set and the release set were disjoint, as the issue's static reading predicts.

Verbatim capture of the live-owner refusal from the same session (matches ledger.rs:587 exactly, conflicting owner was running at the time):

Error: Failed to spawn sub-agent: write-scope contention with agent_601841f0: requested roots ["codewhale-ops/ledger"], files [], contracts [] overlap its writable roots ["codewhale-ops/ledger"], files [], contracts []. Claim disjoint sibling write_roots (for example tmp/scan/worker-a and tmp/scan/worker-b) or exact_files for each output. A read-only worker uses write_authority=read_only without a write claim. Otherwise serialize the writers or use worktree isolation; a nested path inside an existing writable root still overlaps.

This leaves the reporter's observed refusal+release-cleared-it co-occurrence unexplained by hypotheses 1 and 2 in tonight's instance — leaning toward (3) incidental, or a liveness race in the reporter's session (owner present in agents/worker_records but process already gone). Worth one more look at is_live_coordination_owner for a status-blind presence check before closing this as text-only.

[Hmbown]

Landed in 3dcb41f5d2, on main.

The description claimed release was "the remediation a write-scope contention refusal names". It was not, and git log -S shows why: the sentence that did name it was removed in 5a1cef906c, whose own message says it was replaced to "explain actual write/write overlap remedies". The description kept pointing at text that no longer existed.

Pointing it back would have been worse. A contention refusal names the owner currently holding the claim, and release only clears claims whose owner is no longer running — release_stale_write_claims filters on active (mod.rs:4206), and coord.rs:1748 pins that a named release of a live claimant is a no-op that still succeeds. The repo had already decided this deliberately: tests.rs:12466 asserts the sibling peer-gate refusal states remediation "without telling a writer to remove a live peer".

So the remedy moved into the refusal, where it is paid only when the refusal fires rather than sitting in every session's KV-cache prefix: "serialize the writers (wait for that owner to settle, or cancel it)". Two doc comments that repeated the false cross-reference are corrected.

Tests: cargo nextest run -p codewhale-tui --lib -E 'test(write_scope_contention) or test(waiting_for_user_headless_worker) or test(contention)' — 8 run, 8 passed. No test added: the only assertion available would pin the absence of a prose substring in a model-facing description, which protects no behaviour and breaks on the next reword.