From d0ed6f01ae5d8b6c980bd9f4ddc1584e3dcb7bde Mon Sep 17 00:00:00 2001
From: Samuel K <skevetter@pm.me>
Date: Wed, 14 Oct 2026 18:45:54 -0600
Subject: [PATCH 1/5] feat(desktop): select external MicroSandbox for new
 providers

---
 .../main/__tests__/ipc-provider-jobs.test.ts  |  16 ++
 .../components/provider/ProviderWizard.svelte |  21 +-
 .../provider/ProviderWizard.test.ts           | 204 ++++++++++++++++++
 .../external-runtime-rollout.mdx              |  14 +-
 4 files changed, 243 insertions(+), 12 deletions(-)
 create mode 100644 desktop/src/renderer/src/lib/components/provider/ProviderWizard.test.ts

diff --git a/desktop/src/main/__tests__/ipc-provider-jobs.test.ts b/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
index 8a2cffd621..47fe8043a0 100644
--- a/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
+++ b/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
@@ -235,6 +235,22 @@ describe("provider job lifecycle over IPC", () => {
     expect(providerJobs.get("docker")?.activity).toBe("installing")
   })
 
+  it("adds and initializes the external Microsandbox preset without selecting a default", async () => {
+    const { cli, providerJobs } = setup()
+    const source = "github.com/devsy-org/devsy-provider-microsandbox@v0.1.8"
+
+    await invoke("provider_add", { name: "microsandbox", source })
+    await invoke("provider_init", { name: "microsandbox" })
+
+    expect(cli.runStreaming.mock.calls.map(([args]) => args)).toEqual([
+      ["provider", "add", source, "--use=false", "--name", "microsandbox"],
+      ["provider", "init", "microsandbox"],
+    ])
+    expect(cli.run).not.toHaveBeenCalled()
+    expect(cli.runRaw).not.toHaveBeenCalled()
+    expect(providerJobs.get("microsandbox")).toBeUndefined()
+  })
+
   it("releases an abandoned job so the card stops spinning", async () => {
     const { providerJobs } = setup(() => ({ lines: [], code: 0 }))
 
diff --git a/desktop/src/renderer/src/lib/components/provider/ProviderWizard.svelte b/desktop/src/renderer/src/lib/components/provider/ProviderWizard.svelte
index b51969730b..67d6ca9971 100644
--- a/desktop/src/renderer/src/lib/components/provider/ProviderWizard.svelte
+++ b/desktop/src/renderer/src/lib/components/provider/ProviderWizard.svelte
@@ -31,11 +31,17 @@ import { isCommandSuccess } from "$lib/utils/log-parser.js"
 import type { ProviderOption } from "$lib/types/index.js"
 import type { UnlistenFn } from "$lib/ipc/types.js"
 
-const PRESETS = [
+type ProviderPreset = { name: string; description: string; source?: string }
+
+const PRESETS: ProviderPreset[] = [
   { name: "docker", description: "Local Docker containers" },
   { name: "podman", description: "Local Podman containers" },
   { name: "apple", description: "Apple containers (macOS 26+, Apple silicon)" },
-  { name: "microsandbox", description: "Hardware-isolated microVMs" },
+  {
+    name: "microsandbox",
+    source: "github.com/devsy-org/devsy-provider-microsandbox@v0.1.8",
+    description: "Hardware-isolated microVMs",
+  },
   { name: "lima", description: "Linux VMs via Lima (macOS)" },
   {
     name: "orbstack",
@@ -49,6 +55,10 @@ const PRESETS = [
   { name: "digitalocean", description: "DigitalOcean Droplets" },
 ]
 
+function presetSource(preset: ProviderPreset): string {
+  return preset.source ?? preset.name
+}
+
 type Step = "select" | "configure" | "initialize" | "complete"
 type StepState = "pending" | "active" | "complete" | "error"
 
@@ -196,7 +206,8 @@ async function handleSelect() {
     error = "Provider source is required"
     return
   }
-  const name = customName.trim() || src
+  const preset = PRESETS.find((item) => presetSource(item) === src)
+  const name = customName.trim() || preset?.name || src
   if (nameExists(name)) {
     error = `Provider "${name}" already exists. Choose a different name.`
     return
@@ -381,9 +392,9 @@ function handleDone() {
               <button
                 type="button"
                 class="flex items-center gap-2.5 rounded-lg border p-3 text-left transition-colors hover:bg-accent/50
-                  {source === p.name ? 'border-primary ring-1 ring-primary' : ''}"
+                  {source === presetSource(p) ? 'border-primary ring-1 ring-primary' : ''}"
                 disabled={adding}
-                onclick={() => { source = p.name; customName = "" }}
+                onclick={() => { source = presetSource(p); customName = "" }}
               >
                 <ProviderIcon name={p.name} class="size-6 shrink-0" />
                 <div>
diff --git a/desktop/src/renderer/src/lib/components/provider/ProviderWizard.test.ts b/desktop/src/renderer/src/lib/components/provider/ProviderWizard.test.ts
new file mode 100644
index 0000000000..c150a1f5d6
--- /dev/null
+++ b/desktop/src/renderer/src/lib/components/provider/ProviderWizard.test.ts
@@ -0,0 +1,204 @@
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/svelte"
+import { get } from "svelte/store"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import { providers } from "$lib/stores/providers.js"
+import type { Provider } from "$lib/types/index.js"
+
+const {
+  providerAdd,
+  providerInitStreaming,
+  providerList,
+  providerOptions,
+  providerReleaseJob,
+  providerSetOptions,
+  onCommandProgress,
+} = vi.hoisted(() => ({
+  providerAdd: vi.fn(),
+  providerInitStreaming: vi.fn(),
+  providerList: vi.fn(),
+  providerOptions: vi.fn(),
+  providerReleaseJob: vi.fn(),
+  providerSetOptions: vi.fn(),
+  onCommandProgress: vi.fn(),
+}))
+
+vi.mock("$lib/ipc/commands.js", () => ({
+  providerAdd,
+  providerInitStreaming,
+  providerList,
+  providerOptions,
+  providerReleaseJob,
+  providerSetOptions,
+}))
+
+vi.mock("$lib/ipc/events.js", () => ({ onCommandProgress }))
+vi.mock("$lib/stores/toasts.js", () => ({
+  toasts: { error: vi.fn() },
+}))
+
+import ProviderWizard from "./ProviderWizard.svelte"
+
+const microsandboxSource =
+  "github.com/devsy-org/devsy-provider-microsandbox@v0.1.8"
+
+function makeProvider(name: string): Provider {
+  return {
+    name,
+    version: "0.1.0",
+    state: { initialized: true },
+  }
+}
+
+function renderWizard() {
+  return render(ProviderWizard, { open: true })
+}
+
+describe("ProviderWizard", () => {
+  afterEach(() => cleanup())
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    providers.set([])
+    providerAdd.mockResolvedValue(undefined)
+    providerInitStreaming.mockResolvedValue("init-command")
+    providerOptions.mockResolvedValue({})
+    providerList.mockResolvedValue([])
+    providerReleaseJob.mockResolvedValue(undefined)
+    providerSetOptions.mockResolvedValue(undefined)
+    onCommandProgress.mockImplementation(async () => () => undefined)
+  })
+
+  it("adds a fresh Microsandbox preset with the pinned source and keeps it selected", async () => {
+    const page = renderWizard()
+    const preset = screen.getByRole("button", {
+      name: /microsandbox Hardware-isolated microVMs/,
+    })
+
+    await fireEvent.click(preset)
+    expect(preset.className).toContain("ring-primary")
+    await fireEvent.click(screen.getByRole("button", { name: "Continue" }))
+
+    await waitFor(() => {
+      expect(providerAdd).toHaveBeenCalledExactlyOnceWith(
+        "microsandbox",
+        microsandboxSource,
+        false,
+      )
+    })
+    page.unmount()
+  })
+
+  it("keeps ordinary presets using their name as the source", async () => {
+    const page = renderWizard()
+    await fireEvent.click(
+      screen.getByRole("button", { name: /docker Local Docker/ }),
+    )
+    await fireEvent.click(screen.getByRole("button", { name: "Continue" }))
+
+    await waitFor(() => {
+      expect(providerAdd).toHaveBeenCalledExactlyOnceWith(
+        "docker",
+        undefined,
+        false,
+      )
+    })
+    page.unmount()
+  })
+
+  it("keeps the literal Microsandbox source available for the embedded provider", async () => {
+    const page = renderWizard()
+    await fireEvent.input(
+      screen.getByPlaceholderText("github.com/org/provider"),
+      {
+        target: { value: "microsandbox" },
+      },
+    )
+    await fireEvent.click(screen.getByRole("button", { name: "Continue" }))
+
+    await waitFor(() => {
+      expect(providerAdd).toHaveBeenCalledExactlyOnceWith(
+        "microsandbox",
+        undefined,
+        false,
+      )
+    })
+    page.unmount()
+  })
+
+  it("uses a custom name before the preset name", async () => {
+    const page = renderWizard()
+    await fireEvent.click(
+      screen.getByRole("button", {
+        name: /microsandbox Hardware-isolated microVMs/,
+      }),
+    )
+    await fireEvent.input(
+      screen.getByPlaceholderText("Defaults to source name"),
+      {
+        target: { value: "micro-lab" },
+      },
+    )
+    await fireEvent.click(screen.getByRole("button", { name: "Continue" }))
+
+    await waitFor(() => {
+      expect(providerAdd).toHaveBeenCalledExactlyOnceWith(
+        "micro-lab",
+        microsandboxSource,
+        false,
+      )
+    })
+    page.unmount()
+  })
+
+  it("does not retain the preset name after the source is edited", async () => {
+    const page = renderWizard()
+    await fireEvent.click(
+      screen.getByRole("button", {
+        name: /microsandbox Hardware-isolated microVMs/,
+      }),
+    )
+    await fireEvent.input(
+      screen.getByPlaceholderText("github.com/org/provider"),
+      {
+        target: { value: "https://example.test/provider.yaml" },
+      },
+    )
+    await fireEvent.click(screen.getByRole("button", { name: "Continue" }))
+
+    await waitFor(() => {
+      expect(providerAdd).toHaveBeenCalledExactlyOnceWith(
+        "https://example.test/provider.yaml",
+        undefined,
+        false,
+      )
+    })
+    page.unmount()
+  })
+
+  it("rejects an existing Microsandbox name before IPC and preserves the provider", async () => {
+    const existing = makeProvider("microsandbox")
+    providers.set([existing])
+    const page = renderWizard()
+    await fireEvent.click(
+      screen.getByRole("button", {
+        name: /microsandbox Hardware-isolated microVMs/,
+      }),
+    )
+    await fireEvent.click(screen.getByRole("button", { name: "Continue" }))
+
+    expect(
+      await screen.findByText(
+        'Provider "microsandbox" already exists. Choose a different name.',
+      ),
+    ).toBeTruthy()
+    expect(providerAdd).not.toHaveBeenCalled()
+    expect(get(providers)).toEqual([existing])
+    page.unmount()
+  })
+})
diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
index e8944f14e5..330a7dc2cd 100644
--- a/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
+++ b/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
@@ -1,10 +1,10 @@
 ---
 title: External MicroSandbox Runtime Rollout Decision
 sidebar_label: Runtime Rollout Decision
-description: Evidence and conditions for a future fresh-install source change to the external MicroSandbox provider.
+description: Fresh Desktop provider selection, existing-provider migration, and external MicroSandbox runtime evidence.
 ---
 
-**Status: proposed and gated.** The external provider is validated for the covered Linux/KVM scenarios, but the fresh-install choice has not changed. Existing internal providers continue to use the embedded MicroSandbox driver. A reviewed Desktop preset change can select the published source for new installations after these documented compatibility and evidence boundaries are accepted.
+**Status: fresh Desktop preset selects the published provider.** The Microsandbox preset installs the pinned external source for a new provider while retaining the name `microsandbox`. Existing internal providers continue to use the embedded MicroSandbox driver until an explicit source migration. The runtime evidence remains limited to the covered Linux/KVM scenarios.
 
 ## Current host and runtime contract
 
@@ -22,16 +22,16 @@ The registry cases exercise the published provider against an owned TLS registry
 
 The separate Windows provider-update job exercises Go archive and provider-update tests; it is not evidence of a MicroSandbox VM running on Windows. Native provider/VM evidence is Linux/amd64 with KVM only.
 
-## Proposed fresh-install change
+## Fresh Desktop installation
 
-Change only the Desktop Microsandbox preset to install the pinned source [`github.com/devsy-org/devsy-provider-microsandbox@v0.1.8`](https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.8), while retaining the provider name `microsandbox`. The existing Desktop setup path uses `provider add ... --use=false`; this preserves its current default-provider behavior. The explicit embedded source alias `microsandbox` remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.
+The Desktop Microsandbox preset installs the pinned source [`github.com/devsy-org/devsy-provider-microsandbox@v0.1.8`](https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.8), while retaining the provider name `microsandbox`. The existing Desktop setup path uses `provider add ... --use=false`; this preserves its current default-provider behavior. The explicit embedded source alias `microsandbox` remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.
 
-This proposal is fresh-install only. Existing records change source only through the supported `provider set-source` command. Changing the embedded manifest does not migrate those records. If initialization fails after a source change is committed, the new source remains selected and the provider records `InitError`; the command does not promise rollback. The running and stopped migration cases provide evidence for the tested successful transition, not for rollback after arbitrary failures.
+This choice applies only to a new provider. The wizard refuses an existing provider name before installation; it does not replace or migrate that record. Other presets and custom names retain their behavior, and entering `microsandbox` as a custom source explicitly chooses the embedded provider. Existing records change source only through the supported `provider set-source` command. Loading an internal provider refreshes its embedded Exec blocks, not its stored driver or binaries. If initialization fails after a source change is committed, the new source remains selected and the provider records `InitError`; the command does not promise rollback. The running and stopped migration cases provide evidence for the tested successful transition, not for rollback after arbitrary failures.
 
-## Limits and decision conditions
+## Evidence and compatibility limits
 
 The performance artifact from run 38628263920 records one Linux/amd64 hosted run with SDK v1.6.0 and provider v0.1.8. It observed fresh and reused `up` wall times of 13.504s and 6.335s. Four direct/supervised/supervised/direct probe runs collected one first sample and 100 warm `Info` and `Find` samples each; all 808 launches were reaped. The artifact marks `cold_cache_measured=false`. These are observations, not thresholds, cold-start results, or evidence that supervision improves performance. No process pool is proposed.
 
 Other provider-supported host profiles remain untested here. Upstream requires Apple Silicon on macOS, KVM on Linux, and WHP on Windows; this campaign does not claim runtime parity on those other hosts. The registry tests do not cover every proxy, Docker daemon/context/socket, credential-store, or temp-directory configuration. Neither the built-in driver nor the external provider guarantees removal of every effect after a failed or interrupted create; use a fresh `Find` and explicit cleanup where recovery is needed. The exact native VM artifacts surviving a particular interruption remain unproven.
 
-The source-migration review and merge gates are complete. A fresh-install preset change remains a separate reviewed implementation and must preserve these platform, performance, environment, and recovery limits. Keep the embedded provider and existing records intact until the explicit migration path and compatibility window are accepted.
+The source-migration review and merge gates are complete. The fresh Desktop selection preserves these platform, performance, environment, and recovery limits. The embedded source alias, manifest, built-in implementation and explicit built-in parity fixture remain available for existing records and deliberate embedded installs; this change removes none of them.

From 5d0f7f86ce04c7ccf10fadb6c7f8ef856255c788 Mon Sep 17 00:00:00 2001
From: Samuel K <skevetter@pm.me>
Date: Wed, 14 Oct 2026 22:11:48 -0600
Subject: [PATCH 2/5] fix(provider): preserve GitHub pins when reloading
 sources

---
 cmd/internal/check_provider_update.go         |  4 ++
 cmd/internal/check_provider_update_test.go    | 52 +++++++++++++++++++
 pkg/provider/resolve.go                       | 14 +++--
 pkg/provider/resolve_test.go                  | 39 ++++++++++++++
 pkg/workspace/provider_source_test.go         | 45 ++++++++++++++++
 pkg/workspace/provider_update_test.go         | 13 +++--
 .../external-runtime-rollout.mdx              |  2 +-
 7 files changed, 160 insertions(+), 9 deletions(-)
 create mode 100644 cmd/internal/check_provider_update_test.go
 create mode 100644 pkg/workspace/provider_source_test.go

diff --git a/cmd/internal/check_provider_update.go b/cmd/internal/check_provider_update.go
index 2d7a7421fe..aa0eaf5c60 100644
--- a/cmd/internal/check_provider_update.go
+++ b/cmd/internal/check_provider_update.go
@@ -99,6 +99,10 @@ func loadCurrentProvider(
 		return "", "", errProviderNotFound
 	}
 
+	// This probe checks latest; ordinary source reloads retain the installed pin.
+	if strings.HasPrefix(source, "github.com/") {
+		source, _ = provider.SplitSourceAndTag(source)
+	}
 	return source, currentProvider.Config.Version, nil
 }
 
diff --git a/cmd/internal/check_provider_update_test.go b/cmd/internal/check_provider_update_test.go
new file mode 100644
index 0000000000..5c86546ef4
--- /dev/null
+++ b/cmd/internal/check_provider_update_test.go
@@ -0,0 +1,52 @@
+package cmdinternal
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/devsy-org/devsy/pkg/config"
+	"github.com/devsy-org/devsy/pkg/provider"
+	"github.com/devsy-org/devsy/pkg/workspace"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLoadCurrentProviderUsesLatestGitHubSourceWithoutChangingPin(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	t.Setenv(config.EnvHome, filepath.Join(home, ".devsy"))
+	config.ResetPathManager()
+	t.Cleanup(config.ResetPathManager)
+
+	const name = "microsandbox"
+	cfg := &config.Config{
+		DefaultContext: config.DefaultContext,
+		Contexts: map[string]*config.ContextConfig{
+			config.DefaultContext: {
+				Providers: map[string]*config.ProviderConfig{name: {Initialized: true}},
+			},
+		},
+	}
+	require.NoError(t, config.SaveConfig(cfg))
+	const repo = "github.com/devsy-org/devsy-provider-microsandbox"
+	const pinned = repo + "@v0.1.8"
+	stored := &provider.ProviderConfig{
+		Name: name, Version: "v0.1.8",
+		Exec: provider.ProviderCommands{Command: []string{"true"}},
+		Source: provider.ProviderSource{
+			Github: "devsy-org/devsy-provider-microsandbox", Raw: pinned,
+		},
+	}
+	require.NoError(t, provider.SaveProviderConfig(config.DefaultContext, stored))
+	reloadSource, err := workspace.ResolveProviderSource(cfg, name)
+	require.NoError(t, err)
+	require.Equal(t, pinned, reloadSource, "a reload must retain the installed pin")
+
+	source, version, err := loadCurrentProvider(cfg, name)
+	require.NoError(t, err)
+	require.Equal(t, repo, source, "the update probe must fetch latest, not the installed pin")
+	require.Equal(t, stored.Version, version)
+	loaded, err := provider.LoadProviderConfig(config.DefaultContext, name)
+	require.NoError(t, err)
+	require.Equal(t, stored.Source, loaded.Source, "checking for updates must not mutate the pin")
+}
diff --git a/pkg/provider/resolve.go b/pkg/provider/resolve.go
index b1a745248b..132361a00c 100644
--- a/pkg/provider/resolve.go
+++ b/pkg/provider/resolve.go
@@ -229,10 +229,18 @@ func GetProviderSource(src ProviderSource, configName string) string {
 	case src.Github != "":
 		// Canonicalize to github.com/<org>/<repo> so version helpers
 		// (classifyVersionSource, parseGitHubSourcePath) recognize it.
-		if strings.HasPrefix(src.Github, "github.com/") {
-			return src.Github
+		githubSource, githubTag := SplitSourceAndTag(src.Github)
+		if !strings.HasPrefix(githubSource, "github.com/") {
+			githubSource = "github.com/" + githubSource
 		}
-		return "github.com/" + src.Github
+		_, rawTag := SplitSourceAndTag(src.Raw)
+		if rawTag != "" {
+			githubTag = rawTag
+		}
+		if githubTag != "" {
+			return githubSource + "@" + githubTag
+		}
+		return githubSource
 	default:
 		return ""
 	}
diff --git a/pkg/provider/resolve_test.go b/pkg/provider/resolve_test.go
index a5627acb3a..81a697fd57 100644
--- a/pkg/provider/resolve_test.go
+++ b/pkg/provider/resolve_test.go
@@ -23,6 +23,45 @@ func TestGetProviderSource_GithubCanonicalization(t *testing.T) {
 			src:  ProviderSource{Github: canonicalGithub},
 			want: canonicalGithub,
 		},
+		{
+			name: "pinned full GitHub path retains its tag",
+			src: ProviderSource{
+				Github: githubPath,
+				Raw:    "github.com/" + githubPath + "@v1.2.3",
+			},
+			want: canonicalGithub + "@v1.2.3",
+		},
+		{
+			name: "pinned shorthand uses canonical repository path",
+			src: ProviderSource{
+				Github: githubPath,
+				Raw:    "devsy-provider-ssh@v1.2.3",
+			},
+			want: canonicalGithub + "@v1.2.3",
+		},
+		{
+			name: "raw tag replaces a legacy GitHub tag without duplication",
+			src: ProviderSource{
+				Github: canonicalGithub + "@v1.0.0",
+				Raw:    "devsy-provider-ssh@v1.2.3",
+			},
+			want: canonicalGithub + "@v1.2.3",
+		},
+		{
+			name: "legacy GitHub field tag remains when raw is empty",
+			src: ProviderSource{
+				Github: canonicalGithub + "@v1.0.0",
+			},
+			want: canonicalGithub + "@v1.0.0",
+		},
+		{
+			name: "unpinned raw source remains canonical and unpinned",
+			src: ProviderSource{
+				Github: githubPath,
+				Raw:    "devsy-provider-ssh",
+			},
+			want: canonicalGithub,
+		},
 		{
 			name: "internal source returns raw",
 			src:  ProviderSource{Internal: true, Raw: "docker"},
diff --git a/pkg/workspace/provider_source_test.go b/pkg/workspace/provider_source_test.go
new file mode 100644
index 0000000000..e6361e94f0
--- /dev/null
+++ b/pkg/workspace/provider_source_test.go
@@ -0,0 +1,45 @@
+package workspace
+
+import (
+	"testing"
+
+	"github.com/devsy-org/devsy/pkg/config"
+	"github.com/devsy-org/devsy/pkg/provider"
+	"github.com/stretchr/testify/require"
+)
+
+func TestResolveProviderSourcePreservesPersistedGitHubPin(t *testing.T) {
+	setupTestPathManager(t)
+	t.Setenv(config.EnvHome, t.TempDir())
+	config.ResetPathManager()
+
+	const providerName = "pinned-microsandbox"
+	devsyConfig := &config.Config{
+		DefaultContext: testDefaultContext,
+		Contexts: map[string]*config.ContextConfig{
+			testDefaultContext: {
+				Providers: map[string]*config.ProviderConfig{
+					providerName: {},
+				},
+			},
+		},
+	}
+	require.NoError(t, config.SaveConfig(devsyConfig))
+	require.NoError(t, provider.SaveProviderConfig(testDefaultContext, &provider.ProviderConfig{
+		Name:    providerName,
+		Version: "v0.1.8",
+		Exec:    provider.ProviderCommands{Command: []string{"true"}},
+		Source: provider.ProviderSource{
+			Github: "devsy-org/devsy-provider-microsandbox",
+			Raw:    "devsy-provider-microsandbox@v0.1.8",
+		},
+	}))
+
+	source, err := ResolveProviderSource(devsyConfig, providerName)
+	require.NoError(t, err)
+	require.Equal(
+		t,
+		"github.com/devsy-org/devsy-provider-microsandbox@v0.1.8",
+		source,
+	)
+}
diff --git a/pkg/workspace/provider_update_test.go b/pkg/workspace/provider_update_test.go
index a4eecf934e..e75e5fce58 100644
--- a/pkg/workspace/provider_update_test.go
+++ b/pkg/workspace/provider_update_test.go
@@ -119,11 +119,14 @@ func TestProviderVersionNeedsUpdate(t *testing.T) {
 func TestProviderUpdateSkipReasonResolvedGitHubSource(t *testing.T) {
 	original := provider.ProviderSource{Github: "org/provider", Raw: "org/provider@v1.0.0"}
 	changed := provider.ProviderSource{Github: "org/provider", Raw: "org/provider@v1.1.0"}
-	assert.Equal(
-		t,
-		provider.GetProviderSource(original, "provider"),
-		provider.GetProviderSource(changed, "provider"),
-	)
+	originalSource := provider.GetProviderSource(original, "provider")
+	changedSource := provider.GetProviderSource(changed, "provider")
+	originalBase, originalTag := provider.SplitSourceAndTag(originalSource)
+	changedBase, changedTag := provider.SplitSourceAndTag(changedSource)
+	assert.Equal(t, "github.com/org/provider", originalBase)
+	assert.Equal(t, originalBase, changedBase)
+	assert.Equal(t, "v1.0.0", originalTag)
+	assert.Equal(t, "v1.1.0", changedTag)
 	assert.Equal(t, "provider source changed", providerUpdateSkipReason(
 		original, changed, "v1.0.0", "v1.2.0",
 	))
diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
index 330a7dc2cd..0249633425 100644
--- a/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
+++ b/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
@@ -24,7 +24,7 @@ The separate Windows provider-update job exercises Go archive and provider-updat
 
 ## Fresh Desktop installation
 
-The Desktop Microsandbox preset installs the pinned source [`github.com/devsy-org/devsy-provider-microsandbox@v0.1.8`](https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.8), while retaining the provider name `microsandbox`. The existing Desktop setup path uses `provider add ... --use=false`; this preserves its current default-provider behavior. The explicit embedded source alias `microsandbox` remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.
+The Desktop Microsandbox preset installs the pinned source [`github.com/devsy-org/devsy-provider-microsandbox@v0.1.8`](https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.8), while retaining the provider name `microsandbox`. Reloading this provider without a replacement source retains the pinned tag. The existing Desktop setup path uses `provider add ... --use=false`; this preserves its current default-provider behavior. The explicit embedded source alias `microsandbox` remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.
 
 This choice applies only to a new provider. The wizard refuses an existing provider name before installation; it does not replace or migrate that record. Other presets and custom names retain their behavior, and entering `microsandbox` as a custom source explicitly chooses the embedded provider. Existing records change source only through the supported `provider set-source` command. Loading an internal provider refreshes its embedded Exec blocks, not its stored driver or binaries. If initialization fails after a source change is committed, the new source remains selected and the provider records `InitError`; the command does not promise rollback. The running and stopped migration cases provide evidence for the tested successful transition, not for rollback after arbitrary failures.
 

From bd1293119090ee097e801b27e1694eb03413fdc4 Mon Sep 17 00:00:00 2001
From: Samuel K <skevetter@pm.me>
Date: Wed, 14 Oct 2026 23:30:37 -0600
Subject: [PATCH 3/5] fix(desktop): install confirmed versions for pinned
 providers

---
 .../main/__tests__/ipc-provider-jobs.test.ts  |  28 ++++
 desktop/src/main/ipc.ts                       |  36 +++--
 .../components/provider/ProviderSheet.svelte  |  11 +-
 .../components/provider/ProviderSheet.test.ts | 137 ++++++++++++++++--
 .../provider/UpdateConfirmDialog.svelte       |   4 +-
 .../src/renderer/src/lib/ipc/commands.test.ts |  20 +++
 desktop/src/renderer/src/lib/ipc/commands.ts  |   7 +-
 .../external-runtime-rollout.mdx              |   2 +-
 8 files changed, 211 insertions(+), 34 deletions(-)

diff --git a/desktop/src/main/__tests__/ipc-provider-jobs.test.ts b/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
index 47fe8043a0..79dd73114d 100644
--- a/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
+++ b/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
@@ -284,6 +284,34 @@ describe("provider job lifecycle over IPC", () => {
     expect(providerJobs.get("docker")).toBeUndefined()
   })
 
+  it.each(["provider_update", "provider_update_streaming"])(
+    "%s installs the confirmed version before initializing",
+    async (command) => {
+      const seen: string[][] = []
+      const { providerJobs } = setup((cliArgs) => {
+        seen.push(cliArgs)
+        return { lines: [], code: 0 }
+      })
+
+      await invoke(command, { name: "microsandbox", tag: "v0.2.0" })
+
+      await vi.waitFor(() =>
+        expect(providerJobs.get("microsandbox")).toBeUndefined(),
+      )
+      expect(seen).toEqual([
+        [
+          "provider",
+          "set-source",
+          "microsandbox",
+          "--use=false",
+          "--version",
+          "v0.2.0",
+        ],
+        ["provider", "init", "microsandbox"],
+      ])
+    },
+  )
+
   it("records the failure when the update's chained init fails", async () => {
     const { providerJobs } = setup((cliArgs) => ({
       lines: [],
diff --git a/desktop/src/main/ipc.ts b/desktop/src/main/ipc.ts
index ce3ec0d65d..bcc5a423dc 100644
--- a/desktop/src/main/ipc.ts
+++ b/desktop/src/main/ipc.ts
@@ -1295,21 +1295,25 @@ export function registerIpcHandlers(deps: IpcDependencies): {
   // set-source installs replacement binaries and clears Initialized, since
   // the new binary has not run its init. Chain init so the provider ends up
   // usable rather than sitting in a needs-re-init state the user must notice.
-  ipcMain.handle("provider_update", async (_event, args: { name: string }) => {
-    await withProviderJob(args.name, "updating", async () => {
-      await runProviderWithStatus(args.name, [
-        "provider",
-        "set-source",
-        args.name,
-        "--use=false",
-      ])
-      await runProviderWithStatus(args.name, ["provider", "init", args.name])
-    })
-  })
+  ipcMain.handle(
+    "provider_update",
+    async (_event, args: { name: string; tag?: string }) => {
+      await withProviderJob(args.name, "updating", async () => {
+        await runProviderWithStatus(args.name, [
+          "provider",
+          "set-source",
+          args.name,
+          "--use=false",
+          ...(args.tag ? ["--version", args.tag] : []),
+        ])
+        await runProviderWithStatus(args.name, ["provider", "init", args.name])
+      })
+    },
+  )
 
   ipcMain.handle(
     "provider_update_streaming",
-    async (_event, args: { name: string }) => {
+    async (_event, args: { name: string; tag?: string }) => {
       const cmdId = crypto.randomUUID()
       const win = deps.getMainWindow()
       providerJobs.start(args.name, "updating")
@@ -1366,7 +1370,13 @@ export function registerIpcHandlers(deps: IpcDependencies): {
         let failure: CLIError | undefined
         try {
           sendProgress("Downloading provider update", "info")
-          await runStep(["provider", "set-source", args.name, "--use=false"])
+          await runStep([
+            "provider",
+            "set-source",
+            args.name,
+            "--use=false",
+            ...(args.tag ? ["--version", args.tag] : []),
+          ])
           sendProgress("Initializing updated provider", "info")
           await runStep(["provider", "init", args.name])
         } catch (error) {
diff --git a/desktop/src/renderer/src/lib/components/provider/ProviderSheet.svelte b/desktop/src/renderer/src/lib/components/provider/ProviderSheet.svelte
index 1d8d73939e..64426982f3 100644
--- a/desktop/src/renderer/src/lib/components/provider/ProviderSheet.svelte
+++ b/desktop/src/renderer/src/lib/components/provider/ProviderSheet.svelte
@@ -277,7 +277,16 @@ async function runUpdate() {
   updateLines = []
   confirmUpdateOpen = false
   try {
-    updateCommandId = await providerUpdateStreaming(name)
+    const latestVersion = $providerVersions.updates[name]?.latest
+    const source = provider.source
+    const isPinnedGithub =
+      !!source?.github &&
+      (source.github.includes("@") || source.raw?.includes("@"))
+    if (isPinnedGithub && latestVersion) {
+      updateCommandId = await providerUpdateStreaming(name, latestVersion)
+    } else {
+      updateCommandId = await providerUpdateStreaming(name)
+    }
     const matching = pendingUpdateProgress.filter(
       (progress) => progress.commandId === updateCommandId,
     )
diff --git a/desktop/src/renderer/src/lib/components/provider/ProviderSheet.test.ts b/desktop/src/renderer/src/lib/components/provider/ProviderSheet.test.ts
index b8a728ac22..85294a4d60 100644
--- a/desktop/src/renderer/src/lib/components/provider/ProviderSheet.test.ts
+++ b/desktop/src/renderer/src/lib/components/provider/ProviderSheet.test.ts
@@ -1,12 +1,17 @@
 import { render } from "@testing-library/svelte"
 import { tick } from "svelte"
+import type { Readable, Writable } from "svelte/store"
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+import type { providerVersions as providerVersionsStore } from "$lib/stores/providerVersions.js"
 import type {
   CommandProgress,
   Provider,
   ProviderJob,
 } from "$lib/types/index.js"
 
+type ProviderVersionsState =
+  typeof providerVersionsStore extends Readable<infer State> ? State : never
+
 const providerOptions = vi.fn()
 const providerUse = vi.fn()
 const providerUpdateStreaming = vi.fn()
@@ -24,6 +29,9 @@ const providerJobsBox = vi.hoisted(() => ({
     Record<string, ProviderJob>
   >,
 }))
+const providerVersionsBox = vi.hoisted(() => ({
+  store: undefined as unknown as Writable<ProviderVersionsState>,
+}))
 let progressCallback: ((progress: CommandProgress) => void) | null = null
 
 vi.mock("$lib/ipc/commands.js", () => ({
@@ -62,22 +70,30 @@ vi.mock("$lib/stores/providers.js", async () => {
 
 vi.mock("$lib/stores/providerVersions.js", async () => {
   const { writable } = await import("svelte/store")
-  return {
-    providerVersions: writable({
-      byProvider: {
-        ssh: {
-          versions: [
-            { tag: "0.1.0", current: true },
-            { tag: "0.2.0", current: false },
-          ],
-          unsupported: false,
-        },
+  providerVersionsBox.store = writable<ProviderVersionsState>({
+    byProvider: {
+      ssh: {
+        versions: [
+          { tag: "0.1.0", current: true, publishedAt: "", prerelease: false },
+          { tag: "0.2.0", current: false, publishedAt: "", prerelease: false },
+        ],
+        unsupported: false,
       },
-      updates: {
-        ssh: { updateAvailable: true, current: "0.1.0", latest: "0.2.0" },
+    },
+    updates: {
+      ssh: {
+        updateAvailable: true,
+        current: "0.1.0",
+        latest: "0.2.0",
+        unsupported: false,
       },
-      lastCheckedAt: null,
-    }),
+    },
+    lastCheckedAt: null,
+    refreshing: false,
+    refreshError: null,
+  })
+  return {
+    providerVersions: providerVersionsBox.store,
     loadVersionsFor: (...args: unknown[]) => loadVersionsFor(...args),
     refreshUpdates: (...args: unknown[]) => refreshUpdates(...args),
   }
@@ -116,6 +132,17 @@ describe("ProviderSheet", () => {
   beforeEach(() => {
     progressCallback = null
     providerJobsBox.store.set({})
+    providerVersionsBox.store.update((state) => ({
+      ...state,
+      updates: {
+        ssh: {
+          updateAvailable: true,
+          current: "0.1.0",
+          latest: "0.2.0",
+          unsupported: false,
+        },
+      },
+    }))
     providerOptions.mockReset()
     providerOptions.mockImplementation(async (name: string) => {
       await new Promise((r) => setTimeout(r, MOCK_IPC_DELAY_MS))
@@ -312,7 +339,15 @@ describe("ProviderSheet", () => {
 
   it("confirming the update dialog starts one streaming provider update", async () => {
     const { unmount } = render(ProviderSheet, {
-      props: { provider: makeProvider("ssh"), open: true },
+      props: {
+        provider: makeProvider("ssh", {
+          source: {
+            github: "github.com/example/ssh-provider",
+            raw: "github.com/example/ssh-provider@0.1.0",
+          },
+        }),
+        open: true,
+      },
     })
 
     await flushAsync()
@@ -333,6 +368,78 @@ describe("ProviderSheet", () => {
     confirmBtn?.click()
     await flushAsync()
 
+    expect(providerUpdateStreaming).toHaveBeenCalledTimes(1)
+    expect(providerUpdateStreaming).toHaveBeenCalledWith("ssh", "0.2.0")
+    unmount()
+  })
+
+  it("leaves an unpinned GitHub update on the latest-release path", async () => {
+    const { unmount } = render(ProviderSheet, {
+      props: {
+        provider: makeProvider("ssh", {
+          source: { github: "github.com/example/ssh-provider" },
+        }),
+        open: true,
+      },
+    })
+
+    await flushAsync()
+    Array.from(document.querySelectorAll("button"))
+      .find((button) => button.textContent?.trim() === "Update")
+      ?.click()
+    await tick()
+    const confirmDialog = Array.from(
+      document.querySelectorAll("[role='dialog']"),
+    ).find((dialog) => dialog.textContent?.includes("Update 'ssh' to 0.2.0"))
+    Array.from(confirmDialog?.querySelectorAll("button") ?? [])
+      .find((button) => button.textContent?.trim() === "Update")
+      ?.click()
+    await flushAsync()
+
+    expect(providerUpdateStreaming).toHaveBeenCalledTimes(1)
+    expect(providerUpdateStreaming).toHaveBeenCalledWith("ssh")
+    unmount()
+  })
+
+  it("reloads the configured source when the latest version is unknown", async () => {
+    providerVersionsBox.store.update((state) => ({
+      ...state,
+      updates: {
+        ssh: {
+          current: "0.1.0",
+          latest: "",
+          updateAvailable: false,
+          unsupported: false,
+        },
+      },
+    }))
+    const { unmount } = render(ProviderSheet, {
+      props: {
+        provider: makeProvider("ssh", {
+          source: {
+            github: "github.com/example/ssh-provider",
+            raw: "github.com/example/ssh-provider@0.1.0",
+          },
+        }),
+        open: true,
+      },
+    })
+
+    await flushAsync()
+    Array.from(document.querySelectorAll("button"))
+      .find((button) => button.textContent?.trim() === "Update")
+      ?.click()
+    await tick()
+
+    const confirmDialog = Array.from(
+      document.querySelectorAll("[role='dialog']"),
+    ).find((dialog) => dialog.textContent?.includes("configured source"))
+    expect(confirmDialog).toBeDefined()
+    Array.from(confirmDialog?.querySelectorAll("button") ?? [])
+      .find((button) => button.textContent?.trim() === "Update")
+      ?.click()
+    await flushAsync()
+
     expect(providerUpdateStreaming).toHaveBeenCalledTimes(1)
     expect(providerUpdateStreaming).toHaveBeenCalledWith("ssh")
     unmount()
diff --git a/desktop/src/renderer/src/lib/components/provider/UpdateConfirmDialog.svelte b/desktop/src/renderer/src/lib/components/provider/UpdateConfirmDialog.svelte
index 9b6938577c..6823746fa7 100644
--- a/desktop/src/renderer/src/lib/components/provider/UpdateConfirmDialog.svelte
+++ b/desktop/src/renderer/src/lib/components/provider/UpdateConfirmDialog.svelte
@@ -37,9 +37,9 @@ let description = $derived.by(() => {
     return `This will update ${providerName} from ${currentVersion} to ${latestVersion}, then re-initialize it.`
   }
   if (currentVersion) {
-    return `Currently on ${currentVersion}. DevSy could not determine the latest version. This update will re-fetch and re-initialize the provider.`
+    return `Currently on ${currentVersion}. DevSy could not determine the latest version. This will re-fetch the configured source and re-initialize the provider.`
   }
-  return "Check for and install the latest version, then re-initialize the provider."
+  return "Re-fetch the configured source and re-initialize the provider."
 })
 </script>
 
diff --git a/desktop/src/renderer/src/lib/ipc/commands.test.ts b/desktop/src/renderer/src/lib/ipc/commands.test.ts
index f1ff9808ad..6b9c4c3953 100644
--- a/desktop/src/renderer/src/lib/ipc/commands.test.ts
+++ b/desktop/src/renderer/src/lib/ipc/commands.test.ts
@@ -18,6 +18,7 @@ import {
   openDirectoryDialog,
   providerAdd,
   providerSetOptions,
+  providerUpdateStreaming,
   secretAttach,
   secretDelete,
   secretDetach,
@@ -41,6 +42,25 @@ describe("IPC commands", () => {
     mockInvoke.mockResolvedValue(undefined)
   })
 
+  it("forwards a confirmed provider version without replacing its identity", async () => {
+    mockInvoke.mockResolvedValue("update-command")
+    expect(await providerUpdateStreaming("microsandbox", "v0.2.0")).toBe(
+      "update-command",
+    )
+    expect(mockInvoke).toHaveBeenCalledWith("provider_update_streaming", {
+      name: "microsandbox",
+      tag: "v0.2.0",
+    })
+  })
+
+  it("leaves provider refreshes without a confirmed version unversioned", async () => {
+    await providerUpdateStreaming("microsandbox")
+    expect(mockInvoke).toHaveBeenCalledWith("provider_update_streaming", {
+      name: "microsandbox",
+      tag: undefined,
+    })
+  })
+
   describe("workspace commands", () => {
     it("workspaceUp passes all parameters", async () => {
       mockInvoke.mockResolvedValue("cmd-123")
diff --git a/desktop/src/renderer/src/lib/ipc/commands.ts b/desktop/src/renderer/src/lib/ipc/commands.ts
index 28783a3b2b..11f00fb152 100644
--- a/desktop/src/renderer/src/lib/ipc/commands.ts
+++ b/desktop/src/renderer/src/lib/ipc/commands.ts
@@ -169,8 +169,11 @@ export async function providerReleaseJob(name: string): Promise<void> {
   return invoke<void>("provider_release_job", { name })
 }
 
-export async function providerUpdateStreaming(name: string): Promise<string> {
-  return invoke<string>("provider_update_streaming", { name })
+export async function providerUpdateStreaming(
+  name: string,
+  tag?: string,
+): Promise<string> {
+  return invoke<string>("provider_update_streaming", { name, tag })
 }
 
 export async function providerRefreshState(name: string): Promise<void> {
diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
index 0249633425..4ad430c1cb 100644
--- a/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
+++ b/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
@@ -24,7 +24,7 @@ The separate Windows provider-update job exercises Go archive and provider-updat
 
 ## Fresh Desktop installation
 
-The Desktop Microsandbox preset installs the pinned source [`github.com/devsy-org/devsy-provider-microsandbox@v0.1.8`](https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.8), while retaining the provider name `microsandbox`. Reloading this provider without a replacement source retains the pinned tag. The existing Desktop setup path uses `provider add ... --use=false`; this preserves its current default-provider behavior. The explicit embedded source alias `microsandbox` remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.
+The Desktop Microsandbox preset installs the pinned source [`github.com/devsy-org/devsy-provider-microsandbox@v0.1.8`](https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.8), while retaining the provider name `microsandbox`. Reloading this provider without a replacement source retains the pinned tag. A Desktop update to a displayed version explicitly selects that version; refreshing without a known target retains the configured pin. The existing Desktop setup path uses `provider add ... --use=false`; this preserves its current default-provider behavior. The explicit embedded source alias `microsandbox` remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.
 
 This choice applies only to a new provider. The wizard refuses an existing provider name before installation; it does not replace or migrate that record. Other presets and custom names retain their behavior, and entering `microsandbox` as a custom source explicitly chooses the embedded provider. Existing records change source only through the supported `provider set-source` command. Loading an internal provider refreshes its embedded Exec blocks, not its stored driver or binaries. If initialization fails after a source change is committed, the new source remains selected and the provider records `InitError`; the command does not promise rollback. The running and stopped migration cases provide evidence for the tested successful transition, not for rollback after arbitrary failures.
 

From 0ec54d985fe28e316f49affa3a5f01c2d8b9c04f Mon Sep 17 00:00:00 2001
From: Samuel K <skevetter@pm.me>
Date: Thu, 15 Oct 2026 03:24:14 -0600
Subject: [PATCH 4/5] docs(runtime): scope confirmed updates to pinned GitHub
 providers

---
 .../docs/developing-providers/external-runtime-rollout.mdx      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx b/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
index 4ad430c1cb..3da6891cec 100644
--- a/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
+++ b/sites/docs-devsy-sh/content/docs/developing-providers/external-runtime-rollout.mdx
@@ -24,7 +24,7 @@ The separate Windows provider-update job exercises Go archive and provider-updat
 
 ## Fresh Desktop installation
 
-The Desktop Microsandbox preset installs the pinned source [`github.com/devsy-org/devsy-provider-microsandbox@v0.1.8`](https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.8), while retaining the provider name `microsandbox`. Reloading this provider without a replacement source retains the pinned tag. A Desktop update to a displayed version explicitly selects that version; refreshing without a known target retains the configured pin. The existing Desktop setup path uses `provider add ... --use=false`; this preserves its current default-provider behavior. The explicit embedded source alias `microsandbox` remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.
+The Desktop Microsandbox preset installs the pinned source [`github.com/devsy-org/devsy-provider-microsandbox@v0.1.8`](https://github.com/devsy-org/devsy-provider-microsandbox/releases/tag/v0.1.8), while retaining the provider name `microsandbox`. Reloading this provider without a replacement source retains the pinned tag. For an already pinned GitHub provider, a Desktop update to a displayed version explicitly selects that version; refreshing without a known target retains the configured pin. The existing Desktop setup path uses `provider add ... --use=false`; this preserves its current default-provider behavior. The explicit embedded source alias `microsandbox` remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.
 
 This choice applies only to a new provider. The wizard refuses an existing provider name before installation; it does not replace or migrate that record. Other presets and custom names retain their behavior, and entering `microsandbox` as a custom source explicitly chooses the embedded provider. Existing records change source only through the supported `provider set-source` command. Loading an internal provider refreshes its embedded Exec blocks, not its stored driver or binaries. If initialization fails after a source change is committed, the new source remains selected and the provider records `InitError`; the command does not promise rollback. The running and stopped migration cases provide evidence for the tested successful transition, not for rollback after arbitrary failures.
 

From d46ee6f22dc33d0c22acd65afa581ff6f1224ae4 Mon Sep 17 00:00:00 2001
From: Samuel K <skevetter@pm.me>
Date: Thu, 15 Oct 2026 04:52:48 -0600
Subject: [PATCH 5/5] fix(desktop): validate provider version tags before jobs

---
 .../main/__tests__/ipc-provider-jobs.test.ts  | 71 +++++++++++++++++++
 desktop/src/main/ipc.ts                       | 26 +++++--
 2 files changed, 90 insertions(+), 7 deletions(-)

diff --git a/desktop/src/main/__tests__/ipc-provider-jobs.test.ts b/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
index 79dd73114d..aee88e154d 100644
--- a/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
+++ b/desktop/src/main/__tests__/ipc-provider-jobs.test.ts
@@ -312,6 +312,77 @@ describe("provider job lifecycle over IPC", () => {
     },
   )
 
+  it.each(["provider_update", "provider_update_streaming"])(
+    "%s rejects a non-string version before opening a job",
+    async (command) => {
+      const { providerJobs, cli } = setup()
+
+      await expect(
+        invoke(command, { name: "docker", tag: { version: "v1" } }),
+      ).rejects.toThrow("Provider version tag must be a string.")
+
+      expect(providerJobs.get("docker")).toBeUndefined()
+      expect(cli.runRaw).not.toHaveBeenCalled()
+      expect(cli.runStreaming).not.toHaveBeenCalled()
+    },
+  )
+
+  it.each(["provider_update", "provider_update_streaming"])(
+    "%s treats an empty optional version as source reload",
+    async (command) => {
+      const seen: string[][] = []
+      const { providerJobs } = setup((cliArgs) => {
+        seen.push(cliArgs)
+        return { lines: [], code: 0 }
+      })
+
+      await invoke(command, { name: "docker", tag: "" })
+      await vi.waitFor(() => expect(providerJobs.get("docker")).toBeUndefined())
+
+      expect(seen).toEqual([
+        ["provider", "set-source", "docker", "--use=false"],
+        ["provider", "init", "docker"],
+      ])
+    },
+  )
+
+  it.each([undefined, "", 42])(
+    "provider_set_version rejects invalid required tag %s before opening a job",
+    async (tag) => {
+      const { providerJobs, cli } = setup()
+
+      await expect(
+        invoke("provider_set_version", { name: "docker", tag }),
+      ).rejects.toThrow(
+        tag === undefined || tag === ""
+          ? "A provider version tag is required."
+          : "Provider version tag must be a string.",
+      )
+
+      expect(providerJobs.get("docker")).toBeUndefined()
+      expect(cli.runStreaming).not.toHaveBeenCalled()
+    },
+  )
+
+  it("passes valid Git ref syntax as a separate set-version argument", async () => {
+    const seen: string[][] = []
+    const { providerJobs } = setup((cliArgs) => {
+      seen.push(cliArgs)
+      return { lines: [], code: 0 }
+    })
+
+    await invoke("provider_set_version", {
+      name: "docker",
+      tag: "release/candidate+1",
+    })
+    await vi.waitFor(() => expect(providerJobs.get("docker")).toBeUndefined())
+
+    expect(seen).toEqual([
+      ["provider", "set-source", "docker", "--version", "release/candidate+1"],
+      ["provider", "init", "docker"],
+    ])
+  })
+
   it("records the failure when the update's chained init fails", async () => {
     const { providerJobs } = setup((cliArgs) => ({
       lines: [],
diff --git a/desktop/src/main/ipc.ts b/desktop/src/main/ipc.ts
index bcc5a423dc..b18b6ed6b3 100644
--- a/desktop/src/main/ipc.ts
+++ b/desktop/src/main/ipc.ts
@@ -80,6 +80,16 @@ function validateSecretUnlockInput(args: unknown): SecretUnlockInput {
   return { ok: true, requestId: input.requestId, passphrase, remember }
 }
 
+function providerVersionFlags(tag: unknown, required = false): string[] {
+  if (tag === undefined || tag === "") {
+    if (!required) return []
+    throw new Error("A provider version tag is required.")
+  }
+  if (typeof tag !== "string")
+    throw new Error("Provider version tag must be a string.")
+  return ["--version", tag]
+}
+
 interface SecretEntry {
   name: string
   context: string
@@ -1297,14 +1307,15 @@ export function registerIpcHandlers(deps: IpcDependencies): {
   // usable rather than sitting in a needs-re-init state the user must notice.
   ipcMain.handle(
     "provider_update",
-    async (_event, args: { name: string; tag?: string }) => {
+    async (_event, args: { name: string; tag?: unknown }) => {
+      const versionFlags = providerVersionFlags(args.tag)
       await withProviderJob(args.name, "updating", async () => {
         await runProviderWithStatus(args.name, [
           "provider",
           "set-source",
           args.name,
           "--use=false",
-          ...(args.tag ? ["--version", args.tag] : []),
+          ...versionFlags,
         ])
         await runProviderWithStatus(args.name, ["provider", "init", args.name])
       })
@@ -1313,7 +1324,8 @@ export function registerIpcHandlers(deps: IpcDependencies): {
 
   ipcMain.handle(
     "provider_update_streaming",
-    async (_event, args: { name: string; tag?: string }) => {
+    async (_event, args: { name: string; tag?: unknown }) => {
+      const versionFlags = providerVersionFlags(args.tag)
       const cmdId = crypto.randomUUID()
       const win = deps.getMainWindow()
       providerJobs.start(args.name, "updating")
@@ -1375,7 +1387,7 @@ export function registerIpcHandlers(deps: IpcDependencies): {
             "set-source",
             args.name,
             "--use=false",
-            ...(args.tag ? ["--version", args.tag] : []),
+            ...versionFlags,
           ])
           sendProgress("Initializing updated provider", "info")
           await runStep(["provider", "init", args.name])
@@ -1486,7 +1498,8 @@ export function registerIpcHandlers(deps: IpcDependencies): {
 
   ipcMain.handle(
     "provider_set_version",
-    async (_event, args: { name: string; tag: string }) => {
+    async (_event, args: { name: string; tag?: unknown }) => {
+      const versionFlags = providerVersionFlags(args.tag, true)
       // Pinning a version swaps binaries via the same update path, so it
       // clears Initialized and needs the same re-init as a source change.
       await withProviderJob(args.name, "updating", async () => {
@@ -1494,8 +1507,7 @@ export function registerIpcHandlers(deps: IpcDependencies): {
           "provider",
           "set-source",
           args.name,
-          "--version",
-          args.tag,
+          ...versionFlags,
         ])
         await runProviderWithStatus(args.name, ["provider", "init", args.name])
       })