feat(team): invite-accept UX + sidebar team data + GitHub numeric id (Phase 3 P3.4)

Frontend for the cloud team registry: a ?invite=<token> deep link (or pasted
link) raises a confirm dialog, resolves the user's GitHub identity, POSTs
/team/accept, saves team config + activates team mode. The sidebar team
section renders real members (avatars) + workspaces from /team/members and
/team/workspaces (React Query). Worker HTTP client lives in src/lib/team-api.ts
(distinct from the Tauri-invoke bridge). Adds the load-bearing GitHub numeric
id to ForgeAccount (members.id = GitHub numeric id). All team UI is gated behind
isTeamModeActive() so single-user mode is unchanged.

Verified: typecheck, biome, vitest (1668 pass), cargo test forge (208), clippy.

Author: dohooo

.changeset/team-invite-accept.md

@@ -0,0 +1,8 @@
+---
+"helmor": minor
+---
+
+Team cloud: accept an invite link to join a shared workspace, and see real team data in the sidebar.
+
+- Opening Helmor with a `?invite=…` link (or pasting one into Settings → Team) registers you against the team backend with your GitHub identity and switches into team mode; unknown, expired, and already-claimed invites are surfaced distinctly.
+- In team mode the sidebar shows the live team roster (member avatars) and the shared sandbox's workspaces.

src-tauri/src/forge/accounts.rs

@@ -31,6 +31,12 @@ pub struct ForgeAccount {
     pub avatar_url: Option<String>,
     pub email: Option<String>,
     pub active: bool,
+    /// Stable numeric account id (string form), e.g. GitHub's `gh api
+    /// /user` `.id`. A login can rename, so the numeric id is the durable
+    /// identity used by team-mode member registration. `None` for GitLab
+    /// (a separate id space team mode doesn't key on) or when the profile
+    /// fetch failed.
+    pub id: Option<String>,
 }
 
 /// Tristate auth probe result. `LoggedOut` only when we definitively

src-tauri/src/forge/github/accounts.rs

@@ -53,6 +53,7 @@ impl ForgeAccountBackend for GithubAccountBackend {
             avatar_url: profile.avatar_url,
             email: profile.email,
             active: false,
+            id: profile.id.map(|id| id.to_string()),
         })
     }
 
@@ -351,6 +352,7 @@ fn list_github_accounts_full() -> Result<Vec<ForgeAccount>> {
                         login: slot.login.clone(),
                         name: profile.as_ref().and_then(|p| p.name.clone()),
                         avatar_url: profile.as_ref().and_then(|p| p.avatar_url.clone()),
+                        id: profile.as_ref().and_then(|p| p.id.map(|id| id.to_string())),
                         email: profile.and_then(|p| p.email),
                         active: slot.active,
                     }
