feat(roadmap): refine and intake keep a failure class and wait #4061

Problem

Refine records only the failures that the item caused (RefineFailure.item_caused, #1526). A timeout or a dropped stream says nothing about the item, so refine records nothing. It takes the same item again in every round while the cause lasts. Refine has no time mark.

Intake keeps what it decided in IntakeRecord (intake.py, waiting). A candidate whose placement raised is decided again after the fresh ones (IntakeRecord.after, run.py _run_intake_adapter). Each repeat costs a triage call and an embedding call. Intake keeps no class or count for the failure.

Expected

Use CLASS_BY_EXCEPTION, RETRY_AFTER and StepName. They come from two issues: #4056 and #4060. Add the StepName members that these rows use: investigate for refine and place for intake.

Refine.

• Add the keys refine.failed_at, refine.failed_step and refine.failed_class to RefineRecordKey.
• Write them in the existing failure marks (_failure_marks). Write them also for a failure that the item did not cause.
• The selection leaves the item out until failed_at + RETRY_AFTER[class].
• A success clears the three keys, as it clears refine.failure today.

Intake.

• Keep the failure in IntakeRecord, not in the item record. Add a field failed: dict[int, Failed] with the class, the count and the time of the last failure.
• A candidate with a recorded class waits for RETRY_AFTER[class]. So the next round makes no triage or embedding call for it.
• The count lives only in IntakeRecord.
• The record file stays readable when the new field is absent. The default is an empty dict.

The change adds no request. The refine marks ride on the existing marks write. Update the failure rows of docs/ROADMAP_WORKFLOW.md.

Acceptance criteria

• uv run pytest tests/roadmap/refine/test_roadmap_refine_failure_class.py - a timeout in refine records class, step and time. The next round skips the item until the time passes. A success clears the keys.
• uv run pytest tests/roadmap/intake/test_roadmap_intake_failure_class.py -k repeated_failure - the second round makes no triage call for a candidate with a recorded class. The count is in IntakeRecord only.
• uv run pytest tests/roadmap/intake/test_roadmap_intake_failure_class.py -k old_record - an IntakeRecord file from before this change loads and keeps its candidates.
• uv run pytest tests/roadmap/intake/test_roadmap_intake_failure_class.py -k no_item_mark - the item record gets no mark for an intake failure.

Every command above fails on the unchanged code. The pull request cites the fail-to-pass run (devops ci fail-to-pass --base <ref>).

Feasibility

I read these files at origin/main: refine.py (RefineFailure, _failure_marks, _record_failure), intake.py (IntakeRecord, Waiting, _Run, apply_intake) and run.py (_run_intake_adapter, read_intake_record). I did not run the code.

The existing behavior for a failure that the item did not cause is a deliberate design (#1526). This change keeps the rule that the item is not marked as at fault. It adds a wait only. The alternatives row keeps its own roadmap.alternatives.retry_days and is not part of this issue.

Existing tool considered

IntakeRecord, the refine marks and the tables of the two issues named above. No library is needed.

Cost

Build: about 70k tokens and 3.5 h. Keep: about 3k tokens per quarter. Fix: about 15k tokens and 1 h.

Related

Part of #3027. #3650. Depends on the issue #4060. Order: after that issue (both change failure.py, run.py and ROADMAP_WORKFLOW.md).