Add workspace setup streaming and setup tab

2026-03-31 09:09:38 +07:00
parent 266d042528
commit 1f6ffa9e0e
28 changed files with 1645 additions and 165 deletions
@@ -0,0 +1,156 @@
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { expect, type Page } from "@playwright/test";
+import { gotoAppShell } from "./app";
+import type { SessionOutboundMessage } from "@server/shared/messages";
+
+type WorkspaceSetupDaemonClient = {
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  openProject(
+    cwd: string,
+  ): Promise<{ workspace: { id: string; name: string } | null; error: string | null }>;
+  createPaseoWorktree(
+    input: { cwd: string; worktreeSlug?: string },
+  ): Promise<{ workspace: { id: string; name: string } | null; error: string | null }>;
+  subscribeRawMessages(handler: (message: SessionOutboundMessage) => void): () => void;
+};
+
+export type WorkspaceSetupProgressPayload = Extract<
+  SessionOutboundMessage,
+  { type: "workspace_setup_progress" }
+>["payload"];
+
+function getDaemonWsUrl(): string {
+  const daemonPort = process.env.E2E_DAEMON_PORT;
+  if (!daemonPort) {
+    throw new Error("E2E_DAEMON_PORT is not set.");
+  }
+  return `ws://127.0.0.1:${daemonPort}/ws`;
+}
+
+async function loadDaemonClientConstructor(): Promise<
+  new (config: { url: string; clientId: string; clientType: "cli" }) => WorkspaceSetupDaemonClient
+> {
+  const repoRoot = path.resolve(process.cwd(), "../..");
+  const moduleUrl = pathToFileURL(
+    path.join(repoRoot, "packages/server/dist/server/server/exports.js"),
+  ).href;
+  const mod = (await import(moduleUrl)) as {
+    DaemonClient: new (config: {
+      url: string;
+      clientId: string;
+      clientType: "cli";
+    }) => WorkspaceSetupDaemonClient;
+  };
+  return mod.DaemonClient;
+}
+
+export async function connectWorkspaceSetupClient(): Promise<WorkspaceSetupDaemonClient> {
+  const DaemonClient = await loadDaemonClientConstructor();
+  const client = new DaemonClient({
+    url: getDaemonWsUrl(),
+    clientId: `workspace-setup-${randomUUID()}`,
+    clientType: "cli",
+  });
+  await client.connect();
+  return client;
+}
+
+export async function seedProjectForWorkspaceSetup(
+  client: WorkspaceSetupDaemonClient,
+  repoPath: string,
+): Promise<void> {
+  const result = await client.openProject(repoPath);
+  if (!result.workspace || result.error) {
+    throw new Error(result.error ?? `Failed to open project ${repoPath}`);
+  }
+}
+
+export function projectNameFromPath(repoPath: string): string {
+  return repoPath.replace(/\/+$/, "").split("/").filter(Boolean).pop() ?? repoPath;
+}
+
+export async function openHomeWithProject(page: Page, repoPath: string): Promise<void> {
+  await gotoAppShell(page);
+  await expect(createWorkspaceButton(page, repoPath)).toBeVisible({ timeout: 30_000 });
+}
+
+function createWorkspaceButton(page: Page, repoPath: string) {
+  return page.getByRole("button", {
+    name: `Create a new workspace for ${projectNameFromPath(repoPath)}`,
+  });
+}
+
+async function revealWorkspaceButton(page: Page, repoPath: string): Promise<void> {
+  await page.getByTestId(`sidebar-project-row-${repoPath}`).hover();
+}
+
+export async function createWorkspaceFromSidebar(page: Page, repoPath: string): Promise<void> {
+  await revealWorkspaceButton(page, repoPath);
+  await expect(createWorkspaceButton(page, repoPath)).toBeEnabled({ timeout: 30_000 });
+  await createWorkspaceButton(page, repoPath).click();
+  await expect(page).toHaveURL(/\/workspace\//, { timeout: 30_000 });
+}
+
+export async function expectSetupPanel(page: Page): Promise<void> {
+  await expect(page.getByText("Workspace setup", { exact: true })).toBeVisible({ timeout: 30_000 });
+}
+
+export async function expectSetupStatus(
+  page: Page,
+  status: "Running" | "Completed" | "Failed",
+): Promise<void> {
+  await expect(page.getByTestId("workspace-setup-status")).toContainText(status, {
+    timeout: 30_000,
+  });
+}
+
+export async function expectSetupLogContains(page: Page, text: string): Promise<void> {
+  await expect(page.getByTestId("workspace-setup-log")).toContainText(text, {
+    timeout: 30_000,
+  });
+}
+
+export async function expectNoSetupMessage(page: Page): Promise<void> {
+  await expect(page.getByText("No setup commands ran for this workspace.", { exact: true })).toBeVisible({
+    timeout: 30_000,
+  });
+}
+
+export async function createWorkspaceThroughDaemon(
+  client: WorkspaceSetupDaemonClient,
+  input: { cwd: string; worktreeSlug: string },
+): Promise<{ id: string; name: string }> {
+  const result = await client.createPaseoWorktree(input);
+  if (!result.workspace || result.error) {
+    throw new Error(result.error ?? `Failed to create workspace for ${input.cwd}`);
+  }
+  return result.workspace;
+}
+
+export async function waitForWorkspaceSetupProgress(
+  client: WorkspaceSetupDaemonClient,
+  predicate: (payload: WorkspaceSetupProgressPayload) => boolean,
+  timeoutMs = 30_000,
+): Promise<WorkspaceSetupProgressPayload> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      unsubscribe();
+      reject(new Error(`Timed out waiting for workspace_setup_progress after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    const unsubscribe = client.subscribeRawMessages((message) => {
+      if (message.type !== "workspace_setup_progress") {
+        return;
+      }
+      if (!predicate(message.payload)) {
+        return;
+      }
+      clearTimeout(timeout);
+      unsubscribe();
+      resolve(message.payload);
+    });
+  });
+}
@@ -10,7 +10,11 @@ type TempRepo = {

 export const createTempGitRepo = async (
  prefix = "paseo-e2e-",
-  options?: { withRemote?: boolean },
+  options?: {
+    withRemote?: boolean;
+    paseoConfig?: Record<string, unknown>;
+    files?: Array<{ path: string; content: string }>;
+  },
 ): Promise<TempRepo> => {
  // Keep E2E repo paths short so terminal prompt + typed commands stay visible without zsh clipping.
  const tempRoot = process.platform === "win32" ? tmpdir() : "/tmp";
@@ -22,7 +26,24 @@ export const createTempGitRepo = async (
  execSync('git config user.name "Paseo E2E"', { cwd: repoPath, stdio: "ignore" });
  execSync("git config commit.gpgsign false", { cwd: repoPath, stdio: "ignore" });
  await writeFile(path.join(repoPath, "README.md"), "# Temp Repo\n");
+  if (options?.paseoConfig) {
+    await writeFile(
+      path.join(repoPath, "paseo.json"),
+      JSON.stringify(options.paseoConfig, null, 2),
+    );
+  }
+  for (const file of options?.files ?? []) {
+    const filePath = path.join(repoPath, file.path);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, file.content);
+  }
  execSync("git add README.md", { cwd: repoPath, stdio: "ignore" });
+  if (options?.paseoConfig) {
+    execSync("git add paseo.json", { cwd: repoPath, stdio: "ignore" });
+  }
+  for (const file of options?.files ?? []) {
+    execSync(`git add ${JSON.stringify(file.path)}`, { cwd: repoPath, stdio: "ignore" });
+  }
  execSync('git commit -m "Initial commit"', { cwd: repoPath, stdio: "ignore" });

  if (withRemote) {
@@ -0,0 +1,132 @@
+import { test, expect } from "./fixtures";
+import { createTempGitRepo } from "./helpers/workspace";
+import {
+  connectWorkspaceSetupClient,
+  createWorkspaceFromSidebar,
+  createWorkspaceThroughDaemon,
+  expectSetupPanel,
+  openHomeWithProject,
+  seedProjectForWorkspaceSetup,
+  waitForWorkspaceSetupProgress,
+} from "./helpers/workspace-setup";
+
+test.describe("Workspace setup streaming", () => {
+  test("opens the setup tab when a workspace is created from the sidebar", async ({ page }) => {
+    const client = await connectWorkspaceSetupClient();
+    const repo = await createTempGitRepo("setup-open-", {
+      paseoConfig: {
+        worktree: {
+          setup: ["sh -c 'echo starting setup; sleep 2; echo setup complete'"],
+        },
+      },
+    });
+
+    try {
+      await seedProjectForWorkspaceSetup(client, repo.path);
+      await openHomeWithProject(page, repo.path);
+      await createWorkspaceFromSidebar(page, repo.path);
+
+      await expectSetupPanel(page);
+      await expect(page).toHaveURL(/\/workspace\//, { timeout: 30_000 });
+    } finally {
+      await client.close();
+      await repo.cleanup();
+    }
+  });
+
+  test("streams running and completed setup snapshots for a successful setup", async () => {
+    const client = await connectWorkspaceSetupClient();
+    const repo = await createTempGitRepo("setup-success-", {
+      paseoConfig: {
+        worktree: {
+          setup: ["sh -c 'echo starting setup; sleep 2; echo setup complete'"],
+        },
+      },
+    });
+
+    try {
+      await seedProjectForWorkspaceSetup(client, repo.path);
+      const running = waitForWorkspaceSetupProgress(client, (payload) => payload.status === "running");
+      const completed = waitForWorkspaceSetupProgress(
+        client,
+        (payload) => payload.status === "completed" && payload.detail.log.includes("setup complete"),
+      );
+
+      await createWorkspaceThroughDaemon(client, {
+        cwd: repo.path,
+        worktreeSlug: "workspace-setup-success",
+      });
+
+      const runningPayload = await running;
+      const completedPayload = await completed;
+
+      expect(runningPayload.detail.log).toContain("starting setup");
+      expect(completedPayload.detail.log).toContain("setup complete");
+      expect(completedPayload.error).toBeNull();
+    } finally {
+      await client.close();
+      await repo.cleanup();
+    }
+  });
+
+  test("streams a failed setup snapshot when setup fails", async () => {
+    const client = await connectWorkspaceSetupClient();
+    const repo = await createTempGitRepo("setup-failure-", {
+      paseoConfig: {
+        worktree: {
+          setup: ["sh -c 'echo starting setup; sleep 2; echo setup failed 1>&2; exit 1'"],
+        },
+      },
+    });
+
+    try {
+      await seedProjectForWorkspaceSetup(client, repo.path);
+      const failed = waitForWorkspaceSetupProgress(
+        client,
+        (payload) => payload.status === "failed" && payload.detail.log.includes("setup failed"),
+      );
+
+      await createWorkspaceThroughDaemon(client, {
+        cwd: repo.path,
+        worktreeSlug: "workspace-setup-failure",
+      });
+
+      const failedPayload = await failed;
+      expect(failedPayload.detail.log).toContain("starting setup");
+      expect(failedPayload.detail.log).toContain("setup failed");
+      expect(failedPayload.error).toMatch(/failed/i);
+    } finally {
+      await client.close();
+      await repo.cleanup();
+    }
+  });
+
+  test("emits a completed empty snapshot when no setup commands exist", async () => {
+    const client = await connectWorkspaceSetupClient();
+    const repo = await createTempGitRepo("setup-none-");
+
+    try {
+      await seedProjectForWorkspaceSetup(client, repo.path);
+      const completed = waitForWorkspaceSetupProgress(
+        client,
+        (payload) =>
+          payload.status === "completed" &&
+          payload.detail.commands.length === 0 &&
+          payload.detail.log === "",
+      );
+
+      await createWorkspaceThroughDaemon(client, {
+        cwd: repo.path,
+        worktreeSlug: "workspace-setup-none",
+      });
+
+      const completedPayload = await completed;
+      expect(completedPayload.error).toBeNull();
+      expect(completedPayload.detail.commands).toEqual([]);
+      expect(completedPayload.detail.log).toBe("");
+    } finally {
+      await client.close();
+      await repo.cleanup();
+    }
+  });
+});
@@ -31,6 +31,9 @@ function getOpenIntentTarget(openIntent: WorkspaceOpenIntent): WorkspaceTabTarge
  if (openIntent.kind === "file") {
    return { kind: "file", path: openIntent.path };
  }
+  if (openIntent.kind === "setup") {
+    return { kind: "setup", workspaceId: openIntent.workspaceId };
+  }
  return { kind: "draft", draftId: openIntent.draftId };
 }

@@ -695,7 +695,7 @@ function ProjectHeaderRow({
        prepareWorkspaceTab({
          serverId: serverId!,
          workspaceId: workspace.id,
-          target: { kind: "draft", draftId: "new" },
+          target: { kind: "setup", workspaceId: workspace.id },
        }) as any,
      );
    },
@@ -35,6 +35,7 @@ import {
  normalizeWorkspaceDescriptor,
 } from "@/stores/session-store";
 import { useDraftStore } from "@/stores/draft-store";
+import { useWorkspaceSetupStore } from "@/stores/workspace-setup-store";
 import type { AgentDirectoryEntry } from "@/types/agent-directory";
 import { sendOsNotification } from "@/utils/os-notifications";
 import { getIsAppActivelyVisible } from "@/utils/app-visibility";
@@ -159,6 +160,10 @@ type WorkspaceUpdatePayload = Extract<
  SessionOutboundMessage,
  { type: "workspace_update" }
 >["payload"];
+type WorkspaceSetupProgressPayload = Extract<
+  SessionOutboundMessage,
+  { type: "workspace_setup_progress" }
+>["payload"];

 const getAgentIdFromUpdate = (update: AgentUpdatePayload): string =>
  update.kind === "remove" ? update.agentId : update.agent.id;
@@ -264,6 +269,9 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
  const setQueuedMessages = useSessionStore((state) => state.setQueuedMessages);
  const updateSessionClient = useSessionStore((state) => state.updateSessionClient);
  const updateSessionServerInfo = useSessionStore((state) => state.updateSessionServerInfo);
+  const upsertWorkspaceSetupProgress = useWorkspaceSetupStore((state) => state.upsertProgress);
+  const removeWorkspaceSetup = useWorkspaceSetupStore((state) => state.removeWorkspace);
+  const clearWorkspaceSetupServer = useWorkspaceSetupStore((state) => state.clearServer);

  // Track focused agent for heartbeat
  const focusedAgentId = useSessionStore(
@@ -748,6 +756,13 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
    ],
  );

+  const applyWorkspaceSetupProgress = useCallback(
+    (payload: WorkspaceSetupProgressPayload) => {
+      upsertWorkspaceSetupProgress({ serverId, payload });
+    },
+    [serverId, upsertWorkspaceSetupProgress],
+  );
+
  const requestCanonicalCatchUp = useCallback(
    (agentId: string, cursor: { epoch: string; endSeq: number }) => {
      void client
@@ -1090,12 +1105,18 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
    const unsubWorkspaceUpdate = client.on("workspace_update", (message) => {
      if (message.type !== "workspace_update") return;
      if (message.payload.kind === "remove") {
+        removeWorkspaceSetup({ serverId, workspaceId: message.payload.id });
        removeWorkspace(serverId, message.payload.id);
        return;
      }
      mergeWorkspaces(serverId, [normalizeWorkspaceDescriptor(message.payload.workspace)]);
    });

+    const unsubWorkspaceSetupProgress = client.on("workspace_setup_progress", (message) => {
+      if (message.type !== "workspace_setup_progress") return;
+      applyWorkspaceSetupProgress(message.payload);
+    });
+
    const unsubStatus = client.on("status", (message) => {
      if (message.type !== "status") return;
      const serverInfo = parseServerInfoStatusPayload(message.payload);
@@ -1444,6 +1465,7 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
      unsubAgentStream();
      unsubAgentTimeline();
      unsubWorkspaceUpdate();
+      unsubWorkspaceSetupProgress();
      unsubStatus();
      unsubPermissionRequest();
      unsubPermissionResolved();
@@ -1471,6 +1493,7 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
    setAgents,
    mergeWorkspaces,
    removeWorkspace,
+    removeWorkspaceSetup,
    setAgentLastActivity,
    setPendingPermissions,
    setHasHydratedAgents,
@@ -1478,6 +1501,7 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
    notifyAgentAttention,
    requestCanonicalCatchUp,
    applyAgentUpdatePayload,
+    applyWorkspaceSetupProgress,
    applyTimelineResponse,
    voiceRuntime,
    voiceAudioEngine,
@@ -1681,9 +1705,10 @@ function SessionProviderInternal({ children, serverId, client }: SessionProvider
  // Cleanup on unmount
  useEffect(() => {
    return () => {
+      clearWorkspaceSetupServer(serverId);
      clearSession(serverId);
    };
-  }, [clearSession, serverId]);
+  }, [clearSession, clearWorkspaceSetupServer, serverId]);

  return children;
 }
@@ -2,6 +2,7 @@ import { agentPanelRegistration } from "@/panels/agent-panel";
 import { draftPanelRegistration } from "@/panels/draft-panel";
 import { filePanelRegistration } from "@/panels/file-panel";
 import { registerPanel } from "@/panels/panel-registry";
+import { setupPanelRegistration } from "@/panels/setup-panel";
 import { terminalPanelRegistration } from "@/panels/terminal-panel";

 let panelsRegistered = false;
@@ -12,6 +13,7 @@ export function ensurePanelsRegistered(): void {
  }
  registerPanel(draftPanelRegistration);
  registerPanel(agentPanelRegistration);
+  registerPanel(setupPanelRegistration);
  registerPanel(terminalPanelRegistration);
  registerPanel(filePanelRegistration);
  panelsRegistered = true;
@@ -0,0 +1,309 @@
+import { CheckCircle2, CircleAlert, SquareTerminal } from "lucide-react-native";
+import { ScrollView, Text, View } from "react-native";
+import invariant from "tiny-invariant";
+import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { Fonts } from "@/constants/theme";
+import { usePaneContext } from "@/panels/pane-context";
+import type { PanelDescriptor, PanelRegistration } from "@/panels/panel-registry";
+import { buildWorkspaceTabPersistenceKey } from "@/stores/workspace-tabs-store";
+import { useWorkspaceSetupStore } from "@/stores/workspace-setup-store";
+
+function useSetupPanelDescriptor(
+  target: { kind: "setup"; workspaceId: string },
+  context: { serverId: string; workspaceId: string },
+): PanelDescriptor {
+  const key = buildWorkspaceTabPersistenceKey({
+    serverId: context.serverId,
+    workspaceId: target.workspaceId,
+  });
+  const snapshot = useWorkspaceSetupStore((state) => (key ? state.snapshots[key] ?? null : null));
+
+  if (snapshot?.status === "completed") {
+    return {
+      label: "Setup",
+      subtitle: "Setup completed",
+      titleState: "ready",
+      icon: CheckCircle2,
+      statusBucket: null,
+    };
+  }
+
+  if (snapshot?.status === "failed") {
+    return {
+      label: "Setup",
+      subtitle: "Setup failed",
+      titleState: "ready",
+      icon: CircleAlert,
+      statusBucket: null,
+    };
+  }
+
+  return {
+    label: "Setup",
+    subtitle: "Workspace setup",
+    titleState: "ready",
+    icon: SquareTerminal,
+    statusBucket: snapshot?.status === "running" ? "running" : null,
+  };
+}
+
+function formatCommandStatus(status: "running" | "completed" | "failed"): string {
+  if (status === "running") {
+    return "Running";
+  }
+  if (status === "completed") {
+    return "Completed";
+  }
+  return "Failed";
+}
+
+function formatSetupStatus(status: "running" | "completed" | "failed" | null): string {
+  if (status === "running") {
+    return "Running";
+  }
+  if (status === "completed") {
+    return "Completed";
+  }
+  if (status === "failed") {
+    return "Failed";
+  }
+  return "Waiting for setup output";
+}
+
+function SetupPanel() {
+  const { theme } = useUnistyles();
+  const { serverId, target } = usePaneContext();
+  invariant(target.kind === "setup", "SetupPanel requires setup target");
+
+  const key = buildWorkspaceTabPersistenceKey({
+    serverId,
+    workspaceId: target.workspaceId,
+  });
+  const snapshot = useWorkspaceSetupStore((state) => (key ? state.snapshots[key] ?? null : null));
+
+  const commands = snapshot?.detail.commands ?? [];
+  const log = snapshot?.detail.log ?? "";
+  const statusLabel = formatSetupStatus(snapshot?.status ?? null);
+  const hasNoSetupCommands =
+    snapshot?.status === "completed" && commands.length === 0 && log.trim().length === 0;
+
+  return (
+    <View style={styles.container} testID="workspace-setup-panel">
+      <View
+        style={styles.header}
+        accessible
+        accessibilityLabel={`Workspace setup status: ${statusLabel}`}
+        testID="workspace-setup-status"
+      >
+        <Text style={styles.title}>Workspace setup</Text>
+        <View
+          style={[
+            styles.statusBadge,
+            snapshot?.status === "completed" && {
+              backgroundColor: theme.colors.palette.green[100],
+            },
+            snapshot?.status === "failed" && {
+              backgroundColor: theme.colors.palette.red[100],
+            },
+          ]}
+        >
+          <Text
+            style={[
+              styles.statusBadgeText,
+              snapshot?.status === "completed" && {
+                color: theme.colors.palette.green[600],
+              },
+              snapshot?.status === "failed" && {
+                color: theme.colors.palette.red[600],
+              },
+            ]}
+          >
+            {statusLabel}
+          </Text>
+        </View>
+      </View>
+
+      {snapshot?.error ? (
+        <View style={styles.errorCard}>
+          <Text style={styles.errorTitle}>Setup error</Text>
+          <Text selectable style={styles.errorBody}>
+            {snapshot.error}
+          </Text>
+        </View>
+      ) : null}
+
+      {commands.length > 0 ? (
+        <View style={styles.section}>
+          <Text style={styles.sectionTitle}>Commands</Text>
+          <View style={styles.commandList}>
+            {commands.map((command) => (
+              <View key={`${command.index}:${command.command}`} style={styles.commandRow}>
+                <Text style={styles.commandIndex}>{command.index}.</Text>
+                <View style={styles.commandTextColumn}>
+                  <Text selectable style={styles.commandText}>
+                    {command.command}
+                  </Text>
+                  <Text style={styles.commandMeta}>
+                    {formatCommandStatus(command.status)}
+                    {typeof command.exitCode === "number" ? ` · exit ${command.exitCode}` : ""}
+                  </Text>
+                </View>
+              </View>
+            ))}
+          </View>
+        </View>
+      ) : null}
+
+      <View style={styles.sectionFill}>
+        <Text style={styles.sectionTitle}>Log</Text>
+        {hasNoSetupCommands ? (
+          <View style={styles.emptyCard}>
+            <Text
+              style={styles.emptyText}
+              accessible
+              accessibilityLabel="No setup commands ran for this workspace"
+            >
+              No setup commands ran for this workspace.
+            </Text>
+          </View>
+        ) : (
+          <ScrollView
+            style={styles.logContainer}
+            contentContainerStyle={styles.logContent}
+            showsVerticalScrollIndicator
+            testID="workspace-setup-log"
+            accessible
+            accessibilityLabel="Workspace setup log"
+          >
+            <Text selectable style={styles.logText}>
+              {log.trim().length > 0 ? log : "Waiting for setup output..."}
+            </Text>
+          </ScrollView>
+        )}
+      </View>
+    </View>
+  );
+}
+
+export const setupPanelRegistration: PanelRegistration<"setup"> = {
+  kind: "setup",
+  component: SetupPanel,
+  useDescriptor: useSetupPanelDescriptor,
+};
+
+const styles = StyleSheet.create((theme) => ({
+  container: {
+    flex: 1,
+    minHeight: 0,
+    padding: theme.spacing[4],
+    gap: theme.spacing[4],
+    backgroundColor: theme.colors.surface0,
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+    gap: theme.spacing[3],
+  },
+  title: {
+    fontSize: theme.fontSize.lg,
+    fontWeight: "600",
+    color: theme.colors.foreground,
+  },
+  statusBadge: {
+    borderRadius: theme.borderRadius.full,
+    paddingHorizontal: theme.spacing[3],
+    paddingVertical: theme.spacing[1],
+    backgroundColor: theme.colors.surface2,
+  },
+  statusBadgeText: {
+    fontSize: theme.fontSize.sm,
+    fontWeight: "600",
+    color: theme.colors.foregroundMuted,
+  },
+  errorCard: {
+    borderRadius: theme.borderRadius.lg,
+    borderWidth: 1,
+    borderColor: theme.colors.palette.red[200],
+    backgroundColor: theme.colors.palette.red[100],
+    padding: theme.spacing[3],
+    gap: theme.spacing[2],
+  },
+  errorTitle: {
+    fontSize: theme.fontSize.sm,
+    fontWeight: "600",
+    color: theme.colors.palette.red[800],
+  },
+  errorBody: {
+    fontSize: theme.fontSize.sm,
+    color: theme.colors.palette.red[800],
+  },
+  section: {
+    gap: theme.spacing[2],
+  },
+  sectionFill: {
+    flex: 1,
+    minHeight: 0,
+    gap: theme.spacing[2],
+  },
+  sectionTitle: {
+    fontSize: theme.fontSize.sm,
+    fontWeight: "600",
+    color: theme.colors.foregroundMuted,
+    textTransform: "uppercase",
+    letterSpacing: 0.5,
+  },
+  commandList: {
+    gap: theme.spacing[2],
+  },
+  commandRow: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: theme.spacing[2],
+    borderRadius: theme.borderRadius.md,
+    backgroundColor: theme.colors.surface1,
+    padding: theme.spacing[3],
+  },
+  commandIndex: {
+    width: 18,
+    fontSize: theme.fontSize.sm,
+    color: theme.colors.foregroundMuted,
+  },
+  commandTextColumn: {
+    flex: 1,
+    gap: theme.spacing[1],
+  },
+  commandText: {
+    fontFamily: Fonts.mono,
+    fontSize: theme.fontSize.sm,
+    color: theme.colors.foreground,
+  },
+  commandMeta: {
+    fontSize: theme.fontSize.xs,
+    color: theme.colors.foregroundMuted,
+  },
+  logContainer: {
+    flex: 1,
+    minHeight: 0,
+    borderRadius: theme.borderRadius.lg,
+    backgroundColor: theme.colors.surface1,
+  },
+  logContent: {
+    padding: theme.spacing[3],
+  },
+  logText: {
+    fontFamily: Fonts.mono,
+    fontSize: theme.fontSize.sm,
+    lineHeight: 20,
+    color: theme.colors.foreground,
+  },
+  emptyCard: {
+    borderRadius: theme.borderRadius.lg,
+    backgroundColor: theme.colors.surface1,
+    padding: theme.spacing[3],
+  },
+  emptyText: {
+    fontSize: theme.fontSize.sm,
+    color: theme.colors.foregroundMuted,
+  },
+}));
@@ -79,6 +79,9 @@ function getFallbackTabLabel(tab: WorkspaceTabDescriptor): string {
  if (tab.target.kind === "draft") {
    return "New Agent";
  }
+  if (tab.target.kind === "setup") {
+    return "Setup";
+  }
  if (tab.target.kind === "terminal") {
    return "Terminal";
  }
@@ -139,6 +139,9 @@ function getFallbackTabOptionLabel(tab: WorkspaceTabDescriptor): string {
  if (tab.target.kind === "draft") {
    return "New Agent";
  }
+  if (tab.target.kind === "setup") {
+    return "Setup";
+  }
  if (tab.target.kind === "terminal") {
    return "Terminal";
  }
@@ -152,6 +155,9 @@ function getFallbackTabOptionDescription(tab: WorkspaceTabDescriptor): string {
  if (tab.target.kind === "draft") {
    return "New Agent";
  }
+  if (tab.target.kind === "setup") {
+    return "Workspace setup";
+  }
  if (tab.target.kind === "agent") {
    return "Agent";
  }
@@ -76,6 +76,9 @@ function getCloseButtonTestId(tab: WorkspaceTabDescriptor): string {
  if (tab.target.kind === "draft") {
    return `workspace-draft-close-${tab.target.draftId}`;
  }
+  if (tab.target.kind === "setup") {
+    return `workspace-setup-close-${encodeFilePathForPathSegment(tab.target.workspaceId)}`;
+  }
  return `workspace-file-close-${encodeFilePathForPathSegment(tab.target.path)}`;
 }

@@ -0,0 +1,72 @@
+import type { SessionOutboundMessage } from "@server/shared/messages";
+import { create } from "zustand";
+import { buildWorkspaceTabPersistenceKey } from "@/stores/workspace-tabs-store";
+
+export type WorkspaceSetupProgressPayload = Extract<
+  SessionOutboundMessage,
+  { type: "workspace_setup_progress" }
+>["payload"];
+
+export interface WorkspaceSetupSnapshot extends WorkspaceSetupProgressPayload {
+  updatedAt: number;
+}
+
+interface WorkspaceSetupStoreState {
+  snapshots: Record<string, WorkspaceSetupSnapshot>;
+  upsertProgress: (input: { serverId: string; payload: WorkspaceSetupProgressPayload }) => void;
+  removeWorkspace: (input: { serverId: string; workspaceId: string }) => void;
+  clearServer: (serverId: string) => void;
+}
+
+function buildWorkspaceSetupKey(input: {
+  serverId: string;
+  workspaceId: string;
+}): string | null {
+  return buildWorkspaceTabPersistenceKey(input);
+}
+
+export const useWorkspaceSetupStore = create<WorkspaceSetupStoreState>()((set) => ({
+  snapshots: {},
+  upsertProgress: ({ serverId, payload }) => {
+    const key = buildWorkspaceSetupKey({ serverId, workspaceId: payload.workspaceId });
+    if (!key) {
+      return;
+    }
+
+    set((state) => ({
+      snapshots: {
+        ...state.snapshots,
+        [key]: {
+          ...payload,
+          updatedAt: Date.now(),
+        },
+      },
+    }));
+  },
+  removeWorkspace: ({ serverId, workspaceId }) => {
+    const key = buildWorkspaceSetupKey({ serverId, workspaceId });
+    if (!key) {
+      return;
+    }
+
+    set((state) => {
+      if (!(key in state.snapshots)) {
+        return state;
+      }
+      const next = { ...state.snapshots };
+      delete next[key];
+      return { snapshots: next };
+    });
+  },
+  clearServer: (serverId) => {
+    set((state) => {
+      const nextEntries = Object.entries(state.snapshots).filter(
+        ([key]) => !key.startsWith(`${serverId}:`),
+      );
+      if (nextEntries.length === Object.keys(state.snapshots).length) {
+        return state;
+      }
+      return { snapshots: Object.fromEntries(nextEntries) };
+    });
+  },
+}));
@@ -200,4 +200,19 @@ describe("workspace-tabs-store retargetTab", () => {
    expect(reopenedFileTabId).toBe(fileTabId);
    expect(useWorkspaceTabsStore.getState().focusedTabIdByWorkspace[workspaceKey]).toBe(fileTabId);
  });
+
+  it("builds a deterministic setup tab keyed by workspace id", () => {
+    const key = buildWorkspaceTabPersistenceKey({ serverId: SERVER_ID, workspaceId: WORKSPACE_ID });
+    expect(key).toBeTruthy();
+    const workspaceKey = key as string;
+
+    const tabId = useWorkspaceTabsStore.getState().openOrFocusTab({
+      serverId: SERVER_ID,
+      workspaceId: WORKSPACE_ID,
+      target: { kind: "setup", workspaceId: WORKSPACE_ID },
+    });
+
+    expect(tabId).toBe(`setup_${WORKSPACE_ID}`);
+    expect(useWorkspaceTabsStore.getState().focusedTabIdByWorkspace[workspaceKey]).toBe(tabId);
+  });
 });
@@ -6,7 +6,8 @@ export type WorkspaceTabTarget =
  | { kind: "draft"; draftId: string }
  | { kind: "agent"; agentId: string }
  | { kind: "terminal"; terminalId: string }
-  | { kind: "file"; path: string };
+  | { kind: "file"; path: string }
+  | { kind: "setup"; workspaceId: string };

 export type WorkspaceTab = {
  tabId: string;
@@ -60,6 +61,10 @@ function normalizeTabTarget(
    const path = trimNonEmpty(value.path);
    return path ? { kind: "file", path: path.replace(/\\/g, "/") } : null;
  }
+  if (value.kind === "setup") {
+    const workspaceId = trimNonEmpty(value.workspaceId);
+    return workspaceId ? { kind: "setup", workspaceId: workspaceId.replace(/\\/g, "/") } : null;
+  }
  return null;
 }

@@ -79,6 +84,9 @@ function tabTargetsEqual(left: WorkspaceTabTarget, right: WorkspaceTabTarget): b
  if (left.kind === "file" && right.kind === "file") {
    return left.path === right.path;
  }
+  if (left.kind === "setup" && right.kind === "setup") {
+    return left.workspaceId === right.workspaceId;
+  }
  return false;
 }

@@ -92,6 +100,9 @@ function buildDeterministicTabId(target: WorkspaceTabTarget): string {
  if (target.kind === "terminal") {
    return `terminal_${target.terminalId}`;
  }
+  if (target.kind === "setup") {
+    return `setup_${target.workspaceId}`;
+  }
  return `file_${target.path}`;
 }

@@ -82,6 +82,10 @@ describe("workspace route parsing", () => {
      kind: "file",
      path: "src/index.ts",
    });
+    expect(parseWorkspaceOpenIntent("setup:L3RtcC9yZXBv")).toEqual({
+      kind: "setup",
+      workspaceId: "/tmp/repo",
+    });
  });

  it("uses the plain workspace route when workspace context is provided", () => {
@@ -99,7 +99,8 @@ export type WorkspaceOpenIntent =
  | { kind: "agent"; agentId: string }
  | { kind: "terminal"; terminalId: string }
  | { kind: "file"; path: string }
-  | { kind: "draft"; draftId: string };
+  | { kind: "draft"; draftId: string }
+  | { kind: "setup"; workspaceId: string };

 export function parseWorkspaceOpenIntent(
  value: string | null | undefined,
@@ -136,6 +137,13 @@ export function parseWorkspaceOpenIntent(
    }
    return { kind: "file", path: decodedPath };
  }
+  if (kind === "setup") {
+    const workspaceId = decodeWorkspaceIdFromPathSegment(payload);
+    if (!workspaceId) {
+      return null;
+    }
+    return { kind: "setup", workspaceId };
+  }

  return null;
 }
@@ -22,6 +22,10 @@ export function normalizeWorkspaceTabTarget(
    const path = trimNonEmpty(value.path);
    return path ? { kind: "file", path: path.replace(/\\/g, "/") } : null;
  }
+  if (value.kind === "setup") {
+    const workspaceId = trimNonEmpty(value.workspaceId);
+    return workspaceId ? { kind: "setup", workspaceId: workspaceId.replace(/\\/g, "/") } : null;
+  }
  return null;
 }

@@ -44,6 +48,9 @@ export function workspaceTabTargetsEqual(
  if (left.kind === "file" && right.kind === "file") {
    return left.path === right.path;
  }
+  if (left.kind === "setup" && right.kind === "setup") {
+    return left.workspaceId === right.workspaceId;
+  }
  return false;
 }

@@ -57,6 +64,9 @@ export function buildDeterministicWorkspaceTabId(target: WorkspaceTabTarget): st
  if (target.kind === "terminal") {
    return `terminal_${target.terminalId}`;
  }
+  if (target.kind === "setup") {
+    return `setup_${target.workspaceId}`;
+  }
  return `file_${target.path}`;
 }