fix(flows): let a nested run's verdict reach the run that contains it

[filip131311]

Fixes #606.

The bug

A flow step that runs another orchestrator reported pass whatever the nested run did. case "tool" treats any non-throwing result as a pass, and both flow-execute and run-sequence report failure in their result rather than by throwing.

Reproduced live — the same flow, run two ways:

run DIRECTLY                            ->  ok=False  passed=0  failed=1
run NESTED via raw `tool: flow-execute`  ->  OUTER ok=True  passed=1  failed=0
                                             step status = pass
                                             sub-report right there: ok=False failed=1

The failing verdict was sitting inside the very object being reported as a pass. A second shape lost the verdict entirely: a sub-flow whose executionPrerequisite was never acknowledged returns a notice, runs zero steps, and also reported a green pass.

The fix

Two shapes, mapped to statuses the runner already has:

nested result	status	why
ok: false	fail	the composed flow ran and its assertions failed — what an inline run: composition already produces
notice, zero steps	error	never runnable as written; the class the runner already uses for an unreadable fragment or a cyclic reference
aborted: true	skip	matches the runner's own rule that a cancelled step is a skip, never a failure

Both fail and error hard-stop — in this runner every fail and error does (state.stopped), and there is no continue-on-failure concept: a per-step optional: is rejected at parse time because when: already expresses it.

run-sequence had the same hole

Found while reviewing the plan. run-sequence has no verdict field at all — every failure path (disallowed tool, unsupported operation, unmet await-ui-element, a tool that threw) pushes an error entry, breaks, and returns normally. So a flow step whose sequence stopped at step 1 of 8 also reported a pass. Fixed here rather than left as a known identical bug on the same line.

Why not a blanket ok === false rule

There is no ok contract in this codebase to generalise. The only other soft-verdict tool spells it success (await-ui-element), run-sequence spells it neither way, and case "tool" dispatches tools whose results are typed unknown or Record<string, unknown> — several carrying app-derived payloads. A blanket rule would silently bind all of those, and every tool added later, to "a key called ok decides my flow's verdict". isUnmetUiWaitResult set the precedent for naming the tool instead. There is a test pinning this, so a future blanket refactor trips.

Verified exhaustively: exactly one registered tool returns a top-level ok in its result — flow-execute. In particular settings-permissions does not; its {ok: false} is a private per-pm-invocation type that either throws (already an error) or returns applied/skipped (a legitimate pass).

Verified live

raw-b-fail   direct  -> ok=False failed=1
             nested  -> OUTER ok=False failed=1, step fail
                        reason: flow "b-fail" failed: 0 passed, 1 failed, 0 errored (await: …)
                        sub-report attached
raw-b-prereq nested  -> OUTER ok=False errored=1, step error
                        reason: flow "b-prereq" did not run — its execution prerequisite was not
                        acknowledged: Settings must be open. Add prerequisiteAcknowledged: true to
                        the step's args, or compose with run: instead.

The direct and nested verdicts now agree, which is the exact discrepancy in the issue.

11 new tests in a new file; the 5 behavioural ones each confirmed to fail before and pass after. Full suite 3097 passing; lint, prettier, typecheck:tests and the tool-description gate clean.

Reporting shape

One failing step carrying a summarising reason plus the whole sub-report in result — the pass path already attached result, so this is the same shape with a non-pass status. The nested steps are deliberately not spliced into the outer steps[]: run: can expand inline only because it shares one ExecState (one index sequence, one depth base, one device, one baseline dir), whereas a raw tool: flow-execute is a separate runner invocation. Splicing would mean renumbering indices and re-homing artifacts — a wire-format change for a bug fix. Nothing is lost: MCP renders result for any step that has one, and the CLI (which renders only reason) gets the sub-flow's own first failure inside the reason string.

No new StepReport fields, no wire-format change; older clients render the new line unchanged.

Merge ordering and conflicts

• Merge fix(flows): stop a recorded sub-flow pinning the device it was recorded on #696 (flow replay: a recorded flow-execute step pins the record-time device — device is not a DEVICE_BIND_KEY #607) first. Before it, a nested flow-execute could run against a stale baked-in device and legitimately report ok: false; with this landed that becomes a parent failure and would read like a regression caused by this PR. No code-level conflict — fix(flows): stop a recorded sub-flow pinning the device it was recorded on #696 touches flow-device.ts and three other test files.
• feat(flow): CI-friendly failure diagnostics for argent flow #578 rewrites this exact block (case "tool", adding an evidence code to each return) and adds StepReport.failure/durationMs. Whichever lands second should give the new branches an evidence code — likely nested-flow-failed / nested-flow-prerequisite-unacknowledged / nested-flow-aborted — so its CI diagnostics classify the composition case. fix(flow): let a flow launch an app that can never be instrumented #677 also edits execLeafStep and adds StepReport.warning.

Behaviour change worth knowing

Previously-green flows containing a nested composition that was silently failing will now go red. That is the fix, but it surfaces pre-existing breakage on upgrade. The likeliest one is a recorded raw step missing prerequisiteAcknowledged, which becomes a hard error instead of a silent no-op — the reason names both remedies.

Follow-up, deliberately not bundled

Raw tool: flow-execute nesting has no cycle or depth guard: MAX_RUN_DEPTH and the run-stack cycle check cover only run:, so a flow whose raw step names itself recurses through fresh runner invocations. Independent of this issue; filing separately.

---

Stacked on #649 (filip/flow-deviceless-and-counts). Both edit the import block of packages/tool-server/src/tools/flows/flow-run.ts — #649 widens the ./flow-device import for its device-optional run, this one adds ./flow-nested-outcome. Rebased on #649, so review only the top commit. GitHub retargets it to main when #649 merges.