FAB-380: container lifecycle ops UI (instance + cluster), safe mode, resend invite

[DavidCockerill]

Summary

Studio UI for the FAB-380 container lifecycle operations (stop / start / restart, with safe mode), plus a small resend-invite addition for pending org users. This is the front-end for the central-manager / host-manager work in HarperFast/central-manager#404 and HarperFast/host-manager#126.

Container ops are a distinct class from the existing proxied Harper "restart" — they're handled host-side via the CM, are async (the endpoint returns a transitional status and the resting state lands as the poll catches up), and support safeMode (boot Harper core without loading user apps/components).

What's included

Per-instance container ops (useInstanceMenuItems)

• A Container section in the instance ⋯ menu — Start / Start in safe mode (when STOPPED), Restart / Restart in safe mode / Stop (when RUNNING). Hidden mid-transition.
• New useInstanceContainerOps hook + instanceContainerOperation client (POST /HDBInstance/{id}/container/{action}).

Cluster-wide container ops (ClusterCard)

• A Container section in the cluster ⋯ menu, gated by cluster state (RUNNING → Restart/Restart-safe/Stop, STOPPED → Start/Start-safe, PARTIAL → Start/Stop/Restart).
• Safe-mode ops force strategy: parallel (the CM rejects safeMode + rolling). Stop shows a confirm dialog; non-safe Restart opens a rolling/parallel picker.
• New useClusterContainerOps hook + clusterContainerOperation client (POST /Cluster/{id}/container/{action}), and ClusterContainerOpModals.

Cluster overview — discoverability (ClusterStateMenu)

• A labeled "Cluster actions" dropdown (AWS EC2 "Instance state" style) on the cluster overview that surfaces every op — Start / Start in safe mode / Restart / Restart in safe mode / Stop — plus Terminate, in one place. Ops that don't apply to the current status are shown but disabled, so the feature set stays discoverable (feedback was that safe mode in particular was hard to find). Hidden for self-managed clusters.
• Safe-mode explain-and-confirm dialog (SafeModeConfirmDialog): "safe mode" is jargon and a recovery action, so rather than a hover-only tooltip we explain what it does at the moment of use. Shared by the start-in-safe-mode and restart-in-safe-mode entries on both the overview and the card.
• Transient op status on the clusters-list card: while an op is in flight the card shows a Stopping / Starting / Restarting badge (with spinner), and a Stopped label when the cluster is stopped — so users can see what's happening without opening the cluster. Clears on its own as the 10s poll catches the resting state.
• Plain (non-safe) Start/Restart send safeMode: false so a cluster that's in safe mode returns to normal mode. (Previously the UI omitted safeMode, and the CM preserves the current mode when it's omitted — so a plain restart of a safe-mode cluster stayed in safe mode.)

Safe mode indicators

• Per-instance amber "Safe mode" badge on the Instances page.
• A "Safe mode" pill next to the status pill on the cluster overview when every instance is in safe mode.

Stopped-state handling

• isStoppedOrTransitioning helper; stopped/transitioning instances stop get_status polling (the ops API is unreachable), show a muted dot instead of a stale "Available"/endless spinner, and a "—" in the sign-in cell.
• STOPPED badge is now destructive (red); cluster status pill colors STOPPED red / PARTIAL yellow. Stopped cards open the instances page; partial cards open the overview.

Resend invite

• A "Resend invite" action in the org users table, shown only for PENDING users. Reuses the existing invite mutation (POST /UserInvite with { email, roleId }); the CM treats a repeat invite for a pending user as a resend.

Screenshots

Cluster overview — Running + Safe mode pill

Instances — Safe mode badges

Per-instance ⋯ menu — Container section

Cluster ⋯ menu — Container section

Restart strategy picker (non-safe cluster restart)

Resend invite (pending users only)

Backend dependencies / notes

• Depends on the CM/HM container endpoints (HarperFast/central-manager#404, HarperFast/host-manager#126). The container clients are hand-typed past the generated SDK — the /container/{action} paths and safeMode/strategy body aren't in the CM OpenAPI yet (same pattern as terminateCluster). Follow-up: regenerate the SDK once the CM OpenAPI exposes them and drop the casts.
• Instance.safeMode and Cluster.instances (now the patched Instance[]) are added in api.patch.d.ts for the same reason.
• Resend invite needs the CM invite-endpoint change deployed. On the dev CM a repeat invite for a pending user still returns 409 "User already has a pending invite"; the UI is correct and will work once that build is out.

Out of scope / follow-ups

• Error toasts: op/terminate failures in this PR route through the global MutationCache.onError (which shows the server's message) with no local error toast, so there's no double-toasting. The same pre-existing local-onError double-toast pattern lives elsewhere in the app (e.g. ClusterCard terminate, org settings/roles/users, ClusterForm) — intentionally left for a separate repo-wide cleanup rather than widened here.
• Disable-vs-hide: the "Cluster actions" dropdown disables inapplicable ops (better discoverability); the ⋯ menus hide them. Worth aligning on one convention in a follow-up.

Testing

• tsc -p tsconfig.app.json, oxlint, dprint all pass; full unit suite green (pre-commit, 1239 tests).
• Two gemini-code-assist review passes addressed — genuine findings fixed (double-toasts, [clusterId] invalidation guard, Cancel-button variants, focus-visible a11y ring); icon-size comments verified as no-ops (DropdownMenuItem/Badge already size their svg children).
• Verified live against dev/stage: instance + cluster ops fire and are accepted, safe-mode restart round-trips (badges + pill render), a plain restart of a safe-mode cluster returns it to normal mode, stopped-state polling stops, transient card status renders and clears, restart picker works, and the resend button shows only for pending rows.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces container lifecycle operations (start, stop, restart, and safe mode) for both individual instances and entire clusters, alongside a new "Resend invite" button for pending organization users. The review feedback focuses on improving code robustness and UI consistency, recommending the removal of local error handlers to prevent double-toasting, guarding query invalidations against undefined parameters, adding size classes to icons, utilizing appropriate button variants, and enhancing accessibility with focus-visible ring styles on custom buttons.

[gemini-code-assist]

To prevent duplicate error notifications (double-toasting), do not add local onError handlers to individual mutations if a global error handler (such as a global MutationCache.onError in React Query) is already configured to handle and display error messages.

			inviteUser(
				{ email: user.email, roleId },
				{
					onSuccess: () => toast.success(`Invitation resent to ${user.email}.`),
				}
			);

References

1. Do not add local onError handlers to individual mutations if a global error handler (such as a global MutationCache.onError in React Query) is already configured to handle and display error messages, to prevent duplicate error notifications (double-toasting).

[gemini-code-assist]

To prevent duplicate error notifications (double-toasting), avoid adding local error toasts in the caught error block of mutations if a global error handler is already configured. Simply dismiss the loading toast and let the global handler display the error message.

			} catch {
				toast.dismiss(toastId);
			}

References

1. Do not add local onError handlers to individual mutations if a global error handler (such as a global MutationCache.onError in React Query) is already configured to handle and display error messages, to prevent duplicate error notifications (double-toasting).

[gemini-code-assist]

To prevent duplicate error notifications (double-toasting), avoid adding local error toasts in the caught error block of mutations if a global error handler is already configured. Simply dismiss the loading toast and let the global handler display the error message.

			} catch {
				toast.dismiss(toastId);
			}

References

1. Do not add local onError handlers to individual mutations if a global error handler (such as a global MutationCache.onError in React Query) is already configured to handle and display error messages, to prevent duplicate error notifications (double-toasting).

[gemini-code-assist]

Since clusterId is retrieved from useParams({ strict: false }) and is optional, guard the query invalidation to prevent invalidating [undefined], which could lead to unexpected behavior or invalidating more queries than intended.

				if (clusterId) {
					void queryClient.invalidateQueries({ queryKey: [clusterId] });
				}
				void queryClient.invalidateQueries({ queryKey: [instance.id] });

[gemini-code-assist]

Add a size class to LifeBuoyIcon inside the Badge to ensure visual consistency with the SafeModePill in ClusterHome.tsx (which uses size-3) and prevent it from rendering at its default large size.

Suggested change

	<Badge variant="warning" title="Running in safe mode — user apps/components are not loaded">
	<LifeBuoyIcon />
	Safe mode
	</Badge>
	<Badge variant="warning" title="Running in safe mode — user apps/components are not loaded">
	<LifeBuoyIcon className="size-3" />
	Safe mode
	</Badge>

[gemini-code-assist]

The "Cancel" button should use variant="defaultOutline" or variant="ghost" to prevent visual competition with the primary/destructive action ("Stop cluster").

Suggested change

	<Button type="button" onClick={() => setStopOpen(false)}>Cancel</Button>
	<Button type="button" variant="defaultOutline" onClick={() => setStopOpen(false)}>Cancel</Button>

References

1. Do not replace the custom button variant 'defaultOutline' with the standard shadcn/ui 'outline' variant, as 'defaultOutline' is a valid custom variant in this repository (defined in 'src/components/ui/buttonVariants.tsx') that provides a primary border.

[gemini-code-assist]

The "Cancel" button should use variant="defaultOutline" or variant="ghost" to prevent visual competition with the primary actions.

Suggested change

	<Button type="button" onClick={() => setRestartOpen(false)}>Cancel</Button>
	<Button type="button" variant="defaultOutline" onClick={() => setRestartOpen(false)}>Cancel</Button>

References

1. Do not replace the custom button variant 'defaultOutline' with the standard shadcn/ui 'outline' variant, as 'defaultOutline' is a valid custom variant in this repository (defined in 'src/components/ui/buttonVariants.tsx') that provides a primary border.

[gemini-code-assist]

Add focus-visible ring styles to the custom <button> element to ensure keyboard navigation is visible and accessible.

Suggested change

	<button
	type="button"
	disabled={isPending}
	onClick={() => onConfirmRestart('rolling')}
	className="rounded-lg border border-border p-4 text-left transition-colors hover:border-primary hover:bg-accent/50 disabled:opacity-60"
	>
	<button
	type="button"
	disabled={isPending}
	onClick={() => onConfirmRestart('rolling')}
	className="rounded-lg border border-border p-4 text-left transition-colors hover:border-primary hover:bg-accent/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary disabled:opacity-60"
	>

