Show a failed app import or redeploy once, and keep a failed import beside its form

[dawsontoth]

⊙ Problem

Every failed deploy showed the same failure twice. useDeployComponentMutation didn't opt out of the global mutation toast, so mutationErrorHandler toasted it, and then the import form ("Failed to import …") or the redeploy modal ("Failed to redeploy …") toasted it again. The streamed redeploy also showed it in its progress panel, so that path showed it three times. The import form had no persistent failure display at all, just a toast that faded, even though these are failures the user has to fix and retry: #1699 measured one session retrying the same import 9 times in 22 minutes. Closes #1833.

❓ Your call: This fixes one mutation, not the global handler. #1808 tracks the general double report and toast for route loads, and changing errorHandler there is a separate decision. The PR is stacked on #1841 because it rewrites that PR's global-toast test, so it should merge after #1841 or be rebased onto stage once #1841 lands.

💡 Solution

The deploy mutation now opts out of the global toast. It keeps the RUM report with a mutation-level console.error, the pattern AGENTS.md documents in "Dropping errorHandler from an onError also drops the RUM report". Each caller now shows the failure once:

• Import. The failure stays above the Import button until the next attempt clears it. It reuses the redeploy panel's failure block, which this PR moves into a shared DeployFailure component, so a private-repository SSH failure also gets the "Manage SSH keys" link here. The loading toast is dismissed and no error toast is shown.
• Streamed redeploy. The failure shows only in the open progress panel. A toast is used only when the panel is no longer on screen.
• Buffered redeploy. This path closes the modal before deploying, so a toast is the only place left to show the failure. It used to depend on the global toast. Now it replaces its own progress toast with the reason.

Every one of these displays now gets its text from describeError. Before, the import and redeploy toasts used error.message, which on the buffered path is axios's Request failed with status code 500 and not the server's reason. Only the global toast had shown the real text.

Both callers now await mutateAsync instead of passing callbacks to mutate. React Query drops a mutate caller's callbacks once the component unmounts. Before this PR the global toast still reached a user who had navigated away, so without this change a failure that arrived after they left would have been silent. In that case it now arrives as a toast. Because the continuation now outlives its form, the second commit keeps it out of whatever is on screen by then. An import that finishes after the form unmounted still refreshes the tree and reports its result, but it leaves the editor selection alone. The redeploy modal records which deploy its panel is showing, and any other deploy never settles that panel or closes the modal.

Also fixed: an inconclusive stream (SSEInconclusiveError) no longer shows a generic "Error" toast on top of the "verifying…" health-check result. That toast came from the global handler, which never treated the inconclusive case as anything special. RUM still receives it, as it did before.

❓ Your call: while the import form is mounted, the failure is shown inline only, with no toast. The progress toast disappears and the reason appears right above the button the user just clicked. If you want a toast as well, so the user notices the spinner ended, that is a one-line toast.error in the mounted branch. I left it out because the issue asks for one display.

#1808 is the broader version of this: React Query's global errorHandler double-reports and double-shows failed route loads. This PR doesn't change the global handler. It only opts this one mutation out, the way the sign-in, sign-up, forgot-password and add-domain mutations already do.

⚖️ Alternatives

• Keep mutate and accept a silent failure after unmount. Rejected: that would be a regression, because the global toast had covered that case.
• Detect "no caller is observing" inside the mutation's onError and toast only then. Rejected: the mutation-level onError runs before any caller's, and the Mutation doesn't expose its observers publicly.
• Keep the buffered redeploy modal open so it can show the failure inline as well. That would change the buffered path's flow, so it is left for a separate change. This PR keeps its single toast.

🔧 Changes