@@ -594,6 +596,10 @@ struct GhHostStatusFullEntry {
 #[derive(Debug, Clone, Deserialize)]
 #[serde(rename_all = "snake_case")]
 struct GithubUserResponse {
+    /// GitHub's stable numeric account id. Surfaced as `ForgeAccount.id`
+    /// (string form) for team-mode member identity — a login can rename,
+    /// the id can't.
+    id: Option<u64>,
     name: Option<String>,
     avatar_url: Option<String>,
     email: Option<String>,
@@ -623,6 +629,32 @@ fn looks_like_not_found(message: &str) -> bool {
 mod tests {
     use super::*;
 
+    #[test]
+    fn github_user_response_captures_numeric_id() {
+        // `gh api /user` returns a numeric `id` that survives a login
+        // rename — the durable identity team-mode member registration
+        // keys on. Lock the parse so the field can't silently drop.
+        let stdout = r#"{
+            "id": 583231,
+            "login": "octocat",
+            "name": "The Octocat",
+            "avatar_url": "https://avatars.example/u/583231",
+            "email": "octo@example.com"
+        }"#;
+        let parsed: GithubUserResponse = serde_json::from_str(stdout).unwrap();
+        assert_eq!(parsed.id, Some(583231));
+        assert_eq!(parsed.name.as_deref(), Some("The Octocat"));
+    }
+
+    #[test]
+    fn github_user_response_id_optional_when_absent() {
+        // Defensive: a payload missing `id` must parse (id → None)
+        // rather than erroring the whole profile fetch.
+        let stdout = r#"{ "login": "octocat" }"#;
+        let parsed: GithubUserResponse = serde_json::from_str(stdout).unwrap();
+        assert_eq!(parsed.id, None);
+    }
+
     #[test]
     fn looks_like_not_found_matches_canonical_phrases() {
         assert!(looks_like_not_found("HTTP 404"));

src-tauri/src/forge/gitlab/accounts.rs

@@ -103,6 +103,9 @@ impl ForgeAccountBackend for GitlabAccountBackend {
             avatar_url: profile.avatar_url,
             email: profile.email,
             active: true,
+            // Team-mode member identity is GitHub-numeric-id keyed; GitLab
+            // uses a separate id space we don't surface here.
+            id: None,
         })
     }
 
@@ -494,6 +497,7 @@ fn fetch_gitlab_account_with_login(host: &str, login: &str) -> ForgeAccount {
         avatar_url: profile.as_ref().and_then(|p| p.avatar_url.clone()),
         email: profile.and_then(|p| p.email),
         active: true,
+        id: None,
     }
 }
 

src/features/navigation/index.tsx

@@ -33,6 +33,7 @@ import {
 	TooltipTrigger,
 } from "@/components/ui/tooltip";
 import { InlineShortcutDisplay } from "@/features/shortcuts/shortcut-display";
+import { TeamSection } from "@/features/team/team-section";
 import type {
 	RepositoryCreateOption,
 	StackRowMeta,
@@ -1151,6 +1152,10 @@ export const WorkspacesSidebar = memo(function WorkspacesSidebar({
 				<div data-tauri-drag-region className="h-full flex-1" />
 			</div>
 
+			{/* Team roster + shared workspaces — renders only in team mode,
+			    so local single-user mode is unchanged. */}
+			<TeamSection />
+
 			<div className="mt-1 flex items-center justify-between px-3">
 				<h2 className="text-title font-medium text-muted-foreground">
 					Workspaces

src/features/settings/panels/team.tsx

@@ -3,9 +3,12 @@ import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Switch } from "@/components/ui/switch";
+import { useInviteAccept } from "@/features/team/use-invite-accept";
+import { useTeamIdentity } from "@/features/team/use-team-identity";
 import {
 	getTeamConfig,
 	isTeamModeActive,
+	parseInviteLink,
 	pingTeamBackend,
 	saveTeamConfig,
 	setTeamModeActive,
@@ -23,7 +26,28 @@ export function TeamPanel() {
 	const [url, setUrl] = useState(initial?.url ?? "");
 	const [token, setToken] = useState(initial?.token ?? "");
 	const [testing, setTesting] = useState(false);
+	const [inviteLink, setInviteLink] = useState("");
 	const active = isTeamModeActive();
+	const { identity } = useTeamIdentity();
+	const { status: acceptStatus, accept } = useInviteAccept();
+	const joining = acceptStatus === "accepting";
+
+	const handleJoinWithInvite = async () => {
+		const invite = parseInviteLink(inviteLink);
+		if (!invite) {
+			toast.error("That doesn't look like a valid invite link");
+			return;
+		}
+		if (!identity) {
+			toast.error("Connect a GitHub account first (Settings → Accounts)");
+			return;
+		}
+		// On success the hook persists config, flips team mode on, and
+		// reloads — so there's no follow-up here. On failure it returns the
+		// message, which we surface as a toast.
+		const outcome = await accept(invite, identity);
+		if (!outcome.ok && outcome.error) toast.error(outcome.error);
+	};
 
 	const handleTest = async () => {
 		setTesting(true);
@@ -56,6 +80,32 @@ export function TeamPanel() {
 
 	return (
 		<SettingsGroup>
+			<SettingsRow
+				title="Join with invite link"
+				description="Paste an invite link to register with your GitHub identity and switch to the team workspace. The app reloads on success."
+				align="start"
+			>
+				<div className="flex items-center gap-2">
+					<Input
+						value={inviteLink}
+						onChange={(event) => setInviteLink(event.target.value)}
+						placeholder="https://…/?invite=…"
+						className="w-[280px]"
+						autoComplete="off"
+						autoCapitalize="off"
+						spellCheck={false}
+						disabled={joining}
+					/>
+					<Button
+						size="sm"
+						onClick={() => void handleJoinWithInvite()}
+						disabled={joining || !inviteLink.trim()}
+					>
+						{joining ? "Joining…" : "Join"}
+					</Button>
+				</div>
+			</SettingsRow>
+
 			<SettingsRow
 				title="Team mode"
 				description="Run against a shared cloud backend instead of this machine. The app reloads when you switch."

src/features/team/invite-accept-dialog.tsx

@@ -0,0 +1,126 @@
+import { Loader2, Users } from "lucide-react";
+import { GithubBrandIcon } from "@/components/brand-icon";
+import { CachedAvatar } from "@/components/cached-avatar";
+import { Button } from "@/components/ui/button";
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+} from "@/components/ui/dialog";
+import { initialsFor } from "@/lib/initials";
+import type { ParsedInvite } from "@/lib/team-mode";
+import { useInviteAccept } from "./use-invite-accept";
+import { useTeamIdentity } from "./use-team-identity";
+
+/**
+ * Headline invite-accept UX. Shown when the app is opened with a team invite
+ * (`?invite=<token>`). Confirms the GitHub identity we'll register, then
+ * redeems the token — on success the hook persists the config, flips team
+ * mode on, and reloads.
+ */
+export function InviteAcceptDialog({
+	invite,
+	onDismiss,
+}: {
+	invite: ParsedInvite;
+	onDismiss: () => void;
+}) {
+	const { identity, isLoading } = useTeamIdentity();
+	const { status, errorMessage, accept } = useInviteAccept();
+	const accepting = status === "accepting";
+	const displayName = identity?.displayName?.trim() || identity?.login || "";
+
+	return (
+		<Dialog
+			open
+			onOpenChange={(next) => {
+				// Don't let an outside-click cancel mid-accept (the reload is
+				// imminent); otherwise dismissing just closes the prompt.
+				if (!next && !accepting) onDismiss();
+			}}
+		>
+			<DialogContent className="max-w-[420px]">
+				<DialogHeader>
+					<div className="mb-1 flex size-10 items-center justify-center rounded-full bg-accent">
+						<Users className="size-5 text-foreground" strokeWidth={2} />
+					</div>
+					<DialogTitle>Join the team workspace</DialogTitle>
+					<DialogDescription>
+						You've been invited to a shared Helmor cloud workspace at{" "}
+						<span className="font-medium text-foreground">{invite.url}</span>.
+					</DialogDescription>
+				</DialogHeader>
+
+				{isLoading ? (
+					<div className="flex items-center justify-center gap-2 py-6 text-small text-muted-foreground">
+						<Loader2 className="size-3.5 animate-spin" />
+						Detecting your GitHub account…
+					</div>
+				) : identity ? (
+					<div className="flex items-center gap-3 rounded-lg border border-border/50 bg-muted/30 p-3">
+						<div className="relative shrink-0">
+							<CachedAvatar
+								size="lg"
+								className="size-9"
+								src={identity.avatarUrl}
+								alt={identity.login}
+								fallback={initialsFor(displayName)}
+								fallbackClassName="bg-muted text-ui font-semibold uppercase text-muted-foreground"
+							/>
+							<span className="absolute -right-1 -bottom-1 flex size-[16px] items-center justify-center rounded-full bg-background ring-2 ring-background">
+								<GithubBrandIcon size={10} />
+							</span>
+						</div>
+						<div className="min-w-0">
+							<div className="truncate text-ui font-semibold text-foreground">
+								{displayName}
+							</div>
+							<div className="truncate text-small text-muted-foreground">
+								@{identity.login}
+							</div>
+						</div>
+					</div>
+				) : (
+					<div className="rounded-lg border border-destructive/40 bg-destructive/5 p-3 text-small text-muted-foreground">
+						No GitHub account is connected. Sign in to GitHub in Settings →
+						Accounts, then reopen the invite link.
+					</div>
+				)}
+
+				{errorMessage ? (
+					<p className="text-small text-destructive">{errorMessage}</p>
+				) : null}
+
+				<DialogFooter>
+					<Button
+						variant="ghost"
+						onClick={onDismiss}
+						disabled={accepting}
+						className="cursor-pointer"
+					>
+						Not now
+					</Button>
+					<Button
+						onClick={() => {
+							if (identity) void accept(invite, identity);
+						}}
+						disabled={!identity || accepting}
+						className="cursor-pointer"
+					>
+						{accepting ? (
+							<>
+								<Loader2 className="size-3.5 animate-spin" />
+								Joining…
+							</>
+						) : (
+							"Join team"
+						)}
+					</Button>
+				</DialogFooter>
+			</DialogContent>
+		</Dialog>
+	);
+}

src/features/team/invite-accept-host.tsx

@@ -0,0 +1,40 @@
+import { useState } from "react";
+import {
+	clearInviteFromLocation,
+	getInviteFromLocation,
+	isTeamModeActive,
+	type ParsedInvite,
+} from "@/lib/team-mode";
+import { InviteAcceptDialog } from "./invite-accept-dialog";
+
+/**
+ * Reads a team invite out of the launch URL (`?invite=<token>`) once at
+ * mount and, when present, raises the {@link InviteAcceptDialog}. Renders
+ * nothing in the common (no-invite) case.
+ *
+ * Skipped when team mode is already active — the user is already in a team,
+ * so a leftover `?invite=` param is stale; we just strip it.
+ */
+export function InviteAcceptHost() {
+	const [invite, setInvite] = useState<ParsedInvite | null>(() => {
+		const detected = getInviteFromLocation();
+		if (!detected) return null;
+		if (isTeamModeActive()) {
+			// Already in a team — drop the stale param, don't prompt.
+			clearInviteFromLocation();
+			return null;
+		}
+		return detected;
+	});
+
+	if (!invite) return null;
+	return (
+		<InviteAcceptDialog
+			invite={invite}
+			onDismiss={() => {
+				clearInviteFromLocation();
+				setInvite(null);
+			}}
+		/>
+	);
+}