fix(custodian): close the vulture fail-open in the pre-push gate

[ProtocolWarden]

Read the consequence section before merging. This turns the pre-push gate red on 10 genuine findings. That is the intended effect — it was green by accident.

The gate was lying

The Custodian pre-push gate reported 0 findings, clean on this repo, while a Windows box running a newer Custodian reported hundreds. Windows was the correct side. The green gate was a false clean, and had been for as long as the pin has been in place.

Three things had to line up to hide it:

1. .custodian/config.yaml sets tools.vulture: true — the detector is meant to run.
2. pyproject.toml never declared vulture in the dev extra, so uv pip install -e .[dev] never installed it. The fleet venv has no vulture and none is on PATH.
3. The custodian pin d6ba8ab predates Custodian 261bbb5 — "fix(vulture): put paths before options, and stop reading a failed run as clean". On that pin the adapter built vulture <src> --min-confidence=N <tests>, which vulture's argparse rejects (exit 2, empty stdout), and the empty output was read as "no dead code".

So even had vulture been installed, the pinned adapter could not have produced a finding — the invocation itself was malformed and the failure was swallowed. The detector has never once run.

The fix

• Bump the pin to 7a780b7 (origin/main, contains 261bbb5)
• Declare vulture==2.16 alongside the existing ruff/ty pins

These must land together: after 261bbb5 a missing vulture fails loudly, so bumping the pin alone would red the gate on "vulture not found".

Threshold set explicitly to tools.vulture_min_confidence: 80. Custodian's adapter registry falls back to 60 while its own config loader documents 80 as the intended default — relying on whichever wins is how this stays surprising.

--min-confidence	findings
60	621 (essentially all UNUSED_METHOD/attribute heuristics)
80	32 (every one at 100% confidence)

What's whitelisted, and what deliberately isn't

Of the 32, 22 are names an external contract forces us to accept: the __exit__ protocol, pytest's pytest_sessionfinish hookspec, fixtures requested purely for a side effect, and lambda stubs that must mirror the callee they replace — plus two compat shims the source already documents as deliberate (max_rewrite_attempts carries # noqa: ARG002 — kept for signature compat; queue_threshold carries # kept for config compat, not used in logic).

Those go in a new .vulture_whitelist.py, which Custodian's adapter picks up automatically when present. It matches on bare name, not location, so it's kept minimal with a justification per entry.

The remaining 10 are real and are deliberately not whitelisted:

• observer/cli.py ×8 — --format, --skip-validation, --output, --filter-status, --signals-only, --input, --validate-after, --keep are declared as typer.Option(...) and never read in the body. layers and full in the same command are read, which is what makes these stand out rather than look like a vulture blind spot. User-visible: passing --format yaml today silently produces JSON.
• pr_review_watcher/main.py:2508,2543 — pending_checks threaded through two call sites and never used.

Consequence

Merging turns the gate red until those 10 are triaged. Whether each observer flag should be wired up or deleted is product work and is not guessed at here — tracked in .console/backlog.md under "Up Next".

If you'd rather not take a red gate right now, hold this PR and I'll fix the 10 first; the fail-open has been in place a long time and a few more days won't change anything.

Separate finding, not fixable from this repo

5ef3f0f fix(adapters): make find_tool's venv-first preference work on Windows exists only in the local Custodian checkout (branch claude/reconcile-june-2026-08-03, upstream gone). origin/main is at 7a780b7, so that fix can't be pinned. Until it's pushed, a Windows Custodian run resolves linters off PATH rather than a venv — that produced 1222 phantom ruff findings earlier today (ruff 0.16's widened default rule set vs OC's pinned 0.15.13) until the local checkout picked the commit up mid-session. Also tracked in the backlog.

Verification

vulture src tests --min-confidence=80                          ->  32 findings
vulture src tests .vulture_whitelist.py --min-confidence=80     ->  10 findings

The 10 are exactly the genuine set listed above. Every whitelisted name was inspected at its source location and classified before being added.

🤖 Generated with Claude Code