fix(portal): teach the phone the receipt shape and say what actually broke

[abrichr]

The founder paired a phone to a real halted run and could not tell what to do. The decision view asked "Is the live application ready for OpenAdapt to verify and continue?", offered I fixed it, verify and continue / Teach the correction / Needs more help, and said neither what broke nor what any of the three answers would do. The engine knew: that pause carried category: resolution and "could not resolve target for step_000 (click 'Open'): all resolution rungs failed".

BLOCKING: the receipt shape

engine/portal/shell/app.js read body.status / body.message. openadapt-flow PR #290 replaces that reply with the closed HumanDecisionReceiptV1, which carries state / reason_code and deliberately no message. Every terminal outcome therefore fell through to the else branch and rendered as "That decision was refused" — a real halted was observed doing exactly that.

Every (state, reason_code) pair Flow can emit now maps to its own operator copy in RECEIPT_COPY. A pair this build does not recognise is reported as an unknown outcome, never as a refusal: showing a real terminal outcome as some other outcome is the whole failure this table exists to prevent. A runner still returning the older decision record is mapped through Flow's own _RECEIPT_STATE table so it renders identically, and the engine's free-text message is never rendered even when present.

openadapt-flow#290 is unblocked by this PR.

Say what broke, and what "fixed" means

Flow's local decision detail (presentation.halt) carries closed values only: the typed halt category, the step's ordinal, its action kind, the target's role, and the target's label only when the engine proved that label is static control chrome rather than record content. The shell composes the sentence, because the wire carries no prose — that is what keeps a typed value off it:

Step 1 of 6 could not start: OpenAdapt could not find the button labelled “Open” on the screen, so it did not click anything.

A withheld label degrades to the role noun alone, so a TYPE step reads "could not find the text field", never the value. The view also lists which resolution rungs were tried and their verdicts (rungs with no recorded evidence are shown as never attempted, not as failures), and what a continue will re-check before anything happens.

Distinguish the three answers by consequence

Which is what could not be told apart. Each button carries its consequence, and the card states it in full:

• check and continue — this run only; the saved workflow is unchanged, so the same drift stops the next run
• teach the correction — changes future runs; nothing continues now
• needs more help — the run stays paused exactly where it is

The two cosmetic defects, causes established

1. The action bar stayed visible after a terminal receipt. .actions { display: grid } outranks the user-agent [hidden] { display: none } rule, so actionBar.hidden = true set an attribute that nothing acted on. Fixed with an explicit .actions[hidden] { display: none }.
2. The outcome text sat under the fixed bar. The page reserved a constant 200px, which three two-line buttons exceed. The bar's real height is now measured into --action-bar-height and released when it is hidden.

Also: a fetch that never returns is now status 0 — "the result is uncertain" — instead of an unhandled rejection leaving "Submitted, waiting…" on screen forever.

Verification

src/portalShell.test.ts drives the shipped app.js in a DOM rather than grepping it, because every existing source-text assertion passed while the surface a human reads showed every outcome as a refusal. 53 frontend tests, 737 Python tests, tsc && vite build, and ruff check pass locally; the loop was also driven end to end against a real halt over the live tunnel from a mobile device profile.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM