feat: unified invite flow — knock any Voltius user (client)

src/components/hosts/TeamSessions.tsx

@@ -13,6 +13,7 @@ import { AvatarTile } from "@/components/shared/AvatarTile";
 import { BaseCard } from "@/components/shared/BaseCard";
 import { parseInviteCode } from "@/services/inviteCode";
 import { joinTeamSessionAndOpenTab } from "@/services/teamSessionJoin";
+import { sessionDisplayName } from "@/services/teamSharing";
 
 function JoinByCodeButton({ onClick }: { onClick: () => void }) {
   const { t } = useTranslation();
@@ -85,7 +86,10 @@ export function TeamSessions() {
     await joinTeamSessionAndOpenTab({
       sessionId,
       displayName,
-      connectionName: activeSessions.find((a) => a.id === sessionId)?.connection_name ?? t("hosts.teamSessions.sharedTerminalFallback"),
+      // Session not found (not yet loaded) collapses to the same redacted state as a null name.
+      connectionName: sessionDisplayName({
+        connection_name: activeSessions.find((a) => a.id === sessionId)?.connection_name ?? null,
+      }),
       inviteToken,
     });
   };
@@ -260,7 +264,7 @@ export function TeamSessions() {
 
                   <div className="flex flex-col gap-0.5 flex-1 min-w-0">
                     <p className="text-sm font-bold truncate text-(--t-text-bright)">
-                      {session.connection_name}
+                      {sessionDisplayName(session)}
                     </p>
 
                     {/* Avatar stack — where tags sit on host cards */}

src/components/layout/SidebarAccountButton.tsx

@@ -5,9 +5,10 @@ import { useTranslation } from "react-i18next";
 import { useUIStore } from "@/stores/uiStore";
 import { useThemeStore } from "@/stores/themeStore";
 import { useRipple } from "@/hooks/useRipple";
-import { getAccountMode, lockVaultSession, logout } from "@/services/account";
+import { getAccountMode, getMe, lockVaultSession, logout } from "@/services/account";
 import { getSavedAccounts, saveCurrentAccount, switchToAccount, removeSavedAccount, type SavedAccount } from "@/services/savedAccounts";
 import { DropdownMenuItem } from "@/components/shared/DropdownMenuItem";
+import { useCopyHandle } from "@/hooks/useCopyHandle";
 
 export function SidebarAccountButton() {
   const { t } = useTranslation();
@@ -22,17 +23,26 @@ export function SidebarAccountButton() {
   const [accountEmail, setAccountEmail] = useState<string | null>(null);
   const [savedAccounts, setSavedAccounts] = useState<SavedAccount[]>([]);
   const [currentAccountId, setCurrentAccountId] = useState<string | null>(null);
+  const [accountHandle, setAccountHandle] = useState<string | null>(null);
+  const { copied: handleCopied, copy: copyHandle } = useCopyHandle(accountHandle);
 
   const refreshAccountInfo = async () => {
     const { invoke: inv } = await import("@tauri-apps/api/core");
-    const [mode, email, accountId] = await Promise.all([
+    const [mode, email, accountId, handle] = await Promise.all([
       getAccountMode().catch(() => null),
       inv<string | null>("keychain_get", { key: "email" }).catch(() => null),
       inv<string | null>("keychain_get", { key: "account_id" }).catch(() => null),
+      // Cached by getMe(); an account that signed in before handles existed has
+      // none yet, so fall back to the server rather than hiding the row forever.
+      inv<string | null>("keychain_get", { key: "handle" }).catch(() => null),
     ]);
     setAccountMode(mode);
     setAccountEmail(email);
     setCurrentAccountId(accountId);
+    setAccountHandle(handle);
+    if (!handle && mode === "server") {
+      getMe().then((me) => setAccountHandle(me?.handle ?? null)).catch(() => {});
+    }
   };
 
   useEffect(() => { refreshAccountInfo(); }, []);
@@ -137,6 +147,18 @@ export function SidebarAccountButton() {
                     {accountEmail ?? t("layout.sidebarAccount.localAccountFallback")}
                   </span>
                 </div>
+                {accountHandle && (
+                  <button
+                    type="button"
+                    onClick={copyHandle}
+                    title={t("layout.sidebarAccount.copyHandle")}
+                    className="flex items-center gap-1 mt-0.5 text-xs transition-colors"
+                    style={{ color: "var(--t-text-dim)" }}
+                  >
+                    <span className="truncate">@{accountHandle}</span>
+                    <Icon icon={handleCopied ? "lucide:check" : "lucide:copy"} width={11} />
+                  </button>
+                )}
                 {accountMode && (
                   <span className="text-xs mt-0.5 block" style={{ color: "var(--t-text-dim)" }}>
                     {accountMode === "server" ? t("layout.sidebarAccount.modeCloud") : accountMode === "local" ? t("layout.sidebarAccount.modeLocalPassword") : t("layout.sidebarAccount.modeLocal")}

src/components/members/MembersPage.tsx

@@ -35,10 +35,10 @@ import { openBillingCheckout } from "@/services/billingCheckout";
 import { useTeamVaultStateStore } from "@/stores/teamVaultStateStore";
 import { RoleModal, PERM_META, TeamRolesPanel } from "@/components/settings/sections/RolesSection";
 import { seatAvailability } from "@/services/seatMath";
-import { guestCapFor, inviteSessionOf, memberHasAccess, seatUsage } from "@/services/teamSharing";
+import { guestCapFor, inviteSessionOf, memberHasAccess, seatUsage, sessionDisplayName } from "@/services/teamSharing";
 import { SeatsMeter } from "@/components/members/SeatsMeter";
 import { ROLE_META, RoleToggleChip } from "@/components/members/roleChips";
-import { useUserSearch } from "@/hooks/useUserSearch";
+import { useUserSearch, type UserSearchResult } from "@/hooks/useUserSearch";
 
 function RoleChip({ role }: { role: TeamRole }) {
   const { t } = useTranslation();
@@ -661,8 +661,6 @@ export function PendingInviteCard({
 
 // ─── Invite panel ─────────────────────────────────────────────────────────────
 
-interface SearchResult { user_id: string; display_name: string; public_key: string; }
-
 function isValidEmail(s: string) {
   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s);
 }
@@ -687,7 +685,7 @@ export function InvitePanel({ teamId, existingIds, teamRoles, onClose, onMemberA
   const [sendingInvite, setSendingInvite] = useState(false);
   const [success, setSuccess] = useState("");
   const [error, setError] = useState("");
-  const [buySeatsFor, setBuySeatsFor] = useState<SearchResult | null | undefined>(undefined);
+  const [buySeatsFor, setBuySeatsFor] = useState<UserSearchResult | null | undefined>(undefined);
 
   const { atLimit: isAtSeatLimit } = seatAvailability(usedSeats, totalSeats);
 
@@ -724,7 +722,7 @@ export function InvitePanel({ teamId, existingIds, teamRoles, onClose, onMemberA
   useEffect(() => { void reloadSubscription(); }, []);
   useEffect(() => { inputRef.current?.focus(); }, []);
 
-  const handleAdd = async (user: SearchResult) => {
+  const handleAdd = async (user: UserSearchResult) => {
     if (isAtSeatLimit) { setBuySeatsFor(user); setOpen(false); return; }
     setAdding(user.user_id); setError(""); setSuccess("");
     try {
@@ -880,15 +878,15 @@ function PrivateVaultInvitePanel({
 }: {
   query: string;
   onQueryChange: (v: string) => void;
-  results: { user_id: string; display_name: string; public_key: string }[];
+  results: UserSearchResult[];
   searching: boolean;
   open: boolean;
   setOpen: (v: boolean) => void;
   adding: string | null;
   error: string;
   inputRef: React.RefObject<HTMLInputElement | null>;
   dropdownRef: React.RefObject<HTMLDivElement | null>;
-  onAdd: (user: { user_id: string; display_name: string; public_key: string }, roleName: string) => void;
+  onAdd: (user: UserSearchResult, roleName: string) => void;
   onClose: () => void;
 }) {
   const { t } = useTranslation();
@@ -1105,7 +1103,7 @@ export default function MembersPage() {
     loadPendingInvitations(teamId).catch(() => {});
   }, [teamId, canManageMembers, loadPendingInvitations]);
 
-  const handlePrivateAdd = async (user: { user_id: string; display_name: string; public_key: string }, roleName: string) => {
+  const handlePrivateAdd = async (user: UserSearchResult, roleName: string) => {
     if (!localVault || !primaryVaultId) return;
     setPrivateAdding(user.user_id); setPrivateError("");
     try {
@@ -1189,7 +1187,7 @@ export default function MembersPage() {
       if (!active) return [];
       const session = inviteSessionOf(c, active);
       const { atCap } = seatUsage(session, [], guestCapFor(c.vaultOwnerTier ?? tier));
-      return [{ localSessionId, connectionName: active.connection_name, session, atCap }];
+      return [{ localSessionId, connectionName: sessionDisplayName(active), session, atCap }];
     }), [connections, activeSessions, tier]);
 
   // Context menu builders

src/components/omni/OmniSearch.tsx

@@ -34,6 +34,7 @@ import { joinTeamSessionAndOpenTab } from "@/services/teamSessionJoin";
 import { useToggleSettings } from "@/hooks/useToggleSettings";
 import { parseQuickConnect, type QuickConnectIntent } from "@/services/quickConnect";
 import { launchHost, launchQuickConnect, launchLocalShell } from "@/services/launch";
+import { sessionDisplayName } from "@/services/teamSharing";
 import { isInviteCode, parseInviteCode } from "@/services/inviteCode";
 import { computeSectionBoundaries } from "./omniSections";
 import {
@@ -230,7 +231,7 @@ export default function OmniSearch({ onClose }: OmniSearchProps) {
         return [{ kind: "join-code", id: "", label: "", icon: "", code: query.trim() }];
       }
       const sessionItems = teamSessions
-        .filter((s) => !q || s.connection_name.toLowerCase().includes(q))
+        .filter((s) => !q || sessionDisplayName(s).toLowerCase().includes(q))
         .map((s): OmniItem => ({ kind: "team-session", session: s, alreadyIn: myMpSessionIds.has(s.id) }));
       return [...sessionItems, { kind: "join-code-prompt", id: "", label: "", icon: "" }];
     }
@@ -259,7 +260,7 @@ export default function OmniSearch({ onClose }: OmniSearchProps) {
     // Active team sessions
     result.push(
       ...teamSessions
-        .filter((s) => !q || s.connection_name.toLowerCase().includes(q))
+        .filter((s) => !q || sessionDisplayName(s).toLowerCase().includes(q))
         .map((s): OmniItem => ({ kind: "team-session", session: s, alreadyIn: myMpSessionIds.has(s.id) })),
     );
 
@@ -482,7 +483,7 @@ export default function OmniSearch({ onClose }: OmniSearchProps) {
             await joinTeamSessionAndOpenTab({
               sessionId: session.id,
               displayName,
-              connectionName: session.connection_name,
+              connectionName: sessionDisplayName(session),
             });
             setSidebarOpen(false);
           })().catch(console.error);
@@ -828,7 +829,7 @@ export default function OmniSearch({ onClose }: OmniSearchProps) {
           <div className="flex-1 min-w-0">
             <span className="text-sm font-medium truncate"
               style={{ color: isSelected ? "var(--t-accent)" : "var(--t-text-primary)" }}>
-              {session.connection_name}
+              {sessionDisplayName(session)}
             </span>
           </div>
           <span className="text-xs shrink-0 text-(--t-text-dim)">

src/components/settings/sections/AccountSection.handle.test.tsx

@@ -0,0 +1,150 @@
+import { test, expect, vi, afterEach } from "vitest";
+import { render, screen, cleanup, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { MeResponse } from "@/services/account";
+
+const h = vi.hoisted(() => ({
+  getMe: vi.fn(async (): Promise<MeResponse | null> => null),
+  claimHandle: vi.fn(),
+  updateInvitePreferences: vi.fn(async () => {}),
+}));
+
+class HandleClaimError extends Error {
+  constructor(public status: number) {
+    super(`handle claim failed: ${status}`);
+  }
+}
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({ t: (k: string) => k }),
+  initReactI18next: { type: "3rdParty", init: () => {} },
+}));
+vi.mock("@iconify/react", () => ({ Icon: () => null }));
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn(async () => null) }));
+vi.mock("@/services/vault", () => ({ resetVault: vi.fn(async () => {}) }));
+vi.mock("@/stores/securityStore", () => ({
+  useSecurityStore: (selector: (s: unknown) => unknown) =>
+    selector({ sessionTimeoutMinutes: null, setSessionTimeoutMinutes: vi.fn() }),
+}));
+vi.mock("@/stores/subscriptionStore", () => ({
+  useSubscriptionStore: () => ({
+    tier: "free", trialEndsAt: null, isTrialActive: false, isPro: false, isTeams: false, isBusiness: false,
+    usedSeats: null, totalSeats: null, subscriptionStatus: null, subscriptionCancelled: false, renewsAt: null, endsAt: null,
+  }),
+}));
+vi.mock("@/utils/billing", () => ({ openPortal: vi.fn() }));
+vi.mock("@/services/billingCheckout", () => ({ openBillingCheckout: vi.fn(async () => {}) }));
+vi.mock("./EditEmailModal", () => ({ default: () => null }));
+vi.mock("./ChangeMasterPasswordModal", () => ({ default: () => null }));
+vi.mock("@/services/account", async () => {
+  const actual = await vi.importActual<typeof import("@/services/account")>("@/services/account");
+  return {
+    ...actual,
+    getAccountMode: vi.fn(async () => "server"),
+    getCurrentUserEmail: vi.fn(async () => "ada@example.com"),
+    getMe: h.getMe,
+    updateDisplayName: vi.fn(async () => {}),
+    setMasterPassword: vi.fn(async () => {}),
+    logout: vi.fn(async () => {}),
+    lockVaultSession: vi.fn(async () => {}),
+  };
+});
+vi.mock("@/services/teamService", () => ({
+  claimHandle: h.claimHandle,
+  updateInvitePreferences: h.updateInvitePreferences,
+  HandleClaimError,
+}));
+
+const { default: AccountSection } = await import("./AccountSection");
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+test("a free account sees its generated handle, a copy button and the upsell — no claim form", async () => {
+  h.getMe.mockResolvedValue({ handle: "swift-otter-4821", handle_is_custom: false, tier: "free", allow_stranger_invites: true });
+  render(<AccountSection />);
+  expect(await screen.findByText("@swift-otter-4821")).toBeTruthy();
+  expect(screen.getByText("settings.account.handle.upsell")).toBeTruthy();
+  expect(screen.queryByRole("button", { name: "settings.account.handle.save" })).toBeNull();
+});
+
+test("a pro account can claim and the taken case is explained, not swallowed", async () => {
+  h.getMe.mockResolvedValue({ handle: "swift-otter-4821", handle_is_custom: false, tier: "pro", allow_stranger_invites: true });
+  h.claimHandle.mockRejectedValue(new HandleClaimError(409));
+  render(<AccountSection />);
+  await userEvent.click(await screen.findByRole("button", { name: "settings.account.handle.choose" }));
+  await userEvent.type(screen.getByRole("textbox", { name: /handle/i }), "kevin-p");
+  await userEvent.click(screen.getByRole("button", { name: "settings.account.handle.save" }));
+  expect(await screen.findByText("settings.account.handle.errorTaken")).toBeTruthy();
+});
+
+test("the stranger-invite toggle persists", async () => {
+  h.getMe.mockResolvedValue({ handle: "h", handle_is_custom: false, tier: "pro", allow_stranger_invites: true });
+  render(<AccountSection />);
+  await userEvent.click(await screen.findByRole("switch", { name: "settings.account.strangerInvites.label" }));
+  expect(h.updateInvitePreferences).toHaveBeenCalledWith(false);
+});
+
+test("the stranger-invite toggle reverts on failure", async () => {
+  h.getMe.mockResolvedValue({ handle: "h", handle_is_custom: false, tier: "pro", allow_stranger_invites: true });
+  h.updateInvitePreferences.mockRejectedValueOnce(new Error("network error"));
+  render(<AccountSection />);
+  const toggle = await screen.findByRole("switch", { name: "settings.account.strangerInvites.label" });
+  await userEvent.click(toggle);
+  await screen.findByText("network error");
+  expect(toggle.getAttribute("aria-checked")).toBe("true");
+});
+
+test("a pro account sees distinct copy for each claim-failure status", async () => {
+  h.getMe.mockResolvedValue({ handle: "h", handle_is_custom: false, tier: "pro", allow_stranger_invites: true });
+  const cases: [number, string][] = [
+    [402, "settings.account.handle.errorTierRequired"],
+    [422, "settings.account.handle.errorInvalid"],
+    [429, "settings.account.handle.errorCooldown"],
+  ];
+  for (const [status, key] of cases) {
+    h.claimHandle.mockRejectedValueOnce(new HandleClaimError(status));
+    render(<AccountSection />);
+    await userEvent.click(await screen.findByRole("button", { name: "settings.account.handle.choose" }));
+    await userEvent.type(screen.getByRole("textbox", { name: /handle/i }), "kevin-p");
+    await userEvent.click(screen.getByRole("button", { name: "settings.account.handle.save" }));
+    expect(await screen.findByText(key)).toBeTruthy();
+    cleanup();
+  }
+});
+
+test("a lapsed pro user keeps the custom-handle message, not the upsell", async () => {
+  h.getMe.mockResolvedValue({ handle: "kevin-p", handle_is_custom: true, tier: "free", allow_stranger_invites: true });
+  render(<AccountSection />);
+  await screen.findByText("@kevin-p");
+  expect(screen.getByText("settings.account.handle.lapsedKeepsHandle")).toBeTruthy();
+  expect(screen.queryByText("settings.account.handle.upsell")).toBeNull();
+});
+
+test("no upsell flash before the tier is known", async () => {
+  let resolveMe!: (v: MeResponse) => void;
+  h.getMe.mockReturnValue(new Promise<MeResponse>((resolve) => { resolveMe = resolve; }));
+  render(<AccountSection />);
+  // Wait for mode ("server") to resolve and the handle block to mount, while
+  // getMe (and so the tier) is still pending — this is the exact window a
+  // paying user would otherwise see the free-tier upsell flash in.
+  await screen.findByText("settings.account.handle.title");
+  expect(screen.queryByText("settings.account.handle.upsell")).toBeNull();
+  expect(screen.queryByRole("button", { name: "settings.account.handle.choose" })).toBeNull();
+  resolveMe({ handle: "swift-otter-4821", handle_is_custom: false, tier: "pro", allow_stranger_invites: true });
+  expect(await screen.findByRole("button", { name: "settings.account.handle.choose" })).toBeTruthy();
+});
+
+test("the stranger-invite toggle disables itself mid-flight so a second click can't race it", async () => {
+  h.getMe.mockResolvedValue({ handle: "h", handle_is_custom: false, tier: "pro", allow_stranger_invites: true });
+  let resolveUpdate!: () => void;
+  h.updateInvitePreferences.mockReturnValue(new Promise<void>((resolve) => { resolveUpdate = resolve; }));
+  render(<AccountSection />);
+  const toggle = await screen.findByRole("switch", { name: "settings.account.strangerInvites.label" });
+  await userEvent.click(toggle);
+  expect(toggle.hasAttribute("disabled")).toBe(true);
+  resolveUpdate();
+  await waitFor(() => expect(toggle.hasAttribute("disabled")).toBe(false));
+});