From a35211425bfd570c35566f9e32addc11a5c18fcd Mon Sep 17 00:00:00 2001
From: Ehab Younes <ehab.alyounes@gmail.com>
Date: Wed, 30 Sep 2026 15:36:13 +0300
Subject: [PATCH] feat: dynamic parameter form for workspace updates

Updating a workspace whose template uses dynamic parameters now works like
the dashboard. The extension evaluates the new template version with the
current values, and opens a form only when they fail. If the build still
rejects the values, the form reopens with the server's reasons. Servers
before 2.24 lack the evaluate endpoint and keep the classic prompts.

The update prompts now show the new template version's message, and a
failed update shows the server's error detail instead of the HTTP status.

The form follows the VS Code settings editor layout and uses a new
ValidationMessage component in @repo/ui that matches VS Code's input
validation styles.
---
 CHANGELOG.md                                  |  15 ++
 packages/mocks/src/index.ts                   |   1 +
 packages/mocks/src/parameters.ts              |  51 ++++
 packages/shared/src/index.ts                  |   5 +
 packages/shared/src/workspaceUpdate/api.ts    |  21 ++
 .../shared/src/workspaceUpdate/parameters.ts  |  22 ++
 packages/shared/src/workspaceUpdate/types.ts  |  12 +
 packages/ui/src/components/Field/Field.css    |   7 +-
 .../ui/src/components/Field/Field.stories.tsx |   7 +-
 packages/ui/src/components/Field/Field.tsx    |   5 +-
 packages/ui/src/components/Select/Select.css  |   4 +
 .../ValidationMessage/ValidationMessage.css   |  30 +++
 .../ValidationMessage.stories.tsx             |  54 ++++
 .../ValidationMessage/ValidationMessage.tsx   |  29 ++
 packages/ui/src/components/text-control.css   |   4 +
 packages/ui/src/index.ts                      |   5 +
 packages/ui/src/tokens.css                    |  43 +++
 packages/workspace-update/package.json        |  31 +++
 packages/workspace-update/src/App.tsx         |  91 +++++++
 .../src/components/Diagnostics.tsx            |  40 +++
 .../src/components/ParameterField.tsx         | 250 ++++++++++++++++++
 .../WorkspaceUpdateForm.stories.tsx           | 140 ++++++++++
 .../src/components/WorkspaceUpdateForm.tsx    | 107 ++++++++
 packages/workspace-update/src/css.d.ts        |   1 +
 .../src/hooks/useDebouncedValue.ts            |  11 +
 .../src/hooks/useWorkspaceUpdateApi.ts        |   6 +
 packages/workspace-update/src/index.css       |  73 +++++
 packages/workspace-update/src/index.tsx       |  28 ++
 .../workspace-update/storybook.preview.ts     |   1 +
 packages/workspace-update/tsconfig.json       |  11 +
 packages/workspace-update/vite.config.ts      |   6 +
 pnpm-lock.yaml                                |  49 ++++
 src/api/dynamicParameters.ts                  | 187 +++++++++++++
 src/api/updateParameters.ts                   |  14 +-
 src/api/workspace.ts                          |  15 ++
 src/commands.ts                               |  13 +-
 src/container.ts                              |  10 +
 src/error/normalize.ts                        |  11 +
 src/featureSet.ts                             |   3 +
 src/remote/workspaceStateMachine.ts           |  67 ++++-
 src/webviews/coderPanel.ts                    |  63 +++++
 src/webviews/resultPanel.ts                   |  70 +----
 .../workspaceUpdatePanelFactory.ts            |  60 +++++
 test/mocks/testHelpers.ts                     |  28 ++
 test/tsconfig.json                            |   3 +-
 test/unit/api/dynamicParameters.test.ts       | 155 +++++++++++
 test/unit/api/workspace.test.ts               |   1 +
 test/unit/commands.updateWorkspace.test.ts    |  24 ++
 test/unit/featureSet.test.ts                  |  11 +
 .../unit/remote/workspaceStateMachine.test.ts | 113 +++++++-
 .../webviews/tasks/tasksPanelProvider.test.ts |  26 +-
 .../workspaceUpdatePanelFactory.test.ts       |  85 ++++++
 .../webview/ui/components/components.test.tsx |  15 ++
 test/webview/workspace-update/App.test.tsx    | 168 ++++++++++++
 vitest.config.mts                             |   4 +
 55 files changed, 2194 insertions(+), 112 deletions(-)
 create mode 100644 packages/mocks/src/parameters.ts
 create mode 100644 packages/shared/src/workspaceUpdate/api.ts
 create mode 100644 packages/shared/src/workspaceUpdate/parameters.ts
 create mode 100644 packages/shared/src/workspaceUpdate/types.ts
 create mode 100644 packages/ui/src/components/ValidationMessage/ValidationMessage.css
 create mode 100644 packages/ui/src/components/ValidationMessage/ValidationMessage.stories.tsx
 create mode 100644 packages/ui/src/components/ValidationMessage/ValidationMessage.tsx
 create mode 100644 packages/workspace-update/package.json
 create mode 100644 packages/workspace-update/src/App.tsx
 create mode 100644 packages/workspace-update/src/components/Diagnostics.tsx
 create mode 100644 packages/workspace-update/src/components/ParameterField.tsx
 create mode 100644 packages/workspace-update/src/components/WorkspaceUpdateForm.stories.tsx
 create mode 100644 packages/workspace-update/src/components/WorkspaceUpdateForm.tsx
 create mode 100644 packages/workspace-update/src/css.d.ts
 create mode 100644 packages/workspace-update/src/hooks/useDebouncedValue.ts
 create mode 100644 packages/workspace-update/src/hooks/useWorkspaceUpdateApi.ts
 create mode 100644 packages/workspace-update/src/index.css
 create mode 100644 packages/workspace-update/src/index.tsx
 create mode 100644 packages/workspace-update/storybook.preview.ts
 create mode 100644 packages/workspace-update/tsconfig.json
 create mode 100644 packages/workspace-update/vite.config.ts
 create mode 100644 src/api/dynamicParameters.ts
 create mode 100644 src/webviews/coderPanel.ts
 create mode 100644 src/webviews/workspaceUpdate/workspaceUpdatePanelFactory.ts
 create mode 100644 test/unit/api/dynamicParameters.test.ts
 create mode 100644 test/unit/webviews/workspaceUpdate/workspaceUpdatePanelFactory.test.ts
 create mode 100644 test/webview/workspace-update/App.test.tsx

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c5963531f..396638e763 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,21 @@
      from published versions since it shows up in the VS Code extension changelog
      tab and is confusing to users. Add it back between releases if needed. -->
 
+## Unreleased
+
+### Added
+
+- Updating a workspace whose template uses dynamic parameters works like the
+  dashboard: the update goes ahead when the current values are still valid, and
+  a form asks only for missing or invalid ones. Servers before v2.24 keep the
+  classic prompts.
+- The update prompts show the new template version's message.
+
+### Fixed
+
+- A failed workspace update shows the server's error detail instead of the HTTP
+  status.
+
 ## [v1.17.2](https://github.com/coder/vscode-coder/releases/tag/v1.17.2) 2026-10-28
 
 ### Changed
diff --git a/packages/mocks/src/index.ts b/packages/mocks/src/index.ts
index bf3d4e3af4..f1b990c9ee 100644
--- a/packages/mocks/src/index.ts
+++ b/packages/mocks/src/index.ts
@@ -1,2 +1,3 @@
+export * from "./parameters";
 export * from "./tasks";
 export * from "./workspaces";
diff --git a/packages/mocks/src/parameters.ts b/packages/mocks/src/parameters.ts
new file mode 100644
index 0000000000..7c3e95c8d6
--- /dev/null
+++ b/packages/mocks/src/parameters.ts
@@ -0,0 +1,51 @@
+/**
+ * Test factories for dynamic template parameter types.
+ */
+
+import type {
+	FriendlyDiagnostic,
+	PreviewParameter,
+	PreviewParameterOption,
+} from "coder/site/src/api/typesGenerated";
+
+/** Create a mutable, optional string PreviewParameter with no diagnostics. */
+export function previewParameter(
+	overrides: Partial<PreviewParameter> = {},
+): PreviewParameter {
+	return {
+		name: "region",
+		display_name: "",
+		description: "",
+		type: "string",
+		form_type: "input",
+		styling: {},
+		mutable: true,
+		default_value: { valid: true, value: "" },
+		value: { valid: true, value: "" },
+		icon: "",
+		options: [],
+		validations: [],
+		required: false,
+		order: 0,
+		ephemeral: false,
+		diagnostics: [],
+		...overrides,
+	};
+}
+
+/** Create a PreviewParameterOption whose name defaults to its value. */
+export function parameterOption(
+	value: string,
+	name = value,
+	description = "",
+): PreviewParameterOption {
+	return { name, description, value: { valid: true, value }, icon: "" };
+}
+
+/** Create a FriendlyDiagnostic, an error unless `severity` says otherwise. */
+export function diagnostic(
+	summary: string,
+	severity: FriendlyDiagnostic["severity"] = "error",
+): FriendlyDiagnostic {
+	return { severity, summary, detail: "", extra: { code: "" } };
+}
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 711137cb6b..21c41e2ff8 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -33,3 +33,8 @@ export type {
 // Workspaces types and API
 export * from "./workspaces/types";
 export { WorkspacesApi } from "./workspaces/api";
+
+// Workspace Update types and API
+export * from "./workspaceUpdate/types";
+export * from "./workspaceUpdate/parameters";
+export { WorkspaceUpdateApi } from "./workspaceUpdate/api";
diff --git a/packages/shared/src/workspaceUpdate/api.ts b/packages/shared/src/workspaceUpdate/api.ts
new file mode 100644
index 0000000000..b425add727
--- /dev/null
+++ b/packages/shared/src/workspaceUpdate/api.ts
@@ -0,0 +1,21 @@
+/**
+ * Workspace Update API - Type-safe message definitions for the parameter
+ * form shown when updating a workspace to the latest template version.
+ */
+
+import { defineCommand, defineRequest } from "../ipc/protocol";
+
+import type { DynamicParametersResponse } from "coder/site/src/api/typesGenerated";
+
+import type { ParameterValues, WorkspaceUpdateInit } from "./types";
+
+export const WorkspaceUpdateApi = {
+	// Requests
+	init: defineRequest<void, WorkspaceUpdateInit>("workspaceUpdate/init"),
+	evaluate: defineRequest<ParameterValues, DynamicParametersResponse>(
+		"workspaceUpdate/evaluate",
+	),
+	// Commands
+	submit: defineCommand<ParameterValues>("workspaceUpdate/submit"),
+	cancel: defineCommand<void>("workspaceUpdate/cancel"),
+} as const;
diff --git a/packages/shared/src/workspaceUpdate/parameters.ts b/packages/shared/src/workspaceUpdate/parameters.ts
new file mode 100644
index 0000000000..1fd6d9f6aa
--- /dev/null
+++ b/packages/shared/src/workspaceUpdate/parameters.ts
@@ -0,0 +1,22 @@
+import type { DynamicParametersResponse } from "coder/site/src/api/typesGenerated";
+
+export function hasErrorDiagnostics({
+	parameters,
+	diagnostics,
+}: DynamicParametersResponse): boolean {
+	return [...diagnostics, ...parameters.flatMap((p) => p.diagnostics)].some(
+		(d) => d.severity === "error",
+	);
+}
+
+/** Multi-select values are stored as a JSON-encoded string array. */
+export function parseMultiSelectValue(raw: string): string[] | null {
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		return Array.isArray(parsed) && parsed.every((v) => typeof v === "string")
+			? parsed
+			: null;
+	} catch {
+		return null;
+	}
+}
diff --git a/packages/shared/src/workspaceUpdate/types.ts b/packages/shared/src/workspaceUpdate/types.ts
new file mode 100644
index 0000000000..3cb2c0341a
--- /dev/null
+++ b/packages/shared/src/workspaceUpdate/types.ts
@@ -0,0 +1,12 @@
+import type { DynamicParametersResponse } from "coder/site/src/api/typesGenerated";
+
+export type ParameterValues = Readonly<Record<string, string>>;
+
+export interface WorkspaceUpdateInit {
+	readonly workspaceName: string;
+	/** Omitted parameters use the server's value. */
+	readonly values: ParameterValues;
+	/** The server's evaluation of `values`. */
+	readonly evaluation: DynamicParametersResponse;
+	readonly restart: boolean;
+}
diff --git a/packages/ui/src/components/Field/Field.css b/packages/ui/src/components/Field/Field.css
index e2af3c4558..e1c15de747 100644
--- a/packages/ui/src/components/Field/Field.css
+++ b/packages/ui/src/components/Field/Field.css
@@ -4,15 +4,18 @@
 }
 
 .ui-field {
+	--ui-field-gap: 4px;
+
 	display: flex;
 	flex-direction: column;
-	gap: 4px;
+	gap: var(--ui-field-gap);
 }
 
 .ui-field__description {
 	color: var(--ui-description-foreground);
 }
 
+/* Attaches to the control above, like VS Code's input validation. */
 .ui-field__error {
-	color: var(--ui-error-foreground);
+	margin-top: calc(-1 * var(--ui-field-gap));
 }
diff --git a/packages/ui/src/components/Field/Field.stories.tsx b/packages/ui/src/components/Field/Field.stories.tsx
index 8037c606c6..4d4664bf2e 100644
--- a/packages/ui/src/components/Field/Field.stories.tsx
+++ b/packages/ui/src/components/Field/Field.stories.tsx
@@ -3,6 +3,7 @@ import { useId, useState } from "react";
 import { PIXEL_ALL_THEMES } from "#storybook";
 
 import { Input } from "../Input/Input";
+import { ValidationMessage } from "../ValidationMessage/ValidationMessage";
 
 import { Field } from "./Field";
 
