wip: close the last two PRHunt delay defects and update the procedure

Batch refresh for candidates whose freshness evidence aged out while another
candidate was still in review (#69). Validation of the verification
passthrough, so a Mailman option can no longer reach the test runner and read
as a candidate failure (#70).

Procedure raised to version 2: coordinator ownership, checkpoint pages,
the cumulative review budget, health states, narrow-first duplicate search and
the pre-finish refresh. The skill and command carry the ownership rule.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: wolfgang-aura

.agents/skills/prhunt/SKILL.md

@@ -8,6 +8,11 @@ Read `mailman/procedure.md` from the repository root, or run
 model. Follow it through `hunt finish`; do not stop after the agents finish.
 
 Read existing hunt state with `python -m mailman hunt list` before starting.
+One hunt has one coordinator. If `hunt status` shows a live lease you do not
+hold, another task owns it: take a separate hunt, or take that one over with
+`hunt lease --takeover --reason`. Never sit in a loop polling someone else's
+hunt. Show the checkpoint page as soon as any candidate is ready rather than
+holding finished work until the quota is met.
 If model choices are missing, ask which primary and reviewer adapter/model IDs
 the user wants. Do not assume defaults. N counts complete PR candidates, not
 attempts. Repair routine failures or replace candidates without asking the user.

mailman/cli.py

@@ -122,7 +122,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "action",
         choices=(
             "init", "add", "drop", "restore", "status", "finish", "list",
-            "escalate", "refresh-procedure", "lease", "release",
+            "escalate", "refresh-procedure", "lease", "release", "refresh",
         ),
     )
     hunt.add_argument("hunt_id", nargs="?")
@@ -714,7 +714,7 @@ def _hunt(arguments: argparse.Namespace) -> int:
         hunt.release_lease(root, record, owner=arguments.owner)
         print(json.dumps({"hunt_id": record["hunt_id"], "lease": None}, indent=2))
         return 0
-    if arguments.action in ("add", "drop", "restore", "escalate", "finish"):
+    if arguments.action in ("add", "drop", "restore", "escalate", "finish", "refresh"):
         hunt.require_lease(record, arguments.owner)
     if arguments.action == "add":
         if not arguments.run_id:
@@ -742,7 +742,12 @@ def _hunt(arguments: argparse.Namespace) -> int:
                                       "attempted": arguments.attempted, "why_user": arguments.why_user,
                                       "user_action": arguments.user_action})
         hunt.save(hunt.hunt_path(root, record["hunt_id"]), record)
-    result = hunt.finish(root, record) if arguments.action == "finish" else hunt.status(root, record)
+    if arguments.action == "refresh":
+        result = hunt.refresh(root, record)
+    elif arguments.action == "finish":
+        result = hunt.finish(root, record)
+    else:
+        result = hunt.status(root, record)
     print(json.dumps(result, indent=2))
     return 1 if arguments.action == "finish" and not result["complete"] else 0
 
@@ -1966,6 +1971,36 @@ def _tail(text: str, lines: int = 20) -> str:
     return "\n".join(text.strip().splitlines()[-lines:])
 
 
+#: Options only Mailman defines. One of these after `--` is always a mistake:
+#: it reaches the test runner, which fails collection, and the failure reads
+#: like a broken candidate. https://github.com/wolfgang-aura/Mailman/issues/70
+_MAILMAN_ONLY_OPTIONS = frozenset({
+    "--data-root", "--max-revisions", "--max-review-cycles", "--reasoning-effort",
+    "--max-turns", "--agent-timeout", "--verification-timeout", "--owner",
+    "--acknowledge-prior-attempts", "--acknowledge-claims", "--verification",
+})
+
+
+def check_verification_command(command: list[str]) -> None:
+    """Refuse a passthrough that cannot be what the operator meant."""
+    if not command:
+        return
+    if command[0].startswith("-"):
+        raise ValueError(
+            f"the verification command starts with {command[0]!r}. Everything "
+            "after `--` is run as a program, so the first token must be an "
+            "executable, not an option."
+        )
+    for token in command:
+        name = token.split("=", 1)[0]
+        if name in _MAILMAN_ONLY_OPTIONS:
+            raise ValueError(
+                f"{name} is a Mailman option, but it appears after `--`, so the "
+                "test runner would receive it and fail collection. Move it "
+                "before the `--` separator."
+            )
+
+
 def main(arguments: list[str] | None = None) -> int:
     raw_arguments = list(arguments if arguments is not None else sys.argv[1:])
     verification_command: list[str] | None = None
