Fail AMR insufficient-balance runs before session startup

[AmyShang-alt]

Problem

When an AMR account has insufficient balance, Open Design still spends close to 10 seconds before surfacing the recharge card.

This is separate from PR #5053. PR #5053 correctly classifies AMR/Vela structured insufficient-balance errors as AMR_INSUFFICIENT_BALANCE, but the user-visible failure still arrives late because the error is only returned after AMR/Vela session creation and event-stream startup.

Evidence

Validated locally in PR #5053 Electron runtime:

• Worktree: /Users/mac/open-design/pr-5053-electron
• PR head: f35299f0b20b0070d13b04bbf9e038ac07a741a2
• Namespace: pr5053
• Run/trace id: cf0af90f-326d-47f8-a35c-f587d590c0ca
• Model: deepseek-v4-flash
• UI displayed: 已完成 9.9s

Run event timeline:

• 03:33:15.454 run start
• 03:33:21.217 AMR opencode session created, about 5.8s after start
• 03:33:24.240 Open Design emitted AMR_INSUFFICIENT_BALANCE, about 8.8s after start
• 03:33:24.899 run ended failed, about 9.4s after start

AMR runtime log showed the balance failure only at event-stream phase:

opencode_event_stream_failure ... phase=event_stream ... status.message="[code=insufficient_balance] insufficient wallet balance"

Expected

If Open Design already knows the AMR account balance is insufficient, the run should fail before starting the expensive AMR/opencode session path, ideally within a short preflight step.

The UI should still show the existing AMR_INSUFFICIENT_BALANCE recharge card, but without spending close to 10 seconds.

Possible fixes

• Add an Open Design-side AMR wallet/balance preflight before starting AMR runs.
• Or have Vela/ACP return structured insufficient-balance details during session initialization instead of waiting until event stream.

Acceptance

• With an insufficient-balance AMR account, starting a run surfaces the recharge card quickly rather than after session/event-stream startup.
• The error code remains AMR_INSUFFICIENT_BALANCE.
• The recovery card still includes the recharge action URL.
• Auth-required and unrelated model/service errors are not misclassified as insufficient balance.

[lefarcen]

Hey @AmyShang-alt — good catch separating this from #5053.

This looks confirmed from both the trace you attached and the current daemon path: today we preflight AMR auth/model availability before spawn, but the insufficient-balance case is still being promoted out of the downstream ACP/event-stream failure path, so the ~9–10s delay before the recharge card is consistent with the code as it stands.

We already have AMR wallet/account readers in the daemon (/api/integrations/vela/wallet and fetchVelaBillingSummary), so a short pre-session balance preflight looks like the right direction for this follow-up — with the important guard that auth / network / model errors must stay distinct from true AMR_INSUFFICIENT_BALANCE.

[lefarcen]

Heads-up: PR #5349 is open as a follow-up on the AMR pre-run balance gate. It keeps the hard insufficient-balance fast-fail path intact, but narrows the dismissible low-balance warning from the broader range added in #5103 down to balances at or below $2.00. Keeping this issue open until that follow-up lands and the preflight path remains validated.

[lefarcen]

Hey @AmyShang-alt — PR #5349 has now merged.

This follow-up tightens the AMR low-balance pre-run warning to <= $2.00, keeps the $0 hard block, and keeps the insufficient-balance path on the faster pre-run check instead of waiting for session/event-stream startup.

When you have a chance, could you re-test the insufficient-balance flow and confirm whether the recharge / warning behavior now shows up promptly on your side? We’ll keep this issue open until that’s validated.

[lefarcen]

Heads-up: PR #5591 is open as a follow-up on the remaining AMR low-balance experience for Free users. It keeps the hard insufficient-balance path intact, removes the Free soft-intercept before value is shown, and instead moves the upgrade prompt to the post-artifact send / home flow. Keeping this issue open until that follow-up lands and the user-visible path is validated.

[lefarcen]

Hey @AmyShang-alt — PR #5591 has now merged and the merged head has also been QA-validated.

This follow-up keeps the hard insufficient-balance path intact, removes the Free soft intercept before value is shown, and moves the upgrade prompt to the post-artifact send / Home flow, with the fail-open guard in place when billing-plan data is unavailable.

When you have a chance, could you retry the AMR low-balance / insufficient-balance path on your side and let us know whether the behavior now matches what you expected? We’ll keep this issue open for a bit for validation in case anything still feels off.