[gemini-code-assist]

Add focus-visible ring styles to the custom <button> element to ensure keyboard navigation is visible and accessible.

Suggested change

	<button
	type="button"
	disabled={isPending}
	onClick={() => onConfirmRestart('parallel')}
	className="rounded-lg border border-border p-4 text-left transition-colors hover:border-primary hover:bg-accent/50 disabled:opacity-60"
	>
	<button
	type="button"
	disabled={isPending}
	onClick={() => onConfirmRestart('parallel')}
	className="rounded-lg border border-border p-4 text-left transition-colors hover:border-primary hover:bg-accent/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary disabled:opacity-60"
	>

[dawsontoth]

@DavidCockerill Can you get it to rebase, and then take a look at the new nav paradigm for clusters? Surfacing things in the ... menu for clusters is great, but you can also surface them on the cluster dashboard, before you navigate into the cluster. That can aid discoverability of these features. Take a pass at the instance level features too to see if any of those can be brought out of the ... on instances, and perhaps surfaced around that instances table for better discoverability.

[dawsontoth]

FWIW, I tend to rebase instead of merging changes in. That will better represent what will happen when we move to bring this PR into the main branch. Plus, it gives you a clearer view of your changes being additive to the changes that have landed already.

[DavidCockerill]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces cluster-wide and instance-level container lifecycle operations (stop, start, restart, and safe mode) along with confirmation dialogs, status badges, and polling suppression for stopped or transitioning instances. It also adds a "Resend invite" button for pending organization users. The review feedback suggests removing a local onError handler in ClusterStateMenu to prevent duplicate error notifications, and adding size and margin classes to several icons inside dropdown items and badges to ensure proper layout and alignment.

[gemini-code-assist]

Do not add local onError handlers that display error messages if a global error handler (such as a global MutationCache.onError in React Query) is already configured to handle and display error messages, to prevent duplicate error notifications (double-toasting). Instead, just handle the local state cleanup (like closing the modal).

			onError: () => {
				setTerminateOpen(false);
			},

References

1. Do not add local onError handlers to individual mutations if a global error handler (such as a global MutationCache.onError in React Query) is already configured to handle and display error messages, to prevent duplicate error notifications (double-toasting).

[gemini-code-assist]

Icons rendered directly inside DropdownMenuItem (PlayIcon, LifeBuoyIcon, RotateCwIcon, SquareIcon, TrashIcon) lack size and margin classes, which will cause them to render at their default large size (24x24) and sit right next to the text without any spacing. Consider adding className="mr-2 size-4" to each of these icons to keep them compact and properly spaced.

					<DropdownMenuItem
						disabled={opsDisabled || !(isStopped || isPartial)}
						onClick={() => void runClusterOp('start', { safeMode: false, strategy: 'parallel' })}
					>
						<PlayIcon className="mr-2 size-4" /> Start
					</DropdownMenuItem>
					<DropdownMenuItem disabled={opsDisabled || !isStopped} onClick={() => setSafeModeAction('start')}>
						<LifeBuoyIcon className="mr-2 size-4" /> Start in safe mode
					</DropdownMenuItem>
					<DropdownMenuItem
						disabled={opsDisabled || !(isRunning || isPartial)}
						onClick={() => setRestartOpen(true)}
					>
						<RotateCwIcon className="mr-2 size-4" /> Restart
					</DropdownMenuItem>
					<DropdownMenuItem disabled={opsDisabled || !isRunning} onClick={() => setSafeModeAction('restart')}>
						<LifeBuoyIcon className="mr-2 size-4" /> Restart in safe mode
					</DropdownMenuItem>
					<DropdownMenuItem
						variant="destructive"
						disabled={opsDisabled || !(isRunning || isPartial)}
						onClick={() => setStopOpen(true)}
					>
						<SquareIcon className="mr-2 size-4" /> Stop
					</DropdownMenuItem>
					<DropdownMenuSeparator />
					<DropdownMenuItem variant="destructive" disabled={!remove} onClick={() => setTerminateOpen(true)}>
						<TrashIcon className="mr-2 size-4" /> Terminate
					</DropdownMenuItem>

[gemini-code-assist]

The LifeBuoyIcon inside the Badge lacks a size class, which may cause it to render at its default large size (24x24) and distort the badge layout. Consider adding a size class like size-3.5 to keep it compact and consistent with other status indicators.

Suggested change

	<LifeBuoyIcon />
	<LifeBuoyIcon className="size-3.5" />

[gemini-code-assist]

The Loader2 icon inside the Badge lacks a size class, which may cause it to render at its default large size (24x24) and distort the badge layout. Consider adding a size class like size-3.5 to keep it compact and consistent.

Suggested change

	{isClusterTransitioning && <Loader2 className="animate-spin" />}
	{isClusterTransitioning && <Loader2 className="size-3.5 animate-spin" />}