@@ -1980,6 +2015,8 @@ def main(arguments: list[str] | None = None) -> int:
     if parsed.subcommand in ("verify", "orchestrate", "resume-review", "reproduce", "build-prompts"):
         parsed.command = verification_command or []
     try:
+        if parsed.subcommand in ("verify", "orchestrate", "resume-review", "reproduce", "build-prompts"):
+            check_verification_command(parsed.command)
         if parsed.subcommand == "doctor":
             return _doctor()
         if parsed.subcommand == "procedure":

mailman/hunt.py

@@ -338,6 +338,60 @@ def write_checkpoint(root: Path, record: dict, result: dict) -> Path | None:
     return destination
 
 
+def refresh(root: Path, record: dict) -> dict:
+    """Re-run the aging evidence for every ready candidate, as one batch.
+
+    Duplicate searches and claim reads expire in an hour. Two finished
+    candidates were withheld while a third was still in review, aged out one at
+    a time, and the visible ready count fell from two to zero. Refreshing them
+    together is what the coordinator was doing by hand.
+
+    This does not weaken the filing gate. `hunt finish` still re-checks every
+    candidate and still refuses stale evidence; this only makes getting them
+    fresh together a single command.
+    See https://github.com/wolfgang-aura/Mailman/issues/69.
+    """
+    from mailman.claims import read_claims
+    from mailman.submission import record_duplicate_search
+
+    before = status(root, record)
+    refreshed: list[dict] = []
+    for row in before["runs"]:
+        if row.get("dropped"):
+            continue
+        run, directory = load_run(row["run_id"], root)
+        # A candidate that is ready needs no refresh, and one that never
+        # reached a handoff has an earlier problem than aging. The runs this is
+        # for are the finished ones whose evidence expired while another
+        # candidate was still in review: complete packages reading as failures.
+        if row["ready"] or load_handoff(directory) is None:
+            continue
+        outcome = {"run_id": run.run_id}
+        search = read_object(directory / "duplicate-search.json")
+        if not search.get("query"):
+            outcome["duplicate_search"] = "no recorded query; run duplicate-search first"
+        else:
+            fresh = record_duplicate_search(
+                directory,
+                repository=run.repository,
+                query=search["query"],
+                issue_number=search.get("issue_number"),
+                symbols=search.get("symbols") or (),
+            )
+            outcome["duplicate_search"] = {
+                "success": fresh["success"], "complete": fresh["complete"],
+                "matches": fresh.get("match_count", 0),
+                "decided_by": fresh.get("decided_by"),
+            }
+        claims = read_claims(directory)
+        outcome["claims"] = {"success": claims.get("success"),
+                             "assignees": claims.get("assignees")}
+        refreshed.append(outcome)
+    after = status(root, record)
+    return {**after, "refreshed": refreshed,
+            "ready_before_refresh": before["ready"]}
+
+
 def finish(root: Path, record: dict) -> dict:
     from mailman.review_packet import write_packet_page
     from mailman.review_page import write_run_page

mailman/procedure.md

@@ -1,4 +1,4 @@
-# PRHunt procedure, version 1
+# PRHunt procedure, version 2
 
 This is the procedure for every Mailman coordinator, regardless of model.
 Read it on `/PRHunt N`, `$prhunt N`, or a request to hunt for N pull requests.