• deployComponent.ts: useDeployComponentMutation sets meta: { skipGlobalErrorToast: true } and a mutation-level onError: console.error.
• DeployFailure.tsx (new): the failure block and its SSH-keys link, moved out of DeployProgress. It takes an optional title and has role="alert".
• DeployProgress.tsx: renders DeployFailure in place of its inline markup.
• useImportApplication.ts: holds importFailure in component state, clears it on the next attempt, awaits mutateAsync, toasts only once unmounted, and leaves the editor selection alone after unmount.
• ImportInstructions.tsx and NewApplication/index.tsx: render importFailure above the Import button.
• RedeployApplicationModal.tsx: both paths await mutateAsync. The streamed path keeps the deploy that owns the on-screen panel in a ref and toasts only for one that doesn't own it. The buffered path replaces its progress toast with the reason from describeError.

✅ Verification

Route: component and hook tests through the real useDeployComponentMutation and a QueryClient built on the app's own mutationErrorHandler, so the global-toast opt-out is what gets exercised. Only the network edge (instanceClient.post, deployComponentStream) and the toasts are mocked. No browser run: the deploy forms sit behind a signed-in instance, and the failure has to come from a real Harper.

• deployComponent.test.ts: the parent PR's test said the global toast showed the guidance. It now checks the opposite. The hook rejects through an observer that unmounts first, and the test asserts that no toast fires and that console.error gets the explained error exactly once.
• useImportApplication.test.ts (new) covers five cases. A failed import keeps the server's reason (not axios's) for the form, shows no error toast, and reports to RUM once. A retry clears the failure. A failure after unmount becomes a toast. A success after unmount reports and refreshes but doesn't touch the selection. An inconclusive stream is verified and not reported as a failure.
• RedeployApplicationModal.test.tsx (new) covers four cases. A streamed failure shows in the open panel with no toast. A failure after the modal was closed, or after the page was left, toasts once. A deploy that succeeds after the modal was closed and reopened leaves the reopened modal open. A buffered failure replaces its progress toast with the server's reason.
• NewApplication.test.tsx: the inline alert renders beside the Import button, and an SSH failure links to config/ssh-keys.
• Mutation checks: I removed each guard in turn and a test went red every time. The guards were skipGlobalErrorToast (8 tests), the mutation-level console.error (3), the import's mounted check (1), describeError in place of error.message (2), the panel-ownership check (1 to 2 each), and the two stale-continuation guards (1 each). Fails-on-base: all 11 new or changed tests fail against claude/1699-missing-package-json-guidance's source.
• Gates: npx vitest run over src/features/instance/applications and src/integrations/api/instance/applications passed 37 files and 398 tests. npx tsc -b, npx oxlint --format stylish . and npx dprint check all exited 0. The pre-commit hook's full suite passed on every commit, most recently 399 files and 3,695 tests.
• Cross-model review ran two rounds, with codex and gemini both times. The Cursor leg failed because git fetch could not sign through the 1Password SSH agent, and the Harper domain leg failed both rounds on an expired Claude OAuth session, so I triaged the findings by hand.
  • Round 1, codex: an import that finished after unmount moved the editor selection, and an earlier deploy's continuation could close a reopened modal. Both were real, both are fixed in the second commit, and both have tests. Round 2 marked both resolved.
  • Round 1, gemini (major): claimed a useMutation onError is dropped on unmount. Rejected. Mutation-level options run in Mutation.execute whether or not an observer is still attached, and the hook test above proves it: with the global handler opted out, that onError is the only thing that can produce the console.error, and deleting it turns the test red.
  • Round 2, gemini (major): claimed runHealthCheck could reject outside a try. Rejected: useComponentHealthCheck catches every read failure inside its polling loop and always resolves.
  • Both rounds flagged comments as narrating history. I trimmed them in the third commit, which changes only comments and adds an ?. guard to the test teardown that the CLI's self-check flagged.
• gemini-code-assist feedback: declined its one comment, to change useRef<symbol>(undefined) to useRef<symbol>(). Under @types/react 19 every useRef overload requires an argument, and applying the suggestion fails tsc -b with TS2554 and two TS2322s. Since then this branch has merged fix(applications): explain a git deploy with no root package.json #1841's fix for its own gemini comment (0efc440: the explained Axios body omits the raw text fields instead of setting them to undefined). This PR's own diff is unchanged.

