Add files using upload-large-folder tool

.github/dependabot.yml

@@ -0,0 +1,110 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:00"
+      timezone: "UTC"
+    cooldown:
+      default-days: 7
+    versioning-strategy: increase
+    open-pull-requests-limit: 10
+    commit-message:
+      prefix: chore
+      include: scope
+    labels:
+      - dependencies
+      - npm
+    # Group related packages together so they ship in a single PR.
+    # Packages that aren't matched by any group still get their own PR
+    # (the default behavior), which is what we want for high-impact deps
+    # like vite, react-router, framer-motion, etc.
+    groups:
+      tailwind:
+        patterns:
+          - "tailwindcss"
+          - "@tailwindcss/*"
+          - "tailwind-merge"
+          - "tailwind-scrollbar"
+      tanstack:
+        patterns:
+          - "@tanstack/*"
+      i18next:
+        patterns:
+          - "i18next"
+          - "i18next-*"
+          - "react-i18next"
+          - "eslint-plugin-i18next"
+      react:
+        patterns:
+          - "react"
+          - "react-dom"
+          - "@types/react"
+          - "@types/react-dom"
+          - "@types/react-*"
+          - "eslint-plugin-react"
+          - "eslint-plugin-react-hooks"
+      react-router:
+        patterns:
+          - "react-router"
+          - "@react-router/*"
+          - "@vercel/react-router"
+          - "isbot"
+      testing:
+        patterns:
+          - "vitest"
+          - "@vitest/*"
+          - "@testing-library/*"
+          - "jsdom"
+          - "@playwright/test"
+          - "msw"
+          - "@mswjs/*"
+      eslint:
+        patterns:
+          - "eslint"
+          - "eslint-config-*"
+          - "eslint-plugin-*"
+          - "@typescript-eslint/*"
+          - "prettier"
+        exclude-patterns:
+          # These are grouped under their feature area instead.
+          - "eslint-plugin-i18next"
+          - "eslint-plugin-react"
+          - "eslint-plugin-react-hooks"
+      monaco:
+        patterns:
+          - "monaco-editor"
+          - "@monaco-editor/*"
+      xterm:
+        patterns:
+          - "@xterm/*"
+      types:
+        patterns:
+          - "@types/*"
+        exclude-patterns:
+          - "@types/react"
+          - "@types/react-dom"
+          - "@types/react-*"
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+      time: "09:00"
+      timezone: "UTC"
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: ci
+      include: scope
+    labels:
+      - dependencies
+      - github-actions
+    groups:
+      actions:
+        patterns:
+          - "*"

.github/pull_request_template.md

@@ -0,0 +1,65 @@
+<!-- Keep this PR as draft until it is ready for review. -->
+
+HUMAN:
+
+<!-- Human contributors: add a short note about your testing. -->
+
+---
+
+AGENT:
+
+<!-- AI/LLM agents:
+Do not edit the HUMAN section.
+Write a concise summary of what changed and link any reviewer artifacts, such
+as files under `.pr/`. For HTML artifacts, include a rendered preview link:
+https://htmlpreview.github.io/?https://github.com/<owner>/<repo>/blob/<branch>/.pr/<file>.html
+In this AGENT section and the template fields below, provide evidence that the
+code runs properly end-to-end. Just running unit tests is NOT sufficient. Explain
+exactly what command you ran and include logs, screenshots, or reproduction notes.
+-->
+
+## Why
+
+<!-- Describe problem, motivation, etc. -->
+
+## Summary
+
+<!-- 1-3 bullets describing what changed. -->
+-
+
+## Issue Number
+<!-- Required. The linked issue must carry the `ready-for-dev` label, which
+means it has clear acceptance criteria (and, for bugs, reproduction evidence).
+If no such issue exists yet, open one using the Bug or Feature Request template
+and wait for it to be labeled `ready-for-dev` before opening this PR. -->
+Fixes #
+
+## How to Test
+
+<!--
+Required. Share the steps for the reviewer to be able to test your PR. e.g. You can test by running `npm install` then `npm build dev`.
+
+If you could not test this, say why.
+-->
+
+## Video/Screenshots
+
+<!--
+Provide a video or screenshots of testing your PR. e.g. you added a new feature to the gui, show us the video of you testing it successfully.
+
+For bug fixes: reproduction evidence is required. Show the bug reproduced (the
+error state) and then the result after your fix. A terminal screenshot or video
+is fine for non-UI bugs.
+-->
+
+## Type
+
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Refactor
+- [ ] Breaking change
+- [ ] Docs / chore
+
+## Notes
+
+<!-- Optional: migrations, config changes, rollout concerns, follow-ups, or anything reviewers should know. -->

.github/release.yml

@@ -0,0 +1,14 @@
+changelog:
+  categories:
+    - title: Features
+      labels: ["type: feat"]
+    - title: Bug Fixes
+      labels: ["type: fix"]
+    - title: Performance
+      labels: ["type: perf"]
+    - title: Documentation
+      labels: ["type: docs"]
+    - title: Maintenance
+      labels: ["type: chore", "type: build", "type: ci", "type: refactor", "type: style", "type: test", "type: revert"]
+    - title: Other Changes
+      labels: ["*"]

__tests__/MSW.md

@@ -0,0 +1,134 @@
+# Mock Service Worker (MSW) Guide
+
+## Overview
+
+[Mock Service Worker (MSW)](https://mswjs.io/) is an API mocking library that intercepts outgoing network requests at the network level. Unlike traditional mocking that patches `fetch` or `axios`, MSW uses a Service Worker in the browser and direct request interception in Node.js—making mocks transparent to your application code.
+
+We use MSW in this project for:
+- **Testing**: Write reliable unit and integration tests without real network calls
+- **Development**: Run the frontend with mocked APIs when the backend isn't available or when working on features with pending backend APIs
+
+The same mock handlers work in both environments, so you write them once and reuse everywhere.
+
+## Relevant Files
+
+- `src/mocks/handlers.ts` - Main handler registry that combines all domain handlers
+- `src/mocks/*-handlers.ts` - Domain-specific handlers (auth, conversation, etc.)
+- `src/mocks/browser.ts` - Browser setup for development mode
+- `src/mocks/node.ts` - Node.js setup for tests
+- `vitest.setup.ts` - Global test setup with MSW lifecycle hooks
+
+## Development Workflow
+
+### Running with Mocked APIs
+
+```sh
+# Run with API mocking enabled
+npm run dev:mock
+```
+
+This command sets `VITE_MOCK_API=true` which activates the MSW Service Worker to intercept requests.
+
+
+## Writing Tests
+
+### Service Layer Mocking (Recommended)
+
+For most tests, mock at the service layer using `vi.spyOn`. This approach is explicit, test-scoped, and makes the scenario being tested clear.
+
+```typescript
+import { vi } from "vitest";
+import SettingsService from "#/api/settings-service/settings-service.api";
+
+const getSettingsSpy = vi.spyOn(SettingsService, "getSettings");
+getSettingsSpy.mockResolvedValue({
+  llm_model: "openai/gpt-4o",
+  llm_api_key_set: true,
+  // ... other settings
+});
+```
+
+Use `mockResolvedValue` for success scenarios and `mockRejectedValue` for error scenarios:
+
+```typescript
+getSettingsSpy.mockRejectedValue(new Error("Failed to fetch settings"));
+```
+
+### Network Layer Mocking (Advanced)
+
+For tests that need actual network-level behavior (WebSockets, testing retry logic, etc.), use `server.use()` to override handlers per test.
+
+> [!IMPORTANT]
+> **Reuse the global server instance** - Don't create new `setupServer()` calls in individual tests. The project already has a global MSW server configured in `vitest.setup.ts` that handles lifecycle (`server.listen()`, `server.resetHandlers()`, `server.close()`). Use `server.use()` to add runtime handlers for specific test scenarios.
+
+```typescript
+import { http, HttpResponse } from "msw";
+import { server } from "#/mocks/node";
+
+it("should handle server errors", async () => {
+  server.use(
+    http.get("/api/my-endpoint", () => {
+      return new HttpResponse(null, { status: 500 });
+    }),
+  );
+  // ... test code
+});
+```
+
+For WebSocket testing, see `__tests__/helpers/msw-websocket-setup.ts` for utilities.
+
+## Adding New API Mocks
+
+When adding new API endpoints, create mocks in both places to maintain 1:1 similarity with the backend:
+
+### 1. Add to `src/mocks/` (for development)
+
+Create or update a domain-specific handler file:
+
+```typescript
+// src/mocks/my-feature-handlers.ts
+import { http, HttpResponse } from "msw";
+
+export const MY_FEATURE_HANDLERS = [
+  http.get("/api/my-feature", () => {
+    return HttpResponse.json({
+      data: "mock response",
+    });
+  }),
+];
+```
+
+Register in `handlers.ts`:
+
+```typescript
+import { MY_FEATURE_HANDLERS } from "./my-feature-handlers";
+
+export const handlers = [
+  // ... existing handlers
+  ...MY_FEATURE_HANDLERS,
+];
+```
+
+### 2. Mock in tests for specific scenarios
+
+In your test files, spy on the service method to control responses per test case:
+
+```typescript
+import { vi } from "vitest";
+import MyFeatureService from "#/api/my-feature-service.api";
+
+const spy = vi.spyOn(MyFeatureService, "getData");
+spy.mockResolvedValue({ data: "test-specific response" });
+```
+
+See `__tests__/routes/llm-settings.test.tsx` for a real-world example of service layer mocking.
+
+> [!TIP]
+> For guidance on creating service APIs, see `src/api/README.md`.
+
+## Best Practices
+
+- **Keep mocks close to real API contracts** - Update mocks when backend changes
+- **Use service layer mocking for most tests** - It's simpler and more explicit
+- **Reserve network layer mocking for integration tests** - WebSockets, retry logic, etc.
+- **Export mock data from handler files** - Reuse in tests (e.g., `MOCK_DEFAULT_USER_SETTINGS`)

__tests__/agent-server-ui-providers.test.tsx

@@ -0,0 +1,279 @@
+import React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { QueryClient, useQueryClient } from "@tanstack/react-query";
+import { createInstance } from "i18next";
+import { initReactI18next, useTranslation } from "react-i18next";
+
+vi.mock("react-i18next", async (importOriginal) =>
+  importOriginal<typeof import("react-i18next")>(),
+);
+
+import {
+  AGENT_SERVER_UI_SCOPE_SELECTOR,
+  AgentServerUIRoot,
+  AgentServerUIProviders,
+  OPENHANDS_I18N_NAMESPACE,
+  getDefaultI18n,
+  getDefaultQueryClient,
+  getI18n,
+  getQueryClient,
+  queryClient,
+  setI18n,
+  setQueryClient,
+} from "#/index";
+import i18n from "#/i18n";
+
+const telemetryProviderMock = vi.hoisted(() => vi.fn());
+vi.mock("#/components/providers/telemetry-provider", () => ({
+  TelemetryProvider: (props: {
+    children: React.ReactNode;
+    config?: unknown;
+  }) => {
+    telemetryProviderMock(props);
+    return props.children;
+  },
+}));
+
+const BaseProbe = ({ translation }: { translation?: string }) => {
+  const currentQueryClient = useQueryClient();
+
+  return (
+    <div>
+      <div data-testid="query-client-kind">
+        {currentQueryClient === getDefaultQueryClient() ? "default" : "custom"}
+      </div>
+      <div data-testid="query-client-value">
+        {String(queryClient.getQueryData(["provider-probe"]))}
+      </div>
+      {translation && <div data-testid="translation-value">{translation}</div>}
+      <div data-testid="imperative-translation-value">
+        {i18n.t("PROVIDER$LABEL")}
+      </div>
+    </div>
+  );
+};
+
+const DefaultProbe = () => <BaseProbe />;
+
+const CustomProbe = () => {
+  const { t } = useTranslation(OPENHANDS_I18N_NAMESPACE);
+
+  return <BaseProbe translation={t("PROVIDER$LABEL")} />;
+};
+
+const createTestI18n = async (value: string) => {
+  const instance = createInstance();
+
+  await instance.use(initReactI18next).init({
+    lng: "en",
+    fallbackLng: "en",
+    ns: ["host", OPENHANDS_I18N_NAMESPACE],
+    defaultNS: "host",
+    interpolation: { escapeValue: false },
+    resources: {
+      en: {
+        host: {
+          PROVIDER$LABEL: "Host provider",
+        },
+        [OPENHANDS_I18N_NAMESPACE]: {
+          PROVIDER$LABEL: value,
+        },
+      },
+    },
+  });
+
+  return instance;
+};
+
+afterEach(() => {
+  cleanup();
+  getDefaultQueryClient().removeQueries({ queryKey: ["provider-probe"] });
+  setQueryClient();
+  setI18n();
+  vi.restoreAllMocks();
+});
+
+describe("AgentServerUIProviders", () => {
+  it("exports and uses the default query client and i18n instances when props are omitted", async () => {
+    const defaultI18n = getDefaultI18n();
+
+    defaultI18n.addResourceBundle(
+      "en",
+      OPENHANDS_I18N_NAMESPACE,
+      { PROVIDER$LABEL: "Default provider" },
+      true,
+      true,
+    );
+    await defaultI18n.changeLanguage("en");
+
+    getDefaultQueryClient().setQueryData(["provider-probe"], "default-client");
+
+    render(
+      <AgentServerUIProviders>
+        <DefaultProbe />
+      </AgentServerUIProviders>,
+    );
+
+    expect(screen.getByTestId("query-client-kind")).toHaveTextContent(
+      "default",
+    );
+    expect(screen.getByTestId("query-client-value")).toHaveTextContent(
+      "default-client",
+    );
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("imperative-translation-value"),
+      ).toHaveTextContent("Default provider");
+    });
+
+    expect(getQueryClient()).toBe(getDefaultQueryClient());
+  });
+
+  it("injects a custom query client and i18n instance without conflicting with imperative callers", async () => {
+    const customQueryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+      },
+    });
+    const customI18n = await createTestI18n("Custom provider");
+
+    customQueryClient.setQueryData(["provider-probe"], "custom-client");
+
+    const view = render(
+      <AgentServerUIProviders queryClient={customQueryClient} i18n={customI18n}>
+        <CustomProbe />
+      </AgentServerUIProviders>,
+    );
+
+    expect(screen.getByTestId("query-client-kind")).toHaveTextContent("custom");
+    expect(screen.getByTestId("query-client-value")).toHaveTextContent(
+      "custom-client",
+    );
+
+    await waitFor(() => {
+      expect(screen.getByTestId("translation-value")).toHaveTextContent(
+        "Custom provider",
+      );
+      expect(
+        screen.getByTestId("imperative-translation-value"),
+      ).toHaveTextContent("Custom provider");
+    });
+
+    expect(getQueryClient()).toBe(customQueryClient);
+    expect(getI18n()).toBe(customI18n);
+
+    view.unmount();
+
+    expect(getQueryClient()).toBe(getDefaultQueryClient());
+    expect(getI18n()).toBe(getDefaultI18n());
+  });
+
+  it("passes disabled and runtime analytics configuration to TelemetryProvider", () => {
+    telemetryProviderMock.mockClear();
+
+    const noAnalyticsView = render(
+      <AgentServerUIProviders>
+        <div data-testid="child">child</div>
+      </AgentServerUIProviders>,
+    );
+
+    expect(screen.getByTestId("child")).toHaveTextContent("child");
+    expect(telemetryProviderMock).toHaveBeenCalledWith(
+      expect.objectContaining({ config: false }),
+    );
+
+    noAnalyticsView.unmount();
+    telemetryProviderMock.mockClear();
+
+    const analytics = {
+      provider: "posthog" as const,
+      apiKey: "phc_embedded",
+      apiHost: "https://events.example.com",
+      uiHost: "https://posthog.example.com",
+    };
+
+    render(
+      <AgentServerUIProviders analytics={analytics}>
+        <div data-testid="child-with-analytics">child</div>
+      </AgentServerUIProviders>,
+    );
+
+    expect(telemetryProviderMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: {
+          apiKey: analytics.apiKey,
+          apiHost: analytics.apiHost,
+          uiHost: analytics.uiHost,
+        },
+      }),
+    );
+  });
+
+  it("wraps children in a scoped, customizable style root by default", () => {
+    const { unmount } = render(
+      <AgentServerUIProviders
+        contentClassName="min-h-screen"
+        styleOverrides={{ "--oh-color-base": "#010203" }}
+      >
+        <div data-testid="styled-child">child</div>
+      </AgentServerUIProviders>,
+    );
+
+    const scopeRoot = document.querySelector<HTMLDivElement>(
+      AGENT_SERVER_UI_SCOPE_SELECTOR,
+    );
+
+    expect(scopeRoot).toBeInTheDocument();
+    expect(scopeRoot?.style.getPropertyValue("--oh-color-base")).toBe(
+      "#010203",
+    );
+
+    const themedContainer =
+      scopeRoot?.firstElementChild as HTMLDivElement | null;
+    expect(themedContainer).toHaveAttribute("data-theme", "dark");
+    expect(themedContainer).toHaveClass("dark", "min-h-screen");
+    expect(themedContainer).toContainElement(
+      screen.getByTestId("styled-child"),
+    );
+
+    unmount();
+
+    render(
+      <AgentServerUIProviders withStyleRoot={false}>
+        <div data-testid="unstyled-child">child</div>
+      </AgentServerUIProviders>,
+    );
+
+    expect(document.querySelector(AGENT_SERVER_UI_SCOPE_SELECTOR)).toBeNull();
+  });
+
+  it("exposes a standalone style root for host-controlled customization", () => {
+    render(
+      <AgentServerUIRoot
+        className="outer-shell"
+        contentClassName="inner-shell"
+        theme="light"
+        styleOverrides={{ "--oh-color-primary": "#abcdef" }}
+      >
+        <div data-testid="root-child">child</div>
+      </AgentServerUIRoot>,
+    );
+
+    const scopeRoot = document.querySelector<HTMLDivElement>(
+      AGENT_SERVER_UI_SCOPE_SELECTOR,
+    );
+
+    expect(scopeRoot).toHaveClass("outer-shell");
+    expect(scopeRoot?.style.getPropertyValue("--oh-color-primary")).toBe(
+      "#abcdef",
+    );
+
+    const themedContainer =
+      scopeRoot?.firstElementChild as HTMLDivElement | null;
+    expect(themedContainer).toHaveAttribute("data-theme", "light");
+    expect(themedContainer).toHaveClass("light", "inner-shell");
+    expect(themedContainer).toContainElement(screen.getByTestId("root-child"));
+  });
+});

__tests__/agent-server-ui-style-scope.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import {
+  AGENT_SERVER_UI_SCOPE_SELECTOR,
+  transformAgentServerUISelector,
+} from "#/styles/agent-server-ui-style-scope";
+
+describe("transformAgentServerUISelector", () => {
+  it("prefixes ordinary selectors under the scoped root", () => {
+    expect(
+      transformAgentServerUISelector(
+        AGENT_SERVER_UI_SCOPE_SELECTOR,
+        ".button-base",
+        `${AGENT_SERVER_UI_SCOPE_SELECTOR} .button-base`,
+      ),
+    ).toBe(`${AGENT_SERVER_UI_SCOPE_SELECTOR} .button-base`);
+  });
+
+  it("replaces :host selectors with the scoped root", () => {
+    expect(
+      transformAgentServerUISelector(
+        AGENT_SERVER_UI_SCOPE_SELECTOR,
+        ":host",
+        `${AGENT_SERVER_UI_SCOPE_SELECTOR} :host`,
+      ),
+    ).toBe(AGENT_SERVER_UI_SCOPE_SELECTOR);
+  });
+
+  it.each([":root", "body", "html"])(
+    "maps %s selectors directly to the scoped root",
+    (selector) => {
+      expect(
+        transformAgentServerUISelector(
+          AGENT_SERVER_UI_SCOPE_SELECTOR,
+          selector,
+          `${AGENT_SERVER_UI_SCOPE_SELECTOR} ${selector}`,
+        ),
+      ).toBe(AGENT_SERVER_UI_SCOPE_SELECTOR);
+    },
+  );
+
+  it("does not double-prefix selectors that are already scoped", () => {
+    const selector = `${AGENT_SERVER_UI_SCOPE_SELECTOR} .xterm`;
+
+    expect(
+      transformAgentServerUISelector(
+        AGENT_SERVER_UI_SCOPE_SELECTOR,
+        selector,
+        `${AGENT_SERVER_UI_SCOPE_SELECTOR} ${selector}`,
+      ),
+    ).toBe(selector);
+  });
+});

__tests__/build-websocket-url.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { buildWebSocketUrl } from "#/utils/websocket-url";
+
+describe("buildWebSocketUrl", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("Basic URL construction", () => {
+    it("should build WebSocket URL with conversation ID and URL", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "localhost:3000",
+      });
+
+      const result = buildWebSocketUrl(
+        "conv-123",
+        "http://localhost:8080/api/conversations/conv-123",
+      );
+
+      expect(result).toBe("ws://localhost:8080/sockets/events/conv-123");
+    });
+
+    it("should use wss:// protocol when window.location.protocol is https:", () => {
+      vi.stubGlobal("location", {
+        protocol: "https:",
+        host: "localhost:3000",
+      });
+
+      const result = buildWebSocketUrl(
+        "conv-123",
+        "https://example.com:8080/api/conversations/conv-123",
+      );
+
+      expect(result).toBe("wss://example.com:8080/sockets/events/conv-123");
+    });
+
+    it("should use ws:// for external HTTP hosts when page is HTTP", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "localhost:3000",
+      });
+
+      const result = buildWebSocketUrl(
+        "conv-456",
+        "http://agent-server.com:9000/api/conversations/conv-456",
+      );
+
+      expect(result).toBe("ws://agent-server.com:9000/sockets/events/conv-456");
+    });
+
+    it("should use wss:// for external HTTPS hosts when page is HTTP", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "localhost:3000",
+      });
+
+      const result = buildWebSocketUrl(
+        "conv-456",
+        "https://agent-server.com:9000/api/conversations/conv-456",
+      );
+
+      expect(result).toBe(
+        "wss://agent-server.com:9000/sockets/events/conv-456",
+      );
+    });
+
+    it("should use ws:// for localhost when page is HTTP", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "localhost:3000",
+      });
+
+      const result = buildWebSocketUrl(
+        "conv-456",
+        "http://127.0.0.1:9000/api/conversations/conv-456",
+      );
+
+      expect(result).toBe("ws://127.0.0.1:9000/sockets/events/conv-456");
+    });
+  });
+
+  describe("Query parameters handling", () => {
+    beforeEach(() => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "localhost:3000",
+      });
+    });
+
+    it("should not include query parameters in the URL (handled by useWebSocket hook)", () => {
+      const result = buildWebSocketUrl(
+        "conv-123",
+        "http://localhost:8080/api/conversations/conv-123",
+      );
+
+      expect(result).toBe("ws://localhost:8080/sockets/events/conv-123");
+      expect(result).not.toContain("?");
+      expect(result).not.toContain("session_api_key");
+    });
+  });
+
+  describe("Fallback to window.location.host", () => {
+    it("should use window.location.host when conversation URL is null", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "fallback-host:4000",
+      });
+
+      const result = buildWebSocketUrl("conv-123", null);
+
+      expect(result).toBe("ws://fallback-host:4000/sockets/events/conv-123");
+    });
+
+    it("should use window.location.host when conversation URL is undefined", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "fallback-host:4000",
+      });
+
+      const result = buildWebSocketUrl("conv-123", undefined);
+
+      expect(result).toBe("ws://fallback-host:4000/sockets/events/conv-123");
+    });
+
+    it("should use window.location.host when conversation URL is relative path", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "fallback-host:4000",
+      });
+
+      const result = buildWebSocketUrl(
+        "conv-123",
+        "/api/conversations/conv-123",
+      );
+
+      expect(result).toBe("ws://fallback-host:4000/sockets/events/conv-123");
+    });
+
+    it("should use window.location.host when conversation URL is invalid", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "fallback-host:4000",
+      });
+
+      const result = buildWebSocketUrl("conv-123", "not-a-valid-url");
+
+      expect(result).toBe("ws://fallback-host:4000/sockets/events/conv-123");
+    });
+  });
+
+  describe("Edge cases", () => {
+    beforeEach(() => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "localhost:3000",
+      });
+    });
+
+    it("should return null when conversationId is undefined", () => {
+      const result = buildWebSocketUrl(
+        undefined,
+        "http://localhost:8080/api/conversations/conv-123",
+      );
+
+      expect(result).toBeNull();
+    });
+
+    it("should return null when conversationId is empty string", () => {
+      const result = buildWebSocketUrl(
+        "",
+        "http://localhost:8080/api/conversations/conv-123",
+      );
+
+      expect(result).toBeNull();
+    });
+
+    it("should handle conversation URLs with non-standard ports on external hosts", () => {
+      const result = buildWebSocketUrl(
+        "conv-123",
+        "http://example.com:12345/api/conversations/conv-123",
+      );
+
+      expect(result).toBe("ws://example.com:12345/sockets/events/conv-123");
+    });
+
+    it("should handle conversation URLs without port (default port) on external hosts", () => {
+      const result = buildWebSocketUrl(
+        "conv-123",
+        "http://example.com/api/conversations/conv-123",
+      );
+
+      expect(result).toBe("ws://example.com/sockets/events/conv-123");
+    });
+
+    it("should handle conversation IDs with special characters", () => {
+      const result = buildWebSocketUrl(
+        "conv-123-abc_def",
+        "http://localhost:8080/api/conversations/conv-123-abc_def",
+      );
+
+      expect(result).toBe(
+        "ws://localhost:8080/sockets/events/conv-123-abc_def",
+      );
+    });
+
+    it("should build URL without query parameters", () => {
+      const result = buildWebSocketUrl(
+        "conv-123",
+        "http://localhost:8080/api/conversations/conv-123",
+      );
+
+      expect(result).toBe("ws://localhost:8080/sockets/events/conv-123");
+      expect(result).not.toContain("?");
+    });
+  });
+
+  describe("protocol selection for external hosts", () => {
+    it("should use wss:// for HTTPS prod-runtime.all-hands.dev domains", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "localhost:8000",
+      });
+
+      // Use obviously fake IDs that follow the format pattern
+      const fakeConversationId = "00000000deadbeef0000000000000000";
+      const fakeRuntimeHost = "faketesthost.prod-runtime.all-hands.dev";
+
+      const result = buildWebSocketUrl(
+        fakeConversationId,
+        `https://${fakeRuntimeHost}/api/conversations/${fakeConversationId}`,
+      );
+
+      expect(result).toBe(
+        `wss://${fakeRuntimeHost}/sockets/events/${fakeConversationId}`,
+      );
+    });
+
+    it("should use ws:// for ::1 (IPv6 localhost)", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "[::1]:3000",
+      });
+
+      const result = buildWebSocketUrl(
+        "test-conv-ipv6",
+        "http://[::1]:8080/api/conversations/test-conv-ipv6",
+      );
+
+      expect(result).toBe("ws://[::1]:8080/sockets/events/test-conv-ipv6");
+    });
+
+    it("should use ws:// for .localhost subdomains", () => {
+      vi.stubGlobal("location", {
+        protocol: "http:",
+        host: "app.localhost:3000",
+      });
+
+      const result = buildWebSocketUrl(
+        "test-conv-localhost-subdomain",
+        "http://api.localhost:8080/api/conversations/test-conv-localhost-subdomain",
+      );
+
+      expect(result).toBe(
+        "ws://api.localhost:8080/sockets/events/test-conv-localhost-subdomain",
+      );
+    });
+  });
+});

__tests__/conversation-local-storage.test.ts

@@ -0,0 +1,692 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  clearConversationLocalStorage,
+  getConversationState,
+  isTaskConversationId,
+  setConversationState,
+  LOCAL_STORAGE_KEYS,
+} from "#/utils/conversation-local-storage";
+
+describe("conversation localStorage utilities", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  describe("isTaskConversationId", () => {
+    it("returns true for IDs starting with task-", () => {
+      expect(isTaskConversationId("task-abc-123")).toBe(true);
+      expect(isTaskConversationId("task-")).toBe(true);
+    });
+
+    it("returns false for normal conversation IDs", () => {
+      expect(isTaskConversationId("conv-123")).toBe(false);
+      expect(isTaskConversationId("abc")).toBe(false);
+    });
+  });
+
+  describe("getConversationState", () => {
+    it("returns default state including conversationMode for task IDs without reading localStorage", () => {
+      const state = getConversationState("task-uuid-123");
+
+      expect(state.conversationMode).toBe("code");
+      expect(state.selectedTab).toBe("files");
+      expect(
+        localStorage.getItem(
+          `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-task-uuid-123`,
+        ),
+      ).toBeNull();
+    });
+
+    it("returns merged state from localStorage for real conversation ID including conversationMode", () => {
+      const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-conv-1`;
+      localStorage.setItem(
+        key,
+        JSON.stringify({ conversationMode: "plan", selectedTab: "terminal" }),
+      );
+
+      const state = getConversationState("conv-1");
+
+      expect(state.conversationMode).toBe("plan");
+      expect(state.selectedTab).toBe("terminal");
+    });
+
+    it("round-trips rightPanelShown through localStorage", () => {
+      const conversationId = "conv-right-panel";
+      setConversationState(conversationId, {
+        selectedTab: "terminal",
+        rightPanelShown: true,
+        unpinnedTabs: ["browser"],
+      });
+
+      const state = getConversationState(conversationId);
+
+      expect(state.selectedTab).toBe("terminal");
+      expect(state.unpinnedTabs).toEqual(["browser"]);
+      expect(state.rightPanelShown).toBe(true);
+    });
+
+    it("defaults rightPanelShown to false and drops corrupt values", () => {
+      expect(getConversationState("conv-right-panel-default").rightPanelShown).toBe(
+        false,
+      );
+
+      const conversationId = "conv-right-panel-corrupt";
+      const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+      localStorage.setItem(
+        key,
+        JSON.stringify({
+          selectedTab: "terminal",
+          rightPanelShown: "yes",
+        }),
+      );
+
+      expect(getConversationState(conversationId).rightPanelShown).toBe(false);
+    });
+
+    it("returns default state when key is missing or invalid", () => {
+      expect(getConversationState("conv-missing").conversationMode).toBe(
+        "code",
+      );
+
+      const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-conv-bad`;
+      localStorage.setItem(key, "not json");
+      expect(getConversationState("conv-bad").conversationMode).toBe("code");
+    });
+  });
+
+  describe("setConversationState", () => {
+    it("does not persist when conversationId is a task ID", () => {
+      setConversationState("task-xyz", { conversationMode: "plan" });
+
+      expect(
+        localStorage.getItem(
+          `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-task-xyz`,
+        ),
+      ).toBeNull();
+    });
+
+    it("persists conversationMode for real conversation ID and getConversationState returns it", () => {
+      setConversationState("conv-2", { conversationMode: "plan" });
+
+      const state = getConversationState("conv-2");
+      expect(state.conversationMode).toBe("plan");
+    });
+  });
+
+  describe("clearConversationLocalStorage", () => {
+    it("removes the consolidated conversation-state localStorage entry", () => {
+      const conversationId = "conv-123";
+
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+      localStorage.setItem(
+        consolidatedKey,
+        JSON.stringify({
+          selectedTab: "editor",
+          unpinnedTabs: [],
+        }),
+      );
+
+      clearConversationLocalStorage(conversationId);
+
+      expect(localStorage.getItem(consolidatedKey)).toBeNull();
+    });
+
+    it("does not throw if conversation keys do not exist", () => {
+      expect(() => {
+        clearConversationLocalStorage("non-existent-id");
+      }).not.toThrow();
+    });
+  });
+
+  describe("getConversationState", () => {
+    it("returns default state with subConversationTaskId as null when no state exists", () => {
+      const conversationId = "conv-123";
+      const state = getConversationState(conversationId);
+
+      expect(state.subConversationTaskId).toBeNull();
+      expect(state.selectedTab).toBe("files");
+      expect(state.unpinnedTabs).toEqual([]);
+      expect(state.unpinnedOverviewSections).toEqual([]);
+      expect(state.unpinnedOverviewGitParts).toEqual([]);
+    });
+
+    it("persists and sanitizes unpinnedOverviewSections", () => {
+      const conversationId = "conv-overview-pins";
+      setConversationState(conversationId, {
+        unpinnedOverviewSections: ["skills", "not-a-section", "mcp", "workspace"],
+      });
+
+      const state = getConversationState(conversationId);
+      // Legacy section ids (mcp/skills/secrets/…) are dropped by the allowlist.
+      expect(state.unpinnedOverviewSections).toEqual(["workspace"]);
+    });
+
+    it("persists and sanitizes unpinnedOverviewGitParts", () => {
+      const conversationId = "conv-overview-git-pins";
+      setConversationState(conversationId, {
+        unpinnedOverviewGitParts: ["branch", "not-a-part", "issues"],
+      });
+
+      const state = getConversationState(conversationId);
+      // Legacy git part ids (issues) are dropped by the allowlist.
+      expect(state.unpinnedOverviewGitParts).toEqual(["branch"]);
+    });
+
+    it("retrieves subConversationTaskId from localStorage when it exists", () => {
+      const conversationId = "conv-123";
+      const taskId = "task-uuid-123";
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+      localStorage.setItem(
+        consolidatedKey,
+        JSON.stringify({
+          selectedTab: "editor",
+          unpinnedTabs: [],
+          subConversationTaskId: taskId,
+        }),
+      );
+
+      const state = getConversationState(conversationId);
+
+      expect(state.subConversationTaskId).toBe(taskId);
+    });
+
+    it("merges stored state with defaults when partial state exists", () => {
+      const conversationId = "conv-123";
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+      localStorage.setItem(
+        consolidatedKey,
+        JSON.stringify({
+          subConversationTaskId: "task-123",
+        }),
+      );
+
+      const state = getConversationState(conversationId);
+
+      expect(state.subConversationTaskId).toBe("task-123");
+      expect(state.selectedTab).toBe("files");
+      expect(state.unpinnedTabs).toEqual([]);
+    });
+
+    it("falls back to the default tab when stored selectedTab is no longer valid", () => {
+      const conversationId = "conv-123";
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+      // Persisted from a previous app version where "editor" was a tab.
+      localStorage.setItem(
+        consolidatedKey,
+        JSON.stringify({
+          selectedTab: "editor",
+          unpinnedTabs: [],
+        }),
+      );
+
+      const state = getConversationState(conversationId);
+
+      expect(state.selectedTab).toBe("files");
+    });
+
+    it("migrates a stored Diffs (changes) tab selection to Commits", () => {
+      const conversationId = "conv-123";
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+      localStorage.setItem(
+        consolidatedKey,
+        JSON.stringify({
+          selectedTab: "changes",
+          unpinnedTabs: [],
+        }),
+      );
+
+      const state = getConversationState(conversationId);
+
+      expect(state.selectedTab).toBe("commits");
+    });
+
+    it("filters obsolete tabs out of stored unpinnedTabs (editor / served / app / changes)", () => {
+      // Returning users may have unpinned the now-removed Editor, Served,
+      // App, or Diffs (`changes`) tabs in a previous version. Those names
+      // should not survive the read — otherwise they linger forever in
+      // localStorage since the UI has no way to surface them again to be
+      // re-pinned.
+      const conversationId = "conv-123";
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+      localStorage.setItem(
+        consolidatedKey,
+        JSON.stringify({
+          selectedTab: "files",
+          unpinnedTabs: ["editor", "changes", "served", "app", "terminal"],
+        }),
+      );
+
+      const state = getConversationState(conversationId);
+
+      // Obsolete names are dropped; still-valid `terminal` stays.
+      expect(state.unpinnedTabs).toEqual(["terminal"]);
+    });
+  });
+
+  describe("setConversationState", () => {
+    it("persists subConversationTaskId to localStorage", () => {
+      const conversationId = "conv-123";
+      const taskId = "task-uuid-456";
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+      setConversationState(conversationId, {
+        subConversationTaskId: taskId,
+      });
+
+      const stored = localStorage.getItem(consolidatedKey);
+      expect(stored).not.toBeNull();
+
+      const parsed = JSON.parse(stored!);
+      expect(parsed.subConversationTaskId).toBe(taskId);
+    });
+
+    it("merges subConversationTaskId with existing state", () => {
+      const conversationId = "conv-123";
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+      // Set initial state
+      localStorage.setItem(
+        consolidatedKey,
+        JSON.stringify({
+          selectedTab: "browser",
+          unpinnedTabs: ["tab-1"],
+          subConversationTaskId: "old-task-id",
+        }),
+      );
+
+      // Update only subConversationTaskId
+      setConversationState(conversationId, {
+        subConversationTaskId: "new-task-id",
+      });
+
+      const stored = localStorage.getItem(consolidatedKey);
+      const parsed = JSON.parse(stored!);
+
+      expect(parsed.subConversationTaskId).toBe("new-task-id");
+      expect(parsed.selectedTab).toBe("browser");
+      expect(parsed.unpinnedTabs).toEqual(["tab-1"]);
+    });
+
+    it("clears subConversationTaskId when set to null", () => {
+      const conversationId = "conv-123";
+      const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+      // Set initial state with task ID
+      localStorage.setItem(
+        consolidatedKey,
+        JSON.stringify({
+          subConversationTaskId: "task-123",
+        }),
+      );
+
+      // Clear the task ID
+      setConversationState(conversationId, {
+        subConversationTaskId: null,
+      });
+
+      const stored = localStorage.getItem(consolidatedKey);
+      const parsed = JSON.parse(stored!);
+
+      expect(parsed.subConversationTaskId).toBeNull();
+    });
+  });
+
+  describe("draftMessage persistence", () => {
+    describe("getConversationState", () => {
+      it("returns default draftMessage as null when no state exists", () => {
+        // Arrange
+        const conversationId = "conv-draft-1";
+
+        // Act
+        const state = getConversationState(conversationId);
+
+        // Assert
+        expect(state.draftMessage).toBeNull();
+      });
+
+      it("retrieves draftMessage from localStorage when it exists", () => {
+        // Arrange
+        const conversationId = "conv-draft-2";
+        const draftText = "This is my saved draft message";
+        const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+        localStorage.setItem(
+          consolidatedKey,
+          JSON.stringify({
+            draftMessage: draftText,
+          }),
+        );
+
+        // Act
+        const state = getConversationState(conversationId);
+
+        // Assert
+        expect(state.draftMessage).toBe(draftText);
+      });
+
+      it("returns null draftMessage for task conversation IDs (not persisted)", () => {
+        // Arrange
+        const taskId = "task-uuid-123";
+        const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${taskId}`;
+
+        // Even if somehow there's data in localStorage for a task ID
+        localStorage.setItem(
+          consolidatedKey,
+          JSON.stringify({
+            draftMessage: "Should not be returned",
+          }),
+        );
+
+        // Act
+        const state = getConversationState(taskId);
+
+        // Assert - should return default state, not the stored value
+        expect(state.draftMessage).toBeNull();
+      });
+    });
+
+    describe("setConversationState", () => {
+      it("persists draftMessage to localStorage", () => {
+        // Arrange
+        const conversationId = "conv-draft-3";
+        const draftText = "New draft message to save";
+        const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+        // Act
+        setConversationState(conversationId, {
+          draftMessage: draftText,
+        });
+
+        // Assert
+        const stored = localStorage.getItem(consolidatedKey);
+        expect(stored).not.toBeNull();
+        const parsed = JSON.parse(stored!);
+        expect(parsed.draftMessage).toBe(draftText);
+      });
+
+      it("does not persist draftMessage for task conversation IDs", () => {
+        // Arrange
+        const taskId = "task-draft-xyz";
+        const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${taskId}`;
+
+        // Act
+        setConversationState(taskId, {
+          draftMessage: "Draft for task ID",
+        });
+
+        // Assert - nothing should be stored
+        expect(localStorage.getItem(consolidatedKey)).toBeNull();
+      });
+
+      it("merges draftMessage with existing state without overwriting other fields", () => {
+        // Arrange
+        const conversationId = "conv-draft-4";
+        const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+        localStorage.setItem(
+          consolidatedKey,
+          JSON.stringify({
+            selectedTab: "terminal",
+            unpinnedTabs: ["tab-1", "tab-2"],
+            conversationMode: "plan",
+            subConversationTaskId: "task-123",
+          }),
+        );
+
+        // Act
+        setConversationState(conversationId, {
+          draftMessage: "Updated draft",
+        });
+
+        // Assert
+        const stored = localStorage.getItem(consolidatedKey);
+        const parsed = JSON.parse(stored!);
+
+        expect(parsed.draftMessage).toBe("Updated draft");
+        expect(parsed.selectedTab).toBe("terminal");
+        expect(parsed.unpinnedTabs).toEqual(["tab-1", "tab-2"]);
+        expect(parsed.conversationMode).toBe("plan");
+        expect(parsed.subConversationTaskId).toBe("task-123");
+      });
+
+      it("clears draftMessage when set to null", () => {
+        // Arrange
+        const conversationId = "conv-draft-5";
+        const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+        localStorage.setItem(
+          consolidatedKey,
+          JSON.stringify({
+            draftMessage: "Existing draft",
+          }),
+        );
+
+        // Act
+        setConversationState(conversationId, {
+          draftMessage: null,
+        });
+
+        // Assert
+        const stored = localStorage.getItem(consolidatedKey);
+        const parsed = JSON.parse(stored!);
+        expect(parsed.draftMessage).toBeNull();
+      });
+
+      it("clears draftMessage when set to empty string (stored as empty string)", () => {
+        // Arrange
+        const conversationId = "conv-draft-6";
+        const consolidatedKey = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+
+        localStorage.setItem(
+          consolidatedKey,
+          JSON.stringify({
+            draftMessage: "Existing draft",
+          }),
+        );
+
+        // Act
+        setConversationState(conversationId, {
+          draftMessage: "",
+        });
+
+        // Assert
+        const stored = localStorage.getItem(consolidatedKey);
+        const parsed = JSON.parse(stored!);
+        expect(parsed.draftMessage).toBe("");
+      });
+    });
+
+    describe("conversation-specific draft isolation", () => {
+      it("stores drafts separately for different conversations", () => {
+        // Arrange
+        const convA = "conv-A";
+        const convB = "conv-B";
+        const draftA = "Draft for conversation A";
+        const draftB = "Draft for conversation B";
+
+        // Act
+        setConversationState(convA, { draftMessage: draftA });
+        setConversationState(convB, { draftMessage: draftB });
+
+        // Assert
+        const stateA = getConversationState(convA);
+        const stateB = getConversationState(convB);
+
+        expect(stateA.draftMessage).toBe(draftA);
+        expect(stateB.draftMessage).toBe(draftB);
+      });
+
+      it("updating one conversation draft does not affect another", () => {
+        // Arrange
+        const convA = "conv-isolated-A";
+        const convB = "conv-isolated-B";
+
+        setConversationState(convA, { draftMessage: "Original draft A" });
+        setConversationState(convB, { draftMessage: "Original draft B" });
+
+        // Act - update only conversation A
+        setConversationState(convA, { draftMessage: "Updated draft A" });
+
+        // Assert - conversation B should be unchanged
+        const stateA = getConversationState(convA);
+        const stateB = getConversationState(convB);
+
+        expect(stateA.draftMessage).toBe("Updated draft A");
+        expect(stateB.draftMessage).toBe("Original draft B");
+      });
+
+      it("clearing one conversation draft does not affect another", () => {
+        // Arrange
+        const convA = "conv-clear-A";
+        const convB = "conv-clear-B";
+
+        setConversationState(convA, { draftMessage: "Draft A" });
+        setConversationState(convB, { draftMessage: "Draft B" });
+
+        // Act - clear draft for conversation A
+        setConversationState(convA, { draftMessage: null });
+
+        // Assert
+        const stateA = getConversationState(convA);
+        const stateB = getConversationState(convB);
+
+        expect(stateA.draftMessage).toBeNull();
+        expect(stateB.draftMessage).toBe("Draft B");
+      });
+    });
+  });
+
+  describe("filesTabDiffView preference", () => {
+    it("preserves filesTabDiffView from stored blobs on read", () => {
+      const conversationId = "files-diff-legacy";
+      localStorage.setItem(
+        `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`,
+        JSON.stringify({
+          selectedTab: "files",
+          filesTabDiffView: true,
+        }),
+      );
+
+      const state = getConversationState(conversationId);
+      expect(state.filesTabDiffView).toBe(true);
+    });
+  });
+
+  describe("filesTabContentViewMode persistence", () => {
+    // The rich/plain toggle for the file content viewer also persists
+    // per conversation. Default is "rich" — verified explicitly here so
+    // a careless change to the default field initializer doesn't slip
+    // through unnoticed (it would flip every existing user from rich to
+    // plain after deploy).
+
+    it("defaults to 'rich' when nothing is stored", () => {
+      const state = getConversationState("files-view-conv-1");
+      expect(state.filesTabContentViewMode).toBe("rich");
+    });
+
+    it("round-trips 'plain' through localStorage", () => {
+      const conversationId = "files-view-conv-2";
+      setConversationState(conversationId, {
+        filesTabContentViewMode: "plain",
+      });
+
+      expect(getConversationState(conversationId).filesTabContentViewMode).toBe(
+        "plain",
+      );
+
+      const raw = localStorage.getItem(
+        `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`,
+      );
+      expect(JSON.parse(raw as string).filesTabContentViewMode).toBe("plain");
+    });
+
+    it("round-trips 'rich' through localStorage (explicit save, not default)", () => {
+      const conversationId = "files-view-conv-3";
+      setConversationState(conversationId, {
+        filesTabContentViewMode: "rich",
+      });
+
+      expect(getConversationState(conversationId).filesTabContentViewMode).toBe(
+        "rich",
+      );
+    });
+
+    it("is isolated per conversation", () => {
+      setConversationState("files-view-convA", {
+        filesTabContentViewMode: "plain",
+      });
+      setConversationState("files-view-convB", {
+        filesTabContentViewMode: "rich",
+      });
+
+      expect(
+        getConversationState("files-view-convA").filesTabContentViewMode,
+      ).toBe("plain");
+      expect(
+        getConversationState("files-view-convB").filesTabContentViewMode,
+      ).toBe("rich");
+    });
+
+    it("falls back to the 'rich' default when localStorage holds a junk value", () => {
+      // A corrupted entry (older build with a renamed mode, a hand-edited
+      // value in devtools, …) must not leak through to the ViewMode-typed
+      // consumer — the sanitizer drops the bad value so the merged result
+      // re-applies the typed default.
+      const conversationId = "files-view-corrupt";
+      const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+      localStorage.setItem(
+        key,
+        JSON.stringify({ filesTabContentViewMode: "fancy" }),
+      );
+
+      const state = getConversationState(conversationId);
+      expect(state.filesTabContentViewMode).toBe("rich");
+    });
+  });
+
+  describe("files tab open-state / tree persistence", () => {
+    it("defaults to an expanded tree and no open files", () => {
+      const state = getConversationState("files-open-defaults");
+      expect(state.filesTabTreeVisible).toBe(true);
+      expect(state.filesTabOpenPaths).toEqual([]);
+      expect(state.filesTabSelectedPath).toBeNull();
+    });
+
+    it("round-trips tree visibility and open tabs", () => {
+      const conversationId = "files-open-roundtrip";
+      setConversationState(conversationId, {
+        filesTabTreeVisible: false,
+        filesTabOpenPaths: ["README.md", "src/main.ts"],
+        filesTabSelectedPath: "src/main.ts",
+      });
+
+      const state = getConversationState(conversationId);
+      expect(state.filesTabTreeVisible).toBe(false);
+      expect(state.filesTabOpenPaths).toEqual(["README.md", "src/main.ts"]);
+      expect(state.filesTabSelectedPath).toBe("src/main.ts");
+    });
+
+    it("sanitizes corrupt open-state fields", () => {
+      const conversationId = "files-open-corrupt";
+      const key = `${LOCAL_STORAGE_KEYS.CONVERSATION_STATE}-${conversationId}`;
+      localStorage.setItem(
+        key,
+        JSON.stringify({
+          filesTabTreeVisible: "yes",
+          filesTabOpenPaths: ["ok.ts", 12, "", null],
+          filesTabSelectedPath: { path: "nope" },
+        }),
+      );
+
+      const state = getConversationState(conversationId);
+      expect(state.filesTabTreeVisible).toBe(true);
+      expect(state.filesTabOpenPaths).toEqual(["ok.ts"]);
+      expect(state.filesTabSelectedPath).toBeNull();
+    });
+  });
+});

__tests__/initial-query.test.tsx

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { useInitialQueryStore } from "../src/stores/initial-query-store";
+
+describe("Initial Query Behavior", () => {
+  beforeEach(() => {
+    // Reset the store before each test
+    useInitialQueryStore.getState().reset();
+  });
+
+  it("should clear initial query when clearInitialPrompt is called", () => {
+    const { setInitialPrompt, clearInitialPrompt, initialPrompt } =
+      useInitialQueryStore.getState();
+
+    // Set up initial query in the store
+    setInitialPrompt("test query");
+    expect(useInitialQueryStore.getState().initialPrompt).toBe("test query");
+
+    // Clear the initial query
+    clearInitialPrompt();
+
+    // Verify initial query is cleared
+    expect(useInitialQueryStore.getState().initialPrompt).toBeNull();
+  });
+});

__tests__/library-entrypoints.test.ts

@@ -0,0 +1,49 @@
+import * as publicApi from "../src/index";
+import * as browserApi from "../src/components/browser/index";
+import * as conversationApi from "../src/components/conversation/index";
+import * as filesApi from "../src/components/files/index";
+import * as settingsApi from "../src/components/settings/index";
+import * as sidebarApi from "../src/components/sidebar/index";
+import * as terminalApi from "../src/components/terminal/index";
+import { describe, expect, it } from "vitest";
+
+describe("library public entrypoints", () => {
+  it("re-exports the primary library surface from the root entry", () => {
+    expect(publicApi.ConversationView).toBeTypeOf("function");
+    expect(publicApi.ChatPanel).toBeTypeOf("function");
+    expect(publicApi.TerminalPanel).toBeTypeOf("function");
+    expect(publicApi.BrowserPanel).toBeTypeOf("function");
+    expect(publicApi.FileExplorer).toBeTypeOf("function");
+    expect(publicApi.SettingsPanel).toBeTypeOf("function");
+    expect(publicApi.LLMSettings).toBeTypeOf("function");
+    expect(publicApi.Sidebar).toBeTypeOf("function");
+    expect(publicApi.ConversationPanel).toBeTypeOf("function");
+    expect(publicApi.AgentServerUIProviders).toBeTypeOf("function");
+    expect(publicApi.AgentServerUIRoot).toBeTypeOf("function");
+    expect(publicApi.AGENT_SERVER_UI_SCOPE_SELECTOR).toBe(
+      "[data-agent-server-ui]",
+    );
+    expect(publicApi.AGENT_SERVER_UI_DEFAULT_THEME).toBe("dark");
+  });
+
+  it("keeps each component-domain barrel importable", () => {
+    expect(conversationApi.ConversationView).toBeTypeOf("function");
+    expect(conversationApi.ChatPanel).toBeTypeOf("function");
+    expect(browserApi.BrowserPanel).toBeTypeOf("function");
+    expect(terminalApi.TerminalPanel).toBeTypeOf("function");
+    expect(filesApi.FileExplorer).toBeTypeOf("function");
+    expect(settingsApi.SettingsPanel).toBeTypeOf("function");
+    expect(settingsApi.AppSettings).toBeTypeOf("function");
+    expect(settingsApi.LLMSettings).toBeTypeOf("function");
+    expect(settingsApi.MCPSettings).toBeTypeOf("function");
+    expect(settingsApi.SecretsSettings).toBeTypeOf("function");
+    expect(sidebarApi.Sidebar).toBeTypeOf("function");
+    expect(sidebarApi.ConversationPanel).toBeTypeOf("function");
+  });
+
+  it("no longer exposes the removed AgentServerSettings entry", () => {
+    expect(
+      (settingsApi as Record<string, unknown>).AgentServerSettings,
+    ).toBeUndefined();
+  });
+});

__tests__/package-library.test.ts

@@ -0,0 +1,158 @@
+// @vitest-environment node
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const packageJson = JSON.parse(
+  readFileSync(resolve(__dirname, "../package.json"), "utf8"),
+) as {
+  name: string;
+  main: string;
+  module: string;
+  types: string;
+  exports: Record<string, unknown>;
+  scripts: Record<string, string>;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+const EXACT_SEMVER_PATTERN =
+  /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+describe("package library metadata", () => {
+  const ALLOWED_STACK_PIN_DEPS = new Set([
+    "@openhands/extensions",
+    "@openhands/typescript-client",
+  ]);
+
+  it("publishes the agent-canvas package entrypoints", () => {
+    expect(packageJson.name).toBe("@openhands/agent-canvas");
+    expect(packageJson.main).toBe("./dist/index.cjs");
+    expect(packageJson.module).toBe("./dist/index.js");
+    expect(packageJson.types).toBe("./dist/index.d.ts");
+    expect(packageJson.exports).toMatchObject({
+      ".": {
+        types: "./dist/index.d.ts",
+        import: "./dist/index.js",
+        require: "./dist/index.cjs",
+      },
+      "./conversation": {
+        types: "./dist/components/conversation/index.d.ts",
+        import: "./dist/components/conversation/index.js",
+        require: "./dist/components/conversation/index.cjs",
+      },
+      "./settings": {
+        types: "./dist/components/settings/index.d.ts",
+        import: "./dist/components/settings/index.js",
+        require: "./dist/components/settings/index.cjs",
+      },
+      "./terminal": {
+        types: "./dist/components/terminal/index.d.ts",
+        import: "./dist/components/terminal/index.js",
+        require: "./dist/components/terminal/index.cjs",
+      },
+      "./i18n": {
+        types: "./dist/i18n/index.d.ts",
+        import: "./dist/i18n/index.js",
+        require: "./dist/i18n/index.cjs",
+      },
+    });
+  });
+
+  // Git dependencies break `npm install -g` because npm clones the repo and
+  // runs the prepare script without devDependencies. All packages should be
+  // referenced from a registry. @openhands/extensions is allowed until it is
+  // published to npm; @openhands/typescript-client is temporarily allowed while
+  // this stacked PR waits for the subscription client branch to merge/release.
+  // TODO(#917): remove @openhands/typescript-client exemption once
+  // OpenHands/typescript-client#178 merges and publishes to npm.
+  it("does not use git dependencies except approved stack pins", () => {
+    const GIT_DEP_PATTERN =
+      /^(git[+:]|github:|bitbucket:|gitlab:|[a-zA-Z0-9_-]+\/)/;
+    const allDeps = {
+      ...packageJson.dependencies,
+      ...packageJson.devDependencies,
+    };
+
+    const violations = Object.entries(allDeps)
+      .filter(
+        ([name, version]) =>
+          GIT_DEP_PATTERN.test(version) && !ALLOWED_STACK_PIN_DEPS.has(name),
+      )
+      .map(([name, version]) => `${name}: ${version}`);
+
+    expect(violations).toEqual([]);
+  });
+
+  it("pins direct dependency versions exactly", () => {
+    const allDepsBySection = {
+      dependencies: packageJson.dependencies,
+      devDependencies: packageJson.devDependencies,
+    };
+
+    const violations = Object.entries(allDepsBySection).flatMap(
+      ([section, dependencies]) =>
+        Object.entries(dependencies ?? {})
+          .filter(
+            ([name, version]) =>
+              !EXACT_SEMVER_PATTERN.test(version) &&
+              !ALLOWED_STACK_PIN_DEPS.has(name),
+          )
+          .map(([name, version]) => `${section}.${name}: ${version}`),
+    );
+
+    expect(violations).toEqual([]);
+  });
+
+  it("prints startup guidance only for global installs", () => {
+    const runPostinstall = (isGlobal: boolean) => {
+      const env = { ...process.env };
+      if (isGlobal) {
+        env.npm_config_global = "true";
+      } else {
+        delete env.npm_config_global;
+      }
+
+      return spawnSync(packageJson.scripts.postinstall, {
+        encoding: "utf8",
+        env,
+        shell: true,
+      });
+    };
+
+    const dependencyInstall = runPostinstall(false);
+    const globalInstall = runPostinstall(true);
+
+    expect(dependencyInstall.status).toBe(0);
+    expect(dependencyInstall.stdout).toBe("");
+    expect(globalInstall.status).toBe(0);
+    expect(globalInstall.stdout).toContain("To start Agent Canvas, run:");
+  });
+
+  it("ships runtime logger dependencies for the published CLI", () => {
+    expect(packageJson.dependencies).toMatchObject({
+      winston: "3.19.0",
+      "winston-daily-rotate-file": "5.0.0",
+    });
+    expect(packageJson.devDependencies?.winston).toBeUndefined();
+    expect(
+      packageJson.devDependencies?.["winston-daily-rotate-file"],
+    ).toBeUndefined();
+  });
+
+  it("uses local dev commands without Docker", () => {
+    expect(packageJson.scripts.dev).toBe(
+      "node --env-file-if-exists=.env scripts/dev-with-automation.mjs",
+    );
+    expect(packageJson.scripts["dev:static"]).toBe(
+      "node --env-file-if-exists=.env scripts/dev-static.mjs",
+    );
+    expect(packageJson.scripts["dev:minimal"]).toBe(
+      "node --env-file-if-exists=.env scripts/dev-safe.mjs",
+    );
+    expect(packageJson.scripts["dev:docker"]).toBeUndefined();
+    expect(packageJson.scripts["dev:docker:dynamic"]).toBeUndefined();
+    expect(packageJson.scripts["dev:dangerously-dockerless"]).toBeUndefined();
+  });
+});

__tests__/query-client-config.behavior.test.ts

@@ -0,0 +1,522 @@
+import { QueryClient } from "@tanstack/react-query";
+import { AxiosError } from "axios";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createAgentServerQueryClient } from "#/query-client-config";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import type { Backend } from "#/api/backend-registry/types";
+import {
+  __resetHealthStoreForTests,
+  getBackendHealthEntry,
+  recordBackendFailure,
+} from "#/api/backend-registry/health-store";
+import * as ToastHandlers from "#/utils/custom-toast-handlers";
+
+interface ErrorOptions {
+  directStatus?: boolean;
+  message?: string;
+  status?: number;
+  url?: string;
+}
+
+function createAxiosError({
+  directStatus = false,
+  message = "Request failed",
+  status,
+  url,
+}: ErrorOptions = {}) {
+  const error = new AxiosError(
+    message,
+    "ERR_BAD_REQUEST",
+    url ? ({ url } as never) : undefined,
+    undefined,
+    !directStatus && status !== undefined ? ({ status } as never) : undefined,
+  );
+  error.status = directStatus ? status : undefined;
+  return error;
+}
+
+function createBackend(overrides: Partial<Backend> = {}): Backend {
+  return {
+    id: "local-backend",
+    name: "Local Backend",
+    host: "http://localhost:3000",
+    apiKey: "test-key",
+    kind: "local",
+    ...overrides,
+  };
+}
+
+function activateBackend(backend: Backend) {
+  const selection = { backendId: backend.id, orgId: null };
+  window.localStorage.setItem("openhands-backends", JSON.stringify([backend]));
+  window.localStorage.setItem(
+    "openhands-active-backend",
+    JSON.stringify(selection),
+  );
+  window.sessionStorage.setItem(
+    "openhands-active-backend",
+    JSON.stringify(selection),
+  );
+  __resetActiveStoreForTests();
+}
+
+function executeFailingQuery(
+  client: QueryClient,
+  error: unknown,
+  {
+    meta,
+    queryKey = ["behavior", "failure"],
+  }: {
+    meta?: Record<string, unknown>;
+    queryKey?: readonly unknown[];
+  } = {},
+) {
+  return client.fetchQuery({
+    queryKey,
+    queryFn: async () => {
+      throw error;
+    },
+    meta,
+    retry: false,
+  });
+}
+
+function executeFailingMutation(
+  client: QueryClient,
+  error: unknown,
+  meta?: Record<string, unknown>,
+) {
+  const mutation = client.getMutationCache().build(client, {
+    mutationFn: async () => {
+      throw error;
+    },
+    meta,
+    retry: false,
+  });
+  return mutation.execute(undefined);
+}
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  delete (window as typeof window & { __OH_QUERY_CLIENT__?: QueryClient })
+    .__OH_QUERY_CLIENT__;
+  __resetActiveStoreForTests();
+  __resetHealthStoreForTests();
+});
+
+describe("query client behavior", () => {
+  it("records successful queries for string backend identifiers only", async () => {
+    const client = createAgentServerQueryClient();
+    const malformedBackendId = 42;
+    const malformedMeta = { backendId: malformedBackendId } as unknown as {
+      backendId: string;
+    };
+    recordBackendFailure("backend-one", new Error("offline"));
+    recordBackendFailure(
+      malformedBackendId as unknown as string,
+      new Error("offline"),
+    );
+
+    await client.fetchQuery({
+      queryKey: ["health", "backend-one"],
+      queryFn: async () => "healthy",
+      meta: { backendId: "backend-one" },
+    });
+    await client.fetchQuery({
+      queryKey: ["health", "backend-two"],
+      queryFn: async () => "healthy",
+      meta: malformedMeta,
+    });
+    await client.fetchQuery({
+      queryKey: ["health", "unattributed"],
+      queryFn: async () => "healthy",
+    });
+
+    expect(getBackendHealthEntry("backend-one")).toBeNull();
+    expect(
+      getBackendHealthEntry(malformedBackendId as unknown as string),
+    ).not.toBeNull();
+  });
+
+  it.each([
+    { queryKey: ["settings"], description: "an unrelated query" },
+    { queryKey: ["user", "profile"], description: "another user query" },
+    {
+      queryKey: ["settings", "authenticated"],
+      description: "a non-user query ending in authenticated",
+    },
+  ])(
+    "invalidates authentication after a 401 from $description",
+    async ({ queryKey }) => {
+      const client = createAgentServerQueryClient();
+      const invalidateQueries = vi
+        .spyOn(client, "invalidateQueries")
+        .mockResolvedValue();
+      const error = createAxiosError({ status: 401 });
+
+      await expect(
+        executeFailingQuery(client, error, {
+          meta: { disableToast: true },
+          queryKey,
+        }),
+      ).rejects.toBe(error);
+
+      expect(invalidateQueries).toHaveBeenCalledWith({
+        queryKey: ["user", "authenticated"],
+      });
+    },
+  );
+
+  it("does not recursively invalidate authentication when that query fails", async () => {
+    const client = createAgentServerQueryClient();
+    const invalidateQueries = vi
+      .spyOn(client, "invalidateQueries")
+      .mockResolvedValue();
+    const error = createAxiosError({ status: 401 });
+
+    await expect(
+      executeFailingQuery(client, error, {
+        meta: { disableToast: true },
+        queryKey: ["user", "authenticated"],
+      }),
+    ).rejects.toBe(error);
+
+    expect(invalidateQueries).not.toHaveBeenCalled();
+  });
+
+  it("recognizes a direct Axios status when a mutation receives a 401", async () => {
+    const client = createAgentServerQueryClient();
+    const invalidateQueries = vi
+      .spyOn(client, "invalidateQueries")
+      .mockResolvedValue();
+    const error = createAxiosError({ directStatus: true, status: 401 });
+
+    await expect(
+      executeFailingMutation(client, error, { disableToast: true }),
+    ).rejects.toBe(error);
+
+    expect(invalidateQueries).toHaveBeenCalledWith({
+      queryKey: ["user", "authenticated"],
+    });
+  });
+
+  it("does not invalidate authentication for non-401 failures", async () => {
+    const client = createAgentServerQueryClient();
+    const invalidateQueries = vi
+      .spyOn(client, "invalidateQueries")
+      .mockResolvedValue();
+    const error = createAxiosError({ status: 500 });
+
+    await expect(
+      executeFailingQuery(client, error, { meta: { disableToast: true } }),
+    ).rejects.toBe(error);
+
+    expect(invalidateQueries).not.toHaveBeenCalled();
+  });
+
+  it("preserves null mutation failures without invalidating authentication", async () => {
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const invalidateQueries = vi
+      .spyOn(client, "invalidateQueries")
+      .mockResolvedValue();
+
+    await expect(executeFailingMutation(client, null)).rejects.toBeNull();
+
+    expect(invalidateQueries).not.toHaveBeenCalled();
+    expect(toast).toHaveBeenCalledWith(expect.any(String));
+  });
+
+  it.each([
+    {
+      directStatus: false,
+      url: undefined,
+      description: "has no request URL",
+    },
+    {
+      directStatus: false,
+      url: "https://cloud.example/api/conversations",
+      description: "targets the active cloud host",
+    },
+    {
+      directStatus: true,
+      url: "https://cloud.example/api/settings",
+      description: "reports 401 directly for the active cloud host",
+    },
+  ])(
+    "suppresses a cloud authentication toast when the request $description",
+    async ({ directStatus, url }) => {
+      activateBackend(
+        createBackend({
+          id: "cloud-backend",
+          name: "Cloud Backend",
+          host: "https://cloud.example///",
+          kind: "cloud",
+        }),
+      );
+      const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+      const client = createAgentServerQueryClient();
+      const error = createAxiosError({
+        directStatus,
+        message: "Cloud authentication failed",
+        status: 401,
+        url,
+      });
+
+      await expect(
+        executeFailingQuery(client, error, {
+          queryKey: ["cloud", url ?? "missing-url"],
+        }),
+      ).rejects.toBe(error);
+
+      expect(toast).not.toHaveBeenCalled();
+    },
+  );
+
+  it("shows a non-authentication error from the active cloud host", async () => {
+    activateBackend(
+      createBackend({
+        id: "cloud-backend",
+        host: "https://cloud.example",
+        kind: "cloud",
+      }),
+    );
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const error = createAxiosError({
+      message: "Cloud service unavailable",
+      status: 503,
+      url: "https://cloud.example/api/settings",
+    });
+
+    await expect(
+      executeFailingQuery(client, error, {
+        queryKey: ["cloud", "service-unavailable"],
+      }),
+    ).rejects.toBe(error);
+
+    expect(toast).toHaveBeenCalledWith("Cloud service unavailable");
+  });
+
+  it("shows a 401 toast when a cloud request targets another host", async () => {
+    activateBackend(
+      createBackend({
+        id: "cloud-backend",
+        host: "https://cloud.example",
+        kind: "cloud",
+      }),
+    );
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const error = createAxiosError({
+      message: "Foreign host authentication failed",
+      status: 401,
+      url: "https://different.example/api",
+    });
+
+    await expect(
+      executeFailingQuery(client, error, {
+        queryKey: ["cloud", "foreign-host"],
+      }),
+    ).rejects.toBe(error);
+
+    expect(toast).toHaveBeenCalledWith("Foreign host authentication failed");
+  });
+
+  it("shows a 401 toast for an active local backend", async () => {
+    activateBackend(createBackend());
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const error = createAxiosError({
+      message: "Local authentication failed",
+      status: 401,
+    });
+
+    await expect(
+      executeFailingQuery(client, error, {
+        queryKey: ["local", "authentication"],
+      }),
+    ).rejects.toBe(error);
+
+    expect(toast).toHaveBeenCalledWith("Local authentication failed");
+  });
+
+  it("deduplicates query toasts until the cooldown expires", async () => {
+    vi.useFakeTimers();
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const first = new AxiosError("Repeated query failure");
+    const second = new AxiosError("Repeated query failure");
+
+    await expect(
+      executeFailingQuery(client, first, {
+        queryKey: ["dedupe", "first"],
+      }),
+    ).rejects.toBe(first);
+    await expect(
+      executeFailingQuery(client, second, {
+        queryKey: ["dedupe", "second"],
+      }),
+    ).rejects.toBe(second);
+    expect(toast).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(3000);
+    const afterCooldown = new AxiosError("Repeated query failure");
+    await expect(
+      executeFailingQuery(client, afterCooldown, {
+        queryKey: ["dedupe", "after-cooldown"],
+      }),
+    ).rejects.toBe(afterCooldown);
+
+    expect(toast).toHaveBeenCalledTimes(2);
+  });
+
+  it("uses the translated generic query error when no message is available", async () => {
+    vi.useFakeTimers();
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const first = {};
+    const duplicate = {};
+
+    await expect(
+      executeFailingQuery(client, first, {
+        queryKey: ["generic", "first"],
+      }),
+    ).rejects.toBe(first);
+    await expect(
+      executeFailingQuery(client, duplicate, {
+        queryKey: ["generic", "duplicate"],
+      }),
+    ).rejects.toBe(duplicate);
+
+    expect(toast).toHaveBeenCalledWith(expect.any(String));
+    expect(toast).toHaveBeenCalledTimes(1);
+
+    await vi.advanceTimersByTimeAsync(3000);
+    const afterCooldown = {};
+    await expect(
+      executeFailingQuery(client, afterCooldown, {
+        queryKey: ["generic", "after-cooldown"],
+      }),
+    ).rejects.toBe(afterCooldown);
+
+    expect(toast).toHaveBeenCalledTimes(2);
+  });
+
+  it("honors mutation toast metadata", async () => {
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const visible = new AxiosError("Visible mutation failure");
+    const suppressed = new AxiosError("Suppressed mutation failure");
+
+    await expect(executeFailingMutation(client, visible)).rejects.toBe(visible);
+    await expect(
+      executeFailingMutation(client, suppressed, { disableToast: true }),
+    ).rejects.toBe(suppressed);
+
+    expect(toast).toHaveBeenCalledOnce();
+    expect(toast).toHaveBeenCalledWith("Visible mutation failure");
+  });
+
+  it("suppresses matching cloud-auth mutation errors", async () => {
+    activateBackend(
+      createBackend({
+        id: "cloud-backend",
+        host: "https://cloud.example",
+        kind: "cloud",
+      }),
+    );
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const error = createAxiosError({
+      message: "Cloud mutation authentication failed",
+      status: 401,
+      url: "https://cloud.example/api/settings",
+    });
+
+    await expect(executeFailingMutation(client, error)).rejects.toBe(error);
+
+    expect(toast).not.toHaveBeenCalled();
+  });
+
+  it("uses the translated generic mutation error when no message is available", async () => {
+    const toast = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+    const error = {};
+
+    await expect(executeFailingMutation(client, error)).rejects.toBe(error);
+
+    expect(toast).toHaveBeenCalledWith(expect.any(String));
+  });
+});
+
+describe("query client selection and proxy behavior", () => {
+  it("creates one default client and exposes it in development", async () => {
+    vi.resetModules();
+    const config = await import("#/query-client-config");
+
+    const first = config.getDefaultQueryClient();
+    const second = config.getDefaultQueryClient();
+
+    expect(first).toBeInstanceOf(QueryClient);
+    expect(second).toBe(first);
+    expect(config.getQueryClient()).toBe(first);
+    expect(
+      (window as typeof window & { __OH_QUERY_CLIENT__?: QueryClient })
+        .__OH_QUERY_CLIENT__,
+    ).toBe(first);
+  });
+
+  it("selects custom clients and forwards proxy reads, calls, and writes", async () => {
+    vi.resetModules();
+    const config = await import("#/query-client-config");
+    const custom = new QueryClient();
+
+    expect(config.setQueryClient(custom)).toBe(custom);
+    expect(config.getQueryClient()).toBe(custom);
+
+    config.queryClient.setQueryData(["proxy", "value"], "forwarded");
+    expect(custom.getQueryData(["proxy", "value"])).toBe("forwarded");
+
+    const extendedProxy = config.queryClient as QueryClient & {
+      marker?: string;
+    };
+    const extendedClient = custom as QueryClient & { marker?: string };
+    extendedProxy.marker = "proxy-write";
+    expect(extendedProxy.marker).toBe("proxy-write");
+    expect(extendedClient.marker).toBe("proxy-write");
+
+    expect(config.setQueryClient(undefined)).toBe(
+      config.getDefaultQueryClient(),
+    );
+    expect(config.setQueryClient(null)).toBe(config.getDefaultQueryClient());
+  });
+
+  it.each([
+    { mockApi: "true", expectedExposure: true },
+    { mockApi: "false", expectedExposure: false },
+  ])(
+    "sets window exposure to $expectedExposure outside development when VITE_MOCK_API is $mockApi",
+    async ({ expectedExposure, mockApi }) => {
+      vi.stubEnv("DEV", false);
+      vi.stubEnv("VITE_MOCK_API", mockApi);
+      vi.resetModules();
+      const config = await import("#/query-client-config");
+
+      const client = config.getDefaultQueryClient();
+      const exposed = (
+        window as typeof window & { __OH_QUERY_CLIENT__?: QueryClient }
+      ).__OH_QUERY_CLIENT__;
+
+      if (expectedExposure) {
+        expect(exposed).toBe(client);
+      } else {
+        expect(exposed).toBeUndefined();
+      }
+    },
+  );
+});

__tests__/query-client-config.test.ts

@@ -0,0 +1,92 @@
+import { AxiosError } from "axios";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createAgentServerQueryClient } from "#/query-client-config";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import * as ToastHandlers from "#/utils/custom-toast-handlers";
+
+afterEach(() => {
+  window.localStorage.clear();
+  window.sessionStorage.clear();
+  __resetActiveStoreForTests();
+  vi.restoreAllMocks();
+});
+
+describe("createAgentServerQueryClient", () => {
+  it("does not show a toast when query meta disables toasts", async () => {
+    const toastSpy = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+
+    await expect(
+      client.fetchQuery({
+        queryKey: ["config", "suppressed"],
+        queryFn: async () => {
+          throw new AxiosError("suppressed query error");
+        },
+        meta: { disableToast: true },
+        retry: false,
+      }),
+    ).rejects.toThrow("suppressed query error");
+
+    expect(toastSpy).not.toHaveBeenCalled();
+  });
+
+  it("shows a toast when query meta does not disable toasts", async () => {
+    const toastSpy = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const client = createAgentServerQueryClient();
+
+    await expect(
+      client.fetchQuery({
+        queryKey: ["config", "toast"],
+        queryFn: async () => {
+          throw new AxiosError("query error with toast");
+        },
+        retry: false,
+      }),
+    ).rejects.toThrow("query error with toast");
+
+    expect(toastSpy).toHaveBeenCalledWith("query error with toast");
+  });
+
+  it("does not show raw 401 toasts while the active cloud backend is logged out", async () => {
+    const toastSpy = vi.spyOn(ToastHandlers, "displayErrorToast");
+    const backend = {
+      id: "cloud-expired",
+      name: "OpenHands Cloud",
+      host: "https://app.all-hands.dev",
+      apiKey: "expired-token",
+      kind: "cloud",
+    };
+    window.localStorage.setItem(
+      "openhands-backends",
+      JSON.stringify([backend]),
+    );
+    window.localStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: backend.id, orgId: null }),
+    );
+    window.sessionStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: backend.id, orgId: null }),
+    );
+    __resetActiveStoreForTests();
+    const client = createAgentServerQueryClient();
+
+    await expect(
+      client.fetchQuery({
+        queryKey: ["cloud", "logged-out"],
+        queryFn: async () => {
+          throw new AxiosError(
+            "Request failed with status code 401",
+            "ERR_BAD_REQUEST",
+            undefined,
+            undefined,
+            { status: 401 } as never,
+          );
+        },
+        retry: false,
+      }),
+    ).rejects.toThrow("Request failed with status code 401");
+
+    expect(toastSpy).not.toHaveBeenCalled();
+  });
+});

__tests__/root.test.tsx

@@ -0,0 +1,926 @@
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createRoutesStub } from "react-router";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { http, HttpResponse } from "msw";
+import App, { links } from "#/root";
+import { server } from "#/mocks/node";
+import { __resetActiveStoreForTests } from "#/api/backend-registry/active-store";
+import { LOCKED_CLOUD_BACKEND_ID } from "#/api/backend-registry/default-backend";
+import { __resetHealthStoreForTests } from "#/api/backend-registry/health-store";
+import {
+  BACKEND_HEALTH_STORAGE_KEY,
+  MAX_CONSECUTIVE_FAILURES,
+} from "#/api/backend-registry/health-storage";
+import { CLOUD_BACKEND_LOGGED_OUT_ERROR } from "#/hooks/query/use-backends-health";
+import { ActiveBackendProvider } from "#/contexts/active-backend-context";
+import { ONBOARDING_COMPLETED_STORAGE_KEY } from "#/components/features/onboarding/use-onboarding-completion";
+
+const TRANSLATIONS: Record<string, string> = {
+  BACKEND$MANAGE_TITLE: "Manage backends",
+  BACKEND$RECONNECT_CLOUD_TITLE: "Reconnect to Cloud",
+  BACKEND$RECONNECT_CLOUD: "Reconnect to Cloud",
+  BACKEND$MANAGE_EMPTY: "No backends yet.",
+  BACKEND$ADD: "+ Add Backend",
+  BACKEND$LOG_BACK_IN: "Log back in",
+  BACKEND$LOGGED_OUT: "Logged out",
+  BACKEND$KIND_LOCAL: "Local",
+  BACKEND$KIND_CLOUD: "Cloud",
+  BACKEND$EDIT: "Edit",
+  BACKEND$REMOVE: "Remove",
+  HOME$DONE: "Done",
+};
+
+vi.mock("react-i18next", () => ({
+  useTranslation: () => ({
+    t: (key: string, options?: Record<string, string | number>) => {
+      let value = TRANSLATIONS[key] ?? key;
+      for (const [optionKey, optionValue] of Object.entries(options ?? {})) {
+        value = value.replaceAll(`{{${optionKey}}}`, String(optionValue));
+      }
+      return value;
+    },
+  }),
+}));
+
+vi.mock("#/components/features/onboarding/onboarding-modal", async () => {
+  const React = await import("react");
+  const { useNavigation } = await import("#/context/navigation-context");
+
+  return {
+    OnboardingModal: ({ onClose }: { onClose: () => void }) => {
+      const { navigate } = useNavigation();
+      return React.createElement(
+        "div",
+        { "data-testid": "onboarding-modal" },
+        React.createElement("div", {
+          "data-testid": "onboarding-step-check-backend",
+        }),
+        React.createElement(
+          "button",
+          {
+            type: "button",
+            "data-testid": "mock-onboarding-launch",
+            onClick: () => {
+              navigate("/conversations/mock-conversation");
+              onClose();
+            },
+          },
+          "Launch conversation",
+        ),
+      );
+    },
+  };
+});
+
+const ORIGINAL_LOCATION = window.location;
+
+const RouterStub = createRoutesStub([
+  {
+    Component: App,
+    path: "/",
+    children: [
+      {
+        Component: () => <div data-testid="app-outlet">app outlet</div>,
+        path: "/",
+      },
+      {
+        Component: () => (
+          <div data-testid="conversation-outlet">conversation outlet</div>
+        ),
+        path: "/conversations/:conversationId",
+      },
+    ],
+  },
+]);
+
+const renderApp = (initialEntries: string[] = ["/"]) =>
+  render(<RouterStub initialEntries={initialEntries} />, {
+    wrapper: ({ children }) => (
+      <QueryClientProvider
+        client={
+          new QueryClient({
+            defaultOptions: { queries: { retry: false } },
+          })
+        }
+      >
+        <ActiveBackendProvider>{children}</ActiveBackendProvider>
+      </QueryClientProvider>
+    ),
+  });
+
+const COOKIE_DEPLOYMENT_ORIGIN = "https://pr-254.staging.openhands.dev";
+
+/**
+ * Simulate an OHE-hosted Canvas: served from the locked Cloud host itself, so
+ * the single locked backend authenticates with the main-app session cookie.
+ * Returns the `window.location.assign` spy that observes login redirects.
+ */
+function mockLockedCookieDeployment() {
+  const assign = vi.fn();
+  Object.defineProperty(window, "location", {
+    configurable: true,
+    value: {
+      ...ORIGINAL_LOCATION,
+      origin: COOKIE_DEPLOYMENT_ORIGIN,
+      hostname: "pr-254.staging.openhands.dev",
+      pathname: "/canvas",
+      search: "",
+      hash: "",
+      assign,
+    },
+  });
+  vi.stubEnv("VITE_LOCK_TO_CLOUD", COOKIE_DEPLOYMENT_ORIGIN);
+  vi.stubEnv("VITE_SESSION_API_KEY", "");
+  delete (window as unknown as Record<string, unknown>)
+    .__AGENT_CANVAS_SESSION_API_KEY__;
+  __resetActiveStoreForTests();
+  return assign;
+}
+
+describe("App root agent-server availability guard", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    __resetHealthStoreForTests();
+    vi.unstubAllEnvs();
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_AUTH_REQUIRED__;
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_LOCK_TO_CLOUD__;
+    (
+      window as unknown as Record<string, unknown>
+    ).__AGENT_CANVAS_SESSION_API_KEY__ = "test-session-key";
+    __resetActiveStoreForTests();
+  });
+
+  afterEach(() => {
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      value: ORIGINAL_LOCATION,
+    });
+  });
+
+  it("shows first-run onboarding before the auth gate when public mode has no backend key", async () => {
+    vi.stubEnv("VITE_AUTH_REQUIRED", "true");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(
+      await screen.findByTestId("onboarding-step-check-backend"),
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("api-key-entry-screen"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows first-run onboarding before the recovery modal when no backend is configured", async () => {
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("agent-server-onboarding-screen"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("manage-backends-modal"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("lets root-level onboarding navigate to the launched conversation before closing", async () => {
+    server.use(
+      http.get("*/server_info", () =>
+        HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.28.1" }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    fireEvent.click(await screen.findByTestId("mock-onboarding-launch"));
+
+    await waitFor(() => {
+      expect(screen.getByTestId("conversation-outlet")).toBeInTheDocument();
+    });
+    expect(window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY)).toBe(
+      "1",
+    );
+    expect(
+      screen.queryByTestId("first-run-onboarding-screen"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows first-run onboarding before the recovery modal when locked to Cloud with no backend", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("agent-server-onboarding-screen"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("manage-backends-modal"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows first-run onboarding when locked to Cloud even if a session API key is baked in", async () => {
+    // Reproduces Hiep's report on PR #1389: a pre-built bundle with a baked-in
+    // VITE_SESSION_API_KEY plus --lock-to-cloud used to seed a disconnected
+    // Local backend, which skipped onboarding and landed on the Manage Backends
+    // recovery modal. Locked mode must not seed a Local backend, so onboarding
+    // still owns the first-run Cloud login.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "baked-session-key");
+    (
+      window as unknown as Record<string, unknown>
+    ).__AGENT_CANVAS_SESSION_API_KEY__ = "baked-session-key";
+    window.localStorage.clear();
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("agent-server-onboarding-screen"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("manage-backends-modal"),
+    ).not.toBeInTheDocument();
+    // No Local backend should have been seeded into the registry.
+    expect(window.localStorage.getItem("openhands-backends")).toBeNull();
+  });
+
+  it("shows first-run onboarding when locked to Cloud with a stale persisted Local backend", async () => {
+    // A Local backend persisted from a previous non-locked session must not
+    // bypass onboarding once the deployment is locked to Cloud.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    window.localStorage.setItem(
+      "openhands-backends",
+      JSON.stringify([
+        {
+          id: "default-local",
+          name: "Local",
+          host: "http://127.0.0.1:8000",
+          apiKey: "stale-key",
+          kind: "local",
+        },
+      ]),
+    );
+    window.localStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: "default-local", orgId: null }),
+    );
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("manage-backends-modal"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("forces first-run onboarding in locked mode even when a stale Local backend reports a configured LLM", async () => {
+    // Critical regression for PR #1389 review: in locked-to-Cloud mode the
+    // stale Local backend must not bypass onboarding, even when it happens
+    // to report a configured LLM. The user must be routed through the Cloud
+    // login / replacement flow instead.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    window.localStorage.setItem(
+      "openhands-backends",
+      JSON.stringify([
+        {
+          id: "user-added-local",
+          name: "My agent-server",
+          host: "http://127.0.0.1:8000",
+          apiKey: "stale-key",
+          kind: "local",
+        },
+      ]),
+    );
+    window.localStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: "user-added-local", orgId: null }),
+    );
+    __resetActiveStoreForTests();
+    server.use(
+      http.get("*/api/settings", () =>
+        HttpResponse.json({
+          llm_api_key_is_set: true,
+          agent_settings: {
+            llm: { model: "openai/gpt-5.5", api_key: "stored" },
+          },
+        }),
+      ),
+      http.get("*/server_info", () =>
+        HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.28.1" }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("manage-backends-modal"),
+    ).not.toBeInTheDocument();
+    // Backend readiness must NOT persist onboarding completion.
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("forces first-run onboarding in locked mode when a Cloud backend points at a different host with a configured LLM", async () => {
+    // Companion to the stale-Local test: a Cloud backend on a *different*
+    // host than the locked Cloud host must also be forced through
+    // onboarding, even if it reports a configured LLM. `kind === "cloud"`
+    // alone is not enough — the host must match the locked host.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    const otherCloud = {
+      id: "other-cloud",
+      name: "Other Cloud",
+      host: "https://other-cloud.example.com",
+      apiKey: "other-token",
+      kind: "cloud",
+    };
+    window.localStorage.setItem(
+      "openhands-backends",
+      JSON.stringify([otherCloud]),
+    );
+    window.localStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: otherCloud.id, orgId: null }),
+    );
+    __resetActiveStoreForTests();
+    server.use(
+      http.get("*/api/settings", () =>
+        HttpResponse.json({
+          llm_api_key_set: true,
+          agent_settings: {
+            llm: { model: "openai/gpt-5.5" },
+          },
+        }),
+      ),
+      http.get("*/server_info", () =>
+        HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.28.1" }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("shows first-run onboarding when locked to Cloud even if onboarding was previously completed", async () => {
+    // Reproduces hieptl's report on PR #1389: the user had previously
+    // completed onboarding in a non-locked session (so the
+    // `openhands-onboarded` localStorage flag is set), then relaunched the
+    // static server with --lock-to-cloud. The stale completion flag used to
+    // suppress first-run onboarding, so the app fell through to the Manage
+    // Backends recovery modal ("Add Backend") instead of going straight to
+    // Cloud login. In locked-to-Cloud mode the completion flag must not
+    // bypass onboarding when the active backend is not a connected Cloud
+    // backend.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    window.localStorage.clear();
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(
+      screen.queryByTestId("agent-server-onboarding-screen"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("manage-backends-modal"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows the auth gate after onboarding was already completed", async () => {
+    vi.stubEnv("VITE_AUTH_REQUIRED", "true");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    window.localStorage.clear();
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("api-key-entry-screen")).toBeInTheDocument();
+    });
+    expect(screen.queryByTestId("onboarding-modal")).not.toBeInTheDocument();
+  });
+
+  it("shows the manage-backends modal when the connected server reports an old version", async () => {
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    server.use(
+      http.get("*/server_info", () =>
+        HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.27.1" }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("agent-server-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+
+    await waitFor(() => {
+      expect(screen.getByTestId("manage-backends-modal")).toBeInTheDocument();
+    });
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+  });
+
+  it("shows the manage-backends modal when the server omits a version field", async () => {
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    server.use(
+      http.get("*/server_info", () =>
+        HttpResponse.json({ uptime: 0, idle_time: 0 }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("agent-server-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+  });
+
+  it("shows the manage-backends modal when the backend is unreachable", async () => {
+    let serverInfoRequests = 0;
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+
+    // Use "*" prefix to match both relative paths and absolute URLs (e.g.,
+    // http://127.0.0.1:8000/server_info) when VITE_BACKEND_BASE_URL is configured.
+    server.use(
+      http.get("*/server_info", () => {
+        serverInfoRequests += 1;
+        return HttpResponse.error();
+      }),
+    );
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("agent-server-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+
+    // The onboarding placeholder now hosts the Manage Backends modal
+    // directly so the user can edit/add a backend immediately. The
+    // modal additionally probes /server_info per registered backend
+    // for its status dot + version label, so the request count is
+    // bounded but greater than the single config probe.
+    await waitFor(() => {
+      expect(screen.getByTestId("manage-backends-modal")).toBeInTheDocument();
+    });
+    expect(serverInfoRequests).toBeGreaterThanOrEqual(1);
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+  });
+
+  it("shows the manage-backends recovery modal when the active cloud backend is logged out", async () => {
+    const cloudBackend = {
+      id: "cloud-expired",
+      name: "OpenHands Cloud",
+      host: "https://app.all-hands.dev",
+      apiKey: "expired-token",
+      kind: "cloud",
+    };
+    window.localStorage.setItem(
+      "openhands-backends",
+      JSON.stringify([cloudBackend]),
+    );
+    window.localStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: cloudBackend.id, orgId: null }),
+    );
+    window.sessionStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: cloudBackend.id, orgId: null }),
+    );
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    __resetActiveStoreForTests();
+    server.use(
+      http.get("https://app.all-hands.dev/api/keys/current", () =>
+        HttpResponse.json({ detail: "NoCredentialsError" }, { status: 401 }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("agent-server-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(screen.getByTestId("manage-backends-modal")).toBeInTheDocument();
+    expect(screen.getByText("Logged out")).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Log back in" }),
+    ).toBeInTheDocument();
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+  });
+
+  it("shows locked Cloud reconnect recovery without add-backend controls", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    const cloudBackend = {
+      id: "cloud-expired",
+      name: "OpenHands Cloud",
+      host: "https://app.all-hands.dev",
+      apiKey: "expired-token",
+      kind: "cloud",
+    };
+    window.localStorage.setItem(
+      "openhands-backends",
+      JSON.stringify([cloudBackend]),
+    );
+    window.localStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: cloudBackend.id, orgId: null }),
+    );
+    window.sessionStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: cloudBackend.id, orgId: null }),
+    );
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    __resetActiveStoreForTests();
+    server.use(
+      http.get("https://app.all-hands.dev/api/keys/current", () =>
+        HttpResponse.json({ detail: "NoCredentialsError" }, { status: 401 }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole("heading", { name: "Reconnect to Cloud" }),
+      ).toBeInTheDocument();
+    });
+    expect(screen.queryByTestId("manage-backends-add")).not.toBeInTheDocument();
+    expect(
+      screen.getByTestId("manage-backends-reconnect-cloud-login-button"),
+    ).toHaveTextContent("Reconnect to Cloud");
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+  });
+
+  it("renders the routed page when the agent server is reachable", async () => {
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("app-outlet")).toBeInTheDocument();
+    });
+
+    expect(
+      screen.queryByTestId("agent-server-onboarding-screen"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("shows first-run onboarding for the launcher-seeded default-local backend even when the agent-server reports a configured LLM", async () => {
+    // Regression for mock-llm-onboarding-regressions.spec.ts:16
+    // ("keeps the modal open on backdrop click and Escape") and
+    // mock-llm-auth-modes.spec.ts:57 ("reaches the onboarding modal
+    // without pre-seeded localStorage"). The shared mock-LLM
+    // agent-server retains a previously-configured LLM across browser
+    // sessions, so a genuinely fresh browser install (launcher-seeded
+    // default-local backend, no `openhands-onboarded` flag) must NOT
+    // have onboarding auto-marked complete by backend readiness.
+    vi.stubEnv("VITE_BACKEND_BASE_URL", "http://127.0.0.1:8000");
+    vi.stubEnv("VITE_SESSION_API_KEY", "test-session-key");
+    // The launcher-seeded default-local backend (id
+    // SEEDED_DEFAULT_BACKEND_ID) is created from these env stubs by
+    // readStoredBackends().
+    __resetActiveStoreForTests();
+    server.use(
+      http.get("*/api/settings", () =>
+        HttpResponse.json({
+          llm_api_key_is_set: true,
+          agent_settings: {
+            llm: { model: "openai/gpt-5.5", api_key: "stored" },
+          },
+        }),
+      ),
+      http.get("*/server_info", () =>
+        HttpResponse.json({ uptime: 0, idle_time: 0, version: "1.28.1" }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+
+    expect(
+      window.localStorage.getItem(ONBOARDING_COMPLETED_STORAGE_KEY),
+    ).toBeNull();
+  });
+
+  it("renders Cloud login directly for a fresh locked-to-Cloud first run", async () => {
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByTestId("first-run-onboarding-screen"),
+      ).toBeInTheDocument();
+    });
+
+    expect(await screen.findByTestId("onboarding-modal")).toBeInTheDocument();
+    expect(screen.getByTestId("add-backend-cloud-title")).toBeVisible();
+    expect(screen.getByTestId("add-backend-login-button")).toBeVisible();
+    expect(
+      screen.queryByTestId("onboarding-step-check-backend"),
+    ).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("onboarding-progress-bar"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("add-backend-close")).not.toBeInTheDocument();
+    expect(
+      screen.queryByTestId("add-backend-advanced-toggle"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+  });
+
+  it("redirects unauthenticated locked-cookie deployments to main app login", async () => {
+    const assign = vi.fn();
+    Object.defineProperty(window, "location", {
+      configurable: true,
+      value: {
+        ...ORIGINAL_LOCATION,
+        origin: "https://pr-254.staging.openhands.dev",
+        hostname: "pr-254.staging.openhands.dev",
+        pathname: "/canvas",
+        search: "?tab=home",
+        hash: "#top",
+        assign,
+      },
+    });
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://pr-254.staging.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    server.use(
+      http.post("*/api/authenticate", () =>
+        HttpResponse.json({ error: "unauthenticated" }, { status: 401 }),
+      ),
+    );
+    __resetActiveStoreForTests();
+
+    renderApp(["/"]);
+
+    await waitFor(() => {
+      expect(assign).toHaveBeenCalledWith(
+        "/login?returnTo=%2Fcanvas%3Ftab%3Dhome%23top",
+      );
+    });
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+  });
+
+  it("redirects to main app login when the cookie session expires after the Canvas loaded", async () => {
+    // Arrange: the session is valid at load, then expires — the Cloud probe
+    // starts returning 401 and the next main-app auth check confirms it.
+    const assign = mockLockedCookieDeployment();
+    let sessionExpired = false;
+    server.use(
+      http.post("*/api/authenticate", () =>
+        sessionExpired
+          ? HttpResponse.json({ error: "unauthenticated" }, { status: 401 })
+          : HttpResponse.json({ ok: true }),
+      ),
+      http.get(`${COOKIE_DEPLOYMENT_ORIGIN}/api/organizations`, () => {
+        sessionExpired = true;
+        return HttpResponse.json(
+          { detail: "Not authenticated" },
+          { status: 401 },
+        );
+      }),
+    );
+
+    // Act
+    renderApp(["/"]);
+
+    // Assert: main-app login, not the device-flow recovery modal.
+    await waitFor(() => {
+      expect(assign).toHaveBeenCalledWith("/login?returnTo=%2Fcanvas");
+    });
+    expect(
+      screen.queryByTestId("manage-backends-modal"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("app-outlet")).not.toBeInTheDocument();
+  });
+
+  it("keeps a valid cookie session on the app when a stale logged-out health entry is persisted", async () => {
+    // Arrange: a previous visit left the locked backend persisted as disabled
+    // and "Logged out", but the user has since logged back in on the main app.
+    const assign = mockLockedCookieDeployment();
+    window.localStorage.setItem(
+      BACKEND_HEALTH_STORAGE_KEY,
+      JSON.stringify({
+        [LOCKED_CLOUD_BACKEND_ID]: {
+          consecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+          lastError: CLOUD_BACKEND_LOGGED_OUT_ERROR,
+          lastFailureAt: 1,
+          disabled: true,
+        },
+      }),
+    );
+    __resetHealthStoreForTests();
+    server.use(
+      http.get(`${COOKIE_DEPLOYMENT_ORIGIN}/api/organizations`, () =>
+        HttpResponse.json({ items: [], current_org_id: null }),
+      ),
+    );
+
+    // Act
+    renderApp(["/"]);
+
+    // Assert: the stale health verdict must not bounce a valid session to
+    // /login (which would loop back via returnTo); the app renders instead.
+    await waitFor(() => {
+      expect(screen.getByTestId("app-outlet")).toBeInTheDocument();
+    });
+    expect(assign).not.toHaveBeenCalled();
+  });
+
+  it("hides first-run onboarding immediately after Cloud login completes in locked-to-Cloud mode (no flicker)", async () => {
+    // Regression for hieptl's flicker report on PR #1389: after Cloud
+    // login succeeds in locked-to-Cloud mode, the onboarding modal's
+    // onClose marks onboarding complete. The root first-run gate must
+    // honor that completion IMMEDIATELY — without waiting for the Cloud
+    // settings probe to confirm a configured LLM — so the first-run
+    // screen disappears and the routed app renders, rather than the
+    // modal flickering back via OnboardingHost. This test simulates the
+    // post-login state (active locked Cloud backend + completion flag
+    // set by the modal's onClose) with the Cloud settings probe
+    // reporting NO configured LLM, which is exactly the window where
+    // the old LLM-readiness gate kept the first-run screen mounted and
+    // caused the reopen.
+    vi.stubEnv("VITE_LOCK_TO_CLOUD", "https://app.all-hands.dev");
+    vi.stubEnv("VITE_SESSION_API_KEY", "");
+    delete (window as unknown as Record<string, unknown>)
+      .__AGENT_CANVAS_SESSION_API_KEY__;
+    const lockedCloud = {
+      id: "locked-cloud",
+      name: "OpenHands Cloud",
+      host: "https://app.all-hands.dev",
+      apiKey: "cloud-session-key",
+      kind: "cloud",
+    };
+    window.localStorage.setItem(
+      "openhands-backends",
+      JSON.stringify([lockedCloud]),
+    );
+    window.localStorage.setItem(
+      "openhands-active-backend",
+      JSON.stringify({ backendId: lockedCloud.id, orgId: null }),
+    );
+    // The onboarding modal's onClose (markCompleted) sets this right
+    // after Cloud login succeeds — before the Cloud settings probe
+    // resolves. Seed it to reproduce the post-login moment.
+    window.localStorage.setItem(ONBOARDING_COMPLETED_STORAGE_KEY, "1");
+    __resetActiveStoreForTests();
+    // Cloud settings probe reports no configured LLM. The completed
+    // onboarding flag should still hide first-run onboarding once the
+    // locked Cloud backend is active.
+    server.use(
+      http.get("https://app.all-hands.dev/api/v1/settings", () =>
+        HttpResponse.json({ llm_api_key_set: false }),
+      ),
+      http.get("https://app.all-hands.dev/api/keys/current", () =>
+        HttpResponse.json({ org_id: "org-1" }),
+      ),
+    );
+
+    renderApp(["/"]);
+
+    // The first-run onboarding screen must NOT be mounted (no reopen),
+    // and the routed app must render instead.
+    await waitFor(() => {
+      expect(screen.getByTestId("app-outlet")).toBeInTheDocument();
+    });
+    expect(
+      screen.queryByTestId("first-run-onboarding-screen"),
+    ).not.toBeInTheDocument();
+    expect(screen.queryByTestId("onboarding-modal")).not.toBeInTheDocument();
+  });
+});
+
+describe("App root document links", () => {
+  it("declares the SVG favicon used by the browser tab", () => {
+    // Act
+    const documentLinks = links();
+
+    // Assert
+    expect(documentLinks).toContainEqual({
+      rel: "icon",
+      type: "image/svg+xml",
+      href: "/favicon.svg",
+    });
+  });
+
+  it("prefixes document links when Canvas is mounted under a base path", () => {
+    // Arrange
+    vi.stubEnv("VITE_BASE_PATH", "/canvas");
+
+    // Act
+    const documentLinks = links();
+
+    // Assert
+    expect(documentLinks).toContainEqual({
+      rel: "icon",
+      type: "image/svg+xml",
+      href: "/canvas/favicon.svg",
+    });
+
+    vi.unstubAllEnvs();
+  });
+});

__tests__/router.md

@@ -0,0 +1,227 @@
+# Testing with React Router
+
+## Overview
+
+React Router components and hooks require a routing context to function. In tests, we need to provide this context while maintaining control over the routing state.
+
+This guide covers the two main approaches used in the OpenHands frontend:
+
+1. **`createRoutesStub`** - Creates a complete route structure for testing components with their actual route configuration, loaders, and nested routes.
+2. **`MemoryRouter`** - Provides a minimal routing context for components that just need router hooks to work.
+
+Choose your approach based on what your component actually needs from the router.
+
+## When to Use Each Approach
+
+### `createRoutesStub` (Recommended)
+
+Use `createRoutesStub` when your component:
+- Relies on route parameters (`useParams`)
+- Uses loader data (`useLoaderData`) or `clientLoader`
+- Has nested routes or uses `<Outlet />`
+- Needs to test navigation between routes
+
+> [!NOTE]
+> `createRoutesStub` is intended for unit testing **reusable components** that depend on router context. For testing full route/page components, consider E2E tests (Playwright, Cypress) instead.
+
+```typescript
+import { createRoutesStub } from "react-router";
+import { render } from "@testing-library/react";
+
+const RouterStub = createRoutesStub([
+  {
+    Component: MyRouteComponent,
+    path: "/conversations/:conversationId",
+  },
+]);
+
+render(<RouterStub initialEntries={["/conversations/123"]} />);
+```
+
+**With nested routes and loaders:**
+
+```typescript
+const RouterStub = createRoutesStub([
+  {
+    Component: SettingsScreen,
+    clientLoader,
+    path: "/settings",
+    children: [
+      {
+        Component: () => <div data-testid="llm-settings" />,
+        path: "/settings",
+      },
+      {
+        Component: () => <div data-testid="mcp-settings" />,
+        path: "/settings/mcp",
+      },
+    ],
+  },
+]);
+
+render(<RouterStub initialEntries={["/settings/mcp"]} />);
+```
+
+> [!TIP]
+> When using `clientLoader` from a Route module, you may encounter type mismatches. Use `@ts-expect-error` as a workaround:
+
+```typescript
+import { clientLoader } from "@/routes/settings";
+
+const RouterStub = createRoutesStub([
+  {
+    path: "/settings",
+    Component: SettingsScreen,
+    // @ts-expect-error: loader types won't align between test and app code
+    loader: clientLoader,
+  },
+]);
+```
+
+### `MemoryRouter`
+
+Use `MemoryRouter` when your component:
+- Only needs basic routing context to render
+- Uses `<Link>` components but you don't need to test navigation
+- Doesn't depend on specific route parameters or loaders
+
+```typescript
+import { MemoryRouter } from "react-router";
+import { render } from "@testing-library/react";
+
+render(
+  <MemoryRouter>
+    <MyComponent />
+  </MemoryRouter>
+);
+```
+
+**With initial route:**
+
+```typescript
+render(
+  <MemoryRouter initialEntries={["/some/path"]}>
+    <MyComponent />
+  </MemoryRouter>
+);
+```
+
+## Anti-patterns to Avoid
+
+### Using `BrowserRouter` in tests
+
+`BrowserRouter` interacts with the actual browser history API, which can cause issues in test environments:
+
+```typescript
+// ❌ Avoid
+render(
+  <BrowserRouter>
+    <MyComponent />
+  </BrowserRouter>
+);
+
+// ✅ Use MemoryRouter instead
+render(
+  <MemoryRouter>
+    <MyComponent />
+  </MemoryRouter>
+);
+```
+
+### Mocking router hooks when `createRoutesStub` would work
+
+Mocking hooks like `useParams` directly can be brittle and doesn't test the actual routing behavior:
+
+```typescript
+// ❌ Avoid when possible
+vi.mock("react-router", async () => {
+  const actual = await vi.importActual("react-router");
+  return {
+    ...actual,
+    useParams: () => ({ conversationId: "123" }),
+  };
+});
+
+// ✅ Prefer createRoutesStub - tests real routing behavior
+const RouterStub = createRoutesStub([
+  {
+    Component: MyComponent,
+    path: "/conversations/:conversationId",
+  },
+]);
+
+render(<RouterStub initialEntries={["/conversations/123"]} />);
+```
+
+## Common Patterns
+
+### Combining with `QueryClientProvider`
+
+Many components need both routing and TanStack Query context:
+
+```typescript
+import { createRoutesStub } from "react-router";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { retry: false },
+  },
+});
+
+const RouterStub = createRoutesStub([
+  {
+    Component: MyComponent,
+    path: "/",
+  },
+]);
+
+render(<RouterStub />, {
+  wrapper: ({ children }) => (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  ),
+});
+```
+
+### Testing navigation behavior
+
+Verify that user interactions trigger the expected navigation:
+
+```typescript
+import { createRoutesStub } from "react-router";
+import { screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+const RouterStub = createRoutesStub([
+  {
+    Component: HomeScreen,
+    path: "/",
+  },
+  {
+    Component: () => <div data-testid="settings-screen" />,
+    path: "/settings",
+  },
+]);
+
+render(<RouterStub initialEntries={["/"]} />);
+
+const user = userEvent.setup();
+await user.click(screen.getByRole("link", { name: /settings/i }));
+
+expect(screen.getByTestId("settings-screen")).toBeInTheDocument();
+```
+
+## See Also
+
+### Codebase Examples
+
+- [settings.test.tsx](routes/settings.test.tsx) - `createRoutesStub` with nested routes and loaders
+- [root-layout.test.tsx](routes/root-layout.test.tsx) - `createRoutesStub` with `initialEntries` navigation
+- [chat-interface.test.tsx](components/chat/chat-interface.test.tsx) - `MemoryRouter` usage
+
+### Official Documentation
+
+- [React Router Testing Guide](https://reactrouter.com/start/framework/testing) - Official guide on testing with `createRoutesStub`
+- [MemoryRouter API](https://reactrouter.com/api/declarative-routers/MemoryRouter) - API reference for `MemoryRouter`

__tests__/settings-schema-descriptions.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { MOCK_DEFAULT_USER_SETTINGS } from "#/mocks/handlers";
+
+describe("settings schema descriptions", () => {
+  it("provides helper descriptions for every schema-driven settings field", () => {
+    const schemas = [
+      MOCK_DEFAULT_USER_SETTINGS.agent_settings_schema,
+      MOCK_DEFAULT_USER_SETTINGS.conversation_settings_schema,
+    ].filter((schema): schema is NonNullable<typeof schema> => Boolean(schema));
+
+    const missingDescriptions = schemas.flatMap((schema) =>
+      schema.sections.flatMap((section) =>
+        section.fields
+          .filter((field) => !field.description?.trim())
+          .map((field) => field.key),
+      ),
+    );
+
+    expect(missingDescriptions).toEqual([]);
+  });
+});

__tests__/vite-config.test.ts

@@ -0,0 +1,98 @@
+// @vitest-environment node
+import viteConfig from "../vite.config";
+import { afterEach, describe, expect, it } from "vitest";
+
+afterEach(() => {
+  delete process.env.BUILD_LIB;
+});
+
+describe("vite optimizeDeps", () => {
+  it("prebundles core client entry dependencies", async () => {
+    const config = await viteConfig({ mode: "development", command: "serve" });
+    const optimizedDeps = config.optimizeDeps?.include ?? [];
+
+    expect(optimizedDeps).toEqual(
+      expect.arrayContaining([
+        "react",
+        "react/jsx-runtime",
+        "react-dom/client",
+        "react-router/dom",
+      ]),
+    );
+  });
+});
+
+describe("vite path resolution", () => {
+  it("uses Vite's native tsconfig paths support", async () => {
+    const config = await viteConfig({ mode: "development", command: "serve" });
+
+    expect(config.resolve?.tsconfigPaths).toBe(true);
+    expect(config.plugins).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: "vite-tsconfig-paths" }),
+      ]),
+    );
+  });
+});
+
+describe("vite app build", () => {
+  it("configures Rolldown code splitting for large vendor chunks", async () => {
+    const config = await viteConfig({ mode: "production", command: "build" });
+    const appBuild = config as {
+      build?: {
+        rolldownOptions?: {
+          output?: {
+            codeSplitting?: {
+              groups?: Array<{
+                name?: string;
+                maxSize?: number;
+                entriesAware?: boolean;
+              }>;
+            };
+          };
+        };
+      };
+    };
+
+    expect(appBuild.build?.rolldownOptions?.output?.codeSplitting?.groups).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: "vendor",
+          maxSize: 450 * 1024,
+          entriesAware: true,
+        }),
+      ]),
+    );
+  });
+});
+
+describe("vite library build", () => {
+  it("configures a dual-format preserved-module library build", async () => {
+    process.env.BUILD_LIB = "true";
+
+    const config = await viteConfig({ mode: "production", command: "build" });
+
+    expect((config as { copyPublicDir?: boolean }).copyPublicDir).toBe(false);
+    expect(config.build?.lib).toMatchObject({
+      formats: ["es"],
+    });
+    expect(config.build?.rollupOptions?.external).toEqual(
+      expect.arrayContaining(["react", "react-dom", "react-router"]),
+    );
+    expect(config.build?.rollupOptions?.output).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          format: "es",
+          preserveModules: true,
+          preserveModulesRoot: "src",
+        }),
+        expect.objectContaining({
+          format: "cjs",
+          preserveModules: true,
+          preserveModulesRoot: "src",
+          exports: "named",
+        }),
+      ]),
+    );
+  });
+});

__tests__/vitest-setup-progress-event.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+/**
+ * Regression test for the `ReferenceError: ProgressEvent is not defined`
+ * unhandled rejection that intermittently failed whole CI runs
+ * (all tests green, exit code 1).
+ *
+ * MSW's XMLHttpRequest interceptor evaluates the bare `ProgressEvent`
+ * identifier inside async response callbacks. Vitest's jsdom teardown does
+ * `keys.forEach((key) => delete global[key])`, so any *own* property named
+ * `ProgressEvent` — jsdom's, or a polyfill a setup file installed — is gone
+ * once the environment for a test file is torn down. A callback that settles
+ * after that point then throws.
+ *
+ * `vitest.setup.ts` therefore keeps a fallback on `globalThis`'s prototype
+ * chain, which `delete` cannot reach. This test performs exactly the deletion
+ * teardown performs and asserts the identifier still resolves.
+ */
+describe("ProgressEvent fallback in vitest.setup.ts", () => {
+  it("resolves the bare identifier after teardown deletes the own property", () => {
+    const live = Object.getOwnPropertyDescriptor(globalThis, "ProgressEvent");
+    expect(live).toBeDefined();
+
+    // What vitest's jsdom teardown does to every jsdom key.
+    delete (globalThis as { ProgressEvent?: unknown }).ProgressEvent;
+
+    try {
+      // Before the fix this is "undefined", and the construction below throws
+      // ReferenceError — the exact failure seen in CI.
+      expect(typeof ProgressEvent).toBe("function");
+
+      const event = new ProgressEvent("error", {
+        lengthComputable: true,
+        loaded: 3,
+        total: 7,
+      });
+
+      expect(event).toBeInstanceOf(Event);
+      expect(event.type).toBe("error");
+      expect(event.lengthComputable).toBe(true);
+      expect(event.loaded).toBe(3);
+      expect(event.total).toBe(7);
+    } finally {
+      if (live) Object.defineProperty(globalThis, "ProgressEvent", live);
+    }
+  });
+
+  it("prefers jsdom's own ProgressEvent while the environment is alive", () => {
+    // The own property shadows the prototype fallback, so nothing observes the
+    // stand-in until teardown removes jsdom's class.
+    expect(
+      Object.getOwnPropertyDescriptor(globalThis, "ProgressEvent"),
+    ).toBeDefined();
+    expect(new ProgressEvent("progress").type).toBe("progress");
+  });
+
+  it("does not add ProgressEvent to plain objects", () => {
+    // The fallback lives on globalThis's own prototype chain, which in Node is
+    // not Object.prototype — so it must not leak onto ordinary objects.
+    expect("ProgressEvent" in {}).toBe(false);
+  });
+});

docs/ACP_AGENTS.md

@@ -0,0 +1,239 @@
+# Using ACP agents
+
+Agent Canvas can drive your conversations with the built-in **OpenHands** agent or
+with an external **ACP agent** — Claude Code, Codex, or Gemini CLI. This guide
+explains what ACP agents are, how to onboard one, and how to switch agents or
+models later.
+
+## What is an ACP agent?
+
+The [Agent Client Protocol (ACP)](https://agentclientprotocol.com/protocol/overview)
+is a standard for talking to coding agents over JSON-RPC on stdio. Instead of
+Agent Canvas calling an LLM directly, the Agent Server spawns the agent's own CLI
+as a subprocess and relays each turn to it. The external agent manages its own
+LLM, tools, and execution; Agent Canvas sends messages and renders what comes
+back.
+
+```mermaid
+flowchart LR
+    canvas["Agent Canvas<br/>(this UI)"]
+    server["Agent Server"]
+    acp["ACP subprocess<br/>(e.g. claude-agent-acp)"]
+    llm["LLM provider<br/>(Anthropic / OpenAI / Google)"]
+    canvas -- "PATCH /api/settings<br/>(agent_kind, acp_*)" --> server
+    canvas -- "conversation turns" --> server
+    server -- "spawn + JSON-RPC over stdio" --> acp
+    acp -- "API calls" --> llm
+```
+
+The Agent Server owns the subprocess and the credentials; Agent Canvas only
+records *which* agent to run and surfaces a form for the secrets it needs. The
+agent choice is stored per backend, so switching backends can switch agents.
+
+## Supported providers
+
+The provider list is sourced from the SDK registry
+(`openhands.sdk.settings.acp_providers`, mirrored into
+`@openhands/typescript-client`) and enriched with Canvas UI metadata in
+[`src/constants/acp-providers.ts`](../src/constants/acp-providers.ts). Adding or
+changing a provider happens upstream in the SDK, not here.
+
+| Provider | Default command |
+|---|---|
+| **Claude Code** | `npx -y @agentclientprotocol/claude-agent-acp` |
+| **Codex** | `npx -y @agentclientprotocol/codex-acp` |
+| **Gemini CLI** | `npx -y @google/gemini-cli --acp` |
+
+See [Authentication](#authentication) for how each one authenticates.
+
+## Authentication
+
+> [!IMPORTANT]
+> ACP agents authenticate **two ways: a subscription login, or an API key** — and
+> the onboarding fields are optional. If you're already signed in to the
+> provider's CLI on the machine the agent runs on, it reuses that login
+> automatically, so locally you often don't need a key at all. **The login takes
+> priority over an API key:** while you're signed in, a key set in the
+> environment isn't used — so the onboarding key fields do nothing and can be
+> left blank.
+
+A "subscription login" is the credential the provider's own CLI stores when you
+sign in once — a file in your home directory, or, for Claude Code on macOS, the
+system **Keychain**. When the Agent Server runs **on that same machine** (a local
+or self-hosted backend), the provider CLI finds that login automatically — no API
+key required. On a clean cloud sandbox there's no stored login, so an API key is
+needed instead.
+
+| Provider | Subscription login (auto-detected) | API key |
+|---|---|---|
+| **Claude Code** | A Claude Code login (Pro/Max), from Claude Code's own credential store: the **macOS Keychain**, or `~/.claude/.credentials.json` on Linux | `ANTHROPIC_API_KEY` *(onboarding)* |
+| **Codex** | A ChatGPT login (`codex login`) cached at `~/.codex/auth.json` | `OPENAI_API_KEY` *(onboarding)* |
+| **Gemini CLI** | Your Google login (`gemini`/`gemini --acp`) cached at `~/.gemini/oauth_creds.json` | `GEMINI_API_KEY` *(onboarding)* |
+
+All three collect an *optional* API key (+ base URL) in onboarding. As noted
+above, **a subscription / OAuth login takes priority over an API key** — when the
+provider's CLI is signed in, a key set in the environment is not used. Verified
+per provider:
+
+- **Codex** — `codex login status` keeps reporting the ChatGPT login even with
+  `OPENAI_API_KEY` set.
+- **Gemini CLI** — uses the OAuth auth type chosen at `gemini` login;
+  `GEMINI_API_KEY` is only consulted if you switch the auth type. The free Google
+  login is the common no-key path locally — sign in once and it **just works**.
+- **Claude Code** — with both present, `claude auth status` reports it is
+  authenticated via the subscription (`claude.ai`), not the key. The login is
+  auto-detected from the macOS Keychain (or `~/.claude/.credentials.json` on
+  Linux); `CLAUDE_CONFIG_DIR` is **not** required for it — it only relocates
+  Claude Code's config directory (settings/history, not the token; e.g. for
+  containers or multiple accounts) and signals the SDK to strip a conflicting
+  `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`.
+
+The one exception is the **base URL** (`*_BASE_URL`): a custom value points the
+CLI at a different endpoint (a proxy or gateway) and *does* take effect even
+under a login — for Gemini it rides the ACP `gateway` param. It's an advanced
+override, not needed for normal use.
+
+## Onboarding an ACP agent
+
+First-time users get a four-step onboarding modal. To onboard an ACP agent:
+
+1. **Choose agent** — pick Claude Code, Codex, or Gemini CLI instead of
+   OpenHands. The choice is saved immediately to your backend's settings.
+2. **Check backend** — confirms Agent Canvas can reach the Agent Server.
+3. **Set up credentials** — enter the provider's credentials. Beyond the API
+   key (+ optional base URL), this step also collects the credentials a
+   *containerized* backend needs, since a fresh container has no host login:
+   - **Codex** — `CODEX_AUTH_JSON` (the contents of `~/.codex/auth.json`).
+   - **Claude Code** — `CLAUDE_CODE_OAUTH_TOKEN` (a Pro/Max OAuth token).
+   - **Gemini CLI** — `GOOGLE_APPLICATION_CREDENTIALS_JSON` (Vertex SA / ADC JSON)
+     plus `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, and
+     `GOOGLE_GENAI_USE_VERTEXAI`.
+
+   On a **local** backend the step is optional (a host login is reused
+   automatically); on a **Docker / cloud** backend it's **required**, because
+   there's no host login to fall back on. When the login probe detects an
+   existing session, the step shows a "you're already signed in" banner and
+   stays skippable.
+4. **Say hello** — creates your first conversation and closes the modal.
+
+> [!NOTE]
+> On a local backend every credential field is optional and the step is
+> skippable. Leave a field blank to reuse a key already set on the backend, or to
+> authenticate the agent through a subscription / OAuth login instead.
+
+### How credentials reach the agent
+
+Each credential you enter is saved as a **global secret** whose name is exactly
+the environment variable the Agent Server exports into the ACP subprocess (e.g.
+`ANTHROPIC_API_KEY`). Saving in onboarding is identical to adding the secret
+under **Settings → Secrets**, where you can edit or remove it anytime. Keeping
+the secret name equal to the env var is what makes a saved key actually reach the
+provider CLI.
+
+## Running ACP agents in a Docker container
+
+The walkthrough above assumes the Agent Server runs on your own machine, where
+the provider CLIs reuse a host login. You can also run the Agent Server **in a
+container** — Canvas drives it the same way, but since a fresh container has no
+host login, you supply credentials through the UI and Canvas sends them inline
+on the conversation start request.
+
+A ready-to-run setup lives in
+[`examples/acp-docker/`](../examples/acp-docker/) (`docker compose up`, then
+point Canvas at it). In short:
+
+```bash
+# 1. Agent Server in a container (CORS allows localhost, so the browser talks
+#    to it directly). The image pre-installs the ACP CLI wrappers. New
+#    canvas_ui_control calls use client_tools; the Python mount keeps
+#    pre-migration conversations loadable when persisted metadata imports
+#    canvas_ui_tool.
+# Minimum image: 1.28.0-python (first compatible ACP provider/model protocol
+# surface for current Canvas). Override SHA with a newer build.
+docker run -d --name oh-acp -p 8010:8000 -v acp-data:/workspace \
+  -v "$(pwd)/tools:/canvas-tools:ro" -e OH_EXTRA_PYTHON_PATH=/canvas-tools \
+  ghcr.io/openhands/agent-server:1.28.0-python
+
+# 2. Canvas pointed at the container.
+VITE_BACKEND_BASE_URL=http://localhost:8010 npm run dev:frontend
+```
+
+### How credentials reach a containerized agent
+
+In onboarding's **Set up credentials** step, the credentials you enter are saved
+as global secrets in the agent-server's secret store (as usual). The start
+request then references each as a **`LookupSecret`** — uniformly for ACP and
+non-ACP — and the agent-server resolves the value back from its own store at
+spawn time. For ACP this resolution runs **off the event loop**
+(software-agent-sdk#3510), so the loopback fetch does not self-deadlock. The
+SDK's `acp_file_secrets` defaults then:
+
+- materialise `CODEX_AUTH_JSON` back to `auth.json` under `CODEX_HOME` and point
+  Codex at it;
+- materialise `GOOGLE_APPLICATION_CREDENTIALS_JSON` to a file referenced by
+  `GOOGLE_APPLICATION_CREDENTIALS` and route Gemini through Vertex AI;
+- export the rest (`CLAUDE_CODE_OAUTH_TOKEN`, project/location, API keys) as env
+  vars for the CLI.
+
+Canvas just sends the secrets — it does **not** hand-roll the file
+materialisation. The `npx -y <pkg>` command is rewritten to the pinned
+pre-installed binary inside the container by the SDK, so no command change is
+needed.
+
+> [!IMPORTANT]
+> **Do not set `ANTHROPIC_BASE_URL` alongside the Claude OAuth token.** An
+> inherited LiteLLM base URL silently breaks the token's bearer auth (it routes
+> the request away from Anthropic). Canvas never derives a base-URL secret from
+> your LLM settings — but a base URL you save yourself rides along on every
+> start request like any other saved secret, which is why the credential forms
+> warn when both are set. Only set it deliberately, and not with the OAuth path.
+
+> [!IMPORTANT]
+> **Gemini Vertex needs a fresh ADC.** Run `gcloud auth application-default login`
+> before copying `~/.config/gcloud/application_default_credentials.json` — a stale
+> token surfaces as `invalid_rapt`, which is a credential problem, not a Canvas
+> bug.
+
+> [!NOTE]
+> **Pick a non-flash Gemini model.** gemini-cli 0.45.x re-resolves any `*-flash`
+> model id at generation time to its *current default* flash (e.g.
+> `gemini-2.5-flash` silently ran `gemini-3-flash`, which 404s on projects that
+> don't serve it — software-agent-sdk#3532). Only a non-flash id sticks, so
+> Canvas preselects `gemini-2.5-pro`. If a Gemini turn fails with
+> `Publisher Model … was not found`, check the selected model isn't a flash id.
+
+### Per-conversation isolation
+
+Concurrent same-provider conversations in one container share a HOME, so they can
+race on the CLI's auth/config/lock files. The SDK supports opting into a
+per-conversation data dir (`acp_isolate_data_dir`, software-agent-sdk#3492), but
+the released `@openhands/typescript-client` does not yet expose it on
+`ACPAgentSettings`, so Canvas can't send it without risking a validation error on
+older servers. This is tracked as a follow-up (agent-canvas#1019); cloud
+grouping isolation is separate (agent-canvas#1016).
+
+## Switching agent or model later
+
+Open **Settings → Agent** at any time:
+
+- **Agent** — switch between **OpenHands** and **ACP**.
+- **Preset** — pick a built-in provider (Claude Code, Codex, Gemini CLI) or
+  **Custom** to point at any other ACP server.
+- **Command** — the command line used to spawn the subprocess. Selecting a preset
+  fills this in; editing it to match another preset re-detects that provider.
+  API keys are *not* entered here — they live in the Secrets panel.
+- **Model** — choose a suggested model for the provider or enter a custom model
+  override. Built-in providers save a concrete model rather than leaving it
+  blank.
+
+Saving writes an `agent_settings_diff` (`agent_kind`, `acp_server`,
+`acp_command`, `acp_model`) to `PATCH /api/settings`. A running conversation
+keeps the agent it started with; the new choice applies to conversations you
+start afterward.
+
+## Custom ACP servers
+
+Any stdio ACP server works: choose **Custom** in Settings → Agent and enter its
+launch command. Custom servers have no curated model list, so enter the model ID
+the server expects (if any) as a custom model. Pass credentials by adding the
+env vars the server reads as global secrets under **Settings → Secrets**.

docs/CANVAS_EXTENSIONS_TESTING.md

@@ -0,0 +1,93 @@
+# Canvas Extensions manual testing
+
+Canvas Extensions can be exercised locally before the Agent Server implements
+the `/api/canvas-extensions` endpoints. Canvas's existing MSW development mode
+contains an in-memory implementation of the API and serves the checked-in demo
+extension bundle through the same frontend service and runtime used in a real
+deployment.
+
+This path is for frontend development only. It does not test Agent Server
+installation, filesystem validation, persistence, authentication, or Git
+resolution.
+
+## Start the mock frontend
+
+From the repository root, run:
+
+```sh
+VITE_FRONTEND_PORT=3102 \
+VITE_BACKEND_BASE_URL=http://127.0.0.1:8000 \
+VITE_SESSION_API_KEY=canvas-extension-dev \
+npm run dev:mock
+```
+
+Port `3102` avoids the `3001` Vite process used by the normal local stack. The
+backend URL only gives Canvas a local backend identity; MSW intercepts the
+extension requests in the browser. The mock also covers the settings and server
+information probes needed to mark that backend healthy, so the Agent Server
+does not need the extension endpoints and does not need to be running.
+
+Open <http://localhost:3102/extensions>. Do not use the normal ingress URL at
+`http://localhost:8000` for this test because its `/api` traffic goes directly
+to the unmodified Agent Server rather than through the mock browser session.
+
+If the browser profile already contains incompatible backend or onboarding
+state, use a private window or clear local storage for `localhost:3102` and
+reload.
+
+## Install and enable the fixture
+
+1. In **Customize -> Extensions**, select **Add extension**.
+2. Enter this exact source:
+
+   ```text
+   src/fixtures/canvas-extensions/demo-page
+   ```
+
+3. Leave **Ref** and **Repository path** empty, then select **Install**.
+4. Confirm that **Demo page** appears disabled. Installation must not execute
+   the bundle or add its navigation item.
+5. Turn on the extension and accept the trusted-code confirmation.
+6. Confirm that **Extension demo** appears in the main left rail.
+7. Open it and verify the page says **Hello from a Canvas Extension**.
+8. Visit `/extensions/demo-page/hello/nested` directly and verify the page
+   renders `Nested extension path: nested`.
+
+## Lifecycle checks
+
+- **Disable:** turn the extension off. Its rail item should disappear, and its
+  route should no longer render the contributed page.
+- **Re-enable:** turn it on again. The item and page should return without a
+  Canvas restart.
+- **Uninstall:** select **Uninstall** and confirm. The inventory and rail item
+  should become empty.
+- **Reload:** reload the page and confirm the installation and enablement are
+  retained for this browser tab. The mock uses session storage and clears when
+  you uninstall it or end the browser session.
+
+## Test an extension edit
+
+Edit
+`src/fixtures/canvas-extensions/demo-page/extension.js`, restart the mock
+frontend if Vite does not rebuild the raw fixture import automatically, then
+uninstall and reinstall the fixture. This allows page mounting, cleanup,
+subrouting, and use of the host API to be developed before backend support is
+available.
+
+The fixture must remain a self-contained browser ES module: it may not rely on
+bare package imports or additional output chunks.
+
+## What still requires the Agent Server
+
+Repeat this flow against `http://localhost:8000/extensions` after the backend
+contract lands. That test must additionally verify:
+
+- Git and backend-local-path installation;
+- immutable revision resolution;
+- manifest, traversal, symlink, and entrypoint validation;
+- persistence across Agent Server and browser restarts;
+- session-authenticated bundle delivery;
+- isolation when switching between active backends.
+
+The backend contract and acceptance criteria are documented in
+[`specs/canvas-extensions.md`](../specs/canvas-extensions.md).

docs/DEVELOPMENT.md

@@ -0,0 +1,205 @@
+# Development
+
+This document is for contributors working on `agent-canvas` itself.
+
+## Recommended local workflow
+
+`npm run dev` runs the full local stack (agent-server + automation backend via
+`uvx`, Vite dev server with live reload, and an ingress proxy) — all without
+Docker.
+
+## Repository boundaries
+
+This repository contains the Agent Canvas frontend and local-stack orchestration. Use the sibling repositories for their owned layers:
+
+- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and server API.
+- [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns browser-compatible typed access to that Agent Server API. Add client methods there rather than reimplementing API calls in Canvas.
+- [`OpenHands/extensions`](https://github.com/OpenHands/extensions) owns reusable skills, plugins, automations, and integrations; [`OpenHands/automation`](https://github.com/OpenHands/automation) owns automation definitions, scheduling, webhooks, run history, and dispatching; Agent Server/SDK code executes the dispatched conversations.
+
+When a feature crosses repositories, implement the backend contract in the SDK first, expose it through `typescript-client`, and consume it in Canvas. Coordinate automation lifecycle changes in `automation`. See the repository [contributor notes](../AGENTS.md) and follow the [custom code-review guide](../.agents/skills/custom-codereview-guide.md) for every pull request.
+
+
+For a static frontend build (better for slow networks, remote access, tunnels):
+
+```sh
+npm run dev:static
+```
+
+The published `agent-canvas` binary also supports partial-stack modes when you want to run the frontend and backend processes separately:
+
+```sh
+agent-canvas --frontend-only
+agent-canvas --backend-only
+```
+
+Both modes still start the ingress proxy; the proxy only routes to the services started by that mode.
+
+The dev stack uses `uvx` to run a temporary `agent-server`
+installation on `127.0.0.1:18000` and points the frontend at it. It isolates
+conversation persistence by setting separate `OH_CONVERSATIONS_PATH`,
+`OH_BASH_EVENTS_DIR`, and `OH_VSCODE_PORT` values under `.openhands-dev/`, and
+keeps its tmux sockets under `~/.openhands/agent-canvas/tmux` (via
+`TMUX_TMPDIR`), so it does not collide with other local or cloud-backed
+OpenHands sessions. If `$HOME` is on a filesystem that does not support Unix
+domain sockets (some devcontainers, NFS/CIFS homes), set the standard
+`TMUX_TMPDIR` env var to a local path such as `/tmp` and the dev stack will use
+it instead.
+
+### Environment Variables
+
+| Variable                  | Description                    | Default |
+| ------------------------- | ------------------------------ | ------- |
+| `PORT`                    | Ingress port                   | `8000`  |
+| `OH_AUTOMATION_GIT_REF`   | Git ref for automation backend (overrides the pinned default version) | *(unset)* |
+| `OH_AGENT_SERVER_GIT_REF` | Git ref for agent-server (overrides the pinned default version) | *(unset)* |
+
+### Alternative: Minimal Mode (without Automation)
+
+To run without the automation service:
+
+```sh
+npm run dev:minimal
+```
+
+This runs only agent-server + Vite (no automation backend or ingress).
+Access at `http://localhost:3001/`
+
+### Agent server version selection
+
+By default, the latest released version from PyPI is used. You can override this (highest precedence first):
+
+```sh
+# Run against a local software-agent-sdk checkout.
+OH_AGENT_SERVER_LOCAL_PATH=/abs/path/to/software-agent-sdk npm run dev
+
+# Use a git branch or commit (takes precedence over version)
+OH_AGENT_SERVER_GIT_REF=main npm run dev
+OH_AGENT_SERVER_GIT_REF=abc1234 npm run dev
+
+# Use a specific PyPI version
+OH_AGENT_SERVER_VERSION=1.18.0 npm run dev
+```
+
+`OH_AGENT_SERVER_LOCAL_PATH` must be an absolute path to a `software-agent-sdk` checkout containing the `openhands-agent-server`, `openhands-sdk`, `openhands-tools`, and `openhands-workspace` workspace packages. The agent-server itself is rebuilt from local source on each start (`uvx --reinstall`); the other workspace packages are installed editable, so their source changes take effect without a rebuild.
+
+### Other useful overrides
+
+- `OH_CANVAS_SAFE_BACKEND_PORT` — backend port for the isolated server (default `18000`)
+- `OH_CANVAS_SAFE_VSCODE_PORT` — VS Code sidecar port (default `backend port + 1`)
+- `OH_CANVAS_SAFE_STATE_DIR` — base directory for isolated server state
+- `VITE_WORKING_DIR` — repo root used for new conversations (defaults to the current checkout)
+
+## Alternative development workflows
+
+### Multiple local backends (shared persistence)
+
+To run a second standalone agent-server alongside `npm run dev` while sharing
+its conversation history and encrypted secrets, you can use the
+`npm run dev:extra-backend` helper. It launches an extra server on `:18002` that
+reuses the bundled instance's state dir.
+
+### Frontend against an existing backend
+
+Use this only if you intentionally started `agent-server` yourself or want the frontend to talk to another backend:
+
+```sh
+npm run dev:frontend
+```
+
+The frontend-only workflow expects the backend at `127.0.0.1:8000` by default.
+
+If you set `LOCAL_BACKEND_API_KEY`, it is used as the API key for the agent-server (mapped internally to `OH_SESSION_API_KEYS_0`). The launcher auto-generates and persists a key when `LOCAL_BACKEND_API_KEY` is not set.
+
+### Mock mode
+
+If you want to run the frontend without a live backend, use:
+
+```sh
+npm run dev:mock
+```
+
+## Build and test
+
+```sh
+npm run test
+npm run build
+npm run start
+```
+
+Useful targeted verification for the isolated dev launcher:
+
+```sh
+npm run test -- __tests__/api/agent-server-config.test.ts __tests__/scripts/dev-safe.test.ts
+```
+
+### Mutation testing
+
+Stryker checks whether the Vitest suite detects deliberate changes to the
+first-party TypeScript source under `src/`. The default configuration excludes
+tests, declarations, generated files, fixtures, mocks, and development seeds.
+
+```sh
+# Full mutation run (expensive for the whole frontend)
+npm run test:mutation
+
+# Reuse results from the previous run
+npm run test:mutation:incremental
+
+# Mutate only production files changed from the local main branch
+npm run test:mutation:diff
+
+# Compare with another base ref, such as the latest remote main
+npm run test:mutation:diff -- origin/main
+```
+
+The HTML report is written to `reports/mutation.html`. Mutation scores are
+report-only initially; establish a stable baseline before adding a failing
+threshold.
+
+Stryker does not cover the small Python surface in this repository; mutating it
+would need a Python test harness and Python-specific mutation tool.
+
+## CSS isolation and host-app customization
+
+The standalone app and the exported provider/root wrapper now scope all bundled CSS under a dedicated shell element with the `data-agent-server-ui` attribute. That means Tailwind utilities, HeroUI component styles, xterm styles, and local CSS only apply inside the OpenHands UI subtree instead of leaking into a host app.
+
+### Embedding strategy
+
+- Use `AgentServerUIProviders` in host apps. It renders a scoped style root by default.
+- For direct wrapper control, use `AgentServerUIRoot`.
+- The standalone app opts out of the provider wrapper because the router layout already renders the scoped root.
+
+### Customization strategy
+
+Theme and surface tokens are exposed as CSS custom properties on the scoped root. You can override them either through the provider/root `styleOverrides` prop or with host CSS targeting `[data-agent-server-ui]`.
+
+```tsx
+<AgentServerUIProviders
+  styleOverrides={{
+    "--oh-color-base": "#101820",
+    "--oh-color-content-2": "#f5f7ff",
+    "--oh-accent": "#8b5cf6",
+  }}
+>
+  <App />
+</AgentServerUIProviders>
+```
+
+If you want Tailwind layout utilities on the inner themed container, pass `contentClassName` instead of `className`, because the outer scope element is what all generated selectors key off of.
+
+## Environment variables
+
+You can create a `.env` file in the project directory with these variables based on `.env.sample`.
+
+| Variable                    | Description                                                                               | Default Value          |
+| --------------------------- | ----------------------------------------------------------------------------------------- | ---------------------- |
+| `VITE_BACKEND_BASE_URL`     | Full base URL for the agent server used by direct browser requests                        | current browser origin |
+| `VITE_BACKEND_HOST`         | Backend host used by the Vite dev proxy                                                   | `127.0.0.1:8000`       |
+| `VITE_SESSION_API_KEY`      | (Internal) Session API key injected by the launcher — set `LOCAL_BACKEND_API_KEY` instead | -                      |
+| `VITE_WORKING_DIR`          | Workspace path sent when starting new conversations                                       | `workspace/project`    |
+| `VITE_ENABLE_BROWSER_TOOLS` | Set to `false` to omit `BrowserToolSet` from new conversation payloads                    | `true`                 |
+| `VITE_BASE_PATH`            | Build/serve the SPA under a subpath such as `/canvas`                                     | `/`                    |
+| `VITE_MOCK_API`             | Enable/disable API mocking with MSW                                                       | `false`                |
+| `VITE_USE_TLS`              | Use HTTPS/WSS for the Vite proxy target                                                   | `false`                |
+| `VITE_FRONTEND_PORT`        | Port to run the frontend application                                                      | `3001`                 |
+| `VITE_INSECURE_SKIP_VERIFY` | Skip TLS certificate verification for proxied backend requests                            | `false`                |

docs/DefenseClaw.md

@@ -0,0 +1,303 @@
+# Integrating DefenseClaw with Agent Canvas
+
+[DefenseClaw](https://github.com/cisco-ai-defense/defenseclaw) is a security governance layer for agentic AI runtimes — it scans skills and MCP servers before they run, inspects LLM traffic at runtime, and produces durable audit evidence. This guide explains how to run DefenseClaw alongside the [OpenHands Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server) that powers Agent Canvas, without making any code-level changes to either project.
+
+> **Status:** DefenseClaw is purpose-built around the OpenClaw runtime and its TypeScript plugin hooks. The integration described here targets the lowest-friction overlap points — skill injection, LLM proxying, CLI scanning, and audit export — that work without modifying Agent Canvas or DefenseClaw source code. [Future work](#future-work-code-level-extensions) describes deeper hooks that would require code changes.
+
+---
+
+## How the Two Systems Fit Together
+
+```mermaid
+flowchart TD
+    UI["Agent Canvas (browser)"]
+    AS["OpenHands Agent Server\nlocalhost:18000"]
+    GP["DefenseClaw Guardrail Proxy\nlocalhost:4000"]
+    LLM["LLM Provider"]
+    GW["DefenseClaw Gateway Sidecar\nlocalhost:18970"]
+    CLI["DefenseClaw CLI / TUI"]
+
+    UI -->|HTTP| AS
+    AS -->|LLM API calls| GP
+    GP -->|forwarded request| LLM
+    GW <-->|REST API| AS
+    CLI <-->|REST API| GW
+
+    style GW fill:#fff3cd,stroke:#856404
+    style CLI fill:#fff3cd,stroke:#856404
+    style GP fill:#f8d7da,stroke:#842029
+```
+
+**Shared concepts:**
+
+| Agent Canvas / Agent Server | DefenseClaw equivalent |
+|---|---|
+| Skills (`.agents/skills/`) | Skills (scanned by `cisco-ai-skill-scanner` + CodeGuard) |
+| MCP servers | MCP servers (scanned by `cisco-ai-mcp-scanner`) |
+| LLM settings (`base_url`) | Guardrail proxy upstream target |
+| Workspace files (generated code) | CodeGuard scan surface |
+| Agent Server hooks | Potential enforcement point (future work) |
+
+---
+
+## Prerequisites
+
+| Component | Version |
+|---|---|
+| Agent Canvas / Agent Server | Current `main` |
+| Python | 3.10+ |
+| Go | 1.26.2+ (for DefenseClaw gateway) |
+| DefenseClaw | Latest release |
+
+---
+
+## Installation
+
+### 1. Install and initialise DefenseClaw
+
+```bash
+# Install from the release script
+curl -LsSf https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/main/scripts/install.sh | bash
+
+# Initialise config and enable the guardrail proxy
+defenseclaw init --enable-guardrail
+```
+
+Verify the installation:
+
+```bash
+defenseclaw doctor
+```
+
+Start the Go gateway sidecar (keep this running alongside the Agent Server):
+
+```bash
+defenseclaw-gateway start
+```
+
+### 2. Start Agent Canvas
+
+Follow the standard [Agent Canvas quickstart](../README.md). The integration steps below assume the Agent Server is reachable at `http://localhost:18000`.
+
+---
+
+## Integration Points
+
+### A. Load the CodeGuard Skill
+
+DefenseClaw ships a ready-made OpenHands skill — `skills/codeguard/SKILL.md` — that teaches the agent the CodeGuard security rules. When the skill is active, the agent writes code that avoids the patterns DefenseClaw blocks at scan time (hardcoded secrets, `os.system()`, string-interpolated SQL, weak crypto, path traversal, etc.).
+
+**Install the skill into a user or project skill directory:**
+
+```bash
+# User-level (applies to all Agent Server conversations on this machine)
+mkdir -p ~/.agents/skills/codeguard
+curl -fsSL https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/main/skills/codeguard/SKILL.md \
+  -o ~/.agents/skills/codeguard/SKILL.md
+
+# Project-level (checked in alongside your project, only affects that workspace)
+mkdir -p .agents/skills/codeguard
+curl -fsSL https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/main/skills/codeguard/SKILL.md \
+  -o .agents/skills/codeguard/SKILL.md
+```
+
+The Agent Server loads skills from these directories automatically at conversation start. No restart of the server is required for user-level skills; project-level skills are loaded when the conversation workspace is opened.
+
+**What this achieves:** The agent's system prompt is augmented with the full CodeGuard rule set. Code it generates will pre-emptively avoid the patterns that the downstream `defenseclaw codeguard scan` would flag.
+
+---
+
+### B. Route LLM Traffic Through the Guardrail Proxy
+
+The DefenseClaw guardrail proxy runs on `localhost:4000` and acts as an OpenAI-compatible reverse proxy. Pointing the Agent Server's LLM calls through it causes every prompt and completion to be inspected — in observe mode (log only) or action mode (block on policy violations).
+
+**Configure the LLM base URL in Agent Canvas:**
+
+Open the Agent Canvas settings panel → select your active backend → under **LLM settings**, set **Base URL** to:
+
+```
+http://localhost:4000
+```
+
+Leave the model name and API key as-is. The proxy reads the original `Authorization` / `x-api-key` header, forwards the request to the real provider, and injects its own `X-DC-Target-URL` routing header — the agent code and Agent Server require no changes.
+
+**Via environment variable (server-side):**
+
+If you configure your Agent Server through environment variables, set the LLM base URL before starting it:
+
+```bash
+# Example using OpenAI; set model and key as normal, only base_url changes
+export OH_LLM__BASE_URL="http://localhost:4000"
+npm run dev
+```
+
+> Consult the Agent Server [settings schema](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-agent-server/openhands/agent_server/settings_router.py) for the exact environment variable name used in your deployment.
+
+**Start the guardrail in observe mode (safe default) or action mode:**
+
+```bash
+# Observe — log findings, never block (recommended while tuning)
+defenseclaw setup guardrail --mode observe --restart
+
+# Action — block prompts and responses that match policies
+defenseclaw setup guardrail --mode action --restart
+```
+
+**Supported providers:**
+
+The DefenseClaw proxy handles Anthropic (`api.anthropic.com`), OpenAI (`api.openai.com`), OpenRouter, Azure OpenAI, Gemini, Ollama, and Bedrock. Provider detection is automatic based on the target URL.
+
+---
+
+### C. Scan Skills Before Loading
+
+Before installing a skill from the marketplace or an external source into the Agent Server, use the DefenseClaw CLI to vet it:
+
+```bash
+# Scan a locally downloaded skill directory
+defenseclaw skill scan path/to/skill-directory
+
+# Scan an installed skill by name (requires the skill to be registered in the DefenseClaw inventory)
+defenseclaw skill scan my-skill-name
+
+# List all skills currently visible to DefenseClaw
+defenseclaw skill list
+```
+
+The scanner applies `cisco-ai-skill-scanner` rules plus CodeGuard static analysis and emits a verdict (`PASS`, `WARN`, `BLOCK`) with per-finding details. HIGH and CRITICAL findings block skill use in action mode.
+
+**Workflow recommendation:** Add `defenseclaw skill scan <skill-dir>` as a pre-commit or CI step in repositories that ship skills for Agent Canvas.
+
+---
+
+### D. Scan Agent-Generated Code
+
+After an agent conversation produces code in the workspace, run CodeGuard on the output before committing:
+
+```bash
+# Scan an entire workspace directory
+defenseclaw codeguard scan /path/to/workspace
+
+# Scan a single file
+defenseclaw codeguard scan /path/to/workspace/src/auth.py
+
+# Output as JSON (useful in CI pipelines)
+defenseclaw codeguard scan /path/to/workspace --json
+```
+
+CodeGuard checks for hardcoded secrets, dangerous command execution, SQL injection, unsafe deserialization, weak cryptography, SSRF-prone network calls, and path traversal — covering Python, JavaScript, TypeScript, Go, Java, Ruby, and PHP.
+
+**Zero-friction CI gate example (GitHub Actions):**
+
+```yaml
+- name: Scan agent-generated code
+  run: |
+    defenseclaw codeguard scan ${{ github.workspace }} --json \
+      | python3 -c "
+    import sys, json
+    findings = json.load(sys.stdin)
+    criticals = [f for f in findings if f.get('severity') in ('HIGH','CRITICAL')]
+    if criticals:
+        for f in criticals:
+            print(f'::error file={f[\"file\"]},line={f[\"line\"]}::{f[\"rule\"]}: {f[\"message\"]}')
+        sys.exit(1)
+    "
+```
+
+---
+
+### E. Monitor via the DefenseClaw TUI and Audit Store
+
+All scan results, guardrail decisions, tool-call inspections, and policy verdicts are written to DefenseClaw's SQLite audit store. The TUI gives a live operator view:
+
+```bash
+defenseclaw tui
+```
+
+The TUI panels cover:
+- **Alerts** — recent HIGH/CRITICAL findings and blocked events
+- **Scans** — historical scan results per skill/file
+- **Tools** — tool-call verdicts from the inspection engine
+- **Policy** — current block/allow lists
+
+**Export to external systems:**
+
+| Target | Setup |
+|---|---|
+| OTLP (Prometheus/Grafana/Honeycomb) | `defenseclaw setup observability --otlp-endpoint http://collector:4317` |
+| Splunk HEC | `defenseclaw setup splunk --hec-url http://splunk:8088 --hec-token $TOKEN` |
+| Slack / PagerDuty / Webex | `defenseclaw setup notifications --slack-webhook $SLACK_URL` |
+| Local Splunk bundle (Docker) | `defenseclaw setup splunk --logs --accept-splunk-license` |
+
+---
+
+## Integration Summary
+
+| Goal | Mechanism | Config change? | Code change? |
+|---|---|---|---|
+| Agent writes secure code by default | CodeGuard skill in `.agents/skills/` | Drop-in file | No |
+| Inspect all LLM prompts and responses | Guardrail proxy at `localhost:4000` | Set `base_url` | No |
+| Vet skills before loading | `defenseclaw skill scan` in CI/workflow | None | No |
+| Scan agent-generated code | `defenseclaw codeguard scan <workspace>` | None | No |
+| Audit trail and alerting | DefenseClaw TUI, OTLP, Splunk, webhooks | DefenseClaw config | No |
+
+---
+
+## Future Work: Code-Level Extensions
+
+The following integrations would require changes to Agent Canvas, the Agent Server, or DefenseClaw, but would significantly deepen the security posture.
+
+### 1. Native `SecurityAnalyzer` hook
+
+The OpenHands SDK exposes a [`SecurityAnalyzer`](https://docs.openhands.dev/sdk/arch/security.md) interface. A custom implementation could call DefenseClaw's `/api/v1/inspect/tool` endpoint before every tool invocation — mirroring the inspection the OpenClaw TypeScript plugin performs. This would gate bash commands, file writes, and other tool calls through DefenseClaw's four-stage inspection pipeline (regex, Cisco AI Defense cloud rules, LLM judge, OPA policy) before they execute.
+
+```python
+# Sketch — not yet implemented
+class DefenseClawSecurityAnalyzer(SecurityAnalyzer):
+    async def analyze(self, action: Action) -> ActionSecurityRisk:
+        resp = await httpx.post(
+            "http://localhost:18970/api/v1/inspect/tool",
+            json={"tool": action.tool_name, "args": action.args},
+            headers={"X-DefenseClaw-Client": "agent-server"},
+        )
+        if resp.json()["action"] == "block":
+            return ActionSecurityRisk.HIGH
+        return ActionSecurityRisk.LOW
+```
+
+### 2. Skill install pipeline integration
+
+The Agent Server's `skills_service.py` (`service_install_skill`) runs skill validation during install. A pre-install hook that calls `defenseclaw skill scan` and fails the install on HIGH/CRITICAL findings would enforce a mandatory scan gate — no skill reaches the agent without passing DefenseClaw's scanner. This change would live in `openhands-agent-server`.
+
+### 3. Hooks integration
+
+The Agent Server loads `.openhands/hooks.json` from the workspace. An `on_conversation_end` hook that runs `defenseclaw codeguard scan <workspace>` and writes findings to a structured report file would give per-session security evidence without manual operator intervention.
+
+### 4. Agent Canvas security dashboard
+
+A dedicated panel in the Agent Canvas UI that queries DefenseClaw's gateway REST API (`GET /alerts`, `GET /enforce/blocked`) would surface guardrail findings inline with the conversation view — correlating blocked prompts or tool calls with the agent turn that triggered them.
+
+### 5. Agent Server → DefenseClaw audit bridge
+
+The Agent Server supports outgoing webhooks (`WebhookSpec`). A webhook handler that forwards conversation events to `POST /audit/event` on the DefenseClaw gateway would allow DefenseClaw's audit store to record Agent Server conversation lifecycle events (start, tool invocation, finish) alongside its own security findings — building a single correlated audit trail.
+
+### 6. Skill registry alignment
+
+DefenseClaw's registry system (`defenseclaw registry add`) ingests external skill/MCP catalogs from ClawHub, Smithery, skills.sh, HTTP YAML, and Git sources. Aligning the Agent Server's marketplace skill catalog with the DefenseClaw registry would allow `defenseclaw skill scan all` to exhaustively vet the entire available catalog, not just individually installed skills.
+
+---
+
+## References
+
+- [DefenseClaw GitHub](https://github.com/cisco-ai-defense/defenseclaw)
+- [DefenseClaw Quick Start](https://github.com/cisco-ai-defense/defenseclaw/blob/main/docs/QUICKSTART.md)
+- [DefenseClaw API Reference](https://github.com/cisco-ai-defense/defenseclaw/blob/main/docs/API.md)
+- [DefenseClaw Guardrail Architecture](https://github.com/cisco-ai-defense/defenseclaw/blob/main/docs/GUARDRAIL.md)
+- [DefenseClaw CodeGuard Skill](https://github.com/cisco-ai-defense/defenseclaw/blob/main/skills/codeguard/SKILL.md)
+- [OpenHands Agent Server](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server)
+- [OpenHands SDK Security Analyzer](https://docs.openhands.dev/sdk/arch/security.md)
+- [Agent Canvas Self-Hosting](./SELF_HOSTING.md)
+
+---
+
+_This document was created by an AI agent (OpenHands) on behalf of the user._

docs/README.md

@@ -0,0 +1,11 @@
+# Agent Canvas docs
+
+This directory contains the project documentation.
+
+- [Architecture](./architecture.md): system boundaries, runtime modes, and quality gates.
+- [Using ACP agents](./ACP_AGENTS.md): onboard and configure external agents (Claude Code, Codex, Gemini CLI).
+- [Development guide](./DEVELOPMENT.md)
+- [Canvas Extensions manual testing](./CANVAS_EXTENSIONS_TESTING.md)
+- [Self-hosting guide](./SELF_HOSTING.md)
+- [Integrating DefenseClaw](./DefenseClaw.md): run the DefenseClaw security governance layer alongside the Agent Server.
+- [Testing matrix](./TESTING_MATRIX.md): release smoke-test coverage across installers, operating systems, and agents.

electron/loading.html

@@ -0,0 +1,359 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>OpenHands Agent Canvas</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    /* Agent Canvas design tokens. The splash renders before the frontend is
+       served, so it cannot import the app's CSS — these values mirror the
+       static baseline in src/tailwind.css / src/index.css. Keep in sync. */
+    :root {
+      --oh-background: #0b0e14; /* cool-grey-950 */
+      --oh-foreground: #eef2f7; /* cool-grey-100 */
+      --oh-muted: #a3b0c4; /* cool-grey-400 */
+      --oh-text-dim: #7e8a9e; /* cool-grey-500 */
+      --oh-text-subtle: #626d82; /* cool-grey-600 */
+      --oh-border: #4b5468; /* cool-grey-700 */
+      --oh-border-subtle: #383f50; /* cool-grey-800 */
+      --oh-surface-deep: #05070a; /* cool-grey-975 */
+      --oh-color-danger: #e76a5e;
+    }
+
+    html, body {
+      width: 100%; height: 100%;
+      background: var(--oh-background);
+      font-family:
+        -apple-system, "SF Pro", BlinkMacSystemFont, "Segoe UI", "Roboto",
+        "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans",
+        "Helvetica Neue", sans-serif;
+      -webkit-font-smoothing: antialiased;
+      -moz-osx-font-smoothing: grayscale;
+      color: var(--oh-foreground);
+      user-select: none;
+      -webkit-app-region: drag;
+      overflow: hidden;
+    }
+
+    body {
+      display: flex;
+      flex-direction: column;
+    }
+
+    .container {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      /* Must equal the collapsed window height (LOADING_WIN_HEIGHT in
+         main.mjs): the block keeps its layout when the window grows to
+         reveal the startup-log console below it. */
+      height: 360px;
+      flex: none;
+      gap: 0;
+    }
+
+    /* Real app icon — squircle corners are baked into the PNG. Kept inert so
+       image dragging cannot hijack the -webkit-app-region window drag. */
+    .logo {
+      width: 72px;
+      height: 72px;
+      margin-bottom: 20px;
+      -webkit-user-drag: none;
+    }
+
+    h1 {
+      font-size: 22px;
+      font-weight: 600;
+      letter-spacing: -0.3px;
+      margin-bottom: 8px;
+      color: var(--oh-foreground);
+    }
+
+    .tagline {
+      font-size: 13px;
+      color: var(--oh-muted);
+      margin-bottom: 36px;
+    }
+
+    /* The app's canonical loading indicator: the 270° arc from
+       src/icons/loading-outer.svg with LoadingSpinner's animate-spin timing. */
+    .spinner {
+      width: 25px;
+      height: 25px;
+      color: #fff;
+      animation: spin 1s linear infinite;
+      margin-bottom: 14px;
+    }
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+
+    .status {
+      font-size: 12px;
+      color: var(--oh-text-dim);
+      letter-spacing: 0.3px;
+      /* Long lines (e.g. uvx "Installing openhands-agent-server==1.24.0…")
+         must not push the window or wrap awkwardly. */
+      max-width: 360px;
+      text-align: center;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .hint {
+      margin-top: 14px;
+      font-size: 11px;
+      color: var(--oh-text-subtle);
+      letter-spacing: 0.2px;
+      max-width: 340px;
+      text-align: center;
+      line-height: 1.5;
+    }
+
+    /* Progress dots animation for status text */
+    .dots::after {
+      content: "";
+      animation: dots 1.5s steps(3, end) infinite;
+    }
+    @keyframes dots {
+      0%   { content: ""; }
+      33%  { content: "."; }
+      66%  { content: ".."; }
+      100% { content: "..."; }
+    }
+
+    .actions {
+      margin-top: 16px;
+      display: flex;
+      gap: 10px;
+      -webkit-app-region: no-drag;
+    }
+
+    .ghost-button {
+      font: inherit;
+      font-size: 11px;
+      padding: 4px 12px;
+      color: var(--oh-muted);
+      background: transparent;
+      border: 1px solid var(--oh-border);
+      border-radius: 8px;
+      cursor: pointer;
+      -webkit-app-region: no-drag;
+    }
+    .ghost-button:hover {
+      color: var(--oh-foreground);
+      background: rgba(255, 255, 255, 0.06);
+    }
+
+    /* ── Startup-log console ─────────────────────────────────────────────
+       Fills the extra height revealed by "Show details" (the window grows —
+       see setLoadingWindowExpanded in main.mjs); zero-height and clipped
+       while the window is collapsed. Interactive: opts out of the window
+       drag region and re-enables text selection. */
+    .console {
+      flex: 1 1 auto;
+      min-height: 0;
+      display: flex;
+      flex-direction: column;
+      margin: 0 16px 16px;
+      background: var(--oh-surface-deep);
+      border: 1px solid var(--oh-border-subtle);
+      border-radius: 8px;
+      overflow: hidden;
+      -webkit-app-region: no-drag;
+    }
+
+    .console-head {
+      flex: none;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 5px 6px 5px 12px;
+      border-bottom: 1px solid var(--oh-border-subtle);
+      font-size: 11px;
+      color: var(--oh-muted);
+    }
+
+    .log {
+      flex: 1 1 auto;
+      min-height: 0;
+      overflow-y: auto;
+      padding: 8px 12px;
+      /* The app's `code` stack (src/index.css). */
+      font-family:
+        source-code-pro, Menlo, Monaco, Consolas, "Courier New", monospace;
+      font-size: 10.5px;
+      line-height: 1.55;
+      color: var(--oh-text-dim);
+      user-select: text;
+      -webkit-user-select: text;
+      cursor: text;
+      /* Full lines, never truncated — long uvx/pip output wraps. */
+      white-space: pre-wrap;
+      overflow-wrap: anywhere;
+    }
+    .log:empty::before {
+      content: "Waiting for output…";
+      color: var(--oh-text-subtle);
+    }
+
+    .log-name {
+      color: var(--oh-text-subtle);
+    }
+    .log-line-error {
+      color: var(--oh-color-danger);
+    }
+
+    /* ── Failure state (main.mjs::showStartupFailure) ──────────────────── */
+    body.failed .spinner {
+      display: none;
+    }
+    body.failed .status {
+      color: var(--oh-color-danger);
+      /* The full error summary matters more than a tidy single line here. */
+      white-space: normal;
+      line-height: 1.45;
+    }
+    body.failed .hint {
+      display: none;
+    }
+    .quit-button {
+      display: none;
+    }
+    body.failed .quit-button {
+      display: inline-block;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <img class="logo" src="build-resources/icon.png" alt="" draggable="false" />
+    <h1>OpenHands Agent Canvas</h1>
+    <p class="tagline">AI coding agent interface</p>
+    <svg class="spinner" viewBox="0 0 66 66" fill="none" aria-hidden="true"
+      xmlns="http://www.w3.org/2000/svg">
+      <path d="M63 33C63 16.4315 49.5685 3 33 3C16.4315 3 3 16.4315 3 33C3 49.5685 16.4315 63 33 63"
+        stroke="currentColor" stroke-width="6" stroke-linecap="round" />
+    </svg>
+    <p id="status" class="status">Starting services<span class="dots"></span></p>
+    <p class="hint">
+      First launch downloads Python + the OpenHands agent server.<br />
+      This can take a few minutes on a fresh machine.
+    </p>
+    <div class="actions">
+      <button id="details-toggle" type="button" class="ghost-button">
+        Show details
+      </button>
+      <button id="quit-button" type="button" class="ghost-button quit-button">
+        Quit
+      </button>
+    </div>
+  </div>
+  <div class="console" aria-label="Startup log">
+    <div class="console-head">
+      <span>Startup log</span>
+      <button id="copy-logs" type="button" class="ghost-button">Copy</button>
+    </div>
+    <div id="log" class="log"></div>
+  </div>
+  <script>
+    // Called from the Electron main process via webContents.executeJavaScript
+    // (see electron/main.mjs::setLoadingStatus). Replaces the entire status
+    // line, so the animated dots only appear when no concrete status is set.
+    window.__setLoadingStatus = function (line) {
+      var el = document.getElementById("status");
+      if (!el) return;
+      var text = String(line == null ? "" : line);
+      el.textContent = text || "";
+    };
+
+    // ── Startup-log console ──────────────────────────────────────────────
+    // Fed by the main process over IPC via preload.cjs (window.desktopBoot);
+    // undefined when the file is opened outside Electron, so every use is
+    // guarded and the static layout stays previewable in a plain browser.
+    // All DOM insertion uses textContent — log lines are untrusted process
+    // output and must never be parsed as HTML.
+    (function () {
+      var boot = window.desktopBoot;
+      var logEl = document.getElementById("log");
+      var statusEl = document.getElementById("status");
+      var toggleBtn = document.getElementById("details-toggle");
+      var copyBtn = document.getElementById("copy-logs");
+      var quitBtn = document.getElementById("quit-button");
+
+      // Cap DOM rows so an hours-long install can't grow layout cost;
+      // matches the main process's BOOT_LOG_MAX_LINES buffer cap.
+      var MAX_LINES = 2000;
+      var expanded = false;
+      // Follow the tail only while the user hasn't scrolled up.
+      var pinned = true;
+
+      logEl.addEventListener("scroll", function () {
+        pinned =
+          logEl.scrollTop + logEl.clientHeight >= logEl.scrollHeight - 8;
+      });
+
+      function appendBatch(batch) {
+        if (!batch || !batch.length) return;
+        var frag = document.createDocumentFragment();
+        for (var i = 0; i < batch.length; i++) {
+          var entry = batch[i];
+          var row = document.createElement("div");
+          row.className =
+            "log-line" + (entry.level === "error" ? " log-line-error" : "");
+          var name = document.createElement("span");
+          name.className = "log-name";
+          name.textContent = "[" + entry.name + "]";
+          row.appendChild(name);
+          row.appendChild(document.createTextNode(" " + entry.line));
+          frag.appendChild(row);
+        }
+        logEl.appendChild(frag);
+        while (logEl.childElementCount > MAX_LINES) {
+          logEl.removeChild(logEl.firstElementChild);
+        }
+        if (pinned) logEl.scrollTop = logEl.scrollHeight;
+      }
+
+      function setExpanded(next) {
+        expanded = next;
+        toggleBtn.textContent = expanded ? "Hide details" : "Show details";
+        if (boot) boot.setDetailsExpanded(expanded);
+        if (expanded && pinned) logEl.scrollTop = logEl.scrollHeight;
+      }
+
+      toggleBtn.addEventListener("click", function () {
+        setExpanded(!expanded);
+      });
+
+      copyBtn.addEventListener("click", function () {
+        if (!boot) return;
+        boot.copyLogs().then(function () {
+          copyBtn.textContent = "Copied";
+          setTimeout(function () {
+            copyBtn.textContent = "Copy";
+          }, 1200);
+        });
+      });
+
+      quitBtn.addEventListener("click", function () {
+        if (boot) boot.quit();
+      });
+
+      if (boot) {
+        boot.onLogBatch(appendBatch);
+        boot.onFatal(function (summary) {
+          document.body.classList.add("failed");
+          statusEl.textContent = String(summary == null ? "" : summary);
+          // Main already resized the window; sync the local toggle state.
+          if (!expanded) setExpanded(true);
+        });
+      }
+    })();
+  </script>
+</body>
+</html>

electron/main.mjs

@@ -0,0 +1,785 @@
+/**
+ * Electron Main Process — Agent Canvas Desktop
+ *
+ * Starts the full Agent Canvas stack (agent-server + automation via uvx,
+ * static frontend, ingress proxy), then opens a native BrowserWindow once
+ * the ingress is ready. Shows a loading screen while backends start.
+ *
+ * Path layout (electron-builder uses directories.app: 'electron'):
+ *
+ *   Packaged (macOS example):
+ *     Contents/Resources/app/     ← __dirname (main.mjs lives here)
+ *       main.mjs
+ *       loading.html
+ *       scripts/                  ← copied from repo scripts/
+ *       config/                   ← copied from repo config/
+ *       build/                    ← static frontend
+ *     Contents/Resources/bin/     ← process.resourcesPath/bin
+ *       uv  uvx                   ← bundled via extraResources
+ *
+ *   Dev (npm run desktop  →  electron electron):
+ *     electron/main.mjs           ← __dirname = <repo>/electron/
+ *     scripts/ config/ build/     ← one level up: <repo>/
+ *     system uvx from PATH
+ *
+ * When packaged, scripts/config/build are siblings of main.mjs so
+ * projectRoot === __dirname. In dev they are one level up.
+ *
+ * The dev command points electron at the electron/ DIRECTORY, not at
+ * main.mjs directly. Electron's default_app only reads name/productName/
+ * version out of <arg>/package.json, so passing the file makes it look for
+ * electron/main.mjs/package.json, miss, and leave app.name at the host
+ * bundle's default — "Electron" in the menu bar and userData path.
+ */
+
+import {
+  app,
+  BrowserWindow,
+  clipboard,
+  dialog,
+  ipcMain,
+  nativeImage,
+  nativeTheme,
+  shell,
+} from "electron";
+import { chmodSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+
+import { isExternalBrowsableUrl, isLoopbackAppUrl } from "./lib/window-url-policy.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ── Path resolution ───────────────────────────────────────────────────────────
+// Packaged (directories.app: 'electron'): scripts/config/build are SIBLINGS of
+// main.mjs inside Resources/app/, so projectRoot === __dirname.
+// Dev (electron electron): those directories are one level UP in the
+// repo root, so projectRoot === join(__dirname, '..').
+// Both branches key off __dirname (always <repo>/electron in dev), not
+// app.getAppPath(), so the entry-point form doesn't affect them.
+
+const projectRoot = app.isPackaged ? __dirname : join(__dirname, "..");
+const buildDir = join(projectRoot, "build");
+const scriptsDir = join(projectRoot, "scripts");
+
+// OpenHands raised-hands app icon, used as the BrowserWindow.icon option.
+// Windows gets the multi-size icon.ico (16→256, small sizes as classic BMP
+// entries — the Windows shell needs those); Linux uses the 1024×1024 PNG
+// for its taskbar. On macOS the dock icon comes from the .app bundle's
+// icon.icns, so this path is unused there. Both files live next to main.mjs
+// in dev and are copied into Resources/app/build-resources/ via the
+// `files:` array. Regenerate with `npm run generate-icons`.
+const appIconPath = join(
+  __dirname,
+  "build-resources",
+  process.platform === "win32" ? "icon.ico" : "icon.png",
+);
+
+// electron-builder's NSIS shortcuts are stamped with AppUserModelId
+// ${APP_ID} (WinShell::SetLnkAUMI in installer.nsh). Declare the same id so
+// running/pinned taskbar entries group with the shortcut and inherit its
+// icon. Must match appId in electron-builder.config.mjs, and must be set
+// before any BrowserWindow is created.
+if (process.platform === "win32") {
+  app.setAppUserModelId("dev.openhands.agent-canvas");
+}
+
+// ── Bundled uv ────────────────────────────────────────────────────────────────
+
+/**
+ * Inject the bundled uv binary into PATH so that uvx calls inside
+ * dev-with-automation.mjs resolve to our bundled binary.
+ * No-op in dev mode (falls back to system uv).
+ */
+function injectBundledUv() {
+  if (!app.isPackaged) return;
+
+  const isWin = process.platform === "win32";
+  const uvName = isWin ? "uv.exe" : "uv";
+  const uvxName = isWin ? "uvx.exe" : "uvx";
+  const binDir = join(process.resourcesPath, "bin");
+  const uvPath = join(binDir, uvName);
+
+  // We only probe for `uv` here — `uv` and `uvx` ship together in the
+  // bundle (`download-uv.mjs` writes both), so if `uv` is present we
+  // assume `uvx` is too. `uvxAvailable()` is called separately by
+  // start-up code to confirm the resolved binary actually runs.
+  if (!existsSync(uvPath)) {
+    console.warn("[desktop] Bundled uv not found at", uvPath);
+    return;
+  }
+
+  // electron-builder copies files without preserving the +x bit on Unix.
+  if (!isWin) {
+    try {
+      chmodSync(uvPath, 0o755);
+      const uvxPath = join(binDir, uvxName);
+      if (existsSync(uvxPath)) chmodSync(uvxPath, 0o755);
+    } catch {}
+  }
+
+  const sep = isWin ? ";" : ":";
+  process.env.PATH = `${binDir}${sep}${process.env.PATH ?? ""}`;
+  console.log("[desktop] Injected bundled uv from", binDir);
+}
+
+/**
+ * Verify uvx is reachable (either bundled or system).
+ * Returns true/false — callers show a dialog on false.
+ */
+function uvxAvailable() {
+  const cmd = process.platform === "win32" ? "uvx.exe" : "uvx";
+  const r = spawnSync(cmd, ["--version"], { stdio: "pipe" });
+  return r.status === 0;
+}
+
+/**
+ * Inject the bundled Node.js distribution into PATH so subsequent spawns
+ * can find `node`, `npm`, and `npx`.
+ *
+ * When the app runs as a packaged .app on macOS, the system PATH is minimal
+ * (/usr/bin:/bin only) — Homebrew, nvm, asdf etc. installs of Node are
+ * invisible. Two breakages flow from that:
+ *
+ *   1. The dev-with-automation.mjs stack spawns `node scripts/ingress.mjs`
+ *      and `node scripts/static-server.mjs`; if `node` is not found those
+ *      processes fail silently and port 8000 never responds.
+ *   2. Most stdio MCP marketplace entries (Slack, GitHub, Figma, etc.)
+ *      use `command: "npx"`. When the agent-server tries to spawn one the
+ *      missing `npx` makes the spawn fail with ENOENT; the SDK reports it
+ *      as an `error_kind: "connection"` MCP test failure, surfaced in the
+ *      install modal as "Could not reach the server".
+ *
+ * We tried bridging via Electron-as-Node (ELECTRON_RUN_AS_NODE=1) wrappers
+ * first. That fixed the ENOENT but introduced a new failure: stdio MCP
+ * servers spawned through the wrapper exited with "McpError: Connection
+ * closed" before the JSON-RPC handshake completed. Electron-as-Node is
+ * fine for our networking helper scripts but its stdin/stdout semantics
+ * differ enough from a vanilla `node` binary that stdio JSON-RPC servers
+ * are not reliable under it. The robust fix is to ship a real Node.js
+ * runtime as an extraResource (see scripts/download-node.mjs and the
+ * `resources/node/` entry in electron-builder.config.mjs) and just put
+ * its bin dir on PATH.
+ *
+ * No-op in dev mode (`npm run desktop`): the user's terminal PATH already
+ * has Node tooling and `app.isPackaged` is false. If the bundled dir is
+ * somehow missing (e.g. the download step was skipped during packaging),
+ * we log a loud warning and leave PATH untouched so the failure mode is
+ * obvious in the console rather than confusing downstream.
+ */
+function injectBundledNode() {
+  if (!app.isPackaged) return;
+
+  const isWin = process.platform === "win32";
+  const nodeRoot = join(process.resourcesPath, "node");
+  // POSIX Node distributions put binaries in bin/; Windows zips put node.exe
+  // and the npm.cmd / npx.cmd wrappers at the distribution root.
+  const binDir = isWin ? nodeRoot : join(nodeRoot, "bin");
+  const nodeExe = isWin ? join(nodeRoot, "node.exe") : join(binDir, "node");
+
+  if (!existsSync(nodeExe)) {
+    console.warn(
+      `[desktop] Bundled Node.js not found at ${nodeExe} — backend ` +
+        "scripts and stdio MCP servers will fail. Run `npm run download-node` " +
+        "and rebuild.",
+    );
+    return;
+  }
+
+  // node.exe alone is not enough. npm / npx are wrapper scripts that exec
+  // npm's JS entry points out of the distribution's own node_modules, and
+  // that directory is the one piece electron-builder drops on Windows (see
+  // restoreBundledNodeNpm in electron-builder.config.mjs). Since we PREPEND
+  // this dir to PATH, a half-copied bundle doesn't just fail to help — it
+  // shadows the user's working npm with shims that die on MODULE_NOT_FOUND.
+  // Warn loudly, but still inject: `node` itself works and the backend
+  // launcher scripts need it.
+  const npmCli = isWin
+    ? join(nodeRoot, "node_modules", "npm", "bin", "npm-cli.js")
+    : join(nodeRoot, "lib", "node_modules", "npm", "bin", "npm-cli.js");
+  if (!existsSync(npmCli)) {
+    console.warn(
+      `[desktop] Bundled npm is incomplete — ${npmCli} is missing. ` +
+        "`npx`-launched subprocesses (stdio MCP servers, ACP servers) will " +
+        "fail with MODULE_NOT_FOUND, and this bundle shadows any npm already " +
+        "on PATH. Rebuild with `npm run download-node`.",
+    );
+  }
+
+  // electron-builder doesn't always preserve the +x bit on POSIX. node, npm,
+  // and npx need to be executable for shell PATH lookup to consider them.
+  if (!isWin) {
+    const required = ["node", "npm", "npx"];
+    for (const name of required) {
+      const p = join(binDir, name);
+      try {
+        if (existsSync(p)) chmodSync(p, 0o755);
+      } catch {
+        // best-effort: a stale read-only mount or test fixture is fine to skip
+      }
+    }
+  }
+
+  const sep = isWin ? ";" : ":";
+  process.env.PATH = `${binDir}${sep}${process.env.PATH ?? ""}`;
+  console.log("[desktop] Injected bundled Node from", binDir);
+}
+
+// ── Readiness polling ���────────────────────────────────────────────────────────
+
+/**
+ * Wait until `url` responds at all (status < 500). Used to confirm the
+ * ingress proxy is bound — not a guarantee that the agent-server behind it
+ * is ready. Use {@link waitForAgentServer} for that.
+ */
+async function waitForUrl(url, timeoutMs = 120_000, intervalMs = 600) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+      if (res.status < 500) return;
+    } catch {}
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(
+    `Timed out waiting for ${url} to become ready (${timeoutMs / 1000}s).`,
+  );
+}
+
+/**
+ * Wait until `url` returns HTTP 200 — meaning the agent-server itself is
+ * serving requests, not just that the ingress proxy is up.
+ *
+ * On first launch, `uvx` has to download a Python toolchain and install
+ * `openhands-agent-server` and its workspace deps from PyPI, which can
+ * easily take a few minutes on a slow network. We poll the route end-to-end
+ * (through ingress on port 8000, so a missing or restarted ingress is also
+ * caught) instead of just probing the static-server fallback that
+ * `waitForUrl` would accept.
+ */
+async function waitForAgentServer(
+  url = "http://localhost:8000/server_info",
+  timeoutMs = 10 * 60_000,
+  intervalMs = 1_000,
+) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+      // Only 200 is success here. 502 from ingress means the upstream agent
+      // server isn't bound yet; 401 means auth is required and the bundled
+      // key didn't reach us — we still treat that as "the agent server is
+      // up", because the proxy got a real HTTP response from it.
+      if (res.status === 200 || res.status === 401) return;
+    } catch {
+      // Transient network / DNS / timeout — keep polling until the deadline.
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error(
+    `Agent server at ${url} never came up (${Math.round(timeoutMs / 1000)}s). ` +
+      "Check the terminal log for errors from uvx / the agent-server process.",
+  );
+}
+
+// ── Windows ───────────────────────────────────────────────────────────────────
+
+let loadingWin = null;
+let mainWin = null;
+
+// Collapsed splash size — loading.html's .container height must match. The
+// expanded height reveals the startup-log console below it ("Show details").
+const LOADING_WIN_WIDTH = 460;
+const LOADING_WIN_HEIGHT = 360;
+const LOADING_WIN_EXPANDED_HEIGHT = 560;
+
+/**
+ * Grow or shrink the loading window to reveal/hide the startup-log console.
+ * Keeps the top edge fixed so the splash content doesn't jump. Invoked from
+ * the renderer ("Show details" toggle) and from showStartupFailure().
+ */
+function setLoadingWindowExpanded(expanded) {
+  if (!loadingWin || loadingWin.isDestroyed()) return;
+  const bounds = loadingWin.getBounds();
+  const height = expanded ? LOADING_WIN_EXPANDED_HEIGHT : LOADING_WIN_HEIGHT;
+  if (bounds.height === height) return;
+  // macOS ignores programmatic resizes of resizable:false windows on some
+  // Electron versions — lift the flag around the change.
+  loadingWin.setResizable(true);
+  loadingWin.setBounds({ ...bounds, height }, true);
+  loadingWin.setResizable(false);
+}
+
+function createLoadingWindow() {
+  loadingWin = new BrowserWindow({
+    width: LOADING_WIN_WIDTH,
+    // Tall enough to fit the streaming status line + the "first launch can
+    // take a few minutes" hint without scrollbars.
+    height: LOADING_WIN_HEIGHT,
+    resizable: false,
+    frame: false,
+    center: true,
+    show: false,
+    // Pre-paint window color; must match --oh-background in loading.html.
+    backgroundColor: "#0b0e14",
+    icon: appIconPath,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+      // Bridges the startup-log console over IPC (see preload.cjs).
+      preload: join(__dirname, "preload.cjs"),
+    },
+  });
+
+  // The renderer can only receive IPC once the page has loaded — replay the
+  // lines buffered until now, then stream live batches (see appendBootLog).
+  loadingWin.webContents.on("did-finish-load", () => {
+    if (!loadingWin || loadingWin.isDestroyed()) return;
+    clearTimeout(bootLogFlushTimer);
+    bootLogFlushTimer = null;
+    bootLogPending = [];
+    if (bootLog.length) {
+      loadingWin.webContents.send("boot-log:batch", bootLog.slice());
+    }
+    bootLogReady = true;
+    if (fatalSummary) {
+      loadingWin.webContents.send("boot-log:fatal", fatalSummary);
+    }
+  });
+
+  loadingWin.loadFile(join(__dirname, "loading.html"));
+  loadingWin.once("ready-to-show", () => loadingWin?.show());
+}
+
+function createMainWindow() {
+  mainWin = new BrowserWindow({
+    width: 1440,
+    height: 900,
+    minWidth: 800,
+    minHeight: 600,
+    show: false,
+    // App-shell background (--oh-background in src/index.css) — avoids white
+    // flashes during the show → maximize repaint after the splash closes.
+    backgroundColor: "#0b0e14",
+    titleBarStyle: process.platform === "darwin" ? "hiddenInset" : "default",
+    icon: appIconPath,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+    },
+  });
+
+  mainWin.loadURL("http://localhost:8000");
+
+  mainWin.once("ready-to-show", () => {
+    loadingWin?.destroy();
+    loadingWin = null;
+    mainWin?.show();
+    mainWin?.maximize();
+  });
+
+  // Route window.open() calls appropriately.
+  mainWin.webContents.setWindowOpenHandler(({ url }) => {
+    // The "Login with OpenHands Cloud" device-flow opens about:blank immediately
+    // on the user's click (to beat popup blockers), then navigates the popup to
+    // the OAuth verification URL once it has one.  We must allow about:blank
+    // through so window.open() returns a non-null WindowProxy; the did-create-window
+    // handler below redirects the popup to the system browser when it navigates.
+    if (url === "about:blank") {
+      return {
+        action: "allow",
+        overrideBrowserWindowOptions: { width: 800, height: 700 },
+      };
+    }
+    // All other URLs open directly in the system browser. The loopback test
+    // goes through URL parsing: prefix matching would also accept
+    // attacker-controlled hosts like http://localhost.evil.com (or
+    // http://localhost@evil.com) and render them in a chromeless native
+    // window. Schemes outside the openExternal allowlist are denied
+    // outright — shell.openExternal would forward them to OS protocol
+    // handlers.
+    if (isLoopbackAppUrl(url)) {
+      return { action: "allow" };
+    }
+    if (isExternalBrowsableUrl(url)) {
+      shell.openExternal(url);
+    }
+    return { action: "deny" };
+  });
+
+  // When the renderer opens a popup (the about:blank above), watch for its
+  // first navigation away from about:blank.  That navigation will be to the
+  // OAuth verification URL — open it in the system browser and close the
+  // now-unneeded Electron popup.
+  mainWin.webContents.on("did-create-window", (popupWin) => {
+    popupWin.webContents.on("will-navigate", (_event, url) => {
+      if (url !== "about:blank" && !isLoopbackAppUrl(url)) {
+        _event.preventDefault();
+        if (isExternalBrowsableUrl(url)) {
+          shell.openExternal(url);
+        }
+        popupWin.close();
+      }
+    });
+  });
+
+  mainWin.on("closed", () => {
+    mainWin = null;
+  });
+}
+
+// ── Startup log buffer ────────────────────────────────────────────────────────
+//
+// Every service log line (all services, all levels, sanitized) is kept in a
+// bounded buffer and streamed to the loading window's console in batches over
+// IPC (see preload.cjs + loading.html). The buffer is the single source of
+// truth: it is replayed once the page loads (lines emitted earlier would
+// otherwise be lost) and it backs the "Copy logs" action. In a packaged app
+// this console is the only log surface — stdout/stderr go to /dev/null when
+// launched from Finder, and the winston file logger is a no-op there (see
+// AGENTS.md on the node_modules strip).
+
+const BOOT_LOG_MAX_LINES = 2000;
+const BOOT_LOG_FLUSH_MS = 200;
+
+const bootLog = []; // {name, line, level}[] — level: stdout|stderr|info|warn|error
+let bootLogPending = [];
+let bootLogFlushTimer = null;
+let bootLogReady = false; // true once loading.html has loaded and can receive
+let fatalSummary = null;
+
+// SGR color codes AND cursor-control CSI sequences (uv/uvicorn can emit
+// either when they mis-detect a TTY).
+const ANSI_CSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+
+/**
+ * Strip ANSI escapes and reduce carriage-return progress redraws (e.g. uv
+ * download bars arrive as one chunk of "\r"-separated frames) to the final
+ * frame — what a real terminal would have settled on.
+ */
+function sanitizeLogLine(line) {
+  const frames = String(line ?? "")
+    .replace(ANSI_CSI_RE, "")
+    .split("\r")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return frames.length ? frames[frames.length - 1] : "";
+}
+
+function appendBootLog(name, line, level) {
+  const entry = { name, line, level };
+  bootLog.push(entry);
+  if (bootLog.length > BOOT_LOG_MAX_LINES) {
+    bootLog.splice(0, bootLog.length - BOOT_LOG_MAX_LINES);
+  }
+  bootLogPending.push(entry);
+  if (!bootLogFlushTimer) {
+    bootLogFlushTimer = setTimeout(flushBootLog, BOOT_LOG_FLUSH_MS);
+  }
+}
+
+function flushBootLog() {
+  clearTimeout(bootLogFlushTimer);
+  bootLogFlushTimer = null;
+  if (!bootLogPending.length) return;
+  const batch = bootLogPending;
+  bootLogPending = [];
+  // Not ready / window gone: drop the batch — the entries stay in bootLog,
+  // which did-finish-load replays wholesale.
+  if (bootLogReady && loadingWin && !loadingWin.isDestroyed()) {
+    loadingWin.webContents.send("boot-log:batch", batch);
+  }
+}
+
+/**
+ * Switch the splash into its failure state: expand the console and show the
+ * error summary with Copy logs / Quit actions, keeping the window open so the
+ * user can actually read why startup failed. Returns false when the loading
+ * window is gone (caller falls back to a native dialog).
+ */
+function showStartupFailure(summary) {
+  if (!loadingWin || loadingWin.isDestroyed()) return false;
+  fatalSummary = summary;
+  setLoadingWindowExpanded(true);
+  if (bootLogReady) {
+    flushBootLog();
+    loadingWin.webContents.send("boot-log:fatal", summary);
+  }
+  // If the page hasn't loaded yet, did-finish-load replays the buffer and
+  // then delivers fatalSummary.
+  return true;
+}
+
+// IPC surface for the loading window (see preload.cjs). Guarded to that
+// window's webContents so the main app window can never reach these.
+function isLoadingWinEvent(event) {
+  return (
+    loadingWin !== null &&
+    !loadingWin.isDestroyed() &&
+    event.sender === loadingWin.webContents
+  );
+}
+
+ipcMain.handle("boot-log:set-expanded", (event, expanded) => {
+  if (!isLoadingWinEvent(event)) return;
+  setLoadingWindowExpanded(Boolean(expanded));
+});
+
+ipcMain.handle("boot-log:copy", (event) => {
+  if (!isLoadingWinEvent(event)) return 0;
+  clipboard.writeText(bootLog.map((e) => `[${e.name}] ${e.line}`).join("\n"));
+  return bootLog.length;
+});
+
+// The frameless splash has no close control; the failure state shows a Quit
+// button instead.
+ipcMain.handle("boot-log:quit", (event) => {
+  if (!isLoadingWinEvent(event)) return;
+  app.quit();
+});
+
+// ── Backend stack ─────────────────────────────────────────────────────────────
+
+/**
+ * Update the status line on the loading window, if it's still alive.
+ *
+ * The loading screen exposes a global `window.__setLoadingStatus(line)`
+ * function (see loading.html) that swaps the status text. We call it via
+ * `executeJavaScript` so no preload script / IPC plumbing is needed.
+ *
+ * Best-effort: any failure (window destroyed, JS not loaded yet, etc.) is
+ * swallowed — this is purely a UX nicety and must never crash the launcher.
+ */
+function setLoadingStatus(line) {
+  if (!loadingWin || loadingWin.isDestroyed()) return;
+  // Limit to a single line, max ~120 chars, to keep the splash readable.
+  const oneLine = String(line ?? "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 120);
+  if (!oneLine) return;
+  const safe = JSON.stringify(oneLine);
+  loadingWin.webContents
+    .executeJavaScript(
+      `window.__setLoadingStatus && window.__setLoadingStatus(${safe});`,
+      true,
+    )
+    .catch(() => {});
+}
+
+/**
+ * Phase marker: headline + a line in the startup-log console, so the log
+ * records which stage a failed boot died in.
+ */
+function setBootPhase(message) {
+  appendBootLog("desktop", message, "info");
+  setLoadingStatus(message);
+}
+
+/**
+ * Last few `level: "error"` service log lines (spawn failures, non-zero
+ * exits). Appended to the startup-failure dialog: a packaged app launched
+ * from Finder has stdout/stderr wired to /dev/null, so without this a
+ * crashed ingress/static-server surfaces only as an opaque "timed out
+ * waiting for http://localhost:8000" message.
+ */
+const recentServiceErrors = [];
+
+/**
+ * Forward dev-stack service log lines to (a) the loading screen and (b) the
+ * terminal log. The terminal already receives them via `logService`; we add
+ * a tee here so the user can see what's happening on first launch when uvx
+ * is downloading Python + agent-server.
+ */
+function handleServiceLog(name, line, level) {
+  if (!line) return;
+  const clean = sanitizeLogLine(line);
+  if (!clean) return;
+  // Full-fidelity stream: every service and level goes to the console buffer.
+  // The one-line headline below stays filtered to the interesting services.
+  appendBootLog(name, clean, level);
+  if (name === "agent-server" || name === "automation") {
+    setLoadingStatus(`${name}: ${clean}`);
+  }
+  // Mirror errors to a `[desktop]` terminal line so dev runs stay grep-friendly.
+  if (level === "error") {
+    console.error(`[desktop] [${name}] ${clean}`);
+    // Errors from ANY service (including ingress/static, which the headline
+    // filter above skips) are worth showing — a dead ingress is exactly the
+    // case where the user would otherwise stare at a silent 120 s timeout.
+    setLoadingStatus(`${name}: ${clean}`);
+    recentServiceErrors.push(`${name}: ${clean}`);
+    if (recentServiceErrors.length > 5) recentServiceErrors.shift();
+  }
+}
+
+async function startStack() {
+  const entryUrl = pathToFileURL(
+    join(scriptsDir, "dev-with-automation.mjs"),
+  ).href;
+  const { main } = await import(entryUrl);
+
+  // main() starts agent-server + automation backend + static server + ingress.
+  //   skipNpmCheck: npm is not needed at runtime in static mode.
+  //   agentServerReadyTimeoutMs: dev defaults to 60 s (warm uvx cache); a
+  //     packaged binary on a fresh machine can spend several minutes inside
+  //     uvx the first time, downloading Python + installing openhands-
+  //     agent-server from PyPI. 10 minutes is generous but bounded.
+  //   onServiceLog: stream uvx/agent-server output to the loading window so
+  //     the user sees progress instead of an indefinite spinner.
+  const result = await main({
+    bannerTitle: "OpenHands Agent Canvas",
+    staticMode: true,
+    staticDir: buildDir,
+    mode: "agent-canvas",
+    isPublic: false,
+    skipNpmCheck: true,
+    agentServerReadyTimeoutMs: 10 * 60_000,
+    onServiceLog: handleServiceLog,
+  });
+
+  // main() returns { config, agentServerReady } — treat a timeout as a fatal
+  // startup error so the splash shows a clear dialog instead of dropping the
+  // user into a half-booted UI that will only emit "Request timeout" popups.
+  if (result?.agentServerReady === false) {
+    throw new Error(
+      "The agent server did not finish starting in time. " +
+        "On first launch this can take several minutes while uvx downloads " +
+        "Python and the OpenHands agent-server from PyPI. " +
+        "Check your internet connection and try again.",
+    );
+  }
+}
+
+// ── App lifecycle ─────────────────────────────────────────────────────────────
+
+app.whenReady().then(async () => {
+  nativeTheme.themeSource = "dark";
+
+  // Set the dock icon explicitly on macOS so `npm run desktop` shows the
+  // OpenHands logo instead of the default Electron logo. In a packaged
+  // build the .app bundle's icon.icns already provides this, but
+  // app.dock.setIcon() is a cheap idempotent override that also fixes
+  // the dev workflow.
+  if (process.platform === "darwin" && app.dock && existsSync(appIconPath)) {
+    app.dock.setIcon(nativeImage.createFromPath(appIconPath));
+  }
+
+  injectBundledUv();
+  injectBundledNode();
+
+  if (!uvxAvailable()) {
+    dialog.showErrorBox(
+      "Missing prerequisite: uv",
+      app.isPackaged
+        ? "The bundled uv binary could not be found. Please reinstall OpenHands Agent Canvas."
+        : "uv (uvx) is not installed.\n\nInstall it from https://docs.astral.sh/uv/ then restart.",
+    );
+    app.quit();
+    return;
+  }
+
+  createLoadingWindow();
+
+  try {
+    setBootPhase("Starting backend services…");
+    await startStack();
+
+    // Stage 1: ingress proxy is bound (anything < 500 on /).
+    setBootPhase("Waiting for proxy…");
+    await waitForUrl("http://localhost:8000");
+
+    // Stage 2: the agent-server behind the proxy is actually serving
+    // requests. `startStack()` already waited for this internally, but we
+    // re-probe end-to-end here so that if the user closes the splash race
+    // window between processes binding, we still open the main window with
+    // a live backend. Cheap (a single 200 response) when everything is up.
+    setBootPhase("Connecting to agent server…");
+    await waitForAgentServer("http://localhost:8000/server_info", 60_000);
+
+    setBootPhase("Ready.");
+    createMainWindow();
+  } catch (err) {
+    const summary =
+      err.message +
+      " Ensure ports 8000, 18000, and 18001 are free, then try again.";
+    // Record the failure in the terminal and the startup-log buffer so it
+    // shows (and copies) as the final console line.
+    console.error("[desktop] Startup failed:", err);
+    appendBootLog("desktop", summary, "error");
+    // Keep the splash open in its failure state so the full startup log can
+    // be read and copied; the app quits via the splash's Quit button (or
+    // Cmd+Q / closing the window).
+    if (showStartupFailure(summary)) return;
+    // Loading window already gone — fall back to the old dialog-and-quit.
+    const errorTail = recentServiceErrors.length
+      ? `\n\nRecent service errors:\n${recentServiceErrors.join("\n")}`
+      : "";
+    dialog.showErrorBox("OpenHands Agent Canvas failed to start", summary + errorTail);
+    app.quit();
+  }
+});
+
+// ── Graceful shutdown ─────────────────────────────────────────────────────────
+//
+// dev-with-automation.mjs spawns the backend processes with detached:true so
+// they form their own OS process groups and survive the parent's death by
+// default. We must explicitly kill them when the app quits.
+//
+// createShutdownHookRegistry (dev-process-utils.mjs) already registered a
+// SIGTERM handler that iterates every tracked process, calls signalProcessTree
+// on its group, waits for exit, then calls process.exit(0). We just need to
+// fire that handler before Electron lets the process die.
+//
+// Flow:
+//   user closes window / Cmd+Q
+//     → window-all-closed → app.quit()
+//     → before-quit fires (first time)  → we preventDefault + send SIGTERM
+//     → SIGTERM handler kills all children, calls process.exit(0)
+//     → before-quit fires again (cleanupStarted=true) → we return, Electron exits
+//
+// Windows has no real POSIX signals: process.kill(pid, "SIGTERM") would
+// terminate this process WITHOUT running the "SIGTERM" listener, skipping
+// cleanup and orphaning the children on ports 8000/18000/18001 (the next
+// launch then fails at startup). process.emit("SIGTERM") runs the same
+// registered handler in-process instead.
+
+let cleanupStarted = false;
+
+app.on("before-quit", (event) => {
+  if (cleanupStarted) return; // SIGTERM cleanup already running — allow exit
+
+  cleanupStarted = true;
+  event.preventDefault();
+
+  console.log("[desktop] Stopping backend services…");
+  if (process.platform === "win32") {
+    // Run the cleanup handler in-process (see header note). emit() returns
+    // false when no listener is registered — the stack never started, so
+    // there is nothing to clean up and we can exit immediately.
+    if (!process.emit("SIGTERM")) app.exit(0);
+  } else {
+    process.kill(process.pid, "SIGTERM");
+  }
+
+  // Safety net: if the SIGTERM handler doesn't finish within 6 s, force-quit.
+  const t = setTimeout(() => {
+    console.warn("[desktop] Cleanup timed out — forcing exit");
+    app.exit(0);
+  }, 6000);
+  if (t.unref) t.unref();
+});
+
+app.on("window-all-closed", () => {
+  app.quit();
+});
+
+// macOS: clicking the dock icon when no window is open re-launches the app.
+app.on("activate", () => {
+  if (BrowserWindow.getAllWindows().length === 0) {
+    // The backend is already running — just open a new renderer window.
+    if (mainWin === null) createMainWindow();
+  }
+});

electron/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "agent-canvas",
+  "productName": "OpenHands Agent Canvas",
+  "version": "1.0.0",
+  "private": true,
+  "main": "main.mjs"
+}

electron/preload.cjs

@@ -0,0 +1,31 @@
+/**
+ * Preload for the loading window (loading.html).
+ *
+ * Bridges the startup-log console to the main process over IPC while keeping
+ * contextIsolation (and the default renderer sandbox) intact. The one-line
+ * status headline intentionally does NOT go through here — main.mjs sets it
+ * via executeJavaScript → window.__setLoadingStatus (see setLoadingStatus).
+ *
+ * CommonJS on purpose: sandboxed preload scripts cannot use ESM.
+ */
+const { contextBridge, ipcRenderer } = require("electron");
+
+contextBridge.exposeInMainWorld("desktopBoot", {
+  /** Subscribe to batched startup-log lines: cb([{name, line, level}, …]). */
+  onLogBatch(cb) {
+    if (typeof cb !== "function") return;
+    ipcRenderer.on("boot-log:batch", (_event, batch) => cb(batch));
+  },
+  /** Subscribe to the fatal startup-failure notification: cb(summary). */
+  onFatal(cb) {
+    if (typeof cb !== "function") return;
+    ipcRenderer.on("boot-log:fatal", (_event, summary) => cb(summary));
+  },
+  /** Grow/shrink the window to reveal or hide the console panel. */
+  setDetailsExpanded: (expanded) =>
+    ipcRenderer.invoke("boot-log:set-expanded", Boolean(expanded)),
+  /** Copy the full buffered startup log to the clipboard. */
+  copyLogs: () => ipcRenderer.invoke("boot-log:copy"),
+  /** Quit the app (failure-state action; the frameless splash has no close UI). */
+  quit: () => ipcRenderer.invoke("boot-log:quit"),
+});

public/browserconfig.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<browserconfig>
+    <msapplication>
+        <tile>
+            <square150x150logo src="/mstile-150x150.png"/>
+            <TileColor>#da532c</TileColor>
+        </tile>
+    </msapplication>
+</browserconfig>

public/mockServiceWorker.js

@@ -0,0 +1,361 @@
+/* eslint-disable */
+/* tslint:disable */
+
+/**
+ * Mock Service Worker.
+ * @see https://github.com/mswjs/msw
+ * - Please do NOT modify this file.
+ */
+
+const PACKAGE_VERSION = '2.15.0'
+const INTEGRITY_CHECKSUM = '03cb67ac84128e63d7cd722a6e5b7f1e'
+const IS_MOCKED_RESPONSE = Symbol('isMockedResponse')
+const activeClientIds = new Set()
+
+addEventListener('install', function () {
+  self.skipWaiting()
+})
+
+addEventListener('activate', function (event) {
+  event.waitUntil(self.clients.claim())
+})
+
+addEventListener('message', async function (event) {
+  const clientId = Reflect.get(event.source || {}, 'id')
+
+  if (!clientId || !self.clients) {
+    return
+  }
+
+  const client = await self.clients.get(clientId)
+
+  if (!client) {
+    return
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  })
+
+  switch (event.data) {
+    case 'KEEPALIVE_REQUEST': {
+      sendToClient(client, {
+        type: 'KEEPALIVE_RESPONSE',
+      })
+      break
+    }
+
+    case 'INTEGRITY_CHECK_REQUEST': {
+      sendToClient(client, {
+        type: 'INTEGRITY_CHECK_RESPONSE',
+        payload: {
+          packageVersion: PACKAGE_VERSION,
+          checksum: INTEGRITY_CHECKSUM,
+        },
+      })
+      break
+    }
+
+    case 'MOCK_ACTIVATE': {
+      activeClientIds.add(clientId)
+
+      sendToClient(client, {
+        type: 'MOCKING_ENABLED',
+        payload: {
+          client: {
+            id: client.id,
+            frameType: client.frameType,
+          },
+        },
+      })
+      break
+    }
+
+    case 'CLIENT_CLOSED': {
+      activeClientIds.delete(clientId)
+
+      const remainingClients = allClients.filter((client) => {
+        return client.id !== clientId
+      })
+
+      // Unregister itself when there are no more clients
+      if (remainingClients.length === 0) {
+        self.registration.unregister()
+      }
+
+      break
+    }
+  }
+})
+
+addEventListener('fetch', function (event) {
+  const requestInterceptedAt = Date.now()
+
+  // Bypass navigation requests.
+  if (event.request.mode === 'navigate') {
+    return
+  }
+
+  // Opening the DevTools triggers the "only-if-cached" request
+  // that cannot be handled by the worker. Bypass such requests.
+  if (
+    event.request.cache === 'only-if-cached' &&
+    event.request.mode !== 'same-origin'
+  ) {
+    return
+  }
+
+  // Bypass all requests when there are no active clients.
+  // Prevents the self-unregistered worked from handling requests
+  // after it's been terminated (still remains active until the next reload).
+  if (activeClientIds.size === 0) {
+    return
+  }
+
+  const requestId = crypto.randomUUID()
+  event.respondWith(handleRequest(event, requestId, requestInterceptedAt))
+})
+
+/**
+ * @param {FetchEvent} event
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ */
+async function handleRequest(event, requestId, requestInterceptedAt) {
+  const client = await resolveMainClient(event)
+  const requestCloneForEvents = event.request.clone()
+  const response = await getResponse(
+    event,
+    client,
+    requestId,
+    requestInterceptedAt,
+  )
+
+  // Send back the response clone for the "response:*" life-cycle events.
+  // Ensure MSW is active and ready to handle the message, otherwise
+  // this message will pend indefinitely.
+  if (client && activeClientIds.has(client.id)) {
+    const serializedRequest = await serializeRequest(requestCloneForEvents)
+
+    // Omit the body of server-sent event stream responses.
+    // Cloning such responses would prevent client-side stream cancelations
+    // from reaching the original stream (a teed stream only cancels its
+    // source once both of its branches cancel) and would buffer the
+    // entire stream into the unconsumed clone indefinitely.
+    const isEventStreamResponse = response.headers
+      .get('content-type')
+      ?.toLowerCase()
+      .startsWith('text/event-stream')
+
+    // Clone the response so both the client and the library could consume it.
+    const responseClone = isEventStreamResponse ? null : response.clone()
+
+    sendToClient(
+      client,
+      {
+        type: 'RESPONSE',
+        payload: {
+          isMockedResponse: IS_MOCKED_RESPONSE in response,
+          request: {
+            id: requestId,
+            ...serializedRequest,
+          },
+          response: {
+            type: response.type,
+            status: response.status,
+            statusText: response.statusText,
+            headers: Object.fromEntries(response.headers.entries()),
+            body: responseClone ? responseClone.body : null,
+          },
+        },
+      },
+      responseClone && responseClone.body
+        ? [serializedRequest.body, responseClone.body]
+        : [],
+    )
+  }
+
+  return response
+}
+
+/**
+ * Resolve the main client for the given event.
+ * Client that issues a request doesn't necessarily equal the client
+ * that registered the worker. It's with the latter the worker should
+ * communicate with during the response resolving phase.
+ * @param {FetchEvent} event
+ * @returns {Promise<Client | undefined>}
+ */
+async function resolveMainClient(event) {
+  const client = await self.clients.get(event.clientId)
+
+  if (activeClientIds.has(event.clientId)) {
+    return client
+  }
+
+  if (client?.frameType === 'top-level') {
+    return client
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  })
+
+  return allClients
+    .filter((client) => {
+      // Get only those clients that are currently visible.
+      return client.visibilityState === 'visible'
+    })
+    .find((client) => {
+      // Find the client ID that's recorded in the
+      // set of clients that have registered the worker.
+      return activeClientIds.has(client.id)
+    })
+}
+
+/**
+ * @param {FetchEvent} event
+ * @param {Client | undefined} client
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ * @returns {Promise<Response>}
+ */
+async function getResponse(event, client, requestId, requestInterceptedAt) {
+  // Clone the request because it might've been already used
+  // (i.e. its body has been read and sent to the client).
+  const requestClone = event.request.clone()
+
+  function passthrough() {
+    // Cast the request headers to a new Headers instance
+    // so the headers can be manipulated with.
+    const headers = new Headers(requestClone.headers)
+
+    // Remove the "accept" header value that marked this request as passthrough.
+    // This prevents request alteration and also keeps it compliant with the
+    // user-defined CORS policies.
+    const acceptHeader = headers.get('accept')
+    if (acceptHeader) {
+      const values = acceptHeader.split(',').map((value) => value.trim())
+      const filteredValues = values.filter(
+        (value) => value !== 'msw/passthrough',
+      )
+
+      if (filteredValues.length > 0) {
+        headers.set('accept', filteredValues.join(', '))
+      } else {
+        headers.delete('accept')
+      }
+    }
+
+    return fetch(requestClone, { headers })
+  }
+
+  // Bypass mocking when the client is not active.
+  if (!client) {
+    return passthrough()
+  }
+
+  // Bypass initial page load requests (i.e. static assets).
+  // The absence of the immediate/parent client in the map of the active clients
+  // means that MSW hasn't dispatched the "MOCK_ACTIVATE" event yet
+  // and is not ready to handle requests.
+  if (!activeClientIds.has(client.id)) {
+    return passthrough()
+  }
+
+  // Notify the client that a request has been intercepted.
+  const serializedRequest = await serializeRequest(event.request)
+  const clientMessage = await sendToClient(
+    client,
+    {
+      type: 'REQUEST',
+      payload: {
+        id: requestId,
+        interceptedAt: requestInterceptedAt,
+        ...serializedRequest,
+      },
+    },
+    [serializedRequest.body],
+  )
+
+  switch (clientMessage.type) {
+    case 'MOCK_RESPONSE': {
+      return respondWithMock(clientMessage.data)
+    }
+
+    case 'PASSTHROUGH': {
+      return passthrough()
+    }
+  }
+
+  return passthrough()
+}
+
+/**
+ * @param {Client} client
+ * @param {any} message
+ * @param {Array<Transferable>} transferrables
+ * @returns {Promise<any>}
+ */
+function sendToClient(client, message, transferrables = []) {
+  return new Promise((resolve, reject) => {
+    const channel = new MessageChannel()
+
+    channel.port1.onmessage = (event) => {
+      if (event.data && event.data.error) {
+        return reject(event.data.error)
+      }
+
+      resolve(event.data)
+    }
+
+    client.postMessage(message, [
+      channel.port2,
+      ...transferrables.filter(Boolean),
+    ])
+  })
+}
+
+/**
+ * @param {Response} response
+ * @returns {Response}
+ */
+function respondWithMock(response) {
+  // Setting response status code to 0 is a no-op.
+  // However, when responding with a "Response.error()", the produced Response
+  // instance will have status code set to 0. Since it's not possible to create
+  // a Response instance with status code 0, handle that use-case separately.
+  if (response.status === 0) {
+    return Response.error()
+  }
+
+  const mockedResponse = new Response(response.body, response)
+
+  Reflect.defineProperty(mockedResponse, IS_MOCKED_RESPONSE, {
+    value: true,
+    enumerable: true,
+  })
+
+  return mockedResponse
+}
+
+/**
+ * @param {Request} request
+ */
+async function serializeRequest(request) {
+  return {
+    url: request.url,
+    mode: request.mode,
+    method: request.method,
+    headers: Object.fromEntries(request.headers.entries()),
+    cache: request.cache,
+    credentials: request.credentials,
+    destination: request.destination,
+    integrity: request.integrity,
+    redirect: request.redirect,
+    referrer: request.referrer,
+    referrerPolicy: request.referrerPolicy,
+    body: await request.arrayBuffer(),
+    keepalive: request.keepalive,
+  }
+}

public/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:

public/site.webmanifest

@@ -0,0 +1,19 @@
+{
+    "name": "",
+    "short_name": "",
+    "icons": [
+        {
+            "src": "/android-chrome-192x192.png",
+            "sizes": "192x192",
+            "type": "image/png"
+        },
+        {
+            "src": "/android-chrome-512x512.png",
+            "sizes": "512x512",
+            "type": "image/png"
+        }
+    ],
+    "theme_color": "#ffffff",
+    "background_color": "#ffffff",
+    "display": "standalone"
+}

scripts/brand-dev-electron.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Brand the dev Electron app bundle with the product name (macOS only).
+ *
+ * Run automatically as the `predesktop` npm hook.
+ *
+ * WHY THIS EXISTS
+ *
+ * `npm run desktop` runs the app inside Electron's own prebuilt bundle,
+ * node_modules/electron/dist/Electron.app. macOS derives the name it shows
+ * in the Dock tooltip, the ⌘-Tab switcher and Finder from that bundle, at
+ * launch, before any JavaScript runs. No runtime API can change it —
+ * `app.setName()`, `app.name` and package.json `productName` only drive
+ * Electron's own notion of the name (menu bar, About panel, and
+ * app.getPath("userData")).
+ *
+ * The packaged app has never had this problem: electron-builder emits a
+ * bundle literally named "<productName>.app" with matching plist keys. This
+ * script puts the dev bundle in that same state.
+ *
+ * THE BUNDLE FILENAME IS THE PART THAT ACTUALLY SHOWS
+ *
+ * Patching the plist alone is NOT enough — verified the hard way. macOS
+ * prefers the bundle's filesystem name over CFBundleName/CFBundleDisplayName
+ * for the Dock tooltip. Two installed apps prove each half of this:
+ *
+ *   DBeaver.app        CFBundleName "DBeaver Community" → displays "DBeaver"
+ *                      (the filename wins over the plist)
+ *   Antigravity.app    CFBundleExecutable "Electron"    → displays "Antigravity"
+ *                      (an Electron app whose executable name is irrelevant)
+ *
+ * So the fix aligns every source of the name at once: the .app directory
+ * name, CFBundleName and CFBundleDisplayName. That is exactly the shape of a
+ * packaged build, which is known to display correctly.
+ *
+ * Renaming the bundle means node_modules/electron/path.txt has to move with
+ * it: getElectronPath() in node_modules/electron/index.js joins path.txt onto
+ * dist/ and silently re-downloads Electron (~100 MB) if the result does not
+ * exist. The two are updated together, and the rename is rolled back if
+ * path.txt cannot be written.
+ *
+ * WHY THIS IS SAFE
+ *
+ *   - Electron's prebuilt dist is ad-hoc *linker-signed*: `codesign -dv`
+ *     reports `flags=0x20002(adhoc,linker-signed)`, `Info.plist=not bound`,
+ *     `Sealed Resources=none`. The signature covers only the Mach-O, so
+ *     editing Info.plist does not invalidate it and no re-signing is needed.
+ *   - `npm run build:desktop` is unaffected: electron-builder packages from
+ *     its own download cache (~/Library/Caches/electron/electron-v*.zip),
+ *     never from node_modules/electron/dist.
+ *
+ * WHAT IT DELIBERATELY DOES NOT TOUCH
+ *
+ *   CFBundleExecutable — left as "Electron". Antigravity above shows it has
+ *     no bearing on the displayed name; it only feeds ps / Activity Monitor.
+ *     Leaving it alone keeps path.txt's trailing segments valid.
+ *   CFBundleIdentifier — kept at com.github.Electron. Changing it would split
+ *     LaunchServices / TCC state per checkout for no visible gain.
+ *
+ * The changes live in node_modules, which `npm ci` wipes. That is fine: the
+ * `predesktop` hook re-applies them on every `npm run desktop`.
+ *
+ * This script must never block the desktop run — every failure path warns
+ * and exits 0.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..");
+
+// Both keys are set. CFBundleDisplayName is the one LaunchServices reports;
+// CFBundleName is the fallback and shows up in other bundle-name surfaces.
+const NAME_KEYS = ["CFBundleDisplayName", "CFBundleName"];
+
+function warn(message) {
+  console.warn(`[brand-dev-electron] ${message}`);
+}
+
+/** Root of the installed `electron` package, or null if it isn't resolvable. */
+function resolveElectronPackage() {
+  const require = createRequire(import.meta.url);
+  return dirname(require.resolve("electron/package.json"));
+}
+
+/** Current value of `key`, or null when the key is absent. */
+function readPlistString(plistPath, key) {
+  try {
+    return execFileSync(
+      "plutil",
+      ["-extract", key, "raw", "-o", "-", plistPath],
+      { encoding: "utf8" },
+    ).trim();
+  } catch {
+    return null;
+  }
+}
+
+function writePlistString(plistPath, key, value) {
+  execFileSync("plutil", ["-replace", key, "-string", value, plistPath], {
+    stdio: "pipe",
+  });
+}
+
+/**
+ * Rename dist/<current>.app to dist/<productName>.app and repoint path.txt.
+ * Returns { appDir, renamed }, or null if the bundle can't be determined.
+ */
+function ensureBundleName(pkgDir, productName) {
+  const distDir = join(pkgDir, "dist");
+  const pathFile = join(pkgDir, "path.txt");
+  if (!existsSync(pathFile)) {
+    warn(`No ${pathFile} — leaving the dev bundle alone.`);
+    return null;
+  }
+
+  // e.g. "Electron.app/Contents/MacOS/Electron" — only the first segment
+  // (the bundle directory) is ours to rename.
+  const relative = readFileSync(pathFile, "utf8").trim();
+  const segments = relative.split("/");
+  const currentName = segments[0];
+  const desiredName = `${productName}.app`;
+  if (!currentName.endsWith(".app")) {
+    warn(`Unexpected path.txt entry "${relative}" — leaving the bundle alone.`);
+    return null;
+  }
+
+  const desiredDir = join(distDir, desiredName);
+  if (currentName === desiredName && existsSync(desiredDir)) {
+    return { appDir: desiredDir, renamed: false };
+  }
+
+  const currentDir = join(distDir, currentName);
+  let renamed = false;
+  if (existsSync(currentDir) && currentDir !== desiredDir) {
+    if (existsSync(desiredDir)) {
+      // Both present: a previous run renamed the bundle and something
+      // restored the original. Prefer the correctly named one and just fix
+      // path.txt rather than clobbering either bundle.
+      warn(`Both ${currentName} and ${desiredName} exist — using the latter.`);
+    } else {
+      renameSync(currentDir, desiredDir);
+      renamed = true;
+    }
+  } else if (!existsSync(desiredDir)) {
+    warn(`No Electron bundle under ${distDir} — leaving the dev bundle alone.`);
+    return null;
+  }
+
+  // path.txt MUST agree with the directory on disk; a stale entry makes
+  // getElectronPath() re-download Electron on the next run.
+  segments[0] = desiredName;
+  try {
+    writeFileSync(pathFile, segments.join("/"));
+  } catch (err) {
+    // Undo the rename so the checkout is left in a working state.
+    if (existsSync(desiredDir) && !existsSync(currentDir)) {
+      try {
+        renameSync(desiredDir, currentDir);
+      } catch {
+        warn(`Could not roll back the bundle rename in ${distDir}.`);
+      }
+    }
+    warn(`Could not update ${pathFile}: ${err.message}`);
+    return null;
+  }
+
+  return { appDir: desiredDir, renamed };
+}
+
+function main() {
+  // The Dock/⌘-Tab name is a macOS bundle concept. On Windows the dev
+  // taskbar name comes from electron.exe's version resource and on Linux
+  // from the .desktop file / WM_CLASS — neither exists until the app is
+  // packaged, so there is nothing to patch.
+  if (process.platform !== "darwin") return;
+
+  const manifestPath = join(projectRoot, "electron", "package.json");
+  let productName;
+  try {
+    productName = JSON.parse(readFileSync(manifestPath, "utf8")).productName;
+  } catch (err) {
+    warn(`Could not read ${manifestPath}: ${err.message}`);
+    return;
+  }
+  if (!productName) {
+    warn(`No productName in ${manifestPath} — leaving the dev bundle alone.`);
+    return;
+  }
+  // The name becomes a directory entry; a "/" would silently retarget it.
+  if (productName.includes("/")) {
+    warn(`productName "${productName}" cannot be used as a bundle name.`);
+    return;
+  }
+
+  let pkgDir;
+  try {
+    pkgDir = resolveElectronPackage();
+  } catch (err) {
+    warn(`Could not resolve the electron package: ${err.message}`);
+    return;
+  }
+
+  let bundle;
+  try {
+    bundle = ensureBundleName(pkgDir, productName);
+  } catch (err) {
+    warn(`Could not rename the dev bundle: ${err.message}`);
+    return;
+  }
+  if (!bundle) return;
+
+  const plistPath = join(bundle.appDir, "Contents", "Info.plist");
+  if (!existsSync(plistPath)) {
+    warn(`No Info.plist at ${plistPath} — leaving the plist alone.`);
+    return;
+  }
+
+  const stale = NAME_KEYS.filter(
+    (key) => readPlistString(plistPath, key) !== productName,
+  );
+
+  try {
+    for (const key of stale) writePlistString(plistPath, key, productName);
+  } catch (err) {
+    // Read-only node_modules (CI caches, sandboxes) lands here. The app still
+    // runs; only the displayed name keeps saying "Electron".
+    warn(`Could not patch ${plistPath}: ${err.message}`);
+    return;
+  }
+
+  // Stay quiet when there was nothing to do, so repeat runs don't add noise.
+  if (bundle.renamed || stale.length > 0) {
+    console.log(
+      `[brand-dev-electron] Dev Electron bundle now identifies as "${productName}".`,
+    );
+  }
+}
+
+main();

scripts/check-sdk-version-sync.mjs

@@ -0,0 +1,500 @@
+#!/usr/bin/env node
+
+/**
+ * Check SDK Version Sync
+ *
+ * Verifies two things against versions.agentServer in config/defaults.json:
+ *
+ * 1. The local @openhands/typescript-client pin in package.json. Canvas renders
+ *    the ACP provider picker from that generated registry mirror but launches
+ *    the adapter through the agent-server image, so a skew ships a picker
+ *    offering models and launch commands agent-server does not implement.
+ *
+ * 2. That the released automation package (openhands-automation on PyPI)
+ *    uses the SDK version expected for that automation release for all agent SDK libraries:
+ *   - openhands-sdk
+ *   - openhands-tools
+ *   - openhands-workspace
+ *   - openhands-agent-server
+ *
+ * This script checks the RELEASED PyPI version of openhands-automation (as specified
+ * by versions.automation in config/defaults.json), not the main branch.
+ * The expected SDK dependency version is versions.agentServer — the two must
+ * always match, so this script catches any drift.
+ *
+ * This script is run in CI to catch version drift between projects.
+ *
+ * Usage:
+ *   node scripts/check-sdk-version-sync.mjs
+ *   EXPECTED_SDK_VERSION=1.46.0 node scripts/check-sdk-version-sync.mjs
+ *   node scripts/check-sdk-version-sync.mjs --check-pypi
+ *
+ * Environment variables:
+ *   EXPECTED_SDK_VERSION      - Override the expected version (instead of reading from config/defaults.json)
+ *   AUTOMATION_PACKAGE_NAME   - Override the automation package name (default: openhands-automation)
+ *   AUTOMATION_PACKAGE_VERSION - Override the automation package version (instead of reading from config/defaults.json)
+ *
+ * Options:
+ *   --check-pypi    Also check the latest SDK version on PyPI
+ *   --help          Show help
+ *
+ * Exit codes:
+ *   0 - All SDK versions match
+ *   1 - Version mismatch detected or error occurred
+ */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..");
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const checkPyPI = args.includes("--check-pypi");
+const showHelp = args.includes("--help") || args.includes("-h");
+
+if (showHelp) {
+  console.log(`
+SDK Version Sync Check
+
+Verifies that the released openhands-automation package on PyPI uses the
+SDK version expected for that automation release.
+
+The automation version is read from config/defaults.json (versions.automation).
+The expected SDK dependency version is read from versions.agentServer.
+
+Usage:
+  node scripts/check-sdk-version-sync.mjs [options]
+
+Options:
+  --check-pypi    Also check the latest SDK version on PyPI
+  --help, -h      Show this help
+
+Environment variables:
+  EXPECTED_SDK_VERSION        Override the expected SDK version (instead of reading from config/defaults.json)
+  AUTOMATION_PACKAGE_NAME     Override the automation package name (default: openhands-automation)
+  AUTOMATION_PACKAGE_VERSION  Override the automation package version (instead of reading from config/defaults.json)
+
+Triggering from other repos:
+  The automation repo or SDK repo can trigger this check via GitHub repository_dispatch:
+
+  curl -X POST \\
+    -H "Authorization: token \$GITHUB_TOKEN" \\
+    -H "Accept: application/vnd.github.v3+json" \\
+    https://api.github.com/repos/OpenHands/OpenHands/dispatches \\
+    -d '{"event_type": "sdk-version-check", "client_payload": {"version": "1.46.0"}}'
+`);
+  process.exit(0);
+}
+
+// ANSI color codes for terminal output
+const colors = {
+  reset: "\x1b[0m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  dim: "\x1b[2m",
+};
+
+// SDK packages that must have matching versions
+const SDK_PACKAGES = [
+  "openhands-sdk",
+  "openhands-tools",
+  "openhands-workspace",
+  "openhands-agent-server",
+];
+
+// Mirrors the SDK's ACP provider registry. Must track versions.agentServer:
+// the picker is rendered from this pin but the adapter is launched by that
+// image, so a skew advertises models the running agent-server cannot run.
+const CLIENT_PACKAGE_NAME = "@openhands/typescript-client";
+
+// Configurable automation package (can be overridden via env)
+const AUTOMATION_PACKAGE_NAME = process.env.AUTOMATION_PACKAGE_NAME || "openhands-automation";
+
+// Default retry configuration
+const RETRY_COUNT = 3;
+const RETRY_DELAY_MS = 1000;
+
+/**
+ * Normalize a version string for comparison.
+ * Handles variations like "1.22" vs "1.22.0" by ensuring consistent format.
+ */
+function normalizeVersion(version) {
+  if (!version) return null;
+  
+  // Remove any pre-release or build metadata for base comparison
+  const baseVersion = version.split(/[-+]/)[0];
+  
+  // Split into parts and pad to 3 parts (major.minor.patch)
+  const parts = baseVersion.split(".").map((p) => parseInt(p, 10) || 0);
+  while (parts.length < 3) {
+    parts.push(0);
+  }
+  
+  return parts.slice(0, 3).join(".");
+}
+
+/**
+ * Compare two versions for equality (handles semantic equivalence)
+ */
+function versionsEqual(v1, v2) {
+  return normalizeVersion(v1) === normalizeVersion(v2);
+}
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ── Centralized config ──────────────────────────────────────────────────────
+let SHARED_DEFAULTS;
+try {
+  SHARED_DEFAULTS = JSON.parse(
+    readFileSync(join(projectRoot, "config", "defaults.json"), "utf-8"),
+  );
+  if (!SHARED_DEFAULTS.versions?.agentServer) {
+    throw new Error("missing required field: versions.agentServer");
+  }
+} catch (err) {
+  console.error(`${colors.red}Failed to load config/defaults.json: ${err.message}${colors.reset}`);
+  console.error("Ensure the file exists and contains valid JSON with required fields.");
+  process.exit(1);
+}
+
+/**
+ * Read the expected automation SDK dependency version from environment
+ * or config/defaults.json.
+ */
+function getExpectedVersion() {
+  // Allow override via environment variable (useful for CI triggers).
+  const envVersion = process.env.EXPECTED_SDK_VERSION;
+  if (envVersion && envVersion.trim()) {
+    return { version: envVersion.trim(), source: "EXPECTED_SDK_VERSION env var" };
+  }
+
+  return {
+    version: SHARED_DEFAULTS.versions.agentServer,
+    source: "config/defaults.json (versions.agentServer)",
+  };
+}
+
+/**
+ * Compare the local typescript-client pin against the expected SDK version.
+ * Returns a mismatch descriptor, or null when they agree.
+ */
+function findClientPinMismatch(pinnedVersion, expectedVersion) {
+  if (!pinnedVersion) {
+    return { package: CLIENT_PACKAGE_NAME, expected: expectedVersion, actual: null };
+  }
+  // A range would reintroduce the skew this check exists to catch.
+  if (!/^[0-9]/.test(pinnedVersion)) {
+    return { package: CLIENT_PACKAGE_NAME, expected: expectedVersion, actual: pinnedVersion };
+  }
+  if (versionsEqual(pinnedVersion, expectedVersion)) {
+    return null;
+  }
+  return { package: CLIENT_PACKAGE_NAME, expected: expectedVersion, actual: pinnedVersion };
+}
+
+/**
+ * Read the typescript-client pin from package.json.
+ */
+function readClientPin() {
+  const pkg = JSON.parse(
+    readFileSync(join(projectRoot, "package.json"), "utf-8"),
+  );
+  return pkg.dependencies?.[CLIENT_PACKAGE_NAME] ?? null;
+}
+
+/**
+ * Fetch the latest version of a package from PyPI
+ */
+async function fetchPyPIVersion(packageName) {
+  const url = `https://pypi.org/pypi/${packageName}/json`;
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      return null;
+    }
+    const data = await response.json();
+    return data.info?.version || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the automation version from env var or config/defaults.json
+ */
+function getAutomationVersion() {
+  // Allow override via environment variable
+  const envVersion = process.env.AUTOMATION_PACKAGE_VERSION;
+  if (envVersion && envVersion.trim()) {
+    return { version: envVersion.trim(), source: "AUTOMATION_PACKAGE_VERSION env var" };
+  }
+
+  return {
+    version: SHARED_DEFAULTS.versions.automation,
+    source: "config/defaults.json (versions.automation)",
+  };
+}
+
+/**
+ * Fetch package metadata from PyPI and extract dependencies (with retry)
+ */
+async function fetchPyPIDependencies(packageName, version) {
+  const url = `https://pypi.org/pypi/${packageName}/${version}/json`;
+
+  console.log(`${colors.dim}Fetching ${url}${colors.reset}`);
+
+  let lastError;
+  for (let attempt = 0; attempt < RETRY_COUNT; attempt++) {
+    try {
+      const response = await fetch(url);
+      
+      // 404 is a config issue, don't retry
+      if (response.status === 404) {
+        throw new Error(
+          `Package ${packageName}==${version} not found on PyPI (404). Check the package name and version.`,
+        );
+      }
+      
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch ${packageName}==${version} from PyPI: ${response.status} ${response.statusText}`,
+        );
+      }
+      
+      const data = await response.json();
+      return data.info?.requires_dist || [];
+    } catch (err) {
+      lastError = err;
+      
+      // Don't retry on 404 (config issue)
+      if (err.message.includes("not found on PyPI (404)")) {
+        throw err;
+      }
+      
+      // Retry on other errors (network issues, 5xx, etc.)
+      if (attempt < RETRY_COUNT - 1) {
+        const delay = RETRY_DELAY_MS * (attempt + 1);
+        console.log(
+          `${colors.yellow}Retry ${attempt + 1}/${RETRY_COUNT - 1} after ${delay}ms...${colors.reset}`,
+        );
+        await sleep(delay);
+      }
+    }
+  }
+  
+  throw lastError;
+}
+
+/**
+ * Parse PyPI requires_dist array and extract SDK package versions
+ *
+ * PyPI returns dependencies in PEP 508 format like:
+ *   "openhands-sdk>=1.46.0,<2.0.0"
+ *   "openhands-tools==1.46.0"
+ *   "openhands-workspace (>=1.46.0)"
+ */
+function parseSdkVersionsFromRequiresDist(requiresDist) {
+  const versions = {};
+
+  for (const pkg of SDK_PACKAGES) {
+    for (const dep of requiresDist) {
+      // Check if the dependency starts with our package name
+      // The package name may be followed by whitespace, operators, or parentheses
+      if (!dep.toLowerCase().startsWith(pkg.toLowerCase())) {
+        continue;
+      }
+
+      // Extract the version number - look for patterns like:
+      // ">=1.46.0", "==1.46.0", "(>=1.46.0)", "~=1.46.0"
+      // After the package name and before any comma or closing paren
+      const versionPattern = /[><=~!]+\s*([0-9]+(?:\.[0-9]+)*)/;
+      const match = dep.match(versionPattern);
+      if (match) {
+        versions[pkg] = match[1];
+        break;
+      }
+    }
+  }
+
+  return versions;
+}
+
+/**
+ * Main entry point
+ */
+async function main() {
+  console.log("");
+  console.log(
+    `${colors.cyan}SDK Version Sync Check${colors.reset}`,
+  );
+  console.log("─".repeat(50));
+  console.log("");
+
+  try {
+    // Get expected version from env var or config/defaults.json
+    const { version: expectedVersion, source: versionSource } = getExpectedVersion();
+    console.log(
+      `Expected automation SDK version: ${colors.green}${expectedVersion}${colors.reset} (from ${versionSource})`,
+    );
+
+    // Offline, so it runs first and fails fast without the PyPI round trip.
+    const clientMismatch = findClientPinMismatch(readClientPin(), expectedVersion);
+    if (clientMismatch) {
+      console.log("");
+      console.log(
+        `  ${CLIENT_PACKAGE_NAME.padEnd(30)} ${colors.red}✗ ${clientMismatch.actual ?? "(absent)"} (expected ${expectedVersion})${colors.reset}`,
+      );
+      console.log("");
+      console.log(`${colors.red}Version mismatch detected!${colors.reset}`);
+      console.log("");
+      console.log(
+        `${CLIENT_PACKAGE_NAME} mirrors the SDK's ACP provider registry that Canvas renders the`,
+      );
+      console.log(
+        `ACP picker from, but the adapter is launched by agent-server ${expectedVersion}. A skew ships a`,
+      );
+      console.log("picker offering models and launch commands that agent-server does not implement.");
+      console.log("");
+      console.log("To fix, update one of the following:");
+      console.log(`  1. Pin ${CLIENT_PACKAGE_NAME} to ${expectedVersion} in package.json`);
+      console.log("  2. Update versions.agentServer in config/defaults.json");
+      console.log("");
+      process.exit(1);
+    }
+    console.log(
+      `Client registry pin: ${colors.green}${CLIENT_PACKAGE_NAME}@${expectedVersion}${colors.reset} (matches versions.agentServer)`,
+    );
+
+    // Get automation version from env var or config/defaults.json
+    const { version: automationVersion, source: automationSource } = getAutomationVersion();
+    console.log(
+      `Automation package: ${colors.cyan}${AUTOMATION_PACKAGE_NAME}==${automationVersion}${colors.reset} (from ${automationSource})`,
+    );
+
+    // Optionally check PyPI for the latest SDK version
+    if (checkPyPI) {
+      console.log("");
+      console.log("Checking latest SDK versions on PyPI:");
+      for (const pkg of SDK_PACKAGES) {
+        const pypiVersion = await fetchPyPIVersion(pkg);
+        if (pypiVersion) {
+          const status = versionsEqual(pypiVersion, expectedVersion)
+            ? colors.green
+            : colors.yellow;
+          console.log(`  ${pkg.padEnd(25)} ${status}${pypiVersion}${colors.reset}`);
+        } else {
+          console.log(`  ${pkg.padEnd(25)} ${colors.dim}(not found on PyPI)${colors.reset}`);
+        }
+      }
+    }
+
+    console.log("");
+
+    // Fetch automation package dependencies from PyPI
+    const requiresDist = await fetchPyPIDependencies(AUTOMATION_PACKAGE_NAME, automationVersion);
+    const automationVersions = parseSdkVersionsFromRequiresDist(requiresDist);
+
+    // Check each SDK package
+    let hasErrors = false;
+    let foundAny = false;
+    const mismatches = [];
+
+    console.log(`Checking ${AUTOMATION_PACKAGE_NAME}==${automationVersion} SDK dependencies:`);
+    console.log("");
+
+    for (const pkg of SDK_PACKAGES) {
+      const actualVersion = automationVersions[pkg];
+
+      if (actualVersion) {
+        foundAny = true;
+        if (versionsEqual(actualVersion, expectedVersion)) {
+          console.log(
+            `  ${pkg.padEnd(25)} ${colors.green}✓ ${actualVersion}${colors.reset}`,
+          );
+        } else {
+          hasErrors = true;
+          console.log(
+            `  ${pkg.padEnd(25)} ${colors.red}✗ ${actualVersion} (expected ${expectedVersion})${colors.reset}`,
+          );
+          mismatches.push({
+            package: pkg,
+            expected: expectedVersion,
+            actual: actualVersion,
+          });
+        }
+      } else {
+        // Package not found - might be a transitive dependency, not an error
+        console.log(
+          `  ${pkg.padEnd(25)} ${colors.dim}- not a direct dependency${colors.reset}`,
+        );
+      }
+    }
+
+    console.log("");
+
+    if (!foundAny) {
+      console.log(
+        `${colors.yellow}Warning: No SDK packages found in ${AUTOMATION_PACKAGE_NAME}==${automationVersion} dependencies${colors.reset}`,
+      );
+      console.log("This might indicate a parsing issue or the package is not yet published.");
+      console.log("");
+      process.exit(1);
+    }
+
+    if (hasErrors) {
+      console.log(
+        `${colors.red}Version mismatch detected!${colors.reset}`,
+      );
+      console.log("");
+      console.log(`The released ${AUTOMATION_PACKAGE_NAME}==${automationVersion} uses different SDK versions than expected for that automation release.`);
+      console.log("");
+      console.log("Mismatched packages:");
+      for (const m of mismatches) {
+        console.log(`  - ${m.package}: ${m.actual} (expected ${m.expected})`);
+      }
+      console.log("");
+      console.log("To fix, update one of the following:");
+      console.log(
+        `  1. Release a new version of ${AUTOMATION_PACKAGE_NAME} with SDK dependencies pinned to ${expectedVersion}`,
+      );
+      console.log(
+        `  2. Update versions.automation in config/defaults.json to a newer release`,
+      );
+      console.log("");
+      process.exit(1);
+    }
+
+    console.log(
+      `${colors.green}All SDK versions are in sync!${colors.reset}`,
+    );
+    console.log("");
+  } catch (error) {
+    console.error(`${colors.red}Error: ${error.message}${colors.reset}`);
+    process.exit(1);
+  }
+}
+
+// Export for testing
+export {
+  normalizeVersion,
+  versionsEqual,
+  parseSdkVersionsFromRequiresDist,
+  findClientPinMismatch,
+  readClientPin,
+  SDK_PACKAGES,
+  CLIENT_PACKAGE_NAME,
+  AUTOMATION_PACKAGE_NAME,
+};
+
+main();

scripts/check-translation-completeness.cjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * Pre-commit hook script to check for translation completeness
+ * This script ensures that all translation keys have entries for all supported languages
+ * and that values are actually translated rather than English copied to every language.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Keys whose value is intentionally identical in every language (brand names,
+// protocol/technical terms, placeholder-only format strings). Add a key here
+// only when the English value is genuinely correct for all languages.
+const IDENTICAL_VALUE_ALLOWLIST = new Set([
+  'ACTION_MESSAGE$ACP_TOOL',
+  'API$TAVILY_KEY_EXAMPLE',
+  'API$TVLY_KEY_EXAMPLE',
+  'AUTOMATIONS$DOWNLOAD_TARBALL',
+  'AUTOMATIONS$GIT_SYNC$BRANCH_PLACEHOLDER',
+  'AUTOMATIONS$GIT_SYNC$PATH_PLACEHOLDER',
+  'AUTOMATIONS$GIT_SYNC$REPO_URL_PLACEHOLDER',
+  'BACKEND$CLOUD_TITLE',
+  'BACKEND$VERSION_LABEL',
+  'BRANDING$OPENHANDS',
+  'COMMAND_MENU$SHORTCUT',
+  'CONVERSATION$ACP_AGENT_GENERIC',
+  'CONVERSATION$BUDGET_USAGE_FORMAT',
+  'CONVERSATION$OVERVIEW_DIFF_ADDITIONS',
+  'CONVERSATION$OVERVIEW_DIFF_DELETIONS',
+  'CONVERSATION$OVERVIEW_GIT',
+  'CONVERSATION$OVERVIEW_UNAVAILABLE',
+  'CONVERSATION_PANEL$PREVIEW_GIT',
+  'FILES$VSCODE',
+  'GITHUB$AUTH_SCOPE',
+  'LAUNCH$PLUGIN_PATH',
+  'LAUNCH$PLUGIN_REF',
+  'SCHEMA$LLM$SECTION_LABEL',
+  'SCHEMA$LLM$TOP_K$LABEL',
+  'SCHEMA$LLM$TOP_P$LABEL',
+  'SCHEMA$SECURITY_ANALYZER$CHOICE$LLM',
+  'SCHEMA$VERIFICATION$SECURITY_ANALYZER$CHOICE$LLM',
+  'SETTINGS$AGENT_SERVER_URL_PLACEHOLDER',
+  'SETTINGS$AGENT_TYPE_OPENHANDS',
+  'SETTINGS$APP_UPDATE_CARD_TITLE',
+  'SETTINGS$AZURE_DEVOPS',
+  'SETTINGS$CLOUD_SETTINGS_LINK',
+  'SETTINGS$VERSION_DOCKER',
+  'SETTINGS$VERSION_NPM_RECOMMENDED',
+  'SETTINGS$VERSION_PRODUCT_NAME',
+  'SETTINGS$GITHUB',
+  'SETTINGS$GITLAB',
+  'SETTINGS$MCP_AUTH_MODE_OAUTH',
+  'SETTINGS$MCP_DEFAULT_CONFIG',
+  'SETTINGS$MCP_HEADERS_PLACEHOLDER',
+  'SETTINGS$MCP_OAUTH_CLIENT_ID_PLACEHOLDER',
+  'SETTINGS$MCP_OAUTH_CLIENT_SECRET_PLACEHOLDER',
+  'SETTINGS$MCP_OAUTH_SCOPES_PLACEHOLDER',
+  'SETTINGS$MCP_SERVER_TYPE_SHTTP',
+  'SETTINGS$MCP_SERVER_TYPE_SSE',
+  'SETTINGS$MCP_SERVER_TYPE_STDIO',
+  'SETTINGS$NAV_LLM',
+  'SETTINGS$OPENHANDS_API_KEY_HELP_LINK',
+  'SETTINGS$SKILLS_PILLS_MORE',
+  'SETTINGS$SKILLS_VERSION',
+  'SETTINGS$SLACK',
+  'SETTINGS$TITLE_GENERATION_PROFILE_OPTION',
+  'SETUP$REPOSITORY_PLACEHOLDER',
+  'VSCODE$TITLE',
+  'WORKSPACE$JUPYTER_TAB_LABEL',
+]);
+
+// Extract the language codes from the AvailableLanguages array in the i18n index file
+function getSupportedLanguageCodes() {
+  const i18nIndexPath = path.join(__dirname, '../src/i18n/index.ts');
+  const i18nIndexContent = fs.readFileSync(i18nIndexPath, 'utf8');
+
+  const languageCodesRegex = /\{ label: "[^"]+", value: "([^"]+)" \}/g;
+  const supportedLanguageCodes = [];
+  let match;
+
+  while ((match = languageCodesRegex.exec(i18nIndexContent)) !== null) {
+    supportedLanguageCodes.push(match[1]);
+  }
+
+  return supportedLanguageCodes;
+}
+
+// Check each translation key for missing languages, extra languages, and
+// untranslated (English-copied) values
+function checkTranslations(translationJson, supportedLanguageCodes) {
+  const missingTranslations = {};
+  const extraLanguages = {};
+  const untranslatedKeys = {};
+
+  const nonEnglishLanguageCodes = supportedLanguageCodes.filter(
+    (langCode) => langCode !== 'en'
+  );
+
+  Object.entries(translationJson).forEach(([key, translations]) => {
+    // Get the languages available for this key
+    const availableLanguages = Object.keys(translations);
+
+    // Find missing languages for this key
+    const missing = supportedLanguageCodes.filter(
+      (langCode) => !availableLanguages.includes(langCode)
+    );
+
+    if (missing.length > 0) {
+      missingTranslations[key] = missing;
+    }
+
+    // Find extra languages for this key
+    const extra = availableLanguages.filter(
+      (langCode) => !supportedLanguageCodes.includes(langCode)
+    );
+
+    if (extra.length > 0) {
+      extraLanguages[key] = extra;
+    }
+
+    // Flag keys where every non-English value is the English value copied
+    // verbatim — a strong signal the key was never translated. Keys whose value
+    // is legitimately identical everywhere belong in IDENTICAL_VALUE_ALLOWLIST.
+    if (
+      !IDENTICAL_VALUE_ALLOWLIST.has(key) &&
+      translations.en !== undefined &&
+      nonEnglishLanguageCodes.every(
+        (langCode) => translations[langCode] === translations.en
+      )
+    ) {
+      untranslatedKeys[key] = translations.en;
+    }
+  });
+
+  return { missingTranslations, extraLanguages, untranslatedKeys };
+}
+
+module.exports = {
+  IDENTICAL_VALUE_ALLOWLIST,
+  getSupportedLanguageCodes,
+  checkTranslations,
+};
+
+if (require.main === module) {
+  // Load the translation file
+  const translationJsonPath = path.join(__dirname, '../src/i18n/translation.json');
+  const translationJson = require(translationJsonPath);
+
+  const { missingTranslations, extraLanguages, untranslatedKeys } =
+    checkTranslations(translationJson, getSupportedLanguageCodes());
+
+  const hasErrors =
+    Object.keys(missingTranslations).length > 0 ||
+    Object.keys(extraLanguages).length > 0 ||
+    Object.keys(untranslatedKeys).length > 0;
+
+  // Generate detailed error message if there are missing translations
+  if (Object.keys(missingTranslations).length > 0) {
+    console.error('\x1b[31m%s\x1b[0m', 'ERROR: Missing translations detected');
+    console.error(`Found ${Object.keys(missingTranslations).length} translation keys with missing languages:`);
+
+    Object.entries(missingTranslations).forEach(([key, langs]) => {
+      console.error(`- Key "${key}" is missing translations for: ${langs.join(', ')}`);
+    });
+
+    console.error('\nPlease add the missing translations before committing.');
+  }
+
+  // Generate detailed error message if there are extra languages
+  if (Object.keys(extraLanguages).length > 0) {
+    console.error('\x1b[31m%s\x1b[0m', 'ERROR: Extra languages detected');
+    console.error(`Found ${Object.keys(extraLanguages).length} translation keys with extra languages not in AvailableLanguages:`);
+
+    Object.entries(extraLanguages).forEach(([key, langs]) => {
+      console.error(`- Key "${key}" has translations for unsupported languages: ${langs.join(', ')}`);
+    });
+
+    console.error('\nPlease remove the extra languages before committing.');
+  }
+
+  // Generate detailed error message if there are untranslated keys
+  if (Object.keys(untranslatedKeys).length > 0) {
+    console.error('\x1b[31m%s\x1b[0m', 'ERROR: Untranslated keys detected');
+    console.error(`Found ${Object.keys(untranslatedKeys).length} translation keys where the English value is copied to every language:`);
+
+    Object.entries(untranslatedKeys).forEach(([key, value]) => {
+      console.error(`- Key "${key}" has the same value ("${value}") for all languages`);
+    });
+
+    console.error('\nPlease translate the values before committing. If a value is intentionally identical in every language (brand name, technical term, format string), add the key to IDENTICAL_VALUE_ALLOWLIST in scripts/check-translation-completeness.cjs.');
+  }
+
+  // Exit with error code if there are issues
+  if (hasErrors) {
+    process.exit(1);
+  } else {
+    console.log('\x1b[32m%s\x1b[0m', 'All translation keys have complete language coverage!');
+  }
+}

scripts/dev-extra-backend.mjs

@@ -0,0 +1,262 @@
+import { spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { setTimeout as delay } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+
+import {
+  buildAgentServerCommand,
+  buildAgentServerEnv,
+  buildSafeDevConfig,
+  formatMissingUvxGuidance,
+  validateLocalAgentServerPath,
+} from "./dev-safe.mjs";
+import {
+  getProcessTreeSpawnOptions,
+  isProcessRunning,
+  signalProcessTree,
+} from "./dev-process-utils.mjs";
+
+const DEFAULT_EXTRA_BACKEND_PORT = 18002;
+const DEFAULT_EXTRA_VSCODE_PORT = 18003;
+const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
+
+function parsePort(value, fallback) {
+  if (value == null || value === "") {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Build a config for an *extra* standalone agent-server that shares the
+ * bundled instance's persistence (state dir, conversations, secret key)
+ * but listens on a different backend + vscode port.
+ *
+ * @param {string} cwd
+ * @param {Record<string, string | undefined>} env
+ */
+export function buildExtraBackendConfig(
+  cwd = process.cwd(),
+  env = process.env,
+) {
+  const base = buildSafeDevConfig(cwd, env);
+
+  const backendPort = parsePort(
+    env.OH_CANVAS_EXTRA_BACKEND_PORT,
+    DEFAULT_EXTRA_BACKEND_PORT,
+  );
+  const vscodePort = parsePort(
+    env.OH_CANVAS_EXTRA_VSCODE_PORT,
+    DEFAULT_EXTRA_VSCODE_PORT,
+  );
+
+  return {
+    ...base,
+    backendPort,
+    vscodePort,
+    backendBaseUrl: `http://127.0.0.1:${backendPort}`,
+    backendHost: `127.0.0.1:${backendPort}`,
+  };
+}
+
+function isEnoentError(error) {
+  return Boolean(
+    (error &&
+      typeof error === "object" &&
+      "code" in error &&
+      error.code === "ENOENT") ||
+    /ENOENT/.test(String(error)),
+  );
+}
+
+async function waitForServer(url, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS) {
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return;
+      }
+    } catch {
+      // Keep polling until timeout.
+    }
+
+    await delay(500);
+  }
+
+  throw new Error(`Timed out waiting for agent-server at ${url}`);
+}
+
+function spawnProcess(command, args, options = {}) {
+  const child = spawn(
+    command,
+    args,
+    getProcessTreeSpawnOptions({
+      stdio: "inherit",
+      ...options,
+    }),
+  );
+
+  child.once("error", (error) => {
+    if (isEnoentError(error) && command === "uvx") {
+      console.error(formatMissingUvxGuidance(options?.cwd));
+    } else if (isEnoentError(error)) {
+      console.error(
+        `Failed to start ${command}. Make sure it is installed and on your PATH.`,
+      );
+    } else {
+      console.error(`Failed to start ${command}:`, error);
+    }
+  });
+
+  return child;
+}
+
+async function main() {
+  const config = buildExtraBackendConfig();
+
+  if (process.env.OH_AGENT_SERVER_LOCAL_PATH) {
+    validateLocalAgentServerPath(process.env.OH_AGENT_SERVER_LOCAL_PATH);
+  }
+
+  for (const dir of [
+    config.stateDir,
+    config.tmuxTmpDir,
+    config.conversationsPath,
+    config.workspacesPath,
+    config.bashEventsDir,
+  ]) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const agentServerCmd = buildAgentServerCommand();
+
+  const secretKeySource = process.env.OH_SECRET_KEY
+    ? "custom (from OH_SECRET_KEY)"
+    : "default (for local development)";
+
+  console.log("Starting EXTRA standalone agent-server (shared state)...");
+  console.log(`- agent-server: ${agentServerCmd.source}`);
+  console.log(`- backend: ${config.backendBaseUrl}`);
+  console.log(`- vscode port: ${config.vscodePort}`);
+  console.log(`- shared state dir: ${config.stateDir}`);
+  console.log(`- shared conversations: ${config.conversationsPath}`);
+  console.log(`- secret key: ${secretKeySource}`);
+  console.log("");
+  console.log(
+    "Connect via the GUI: open Add Backend, enter " +
+      `${config.backendBaseUrl} as the host. Leave the API key blank ` +
+      "unless this server is started with OH_SESSION_API_KEYS_0 set.",
+  );
+  console.log("");
+
+  const backend = spawnProcess(
+    agentServerCmd.command,
+    [
+      ...agentServerCmd.args,
+      "--host",
+      "127.0.0.1",
+      "--port",
+      String(config.backendPort),
+    ],
+    {
+      cwd: config.cwd,
+      env: {
+        // Deliberately not opting into the editor path prefix. This server is
+        // reached by registering it as an extra backend from a browser whose
+        // origin belongs to some *other* stack, so a prefix on that origin
+        // either does not resolve or — worse — resolves to the bundled
+        // stack's editor, silently handing back a different container's
+        // workspace. No single global prefix can disambiguate the two, so this
+        // launcher stays out of prefix-mode; the editor button is unavailable
+        // for conversations on an extra backend.
+        ...process.env,
+        ...buildAgentServerEnv(config),
+      },
+    },
+  );
+
+  let shuttingDown = false;
+
+  const shutdown = (signal = "SIGTERM") => {
+    if (shuttingDown) {
+      return;
+    }
+
+    shuttingDown = true;
+    signalProcessTree(backend, signal);
+
+    setTimeout(() => {
+      if (isProcessRunning(backend)) {
+        signalProcessTree(backend, "SIGKILL");
+      }
+      process.exit(process.exitCode ?? 0);
+    }, 3000);
+  };
+
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  // The agent-server is spawned detached, so a SIGHUP that kills this launcher
+  // (terminal or multiplexer death) would otherwise leave it running and holding
+  // its port. Forward SIGTERM rather than SIGHUP: uvicorn only handles
+  // SIGINT/SIGTERM, so a forwarded SIGHUP would terminate the agent-server by
+  // default action instead of shutting it down gracefully.
+  process.on("SIGHUP", () => shutdown("SIGTERM"));
+
+  const backendErrored = new Promise((_, reject) => {
+    backend.once("error", (error) => reject(error));
+  });
+  const backendExited = new Promise((_, reject) => {
+    backend.once("exit", (code, signal) => {
+      if (!shuttingDown) {
+        reject(
+          new Error(
+            `agent-server exited before startup completed (code=${code ?? "null"}, signal=${signal ?? "null"})`,
+          ),
+        );
+      }
+    });
+  });
+
+  try {
+    await Promise.race([
+      waitForServer(`${config.backendBaseUrl}/server_info`),
+      backendErrored,
+      backendExited,
+    ]);
+  } catch (error) {
+    shutdown();
+    throw error;
+  }
+
+  console.log(`Extra agent-server is ready at ${config.backendBaseUrl}.`);
+
+  backend.once("exit", (code) => {
+    if (!shuttingDown) {
+      console.error(`agent-server exited unexpectedly with code ${code ?? 0}`);
+      shutdown();
+      process.exitCode = code ?? 1;
+    } else {
+      process.exitCode = code ?? 0;
+    }
+  });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  });
+}

scripts/dev-process-utils.mjs

@@ -0,0 +1,150 @@
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+/**
+ * Return true while Node still considers the child process active.
+ *
+ * Do not use ChildProcess#killed for cleanup decisions. In Node, `killed`
+ * only means a signal was sent successfully; it does not mean the process has
+ * exited. That distinction matters for dev launchers because uvx/npm
+ * wrappers can receive SIGTERM while their long-running child process keeps
+ * serving on the original port.
+ */
+export function isProcessRunning(proc) {
+  return proc.exitCode === null && proc.signalCode === null;
+}
+
+/**
+ * Add spawn options needed for safe service launches and process-tree cleanup.
+ *
+ * Arguments must bypass shell parsing so values such as version constraints
+ * containing `<` are forwarded literally. Callers that need shell behavior
+ * must invoke the shell explicitly as the command.
+ *
+ * On POSIX, `detached: true` makes the spawned service the leader of a new
+ * process group. Later we can signal `-pid` to terminate that whole group,
+ * including wrapper chains like:
+ *
+ *   launcher -> uvx -> python agent-server
+ *   launcher -> npm -> sh -> Vite
+ *
+ * Windows does not support POSIX process groups, so callers fall back to
+ * signaling the direct child process there.
+ */
+export function getProcessTreeSpawnOptions(options = {}) {
+  return {
+    ...options,
+    shell: false,
+    detached: process.platform !== "win32",
+  };
+}
+
+/**
+ * Resolve a service command to a directly spawnable target on Windows.
+ *
+ * Services spawn without a shell so argument values reach the child verbatim.
+ * Spawning `uvx` via cmd.exe instead makes it parse the args: a constraint like
+ * `agent-client-protocol<0.11` is read as `<` input redirection and the spawn
+ * dies with "The system cannot find the file specified." Resolving to an
+ * absolute path lets callers spawn it shell-free.
+ *
+ * Returns `command` unchanged off Windows, when already a path, or if the lookup
+ * fails.
+ */
+export function resolveWindowsCommand(
+  command,
+  platform = process.platform,
+  lookup = whereCommandLookup,
+) {
+  if (platform !== "win32") {
+    return command;
+  }
+  if (command.includes("/") || command.includes("\\")) {
+    return command;
+  }
+  return lookup(command) || command;
+}
+
+function whereCommandLookup(command) {
+  const result = spawnSync("where.exe", [command], { encoding: "utf8" });
+  if (result.status !== 0 || !result.stdout) {
+    return null;
+  }
+  return result.stdout.split(/\r?\n/).find(Boolean)?.trim() || null;
+}
+
+/**
+ * Signal the whole spawned service tree when possible.
+ *
+ * POSIX `process.kill(-pid, signal)` targets the process group whose id is
+ * `pid`; this only works because services are spawned with
+ * `getProcessTreeSpawnOptions()`. Without the negative pid, shutdown would
+ * often stop only the wrapper process and leave the actual server child
+ * listening on its port.
+ */
+export function signalProcessTree(proc, signal) {
+  if (!isProcessRunning(proc)) {
+    return false;
+  }
+
+  try {
+    if (process.platform === "win32" && proc.pid) {
+      killWindowsProcessTree(proc, signal);
+    } else if (!proc.pid) {
+      proc.kill(signal);
+    } else {
+      process.kill(-proc.pid, signal);
+    }
+    return true;
+  } catch (err) {
+    if (err?.code === "ESRCH") {
+      return false;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Windows has no POSIX process groups: ChildProcess#kill reaches only the
+ * direct child (e.g. the uvx wrapper), leaving grandchildren — the actual
+ * python agent-server holding its port — running. `taskkill /t` walks the
+ * child tree instead. Windows also has no graceful tree signal (taskkill
+ * without /f posts WM_CLOSE, which console processes ignore), so SIGTERM and
+ * SIGKILL both map to the same forceful /f kill; callers' delayed SIGKILL
+ * pass skips already-exited trees via isProcessRunning, so the repeat is a
+ * no-op. A non-zero taskkill exit just means the tree already exited — only
+ * a failure to spawn taskkill itself falls back to the direct kill.
+ */
+function killWindowsProcessTree(proc, signal) {
+  const result = spawnSync(
+    "taskkill",
+    ["/pid", String(proc.pid), "/t", "/f"],
+    // windowsHide avoids a console window flash when invoked from the
+    // packaged (GUI) Electron process.
+    { stdio: "ignore", windowsHide: true },
+  );
+  if (result.error) {
+    proc.kill(signal);
+  }
+}
+
+export function createShutdownHookRegistry(onError) {
+  const hooks = new Set();
+
+  return {
+    add(hook) {
+      hooks.add(hook);
+      return () => hooks.delete(hook);
+    },
+
+    run() {
+      for (const hook of hooks) {
+        try {
+          hook();
+        } catch (err) {
+          onError?.(err);
+        }
+      }
+    },
+  };
+}

scripts/dev-safe.mjs

@@ -0,0 +1,1217 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import net from "node:net";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { setTimeout as delay } from "node:timers/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import {
+  getProcessTreeSpawnOptions,
+  isProcessRunning,
+  signalProcessTree,
+} from "./dev-process-utils.mjs";
+// buildRuntimeServicesInfo moved to its own dependency-free module so the
+// Docker entrypoint can run it as a CLI. Re-exported below for back-compat
+// (dev-with-automation.mjs and tests still import it from here).
+import { buildRuntimeServicesInfo } from "./runtime-services-info.mjs";
+import { fileLog, stripAnsi } from "./logger.mjs";
+
+// ── Centralized config (single source of truth for versions, ports, etc.) ───
+const __dev_safe_dirname = path.dirname(fileURLToPath(import.meta.url));
+const SHARED_DEFAULTS = JSON.parse(
+  readFileSync(
+    path.join(__dev_safe_dirname, "..", "config", "defaults.json"),
+    "utf-8",
+  ),
+);
+
+const DEFAULT_BACKEND_PORT = SHARED_DEFAULTS.ports.agentServer;
+// Path prefix the bundled editor is served under. The same value has to reach
+// agent-server (as OH_VSCODE_BASE_PATH, so openvscode-server is launched with
+// --server-base-path and advertises the prefix) and the ingress route table,
+// or the advertised URL and the route that serves it disagree.
+export const VSCODE_BASE_PATH = SHARED_DEFAULTS.paths.vscodeBasePath;
+const DEFAULT_VITE_PORT = 3001;
+const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
+const DEFAULT_AGENT_SERVER_PACKAGE = SHARED_DEFAULTS.packages.agentServer;
+const AGENT_SERVER_GIT_REPO = "https://github.com/OpenHands/software-agent-sdk";
+const LOCAL_AGENT_SERVER_SUBDIRS = [
+  "openhands-agent-server",
+  "openhands-sdk",
+  "openhands-tools",
+  "openhands-workspace",
+];
+const DEFAULT_AGENT_SERVER_VERSION = SHARED_DEFAULTS.versions.agentServer;
+// Temporary transitive-dep pin: openhands-sdk 1.40.1 leaves agent-client-protocol
+// unbounded (>=0.10.1), but acp 0.11.0 reordered the ACP prompt() args and breaks
+// the SDK's ACP client. Hold acp <0.11 until a fixed SDK ships. See config/defaults.json.
+const AGENT_CLIENT_PROTOCOL_CONSTRAINT =
+  SHARED_DEFAULTS.constraints?.agentClientProtocol;
+const DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_API_KEY =
+  SHARED_DEFAULTS.telemetry.posthogApiKey;
+const DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_HOST =
+  SHARED_DEFAULTS.telemetry.posthogHost;
+const AGENT_SERVER_POSTHOG_CONSTRAINT = "posthog>=6,<7";
+const FRONTEND_REQUIRED_BINS = ["cross-env", "react-router"];
+
+/**
+ * Generate a cryptographically secure random API key.
+ * Returns a 64-character hex string (256-bit).
+ */
+export function generateRandomApiKey() {
+  return randomBytes(32).toString("hex");
+}
+
+// Where the auto-generated API key is persisted so it stays stable across
+// `npm run dev` restarts. Keeping the key stable means the value baked into
+// the frontend (VITE_SESSION_API_KEY) and the persisted backend-registry entry
+// (`openhands-backends` localStorage) stay in sync without users needing to
+// set anything in `.env`.
+//
+// To rotate the key, delete this file. To pin a key explicitly, export
+// LOCAL_BACKEND_API_KEY — it takes precedence over the persisted file.
+export const DEFAULT_API_KEY_PATH = path.join(
+  homedir(),
+  ".openhands",
+  "agent-canvas",
+  "api-key.txt",
+);
+
+/** @deprecated Use DEFAULT_API_KEY_PATH */
+export const DEFAULT_SESSION_API_KEY_PATH = DEFAULT_API_KEY_PATH;
+
+// Where the OH_SECRET_KEY is persisted so dev mode and Docker mode share the
+// same encryption key when both use ~/.openhands as their state directory.
+// docker/entrypoint.sh reads and writes this same file, so whichever mode runs
+// first generates the key and the other picks it up automatically.
+//
+// To rotate the key, delete this file and restart both modes. To pin a key
+// explicitly, export OH_SECRET_KEY — that takes precedence over the file.
+export const DEFAULT_SECRET_KEY_PATH = path.join(
+  homedir(),
+  ".openhands",
+  "agent-canvas",
+  "secret-key.txt",
+);
+
+// Cache so repeated lookups within a single process return the same key,
+// keyed by file path so tests can use temp paths in isolation.
+const persistedApiKeyCache = new Map();
+
+/**
+ * Load the persisted default API key, generating + persisting one if the file
+ * doesn't exist yet.
+ *
+ * Best-effort: if the file can't be written (e.g. read-only home dir), we
+ * fall back to an in-memory key for this process so dev still works -- the
+ * key just won't survive a restart.
+ *
+ * @param {string} filePath - Where to read/write the key.
+ * @returns {string} The (hex) API key.
+ */
+export function getOrCreatePersistedApiKeyFile(
+  filePath = DEFAULT_API_KEY_PATH,
+) {
+  return getOrCreatePersistedApiKey(filePath, "session");
+}
+
+/** @deprecated Use getOrCreatePersistedApiKeyFile */
+export function getOrCreatePersistedSessionApiKey(
+  filePath = DEFAULT_API_KEY_PATH,
+) {
+  return getOrCreatePersistedApiKeyFile(filePath);
+}
+
+/**
+ * Load a persisted default API key, generating + persisting one if the file
+ * doesn't exist yet.
+ *
+ * Best-effort: if the file can't be written (e.g. read-only home dir), we
+ * fall back to an in-memory key for this process so dev still works -- the
+ * key just won't survive a restart.
+ *
+ * @param {string} filePath - Where to read/write the key.
+ * @param {string} label - Human-readable key label for warning messages.
+ * @returns {string} The (hex) API key.
+ */
+export function getOrCreatePersistedApiKey(filePath, label = "API") {
+  const cached = persistedApiKeyCache.get(filePath);
+  if (cached) return cached;
+
+  // Try to read an existing key.
+  try {
+    const existing = readFileSync(filePath, "utf8").trim();
+    if (existing) {
+      persistedApiKeyCache.set(filePath, existing);
+      return existing;
+    }
+    // File exists but is empty -- treat as if missing and regenerate.
+  } catch (error) {
+    if (!isEnoentError(error)) {
+      console.warn(
+        `Could not read persisted ${label} API key from ${filePath}: ${error.message}. Regenerating.`,
+      );
+    }
+  }
+
+  // Generate and persist a new key.
+  const newKey = generateRandomApiKey();
+  try {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${newKey}\n`, { mode: 0o600 });
+  } catch (error) {
+    console.warn(
+      `Could not persist ${label} API key to ${filePath}: ${error.message}. Falling back to in-memory key (will not survive restarts).`,
+    );
+  }
+  persistedApiKeyCache.set(filePath, newKey);
+  return newKey;
+}
+
+/**
+ * Clear the in-memory cache used by {@link getOrCreatePersistedSessionApiKey}.
+ * Intended for tests that swap the persisted file path between cases.
+ */
+export function resetPersistedSessionApiKeyCache() {
+  persistedApiKeyCache.clear();
+}
+
+function isEnoentError(error) {
+  return Boolean(
+    (error &&
+      typeof error === "object" &&
+      "code" in error &&
+      error.code === "ENOENT") ||
+    /ENOENT/.test(String(error)),
+  );
+}
+
+/**
+ * Find a free port, preferring the specified port if available.
+ *
+ * Tries the preferred port first; if it's busy, falls back to letting
+ * the OS assign any available port. This preserves predictable defaults
+ * while gracefully handling port conflicts.
+ *
+ * **Note on race conditions:** There is a small window between when this
+ * function checks port availability and when the calling service actually
+ * binds to the port. During this window, another process could theoretically
+ * grab the port. This is an accepted limitation of the "check-then-use"
+ * approach. Callers (like agent-server) should handle EADDRINUSE gracefully.
+ * For Vite, `strictPort: true` ensures a fast failure if this occurs.
+ *
+ * @param {number} preferredPort - The port to try first
+ * @param {string} host - The host to bind to (default: "127.0.0.1")
+ * @returns {Promise<number>} The actual port that was acquired
+ */
+export async function findFreePort(preferredPort, host = "127.0.0.1") {
+  // If preferredPort is 0, skip the check and go straight to OS assignment
+  if (preferredPort > 0) {
+    const preferredAvailable = await tryPort(preferredPort, host);
+    if (preferredAvailable) {
+      return preferredPort;
+    }
+  }
+
+  // Fall back to OS-assigned port
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once("error", reject);
+    server.listen(0, host, () => {
+      const { port } = server.address();
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+/**
+ * Check if a port is available by attempting to bind to it.
+ *
+ * @param {number} port - The port to check
+ * @param {string} host - The host to bind to
+ * @returns {Promise<boolean>} True if the port is available
+ */
+function tryPort(port, host = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.listen(port, host, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+/**
+ * Assert that all listed ports are available, throwing a descriptive error if
+ * any are already in use.
+ *
+ * Intended as a pre-flight check before spawning services so that a concurrent
+ * agent-canvas instance is detected immediately rather than silently starting
+ * on a different port.
+ *
+ * @param {Array<{name: string, port: number}>} portConfigs - Named port list
+ * @param {string} [host]
+ */
+export async function assertPortsFree(portConfigs, host = "127.0.0.1") {
+  const results = await Promise.all(
+    portConfigs.map(async ({ name, port }) => ({
+      name,
+      port,
+      free: await tryPort(port, host),
+    })),
+  );
+  const busy = results.filter(({ free }) => !free);
+  if (busy.length === 0) return;
+
+  const lines = busy
+    .map(({ name, port }) => `   • ${name}: port ${port}`)
+    .join("\n");
+  throw new Error(
+    `Cannot start: the following ports are already in use:\n\n${lines}\n\n` +
+      `Another agent-canvas instance may already be running.\n` +
+      `Stop it first, or override the port via environment variables (e.g. PORT=<other>).`,
+  );
+}
+
+/**
+ * Find multiple free ports at once, each preferring its specified default.
+ *
+ * Allocates ports sequentially to avoid race conditions between checks.
+ *
+ * @param {Array<{name: string, preferred: number}>} portConfigs - Port configurations
+ * @param {string} host - The host to bind to (default: "127.0.0.1")
+ * @returns {Promise<Record<string, number>>} Map of name to actual port
+ */
+export async function findFreePorts(portConfigs, host = "127.0.0.1") {
+  const result = {};
+  const usedPorts = new Set();
+
+  for (const { name, preferred } of portConfigs) {
+    // Try preferred if not already taken by a previous allocation
+    // Skip if preferred is 0 (means "any port") or already used
+    if (preferred > 0 && !usedPorts.has(preferred)) {
+      const available = await tryPort(preferred, host);
+      if (available) {
+        result[name] = preferred;
+        usedPorts.add(preferred);
+        continue;
+      }
+    }
+
+    // Fall back to OS-assigned port, retrying if we get a collision
+    let port;
+    let attempts = 0;
+    const maxAttempts = 100;
+    do {
+      port = await findFreePort(0, host);
+      if (++attempts > maxAttempts) {
+        throw new Error(
+          `Could not allocate unique port for "${name}" after ${maxAttempts} attempts`,
+        );
+      }
+    } while (usedPorts.has(port));
+
+    result[name] = port;
+    usedPorts.add(port);
+  }
+
+  return result;
+}
+
+export function formatMissingUvxGuidance(cwd = process.cwd()) {
+  const readmePath = path.join(cwd, "README.md");
+
+  return [
+    "Failed to start uvx. Make sure uv is installed and on your PATH.",
+    "",
+    "To fix this:",
+    "1. Install uv:",
+    "   curl -LsSf https://astral.sh/uv/install.sh | sh",
+    "2. Make sure the uv bin dir is on your PATH:",
+    '   export PATH="$HOME/.local/bin:$PATH"',
+    "   command -v uvx",
+    "",
+    "Need Windows or another install method? https://docs.astral.sh/uv/getting-started/installation/",
+    `See the local Quickstart for details: ${readmePath}`,
+    "",
+    "Other options:",
+    "- npm run dev:frontend   # use an already running backend",
+    "- npm run dev:mock       # run the frontend with mock APIs",
+  ].join("\n");
+}
+
+function npmBinCandidates(binName, platform = process.platform) {
+  const candidates = [binName];
+  if (platform === "win32") {
+    candidates.push(`${binName}.cmd`, `${binName}.ps1`);
+  }
+  return candidates;
+}
+
+export function getMissingFrontendDependencyBins(
+  cwd = process.cwd(),
+  platform = process.platform,
+) {
+  const binDir = path.join(cwd, "node_modules", ".bin");
+  return FRONTEND_REQUIRED_BINS.filter(
+    (binName) =>
+      !npmBinCandidates(binName, platform).some((candidate) =>
+        existsSync(path.join(binDir, candidate)),
+      ),
+  );
+}
+
+export function formatMissingFrontendDependenciesGuidance(
+  missingBins,
+  cwd = process.cwd(),
+) {
+  const missingList = missingBins.join(", ");
+  return [
+    "Frontend dependencies are not installed or are incomplete.",
+    "",
+    `Missing npm binaries: ${missingList}`,
+    "",
+    "Run this from the repository root:",
+    "  npm ci",
+    "",
+    `Repository root: ${cwd}`,
+  ].join("\n");
+}
+
+export function validateFrontendDependencies(
+  cwd = process.cwd(),
+  platform = process.platform,
+) {
+  const missingBins = getMissingFrontendDependencyBins(cwd, platform);
+  if (missingBins.length > 0) {
+    throw new Error(
+      formatMissingFrontendDependenciesGuidance(missingBins, cwd),
+    );
+  }
+}
+
+/**
+ * Modules the agent-server imports at startup (`--import-modules`). They are
+ * resolved from `tools/`, which `buildAgentServerEnv` exposes through
+ * OH_EXTRA_PYTHON_PATH. Importing `canvas_ui_tool` eagerly registers the SDK's
+ * builtin FinishTool so automation presets (openhands-automation >= 1.9.0) can
+ * resolve it on the remote conversations they dispatch — see the note at the
+ * bottom of tools/canvas_ui_tool.py.
+ */
+export const AGENT_SERVER_IMPORT_MODULES = "canvas_ui_tool";
+
+/**
+ * Build the uvx command and arguments for running agent-server.
+ *
+ * Environment variables (highest precedence first):
+ * - OH_AGENT_SERVER_LOCAL_PATH: Absolute path to a software-agent-sdk checkout.
+ *   Runs the local checkout via uvx with editable installs of the workspace
+ *   packages (openhands-sdk, openhands-tools, openhands-workspace) so source
+ *   edits are picked up without a manual reinstall. The agent-server itself
+ *   is rebuilt from local source on each invocation (--reinstall).
+ * - OH_AGENT_SERVER_GIT_REF: Git commit SHA or branch name
+ * - OH_AGENT_SERVER_VERSION: Specific PyPI version (e.g., "1.46.0")
+ *
+ * If none are set, defaults to the released version specified by
+ * DEFAULT_AGENT_SERVER_VERSION. Set OH_AGENT_SERVER_GIT_REF to use a
+ * git branch or commit instead.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {{ command: string, args: string[], source: string }}
+ */
+export function buildAgentServerCommand(env = process.env) {
+  const localPath = env.OH_AGENT_SERVER_LOCAL_PATH;
+  const gitRef = env.OH_AGENT_SERVER_GIT_REF;
+  const version = env.OH_AGENT_SERVER_VERSION;
+
+  const uvxArgs = [];
+  let source = "";
+
+  if (localPath) {
+    if (!path.isAbsolute(localPath)) {
+      throw new Error(
+        `OH_AGENT_SERVER_LOCAL_PATH must be an absolute path, got: ${localPath}`,
+      );
+    }
+    uvxArgs.push(
+      "--reinstall",
+      "--from",
+      path.join(localPath, "openhands-agent-server"),
+      "--with-editable",
+      path.join(localPath, "openhands-sdk"),
+      "--with-editable",
+      path.join(localPath, "openhands-tools"),
+      "--with-editable",
+      path.join(localPath, "openhands-workspace"),
+      "--with",
+      AGENT_SERVER_POSTHOG_CONSTRAINT,
+      "agent-server",
+    );
+    source = `local (${localPath})`;
+  } else if (gitRef) {
+    // Use git ref with subdirectory syntax for uv workspace monorepo.
+    // The software-agent-sdk repo has packages in subdirectories:
+    // openhands-agent-server/, openhands-sdk/, openhands-tools/, openhands-workspace/
+    // All four must come from the same ref so inter-package APIs stay in sync.
+    //
+    // --reinstall is required because the git branch may carry the same version
+    // string as the current PyPI release (e.g. both "1.26.0"). Without it, uv
+    // silently reuses the cached PyPI wheels and the git ref is never actually
+    // used, even though it was explicitly requested.
+    const baseGitUrl = `git+${AGENT_SERVER_GIT_REPO}@${gitRef}`;
+    uvxArgs.push(
+      "--reinstall",
+      "--from",
+      `${baseGitUrl}#subdirectory=openhands-agent-server`,
+      "--with",
+      `${baseGitUrl}#subdirectory=openhands-sdk`,
+      "--with",
+      `${baseGitUrl}#subdirectory=openhands-tools`,
+      "--with",
+      `${baseGitUrl}#subdirectory=openhands-workspace`,
+      "--with",
+      AGENT_SERVER_POSTHOG_CONSTRAINT,
+      "agent-server",
+    );
+    source = `git (${gitRef})`;
+  } else if (version) {
+    // Use specific PyPI version: uvx --from openhands-agent-server==version agent-server
+    // The package name differs from the executable name, so we need --from syntax
+    // Pin all SDK packages to the same version for consistency
+    uvxArgs.push(
+      "--from",
+      `${DEFAULT_AGENT_SERVER_PACKAGE}==${version}`,
+      "--with",
+      `openhands-sdk==${version}`,
+      "--with",
+      `openhands-tools==${version}`,
+      "--with",
+      `openhands-workspace==${version}`,
+    );
+    if (AGENT_CLIENT_PROTOCOL_CONSTRAINT) {
+      uvxArgs.push("--with", AGENT_CLIENT_PROTOCOL_CONSTRAINT);
+    }
+    uvxArgs.push("--with", AGENT_SERVER_POSTHOG_CONSTRAINT);
+    uvxArgs.push("agent-server");
+    source = `PyPI (${version})`;
+  } else {
+    // Default to released PyPI version
+    // Pin all SDK packages to the same version for consistency
+    uvxArgs.push(
+      "--from",
+      `${DEFAULT_AGENT_SERVER_PACKAGE}==${DEFAULT_AGENT_SERVER_VERSION}`,
+      "--with",
+      `openhands-sdk==${DEFAULT_AGENT_SERVER_VERSION}`,
+      "--with",
+      `openhands-tools==${DEFAULT_AGENT_SERVER_VERSION}`,
+      "--with",
+      `openhands-workspace==${DEFAULT_AGENT_SERVER_VERSION}`,
+    );
+    if (AGENT_CLIENT_PROTOCOL_CONSTRAINT) {
+      uvxArgs.push("--with", AGENT_CLIENT_PROTOCOL_CONSTRAINT);
+    }
+    uvxArgs.push("--with", AGENT_SERVER_POSTHOG_CONSTRAINT);
+    uvxArgs.push("agent-server");
+    source = `PyPI (${DEFAULT_AGENT_SERVER_VERSION}, default)`;
+  }
+
+  // Everything after the executable name is an agent-server CLI argument.
+  // Import the registration module before any conversation is created.
+  uvxArgs.push("--import-modules", AGENT_SERVER_IMPORT_MODULES);
+
+  return {
+    command: "uvx",
+    args: uvxArgs,
+    source,
+  };
+}
+
+function parsePort(value, fallback) {
+  if (value == null || value === "") {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+
+  return parsed;
+}
+
+/**
+ * Build safe dev configuration (synchronous version).
+ *
+ * Uses the port values from environment variables or defaults WITHOUT checking
+ * port availability. Use this when:
+ * - You need synchronous config (e.g., for test setup, config inspection)
+ * - Ports are already known to be available (e.g., specified via env vars)
+ * - You're building config objects for downstream use, not starting services
+ *
+ * For scripts that actually start services (dev-safe.mjs main, dev-with-automation.mjs),
+ * use {@link buildSafeDevConfigAsync} instead to handle port conflicts gracefully.
+ *
+ * @param {string} cwd - Current working directory
+ * @param {Record<string, string | undefined>} env - Environment variables
+ * @returns {SafeDevConfig} Configuration object
+ */
+export function buildSafeDevConfig(cwd = process.cwd(), env = process.env) {
+  const backendPort = parsePort(
+    env.OH_CANVAS_SAFE_BACKEND_PORT,
+    DEFAULT_BACKEND_PORT,
+  );
+  const vscodePort = parsePort(env.OH_CANVAS_SAFE_VSCODE_PORT, backendPort + 1);
+
+  return buildConfigFromPorts({ backendPort, vscodePort }, cwd, env);
+}
+
+/**
+ * Build safe dev configuration with dynamic port allocation.
+ *
+ * Tries preferred ports first; if busy, finds available alternatives.
+ * This is the recommended entry point for scripts that start services.
+ *
+ * @param {string} cwd - Current working directory
+ * @param {Record<string, string | undefined>} env - Environment variables
+ * @returns {Promise<SafeDevConfig>} Configuration object with allocated ports
+ */
+export async function buildSafeDevConfigAsync(
+  cwd = process.cwd(),
+  env = process.env,
+) {
+  // Get preferred ports from env or defaults
+  const preferredBackendPort = parsePort(
+    env.OH_CANVAS_SAFE_BACKEND_PORT,
+    DEFAULT_BACKEND_PORT,
+  );
+  const preferredVscodePort = parsePort(
+    env.OH_CANVAS_SAFE_VSCODE_PORT,
+    preferredBackendPort + 1,
+  );
+
+  // Fail fast if any required port is already in use.
+  await assertPortsFree([
+    { name: "agent-server", port: preferredBackendPort },
+    { name: "vscode", port: preferredVscodePort },
+  ]);
+
+  return buildConfigFromPorts(
+    { backendPort: preferredBackendPort, vscodePort: preferredVscodePort },
+    cwd,
+    env,
+  );
+}
+
+/**
+ * @typedef {object} SafeDevConfig
+ * @property {string} cwd
+ * @property {number} backendPort
+ * @property {number} vscodePort
+ * @property {string} vscodeBasePath
+ * @property {string} stateDir
+ * @property {string} tmuxTmpDir
+ * @property {string} conversationsPath
+ * @property {string} workspacesPath
+ * @property {string} bashEventsDir
+ * @property {string} backendBaseUrl
+ * @property {string} backendHost
+ * @property {string} workingDir
+ * @property {string} secretKey
+ * @property {string} sessionApiKey
+ * @property {string} canvasToolsDir
+ */
+
+/**
+ * Internal helper to build config from already-resolved ports.
+ * @param {{backendPort: number, vscodePort: number}} ports
+ * @param {string} cwd
+ * @param {Record<string, string | undefined>} env
+ * @returns {SafeDevConfig}
+ */
+function buildConfigFromPorts(ports, cwd, env) {
+  const { backendPort, vscodePort } = ports;
+  const stateDir = path.resolve(
+    cwd,
+    env.OH_CANVAS_SAFE_STATE_DIR ||
+      path.join(homedir(), ".openhands", "agent-canvas"),
+  );
+  const conversationsPath = path.join(stateDir, "dev_conversations");
+  const workspacesPath = path.join(stateDir, "workspaces");
+  // Use provided secret key, or read/generate one persisted to
+  // ~/.openhands/agent-canvas/secret-key.txt. Persisting ensures dev mode
+  // and Docker mode share the same encryption key when they mount the same
+  // ~/.openhands directory (docker/entrypoint.sh reads/writes the same file).
+  const secretKeyPath = env.OH_SECRET_KEY_PATH || DEFAULT_SECRET_KEY_PATH;
+  const secretKey =
+    env.OH_SECRET_KEY || getOrCreatePersistedApiKey(secretKeyPath, "secret");
+  // Use the user-provided LOCAL_BACKEND_API_KEY or fall back to a key
+  // persisted to ~/.openhands/agent-canvas/api-key.txt. Persisting on disk
+  // keeps the agent-server, the Vite-baked VITE_SESSION_API_KEY, and any
+  // `openhands-backends` localStorage entries the frontend has cached all
+  // pointing at the same value across dev restarts.
+  //
+  // LOCAL_BACKEND_API_KEY is the single user-facing env var for the API key.
+  // OH_SESSION_API_KEY_PATH overrides the persisted file path (used by tests).
+  const persistedKeyPath = env.OH_SESSION_API_KEY_PATH || DEFAULT_API_KEY_PATH;
+  const sessionApiKey =
+    env.LOCAL_BACKEND_API_KEY ||
+    getOrCreatePersistedApiKeyFile(persistedKeyPath);
+
+  // Host directory containing the legacy canvas_ui Python module. Persisted
+  // conversations created before the client_tools migration still reference
+  // its module qualname, so the agent-server can import it when resuming them.
+  const canvasToolsDir = fileURLToPath(new URL("../tools", import.meta.url));
+
+  return {
+    cwd,
+    backendPort,
+    vscodePort,
+    vscodeBasePath: VSCODE_BASE_PATH,
+    stateDir,
+    // tmux socket directory. Defaults to <stateDir>/tmux (under
+    // ~/.openhands/agent-canvas), matching where the rest of dev state lives
+    // and persisting across restarts.
+    //
+    // Do NOT use os.tmpdir() here: on macOS it resolves to the per-user
+    // $TMPDIR (/var/folders/.../T), which the OS periodically reaps
+    // (com.apple.bsd.dirhelper deletes entries untouched for a few days).
+    // Reaping deletes the live tmux socket while the server process keeps
+    // running, orphaning it — every later new-window then fails with
+    // "error connecting to .../openhands (No such file or directory)".
+    //
+    // The only hosts where <stateDir>/tmux can't hold the socket are those
+    // whose $HOME is a network/overlay mount without Unix-domain-socket
+    // support (some devcontainers, NFS/CIFS homes). Those rare cases can point
+    // tmux at a local, socket-capable path with the standard TMUX_TMPDIR env
+    // var (e.g. TMUX_TMPDIR=/tmp), which we honor and pass through below.
+    tmuxTmpDir: env.TMUX_TMPDIR || path.join(stateDir, "tmux"),
+    conversationsPath,
+    workspacesPath,
+    bashEventsDir: path.join(stateDir, "bash_events"),
+    backendBaseUrl: `http://127.0.0.1:${backendPort}`,
+    backendHost: `127.0.0.1:${backendPort}`,
+    workingDir: env.VITE_WORKING_DIR || workspacesPath,
+    secretKey,
+    sessionApiKey,
+    canvasToolsDir,
+  };
+}
+
+/**
+ * Telemetry-related env vars for the agent-server process.
+ *
+ * Split out from `buildAgentServerEnv` so callers that assemble their own
+ * agent-server environment can reuse the same mapping.
+ *
+ * @param {Record<string, string | undefined>} [env] - Source environment.
+ * @returns {Record<string, string>} Telemetry env vars for agent-server
+ */
+export function buildAgentServerTelemetryEnv(env = process.env) {
+  const telemetryDisabled =
+    env.VITE_DO_NOT_TRACK === "1" || env.DO_NOT_TRACK === "1";
+  const result = {};
+
+  for (const key of [
+    "OH_TELEMETRY_EXPORTER",
+    "OH_TELEMETRY_POSTHOG_API_KEY",
+    "OH_TELEMETRY_POSTHOG_HOST",
+    "OH_TELEMETRY_HTTP_ENDPOINT",
+    "OH_TELEMETRY_HTTP_TOKEN",
+    "OH_TELEMETRY_CONSENT",
+    "OH_TELEMETRY_CONSENT_MODE",
+    "OH_TELEMETRY_SALT",
+  ]) {
+    if (env[key]) result[key] = env[key];
+  }
+
+  if (telemetryDisabled) {
+    result.DO_NOT_TRACK = "1";
+  }
+
+  const apiKey =
+    env.OH_TELEMETRY_POSTHOG_API_KEY ||
+    env.VITE_POSTHOG_API_KEY ||
+    (telemetryDisabled ? "" : DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_API_KEY);
+  const exporter = env.OH_TELEMETRY_EXPORTER || (apiKey ? "posthog" : "");
+
+  if (exporter) {
+    result.OH_TELEMETRY_EXPORTER = exporter;
+  }
+
+  if (exporter === "posthog" && apiKey) {
+    result.OH_TELEMETRY_POSTHOG_API_KEY = apiKey;
+    result.OH_TELEMETRY_POSTHOG_HOST =
+      env.OH_TELEMETRY_POSTHOG_HOST ||
+      env.VITE_POSTHOG_HOST ||
+      DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_HOST;
+  }
+
+  return result;
+}
+
+/**
+ * Build the environment variables object for spawning the agent-server process.
+ *
+ * This is exported so downstream consumers (e.g., automation service) can use
+ * the same env vars without duplicating the mapping logic.
+ *
+ * `vscodeBasePath` is an explicit opt-in rather than a field read off `config`,
+ * and that is deliberate. Setting it changes the URL `/api/vscode/url`
+ * advertises: agent-server appends the prefix to the browser origin the
+ * frontend sends, so the editor is only reachable if the same origin also
+ * routes that prefix to the editor port. A launcher that sets it without
+ * registering the route advertises `<origin>/vscode/…`, which serves the
+ * canvas SPA shell instead of the editor.
+ *
+ * Requiring the caller to name it makes the pairing greppable: every call site
+ * that passes `vscodeBasePath` must also register a matching route, and
+ * `__tests__/scripts/vscode-base-path-opt-in.test.ts` asserts that no launcher
+ * opts in without one.
+ *
+ * @param {ReturnType<typeof buildSafeDevConfig>} config - Config from buildSafeDevConfig
+ * @param {{vscodeBasePath?: string | null, env?: Record<string, string | undefined>}} [options]
+ * @param {string | null} [options.vscodeBasePath] - Opt into prefix-mode by
+ *   passing the path prefix the caller also routes to `config.vscodePort`.
+ * @param {Record<string, string | undefined>} [options.env] - Source
+ *   environment for the telemetry mapping (defaults to `process.env`).
+ * @returns {Record<string, string>} Environment variables for agent-server
+ */
+export function buildAgentServerEnv(config, options = {}) {
+  const { vscodeBasePath = null, env = process.env } = options;
+  return {
+    ...buildAgentServerTelemetryEnv(env),
+    // Force Python to use UTF-8 for all file I/O and streams.
+    //
+    // On Windows, Python defaults to the system ANSI codepage (e.g. cp1252).
+    // The agent-server writes conversation metadata JSON that can contain
+    // emoji (e.g. ✅ U+2705) which cp1252 cannot encode, producing:
+    //   UnicodeEncodeError: 'charmap' codec can't encode character '\u2705'
+    // Setting PYTHONUTF8=1 enables Python's UTF-8 mode (PEP 540) for the
+    // entire agent-server process, matching the behaviour on Linux/macOS
+    // where the locale is already UTF-8.
+    // This is a no-op on Linux/macOS where the locale is already UTF-8.
+    PYTHONUTF8: "1",
+    TMUX_TMPDIR: config.tmuxTmpDir,
+    // Parent of stateDir (= ~/.openhands) so settings/secrets match Docker.
+    OH_PERSISTENCE_DIR: path.dirname(config.stateDir),
+    OH_CONVERSATIONS_PATH: config.conversationsPath,
+    OH_BASH_EVENTS_DIR: config.bashEventsDir,
+    OH_VSCODE_PORT: String(config.vscodePort),
+    // Serve the editor under a path prefix on the canvas origin rather than on
+    // its own published port. agent-server passes this to openvscode-server as
+    // --server-base-path and includes it in the URL from /api/vscode/url, which
+    // matches the ingress route the caller registers for the same prefix.
+    //
+    // Omitted unless the caller opts in — see the note on this function.
+    ...(vscodeBasePath ? { OH_VSCODE_BASE_PATH: vscodeBasePath } : {}),
+    OH_SECRET_KEY: config.secretKey,
+    // Use OH_SESSION_API_KEYS_0 for agent-server V1 config format
+    OH_SESSION_API_KEYS_0: config.sessionApiKey,
+    // Alias for the agent-server's own URL. The agent-server itself sets
+    // OH_INTERNAL_SERVER_URL at startup, but downstream consumers (the
+    // OpenHands SDK boilerplate emitted by automation prompt/plugin
+    // presets) read AGENT_SERVER_URL — the canonical SDK name. Mirror it
+    // here so automation runs work without each tarball having to know
+    // about the OH_-prefixed variant.
+    //
+    // We deliberately do NOT set a SESSION_API_KEY alias: the SDK's
+    // sanitized_env() would strip it from bash subprocesses anyway, and
+    // a follow-up change to the automation preset reads
+    // OH_SESSION_API_KEYS_0 directly (which is already in env).
+    AGENT_SERVER_URL: config.backendBaseUrl,
+    // Let the agent-server resolve canvas_ui_tool when old persisted metadata
+    // requests that compatibility module during startup.
+    OH_EXTRA_PYTHON_PATH: config.canvasToolsDir,
+  };
+}
+
+// Re-export so existing importers (dev-with-automation.mjs, tests) keep
+// resolving `buildRuntimeServicesInfo` from this module. The implementation
+// now lives in ./runtime-services-info.mjs (imported at the top of this file).
+export { buildRuntimeServicesInfo };
+
+export function buildNpmScriptCommand(
+  scriptName,
+  platform = process.platform,
+  env = process.env,
+  nodeExecPath = process.execPath,
+) {
+  // On Windows, always use cmd.exe regardless of whether npm_execpath is set.
+  // npm_execpath points to a path like
+  // "C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js" which contains
+  // spaces. When that path is passed as an argument with shell:true in
+  // spawnService, cmd.exe splits on the space and tries to run "C:\Program"
+  // as a command, producing "not recognized as an internal or external command".
+  // Using "npm" via cmd.exe avoids the problem entirely.
+  if (platform === "win32") {
+    return {
+      command: env.ComSpec || "cmd.exe",
+      args: ["/d", "/s", "/c", "npm", "run", scriptName],
+    };
+  }
+
+  if (env.npm_execpath) {
+    return {
+      command: env.npm_node_execpath || nodeExecPath,
+      args: [env.npm_execpath, "run", scriptName],
+    };
+  }
+
+  return {
+    command: "npm",
+    args: ["run", scriptName],
+  };
+}
+
+export function validateLocalAgentServerPath(localPath) {
+  if (!path.isAbsolute(localPath)) {
+    throw new Error(
+      `OH_AGENT_SERVER_LOCAL_PATH must be an absolute path, got: ${localPath}`,
+    );
+  }
+  if (!existsSync(localPath)) {
+    throw new Error(`OH_AGENT_SERVER_LOCAL_PATH does not exist: ${localPath}`);
+  }
+  for (const subdir of LOCAL_AGENT_SERVER_SUBDIRS) {
+    const subdirPath = path.join(localPath, subdir);
+    if (!existsSync(subdirPath)) {
+      throw new Error(
+        `OH_AGENT_SERVER_LOCAL_PATH is missing expected workspace package '${subdir}': ${subdirPath}`,
+      );
+    }
+  }
+}
+
+async function waitForServer(url, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS) {
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < timeoutMs) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return;
+      }
+    } catch {
+      // Keep polling until timeout.
+    }
+
+    await delay(500);
+  }
+
+  throw new Error(`Timed out waiting for agent-server at ${url}`);
+}
+
+function spawnProcess(command, args, options = {}) {
+  const child = spawn(
+    command,
+    args,
+    getProcessTreeSpawnOptions({
+      stdio: "inherit",
+      ...options,
+    }),
+  );
+
+  child.once("error", (error) => {
+    if (isEnoentError(error) && command === "uvx") {
+      const msg = formatMissingUvxGuidance(options?.cwd);
+      console.error(msg);
+      fileLog("error", stripAnsi(msg));
+    } else if (isEnoentError(error)) {
+      const msg = `Failed to start ${command}. Make sure it is installed and on your PATH.`;
+      console.error(msg);
+      fileLog("error", msg);
+    } else {
+      console.error(`Failed to start ${command}:`, error);
+      fileLog("error", `Failed to start ${command}: ${error.message}`);
+    }
+  });
+
+  return child;
+}
+
+async function main() {
+  console.log("Starting isolated agent-server + frontend dev stack...");
+  fileLog("info", "Starting isolated agent-server + frontend dev stack...");
+  validateFrontendDependencies();
+  console.log("Frontend dependencies found.");
+  fileLog("info", "Frontend dependencies found.");
+  console.log("Allocating ports...");
+  fileLog("info", "Allocating ports...");
+
+  // Use async config builder with dynamic port allocation
+  const config = await buildSafeDevConfigAsync();
+
+  if (process.env.OH_AGENT_SERVER_LOCAL_PATH) {
+    validateLocalAgentServerPath(process.env.OH_AGENT_SERVER_LOCAL_PATH);
+  }
+
+  for (const dir of [
+    config.stateDir,
+    config.tmuxTmpDir,
+    config.conversationsPath,
+    config.workspacesPath,
+    config.bashEventsDir,
+  ]) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const agentServerCmd = buildAgentServerCommand();
+
+  const secretKeySource = process.env.OH_SECRET_KEY
+    ? "custom (from OH_SECRET_KEY)"
+    : `persisted (${process.env.OH_SECRET_KEY_PATH || DEFAULT_SECRET_KEY_PATH})`;
+
+  const sessionKeySource = process.env.LOCAL_BACKEND_API_KEY
+    ? "custom (from LOCAL_BACKEND_API_KEY)"
+    : `persisted (${
+        process.env.OH_SESSION_API_KEY_PATH || DEFAULT_API_KEY_PATH
+      })`;
+
+  console.log(`- agent-server: ${agentServerCmd.source}`);
+  console.log(`- backend: ${config.backendBaseUrl}`);
+  console.log(`- vscode port: ${config.vscodePort}`);
+  console.log(`- working dir: ${config.workingDir}`);
+  console.log(`- isolated state dir: ${config.stateDir}`);
+  console.log(`- secret key: ${secretKeySource}`);
+  console.log(`- session API key: ${sessionKeySource}`);
+  console.log("");
+  fileLog(
+    "info",
+    [
+      "Agent-server stack config:",
+      `  agent-server: ${agentServerCmd.source}`,
+      `  backend:      ${config.backendBaseUrl}`,
+      `  working dir:  ${config.workingDir}`,
+      `  state dir:    ${config.stateDir}`,
+    ].join("\n"),
+  );
+
+  const backend = spawnProcess(
+    agentServerCmd.command,
+    [
+      ...agentServerCmd.args,
+      "--host",
+      "127.0.0.1",
+      "--port",
+      String(config.backendPort),
+    ],
+    {
+      cwd: config.cwd,
+      env: {
+        ...process.env,
+        // Opt into prefix-mode: the Vite dev server proxies the same prefix to
+        // `config.vscodePort` (see VITE_VSCODE_TARGET below), so the advertised
+        // URL resolves on the frontend origin the browser is actually on.
+        ...buildAgentServerEnv(config, {
+          vscodeBasePath: config.vscodeBasePath,
+        }),
+      },
+    },
+  );
+
+  let shuttingDown = false;
+  let frontend = null;
+
+  const shutdown = (signal = "SIGTERM") => {
+    if (shuttingDown) {
+      return;
+    }
+
+    shuttingDown = true;
+    if (frontend) {
+      signalProcessTree(frontend, signal);
+    }
+    signalProcessTree(backend, signal);
+
+    setTimeout(() => {
+      if (frontend && isProcessRunning(frontend)) {
+        signalProcessTree(frontend, "SIGKILL");
+      }
+      if (isProcessRunning(backend)) {
+        signalProcessTree(backend, "SIGKILL");
+      }
+      process.exit(process.exitCode ?? 0);
+    }, 3000);
+  };
+
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  // Services are spawned detached, so a SIGHUP that kills this launcher (terminal
+  // or multiplexer death) would otherwise leave the whole tree running. Forward
+  // SIGTERM rather than SIGHUP: uvicorn only handles SIGINT/SIGTERM, so a
+  // forwarded SIGHUP would terminate the agent-server by default action instead
+  // of shutting it down gracefully.
+  process.on("SIGHUP", () => shutdown("SIGTERM"));
+
+  const backendErrored = new Promise((_, reject) => {
+    backend.once("error", (error) => reject(error));
+  });
+  const backendExited = new Promise((_, reject) => {
+    backend.once("exit", (code, signal) => {
+      if (!shuttingDown) {
+        reject(
+          new Error(
+            `agent-server exited before startup completed (code=${code ?? "null"}, signal=${signal ?? "null"})`,
+          ),
+        );
+      }
+    });
+  });
+
+  try {
+    await Promise.race([
+      waitForServer(`${config.backendBaseUrl}/server_info`),
+      backendErrored,
+      backendExited,
+    ]);
+  } catch (error) {
+    shutdown();
+    throw error;
+  }
+
+  const frontendCommand = buildNpmScriptCommand("dev:frontend");
+  frontend = spawnProcess(frontendCommand.command, frontendCommand.args, {
+    cwd: config.cwd,
+    env: {
+      ...process.env,
+      VITE_BACKEND_HOST: config.backendHost,
+      VITE_BACKEND_BASE_URL: config.backendBaseUrl,
+      VITE_WORKING_DIR: config.workingDir,
+      // Pass session API key so frontend can authenticate with agent-server
+      VITE_SESSION_API_KEY: config.sessionApiKey,
+      // This mode has no static server or ingress in front of Vite, so Vite's
+      // own proxy is the only thing that can serve the editor prefix on the
+      // frontend origin. The editor is a separate process on a port of its
+      // own, so it needs its own proxy target rather than VITE_BACKEND_HOST.
+      VITE_VSCODE_BASE_PATH: config.vscodeBasePath,
+      VITE_VSCODE_TARGET: `http://127.0.0.1:${config.vscodePort}`,
+      // dev:minimal deliberately does NOT supply runtime-services info (the
+      // frontend here talks straight to the agent-server over
+      // VITE_BACKEND_BASE_URL — there is no ingress or static-server in front
+      // of it to append `runtime_services` to `/server_info`, and the
+      // frontend's own VITE_RUNTIME_SERVICES_INFO env var is no longer read).
+      // It is a bare agent-server + Vite stack with no companion services to
+      // advertise, so `fetchBackendRuntimeServicesInfo()` correctly returns
+      // null and conversations simply omit the <RUNTIME_SERVICES> block.
+      // Stacks with automation/ingress/frontend services should use
+      // `npm run dev` / `dev:static`, which pass runtime-services info through
+      // ingress/static-server instead.
+    },
+  });
+
+  frontend.once("exit", (code) => {
+    shutdown();
+    process.exitCode = code ?? 0;
+  });
+
+  backend.once("exit", (code) => {
+    if (!shuttingDown) {
+      const msg = `agent-server exited unexpectedly with code ${code ?? 0}`;
+      console.error(msg);
+      fileLog("error", msg);
+      shutdown();
+      process.exitCode = code ?? 1;
+    }
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Conversation lease cleanup
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns true if `host:port` accepts a TCP connection within `timeoutMs`.
+ * Used to detect a live agent-server we shouldn't disturb.
+ */
+export function isPortBusy(port, host = "127.0.0.1", timeoutMs = 500) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const finish = (busy) => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      resolve(busy);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+    socket.connect(port, host);
+  });
+}
+
+/**
+ * Remove stale `owner_lease.json` files under `conversationsDir` so a
+ * freshly spawned agent-server can claim ownership and re-load every
+ * existing conversation.
+ *
+ * Why this is needed: each conversation directory carries an
+ * `owner_lease.json` that locks it to a single agent-server's
+ * `owner_instance_id` for a 45 s TTL refreshed by heartbeat. On
+ * graceful shutdown the agent-server unlinks its leases; on a hard
+ * kill (or a fast restart, well under 45 s) the leases linger. A new
+ * agent-server with a fresh `owner_instance_id` will then raise
+ * `ConversationLeaseHeldError` for each conversation at startup load
+ * and skip it entirely — `/api/conversations/search` returns `[]`
+ * even though the meta files are right there on disk.
+ *
+ * The caller MUST verify (e.g. with `isPortBusy`) that no agent-server
+ * is currently bound to the backend port before calling this — there
+ * is no other reliable way to tell a stale lease from an actively
+ * renewed one.
+ *
+ * Returns the number of lease files unlinked.
+ */
+export function releaseStaleConversationLeases(conversationsDir) {
+  if (!existsSync(conversationsDir)) return 0;
+
+  let removed = 0;
+  for (const name of readdirSync(conversationsDir)) {
+    const convDir = path.join(conversationsDir, name);
+    let isDir = false;
+    try {
+      isDir = statSync(convDir).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+
+    const leasePath = path.join(convDir, "owner_lease.json");
+    if (!existsSync(leasePath)) continue;
+    try {
+      unlinkSync(leasePath);
+      removed += 1;
+    } catch {
+      // Best-effort: the new agent-server will simply skip this
+      // conversation as before. Don't fail the whole start.
+    }
+  }
+  return removed;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((error) => {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error(msg);
+    fileLog("error", `Fatal error: ${msg}`);
+    if (error instanceof Error && error.stack) {
+      fileLog("error", error.stack);
+    }
+    process.exit(1);
+  });
+}

scripts/dev-static.mjs

@@ -0,0 +1,665 @@
+/**
+ * Static-frontend Development Stack
+ *
+ * Same as the default automation stack but serves a production build of the
+ * frontend via `scripts/static-server.mjs` instead of the Vite dev server.
+ * Designed for slow / flaky network situations (e.g. plane wifi)
+ * where Vite's ~1000 individual module requests per page load are the
+ * bottleneck. The static build collapses the frontend into ~50 hashed
+ * chunks that all 304 cleanly on reload.
+ *
+ * Architecture (identical to dev-with-automation, only the frontend differs):
+ *   ┌──────────────────────────────────────────────────────────────────────────┐
+ *   │              http://localhost:8000 (Ingress Proxy)                       │
+ *   │              /api/automation/* → Automation Backend                      │
+ *   │              /api/*, /sockets  → Agent Server                            │
+ *   │              /*                → Static Frontend                         │
+ *   └──────────────────────────────────────────────────────────────────────────┘
+ *          │                    │                         │
+ *          ▼                    ▼                         ▼
+ *   ┌─────────────┐    ┌───────────────┐         ┌──────────────────┐
+ *   │ sirv-cli    │    │ Agent Server  │         │ Automation       │
+ *   │ build/      │    │ (uvx) :18000  │         │ Backend (uvx)    │
+ *   │ :3001       │    │               │         │ :18001           │
+ *   └─────────────┘    └───────────────┘         └──────────────────┘
+ *
+ * Usage:
+ *   npm run dev:static
+ *   npm run dev:static -- --port 12000
+ *   npm run dev:static -- --skip-build  # reuse an existing build/
+ *   npm run dev:static -- --automation-ref feat/my-branch
+ *
+ * Environment variables (all optional, same as dev):
+ *   - PORT: Ingress port (default: 8000)
+ *   - OH_AUTOMATION_GIT_REF: Git ref for automation (default: main)
+ *   - OH_AGENT_SERVER_GIT_REF: Git ref for agent-server
+ *   - OH_SECRET_KEY: Session secret key
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import process from "node:process";
+
+import { buildFrontend } from "./static-build.mjs";
+import {
+  buildAgentServerCommand,
+  buildSafeDevConfig,
+  buildAgentServerEnv,
+  formatMissingUvxGuidance,
+  isPortBusy,
+  releaseStaleConversationLeases,
+} from "./dev-safe.mjs";
+import {
+  getProcessTreeSpawnOptions,
+  isProcessRunning,
+  resolveWindowsCommand,
+  signalProcessTree,
+} from "./dev-process-utils.mjs";
+import {
+  buildAgentServerAutomationEnv,
+  buildAutomationCommand,
+  buildAutomationTelemetryEnv,
+  buildAutomationRuntimeServicesInfo,
+  buildConfig,
+  buildRouteArgs,
+  getAgentServerBaseUrl,
+  getLocalServiceRoutes,
+  getNoReferrerPrefixArgs,
+  getVSCodeAdvertiseArgs,
+} from "./dev-with-automation.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..");
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Terminal Styling
+// ═══════════════════════════════════════════════════════════════════════════
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+};
+
+function logService(name, message, color = c.reset) {
+  const ts = new Date().toISOString().split("T")[1].split(".")[0];
+  console.log(`${c.dim}${ts}${c.reset} ${color}[${name}]${c.reset} ${message}`);
+}
+
+function logStep(step, message) {
+  console.log(`${c.cyan}[${step}]${c.reset} ${message}`);
+}
+
+function logSuccess(message) {
+  console.log(`${c.green}✓${c.reset} ${message}`);
+}
+
+function logError(message) {
+  console.error(`${c.red}✗${c.reset} ${message}`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CLI parsing
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function parseArgs(argv = process.argv.slice(2)) {
+  const config = {
+    port: null,
+    automationGitRef: null,
+    automationRepo: null,
+    skipBuild: false,
+    verbose: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    switch (argv[i]) {
+      case "-p":
+      case "--port":
+        config.port = parseInt(argv[++i], 10);
+        break;
+      case "--automation-ref":
+        config.automationGitRef = argv[++i];
+        break;
+      case "--automation-repo":
+        config.automationRepo = argv[++i];
+        break;
+      case "--skip-build":
+        config.skipBuild = true;
+        break;
+      case "-v":
+      case "--verbose":
+        config.verbose = true;
+        break;
+      case "-h":
+      case "--help":
+        showHelp();
+        process.exit(0);
+    }
+  }
+
+  return config;
+}
+
+function showHelp() {
+  console.log(`
+Agent Canvas Static-frontend Development Stack
+
+Runs the automation stack, but serves a production build of the
+frontend via scripts/static-server.mjs. Use this when a remote or flaky network
+makes Vite's per-module requests painful (e.g. ngrok or plane wifi).
+
+USAGE:
+  npm run dev:static [-- options]
+
+OPTIONS:
+  -p, --port <port>           Ingress port (default: 8000)
+  --automation-ref <ref>      Git ref for automation backend (default: main)
+  --automation-repo <url>     Git repo URL for automation
+  --skip-build                Reuse existing build/ directory (faster restart)
+  -v, --verbose               Show detailed output
+  -h, --help                  Show this help
+
+ENVIRONMENT VARIABLES:
+  PORT                        Alternative to --port
+  OH_AUTOMATION_GIT_REF       Alternative to --automation-ref
+  OH_AGENT_SERVER_GIT_REF     Git ref for agent-server SDK
+  OH_SECRET_KEY               Secret key for sessions
+
+ACCESS POINTS:
+  Main UI:      http://localhost:PORT/
+  API Docs:     http://localhost:PORT/api/automation/docs
+
+NOTES:
+  • The build is produced once at startup. Edit the source and rerun this
+    command (or rebuild with \`npm run build:app\`) to pick up changes.
+  • The static server sends ETag headers, so reloads return 304s instead of
+    refetching content — much friendlier on slow links.
+`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Prerequisites & Setup
+// ═══════════════════════════════════════════════════════════════════════════
+
+function commandExists(cmd) {
+  const result =
+    process.platform === "win32"
+      ? spawnSync("where.exe", [cmd], { stdio: "pipe" })
+      : spawnSync("sh", ["-c", `command -v ${cmd}`], { stdio: "pipe" });
+
+  return result.status === 0;
+}
+
+function checkPrerequisites() {
+  logStep("1/3", "Checking prerequisites...");
+
+  if (!commandExists("uvx")) {
+    console.error(formatMissingUvxGuidance(projectRoot));
+    process.exit(1);
+  }
+  logSuccess("uvx found");
+
+  if (!commandExists("npm")) {
+    logError("npm is required but not found");
+    process.exit(1);
+  }
+  logSuccess("npm found");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Process Management
+// ═══════════════════════════════════════════════════════════════════════════
+
+const processes = new Map();
+let shuttingDown = false;
+
+function spawnService(name, command, args, options = {}) {
+  const proc = spawn(
+    resolveWindowsCommand(command),
+    args,
+    getProcessTreeSpawnOptions({
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...options.env },
+      cwd: options.cwd,
+    }),
+  );
+
+  const color = options.color || c.reset;
+
+  proc.stdout.on("data", (data) => {
+    data
+      .toString()
+      .split("\n")
+      .filter(Boolean)
+      .forEach((line) => logService(name, line.trim(), color));
+  });
+
+  proc.stderr.on("data", (data) => {
+    data
+      .toString()
+      .split("\n")
+      .filter(Boolean)
+      .forEach((line) => logService(name, line.trim(), c.yellow));
+  });
+
+  proc.on("error", (error) => {
+    logError(`${name} failed to start: ${error.message}`);
+  });
+
+  proc.on("exit", (code) => {
+    if (code !== 0 && code !== null && !shuttingDown) {
+      logService(name, `Exited with code ${code}`, c.red);
+    }
+    processes.delete(name);
+  });
+
+  processes.set(name, proc);
+  return proc;
+}
+
+async function waitForService(name, url, timeoutMs = 30000) {
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url);
+      if (res.ok) {
+        logService(name, `Ready at ${url}`, c.green);
+        return true;
+      }
+    } catch {
+      // Keep trying
+    }
+    await delay(500);
+  }
+
+  logService(name, `Timeout waiting for ${url}`, c.red);
+  return false;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Service Starters (agent-server + automation are byte-for-byte the same as
+// dev-with-automation; the only difference is the frontend service.)
+// ═══════════════════════════════════════════════════════════════════════════
+
+// The static server and the ingress proxy front the same local backends, so
+// they share one route table — dev-with-automation's, rather than a second
+// copy here. The copy this replaces claimed to stay identical to that table
+// but nothing enforced it, and it had already drifted: the editor prefix was
+// missing, so `/vscode` fell through to the SPA fallback and answered editor
+// requests with the canvas shell.
+//
+// This mode always launches both local backends (it never runs frontend-only),
+// so it asks for their routes unconditionally. Every target is IPv4 loopback:
+// the backends bind to `0.0.0.0`, which only accepts IPv4, but localhost can
+// resolve to ::1 first (notably on Windows).
+function buildLocalServiceRouteArgs(config) {
+  return buildRouteArgs(
+    getLocalServiceRoutes({
+      ...config,
+      launchAgentServer: true,
+      launchAutomation: true,
+    }),
+  );
+}
+
+function startAgentServer(config) {
+  logService(
+    "agent-server",
+    `Starting on port ${config.agentServerPort}...`,
+    c.blue,
+  );
+
+  const agentServerCmd = buildAgentServerCommand(process.env);
+  logService("agent-server", `Using ${agentServerCmd.source}`, c.dim);
+
+  const safeConfig = buildSafeDevConfig(config.canvasPath, {
+    ...process.env,
+    OH_CANVAS_SAFE_STATE_DIR: config.stateDir,
+    OH_CANVAS_SAFE_BACKEND_PORT: config.agentServerPort.toString(),
+    OH_CANVAS_SAFE_VSCODE_PORT: config.vscodePort.toString(),
+  });
+
+  const agentServerEnv = {
+    // Opt into prefix-mode: both the static server and the ingress below build
+    // their route tables from `getLocalServiceRoutes`, which registers this
+    // same prefix against `config.vscodePort`.
+    ...buildAgentServerEnv(safeConfig, {
+      vscodeBasePath: config.vscodeBasePath,
+    }),
+    ...buildAgentServerAutomationEnv(config),
+  };
+
+  spawnService(
+    "agent-server",
+    agentServerCmd.command,
+    [
+      ...agentServerCmd.args,
+      "--host",
+      "0.0.0.0",
+      "--port",
+      String(config.agentServerPort),
+    ],
+    {
+      cwd: safeConfig.workspacesPath,
+      env: agentServerEnv,
+      color: c.blue,
+    },
+  );
+}
+
+function buildAutomationBackendEnv(config, env = process.env) {
+  // Both backends share the same session API key value.
+  return {
+    AUTOMATION_AGENT_SERVER_URL: getAgentServerBaseUrl(config),
+    AUTOMATION_AGENT_SERVER_API_KEY: config.sessionApiKey,
+    AUTOMATION_DB_URL: `sqlite+aiosqlite:///${join(config.stateDir, "automations.db")}`,
+    AUTOMATION_BASE_URL: `http://localhost:${config.ingressPort}`,
+    AUTOMATION_WORKSPACE_BASE: join(config.stateDir, "workspaces"),
+    AUTOMATION_LOCAL_API_KEY: config.sessionApiKey,
+    ...buildAutomationTelemetryEnv(env),
+    AUTOMATION_CORS_ORIGINS: `http://localhost:${config.ingressPort},http://127.0.0.1:${config.ingressPort},http://localhost:3001,http://127.0.0.1:3001`,
+    FILE_STORE: "local",
+    LOCAL_STORAGE_PATH: join(config.stateDir, "storage"),
+    OPENHANDS_SUPPRESS_BANNER: "1",
+  };
+}
+
+function startAutomationBackend(config) {
+  logService(
+    "automation",
+    `Starting on port ${config.autoBackendPort}...`,
+    c.green,
+  );
+
+  const automationCmd = buildAutomationCommand(process.env);
+  logService("automation", `Using ${automationCmd.source}`, c.dim);
+
+  spawnService(
+    "automation",
+    automationCmd.command,
+    [
+      ...automationCmd.args,
+      "--host",
+      "0.0.0.0",
+      "--port",
+      config.autoBackendPort.toString(),
+    ],
+    {
+      cwd: config.stateDir,
+      env: buildAutomationBackendEnv(config),
+      color: c.green,
+    },
+  );
+}
+
+function startStaticServer(config) {
+  // Reuse `vitePort` as the upstream port name so the ingress route table
+  // below stays identical to dev-with-automation.mjs.
+  logService("static", `Starting on port ${config.vitePort}...`, c.magenta);
+
+  // Mirror the proxy targets that vite.config.ts exposes in dev mode so that
+  // hitting :3001 directly behaves like Vite's dev server (e.g. /server_info
+  // is forwarded to the agent-server instead of falling back to the SPA
+  // shell). Without this, /server_info on :3001 returns index.html.
+  const staticServerScript = join(projectRoot, "scripts", "static-server.mjs");
+  const runtimeServicesInfo = JSON.stringify(
+    buildAutomationRuntimeServicesInfo({
+      ...config,
+      frontendKind: "static",
+    }),
+  );
+  spawnService(
+    "static",
+    "node",
+    [
+      staticServerScript,
+      "--dir",
+      join(config.canvasPath, "build"),
+      "--port",
+      String(config.vitePort),
+      ...(process.env.VITE_BASE_PATH
+        ? ["--base-path", process.env.VITE_BASE_PATH]
+        : []),
+      // Inject the API key so the pre-built frontend can authenticate
+      // to the agent-server without a baked-in VITE_SESSION_API_KEY.
+      ...(config.sessionApiKey
+        ? ["--session-api-key", config.sessionApiKey]
+        : []),
+      "--runtime-services-info",
+      runtimeServicesInfo,
+      ...buildLocalServiceRouteArgs(config),
+      // Only the static server injects into the document, so only it can tell
+      // the frontend this origin serves the editor. The ingress below routes
+      // the same prefix but proxies the HTML through untouched.
+      ...getVSCodeAdvertiseArgs(config),
+      ...getNoReferrerPrefixArgs(config),
+    ],
+    {
+      cwd: config.canvasPath,
+      color: c.magenta,
+    },
+  );
+}
+
+function startIngress(config) {
+  logService("ingress", `Starting on port ${config.ingressPort}...`, c.yellow);
+
+  const ingressScript = join(projectRoot, "scripts", "ingress.mjs");
+  const runtimeServicesInfo = JSON.stringify(
+    buildAutomationRuntimeServicesInfo({
+      ...config,
+      frontendKind: "static",
+    }),
+  );
+
+  spawnService(
+    "ingress",
+    "node",
+    [
+      ingressScript,
+      "--port",
+      config.ingressPort.toString(),
+      "--runtime-services-info",
+      runtimeServicesInfo,
+      ...buildLocalServiceRouteArgs(config),
+      ...getNoReferrerPrefixArgs(config),
+      "--default",
+      `http://localhost:${config.vitePort}`,
+    ],
+    {
+      cwd: projectRoot,
+      color: c.yellow,
+    },
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Shutdown / Banner
+// ═══════════════════════════════════════════════════════════════════════════
+
+function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+
+  console.log("");
+  console.log(`${c.yellow}Shutting down...${c.reset}`);
+
+  for (const [name, proc] of processes) {
+    logService(name, "Stopping...", c.dim);
+    signalProcessTree(proc, "SIGTERM");
+  }
+
+  setTimeout(() => {
+    for (const [name, proc] of processes) {
+      if (isProcessRunning(proc)) {
+        logService(name, "Force stopping...", c.dim);
+        signalProcessTree(proc, "SIGKILL");
+      }
+    }
+    process.exit(0);
+  }, 3000);
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+function printBanner(config) {
+  console.log("");
+  console.log(
+    `${c.green}${c.bold}╔══════════════════════════════════════════════════════════════╗${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}║${c.reset}  ${c.bold}Agent Canvas Static-frontend Stack${c.reset}                          ${c.green}${c.bold}║${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}╠══════════════════════════════════════════════════════════════╣${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}║${c.reset}                                                              ${c.green}${c.bold}║${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}║${c.reset}  Main UI:      ${c.cyan}http://localhost:${config.ingressPort}/${c.reset}`.padEnd(
+      75,
+    ) + `${c.green}${c.bold}║${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}║${c.reset}  API Docs:     ${c.cyan}http://localhost:${config.ingressPort}/api/automation/docs${c.reset}`.padEnd(
+      75,
+    ) + `${c.green}${c.bold}║${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}║${c.reset}                                                              ${c.green}${c.bold}║${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}╚══════════════════════════════════════════════════════════════╝${c.reset}`,
+  );
+  console.log("");
+  console.log(`${c.dim}State directory: ${config.stateDir}${c.reset}`);
+  console.log(
+    `${c.dim}Frontend served from: ${join(config.canvasPath, "build")}${c.reset}`,
+  );
+  console.log(
+    `${c.dim}Edit sources, then re-run \`npm run dev:static\` to rebuild.${c.reset}`,
+  );
+  console.log(`${c.dim}Press Ctrl+C to stop${c.reset}`);
+  console.log("");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Main
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main() {
+  const args = parseArgs();
+  const config = await buildConfig(args);
+
+  console.log("");
+  console.log(
+    `${c.cyan}${c.bold}Agent Canvas Static-frontend Development Stack${c.reset}`,
+  );
+  console.log("");
+
+  // Setup phase (1/3)
+  checkPrerequisites();
+
+  // Ensure isolated state dirs (same as dev-with-automation).
+  const { mkdirSync } = await import("node:fs");
+  for (const dir of [
+    config.stateDir,
+    join(config.stateDir, "dev_conversations"),
+    join(config.stateDir, "workspaces"),
+    join(config.stateDir, "bash_events"),
+    join(config.stateDir, "storage"),
+  ]) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // Build phase (2/3): block until the SPA is ready to serve.
+  buildFrontend(config, args);
+
+  // Service phase (3/3)
+  logStep("3/3", "Starting services...");
+
+  // The agent-server skip-loads any conversation whose `owner_lease.json`
+  // is held by a different `owner_instance_id` and not yet expired (45 s
+  // TTL). If a previous agent-server (e.g. from `npm run dev`) was killed
+  // ungracefully — or we restart faster than the lease TTL — every
+  // conversation gets hidden until those stale leases age out, which
+  // looks like "the new agent-server doesn't inherit my conversations".
+  // Bail out if a live agent-server is already bound to our port (we'd
+  // collide anyway), otherwise unlink the stale leases so the new server
+  // can claim ownership immediately.
+  if (await isPortBusy(config.agentServerPort)) {
+    logError(
+      `Port ${config.agentServerPort} is already in use — another ` +
+        `agent-server is running. Stop it (e.g. quit \`npm run dev\`) ` +
+        `before running dev:static.`,
+    );
+    process.exit(1);
+  }
+  const conversationsPath = join(config.stateDir, "dev_conversations");
+  const cleared = releaseStaleConversationLeases(conversationsPath);
+  if (cleared > 0) {
+    logService(
+      "agent-server",
+      `Released ${cleared} stale conversation lease(s) so the new ` +
+        `agent-server can resume ownership.`,
+      c.dim,
+    );
+  }
+
+  startAgentServer(config);
+  await waitForService(
+    "agent-server",
+    `${getAgentServerBaseUrl(config)}/server_info`,
+  );
+
+  startAutomationBackend(config);
+
+  startStaticServer(config);
+
+  await delay(2000);
+
+  startIngress(config);
+
+  await delay(1000);
+
+  printBanner(config);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Exports for testing
+// ═══════════════════════════════════════════════════════════════════════════
+
+export {
+  buildAutomationBackendEnv,
+  buildFrontend,
+  buildLocalServiceRouteArgs,
+  startStaticServer,
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Main entry point (only when run directly, not when imported)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const isMainModule =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isMainModule) {
+  main().catch((err) => {
+    logError(`Fatal error: ${err.message}`);
+    if (err.stack) {
+      console.error(c.dim + err.stack + c.reset);
+    }
+    process.exit(1);
+  });
+}

scripts/dev-with-automation.mjs

@@ -0,0 +1,1715 @@
+/**
+ * Development Stack with Automation Service
+ *
+ * Extends agent-canvas's dev-safe.mjs to additionally run the OpenHands Automation
+ * backend via uvx. No cloning required - runs directly from git reference.
+ *
+ * Uses a standalone ingress proxy to route traffic to multiple backends.
+ *
+ * Architecture:
+ *   ┌──────────────────────────────────────────────────────────────────────────┐
+ *   │              http://localhost:8000 (Ingress Proxy)                       │
+ *   │              /api/automation/* → Automation Backend                      │
+ *   │              /api/*, /sockets  → Agent Server                            │
+ *   │              /*                → Vite Dev Server                         │
+ *   └──────────────────────────────────────────────────────────────────────────┘
+ *          │                    │                         │
+ *          ▼                    ▼                         ▼
+ *   ┌─────────────┐    ┌───────────────┐         ┌──────────────────┐
+ *   │ Vite        │    │ Agent Server  │         │ Automation       │
+ *   │ :3001       │    │ (uvx) :18000  │         │ Backend (uvx)    │
+ *   │             │    │               │         │ :18001           │
+ *   └─────────────┘    └───────────────┘         └──────────────────┘
+ *
+ * Usage:
+ *   node scripts/dev-with-automation.mjs
+ *   node scripts/dev-with-automation.mjs --automation-ref feat/my-branch
+ *   node scripts/dev-with-automation.mjs --port 12000
+ *
+ * Environment variables:
+ *   - PORT: Ingress port (default: 8000)
+ *   - OH_AUTOMATION_GIT_REF: Git ref for automation (overrides default version)
+ *   - OH_AGENT_SERVER_LOCAL_PATH: Absolute path to a local software-agent-sdk
+ *     checkout. Highest precedence for agent-server source selection: rebuilds
+ *     the agent-server from local source and installs openhands-sdk,
+ *     openhands-tools and openhands-workspace as editable so source edits are
+ *     picked up without manual reinstall.
+ *   - OH_AGENT_SERVER_GIT_REF: Git ref for agent-server
+ * Secrets:
+ *   The session API key is automatically seeded into agent-server secrets
+ *   as OPENHANDS_AUTOMATION_API_KEY, making it available to agents in conversations.
+ *   Both the agent-server and automation backend use the same key value
+ *   and the same `X-Session-API-Key` header for authentication.
+ *   AUTOMATION_KV_SECRET is derived from the session key if not set explicitly,
+ *   enabling the KV store out of the box for local development.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, existsSync, readFileSync } from "node:fs";
+import { join, resolve, dirname, isAbsolute } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { homedir } from "node:os";
+import { setTimeout as delay } from "node:timers/promises";
+import process from "node:process";
+
+import {
+  assertPortsFree,
+  buildAgentServerCommand,
+  buildSafeDevConfig,
+  buildAgentServerEnv,
+  buildNpmScriptCommand,
+  buildRuntimeServicesInfo,
+  formatMissingUvxGuidance,
+  validateFrontendDependencies,
+  validateLocalAgentServerPath,
+} from "./dev-safe.mjs";
+import {
+  createShutdownHookRegistry,
+  getProcessTreeSpawnOptions,
+  isProcessRunning,
+  resolveWindowsCommand,
+  signalProcessTree,
+} from "./dev-process-utils.mjs";
+import { fileLog, stripAnsi } from "./logger.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..");
+
+// ── Centralized config (single source of truth for versions, ports, etc.) ───
+const SHARED_DEFAULTS = JSON.parse(
+  readFileSync(join(projectRoot, "config", "defaults.json"), "utf-8"),
+);
+
+const DEFAULT_AUTOMATION_REPO = "https://github.com/OpenHands/automation";
+const DEFAULT_AUTOMATION_PACKAGE = SHARED_DEFAULTS.packages.automation;
+const DEFAULT_AUTOMATION_VERSION = SHARED_DEFAULTS.versions.automation;
+const DEFAULT_AUTOMATION_SDK_VERSION = SHARED_DEFAULTS.versions.agentServer;
+const DEFAULT_BACKEND_PORT = SHARED_DEFAULTS.ports.agentServer;
+const DEFAULT_AUTOMATION_PORT = SHARED_DEFAULTS.ports.automation;
+const DEFAULT_POSTHOG_API_KEY = SHARED_DEFAULTS.telemetry.posthogApiKey;
+const DEFAULT_POSTHOG_HOST = SHARED_DEFAULTS.telemetry.posthogHost;
+
+// ═══════════════════════════════════════════════════════════════════��═══════
+// Terminal Styling
+// ═══════════════════════════════════════════════════════════════════════════
+
+const c = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+};
+
+function logService(name, message, color = c.reset) {
+  const ts = new Date().toISOString().split("T")[1].split(".")[0];
+  console.log(`${c.dim}${ts}${c.reset} ${color}[${name}]${c.reset} ${message}`);
+  fileLog("info", `[${name}] ${stripAnsi(message)}`);
+}
+
+function logStep(step, message) {
+  console.log(`${c.cyan}[${step}]${c.reset} ${message}`);
+  fileLog("info", `[${step}] ${message}`);
+}
+
+function logSuccess(message) {
+  console.log(`${c.green}✓${c.reset} ${message}`);
+  fileLog("info", `✓ ${message}`);
+}
+
+function logError(message) {
+  console.error(`${c.red}✗${c.reset} ${message}`);
+  fileLog("error", `✗ ${stripAnsi(message)}`);
+}
+
+/**
+ * Parse one JSON log line produced by the SDK's JsonFormatter and return a
+ * single-line human-readable string + an appropriate ANSI color.
+ *
+ * Returns null for non-JSON lines so callers can fall back to the raw text.
+ *
+ * @param {string} rawLine
+ * @returns {{ text: string; color: string } | null}
+ */
+function parseAgentServerLogLine(rawLine) {
+  try {
+    const obj = JSON.parse(rawLine);
+    if (!obj.levelname || obj.message === undefined) return null;
+    const level = obj.levelname.padEnd(8);
+    const location =
+      obj.filename && obj.lineno ? `  ${obj.filename}:${obj.lineno}` : "";
+    const text = `${level} ${obj.message}${location}`;
+    const lvl = obj.levelname;
+    const color =
+      lvl === "DEBUG"
+        ? c.dim
+        : lvl === "WARNING"
+          ? c.yellow
+          : lvl === "ERROR" || lvl === "CRITICAL"
+            ? c.red
+            : c.blue;
+    return { text, color };
+  } catch {
+    return null;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Configuration
+// ═══════════════════════════════════════════════════════════════════════════
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const config = {
+    port: null,
+    automationGitRef: null,
+    automationRepo: null,
+    verbose: false,
+    static: false,
+    dynamic: false,
+    staticDir: null,
+    skipBuild: false,
+    public: false,
+    frontendOnly: false,
+    backendOnly: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case "-p":
+      case "--port":
+        config.port = parseInt(args[++i], 10);
+        break;
+      case "--automation-ref":
+        config.automationGitRef = args[++i];
+        break;
+      case "--automation-repo":
+        config.automationRepo = args[++i];
+        break;
+      case "-v":
+      case "--verbose":
+        config.verbose = true;
+        break;
+      case "--static":
+        config.static = true;
+        break;
+      case "--dynamic":
+        config.dynamic = true;
+        break;
+      case "--static-dir":
+        config.staticDir = args[++i];
+        break;
+      case "--skip-build":
+        config.skipBuild = true;
+        break;
+      case "--public":
+        config.public = true;
+        break;
+      case "--frontend-only":
+        config.frontendOnly = true;
+        break;
+      case "--backend-only":
+        config.backendOnly = true;
+        break;
+      case "-h":
+      case "--help":
+        showHelp();
+        process.exit(0);
+    }
+  }
+
+  return config;
+}
+
+function showHelp() {
+  console.log(`
+Agent Canvas + Automation Development Stack
+
+Runs agent-canvas with the automation backend (via uvx, no clone needed).
+Uses a standalone ingress proxy to route traffic.
+
+USAGE:
+  node scripts/dev-with-automation.mjs [options]
+
+OPTIONS:
+  -p, --port <port>           Ingress port (default: 8000)
+  --automation-ref <ref>      Git ref for automation (branch/tag/SHA)
+  --automation-repo <url>     Git repo URL (default: ${DEFAULT_AUTOMATION_REPO})
+  --static                    Serve an existing production build instead of Vite
+  --static-dir <dir>          Static build directory (default: build/)
+  --skip-build                Reuse build/ when the launcher builds static assets
+  --dynamic                   Force Vite dev server when a wrapper defaults static
+  --frontend-only             Start only the frontend behind ingress
+  --backend-only              Start only agent-server + automation behind ingress
+  -v, --verbose               Show detailed output
+  -h, --help                  Show this help
+
+ENVIRONMENT VARIABLES:
+  PORT                        Alternative to --port
+  OH_AUTOMATION_GIT_REF       Git ref for automation (overrides default version)
+  OH_AUTOMATION_VERSION       Specific PyPI version for automation (default: ${DEFAULT_AUTOMATION_VERSION})
+  OH_AUTOMATION_LOCAL_PATH    Absolute path to a local automation checkout (overridden only by --automation-git-ref)
+  OH_AGENT_SERVER_LOCAL_PATH  Absolute path to a local software-agent-sdk checkout (highest precedence)
+  OH_AGENT_SERVER_GIT_REF     Git ref for agent-server SDK (overrides default version)
+  OH_AGENT_SERVER_VERSION     Specific PyPI version for agent-server
+  OH_SECRET_KEY               Secret key for sessions
+
+SECRETS:
+  The session API key is automatically seeded into agent-server secrets
+  as OPENHANDS_AUTOMATION_API_KEY, making it available to agents in conversations.
+  Both backends (agent-server and automation) share the same key value.
+  AUTOMATION_KV_SECRET defaults to the session key so the KV store works
+  out of the box; override with an explicit value for stronger isolation.
+
+ACCESS POINTS:
+  Main UI:      http://localhost:PORT/
+  API Docs:     http://localhost:PORT/api/automation/docs
+`);
+}
+
+/**
+ * Fail fast on an unusable OH_AUTOMATION_LOCAL_PATH instead of letting
+ * `uv run --project <bad path>` exit on its own -- that leaves the rest of the
+ * stack up and the automations UI just reporting "backend unavailable", with
+ * nothing pointing at the env var. Mirrors validateLocalAgentServerPath.
+ */
+function validateLocalAutomationPath(localPath) {
+  if (!isAbsolute(localPath)) {
+    throw new Error(
+      `OH_AUTOMATION_LOCAL_PATH must be an absolute path, got: ${localPath}`,
+    );
+  }
+  if (!existsSync(localPath)) {
+    throw new Error(`OH_AUTOMATION_LOCAL_PATH does not exist: ${localPath}`);
+  }
+  const projectFile = join(localPath, "pyproject.toml");
+  if (!existsSync(projectFile)) {
+    throw new Error(
+      `OH_AUTOMATION_LOCAL_PATH is not a Python project (no pyproject.toml): ${projectFile}`,
+    );
+  }
+}
+
+/**
+ * Build the uvx command for running automation backend.
+ *
+ * Environment variables (highest precedence first):
+ * - OH_AUTOMATION_LOCAL_PATH: Absolute path to a local checkout
+ * - OH_AUTOMATION_GIT_REF: Git commit SHA or branch name
+ * - OH_AUTOMATION_VERSION: Specific PyPI version (e.g., "1.0.0a1")
+ *
+ * If none are set, defaults to the released version specified by
+ * DEFAULT_AUTOMATION_VERSION. Set OH_AUTOMATION_GIT_REF to use a
+ * git branch or commit instead.
+ */
+function buildAutomationCommand(env = process.env) {
+  const localPath = env.OH_AUTOMATION_LOCAL_PATH;
+  const gitRef = env.OH_AUTOMATION_GIT_REF;
+  const version = env.OH_AUTOMATION_VERSION;
+  const repoUrl = env.OH_AUTOMATION_REPO || DEFAULT_AUTOMATION_REPO;
+
+  const uvxArgs = [];
+  let source = "";
+
+  if (localPath) {
+    // Run straight from a local checkout via `uv run --project`, so
+    // uncommitted working-tree changes are picked up. Outranks the other
+    // automation env vars, mirroring OH_AGENT_SERVER_LOCAL_PATH for the
+    // agent-server SDK; buildConfig drops it when --automation-git-ref asks
+    // for a specific ref.
+    return {
+      command: "uv",
+      args: [
+        "run",
+        "--project",
+        localPath,
+        "uvicorn",
+        "openhands.automation.app:app",
+      ],
+      source: `local (${localPath})`,
+    };
+  }
+
+  if (gitRef) {
+    // Use git ref - refresh to ensure latest commit is fetched
+    const gitUrl = `git+${repoUrl}@${gitRef}`;
+    uvxArgs.push(
+      "--refresh",
+      "--from",
+      gitUrl,
+      "uvicorn",
+      "openhands.automation.app:app",
+    );
+    source = `git (${gitRef})`;
+  } else if (version) {
+    // Use specific PyPI version
+    uvxArgs.push(
+      "--from",
+      `${DEFAULT_AUTOMATION_PACKAGE}==${version}`,
+      "uvicorn",
+      "openhands.automation.app:app",
+    );
+    source = `PyPI (${version})`;
+  } else {
+    // Default to released PyPI version
+    uvxArgs.push(
+      "--from",
+      `${DEFAULT_AUTOMATION_PACKAGE}==${DEFAULT_AUTOMATION_VERSION}`,
+      "uvicorn",
+      "openhands.automation.app:app",
+    );
+    source = `PyPI (${DEFAULT_AUTOMATION_VERSION}, default)`;
+  }
+
+  return {
+    command: "uvx",
+    args: uvxArgs,
+    source,
+  };
+}
+
+async function buildConfig(args, env = process.env) {
+  // Apply args to env for buildAutomationCommand
+  if (args.automationGitRef) {
+    env.OH_AUTOMATION_GIT_REF = args.automationGitRef;
+    // An explicit flag outranks an ambient env var. Otherwise someone with
+    // OH_AUTOMATION_LOCAL_PATH exported in their shell profile would run their
+    // own working tree while believing they were reproducing against the ref
+    // they just passed.
+    if (env.OH_AUTOMATION_LOCAL_PATH) {
+      logStep(
+        "automation",
+        `--automation-git-ref ${args.automationGitRef} overrides OH_AUTOMATION_LOCAL_PATH (${env.OH_AUTOMATION_LOCAL_PATH})`,
+      );
+      delete env.OH_AUTOMATION_LOCAL_PATH;
+    }
+  }
+  if (args.automationRepo) {
+    env.OH_AUTOMATION_REPO = args.automationRepo;
+  }
+
+  const frontendOnly = Boolean(args.frontendOnly);
+  const backendOnly = Boolean(args.backendOnly);
+  if (frontendOnly && backendOnly) {
+    throw new Error(
+      "--frontend-only and --backend-only cannot be used together",
+    );
+  }
+
+  const launchFrontend = !backendOnly;
+  const launchAgentServer = !frontendOnly;
+  const launchAutomation = !frontendOnly;
+  const isPublic = args.public;
+
+  if (isPublic && frontendOnly) {
+    throw new Error("--public cannot be used with --frontend-only");
+  }
+
+  // In public mode, LOCAL_BACKEND_API_KEY is required — without it the
+  // auth screen has nothing to validate against.
+  if (isPublic && !env.LOCAL_BACKEND_API_KEY) {
+    logError(
+      "PUBLIC MODE requires LOCAL_BACKEND_API_KEY environment variable.\n" +
+        "  Example: LOCAL_BACKEND_API_KEY=my-secret npm run dev -- --public",
+    );
+    process.exit(1);
+  }
+
+  // Preferred ports (from env or defaults).
+  // OH_CANVAS_SAFE_BACKEND_PORT / OH_CANVAS_SAFE_AUTOMATION_PORT /
+  // OH_CANVAS_SAFE_VITE_PORT allow tests (and advanced users) to redirect
+  // internal service ports without affecting the production default.
+  const preferredIngressPort = args.port || parseInt(env.PORT, 10) || 8000;
+  const preferredBackendPort =
+    parseInt(env.OH_CANVAS_SAFE_BACKEND_PORT, 10) || DEFAULT_BACKEND_PORT;
+  const preferredAutomationPort =
+    parseInt(env.OH_CANVAS_SAFE_AUTOMATION_PORT, 10) || DEFAULT_AUTOMATION_PORT;
+  const preferredVitePort = parseInt(env.OH_CANVAS_SAFE_VITE_PORT, 10) || 3001;
+
+  // Fail fast if any preferred port for a service in this mode is already in use.
+  const requiredPorts = [{ name: "ingress", port: preferredIngressPort }];
+  if (launchAgentServer) {
+    requiredPorts.push({ name: "agent-server", port: preferredBackendPort });
+  }
+  if (launchAutomation) {
+    requiredPorts.push({ name: "automation", port: preferredAutomationPort });
+  }
+  if (launchFrontend) {
+    requiredPorts.push({ name: "frontend", port: preferredVitePort });
+  }
+
+  logStep("ports", "Checking ports...");
+  await assertPortsFree(requiredPorts);
+
+  const vscodePort = preferredBackendPort + 1000;
+
+  // API key — shared by both agent-server and automation backend.
+  // Both validate it via the `X-Session-API-Key` header.
+  // LOCAL_BACKEND_API_KEY is the single user-facing env var: if set it's
+  // used directly; otherwise one is auto-generated and persisted.
+  const stateDir =
+    env.OH_CANVAS_SAFE_STATE_DIR ||
+    join(homedir(), ".openhands", "agent-canvas");
+
+  const safeConfig = buildSafeDevConfig(projectRoot, {
+    ...env,
+    OH_CANVAS_SAFE_STATE_DIR: stateDir,
+    OH_CANVAS_SAFE_BACKEND_PORT: preferredBackendPort.toString(),
+    OH_CANVAS_SAFE_VSCODE_PORT: vscodePort.toString(),
+  });
+  const sessionApiKey = safeConfig.sessionApiKey;
+
+  if (isPublic) {
+    logService(
+      "auth",
+      "PUBLIC MODE — key will NOT be injected into the frontend",
+      c.yellow,
+    );
+    logService(
+      "auth",
+      "Users must paste the LOCAL_BACKEND_API_KEY in the browser",
+      c.dim,
+    );
+  }
+
+  return {
+    // Ingress port (main entry point)
+    ingressPort: preferredIngressPort,
+
+    // Service ports (internal)
+    agentServerPort: preferredBackendPort,
+    autoBackendPort: preferredAutomationPort,
+    vitePort: preferredVitePort,
+    vscodePort,
+    // Prefix the editor is served under on the ingress origin. Carried on the
+    // config so the route table and the agent-server env are built from one
+    // value (see getLocalServiceRoutes / buildAgentServerEnv).
+    vscodeBasePath: safeConfig.vscodeBasePath,
+
+    // Paths
+    canvasPath: projectRoot,
+
+    // Data directories (same as dev-safe.mjs)
+    stateDir,
+    // Only bake the host-side workspace path when this launcher also starts
+    // the agent-server that can read it. In frontend-only mode the backend may
+    // be a tunnel/remote service, so leave VITE_WORKING_DIR unset unless the
+    // user explicitly supplied a backend-relative value.
+    viteWorkingDir: launchAgentServer
+      ? safeConfig.workingDir
+      : env.VITE_WORKING_DIR,
+
+    // Auth — single key for both backends
+    sessionApiKey,
+
+    // Public mode — the session key should NOT be baked into the frontend
+    isPublic,
+
+    frontendOnly,
+    backendOnly,
+    launchFrontend,
+    launchAgentServer,
+    launchAutomation,
+
+    verbose: args.verbose,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Prerequisites & Setup
+// ═══════════════════════════════════════════════════════════════════════════
+
+function commandExists(cmd) {
+  const result =
+    process.platform === "win32"
+      ? spawnSync("where.exe", [cmd], { stdio: "pipe" })
+      : spawnSync("sh", ["-c", `command -v ${cmd}`], { stdio: "pipe" });
+
+  return result.status === 0;
+}
+
+function checkPrerequisites({
+  checkUvx = true,
+  checkNpm = true,
+  checkFrontendDependencies = true,
+} = {}) {
+  logStep("1/2", "Checking prerequisites...");
+
+  if (checkUvx) {
+    if (!commandExists("uvx")) {
+      const uvxGuidance = formatMissingUvxGuidance(projectRoot);
+      console.error(uvxGuidance);
+      fileLog("error", stripAnsi(uvxGuidance));
+      process.exit(1);
+    }
+    logSuccess("uvx found");
+  }
+
+  if (checkNpm) {
+    if (!commandExists("npm")) {
+      logError("npm is required but not found");
+      process.exit(1);
+    }
+    logSuccess("npm found");
+  }
+
+  if (checkFrontendDependencies) {
+    try {
+      validateFrontendDependencies(projectRoot);
+    } catch (error) {
+      logError(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+    logSuccess("frontend dependencies found");
+  }
+}
+
+function ensureDirectories(config) {
+  const dirs = [
+    config.stateDir,
+    // Both agent-server and automation use storage; create it unconditionally
+    // whenever either backend service runs (i.e. not frontend-only).
+    ...(!config.frontendOnly ? [join(config.stateDir, "storage")] : []),
+  ];
+
+  if (config.launchAgentServer) {
+    dirs.push(
+      join(config.stateDir, "dev_conversations"),
+      join(config.stateDir, "workspaces"),
+      join(config.stateDir, "bash_events"),
+    );
+  }
+
+  if (config.launchAutomation) {
+    dirs.push(
+      // Automation DB directory — matches docker/entrypoint.sh mkdir -p behaviour.
+      dirname(
+        join(dirname(config.stateDir), SHARED_DEFAULTS.paths.automationDb),
+      ),
+    );
+  }
+
+  for (const dir of dirs) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Process Management
+// ═══════════════════════════════════════════════════════════════════════════
+
+const processes = new Map();
+const shutdownHooks = createShutdownHookRegistry((err) => {
+  logService("cleanup", `Cleanup hook failed: ${err.message}`, c.yellow);
+});
+
+// Optional external listener for every service log line. Set by `main()` from
+// its `onServiceLog` option so embedded launchers (e.g. the Electron desktop
+// app) can stream uvx download / install progress to their loading window
+// without touching the terminal logging path. Receives `(name, line, level)`
+// where `level` is one of "stdout" | "stderr" | "info" | "warn" | "error".
+let serviceLogListener = null;
+
+export function setServiceLogListener(listener) {
+  serviceLogListener = typeof listener === "function" ? listener : null;
+}
+
+function emitServiceLog(name, line, level) {
+  if (!serviceLogListener) return;
+  try {
+    serviceLogListener(name, line, level);
+  } catch {
+    // Never let a listener bug crash the dev stack.
+  }
+}
+
+function registerShutdownHook(hook) {
+  return shutdownHooks.add(hook);
+}
+
+function spawnService(name, command, args, options = {}) {
+  const proc = spawn(
+    resolveWindowsCommand(command),
+    args,
+    getProcessTreeSpawnOptions({
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...options.env },
+      cwd: options.cwd,
+    }),
+  );
+
+  const color = options.color || c.reset;
+  const parseLogLine = options.parseLogLine;
+
+  proc.stdout.on("data", (data) => {
+    data
+      .toString()
+      .split("\n")
+      .filter(Boolean)
+      .forEach((line) => {
+        const trimmed = line.trim();
+        const parsed = parseLogLine ? parseLogLine(trimmed) : null;
+        logService(
+          name,
+          parsed ? parsed.text : trimmed,
+          parsed ? parsed.color : color,
+        );
+        emitServiceLog(name, trimmed, "stdout");
+      });
+  });
+
+  proc.stderr.on("data", (data) => {
+    data
+      .toString()
+      .split("\n")
+      .filter(Boolean)
+      .forEach((line) => {
+        const trimmed = line.trim();
+        const parsed = parseLogLine ? parseLogLine(trimmed) : null;
+        logService(
+          name,
+          parsed ? parsed.text : trimmed,
+          parsed ? parsed.color : c.yellow,
+        );
+        emitServiceLog(name, trimmed, "stderr");
+      });
+  });
+
+  proc.on("error", (error) => {
+    logError(`${name} failed to start: ${error.message}`);
+    emitServiceLog(name, `failed to start: ${error.message}`, "error");
+  });
+
+  proc.on("exit", (code, _signal) => {
+    if (code !== 0 && code !== null && !shuttingDown) {
+      logService(name, `Exited with code ${code}`, c.red);
+      emitServiceLog(name, `exited with code ${code}`, "error");
+    }
+    processes.delete(name);
+  });
+
+  processes.set(name, proc);
+  return proc;
+}
+
+async function waitForService(name, url, timeoutMs = 30000) {
+  const start = Date.now();
+  let lastError = null;
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+      if (res.ok) {
+        logService(name, `Ready at ${url}`, c.green);
+        return true;
+      }
+    } catch (err) {
+      lastError = err;
+      // Keep trying
+    }
+    await delay(500);
+  }
+
+  const elapsed = Math.round((Date.now() - start) / 1000);
+  logService(name, `Timeout waiting for ${url} after ${elapsed}s`, c.red);
+  if (lastError) {
+    logService(name, `Last error: ${lastError.message}`, c.dim);
+  }
+  return false;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Service Starters
+// ═══════════════════════════════════════════════════════════════════════════
+
+const AUTOMATION_ROUTE_PREFIX = "/api/automation";
+const AGENT_SERVER_ROUTE_PREFIXES = [
+  "/api",
+  "/sockets",
+  "/server_info",
+  "/health",
+  "/ready",
+  "/alive",
+  "/docs",
+  "/redoc",
+  "/openapi.json",
+];
+
+// This launcher starts the agent-server with `--host 127.0.0.1`, but localhost
+// can resolve to ::1 first (notably on Windows), so every request this process
+// or the automation backend makes to it must address IPv4 explicitly.
+function getAgentServerBaseUrl(config) {
+  return `http://127.0.0.1:${config.agentServerPort}`;
+}
+
+function getLocalServiceRoutes(config) {
+  const routes = [];
+
+  // These services bind to IPv4 loopback, but localhost can resolve to ::1.
+  if (config.launchAutomation) {
+    routes.push([
+      AUTOMATION_ROUTE_PREFIX,
+      `http://127.0.0.1:${config.autoBackendPort}`,
+    ]);
+  }
+
+  if (config.launchAgentServer) {
+    for (const prefix of AGENT_SERVER_ROUTE_PREFIXES) {
+      routes.push([prefix, getAgentServerBaseUrl(config)]);
+    }
+
+    // The editor is a separate process on its own port, but it is reached
+    // through the same origin as the canvas so no second port has to be
+    // published. The prefix is deliberately preserved rather than stripped:
+    // agent-server launches openvscode-server with `--server-base-path`, so
+    // the editor generates its own HTTP and WebSocket URLs beneath the prefix
+    // and only answers there. `createRouter` matches the longest prefix and
+    // the proxy forwards the original path, so both are already handled.
+    if (config.vscodeBasePath) {
+      routes.push([
+        config.vscodeBasePath,
+        `http://127.0.0.1:${config.vscodePort}`,
+      ]);
+    }
+  }
+
+  return routes;
+}
+
+function buildRouteArgs(routes) {
+  return routes.flatMap(([prefix, url]) => ["--route", `${prefix}=${url}`]);
+}
+
+/**
+ * The editor prefix, if this mode serves it, as `--no-referrer-prefix` args.
+ *
+ * agent-server hands the editor a connection token derived from its session
+ * key and advertises it in the URL's query string, so the workbench document
+ * must not leak a Referer to the subresources it loads.
+ */
+function getNoReferrerPrefixArgs(config) {
+  if (!config.launchAgentServer || !config.vscodeBasePath) return [];
+  return ["--no-referrer-prefix", config.vscodeBasePath];
+}
+
+/**
+ * The editor prefix, if this mode serves it, as `--vscode-base-path` args.
+ *
+ * Gated on exactly the same condition as the editor route in
+ * `getLocalServiceRoutes`, because they answer the same question: an origin
+ * advertises the editor if and only if it routes it. static-server enforces
+ * that pairing at startup, so a future edit that breaks it fails loudly rather
+ * than shipping a control that opens the SPA.
+ */
+function getVSCodeAdvertiseArgs(config) {
+  if (!config.launchAgentServer || !config.vscodeBasePath) return [];
+  return ["--vscode-base-path", config.vscodeBasePath];
+}
+
+/**
+ * Build --reject-prefix args for the static server.
+ * In frontend-only mode, API paths that have no backend should return 503
+ * instead of being SPA-fallbacked to index.html.
+ */
+function getRejectPrefixes(config) {
+  const prefixes = [];
+  if (!config.launchAutomation) {
+    prefixes.push(AUTOMATION_ROUTE_PREFIX);
+  }
+  if (!config.launchAgentServer) {
+    for (const prefix of AGENT_SERVER_ROUTE_PREFIXES) {
+      prefixes.push(prefix);
+    }
+    // No agent-server means no editor behind this prefix either. Reject it
+    // rather than SPA-fallbacking to index.html, which would answer an editor
+    // request with the canvas shell.
+    if (config.vscodeBasePath) {
+      prefixes.push(config.vscodeBasePath);
+    }
+  }
+  return prefixes;
+}
+
+function buildRejectPrefixArgs(prefixes) {
+  return prefixes.flatMap((prefix) => ["--reject-prefix", prefix]);
+}
+
+function getFrontendBackend(config) {
+  return config.launchFrontend ? `http://localhost:${config.vitePort}` : null;
+}
+
+function buildViteBackendEnv(config, env = process.env) {
+  // VITE_BACKEND_HOST tells the Vite dev-server proxy (vite.config.ts) where
+  // to forward /api, /sockets, etc.  It is NOT read by the frontend at
+  // runtime, so it is safe to keep as an absolute address.
+  //
+  // VITE_BACKEND_BASE_URL is intentionally left unset so the frontend falls
+  // back to window.location.origin (same-origin) at runtime — matching the
+  // behaviour of dev:static / agent-canvas and keeping the dev server
+  // portable across localhost, LAN hosts, SSH tunnels, and ngrok.
+  const backendHost = config.launchAgentServer
+    ? `127.0.0.1:${config.ingressPort}`
+    : (env.VITE_BACKEND_HOST ??
+      env.VITE_BACKEND_BASE_URL?.replace(/^https?:\/\//, "") ??
+      "127.0.0.1:8000");
+
+  const env_out = { VITE_BACKEND_HOST: backendHost };
+
+  // If the user supplied VITE_BACKEND_BASE_URL with an https:// scheme and
+  // did not explicitly set VITE_USE_TLS, propagate the HTTPS intent so the
+  // Vite proxy forwards over TLS instead of plain HTTP.
+  if (
+    !config.launchAgentServer &&
+    env.VITE_BACKEND_BASE_URL?.startsWith("https://") &&
+    env.VITE_USE_TLS === undefined
+  ) {
+    env_out.VITE_USE_TLS = "true";
+  }
+
+  return env_out;
+}
+
+function buildAgentServerAutomationEnv(config) {
+  return {
+    // Make the session API key available to terminal commands spawned by the
+    // agent-server as OPENHANDS_AUTOMATION_API_KEY. The launcher also seeds
+    // this into Settings > Secrets, but agents commonly create automations
+    // with a curl command that references `$OPENHANDS_AUTOMATION_API_KEY`;
+    // exposing it here keeps that path working even before/without
+    // secret-registry env expansion.
+    OPENHANDS_AUTOMATION_API_KEY: config.sessionApiKey,
+  };
+}
+
+function buildAutomationTelemetryEnv(env = process.env) {
+  const telemetryDisabled = env.VITE_DO_NOT_TRACK === "1";
+  const apiKey =
+    env.AUTOMATION_POSTHOG_API_KEY ||
+    env.VITE_POSTHOG_API_KEY ||
+    (telemetryDisabled ? "" : DEFAULT_POSTHOG_API_KEY);
+
+  if (!apiKey) return {};
+
+  return {
+    AUTOMATION_POSTHOG_API_KEY: apiKey,
+    AUTOMATION_POSTHOG_HOST:
+      env.AUTOMATION_POSTHOG_HOST ||
+      env.VITE_POSTHOG_HOST ||
+      DEFAULT_POSTHOG_HOST,
+  };
+}
+
+function startAgentServer(config) {
+  logService(
+    "agent-server",
+    `Starting on port ${config.agentServerPort}...`,
+    c.blue,
+  );
+
+  const agentServerCmd = buildAgentServerCommand(process.env);
+  logService("agent-server", `Using ${agentServerCmd.source}`, c.dim);
+
+  // Build safe config for agent-server env vars
+  const safeConfig = buildSafeDevConfig(config.canvasPath, {
+    ...process.env,
+    OH_CANVAS_SAFE_STATE_DIR: config.stateDir,
+    OH_CANVAS_SAFE_BACKEND_PORT: config.agentServerPort.toString(),
+    OH_CANVAS_SAFE_VSCODE_PORT: config.vscodePort.toString(),
+  });
+
+  const agentServerEnv = {
+    // Opt into prefix-mode: `getLocalServiceRoutes` registers the matching
+    // route on both the static server and the ingress, so the prefix this
+    // advertises resolves to the editor port on the canvas origin.
+    ...buildAgentServerEnv(safeConfig, {
+      vscodeBasePath: config.vscodeBasePath,
+    }),
+    ...buildAgentServerAutomationEnv(config),
+    OPENHANDS_REMOTE_WS_READY_REQUIRED:
+      process.env.OPENHANDS_REMOTE_WS_READY_REQUIRED || "false",
+    // Ensure the agent-server uses the resolved key from config. This is
+    // LOCAL_BACKEND_API_KEY when set, or the auto-generated persisted key.
+    OH_SESSION_API_KEYS_0: config.sessionApiKey,
+    // Emit structured JSON log lines instead of Rich-formatted output.
+    // Rich wraps long messages across multiple lines and prepends its own
+    // timestamp; LOG_JSON=true produces one JSON object per record which
+    // parseAgentServerLogLine re-formats into a clean single-line entry.
+    LOG_JSON: "true",
+  };
+
+  spawnService(
+    "agent-server",
+    agentServerCmd.command,
+    [
+      ...agentServerCmd.args,
+      "--host",
+      "127.0.0.1",
+      "--port",
+      String(config.agentServerPort),
+    ],
+    {
+      cwd: safeConfig.workspacesPath,
+      env: agentServerEnv,
+      color: c.blue,
+      parseLogLine: parseAgentServerLogLine,
+    },
+  );
+}
+
+function startAutomationBackend(config) {
+  logService(
+    "automation",
+    `Starting on port ${config.autoBackendPort}...`,
+    c.green,
+  );
+
+  const automationCmd = buildAutomationCommand(process.env);
+  logService("automation", `Using ${automationCmd.source}`, c.dim);
+
+  spawnService(
+    "automation",
+    automationCmd.command,
+    [
+      ...automationCmd.args,
+      "--host",
+      "127.0.0.1",
+      "--port",
+      config.autoBackendPort.toString(),
+    ],
+    {
+      cwd: config.stateDir,
+      env: {
+        // Force UTF-8 for all Python file I/O (same reason as agent-server;
+        // see buildAgentServerEnv in dev-safe.mjs).
+        PYTHONUTF8: "1",
+        OPENHANDS_REMOTE_WS_READY_REQUIRED:
+          process.env.OPENHANDS_REMOTE_WS_READY_REQUIRED || "false",
+        // The URL the automation backend itself uses to call the
+        // agent-server's REST API (tarball upload + bash dispatch).
+        //
+        // Priority:
+        //   1. AUTOMATION_AGENT_SERVER_URL explicitly set in the user's env
+        //   2. `127.0.0.1:<agentServerPort>`
+        AUTOMATION_AGENT_SERVER_URL:
+          process.env.AUTOMATION_AGENT_SERVER_URL ||
+          getAgentServerBaseUrl(config),
+        // The URL exported into the in-sandbox bash chain as
+        // `AGENT_SERVER_URL` (read by main.py / setup.sh to call back into
+        // the agent-server).
+        //
+        // Priority:
+        //   1. AUTOMATION_SANDBOX_AGENT_SERVER_URL explicitly set in env
+        //   2. launcher-provided value
+        //   3. unset — backend falls back to AUTOMATION_AGENT_SERVER_URL
+        ...(process.env.AUTOMATION_SANDBOX_AGENT_SERVER_URL ||
+        config.sandboxAgentServerUrl
+          ? {
+              AUTOMATION_SANDBOX_AGENT_SERVER_URL:
+                process.env.AUTOMATION_SANDBOX_AGENT_SERVER_URL ||
+                config.sandboxAgentServerUrl,
+            }
+          : {}),
+        AUTOMATION_AGENT_SERVER_API_KEY: config.sessionApiKey,
+        // ~/.openhands/automation/automations.db — matches docker/entrypoint.sh.
+        AUTOMATION_DB_URL: `sqlite+aiosqlite:///${join(dirname(config.stateDir), SHARED_DEFAULTS.paths.automationDb)}`,
+        // The automation backend uses this as its publicly-reachable base
+        // URL: it's appended to callback URLs and injected into each
+        // sandbox as `AUTOMATION_API_URL` (consumed by setup.sh for
+        // /sdk-version and by the SDK for run completion).
+        // Priority:
+        //   1. AUTOMATION_BASE_URL explicitly set in the user's env
+        //   2. launcher-provided host
+        //   3. `localhost`
+        AUTOMATION_BASE_URL:
+          process.env.AUTOMATION_BASE_URL ||
+          `http://${config.automationApiHost ?? "localhost"}:${config.ingressPort}`,
+        // The dispatcher resolves this path and embeds it into a
+        // `mkdir -p ...` shell command executed by the agent-server.
+        // Priority:
+        //   1. AUTOMATION_WORKSPACE_BASE explicitly set in the user's env
+        //   2. `automationWorkspaceBase` option passed by the launcher
+        //   3. host-side default under config.stateDir
+        AUTOMATION_WORKSPACE_BASE:
+          process.env.AUTOMATION_WORKSPACE_BASE ||
+          config.automationWorkspaceBase ||
+          join(config.stateDir, "workspaces"),
+        // Session API key for self-hosted auth — shared with agent-server via X-Session-API-Key header
+        AUTOMATION_LOCAL_API_KEY: config.sessionApiKey,
+        ...buildAutomationTelemetryEnv(),
+        // KV store secret — required for automations to use the built-in
+        // key-value store for state persistence between runs. Used for JWT
+        // signing and value encryption.
+        // Priority:
+        //   1. AUTOMATION_KV_SECRET explicitly set in the user's env
+        //   2. sessionApiKey — convenient zero-config default for local dev
+        AUTOMATION_KV_SECRET:
+          process.env.AUTOMATION_KV_SECRET || config.sessionApiKey,
+        // CORS: allow localhost origins for dev, unless explicitly overridden.
+        AUTOMATION_CORS_ORIGINS:
+          process.env.AUTOMATION_CORS_ORIGINS ||
+          `http://localhost:${config.ingressPort},http://127.0.0.1:${config.ingressPort},http://localhost:3001,http://127.0.0.1:3001`,
+        FILE_STORE: "local",
+        LOCAL_STORAGE_PATH: join(config.stateDir, "storage"),
+        OPENHANDS_SUPPRESS_BANNER: "1",
+      },
+      color: c.green,
+    },
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Main
+// ═══════════════════════════════════════════════════════════════════════════
+
+let shuttingDown = false;
+
+function shutdown() {
+  if (shuttingDown) return;
+  shuttingDown = true;
+
+  console.log("");
+  console.log(`${c.yellow}Shutting down...${c.reset}`);
+  fileLog("info", "Shutting down...");
+
+  for (const [name, proc] of processes) {
+    logService(name, "Stopping...", c.dim);
+    signalProcessTree(proc, "SIGTERM");
+  }
+
+  setTimeout(() => {
+    for (const [name, proc] of processes) {
+      if (isProcessRunning(proc)) {
+        logService(name, "Force stopping...", c.dim);
+        signalProcessTree(proc, "SIGKILL");
+      }
+    }
+    shutdownHooks.run();
+    process.exit(0);
+  }, 3000);
+}
+
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+process.on("SIGHUP", shutdown);
+
+function startIngress(config) {
+  logService("ingress", `Starting on port ${config.ingressPort}...`, c.yellow);
+
+  const ingressScript = join(projectRoot, "scripts", "ingress.mjs");
+  const frontendBackend = getFrontendBackend(config);
+  const runtimeServicesInfo = config.launchAgentServer
+    ? JSON.stringify(buildAutomationRuntimeServicesInfo(config))
+    : null;
+
+  spawnService(
+    "ingress",
+    "node",
+    [
+      ingressScript,
+      "--port",
+      config.ingressPort.toString(),
+      ...(runtimeServicesInfo
+        ? ["--runtime-services-info", runtimeServicesInfo]
+        : []),
+      ...buildRouteArgs(getLocalServiceRoutes(config)),
+      ...getNoReferrerPrefixArgs(config),
+      ...(frontendBackend ? ["--default", frontendBackend] : []),
+    ],
+    {
+      cwd: projectRoot,
+      color: c.yellow,
+    },
+  );
+}
+
+/**
+ * Build the JSON-serializable runtime services info for an automation
+ * stack. Backend-serving processes append this to `/server_info` so any
+ * frontend connected to the backend can populate the agent's
+ * `<RUNTIME_SERVICES>` system-prompt block.
+ */
+export function buildAutomationRuntimeServicesInfo(config) {
+  return buildRuntimeServicesInfo({
+    mode: config.mode ?? "dev:automation",
+    agentHostAlias: config.agentHostAlias ?? "localhost",
+    agentServerPort: config.agentServerPort,
+    ingressPort: config.ingressPort,
+    frontendPort: config.launchFrontend ? config.vitePort : undefined,
+    // The same port hosts Vite in dynamic mode and a static-file server
+    // in static mode. The launcher records this on the config so the
+    // description shown to the agent matches reality.
+    frontendKind: config.frontendKind ?? "vite",
+    automation: config.launchAutomation
+      ? { port: config.autoBackendPort }
+      : undefined,
+  });
+}
+
+function startVite(config) {
+  logService("vite", `Starting on port ${config.vitePort}...`, c.magenta);
+
+  const frontendCommand = buildNpmScriptCommand("dev:frontend");
+
+  const viteEnv = {
+    // Full-stack mode points Vite at this launcher's ingress. Frontend-only
+    // mode uses the separately running backend ingress instead.
+    ...buildViteBackendEnv(config),
+    VITE_FRONTEND_PORT: config.vitePort.toString(),
+  };
+  if (config.viteWorkingDir) {
+    viteEnv.VITE_WORKING_DIR = config.viteWorkingDir;
+  }
+
+  // Vite serves the HTML for this mode's browser origin, so this is where the
+  // editor-capability advertisement has to be baked. The ingress in front of it
+  // routes the prefix but is a pure proxy — it injects nothing into the
+  // document, so it cannot tell the frontend what it serves.
+  //
+  // Both variables or neither: `vite.config.ts` only registers the editor proxy
+  // when it has a target as well as a prefix, and this stack has two supported
+  // browser origins — the ingress and Vite's own port, which is why the latter
+  // is in AUTOMATION_CORS_ORIGINS. On the ingress the prefix is routed by the
+  // ingress itself; on the Vite origin only this proxy can serve it. Baking the
+  // prefix alone would advertise an editor on the Vite origin whose URL then
+  // falls through to the SPA — the dead button this gating exists to prevent.
+  if (config.launchAgentServer && config.vscodeBasePath) {
+    viteEnv.VITE_VSCODE_BASE_PATH = config.vscodeBasePath;
+    viteEnv.VITE_VSCODE_TARGET = `http://127.0.0.1:${config.vscodePort}`;
+  }
+
+  // In local mode, bake the session key into the frontend so the user
+  // never has to paste it. In public mode, omit the key and set
+  // VITE_AUTH_REQUIRED so the frontend shows the API key entry screen
+  // immediately (no network round-trip needed).
+  if (config.launchAgentServer && config.isPublic) {
+    viteEnv.VITE_AUTH_REQUIRED = "true";
+  } else if (config.launchAgentServer) {
+    viteEnv.VITE_SESSION_API_KEY = config.sessionApiKey;
+  }
+
+  spawnService("vite", frontendCommand.command, frontendCommand.args, {
+    cwd: config.canvasPath,
+    env: viteEnv,
+    color: c.magenta,
+  });
+}
+
+/**
+ * Seed the session API key into agent-server's secrets store as
+ * OPENHANDS_AUTOMATION_API_KEY so agents can authenticate with the
+ * automation backend in curl commands during conversations.
+ *
+ * Includes retry logic to handle slow server startup or transient failures.
+ *
+ * @param {object} config - Configuration object with agentServerPort, sessionApiKey
+ * @param {object} options - Options for retry behavior
+ * @param {number} options.maxRetries - Maximum number of retry attempts (default: 5)
+ * @param {number} options.retryDelayMs - Delay between retries in ms (default: 2000)
+ * @param {number} options.timeoutMs - Request timeout in ms (default: 10000)
+ * @returns {Promise<boolean>} True if seeding succeeded, false otherwise
+ */
+async function seedAutomationSecret(config, options = {}) {
+  const { maxRetries = 5, retryDelayMs = 2000, timeoutMs = 10000 } = options;
+
+  const secretName = "OPENHANDS_AUTOMATION_API_KEY";
+  const secretDescription =
+    "API key for authenticating with the automation backend";
+
+  logService("secrets", `Seeding ${secretName} into agent-server...`, c.dim);
+
+  const url = `${getAgentServerBaseUrl(config)}/api/settings/secrets`;
+  const body = JSON.stringify({
+    name: secretName,
+    value: config.sessionApiKey,
+    description: secretDescription,
+  });
+
+  const headers = {
+    "Content-Type": "application/json",
+    // Include session API key if configured
+    ...(config.sessionApiKey && { "X-Session-API-Key": config.sessionApiKey }),
+  };
+
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, {
+        method: "PUT",
+        headers,
+        body,
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+
+      if (response.ok) {
+        logService("secrets", `${secretName} seeded successfully`, c.green);
+        return true;
+      }
+
+      const text = await response.text();
+      lastError = `HTTP ${response.status}: ${text}`;
+
+      // Don't retry on authentication errors - they won't resolve with retries
+      if (response.status === 401 || response.status === 403) {
+        logService(
+          "secrets",
+          `Warning: Failed to seed secret (${response.status}): ${text}`,
+          c.yellow,
+        );
+        return false;
+      }
+
+      // Retry on server errors or service unavailable
+      if (attempt < maxRetries) {
+        logService(
+          "secrets",
+          `Retry ${attempt}/${maxRetries} after ${response.status}...`,
+          c.dim,
+        );
+        await delay(retryDelayMs);
+      }
+    } catch (err) {
+      lastError = err.message;
+
+      // Connection errors likely mean server isn't ready - wait and retry
+      if (attempt < maxRetries) {
+        logService(
+          "secrets",
+          `Retry ${attempt}/${maxRetries}: ${err.message}`,
+          c.dim,
+        );
+        await delay(retryDelayMs);
+      }
+    }
+  }
+
+  logService(
+    "secrets",
+    `Warning: Failed to seed secret after ${maxRetries} attempts: ${lastError}`,
+    c.yellow,
+  );
+  return false;
+}
+
+function printBanner(config) {
+  const stackName = config.frontendOnly
+    ? "Agent Canvas Frontend Stack"
+    : config.backendOnly
+      ? "Agent Canvas Backend Stack"
+      : "Agent Canvas + Automation Stack";
+
+  // padEnd counts invisible ANSI escape bytes as visible characters, so we
+  // compute the visible length separately and pad with spaces accordingly.
+  const ansiEscape = String.fromCharCode(27);
+  const ansiRe = new RegExp(`${ansiEscape}\\[[0-9;]*m`, "g");
+  const ansiPadEnd = (str, targetVisible) => {
+    const visible = str.replace(ansiRe, "").length;
+    return str + " ".repeat(Math.max(0, targetVisible - visible));
+  };
+  // The box has 62-char inner width; each content line needs 63 visible chars
+  // before the trailing border (1 leading ║ + 62 inner).
+  const BOX_INNER = 63;
+
+  console.log("");
+  console.log(
+    `${c.green}${c.bold}╔══════════════════════════════════════════════════════════════╗${c.reset}`,
+  );
+  console.log(
+    ansiPadEnd(
+      `${c.green}${c.bold}║${c.reset}  ${c.bold}${stackName}${c.reset}`,
+      BOX_INNER,
+    ) + `${c.green}${c.bold}║${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}╠══════════════════════════════════════════════════════════════╣${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}║${c.reset}                                                              ${c.green}${c.bold}║${c.reset}`,
+  );
+  console.log(
+    ansiPadEnd(
+      `${c.green}${c.bold}║${c.reset}  Ingress:      ${c.cyan}http://localhost:${config.ingressPort}/${c.reset}`,
+      BOX_INNER,
+    ) + `${c.green}${c.bold}║${c.reset}`,
+  );
+  if (config.launchFrontend) {
+    console.log(
+      ansiPadEnd(
+        `${c.green}${c.bold}║${c.reset}  Main UI:      ${c.cyan}http://localhost:${config.ingressPort}/${c.reset}`,
+        BOX_INNER,
+      ) + `${c.green}${c.bold}║${c.reset}`,
+    );
+  }
+  if (config.launchAutomation) {
+    console.log(
+      ansiPadEnd(
+        `${c.green}${c.bold}║${c.reset}  API Docs:     ${c.cyan}http://localhost:${config.ingressPort}/api/automation/docs${c.reset}`,
+        BOX_INNER,
+      ) + `${c.green}${c.bold}║${c.reset}`,
+    );
+  }
+  console.log(
+    `${c.green}${c.bold}║${c.reset}                                                              ${c.green}${c.bold}║${c.reset}`,
+  );
+  console.log(
+    `${c.green}${c.bold}╚══════════════════════════════════════════════════════════════╝${c.reset}`,
+  );
+  console.log("");
+  console.log(`${c.dim}State directory: ${config.stateDir}${c.reset}`);
+  console.log(`${c.dim}Press Ctrl+C to stop${c.reset}`);
+  console.log("");
+
+  // Write a compact plain-text summary to the log file.
+  const summary = [
+    `${stackName} — started`,
+    `  Ingress:         http://localhost:${config.ingressPort}/`,
+    ...(config.launchFrontend
+      ? [`  Main UI:         http://localhost:${config.ingressPort}/`]
+      : []),
+    ...(config.launchAutomation
+      ? [
+          `  API Docs:        http://localhost:${config.ingressPort}/api/automation/docs`,
+        ]
+      : []),
+    `  State directory: ${config.stateDir}`,
+  ];
+  fileLog("info", summary.join("\n"));
+}
+
+async function main(options = {}) {
+  const {
+    bannerTitle = "Agent Canvas + Automation Development Stack",
+    startAgentServer: startAgentServerOverride,
+    extraPrereqs,
+    viteWorkingDir,
+    // Path used as `AUTOMATION_WORKSPACE_BASE` by the automation backend.
+    // Defaults to a host-side path under config.stateDir.
+    automationWorkspaceBase,
+    // Host used in `AUTOMATION_BASE_URL` (the URL the automation sandbox
+    // uses to call back into the automation backend). Defaults to `localhost`.
+    automationApiHost,
+    // Value exported as `AUTOMATION_SANDBOX_AGENT_SERVER_URL` to the
+    // automation backend. This is the URL the in-sandbox bash chain uses
+    // to reach the agent-server. When unset the backend falls back to
+    // AUTOMATION_AGENT_SERVER_URL.
+    sandboxAgentServerUrl,
+    staticMode: staticModeOverride,
+    defaultStaticMode = false,
+    buildStaticFrontend,
+    staticDir: staticDirOverride,
+    // Hostname the agent uses to reach services running on the host.
+    agentHostAlias = "localhost",
+    // Human-readable label for the dev mode, surfaced in the agent's
+    // <RUNTIME_SERVICES> system-prompt block.
+    mode = "dev:automation",
+    // When true, enable public mode (require LOCAL_BACKEND_API_KEY,
+    // don't bake session key into frontend).
+    isPublic: isPublicOverride,
+    // When true, skip the npm prerequisite check. Used by the Electron desktop
+    // launcher where npm is not needed at runtime in static mode.
+    skipNpmCheck = false,
+    // How long to wait for the agent-server's `/server_info` to return 200
+    // before continuing. Defaults to 60 s, which is fine for warm-cache dev
+    // workflows. The Electron desktop launcher bumps this to several minutes
+    // because first-launch on a fresh machine runs `uvx` to download Python
+    // and install `openhands-agent-server` from PyPI, which can take much
+    // longer than 60 s on a slow network.
+    agentServerReadyTimeoutMs = 60_000,
+    // Optional `(name, line, level)` callback that receives every service log
+    // line (stdout, stderr, and lifecycle events) emitted by any spawned
+    // backend process. Used by the Electron loading screen to surface uvx
+    // download / install progress to the user. `level` is one of
+    // "stdout" | "stderr" | "info" | "warn" | "error".
+    onServiceLog,
+  } = options;
+
+  // Install the listener early so log lines emitted before the first
+  // `spawnService` call (e.g. by future setup steps) are also captured.
+  setServiceLogListener(onServiceLog);
+
+  const args = parseArgs();
+
+  // Allow options to override CLI args for public mode
+  if (isPublicOverride != null) {
+    args.public = isPublicOverride;
+  }
+
+  // Allow options to override CLI args (for bin/agent-canvas.mjs)
+  const useStaticMode =
+    staticModeOverride ??
+    (args.dynamic ? false : args.static || defaultStaticMode);
+  const staticDir =
+    staticDirOverride ?? args.staticDir ?? join(projectRoot, "build");
+
+  const modeLabel = useStaticMode && !args.backendOnly ? "(Static)" : "";
+  const titleWithMode = modeLabel ? `${bannerTitle} ${modeLabel}` : bannerTitle;
+
+  console.log("");
+  console.log(`${c.cyan}${c.bold}${titleWithMode}${c.reset}`);
+  console.log("");
+  fileLog("info", titleWithMode);
+
+  // Setup phase
+  checkPrerequisites({
+    checkUvx: !args.frontendOnly,
+    // Static-mode + backend-only has no frontend to build, so npm is not
+    // required — unless the caller provides a custom buildStaticFrontend hook.
+    // The Electron desktop launcher passes `skipNpmCheck: true` because the
+    // packaged binary serves a pre-built static frontend and never invokes
+    // npm at runtime, so we suppress the check unconditionally there.
+    checkNpm:
+      !skipNpmCheck &&
+      ((!useStaticMode && !args.backendOnly) ||
+        typeof buildStaticFrontend === "function"),
+    checkFrontendDependencies:
+      (!useStaticMode && !args.backendOnly) ||
+      typeof buildStaticFrontend === "function",
+  });
+
+  // Fail fast on an obviously bad OH_AGENT_SERVER_LOCAL_PATH so we don't waste
+  // time allocating ports / generating keys / launching uvx with a path that
+  // would only produce a cryptic build error. Mirrors dev-safe.mjs and
+  // dev-extra-backend.mjs.
+  if (!args.frontendOnly && process.env.OH_AGENT_SERVER_LOCAL_PATH) {
+    try {
+      validateLocalAgentServerPath(process.env.OH_AGENT_SERVER_LOCAL_PATH);
+    } catch (error) {
+      logError(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  }
+
+  // Same for the automation checkout -- skipped when --automation-git-ref was
+  // passed, since buildConfig drops the env var in favor of the explicit flag.
+  if (
+    !args.frontendOnly &&
+    !args.automationGitRef &&
+    process.env.OH_AUTOMATION_LOCAL_PATH
+  ) {
+    try {
+      validateLocalAutomationPath(process.env.OH_AUTOMATION_LOCAL_PATH);
+    } catch (error) {
+      logError(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
+  }
+
+  // Build config with dynamic port allocation
+  const config = await buildConfig(args);
+  if (viteWorkingDir) config.viteWorkingDir = viteWorkingDir;
+  if (automationWorkspaceBase) {
+    config.automationWorkspaceBase = automationWorkspaceBase;
+  }
+  if (automationApiHost) {
+    config.automationApiHost = automationApiHost;
+  }
+  if (sandboxAgentServerUrl) {
+    config.sandboxAgentServerUrl = sandboxAgentServerUrl;
+  }
+  // Stamp the dev-mode label, host alias, and frontend kind on the config
+  // so downstream helpers (Vite spawn, static build) can produce a
+  // runtime-services info object describing what the agent can reach.
+  config.mode = mode;
+  config.agentHostAlias = agentHostAlias;
+  config.frontendKind = useStaticMode ? "static" : "vite";
+  ensureDirectories(config);
+  if (typeof extraPrereqs === "function") {
+    extraPrereqs(config);
+  }
+
+  if (
+    config.launchFrontend &&
+    useStaticMode &&
+    typeof buildStaticFrontend === "function"
+  ) {
+    buildStaticFrontend(config, args);
+  }
+
+  // In static mode, verify build exists after any launcher-managed build.
+  if (config.launchFrontend && useStaticMode && !existsSync(staticDir)) {
+    logError(`Static directory not found: ${staticDir}`);
+    logError(`Run 'npm run build' first to create the static files.`);
+    process.exit(1);
+  }
+
+  // Start services phase
+  logStep("2/2", "Starting services...");
+
+  let agentServerReady = false;
+
+  // 1. Start agent-server first (automation depends on it).
+  //
+  // Readiness timeout defaults to 60 s, which is fine for `npm run dev` against
+  // a warm uvx cache. The Electron desktop launcher overrides this via the
+  // `agentServerReadyTimeoutMs` option because first-launch on a fresh machine
+  // runs `uvx` to download Python + install `openhands-agent-server` from PyPI,
+  // which can take several minutes. Dropping the user into a half-booted UI
+  // before that completes triggers axios "Request timeout" popups on the first
+  // SPA fetch that hits an unbound port 18000.
+  if (config.launchAgentServer) {
+    const agentServerStarter = startAgentServerOverride ?? startAgentServer;
+    agentServerStarter(config);
+
+    agentServerReady = await waitForService(
+      "agent-server",
+      `${getAgentServerBaseUrl(config)}/server_info`,
+      agentServerReadyTimeoutMs,
+    );
+  }
+
+  // 2. Seed automation API key into agent-server secrets
+  // This makes the key available to agents during conversations
+  // Note: seedAutomationSecret has its own retry logic if server is still warming up
+  if (config.launchAutomation && agentServerReady) {
+    await seedAutomationSecret(config);
+  } else if (config.launchAutomation) {
+    logService(
+      "secrets",
+      "Skipping secret seeding - agent-server not ready",
+      c.yellow,
+    );
+  }
+
+  // 3. Start automation backend
+  if (config.launchAutomation) {
+    startAutomationBackend(config);
+  }
+
+  // 4. Start frontend server (Vite dev server OR static server)
+  if (config.launchFrontend) {
+    if (useStaticMode) {
+      startStaticFrontend(config, staticDir);
+    } else {
+      startVite(config);
+    }
+  }
+
+  // 5. Wait for services to be ready
+  await delay(2000);
+
+  // 6. Start ingress proxy (routes traffic only to running services)
+  startIngress(config);
+
+  // Wait for ingress to start
+  await delay(1000);
+
+  printBanner(config);
+
+  // Return the resolved config + readiness signal so embedded launchers can
+  // (a) build URLs from the actual allocated ports and (b) decide whether to
+  // show an error to the user when the agent-server never came up.
+  return { config, agentServerReady };
+}
+
+function startStaticFrontend(config, staticDir) {
+  logService("static", `Starting on port ${config.vitePort}...`, c.magenta);
+  logService("static", `Serving from: ${staticDir}`, c.dim);
+
+  // Build the runtime-services info JSON so static-server can append it to
+  // /server_info. The static-server also injects the old window global for
+  // compatibility with previously built frontend bundles.
+  const runtimeServicesInfo = config.launchAgentServer
+    ? JSON.stringify(buildAutomationRuntimeServicesInfo(config))
+    : null;
+
+  const staticServerScript = join(projectRoot, "scripts", "static-server.mjs");
+  spawnService(
+    "static",
+    "node",
+    [
+      staticServerScript,
+      "--dir",
+      staticDir,
+      "--port",
+      String(config.vitePort),
+      ...(process.env.VITE_BASE_PATH
+        ? ["--base-path", process.env.VITE_BASE_PATH]
+        : []),
+      // In local mode, inject the API key so the pre-built frontend can
+      // authenticate transparently. In public mode, pass --auth-required
+      // so the frontend shows the API key entry screen instead.
+      ...(config.launchAgentServer && !config.isPublic && config.sessionApiKey
+        ? ["--session-api-key", config.sessionApiKey]
+        : []),
+      ...(config.launchAgentServer && config.isPublic
+        ? ["--auth-required"]
+        : []),
+      // Inject runtime-services info so the agent knows what's reachable.
+      ...(runtimeServicesInfo
+        ? ["--runtime-services-info", runtimeServicesInfo]
+        : []),
+      // Proxy routes only to services that this launch mode started.
+      ...buildRouteArgs(getLocalServiceRoutes(config)),
+      // Only the static server injects into the document, so only it can tell
+      // the frontend this origin serves the editor. The ingress routes the same
+      // prefix but proxies the HTML through untouched.
+      ...getVSCodeAdvertiseArgs(config),
+      ...getNoReferrerPrefixArgs(config),
+      // Reject known API prefixes that have no backend — returns 503
+      // instead of SPA-fallbacking to index.html.
+      ...buildRejectPrefixArgs(getRejectPrefixes(config)),
+    ],
+    {
+      cwd: config.canvasPath,
+      color: c.magenta,
+    },
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Exports for testing
+// ═══════════════════════════════════════════════════════════════════════════
+
+export {
+  buildAgentServerAutomationEnv,
+  buildAutomationCommand,
+  buildAutomationTelemetryEnv,
+  buildConfig,
+  buildRouteArgs,
+  buildViteBackendEnv,
+  getAgentServerBaseUrl,
+  getFrontendBackend,
+  getLocalServiceRoutes,
+  getNoReferrerPrefixArgs,
+  getRejectPrefixes,
+  getVSCodeAdvertiseArgs,
+  main,
+  registerShutdownHook,
+  spawnService,
+  commandExists,
+  validateLocalAutomationPath,
+  logService,
+  logStep,
+  logSuccess,
+  logError,
+  c,
+  DEFAULT_AUTOMATION_REPO,
+  DEFAULT_AUTOMATION_PACKAGE,
+  DEFAULT_AUTOMATION_VERSION,
+  DEFAULT_AUTOMATION_SDK_VERSION,
+  DEFAULT_BACKEND_PORT,
+  DEFAULT_AUTOMATION_PORT,
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Main entry point (only when run directly, not when imported)
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Check if this module is the main entry point
+const isMainModule =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isMainModule) {
+  main().catch((err) => {
+    logError(`Fatal error: ${err.message}`);
+    if (err.stack) {
+      console.error(c.dim + err.stack + c.reset);
+      fileLog("error", err.stack);
+    }
+    process.exit(1);
+  });
+}

scripts/docker-build.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Local Docker build helper.
+ *
+ * Reads version pins from config/defaults.json and invokes `docker build`
+ * with the correct --build-arg values so developers never need to remember
+ * (or hardcode) version strings.
+ *
+ * Usage:
+ *   node scripts/docker-build.mjs                      # defaults
+ *   node scripts/docker-build.mjs --tag my-tag          # custom tag
+ *   node scripts/docker-build.mjs -- --no-cache         # extra docker args
+ */
+import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..");
+
+const config = JSON.parse(
+  readFileSync(join(projectRoot, "config", "defaults.json"), "utf-8"),
+);
+
+const agentServerImage = `${config.images.agentServer}:${config.versions.agentServer}-python`;
+const automationVersion = config.versions.automation;
+const canvasBasePath = config.paths.canvasBasePath;
+
+// Parse CLI: --tag <name> and everything after -- is passed to docker build
+let tag = "agent-canvas:local";
+const extraArgs = [];
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === "--tag" && i + 1 < args.length) {
+    tag = args[++i];
+  } else if (args[i] === "--") {
+    extraArgs.push(...args.slice(i + 1));
+    break;
+  } else {
+    extraArgs.push(args[i]);
+  }
+}
+
+const cmd = [
+  "docker",
+  "build",
+  "-f",
+  "docker/Dockerfile",
+  "--build-arg",
+  `AGENT_SERVER_IMAGE=${agentServerImage}`,
+  "--build-arg",
+  `AUTOMATION_VERSION=${automationVersion}`,
+  "--build-arg",
+  `VITE_BASE_PATH=${canvasBasePath}`,
+  "-t",
+  tag,
+  ...extraArgs,
+  ".",
+];
+
+console.log(`Agent Server image      : ${agentServerImage}`);
+console.log(`Automation version      : ${automationVersion}`);
+console.log(`Canvas base path        : ${canvasBasePath}`);
+console.log(`Tag                     : ${tag}`);
+console.log(`\n$ ${cmd.join(" ")}\n`);
+
+try {
+  execFileSync(cmd[0], cmd.slice(1), {
+    cwd: projectRoot,
+    stdio: "inherit",
+  });
+} catch (err) {
+  process.exit(err.status || 1);
+}

scripts/download-node.mjs

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+/**
+ * Download the official Node.js distribution for the current platform into
+ * resources/node/, so electron-builder can bundle it as an extraResource.
+ *
+ * The packaged Electron desktop app uses this bundled Node to provide
+ * `node`, `npm`, and `npx` to spawned subprocesses — most importantly the
+ * stdio MCP servers in the marketplace (Slack, GitHub, Figma, etc.) whose
+ * commands start with `npx -y <package>`.
+ *
+ * Why bundle Node instead of using Electron-as-Node (ELECTRON_RUN_AS_NODE=1)?
+ *
+ *   We tried that first. Electron-as-Node works fine for our backend
+ *   helper scripts (static-server.mjs, ingress.mjs) which mostly do
+ *   networking, but it is **not** reliable for stdio JSON-RPC servers.
+ *   When npx-cli.js (running under Electron-as-Node) spawned the MCP
+ *   server, the child's stdin pipe semantics differed from vanilla Node
+ *   on macOS (the parent is a windowed Electron process, not a clean
+ *   command-line Node binary) — the server appeared to start, then
+ *   immediately exited with "McpError: Connection closed" before the
+ *   first JSON-RPC handshake message could land. Bundling the real
+ *   Node binary sidesteps all of that.
+ *
+ * The downloaded Node.js distribution already includes npm and npx at
+ * `bin/npm` / `bin/npx` (POSIX) or `npm.cmd` / `npx.cmd` (Windows), so we
+ * do **not** need a separate npm download (this script supersedes the
+ * earlier download-npm.mjs).
+ *
+ * Usage:
+ *   node scripts/download-node.mjs           # uses NODE_BUNDLE_VERSION below
+ *   NODE_VERSION=22.10.0 node scripts/download-node.mjs
+ *
+ * Output (per platform):
+ *   POSIX:   resources/node/bin/{node,npm,npx} + resources/node/lib/node_modules/npm/...
+ *   Windows: resources/node/{node.exe,npm.cmd,npx.cmd} + resources/node/node_modules/npm/...
+ */
+
+import {
+  chmodSync,
+  createWriteStream,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import { get } from "node:https";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..");
+const outDir = join(projectRoot, "resources", "node");
+
+// Pinned Node version. Electron 42 ships Node 22, so we bundle a 22.x
+// LTS release to match the embedded runtime's ABI/native-module surface.
+// We intentionally use 22.12.0 — the repo's own support floor
+// (package.json engines.node >=22.12.0, volta 22.12.0) — rather than
+// Electron 42.3.2's exact embedded Node patch level: the bundled binary
+// runs this repo's launcher scripts, and native modules only need ABI
+// parity (NODE_MODULE_VERSION 127, shared by all 22.x builds).
+// Override at build time with NODE_VERSION=… (e.g. to test against a
+// newer release). Major version >=22 only; engines.node in npm 10.x
+// requires ^18.17.0 || >=20.5.0.
+const NODE_BUNDLE_VERSION = "22.12.0";
+
+// ── Platform detection ───────────────────────────────────────────────────────
+
+const PLATFORM = process.platform; // 'darwin' | 'linux' | 'win32'
+const ARCH = process.arch; // 'x64' | 'arm64' | 'ia32'
+
+/**
+ * Map (platform, arch) → Node's published distribution name.
+ * Names come straight from https://nodejs.org/dist/<version>/.
+ *
+ *   macOS arm64  → node-v<ver>-darwin-arm64.tar.gz
+ *   macOS x64    → node-v<ver>-darwin-x64.tar.gz
+ *   linux x64    → node-v<ver>-linux-x64.tar.gz
+ *   linux arm64  → node-v<ver>-linux-arm64.tar.gz
+ *   win32 x64    → node-v<ver>-win-x64.zip
+ *   win32 arm64  → node-v<ver>-win-arm64.zip
+ */
+function getPlatformSpec(version) {
+  const base = `node-v${version}`;
+  if (PLATFORM === "darwin") {
+    const arch = ARCH === "arm64" ? "arm64" : "x64";
+    return { name: `${base}-darwin-${arch}`, ext: "tar.gz" };
+  }
+  if (PLATFORM === "linux") {
+    const arch = ARCH === "arm64" ? "arm64" : "x64";
+    return { name: `${base}-linux-${arch}`, ext: "tar.gz" };
+  }
+  if (PLATFORM === "win32") {
+    const arch = ARCH === "arm64" ? "arm64" : "x64";
+    return { name: `${base}-win-${arch}`, ext: "zip" };
+  }
+  throw new Error(`Unsupported platform for Node download: ${PLATFORM}/${ARCH}`);
+}
+
+// ── Version resolution ───────────────────────────────────────────────────────
+
+function resolveVersion() {
+  const requested = process.env.NODE_VERSION?.replace(/^v/, "");
+  return requested || NODE_BUNDLE_VERSION;
+}
+
+// ── HTTP helpers ─────────────────────────────────────────────────────────────
+
+function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = createWriteStream(dest);
+    function doGet(u) {
+      get(u, { headers: { "User-Agent": "agent-canvas-build" } }, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          return doGet(res.headers.location);
+        }
+        if (res.statusCode !== 200) {
+          file.destroy();
+          return reject(new Error(`GET ${u} → HTTP ${res.statusCode}`));
+        }
+        res.pipe(file);
+        file.on("finish", () => file.close(resolve));
+        file.on("error", reject);
+        res.on("error", reject);
+      }).on("error", (err) => {
+        file.destroy();
+        reject(err);
+      });
+    }
+    doGet(url);
+  });
+}
+
+// ── Extraction ───────────────────────────────────────────────────────────────
+
+function extract(archivePath, targetDir, ext) {
+  // Both tar.gz and zip extract via system `tar`:
+  //   GNU/BSD tar (macOS/Linux) handles .tar.gz natively.
+  //   bsdtar (Windows 10+) handles both .tar.gz and .zip.
+  // --strip-components=1 drops the "node-vX.Y.Z-<platform>-<arch>/" top dir.
+  void ext; // archive content is identified by tar's own magic bytes
+  execFileSync(
+    "tar",
+    ["-xf", archivePath, "-C", targetDir, "--strip-components=1"],
+    { stdio: "inherit" },
+  );
+}
+
+function ensureExecutable(p) {
+  if (process.platform === "win32") return;
+  try {
+    chmodSync(p, 0o755);
+  } catch {}
+}
+
+// ── Layout verification ──────────────────────────────────────────────────────
+
+/**
+ * Confirm the extracted tree has the binaries we depend on.
+ * On Unix Node puts them in bin/; on Windows they live at the root.
+ */
+function verifyLayout() {
+  const isWin = PLATFORM === "win32";
+  const required = isWin
+    ? ["node.exe", "npm.cmd", "npx.cmd"]
+    : ["bin/node", "bin/npm", "bin/npx"];
+  for (const rel of required) {
+    const p = join(outDir, rel);
+    if (!existsSync(p)) {
+      throw new Error(
+        `Expected ${rel} in extracted Node distribution but it is missing ` +
+          `at ${p}. Did the tarball layout change?`,
+      );
+    }
+    ensureExecutable(p);
+  }
+
+  // npm/npx are wrapper scripts that invoke node against npm's JS entry
+  // points; verify the targets exist too so a packaged build doesn't ship
+  // a half-broken installation.
+  const npmCli = isWin
+    ? join(outDir, "node_modules", "npm", "bin", "npm-cli.js")
+    : join(outDir, "lib", "node_modules", "npm", "bin", "npm-cli.js");
+  if (!existsSync(npmCli)) {
+    throw new Error(`Bundled Node is missing npm-cli.js at ${npmCli}`);
+  }
+}
+
+// ── Pruning ──────────────────────────────────────────────────────────────────
+
+/**
+ * Drop pieces of the Node distribution that are only useful when building
+ * native modules from source or for human-readable documentation. Stripping
+ * these shrinks the bundled Node from ~170 MB → ~115 MB on Linux x64 (the
+ * Node binary itself is the bulk of what remains and can't be reduced).
+ *
+ * Kept intentionally:
+ *   bin/node, bin/npm, bin/npx      — runtime binaries / wrappers
+ *   lib/node_modules/{npm,corepack} — npm itself
+ *   LICENSE                         — required by the BSD-style Node license
+ */
+function pruneUnusedFiles() {
+  // IMPORTANT: every entry that points into a directory we delete must also
+  // delete any symlink/shim that targets into it, otherwise electron-builder
+  // hits ENOENT trying to stat() the dangling symlink while copying the
+  // extraResource into the .app bundle.
+  //
+  // Example: Node's POSIX tarball ships `bin/corepack` as a symlink to
+  // `../lib/node_modules/corepack/dist/corepack.js`. If we drop the corepack
+  // module under lib/ but leave the symlink, `electron-builder` fails with
+  //   ENOENT: ... Resources/node/bin/corepack
+  const candidates =
+    PLATFORM === "win32"
+      ? [
+          // Windows Node zip lays out npm directly under node_modules/, not lib/.
+          // Strip docs, headers, and node_modules/corepack (the npm runtime
+          // doesn't need corepack to run, and we don't ship yarn/pnpm).
+          "CHANGELOG.md",
+          "README.md",
+          "node_modules/corepack",
+          // Windows ships corepack as both a Bash wrapper and a cmd.exe wrapper
+          // at the distribution root; both proxy into node_modules/corepack.
+          "corepack",
+          "corepack.cmd",
+        ]
+      : [
+          // POSIX layout — keep bin/ and lib/node_modules/npm; drop the rest.
+          "include",
+          "share",
+          "CHANGELOG.md",
+          "README.md",
+          "lib/node_modules/corepack",
+          // Symlink in bin/ targets the corepack we just deleted.
+          "bin/corepack",
+        ];
+  for (const rel of candidates) {
+    const p = join(outDir, rel);
+    // `rmSync(force: true)` resolves the path through symlinks, so once the
+    // corepack target directory is deleted the now-dangling `bin/corepack`
+    // link reads as "already gone" and silently survives — the exact ENOENT
+    // trap failOnDanglingSymlinks() exists to catch. Remove files/symlinks
+    // with `unlinkSync` (lstat semantics, works on dangling links) first and
+    // fall back to `rmSync` for directories.
+    try {
+      unlinkSync(p);
+    } catch {
+      try {
+        rmSync(p, { recursive: true, force: true });
+      } catch {
+        // best-effort
+      }
+    }
+  }
+}
+
+// ── Dangling-symlink check ───────────────────────────────────────────────────
+
+/**
+ * Walk the pruned tree and refuse to finish if any symlink points at a path
+ * that no longer exists. electron-builder calls `stat()` (which follows
+ * symlinks) on every entry it copies into the .app bundle, so a single
+ * dangling symlink blows up the whole `build:desktop` step with a confusing
+ * ENOENT — fail at download time instead, with a message that says which
+ * pruned directory the symlink was reaching into.
+ */
+function failOnDanglingSymlinks() {
+  const broken = [];
+  const stack = [outDir];
+  while (stack.length) {
+    const next = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(next, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const p = join(next, entry.name);
+      if (entry.isSymbolicLink()) {
+        try {
+          // statSync follows the link; if the target is gone this throws.
+          statSync(p);
+        } catch {
+          let target = "<unreadable>";
+          try {
+            if (lstatSync(p).isSymbolicLink()) target = readlinkSync(p);
+          } catch {
+            // ignore — best-effort labelling
+          }
+          broken.push(`${p} → ${target}`);
+        }
+      } else if (entry.isDirectory()) {
+        stack.push(p);
+      }
+    }
+  }
+  if (broken.length) {
+    console.error(
+      "[download-node] Dangling symlinks remain after pruning — these would " +
+        "crash electron-builder later with ENOENT. Add the dangling symlink " +
+        "(or its target) to pruneUnusedFiles() in this script:",
+    );
+    for (const entry of broken) console.error("  •", entry);
+    throw new Error(`${broken.length} dangling symlink(s) in resources/node/`);
+  }
+}
+
+// ── Size report ──────────────────────────────────────────────────────────────
+
+function dirSizeBytes(dir) {
+  let total = 0;
+  const stack = [dir];
+  while (stack.length) {
+    const next = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(next, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const p = join(next, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(p);
+      } else {
+        try {
+          total += statSync(p).size;
+        } catch {}
+      }
+    }
+  }
+  return total;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const version = resolveVersion();
+  const spec = getPlatformSpec(version);
+  const archiveName = `${spec.name}.${spec.ext}`;
+  const url = `https://nodejs.org/dist/v${version}/${archiveName}`;
+  const tmpFile = join(tmpdir(), `node-download-${Date.now()}.${spec.ext}`);
+
+  console.log(
+    `[download-node] Downloading Node v${version} for ${PLATFORM}/${ARCH}`,
+  );
+  console.log(`[download-node] URL: ${url}`);
+
+  try {
+    // Clear any previous output so stale files (different Node version, or
+    // a stale resources/npm/ from the previous wrapper approach) don't
+    // linger in the bundle.
+    if (existsSync(outDir)) rmSync(outDir, { recursive: true, force: true });
+    mkdirSync(outDir, { recursive: true });
+
+    console.log(`[download-node] Downloading to ${tmpFile}`);
+    await downloadFile(url, tmpFile);
+    console.log(`[download-node] Extracting to ${outDir}`);
+    extract(tmpFile, outDir, spec.ext);
+
+    verifyLayout();
+    pruneUnusedFiles();
+    failOnDanglingSymlinks();
+
+    const mb = Math.round(dirSizeBytes(outDir) / (1024 * 1024));
+    console.log(`[download-node] ✓ Node v${version} ready at ${outDir} (~${mb} MB)`);
+  } finally {
+    try {
+      rmSync(tmpFile, { force: true });
+    } catch {}
+  }
+}
+
+main().catch((err) => {
+  console.error("[download-node] Error:", err.message);
+  process.exit(1);
+});