@@ -30,7 +31,11 @@ const FieldStates = (): React.JSX.Element => {
 			<Field
 				label="CPU cores"
 				htmlFor={coresId}
-				error="Value must be between 1 and 16."
+				error={
+					<ValidationMessage severity="error">
+						Value must be between 1 and 16.
+					</ValidationMessage>
+				}
 				errorId={`${coresId}-error`}
 			>
 				<Input
diff --git a/packages/ui/src/components/Field/Field.tsx b/packages/ui/src/components/Field/Field.tsx
index c0c7cc055c..907a66b1d3 100644
--- a/packages/ui/src/components/Field/Field.tsx
+++ b/packages/ui/src/components/Field/Field.tsx
@@ -14,6 +14,7 @@ export interface FieldProps extends ComponentProps<"div"> {
 	description?: ReactNode;
 	/** ID for the description; associate it with the control via aria-describedby. */
 	descriptionId?: string;
+	/** Usually one or more `ValidationMessage`s. */
 	error?: ReactNode;
 	/** ID for the error; the consumer owns aria-describedby and aria-invalid. */
 	errorId?: string;
@@ -22,7 +23,7 @@ export interface FieldProps extends ComponentProps<"div"> {
 }
 
 /* Lays out a labelled control like a settings-editor entry: semibold label,
-   control, then muted description or error text. */
+   muted description, control, then validation messages flush below it. */
 export function Field({
 	label,
 	htmlFor,
@@ -37,12 +38,12 @@ export function Field({
 	return (
 		<div {...props} className={cx("ui-field", className)}>
 			{label !== undefined && <Label htmlFor={htmlFor}>{label}</Label>}
-			{children}
 			{description !== undefined && (
 				<div id={descriptionId} className="ui-field__description">
 					{description}
 				</div>
 			)}
+			{children}
 			{error !== undefined && (
 				<div id={errorId} className="ui-field__error">
 					{error}
diff --git a/packages/ui/src/components/Select/Select.css b/packages/ui/src/components/Select/Select.css
index 678b022bcf..98d80e7d9c 100644
--- a/packages/ui/src/components/Select/Select.css
+++ b/packages/ui/src/components/Select/Select.css
@@ -14,6 +14,10 @@
 	outline: 0;
 }
 
+.ui-select__trigger[aria-invalid="true"] {
+	border-color: var(--ui-message-error-border);
+}
+
 .ui-select__trigger:focus {
 	border-color: var(--ui-focus-border);
 }
diff --git a/packages/ui/src/components/ValidationMessage/ValidationMessage.css b/packages/ui/src/components/ValidationMessage/ValidationMessage.css
new file mode 100644
index 0000000000..a9fa5d30fe
--- /dev/null
+++ b/packages/ui/src/components/ValidationMessage/ValidationMessage.css
@@ -0,0 +1,30 @@
+/* Matches VS Code's .monaco-inputbox-message. */
+.ui-validation-message {
+	box-sizing: border-box;
+	margin-top: -1px;
+	padding: 0.4em;
+	color: var(--ui-validation-foreground);
+	background: var(--ui-validation-background);
+	border: 1px solid var(--ui-validation-border);
+	font-size: 12px;
+	line-height: 17px;
+	overflow-wrap: break-word;
+}
+
+.ui-validation-message--info {
+	--ui-validation-foreground: var(--ui-message-info-foreground);
+	--ui-validation-background: var(--ui-message-info-background);
+	--ui-validation-border: var(--ui-message-info-border);
+}
+
+.ui-validation-message--warning {
+	--ui-validation-foreground: var(--ui-message-warning-foreground);
+	--ui-validation-background: var(--ui-message-warning-background);
+	--ui-validation-border: var(--ui-message-warning-border);
+}
+
+.ui-validation-message--error {
+	--ui-validation-foreground: var(--ui-message-error-foreground);
+	--ui-validation-background: var(--ui-message-error-background);
+	--ui-validation-border: var(--ui-message-error-border);
+}
diff --git a/packages/ui/src/components/ValidationMessage/ValidationMessage.stories.tsx b/packages/ui/src/components/ValidationMessage/ValidationMessage.stories.tsx
new file mode 100644
index 0000000000..8cd514e581
--- /dev/null
+++ b/packages/ui/src/components/ValidationMessage/ValidationMessage.stories.tsx
@@ -0,0 +1,54 @@
+import { PIXEL_ALL_THEMES } from "#storybook";
+
+import { Input } from "../Input/Input";
+
+import {
+	ValidationMessage,
+	type ValidationSeverity,
+} from "./ValidationMessage";
+
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+const MESSAGES: ReadonlyArray<{
+	severity: ValidationSeverity;
+	value: string;
+	message: string;
+}> = [
+	{ severity: "info", value: "dev", message: "Names are case-sensitive." },
+	{
+		severity: "warning",
+		value: "4",
+		message: "Fewer than 8 cores may slow down builds.",
+	},
+	{
+		severity: "error",
+		value: "32",
+		message: "Value must be between 1 and 16.",
+	},
+];
+
+const Messages = (): React.JSX.Element => (
+	<div style={{ display: "grid", gap: "16px", width: "260px" }}>
+		{MESSAGES.map(({ severity, value, message }) => (
+			<div key={severity}>
+				<Input
+					aria-label={severity}
+					aria-invalid={severity === "error" || undefined}
+					value={value}
+					onChange={() => undefined}
+				/>
+				<ValidationMessage severity={severity}>{message}</ValidationMessage>
+			</div>
+		))}
+	</div>
+);
+
+const meta: Meta<typeof Messages> = {
+	title: "UI/ValidationMessage",
+	component: Messages,
+	parameters: { pixel: PIXEL_ALL_THEMES },
+};
+export default meta;
+type Story = StoryObj<typeof Messages>;
+
+export const Severities: Story = {};
diff --git a/packages/ui/src/components/ValidationMessage/ValidationMessage.tsx b/packages/ui/src/components/ValidationMessage/ValidationMessage.tsx
new file mode 100644
index 0000000000..ea5097bb80
--- /dev/null
+++ b/packages/ui/src/components/ValidationMessage/ValidationMessage.tsx
@@ -0,0 +1,29 @@
+import { type ComponentProps } from "react";
+
+import { cx } from "#cx";
+
+import "./ValidationMessage.css";
+
+export type ValidationSeverity = "info" | "warning" | "error";
+
+export interface ValidationMessageProps extends ComponentProps<"div"> {
+	severity: ValidationSeverity;
+}
+
+/** VS Code's input box validation message. */
+export function ValidationMessage({
+	severity,
+	className,
+	...props
+}: ValidationMessageProps): React.JSX.Element {
+	return (
+		<div
+			{...props}
+			className={cx(
+				"ui-validation-message",
+				`ui-validation-message--${severity}`,
+				className,
+			)}
+		/>
+	);
+}
diff --git a/packages/ui/src/components/text-control.css b/packages/ui/src/components/text-control.css
index e2ec7e3a30..d3bd84eaea 100644
--- a/packages/ui/src/components/text-control.css
+++ b/packages/ui/src/components/text-control.css
@@ -14,6 +14,10 @@
 	height: 26px;
 }
 
+.ui-text-control:is([aria-invalid="true"], :has(> [aria-invalid="true"])) {
+	border-color: var(--ui-message-error-border);
+}
+
 .ui-text-control:focus-within {
 	border-color: var(--ui-focus-border);
 }
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 507bc8a49d..4693d89da8 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -52,6 +52,11 @@ export {
 	type StatusPillTone,
 } from "./components/StatusPill/StatusPill";
 export { Textarea, type TextareaProps } from "./components/Textarea/Textarea";
+export {
+	ValidationMessage,
+	type ValidationMessageProps,
+	type ValidationSeverity,
+} from "./components/ValidationMessage/ValidationMessage";
 export type { CodiconName } from "./codicons";
 export {
 	ContextMenu,
diff --git a/packages/ui/src/tokens.css b/packages/ui/src/tokens.css
index 7a15db40ca..1caa381dca 100644
--- a/packages/ui/src/tokens.css
+++ b/packages/ui/src/tokens.css
@@ -29,6 +29,11 @@
 	);
 	--ui-description-foreground: var(--vscode-descriptionForeground);
 	--ui-border: var(--vscode-sideBar-border, transparent);
+	/* Divides sections in an editor tab, like the settings editor's headers */
+	--ui-separator: var(
+		--vscode-settings-headerBorder,
+		var(--vscode-panel-border, var(--ui-border))
+	);
 	--ui-link-foreground: var(--vscode-textLink-foreground);
 	--ui-focus-border: var(
 		--vscode-focusBorder,
@@ -276,6 +281,44 @@
 	/* Only defined by high contrast themes; transparent elsewhere */
 	--ui-contrast-border: var(--vscode-contrastBorder, transparent);
 
+	/* Validation and banner messages */
+	--ui-message-info-background: var(
+		--vscode-inputValidation-infoBackground,
+		transparent
+	);
+	--ui-message-info-border: var(
+		--vscode-inputValidation-infoBorder,
+		var(--ui-contrast-border)
+	);
+	--ui-message-info-foreground: var(
+		--vscode-inputValidation-infoForeground,
+		var(--ui-foreground)
+	);
+	--ui-message-warning-background: var(
+		--vscode-inputValidation-warningBackground,
+		transparent
+	);
+	--ui-message-warning-border: var(
+		--vscode-inputValidation-warningBorder,
+		var(--ui-contrast-border)
+	);
+	--ui-message-warning-foreground: var(
+		--vscode-inputValidation-warningForeground,
+		var(--ui-foreground)
+	);
+	--ui-message-error-background: var(
+		--vscode-inputValidation-errorBackground,
+		transparent
+	);
+	--ui-message-error-border: var(
+		--vscode-inputValidation-errorBorder,
+		var(--ui-contrast-border)
+	);
+	--ui-message-error-foreground: var(
+		--vscode-inputValidation-errorForeground,
+		var(--ui-foreground)
+	);
+
 	/* Portalled overlays; matches the native hover widget's stacking */
 	--ui-z-index-overlay: 40;
 }
diff --git a/packages/workspace-update/package.json b/packages/workspace-update/package.json
new file mode 100644
index 0000000000..40269ea104
--- /dev/null
+++ b/packages/workspace-update/package.json
@@ -0,0 +1,31 @@
+{
+	"name": "@repo/workspace-update",
+	"version": "1.0.0",
+	"description": "Coder workspace update parameter form webview",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build",
+		"dev": "vite build --watch",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@repo/shared": "workspace:*",
+		"@repo/ui": "workspace:*",
+		"@repo/webview-shared": "workspace:*",
+		"@tanstack/react-query": "catalog:",
+		"react": "catalog:",
+		"react-dom": "catalog:"
+	},
+	"devDependencies": {
+		"@repo/mocks": "workspace:*",
+		"@repo/storybook-utils": "workspace:*",
+		"@rolldown/plugin-babel": "catalog:",
+		"@types/react": "catalog:",
+		"@types/react-dom": "catalog:",
+		"@vitejs/plugin-react": "catalog:",
+		"babel-plugin-react-compiler": "catalog:",
+		"typescript": "catalog:",
+		"vite": "catalog:"
+	}
+}
diff --git a/packages/workspace-update/src/App.tsx b/packages/workspace-update/src/App.tsx
new file mode 100644
index 0000000000..3d26ba4e29
--- /dev/null
+++ b/packages/workspace-update/src/App.tsx
@@ -0,0 +1,91 @@
+import {
+	hasErrorDiagnostics,
+	type ParameterValues,
+	type WorkspaceUpdateInit,
+} from "@repo/shared";
+import { ErrorState, LoadingState } from "@repo/ui";
+import { useVsCodeState } from "@repo/webview-shared/react";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+
+import { WorkspaceUpdateForm } from "./components/WorkspaceUpdateForm";
+import { useDebouncedValue } from "./hooks/useDebouncedValue";
+import { useWorkspaceUpdateApi } from "./hooks/useWorkspaceUpdateApi";
+
+import type { PreviewParameter } from "coder/site/src/api/typesGenerated";
+
+/** Like the dashboard, only typing is debounced. */
+const TYPING_DEBOUNCE_MS = 500;
+const TYPED_FORM_TYPES: ReadonlySet<string> = new Set(["input", "textarea"]);
+
+const queryKeys = {
+	init: ["init"],
+	evaluate: (values: ParameterValues) => ["evaluate", values],
+};
+
+export default function App() {
+	const api = useWorkspaceUpdateApi();
+	const init = useQuery({
+		queryKey: queryKeys.init,
+		queryFn: () => api.init(),
+		staleTime: Infinity,
+	});
+
+	if (init.isPending) {
+		return <LoadingState label="Loading parameters" />;
+	}
+	if (init.isError) {
+		return (
+			<ErrorState
+				title="Could not load workspace parameters"
+				description={init.error.message}
+				onRetry={() => void init.refetch()}
+			/>
+		);
+	}
+	return <WorkspaceUpdate init={init.data} />;
+}
+
+function WorkspaceUpdate({ init }: { init: WorkspaceUpdateInit }) {
+	const api = useWorkspaceUpdateApi();
+	// Survives the panel being hidden.
+	const [values, setValues] = useVsCodeState<ParameterValues>(init.values);
+	const [debounceMs, setDebounceMs] = useState(0);
+	const inputs = useDebouncedValue(values, debounceMs);
+	const evaluation = useQuery({
+		queryKey: queryKeys.evaluate(inputs),
+		queryFn: () => api.evaluate(inputs),
+		initialData: inputs === init.values ? init.evaluation : undefined,
+		placeholderData: keepPreviousData,
+		// Same inputs on the same template version always evaluate the same.
+		staleTime: Infinity,
+	});
+	// Restored edits start from the initial evaluation until theirs arrives.
+	const data = evaluation.data ?? init.evaluation;
+
+	const onChange = (parameter: PreviewParameter, value: string) => {
+		setDebounceMs(
+			TYPED_FORM_TYPES.has(parameter.form_type) ? TYPING_DEBOUNCE_MS : 0,
+		);
+		setValues({ ...values, [parameter.name]: value });
+	};
+
+	return (
+		<WorkspaceUpdateForm
+			workspaceName={init.workspaceName}
+			restart={init.restart}
+			evaluation={data}
+			values={values}
+			evaluating={evaluation.isFetching}
+			error={evaluation.error?.message}
+			canSubmit={
+				inputs === values &&
+				!evaluation.isFetching &&
+				!evaluation.isError &&
+				!hasErrorDiagnostics(data)
+			}
+			onChange={onChange}
+			api={api}
+		/>
+	);
+}
diff --git a/packages/workspace-update/src/components/Diagnostics.tsx b/packages/workspace-update/src/components/Diagnostics.tsx
new file mode 100644
index 0000000000..17f6055468
--- /dev/null
+++ b/packages/workspace-update/src/components/Diagnostics.tsx
@@ -0,0 +1,40 @@
+import { ValidationMessage } from "@repo/ui";
+
+import type { FriendlyDiagnostic } from "coder/site/src/api/typesGenerated";
+
+function diagnosticText({ summary, detail }: FriendlyDiagnostic) {
+	return detail ? `${summary}: ${detail}` : summary;
+}
+
+/** Messages under a field, read through the control's `aria-describedby`. */
+export function FieldDiagnostics({
+	diagnostics,
+}: {
+	diagnostics: readonly FriendlyDiagnostic[];
+}) {
+	return diagnostics.map((diagnostic) => (
+		<ValidationMessage
+			key={`${diagnostic.summary}:${diagnostic.detail}`}
+			severity={diagnostic.severity}
+		>
+			{diagnosticText(diagnostic)}
+		</ValidationMessage>
+	));
+}
+
+/** Messages about the whole form, announced as they appear. */
+export function FormDiagnostics({
+	diagnostics,
+}: {
+	diagnostics: readonly FriendlyDiagnostic[];
+}) {
+	return diagnostics.map((diagnostic) => (
+		<ValidationMessage
+			key={`${diagnostic.summary}:${diagnostic.detail}`}
+			role={diagnostic.severity === "error" ? "alert" : "status"}
+			severity={diagnostic.severity}
+		>
+			{diagnosticText(diagnostic)}
+		</ValidationMessage>
+	));
+}
diff --git a/packages/workspace-update/src/components/ParameterField.tsx b/packages/workspace-update/src/components/ParameterField.tsx
new file mode 100644
index 0000000000..10867f70fb
--- /dev/null
+++ b/packages/workspace-update/src/components/ParameterField.tsx
@@ -0,0 +1,250 @@
+import { parseMultiSelectValue } from "@repo/shared";
+import {
+	Checkbox,
+	Field,
+	Input,
+	PasswordInput,
+	Select,
+	SelectContent,
+	SelectItem,
+	SelectTrigger,
+	SelectValue,
+	StatusPill,
+	Textarea,
+} from "@repo/ui";
+import { useId } from "react";
+
+import { FieldDiagnostics } from "./Diagnostics";
+
+import type {
+	FriendlyDiagnostic,
+	PreviewParameter,
+} from "coder/site/src/api/typesGenerated";
+
+interface ParameterFieldProps {
+	parameter: PreviewParameter;
+	value: string;
+	disabled: boolean;
+	onChange: (value: string) => void;
+}
+
+function ParameterLabel({
+	parameter,
+	label,
+	required,
+}: {
+	parameter: PreviewParameter;
+	label: string;
+	required: FriendlyDiagnostic | undefined;
+}) {
+	return (
+		<span className="parameter-label">
+			<span>
+				{label}
+				{parameter.required && (
+					<span className="parameter-label__required"> *</span>
+				)}
+			</span>
+			{!parameter.mutable && (
+				<StatusPill
+					tone="warning"
+					icon="alert"
+					title="Cannot change after the workspace is created."
+				>
+					Immutable
+				</StatusPill>
+			)}
+			{parameter.ephemeral && (
+				<StatusPill
+					tone="success"
+					icon="history"
+					title="Resets to the default on restart."
+				>
+					Ephemeral
+				</StatusPill>
+			)}
+			{required && (
+				<StatusPill tone="danger" title={required.summary}>
+					Required
+				</StatusPill>
+			)}
+		</span>
+	);
+}
+
+/** Like the dashboard's `DynamicParameter`. */
+export function ParameterField(props: ParameterFieldProps) {
+	const { parameter } = props;
+	const id = useId();
+	const label = parameter.display_name || parameter.name;
+	const required = parameter.diagnostics.find(
+		(d) => d.extra?.code === "required",
+	);
+	const diagnostics = parameter.diagnostics.filter((d) => d !== required);
+	const descriptionId = `${id}-description`;
+	const diagnosticsId = `${id}-diagnostics`;
+
+	return (
+		<Field
+			className="parameter-field"
+			label={
+				<ParameterLabel
+					parameter={parameter}
+					label={label}
+					required={required}
+				/>
+			}
+			htmlFor={id}
+			description={parameter.description || undefined}
+			descriptionId={descriptionId}
+			error={
+				diagnostics.length > 0 ? (
+					<FieldDiagnostics diagnostics={diagnostics} />
+				) : undefined
+			}
+			errorId={diagnosticsId}
+		>
+			<ParameterControl
+				{...props}
+				id={id}
+				label={label}
+				describedBy={
+					[
+						parameter.description && descriptionId,
+						diagnostics.length > 0 && diagnosticsId,
+					]
+						.filter(Boolean)
+						.join(" ") || undefined
+				}
+				invalid={parameter.diagnostics.some((d) => d.severity === "error")}
+			/>
+		</Field>
+	);
+}
+
+function ParameterControl({
+	parameter,
+	value,
+	disabled,
+	onChange,
+	id,
+	label,
+	describedBy,
+	invalid,
+}: ParameterFieldProps & {
+	id: string;
+	label: string;
+	describedBy: string | undefined;
+	invalid: boolean;
+}) {
+	const control = {
+		id,
+		disabled,
+		"aria-describedby": describedBy,
+		"aria-invalid": invalid || undefined,
+	};
+	const text = {
+		...control,
+		value,
+		onChange,
+		placeholder: parameter.styling.placeholder,
+	};
+	const options = parameter.options.map((option) => ({
+		value: option.value.value,
+		label: option.name || option.value.value,
+		description: option.description || undefined,
+	}));
+
+	switch (parameter.form_type) {
+		case "error":
+			return null;
+		case "checkbox":
+		case "switch":
+			return (
+				<Checkbox
+					{...control}
+					aria-label={parameter.styling.label ? undefined : label}
+					checked={value === "true"}
+					onChange={(checked) => onChange(String(checked))}
+				>
+					{parameter.styling.label}
+				</Checkbox>
+			);
+		case "dropdown":
+		case "radio":
+			return (
+				<Select
+					items={options}
+					value={value || null}
+					onValueChange={(next) => onChange(next ?? "")}
+					disabled={disabled}
+				>
+					<SelectTrigger {...control} aria-label={label}>
+						<SelectValue
+							placeholder={parameter.styling.placeholder || "Select option"}
+						/>
+					</SelectTrigger>
+					<SelectContent>
+						{options.map((option) => (
+							<SelectItem
+								key={option.value}
+								value={option.value}
+								description={option.description}
+							>
+								{option.label}
+							</SelectItem>
+						))}
+					</SelectContent>
+				</Select>
+			);
+		case "multi-select": {
+			const selected = parseMultiSelectValue(value) ?? [];
+			return (
+				<div role="group" aria-label={label} className="parameter-options">
+					{options.map((option) => (
+						<Checkbox
+							key={option.value}
+							disabled={disabled}
+							checked={selected.includes(option.value)}
+							onChange={(checked) =>
+								onChange(
+									JSON.stringify(
+										checked
+											? [...selected, option.value]
+											: selected.filter((v) => v !== option.value),
+									),
+								)
+							}
+						>
+							{option.label}
+						</Checkbox>
+					))}
+				</div>
+			);
+		}
+		case "textarea":
+			return <Textarea {...text} />;
+		case "":
+		case "input":
+		case "slider":
+		case "tag-select": {
+			if (parameter.type === "number") {
+				const { validation_min: min, validation_max: max } =
+					parameter.validations[0] ?? {};
+				return (
+					<Input
+						{...text}
+						type="number"
+						min={min ?? undefined}
+						max={max ?? undefined}
+					/>
+				);
+			}
+			return parameter.styling.mask_input ? (
+				<PasswordInput {...text} />
+			) : (
+				<Input {...text} />
+			);
+		}
+	}
+}
diff --git a/packages/workspace-update/src/components/WorkspaceUpdateForm.stories.tsx b/packages/workspace-update/src/components/WorkspaceUpdateForm.stories.tsx
new file mode 100644
index 0000000000..a25eb0e5a3
--- /dev/null
+++ b/packages/workspace-update/src/components/WorkspaceUpdateForm.stories.tsx
@@ -0,0 +1,140 @@
+import { diagnostic, parameterOption, previewParameter } from "@repo/mocks";
+import { fn } from "storybook/test";
+
+import { WorkspaceUpdateForm } from "./WorkspaceUpdateForm";
+
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+const PARAMETERS = [
+	previewParameter({
+		name: "region",
+		display_name: "Region",
+		form_type: "dropdown",
+		description: "Where the workspace runs.",
+		required: true,
+		options: [
+			parameterOption("eu", "Frankfurt"),
+			parameterOption("us", "Pittsburgh"),
+		],
+	}),
+	previewParameter({
+		name: "cpus",
+		display_name: "CPU cores",
+		type: "number",
+		description: "Cores reserved for the workspace.",
+		validations: [
+			{
+				validation_error: "",
+				validation_regex: null,
+				validation_min: 1,
+				validation_max: 8,
+				validation_monotonic: null,
+			},
+		],
+	}),
+	previewParameter({
+		name: "image",
+		display_name: "Base image",
+		description: "The container image the workspace starts from.",
+		mutable: false,
+	}),
+	previewParameter({
+		name: "gpu",
+		display_name: "GPU",
+		form_type: "checkbox",
+		styling: { label: "Attach a GPU to the workspace" },
+	}),
+	previewParameter({
+		name: "tools",
+		display_name: "Tools",
+		form_type: "multi-select",
+		type: "list(string)",
+		description: "Installed on first start.",
+		options: [
+			parameterOption("docker", "Docker"),
+			parameterOption("node", "Node.js"),
+			parameterOption("go", "Go"),
+		],
+	}),
+	previewParameter({
+		name: "token",
+		display_name: "Access token",
+		styling: { mask_input: true },
+	}),
+	previewParameter({
+		name: "notes",
+		display_name: "Notes",
+		form_type: "textarea",
+		ephemeral: true,
+	}),
+];
+
+const meta: Meta<typeof WorkspaceUpdateForm> = {
+	title: "WorkspaceUpdate/WorkspaceUpdateForm",
+	component: WorkspaceUpdateForm,
+	args: {
+		workspaceName: "alice/dev",
+		restart: true,
+		evaluation: { id: 0, parameters: PARAMETERS, diagnostics: [] },
+		values: { region: "eu", cpus: "4", image: "ubuntu" },
+		evaluating: false,
+		canSubmit: true,
+		onChange: fn(),
+		api: { submit: fn(), cancel: fn() },
+	},
+	parameters: {
+		// Editor tab width.
+		rootWidth: "800px",
+		pixel: {
+			matrix: {
+				themes: ["light", "dark", "high-contrast", "high-contrast-light"],
+			},
+		},
+	},
+};
+
+export default meta;
+type Story = StoryObj<typeof WorkspaceUpdateForm>;
+
+export const Default: Story = {};
+
+export const WithErrors: Story = {
+	args: {
+		evaluation: {
+			id: 0,
+			parameters: PARAMETERS.map((p) =>
+				p.name === "cpus"
+					? { ...p, diagnostics: [diagnostic("Must be at most 8")] }
+					: p,
+			),
+			diagnostics: [
+				diagnostic("The image list could not be refreshed", "warning"),
+			],
+		},
+		values: { region: "eu", cpus: "16", image: "ubuntu" },
+		canSubmit: false,
+	},
+};
+
+export const Evaluating: Story = {
+	args: { evaluating: true, canSubmit: false },
+};
+
+export const EvaluationFailed: Story = {
+	args: { error: "Request failed with status code 500", canSubmit: false },
+};
+
+export const Blocked: Story = {
+	args: {
+		evaluation: {
+			id: 0,
+			parameters: PARAMETERS.map((p) =>
+				p.name === "image"
+					? { ...p, diagnostics: [diagnostic("Image is no longer offered")] }
+					: p,
+			),
+			diagnostics: [],
+		},
+		canSubmit: false,
+	},
+};
diff --git a/packages/workspace-update/src/components/WorkspaceUpdateForm.tsx b/packages/workspace-update/src/components/WorkspaceUpdateForm.tsx
new file mode 100644
index 0000000000..5f3451e5dd
--- /dev/null
+++ b/packages/workspace-update/src/components/WorkspaceUpdateForm.tsx
@@ -0,0 +1,107 @@
+import { Button, ProgressBar, ValidationMessage } from "@repo/ui";
+
+import { FormDiagnostics } from "./Diagnostics";
+import { ParameterField } from "./ParameterField";
+
+import type { ParameterValues } from "@repo/shared";
+import type {
+	DynamicParametersResponse,
+	PreviewParameter,
+} from "coder/site/src/api/typesGenerated";
+
+import type { useWorkspaceUpdateApi } from "../hooks/useWorkspaceUpdateApi";
+
+export type WorkspaceUpdateCommands = Pick<
+	ReturnType<typeof useWorkspaceUpdateApi>,
+	"submit" | "cancel"
+>;
+
+export function WorkspaceUpdateForm({
+	workspaceName,
+	restart,
+	evaluation,
+	values,
+	evaluating,
+	error,
+	canSubmit,
+	onChange,
+	api,
+}: {
+	workspaceName: string;
+	restart: boolean;
+	evaluation: DynamicParametersResponse;
+	/** Edits; parameters without one show the server's value. */
+	values: ParameterValues;
+	evaluating: boolean;
+	/** Why the latest evaluation failed. */
+	error?: string;
+	canSubmit: boolean;
+	onChange: (parameter: PreviewParameter, value: string) => void;
+	api: WorkspaceUpdateCommands;
+}) {
+	const parameters = evaluation.parameters.toSorted(
+		(a, b) => a.order - b.order,
+	);
+	const valueOf = (parameter: PreviewParameter) =>
+		values[parameter.name] ??
+		(parameter.value.valid ? parameter.value.value : "");
+	const blocked = parameters.some(
+		(p) => !p.mutable && p.diagnostics.length > 0,
+	);
+
+	return (
+		<form
+			className="workspace-update"
+			onSubmit={(event) => {
+				event.preventDefault();
+				api.submit(
+					Object.fromEntries(
+						parameters
+							.filter((p) => p.mutable)
+							.map((p) => [p.name, valueOf(p)]),
+					),
+				);
+			}}
+		>
+			{evaluating && (
+				<ProgressBar
+					label="Evaluating parameters"
+					className="workspace-update__progress"
+				/>
+			)}
+			<header className="workspace-update__header">
+				<h1>Update {workspaceName}</h1>
+				<p>The latest template version needs new parameter values.</p>
+			</header>
+			{blocked && (
+				<ValidationMessage role="alert" severity="error">
+					Workspace update blocked: immutable values conflict with the new
+					version. Contact your template administrator.
+				</ValidationMessage>
+			)}
+			<FormDiagnostics diagnostics={evaluation.diagnostics} />
+			{error && (
+				<ValidationMessage role="alert" severity="error">
+					{error}
+				</ValidationMessage>
+			)}
+			{parameters.map((parameter) => (
+				<ParameterField
+					key={parameter.name}
+					parameter={parameter}
+					value={valueOf(parameter)}
+					disabled={parameter.styling.disabled === true || !parameter.mutable}
+					onChange={(value) => onChange(parameter, value)}
+				/>
+			))}
+			<footer className="workspace-update__footer">
+				<Button variant="secondary" onClick={() => api.cancel()}>
+					Cancel
+				</Button>
+				<Button type="submit" disabled={!canSubmit}>
+					{restart ? "Update and restart" : "Update and start"}
+				</Button>
+			</footer>
+		</form>
+	);
+}
diff --git a/packages/workspace-update/src/css.d.ts b/packages/workspace-update/src/css.d.ts
new file mode 100644
index 0000000000..cbe652dbe0
--- /dev/null
+++ b/packages/workspace-update/src/css.d.ts
@@ -0,0 +1 @@
+declare module "*.css";
diff --git a/packages/workspace-update/src/hooks/useDebouncedValue.ts b/packages/workspace-update/src/hooks/useDebouncedValue.ts
new file mode 100644
index 0000000000..fc65a1c400
--- /dev/null
+++ b/packages/workspace-update/src/hooks/useDebouncedValue.ts
@@ -0,0 +1,11 @@
+import { useEffect, useState } from "react";
+
+/** A zero delay returns `value` in the same render instead of a tick later. */
+export function useDebouncedValue<T>(value: T, delayMs: number): T {
+	const [debounced, setDebounced] = useState(value);
+	useEffect(() => {
+		const timer = setTimeout(() => setDebounced(value), delayMs);
+		return () => clearTimeout(timer);
+	}, [value, delayMs]);
+	return delayMs === 0 ? value : debounced;
+}
diff --git a/packages/workspace-update/src/hooks/useWorkspaceUpdateApi.ts b/packages/workspace-update/src/hooks/useWorkspaceUpdateApi.ts
new file mode 100644
index 0000000000..bdef51d2d9
--- /dev/null
+++ b/packages/workspace-update/src/hooks/useWorkspaceUpdateApi.ts
@@ -0,0 +1,6 @@
+import { buildApiHook, WorkspaceUpdateApi } from "@repo/shared";
+import { useIpc } from "@repo/webview-shared/react";
+
+export function useWorkspaceUpdateApi() {
+	return buildApiHook(WorkspaceUpdateApi, useIpc());
+}
diff --git a/packages/workspace-update/src/index.css b/packages/workspace-update/src/index.css
new file mode 100644
index 0000000000..19b3306dba
--- /dev/null
+++ b/packages/workspace-update/src/index.css
@@ -0,0 +1,73 @@
+.workspace-update {
+	display: flex;
+	flex-direction: column;
+	gap: var(--ui-spacing-240);
+	max-width: 720px;
+	margin: 0 auto;
+	/* VS Code already pads the webview body horizontally. */
+	padding-top: var(--ui-spacing-240);
+}
+
+@media (max-width: 480px) {
+	.workspace-update {
+		gap: var(--ui-spacing-160);
+		padding-top: var(--ui-spacing-160);
+	}
+
+	.workspace-update__header h1 {
+		font-size: 20px;
+	}
+}
+
+.workspace-update__progress {
+	position: fixed;
+	inset: 0 0 auto;
+}
+
+.workspace-update__header {
+	padding-bottom: var(--ui-spacing-160);
+	border-bottom: 1px solid var(--ui-separator);
+}
+
+.workspace-update__header h1 {
+	margin: 0;
+	font-size: 26px;
+	font-weight: var(--ui-font-weight-regular);
+	overflow-wrap: anywhere;
+}
+
+.workspace-update__header p {
+	margin: var(--ui-spacing-60) 0 0;
+	color: var(--ui-description-foreground);
+}
+
+.workspace-update__footer {
+	display: flex;
+	flex-wrap: wrap;
+	justify-content: flex-end;
+	gap: var(--ui-spacing-60) var(--ui-spacing-120);
+	padding: var(--ui-spacing-120) 0 var(--ui-spacing-240);
+	border-top: 1px solid var(--ui-separator);
+}
+
+/* The settings editor's text control width. */
+.parameter-field > :is(.ui-control, .ui-text-control, .ui-field__error) {
+	max-width: 420px;
+}
+
+.parameter-options {
+	display: flex;
+	flex-direction: column;
+	gap: var(--ui-spacing-60);
+}
+
+.parameter-label {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: var(--ui-spacing-60);
+}
+
+.parameter-label__required {
+	color: var(--ui-status-danger-accent);
+}
diff --git a/packages/workspace-update/src/index.tsx b/packages/workspace-update/src/index.tsx
new file mode 100644
index 0000000000..c673e9c219
--- /dev/null
+++ b/packages/workspace-update/src/index.tsx
@@ -0,0 +1,28 @@
+import "@repo/ui/codicon.css";
+import "@repo/ui/tokens.css";
+import { ErrorBoundary } from "@repo/webview-shared/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+
+import App from "./App";
+import "./index.css";
+
+const queryClient = new QueryClient();
+
+const root = document.getElementById("root");
+if (!root) {
+	throw new Error(
+		"Failed to find root element. The webview HTML must contain an element with id='root'.",
+	);
+}
+
+createRoot(root).render(
+	<StrictMode>
+		<QueryClientProvider client={queryClient}>
+			<ErrorBoundary>
+				<App />
+			</ErrorBoundary>
+		</QueryClientProvider>
+	</StrictMode>,
+);
diff --git a/packages/workspace-update/storybook.preview.ts b/packages/workspace-update/storybook.preview.ts
new file mode 100644
index 0000000000..c01b6f9c8d
--- /dev/null
+++ b/packages/workspace-update/storybook.preview.ts
@@ -0,0 +1 @@
+import "./src/index.css";
diff --git a/packages/workspace-update/tsconfig.json b/packages/workspace-update/tsconfig.json
new file mode 100644
index 0000000000..edb289b062
--- /dev/null
+++ b/packages/workspace-update/tsconfig.json
@@ -0,0 +1,11 @@
+{
+	"extends": "../tsconfig.packages.json",
+	"compilerOptions": {
+		"paths": {
+			"@repo/shared": ["../shared/src"],
+			"@repo/ui": ["../ui/src"],
+			"@repo/webview-shared": ["../webview-shared/src"]
+		}
+	},
+	"include": ["src", "storybook.preview.ts"]
+}
diff --git a/packages/workspace-update/vite.config.ts b/packages/workspace-update/vite.config.ts
new file mode 100644
index 0000000000..4982de88ba
--- /dev/null
+++ b/packages/workspace-update/vite.config.ts
@@ -0,0 +1,6 @@
+import { createReactWebviewConfig } from "../webview-shared/createWebviewConfig.ts";
+
+export default createReactWebviewConfig(
+	"workspace-update",
+	import.meta.dirname,
+);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2aa366a5f4..0cc7273d82 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -656,6 +656,55 @@ importers:
         specifier: 'catalog:'
         version: '@typescript/typescript6@6.0.2'
 
+  packages/workspace-update:
+    dependencies:
+      '@repo/shared':
+        specifier: workspace:*
+        version: link:../shared
+      '@repo/ui':
+        specifier: workspace:*
+        version: link:../ui
+      '@repo/webview-shared':
+        specifier: workspace:*
+        version: link:../webview-shared
+      '@tanstack/react-query':
+        specifier: 'catalog:'
+        version: 5.105.0(@types/react@19.3.0)(react@19.3.1)
+      react:
+        specifier: 'catalog:'
+        version: 19.3.1
+      react-dom:
+        specifier: 'catalog:'
+        version: 19.3.1(react@19.3.1)
+    devDependencies:
+      '@repo/mocks':
+        specifier: workspace:*
+        version: link:../mocks
+      '@repo/storybook-utils':
+        specifier: workspace:*
+        version: link:../storybook-utils
+      '@rolldown/plugin-babel':
+        specifier: 'catalog:'
+        version: 0.2.4(@babel/core@7.29.7)(@babel/runtime@7.29.10)(rolldown@1.2.15)(vite@8.3.5)
+      '@types/react':
+        specifier: 'catalog:'
+        version: 19.3.0
+      '@types/react-dom':
+        specifier: 'catalog:'
+        version: 19.3.0(@types/react@19.3.0)
+      '@vitejs/plugin-react':
+        specifier: 'catalog:'
+        version: 6.1.2(@rolldown/plugin-babel@0.2.4)(babel-plugin-react-compiler@1.0.0)(vite@8.3.5)
+      babel-plugin-react-compiler:
+        specifier: 'catalog:'
+        version: 1.0.0
+      typescript:
+        specifier: 'catalog:'
+        version: '@typescript/typescript6@6.0.2'
+      vite:
+        specifier: 'catalog:'
+        version: 8.3.5(@types/node@22.20.5)(esbuild@0.28.2)
+
   packages/workspaces:
     dependencies:
       '@repo/shared':
diff --git a/src/api/dynamicParameters.ts b/src/api/dynamicParameters.ts
new file mode 100644
index 0000000000..ed0c8b195f
--- /dev/null
+++ b/src/api/dynamicParameters.ts
@@ -0,0 +1,187 @@
+import { isApiValidationError } from "coder/site/src/api/errors";
+
+import {
+	hasErrorDiagnostics,
+	parseMultiSelectValue,
+	type ParameterValues,
+	type WorkspaceUpdateInit,
+} from "@repo/shared";
+
+import { HttpStatusCode } from "./httpStatusCode";
+import { createWorkspaceIdentifier } from "./models";
+
+import type { Api } from "coder/site/src/api/api";
+import type {
+	DynamicParametersResponse,
+	FriendlyDiagnostic,
+	PreviewParameter,
+	ValidationError,
+	Workspace,
+	WorkspaceBuildParameter,
+} from "coder/site/src/api/typesGenerated";
+
+import type { ServerFeatureSet } from "../featureSet";
+
+export type EvaluateParameters = (
+	inputs: ParameterValues,
+) => Promise<DynamicParametersResponse>;
+
+/** Shows the parameter form and resolves with the submitted values. */
+export type ShowUpdateForm = (
+	init: WorkspaceUpdateInit,
+	evaluate: EvaluateParameters,
+) => Promise<WorkspaceBuildParameter[]>;
+
+/** Older servers omit the template flag, so only an explicit `false` counts. */
+export function usesDynamicParameters(
+	workspace: Workspace,
+	features: Pick<ServerFeatureSet, "dynamicParameters">,
+): boolean {
+	return (
+		features.dynamicParameters &&
+		workspace.template_use_classic_parameter_flow === false
+	);
+}
+
+/**
+ * Keeps the previous values when the new version accepts them, otherwise
+ * asks through the form, like the dashboard.
+ */
+export async function collectDynamicParameters(
+	restClient: Api,
+	workspace: Workspace,
+	showForm: ShowUpdateForm,
+): Promise<WorkspaceBuildParameter[]> {
+	const evaluate = evaluator(restClient, workspace);
+	const previous = await previousValues(restClient, workspace);
+	const evaluation = await evaluate(previous);
+	if (!hasErrorDiagnostics(evaluation)) {
+		return [];
+	}
+	const values = acceptedValues(evaluation.parameters, previous);
+	const unchanged = Object.keys(values).length === Object.keys(previous).length;
+	return showForm(
+		formInit(
+			workspace,
+			values,
+			unchanged ? evaluation : await evaluate(values),
+		),
+		evaluate,
+	);
+}
+
+/** Reopens the form on values the build rejected, with the server's reasons. */
+export async function reviseRejectedParameters(
+	restClient: Api,
+	workspace: Workspace,
+	rejected: readonly WorkspaceBuildParameter[],
+	validations: readonly ValidationError[],
+	showForm: ShowUpdateForm,
+): Promise<WorkspaceBuildParameter[]> {
+	const evaluate = evaluator(restClient, workspace);
+	const values = {
+		...(await previousValues(restClient, workspace)),
+		...Object.fromEntries(rejected.map(({ name, value }) => [name, value])),
+	};
+	const evaluation = await evaluate(values);
+	const rejections = validations.map(
+		({ field, detail }): FriendlyDiagnostic => ({
+			severity: "error",
+			summary: `${field}: ${detail}`,
+			detail: "",
+			extra: { code: "" },
+		}),
+	);
+	return showForm(
+		formInit(workspace, values, {
+			...evaluation,
+			diagnostics: [...evaluation.diagnostics, ...rejections],
+		}),
+		evaluate,
+	);
+}
+
+/** The field errors of a build the server rejected for its parameters. */
+export function rejectedParameters(
+	error: unknown,
+): readonly ValidationError[] | undefined {
+	if (
+		!isApiValidationError(error) ||
+		error.response.status !== HttpStatusCode.BAD_REQUEST
+	) {
+		return undefined;
+	}
+	const { validations } = error.response.data;
+	return validations?.length ? validations : undefined;
+}
+
+function evaluator(restClient: Api, workspace: Workspace): EvaluateParameters {
+	const { template_active_version_id: versionId, owner_id } = workspace;
+	return async (inputs) => {
+		const response = await restClient.getTemplateVersionDynamicParameters(
+			versionId,
+			{ id: 0, owner_id, inputs },
+		);
+		// The server sends null for empty lists.
+		return {
+			...response,
+			parameters: response.parameters ?? [],
+			diagnostics: response.diagnostics ?? [],
+		};
+	};
+}
+
+async function previousValues(
+	restClient: Api,
+	workspace: Workspace,
+): Promise<ParameterValues> {
+	const parameters = await restClient.getWorkspaceBuildParameters(
+		workspace.latest_build.id,
+	);
+	return Object.fromEntries(parameters.map(({ name, value }) => [name, value]));
+}
+
+function formInit(
+	workspace: Workspace,
+	values: ParameterValues,
+	evaluation: DynamicParametersResponse,
+): WorkspaceUpdateInit {
+	return {
+		workspaceName: createWorkspaceIdentifier(workspace),
+		values,
+		evaluation,
+		restart: workspace.latest_build.status === "running",
+	};
+}
+
+/** Like the dashboard's `getInitialParameterValues`. */
+function acceptedValues(
+	parameters: readonly PreviewParameter[],
+	previous: ParameterValues,
+): ParameterValues {
+	const accepted: Record<string, string> = {};
+	for (const parameter of parameters) {
+		const value = previous[parameter.name];
+		if (value === undefined || parameter.ephemeral) {
+			continue;
+		}
+		if (isValidOption(parameter, value)) {
+			accepted[parameter.name] = value;
+		}
+	}
+	return accepted;
+}
+
+function isValidOption(parameter: PreviewParameter, value: string): boolean {
+	if (parameter.options.length === 0) {
+		return true;
+	}
+	const options = new Set(parameter.options.map((o) => o.value.value));
+	if (parameter.form_type !== "multi-select") {
+		return options.has(value);
+	}
+	return (
+		parseMultiSelectValue(value)?.some((selected) => options.has(selected)) ??
+		false
+	);
+}
diff --git a/src/api/updateParameters.ts b/src/api/updateParameters.ts
index 3956ba4cfa..8e51701438 100644
--- a/src/api/updateParameters.ts
+++ b/src/api/updateParameters.ts
@@ -1,5 +1,7 @@
 import * as vscode from "vscode";
 
+import { parseMultiSelectValue } from "@repo/shared";
+
 import type { Api } from "coder/site/src/api/api";
 import type {
 	TemplateVersionParameter,
@@ -102,18 +104,6 @@ function promptSpec(
 	return { driftNote };
 }
 
-/** Multi-select values are stored as a JSON-encoded string array. */
-function parseMultiSelectValue(raw: string): string[] | null {
-	try {
-		const parsed: unknown = JSON.parse(raw);
-		return Array.isArray(parsed) && parsed.every((v) => typeof v === "string")
-			? parsed
-			: null;
-	} catch {
-		return null;
-	}
-}
-
 /** Truncates and JSON-quotes a value for safe display in a placeholder. */
 function formatValue(value: string): string {
 	const truncated =
diff --git a/src/api/workspace.ts b/src/api/workspace.ts
index f1796473c5..7e5b4eb4d8 100644
--- a/src/api/workspace.ts
+++ b/src/api/workspace.ts
@@ -135,6 +135,21 @@ export async function startWorkspace(ctx: CliContext): Promise<Workspace> {
 	return ctx.restClient.getWorkspace(ctx.workspace.id);
 }
 
+/** The latest template version's message, or empty if it can't be loaded. */
+export async function getLatestVersionMessage(
+	restClient: Pick<Api, "getTemplateVersion">,
+	workspace: Workspace,
+): Promise<string> {
+	try {
+		const version = await restClient.getTemplateVersion(
+			workspace.template_active_version_id,
+		);
+		return version.message;
+	} catch {
+		return "";
+	}
+}
+
 /**
  * Update a workspace to the latest template version. Callers must collect
  * any newly-required parameters via `collectUpdateParameters` first; this
diff --git a/src/commands.ts b/src/commands.ts
index 19b8ec3041..a86e708b58 100644
--- a/src/commands.ts
+++ b/src/commands.ts
@@ -9,6 +9,7 @@ import {
 	createWorkspaceIdentifier,
 	workspaceStatusLabel,
 } from "./api/models";
+import { getLatestVersionMessage } from "./api/workspace";
 import * as cliExec from "./cli/cliExec";
 import { runDiagnosticCli } from "./command/diagnosticFlow";
 import { openInBrowser, toSafeHost } from "./common/url";
@@ -1344,13 +1345,23 @@ export class Commands {
 			this.telemetryService,
 			workspaceName,
 		);
+		const versionMessage = await getLatestVersionMessage(
+			this.remoteWorkspaceClient,
+			this.workspace,
+		);
 		const action = await operationTelemetry.traceConfirmationPrompt(async () =>
 			vscodeProposed.window.showWarningMessage(
 				"Update Workspace",
 				{
 					useCustom: true,
 					modal: true,
-					detail: `Update ${workspaceName} to the latest version?\n\nUpdating will restart your workspace which stops any running processes and may result in the loss of unsaved work.`,
+					detail: [
+						`Update ${workspaceName} to the latest version?`,
+						"Updating will restart your workspace which stops any running processes and may result in the loss of unsaved work.",
+						versionMessage,
+					]
+						.filter(Boolean)
+						.join("\n\n"),
 				},
 				UPDATE_AND_RESTART_ACTION,
 			),
diff --git a/src/container.ts b/src/container.ts
index a1163c318b..8b2b1b5f62 100644
--- a/src/container.ts
+++ b/src/container.ts
@@ -24,6 +24,7 @@ import { CommandManager } from "./vscode/commandManager";
 import { ContextManager } from "./vscode/contextManager";
 import { NetcheckPanelFactory } from "./webviews/netcheck/netcheckPanelFactory";
 import { SpeedtestPanelFactory } from "./webviews/speedtest/speedtestPanelFactory";
+import { WorkspaceUpdatePanelFactory } from "./webviews/workspaceUpdate/workspaceUpdatePanelFactory";
 import { DuplicateWorkspaceIpc } from "./workspace/duplicateWorkspaceIpc";
 
 import type { Logger } from "./logging/logger";
@@ -47,6 +48,7 @@ export class ServiceContainer implements vscode.Disposable {
 	private readonly duplicateWorkspaceIpc: DuplicateWorkspaceIpc;
 	private readonly oauthCallback: OAuthCallback;
 	private readonly speedtestPanelFactory: SpeedtestPanelFactory;
+	private readonly workspaceUpdatePanelFactory: WorkspaceUpdatePanelFactory;
 	private readonly netcheckPanelFactory: NetcheckPanelFactory;
 	private readonly telemetryService: TelemetryService;
 	private readonly commandManager: CommandManager;
@@ -144,6 +146,10 @@ export class ServiceContainer implements vscode.Disposable {
 			context.extensionUri,
 			this.logger,
 		);
+		this.workspaceUpdatePanelFactory = new WorkspaceUpdatePanelFactory(
+			context.extensionUri,
+			this.logger,
+		);
 		this.netcheckPanelFactory = new NetcheckPanelFactory(
 			context.extensionUri,
 			this.logger,
@@ -199,6 +205,10 @@ export class ServiceContainer implements vscode.Disposable {
 		return this.speedtestPanelFactory;
 	}
 
+	getWorkspaceUpdatePanelFactory(): WorkspaceUpdatePanelFactory {
+		return this.workspaceUpdatePanelFactory;
+	}
+
 	getNetcheckPanelFactory(): NetcheckPanelFactory {
 		return this.netcheckPanelFactory;
 	}
diff --git a/src/error/normalize.ts b/src/error/normalize.ts
index 3a21bdb4c4..c582990a70 100644
--- a/src/error/normalize.ts
+++ b/src/error/normalize.ts
@@ -45,3 +45,14 @@ export function errToStr(error: unknown, def = "No error message provided") {
 	}
 	return def;
 }
+
+/** Like `errToStr`, but keeps the server's detail and field errors. */
+export function describeError(error: unknown): string {
+	if (!isApiError(error)) {
+		return errToStr(error);
+	}
+	const { message, detail, validations = [] } = error.response.data;
+	return [message, detail, ...validations.map((v) => `${v.field}: ${v.detail}`)]
+		.filter(Boolean)
+		.join("\n");
+}
diff --git a/src/featureSet.ts b/src/featureSet.ts
index 923caa2452..99ddf8fb7d 100644
--- a/src/featureSet.ts
+++ b/src/featureSet.ts
@@ -22,6 +22,7 @@ export interface ServerFeatureSet {
 	tasks: boolean;
 	onSuccessBuild: boolean;
 	customSessionAppNames: boolean;
+	dynamicParameters: boolean;
 }
 
 /**
@@ -81,5 +82,7 @@ export function serverFeatureSet(
 		// `on_success` on a stop build, which queues the start in one request
 		onSuccessBuild: versionAtLeast(version, "2.36.0"),
 		customSessionAppNames: versionAtLeast(version, "2.38.0"),
+		// `POST .../dynamic-parameters/evaluate`; 2.23 sends the template flag without it
+		dynamicParameters: versionAtLeast(version, "2.24.0"),
 	};
 }
diff --git a/src/remote/workspaceStateMachine.ts b/src/remote/workspaceStateMachine.ts
index 07aef67d66..e6e5b114f4 100644
--- a/src/remote/workspaceStateMachine.ts
+++ b/src/remote/workspaceStateMachine.ts
@@ -1,16 +1,24 @@
+import {
+	collectDynamicParameters,
+	rejectedParameters,
+	reviseRejectedParameters,
+	usesDynamicParameters,
+	type ShowUpdateForm,
+} from "../api/dynamicParameters";
 import { extractAgents, createWorkspaceIdentifier } from "../api/models";
 import {
 	collectUpdateParameters,
 	WorkspaceUpdateCancelledError,
 } from "../api/updateParameters";
 import {
+	getLatestVersionMessage,
 	LazyStream,
 	startWorkspace,
 	updateWorkspace,
 	streamAgentLogs,
 	streamBuildLogs,
 } from "../api/workspace";
-import { errToStr } from "../error/normalize";
+import { describeError } from "../error/normalize";
 import { WorkspaceOperationTelemetry } from "../instrumentation/workspace";
 import { maybeAskAgent } from "../ui/prompts";
 import { vscodeProposed } from "../vscode/proposed";
@@ -30,6 +38,7 @@ import type { CliFeatureSet, ServerFeatureSet } from "../featureSet";
 import type { Logger } from "../logging/logger";
 import type { CliAuth } from "../settings/cli";
 import type { StartupMode } from "../storage/mementoManager";
+import type { WorkspaceUpdatePanelFactory } from "../webviews/workspaceUpdate/workspaceUpdatePanelFactory";
 
 import type { AuthorityParts } from "./authority";
 
@@ -49,6 +58,7 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 	private queuedStopBuild: string | undefined;
 
 	private readonly logger: Logger;
+	private readonly workspaceUpdatePanel: WorkspaceUpdatePanelFactory;
 
 	constructor(
 		private readonly parts: AuthorityParts,
@@ -61,6 +71,7 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 		container: ServiceContainer,
 	) {
 		this.logger = container.getLogger();
+		this.workspaceUpdatePanel = container.getWorkspaceUpdatePanelFactory();
 		this.terminal = new TerminalOutputChannel("Coder: Workspace Build");
 		const telemetry = container.getTelemetryService();
 		const workspaceName = `${parts.username}/${parts.workspace}`;
@@ -123,8 +134,8 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 
 				if (this.startupMode === "none") {
 					const choice = await this.confirmStartOrUpdate(
+						workspace,
 						workspaceName,
-						workspace.outdated,
 					);
 					if (!choice) {
 						throw new Error(`Workspace start cancelled`);
@@ -322,12 +333,7 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 			status: workspace.latest_build.status,
 		});
 		try {
-			const parameters = await this.operationTelemetry.traceParametersPrompt(
-				() => collectUpdateParameters(this.workspaceClient, workspace),
-			);
-			const updated = await this.operationTelemetry.traceUpdate(() =>
-				updateWorkspace(this.buildCliContext(workspace), parameters),
-			);
+			const updated = await this.updateToLatest(workspace);
 			this.workspace = updated;
 			// Only the one-build update returns a stop; the server starts it after.
 			if (updated.latest_build.transition === "stop") {
@@ -342,7 +348,7 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 				);
 				return undefined;
 			}
-			const reason = errToStr(error);
+			const reason = describeError(error);
 			this.logger.warn(`Update failed for ${workspaceName}: ${reason}`);
 			const connect = await this.operationTelemetry.traceFailurePrompt(() =>
 				this.confirmConnectToExisting(workspaceName, reason),
@@ -355,6 +361,42 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 		}
 	}
 
+	/** Reopens the form once if the build rejects dynamic parameters. */
+	private async updateToLatest(workspace: Workspace): Promise<Workspace> {
+		const dynamic = usesDynamicParameters(workspace, this.serverFeatures);
+		const showForm: ShowUpdateForm = (init, evaluate) =>
+			this.workspaceUpdatePanel.show(init, evaluate);
+		const parameters = await this.operationTelemetry.traceParametersPrompt(() =>
+			dynamic
+				? collectDynamicParameters(this.workspaceClient, workspace, showForm)
+				: collectUpdateParameters(this.workspaceClient, workspace),
+		);
+		try {
+			return await this.operationTelemetry.traceUpdate(() =>
+				updateWorkspace(this.buildCliContext(workspace), parameters),
+			);
+		} catch (error) {
+			const validations = rejectedParameters(error);
+			if (!dynamic || !validations) {
+				throw error;
+			}
+			// Some update paths stop the workspace before the start is rejected.
+			const current = await this.workspaceClient.getWorkspace(workspace.id);
+			const revised = await this.operationTelemetry.traceParametersPrompt(() =>
+				reviseRejectedParameters(
+					this.workspaceClient,
+					current,
+					parameters,
+					validations,
+					showForm,
+				),
+			);
+			return this.operationTelemetry.traceUpdate(() =>
+				updateWorkspace(this.buildCliContext(current), revised),
+			);
+		}
+	}
+
 	/** Offers the existing version after a failed update. */
 	private async confirmConnectToExisting(
 		workspaceName: string,
@@ -374,9 +416,13 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 	}
 
 	private async confirmStartOrUpdate(
+		workspace: Workspace,
 		workspaceName: string,
-		outdated: boolean,
 	): Promise<"start" | "update" | undefined> {
+		const { outdated } = workspace;
+		const versionMessage = outdated
+			? await getLatestVersionMessage(this.workspaceClient, workspace)
+			: "";
 		return this.operationTelemetry.traceStartPrompt(outdated, async () => {
 			const buttons = outdated
 				? (["Start", "Update and Start"] as const)
@@ -386,6 +432,7 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 				{
 					useCustom: true,
 					modal: true,
+					detail: versionMessage || undefined,
 				},
 				...buttons,
 			);
diff --git a/src/webviews/coderPanel.ts b/src/webviews/coderPanel.ts
new file mode 100644
index 0000000000..b69222af42
--- /dev/null
+++ b/src/webviews/coderPanel.ts
@@ -0,0 +1,63 @@
+import * as vscode from "vscode";
+
+import { dispatchWebviewMessage, type WebviewHandlers } from "./dispatch";
+import { getWebviewHtml } from "./html";
+
+import type { Logger } from "../logging/logger";
+
+export interface CoderPanelOptions {
+	extensionUri: vscode.Uri;
+	logger: Logger;
+	/** Panel view type, e.g. `coder.speedtestPanel`. */
+	viewType: string;
+	/** Bundle name under `dist/webviews/`. */
+	webviewName: string;
+	title: string;
+	/**
+	 * Build the handler maps with `buildCommandHandlers` and
+	 * `buildRequestHandlers` so the compile-time exhaustiveness check stays
+	 * with the concrete API definition.
+	 */
+	handlers: WebviewHandlers;
+}
+
+/**
+ * Opens a Coder-branded webview panel for a bundled webview and dispatches
+ * its messages until the panel is disposed.
+ */
+export function createCoderPanel(
+	options: CoderPanelOptions,
+): vscode.WebviewPanel {
+	const { extensionUri, logger, webviewName, title, handlers } = options;
+	const panel = vscode.window.createWebviewPanel(
+		options.viewType,
+		title,
+		vscode.ViewColumn.One,
+		{
+			enableScripts: true,
+			localResourceRoots: [
+				vscode.Uri.joinPath(extensionUri, "dist", "webviews", webviewName),
+			],
+		},
+	);
+
+	panel.iconPath = {
+		light: vscode.Uri.joinPath(extensionUri, "media", "logo-black.svg"),
+		dark: vscode.Uri.joinPath(extensionUri, "media", "logo-white.svg"),
+	};
+
+	panel.webview.html = getWebviewHtml(
+		panel.webview,
+		extensionUri,
+		webviewName,
+		title,
+	);
+
+	const listener = panel.webview.onDidReceiveMessage((message: unknown) => {
+		void dispatchWebviewMessage(message, handlers, panel.webview, { logger });
+	});
+	panel.onDidDispose(() => {
+		listener.dispose();
+	});
+	return panel;
+}
diff --git a/src/webviews/resultPanel.ts b/src/webviews/resultPanel.ts
index 42d1fcb7bf..d1d204a8b9 100644
--- a/src/webviews/resultPanel.ts
+++ b/src/webviews/resultPanel.ts
@@ -1,11 +1,9 @@
 import * as vscode from "vscode";
 
-import { dispatchWebviewMessage, onWhileVisible } from "./dispatch";
-import { getWebviewHtml } from "./html";
+import { createCoderPanel, type CoderPanelOptions } from "./coderPanel";
+import { onWhileVisible, type WebviewHandlers } from "./dispatch";
 import { openJsonBeside } from "./openJson";
 
-import type { Logger } from "../logging/logger";
-
 export interface ResultPanelHandlerContext {
 	/** Push the payload to the webview. */
 	sendData: () => void;
@@ -13,14 +11,10 @@ export interface ResultPanelHandlerContext {
 	openRawJson: () => Promise<void>;
 }
 
-export interface ResultPanelOptions {
-	extensionUri: vscode.Uri;
-	logger: Logger;
-	/** Panel view type, e.g. `coder.speedtestPanel`. */
-	viewType: string;
-	/** Bundle name under `dist/webviews/`. */
-	webviewName: string;
-	title: string;
+export interface ResultPanelOptions extends Omit<
+	CoderPanelOptions,
+	"handlers"
+> {
 	/** Raw CLI output backing the open-JSON action. */
 	rawJson: string;
 	/** Human-readable feature name used in error messages, e.g. "speed test". */
@@ -32,49 +26,21 @@ export interface ResultPanelOptions {
 	 * `buildRequestHandlers` so the compile-time exhaustiveness check stays
 	 * with the concrete API definition.
 	 */
-	buildHandlers: (ctx: ResultPanelHandlerContext) => {
-		commands: Record<string, (params: unknown) => void | Promise<void>>;
-		requests: Record<string, (params: unknown) => Promise<unknown>>;
-	};
+	buildHandlers: (ctx: ResultPanelHandlerContext) => WebviewHandlers;
 }
 
 /**
- * Create a webview panel that renders a one-shot CLI result. Owns the panel
- * scaffolding shared by such panels: HTML/CSP generation, payload re-send on
- * visibility and theme changes, message dispatch, and disposal.
+ * Create a webview panel that renders a one-shot CLI result, re-sending the
+ * payload on visibility and theme changes.
  */
 export function showResultPanel(options: ResultPanelOptions): void {
-	const { extensionUri, logger, webviewName, title } = options;
-	const panel = vscode.window.createWebviewPanel(
-		options.viewType,
-		title,
-		vscode.ViewColumn.One,
-		{
-			enableScripts: true,
-			localResourceRoots: [
-				vscode.Uri.joinPath(extensionUri, "dist", "webviews", webviewName),
-			],
-		},
-	);
-
-	panel.iconPath = {
-		light: vscode.Uri.joinPath(extensionUri, "media", "logo-black.svg"),
-		dark: vscode.Uri.joinPath(extensionUri, "media", "logo-white.svg"),
-	};
-
-	panel.webview.html = getWebviewHtml(
-		panel.webview,
-		extensionUri,
-		webviewName,
-		title,
-	);
-
+	// Called only after the panel exists.
 	const sendData = () => options.notify(panel.webview);
 	const openRawJson = () =>
-		openJsonBeside(options.rawJson, options.jsonErrorLabel, logger);
-	const { commands, requests } = options.buildHandlers({
-		sendData,
-		openRawJson,
+		openJsonBeside(options.rawJson, options.jsonErrorLabel, options.logger);
+	const panel = createCoderPanel({
+		...options,
+		handlers: options.buildHandlers({ sendData, openRawJson }),
 	});
 
 	// Webview JS is discarded when hidden (no retainContextWhenHidden), and
@@ -83,14 +49,6 @@ export function showResultPanel(options: ResultPanelOptions): void {
 	const disposables: vscode.Disposable[] = [
 		onWhileVisible(panel, panel.onDidChangeViewState, sendData),
 		onWhileVisible(panel, vscode.window.onDidChangeActiveColorTheme, sendData),
-		panel.webview.onDidReceiveMessage((message: unknown) => {
-			void dispatchWebviewMessage(
-				message,
-				{ requests, commands },
-				panel.webview,
-				{ logger },
-			);
-		}),
 	];
 	panel.onDidDispose(() => {
 		for (const d of disposables) {
diff --git a/src/webviews/workspaceUpdate/workspaceUpdatePanelFactory.ts b/src/webviews/workspaceUpdate/workspaceUpdatePanelFactory.ts
new file mode 100644
index 0000000000..658442620e
--- /dev/null
+++ b/src/webviews/workspaceUpdate/workspaceUpdatePanelFactory.ts
@@ -0,0 +1,60 @@
+import {
+	buildCommandHandlers,
+	buildRequestHandlers,
+	WorkspaceUpdateApi,
+	type WorkspaceUpdateInit,
+} from "@repo/shared";
+
+import { WorkspaceUpdateCancelledError } from "../../api/updateParameters";
+import { createCoderPanel } from "../coderPanel";
+
+import type { WorkspaceBuildParameter } from "coder/site/src/api/typesGenerated";
+import type * as vscode from "vscode";
+
+import type { EvaluateParameters } from "../../api/dynamicParameters";
+import type { Logger } from "../../logging/logger";
+
+export class WorkspaceUpdatePanelFactory {
+	public constructor(
+		private readonly extensionUri: vscode.Uri,
+		private readonly logger: Logger,
+	) {}
+
+	/** Resolves with the submitted values; closing the form cancels. */
+	public show(
+		init: WorkspaceUpdateInit,
+		evaluate: EvaluateParameters,
+	): Promise<WorkspaceBuildParameter[]> {
+		return new Promise((resolve, reject) => {
+			const panel = createCoderPanel({
+				extensionUri: this.extensionUri,
+				logger: this.logger,
+				viewType: "coder.workspaceUpdate",
+				webviewName: "workspace-update",
+				title: `Update ${init.workspaceName}`,
+				handlers: {
+					commands: buildCommandHandlers(WorkspaceUpdateApi, {
+						submit: (values) => {
+							resolve(
+								Object.entries(values).map(([name, value]) => ({
+									name,
+									value,
+								})),
+							);
+							panel.dispose();
+						},
+						cancel: () => {
+							panel.dispose();
+						},
+					}),
+					requests: buildRequestHandlers(WorkspaceUpdateApi, {
+						init: () => Promise.resolve(init),
+						evaluate,
+					}),
+				},
+			});
+			// No-op once submit has resolved.
+			panel.onDidDispose(() => reject(new WorkspaceUpdateCancelledError()));
+		});
+	}
+}
diff --git a/test/mocks/testHelpers.ts b/test/mocks/testHelpers.ts
index 6c2bc77798..da5dda6617 100644
--- a/test/mocks/testHelpers.ts
+++ b/test/mocks/testHelpers.ts
@@ -54,6 +54,9 @@ import type {
 	ParsedMessageEvent,
 	UnidirectionalStream,
 } from "@/websocket/eventStreamConnection";
+import type { WorkspaceUpdatePanelFactory } from "@/webviews/workspaceUpdate/workspaceUpdatePanelFactory";
+
+import type { RequestDef } from "@repo/shared";
 /**
  * Subset of `ContextManager`'s public API that mocks (e.g. `MockContextManager`)
  * implement. Used by `createMockServiceContainer` so tests can pass either the
@@ -676,6 +679,7 @@ export function createMockServiceContainer(
 		pathResolver?: PathResolver;
 		contextManager?: ContextManagerLike;
 		loginCoordinator?: LoginCoordinatorLike;
+		workspaceUpdatePanelFactory?: WorkspaceUpdatePanelFactory;
 	} = {},
 ): ServiceContainer {
 	const telemetry = overrides.telemetry ?? createTestTelemetryService();
@@ -701,6 +705,8 @@ export function createMockServiceContainer(
 			require("contextManager", overrides.contextManager) as ContextManager,
 		getLoginCoordinator: () =>
 			require("loginCoordinator", overrides.loginCoordinator) as LoginCoordinator,
+		getWorkspaceUpdatePanelFactory: () =>
+			require("workspaceUpdatePanelFactory", overrides.workspaceUpdatePanelFactory),
 	} as ServiceContainer;
 }
 
@@ -760,6 +766,28 @@ function createMockWebview(options: vscode.WebviewOptions) {
 	return { webview, messageEmitter, postedMessages };
 }
 
+/** Sends a request as the webview and resolves with the extension's response. */
+export function sendWebviewRequest<P, R>(
+	hooks: Pick<WebviewPanelTestHooks, "sendFromWebview" | "postedMessages">,
+	def: RequestDef<P, R>,
+	...args: P extends void ? [] : [params: P]
+): Promise<{ success: boolean; data?: R; error?: string }> {
+	const requestId = crypto.randomUUID();
+	hooks.sendFromWebview({ requestId, method: def.method, params: args[0] });
+	return vi.waitFor(
+		() => {
+			const response = hooks.postedMessages.find(
+				(m) => (m as { requestId?: string }).requestId === requestId,
+			);
+			if (!response) {
+				throw new Error(`No response to ${def.method} yet`);
+			}
+			return response as { success: boolean; data?: R; error?: string };
+		},
+		{ timeout: 1000 },
+	);
+}
+
 /** Hooks to drive lifecycle and inspect messages on a mocked WebviewPanel. */
 export interface WebviewPanelTestHooks {
 	setVisible(visible: boolean): void;
diff --git a/test/tsconfig.json b/test/tsconfig.json
index 6c1e8a50e7..74298d9885 100644
--- a/test/tsconfig.json
+++ b/test/tsconfig.json
@@ -17,7 +17,8 @@
 			"@repo/ui/*": ["../packages/ui/src/*"],
 			"@repo/netcheck/*": ["../packages/netcheck/src/*"],
 			"@repo/speedtest/*": ["../packages/speedtest/src/*"],
-			"@repo/workspaces/*": ["../packages/workspaces/src/*"]
+			"@repo/workspaces/*": ["../packages/workspaces/src/*"],
+			"@repo/workspace-update/*": ["../packages/workspace-update/src/*"]
 		}
 	},
 	"include": [".", "../src", "../vitest.config.mts"]
diff --git a/test/unit/api/dynamicParameters.test.ts b/test/unit/api/dynamicParameters.test.ts
new file mode 100644
index 0000000000..a7574ea8c3
--- /dev/null
+++ b/test/unit/api/dynamicParameters.test.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+	collectDynamicParameters,
+	reviseRejectedParameters,
+	usesDynamicParameters,
+	type ShowUpdateForm,
+} from "@/api/dynamicParameters";
+
+import {
+	diagnostic,
+	parameterOption,
+	previewParameter,
+	workspace,
+} from "@repo/mocks";
+
+import type { Api } from "coder/site/src/api/api";
+import type { PreviewParameter } from "coder/site/src/api/typesGenerated";
+
+function setup(parameters: PreviewParameter[]) {
+	const client: Pick<
+		Api,
+		"getWorkspaceBuildParameters" | "getTemplateVersionDynamicParameters"
+	> = {
+		getWorkspaceBuildParameters: vi.fn().mockResolvedValue([
+			{ name: "region", value: "eu" },
+			{ name: "size", value: "retired" },
+			{ name: "token", value: "old" },
+		]),
+		getTemplateVersionDynamicParameters: vi
+			.fn()
+			.mockResolvedValue({ id: 0, parameters, diagnostics: null }),
+	};
+	const ws = workspace({
+		template_use_classic_parameter_flow: false,
+		template_active_version_id: "version-2",
+		latest_build: { status: "running" },
+	});
+	const showForm = vi.fn<ShowUpdateForm>().mockResolvedValue([]);
+	return { client: client as Api, ws, showForm };
+}
+
+describe("usesDynamicParameters", () => {
+	it.each([
+		{ flag: false, supported: true, expected: true },
+		{ flag: true, supported: true, expected: false },
+		{ flag: undefined, supported: true, expected: false },
+		{ flag: false, supported: false, expected: false },
+	])(
+		"flag $flag on a server with support $supported is $expected",
+		({ flag, supported, expected }) => {
+			const ws = workspace({ template_use_classic_parameter_flow: flag });
+			expect(usesDynamicParameters(ws, { dynamicParameters: supported })).toBe(
+				expected,
+			);
+		},
+	);
+});
+
+describe("collectDynamicParameters", () => {
+	it("keeps the previous values without a form when the new version accepts them", async () => {
+		const { client, ws, showForm } = setup([
+			previewParameter({ name: "region" }),
+		]);
+
+		expect(await collectDynamicParameters(client, ws, showForm)).toEqual([]);
+		expect(client.getTemplateVersionDynamicParameters).toHaveBeenCalledWith(
+			"version-2",
+			{
+				id: 0,
+				owner_id: ws.owner_id,
+				inputs: { region: "eu", size: "retired", token: "old" },
+			},
+		);
+		expect(showForm).not.toHaveBeenCalled();
+	});
+
+	it("opens the form with the previous values the new version still accepts", async () => {
+		const parameters = [
+			previewParameter({ name: "region" }),
+			previewParameter({
+				name: "size",
+				form_type: "dropdown",
+				options: [parameterOption("small")],
+				diagnostics: [diagnostic("Invalid")],
+			}),
+			previewParameter({ name: "token", ephemeral: true }),
+		];
+		const { client, ws, showForm } = setup(parameters);
+		await collectDynamicParameters(client, ws, showForm);
+
+		const values = { region: "eu" };
+		expect(showForm).toHaveBeenCalledWith(
+			{
+				workspaceName: "testuser/test-workspace",
+				values,
+				evaluation: { id: 0, parameters, diagnostics: [] },
+				restart: true,
+			},
+			expect.any(Function),
+		);
+		expect(client.getTemplateVersionDynamicParameters).toHaveBeenLastCalledWith(
+			"version-2",
+			expect.objectContaining({ inputs: values }),
+		);
+	});
+
+	it("evaluates once when the new version accepts every previous value", async () => {
+		const { client, ws, showForm } = setup([
+			previewParameter({ name: "region" }),
+			previewParameter({ name: "size" }),
+			previewParameter({ name: "token" }),
+			previewParameter({ name: "gpu", diagnostics: [diagnostic("Required")] }),
+		]);
+		await collectDynamicParameters(client, ws, showForm);
+
+		expect(client.getTemplateVersionDynamicParameters).toHaveBeenCalledOnce();
+		expect(showForm).toHaveBeenCalledWith(
+			expect.objectContaining({
+				values: { region: "eu", size: "retired", token: "old" },
+			}),
+			expect.any(Function),
+		);
+	});
+});
+
+describe("reviseRejectedParameters", () => {
+	it("reopens the form on the rejected values with the server's reasons", async () => {
+		const { client, ws, showForm } = setup([
+			previewParameter({ name: "region" }),
+		]);
+
+		await reviseRejectedParameters(
+			client,
+			ws,
+			[{ name: "region", value: "mars" }],
+			[
+				{ field: "region", detail: "Unknown region" },
+				{ field: "quota", detail: "Over quota" },
+			],
+			showForm,
+		);
+
+		const [init] = showForm.mock.lastCall ?? [];
+		expect(init?.values).toEqual({
+			region: "mars",
+			size: "retired",
+			token: "old",
+		});
+		expect(init?.evaluation.diagnostics).toEqual([
+			diagnostic("region: Unknown region"),
+			diagnostic("quota: Over quota"),
+		]);
+	});
+});
diff --git a/test/unit/api/workspace.test.ts b/test/unit/api/workspace.test.ts
index d7772476d6..5eb1efd479 100644
--- a/test/unit/api/workspace.test.ts
+++ b/test/unit/api/workspace.test.ts
@@ -119,6 +119,7 @@ function createUpdateCtx(
 			tasks: false,
 			onSuccessBuild: false,
 			customSessionAppNames: false,
+			dynamicParameters: false,
 			...overrides.serverFeatures,
 		},
 	};
diff --git a/test/unit/commands.updateWorkspace.test.ts b/test/unit/commands.updateWorkspace.test.ts
index b24c9b5f3d..4542f0355f 100644
--- a/test/unit/commands.updateWorkspace.test.ts
+++ b/test/unit/commands.updateWorkspace.test.ts
@@ -60,4 +60,28 @@ describe("Commands.updateWorkspace", () => {
 			}
 		},
 	);
+
+	it("shows the latest version's message in the confirmation", async () => {
+		const { commands } = setup();
+		const getTemplateVersion = vi
+			.fn()
+			.mockResolvedValue({ message: "Adds a GPU option." });
+		commands.remoteWorkspaceClient = { getTemplateVersion } as Pick<
+			CoderApi,
+			"getTemplateVersion"
+		> as CoderApi;
+
+		await commands.updateWorkspace();
+
+		expect(getTemplateVersion).toHaveBeenCalledWith(
+			commands.workspace?.template_active_version_id,
+		);
+		expect(vscode.window.showWarningMessage).toHaveBeenCalledWith(
+			"Update Workspace",
+			expect.objectContaining({
+				detail: expect.stringMatching(/\n\nAdds a GPU option\.$/),
+			}),
+			UPDATE_ACTION,
+		);
+	});
 });
diff --git a/test/unit/featureSet.test.ts b/test/unit/featureSet.test.ts
index 921108c7d7..0eca7053df 100644
--- a/test/unit/featureSet.test.ts
+++ b/test/unit/featureSet.test.ts
@@ -122,6 +122,17 @@ describe("check version support", () => {
 		expect(serverFeatureSet(parsed).customSessionAppNames).toBe(expected);
 	});
 
+	it("dynamic parameter evaluation from 2.24", () => {
+		for (const v of ["v2.23.5", "v2.0.0"]) {
+			expect(serverFeatureSet(semver.parse(v)).dynamicParameters, v).toBe(
+				false,
+			);
+		}
+		for (const v of ["v2.24.0", "v2.36.1", "v0.0.0-devel+abc123"]) {
+			expect(serverFeatureSet(semver.parse(v)).dynamicParameters, v).toBe(true);
+		}
+	});
+
 	it("enables all features for development builds", () => {
 		const featureSet = cliFeatureSet(semver.parse("v0.0.0-devel+abc123"));
 
diff --git a/test/unit/remote/workspaceStateMachine.test.ts b/test/unit/remote/workspaceStateMachine.test.ts
index 2bbfec3218..e28cb362f4 100644
--- a/test/unit/remote/workspaceStateMachine.test.ts
+++ b/test/unit/remote/workspaceStateMachine.test.ts
@@ -1,11 +1,13 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import * as vscode from "vscode";
 
+import { reviseRejectedParameters } from "@/api/dynamicParameters";
 import {
 	collectUpdateParameters,
 	WorkspaceUpdateCancelledError,
 } from "@/api/updateParameters";
 import {
+	getLatestVersionMessage,
 	startWorkspace,
 	updateWorkspace,
 	streamBuildLogs,
@@ -25,6 +27,7 @@ import {
 	TestSink,
 } from "../../mocks/telemetry";
 import {
+	createAxiosError,
 	createMockLogger,
 	createMockServiceContainer,
 	MockConfigurationProvider,
@@ -43,6 +46,7 @@ import type { CliFeatureSet } from "@/featureSet";
 import type { AuthorityParts } from "@/remote/authority";
 import type { StartupMode } from "@/storage/mementoManager";
 import type { TelemetryService } from "@/telemetry/service";
+import type { WorkspaceUpdatePanelFactory } from "@/webviews/workspaceUpdate/workspaceUpdatePanelFactory";
 
 vi.mock("@/api/workspace", async (importActual) => {
 	const { LazyStream } = await importActual<typeof import("@/api/workspace")>();
@@ -50,6 +54,7 @@ vi.mock("@/api/workspace", async (importActual) => {
 	const stream = () => Promise.resolve(new MockEventStream());
 	return {
 		LazyStream,
+		getLatestVersionMessage: vi.fn(() => Promise.resolve("")),
 		startWorkspace: vi.fn((ctx: { workspace: Workspace }) =>
 			Promise.resolve(ctx.workspace),
 		),
@@ -69,6 +74,15 @@ vi.mock("@/api/updateParameters", async (importActual) => {
 	};
 });
 
+vi.mock("@/api/dynamicParameters", async (importActual) => {
+	const actual = await importActual<typeof import("@/api/dynamicParameters")>();
+	return {
+		...actual,
+		collectDynamicParameters: vi.fn(() => Promise.resolve([])),
+		reviseRejectedParameters: vi.fn(),
+	};
+});
+
 vi.mock("@/ui/prompts", () => ({
 	maybeAskAgent: vi.fn((agents: WorkspaceAgent[]) =>
 		Promise.resolve(agents.length > 0 ? agents[0] : undefined),
@@ -95,6 +109,18 @@ const CONFIRM_MESSAGE =
 // The message shown by confirmConnectToExisting.
 const UPDATE_FAILED_MESSAGE = "Failed to update testuser/test-workspace";
 
+/** The 400 a build returns when the server rejects its parameters. */
+function parameterRejection(detail: string) {
+	const error = createAxiosError(400, "Request failed with status code 400");
+	if (error.response) {
+		error.response.data = {
+			message: "Unable to validate parameters",
+			validations: [{ field: "region", detail }],
+		};
+	}
+	return error;
+}
+
 function runningWorkspace(
 	agentOverrides: Partial<WorkspaceAgent> = {},
 	buildOverrides: Partial<Workspace["latest_build"]> = {},
@@ -108,24 +134,34 @@ function runningWorkspace(
 function setup(
 	startupMode: StartupMode = "start",
 	telemetry?: TelemetryService,
+	client: Partial<CoderApi> = {},
 ) {
 	enableLocalTelemetry();
 	const progress = new MockProgress<{ message?: string }>();
 	const userInteraction = new MockUserInteraction();
 	const sm = new WorkspaceStateMachine(
 		DEFAULT_PARTS,
-		{} as CoderApi,
+		client as CoderApi,
 		startupMode,
 		"/usr/bin/coder",
 		{} as CliFeatureSet,
-		{ tasks: false, onSuccessBuild: true, customSessionAppNames: true },
+		{
+			tasks: false,
+			onSuccessBuild: true,
+			customSessionAppNames: true,
+			dynamicParameters: true,
+		},
 		{
 			store: "cli",
 			url: "https://test.coder.com",
 			useKeyring: undefined,
 			allowRedirects: false,
 		},
-		createMockServiceContainer({ telemetry, logger: createMockLogger() }),
+		createMockServiceContainer({
+			telemetry,
+			logger: createMockLogger(),
+			workspaceUpdatePanelFactory: {} as WorkspaceUpdatePanelFactory,
+		}),
 	);
 	return { sm, progress, userInteraction };
 }
@@ -270,6 +306,54 @@ describe("WorkspaceStateMachine", () => {
 			});
 		});
 
+		it("shows the server's reasons when the build rejects the parameters", async () => {
+			vi.mocked(updateWorkspace).mockRejectedValueOnce(
+				parameterRejection("Unknown region"),
+			);
+			const { sm, progress, userInteraction } = setup("update");
+			userInteraction.setResponse(UPDATE_FAILED_MESSAGE, "Connect Anyway");
+			const ws = createWorkspace({
+				template_use_classic_parameter_flow: true,
+				latest_build: { status: "stopped" },
+			});
+
+			await sm.processWorkspace(ws, progress);
+
+			expect(userInteraction.getMessageCalls()[0].options).toMatchObject({
+				detail: "Unable to validate parameters\nregion: Unknown region",
+			});
+			expect(reviseRejectedParameters).not.toHaveBeenCalled();
+		});
+
+		it("reopens the form when the build rejects dynamic parameters", async () => {
+			const rejection = parameterRejection("Unknown region");
+			vi.mocked(updateWorkspace).mockRejectedValueOnce(rejection);
+			const revised = [{ name: "region", value: "us" }];
+			vi.mocked(reviseRejectedParameters).mockResolvedValueOnce(revised);
+			const ws = createWorkspace({
+				template_use_classic_parameter_flow: false,
+				latest_build: { status: "stopped" },
+			});
+			const { sm, progress } = setup("update", undefined, {
+				getWorkspace: vi.fn().mockResolvedValue(ws),
+			});
+
+			await sm.processWorkspace(ws, progress);
+
+			expect(reviseRejectedParameters).toHaveBeenCalledWith(
+				expect.anything(),
+				ws,
+				[],
+				[{ field: "region", detail: "Unknown region" }],
+				expect.any(Function),
+			);
+			expect(updateWorkspace).toHaveBeenLastCalledWith(
+				expect.anything(),
+				revised,
+			);
+			expect(startWorkspace).not.toHaveBeenCalled();
+		});
+
 		it("rethrows when the update fails and the user dismisses the prompt", async () => {
 			vi.mocked(updateWorkspace).mockRejectedValueOnce(
 				new Error("template not found"),
@@ -288,7 +372,10 @@ describe("WorkspaceStateMachine", () => {
 				new WorkspaceUpdateCancelledError(),
 			);
 			const { sm, progress } = setup("update");
-			const ws = createWorkspace({ latest_build: { status: "stopped" } });
+			const ws = createWorkspace({
+				template_use_classic_parameter_flow: true,
+				latest_build: { status: "stopped" },
+			});
 
 			expect(await sm.processWorkspace(ws, progress)).toBe(false);
 			expect(updateWorkspace).not.toHaveBeenCalled();
@@ -324,6 +411,24 @@ describe("WorkspaceStateMachine", () => {
 			expect(startWorkspace).not.toHaveBeenCalled();
 		});
 
+		it("shows the latest version's message when offering the update", async () => {
+			vi.mocked(getLatestVersionMessage).mockResolvedValueOnce(
+				"Adds a GPU option.",
+			);
+			const { sm, progress, userInteraction } = setup("none");
+			userInteraction.setResponse(CONFIRM_MESSAGE, "Start");
+			const ws = createWorkspace({
+				outdated: true,
+				latest_build: { status: "stopped" },
+			});
+
+			await sm.processWorkspace(ws, progress);
+
+			expect(userInteraction.getMessageCalls()[0].options).toMatchObject({
+				detail: "Adds a GPU option.",
+			});
+		});
+
 		it("does not offer 'Update and Start' when workspace is not outdated", async () => {
 			const { sm, progress, userInteraction } = setup("none");
 			userInteraction.setResponse(CONFIRM_MESSAGE, "Start");
diff --git a/test/unit/webviews/tasks/tasksPanelProvider.test.ts b/test/unit/webviews/tasks/tasksPanelProvider.test.ts
index 7e9cf2666f..5be76b182d 100644
--- a/test/unit/webviews/tasks/tasksPanelProvider.test.ts
+++ b/test/unit/webviews/tasks/tasksPanelProvider.test.ts
@@ -28,6 +28,7 @@ import {
 	createMockWebviewView,
 	MockConfigurationProvider,
 	MockUserInteraction,
+	sendWebviewRequest,
 } from "../../../mocks/testHelpers";
 
 import type {
@@ -149,31 +150,10 @@ function createHarness(): Harness {
 		client,
 		ui,
 		messages: () => [...hooks.postedMessages],
-		request: async <P, R>(
+		request: <P, R>(
 			def: RequestDef<P, R>,
 			...args: P extends void ? [] : [params: P]
-		) => {
-			const params = args[0];
-			const requestId = `req-${Date.now()}-${Math.random()}`;
-			hooks.sendFromWebview({ requestId, method: def.method, params });
-
-			await vi.waitFor(
-				() => {
-					if (
-						!hooks.postedMessages.some(
-							(m) => (m as { requestId?: string }).requestId === requestId,
-						)
-					) {
-						throw new Error("waiting");
-					}
-				},
-				{ timeout: 1000 },
-			);
-
-			return hooks.postedMessages.find(
-				(m) => (m as { requestId?: string }).requestId === requestId,
-			) as { success: boolean; data?: R; error?: string };
-		},
+		) => sendWebviewRequest(hooks, def, ...args),
 		command: async <P>(
 			def: CommandDef<P>,
 			...args: P extends void ? [] : [params: P]
diff --git a/test/unit/webviews/workspaceUpdate/workspaceUpdatePanelFactory.test.ts b/test/unit/webviews/workspaceUpdate/workspaceUpdatePanelFactory.test.ts
new file mode 100644
index 0000000000..7ad53a3326
--- /dev/null
+++ b/test/unit/webviews/workspaceUpdate/workspaceUpdatePanelFactory.test.ts
@@ -0,0 +1,85 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import * as vscode from "vscode";
+
+import { WorkspaceUpdateCancelledError } from "@/api/updateParameters";
+import { WorkspaceUpdatePanelFactory } from "@/webviews/workspaceUpdate/workspaceUpdatePanelFactory";
+
+import { previewParameter } from "@repo/mocks";
+import { WorkspaceUpdateApi, type WorkspaceUpdateInit } from "@repo/shared";
+
+import {
+	createMockLogger,
+	createMockWebviewPanel,
+	sendWebviewRequest,
+} from "../../../mocks/testHelpers";
+
+import type { EvaluateParameters } from "@/api/dynamicParameters";
+
+const EVALUATION = {
+	id: 0,
+	parameters: [previewParameter({ name: "region" })],
+	diagnostics: [],
+};
+
+const INIT: WorkspaceUpdateInit = {
+	workspaceName: "testuser/test-workspace",
+	values: { region: "eu" },
+	evaluation: EVALUATION,
+	restart: true,
+};
+
+function setup() {
+	const { panel, hooks } = createMockWebviewPanel(
+		"coder.workspaceUpdate",
+		"Update",
+		vscode.ViewColumn.One,
+	);
+	vi.mocked(vscode.window.createWebviewPanel).mockReturnValue(panel);
+	const evaluate = vi.fn<EvaluateParameters>().mockResolvedValue(EVALUATION);
+	const result = new WorkspaceUpdatePanelFactory(
+		vscode.Uri.file("/ext"),
+		createMockLogger(),
+	).show(INIT, evaluate);
+	return { panel, hooks, evaluate, result };
+}
+
+describe("WorkspaceUpdatePanelFactory", () => {
+	beforeEach(() => {
+		vi.resetAllMocks();
+	});
+
+	it("serves the initial state and evaluations to the form", async () => {
+		const { hooks, evaluate } = setup();
+
+		expect(
+			await sendWebviewRequest(hooks, WorkspaceUpdateApi.init),
+		).toMatchObject({ success: true, data: INIT });
+		expect(
+			await sendWebviewRequest(hooks, WorkspaceUpdateApi.evaluate, {
+				region: "us",
+			}),
+		).toMatchObject({ success: true, data: EVALUATION });
+		expect(evaluate).toHaveBeenCalledWith({ region: "us" });
+	});
+
+	it("resolves with the submitted values and closes", async () => {
+		const { hooks, result, panel } = setup();
+		const dispose = vi.spyOn(panel, "dispose");
+
+		hooks.sendFromWebview({
+			method: WorkspaceUpdateApi.submit.method,
+			params: { size: "small" },
+		});
+
+		expect(await result).toEqual([{ name: "size", value: "small" }]);
+		expect(dispose).toHaveBeenCalled();
+	});
+
+	it("rejects as cancelled when closed", async () => {
+		const { hooks, result } = setup();
+
+		hooks.sendFromWebview({ method: WorkspaceUpdateApi.cancel.method });
+
+		await expect(result).rejects.toBeInstanceOf(WorkspaceUpdateCancelledError);
+	});
+});
diff --git a/test/webview/ui/components/components.test.tsx b/test/webview/ui/components/components.test.tsx
index a660d87b4b..aede7aaa23 100644
--- a/test/webview/ui/components/components.test.tsx
+++ b/test/webview/ui/components/components.test.tsx
@@ -11,6 +11,7 @@ import {
 	Spinner,
 	StatusPill,
 	TooltipProvider,
+	ValidationMessage,
 } from "@repo/ui";
 
 import { qs } from "../../helpers";
@@ -110,6 +111,20 @@ describe("StatusPill", () => {
 	});
 });
 
+describe("ValidationMessage", () => {
+	it("applies the severity and forwards props", () => {
+		render(
+			<ValidationMessage severity="warning" role="status">
+				Check this value.
+			</ValidationMessage>,
+		);
+		expect(screen.getByRole("status")).toHaveTextContent("Check this value.");
+		expect(screen.getByRole("status")).toHaveClass(
+			"ui-validation-message--warning",
+		);
+	});
+});
+
 describe("state panels", () => {
 	it("renders empty state content and an optional action", () => {
 		render(
diff --git a/test/webview/workspace-update/App.test.tsx b/test/webview/workspace-update/App.test.tsx
new file mode 100644
index 0000000000..0afdf9bb34
--- /dev/null
+++ b/test/webview/workspace-update/App.test.tsx
@@ -0,0 +1,168 @@
+import { act, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, onTestFinished, vi } from "vitest";
+
+import { diagnostic, previewParameter } from "@repo/mocks";
+import App from "@repo/workspace-update/App";
+
+import { renderWithQuery } from "../render";
+
+import type {
+	FriendlyDiagnostic,
+	PreviewParameter,
+} from "coder/site/src/api/typesGenerated";
+
+import type { ParameterValues } from "@repo/shared";
+
+const { mockApi } = vi.hoisted(() => ({
+	mockApi: {
+		init: vi.fn(),
+		evaluate: vi.fn(),
+		submit: vi.fn(),
+		cancel: vi.fn(),
+	},
+}));
+
+vi.mock("@repo/workspace-update/hooks/useWorkspaceUpdateApi", () => ({
+	useWorkspaceUpdateApi: () => mockApi,
+}));
+
+vi.stubGlobal("acquireVsCodeApi", () => ({
+	postMessage: vi.fn(),
+	getState: () => undefined,
+	setState: vi.fn(),
+}));
+
+function parameter(overrides: Partial<PreviewParameter>): PreviewParameter {
+	return previewParameter({ display_name: "Region", ...overrides });
+}
+
+interface RenderOptions {
+	diagnostics?: FriendlyDiagnostic[];
+	values?: ParameterValues;
+}
+
+function renderApp(
+	parameters: PreviewParameter[],
+	{ diagnostics = [], values = { region: "eu" } }: RenderOptions = {},
+) {
+	const evaluation = { id: 0, parameters, diagnostics };
+	mockApi.init.mockResolvedValue({
+		workspaceName: "me/dev",
+		values,
+		evaluation,
+		restart: true,
+	});
+	mockApi.evaluate.mockResolvedValue(evaluation);
+	return renderWithQuery(<App />);
+}
+
+const updateButton = () =>
+	screen.getByRole("button", { name: "Update and restart" });
+
+describe("App", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("submits mutable values, using the server's value for untouched ones", async () => {
+		const user = userEvent.setup();
+		renderApp([
+			parameter({ name: "region" }),
+			parameter({
+				name: "size",
+				display_name: "Size",
+				value: { valid: true, value: "large" },
+			}),
+			parameter({ name: "image", display_name: "Image", mutable: false }),
+		]);
+
+		expect(await screen.findByRole("textbox", { name: "Region" })).toHaveValue(
+			"eu",
+		);
+		await waitFor(() => expect(updateButton()).toBeEnabled());
+		await user.click(updateButton());
+
+		expect(mockApi.evaluate).not.toHaveBeenCalled();
+		expect(mockApi.submit).toHaveBeenCalledWith({
+			region: "eu",
+			size: "large",
+		});
+	});
+
+	it("re-evaluates typed edits once typing pauses, before allowing submit", async () => {
+		// Testing Library's async utilities need the clock to keep moving.
+		vi.useFakeTimers({ shouldAdvanceTime: true });
+		onTestFinished(() => {
+			vi.useRealTimers();
+		});
+		const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+		renderApp([parameter({ name: "region" })]);
+		const region = await screen.findByRole("textbox", { name: "Region" });
+
+		await user.clear(region);
+		await user.type(region, "us");
+		expect(updateButton()).toBeDisabled();
+
+		await act(() => vi.advanceTimersByTimeAsync(500));
+		expect(mockApi.evaluate).toHaveBeenLastCalledWith({ region: "us" });
+		await waitFor(() => expect(updateButton()).toBeEnabled());
+	});
+
+	it("blocks submit and shows errors from the evaluator", async () => {
+		renderApp(
+			[
+				parameter({
+					name: "region",
+					diagnostics: [diagnostic("Unknown region")],
+				}),
+			],
+			{ diagnostics: [diagnostic("Template failed")] },
+		);
+
+		expect(await screen.findByText("Unknown region")).toBeInTheDocument();
+		expect(screen.getByRole("alert")).toHaveTextContent("Template failed");
+		expect(screen.getByRole("textbox", { name: "Region" })).toBeInvalid();
+		expect(updateButton()).toBeDisabled();
+	});
+
+	it("locks immutable parameters and blocks the update when they are invalid", async () => {
+		renderApp([
+			parameter({
+				name: "region",
+				mutable: false,
+				diagnostics: [diagnostic("No longer allowed")],
+			}),
+		]);
+
+		expect(
+			await screen.findByRole("textbox", { name: /^Region/ }),
+		).toBeDisabled();
+		expect(screen.getByRole("alert")).toHaveTextContent(
+			"Workspace update blocked",
+		);
+	});
+
+	it("sorts parameters by their order", async () => {
+		renderApp(
+			[
+				parameter({ name: "b", display_name: "B", order: 2 }),
+				parameter({ name: "a", display_name: "A", order: 1 }),
+			],
+			{ values: {} },
+		);
+
+		await screen.findByRole("textbox", { name: "A" });
+		const [first] = screen.getAllByRole("textbox");
+		expect(first).toHaveAccessibleName("A");
+	});
+
+	it("cancels the update", async () => {
+		const user = userEvent.setup();
+		renderApp([]);
+
+		await user.click(await screen.findByRole("button", { name: "Cancel" }));
+
+		expect(mockApi.cancel).toHaveBeenCalled();
+	});
+});
diff --git a/vitest.config.mts b/vitest.config.mts
index 12d2400c62..60128dffd4 100644
--- a/vitest.config.mts
+++ b/vitest.config.mts
@@ -60,6 +60,10 @@ export default defineConfig({
 							import.meta.dirname,
 							"packages/workspaces/src",
 						),
+						"@repo/workspace-update": path.resolve(
+							import.meta.dirname,
+							"packages/workspace-update/src",
+						),
 						"@repo/netcheck": path.resolve(
 							import.meta.dirname,
 							"packages/netcheck/src",