perf(desktop): eliminate workspace tab-switch freeze via WorkspaceKeepAlive

[Sandman-Ren]

Summary

• Eliminates the 2s+ full-window freeze that occurred on every workspace tab switch by keeping workspace content trees mounted (display:none when inactive) instead of unmounting and remounting them
• Fixes host-service SQLite migration failure in dev mode caused by incorrect migrations path resolution
• Includes Windows runtime patches, CI fixes, and upstream sync from prior commits on this branch

What was freezing and why

Every workspace navigation unmounted the previous workspace's React tree and mounted the new one. Each terminal pane synchronously ran createTerminalInstance() on mount:

per pane (~200–400ms each):
  new Terminal()          — XTerm constructor
  xterm.open(container)   — WebGL canvas init + DOM attachment
  new LigaturesAddon()    — synchronous font measurement  ← most expensive
  fitAddon.fit()          — layout reflow

With 2–4 panes open, this was 400ms–1600ms+ of synchronous main-thread work before the browser could paint — a complete UI freeze.

Fix: WorkspaceKeepAlive

WorkspaceKeepAlive in DashboardLayout keeps up to 5 recently-visited workspace content trees mounted simultaneously, toggling display:none on inactive ones. Terminals are never destroyed or recreated on switch — only the first visit to each workspace pays initialization cost.

Supporting changes:

• WorkspaceIdContext — React context so multiple simultaneously-mounted workspace trees each read their own workspace ID, not the URL's
• WorkspaceContent — extracted all heavy UI (terminals, hotkeys, dialogs) from page.tsx into a standalone component; hotkeys use { enabled: isActive } so hidden workspaces don't intercept shortcuts
• Route loader staleTime: 30_000 — warm navigations no longer block on an unnecessary IPC round-trip
• 10 workspace content files migrated from useParams() to useWorkspaceId() context hook

host-service migration fix

In dev mode, getMigrationsFolder() returned process.resourcesPath + "/resources/host-migrations" — which resolves to inside the Electron binary's resources directory, not the project source. Added existsSync guard so it falls through to the source-relative path when the production directory doesn't exist.

Documentation

Full investigation report at docs/issues/workspace-tab-switch-freeze.md.

Test plan

• Switch between workspaces with multiple terminal panes open — confirm no visible freeze
• First visit to a workspace still initializes terminals correctly
• Hotkeys (new tab, close workspace, presets) work in active workspace and do not fire in background workspaces
• Non-workspace routes (settings) render correctly while workspace trees are kept alive
• Restart dev server — confirm host-service initializes without migration errors

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adapts the Superset fork for Windows desktop builds and runtime behavior, while also refactoring agent/terminal integration (including Amp support) and aligning CI/workflows with the fork’s needs.

Changes:

• Adds Windows-focused desktop runtime/build updates (custom protocol loading, terminal-host IPC path handling, packaging adjustments, Windows UX tweaks).
• Refactors shared agent definitions/prompt launching (prompt transports, builtin agent registry, Amp preset/icon/docs) and extends MCP discovery.
• Cleans up upstream-only GitHub workflows and introduces fork-specific CI/upstream-sync automation.

Reviewed changes

