feat(workspaces): sign the workspace login handoff and gate readiness (#11671)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Managed worktree services run isolated Paperclip instances with
cloned databases.
> - A reachable service was reported as ready even when its database,
runtime identity, or login path was not usable.
> - The first candidate added verified database seeding and managed
repair in #11665.
> - This pull request consolidates that candidate with signed login
handoff and a complete readiness contract.
> - Post-QA fixes close five defects in repair identity, repair
responses, UI retry, seed journal handling, and seed-source trust.
> - The benefit is a workspace that either opens safely or reports one
accurate recovery action.

## Linked Issues or Issue Description

No public GitHub issue exists for this work, so the problem is described
here.

**What happened**

Managed workspace URLs could return HTTP 200 and report ready while
login failed. QA also found cases where repair used the wrong instance
identity, returned a generic error, left the UI stuck, rejected a safe
journal lag, or trusted a mutable workspace manifest.

**Expected behavior**

Opening a ready workspace signs the board user in to the correct
isolated instance. Provisioning and repair use a registered source and
report a structured recovery state.

**Actual behavior**

Entry depended on a password copied into the clone. Several failure
paths could publish stale readiness, hide the repair precondition, or
trust state that the workspace could modify.

**Additional context**

This pull request includes the commits first published in #11665. That
pull request keeps the original base head for review history. This
consolidated pull request is the merge candidate. Related open readiness
work includes #11575 and #11621.

## What Changed

- Adds a short-lived, signed, single-use login ticket. It binds the
user, workspace, instance, and runtime origin.
- Exchanges the ticket through Better Auth. It creates the session and
cookie through the supported adapter path.
- Adds protected workspace readiness fields for the database, clone
data, login handoff, seed phase, and runtime identity.
- Fails readiness closed when the guest has no company or
execution-workspace binding.
- Binds ticket issuance to the exact cloned user and active company
membership selected for the handoff.
- Verifies every current active board identity through the exact-user
handoff before publication or reuse.
- Gates managed runtime publication on the readiness contract and the
recorded worktree instance identity.
- Refreshes runtime work products from the live runtime row after a port
change.
- Adds one workspace access card with ready, degraded, repairing, and
failed states.
- Uses the runtime response identity for repair. It returns structured
repair precondition errors.
- Lets a valid source journal lag converge during provisioning.
- Binds seed and repair manifests to a source registered outside the
agent-writable worktree.
- Clears recovered UI errors so a successful retry can open the
workspace.
- Makes runtime tests register canonical sources and avoid ports owned
by live host listeners.
- Keeps Vitest on source suites when compiled `dist` trees exist.
- Isolates CLI and adapter tests from ambient AWS and runtime API
environment variables.
- Preserves a 404 response for cross-company workspace ID lookups before
runtime authorization.
- Makes concurrent single-flight coverage independent of
path-canonicalization scheduling order.

## Verification

The following checks passed on the integrated head:

```sh
pnpm -r typecheck
pnpm build
pnpm check:token-gates
pnpm --filter @paperclipai/db check:migrations
```

- The server source lane passed 420 files and 4,953 tests. Five tests
were skipped.
- The CLI lane passed 57 files and 385 tests.
- The database lane passed 26 files and 97 tests.
- The shared package passed 58 files and 506 tests.
- The adapter utility lane passed 640 tests. Four tests were skipped.
- The Claude adapter passed 220 tests. One test was skipped.
- The Codex adapter passed 323 tests.
- The OpenClaw adapter passed 13 tests.
- The OpenCode adapter passed 42 tests.
- The plugin SDK passed 45 tests.
- The workspace runtime suite passed 124 tests.
- The caller-scoped readiness and handoff suite passed 52 tests.
- The workspace provisioning shell suite passed 7 tests.
- The runtime exposure suite passed 17 tests while live host mappings
occupied fixed test ports.
- `git diff --check` passed and the worktree is clean.

The serialized route lane will run in GitHub CI with its normal shards.
No deployment or active-workspace migration was performed.

## Risks

- This is a medium-risk authentication and runtime-readiness change.
- The login ticket uses exact origin, workspace, instance, and user
binding. It has a short expiry and a one-time nonce.
- Runtime publication is stricter. A real readiness, identity, per-user
handoff, or control-plane database disagreement now blocks publication.
- This pull request supersedes #11665 as the merge candidate. Close
#11665 after this pull request merges.
- No new database migration is included. The lockfile and workflow files
are unchanged.
- Deployment and active-workspace migration are intentionally outside
this pull request.

> 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`.

## Model Used

Claude Opus 5 (`claude-opus-5[1m]`), 1M context, extended thinking, tool
use, and code execution produced the main candidate. OpenAI GPT-5
(`gpt-5`) through Codex, with agentic reasoning, tool use, and code
execution, integrated the post-QA fixes and hardened the test gates. The
Codex context-window size was not exposed.

## 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 searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

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

ui/src/components/WorkspaceAccessCard.test.tsx

@@ -0,0 +1,194 @@
+// @vitest-environment jsdom
+
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { WorkspaceAccessCard } from "./WorkspaceAccessCard";
+import type { WorkspaceAccessState } from "../lib/workspace-access-state";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+function act(callback: () => void) {
+  flushSync(callback);
+}
+
+function accessState(overrides: Partial<WorkspaceAccessState> = {}): WorkspaceAccessState {
+  return {
+    state: "ready",
+    title: "Ready",
+    description: "Opening the workspace signs you in to the cloned board without a password.",
+    action: { kind: "open", label: "Open workspace" },
+    handoffAvailable: true,
+    ...overrides,
+  };
+}
+
+describe("WorkspaceAccessCard", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  function renderCard(props: Partial<Parameters<typeof WorkspaceAccessCard>[0]> = {}) {
+    const handlers = {
+      onOpen: vi.fn(),
+      onStart: vi.fn(),
+      onRepair: vi.fn(),
+      onViewLogs: vi.fn(),
+    };
+    const root = createRoot(container);
+    act(() => {
+      root.render(<WorkspaceAccessCard access={accessState()} {...handlers} {...props} />);
+    });
+    const button = container.querySelector("button");
+    return { ...handlers, root, button };
+  }
+
+  function findButton(label: string) {
+    return Array.from(container.querySelectorAll("button")).find(
+      (candidate) => candidate.textContent?.trim() === label,
+    );
+  }
+
+  it("renders the ready state and opens without asking for a password", () => {
+    const { onOpen, root } = renderCard();
+    const card = container.querySelector("[data-testid='workspace-access-card']");
+    expect(card?.getAttribute("data-state")).toBe("ready");
+    expect(container.textContent).toContain("Ready");
+    expect(container.textContent).toContain("single-use login handoff");
+
+    const button = findButton("Open workspace");
+    expect(button).toBeDefined();
+    act(() => button!.click());
+    expect(onOpen).toHaveBeenCalledTimes(1);
+
+    act(() => root.unmount());
+  });
+
+  it("keeps a superseded repair failure visible without hiding the open action", () => {
+    const { onOpen, onViewLogs, root } = renderCard({
+      access: accessState({
+        secondaryNotice: {
+          title: "Repair failed",
+          description: "The repair stopped during managed_restart. The pre-repair backup was kept.",
+          action: { kind: "view_logs", label: "View repair log" },
+        },
+      }),
+    });
+
+    const openButton = findButton("Open workspace");
+    const logButton = findButton("View repair log");
+    expect(openButton).toBeDefined();
+    expect(logButton).toBeDefined();
+    expect(container.querySelector("[data-testid='workspace-access-secondary-notice']")?.textContent)
+      .toContain("pre-repair backup was kept");
+
+    act(() => openButton!.click());
+    act(() => logButton!.click());
+    expect(onOpen).toHaveBeenCalledTimes(1);
+    expect(onViewLogs).toHaveBeenCalledTimes(1);
+    act(() => root.unmount());
+  });
+
+  it("labels the credential fallback accurately when no handoff is available", () => {
+    const { root } = renderCard({
+      access: accessState({
+        handoffAvailable: false,
+        description: "Opening the board will ask for the credentials captured in this snapshot.",
+      }),
+    });
+    expect(container.textContent).toContain("snapshot-local credentials captured");
+    expect(container.textContent).not.toContain("single-use login handoff");
+    act(() => root.unmount());
+  });
+
+  it("gives provisioning, degraded, and failed states their own safe action", () => {
+    const cases = [
+      {
+        access: accessState({
+          state: "provisioning" as const,
+          title: "Provisioning database",
+          action: { kind: "start" as const, label: "Start workspace" },
+        }),
+        label: "Start workspace",
+        handlerKey: "onStart" as const,
+      },
+      {
+        access: accessState({
+          state: "degraded" as const,
+          title: "Workspace is degraded",
+          action: { kind: "repair" as const, label: "Repair workspace" },
+        }),
+        label: "Repair workspace",
+        handlerKey: "onRepair" as const,
+      },
+      {
+        access: accessState({
+          state: "failed" as const,
+          title: "Repair failed",
+          action: { kind: "view_logs" as const, label: "View repair log" },
+        }),
+        label: "View repair log",
+        handlerKey: "onViewLogs" as const,
+      },
+    ];
+
+    for (const testCase of cases) {
+      const rendered = renderCard({ access: testCase.access });
+      expect(container.textContent).toContain(testCase.access.title);
+      const button = findButton(testCase.label);
+      expect(button).toBeDefined();
+      expect(button!.disabled).toBe(false);
+      act(() => button!.click());
+      expect(rendered[testCase.handlerKey]).toHaveBeenCalledTimes(1);
+      act(() => rendered.root.unmount());
+      container.innerHTML = "";
+    }
+  });
+
+  it("offers nothing clickable while a repair is already running", () => {
+    const { root } = renderCard({
+      access: accessState({
+        state: "repairing",
+        title: "Repairing workspace database",
+        action: { kind: "wait", label: "Repair in progress" },
+      }),
+    });
+    expect(findButton("Repair in progress")?.disabled).toBe(true);
+    expect(
+      container.querySelector("[data-testid='workspace-access-badge']")?.textContent,
+    ).toContain("Repairing");
+    act(() => root.unmount());
+  });
+
+  it("always names the state and the cause instead of a bare failure", () => {
+    const { root } = renderCard({
+      access: accessState({
+        state: "failed",
+        title: "Database provisioning failed",
+        description: "The clone failed during restore. Repairing replaces only the isolated database.",
+        action: { kind: "repair", label: "Repair workspace" },
+      }),
+      errorMessage: "Failed to open the workspace.",
+    });
+    expect(container.textContent).toContain("Database provisioning failed");
+    expect(container.textContent).toContain("failed during restore");
+    expect(
+      container.querySelector("[data-testid='workspace-access-error']")?.textContent,
+    ).toContain("Failed to open the workspace.");
+    act(() => root.unmount());
+  });
+
+  it("disables the action while the caller reports it busy", () => {
+    const { root } = renderCard({ isBusy: true });
+    expect(findButton("Open workspace")?.disabled).toBe(true);
+    act(() => root.unmount());
+  });
+});

ui/src/components/WorkspaceAccessCard.tsx

@@ -0,0 +1,149 @@
+import { ExternalLink, Loader2, Play, ScrollText, Wrench } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { cn } from "../lib/utils";
+import type { WorkspaceAccessState } from "../lib/workspace-access-state";
+
+/**
+ * Workspace access surface (PAP-17572).
+ *
+ * One card per workspace that names the state, the cause, and the single safe
+ * next action. It replaces the previous behavior where a cloned workspace whose
+ * database was missing still rendered a plain "Open" link and answered with
+ * "invalid email or password".
+ */
+
+/**
+ * Badge tones come from the semantic status token layer, so a theme change moves
+ * these states with every other status surface. `ready` reuses the "done" tone
+ * and `degraded` the "todo" (amber) tone; the icon variants are the contrast-
+ * corrected pair the token layer already tunes per mode.
+ */
+const STATE_BADGE_CLASSES: Record<WorkspaceAccessState["state"], string> = {
+  provisioning: "border-border text-muted-foreground",
+  validating: "border-border text-muted-foreground",
+  ready: "border-(--status-task-done) text-(--status-task-icon-done)",
+  degraded: "border-(--status-task-todo) text-(--status-task-icon-todo)",
+  repairing: "border-border text-muted-foreground",
+  failed: "border-destructive/50 text-destructive",
+};
+
+const STATE_LABELS: Record<WorkspaceAccessState["state"], string> = {
+  provisioning: "Provisioning",
+  validating: "Validating clone",
+  ready: "Ready",
+  degraded: "Degraded",
+  repairing: "Repairing",
+  failed: "Failed",
+};
+
+const ACTION_ICONS = {
+  open: ExternalLink,
+  start: Play,
+  repair: Wrench,
+  view_logs: ScrollText,
+  wait: Loader2,
+} as const;
+
+export function WorkspaceAccessCard({
+  access,
+  isBusy,
+  onOpen,
+  onStart,
+  onRepair,
+  onViewLogs,
+  errorMessage,
+}: {
+  access: WorkspaceAccessState;
+  isBusy?: boolean;
+  onOpen: () => void;
+  onStart: () => void;
+  onRepair: () => void;
+  onViewLogs: () => void;
+  errorMessage?: string | null;
+}) {
+  const Icon = ACTION_ICONS[access.action.kind];
+  const isWaiting = access.action.kind === "wait";
+  const handlers: Record<WorkspaceAccessState["action"]["kind"], () => void> = {
+    open: onOpen,
+    start: onStart,
+    repair: onRepair,
+    view_logs: onViewLogs,
+    wait: () => undefined,
+  };
+  const SecondaryNoticeIcon = access.secondaryNotice
+    ? ACTION_ICONS[access.secondaryNotice.action.kind]
+    : null;
+
+  return (
+    <Card data-testid="workspace-access-card" data-state={access.state}>
+      <CardHeader>
+        <div className="flex flex-wrap items-center gap-2">
+          <CardTitle>{access.title}</CardTitle>
+          <span
+            data-testid="workspace-access-badge"
+            className={cn(
+              "inline-flex items-center rounded-full border bg-background px-2.5 py-1 text-xs",
+              STATE_BADGE_CLASSES[access.state],
+            )}
+          >
+            {(access.state === "repairing" || access.state === "provisioning") && (
+              <Loader2 className="mr-1.5 h-3 w-3 animate-spin" />
+            )}
+            {STATE_LABELS[access.state]}
+          </span>
+        </div>
+        <CardDescription>{access.description}</CardDescription>
+      </CardHeader>
+      <CardContent className="flex flex-col gap-3">
+        <div className="flex flex-wrap items-center gap-2">
+          <Button
+            type="button"
+            variant={access.action.kind === "open" ? "default" : "outline"}
+            disabled={isWaiting || isBusy}
+            onClick={handlers[access.action.kind]}
+          >
+            {isBusy && !isWaiting ? (
+              <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+            ) : (
+              <Icon className={cn("mr-2 h-4 w-4", isWaiting && "animate-spin")} />
+            )}
+            {access.action.label}
+          </Button>
+          {access.state === "ready" && !access.handoffAvailable ? (
+            <span className="text-xs text-muted-foreground">
+              Signs in with the snapshot-local credentials captured when this clone was made.
+            </span>
+          ) : null}
+          {access.state === "ready" && access.handoffAvailable ? (
+            <span className="text-xs text-muted-foreground">
+              Uses a single-use login handoff — no password needed.
+            </span>
+          ) : null}
+        </div>
+        {errorMessage ? (
+          <p data-testid="workspace-access-error" className="text-sm text-destructive">
+            {errorMessage}
+          </p>
+        ) : null}
+        {access.secondaryNotice && SecondaryNoticeIcon ? (
+          <div data-testid="workspace-access-secondary-notice" className="flex flex-col gap-1.5 text-sm">
+            <p className="font-medium text-destructive">{access.secondaryNotice.title}</p>
+            <p className="text-muted-foreground">{access.secondaryNotice.description}</p>
+            <Button
+              type="button"
+              variant="link"
+              size="sm"
+              className="h-auto w-fit p-0"
+              disabled={isBusy}
+              onClick={handlers[access.secondaryNotice.action.kind]}
+            >
+              <SecondaryNoticeIcon className="mr-2 h-4 w-4" />
+              {access.secondaryNotice.action.label}
+            </Button>
+          </div>
+        ) : null}
+      </CardContent>
+    </Card>
+  );
+}