@@ -16,20 +16,35 @@ Claude CLI adapters. Confirm each selected CLI is installed and authenticated
 with a harmless local fixture before spending a target run.
 
 Create the hunt with `mailman hunt init N --primary ADAPTER --primary-model ID
---reviewer ADAPTER --reviewer-model ID`. `mailman hunt status HUNT_ID` gives the
-next missing step and last-check timestamp. Update it after each run. Its
-records survive a new conversation. The coordinator performs the actions;
-the command does not spawn a background agent or discover targets itself.
+--reviewer ADAPTER --reviewer-model ID`. It prints a lease with an `owner`
+token. Keep that token: every action that changes the hunt takes `--owner
+TOKEN`. `mailman hunt status HUNT_ID` gives the next missing step and last-check
+timestamp. Update it after each run. Its records survive a new conversation.
+The coordinator performs the actions; the command does not spawn a background
+agent or discover targets itself.
+
+One hunt has one coordinator. If `hunt status` shows a live lease you do not
+hold, you are the second task on someone else's hunt. Do not poll it and do not
+work around it. Either take a separate hunt of your own, or, when the other
+coordinator is genuinely gone, take over with `mailman hunt lease HUNT_ID
+--owner YOUR_TOKEN --takeover --reason "..."`, which records what you took and
+why. Waiting on another coordinator is not progress; it costs the same model
+allowance and produces nothing.
+
+Renew the lease with `mailman hunt lease` during long stages. Release it with
+`mailman hunt release --owner TOKEN` when you stop.
 
 ## Find and screen
 
 1. Read the target's contributor instructions and AI policy. Run
    `mailman screen-target OWNER/REPO --refresh`. Reject a failed screen.
    Human-only authorship declarations, assignment requirements and bans on
    generated descriptions are reasons to pick another target for this flow.
-2. Search open and closed PRs by exact affected symbol, behaviour and issue
-   number, using more than one query where needed. Read overlapping patches
-   and maintainer responses. A broad empty search is not sufficient evidence.
+2. Search narrow first. Give `duplicate-search` the issue number and the
+   symbols the change touches with `--symbol`; the broad listing runs after.
+   A record whose `decided_by` is `narrow` already found a duplicate and the
+   candidate is finished. Read overlapping patches and maintainer responses. A
+   broad empty search is not sufficient evidence, and neither is a narrow one.
 3. Initialize a run at an exact current upstream commit with the hunt's model
    configuration. Add it with `mailman hunt add HUNT_ID RUN_ID`.
 4. Run `fetch-issue`, `duplicate-search`, `prior-art`, `target-intel` and
@@ -48,9 +63,11 @@ the command does not spawn a background agent or discover targets itself.
    missing dependencies from the reported defect. Run `reproduce`, then
    `check-target`. A bug that no longer reproduces means replace the candidate.
 8. Use `build-prompts RUN_ID -- EXECUTABLE ARG ...` to record verification argv.
-   `orchestrate RUN_ID` reads that same command. Do not supply custom prompts
-   or call `run-agent` to bypass this sequence. Both model roles must use the
-   same recorded procedure and the independent verification gate.
+   Everything after `--` is run as a program, so it starts with an executable
+   and carries no Mailman option; the CLI refuses the common mistakes but not
+   all of them. `orchestrate RUN_ID` reads that same command. Do not supply
+   custom prompts or call `run-agent` to bypass this sequence. Both model roles
+   must use the same recorded procedure and the independent verification gate.
 
 ## Repair without escalating routine work
 
@@ -61,6 +78,16 @@ the command does not spawn a background agent or discover targets itself.
     before another edit. Never retry an identical command indefinitely.
     For an unusable review, preserve the patch, repair the environment, then
     run `resume-review`. Do not restart a dirty primary workspace.
+    Reviewer passes are budgeted per run, not per command: `--max-review-cycles`
+    counts across every `orchestrate` and `resume-review`. When a run blocks on
+    a spent budget, replace the candidate or raise the budget deliberately and
+    say why. Do not resume repeatedly to buy more passes.
+    A run whose `hunt status` carries a `health` state stopped for a reason
+    outside the candidate. `USAGE_LIMIT` means the account, not the code, and
+    the record holds the stage and the exact resume command; retrying the
+    candidate spends the same allowance again. `INFRASTRUCTURE` means the host,
+    such as an unwritable temporary directory. Neither is a candidate defect and
+    neither is a reason to drop a target.
 11. Drop duplicate, assigned, prohibited, unreproducible or unsuitable targets.
     Record why and continue searching until N candidates pass. A dropped run
     costs no user decision. A failed candidate may be replaced after bounded
@@ -85,11 +112,20 @@ the command does not spawn a background agent or discover targets itself.
     exact local branch and final body. Run `handoff-check`. Keep all filings
     and upstream writes pending. For a self-sourced defect, prepare any required
     issue text alongside the PR and ask for approval of the ordered filings.
-15. `mailman hunt finish HUNT_ID` must exit 0. It counts only SEND decisions
+15. Refresh the aging evidence for every ready candidate together with
+    `mailman hunt refresh HUNT_ID --owner TOKEN` immediately before finishing.
+    Duplicate searches and claim reads expire in an hour, and refreshing them
+    one at a time is how a hunt with two ready candidates reported zero.
+16. `mailman hunt finish HUNT_ID --owner TOKEN` must exit 0. It counts only SEND decisions
     with passing filing checks and generates the existing packet format.
     Inspect that generated packet visually. Never hand-write review HTML.
     Present the packet and ask for approval of the exact filings once.
 
+Do not hold finished work back until the quota is met. `hunt status` writes a
+checkpoint page as soon as any candidate is ready. Show it. A candidate that is
+ready and invisible is indistinguishable to the user from no candidate at all,
+and that is what fifteen hours of silence looked like.
+
 ## What reaches the user
 
 Only escalate unavailable user-controlled authentication, an explicit budget

tests/test_hunt.py

@@ -19,6 +19,7 @@
     finish,
     load_hunt,
     next_action,
+    refresh,
     restore_run,
     status,
 )
@@ -122,6 +123,77 @@ def test_no_checkpoint_is_written_when_nothing_is_ready(self):
         add_run(self.data_root, hunt, run.run_id)
         self.assertNotIn("checkpoint", status(self.data_root, hunt))
 
+    def test_refresh_renews_every_ready_candidate_in_one_batch(self):
+        """https://github.com/wolfgang-aura/Mailman/issues/69
+
+        Aging evidence is what turned two ready candidates into a reported
+        zero. `hunt refresh` renews them together; `hunt finish` still decides.
+        """
+        from datetime import timedelta
+
+        import mailman.hunt as hunt_module
+
+        hunt = self.new_hunt()
+        directory = self.ready_run()
+        add_run(self.data_root, hunt, directory.name)
+        self.assertEqual(status(self.data_root, hunt)["ready"], 1)
+
+        stale = (datetime.now(UTC) - timedelta(hours=3)).isoformat()
+        for name in ("duplicate-search.json", "claims.json"):
+            payload = json.loads((directory / name).read_text(encoding="utf-8"))
+            payload["searched_at" if "duplicate" in name else "collected_at"] = stale
+            if "duplicate" in name:
+                payload["query"] = "fixture defect"
+            (directory / name).write_text(json.dumps(payload), encoding="utf-8")
+        self.assertEqual(status(self.data_root, hunt)["ready"], 0)
+        self.assertFalse(finish(self.data_root, hunt)["complete"])
+
+        now = datetime.now(UTC).isoformat()
+        calls = []
+
+        def fake_duplicate_search(run_directory, *, repository, query, issue_number=None,
+                                  symbols=(), **_):
+            calls.append(("duplicate-search", query))
+            record = {"success": True, "complete": True, "searched_at": now,
+                      "repository": "example/project", "query": query, "matches": [],
+                      "match_count": 0, "decided_by": "broad", "symbols": list(symbols)}
+            (run_directory / "duplicate-search.json").write_text(
+                json.dumps(record), encoding="utf-8")
+            return record
+
+        def fake_read_claims(run_directory, **_):
+            calls.append(("claims", run_directory.name))
+            record = json.loads((run_directory / "claims.json").read_text(encoding="utf-8"))
+            record.update(collected_at=now, success=True)
+            (run_directory / "claims.json").write_text(json.dumps(record), encoding="utf-8")
+            return record
+
+        import mailman.claims
+        import mailman.submission
+        original_search = mailman.submission.record_duplicate_search
+        original_claims = mailman.claims.read_claims
+        mailman.submission.record_duplicate_search = fake_duplicate_search
+        mailman.claims.read_claims = fake_read_claims
+        try:
+            result = refresh(self.data_root, hunt)
+        finally:
+            mailman.submission.record_duplicate_search = original_search
+            mailman.claims.read_claims = original_claims
+
+        self.assertEqual(result["ready_before_refresh"], 0)
+        self.assertEqual(result["ready"], 1)
+        self.assertEqual(len(result["refreshed"]), 1)
+        self.assertEqual([kind for kind, _ in calls], ["duplicate-search", "claims"])
+        self.assertTrue(finish(self.data_root, hunt)["complete"])
+
+    def test_refresh_leaves_a_ready_candidate_alone(self):
+        hunt = self.new_hunt()
+        directory = self.ready_run()
+        add_run(self.data_root, hunt, directory.name)
+        result = refresh(self.data_root, hunt)
+        self.assertEqual(result["ready"], 1)
+        self.assertEqual(result["refreshed"], [])
+
     def test_a_second_coordinator_cannot_change_a_leased_hunt(self):
         """https://github.com/wolfgang-aura/Mailman/issues/63"""
         hunt = self.new_hunt()

tests/test_prevention.py

@@ -218,3 +218,45 @@ def test_a_search_with_nothing_narrow_to_go_on_is_unchanged(self):
         )
         self.assertEqual(record["decided_by"], "broad")
         self.assertNotIn("narrow", record["methods"]["pr"])
+
+
+class VerificationPassthroughTests(unittest.TestCase):
+    """https://github.com/wolfgang-aura/Mailman/issues/70"""
+
+    def test_a_mailman_option_after_the_separator_is_refused(self):
+        from mailman.cli import check_verification_command
+
+        for command in (
+            ["pytest", "-q", "--data-root", "runs"],
+            ["pytest", "--max-review-cycles=2"],
+            ["python", "-m", "pytest", "--reasoning-effort", "max"],
+        ):
+            with self.subTest(command=command):
+                with self.assertRaisesRegex(ValueError, "Mailman option"):
+                    check_verification_command(command)
+
+    def test_a_command_that_starts_with_an_option_is_refused(self):
+        from mailman.cli import check_verification_command
+
+        with self.assertRaisesRegex(ValueError, "must be an executable"):
+            check_verification_command(["-q", "tests"])
+
+    def test_a_real_verification_command_passes(self):
+        from mailman.cli import check_verification_command
+
+        check_verification_command(
+            ["python", "-m", "pytest", "tests/test_show.py", "-q", "-p", "no:cacheprovider"]
+        )
+        check_verification_command([])
+
+    def test_the_cli_reports_it_rather_than_running_the_runner(self):
+        from contextlib import redirect_stderr
+        from io import StringIO
+
+        from mailman.cli import main
+
+        stderr = StringIO()
+        with redirect_stderr(stderr):
+            code = main(["build-prompts", "RUN", "--", "pytest", "--data-root", "x"])
+        self.assertNotEqual(code, 0)
+        self.assertIn("Mailman option", stderr.getvalue())