Agentic-mode multi-candidate ambiguity guard fails after burning attempts

Consolidated from issue #311 (Item 2).

Problem

agentic.py's _compose_directive sends a natural-language "Make me a picture of X" (singular for count=1) rather than a hard UI count control. Google's agentic assistant can ignore this and generate multiple candidates.
await_images' ambiguity guard (issue #281) refuses to guess and raises MediaAttributionError — but only after the generation already ran. This burns time and attempts with zero usable output.

Proposed Improvement

Enhance agentic mode's count enforcement, or modify await_images to download-and-let-caller-pick instead of hard-failing when multiple candidates are returned.

Corrected root cause + validated fix design (live-verified 2026-07-16)

Both proposed fixes in the issue body turn out to be non-viable on closer investigation — but a live check of the current Flow UI (thanks to a maintainer catch — the assumption below was wrong) surfaced the real mechanism and a validated fix.

What's wrong with the original proposals

"Enforce count harder via a UI control" — a prior static-code read concluded this control doesn't exist in Agent mode (configure_image_settings docstring says agentic settings are "resolved from natural language"; a 33-day-old memory documented Agent mode removing the whole settings panel, PR fix(transports): exit Agent composer mode before mode switch so the gen panel mounts #124/fix(transports): handle Flow's Agent chat-panel shape in _exit_agent_mode #138). This was stale. Flow's UI has since added a real settings surface — see below.
"Download-and-let-caller-pick" — still correctly ruled out: breaks the exact-count invariant in _build_generated_images (agentic.py:600-614) and needs new CLI selection UX. Out of scope for this fix.

The actual mechanism (live-verified against a real Flow project)

Agent mode's composer has a tune (Settings) icon that opens a full "Agent settings" panel — not a small popover like classic mode's crop_* menu. It has:

"Confirm before generating": Always / Never
"Image generation default": aspect-ratio tabs (16:9/4:3/1:1/3:4/9:16) + count tabs (1x/x2/x3/x4) + model dropdown
"Video generation default": same shape, 2 aspect options + count tabs + model dropdown
"Save" button

Critically, this is a sticky default, not a per-message setting. On the test project it was found stuck on x2 from some prior state. gflow-cli's automation never touches this panel, so this leftover default silently overrides the natural-language "a picture" (singular) phrasing — that's the actual cause of the multi-candidate ambiguity, not the AI "ignoring" phrasing.

Validated fix mechanics

Click tune (ligature-based selector, locale-invariant).
The image count control is reliably the first [role='tablist'] (DOM order) containing both 1x and x2 buttons — image section always renders before video section.
Click the button matching the requested count (1→1x .. 4→x4). Must use a real Playwright mouse click — a raw JS element.click() does not trigger this React app's selection handler (verified: aria-selected never flips with a synthetic click).
Click "Save" — no icon/data-attribute/aria-label available on this button and text is locale-dependent ("Salvar" in pt), so it needs a scoped selector: walk up from the arrow_back icon (present at the panel header) to the ancestor that also contains the count tablist, then take the last visible button within that scope. Verified this resolves to the same element as the Save button.
Save auto-closes the panel back to the composer (no extra back-arrow step needed) — verified the Slate composer textbox is visible immediately after.
Keep the existing natural-language phrasing (still needed to keep the agent's reasoning step engaged for project-brief instruction cards, per the 2026-07-08 finding already in _compose_directive's docstring) — the UI control becomes authoritative, phrasing stays as reinforcement.
Keep the existing MediaAttributionError fail-fast guard as a backstop for the rare case the agent still ignores both signals.

Scope stays count-only (no aspect/model automation via this panel) to match the issue as filed.

Implementation pending — this is a larger/riskier change than originally scoped (new locale-invariant selectors driving a previously-undocumented settings surface), so it'll go through subagent-driven development with task-level review before merge.

Merge pull request #325 from ffroliva/feature/agentic-count-enforcement

Closed automatically by merging #325 to develop (commit df8f8ea). Live e2e-verified before merge: deliberately set a real Flow project's sticky count default to x3 (a mismatch), then requested 1 image via gflow image t2i — got exactly 1 back, no MediaAttributionError. Will ship to main in the next release.