[codex] Add private browser first-admin claim flow (#6755)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Fresh self-hosted deployments need an operator path before any
invite exists.
> - Umbrel installs are private LAN deployments, so a one-time browser
claim is appropriate only when the deployment is private and unclaimed.
> - Public deployments and installs with active invites must keep the
existing invite-only model so admin creation is not exposed broadly.
> - GitHub PR #2927 established the useful direction, but it needed to
be adapted onto current `master` rather than merged as-is.
> - This pull request adds that adapted private-only claim flow across
server, UI, docs, and regression coverage.
> - The benefit is that a fresh private Umbrel-style install can be
claimed from the browser without weakening public deployment access.

## What Changed

- Added a first-admin claim service and access route support for
one-time admin claim eligibility on private unclaimed deployments.
- Updated the bootstrap/access UI so eligible private installs show a
setup claim path, while public and invited deployments keep invite-first
behavior.
- Added a bootstrap-pending setup UX lab covering claim, invite, public,
and signed-in access states.
- Updated deployment and local development docs for authenticated
private/public behavior and the Umbrel-style claim path.
- Added server and UI regression tests for private claim, public
no-claim, active invite fallback, existing board/no-access flows, and
health exposure reporting.
- Stabilized PR handoff verification by serializing the aggregate server
Vitest workspace run, forcing `NODE_ENV=test`, and relaxing the
heartbeat batching test around legitimate recovery follow-up runs.

## Verification

- `pnpm -r typecheck`
- `pnpm build`
- `pnpm vitest --run
server/src/__tests__/heartbeat-comment-wake-batching.test.ts`
- `pnpm vitest --run
server/src/__tests__/health-dev-server-token.test.ts`
- `pnpm test:run`
- QA validation: PAP-10115 passed browser validation with screenshots
for private fresh install claim, active invite versus claim conflict,
public invite-only/claim-absent behavior, existing invite fallback, and
normal board/no-access flows.
- GitHub closeout: issue #2579 and PR #2927 were updated with the
accepted direction: adapt the implementation, do not direct-merge #2927
as-is.

## Risks

- The claim endpoint must remain private-only and one-time; a regression
here could expose admin creation on public deployments.
- Existing invite behavior must remain intact for public deployments and
installs that already have an active invite.
- The stable Vitest harness now serializes the aggregate server
workspace group; this is slower, but it avoids DB-backed suite
collisions under root workspace mode.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected - check the roadmap
first. See `CONTRIBUTING.md`.
>
> ROADMAP.md checked: this is a scoped deployment bootstrap/access fix
and does not duplicate a listed roadmap project.

## Model Used

- OpenAI GPT-5 Codex via Paperclip `codex_local` for product
engineering, implementation, and verification, with tool-enabled local
code execution. Paperclip QA browser validation was performed in
PAP-10115 by the assigned QA agent; exact adapter model metadata for
that QA run is not exposed in this PR context.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/pages/BootstrapSetupUxLab.tsx

@@ -0,0 +1,247 @@
+import type { ReactElement, ReactNode } from "react";
+import { Loader2, ShieldCheck, Terminal, TriangleAlert } from "lucide-react";
+import { BOOTSTRAP_FALLBACK_COMMAND } from "@/bootstrapSetup";
+import { Button } from "@/components/ui/button";
+
+type LabFixtureKey =
+  | "signed-out-private"
+  | "signed-in-private"
+  | "claiming"
+  | "claim-error"
+  | "claim-success"
+  | "public-invite-only";
+
+const FIXTURE_LABELS: Record<LabFixtureKey, string> = {
+  "signed-out-private": "1 · authenticated/private — signed out (browser claim available)",
+  "signed-in-private": "2 · authenticated/private — signed in (claim CTA primary)",
+  claiming: "3 · authenticated/private — claim in flight",
+  "claim-error": "4 · authenticated/private — claim error (e.g. 409 already claimed)",
+  "claim-success": "5 · authenticated/private — claim succeeded, redirect pending",
+  "public-invite-only": "6 · authenticated/public — invite-only (no browser claim)",
+};
+
+const FIXTURE_ORDER: LabFixtureKey[] = [
+  "signed-out-private",
+  "signed-in-private",
+  "claiming",
+  "claim-error",
+  "claim-success",
+  "public-invite-only",
+];
+
+function CliFallback({ hasActiveInvite }: { hasActiveInvite: boolean }) {
+  return (
+    <div className="mt-6 border-t border-border pt-5">
+      <div className="flex items-center gap-2 text-sm font-medium">
+        <Terminal className="size-4 text-muted-foreground" aria-hidden />
+        <span>Prefer to finish setup from the host?</span>
+      </div>
+      <p className="mt-2 text-sm text-muted-foreground">
+        {hasActiveInvite
+          ? "A bootstrap invite is already active. Check your Paperclip startup logs for the first‑admin URL, or run this command on the host to rotate it:"
+          : "Run this command on the host that runs Paperclip to print a one‑time first‑admin invite URL:"}
+      </p>
+      <pre className="mt-3 overflow-x-auto rounded-md border border-border bg-muted/30 p-3 font-mono text-xs">
+{BOOTSTRAP_FALLBACK_COMMAND}
+      </pre>
+    </div>
+  );
+}
+
+function StateChrome({ children }: { children: ReactNode }) {
+  return (
+    <div className="mx-auto max-w-xl py-10">
+      <div className="rounded-lg border border-border bg-card p-6">{children}</div>
+    </div>
+  );
+}
+
+function SignedOutPrivate() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Sign in or create your Paperclip account to become the first
+        admin from this browser.
+      </p>
+      <div className="mt-5">
+        <Button asChild>
+          <a href="/auth?next=/">Sign in / Create account</a>
+        </Button>
+      </div>
+      <CliFallback hasActiveInvite={false} />
+    </StateChrome>
+  );
+}
+
+function SignedInPrivate() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Claim it now to become the first admin and start onboarding.
+      </p>
+      <div className="mt-5 flex flex-wrap items-center gap-3">
+        <Button>Claim this instance</Button>
+        <span className="text-sm text-muted-foreground">
+          Signed in as <span className="font-medium text-foreground">jane@appliance.local</span>
+        </span>
+      </div>
+      <p className="mt-3 text-xs text-muted-foreground">
+        Wrong account?{" "}
+        <a href="/auth?next=/" className="underline underline-offset-2">
+          Switch account
+        </a>
+        .
+      </p>
+      <CliFallback hasActiveInvite={false} />
+    </StateChrome>
+  );
+}
+
+function ClaimingPrivate() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Claim it now to become the first admin and start onboarding.
+      </p>
+      <div className="mt-5 flex flex-wrap items-center gap-3">
+        <Button disabled>
+          <Loader2 className="mr-2 size-4 animate-spin" aria-hidden />
+          Claiming…
+        </Button>
+        <span className="text-sm text-muted-foreground">
+          Signed in as <span className="font-medium text-foreground">jane@appliance.local</span>
+        </span>
+      </div>
+      <CliFallback hasActiveInvite={false} />
+    </StateChrome>
+  );
+}
+
+function ClaimErrorPrivate() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">Finish setting up this Paperclip</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        No admin has claimed this instance yet. Claim it now to become the first admin and start onboarding.
+      </p>
+      <div className="mt-5 flex flex-wrap items-center gap-3">
+        <Button>Claim this instance</Button>
+        <span className="text-sm text-muted-foreground">
+          Signed in as <span className="font-medium text-foreground">jane@appliance.local</span>
+        </span>
+      </div>
+      <div
+        role="alert"
+        className="mt-4 flex items-start gap-2 rounded-md border border-destructive/40 bg-destructive/10 p-3 text-sm text-destructive"
+      >
+        <TriangleAlert className="mt-0.5 size-4 flex-shrink-0" aria-hidden />
+        <div>
+          <p className="font-medium">Someone else has already claimed this instance.</p>
+          <p className="mt-1 text-destructive/90">
+            Refresh to sign in, or ask the existing admin to invite you from{" "}
+            <span className="font-mono">Instance settings → Access</span>.
+          </p>
+        </div>
+      </div>
+      <CliFallback hasActiveInvite={false} />
+    </StateChrome>
+  );
+}
+
+function ClaimSuccess() {
+  return (
+    <StateChrome>
+      <div className="flex items-start gap-3">
+        <div className="mt-0.5 flex size-9 flex-shrink-0 items-center justify-center rounded-full bg-emerald-500/15 text-emerald-600 dark:text-emerald-400">
+          <ShieldCheck className="size-5" aria-hidden />
+        </div>
+        <div>
+          <h1 className="text-xl font-semibold">You&rsquo;re the instance admin</h1>
+          <p className="mt-2 text-sm text-muted-foreground">
+            Setup is complete. Taking you to onboarding to create your first company&hellip;
+          </p>
+        </div>
+      </div>
+      <div className="mt-5 flex items-center gap-3">
+        <Loader2 className="size-4 animate-spin text-muted-foreground" aria-hidden />
+        <span className="text-sm text-muted-foreground">Redirecting&hellip;</span>
+      </div>
+      <div className="mt-5">
+        <Button asChild variant="outline">
+          <a href="/">Continue to dashboard</a>
+        </Button>
+      </div>
+    </StateChrome>
+  );
+}
+
+function PublicInviteOnly() {
+  return (
+    <StateChrome>
+      <h1 className="text-xl font-semibold">This Paperclip is waiting on its first admin</h1>
+      <p className="mt-2 text-sm text-muted-foreground">
+        This instance runs in invite‑only mode. The operator must generate a one‑time first‑admin invite URL
+        from the host. Once you have the link, open it from this browser to finish setup.
+      </p>
+      <CliFallback hasActiveInvite />
+      <p className="mt-4 text-xs text-muted-foreground">
+        Browser‑based claim is intentionally disabled in public mode so anyone on the network can&rsquo;t
+        promote themselves.
+      </p>
+    </StateChrome>
+  );
+}
+
+const FIXTURE_BODIES: Record<LabFixtureKey, ReactElement> = {
+  "signed-out-private": <SignedOutPrivate />,
+  "signed-in-private": <SignedInPrivate />,
+  claiming: <ClaimingPrivate />,
+  "claim-error": <ClaimErrorPrivate />,
+  "claim-success": <ClaimSuccess />,
+  "public-invite-only": <PublicInviteOnly />,
+};
+
+export function BootstrapSetupUxLab() {
+  return (
+    <div className="bg-background min-h-screen pb-16">
+      <header className="border-b border-border bg-muted/20">
+        <div className="mx-auto max-w-3xl px-6 py-6">
+          <p className="text-xs font-medium uppercase tracking-wider text-muted-foreground">UX Lab</p>
+          <h1 className="mt-1 text-2xl font-semibold">Bootstrap-pending setup states</h1>
+          <p className="mt-2 max-w-2xl text-sm text-muted-foreground">
+            Fixtures for the bootstrap-pending screen in <span className="font-mono">CloudAccessGate</span>. Used
+            as the UX spec for{" "}
+            <a className="underline underline-offset-2" href="/PAP/issues/PAP-10113">
+              PAP-10113
+            </a>{" "}
+            and the implementation reference for{" "}
+            <a className="underline underline-offset-2" href="/PAP/issues/PAP-10114">
+              PAP-10114
+            </a>
+            . The browser claim CTA only appears when{" "}
+            <span className="font-mono">deploymentMode === &quot;authenticated&quot;</span> and{" "}
+            <span className="font-mono">deploymentExposure === &quot;private&quot;</span>.
+          </p>
+        </div>
+      </header>
+      <main className="mx-auto max-w-3xl space-y-12 px-6 pt-10">
+        {FIXTURE_ORDER.map((key) => (
+          <section key={key} aria-labelledby={`lab-${key}`}>
+            <h2
+              id={`lab-${key}`}
+              className="mb-3 text-xs font-medium uppercase tracking-wider text-muted-foreground"
+            >
+              {FIXTURE_LABELS[key]}
+            </h2>
+            <div className="rounded-lg border border-dashed border-border/70 bg-muted/10 p-2">
+              {FIXTURE_BODIES[key]}
+            </div>
+          </section>
+        ))}
+      </main>
+    </div>
+  );
+}