feat(attended): let an operator reject a halt and end the run

[abrichr]

Adds reject — an explicit "Stop, this is wrong" that terminates the run — to the attended-decision vocabulary. Second of four repos; depends on openadapt-types 0.6.3 (merged, published, verified on PyPI).

Why

Today's actions are continue / skip / teach / escalate. When the engine is correct to halt — the record genuinely says Ineligible, the member genuinely is not eligible — the operator's only one-tap options are to assert they fixed something or to hand it to a colleague. There is no way to say "you were right, stop."

• Disagreement has no channel, so the answer distribution can never tell you how often your halts are correct — data you need before tuning halt rates.
• Its visible presence communicates that disagreement is an expected outcome.
• It removes the situation where the only one-tap resolution is the agreeable one, which is the shape that produces rubber-stamping.

escalate is not relabelled to carry both meanings: escalate parks the run pending a colleague, reject terminates it. Collapsing them destroys the signal.

The terminal state, and why

Two durable artifacts, and what the second one does not do is the point.

The pause is rewritten with status="rejected" rather than cleared. Clearing it would make the run look like one that was never paused, and the reason it stopped is exactly what an auditor needs. Keeping it also makes the refusal enforceable: enforce_resume_authorization raises a new RunRejected — checked before expiry, because an operator told "the pause expired, re-approve it" would reasonably try to. No approval overrides it.

The run report gets canceled=True and a re-derived transaction_outcome. It does not force CANCELED. It states the human intent and lets classify_transaction_outcome decide what the evidence supports:

Rejection over…	transaction_outcome
a halt whose consequential steps are positively proven effect-free	CANCELED
a run that may already have written	RECONCILIATION_REQUIRED

An operator tapping "stop" must never be able to convert an unreconciled write into a clean bill of health, and the absence-proof gate that prevents it is the same one every other absence-asserting outcome already passes through. No gate was weakened; canceled had no writer before this change, so nothing else is affected.

REJECTED_POLICY was considered and rejected: it means authorization/identity/qualification/environment refused execution, is derived from gate pseudo-steps, and conflating a machine policy gate with an operator's judgement would lose exactly the distinction this action exists to record.

execution_outcome is deliberately untouched. The run really did HALTED; transaction_outcome refines what is known about the business effect without rewriting the coarse lifecycle — the contract openadapt_flow/transaction.py documents.

Should reject be available on every halt?

Yes, except one — and the exception is not the halt category.

Gating on category was considered and is wrong here. Rejecting asserts something about this run — that it must not proceed — which an operator looking at the live application can conclude at a resolution halt as readily as at an effect halt. Worse, category gating would remove reject from exactly the halts where continue is offered (those with postconditions and a usable baseline) and leave it only where continue often is not. That inverts the reason it exists: the pressure toward the agreeable one-tap answer lives wherever the agreeable answer is one tap.

The one exception is a positively recorded uncertain delivery (pending.delivery_uncertainty). There the action may already have landed, the operator's task is reconciliation rather than termination, and escalate — which keeps the pause for someone who can reconcile — is the correct answer.

A trap worth recording: the gate must not read delivery_state == "unknown". That is _delivery_state's fail-closed default for most halts and means only that nothing proved non-delivery. An earlier revision of this branch keyed on it and withheld reject from nearly every pause — the whole feature, quietly disabled by a fail-closed default. Pinned by test.

What does the rejection assert?

That this run must not proceed. Not that the workflow is wrong — that claim changes future runs, and it belongs to teach, which carries the demonstration and requalification gate that authority requires. Reject changes nothing saved.

Does it require a reason?

A closed rejected_by_operator disposition, with exactly one member today, and no free text anywhere on the wire.

A reason taxonomy would make the distribution far more informative, and I deliberately did not invent one: there is no evidence yet for what its members should be — the reject rate is the data that would design them — and a wrong taxonomy is worse than none. Every extra required tap on the disagreement answer while continue stays one tap also re-creates the asymmetry the action exists to remove. The cause is an enum from the start precisely so adding members later is additive rather than a schema change, and so a free-text reason can never appear.

Behavioural verification

test_reject_terminates_the_run_and_the_run_report_says_so proves termination from report.json, not the UI: canceled: true, transaction_outcome: CANCELED, transaction_billable: false, execution_outcome still HALTED, and the pause retained as status="rejected". No live session is even provided, so nothing can be actuated on the way.

test_a_rejected_run_cannot_be_resumed_or_answered_again shuts both doors: a second attended answer (reject, escalate and continue) all 409, and an approved resume() raises RunRejected.

Mutation check — test_reject_admission_refuses_every_mutation_of_its_preconditions removes each precondition one at a time and asserts each refuses on its own: a disposition that does not belong to reject, no authenticated operator, a foreign capability digest, and a pause whose signed capability never carried reject. Each case also asserts the run was not ended.

test_reject_is_withheld_where_a_write_may_already_have_landed makes the delivery genuinely uncertain the production way — a continue whose executor never returns a terminal receipt — with no test backdoor, then asserts the phone route returns 409 naming the uncertainty and the correct next step.

Reverted during development, recorded so it is not re-attempted

Filtering reject out of the projected task once the journal shows an unresolved delivery. allowed_actions is inside the signed payload, so withdrawing an action mid-flight changes the task digest, and every request the phone already holds then fails as "the task changed" instead of with the specific refusal that tells the operator a write may have landed. It also made two existing tests fail for the right reason. execute_attended_action owns that refusal, exactly as it already does for continue and skip.

Local verification

tests/test_attended_actions.py + tests/test_mobile_attended_decision_e2e.py: 82 passed. ruff check openadapt_flow, ruff format --check openadapt_flow tests, and mypy (218 source files) all clean.

Downstream

openadapt-desktop (phone shell) and openadapt-cloud (dashboard) follow. Desktop's openadapt-flow== pin bumps to the release that carries this.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM

---

Added on review: the RECONCILIATION_REQUIRED row was asserted, not proven

The table above claims a rejection over a run that may already have written
stays RECONCILIATION_REQUIRED. That is the whole safety argument for
re-deriving the outcome instead of forcing CANCELED — and no test covered
it. Every existing reject test ran over a halt where nothing had actuated, so
a correct re-derivation and a hardcoded CANCELED were indistinguishable.

test_rejecting_a_run_that_already_wrote_stays_reconciliation_required drives
a real run whose first step is an irreversible write that actuates and is
never verified, and only then halts for a human. The replayer produces the
report; no fixture is hand-edited. Rejecting is still accepted — refusing
to let an operator stop a run because it already wrote would be the wrong
failure — and transaction_outcome is RECONCILIATION_REQUIRED,
transaction_billable false, execution_outcome still HALTED, and the pause
rejected.

Mutation check. Replacing classify_transaction_outcome(report) with a
literal TransactionOutcome.CANCELED in _terminate_rejected_run fails this
test and no other — which is simultaneously the proof that the test is
load-bearing and that the property was previously unpinned.

This is distinct from the withheld case: reject is withheld only where the
runtime positively recorded that this step's delivery is uncertain. Here the
earlier step's delivery is certain and its effect is what is unknown, so the
operator can still legitimately end the run — they just cannot make the run
claim an absence.

tests/test_attended_actions.py + tests/test_mobile_attended_decision_e2e.py:
84 passed.