Copilot reviewed 88 out of 91 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/postinstall.ts	New cross-platform postinstall for Bun (Windows-friendly).
README.md	Fork branding + Windows support/build notes.
packages/ui/src/assets/icons/preset-icons/index.ts	Registers Amp preset icon.
packages/ui/src/assets/icons/preset-icons/amp.svg	Adds Amp SVG asset.
packages/shared/src/builtin-terminal-agents.ts	Centralizes builtin terminal agents (includes Amp).
packages/shared/src/agent-prompt-launch.ts	Introduces prompt transport helpers (argv/stdin).
packages/shared/src/agent-definition.ts	New shared agent definition types + defaults.
packages/shared/src/agent-command.ts	Reworks agent commands to use builtin registry + transports.
packages/shared/src/agent-command.test.ts	Adds coverage for Amp prompt/file launch behavior.
packages/shared/src/agent-catalog.ts	Moves catalog to shared agent definitions; includes builtin agents.
packages/shared/package.json	Exposes new shared entrypoints (agent-definition / prompt-launch).
packages/mcp/src/tools/devices/start-agent-session/shared.ts	Improves supported-agents description generation.
packages/local-db/src/schema/zod.ts	Adds promptTransport + makes promptCommand optional for custom agents.
packages/chat/src/server/desktop/router/mcp-overview/mcp-overview.ts	Adds .amp/settings.json MCP server discovery.
packages/chat/src/server/desktop/router/mcp-overview/mcp-overview.test.ts	Tests .amp/settings.json discovery + precedence/fallback.
package.json	Switches postinstall to TS script (Bun-run).
bun.lock	Updates desktop version and switches to @lydell/node-pty.
apps/docs/content/docs/terminal-presets.mdx	Documents Amp terminal preset.
apps/docs/content/docs/mcp.mdx	Documents Amp MCP setup + config file support.
apps/docs/content/docs/agent-integration.mdx	Adds Amp to supported agents.
apps/desktop/vite/helpers.ts	Adds Windows HTML transform plugin; adjusts env define helper.
apps/desktop/test-setup.ts	Updates desktop test zod mocks for new agent fields.
apps/desktop/src/shared/utils/agent-settings.ts	Adds custom-agent CRUD helpers + prompt transports support.
apps/desktop/src/shared/utils/agent-settings.test.ts	Adds tests for Amp defaults + custom-agent helpers.
apps/desktop/src/shared/utils/agent-launch-request.test.ts	Verifies Amp launch commands use stdin transport.
apps/desktop/src/renderer/stores/tabs/terminal-callbacks.ts	Removes terminal restart callback plumbing.
apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/Terminal.tsx	Stops registering restart callback.
apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/useTerminalLifecycle.ts	Simplifies attach cancellation on unmount.
apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/useTerminalLifecycle.test.ts	Removes tests for deleted attach-unmount helper; keeps throttle tests.
apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/hooks/attach-unmount.ts	Removes attach keepalive helper.
apps/desktop/src/renderer/screens/main/components/WorkspaceView/ContentView/TabsContent/Terminal/helpers.ts	Windows WebGL refresh + Ctrl+C/Ctrl+V behavior tweaks.
apps/desktop/src/renderer/screens/main/components/WorkspaceSidebar/WorkspaceListItem/WorkspaceListItem.tsx	Shows Windows-friendly shortcut label formatting.
apps/desktop/src/renderer/routes/_authenticated/settings/agents/components/AgentsSettings/components/AgentCard/AgentCard.tsx	Splits builtin preset edits vs custom-agent edits via new mutations.
apps/desktop/src/renderer/routes/_authenticated/settings/agents/components/AgentsSettings/components/AgentCard/agent-card.utils.ts	Allows clearing promptCommand for custom terminal agents.
apps/desktop/src/renderer/routes/_authenticated/settings/agents/components/AgentsSettings/components/AgentCard/agent-card.utils.test.ts	Adds tests for builtin vs custom promptCommand clearing.
apps/desktop/src/renderer/routes/_authenticated/_dashboard/workspace/$workspaceId/hooks/useWorkspaceRunCommand.ts	Removes restart-callback path; always relaunches via launch helper.
apps/desktop/src/renderer/lib/terminal/launch-command.ts	Uses \r EOL for command execution to support Windows ConPTY.
apps/desktop/src/renderer/index.html	Adds media-src CSP allowance.
apps/desktop/src/main/windows/main.ts	Adds renderer console forwarding + Windows quit confirmation dialog.
apps/desktop/src/main/terminal-host/test-helpers.ts	Lets socket probe determine support on Windows.
apps/desktop/src/main/terminal-host/index.ts	Switches to centralized terminal-host paths + Windows socket checks.
apps/desktop/src/main/lib/terminal/env.ts	Expands allowed env vars needed for Windows toolchains.
apps/desktop/src/main/lib/terminal/dev-reset.ts	Avoids deleting socket file on Windows; uses path constants.
apps/desktop/src/main/lib/terminal-host/paths.ts	Adds named-pipe/socket path abstraction for terminal host (Windows).
apps/desktop/src/main/lib/terminal-host/client.ts	Uses shared terminal-host paths; adjusts Windows socket existence logic.
apps/desktop/src/main/lib/notifications/server.test.ts	Expands event mapping test coverage (Codex variants).
apps/desktop/src/main/lib/notifications/map-event-type.ts	Maps more Codex event type variants to Start/Stop/PermissionRequest.
apps/desktop/src/main/lib/notification-sound.ts	Plays notification sounds via renderer audio on Windows.
apps/desktop/src/main/lib/auto-updater.ts	Enables Windows auto-update feed URLs for this fork.
apps/desktop/src/main/lib/agent-setup/templates/notify-hook.template.sh	Improves Codex event-type parsing for notify hook.
apps/desktop/src/main/lib/agent-setup/shell-wrappers.ts	Adds cmd/powershell argument handling and typed managed binary iteration.
apps/desktop/src/main/lib/agent-setup/index.ts	Routes setup through new desktop-agent setup orchestration.
apps/desktop/src/main/lib/agent-setup/desktop-agent-setup.ts	New orchestrator for desktop agent setup actions.
apps/desktop/src/main/lib/agent-setup/desktop-agent-capabilities.ts	Declares setup targets/actions and managed binaries (includes Amp).
apps/desktop/src/main/lib/agent-setup/agent-wrappers.ts	Exports Amp wrapper creator.
apps/desktop/src/main/lib/agent-setup/agent-wrappers.test.ts	Adds Amp wrapper tests + expands Codex hooks merge tests.
apps/desktop/src/main/lib/agent-setup/agent-wrappers-common.ts	Sources managed binaries list from capabilities module.
apps/desktop/src/main/lib/agent-setup/agent-wrappers-claude-codex-opencode.ts	Broadens Codex native hooks registration + stale-hook cleanup.
apps/desktop/src/main/lib/agent-setup/agent-wrappers-amp.ts	New Amp passthrough wrapper script generation.
apps/desktop/src/main/index.ts	Registers superset-app:// protocol + Windows CORS handling + quit behavior changes.
apps/desktop/src/lib/window-loader.ts	Uses superset-app:// loading path on Windows prod builds.
apps/desktop/src/lib/trpc/routers/workspaces/utils/teardown.ts	Makes teardown shell selection + process-tree kill Windows-safe.
apps/desktop/src/lib/trpc/routers/settings/index.ts	Adds custom agent CRUD endpoints; uses default terminal preset list from shared.
apps/desktop/src/lib/trpc/routers/settings/agent-preset-router.utils.ts	Adds zod schemas + normalization for custom agent create/update.
apps/desktop/src/lib/trpc/routers/settings/agent-preset-router.utils.test.ts	Tests custom-agent schema validation + normalization.
apps/desktop/src/lib/trpc/routers/ringtone/index.ts	Plays/stops preview audio via renderer on Windows.
apps/desktop/src/lib/trpc/routers/external/helpers.ts	Adds Windows external app resolution (Program Files/Toolbox, etc.).
apps/desktop/src/lib/trpc/routers/changes/workers/git-task-runner.ts	Fixes direct dist/main execution worker script path lookup.
apps/desktop/scripts/rebuild-native-win.mjs	Adds Windows-only native module rebuild helper.
apps/desktop/scripts/copy-native-modules.ts	Improves Windows junction handling + safer npm tarball extraction + node-pty platform module materialization.
apps/desktop/runtime-dependencies.ts	Adds platform-gated runtime dependencies + extra asar unpack globs for node-pty.
apps/desktop/package.json	Switches node-pty to @lydell/node-pty; adds rebuild script.
apps/desktop/electron.vite.config.ts	Adds Windows env/process tweaks + strip-crossorigin plugin + banner tweak.
apps/desktop/electron-builder.ts	Points publishing to fork owner + disables npmRebuild on Windows.
apps/desktop/electron-builder.canary.ts	Points canary publishing to fork owner.
apps/desktop/docs/EXTERNAL_FILES.md	Documents Amp wrapper + updated Codex hooks strategy.
.gitignore	Ignores .amp/*.
.github/workflows/update-docs.yml	Removes upstream docs automation workflow.
.github/workflows/triage-issue.yml	Removes upstream issue triage automation workflow.
.github/workflows/sync-upstream.yml	Adds daily upstream sync PR workflow targeting dev.
.github/workflows/release-desktop.yml	Adds Windows artifact naming/copy logic.
.github/workflows/release-desktop-canary.yml	Removes upstream canary release workflow.
.github/workflows/generate-changelog.yml	Removes upstream changelog automation workflow.
.github/workflows/deploy-production.yml	Removes upstream production deploy workflow.
.github/workflows/cleanup-preview.yml	Removes upstream preview cleanup workflow.
.github/workflows/ci.yml	Adds dev branch push trigger + multi-OS build matrix + Windows long paths.
.github/workflows/build-desktop.yml	Adds dedicated Windows desktop build job + artifacts.
.github/prompts/update-docs.md	Removes upstream Claude docs prompt.
.github/prompts/triage-issue.md	Removes upstream triage prompt.
.github/prompts/generate-changelog.md	Removes upstream changelog prompt.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

defineEnv now uses value || fallback, which treats an explicit empty string as “unset”. That can unexpectedly drop intentionally-empty env values and can also cause this function to return undefined at runtime (since JSON.stringify(undefined) returns undefined), despite the string return type. Prefer value ?? fallback (or value ?? fallback ?? "") so empty strings are preserved and the return value is always a string literal for Vite’s define map.

[Copilot]

writeFileSync is imported but never used. This will fail lint/typecheck in strict setups; please remove the unused import (or use it if intended).

Suggested change

import { satisfies } from "semver";

[Copilot]

On Windows, SOCKET_PATH is currently \\.\pipe\superset-terminal-host-${PIPE_SUFFIX} and does not incorporate SUPERSET_DIR_NAME / workspace name (which is used elsewhere to isolate per-workspace state, e.g. .superset-<workspace>). This can cause terminal-host IPC collisions when running multiple Superset worktrees/workspaces on the same machine. Consider including a sanitized workspace identifier in the pipe name (and/or SUPERSET_HOME_DIR) to preserve the multi-worktree isolation guarantee.

[Copilot]

This module hardcodes SUPERSET_HOME_DIR = join(homedir(), SUPERSET_DIR_NAME) instead of honoring process.env.SUPERSET_HOME_DIR (used elsewhere, e.g. teardown logic and app-environment). If SUPERSET_HOME_DIR is overridden for portability/testing, terminal-host would still read/write token/pid/lock files under the default home path. Consider basing SUPERSET_HOME_DIR on process.env.SUPERSET_HOME_DIR ?? join(homedir(), SUPERSET_DIR_NAME) for consistency.