_{🤖 Generated with Claude Code (Anthropic Claude Opus); posted via @dawsontoth.}

Related PRs: #1841 overlaps (stacked base; this PR replaces its global-toast test)
Complexity: medium

_{Review-Coverage: authored=claude; ran=codex,gemini; blocked=cursor-composer(no-receipt),domain(auth); declined=cursor-grok,cursor-kimi,cursor-muse; rounds=2; full=1 @ f09223e}

_{Review-Attention: study ~9m (raised: degraded review, open major) @ f09223e}

[gemini-code-assist]

Code Review

This pull request refactors application deployment and import error handling by introducing a reusable DeployFailure component to display failure messages and handle SSH access failure links. It updates useImportApplication and RedeployApplicationModal to use mutateAsync from React Query, ensuring that deployment outcomes are correctly handled even if the calling component unmounts. It also suppresses global error toasts for these mutations, routing errors to inline panels or context-aware toasts instead, backed by comprehensive tests. Feedback is provided regarding a TypeScript typing issue in RedeployApplicationModal.tsx where useRef<symbol>(undefined) may cause compilation failures under strict null checks; using useRef<symbol>() is recommended instead.

[gemini-code-assist]

In TypeScript, initializing useRef<symbol>(undefined) types deployOnScreen.current strictly as symbol and will fail compilation under strict null checks because undefined is not assignable to symbol. Since undefined is later assigned to deployOnScreen.current (on lines 48 and 69), the ref should be typed to allow undefined.

Using useRef<symbol>() is the idiomatic way to define a ref that can hold a symbol or undefined.

Suggested change

	const deployOnScreen = useRef<symbol>(undefined);
	const deployOnScreen = useRef<symbol>();

[dawsontoth]

Declining. Studio is on @types/react 19.3.0, where every useRef overload takes a required initialValue (index.d.ts:1744, :1756, :1768); the third, useRef<T>(initialValue: T | undefined): RefObject<T | undefined>, is the one useRef<symbol>(undefined) resolves to, so the ref is already symbol | undefined and tsc -b is clean. I applied the suggested useRef<symbol>() and ran tsc -b: it fails with TS2554: Expected 1 arguments, but got 0 at line 46, then TS2322: Type 'undefined' is not assignable to type 'symbol' at lines 48 and 69.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	72.81%	11963 / 16430
🔵	Statements	72.89%	12740 / 17476
🔵	Functions	67.52%	3162 / 4683
🔵	Branches	68.54%	9399 / 13712

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/instance/applications/components/DeployProgress/DeployFailure.tsx	100%	100%	100%	100%
src/features/instance/applications/components/DeployProgress/DeployProgress.tsx	83.78%	75.94%	83.33%	83.78%	39, 88-120, 252
src/features/instance/applications/components/NewApplication/ImportInstructions.tsx	60%	75%	42.85%	60%	41, 99-136, 170-180
src/features/instance/applications/components/NewApplication/index.tsx	67.56%	60%	83.33%	66.66%	36, 41-42, 49-53, 85-97
src/features/instance/applications/components/NewApplication/useImportApplication.ts	91.42%	81.81%	100%	91.17%	107-111, 113-117, 132-135, 164-165
src/features/instance/applications/modals/RedeployApplicationModal.tsx	74.77%	49.31%	91.66%	74.31%	96, 119-134, 154-161, 165, 171, 189, 203-205, 214-223, 235, 323-333
src/features/instance/config/deployments/components/ActivateStagedRelease.tsx	100%	78.57%	100%	100%
src/integrations/api/instance/applications/deployComponent.ts	100%	100%	100%	100%

Generated in workflow #2263 for commit ab4e737 by the Vitest Coverage Report Action