refactor(app): restore explicit persistence initial state

test(app): remove leaking UI context mocks
fix(app): preserve persisted state compatibility
2026-09-01 14:36:20 +00:00 · 2026-09-01 17:41:49 +08:00 · 2026-09-01 16:44:14 +08:00 · 2026-09-01 16:34:37 +08:00 · 2026-09-01 16:17:40 +08:00 · 2026-09-01 15:19:59 +08:00
156 changed files with 4946 additions and 2349 deletions
@@ -969,6 +969,7 @@
        "mime-types": "3.0.2",
        "minimatch": "10.2.5",
        "npm-package-arg": "13.0.2",
+        "pacote": "21.5.1",
        "resolve.exports": "catalog:",
      },
      "devDependencies": {
@@ -978,6 +979,7 @@
        "@types/node": "catalog:",
        "@types/npm-package-arg": "6.1.4",
        "@types/npmcli__arborist": "6.3.3",
+        "@types/pacote": "11.1.8",
        "@typescript/native-preview": "catalog:",
      },
    },
@@ -1,8 +1,8 @@
 {
  "nodeModules": {
-    "x86_64-linux": "sha256-JStMvgtXBA5GrhyBJ5FtdqD8LWkcaPA9NXef+c2xUzw=",
-    "aarch64-linux": "sha256-WQxF+yS0ZImW0KW620XnZUBsKAJDoJ1jLDOMBaXI2/E=",
-    "aarch64-darwin": "sha256-km7G6s45dfFdW3Z6lFrs4NohD+vmwN1vR8PmEL0WCto=",
-    "x86_64-darwin": "sha256-YFbkcHpuspgTp+B+th3IJ3cnu5C2gEUSiy3NDXpD8UA="
+    "x86_64-linux": "sha256-nV2bI91uUqHJugt1mERgYNCn/zqWJ21YXc5YozwQ+Ss=",
+    "aarch64-linux": "sha256-s/0PghIWeRHsMw9Re84sQ8qW5IZwyhXrhmYlUy2xkt4=",
+    "aarch64-darwin": "sha256-FAm7Bk3NPikHYmmJFwB+0V3saRZqlyxDHuM8gasN3zA=",
+    "x86_64-darwin": "sha256-kdYwYQhubvO9CtVsuHsGnIJ9/byWQ5FMFCLRoScQ614="
  }
 }
@@ -123,7 +123,7 @@ async function setup(page: Page) {
  })

  await page.addInitScript(
-    ({ directory, server, sessionID }) => {
+    ({ directory, server, sessionID, tabKey }) => {
      localStorage.setItem(
        "opencode.global.dat:server",
        JSON.stringify({
@@ -131,10 +131,8 @@ async function setup(page: Page) {
          lastProject: { local: directory },
        }),
      )
-      localStorage.setItem(
-        "opencode.global.dat:layout",
-        JSON.stringify({ review: { diffStyle: "split", panelOpened: true } }),
-      )
+      localStorage.setItem("opencode.global.dat:layout", JSON.stringify({ review: { diffStyle: "split" } }))
+      localStorage.setItem("opencode.window.browser.dat:tabs.panes", JSON.stringify({ [tabKey]: { review: true } }))
      localStorage.setItem(
        "opencode.global.dat:review-panel-v2",
        JSON.stringify({ sidebarOpened: true, sidebarWidth: 240, expandMode: "collapse" }),
@@ -144,6 +142,6 @@ async function setup(page: Page) {
        JSON.stringify([{ type: "session", server, sessionId: sessionID }]),
      )
    },
-    { directory, server, sessionID },
+    { directory, server, sessionID, tabKey: `${server}\n/server/${base64Encode(server)}/session/${sessionID}` },
  )
 }
@@ -80,7 +80,7 @@ test("expands a folder whose path has a trailing Windows separator", async ({ pa
  })

  await page.addInitScript(
-    ({ directory, server, sessionID }) => {
+    ({ directory, server, sessionID, tabKey }) => {
      localStorage.setItem(
        "opencode.global.dat:server",
        JSON.stringify({
@@ -88,10 +88,8 @@ test("expands a folder whose path has a trailing Windows separator", async ({ pa
          lastProject: { local: directory },
        }),
      )
-      localStorage.setItem(
-        "opencode.global.dat:layout",
-        JSON.stringify({ review: { diffStyle: "split", panelOpened: true } }),
-      )
+      localStorage.setItem("opencode.global.dat:layout", JSON.stringify({ review: { diffStyle: "split" } }))
+      localStorage.setItem("opencode.window.browser.dat:tabs.panes", JSON.stringify({ [tabKey]: { review: true } }))
      localStorage.setItem(
        "opencode.global.dat:review-panel-v2",
        JSON.stringify({ sidebarOpened: true, sidebarWidth: 240, expandMode: "collapse" }),
@@ -101,7 +99,7 @@ test("expands a folder whose path has a trailing Windows separator", async ({ pa
        JSON.stringify([{ type: "session", server, sessionId: sessionID }]),
      )
    },
-    { directory, server, sessionID },
+    { directory, server, sessionID, tabKey: `${server}\n/server/${base64Encode(server)}/session/${sessionID}` },
  )

  await page.goto(`/server/${base64Encode(server)}/session/${sessionID}`)
@@ -64,7 +64,7 @@ test("project Extensions stays inside settings while plugins load", async ({ pag
          location: project ? { directory: project } : {},
          data: (project ? ["shared-plugin", "project-plugin"] : ["shared-plugin"]).map((id) => ({
            id,
-            source: { type: "package", package: id },
+            source: { type: "package", target: id },
            state: { status: "active" },
            features: { server: true },
          })),
@@ -61,7 +61,7 @@ test("opens and searches project files inline", async ({ page }) => {
    pageMessages: () => ({ items: [] }),
  })
  await page.addInitScript(
-    ({ directory, server, sessionID }) => {
+    ({ directory, server, sessionID, tabKey }) => {
      localStorage.setItem(
        "opencode.global.dat:server",
        JSON.stringify({
@@ -69,10 +69,8 @@ test("opens and searches project files inline", async ({ page }) => {
          lastProject: { local: directory },
        }),
      )
-      localStorage.setItem(
-        "opencode.global.dat:layout",
-        JSON.stringify({ review: { diffStyle: "split", panelOpened: true } }),
-      )
+      localStorage.setItem("opencode.global.dat:layout", JSON.stringify({ review: { diffStyle: "split" } }))
+      localStorage.setItem("opencode.window.browser.dat:tabs.panes", JSON.stringify({ [tabKey]: { review: true } }))
      localStorage.setItem(
        "opencode.global.dat:review-panel-v2",
        JSON.stringify({ sidebarOpened: false, sidebarWidth: 240, expandMode: "collapse" }),
@@ -82,7 +80,7 @@ test("opens and searches project files inline", async ({ page }) => {
        JSON.stringify([{ type: "session", server, sessionId: sessionID }]),
      )
    },
-    { directory, server, sessionID },
+    { directory, server, sessionID, tabKey: `${server}\n/server/${base64Encode(server)}/session/${sessionID}` },
  )

  await page.goto(`/server/${base64Encode(server)}/session/${sessionID}`)
@@ -22,6 +22,7 @@ test("restores review mode and selected file per session", async ({ page }) => {
  await selectFile(page, "alpha.ts")

  await switchSession(page, titleB)
+  await page.getByRole("button", { name: "Toggle review" }).click()
  await expect(page.getByRole("button", { name: "Git changes" })).toBeVisible()
  await selectFile(page, "gamma.ts")

@@ -18,37 +18,72 @@ const PROBE = "original"

 test.use({ viewport: { width: 1440, height: 900 } })

-// The v2 review pane's diff data is workspace-scoped: switching between session
-// tabs in the same workspace must update its parameters reactively instead of
-// tearing the pane down and remounting it (which flickers).
-test("keeps the v2 review pane mounted when switching session tabs in a workspace", async ({ page }) => {
+// The review pane's data is workspace-scoped, but visibility belongs to each
+// session tab. Switching tabs must keep the pane mounted without opening it.
+test("keeps review visibility per tab and the pane mounted across tab switches", async ({ page }) => {
  await setup(page)

  await page.goto(sessionHref(sessionA))
  await expectSessionTitle(page, titleA)

  await page.getByRole("button", { name: "Toggle review" }).click()
+  await expect
+    .poll(() =>
+      page
+        .locator('[data-slot="session-chat-panel"]')
+        .evaluate((element) => getComputedStyle(element).transitionDuration),
+    )
+    .toContain("0.24s")
  const reviewTab = page.locator("#session-side-panel-review-tab")
  const reviewTabPanel = page.locator("#session-side-panel-review-tabpanel")
+  const chatPanel = page.locator('[data-slot="session-chat-panel"]')
  await expect(reviewTab).toHaveAttribute("aria-controls", "session-side-panel-review-tabpanel")
  await expect(reviewTabPanel).toHaveAttribute("id", "session-side-panel-review-tabpanel")
  const review = page.locator('#review-panel [data-component="session-review-v2"]')
  await expectAppVisible(review)
+  await expect(chatPanel).toHaveCSS("width", "580px")
  await expectAppVisible(page.getByRole("button", { name: "generated-0000.ts" }))
  await writeProbe(page)

  await switchTab(page, titleB)
  await expectSessionTitle(page, titleB)
-  await expectAppVisible(review)
-  await expectAppVisible(page.getByRole("button", { name: "generated-0000.ts" }))
+  await expect(review).toBeHidden()
+  await expect
+    .poll(() =>
+      page
+        .locator('[data-slot="session-chat-panel"]')
+        .evaluate((element) => getComputedStyle(element).transitionDuration),
+    )
+    .toBe("0s")
  expect(await readProbe(page)).toBe(PROBE)

+  await page.getByRole("button", { name: "Toggle review" }).click()
+  await expectAppVisible(review)
+  await expect(chatPanel).toHaveCSS("width", "520px")
+
  await switchTab(page, titleA)
  await expectSessionTitle(page, titleA)
  await expectAppVisible(review)
+  await expect(chatPanel).toHaveCSS("width", "580px")
  await expectAppVisible(page.getByRole("button", { name: "generated-0000.ts" }))
  expect(await readProbe(page)).toBe(PROBE)

+  await expect
+    .poll(() =>
+      page.evaluate(
+        ({ key }) => {
+          const panes = JSON.parse(localStorage.getItem("opencode.window.browser.dat:tabs.panes") ?? "{}")
+          return panes[key]?.review
+        },
+        { key: `${server}\n${sessionHref(sessionA)}` },
+      ),
+    )
+    .toBe(true)
+  await page.reload()
+  await expectSessionTitle(page, titleA)
+  await expectAppVisible(review)
+  await expect(chatPanel).toHaveCSS("width", "580px")
+
  const viewport = page.locator('#review-panel [data-slot="session-review-v2-sidebar-tree"] .scroll-view__viewport')
  await viewport.hover()
  await page.mouse.wheel(0, 100_000)
@@ -102,7 +137,7 @@ async function setup(page: Page) {
  })

  await page.addInitScript(
-    ({ directory, server, sessions }) => {
+    ({ directory, server, sessions, panes }) => {
      localStorage.setItem(
        "opencode.global.dat:server",
        JSON.stringify({
@@ -114,8 +149,19 @@ async function setup(page: Page) {
        "opencode.window.browser.dat:tabs",
        JSON.stringify(sessions.map((sessionId: string) => ({ type: "session", server, sessionId }))),
      )
+      if (!localStorage.getItem("opencode.window.browser.dat:tabs.panes")) {
+        localStorage.setItem("opencode.window.browser.dat:tabs.panes", JSON.stringify(panes))
+      }
+    },
+    {
+      directory,
+      server,
+      sessions: [sessionA, sessionB],
+      panes: {
+        [`${server}\n${sessionHref(sessionA)}`]: { sessionWidth: 580 },
+        [`${server}\n${sessionHref(sessionB)}`]: { sessionWidth: 520 },
+      },
    },
-    { directory, server, sessions: [sessionA, sessionB] },
  )
 }

@@ -123,12 +123,17 @@ test("uses side placement by default and supports the terminal across the bottom
    }),
  )
  await page.routeWebSocket("**/api/pty/pty_review_terminal/connect", () => undefined)
-  await page.addInitScript(() => {
-    localStorage.setItem(
-      "opencode.global.dat:layout",
-      JSON.stringify({ review: { diffStyle: "split", panelOpened: true } }),
-    )
-  })
+  await page.addInitScript(
+    ({ tabKey, server, sessionID }) => {
+      localStorage.setItem("opencode.global.dat:layout", JSON.stringify({ review: { diffStyle: "split" } }))
+      localStorage.setItem("opencode.window.browser.dat:tabs.panes", JSON.stringify({ [tabKey]: { review: true } }))
+      localStorage.setItem(
+        "opencode.window.browser.dat:tabs",
+        JSON.stringify([{ type: "session", server, sessionId: sessionID }]),
+      )
+    },
+    { tabKey: `${server}\n/server/${base64Encode(server)}/session/${sessionID}`, server, sessionID },
+  )

  await page.goto(`/server/${base64Encode(server)}/session/${sessionID}`)
  await expectSessionReady(page, { server, sessionID, title })
@@ -85,7 +85,7 @@ test("extensions opens without waiting for MCPs or plugins", async ({ page }) =>
        data: [
          {
            id: "demo-plugin",
-            source: { type: "package", package: "demo-plugin" },
+            source: { type: "package", target: "demo-plugin" },
            state: { status: "active" },
            features: { server: true },
          },
@@ -252,8 +252,15 @@ test("focuses a terminal created from the new-terminal button", async ({ page })

 function seedCachedTerminal(page: Page) {
  return page.addInitScript(
-    ({ terminalKey, ptyID }) => {
-      localStorage.setItem("opencode.global.dat:layout", JSON.stringify({ terminal: { height: 320, opened: true } }))
+    ({ terminalKey, ptyID, tabKey, server, sessionID }) => {
+      localStorage.setItem(
+        "opencode.window.browser.dat:tabs.panes",
+        JSON.stringify({ [tabKey]: { terminal: true, terminalHeight: 320 } }),
+      )
+      localStorage.setItem(
+        "opencode.window.browser.dat:tabs",
+        JSON.stringify([{ type: "session", server, sessionId: sessionID }]),
+      )
      localStorage.setItem(
        terminalKey,
        JSON.stringify({
@@ -262,7 +269,13 @@ function seedCachedTerminal(page: Page) {
        }),
      )
    },
-    { terminalKey: terminalStorageKey(), ptyID },
+    {
+      terminalKey: terminalStorageKey(),
+      ptyID,
+      tabKey: `${server}\n/server/${base64Encode(server)}/session/${sessionID}`,
+      server,
+      sessionID,
+    },
  )
 }

@@ -16,10 +16,9 @@ const PROBE = "original"

 test.use({ viewport: { width: 1440, height: 900 } })

-// Terminals are workspace-scoped: switching between session tabs in the same
-// workspace must keep the terminal mounted and its PTY connection open instead
-// of tearing it down and reconnecting.
-test("keeps the terminal session alive when switching session tabs in a workspace", async ({ page }) => {
+// Terminal processes are workspace-scoped, but panel visibility belongs to each
+// session tab. Switching tabs must keep the PTY alive without opening its panel.
+test("keeps terminal visibility per tab and the PTY alive across tab switches", async ({ page }) => {
  const connections = await setup(page)

  await page.goto(sessionHref(sessionA))
@@ -27,7 +26,10 @@ test("keeps the terminal session alive when switching session tabs in a workspac

  await page.keyboard.press("Control+Backquote")
  const terminal = page.locator('[data-component="terminal"]')
+  const terminalPanel = page.locator('[data-component="terminal-panel"]')
  await expect(terminal).toBeVisible()
+  await expect(terminalPanel).toHaveAttribute("data-size-animated", "true")
+  await expect(terminalPanel).toHaveCSS("height", "300px")
  await expect.poll(() => connections.length).toBe(1)
  const connection = new URL(connections[0]!)
  expect(connection.pathname).toBe(`/api/pty/${ptyID}/connect`)
@@ -37,15 +39,26 @@ test("keeps the terminal session alive when switching session tabs in a workspac

  await switchTab(page, titleB)
  await expectSessionTitle(page, titleB)
-  await expect(terminal).toBeVisible()
+  await expect(terminal).toBeHidden()
+  await expect(terminalPanel).toHaveAttribute("data-size-animated", "false")
  expect(await readProbe(page)).toBe(PROBE)
  expect(connections.length).toBe(1)

+  await page.keyboard.press("Control+Backquote")
+  await expect(terminal).toBeVisible()
+  await expect(terminalPanel).toHaveCSS("height", "180px")
+
  await switchTab(page, titleA)
  await expectSessionTitle(page, titleA)
  await expect(terminal).toBeVisible()
+  await expect(terminalPanel).toHaveCSS("height", "300px")
  expect(await readProbe(page)).toBe(PROBE)
  expect(connections.length).toBe(1)
+
+  await page.reload()
+  await expectSessionTitle(page, titleA)
+  await expect(terminal).toBeVisible()
+  await expect(terminalPanel).toHaveCSS("height", "300px")
 })

 type Probed = HTMLElement & { __e2eProbe?: string }
@@ -120,7 +133,7 @@ async function setup(page: Page) {
  })

  await page.addInitScript(
-    ({ directory, server, sessions }) => {
+    ({ directory, server, sessions, panes }) => {
      localStorage.setItem(
        "opencode.global.dat:server",
        JSON.stringify({
@@ -132,8 +145,20 @@ async function setup(page: Page) {
        "opencode.window.browser.dat:tabs",
        JSON.stringify(sessions.map((sessionId: string) => ({ type: "session", server, sessionId }))),
      )
+      if (!localStorage.getItem("opencode.window.browser.dat:tabs.panes")) {
+        localStorage.setItem("opencode.window.browser.dat:tabs.panes", JSON.stringify(panes))
+      }
+      localStorage.setItem("settings.v3", JSON.stringify({ general: { terminalPlacement: "bottom" } }))
+    },
+    {
+      directory,
+      server,
+      sessions: [sessionA, sessionB],
+      panes: {
+        [`${server}\n${sessionHref(sessionA)}`]: { terminalHeight: 300 },
+        [`${server}\n${sessionHref(sessionB)}`]: { terminalHeight: 180 },
+      },
    },
-    { directory, server, sessions: [sessionA, sessionB] },
  )
  return connections
 }
@@ -11,12 +11,6 @@ beforeAll(async () => {
    useLocation: () => ({}),
    useSearchParams: () => [{}, () => undefined],
  }))
-  mock.module("@opencode-ai/ui/context", () => ({
-    createSimpleContext: () => ({
-      use: () => undefined,
-      provider: () => undefined,
-    }),
-  }))
  const mod = await import("./comments")
  createCommentSessionForTest = mod.createCommentSessionForTest
 })
@@ -10,14 +10,9 @@ import { createScopedCache } from "@/runtime/server/scoped-cache"
 import { uuid } from "@/runtime/persistence/uuid"
 import type { SelectedLineRange } from "@/workspaces/files/model"
 import { useWorkspaceLocation } from "@/workspaces/location"
+import { CommentStore, type LineComment } from "./schema"

-export type LineComment = {
-  id: string
-  file: string
-  selection: SelectedLineRange
-  comment: string
-  time: number
-}
+export type { LineComment } from "./schema"

 type CommentFocus = { file: string; id: string }

@@ -37,10 +32,6 @@ function decodeSessionKey(key: string) {
  }
 }

-type CommentStore = {
-  comments: Record<string, LineComment[]>
-}
-
 function aggregate(comments: Record<string, LineComment[]>) {
  return Object.keys(comments)
    .flatMap((file) => comments[file] ?? [])
@@ -179,12 +170,9 @@ export function createCommentSessionForTest(comments: Record<string, LineComment
 }

 function createCommentSession(scope: ServerScope, dir: string, id: string | undefined) {
-  const [store, setStore, _, ready] = persisted(
-    Persist.serverScoped(scope, dir, id, "comments"),
-    createStore<CommentStore>({
-      comments: {},
-    }),
-  )
+  const [store, setStore, _, ready] = persisted(Persist.serverScoped(scope, dir, id, "comments"), CommentStore, {
+    comments: {},
+  })
  const session = createCommentSessionState(store, setStore)

  return {
@@ -1,7 +1,9 @@
 import { describe, expect, test } from "bun:test"
 import type { Prompt } from "@/composer/state"
 import { prependHistoryEntry, type PromptHistoryComment } from "./entry"
-import { upgradeHistoryState } from "./store"
+import { Schema } from "effect"
+import { PromptHistoryState } from "../schema"
+import { Persistence } from "@/runtime/persistence/schema"

 const DEFAULT_PROMPT: Prompt = [{ type: "text", content: "", start: 0, end: 0 }]

@@ -58,7 +60,11 @@ describe("Composer history", () => {
  })

  test("upgrades stored prompt arrays once at the persistence boundary", () => {
-    expect(upgradeHistoryState({ entries: [text("stored")] })).toEqual({
+    expect(
+      Schema.decodeUnknownSync(Persistence.withInitial(PromptHistoryState, { entries: [] }))({
+        entries: [text("stored")],
+      }),
+    ).toEqual({
      entries: [{ prompt: text("stored"), comments: [] }],
    })
  })
@@ -1,24 +1,12 @@
 import type { Prompt } from "@/composer/state"
 import type { SelectedLineRange } from "@/workspaces/files/model"
 import { clonePrompt } from "../prompt-parts"
+import type { PromptHistoryComment, PromptHistoryEntry } from "../schema"
+
+export type { PromptHistoryComment, PromptHistoryEntry } from "../schema"

 export const MAX_HISTORY = 100

-export type PromptHistoryComment = {
-  id: string
-  path: string
-  selection: SelectedLineRange
-  comment: string
-  time: number
-  origin?: "review" | "file"
-  preview?: string
-}
-
-export type PromptHistoryEntry = {
-  prompt: Prompt
-  comments: PromptHistoryComment[]
-}
-
 export type PromptHistoryStoredEntry = PromptHistoryEntry

 function cloneSelection(selection: SelectedLineRange): SelectedLineRange {
@@ -1,4 +1,4 @@
-import { createStore, type SetStoreFunction, type Store } from "solid-js/store"
+import { type SetStoreFunction, type Store } from "solid-js/store"
 import type { Prompt } from "@/composer/state"
 import { Persist, persisted } from "@/runtime/persistence/storage"
 import {
@@ -8,28 +8,14 @@ import {
  type PromptHistoryStoredEntry,
 } from "./entry"
 import { clonePrompt } from "../prompt-parts"
+import { PromptHistoryState } from "../schema"

 export type ComposerHistoryStore = {
  entries: (mode: "normal" | "shell") => PromptHistoryStoredEntry[]
  add: (prompt: Prompt, mode: "normal" | "shell", comments: PromptHistoryComment[]) => void
 }

-type PromptHistoryState = { entries: PromptHistoryStoredEntry[] }
-
-export function upgradeHistoryState(value: unknown) {
-  if (!value || typeof value !== "object" || Array.isArray(value) || !("entries" in value)) return value
-  const entries = value.entries
-  if (!Array.isArray(entries)) return value
-  return {
-    ...value,
-    entries: entries.flatMap((entry): PromptHistoryStoredEntry[] => {
-      if (Array.isArray(entry)) return [{ prompt: clonePrompt(entry as Prompt), comments: [] }]
-      if (!entry || typeof entry !== "object" || !("prompt" in entry) || !Array.isArray(entry.prompt)) return []
-      if (!("comments" in entry) || !Array.isArray(entry.comments)) return []
-      return [entry as PromptHistoryStoredEntry]
-    }),
-  }
-}
+type PromptHistoryState = typeof PromptHistoryState.Type

 function createComposerHistoryStore(
  normal: Store<PromptHistoryState>,
@@ -51,12 +37,14 @@ function createComposerHistoryStore(

 export function createComposerHistory() {
  const [normal, setNormal, normalInit] = persisted(
-    { ...Persist.prompt(Persist.global("prompt-history")), migrate: upgradeHistoryState },
-    createStore<PromptHistoryState>({ entries: [] }),
+    Persist.prompt(Persist.global("prompt-history")),
+    PromptHistoryState,
+    { entries: [] },
  )
  const [shell, setShell, shellInit] = persisted(
-    { ...Persist.prompt(Persist.global("prompt-history-shell")), migrate: upgradeHistoryState },
-    createStore<PromptHistoryState>({ entries: [] }),
+    Persist.prompt(Persist.global("prompt-history-shell")),
+    PromptHistoryState,
+    { entries: [] },
  )
  const history = createComposerHistoryStore(normal, setNormal, shell, setShell)
  return {
@@ -0,0 +1,224 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"
+import { SessionMessage } from "@opencode-ai/schema/session-message"
+import {
+  CommentStore,
+  ComposerStore,
+  DEFAULT_PROMPT,
+  PromptHistoryState,
+  type TextPart,
+  type ImageAttachmentPart,
+  type FileAttachmentPart,
+  type LineComment,
+} from "./schema"
+
+const text: TextPart = { type: "text", content: "hello", start: 0, end: 5 }
+const image: Omit<ImageAttachmentPart, "blob"> = {
+  type: "image",
+  id: "image",
+  filename: "image.png",
+  mime: "image/png",
+}
+const comment = { id: "comment", path: "src/app.ts", selection: { start: 1, end: 2 }, comment: "note", time: 1 }
+
+describe("composer persistence schemas", () => {
+  test("defaults missing or invalid fields independently and normalizes the cursor", () => {
+    const decode = Schema.decodeUnknownSync(
+      Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
+    )
+    expect(decode({})).toEqual({ prompt: DEFAULT_PROMPT, context: { items: [] } })
+    const value = decode({
+      prompt: [null, { type: "unknown" }],
+      cursor: -1,
+      mode: "unknown",
+      model: { providerID: 42, modelID: "model" },
+      retry: { id: "bad", agent: "build", providerID: "provider", modelID: "model" },
+      context: { items: [{ type: "file", path: "src/app.ts", commentID: "note", key: "stale" }, null] },
+    })
+    expect(value.prompt).toEqual(DEFAULT_PROMPT)
+    expect(value.cursor).toBe(0)
+    expect(value.mode).toBeUndefined()
+    expect(value.model).toBeUndefined()
+    expect(value.retry).toBeUndefined()
+    expect(value.context.items).toEqual([
+      { type: "file", path: "src/app.ts", commentID: "note", key: "file:src/app.ts:undefined:undefined:c=note" },
+    ])
+    expect(decode({ prompt: false, cursor: Infinity, context: null })).toEqual({
+      prompt: DEFAULT_PROMPT,
+      context: { items: [] },
+    })
+    const first = decode({})
+    first.prompt[0] = { type: "text", content: "changed", start: 0, end: 7 }
+    expect(decode({}).prompt).toEqual(DEFAULT_PROMPT)
+  })
+
+  test("drops invalid parts without losing valid mentions or optional field recovery", () => {
+    const value = Schema.decodeUnknownSync(
+      Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
+    )({
+      prompt: [
+        text,
+        { type: "agent", content: "@build", start: 5, end: 11, name: "build" },
+        { type: "skill", content: "@effect", start: 11, end: 18, id: "effect", name: "Effect" },
+        { type: "agent", content: "@broken", start: 18, end: 25, name: 42 },
+        {
+          type: "file",
+          path: "src/app.ts",
+          content: "@src/app.ts",
+          start: 18,
+          end: 29,
+          selection: { startLine: "broken" },
+          mime: 42,
+          filename: "app.ts",
+          source: { type: "invalid" },
+        },
+      ],
+      model: { providerID: "provider", modelID: "model", variant: null },
+      retry: { id: "msg_retry", agent: "build", providerID: "provider", modelID: "model", variant: false },
+    })
+    expect(value.prompt.map((part) => part.type)).toEqual(["text", "agent", "skill", "file"])
+    expect(value.prompt[3]).toEqual({
+      type: "file",
+      path: "src/app.ts",
+      content: "@src/app.ts",
+      start: 18,
+      end: 29,
+      filename: "app.ts",
+    })
+    expect(value.model?.variant).toBeNull()
+    expect(value.retry).toEqual({
+      id: SessionMessage.ID.make("msg_retry"),
+      agent: "build",
+      providerID: "provider",
+      modelID: "model",
+    })
+    expect(
+      Schema.decodeUnknownSync(
+        Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
+      )(Schema.encodeSync(ComposerStore)(value)),
+    ).toEqual(value)
+  })
+
+  test("preserves file source variants through canonical round trips", () => {
+    const sourceText = { value: "@source", start: 0, end: 7 }
+    const sources: NonNullable<FileAttachmentPart["source"]>[] = [
+      { type: "file", path: "src/app.ts", text: sourceText },
+      { type: "resource", clientName: "docs", uri: "docs://example", text: sourceText },
+      {
+        type: "symbol",
+        path: "src/app.ts",
+        name: "App",
+        kind: 1,
+        range: { start: { line: 1, character: 0 }, end: { line: 2, character: 1 } },
+        text: sourceText,
+      },
+    ]
+    const value = Schema.decodeUnknownSync(
+      Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
+    )({
+      prompt: sources.map((source) => ({
+        type: "file",
+        path: "src/app.ts",
+        content: "@source",
+        start: 0,
+        end: 7,
+        source,
+        selection: { startLine: 1, startChar: 0, endLine: 2, endChar: 1 },
+      })),
+    })
+    expect(value.prompt).toHaveLength(3)
+    expect(value.prompt.map((part) => part.type === "file" && part.source)).toEqual(sources)
+    expect(
+      Schema.decodeUnknownSync(
+        Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
+      )(Schema.encodeSync(ComposerStore)(value)),
+    ).toEqual(value)
+  })
+
+  test("migrates inline images but never encodes dataUrl or unresolved references", () => {
+    const value = Schema.decodeUnknownSync(
+      Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
+    )({
+      prompt: [
+        { ...image, dataUrl: "data:image/png;base64,YQ==", sourcePath: "/image.png" },
+        { ...image, blob: { id: "data:image/png;base64,Yg==" } },
+        { ...image, blob: { id: "hash", url: "blob:hydrated" } },
+        { ...image, blob: { id: "missing" } },
+        { ...image, blob: { id: "bad", url: "https://example.com/image.png" } },
+        { ...image, blob: { id: "missing" }, dataUrl: "data:image/png;base64,YQ==" },
+      ],
+    })
+    expect(value.prompt).toHaveLength(3)
+    expect(value.prompt[0]).toEqual({
+      ...image,
+      sourcePath: "/image.png",
+      blob: { id: "data:image/png;base64,YQ==", url: "data:image/png;base64,YQ==" },
+    })
+    const encoded = Schema.encodeSync(ComposerStore)(value)
+    expect(JSON.stringify(encoded)).not.toContain("dataUrl")
+    expect(
+      Schema.decodeUnknownSync(
+        Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
+      )(encoded),
+    ).toEqual(value)
+  })
+
+  test("migrates legacy history arrays and recovers entries, parts, and comments independently", () => {
+    const value = Schema.decodeUnknownSync(Persistence.withInitial(PromptHistoryState, { entries: [] }))({
+      entries: [
+        [text, null, { ...image, dataUrl: "data:image/png;base64,YQ==" }],
+        null,
+        {},
+        { prompt: false, comments: [] },
+        { prompt: [text, { type: "invalid" }], comments: [comment, { ...comment, selection: null }, false] },
+        { prompt: [text], comments: false },
+      ],
+    })
+    expect(value.entries).toHaveLength(3)
+    expect(value.entries[0].prompt).toHaveLength(2)
+    expect(value.entries[0].comments).toEqual([])
+    expect(value.entries[1]).toEqual({ prompt: [text], comments: [comment] })
+    expect(value.entries[2]).toEqual({ prompt: [text], comments: [] })
+    const encoded = Schema.encodeSync(PromptHistoryState)(value)
+    expect(encoded.entries?.every((entry) => !Array.isArray(entry))).toBe(true)
+    expect(JSON.stringify(encoded)).not.toContain("dataUrl")
+    expect(Schema.decodeUnknownSync(Persistence.withInitial(PromptHistoryState, { entries: [] }))(encoded)).toEqual(
+      value,
+    )
+    expect(
+      Schema.decodeUnknownSync(Persistence.withInitial(PromptHistoryState, { entries: [] }))({ entries: "invalid" }),
+    ).toEqual({ entries: [] })
+  })
+
+  test("recovers comments per file and entry without discarding healthy siblings", () => {
+    const line: LineComment = {
+      id: "comment",
+      file: "src/app.ts",
+      selection: { start: 1, end: 2, side: "additions", endSide: "deletions" },
+      comment: "note",
+      time: 1,
+    }
+    const value = Schema.decodeUnknownSync(Persistence.withInitial(CommentStore, { comments: {} }))({
+      comments: {
+        "src/app.ts": [line, null, { ...line, time: "bad" }, { ...line, selection: { start: 2, end: 4, side: "bad" } }],
+        "broken.ts": { invalid: true },
+        "healthy.ts": [{ ...line, file: "healthy.ts" }],
+      },
+    })
+    expect(value.comments["src/app.ts"]).toEqual([line, { ...line, selection: { start: 2, end: 4 } }])
+    expect(value.comments["broken.ts"]).toEqual([])
+    expect(value.comments["healthy.ts"]).toEqual([{ ...line, file: "healthy.ts" }])
+    expect(
+      Schema.decodeUnknownSync(Persistence.withInitial(CommentStore, { comments: {} }))(
+        Schema.encodeSync(CommentStore)(value),
+      ),
+    ).toEqual(value)
+    expect(Schema.decodeUnknownSync(Persistence.withInitial(CommentStore, { comments: {} }))({})).toEqual({
+      comments: {},
+    })
+    expect(Schema.decodeUnknownSync(Persistence.withInitial(CommentStore, { comments: {} }))({ comments: [] })).toEqual(
+      { comments: {} },
+    )
+  })
+})
@@ -0,0 +1,212 @@
+import { Schema, SchemaGetter } from "effect"
+import { checksum } from "@opencode-ai/util/encode"
+import { SessionMessage } from "@opencode-ai/schema/session-message"
+import { Skill } from "@opencode-ai/schema/skill"
+import { Persistence } from "@/runtime/persistence/schema"
+import { FileSelection, SelectedLineRange } from "@/workspaces/files/types"
+
+const PartBase = {
+  content: Schema.String,
+  start: Schema.Number,
+  end: Schema.Number,
+}
+
+const SourceText = Schema.Struct({ value: Schema.String, start: Schema.Number, end: Schema.Number })
+const Position = Schema.Struct({ line: Schema.Number, character: Schema.Number })
+const FilePartSource = Schema.Union([
+  Schema.Struct({ type: Schema.Literal("file"), text: SourceText, path: Schema.String }),
+  Schema.Struct({
+    type: Schema.Literal("symbol"),
+    text: SourceText,
+    path: Schema.String,
+    range: Schema.Struct({ start: Position, end: Position }),
+    name: Schema.String,
+    kind: Schema.Number,
+  }),
+  Schema.Struct({ type: Schema.Literal("resource"), text: SourceText, clientName: Schema.String, uri: Schema.String }),
+])
+
+export const TextPart = Persistence.struct({ type: Schema.Literal("text"), ...PartBase })
+export type TextPart = typeof TextPart.Type
+
+export const FileAttachmentPart = Persistence.struct({
+  type: Schema.Literal("file"),
+  ...PartBase,
+  path: Schema.String,
+  selection: Persistence.optional(FileSelection),
+  mime: Persistence.optional(Schema.String),
+  filename: Persistence.optional(Schema.String),
+  url: Persistence.optional(Schema.String),
+  source: Persistence.optional(FilePartSource),
+})
+export type FileAttachmentPart = typeof FileAttachmentPart.Type
+
+export const AgentPart = Persistence.struct({ type: Schema.Literal("agent"), ...PartBase, name: Schema.String })
+export type AgentPart = typeof AgentPart.Type
+
+export const SkillPart = Persistence.struct({
+  type: Schema.Literal("skill"),
+  ...PartBase,
+  id: Skill.ID,
+  name: Skill.Name,
+})
+export type SkillPart = typeof SkillPart.Type
+
+const ImageFields = {
+  type: Schema.Literal("image"),
+  id: Schema.String,
+  filename: Schema.String,
+  sourcePath: Persistence.optional(Schema.String),
+  mime: Schema.String,
+}
+const Image = Persistence.struct({
+  ...ImageFields,
+  blob: Schema.Struct({ id: Schema.NonEmptyString, url: Schema.String.check(Schema.isPattern(/^(blob:|data:)/)) }),
+})
+
+// Draft storage hydrates content-addressed blobs before this codec runs. Legacy
+// inline data remains usable, but unresolved references are not renderable.
+export const ImageAttachmentPart = Schema.Struct({
+  ...ImageFields,
+  blob: Persistence.optional(
+    Schema.Struct({ id: Persistence.optional(Schema.String), url: Persistence.optional(Schema.String) }),
+  ),
+  dataUrl: Persistence.optional(Schema.String),
+}).pipe(
+  Schema.decodeTo(Schema.toType(Image), {
+    decode: SchemaGetter.transform((value) => {
+      const id = value.blob?.id ?? value.dataUrl ?? ""
+      const url = value.blob?.url
+      return {
+        type: value.type,
+        id: value.id,
+        filename: value.filename,
+        sourcePath: value.sourcePath,
+        mime: value.mime,
+        blob: {
+          id,
+          url: url?.startsWith("blob:") || url?.startsWith("data:") ? url : id.startsWith("data:") ? id : "",
+        },
+      }
+    }),
+    encode: SchemaGetter.transform((value) => value),
+  }),
+)
+export type ImageAttachmentPart = typeof ImageAttachmentPart.Type
+
+export const ContentPart = Schema.Union([TextPart, FileAttachmentPart, AgentPart, SkillPart, ImageAttachmentPart])
+export type ContentPart = typeof ContentPart.Type
+export const Prompt = Persistence.array(ContentPart)
+export type Prompt = typeof Prompt.Type
+
+export const PromptModel = Persistence.struct({
+  providerID: Schema.String,
+  modelID: Schema.String,
+  variant: Persistence.optional(Schema.NullOr(Schema.String)),
+})
+export type PromptModel = typeof PromptModel.Type
+
+export const FileContextItem = Persistence.struct({
+  type: Schema.Literal("file"),
+  path: Schema.String,
+  selection: Persistence.optional(FileSelection),
+  comment: Persistence.optional(Schema.String),
+  commentID: Persistence.optional(Schema.String),
+  commentOrigin: Persistence.optional(Schema.Literals(["review", "file"])),
+  preview: Persistence.optional(Schema.String),
+})
+export type FileContextItem = typeof FileContextItem.Type
+export type ContextItem = FileContextItem
+
+export function contextItemKey(item: ContextItem) {
+  const key = `${item.type}:${item.path}:${item.selection?.startLine}:${item.selection?.endLine}`
+  if (item.commentID) return `${key}:c=${item.commentID}`
+  const comment = item.comment?.trim()
+  if (!comment) return key
+  const digest = checksum(comment) ?? comment
+  return `${key}:c=${digest.slice(0, 8)}`
+}
+
+const ContextEntry = Schema.Struct({ ...FileContextItem.fields, key: Persistence.optional(Schema.String) }).pipe(
+  Schema.decodeTo(Persistence.struct({ ...FileContextItem.fields, key: Schema.String }).pipe(Schema.toType), {
+    decode: SchemaGetter.transform((item) => ({ ...item, key: contextItemKey(item) })),
+    encode: SchemaGetter.transform((item) => item),
+  }),
+)
+
+export const DEFAULT_PROMPT: Prompt = [{ type: "text", content: "", start: 0, end: 0 }]
+
+export const ComposerStore = Persistence.struct({
+  prompt: Prompt.pipe(
+    Schema.decode({
+      decode: SchemaGetter.transform((prompt) =>
+        prompt.length ? prompt : DEFAULT_PROMPT.map((part) => ({ ...part })),
+      ),
+      encode: SchemaGetter.transform((prompt) => prompt),
+    }),
+  ),
+  cursor: Persistence.optional(
+    Schema.Finite.pipe(
+      Schema.decode({
+        decode: SchemaGetter.transform((cursor) => Math.max(0, cursor)),
+        encode: SchemaGetter.transform((cursor) => cursor),
+      }),
+    ),
+  ),
+  model: Persistence.optional(PromptModel),
+  mode: Persistence.optional(Schema.Literals(["normal", "shell"])),
+  retry: Persistence.optional(
+    Schema.Struct({
+      id: SessionMessage.ID,
+      agent: Schema.String,
+      providerID: Schema.String,
+      modelID: Schema.String,
+      variant: Persistence.optional(Schema.String),
+    }),
+  ),
+  context: Persistence.struct({ items: Persistence.array(ContextEntry) }),
+})
+export type ComposerStore = typeof ComposerStore.Type
+
+export const LineComment = Persistence.struct({
+  id: Schema.String,
+  file: Schema.String,
+  selection: SelectedLineRange,
+  comment: Schema.String,
+  time: Schema.Number,
+})
+export type LineComment = typeof LineComment.Type
+
+export const CommentStore = Persistence.struct({
+  comments: Schema.Record(Schema.String, Schema.mutableKey(Persistence.array(LineComment))),
+})
+export type CommentStore = typeof CommentStore.Type
+
+export const PromptHistoryComment = Persistence.struct({
+  id: Schema.String,
+  path: Schema.String,
+  selection: SelectedLineRange,
+  comment: Schema.String,
+  time: Schema.Number,
+  origin: Persistence.optional(Schema.Literals(["review", "file"])),
+  preview: Persistence.optional(Schema.String),
+})
+export type PromptHistoryComment = typeof PromptHistoryComment.Type
+
+// History entries require a prompt array; only its individual parts recover.
+const HistoryPrompt = Schema.Array(Persistence.fallback(Schema.UndefinedOr(ContentPart), () => undefined)).pipe(
+  Schema.decodeTo(Schema.toType(Prompt), {
+    decode: SchemaGetter.transform((parts) => parts.filter((part) => part !== undefined)),
+    encode: SchemaGetter.transform((parts) => parts),
+  }),
+)
+const HistoryEntry = Schema.Struct({ prompt: HistoryPrompt, comments: Persistence.array(PromptHistoryComment) })
+export const PromptHistoryEntry = Schema.Union([HistoryEntry, HistoryPrompt]).pipe(
+  Schema.decodeTo(Schema.toType(HistoryEntry), {
+    decode: SchemaGetter.transform((entry) => ("prompt" in entry ? entry : { prompt: entry, comments: [] })),
+    encode: SchemaGetter.transform((entry) => entry),
+  }),
+)
+export type PromptHistoryEntry = typeof PromptHistoryEntry.Type
+
+export const PromptHistoryState = Persistence.struct({ entries: Persistence.array(PromptHistoryEntry) })
@@ -1,7 +1,10 @@
 import { describe, expect, test } from "bun:test"
 import { createRoot } from "solid-js"
 import { Skill } from "@opencode-ai/schema/skill"
-import { createMemoryComposerState, DEFAULT_PROMPT, parseComposerStore } from "./state"
+import { Schema, Option } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"
+import { createMemoryComposerState, DEFAULT_PROMPT } from "./state"
+import { ComposerStore } from "./schema"

 describe("prompt state initialization", () => {
  test("initializes prompt text, cursor, and model together", () => {
@@ -29,7 +32,9 @@ describe("prompt state initialization", () => {
  })

  test("parses persisted state into one trusted current shape", () => {
-    const parsed = parseComposerStore({
+    const parsed = Schema.decodeUnknownSync(
+      Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
+    )({
      prompt: [
        { type: "text", content: "hello", start: 0, end: 5 },
        { type: "skill", id: "effect", name: "Effect", content: "@effect", start: 5, end: 12 },
@@ -105,6 +110,6 @@ describe("prompt state initialization", () => {
        ],
      },
    })
-    expect(parseComposerStore("not an object")).toBeUndefined()
+    expect(Option.isNone(Schema.decodeUnknownOption(ComposerStore)("not an object"))).toBe(true)
  })
 })
@@ -1,127 +1,41 @@
-import { checksum } from "@opencode-ai/util/encode"
 import { batch, type Accessor } from "solid-js"
 import { createStore, type SetStoreFunction } from "solid-js/store"
-import type { FileSelection } from "@/workspaces/files/model"
 import { Persist, persisted } from "@/runtime/persistence/storage"
 import { ServerScope } from "@/runtime/server/scope"
-import type { BlobReference } from "@/runtime/persistence/drafts"
 import type { Platform } from "@/runtime/platform/platform"
-import { SessionMessage } from "@opencode-ai/schema/session-message"
-import { Skill } from "@opencode-ai/schema/skill"
 import { clonePrompt } from "./prompt-parts"
+import {
+  ComposerStore,
+  DEFAULT_PROMPT,
+  contextItemKey,
+  type ContextItem,
+  type FileContextItem,
+  type Prompt,
+  type PromptModel,
+} from "./schema"

-interface PartBase {
-  content: string
-  start: number
-  end: number
-}
+export { DEFAULT_PROMPT } from "./schema"
+export type {
+  AgentPart,
+  ComposerStore,
+  ContentPart,
+  ContextItem,
+  FileAttachmentPart,
+  FileContextItem,
+  ImageAttachmentPart,
+  Prompt,
+  PromptModel,
+  SkillPart,
+  TextPart,
+} from "./schema"

-type FilePartSourceText = { value: string; start: number; end: number }
-type FilePartSource =
-  | { text: FilePartSourceText; type: "file"; path: string }
-  | {
-      text: FilePartSourceText
-      type: "symbol"
-      path: string
-      range: { start: { line: number; character: number }; end: { line: number; character: number } }
-      name: string
-      kind: number
-    }
-  | { text: FilePartSourceText; type: "resource"; clientName: string; uri: string }
-
-export interface TextPart extends PartBase {
-  type: "text"
-}
-
-export interface FileAttachmentPart extends PartBase {
-  type: "file"
-  path: string
-  selection?: FileSelection
-  mime?: string
-  filename?: string
-  url?: string
-  source?: FilePartSource
-}
-
-export interface AgentPart extends PartBase {
-  type: "agent"
-  name: string
-}
-
-export interface SkillPart extends PartBase {
-  type: "skill"
-  id: Skill.ID
-  name: Skill.Name
-}
-
-export interface ImageAttachmentPart {
-  type: "image"
-  id: string
-  filename: string
-  sourcePath?: string
-  mime: string
-  blob: BlobReference
-}
-
-export type ContentPart = TextPart | FileAttachmentPart | AgentPart | SkillPart | ImageAttachmentPart
-export type Prompt = ContentPart[]
-
-export type PromptModel = {
-  providerID: string
-  modelID: string
-  variant?: string | null
-}
-
-export type FileContextItem = {
-  type: "file"
-  path: string
-  selection?: FileSelection
-  comment?: string
-  commentID?: string
-  commentOrigin?: "review" | "file"
-  preview?: string
-}
-
-export type ContextItem = FileContextItem
 export type PromptScope = { draftID: string } | { dir: string; id?: string }

-export const DEFAULT_PROMPT: Prompt = [{ type: "text", content: "", start: 0, end: 0 }]
-
-export type ComposerStore = {
-  prompt: Prompt
-  cursor?: number
-  model?: PromptModel
-  mode?: "normal" | "shell"
-  retry?: {
-    id: SessionMessage.ID
-    agent: string
-    providerID: string
-    modelID: string
-    variant?: string
-  }
-  context: {
-    items: (ContextItem & { key: string })[]
-  }
-}
-
 type InitialPrompt = {
  prompt?: string
  model?: PromptModel
 }

-function contextItemKey(item: ContextItem) {
-  if (item.type !== "file") return item.type
-  const start = item.selection?.startLine
-  const end = item.selection?.endLine
-  const key = `${item.type}:${item.path}:${start}:${end}`
-
-  if (item.commentID) return `${key}:c=${item.commentID}`
-  const comment = item.comment?.trim()
-  if (!comment) return key
-  const digest = checksum(comment) ?? comment
-  return `${key}:c=${digest.slice(0, 8)}`
-}
-
 export function isCommentItem(item: ContextItem | (ContextItem & { key: string })) {
  return item.type === "file" && !!item.comment?.trim()
 }
@@ -147,16 +61,14 @@ function createComposerActions(setStore: SetStoreFunction<ComposerStore>) {
 }

 function composerTarget(serverScope: ServerScope, scope: PromptScope) {
-  const target =
-    "draftID" in scope
-      ? Persist.prompt(Persist.draft(scope.draftID, "prompt"))
-      : Persist.prompt({
-          ...Persist.serverScoped(serverScope, scope.dir, scope.id, "prompt"),
-          ...(serverScope === ServerScope.local
-            ? { previousKey: `${scope.dir}/prompt${scope.id ? "/" + scope.id : ""}.v2` }
-            : {}),
-        })
-  return { ...target, migrate: parseComposerStore }
+  return "draftID" in scope
+    ? Persist.prompt(Persist.draft(scope.draftID, "prompt"))
+    : Persist.prompt({
+        ...Persist.serverScoped(serverScope, scope.dir, scope.id, "prompt"),
+        ...(serverScope === ServerScope.local
+          ? { previousKey: `${scope.dir}/prompt${scope.id ? "/" + scope.id : ""}.v2` }
+          : {}),
+      })
 }

 function initialComposerStore(initial?: InitialPrompt): ComposerStore {
@@ -172,203 +84,6 @@ function initialComposerStore(initial?: InitialPrompt): ComposerStore {
  }
 }

-export function parseComposerStore(value: unknown): ComposerStore | undefined {
-  if (!record(value)) return
-  const prompt = Array.isArray(value.prompt) ? value.prompt.flatMap(parsePart) : []
-  const context = record(value.context) && Array.isArray(value.context.items) ? value.context.items : []
-  const model = parseModel(value.model)
-  const retry = parseRetry(value.retry)
-  return {
-    prompt: prompt.length ? prompt : clonePrompt(DEFAULT_PROMPT),
-    ...(typeof value.cursor === "number" && Number.isFinite(value.cursor) ? { cursor: Math.max(0, value.cursor) } : {}),
-    ...(model ? { model } : {}),
-    ...(value.mode === "normal" || value.mode === "shell" ? { mode: value.mode } : {}),
-    ...(retry ? { retry } : {}),
-    context: {
-      items: context.flatMap((item) => {
-        const parsed = parseContextItem(item)
-        return parsed ? [{ ...parsed, key: contextItemKey(parsed) }] : []
-      }),
-    },
-  }
-}
-
-function parseRetry(value: unknown): ComposerStore["retry"] {
-  if (
-    !record(value) ||
-    typeof value.id !== "string" ||
-    !value.id.startsWith("msg_") ||
-    typeof value.agent !== "string" ||
-    typeof value.providerID !== "string" ||
-    typeof value.modelID !== "string"
-  ) {
-    return
-  }
-  return {
-    id: SessionMessage.ID.make(value.id),
-    agent: value.agent,
-    providerID: value.providerID,
-    modelID: value.modelID,
-    ...(typeof value.variant === "string" ? { variant: value.variant } : {}),
-  }
-}
-
-function parsePart(value: unknown): ContentPart[] {
-  if (!record(value) || typeof value.type !== "string") return []
-  if (value.type === "image") {
-    const legacy = typeof value.dataUrl === "string" ? value.dataUrl : undefined
-    const blobID = record(value.blob) && typeof value.blob.id === "string" ? value.blob.id : legacy
-    const hydrated = record(value.blob) && typeof value.blob.url === "string" ? value.blob.url : undefined
-    const blobURL =
-      hydrated?.startsWith("blob:") || hydrated?.startsWith("data:")
-        ? hydrated
-        : blobID?.startsWith("data:")
-          ? blobID
-          : undefined
-    if (
-      typeof value.id !== "string" ||
-      typeof value.filename !== "string" ||
-      typeof value.mime !== "string" ||
-      !blobID ||
-      !blobURL
-    ) {
-      return []
-    }
-    return [
-      {
-        type: "image",
-        id: value.id,
-        filename: value.filename,
-        mime: value.mime,
-        blob: { id: blobID, url: blobURL },
-        ...(typeof value.sourcePath === "string" ? { sourcePath: value.sourcePath } : {}),
-      },
-    ]
-  }
-  if (typeof value.content !== "string" || typeof value.start !== "number" || typeof value.end !== "number") return []
-  if (value.type === "text") return [{ type: "text", content: value.content, start: value.start, end: value.end }]
-  if (value.type === "agent" && typeof value.name === "string") {
-    return [{ type: "agent", name: value.name, content: value.content, start: value.start, end: value.end }]
-  }
-  if (value.type === "skill" && typeof value.id === "string" && typeof value.name === "string") {
-    return [
-      {
-        type: "skill",
-        id: Skill.ID.make(value.id),
-        name: Skill.Name.make(value.name),
-        content: value.content,
-        start: value.start,
-        end: value.end,
-      },
-    ]
-  }
-  if (value.type !== "file" || typeof value.path !== "string") return []
-  const selection = parseSelection(value.selection)
-  const source = parseSource(value.source)
-  return [
-    {
-      type: "file",
-      path: value.path,
-      content: value.content,
-      start: value.start,
-      end: value.end,
-      ...(typeof value.mime === "string" ? { mime: value.mime } : {}),
-      ...(typeof value.filename === "string" ? { filename: value.filename } : {}),
-      ...(typeof value.url === "string" ? { url: value.url } : {}),
-      ...(selection ? { selection } : {}),
-      ...(source ? { source } : {}),
-    },
-  ]
-}
-
-function parseContextItem(value: unknown): ContextItem | undefined {
-  if (!record(value) || value.type !== "file" || typeof value.path !== "string") return
-  const selection = parseSelection(value.selection)
-  const origin = value.commentOrigin === "review" || value.commentOrigin === "file" ? value.commentOrigin : undefined
-  return {
-    type: "file",
-    path: value.path,
-    ...(selection ? { selection } : {}),
-    ...(typeof value.comment === "string" ? { comment: value.comment } : {}),
-    ...(typeof value.commentID === "string" ? { commentID: value.commentID } : {}),
-    ...(origin ? { commentOrigin: origin } : {}),
-    ...(typeof value.preview === "string" ? { preview: value.preview } : {}),
-  }
-}
-
-function parseModel(value: unknown): PromptModel | undefined {
-  if (!record(value) || typeof value.providerID !== "string" || typeof value.modelID !== "string") return
-  return {
-    providerID: value.providerID,
-    modelID: value.modelID,
-    ...(typeof value.variant === "string" || value.variant === null ? { variant: value.variant } : {}),
-  }
-}
-
-function parseSelection(value: unknown): FileSelection | undefined {
-  if (!record(value)) return
-  if (
-    typeof value.startLine !== "number" ||
-    typeof value.startChar !== "number" ||
-    typeof value.endLine !== "number" ||
-    typeof value.endChar !== "number"
-  ) {
-    return
-  }
-  return {
-    startLine: value.startLine,
-    startChar: value.startChar,
-    endLine: value.endLine,
-    endChar: value.endChar,
-  }
-}
-
-function parseSource(value: unknown): FilePartSource | undefined {
-  if (!record(value) || !record(value.text)) return
-  if (
-    typeof value.text.value !== "string" ||
-    typeof value.text.start !== "number" ||
-    typeof value.text.end !== "number"
-  ) {
-    return
-  }
-  const text = { value: value.text.value, start: value.text.start, end: value.text.end }
-  if (value.type === "file" && typeof value.path === "string") return { type: "file", path: value.path, text }
-  if (value.type === "resource" && typeof value.clientName === "string" && typeof value.uri === "string") {
-    return { type: "resource", clientName: value.clientName, uri: value.uri, text }
-  }
-  if (
-    value.type !== "symbol" ||
-    typeof value.path !== "string" ||
-    typeof value.name !== "string" ||
-    typeof value.kind !== "number" ||
-    !record(value.range) ||
-    !record(value.range.start) ||
-    !record(value.range.end) ||
-    typeof value.range.start.line !== "number" ||
-    typeof value.range.start.character !== "number" ||
-    typeof value.range.end.line !== "number" ||
-    typeof value.range.end.character !== "number"
-  ) {
-    return
-  }
-  return {
-    type: "symbol",
-    path: value.path,
-    name: value.name,
-    kind: value.kind,
-    text,
-    range: {
-      start: { line: value.range.start.line, character: value.range.start.character },
-      end: { line: value.range.end.line, character: value.range.end.character },
-    },
-  }
-}
-
-function record(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
 function createComposerStateValue(store: ComposerStore, setStore: SetStoreFunction<ComposerStore>) {
  const actions = createComposerActions(setStore)
  const clearRetry = () => setStore("retry", undefined)
@@ -442,11 +157,7 @@ function createPersistedComposer(
  initial?: InitialPrompt,
  platform?: Platform,
 ) {
-  const [store, setStore, _, ready] = persisted(
-    target,
-    createStore<ComposerStore>(initialComposerStore(initial)),
-    platform,
-  )
+  const [store, setStore, _, ready] = persisted(target, ComposerStore, initialComposerStore(initial), platform)
  return { ready, ...createComposerStateValue(store, setStore) }
 }

@@ -460,13 +171,7 @@ export function createComposerState(
 }

 export function createDraftComposerState(draftID: string, initial?: InitialPrompt) {
-  return createPersistedComposer(
-    {
-      ...Persist.prompt(Persist.draft(draftID, "prompt")),
-      migrate: parseComposerStore,
-    },
-    initial,
-  )
+  return createPersistedComposer(Persist.prompt(Persist.draft(draftID, "prompt")), initial)
 }

 export type ComposerState = ReturnType<typeof createComposerState>
@@ -10,10 +10,15 @@ import { Persist, persisted } from "@/runtime/persistence/storage"
 import { showToast } from "@/shell/notifications/toast"
 import { useDialog } from "@opencode-ai/ui/context/dialog"
 import { createResource } from "solid-js"
-import { createStore } from "solid-js/store"
+import { Schema } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"
 import type { HomeController } from "../model"
 import { useGlobal } from "@/runtime/server/runtime"

+export const HomeServersSchema = Schema.Struct({
+  collapsed: Persistence.record(Persistence.fallback(Schema.Boolean, () => false)),
+})
+
 export function createHomeProjectsController(home: HomeController) {
  const platform = usePlatform()
  const pickDirectory = useDirectoryPicker()
@@ -22,10 +27,7 @@ export function createHomeProjectsController(home: HomeController) {
  const openSettings = useSettingsCommand()
  const serverManagement = useServerActionsController()
  const global = useGlobal()
-  const [_state, setState, _, ready] = persisted(
-    Persist.global("home.servers"),
-    createStore({ collapsed: {} as Record<string, boolean> }),
-  )
+  const [_state, setState, _, ready] = persisted(Persist.global("home.servers"), HomeServersSchema, { collapsed: {} })
  const [state] = createResource(
    () => ready.promise ?? Promise.resolve(),
    (promise) => promise.then(() => _state),
@@ -3,7 +3,7 @@ import { Tooltip } from "@opencode-ai/ui/tooltip"
 import { Icon } from "@opencode-ai/ui/icon"
 import { Wordmark } from "@opencode-ai/ui/wordmark"
 import { Show, createMemo, createSignal } from "solid-js"
-import { createStore } from "solid-js/store"
+import { Schema } from "effect"
 import createPresence from "solid-presence"
 import { Composer } from "@/composer/composer"
 import type { ComposerModel } from "@/composer/model"
@@ -20,10 +20,19 @@ import { useWorkspaceLocation } from "@/workspaces/location"
 import { useProviders } from "@/providers/catalog/providers"
 import { NEW_SESSION_CONTENT_WIDTH } from "@/new-session/layout"
 import { Persist, persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
 import type { NewSessionWorkspaceController } from "./workspace/controller"

 const providerTipDismissalDuration = 30 * 24 * 60 * 60 * 1000

+export const WorkspaceOnboardingSchema = Persistence.struct({
+  used: Schema.Boolean,
+})
+
+export const ProviderTipSchema = Persistence.struct({
+  dismissedAt: Schema.Finite,
+})
+
 export function NewSessionView(props: {
  composer: ComposerModel
  project: PromptProjectController
@@ -31,7 +40,8 @@ export function NewSessionView(props: {
 }) {
  const [onboarding, setOnboarding, , onboardingReady] = persisted(
    Persist.global("workspace-onboarding"),
-    createStore({ used: false }),
+    WorkspaceOnboardingSchema,
+    { used: false },
  )
  const select = (value: string) => {
    props.workspace.selection.set(value)
@@ -110,7 +120,8 @@ function ProviderTip() {
  const providers = useProviders(() => sdk().directory)
  const [persistedState, setPersistedState, , persistedReady] = persisted(
    Persist.global("new-session.provider-tip"),
-    createStore({ dismissedAt: 0 }),
+    ProviderTipSchema,
+    { dismissedAt: 0 },
  )
  const visible = createMemo(
    () =>
@@ -8,7 +8,7 @@ describe("pluginLabels", () => {
      { id: "opencode.internal", source: { type: "builtin" }, state: { status: "active" }, features: { server: true } },
      {
        id: "package-plugin",
-        source: { type: "package", package: "example" },
+        source: { type: "package", target: "example" },
        state: { status: "active" },
        features: { server: true },
      },
@@ -2,7 +2,7 @@ import type { PluginInfo } from "@opencode-ai/client"

 export function pluginLabel(plugin: PluginInfo) {
  if (plugin.id) return plugin.id
-  if (plugin.source.type === "package") return plugin.source.package
+  if (plugin.source.type === "package") return plugin.source.target
  if (plugin.source.type === "local") return plugin.source.path
  return plugin.source.type
 }
@@ -3,10 +3,12 @@ import { base64Encode } from "@opencode-ai/util/encode"
 import { useParams } from "@solidjs/router"
 import { batch, createEffect, createMemo, startTransition } from "solid-js"
 import { createStore } from "solid-js/store"
+import { Schema, SchemaGetter } from "effect"
 import { useModels } from "@/providers/models/models"
 import { useSettings } from "@/settings/model"
 import { useProviders } from "@/providers/catalog/providers"
 import { Persist, persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
 import { hasCustomAgent, resolveAgent } from "./agent"
 import { cycleModelVariant, getConfiguredAgentVariant, resolveModelVariant } from "./variant"
 import { useWorkspaceLocation } from "@/workspaces/location"
@@ -15,39 +17,49 @@ import { normalizeAgentList } from "@/runtime/server/global-sync/utils"
 import { useServerSDK } from "@/runtime/server/client"
 import { ScopedKey, type ServerScope } from "@/runtime/server/scope"

-export type ModelKey = { providerID: string; modelID: string; variant?: string }
+const ModelKeySchema = Schema.Struct({
+  providerID: Schema.String,
+  modelID: Schema.String,
+  variant: Schema.optional(Schema.String),
+})
+export type ModelKey = typeof ModelKeySchema.Type

-type State = {
-  agent?: string
-  model?: ModelKey
-  variant?: string | null
-}
+const StateSchema = Schema.Struct({
+  agent: Persistence.optional(Schema.String),
+  model: Persistence.optional(ModelKeySchema),
+  variant: Persistence.optional(Schema.NullOr(Schema.String)),
+})
+type State = typeof StateSchema.Type

-type Saved = {
-  session: Record<string, State | undefined>
-}
+const SessionsSchema = Schema.Record(
+  Schema.String,
+  Schema.mutableKey(Persistence.fallback(Schema.UndefinedOr(StateSchema), () => undefined)),
+)
+
+const Current = Persistence.struct({ session: SessionsSchema })
+
+export const ModelSelectionSchema = Persistence.migrate(
+  Current,
+  Schema.Struct({
+    session: Persistence.optional(Schema.Record(Schema.String, Schema.Unknown)),
+    pick: Persistence.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  }).pipe(
+    Schema.decode({
+      decode: SchemaGetter.transform((value) => ({
+        session:
+          value.session ??
+          Object.fromEntries(Object.entries(value.pick ?? {}).filter(([key]) => key !== WORKSPACE_KEY)),
+      })),
+      encode: SchemaGetter.transform((value) => value),
+    }),
+  ),
+)

 const WORKSPACE_KEY = "__workspace__"
 const handoff = new Map<string, State>()

 const handoffKey = (scope: ServerScope, dir: string, id: string) => ScopedKey.from(scope, dir, id)

-const migrate = (value: unknown) => {
-  if (!value || typeof value !== "object") return { session: {} }
-
-  const item = value as {
-    session?: Record<string, State | undefined>
-    pick?: Record<string, State | undefined>
-  }
-
-  if (item.session && typeof item.session === "object") return { session: item.session }
-  if (!item.pick || typeof item.pick !== "object") return { session: {} }
-
-  return {
-    session: Object.fromEntries(Object.entries(item.pick).filter(([key]) => key !== WORKSPACE_KEY)),
-  }
-}
-
 const clone = (value: State | undefined) => {
  if (!value) return
  return {
@@ -77,13 +89,9 @@ export const { use: useLocal, provider: LocalProvider } = createSimpleContext({
    const connected = createMemo(() => new Set(providers.connected().map((item) => item.id)))

    const [saved, setSaved, , savedReady] = persisted(
-      {
-        ...Persist.serverWorkspace(serverSDK.scope, sdk().directory, "model-selection"),
-        migrate,
-      },
-      createStore<Saved>({
-        session: {},
-      }),
+      Persist.serverWorkspace(serverSDK.scope, sdk().directory, "model-selection"),
+      ModelSelectionSchema,
+      { session: {} },
    )

    const [store, setStore] = createStore<{
@@ -1,16 +1,25 @@
 import { createMemo, type Accessor } from "solid-js"
 import createPresence from "solid-presence"

-export function createAnimatedPresence<T>(value: Accessor<T | undefined>, element: Accessor<HTMLElement | null>) {
-  const animation = createMemo<{ show: boolean; animate: boolean; value: T | undefined }>((previous) => {
-    const current = value()
-    const show = current !== undefined
-    return {
-      show,
-      animate: previous !== undefined && (previous.animate || previous.show !== show),
-      value: current ?? previous?.value,
-    }
-  })
+export function createAnimatedPresence<T>(
+  value: Accessor<T | undefined>,
+  element: Accessor<HTMLElement | null>,
+  identity?: Accessor<unknown>,
+) {
+  const animation = createMemo<{ identity?: unknown; show: boolean; animate: boolean; value: T | undefined }>(
+    (previous) => {
+      const currentIdentity = identity?.()
+      const current = value()
+      const show = current !== undefined
+      const same = !identity || previous?.identity === currentIdentity
+      return {
+        identity: currentIdentity,
+        show,
+        animate: previous !== undefined && same && (previous.animate || previous.show !== show),
+        value: current ?? (same ? previous?.value : undefined),
+      }
+    },
+  )
  const presence = createPresence({ show: () => animation().show, element })
  return {
    ...presence,
@@ -1,6 +1,7 @@
 import { flatten, resolveTemplate, translator, type Flatten } from "@solid-primitives/i18n"
 import { createEffect, createMemo, createResource, type JSX } from "solid-js"
 import { createStore } from "solid-js/store"
+import { Option, Schema, SchemaGetter } from "effect"
 import { createSimpleContext } from "@opencode-ai/ui/context"
 import {
  I18nProvider,
@@ -11,6 +12,7 @@ import {
  type UiPluralCategory,
 } from "@opencode-ai/ui/context/i18n"
 import { Persist, persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
 import en from "@/runtime/i18n/en"
 import { dict } from "@opencode-ai/ui/i18n/en"
 import {
@@ -54,6 +56,16 @@ function cookie(locale: Locale) {

 const LOCALES: readonly Locale[] = DESKTOP_NATIVE_LOCALES

+const LocaleSchema = Schema.Literals(DESKTOP_NATIVE_LOCALES)
+const StoredLocaleSchema = Schema.Struct({
+  locale: Schema.String.pipe(
+    Schema.decodeTo(LocaleSchema, {
+      decode: SchemaGetter.transform(normalizeLocale),
+      encode: SchemaGetter.transform((locale) => locale),
+    }),
+  ),
+})
+
 const INTL = DESKTOP_NATIVE_LOCALE_TAGS

 const base = flatten({ ...en, ...dict })
@@ -148,17 +160,21 @@ function detectLocale(): Locale {
 }

 export function normalizeLocale(value: string): Locale {
-  return LOCALES.includes(value as Locale) ? (value as Locale) : "en"
+  return Option.getOrElse(Schema.decodeUnknownOption(LocaleSchema)(value), () => "en")
 }

+export const languageSchema = Persistence.struct({
+  locale: StoredLocaleSchema.fields.locale,
+})
+
 function readStoredLocale() {
  if (typeof localStorage !== "object") return
  try {
    const raw = localStorage.getItem("opencode.global.dat:language")
    if (!raw) return
-    const next = JSON.parse(raw) as { locale?: string }
-    if (typeof next?.locale !== "string") return
-    return normalizeLocale(next.locale)
+    const next = Schema.decodeUnknownOption(Schema.fromJsonString(StoredLocaleSchema))(raw)
+    if (Option.isNone(next)) return
+    return next.value.locale
  } catch {
    return
  }
@@ -182,14 +198,9 @@ export const { use: useLanguage, provider: LanguageProvider } = createSimpleCont
  gate: false,
  init: (props: { locale?: Locale; onNativeTranslations?: (bundle: DesktopNativeBundle) => void }) => {
    const initial = props.locale ?? readStoredLocale() ?? detectLocale()
-    const [store, setStore, _, ready] = persisted(
-      Persist.global("language"),
-      createStore({
-        locale: initial,
-      }),
-    )
+    const [store, setStore, _, ready] = persisted(Persist.global("language"), languageSchema, { locale: initial })

-    const locale = createMemo<Locale>(() => normalizeLocale(store.locale))
+    const locale = createMemo(() => store.locale)
    const intl = createMemo(() => INTL[locale()])
    const [layout, setLayout] = createStore({ direction: undefined as Direction | undefined })
    const direction = createMemo(() => layout.direction ?? localeDirection(locale()))
@@ -0,0 +1,80 @@
+# Persisted State
+
+`persisted(target, schema, initial, platformOverride?)` creates a Solid store whose
+type comes from an Effect Schema codec. The required `initial` value supplies
+store defaults and is checked against that type. The function returns the store, setter, storage
+initialization result, and readiness accessor. Both web and desktop use this
+boundary, including cross-window updates.
+
+```ts
+const Preferences = Persistence.struct({
+  visible: Schema.Boolean,
+  mode: Schema.Literals(["normal", "shell"]),
+  directory: Persistence.optional(Schema.String),
+  recent: Persistence.array(Schema.String),
+})
+
+type Preferences = typeof Preferences.Type
+
+const [preferences, setPreferences, , ready] = persisted(Persist.global("preferences"), Preferences, {
+  visible: true,
+  mode: "normal",
+  recent: [],
+})
+```
+
+Keep initialization defaults in `initial`, not repeated across schema fields.
+Plain struct fields recover independently from the corresponding initial value;
+the resulting state is validated before entering the store. Arrays replace rather
+than index-merge, explicit `null` is retained when allowed, and missing optional
+values can inherit dynamic initial defaults.
+
+Field codecs decode atomically, so the persistence layer does not attempt to
+interpret arbitrary transformations. Collection-entry recovery and genuine
+migration rules remain explicit in their schemas.
+
+- `Persistence.fallback(schema, factory)` deliberately recovers invalid values as
+  well as missing or undefined input. Use it for domain-specific recovery, such as
+  defaults inside collection entries, not ordinary store initialization.
+- `Persistence.optional(schema)` omits invalid fields as well as accepting missing
+  or undefined input. Use ordinary `Schema.optional` when no codec-local recovery
+  is needed; the initialized store boundary still recovers fields from `initial`.
+- `Persistence.struct(fields)` makes fields mutable for Solid stores while preserving
+  each field's optionality and codec. It does not add defaults or error recovery.
+- `Persistence.record(valueSchema)` creates a mutable string-keyed record, defaulting
+  missing or invalid records to a fresh `{}`. Its value schema determines entry
+  recovery: pass `Persistence.optional(valueSchema)` to discard only invalid entries,
+  or `Persistence.fallback(valueSchema, factory)` to replace those entries.
+- `Persistence.array(schema)` defaults to an empty mutable array and discards
+  invalid entries individually. Valid entries still pass through their codecs.
+- Recovery is not a substitute for an explicit historical shape transformation.
+
+## Migrations
+
+Describe shipped representations with schemas and transform their typed values
+using `Schema.decode` or `Schema.decodeTo` and `SchemaGetter`. For whole-object
+migrations, pass `Persistence.migrate(currentSchema, storedCodec)` instead of the
+plain schema. The stored codec runs before defaults are applied, preserving
+distinctions such as an absent current field identifying an older format. It
+returns a candidate in the current encoded shape; the current schema then owns
+recovery and validation.
+
+The migration reader preserves excess properties so a migration can describe
+only the fields it observes without dropping unrelated saved preferences. The
+current schema strips fields outside its contract. Writes use only the current
+schema's encoder, never the legacy reader's encoder.
+
+`Persistence.withInitial(schemaOrMigration, initial)` exposes the same initialized
+codec for focused tests. Test canonical encoding and decode/encode/decode stability
+as well as historical fixtures.
+
+Reads normalize stored JSON through decoding and encoding, writing back the
+canonical representation when it changed. Invalid documents fall back to initial
+state; malformed individual values can instead be recovered by their schemas.
+Cross-window values are decoded before entering the store. Writes use the same
+codec's encoder.
+
+Storage-key relocation (`previousKey`, workspace aliases, draft storage moves)
+remains separate from schema migration. Draft blob externalization and hydration
+also remain in the storage adapter: composer codecs receive hydrated references,
+not raw ID-only blob documents.
@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import { WorkspaceOnboardingSchema, ProviderTipSchema } from "@/new-session/view"
+import { ModelSelectionSchema } from "@/providers/models/selection"
+import { Persistence } from "@/runtime/persistence/schema"
+import { FileViewsSchema } from "@/workspaces/files/view-cache"
+import { languageSchema } from "@/runtime/i18n/language"
+import { HomeServersSchema } from "@/home/projects/controller"
+import { ModelProvidersSchema } from "@/settings/models/models"
+
+describe("persisted consumer schemas", () => {
+  test("onboarding and provider tip retain defaults and validate stored values", () => {
+    const onboarding = Schema.decodeUnknownSync(Persistence.withInitial(WorkspaceOnboardingSchema, { used: false }))
+    const tip = Schema.decodeUnknownSync(Persistence.withInitial(ProviderTipSchema, { dismissedAt: 0 }))
+    expect(onboarding({})).toEqual({ used: false })
+    expect(onboarding({ used: "true" })).toEqual({ used: false })
+    expect(onboarding({ used: true })).toEqual({ used: true })
+    expect(tip({})).toEqual({ dismissedAt: 0 })
+    expect(tip({ dismissedAt: "yesterday" })).toEqual({ dismissedAt: 0 })
+    expect(tip({ dismissedAt: Infinity })).toEqual({ dismissedAt: 0 })
+    expect(tip({ dismissedAt: 123 })).toEqual({ dismissedAt: 123 })
+  })
+
+  test("collapse records recover malformed entries without losing valid siblings", () => {
+    for (const schema of [HomeServersSchema, ModelProvidersSchema]) {
+      const decode = Schema.decodeUnknownSync(Persistence.withInitial(schema, { collapsed: {} }))
+      expect(decode({})).toEqual({ collapsed: {} })
+      expect(decode({ collapsed: [] })).toEqual({ collapsed: {} })
+      expect(decode({ collapsed: { open: false, closed: true, invalid: "false" } })).toEqual({
+        collapsed: { open: false, closed: true, invalid: false },
+      })
+    }
+  })
+
+  test("model selection migrates legacy picks and omits workspace state", () => {
+    const decode = Schema.decodeUnknownSync(Persistence.withInitial(ModelSelectionSchema, { session: {} }))
+    expect(decode({})).toEqual({ session: {} })
+    const state = decode({ pick: { __workspace__: { agent: "plan" }, session1: { agent: "build" } } })
+    expect(state.session.session1?.agent).toBe("build")
+    expect(state.session.__workspace__).toBeUndefined()
+    const encoded = Schema.encodeSync(
+      Schema.fromJsonString(Persistence.withInitial(ModelSelectionSchema, { session: {} })),
+    )(state)
+    expect(JSON.parse(encoded)).toEqual({ session: { session1: { agent: "build" } } })
+    expect(decode(JSON.parse(encoded))).toEqual(state)
+  })
+
+  test("current model selections take precedence over legacy picks", () => {
+    expect(
+      Schema.decodeUnknownSync(Persistence.withInitial(ModelSelectionSchema, { session: {} }))({
+        session: {},
+        pick: { session1: { agent: "plan" } },
+      }),
+    ).toEqual({ session: {} })
+  })
+
+  test("model selection validates nested model keys and preserves explicit null variants", () => {
+    const state = Schema.decodeUnknownSync(Persistence.withInitial(ModelSelectionSchema, { session: {} }))({
+      session: {
+        good: { agent: "build", model: { providerID: "provider", modelID: "model", variant: "high" }, variant: null },
+        partial: { agent: "plan", model: { providerID: "provider", modelID: 42 }, variant: false },
+        invalid: "build",
+      },
+    })
+    expect(state.session.good).toEqual({
+      agent: "build",
+      model: { providerID: "provider", modelID: "model", variant: "high" },
+      variant: null,
+    })
+    expect(state.session.partial?.agent).toBe("plan")
+    expect(state.session.partial?.model).toBeUndefined()
+    expect(state.session.partial?.variant).toBeUndefined()
+    expect(state.session.invalid).toBeUndefined()
+  })
+
+  test("file views validate scroll positions and line sides independently", () => {
+    const decode = Schema.decodeUnknownSync(Persistence.withInitial(FileViewsSchema, { file: {} }))
+    expect(decode({})).toEqual({ file: {} })
+    const state = decode({
+      file: {
+        good: {
+          scrollTop: 12,
+          scrollLeft: 4,
+          selectedLines: { start: 9, end: 2, side: "deletions", endSide: "additions" },
+        },
+        partial: { scrollTop: "12", scrollLeft: 8, selectedLines: { start: 1, end: 3, side: "invalid" } },
+        cleared: { selectedLines: null },
+        invalid: false,
+      },
+    })
+    expect(state.file.good).toEqual({
+      scrollTop: 12,
+      scrollLeft: 4,
+      selectedLines: { start: 9, end: 2, side: "deletions", endSide: "additions" },
+    })
+    expect(state.file.partial?.scrollTop).toBeUndefined()
+    expect(state.file.partial?.scrollLeft).toBe(8)
+    expect(state.file.partial?.selectedLines).toEqual({ start: 1, end: 3 })
+    expect(state.file.cleared?.selectedLines).toBeNull()
+    expect(state.file.invalid).toEqual({})
+  })
+
+  test("language preserves runtime defaults and normalizes unsupported locales to English", () => {
+    const decode = Schema.decodeUnknownSync(Persistence.withInitial(languageSchema, { locale: "fr" }))
+    expect(decode({})).toEqual({ locale: "fr" })
+    expect(decode({ locale: undefined })).toEqual({ locale: "fr" })
+    expect(decode({ locale: 42 })).toEqual({ locale: "fr" })
+    expect(decode({ locale: "unsupported" })).toEqual({ locale: "en" })
+    expect(decode({ locale: "ar" })).toEqual({ locale: "ar" })
+  })
+})
@@ -1,4 +1,5 @@
 import type { AsyncStorage } from "@solid-primitives/storage"
+import { Option, Schema } from "effect"

 export type BlobReference = { id: string; url: string }

@@ -81,7 +82,11 @@ export function createDraftStore(driver: Driver): DraftStore {
  return {
    getItem: async (key) => {
      const value = await driver.get(key)
-      return value === null ? null : JSON.stringify(await decode(JSON.parse(value)))
+      if (value === null) return null
+      const parsed = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Unknown))(value)
+      // Let the owning persistence codec apply its invalid-document policy.
+      if (Option.isNone(parsed)) return value
+      return JSON.stringify(await decode(parsed.value))
    },
    setItem: async (key, value) => {
      const version = (versions.get(key) ?? 0) + 1
@@ -0,0 +1,162 @@
+import { describe, expect, test } from "bun:test"
+import { Effect, Schema, SchemaGetter } from "effect"
+import { Persistence } from "./schema"
+
+describe("persistence schemas", () => {
+  test("initial state supplies nested defaults without hiding valid siblings", () => {
+    const schema = Persistence.withInitial(
+      Persistence.struct({
+        enabled: Schema.Boolean,
+        appearance: Persistence.struct({ width: Schema.Number, font: Schema.String }),
+        variant: Schema.optional(Schema.NullOr(Schema.String)),
+      }),
+      { enabled: true, appearance: { width: 240, font: "default" }, variant: "high" },
+    )
+    const decode = Schema.decodeUnknownSync(schema)
+    expect(decode({ appearance: { width: 300 } })).toEqual({
+      enabled: true,
+      appearance: { width: 300, font: "default" },
+      variant: "high",
+    })
+    expect(decode({ enabled: "false", appearance: { width: "wide", font: "saved" }, variant: null })).toEqual({
+      enabled: true,
+      appearance: { width: 240, font: "saved" },
+      variant: null,
+    })
+    expect(decode({ appearance: null })).toEqual({
+      enabled: true,
+      appearance: { width: 240, font: "default" },
+      variant: "high",
+    })
+  })
+
+  test("legacy migration observes missing fields before initial defaults are applied", () => {
+    const current = Persistence.struct({ mode: Schema.Literals(["compact", "full"]), enabled: Schema.Boolean })
+    const stored = Schema.Struct({
+      mode: Schema.optional(Schema.Unknown),
+      expanded: Schema.optional(Schema.Boolean),
+    }).pipe(
+      Schema.decode({
+        decode: SchemaGetter.transform((value) =>
+          value.mode !== undefined || value.expanded === undefined
+            ? value
+            : { ...value, mode: value.expanded ? "full" : "compact" },
+        ),
+        encode: SchemaGetter.passthrough(),
+      }),
+    )
+    const schema = Persistence.withInitial(Persistence.migrate(current, stored), { mode: "compact", enabled: true })
+    const decode = Schema.decodeUnknownSync(schema)
+    expect(decode({ expanded: true, enabled: false })).toEqual({ mode: "full", enabled: false })
+    expect(decode({ expanded: true, mode: "compact" })).toEqual({ mode: "compact", enabled: true })
+    expect(decode({ expanded: true, mode: "invalid" })).toEqual({ mode: "compact", enabled: true })
+    expect(Schema.encodeSync(schema)(decode({ expanded: true }))).toEqual({ mode: "full", enabled: true })
+  })
+
+  test("initial merging preserves field codecs and replaces arrays rather than merging indexes", () => {
+    const current = Persistence.struct({
+      amount: Schema.NumberFromString.check(Schema.isFinite()),
+      items: Schema.mutable(Schema.Array(Schema.String)),
+    })
+    const schema = Persistence.withInitial(current, { amount: 7, items: ["initial"] })
+    const decode = Schema.decodeUnknownSync(schema)
+    expect(decode({ amount: "12", items: [] })).toEqual({ amount: 12, items: [] })
+    expect(decode({ amount: "invalid", items: ["saved"] })).toEqual({ amount: 7, items: ["saved"] })
+    expect(Schema.encodeSync(schema)(decode({}))).toEqual({ amount: "7", items: ["initial"] })
+  })
+
+  test("built-in defaults only recover absent values, not invalid ones", () => {
+    const schema = Persistence.struct({
+      enabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+    })
+    const decode = Schema.decodeUnknownSync(schema)
+    expect(decode({})).toEqual({ enabled: true })
+    expect(decode({ enabled: undefined })).toEqual({ enabled: true })
+    expect(() => decode({ enabled: "true" })).toThrow()
+    const state: typeof schema.Type = { enabled: false }
+    state.enabled = true
+    expect(Schema.encodeSync(schema)(state)).toEqual({ enabled: true })
+  })
+
+  test("defaults missing and invalid fields without discarding valid siblings", () => {
+    const schema = Schema.Struct({
+      enabled: Persistence.fallback(Schema.Boolean, () => true),
+      label: Persistence.fallback(Schema.String, () => "default"),
+    })
+    const decode = Schema.decodeUnknownSync(schema)
+    expect(decode({})).toEqual({ enabled: true, label: "default" })
+    expect(decode({ enabled: "false", label: "saved" })).toEqual({ enabled: true, label: "saved" })
+    expect(decode({ enabled: undefined, label: null })).toEqual({ enabled: true, label: "default" })
+    expect(Schema.encodeSync(schema)(decode({}))).toEqual({ enabled: true, label: "default" })
+  })
+
+  test("optional recovery keeps fields optional without adding an undefined default", () => {
+    const number = Schema.NumberFromString.check(Schema.isFinite())
+    const schema = Persistence.struct({ value: Persistence.optional(number) })
+    const decode = Schema.decodeUnknownSync(schema)
+    const empty: typeof schema.Type = {}
+    expect(decode({})).toEqual(empty)
+    expect(decode({ value: "invalid" })).toEqual(empty)
+    expect(Object.hasOwn(decode({ value: "invalid" }), "value")).toBe(false)
+    expect(decode({ value: undefined })).toEqual({ value: undefined })
+    expect(decode({ value: "42" })).toEqual({ value: 42 })
+    expect(Schema.encodeSync(schema)({ value: 42 })).toEqual({ value: "42" })
+    expect(Schema.encodeSync(schema)(empty)).toEqual({})
+    expect(() =>
+      Schema.decodeUnknownSync(Schema.Struct({ value: Schema.optional(number) }))({ value: "invalid" }),
+    ).toThrow()
+  })
+
+  test("fallbacks use decoded values and retain the codec on writes", () => {
+    const schema = Persistence.struct({
+      value: Persistence.fallback(Schema.NumberFromString.check(Schema.isFinite()), () => 7),
+    })
+    const decode = Schema.decodeUnknownSync(schema)
+    expect(decode({})).toEqual({ value: 7 })
+    expect(decode({ value: "invalid" })).toEqual({ value: 7 })
+    expect(Schema.encodeSync(schema)(decode({}))).toEqual({ value: "7" })
+  })
+
+  test("records default to fresh mutable objects and keep entry recovery explicit", () => {
+    const strict = Persistence.record(Schema.Boolean)
+    const decode = Schema.decodeUnknownSync(strict)
+    expect(decode(undefined)).toEqual({})
+    expect(decode([])).toEqual({})
+    expect(decode({ valid: true, invalid: "true" })).toEqual({})
+    const first: typeof strict.Type = decode(undefined)
+    first.changed = true
+    expect(decode(undefined)).toEqual({})
+
+    const recover = Persistence.record(Persistence.optional(Schema.Boolean))
+    const state = Schema.decodeUnknownSync(recover)({ valid: true, invalid: "true" })
+    expect(state).toEqual({ valid: true })
+    expect(Schema.encodeSync(recover)(state)).toEqual({ valid: true })
+  })
+
+  test("creates fresh default collections", () => {
+    const schema = Schema.Struct({ items: Persistence.array(Schema.String) })
+    const decode = Schema.decodeUnknownSync(schema)
+    const first = decode({})
+    first.items.push("changed")
+    expect(decode({}).items).toEqual([])
+  })
+
+  test("recovers and migrates individual array entries", () => {
+    const current = Schema.Struct({ name: Schema.String })
+    const schema = Persistence.array(
+      Schema.Union([current, Schema.String]).pipe(
+        Schema.decodeTo(current, {
+          decode: SchemaGetter.transform((value) => (typeof value === "string" ? { name: value } : value)),
+          encode: SchemaGetter.passthrough(),
+        }),
+      ),
+    )
+    const decode = Schema.decodeUnknownSync(schema)
+    const value = decode(["old", { name: "new" }, null, { name: false }])
+    expect(value).toEqual([{ name: "old" }, { name: "new" }])
+    expect(Schema.encodeSync(schema)(value)).toEqual(value)
+    expect(decode(Schema.encodeSync(schema)(value))).toEqual(value)
+    expect(decode(undefined)).toEqual([])
+    expect(decode({})).toEqual([])
+  })
+})
@@ -0,0 +1,99 @@
+export * as Persistence from "./schema"
+
+import { Effect, Option, Predicate, Result, Schema, SchemaAST, SchemaGetter, SchemaParser, Struct } from "effect"
+
+export type Migrated<S extends Schema.ConstraintCodec<object, unknown>> = {
+  current: S
+  read: Schema.ConstraintDecoder<unknown>
+}
+
+export function migrate<S extends Schema.ConstraintCodec<object, unknown>>(
+  current: S,
+  read: Schema.ConstraintDecoder<unknown>,
+): Migrated<S> {
+  return { current, read }
+}
+
+function isMigrated<S extends Schema.ConstraintCodec<object, unknown>>(schema: S | Migrated<S>): schema is Migrated<S> {
+  return "current" in schema
+}
+
+export function withInitial<S extends Schema.ConstraintCodec<object, unknown>>(
+  definition: S | Migrated<S>,
+  initial: NoInfer<S["Type"]>,
+) {
+  const schema = isMigrated(definition) ? definition.current : definition
+  const read = isMigrated(definition)
+    ? SchemaParser.decodeUnknownResult(definition.read, { onExcessProperty: "preserve" })
+    : Result.succeed<unknown>
+  const encode = Schema.encodeUnknownSync(schema)
+  return Schema.Unknown.pipe(
+    Schema.decode<Schema.Unknown>({
+      decode: SchemaGetter.transformOrFail((value) =>
+        Effect.fromResult(Result.map(read(value), (stored) => merge(initial, recover(schema.ast, stored, initial)))),
+      ),
+      encode: SchemaGetter.transform((value) => encode(value)),
+    }),
+    Schema.decodeTo(Schema.toType(schema)),
+  )
+}
+
+// Object-level codecs own their recovery. Plain structs can recover fields independently.
+function recover(ast: SchemaAST.AST, value: unknown, initial: unknown): unknown {
+  if (value === undefined) return initial
+  if (ast._tag === "Objects" && !ast.encoding && ast.indexSignatures.length === 0 && Predicate.isObject(value)) {
+    return Object.fromEntries(
+      ast.propertySignatures.flatMap((field) => {
+        const defaults = Predicate.isObject(initial) ? initial[field.name] : undefined
+        const next = recover(field.type, value[field.name], defaults)
+        if (next === undefined && !Object.hasOwn(value, field.name) && defaults === undefined) return []
+        return [[field.name, next]]
+      }),
+    )
+  }
+  const decoded = Schema.decodeUnknownOption(Schema.make<Schema.Codec<unknown, unknown>>(ast))(value)
+  return Option.isSome(decoded) ? decoded.value : initial
+}
+
+function merge(initial: unknown, value: unknown): unknown {
+  if (value === undefined) return initial
+  if (!Predicate.isObject(initial) || !Predicate.isObject(value)) return value
+  return Object.fromEntries(
+    [...new Set([...Object.keys(initial), ...Object.keys(value)])].map((key) => [key, merge(initial[key], value[key])]),
+  )
+}
+
+// Unlike a decoding default, a fallback also replaces invalid persisted values.
+export function fallback<S extends Schema.ConstraintCodec<unknown, unknown>>(schema: S, value: () => S["Type"]) {
+  const defaulted = Schema.withDecodingDefaultType<S>(Effect.sync(value))(schema)
+  return Schema.catchDecoding<typeof defaulted>(() => Effect.sync(() => Option.some(value())))(defaulted)
+}
+
+export function optional<S extends Schema.ConstraintCodec<unknown, unknown>>(schema: S) {
+  const field = Schema.optional(schema)
+  return Schema.catchDecoding<typeof field>(() => Effect.succeed(Option.none()))(field)
+}
+
+export function struct<const Fields extends Schema.Struct.Fields>(fields: Fields) {
+  return Schema.Struct(fields).mapFields(Struct.map(Schema.mutableKey))
+}
+
+export function record<S extends Schema.ConstraintCodec<unknown, unknown>>(schema: S) {
+  const entries = Schema.Record(Schema.String, Schema.mutableKey(schema))
+  return fallback(entries, () => Schema.decodeUnknownSync(entries)({}))
+}
+
+// Recover individual entries rather than discarding a whole history or collection.
+export function array<S extends Schema.ConstraintCodec<unknown, unknown>>(schema: S) {
+  const decode = Schema.decodeUnknownOption(schema)
+  const encode = Schema.encodeSync(schema)
+  return fallback(
+    Schema.Array(Schema.Unknown).pipe(
+      Schema.decodeTo(Schema.mutable(Schema.Array(Schema.toType(schema))), {
+        decode: SchemaGetter.transform((items) => items.flatMap((item) => Option.toArray(decode(item)))),
+        encode: SchemaGetter.transform((items) => items.map((item) => encode(item))),
+      }),
+    ),
+    () => [],
+  )
+}
@@ -107,11 +107,6 @@ describe("persist localStorage resilience", () => {
    expect(storage.getItem("direct-value")).toBe('{"value":5}')
  })

-  test("normalizer rejects malformed JSON payloads", () => {
-    const result = persistTesting.normalize({ value: "ok" }, '{"value":"\\x"}')
-    expect(result).toBeUndefined()
-  })
-
  test("workspace storage sanitizes Windows filename characters", () => {
    const result = persistTesting.workspaceStorage("C:\\Users\\foo")

@@ -2,9 +2,11 @@ import { Platform, usePlatform } from "@/runtime/platform/platform"
 import { makePersisted, messageSync, type AsyncStorage, type SyncStorage } from "@solid-primitives/storage"
 import { checksum } from "@opencode-ai/util/encode"
 import { createResource, onCleanup, type Accessor } from "solid-js"
-import type { SetStoreFunction, Store } from "solid-js/store"
+import { createStore, type SetStoreFunction, type Store } from "solid-js/store"
+import { Option, Schema } from "effect"
 import { pathKey } from "@/workspaces/path-key"
 import { ScopedKey, ServerScope } from "@/runtime/server/scope"
+import { Persistence } from "./schema"

 type InitType = Promise<string> | string | null
 type PersistedWithReady<T> = [
@@ -22,7 +24,6 @@ type PersistTarget = {
  workspaceStorageAliases?: string[]
  previousKey?: string
  key: string
-  migrate?: (value: unknown) => unknown
 }

 const GLOBAL_STORAGE = "opencode.global.dat"
@@ -164,65 +165,10 @@ function write(storage: Storage, key: string, value: string) {
  return ok
 }

-function snapshot(value: unknown) {
-  return JSON.parse(JSON.stringify(value)) as unknown
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
-function merge(defaults: unknown, value: unknown): unknown {
-  if (value === undefined) return defaults
-  if (value === null) return value
-
-  if (Array.isArray(defaults)) {
-    if (Array.isArray(value)) return value
-    return defaults
-  }
-
-  if (isRecord(defaults)) {
-    if (!isRecord(value)) return defaults
-
-    const result: Record<string, unknown> = { ...defaults }
-    for (const key of Object.keys(value)) {
-      if (key in defaults) {
-        result[key] = merge((defaults as Record<string, unknown>)[key], (value as Record<string, unknown>)[key])
-      } else {
-        result[key] = (value as Record<string, unknown>)[key]
-      }
-    }
-    return result
-  }
-
-  return value
-}
-
-function parse(value: string) {
-  try {
-    return JSON.parse(value) as unknown
-  } catch {
-    return undefined
-  }
-}
-
-function normalize(defaults: unknown, raw: string, migrate?: (value: unknown) => unknown) {
-  const parsed = parse(raw)
-  if (parsed === undefined) return
-  const migrated = migrate ? migrate(parsed) : parsed
-  const merged = merge(defaults, migrated)
-  return JSON.stringify(merged)
-}
-
-function readCurrent(input: {
-  storage: SyncStorage
-  key: string
-  defaults: unknown
-  migrate?: (value: unknown) => unknown
-}) {
+function readCurrent(input: { storage: SyncStorage; key: string; normalize: (raw: string) => string | undefined }) {
  const raw = input.storage.getItem(input.key)
  if (raw === null) return
-  const next = normalize(input.defaults, raw, input.migrate)
+  const next = input.normalize(raw)
  if (next === undefined) {
    input.storage.removeItem(input.key)
    return null
@@ -235,15 +181,14 @@ function relocateStoredValue(input: {
  current: SyncStorage
  sources: { storage: SyncStorage; key?: string }[]
  key: string
-  defaults: unknown
-  migrate?: (value: unknown) => unknown
+  normalize: (raw: string) => string | undefined
 }) {
  for (const source of input.sources) {
    const key = source.key ?? input.key
    const raw = source.storage.getItem(key)
    if (raw === null) continue

-    const next = normalize(input.defaults, raw, input.migrate)
+    const next = input.normalize(raw)
    if (next === undefined) {
      source.storage.removeItem(key)
      continue
@@ -259,12 +204,11 @@ function relocateStoredValue(input: {
 async function readCurrentAsync(input: {
  storage: AsyncStorage
  key: string
-  defaults: unknown
-  migrate?: (value: unknown) => unknown
+  normalize: (raw: string) => string | undefined
 }) {
  const raw = await input.storage.getItem(input.key)
  if (raw === null) return
-  const next = normalize(input.defaults, raw, input.migrate)
+  const next = input.normalize(raw)
  if (next === undefined) {
    await input.storage.removeItem(input.key).catch(() => undefined)
    return null
@@ -291,15 +235,14 @@ async function relocateStoredValueAsync(input: {
  current: AsyncStorage
  sources: { storage: AsyncStorage; key?: string }[]
  key: string
-  defaults: unknown
-  migrate?: (value: unknown) => unknown
+  normalize: (raw: string) => string | undefined
 }) {
  for (const source of input.sources) {
    const key = source.key ?? input.key
    const raw = await source.storage.getItem(key)
    if (raw === null) continue

-    const next = normalize(input.defaults, raw, input.migrate)
+    const next = input.normalize(raw)
    if (next === undefined) {
      await removeAsync(source.storage, key)
      continue
@@ -446,7 +389,6 @@ export function draftPersistedKeys() {
 export const PersistTesting = {
  localStorageDirect,
  localStorageWithPrefix,
-  normalize,
  resolveTarget,
  windowStorage,
  workspaceStorage,
@@ -529,15 +471,24 @@ export function removePersisted(
  }
 }

-export function persisted<T>(
+export function persisted<S extends Schema.ConstraintCodec<object, unknown>>(
  target: string | PersistTarget,
-  store: [Store<T>, SetStoreFunction<T>],
+  schema: S | Persistence.Migrated<S>,
+  initial: NoInfer<S["Type"]>,
  platformOverride?: Platform,
-): PersistedWithReady<T> {
+): PersistedWithReady<S["Type"]> {
  const platform = platformOverride ?? usePlatform()
  const config = resolveTarget(typeof target === "string" ? { key: target } : target, platform)

-  const defaults = snapshot(store[0])
+  const initialized = Persistence.withInitial(schema, initial)
+  const json = Schema.fromJsonString(initialized)
+  const decode = Schema.decodeUnknownOption(json)
+  const serialize = Schema.encodeSync(json)
+  const normalize = (raw: string) => {
+    const value = decode(raw)
+    if (Option.isSome(value)) return serialize(value.value)
+  }
+  const store = createStore<S["Type"]>(Schema.decodeUnknownSync(Schema.toType(initialized))(initial))
  const isDesktop = platform.platform === "desktop" && !!platform.storage
  const draft = config.draft ? platform.draftStore : undefined

@@ -567,14 +518,13 @@ export function persisted<T>(

      const api: SyncStorage = {
        getItem: (key) => {
-          const value = readCurrent({ storage: current, key, defaults, migrate: config.migrate })
+          const value = readCurrent({ storage: current, key, normalize })
          if (value !== undefined) return value
          return relocateStoredValue({
            current,
            sources,
            key,
-            defaults,
-            migrate: config.migrate,
+            normalize,
          })
        },
        setItem: (key, value) => {
@@ -610,14 +560,13 @@ export function persisted<T>(

    const api: AsyncStorage = {
      getItem: async (key) => {
-        const value = await readCurrentAsync({ storage: current, key, defaults, migrate: config.migrate })
+        const value = await readCurrentAsync({ storage: current, key, normalize })
        if (value !== undefined) return value
        const relocated = await relocateStoredValueAsync({
          current,
          sources: relocationSources,
          key,
-          defaults,
-          migrate: config.migrate,
+          normalize,
        })
        if (draftLatest === undefined) {
          if (draft && relocated !== null) return (await current.getItem(key)) ?? relocated
@@ -644,9 +593,11 @@ export function persisted<T>(
      : undefined
  if (channel) onCleanup(() => channel.close())

-  const [state, setState, init] = makePersisted<T, typeof store>(store, {
+  const [state, setState, init] = makePersisted<S["Type"], typeof store>(store, {
    name: config.key,
    storage,
+    serialize,
+    deserialize: Schema.decodeUnknownSync(json),
    sync: channel ? messageSync(channel) : undefined,
  })

@@ -5,12 +5,12 @@ import type { State } from "./types"
 import type { QueryOptionsApi } from "../sync"
 import { ServerScope } from "@/runtime/server/scope"
 import type { Data } from "@opencode-ai/client/solid"
+import type { persisted } from "@/runtime/persistence/storage"

 let createChildStoreManager: typeof import("./child-store").createChildStoreManager
 const querySingles: Array<() => { queryKey?: unknown[]; enabled?: boolean }> = []
-const persist: typeof import("@/runtime/persistence/storage").persisted = (_target, store) => [
-  store[0],
-  store[1],
+const persist: typeof persisted = (_target, _schema, initial) => [
+  ...createStore(initial),
  null,
  Object.assign(() => true, { promise: undefined }),
 ]
@@ -20,6 +20,7 @@ import { directoryKey, type DirectoryKey } from "./utils"
 import type { ServerScope } from "@/runtime/server/scope"
 import type { Data } from "@opencode-ai/client/solid"
 import { normalizeAgentList, normalizeProviderList } from "./utils"
+import { IconState, ProjectState, VcsState } from "../persistence"

 export function createChildStoreManager(input: {
  owner: Owner
@@ -155,29 +156,20 @@ export function createChildStoreManager(input: {
    if (!key) console.error("No directory provided")
    if (!children[key]) {
      const vcs = runWithOwner(input.owner, () =>
-        input.persist(
-          Persist.serverWorkspace(input.scope, directory, "vcs"),
-          createStore({ value: undefined as VcsInfo | undefined }),
-        ),
+        input.persist(Persist.serverWorkspace(input.scope, directory, "vcs"), VcsState, { value: undefined }),
      )
      if (!vcs) throw new Error(input.translate("error.childStore.persistedCacheCreateFailed"))
      const vcsStore = vcs[0]
      vcsCache.set(key, { store: vcsStore, setStore: vcs[1], ready: vcs[3] })

      const meta = runWithOwner(input.owner, () =>
-        input.persist(
-          Persist.serverWorkspace(input.scope, directory, "project"),
-          createStore({ value: undefined as ProjectMeta | undefined }),
-        ),
+        input.persist(Persist.serverWorkspace(input.scope, directory, "project"), ProjectState, { value: undefined }),
      )
      if (!meta) throw new Error(input.translate("error.childStore.persistedProjectMetadataCreateFailed"))
      metaCache.set(key, { store: meta[0], setStore: meta[1], ready: meta[3] })

      const icon = runWithOwner(input.owner, () =>
-        input.persist(
-          Persist.serverWorkspace(input.scope, directory, "icon"),
-          createStore({ value: undefined as string | undefined }),
-        ),
+        input.persist(Persist.serverWorkspace(input.scope, directory, "icon"), IconState, { value: undefined }),
      )
      if (!icon) throw new Error(input.translate("error.childStore.persistedProjectIconCreateFailed"))
      iconCache.set(key, { store: icon[0], setStore: icon[1], ready: icon[3] })
@@ -3,17 +3,9 @@ import type { ReferenceInfo } from "@opencode-ai/client/promise"
 import type { CommandInfo, McpResource, McpServer } from "@opencode-ai/client/promise"
 import type { Accessor } from "solid-js"
 import type { SetStoreFunction, Store } from "solid-js/store"
+import { IconState, ProjectState, VcsState } from "../persistence"

-export type ProjectMeta = {
-  name?: string
-  icon?: {
-    override?: string
-    color?: string
-  }
-  commands?: {
-    start?: string
-  }
-}
+export type ProjectMeta = NonNullable<typeof ProjectState.Type.value>

 export type State = {
  status: "loading" | "partial" | "complete"
@@ -40,20 +32,20 @@ export type State = {
 }

 export type VcsCache = {
-  store: Store<{ value: VcsInfo | undefined }>
-  setStore: SetStoreFunction<{ value: VcsInfo | undefined }>
+  store: Store<typeof VcsState.Type>
+  setStore: SetStoreFunction<typeof VcsState.Type>
  ready: Accessor<boolean>
 }

 export type MetaCache = {
-  store: Store<{ value: ProjectMeta | undefined }>
-  setStore: SetStoreFunction<{ value: ProjectMeta | undefined }>
+  store: Store<typeof ProjectState.Type>
+  setStore: SetStoreFunction<typeof ProjectState.Type>
  ready: Accessor<boolean>
 }

 export type IconCache = {
-  store: Store<{ value: string | undefined }>
-  setStore: SetStoreFunction<{ value: string | undefined }>
+  store: Store<typeof IconState.Type>
+  setStore: SetStoreFunction<typeof IconState.Type>
  ready: Accessor<boolean>
 }

@@ -0,0 +1,266 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import { IconState, ModelState, ProjectState, VcsState, serverState } from "./persistence"
+import { createRoot } from "solid-js"
+import { isServer } from "solid-js/web"
+import { Persist, persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
+
+const initial = { list: [], hidden: {}, projects: {}, lastProject: {}, recentlyClosed: {} }
+
+function serverSchema(canonical?: () => string | undefined) {
+  return Persistence.withInitial(serverState(canonical), initial)
+}
+
+describe("server persistence schema", () => {
+  test("migrates legacy auth and writes only current server objects", () => {
+    const schema = serverSchema()
+    const input = {
+      list: [
+        "http://localhost:4096",
+        { url: "https://flat.example", username: "legacy", password: "first" },
+        {
+          type: "http",
+          displayName: "Remote",
+          label: "Production",
+          authToken: true,
+          http: { url: "https://nested.example", username: "legacy", password: "second" },
+        },
+      ],
+      projects: { local: [{ worktree: "/project", expanded: true }] },
+    }
+    const state = Schema.decodeUnknownSync(schema)(input)
+    expect(state).toEqual({
+      list: [
+        { type: "http", http: { url: "http://localhost:4096" } },
+        { type: "http", http: { url: "https://flat.example", password: "first" } },
+        {
+          type: "http",
+          displayName: "Remote",
+          label: "Production",
+          authToken: true,
+          http: { url: "https://nested.example", password: "second" },
+        },
+      ],
+      hidden: {},
+      projects: input.projects,
+      lastProject: {},
+      recentlyClosed: {},
+    })
+    expect(input.list[1]).toHaveProperty("username", "legacy")
+    const encoded = Schema.encodeSync(schema)(state)
+    expect(encoded).toEqual(state)
+    expect(Schema.decodeUnknownSync(schema)(encoded)).toEqual(state)
+  })
+
+  test("defaults missing or malformed fields and drops invalid entries independently", () => {
+    const decode = Schema.decodeUnknownSync(serverSchema())
+    const empty = { list: [], hidden: {}, projects: {}, lastProject: {}, recentlyClosed: {} }
+    expect(decode({})).toEqual(empty)
+    expect(decode({ list: null, hidden: [], projects: false, lastProject: 1, recentlyClosed: "bad" })).toEqual(empty)
+    expect(
+      decode({
+        list: [null, 1, {}, { type: "http", http: { url: 12 } }, "https://valid.example"],
+        projects: { local: [null, {}, { worktree: 1 }, { worktree: "/project" }], remote: false },
+        recentlyClosed: { local: [null, 1, "/closed"], remote: null },
+      }),
+    ).toEqual({
+      ...empty,
+      list: [{ type: "http", http: { url: "https://valid.example" } }],
+      projects: { local: [{ worktree: "/project", expanded: true }], remote: [] },
+      recentlyClosed: { local: ["/closed"], remote: [] },
+    })
+  })
+
+  test("moves canonical project buckets without changing server keys or unrelated scopes", () => {
+    const schema = serverSchema(() => "https://opencode.example.com")
+    const state = Schema.decodeUnknownSync(schema)({
+      list: ["https://opencode.example.com"],
+      hidden: { "https://opencode.example.com": true },
+      projects: {
+        local: [{ worktree: "/local", expanded: false }],
+        "https://opencode.example.com": [
+          { worktree: "/local", expanded: true },
+          { worktree: "/remote", expanded: true },
+          { worktree: "/remote", expanded: false },
+        ],
+        other: [{ worktree: "/other", expanded: true }],
+      },
+      lastProject: { local: "/local", "https://opencode.example.com": "/remote", other: "/other" },
+      recentlyClosed: { local: ["/closed"], "https://opencode.example.com": ["/old-closed"] },
+    })
+    expect(state.projects).toEqual({
+      local: [
+        { worktree: "/local", expanded: false },
+        { worktree: "/remote", expanded: true },
+      ],
+      other: [{ worktree: "/other", expanded: true }],
+    })
+    expect(state.lastProject).toEqual({ local: "/local", other: "/other" })
+    expect(state.list[0]?.http.url).toBe("https://opencode.example.com")
+    expect(state.hidden).toEqual({ "https://opencode.example.com": true })
+    expect(state.recentlyClosed).toEqual({ local: ["/closed"], "https://opencode.example.com": ["/old-closed"] })
+    expect(Schema.encodeSync(schema)(state)).toEqual(state)
+    expect(Schema.decodeUnknownSync(schema)(state)).toEqual(state)
+  })
+
+  test("reads the latest canonical local prop on each decode", () => {
+    const props: { canonicalLocalServer?: string } = {}
+    const schema = serverSchema(() => props.canonicalLocalServer)
+    const decode = Schema.decodeUnknownSync(schema)
+    const input = {
+      projects: { remote: [{ worktree: "/project", expanded: true }] },
+      lastProject: { remote: "/project" },
+    }
+    expect(decode(input).projects).toEqual(input.projects)
+    props.canonicalLocalServer = "remote"
+    expect(decode(input).projects).toEqual({ local: [{ worktree: "/project", expanded: true }] })
+    expect(decode(input).lastProject).toEqual({ local: "/project" })
+    props.canonicalLocalServer = "local"
+    expect(decode(input).projects).toEqual(input.projects)
+    expect(input.lastProject).toEqual({ remote: "/project" })
+  })
+
+  test("migrates a last project without a project list", () => {
+    expect(Schema.decodeUnknownSync(serverSchema(() => "remote"))({ lastProject: { remote: "/project" } })).toEqual({
+      list: [],
+      hidden: {},
+      projects: {},
+      lastProject: { local: "/project" },
+      recentlyClosed: {},
+    })
+  })
+})
+
+describe("model persistence schema", () => {
+  test("defaults missing state and keeps valid entries beside malformed entries", () => {
+    const decode = Schema.decodeUnknownSync(Persistence.withInitial(ModelState, { user: [], recent: [], variant: {} }))
+    expect(decode({})).toEqual({ user: [], recent: [], variant: {} })
+    expect(decode({ user: null, recent: 1, variant: [] })).toEqual({ user: [], recent: [], variant: {} })
+    const state = decode({
+      user: [
+        null,
+        { providerID: "provider", modelID: "model", visibility: "show", favorite: true },
+        { providerID: "provider", modelID: "invalid", visibility: "invalid" },
+        { providerID: "provider", modelID: "hidden", visibility: "hide" },
+      ],
+      recent: [false, { providerID: "provider", modelID: "model" }, { providerID: "missing-model" }],
+      variant: { model: "high" },
+    })
+    expect(state).toEqual({
+      user: [
+        { providerID: "provider", modelID: "model", visibility: "show", favorite: true },
+        { providerID: "provider", modelID: "hidden", visibility: "hide" },
+      ],
+      recent: [{ providerID: "provider", modelID: "model" }],
+      variant: { model: "high" },
+    })
+    expect(Schema.encodeSync(ModelState)(state)).toEqual(state)
+  })
+})
+
+describe("directory cache schemas", () => {
+  test("defaults missing and malformed VCS caches but retains optional branch metadata", () => {
+    const decode = Schema.decodeUnknownSync(Persistence.withInitial(VcsState, { value: undefined }))
+    expect(decode({})).toEqual({ value: undefined })
+    expect(decode({ value: null })).toEqual({ value: undefined })
+    expect(decode({ value: { branch: 1 } })).toEqual({ value: undefined })
+    expect(decode({ value: { default_branch: "main" } })).toEqual({ value: { default_branch: "main" } })
+    const state = decode({ value: { branch: "feature", default_branch: "main", obsolete: true } })
+    expect(state).toEqual({ value: { branch: "feature", default_branch: "main" } })
+    expect(Schema.encodeSync(VcsState)(state)).toEqual(state)
+  })
+
+  test("validates project name, icon overrides and startup commands", () => {
+    const decode = Schema.decodeUnknownSync(Persistence.withInitial(ProjectState, { value: undefined }))
+    expect(decode({})).toEqual({ value: undefined })
+    expect(decode({ value: [] })).toEqual({ value: undefined })
+    expect(decode({ value: { icon: { override: 1 } } })).toEqual({ value: undefined })
+    expect(decode({ value: { commands: { start: false } } })).toEqual({ value: undefined })
+    expect(decode({ value: {} })).toEqual({ value: {} })
+    const state = decode({
+      value: {
+        name: "Project",
+        icon: { override: "data:image/png;base64,abc", color: "blue" },
+        commands: { start: "bun dev" },
+      },
+    })
+    expect(Schema.encodeSync(ProjectState)(state)).toEqual(state)
+    expect(state.value).toEqual({
+      name: "Project",
+      icon: { override: "data:image/png;base64,abc", color: "blue" },
+      commands: { start: "bun dev" },
+    })
+  })
+
+  test("validates optional icon strings", () => {
+    const decode = Schema.decodeUnknownSync(Persistence.withInitial(IconState, { value: undefined }))
+    expect(decode({})).toEqual({ value: undefined })
+    expect(decode({ value: 42 })).toEqual({ value: undefined })
+    expect(decode({ value: null })).toEqual({ value: undefined })
+    expect(decode({ value: "" })).toEqual({ value: "" })
+    expect(Schema.encodeSync(IconState)(decode({ value: "data:image/png;base64,abc" }))).toEqual({
+      value: "data:image/png;base64,abc",
+    })
+  })
+})
+
+test.skipIf(isServer)(
+  "persisted server relocation hydrates migrated state and writes current schema on updates",
+  async () => {
+    const values = new Map([
+      [
+        "default:server.v3",
+        JSON.stringify({
+          list: [{ url: "https://remote.example", username: "legacy", password: "secret" }],
+          projects: { "https://remote.example": [{ worktree: "/project", expanded: false }] },
+          lastProject: { "https://remote.example": "/project" },
+        }),
+      ],
+    ])
+    const root = createRoot((dispose) => ({
+      dispose,
+      state: persisted(
+        { ...Persist.global("server"), previousKey: "server.v3" },
+        serverState(() => "https://remote.example"),
+        initial,
+        {
+          platform: "desktop",
+          windowID: "test",
+          openExternal() {},
+          restart: async () => {},
+          notify: async () => {},
+          openDirectoryPickerDialog: async () => null,
+          storage: (name = "default") => ({
+            getItem: async (key) => values.get(`${name}:${key}`) ?? null,
+            setItem: async (key, value) => {
+              values.set(`${name}:${key}`, value)
+            },
+            removeItem: async (key) => {
+              values.delete(`${name}:${key}`)
+            },
+          }),
+        },
+      ),
+    }))
+    try {
+      await root.state[3].promise
+      expect(values.has("default:server.v3")).toBe(false)
+      expect(root.state[0].list).toEqual([
+        { type: "http", http: { url: "https://remote.example", password: "secret" } },
+      ])
+      expect(root.state[0].projects).toEqual({ local: [{ worktree: "/project", expanded: false }] })
+      expect(root.state[0].lastProject).toEqual({ local: "/project" })
+      root.state[1]("projects", "local", 0, "expanded", true)
+      const stored = values.get("opencode.global.dat:server")
+      expect(stored).toBeDefined()
+      if (!stored) throw new Error("server state was not written")
+      const decoded = Schema.decodeUnknownSync(Schema.fromJsonString(serverSchema()))(stored)
+      expect(decoded.projects.local).toEqual([{ worktree: "/project", expanded: true }])
+      expect(stored).not.toContain("username")
+      expect(decoded.list).toEqual(root.state[0].list)
+    } finally {
+      root.dispose()
+    }
+  },
+)
@@ -0,0 +1,136 @@
+import { Effect, Option, Schema, SchemaGetter } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"
+
+export const ServerKey = Schema.String.pipe(Schema.brand("ServerConnection.Key"))
+
+export const ServerHttpBase = Persistence.struct({
+  url: Schema.String,
+  password: Schema.optional(Schema.String),
+})
+
+export const ServerHttp = Persistence.struct({
+  type: Schema.Literal("http"),
+  http: ServerHttpBase,
+  authToken: Schema.optional(Schema.Boolean),
+  displayName: Schema.optional(Schema.String),
+  label: Schema.optional(Schema.String),
+})
+
+const StoredServer = Schema.Union([ServerHttp, ServerHttpBase, Schema.String]).pipe(
+  Schema.decodeTo(ServerHttp, {
+    decode: SchemaGetter.transform((value) => {
+      if (typeof value === "string") return { type: "http", http: { url: value } }
+      if ("http" in value) return value
+      return { type: "http", http: value }
+    }),
+    encode: SchemaGetter.transform((value) => value),
+  }),
+)
+
+const ProjectList = Persistence.array(
+  Persistence.struct({
+    worktree: Schema.String,
+    expanded: Persistence.fallback(Schema.Boolean, () => true),
+  }),
+)
+const Projects = Persistence.record(ProjectList)
+const LastProject = Persistence.record(Schema.String.pipe(Schema.catchDecoding(() => Effect.succeed(Option.none()))))
+
+const State = Persistence.struct({
+  list: Persistence.array(StoredServer),
+  hidden: Schema.Record(
+    Schema.String,
+    Schema.mutableKey(Schema.Boolean.pipe(Schema.catchDecoding(() => Effect.succeed(Option.none())))),
+  ),
+  projects: Schema.Record(Schema.String, Schema.mutableKey(ProjectList)),
+  lastProject: Schema.Record(
+    Schema.String,
+    Schema.mutableKey(Schema.String.pipe(Schema.catchDecoding(() => Effect.succeed(Option.none())))),
+  ),
+  recentlyClosed: Schema.Record(Schema.String, Schema.mutableKey(Persistence.array(Schema.String))),
+})
+
+export function serverState(canonicalLocalServer: () => string | undefined = () => undefined) {
+  return Persistence.migrate(
+    State,
+    Schema.Struct({ projects: Projects, lastProject: LastProject }).pipe(
+      Schema.decode({
+        decode: SchemaGetter.transform((value) => {
+          const canonical = canonicalLocalServer()
+          if (!canonical || canonical === "local") return value
+          const previous = value.projects[canonical]
+          const last = value.lastProject[canonical]
+          if (!previous && last === undefined) return value
+
+          const projects = { ...value.projects }
+          if (previous) {
+            const local = projects.local ?? []
+            const worktrees = new Set(local.map((project) => project.worktree))
+            projects.local = [
+              ...local,
+              ...previous.filter((project) => {
+                if (worktrees.has(project.worktree)) return false
+                worktrees.add(project.worktree)
+                return true
+              }),
+            ]
+            delete projects[canonical]
+          }
+          const lastProject = { ...value.lastProject }
+          if (last !== undefined) {
+            lastProject.local ??= last
+            delete lastProject[canonical]
+          }
+          return { ...value, projects, lastProject }
+        }),
+        encode: SchemaGetter.transform((value) => value),
+      }),
+    ),
+  )
+}
+
+export const ModelState = Persistence.struct({
+  user: Persistence.array(
+    Persistence.struct({
+      providerID: Schema.String,
+      modelID: Schema.String,
+      visibility: Schema.Literals(["show", "hide"]),
+      favorite: Schema.optional(Schema.Boolean),
+    }),
+  ),
+  recent: Persistence.array(Persistence.struct({ providerID: Schema.String, modelID: Schema.String })),
+  variant: Schema.Record(
+    Schema.String,
+    Schema.mutableKey(
+      Schema.UndefinedOr(Schema.String).pipe(Schema.catchDecoding(() => Effect.succeed(Option.none()))),
+    ),
+  ),
+})
+
+export const VcsState = Persistence.struct({
+  value: Schema.optional(
+    Persistence.struct({
+      branch: Schema.optional(Schema.String),
+      default_branch: Schema.optional(Schema.String),
+    }),
+  ),
+})
+
+const ProjectMeta = Persistence.struct({
+  name: Schema.optional(Schema.String),
+  icon: Schema.optional(
+    Persistence.struct({
+      override: Schema.optional(Schema.String),
+      color: Schema.optional(Schema.String),
+    }),
+  ),
+  commands: Schema.optional(Persistence.struct({ start: Schema.optional(Schema.String) })),
+})
+
+export const ProjectState = Persistence.struct({
+  value: Schema.optional(ProjectMeta),
+})
+
+export const IconState = Persistence.struct({
+  value: Schema.optional(Schema.String),
+})
@@ -1,50 +1,25 @@
 import { describe, expect, test } from "bun:test"
-import { createRoot, createSignal } from "solid-js"
-import {
-  migrateCanonicalLocalServerState,
-  migrateServerAuthState,
-  resolveServerList,
-  ServerConnection,
-} from "./registry"
-import { ServerScope } from "@/runtime/server/scope"
+import { canRemoveServer, createServerProjects, resolveServerList, ServerConnection } from "./registry"
+import { Schema } from "effect"
+import { serverState } from "./persistence"
+import { createStore } from "solid-js/store"
+import { ServerScope } from "./scope"
+import { Persistence } from "@/runtime/persistence/schema"

-describe("migrateServerAuthState", () => {
-  test("removes legacy usernames without changing passwords or other saved state", () => {
-    const state = {
-      list: [
-        "http://localhost:4096",
-        { url: "https://flat.example", username: "legacy", password: "first" },
-        {
-          type: "http",
-          displayName: "Remote",
-          http: { url: "https://nested.example", username: "legacy", password: "second" },
-        },
-      ],
-      projects: { local: [{ worktree: "/project", expanded: true }] },
-    }
-    expect(migrateServerAuthState(state)).toEqual({
-      ...state,
-      list: [
-        "http://localhost:4096",
-        { url: "https://flat.example", password: "first" },
-        { type: "http", displayName: "Remote", http: { url: "https://nested.example", password: "second" } },
-      ],
-    })
-    expect(state.list[1]).toHaveProperty("username", "legacy")
-    expect(migrateServerAuthState(migrateServerAuthState(state))).toEqual(migrateServerAuthState(state))
+function serverSchema() {
+  return Persistence.withInitial(serverState(), {
+    list: [],
+    hidden: {},
+    projects: {},
+    lastProject: {},
+    recentlyClosed: {},
  })
-
-  test("preserves absent or malformed lists", () => {
-    expect(migrateServerAuthState(undefined)).toBeUndefined()
-    expect(migrateServerAuthState({ projects: {} })).toEqual({ projects: {} })
-    expect(migrateServerAuthState({ list: [null, 1, {}] })).toEqual({ list: [null, 1, {}] })
-  })
-})
+}

 describe("resolveServerList", () => {
  test("lets startup auth_token credentials override a persisted same-url server", () => {
    const list = resolveServerList({
-      stored: [{ url: "https://server.example.test" }],
+      stored: Schema.decodeUnknownSync(serverSchema())({ list: [{ url: "https://server.example.test" }] }).list,
      props: [
        {
          type: "http",
@@ -64,17 +39,14 @@ describe("resolveServerList", () => {
      password: "secret",
    })
    expect(list[0]?.type === "http" ? list[0].authToken : false).toBe(true)
-    expect(ServerConnection.key(list[0]!) as string).toBe("https://server.example.test")
+    expect(list[0] && String(ServerConnection.key(list[0]))).toBe("https://server.example.test")
  })

  test("keeps persisted credentials when startup has no auth_token", () => {
    const list = resolveServerList({
-      stored: [
-        {
-          url: "https://server.example.test",
-          password: "saved",
-        },
-      ],
+      stored: Schema.decodeUnknownSync(serverSchema())({
+        list: [{ url: "https://server.example.test", password: "saved" }],
+      }).list,
      props: [{ type: "http", http: { url: "https://server.example.test" } }],
    })

@@ -104,47 +76,42 @@ test("treats WSL sidecars as remote server connections", () => {
  expect(ServerConnection.local({ type: "http", http: { url: "https://server.example.test" } })).toBe(false)
 })

-describe("migrateCanonicalLocalServerState", () => {
-  test("moves an existing canonical web bucket into local scope", () => {
-    expect(
-      migrateCanonicalLocalServerState(
-        {
-          list: [],
-          projects: { "https://opencode.example.com": [{ worktree: "/remote", expanded: true }] },
-          lastProject: { "https://opencode.example.com": "/remote" },
-        },
-        ServerConnection.Key.make("https://opencode.example.com"),
-      ),
-    ).toEqual({
-      list: [],
-      projects: { local: [{ worktree: "/remote", expanded: true }] },
-      lastProject: { local: "/remote" },
-    })
-  })
+test("keeps exact persisted server identities and prevents removing provided servers", () => {
+  const stored = Schema.decodeUnknownSync(serverSchema())({
+    list: ["http://localhost:4096", "http://localhost:4096/", "http://127.0.0.1:4096"],
+  }).list
+  expect(resolveServerList({ stored }).map((server) => String(ServerConnection.key(server)))).toEqual([
+    "http://localhost:4096",
+    "http://localhost:4096/",
+    "http://127.0.0.1:4096",
+  ])
+  const key = ServerConnection.Key.make("http://localhost:4096")
+  expect(canRemoveServer({ key, stored })).toBe(true)
+  expect(canRemoveServer({ key, stored, provided: [{ type: "http", http: { url: key } }] })).toBe(false)
+})

-  test("preserves existing local state while merging a canonical web bucket", () => {
-    expect(
-      migrateCanonicalLocalServerState(
-        {
-          projects: {
-            local: [{ worktree: "/local", expanded: false }],
-            "https://opencode.example.com": [
-              { worktree: "/local", expanded: true },
-              { worktree: "/remote", expanded: true },
-            ],
-          },
-          lastProject: { local: "/local", "https://opencode.example.com": "/remote" },
-        },
-        ServerConnection.Key.make("https://opencode.example.com"),
-      ),
-    ).toEqual({
-      projects: {
-        local: [
-          { worktree: "/local", expanded: false },
-          { worktree: "/remote", expanded: true },
-        ],
-      },
-      lastProject: { local: "/local" },
-    })
+test("project actions update schema-derived state and follow dynamic server scopes", () => {
+  const [store, setStore] = createStore(Schema.decodeUnknownSync(serverSchema())({}))
+  const props: { server: ServerConnection.Key; canonicalLocalServer?: ServerConnection.Key } = {
+    server: ServerConnection.Key.make("https://remote.example"),
+  }
+  const projects = createServerProjects({
+    store,
+    setStore,
+    scope: () => ServerScope.fromServerKey(props.server, props.canonicalLocalServer),
  })
+  projects.open("/remote")
+  projects.collapse("/remote")
+  projects.touch("/remote")
+  expect(projects.list()).toEqual([{ worktree: "/remote", expanded: false }])
+  expect(projects.last()).toBe("/remote")
+  props.canonicalLocalServer = props.server
+  expect(projects.list()).toEqual([])
+  projects.open("/local")
+  projects.close("/local")
+  expect(projects.recentlyClosed()).toEqual(["/local"])
+  projects.open("/local")
+  expect(projects.recentlyClosed()).toEqual([])
+  expect(store.projects.local).toEqual([{ worktree: "/local", expanded: true }])
+  expect(store.projects[props.server]).toEqual([{ worktree: "/remote", expanded: false }])
 })
@@ -1,18 +1,12 @@
 import { createSimpleContext } from "@opencode-ai/ui/context"
-import { type Accessor, batch, createMemo } from "solid-js"
-import { createStore, type SetStoreFunction, type Store } from "solid-js/store"
+import { batch, createMemo } from "solid-js"
+import { type SetStoreFunction, type Store } from "solid-js/store"
 import { Persist, persisted } from "@/runtime/persistence/storage"
 import { pathKey } from "@/workspaces/path-key"
 import { ServerScope } from "@/runtime/server/scope"
+import { ServerHttp, ServerHttpBase, ServerKey, serverState } from "./persistence"

-type StoredProject = { worktree: string; expanded: boolean }
-type StoredServer = string | ServerConnection.HttpBase | ServerConnection.Http
-type ServerProjectState = {
-  projects: Record<string, StoredProject[]>
-  lastProject: Record<string, string>
-  recentlyClosed: Record<string, string[]>
-}
-const HEALTH_POLL_INTERVAL_MS = 10_000
+type ServerState = ReturnType<typeof serverState>["current"]["Type"]
 // The store retains more history than is displayed. Consumers filter recently closed entries
 // against the live project list (dropping deleted projects) and then cap the visible count via
 // RECENTLY_CLOSED_DISPLAY_LIMIT. Retaining extra history ensures entries that are temporarily
@@ -38,65 +32,12 @@ function isLocalHost(url: string) {
  if (host === "localhost" || host === "127.0.0.1") return "local"
 }

-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
-export function migrateServerAuthState(value: unknown) {
-  if (!isRecord(value) || !Array.isArray(value.list)) return value
-  return {
-    ...value,
-    list: value.list.map((server) => {
-      if (!isRecord(server)) return server
-      const http = isRecord(server.http) ? server.http : server
-      if (!("username" in http)) return server
-      const next = { ...http }
-      delete next.username
-      return http === server ? next : { ...server, http: next }
-    }),
-  }
-}
-
-export function migrateCanonicalLocalServerState(value: unknown, canonicalLocalServer?: ServerConnection.Key) {
-  if (!canonicalLocalServer || canonicalLocalServer === "local") return value
-  if (!isRecord(value)) return value
-  const projects = isRecord(value.projects) ? value.projects : undefined
-  const lastProject = isRecord(value.lastProject) ? value.lastProject : undefined
-  const previousProjects = projects?.[canonicalLocalServer]
-  const previousLastProject = lastProject?.[canonicalLocalServer]
-  if (!Array.isArray(previousProjects) && typeof previousLastProject !== "string") return value
-
-  const next = { ...value }
-  if (projects && Array.isArray(previousProjects)) {
-    const local = Array.isArray(projects.local) ? projects.local : []
-    const worktrees = new Set(
-      local.flatMap((project) => (isRecord(project) && typeof project.worktree === "string" ? [project.worktree] : [])),
-    )
-    const migrated = previousProjects.filter((project) => {
-      if (!isRecord(project) || typeof project.worktree !== "string") return true
-      if (worktrees.has(project.worktree)) return false
-      worktrees.add(project.worktree)
-      return true
-    })
-    const nextProjects: Record<string, unknown> = { ...projects, local: [...local, ...migrated] }
-    delete nextProjects[canonicalLocalServer]
-    next.projects = nextProjects
-  }
-  if (lastProject && typeof previousLastProject === "string") {
-    const nextLastProject = { ...lastProject }
-    if (typeof nextLastProject.local !== "string") nextLastProject.local = previousLastProject
-    delete nextLastProject[canonicalLocalServer]
-    next.lastProject = nextLastProject
-  }
-  return next
-}
-
-export function createServerProjects<T extends ServerProjectState>(input: {
+export function createServerProjects(input: {
  scope: () => ServerScope
-  store: Store<T>
-  setStore: SetStoreFunction<T>
+  store: Store<ServerState>
+  setStore: SetStoreFunction<ServerState>
 }) {
-  const setStore = input.setStore as unknown as SetStoreFunction<ServerProjectState>
+  const setStore = input.setStore
  const current = () => input.store.projects[input.scope()] ?? []
  const currentClosed = () => input.store.recentlyClosed?.[input.scope()] ?? []
  const remove = (directory: string) => {
@@ -162,22 +103,13 @@ export function createServerProjects<T extends ServerProjectState>(input: {

 export function resolveServerList(input: {
  props?: Array<ServerConnection.Any>
-  stored: StoredServer[]
+  stored: ServerConnection.Http[]
 }): Array<ServerConnection.Any> {
  const deduped = new Map<ServerConnection.Key, ServerConnection.Any>(
    input.props?.map((v) => [ServerConnection.key(v), v]) ?? [],
  )

-  for (const value of input.stored) {
-    const conn: ServerConnection.Http =
-      typeof value === "string"
-        ? {
-            type: "http" as const,
-            http: { url: value },
-          }
-        : "http" in value
-          ? value
-          : { type: "http", http: value }
+  for (const conn of input.stored) {
    const key = ServerConnection.key(conn)

    const existing = deduped.get(key)
@@ -196,28 +128,19 @@ export function resolveServerList(input: {
 export function canRemoveServer(input: {
  key: ServerConnection.Key
  provided?: Array<ServerConnection.Any>
-  stored: StoredServer[]
+  stored: ServerConnection.Http[]
 }) {
  if (input.provided?.some((server) => ServerConnection.key(server) === input.key)) return false
-  return input.stored.some((server) =>
-    typeof server === "string" ? server === input.key : ("type" in server ? server.http.url : server.url) === input.key,
-  )
+  return input.stored.some((server) => server.http.url === input.key)
 }

 export namespace ServerConnection {
  type Base = { displayName?: string; label?: string }

-  export type HttpBase = {
-    url: string
-    password?: string
-  }
+  export type HttpBase = typeof ServerHttpBase.Type

  // Regular web connections
-  export type Http = {
-    type: "http"
-    http: HttpBase
-    authToken?: boolean
-  } & Base
+  export type Http = typeof ServerHttp.Type

  export type Sidecar = {
    type: "sidecar"
@@ -259,8 +182,8 @@ export namespace ServerConnection {
    }
  }

-  export type Key = string & { _brand: "Key" }
-  export const Key = { make: (v: string) => v as Key }
+  export const Key = ServerKey
+  export type Key = typeof Key.Type

  export const builtin = (conn: Any) => conn.type === "sidecar" && conn.variant === "base"
  export const local = (conn?: Any) =>
@@ -280,19 +203,11 @@ export const { use: useServers, provider: ServersProvider } = createSimpleContex
        ...Persist.global("server"),
        sync: true,
        previousKey: "server.v3",
-        migrate: (value) => migrateCanonicalLocalServerState(migrateServerAuthState(value), props.canonicalLocalServer),
      },
-      createStore({
-        list: [] as StoredServer[],
-        hidden: {} as Record<string, boolean>,
-        projects: {} as Record<string, StoredProject[]>,
-        lastProject: {} as Record<string, string>,
-        recentlyClosed: {} as Record<string, string[]>,
-      }),
+      serverState(() => props.canonicalLocalServer),
+      { list: [], hidden: {}, projects: {}, lastProject: {}, recentlyClosed: {} },
    )

-    const url = (x: StoredServer) => (typeof x === "string" ? x : "type" in x ? x.http.url : x.url)
-
    const allServers = createMemo((): Array<ServerConnection.Any> => {
      return resolveServerList({ stored: store.list, props: props.servers })
    })
@@ -303,7 +218,7 @@ export const { use: useServers, provider: ServersProvider } = createSimpleContex
      if (!url_) return
      const conn: ServerConnection.Http = { ...input, authToken: undefined, http: { ...input.http, url: url_ } }
      return batch(() => {
-        const existing = store.list.findIndex((x) => url(x) === url_)
+        const existing = store.list.findIndex((x) => x.http.url === url_)
        if (existing !== -1) {
          setStore("list", existing, conn)
        } else {
@@ -314,7 +229,7 @@ export const { use: useServers, provider: ServersProvider } = createSimpleContex
    }

    function remove(key: ServerConnection.Key) {
-      const list = store.list.filter((x) => url(x) !== key)
+      const list = store.list.filter((x) => x.http.url !== key)
      batch(() => {
        setStore("list", list)
      })
@@ -12,6 +12,7 @@ import { createPermissionAutoApprover } from "@/session/requests/auto-approve"
 import { createServerNotificationState } from "@/shell/notifications/notification"
 import { Persist, persisted } from "@/runtime/persistence/storage"
 import { createDesktopData } from "./data"
+import { ModelState } from "./persistence"

 export const { use: useGlobal, provider: GlobalProvider } = createSimpleContext({
  name: "Global",
@@ -98,18 +99,11 @@ export const { use: useGlobal, provider: GlobalProvider } = createSimpleContext(
 })

 function createGlobalModels() {
-  const [store, setStore, _, ready] = persisted(
-    Persist.global("model"),
-    createStore<{
-      user: Array<{ providerID: string; modelID: string; visibility: "show" | "hide"; favorite?: boolean }>
-      recent: Array<{ providerID: string; modelID: string }>
-      variant?: Record<string, string | undefined>
-    }>({
-      user: [],
-      recent: [],
-      variant: {},
-    }),
-  )
+  const [store, setStore, _, ready] = persisted(Persist.global("model"), ModelState, {
+    user: [],
+    recent: [],
+    variant: {},
+  })
  const [recent] = createResource(
    async () => {
      const value = store.recent
@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import { OPEN_APPS, OpenAppPreferences } from "./open-in-app"
+import { Persistence } from "@/runtime/persistence/schema"
+
+const decode = Schema.decodeUnknownSync(Persistence.withInitial(OpenAppPreferences, { app: "finder" }))
+
+describe("open app preferences", () => {
+  test.each([...OPEN_APPS])("preserves the %s preference", (app) => {
+    expect(decode({ app })).toEqual({ app })
+  })
+
+  test.each([undefined, null, 42, "unknown", {}])("defaults invalid selection %p", (app) => {
+    expect(decode({ app })).toEqual({ app: "finder" })
+  })
+
+  test("defaults an absent selection", () => {
+    expect(decode({})).toEqual({ app: "finder" })
+  })
+})
@@ -5,6 +5,8 @@ import { usePlatform } from "@/runtime/platform/platform"
 import { Persist, persisted } from "@/runtime/persistence/storage"
 import { showToast } from "@/shell/notifications/toast"
 import { useServer } from "@/runtime/server/current"
+import { Schema } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"

 export const OPEN_APPS = [
  "vscode",
@@ -26,6 +28,10 @@ export const OPEN_APPS = [
 export type OpenApp = (typeof OPEN_APPS)[number]
 export type OpenAppOS = "macos" | "windows" | "linux" | "unknown"

+export const OpenAppPreferences = Persistence.struct({
+  app: Schema.Literals(OPEN_APPS),
+})
+
 export const MAC_OPEN_APPS = [
  {
    id: "vscode",
@@ -163,7 +169,7 @@ export function useOpenInApp(input: { directory: () => string }) {
    ] as const
  })

-  const [prefs, setPrefs] = persisted(Persist.global("open.app"), createStore({ app: "finder" as OpenApp | "finder" }))
+  const [prefs, setPrefs] = persisted(Persist.global("open.app"), OpenAppPreferences, { app: "finder" })
  const [menu, setMenu] = createStore({ open: false })
  const [openRequest, setOpenRequest] = createStore({
    app: undefined as OpenApp | undefined,
@@ -129,6 +129,7 @@ export function useSessionModel() {
    layout: {
      tabs: layout.tabs,
      view: layout.view,
+      tabKey: layout.tabKey,
    },
    ownership: createSessionOwnership(layout.sessionKey),
    tabs: {
@@ -5,18 +5,24 @@ import {
  type SessionReviewExpandMode,
 } from "@opencode-ai/session-ui/v2/session-review-v2"
 import { createSignal } from "solid-js"
-import { createStore } from "solid-js/store"
+import { Schema } from "effect"
 import type { Platform } from "@/runtime/platform/platform"
 import { Persist, persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
+
+const ReviewPanel = Persistence.struct({
+  sidebarOpened: Schema.Boolean,
+  sidebarWidth: Schema.Finite.check(
+    Schema.isBetween({ minimum: SESSION_REVIEW_V2_SIDEBAR_WIDTH_MIN, maximum: SESSION_REVIEW_V2_SIDEBAR_WIDTH_MAX }),
+  ),
+  expandMode: Schema.Literals(["expand", "collapse"]),
+})

 export function createReviewPanelState(platform?: Platform) {
  const [store, setStore, , ready] = persisted(
    Persist.global("review-panel-v2"),
-    createStore({
-      sidebarOpened: true,
-      sidebarWidth: SESSION_REVIEW_V2_SIDEBAR_WIDTH_DEFAULT,
-      expandMode: "collapse" as SessionReviewExpandMode,
-    }),
+    ReviewPanel,
+    { sidebarOpened: true, sidebarWidth: SESSION_REVIEW_V2_SIDEBAR_WIDTH_DEFAULT, expandMode: "collapse" },
    platform,
  )
  // The filter is transient by design: a persisted filter would silently hide
@@ -12,6 +12,7 @@ export function createSessionScreenLayout(session: SessionModel) {
  const layout = useLayout()
  const settings = useSettings()
  const size = createSizing()
+  const view = session.layout.view
  const reviewOpen = createMemo(() => session.isDesktop() && session.layout.view().reviewPanel.opened())
  const reviewPanelOpen = createMemo(() => reviewOpen() && !!session.identity.params.id)
  const terminalOpen = createMemo(() => session.layout.view().terminal.opened())
@@ -42,7 +43,7 @@ export function createSessionScreenLayout(session: SessionModel) {
  const splitReview = createMemo(() => reviewPanelOpen() && layout.review.diffStyle() === "split")
  const resizedWidth = createMemo(() =>
    clampSessionPanelWidth({
-      width: layout.session.width(),
+      width: view().reviewPanel.width(),
      available: available(),
      split: splitReview(),
    }),
@@ -72,7 +73,7 @@ export function createSessionScreenLayout(session: SessionModel) {
  }, panelLayout().stacked)
  const sideRegionOpen = createMemo(() => reviewPanelOpen() || fileTreeOpen())
  const terminalPane = createMemo(() =>
-    Math.min(layout.terminal.height(), typeof window === "undefined" ? 600 : window.innerHeight * 0.6),
+    Math.min(view().terminal.height(), typeof window === "undefined" ? 600 : window.innerHeight * 0.6),
  )
  const terminalPaneHeight = createMemo(() => `${terminalPane()}px`)
  const sideHeight = createMemo(() => rowSize.height)
@@ -11,10 +11,8 @@ import {
  on,
 } from "solid-js"
 import { createStore } from "solid-js/store"
-import createPresence from "solid-presence"
 import { ResizeHandle } from "@opencode-ai/ui/resize-handle"
 import { SessionHeader } from "@/session/header/session-header"
-import { useLayout } from "@/shell/state/layout"
 import { MessageTimeline, SessionSummaryPanel } from "@/session/timeline/message-timeline"
 import { useServer } from "@/runtime/server/current"
 import { projectForSession } from "@/shell/layout/helpers"
@@ -31,6 +29,7 @@ import { SessionContextTab } from "./files/session-context-tab"
 import { createSessionTimelineInteraction } from "./timeline/interaction"
 import { ActiveSessionComposerRegion, createActiveSessionRegion } from "./composer/region"
 import { SessionIdentityHeader } from "./session-identity-header"
+import { createAnimatedPresence } from "@/runtime/animated-presence"

 const SessionMobileFiles = lazy(async () => {
  const { SessionMobileFiles } = await import("./files/session-mobile-files")
@@ -39,7 +38,6 @@ const SessionMobileFiles = lazy(async () => {

 export function SessionScreen(props: { session: SessionModel }) {
  const session = props.session
-  const layout = useLayout()
  const server = useServer()
  const detailsProject = createMemo(() => {
    const info = session.data.info()
@@ -66,14 +64,40 @@ export function SessionScreen(props: { session: SessionModel }) {
  const sideVisible = createMemo(() => isDesktop() && screen.side.layout().visible)
  const sideTerminalVisible = createMemo(() => isDesktop() && screen.terminal.side() && screen.terminal.open())
  const bottomTerminalVisible = createMemo(() => isDesktop() && screen.terminal.open() && screen.terminal.bottom())
-  const sidePresence = createPresence({
-    show: sideVisible,
-    element: () => elements.side ?? null,
-  })
-  const bottomTerminalPresence = createPresence({
-    show: bottomTerminalVisible,
-    element: () => elements.bottomTerminal ?? null,
+  const sidePresence = createAnimatedPresence(
+    () => sideVisible() || undefined,
+    () => elements.side ?? null,
+    session.layout.tabKey,
+  )
+  const bottomTerminalPresence = createAnimatedPresence(
+    () => bottomTerminalVisible() || undefined,
+    () => elements.bottomTerminal ?? null,
+    session.layout.tabKey,
+  )
+  const sideMotion = createMemo<{
+    key?: string
+    region: boolean
+    terminal: boolean
+    animateRegion: boolean
+    animateTerminal: boolean
+  }>((previous) => {
+    const key = session.layout.tabKey()
+    const region = screen.side.region.open()
+    const terminal = sideTerminalVisible()
+    const sameTab = previous?.key === key
+    return {
+      key,
+      region,
+      terminal,
+      animateRegion: !!previous && sameTab && previous.region !== region,
+      animateTerminal: !!previous && sameTab && previous.terminal !== terminal,
+    }
  })
+  const paneAnimating = () =>
+    sidePresence.animate() ||
+    sideMotion().animateRegion ||
+    sideMotion().animateTerminal ||
+    bottomTerminalPresence.animate()
  createEffect(() => {
    if (sideTerminalVisible()) setStore("sideTerminalPresent", true)
    if (bottomTerminalVisible()) setStore("bottomTerminalCached", true)
@@ -256,7 +280,8 @@ export function SessionScreen(props: { session: SessionModel }) {
            classList={{
              "@container relative z-10 shrink-0 flex flex-col min-h-0 h-full flex-1 md:flex-none transition-[width]": true,
              "duration-[240ms] ease-[cubic-bezier(0.22,1,0.36,1)] will-change-[width] motion-reduce:transition-none":
-                !screen.size.active(),
+                !screen.size.active() && sidePresence.animate(),
+              "transition-none": screen.size.active() || !sidePresence.animate(),
            }}
            data-slot="session-chat-panel"
            style={{
@@ -279,18 +304,18 @@ export function SessionScreen(props: { session: SessionModel }) {
                  max={screen.panel.max()}
                  onResize={(width) => {
                    screen.size.touch()
-                    layout.session.resize(width)
+                    session.layout.view().reviewPanel.resize(width)
                  }}
                />
              </div>
            </Show>
          </div>

-          <Show when={sidePresence.present() || store.sideTerminalPresent}>
+          <Show when={sidePresence.present() || store.sideReviewPresent || store.sideTerminalPresent}>
            <div
              ref={(element) => setElements("side", element)}
              data-slot="session-side-panel-presence"
-              data-opened={sideVisible()}
+              data-opened={sidePresence.animate() ? sidePresence.show() : undefined}
              onAnimationEnd={(event) => {
                if (event.currentTarget !== event.target) return
                if (event.animationName !== "terminal-panel-presence-in" || !sideVisible()) return
@@ -311,15 +336,15 @@ export function SessionScreen(props: { session: SessionModel }) {
                  data-slot="session-side-region"
                  classList={{
                    "absolute inset-x-0 top-0 min-h-0 overflow-visible transition-[height] duration-[240ms] ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none": true,
-                    "will-change-[height]": !screen.size.active() && store.sideHeightMotion,
-                    "transition-none": screen.size.active() || !store.sideHeightMotion,
+                    "will-change-[height]": !screen.size.active() && store.sideHeightMotion && paneAnimating(),
+                    "transition-none": screen.size.active() || !store.sideHeightMotion || !paneAnimating(),
                  }}
                  style={{ height: screen.side.region.height() }}
                >
                  <Show when={store.sideRegionPresent}>
                    <div
                      data-slot="session-side-region-presence"
-                      data-opened={screen.side.region.open()}
+                      data-opened={sideMotion().animateRegion ? sideMotion().region : undefined}
                      class="absolute inset-0"
                      onAnimationEnd={(event) => {
                        if (event.currentTarget !== event.target) return
@@ -341,6 +366,7 @@ export function SessionScreen(props: { session: SessionModel }) {
                      "relative z-0 shrink-0 overflow-visible bg-v2-background-bg-deep transition-[height] duration-[40ms] ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none": true,
                      "delay-0": !screen.side.gap.closing(),
                      "delay-[200ms]": screen.side.gap.closing(),
+                      "transition-none": !paneAnimating(),
                    }}
                    style={{ height: screen.side.gap.height() }}
                    onPointerDown={() => screen.size.start()}
@@ -349,13 +375,13 @@ export function SessionScreen(props: { session: SessionModel }) {
                      <ResizeHandle
                        class="!relative !inset-auto !h-full !w-full !transform-none"
                        direction="vertical"
-                        size={layout.terminal.height()}
+                        size={session.layout.view().terminal.height()}
                        min={100}
                        max={typeof window === "undefined" ? 600 : window.innerHeight * 0.6}
                        collapseThreshold={50}
                        onResize={(height) => {
                          screen.size.touch()
-                          layout.terminal.resize(height)
+                          session.layout.view().terminal.resize(height)
                        }}
                        onCollapse={() => session.layout.view().terminal.close()}
                      />
@@ -365,15 +391,15 @@ export function SessionScreen(props: { session: SessionModel }) {
                    data-slot="session-side-terminal-region"
                    classList={{
                      "relative z-10 min-h-0 shrink-0 overflow-visible transition-[height] duration-[240ms] ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none": true,
-                      "will-change-[height]": !screen.size.active() && store.sideHeightMotion,
-                      "transition-none": screen.size.active() || !store.sideHeightMotion,
+                      "will-change-[height]": !screen.size.active() && store.sideHeightMotion && paneAnimating(),
+                      "transition-none": screen.size.active() || !store.sideHeightMotion || !paneAnimating(),
                    }}
                    style={{ height: screen.side.terminal.height() }}
                  >
                    <Show when={store.sideTerminalPresent}>
                      <div
                        data-slot="side-terminal-panel-presence"
-                        data-opened={sideTerminalVisible()}
+                        data-opened={sideMotion().animateTerminal ? sideMotion().terminal : undefined}
                        class="absolute inset-0 rounded-[10px] bg-v2-background-bg-base shadow-[var(--v2-elevation-raised)]"
                      >
                        <div data-slot="side-terminal-panel-clip" class="size-full overflow-clip rounded-[10px]">
@@ -381,6 +407,7 @@ export function SessionScreen(props: { session: SessionModel }) {
                            fill
                            framed={false}
                            present={store.sideTerminalPresent}
+                            animate={sidePresence.animate() || sideMotion().animateTerminal}
                            contentHeight={screen.side.terminal.contentHeight()}
                          />
                        </div>
@@ -397,7 +424,7 @@ export function SessionScreen(props: { session: SessionModel }) {
          <div
            ref={(element) => setElements("bottomTerminal", element)}
            data-slot="terminal-panel-presence"
-            data-opened={bottomTerminalVisible()}
+            data-opened={bottomTerminalPresence.animate() ? bottomTerminalPresence.show() : undefined}
            classList={{
              hidden: !bottomTerminalPresence.present(),
              "relative min-h-0 shrink-0": isDesktop(),
@@ -408,19 +435,23 @@ export function SessionScreen(props: { session: SessionModel }) {
                <ResizeHandle
                  class="!relative !inset-auto !h-full !w-full !transform-none"
                  direction="vertical"
-                  size={layout.terminal.height()}
+                  size={session.layout.view().terminal.height()}
                  min={100}
                  max={typeof window === "undefined" ? 600 : window.innerHeight * 0.6}
                  collapseThreshold={50}
                  onResize={(height) => {
                    screen.size.touch()
-                    layout.terminal.resize(height)
+                    session.layout.view().terminal.resize(height)
                  }}
                  onCollapse={() => session.layout.view().terminal.close()}
                />
              </div>
            </Show>
-            <TerminalPanel stacked={isDesktop()} present={store.bottomTerminalCached} />
+            <TerminalPanel
+              stacked={isDesktop()}
+              present={store.bottomTerminalCached}
+              animate={bottomTerminalPresence.animate()}
+            />
          </div>
        </Show>
      </div>
@@ -5,6 +5,8 @@ import { SessionRouteKey, SessionStateKey } from "@/runtime/server/scope"
 import { useWorkspaceLocation } from "@/workspaces/location"
 import { useServerSDK } from "@/runtime/server/client"
 import { base64Encode } from "@opencode-ai/util/encode"
+import { ServerConnection } from "@/runtime/server/registry"
+import { findSessionTab, tabKey, useTabs } from "@/shell/tabs/tabs"

 export const useSessionKey = () => {
  const params = useParams()
@@ -19,12 +21,32 @@ export const useSessionKey = () => {

 export const useSessionLayout = () => {
  const layout = useLayout()
+  const tabs = useTabs()
  const { params, sessionKey, workspaceKey } = useSessionKey()
+  const serverSDK = useServerSDK()
+  const currentTab = createMemo(() => {
+    if (!params.id) return
+    return findSessionTab(tabs.store, ServerConnection.key(serverSDK.server), params.id)
+  })
+  const panes = {
+    terminalOpened: () => tabs.pane(currentTab(), "terminal"),
+    setTerminalOpened: (opened: boolean) => tabs.setPane(currentTab(), "terminal", opened),
+    terminalHeight: () => tabs.paneSize(currentTab(), "terminalHeight"),
+    setTerminalHeight: (height: number) => tabs.setPaneSize(currentTab(), "terminalHeight", height),
+    reviewOpened: () => tabs.pane(currentTab(), "review"),
+    setReviewOpened: (opened: boolean) => tabs.setPane(currentTab(), "review", opened),
+    sessionWidth: () => tabs.paneSize(currentTab(), "sessionWidth"),
+    setSessionWidth: (width: number) => tabs.setPaneSize(currentTab(), "sessionWidth", width),
+  }
  return {
    params,
    sessionKey,
    workspaceKey,
+    tabKey: createMemo(() => {
+      const tab = currentTab()
+      return tab && tabKey(tab)
+    }),
    tabs: createMemo(() => layout.tabs(sessionKey)),
-    view: createMemo(() => layout.view(sessionKey)),
+    view: createMemo(() => layout.view(sessionKey, panes)),
  }
 }
@@ -2,11 +2,14 @@ import { beforeAll, describe, expect, mock, test } from "bun:test"
 import { ServerScope } from "@/runtime/server/scope"
 import { base64Encode } from "@opencode-ai/util/encode"
 import { Persist } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
 import type { Platform } from "@/runtime/platform/platform"
+import { Schema } from "effect"

 let getWorkspaceTerminalCacheKey: typeof import("./context").getWorkspaceTerminalCacheKey
 let clearWorkspaceTerminals: typeof import("./context").clearWorkspaceTerminals
-let migrateTerminalState: (value: unknown) => unknown
+let decodeTerminalState: (value: unknown) => unknown
+let roundTripTerminalState: (value: unknown) => unknown

 beforeAll(async () => {
  mock.module("@solidjs/router", () => ({
@@ -15,16 +18,13 @@ beforeAll(async () => {
    useLocation: () => ({}),
    useSearchParams: () => [{}, () => undefined],
  }))
-  mock.module("@opencode-ai/ui/context", () => ({
-    createSimpleContext: () => ({
-      use: () => undefined,
-      provider: () => undefined,
-    }),
-  }))
  const mod = await import("./context")
  getWorkspaceTerminalCacheKey = mod.getWorkspaceTerminalCacheKey
  clearWorkspaceTerminals = mod.clearWorkspaceTerminals
-  migrateTerminalState = mod.migrateTerminalState
+  const schema = Persistence.withInitial(mod.TerminalState, { all: [] })
+  decodeTerminalState = Schema.decodeUnknownSync(schema)
+  roundTripTerminalState = (value) =>
+    Schema.decodeUnknownSync(schema)(Schema.encodeSync(schema)(Schema.decodeUnknownSync(schema)(value)))
 })

 describe("getWorkspaceTerminalCacheKey", () => {
@@ -61,10 +61,10 @@ describe("getWorkspaceTerminalCacheKey", () => {
  })
 })

-describe("migrateTerminalState", () => {
+describe("TerminalState", () => {
  test("drops invalid terminals and restores a valid active terminal", () => {
    expect(
-      migrateTerminalState({
+      decodeTerminalState({
        active: "missing",
        all: [
          null,
@@ -85,7 +85,7 @@ describe("migrateTerminalState", () => {

  test("keeps a valid active id", () => {
    expect(
-      migrateTerminalState({
+      decodeTerminalState({
        active: "two",
        all: [
          { id: "one", title: "Terminal 1" },
@@ -100,4 +100,44 @@ describe("migrateTerminalState", () => {
      ],
    })
  })
+
+  test("defaults missing and malformed fields without dropping usable terminals", () => {
+    expect(decodeTerminalState({})).toEqual({ active: undefined, all: [] })
+    expect(decodeTerminalState({ active: 2, all: "invalid" })).toEqual({ active: undefined, all: [] })
+    expect(decodeTerminalState({ all: [null, {}, { id: "" }, { id: 2 }] })).toEqual({ active: undefined, all: [] })
+    expect(
+      decodeTerminalState({
+        all: [
+          {
+            id: "one",
+            title: "Terminal 3",
+            titleNumber: Infinity,
+            rows: "24",
+            cols: 80,
+            buffer: false,
+            cursor: NaN,
+            scrollY: 0,
+          },
+          { id: "two", title: null, titleNumber: -1, buffer: "saved", cursor: 0 },
+        ],
+      }),
+    ).toEqual({
+      active: "one",
+      all: [
+        { id: "one", title: "Terminal 3", titleNumber: 3, cols: 80, scrollY: 0 },
+        { id: "two", title: "", titleNumber: 0, buffer: "saved", cursor: 0 },
+      ],
+    })
+  })
+
+  test("round trips normalized terminal state", () => {
+    const value = {
+      active: "two",
+      all: [
+        { id: "one", title: "Terminal 1", titleNumber: 1 },
+        { id: "two", title: "logs", titleNumber: 4, rows: 24, cols: 80, buffer: "output", cursor: 12, scrollY: 3 },
+      ],
+    }
+    expect(roundTripTerminalState(value)).toEqual(value)
+  })
 })
@@ -8,81 +8,51 @@ import { base64Encode } from "@opencode-ai/util/encode"
 import { defaultTitle, titleNumber } from "./title"
 import { Persist, persisted, removePersisted } from "@/runtime/persistence/storage"
 import { ScopedKey, ServerScope } from "@/runtime/server/scope"
+import { Persistence } from "@/runtime/persistence/schema"
+import { Schema, SchemaGetter } from "effect"

-export type LocalPTY = {
-  id: string
-  title: string
-  titleNumber: number
-  rows?: number
-  cols?: number
-  buffer?: string
-  scrollY?: number
-  cursor?: number
-}
+const PTY = Persistence.struct({
+  id: Schema.NonEmptyString,
+  title: Persistence.fallback(Schema.String, () => ""),
+  titleNumber: Persistence.fallback(Schema.Finite, () => 0),
+  rows: Persistence.optional(Schema.Finite),
+  cols: Persistence.optional(Schema.Finite),
+  buffer: Persistence.optional(Schema.String),
+  scrollY: Persistence.optional(Schema.Finite),
+  cursor: Persistence.optional(Schema.Finite),
+})
+
+export type LocalPTY = typeof PTY.Type

 const WORKSPACE_KEY = "__workspace__"
 const MAX_TERMINAL_SESSIONS = 20

-function record(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value)
-}
-
-function text(value: unknown) {
-  return typeof value === "string" ? value : undefined
-}
-
-function num(value: unknown) {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined
-}
-
 function numberFromTitle(title: string) {
  return titleNumber(title, MAX_TERMINAL_SESSIONS)
 }

-function pty(value: unknown): LocalPTY | undefined {
-  if (!record(value)) return
+const State = Persistence.struct({
+  active: Persistence.optional(Schema.String),
+  all: Persistence.array(PTY),
+})

-  const id = text(value.id)
-  if (!id) return
-
-  const title = text(value.title) ?? ""
-  const number = num(value.titleNumber)
-  const rows = num(value.rows)
-  const cols = num(value.cols)
-  const buffer = text(value.buffer)
-  const scrollY = num(value.scrollY)
-  const cursor = num(value.cursor)
-
-  return {
-    id,
-    title,
-    titleNumber: number && number > 0 ? number : (numberFromTitle(title) ?? 0),
-    ...(rows !== undefined ? { rows } : {}),
-    ...(cols !== undefined ? { cols } : {}),
-    ...(buffer !== undefined ? { buffer } : {}),
-    ...(scrollY !== undefined ? { scrollY } : {}),
-    ...(cursor !== undefined ? { cursor } : {}),
-  }
-}
-
-export function migrateTerminalState(value: unknown) {
-  if (!record(value)) return value
-
-  const seen = new Set<string>()
-  const all = (Array.isArray(value.all) ? value.all : []).flatMap((item) => {
-    const next = pty(item)
-    if (!next || seen.has(next.id)) return []
-    seen.add(next.id)
-    return [next]
-  })
-
-  const active = text(value.active)
-
-  return {
-    active: active && seen.has(active) ? active : all[0]?.id,
-    all,
-  }
-}
+export const TerminalState = State.pipe(
+  Schema.decodeTo(Schema.toType(State), {
+    decode: SchemaGetter.transform((value) => {
+      const seen = new Set<string>()
+      const all = value.all.flatMap((pty) => {
+        if (seen.has(pty.id)) return []
+        seen.add(pty.id)
+        return [{ ...pty, titleNumber: pty.titleNumber > 0 ? pty.titleNumber : (numberFromTitle(pty.title) ?? 0) }]
+      })
+      return {
+        active: value.active && seen.has(value.active) ? value.active : all[0]?.id,
+        all,
+      }
+    }),
+    encode: SchemaGetter.transform((value) => value),
+  }),
+)

 export function getWorkspaceTerminalCacheKey(dir: string, scope: ServerScope = ServerScope.local) {
  return ScopedKey.from(scope, dir, WORKSPACE_KEY)
@@ -131,18 +101,7 @@ function createWorkspaceTerminalSession(
 ) {
  const location = { directory: sdk.directory }

-  const [store, setStore, _, ready] = persisted(
-    {
-      ...terminalPersistTarget(scope, dir),
-      migrate: migrateTerminalState,
-    },
-    createStore<{
-      active?: string
-      all: LocalPTY[]
-    }>({
-      all: [],
-    }),
-  )
+  const [store, setStore, _, ready] = persisted(terminalPersistTarget(scope, dir), TerminalState, { all: [] })
  const [ui, setUi] = createStore({
    focus: undefined as { request: number; id?: string; pending: boolean } | undefined,
  })
@@ -17,7 +17,6 @@ import { SortableTerminalTab } from "@/session/terminal/tab"
 import { Terminal } from "@/session/terminal/terminal"
 import { useCommand } from "@/shell/commands/command"
 import { useLanguage } from "@/runtime/i18n/language"
-import { useLayout } from "@/shell/state/layout"
 import { useTerminal, type LocalPTY } from "@/session/terminal/context"
 import { useWorkspaceLocation } from "@/workspaces/location"
 import { terminalTabLabel } from "@/session/terminal/terminal-label"
@@ -45,9 +44,9 @@ export function TerminalPanel(
    present?: boolean
    contentHeight?: string
    embedded?: boolean
+    animate?: boolean
  } = {},
 ) {
-  const layout = useLayout()
  const terminal = useTerminal()
  const sdk = useWorkspaceLocation()
  const language = useLanguage()
@@ -57,7 +56,7 @@ export function TerminalPanel(
  const isDesktop = createMediaQuery("(min-width: 768px)")
  const opened = createMemo(() => view().terminal.opened())
  const size = createSizing()
-  const height = createMemo(() => layout.terminal.height())
+  const height = createMemo(() => view().terminal.height())
  const close = () => view().terminal.close()
  let root: HTMLElement | undefined
  let tabList: HTMLDivElement | undefined
@@ -238,10 +237,11 @@ export function TerminalPanel(
      pane={pane()}
      max={max()}
      resizing={size.active()}
+      animate={props.animate}
      onResizeStart={size.start}
      onResize={(next) => {
        size.touch()
-        layout.terminal.resize(next)
+        view().terminal.resize(next)
      }}
      onCollapse={close}
    >
@@ -15,6 +15,7 @@ export function TerminalSurface(
    pane: number
    max: number
    resizing: boolean
+    animate?: boolean
    onResizeStart: () => void
    onResize: (height: number) => void
    onCollapse: () => void
@@ -27,7 +28,9 @@ export function TerminalSurface(
      id="terminal-panel"
      data-component="terminal-panel"
      data-opened={props.opened}
-      data-size-animated={!props.embedded && !props.resizing && (!props.desktop || props.stacked)}
+      data-size-animated={
+        props.animate !== false && !props.embedded && !props.resizing && (!props.desktop || props.stacked)
+      }
      role="region"
      aria-label={props.label}
      aria-hidden={!props.opened}
@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
+import { GoUpsellState } from "./usage-exceeded-dialogs"
+import { Persistence } from "@/runtime/persistence/schema"
+
+const decode = Schema.decodeUnknownSync(
+  Persistence.withInitial(GoUpsellState, {
+    go_upsell_last_seen_at: null,
+    go_upsell_dont_show: null,
+    go_upsell_account_rate_limit_last_seen_at: null,
+    go_upsell_account_rate_limit_dont_show: null,
+  }),
+)
+
+describe("usage exceeded preferences", () => {
+  test("defaults unseen prompts", () => {
+    expect(decode({})).toEqual({
+      go_upsell_last_seen_at: null,
+      go_upsell_dont_show: null,
+      go_upsell_account_rate_limit_last_seen_at: null,
+      go_upsell_account_rate_limit_dont_show: null,
+    })
+  })
+
+  test("preserves timestamps while recovering malformed siblings", () => {
+    expect(
+      decode({
+        go_upsell_last_seen_at: 123,
+        go_upsell_dont_show: "true",
+        go_upsell_account_rate_limit_last_seen_at: Infinity,
+        go_upsell_account_rate_limit_dont_show: 456,
+      }),
+    ).toEqual({
+      go_upsell_last_seen_at: 123,
+      go_upsell_dont_show: null,
+      go_upsell_account_rate_limit_last_seen_at: null,
+      go_upsell_account_rate_limit_dont_show: 456,
+    })
+  })
+})
@@ -2,7 +2,8 @@ import { useWorkspaceLocation } from "@/workspaces/location"
 import { Persist, persisted } from "@/runtime/persistence/storage"
 import type { SessionStatus } from "@opencode-ai/client/promise"
 import { onCleanup } from "solid-js"
-import { createStore } from "solid-js/store"
+import { Schema } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"
 import { useSessionLayout } from "./session-layout"
 import { useDialog, useI18n } from "@opencode-ai/ui/context"
 import { DialogUsageExceeded } from "@/providers/connect/usage-exceeded"
@@ -14,6 +15,13 @@ const GO_UPSELL_ACCOUNT_RATE_LIMIT_DONT_SHOW = "go_upsell_account_rate_limit_don
 const GO_UPSELL_WINDOW = 86_400_000 // 24 hrs
 const GO_UPSELL_PROVIDERS = new Set(["opencode", "opencode-go"])

+export const GoUpsellState = Persistence.struct({
+  [GO_UPSELL_FREE_TIER_LAST_SEEN_AT]: Schema.NullOr(Schema.Finite),
+  [GO_UPSELL_FREE_TIER_DONT_SHOW]: Schema.NullOr(Schema.Finite),
+  [GO_UPSELL_ACCOUNT_RATE_LIMIT_LAST_SEEN_AT]: Schema.NullOr(Schema.Finite),
+  [GO_UPSELL_ACCOUNT_RATE_LIMIT_DONT_SHOW]: Schema.NullOr(Schema.Finite),
+})
+
 function goUpsellKeys(status: SessionStatus) {
  if (status.type !== "retry" || !status.action) return
  const { action } = status
@@ -39,15 +47,12 @@ export function useUsageExceededDialogs() {
  const { t, locale } = useI18n()
  const isEnglish = () => locale() === "en"

-  const [goUpsellState, setGoUpsellState] = persisted(
-    Persist.global("go-upsell"),
-    createStore({
-      [GO_UPSELL_FREE_TIER_LAST_SEEN_AT]: null as null | number,
-      [GO_UPSELL_FREE_TIER_DONT_SHOW]: null as null | number,
-      [GO_UPSELL_ACCOUNT_RATE_LIMIT_LAST_SEEN_AT]: null as null | number,
-      [GO_UPSELL_ACCOUNT_RATE_LIMIT_DONT_SHOW]: null as null | number,
-    }),
-  )
+  const [goUpsellState, setGoUpsellState] = persisted(Persist.global("go-upsell"), GoUpsellState, {
+    [GO_UPSELL_FREE_TIER_LAST_SEEN_AT]: null,
+    [GO_UPSELL_FREE_TIER_DONT_SHOW]: null,
+    [GO_UPSELL_ACCOUNT_RATE_LIMIT_LAST_SEEN_AT]: null,
+    [GO_UPSELL_ACCOUNT_RATE_LIMIT_DONT_SHOW]: null,
+  })

  onCleanup(
    sdk().event.on("session.status", (evt) => {
@@ -1,16 +1,32 @@
 import { describe, expect, test } from "bun:test"
-import { migrateSettings, monoDefault, monoFontFamily, sansDefault, sansFontFamily, terminalFontFamily } from "./model"
+import { Schema } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"
+import {
+  settingsSchema,
+  settingsPersistence,
+  defaultSettings,
+  monoDefault,
+  monoFontFamily,
+  sansDefault,
+  sansFontFamily,
+  terminalFontFamily,
+} from "./model"
+
+const schema = Persistence.withInitial(settingsPersistence, defaultSettings)
+const decode = Schema.decodeUnknownSync(schema)
+const encode = Schema.encodeSync(schema)

 describe("settings reasoning mode migration", () => {
  test.each([
    [true, "full"],
    [false, "compact"],
-  ])("maps persisted reasoning summaries %s to %s", (showReasoningSummaries, reasoningMode) => {
+  ] as const)("maps persisted reasoning summaries %s to %s", (showReasoningSummaries, reasoningMode) => {
    const value = { general: { showReasoningSummaries, showTerminal: true }, appearance: { fontSize: 16 } }
-    expect(migrateSettings(value)).toEqual({
-      ...value,
-      general: { ...value.general, reasoningMode },
-    })
+    const settings = decode(value)
+    expect(settings.general.reasoningMode).toBe(reasoningMode)
+    expect(settings.general.showTerminal).toBe(true)
+    expect(settings.appearance.fontSize).toBe(16)
+    expect(settings.general).not.toHaveProperty("showReasoningSummaries")
    expect(value.general).not.toHaveProperty("reasoningMode")
  })

@@ -19,13 +35,151 @@ describe("settings reasoning mode migration", () => {
    (reasoningMode) => {
      ;[true, false].forEach((showReasoningSummaries) => {
        const value = { general: { reasoningMode, showReasoningSummaries } }
-        expect(migrateSettings(value)).toBe(value)
+        expect(decode(value).general.reasoningMode).toBe(reasoningMode)
      })
    },
  )

-  test.each([undefined, null, {}, { general: {} }])("leaves missing legacy settings to the defaults: %j", (value) => {
-    expect(migrateSettings(value)).toBe(value)
+  test.each([undefined, null, {}, { showReasoningSummaries: "true" }])(
+    "defaults invalid or absent legacy settings: %j",
+    (general) => {
+      expect(decode({ general }).general.reasoningMode).toBe("compact")
+    },
+  )
+
+  test("migrates an undefined current mode but defaults an invalid current mode", () => {
+    expect(decode({ general: { reasoningMode: undefined, showReasoningSummaries: true } }).general.reasoningMode).toBe(
+      "full",
+    )
+    expect(decode({ general: { reasoningMode: "invalid", showReasoningSummaries: true } }).general.reasoningMode).toBe(
+      "compact",
+    )
+  })
+
+  test("encodes only the current format and round trips migrated settings", () => {
+    const settings = decode({ general: { showReasoningSummaries: true, obsolete: true }, obsolete: true })
+    const encoded = encode(settings)
+    expect(encoded).toEqual(settings)
+    expect(encoded).not.toHaveProperty("obsolete")
+    expect(encoded).not.toHaveProperty("general.obsolete")
+    expect(encoded).not.toHaveProperty("general.showReasoningSummaries")
+    expect(decode(encoded)).toEqual(settings)
+  })
+})
+
+describe("settings schema", () => {
+  test("uses the supplied initial values independently of the current schema", () => {
+    const initial = {
+      ...defaultSettings,
+      general: { ...defaultSettings.general, reasoningMode: "hidden" as const, autoSave: false },
+      appearance: { ...defaultSettings.appearance, fontSize: 20 },
+    }
+    const restore = Schema.decodeUnknownSync(Persistence.withInitial(settingsPersistence, initial))
+    expect(restore({})).toEqual(initial)
+    expect(restore({ general: { reasoningMode: "invalid", showReasoningSummaries: true } })).toEqual(initial)
+    expect(restore({ general: { showReasoningSummaries: true } }).general.reasoningMode).toBe("full")
+    expect(() => Schema.decodeUnknownSync(settingsSchema)({})).toThrow()
+  })
+
+  test("supplies the existing defaults for an empty document", () => {
+    expect(decode({})).toEqual({
+      general: {
+        autoSave: true,
+        releaseNotes: true,
+        showFileTree: false,
+        showNavigation: false,
+        showSearch: false,
+        showStatus: false,
+        showProjectIcon: false,
+        showTerminal: false,
+        reasoningMode: "compact",
+        shellToolPartsExpanded: false,
+        editToolPartsExpanded: false,
+        showCustomAgents: false,
+        mobileTitlebarPosition: "top",
+        mobileDiffWrap: true,
+        terminalPlacement: "side",
+        followUpBehavior: "steer",
+      },
+      appearance: { fontSize: 14, mono: "", sans: "", terminal: "", tabLayout: "horizontal" },
+      keybinds: {},
+      permissions: { autoApprove: false },
+      workspaces: { defaultDestination: "last-used", lastUsed: {} },
+      notifications: { agent: true, permissions: true, errors: false },
+      sounds: {
+        agentEnabled: true,
+        agent: "staplebops-01",
+        permissionsEnabled: true,
+        permissions: "staplebops-02",
+        errorsEnabled: true,
+        errors: "nope-03",
+      },
+    })
+  })
+
+  test("defaults invalid preferences locally while retaining valid siblings", () => {
+    const settings = decode({
+      general: {
+        showTerminal: true,
+        autoSave: false,
+        releaseNotes: undefined,
+        reasoningMode: 3,
+        followUpBehavior: "invalid",
+      },
+      appearance: { fontSize: "large", mono: "Custom Mono", tabLayout: "vertical" },
+      permissions: { autoApprove: true },
+      workspaces: { defaultDestination: "new", lastUsed: { good: "workspace", bad: true } },
+      keybinds: { good: "ctrl+k", bad: 3 },
+      notifications: { agent: false, permissions: "yes", errors: true },
+      sounds: { agent: "custom", agentEnabled: false, permissions: 3 },
+    })
+    expect(settings.general).toMatchObject({
+      showTerminal: true,
+      autoSave: false,
+      releaseNotes: true,
+      reasoningMode: "compact",
+      followUpBehavior: "steer",
+    })
+    expect(settings.appearance).toEqual({
+      fontSize: 14,
+      mono: "Custom Mono",
+      sans: "",
+      terminal: "",
+      tabLayout: "vertical",
+    })
+    expect(settings.permissions.autoApprove).toBe(true)
+    expect(settings.workspaces).toEqual({ defaultDestination: "new", lastUsed: { good: "workspace" } })
+    expect(settings.keybinds).toEqual({ good: "ctrl+k" })
+    expect(settings.notifications).toEqual({ agent: false, permissions: true, errors: true })
+    expect(settings.sounds).toMatchObject({ agent: "custom", agentEnabled: false, permissions: "staplebops-02" })
+    expect(decode(encode(settings))).toEqual(settings)
+  })
+
+  test.each([undefined, null, false, 7, "invalid", []].map((invalid) => [invalid]))(
+    "defaults malformed sections without losing other sections: %j",
+    (invalid) => {
+      const defaults = decode({})
+      expect(
+        decode({
+          general: invalid,
+          appearance: { fontSize: 18 },
+          keybinds: invalid,
+          permissions: invalid,
+          workspaces: invalid,
+          notifications: invalid,
+          sounds: invalid,
+        }),
+      ).toEqual({
+        ...defaults,
+        appearance: { ...defaults.appearance, fontSize: 18 },
+      })
+    },
+  )
+
+  test("does not silently repair invalid values during encoding", () => {
+    expect(() =>
+      Schema.encodeUnknownSync(settingsSchema)({ ...decode({}), appearance: { fontSize: "large" } }),
+    ).toThrow()
  })
 })

@@ -1,68 +1,20 @@
-import { createStore, reconcile } from "solid-js/store"
+import { reconcile } from "solid-js/store"
 import { createEffect, createMemo } from "solid-js"
+import { Effect, Option, Schema, SchemaGetter } from "effect"
 import { createSimpleContext } from "@opencode-ai/ui/context"
 import type { ReasoningMode } from "@opencode-ai/session-ui/timeline/projection"
 import { persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
 import { ScopedKey, type ServerScope } from "@/runtime/server/scope"

-export type WorkspaceDefaultDestination = "last-used" | "local" | "new"
-export type WorkspaceLastUsed = "local" | "workspace"
-export type TerminalPlacement = "side" | "bottom"
-export type FollowUpBehavior = "queue" | "steer"
-export type TabLayout = "horizontal" | "vertical"
-
-export interface NotificationSettings {
-  agent: boolean
-  permissions: boolean
-  errors: boolean
-}
-
-export interface SoundSettings {
-  agentEnabled: boolean
-  agent: string
-  permissionsEnabled: boolean
-  permissions: string
-  errorsEnabled: boolean
-  errors: string
-}
-
-export interface Settings {
-  general: {
-    autoSave: boolean
-    releaseNotes: boolean
-    showFileTree: boolean
-    showNavigation: boolean
-    showSearch: boolean
-    showStatus: boolean
-    showProjectIcon: boolean
-    showTerminal: boolean
-    reasoningMode: ReasoningMode
-    shellToolPartsExpanded: boolean
-    editToolPartsExpanded: boolean
-    showCustomAgents: boolean
-    mobileTitlebarPosition: "top" | "bottom"
-    mobileDiffWrap: boolean
-    terminalPlacement: TerminalPlacement
-    followUpBehavior: FollowUpBehavior
-  }
-  appearance: {
-    fontSize: number
-    mono: string
-    sans: string
-    terminal: string
-    tabLayout: TabLayout
-  }
-  keybinds: Record<string, string>
-  permissions: {
-    autoApprove: boolean
-  }
-  workspaces: {
-    defaultDestination: WorkspaceDefaultDestination
-    lastUsed: Record<string, WorkspaceLastUsed>
-  }
-  notifications: NotificationSettings
-  sounds: SoundSettings
-}
+export type Settings = typeof settingsSchema.Type
+export type WorkspaceDefaultDestination = Settings["workspaces"]["defaultDestination"]
+export type WorkspaceLastUsed = Settings["workspaces"]["lastUsed"][string]
+export type TerminalPlacement = Settings["general"]["terminalPlacement"]
+export type FollowUpBehavior = Settings["general"]["followUpBehavior"]
+export type TabLayout = Settings["appearance"]["tabLayout"]
+export type NotificationSettings = Settings["notifications"]
+export type SoundSettings = Settings["sounds"]

 export const monoDefault = "IBM Plex Mono"
 export const sansDefault = "Inter"
@@ -116,7 +68,99 @@ export function terminalFontFamily(font: string | undefined) {
  return stack(font, terminalBase)
 }

-const defaultSettings: Settings = {
+const reasoningModeSchema = Schema.Literals(["hidden", "compact", "full"])
+
+const generalSchema = Persistence.struct({
+  autoSave: Schema.Boolean,
+  releaseNotes: Schema.Boolean,
+  showFileTree: Schema.Boolean,
+  showNavigation: Schema.Boolean,
+  showSearch: Schema.Boolean,
+  showStatus: Schema.Boolean,
+  showProjectIcon: Schema.Boolean,
+  showTerminal: Schema.Boolean,
+  reasoningMode: reasoningModeSchema,
+  shellToolPartsExpanded: Schema.Boolean,
+  editToolPartsExpanded: Schema.Boolean,
+  showCustomAgents: Schema.Boolean,
+  mobileTitlebarPosition: Schema.Literals(["top", "bottom"]),
+  mobileDiffWrap: Schema.Boolean,
+  terminalPlacement: Schema.Literals(["side", "bottom"]),
+  followUpBehavior: Schema.Literals(["queue", "steer"]),
+})
+
+const appearanceSchema = Persistence.struct({
+  fontSize: Schema.Number,
+  mono: Schema.String,
+  sans: Schema.String,
+  terminal: Schema.String,
+  tabLayout: Schema.Literals(["horizontal", "vertical"]),
+})
+
+const permissionsSchema = Persistence.struct({
+  autoApprove: Schema.Boolean,
+})
+
+const workspacesSchema = Persistence.struct({
+  defaultDestination: Schema.Literals(["last-used", "local", "new"]),
+  lastUsed: Persistence.record(
+    Schema.Literals(["local", "workspace"]).pipe(Schema.catchDecoding(() => Effect.succeed(Option.none()))),
+  ),
+})
+
+const notificationsSchema = Persistence.struct({
+  agent: Schema.Boolean,
+  permissions: Schema.Boolean,
+  errors: Schema.Boolean,
+})
+
+const soundsSchema = Persistence.struct({
+  agentEnabled: Schema.Boolean,
+  agent: Schema.String,
+  permissionsEnabled: Schema.Boolean,
+  permissions: Schema.String,
+  errorsEnabled: Schema.Boolean,
+  errors: Schema.String,
+})
+
+export const settingsSchema = Persistence.struct({
+  general: generalSchema,
+  appearance: appearanceSchema,
+  keybinds: Persistence.record(Schema.String.pipe(Schema.catchDecoding(() => Effect.succeed(Option.none())))),
+  permissions: permissionsSchema,
+  workspaces: workspacesSchema,
+  notifications: notificationsSchema,
+  sounds: soundsSchema,
+})
+
+export const settingsPersistence = Persistence.migrate(
+  settingsSchema,
+  Schema.Struct({
+    general: Persistence.optional(
+      Schema.Struct({
+        reasoningMode: Schema.optional(Schema.Unknown),
+        showReasoningSummaries: Persistence.optional(Schema.Boolean),
+      }),
+    ),
+  }).pipe(
+    Schema.decode({
+      decode: SchemaGetter.transform((value) => {
+        if (value.general?.reasoningMode !== undefined || value.general?.showReasoningSummaries === undefined)
+          return value
+        return {
+          ...value,
+          general: {
+            ...value.general,
+            reasoningMode: value.general.showReasoningSummaries ? "full" : "compact",
+          },
+        }
+      }),
+      encode: SchemaGetter.transform((value) => value),
+    }),
+  ),
+)
+
+export const defaultSettings: Settings = {
  general: {
    autoSave: true,
    releaseNotes: true,
@@ -135,26 +179,11 @@ const defaultSettings: Settings = {
    terminalPlacement: "side",
    followUpBehavior: "steer",
  },
-  appearance: {
-    fontSize: 14,
-    mono: "",
-    sans: "",
-    terminal: "",
-    tabLayout: "horizontal",
-  },
+  appearance: { fontSize: 14, mono: "", sans: "", terminal: "", tabLayout: "horizontal" },
  keybinds: {},
-  permissions: {
-    autoApprove: false,
-  },
-  workspaces: {
-    defaultDestination: "last-used",
-    lastUsed: {},
-  },
-  notifications: {
-    agent: true,
-    permissions: true,
-    errors: false,
-  },
+  permissions: { autoApprove: false },
+  workspaces: { defaultDestination: "last-used", lastUsed: {} },
+  notifications: { agent: true, permissions: true, errors: false },
  sounds: {
    agentEnabled: true,
    agent: "staplebops-01",
@@ -169,26 +198,11 @@ function withFallback<T>(read: () => T | undefined, fallback: T) {
  return createMemo(() => read() ?? fallback)
 }

-export function migrateSettings(value: unknown) {
-  if (!value || typeof value !== "object" || !("general" in value)) return value
-  const general = value.general
-  if (!general || typeof general !== "object") return value
-  if ("reasoningMode" in general && general.reasoningMode !== undefined) return value
-  if (!("showReasoningSummaries" in general) || typeof general.showReasoningSummaries !== "boolean") return value
-  return {
-    ...value,
-    general: { ...general, reasoningMode: general.showReasoningSummaries ? "full" : "compact" },
-  }
-}
-
 export const { use: useSettings, provider: SettingsProvider } = createSimpleContext({
  name: "Settings",
  gate: false,
  init: () => {
-    const [store, setStore, , ready] = persisted(
-      { key: "settings.v3", migrate: migrateSettings },
-      createStore<Settings>(defaultSettings),
-    )
+    const [store, setStore, , ready] = persisted({ key: "settings.v3" }, settingsPersistence, defaultSettings)
    const showFileTree = withFallback(() => store.general?.showFileTree, defaultSettings.general.showFileTree)
    const showSearch = withFallback(() => store.general?.showSearch, defaultSettings.general.showSearch)
    const showStatus = withFallback(() => store.general?.showStatus, defaultSettings.general.showStatus)
@@ -5,7 +5,8 @@ import { Icon } from "@opencode-ai/ui/icon"
 import { IconButton } from "@opencode-ai/ui/icon-button"
 import { TextInput } from "@opencode-ai/ui/text-input"
 import { type Component, For, Show } from "solid-js"
-import { createStore } from "solid-js/store"
+import { Schema } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"
 import { useLanguage } from "@/runtime/i18n/language"
 import { useModels } from "@/providers/models/models"
 import { useServerSDK } from "@/runtime/server/client"
@@ -20,13 +21,18 @@ type ModelItem = ReturnType<ReturnType<typeof useModels>["list"]>[number]

 const PROVIDER_ICON_SIZE = 16

+export const ModelProvidersSchema = Schema.Struct({
+  collapsed: Persistence.record(Persistence.fallback(Schema.Boolean, () => false)),
+})
+
 export const SettingsModels: Component = () => {
  const language = useLanguage()
  const models = useModels()
  const serverSdk = useServerSDK()
  const [store, setStore] = persisted(
    Persist.serverGlobal(serverSdk.scope, "settings-v2.models.providers"),
-    createStore({ collapsed: {} as Record<string, boolean> }),
+    ModelProvidersSchema,
+    { collapsed: {} },
  )

  const list = useFilteredList<ModelItem>({
@@ -1,12 +1,23 @@
 import { describe, expect, test } from "bun:test"
+import { Schema } from "effect"
 import {
  activeCommandRegistrations,
  addCommandRegistration,
  commandPaletteOptions,
+  CommandCatalog,
  resolveKeybindOption,
  type CommandOption,
 } from "./command"

+test("command catalog persistence validates metadata and omits executable fields", () => {
+  const decode = Schema.decodeUnknownSync(CommandCatalog)
+  const catalog = decode({ open: { title: "Open", keybind: "mod+o", hidden: false, onSelect: "invalid" } })
+  expect(catalog).toEqual({ open: { title: "Open", keybind: "mod+o", hidden: false } })
+  expect(decode({})).toEqual({})
+  expect(() => decode({ open: { title: 1 } })).toThrow()
+  expect(decode(Schema.encodeSync(CommandCatalog)(catalog))).toEqual(catalog)
+})
+
 const paletteOptions: CommandOption[] = [
  { id: "settings.open", title: "Open settings" },
  { id: "session.undo", title: "Undo" },
@@ -2,6 +2,8 @@ import { createSimpleContext } from "@opencode-ai/ui/context"
 import { useDialog } from "@opencode-ai/ui/context/dialog"
 import { type Accessor, createEffect, createMemo, onCleanup, onMount } from "solid-js"
 import { createStore } from "solid-js/store"
+import { Schema } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"
 import { makeEventListener } from "@solid-primitives/event-listener"
 import { useLanguage } from "@/runtime/i18n/language"
 import { useSettings } from "@/settings/model"
@@ -100,14 +102,17 @@ export function resolveKeybindOption(candidates: CommandOption[] | undefined, ev

 type CommandSource = "palette" | "keybind" | "slash"

-export type CommandCatalogItem = {
-  title: string
-  description?: string
-  category?: string
-  keybind?: KeybindConfig
-  slash?: string
-  hidden?: boolean
-}
+export const CommandCatalogItem = Persistence.struct({
+  title: Schema.String,
+  description: Schema.optional(Schema.String),
+  category: Schema.optional(Schema.String),
+  keybind: Schema.optional(Schema.String),
+  slash: Schema.optional(Schema.String),
+  hidden: Schema.optional(Schema.Boolean),
+})
+export type CommandCatalogItem = typeof CommandCatalogItem.Type
+export const CommandCatalog = Schema.Record(Schema.String, Schema.mutableKey(CommandCatalogItem))
+export type CommandCatalog = typeof CommandCatalog.Type

 export type CommandRegistration = {
  key?: string
@@ -268,11 +273,7 @@ export const { use: useCommand, provider: CommandProvider } = createSimpleContex
    })
    const warnedDuplicates = new Set<string>()

-    type CommandCatalog = Record<string, CommandCatalogItem>
-    const [catalog, setCatalog, _, catalogReady] = persisted(
-      Persist.global("command.catalog.v1"),
-      createStore<CommandCatalog>({}),
-    )
+    const [catalog, setCatalog, _, catalogReady] = persisted(Persist.global("command.catalog.v1"), CommandCatalog, {})

    const bind = (id: string, def: KeybindConfig | undefined) => {
      const custom = settings.keybinds.get(actionId(id))
@@ -1,7 +1,24 @@
 import { expect, test } from "bun:test"
+import { Schema } from "effect"
 import type { ServerConnection } from "@/runtime/server/registry"
 import type { Tab } from "@/shell/tabs/tabs"
-import { openNotificationSession } from "./notification"
+import { NotificationStore, openNotificationSession, type Notification } from "./notification"
+import { Persistence } from "@/runtime/persistence/schema"
+
+test("notification persistence validates and salvages individual notifications", () => {
+  const valid: Notification[] = [
+    { type: "turn-complete", time: 123, viewed: false, session: "session-1" },
+    { type: "error", time: 124, viewed: true, error: { type: "api", message: "failed", status: 500 } },
+  ]
+  const decode = Schema.decodeUnknownSync(Persistence.withInitial(NotificationStore, { list: [] }))
+  const store = decode({
+    list: [valid[0], null, { type: "unknown", time: 123, viewed: false }, { ...valid[1], error: "invalid" }, valid[1]],
+  })
+  expect(store.list).toEqual(valid)
+  expect(decode({})).toEqual({ list: [] })
+  expect(decode({ list: {} })).toEqual({ list: [] })
+  expect(decode(Schema.encodeSync(NotificationStore)(store))).toEqual(store)
+})

 test("opens notification sessions through the tab router", () => {
  const server = "local\nhttp://localhost:4096" as ServerConnection.Key
@@ -1,14 +1,16 @@
 import { createStore, reconcile } from "solid-js/store"
+import { Schema } from "effect"
+import { SessionError } from "@opencode-ai/schema/session-error"
 import { type Accessor, batch, createEffect, createMemo, createRoot, getOwner, onCleanup } from "solid-js"
 import { createSimpleContext } from "@opencode-ai/ui/context"
 import type { ServerSDK } from "@/runtime/server/client"
 import type { Data } from "@opencode-ai/client/solid"
-import type { OpenCodeEvent } from "@opencode-ai/client/promise"
 import { usePlatform } from "@/runtime/platform/platform"
 import { useLanguage } from "@/runtime/i18n/language"
 import { useSettings } from "@/settings/model"
 import { decode64 } from "@/runtime/persistence/base64"
 import { Persist, persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
 import { playSoundByIdOnce } from "@/shell/notifications/sound"
 import { useGlobal } from "@/runtime/server/runtime"
 import { ServerConnection, useServers } from "@/runtime/server/registry"
@@ -17,24 +19,19 @@ import { requireServerKey, sessionHref } from "@/shell/routes/session"
 import type { ServerScope } from "@/runtime/server/scope"
 import { useServer } from "@/runtime/server/current"

-type NotificationBase = {
-  directory?: string
-  session?: string
-  metadata?: unknown
-  time: number
-  viewed: boolean
+const NotificationBase = {
+  directory: Schema.optional(Schema.String),
+  session: Schema.optional(Schema.String),
+  metadata: Schema.optional(Schema.Unknown),
+  time: Schema.Finite,
+  viewed: Schema.Boolean,
 }
-
-type TurnCompleteNotification = NotificationBase & {
-  type: "turn-complete"
-}
-
-type ErrorNotification = NotificationBase & {
-  type: "error"
-  error: Extract<OpenCodeEvent, { type: "session.execution.failed" }>["data"]["error"]
-}
-
-export type Notification = TurnCompleteNotification | ErrorNotification
+export const Notification = Schema.Union([
+  Persistence.struct({ ...NotificationBase, type: Schema.Literal("turn-complete") }),
+  Persistence.struct({ ...NotificationBase, type: Schema.Literal("error"), error: SessionError.Error }),
+])
+export type Notification = typeof Notification.Type
+export const NotificationStore = Persistence.struct({ list: Persistence.array(Notification) })

 type NotificationIndex = {
  session: {
@@ -53,11 +50,7 @@ type NotificationIndex = {

 type NotificationTabs = Pick<ReturnType<typeof useTabs>, "addSessionTab" | "rememberSessionRoute" | "select">

-export function openNotificationSession(
-  tabs: NotificationTabs,
-  server: ServerConnection.Key,
-  sessionID: string,
-) {
+export function openNotificationSession(tabs: NotificationTabs, server: ServerConnection.Key, sessionID: string) {
  const tab = tabs.addSessionTab({ server, sessionId: sessionID })
  if (tab.type !== "session") return
  tabs.rememberSessionRoute(tab, sessionID)
@@ -130,9 +123,8 @@ export function createServerNotificationState(input: { sdk: ServerSDK; data: Dat

  const [store, setStore, _, ready] = persisted(
    Persist.serverGlobal(input.sdk.scope, "notification"),
-    createStore({
-      list: [] as Notification[],
-    }),
+    NotificationStore,
+    { list: [] },
  )
  const [index, setIndex] = createStore<NotificationIndex>(buildNotificationIndex(store.list))

@@ -230,10 +222,7 @@ export function createServerNotificationState(input: { sdk: ServerSDK; data: Dat
      if (!session) return
      if (session.parentID) return

-      if (
-        sessionIDHasOpenTab(tabs.store, input.key, sessionID) &&
-        settings.sounds.agentEnabled()
-      ) {
+      if (sessionIDHasOpenTab(tabs.store, input.key, sessionID) && settings.sounds.agentEnabled()) {
        void playSoundByIdOnce(settings.sounds.agent(), `${input.key}\0${eventID}`)
      }

@@ -253,20 +242,12 @@ export function createServerNotificationState(input: { sdk: ServerSDK; data: Dat
    })
  }

-  const handleSessionError = (
-    sessionID: string,
-    error: ErrorNotification["error"],
-    eventID: string,
-    time: number,
-  ) => {
+  const handleSessionError = (sessionID: string, error: SessionError.Error, eventID: string, time: number) => {
    void lookup(sessionID).then((session) => {
      if (meta.disposed) return
      if (session?.parentID) return

-      if (
-        sessionIDHasOpenTab(tabs.store, input.key, sessionID) &&
-        settings.sounds.errorsEnabled()
-      ) {
+      if (sessionIDHasOpenTab(tabs.store, input.key, sessionID) && settings.sounds.errorsEnabled()) {
        void playSoundByIdOnce(settings.sounds.errors(), `${input.key}\0${eventID}`)
      }

@@ -1,7 +1,105 @@
 import { describe, expect, test } from "bun:test"
 import { createRoot, createSignal } from "solid-js"
+import { Schema } from "effect"
+import { ServerConnection } from "@/runtime/server/registry"
+import { Persistence } from "@/runtime/persistence/schema"
+import { initialLayout, layoutPersistence, layoutSchema } from "./layout"
 import { createSessionKeyReader, ensureSessionKey, pruneSessionKeys } from "./helpers"

+describe("layout persistence", () => {
+  const schema = Persistence.withInitial(layoutPersistence, initialLayout(ServerConnection.Key.make("local")))
+  const decode = Schema.decodeUnknownSync(schema)
+
+  test("uses supplied initial preferences after legacy migration", () => {
+    const initial = initialLayout(ServerConnection.Key.make("remote"))
+    initial.sidebar.width = 420
+    initial.fileTree.width = 300
+    initial.review.panelOpened = true
+    const restore = Schema.decodeUnknownSync(Persistence.withInitial(layoutPersistence, initial))
+    expect(restore({})).toEqual(initial)
+    expect(restore({ sidebar: { width: "bad" } }).sidebar.width).toBe(420)
+    expect(restore({ fileTree: { width: 260 } }).fileTree.width).toBe(200)
+    expect(restore({ fileTree: {} }).fileTree.width).toBe(300)
+    expect(restore({ review: {}, fileTree: { opened: false } }).review.panelOpened).toBe(false)
+    expect(() => Schema.decodeUnknownSync(layoutSchema)({})).toThrow()
+  })
+
+  test("restores shipped defaults for missing and invalid fields", () => {
+    const defaults = decode({})
+    expect(defaults).toEqual({
+      sidebar: { opened: false, width: 344, workspaces: {}, workspacesDefault: false },
+      terminal: { height: 280, opened: false },
+      review: { diffStyle: "split", panelOpened: false },
+      fileTree: { opened: false, width: 200, tab: "changes" },
+      session: { width: 600 },
+      mobileSidebar: { opened: false },
+      sessionTabs: {},
+      sessionView: {},
+      home: { selection: { server: ServerConnection.Key.make("local") } },
+    })
+    expect(
+      decode({
+        sidebar: { width: "bad" },
+        terminal: null,
+        session: { width: undefined },
+        review: { diffStyle: "bad" },
+      }),
+    ).toEqual(defaults)
+  })
+
+  test("migrates old sidebar and panel settings and writes current fields", () => {
+    const value = decode({ sidebar: { workspaces: true }, review: {}, fileTree: { opened: true, width: 260 } })
+    expect(value.sidebar).toEqual({ opened: false, width: 344, workspaces: {}, workspacesDefault: true })
+    expect(value.review).toEqual({ diffStyle: "split", panelOpened: true })
+    expect(value.fileTree).toEqual({ opened: true, width: 200, tab: "changes" })
+    expect(Schema.encodeSync(schema)(value)).toEqual(value)
+    expect(decode(Schema.encodeSync(schema)(value))).toEqual(value)
+    expect(decode({ fileTree: { opened: true } }).review.panelOpened).toBe(false)
+  })
+
+  test("preserves current panel preferences", () => {
+    const value = decode({
+      review: { diffStyle: "unified", panelOpened: false },
+      fileTree: { opened: true, width: 260, tab: "all" },
+    })
+    expect(value.review).toEqual({ diffStyle: "unified", panelOpened: false })
+    expect(value.fileTree).toEqual({ opened: true, width: 260, tab: "all" })
+  })
+
+  test("distinguishes an invalid panel field from an invalid review section", () => {
+    const fileTree = { opened: true, tab: "all" }
+    expect(decode({ review: { panelOpened: "bad" }, fileTree }).review.panelOpened).toBe(true)
+    expect(decode({ review: null, fileTree }).review.panelOpened).toBe(false)
+  })
+
+  test("preserves whole-record and whole-entry recovery for strict fields", () => {
+    const key = "local\u0000L3Byb2plY3Q/session"
+    const scroll = { good: { x: 1, y: 2 }, bad: { x: "bad", y: 3 } }
+    expect(
+      decode({
+        sidebar: { workspaces: { good: true, bad: "bad" } },
+        sessionView: { [key]: { scroll, reviewMode: "git" } },
+      }),
+    ).toMatchObject({
+      sidebar: { workspaces: {} },
+      sessionView: { [key]: { scroll: {}, reviewMode: "git" } },
+    })
+    expect(
+      decode({ sessionView: { [key]: { scroll: { good: { x: 1, y: 2 } }, reviewMode: "bad" } } }).sessionView,
+    ).toEqual({ [key]: { scroll: {} } })
+  })
+
+  test("keeps scoped state and salvages valid tab entries", () => {
+    const key = "local\u0000L3Byb2plY3Q/session"
+    const value = decode({
+      sessionTabs: { old: { all: ["old"] }, [key]: { all: ["a", null, "a", "b"], active: 12 } },
+      sessionView: { old: { scroll: {} }, [key]: { scroll: {}, reviewOpen: ["a", null, "b"] } },
+    })
+    expect(value.sessionTabs).toEqual({ [key]: { all: ["a", "b"], active: undefined } })
+    expect(value.sessionView).toEqual({ [key]: { scroll: {}, reviewOpen: ["a", "b"] } })
+  })
+})
+
 describe("layout session-key helpers", () => {
  test("couples touch and scroll seed in order", () => {
    const calls: string[] = []
@@ -1,4 +1,5 @@
 import { createStore, produce, reconcile } from "solid-js/store"
+import { Schema, SchemaGetter } from "effect"
 import { batch, createEffect, createMemo, onCleanup, onMount, type Accessor } from "solid-js"
 import { useLocation } from "@solidjs/router"
 import { createSimpleContext } from "@opencode-ai/ui/context"
@@ -7,6 +8,8 @@ import { ServerConnection, useServers } from "@/runtime/server/registry"
 import { usePlatform } from "@/runtime/platform/platform"
 import type { Project } from "@/runtime/server/types"
 import { Persist, persisted, removePersisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
+import { TabStorage } from "@/shell/tabs/schema"
 import { decode64 } from "@/runtime/persistence/base64"
 import { same } from "@/runtime/persistence/equality"
 import { createScrollPersistence, type SessionScroll } from "./scroll"
@@ -44,21 +47,22 @@ export function getProjectAvatarVariant(key?: string): ProjectAvatarVariant {
  return "gray"
 }

-type SessionView = {
-  scroll: Record<string, SessionScroll>
-  reviewOpen?: string[]
-  reviewMode?: ReviewChangeMode
-  reviewFile?: string
-  pendingMessage?: string
-  pendingMessageAt?: number
-}
-
 export type LocalProject = Partial<Project> & { worktree: string; expanded: boolean }
-export type HomeProjectSelection = { server: ServerConnection.Key; directory?: string }
+export type HomeProjectSelection = typeof layoutSchema.Type.home.selection

-export type ReviewDiffStyle = "unified" | "split"
-export type ReviewChangeMode = "git" | "branch" | "turn"
+export type ReviewDiffStyle = typeof layoutSchema.Type.review.diffStyle
+export type ReviewChangeMode = NonNullable<(typeof layoutSchema.Type.sessionView)[string]["reviewMode"]>
 export type ReviewPanelSource = "context-button" | "other"
+export type TabPanes = {
+  terminalOpened: Accessor<boolean>
+  setTerminalOpened(opened: boolean): void
+  terminalHeight: Accessor<number | undefined>
+  setTerminalHeight(height: number): void
+  reviewOpened: Accessor<boolean>
+  setReviewOpened(opened: boolean): void
+  sessionWidth: Accessor<number | undefined>
+  setSessionWidth(width: number): void
+}

 export type LayoutRoute =
  | { type: "home" }
@@ -123,6 +127,114 @@ export const useCurrentRoute = () => {
  return createMemo(() => currentRoute(location.pathname, location.search))
 }

+const sessionTabsSchema = Persistence.struct({
+  all: Persistence.array(Schema.String),
+  active: Persistence.optional(Schema.String),
+})
+const sessionViewSchema = Persistence.struct({
+  scroll: Persistence.record(Schema.Struct({ x: Schema.Finite, y: Schema.Finite })),
+  reviewOpen: Schema.optional(Persistence.array(Schema.String)),
+  reviewMode: Schema.optional(Schema.Literals(["git", "branch", "turn"])),
+  reviewFile: Schema.optional(Schema.String),
+  pendingMessage: Schema.optional(Schema.String),
+  pendingMessageAt: Schema.optional(Schema.Finite),
+})
+
+export const layoutSchema = Persistence.struct({
+  sidebar: Persistence.struct({
+    opened: Schema.Boolean,
+    width: Schema.Finite,
+    workspaces: Persistence.record(Schema.Boolean),
+    workspacesDefault: Schema.Boolean,
+  }),
+  terminal: Persistence.struct({ height: Schema.Finite, opened: Schema.Boolean }),
+  review: Persistence.struct({
+    diffStyle: Schema.Literals(["unified", "split"]),
+    panelOpened: Schema.Boolean,
+  }),
+  fileTree: Persistence.struct({
+    opened: Schema.Boolean,
+    width: Schema.Finite,
+    tab: Schema.Literals(["changes", "all"]),
+  }),
+  session: Persistence.struct({ width: Schema.Finite }),
+  mobileSidebar: Persistence.struct({ opened: Schema.Boolean }),
+  sessionTabs: Persistence.record(Persistence.fallback(sessionTabsSchema, () => ({ all: [] }))),
+  sessionView: Persistence.record(Persistence.fallback(sessionViewSchema, () => ({ scroll: {} }))),
+  home: Persistence.struct({
+    selection: Persistence.struct({
+      server: TabStorage.ServerKey,
+      directory: Schema.optional(Schema.String),
+    }),
+  }),
+})
+
+export const layoutPersistence = Persistence.migrate(
+  layoutSchema,
+  Schema.Struct({
+    sidebar: Persistence.optional(
+      Schema.Struct({
+        workspaces: Persistence.optional(Schema.Union([Schema.Boolean, Schema.Record(Schema.String, Schema.Boolean)])),
+        workspacesDefault: Persistence.optional(Schema.Boolean),
+      }),
+    ),
+    review: Persistence.optional(Schema.Struct({ panelOpened: Persistence.optional(Schema.Boolean) })),
+    fileTree: Persistence.optional(
+      Schema.Struct({
+        opened: Persistence.optional(Schema.Boolean),
+        width: Persistence.optional(Schema.Finite),
+        tab: Persistence.optional(Schema.Literals(["changes", "all"])),
+      }),
+    ),
+    sessionTabs: layoutSchema.fields.sessionTabs,
+    sessionView: layoutSchema.fields.sessionView,
+  }).pipe(
+    Schema.decode({
+      decode: SchemaGetter.transform((value) => ({
+        ...value,
+        sidebar:
+          typeof value.sidebar?.workspaces === "boolean"
+            ? { ...value.sidebar, workspaces: {}, workspacesDefault: value.sidebar.workspaces }
+            : value.sidebar,
+        // Only an existing review section inherits the old file-tree panel flag.
+        review: value.review
+          ? { ...value.review, panelOpened: value.review.panelOpened ?? value.fileTree?.opened }
+          : value.review,
+        fileTree:
+          value.fileTree && !value.fileTree.tab
+            ? {
+                ...value.fileTree,
+                opened: true,
+                width: value.fileTree.width === 260 ? DEFAULT_FILE_TREE_WIDTH : value.fileTree.width,
+                tab: "changes" as const,
+              }
+            : value.fileTree,
+        sessionTabs: Object.fromEntries(
+          Object.entries(value.sessionTabs)
+            .filter(([key]) => SessionStateKey.is(key))
+            .map(([key, tabs]) => [key, normalizeStoredSessionTabs(key, tabs)]),
+        ),
+        sessionView: Object.fromEntries(Object.entries(value.sessionView).filter(([key]) => SessionStateKey.is(key))),
+      })),
+      encode: SchemaGetter.transform((value) => value),
+    }),
+  ),
+)
+
+export function initialLayout(server: ServerConnection.Key): typeof layoutSchema.Type {
+  return {
+    sidebar: { opened: false, width: DEFAULT_SIDEBAR_WIDTH, workspaces: {}, workspacesDefault: false },
+    terminal: { height: DEFAULT_TERMINAL_HEIGHT, opened: false },
+    review: { diffStyle: "split", panelOpened: DEFAULT_REVIEW_PANEL_OPENED },
+    fileTree: { opened: false, width: DEFAULT_FILE_TREE_WIDTH, tab: "changes" },
+    session: { width: DEFAULT_SESSION_WIDTH },
+    mobileSidebar: { opened: false },
+    sessionTabs: {},
+    sessionView: {},
+    home: { selection: { server } },
+  }
+}
+
 export const { use: useLayout, provider: LayoutProvider } = createSimpleContext({
  name: "Layout",
  gate: false,
@@ -130,137 +242,10 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
    const servers = useServers()
    const platform = usePlatform()

-    const isRecord = (value: unknown): value is Record<string, unknown> =>
-      typeof value === "object" && value !== null && !Array.isArray(value)
-
-    const currentSessionState = (value: unknown) => {
-      if (!isRecord(value)) return value
-      const entries = Object.entries(value)
-      if (entries.every(([key]) => SessionStateKey.is(key))) return value
-      return Object.fromEntries(entries.filter(([key]) => SessionStateKey.is(key)))
-    }
-
-    const migrate = (value: unknown) => {
-      if (!isRecord(value)) return value
-
-      const sidebar = value.sidebar
-      const migratedSidebar = (() => {
-        if (!isRecord(sidebar)) return sidebar
-        if (typeof sidebar.workspaces !== "boolean") return sidebar
-        return {
-          ...sidebar,
-          workspaces: {},
-          workspacesDefault: sidebar.workspaces,
-        }
-      })()
-
-      const review = value.review
-      const fileTree = value.fileTree
-      const migratedFileTree = (() => {
-        if (!isRecord(fileTree)) return fileTree
-        if (fileTree.tab === "changes" || fileTree.tab === "all") return fileTree
-
-        const width = typeof fileTree.width === "number" ? fileTree.width : DEFAULT_FILE_TREE_WIDTH
-        return {
-          ...fileTree,
-          opened: true,
-          width: width === 260 ? DEFAULT_FILE_TREE_WIDTH : width,
-          tab: "changes",
-        }
-      })()
-
-      const migratedReview = (() => {
-        if (!isRecord(review)) return review
-        if (typeof review.panelOpened === "boolean") return review
-
-        const opened =
-          isRecord(fileTree) && typeof fileTree.opened === "boolean" ? fileTree.opened : DEFAULT_REVIEW_PANEL_OPENED
-        return {
-          ...review,
-          panelOpened: opened,
-        }
-      })()
-
-      const sessionTabs = currentSessionState(value.sessionTabs)
-      const sessionView = currentSessionState(value.sessionView)
-      const migratedSessionTabs = (() => {
-        if (!isRecord(sessionTabs)) return sessionTabs
-
-        let changed = false
-        const next = Object.fromEntries(
-          Object.entries(sessionTabs).map(([key, tabs]) => {
-            if (!isRecord(tabs) || !Array.isArray(tabs.all)) return [key, tabs]
-
-            const current = {
-              all: tabs.all.filter((tab): tab is string => typeof tab === "string"),
-              active: typeof tabs.active === "string" ? tabs.active : undefined,
-            }
-            const normalized = normalizeStoredSessionTabs(key, current)
-            if (current.all.length !== tabs.all.length) changed = true
-            if (!same(current.all, normalized.all) || current.active !== normalized.active) changed = true
-            if (tabs.active !== undefined && typeof tabs.active !== "string") changed = true
-            return [key, normalized]
-          }),
-        )
-
-        if (!changed) return sessionTabs
-        return next
-      })()
-
-      if (
-        migratedSidebar === sidebar &&
-        migratedReview === review &&
-        migratedFileTree === fileTree &&
-        migratedSessionTabs === value.sessionTabs &&
-        sessionView === value.sessionView
-      ) {
-        return value
-      }
-
-      return {
-        ...value,
-        sidebar: migratedSidebar,
-        review: migratedReview,
-        fileTree: migratedFileTree,
-        sessionTabs: migratedSessionTabs,
-        sessionView,
-      }
-    }
-
    const [store, setStore, _, ready] = persisted(
-      { ...Persist.global("layout"), previousKey: "layout.v6", migrate },
-      createStore({
-        sidebar: {
-          opened: false,
-          width: DEFAULT_SIDEBAR_WIDTH,
-          workspaces: {} as Record<string, boolean>,
-          workspacesDefault: false,
-        },
-        terminal: {
-          height: DEFAULT_TERMINAL_HEIGHT,
-          opened: false,
-        },
-        review: {
-          diffStyle: "split" as ReviewDiffStyle,
-          panelOpened: DEFAULT_REVIEW_PANEL_OPENED,
-        },
-        fileTree: {
-          opened: false,
-          width: DEFAULT_FILE_TREE_WIDTH,
-          tab: "changes" as "changes" | "all",
-        },
-        session: {
-          width: DEFAULT_SESSION_WIDTH,
-        },
-        mobileSidebar: {
-          opened: false,
-        },
-        sessionTabs: {} as Record<string, SessionTabs>,
-        sessionView: {} as Record<string, SessionView>,
-        home: {
-          selection: { server: ServerConnection.key(servers.list[0]) } as HomeProjectSelection,
-        },
-      }),
+      { ...Persist.global("layout"), previousKey: "layout.v6" },
+      layoutPersistence,
+      initialLayout(ServerConnection.key(servers.list[0])),
    )
    const [ephemeral, setEphemeral] = createStore({
      reviewPanelSource: "other" as ReviewPanelSource,
@@ -508,7 +493,7 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
          return message
        },
      },
-      view(sessionKey: string | Accessor<string>) {
+      view(sessionKey: string | Accessor<string>, panes?: TabPanes) {
        const key = createSessionKeyReader(sessionKey, ensureKey)
        const s = createMemo(() => store.sessionView[key()] ?? { scroll: {} })
        const reviewMode = createMemo(() => {
@@ -519,11 +504,24 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
          const file = s().reviewFile
          if (typeof file === "string") return file
        })
-        const terminalOpened = createMemo(() => store.terminal?.opened ?? false)
-        const reviewPanelOpened = createMemo(() => store.review?.panelOpened ?? DEFAULT_REVIEW_PANEL_OPENED)
+        const terminalOpened = panes?.terminalOpened ?? createMemo(() => store.terminal?.opened ?? false)
+        const terminalHeight = createMemo(() =>
+          panes
+            ? (panes.terminalHeight() ?? DEFAULT_TERMINAL_HEIGHT)
+            : (store.terminal?.height ?? DEFAULT_TERMINAL_HEIGHT),
+        )
+        const reviewPanelOpened =
+          panes?.reviewOpened ?? createMemo(() => store.review?.panelOpened ?? DEFAULT_REVIEW_PANEL_OPENED)
+        const sessionWidth = createMemo(() =>
+          panes ? (panes.sessionWidth() ?? DEFAULT_SESSION_WIDTH) : store.session.width,
+        )
        const reviewPanelSource = createMemo(() => (reviewPanelOpened() ? ephemeral.reviewPanelSource : "other"))

        function setTerminalOpened(next: boolean) {
+          if (panes) {
+            panes.setTerminalOpened(next)
+            return
+          }
          const current = store.terminal
          if (!current) {
            setStore("terminal", { height: DEFAULT_TERMINAL_HEIGHT, opened: next })
@@ -537,6 +535,13 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(

        function setReviewPanelOpened(next: boolean, source: ReviewPanelSource) {
          const nextSource = next ? source : "other"
+          if (panes) {
+            batch(() => {
+              panes.setReviewOpened(next)
+              setEphemeral("reviewPanelSource", nextSource)
+            })
+            return
+          }
          const current = store.review
          if (!current) {
            batch(() => {
@@ -566,6 +571,14 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
          },
          terminal: {
            opened: terminalOpened,
+            height: terminalHeight,
+            resize(height: number) {
+              if (panes) {
+                panes.setTerminalHeight(height)
+                return
+              }
+              setStore("terminal", "height", height)
+            },
            open() {
              setTerminalOpened(true)
            },
@@ -579,6 +592,14 @@ export const { use: useLayout, provider: LayoutProvider } = createSimpleContext(
          reviewPanel: {
            opened: reviewPanelOpened,
            source: reviewPanelSource,
+            width: sessionWidth,
+            resize(width: number) {
+              if (panes) {
+                panes.setSessionWidth(width)
+                return
+              }
+              setStore("session", "width", width)
+            },
            open(source: ReviewPanelSource = "other") {
              setReviewPanelOpened(true, source)
            },
@@ -1,9 +1,7 @@
 import type { SessionTab, Tab } from "./tabs"
+import type { TabStorage } from "./schema"

-export type ClosedTab = {
-  tab: SessionTab
-  index: number
-}
+export type ClosedTab = typeof TabStorage.ClosedTab.Type

 const CLOSED_TAB_LIMIT = 25

@@ -1,50 +0,0 @@
-import type { ServerConnection } from "@/runtime/server/registry"
-import type { Tab } from "./tabs"
-
-export function migrateTabs(value: unknown): Tab[] {
-  if (!Array.isArray(value)) return []
-  return value.flatMap<Tab>((tab) => {
-    if (!tab || typeof tab !== "object") return []
-    if (!("server" in tab) || typeof tab.server !== "string") return []
-    const server = tab.server as ServerConnection.Key
-    if (
-      tab.type === "session" &&
-      typeof tab.sessionId === "string" &&
-      (tab.routeSessionId === undefined || typeof tab.routeSessionId === "string") &&
-      (tab.routeParentId === undefined || typeof tab.routeParentId === "string")
-    ) {
-      return [
-        {
-          type: tab.type,
-          server,
-          sessionId: tab.sessionId,
-          ...(tab.routeSessionId && tab.routeSessionId !== tab.sessionId
-            ? {
-                routeSessionId: tab.routeSessionId,
-                ...(tab.routeParentId ? { routeParentId: tab.routeParentId } : {}),
-              }
-            : {}),
-        },
-      ]
-    }
-    if (
-      tab.type === "draft" &&
-      typeof tab.draftID === "string" &&
-      typeof tab.directory === "string" &&
-      (tab.worktree === undefined || typeof tab.worktree === "string") &&
-      (tab.branch === undefined || typeof tab.branch === "string")
-    ) {
-      return [
-        {
-          type: tab.type,
-          server,
-          draftID: tab.draftID,
-          directory: tab.directory,
-          worktree: tab.worktree,
-          branch: tab.branch,
-        },
-      ]
-    }
-    return []
-  })
-}
@@ -0,0 +1,62 @@
+export * as TabStorage from "./schema"
+
+import { Schema, SchemaGetter } from "effect"
+import { ServerKey } from "@/runtime/server/persistence"
+import { Persistence } from "@/runtime/persistence/schema"
+
+export { ServerKey }
+
+export const Session = Persistence.struct({
+  type: Schema.Literal("session"),
+  server: ServerKey,
+  sessionId: Schema.String,
+  routeSessionId: Persistence.optional(Schema.String),
+  routeParentId: Persistence.optional(Schema.String),
+})
+
+export const Draft = Persistence.struct({
+  type: Schema.Literal("draft"),
+  draftID: Schema.String,
+  server: ServerKey,
+  directory: Schema.String,
+  worktree: Persistence.optional(Schema.String),
+  branch: Persistence.optional(Schema.String),
+})
+
+const SessionCodec = Session.pipe(
+  Schema.decodeTo(Schema.toType(Session), {
+    decode: SchemaGetter.transform((tab) => ({
+      type: tab.type,
+      server: tab.server,
+      sessionId: tab.sessionId,
+      ...(tab.routeSessionId && tab.routeSessionId !== tab.sessionId
+        ? { routeSessionId: tab.routeSessionId, ...(tab.routeParentId ? { routeParentId: tab.routeParentId } : {}) }
+        : {}),
+    })),
+    encode: SchemaGetter.transform((tab) => tab),
+  }),
+)
+
+export const Tab = Schema.Union([Session, Draft])
+export const Tabs = Persistence.array(Schema.Union([SessionCodec, Draft]))
+export const Recent = Persistence.struct({
+  key: Schema.UndefinedOr(Schema.String),
+})
+export const Info = Persistence.struct({
+  title: Schema.optional(Schema.String),
+  directory: Schema.optional(Schema.String),
+})
+export const Infos = Schema.Record(Schema.String, Schema.mutableKey(Info))
+export const Panes = Schema.Record(
+  Schema.String,
+  Schema.mutableKey(
+    Persistence.struct({
+      terminal: Schema.optional(Schema.Boolean),
+      review: Schema.optional(Schema.Boolean),
+      terminalHeight: Schema.optional(Schema.Finite),
+      sessionWidth: Schema.optional(Schema.Finite),
+    }),
+  ),
+)
+export const ClosedTab = Schema.Struct({ tab: SessionCodec, index: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)) })
+export const Closed = Persistence.array(ClosedTab)
@@ -2,11 +2,14 @@ import { describe, expect, test } from "bun:test"
 import { createRoot, getOwner, onCleanup } from "solid-js"
 import { createTabMemory } from "./memory"
 import { nextTabAfterClose, pushClosedTab, removeClosedTabs, takeClosedTab, type ClosedTab } from "./closed"
-import { sessionIDHasOpenTab, tabHref, tabKey, type SessionTab, type Tab } from "./tabs"
-import { migrateTabs } from "./migration"
+import { findSessionTab, sessionIDHasOpenTab, tabHref, tabKey, type SessionTab, type Tab } from "./tabs"
+import { Schema } from "effect"
+import { TabStorage } from "./schema"
 import type { ServerConnection } from "@/runtime/server/registry"
+import { Persistence } from "@/runtime/persistence/schema"

 const server = "local\nhttp://localhost:4096" as ServerConnection.Key
+const decodeTabs = Schema.decodeUnknownSync(Persistence.withInitial(TabStorage.Tabs, []))

 function sessionTab(sessionId: string): SessionTab {
  return { type: "session", server, sessionId }
@@ -15,27 +18,66 @@ function sessionTab(sessionId: string): SessionTab {
 describe("tab migration", () => {
  test("drops null and malformed persisted tabs", () => {
    expect(
-      migrateTabs([null, sessionTab("a"), { type: "session", server }, { type: "unknown", server }, "invalid"]),
+      decodeTabs([null, sessionTab("a"), { type: "session", server }, { type: "unknown", server }, "invalid"]),
    ).toEqual([sessionTab("a")])
  })

  test("drops persisted tabs without a server", () => {
-    expect(migrateTabs([{ type: "session", sessionId: "a" }])).toEqual([])
+    expect(decodeTabs([{ type: "session", sessionId: "a" }])).toEqual([])
  })

  test("replaces invalid top-level persisted data", () => {
-    expect(migrateTabs(null)).toEqual([])
-    expect(migrateTabs({})).toEqual([])
+    expect(decodeTabs(null)).toEqual([])
+    expect(decodeTabs({})).toEqual([])
  })

  test("preserves the active child route", () => {
-    expect(migrateTabs([{ ...sessionTab("root"), routeSessionId: "child", routeParentId: "parent" }])).toEqual([
+    expect(decodeTabs([{ ...sessionTab("root"), routeSessionId: "child", routeParentId: "parent" }])).toEqual([
      { ...sessionTab("root"), routeSessionId: "child", routeParentId: "parent" },
    ])
  })

  test("drops an invalid child route", () => {
-    expect(migrateTabs([{ ...sessionTab("parent"), routeSessionId: 1 }])).toEqual([])
+    expect(decodeTabs([{ ...sessionTab("parent"), routeSessionId: 1 }])).toEqual([sessionTab("parent")])
+    expect(decodeTabs([{ ...sessionTab("parent"), routeSessionId: "child", routeParentId: 1 }])).toEqual([
+      { ...sessionTab("parent"), routeSessionId: "child" },
+    ])
+  })
+
+  test("encodes only canonical tabs and preserves drafts", () => {
+    const draft: Tab = { type: "draft", server, draftID: "draft", directory: "/project", branch: "main" }
+    const tabs = decodeTabs([
+      { ...sessionTab("root"), routeSessionId: "root", routeParentId: "stale", legacy: true },
+      draft,
+    ])
+    expect(tabs).toEqual([sessionTab("root"), draft])
+    expect(Schema.encodeSync(TabStorage.Tabs)(tabs)).toEqual(tabs)
+    expect(decodeTabs(Schema.encodeSync(TabStorage.Tabs)(tabs))).toEqual(tabs)
+  })
+
+  test("salvages valid closed session tabs", () => {
+    expect(
+      Schema.decodeUnknownSync(Persistence.withInitial(TabStorage.Closed, []))([
+        { tab: sessionTab("a"), index: 1 },
+        { tab: sessionTab("b"), index: -1 },
+        { tab: { type: "draft", server, draftID: "d", directory: "/project" }, index: 0 },
+        null,
+      ]),
+    ).toEqual([{ tab: sessionTab("a"), index: 1 }])
+  })
+
+  test("validates auxiliary tab state", () => {
+    expect(
+      Schema.decodeUnknownSync(Persistence.withInitial(TabStorage.Recent, { key: undefined }))({ key: 1 }),
+    ).toEqual({ key: undefined })
+    expect(Schema.decodeUnknownSync(TabStorage.Infos)({})).toEqual({})
+    expect(Schema.decodeUnknownSync(TabStorage.Panes)({})).toEqual({})
+    expect(Schema.decodeUnknownSync(TabStorage.Infos)({ tab: { title: "Title", directory: "/project" } })).toEqual({
+      tab: { title: "Title", directory: "/project" },
+    })
+    const panes = Schema.decodeUnknownSync(TabStorage.Panes)({ tab: { terminal: true, terminalHeight: 300 } })
+    expect(Schema.encodeSync(TabStorage.Panes)(panes)).toEqual({ tab: { terminal: true, terminalHeight: 300 } })
+    expect(() => Schema.decodeUnknownSync(TabStorage.Panes)({ tab: { terminal: "yes" } })).toThrow()
  })
 })

@@ -48,8 +90,12 @@ test("session tab identity stays rooted while its href follows the child route",
 })

 test("finds open root and routed session tabs", () => {
-  const tabs = [{ ...sessionTab("root"), routeSessionId: "child" }]
+  const tab = { ...sessionTab("root"), routeSessionId: "child" }
+  const tabs = [tab]

+  expect(findSessionTab(tabs, server, "root")).toBe(tab)
+  expect(findSessionTab(tabs, server, "child")).toBe(tab)
+  expect(findSessionTab(tabs, server, "closed")).toBeUndefined()
  expect(sessionIDHasOpenTab(tabs, server, "root")).toBe(true)
  expect(sessionIDHasOpenTab(tabs, server, "child")).toBe(true)
  expect(sessionIDHasOpenTab(tabs, server, "closed")).toBe(false)
@@ -13,27 +13,12 @@ import { sessionHref } from "@/shell/routes/session"
 import { createTabMemory } from "./memory"
 import { nextTabAfterClose, pushClosedTab, removeClosedTabs, takeClosedTab, type ClosedTab } from "./closed"
 import { createDraftComposerState, type PromptModel } from "@/composer/state"
-import { migrateTabs } from "./migration"
+import { TabStorage } from "./schema"
 import { useCurrentRoute } from "@/shell/state/layout"

-export type SessionTab = {
-  type: "session"
-  server: ServerConnection.Key
-  sessionId: string
-  routeSessionId?: string
-  routeParentId?: string
-}
-
-export type DraftTab = {
-  type: "draft"
-  draftID: string
-  server: ServerConnection.Key
-  directory: string
-  worktree?: string
-  branch?: string
-}
-
-export type Tab = SessionTab | DraftTab
+export type SessionTab = typeof TabStorage.Session.Type
+export type DraftTab = typeof TabStorage.Draft.Type
+export type Tab = typeof TabStorage.Tab.Type

 export type PendingSession = {
  draft: DraftTab
@@ -41,14 +26,10 @@ export type PendingSession = {
  selection: ComposerSelection
 }

-export type TabInfo = {
-  title?: string
-  directory?: string
-}
+export type TabInfo = typeof TabStorage.Info.Type

-type RecentTab = {
-  key?: string
-}
+export type TabPane = "terminal" | "review"
+export type TabPaneSize = "terminalHeight" | "sessionWidth"

 export const draftHref = (draftID: string) => `/new-session?draftId=${encodeURIComponent(draftID)}`

@@ -62,8 +43,8 @@ export function sessionHasOpenTab(tabs: Tab[], server: ServerConnection.Key, ses
  return sessionIDHasOpenTab(tabs, server, session.id)
 }

-export function sessionIDHasOpenTab(tabs: Tab[], server: ServerConnection.Key, sessionID: string) {
-  return tabs.some(
+export function findSessionTab(tabs: Tab[], server: ServerConnection.Key, sessionID: string) {
+  return tabs.find(
    (tab) =>
      tab.type === "session" &&
      tab.server === server &&
@@ -71,25 +52,23 @@ export function sessionIDHasOpenTab(tabs: Tab[], server: ServerConnection.Key, s
  )
 }

+export function sessionIDHasOpenTab(tabs: Tab[], server: ServerConnection.Key, sessionID: string) {
+  return !!findSessionTab(tabs, server, sessionID)
+}
+
 export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
  name: "Tabs",
  gate: false,
  init: () => {
    const servers = useServers()
    const platform = usePlatform()
-    const [store, setStore, _, ready] = persisted(
-      {
-        ...Persist.window("tabs"),
-        migrate: migrateTabs,
-      },
-      createStore<Tab[]>([]),
-    )
-    const [recent, setRecent, , recentReady] = persisted(Persist.window("tabs.recent"), createStore<RecentTab>({}))
-    const [info, setInfo, , infoReady] = persisted(
-      Persist.window("tabs.info"),
-      createStore<Record<string, TabInfo>>({}),
-    )
-    const [closed, setClosed, , closedReady] = persisted(Persist.window("tabs.closed"), createStore<ClosedTab[]>([]))
+    const [store, setStore, _, ready] = persisted(Persist.window("tabs"), TabStorage.Tabs, [])
+    const [recent, setRecent, , recentReady] = persisted(Persist.window("tabs.recent"), TabStorage.Recent, {
+      key: undefined,
+    })
+    const [info, setInfo, , infoReady] = persisted(Persist.window("tabs.info"), TabStorage.Infos, {})
+    const [panes, setPanes, , panesReady] = persisted(Persist.window("tabs.panes"), TabStorage.Panes, {})
+    const [closed, setClosed, , closedReady] = persisted(Persist.window("tabs.closed"), TabStorage.Closed, [])
    const [pending, setPending] = createStore<Record<string, PendingSession | undefined>>({})

    const params = useParams()
@@ -141,6 +120,15 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
      )
    }

+    const removePanes = (key: string) => {
+      if (!panes[key]) return
+      setPanes(
+        produce((draft) => {
+          delete draft[key]
+        }),
+      )
+    }
+
    onCleanup(memory.dispose)

    createEffect(() => {
@@ -153,6 +141,7 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
            const key = tabKey(tab)
            memory.remove(key)
            removeInfo(key)
+            removePanes(key)
          }
        }
        setStore(() => next)
@@ -162,6 +151,10 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
      for (const key of Object.keys(info)) {
        if (!keys.has(key)) removeInfo(key)
      }
+      if (!panesReady()) return
+      for (const key of Object.keys(panes)) {
+        if (!keys.has(key)) removePanes(key)
+      }
    })

    createEffect(() => {
@@ -198,6 +191,7 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
      }).finally(() => closing.delete(key))
      memory.remove(key)
      removeInfo(key)
+      removePanes(key)
      if (draftID) removeDraftPersisted(draftID)
    }

@@ -491,8 +485,38 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
      stateValue<T>(tab: Tab, name: string) {
        return memory.get<T>(tabKey(tab), name)
      },
+      pane(tab: Tab | undefined, pane: TabPane) {
+        if (!tab) return false
+        return panes[tabKey(tab)]?.[pane] ?? false
+      },
+      setPane(tab: Tab | undefined, pane: TabPane, opened: boolean) {
+        if (!tab) return
+        const key = tabKey(tab)
+        const current = panes[key]
+        if (current?.[pane] === opened) return
+        if (!current) {
+          setPanes(key, { [pane]: opened })
+          return
+        }
+        setPanes(key, pane, opened)
+      },
+      paneSize(tab: Tab | undefined, size: TabPaneSize) {
+        if (!tab) return
+        return panes[tabKey(tab)]?.[size]
+      },
+      setPaneSize(tab: Tab | undefined, size: TabPaneSize, value: number) {
+        if (!tab) return
+        const key = tabKey(tab)
+        const current = panes[key]
+        if (current?.[size] === value) return
+        if (!current) {
+          setPanes(key, { [size]: value })
+          return
+        }
+        setPanes(key, size, value)
+      },
    }

-    return { ...actions, store, info, ready, infoReady, recentReady }
+    return { ...actions, store, info, ready, infoReady, recentReady, panesReady }
  },
 })
@@ -0,0 +1,13 @@
+import { expect, test } from "bun:test"
+import { Schema } from "effect"
+import { HighlightsStore } from "./highlights"
+import { Persistence } from "@/runtime/persistence/schema"
+
+test("highlight persistence defaults missing or invalid versions and round-trips valid versions", () => {
+  const decode = Schema.decodeUnknownSync(Persistence.withInitial(HighlightsStore, { version: undefined }))
+  expect(decode({})).toEqual({ version: undefined })
+  expect(decode({ version: null })).toEqual({ version: undefined })
+  const value = decode({ version: "1.2.3", legacy: true })
+  expect(value).toEqual({ version: "1.2.3" })
+  expect(Schema.encodeSync(HighlightsStore)(value)).toEqual(value)
+})
@@ -1,17 +1,19 @@
 import { createEffect, onCleanup } from "solid-js"
 import { createStore } from "solid-js/store"
+import { Schema } from "effect"
 import { createSimpleContext } from "@opencode-ai/ui/context"
 import { useDialog } from "@opencode-ai/ui/context/dialog"
 import { usePlatform } from "@/runtime/platform/platform"
 import { useSettings } from "@/settings/model"
 import { persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
 import { DialogReleaseNotes, type Highlight } from "@/shell/updates/release-notes"

 const CHANGELOG_URL = "https://opencode.ai/changelog.json"

-type Store = {
-  version?: string
-}
+export const HighlightsStore = Persistence.struct({
+  version: Schema.UndefinedOr(Schema.String),
+})

 type ParsedRelease = {
  tag?: string
@@ -144,7 +146,7 @@ export const { use: useHighlights, provider: HighlightsProvider } = createSimple
    const platform = usePlatform()
    const dialog = useDialog()
    const settings = useSettings()
-    const [store, setStore, _, ready] = persisted("highlights.v1", createStore<Store>({ version: undefined }))
+    const [store, setStore, _, ready] = persisted("highlights.v1", HighlightsStore, { version: undefined })

    const [range, setRange] = createStore({
      from: undefined as string | undefined,
@@ -1,18 +1,22 @@
 import type { FileContent } from "@/runtime/server/types"
+import { Schema } from "effect"
+import { Persistence } from "@/runtime/persistence/schema"

-export type FileSelection = {
-  startLine: number
-  startChar: number
-  endLine: number
-  endChar: number
-}
+export const FileSelection = Persistence.struct({
+  startLine: Schema.Number,
+  startChar: Schema.Number,
+  endLine: Schema.Number,
+  endChar: Schema.Number,
+})
+export type FileSelection = typeof FileSelection.Type

-export type SelectedLineRange = {
-  start: number
-  end: number
-  side?: "additions" | "deletions"
-  endSide?: "additions" | "deletions"
-}
+export const SelectedLineRange = Persistence.struct({
+  start: Schema.Number,
+  end: Schema.Number,
+  side: Persistence.optional(Schema.Literals(["additions", "deletions"])),
+  endSide: Persistence.optional(Schema.Literals(["additions", "deletions"])),
+})
+export type SelectedLineRange = typeof SelectedLineRange.Type

 export type FileViewState = {
  scrollTop?: number
@@ -1,14 +1,26 @@
 import { createEffect, createRoot } from "solid-js"
-import { createStore, produce } from "solid-js/store"
+import { produce } from "solid-js/store"
+import { Schema } from "effect"
 import { Persist, persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
 import { createScopedCache } from "@/runtime/server/scoped-cache"
-import type { FileViewState, SelectedLineRange } from "./types"
+import { SelectedLineRange } from "./types"
 import type { ServerScope } from "@/runtime/server/scope"

 const WORKSPACE_KEY = "__workspace__"
 const MAX_FILE_VIEW_SESSIONS = 20
 const MAX_VIEW_FILES = 500

+const FileViewSchema = Persistence.struct({
+  scrollTop: Persistence.optional(Schema.Finite),
+  scrollLeft: Persistence.optional(Schema.Finite),
+  selectedLines: Persistence.optional(Schema.NullOr(SelectedLineRange)),
+})
+
+export const FileViewsSchema = Schema.Struct({
+  file: Persistence.record(Persistence.fallback(FileViewSchema, () => ({}))),
+})
+
 function normalizeSelectedLines(range: SelectedLineRange): SelectedLineRange {
  if (range.start <= range.end) return { ...range }

@@ -35,14 +47,9 @@ function equalSelectedLines(a: SelectedLineRange | null | undefined, b: Selected
 }

 function createViewSession(scope: ServerScope, dir: string, id: string | undefined) {
-  const [view, setView, _, ready] = persisted(
-    Persist.serverScoped(scope, dir, id, "file-view"),
-    createStore<{
-      file: Record<string, FileViewState>
-    }>({
-      file: {},
-    }),
-  )
+  const [view, setView, _, ready] = persisted(Persist.serverScoped(scope, dir, id, "file-view"), FileViewsSchema, {
+    file: {},
+  })

  const meta = { pruned: false }

@@ -1,6 +1,6 @@
 import { expect, test } from "bun:test"
 import { createAnimatedPresence } from "../src/runtime/animated-presence"
-import { createRoot, createSignal } from "solid-js"
+import { batch, createRoot, createSignal } from "solid-js"

 test("animates visibility changes without animating initial presence", () => {
  createRoot((dispose) => {
@@ -47,3 +47,22 @@ test("animates the first appearance when initially hidden", () => {
    dispose()
  })
 })
+
+test("does not animate visibility changes across identities", () => {
+  createRoot((dispose) => {
+    const [identity, setIdentity] = createSignal("a")
+    const [value, setValue] = createSignal<string | undefined>("visible")
+    const presence = createAnimatedPresence(value, () => null, identity)
+
+    expect(presence.animate()).toBe(false)
+    batch(() => {
+      setIdentity("b")
+      setValue(undefined)
+    })
+    expect(presence.animate()).toBe(false)
+
+    setValue("visible")
+    expect(presence.animate()).toBe(true)
+    dispose()
+  })
+})
@@ -0,0 +1,36 @@
+import { expect, test } from "bun:test"
+import { createRoot } from "solid-js"
+import { ModelSelectionSchema } from "@/providers/models/selection"
+import { persisted } from "@/runtime/persistence/storage"
+
+test("persisted model selection hydrates, updates and serializes the schema shape", () => {
+  const key = `consumer-model-selection-${crypto.randomUUID()}`
+  localStorage.setItem(
+    key,
+    JSON.stringify({ pick: { session1: { agent: "plan" }, __workspace__: { agent: "build" } } }),
+  )
+  createRoot((dispose) => {
+    try {
+      const [state, setState] = persisted(
+        key,
+        ModelSelectionSchema,
+        { session: {} },
+        {
+          platform: "web",
+          openExternal: () => {},
+          restart: async () => {},
+          notify: async () => {},
+        },
+      )
+      expect(state.session.session1?.agent).toBe("plan")
+      setState("session", "session1", { agent: "build", variant: null })
+      expect(state.session.session1?.agent).toBe("build")
+      expect(JSON.parse(localStorage.getItem(key) ?? "null")).toEqual({
+        session: { session1: { agent: "build", variant: null } },
+      })
+    } finally {
+      dispose()
+      localStorage.removeItem(key)
+    }
+  })
+})
@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test"
 import type { AsyncStorage } from "@solid-primitives/storage"
 import { createEffect, createRoot } from "solid-js"
-import { createStore } from "solid-js/store"
+import { Schema } from "effect"
 import type { Platform } from "@/runtime/platform/platform"
 import { createComposerReady, createComposerState } from "@/composer/state"
 import { ServerScope } from "@/runtime/server/scope"
@@ -34,12 +34,96 @@ const platform: Platform = {
 }

 describe("prompt persistence", () => {
+  test.each([null, "null", '"invalid"', "not json"])(
+    "keeps dynamic initial input with unavailable stored state: %s",
+    async (raw) => {
+      const store = createDraftStore({
+        get: async () => raw,
+        set: async () => undefined,
+        remove: async () => undefined,
+        putBlob: async () => "unused",
+        getBlob: async () => null,
+      })
+      const model = { providerID: "provider", modelID: "model", variant: "high" }
+      const root = createRoot((dispose) => ({
+        dispose,
+        session: createComposerState(
+          ServerScope.local,
+          { draftID: `draft-initial-${raw}` },
+          { prompt: "initial prompt", model },
+          { ...platform, draftStore: store },
+        ),
+      }))
+      await root.session.ready.promise
+      expect(root.session.current()).toEqual([{ type: "text", content: "initial prompt", start: 0, end: 14 }])
+      expect(root.session.cursor()).toBe(14)
+      expect(root.session.model.current()).toEqual(model)
+      root.dispose()
+    },
+  )
+
+  test("decodes hydrated images and writes canonical blob references through draft storage", async () => {
+    const documents = new Map<string, string>()
+    const blobs = new Map<string, Blob>()
+    const store = createDraftStore({
+      get: async (key) => documents.get(key) ?? null,
+      set: async (key, value) => void documents.set(key, value),
+      remove: async (key) => void documents.delete(key),
+      putBlob: async (blob) => {
+        blobs.set("composer-image", blob)
+        return "composer-image"
+      },
+      getBlob: async (id) => blobs.get(id) ?? null,
+    })
+    const target = Persist.draft("draft-schema-image", "prompt")
+    const key = `${target.storage}:${target.key}`
+    await store.setItem(
+      key,
+      JSON.stringify({
+        prompt: [
+          {
+            type: "image",
+            id: "image",
+            filename: "image.png",
+            mime: "image/png",
+            dataUrl: "data:image/png;base64,YQ==",
+          },
+        ],
+      }),
+    )
+    const root = createRoot((dispose) => ({
+      dispose,
+      session: createComposerState(ServerScope.local, { draftID: "draft-schema-image" }, undefined, {
+        ...platform,
+        draftStore: store,
+      }),
+    }))
+    await root.session.ready.promise
+    expect(root.session.current()).toEqual([
+      {
+        type: "image",
+        id: "image",
+        filename: "image.png",
+        mime: "image/png",
+        blob: { id: "composer-image", url: expect.stringMatching(/^blob:/) },
+      },
+    ])
+    root.session.set([{ type: "text", content: "hello", start: 0, end: 5 }, ...root.session.current()])
+    await Bun.sleep(0)
+    expect(documents.get(key)).toContain("hello")
+    expect(documents.get(key)).toContain('"blob":{"id":"composer-image"}')
+    expect(documents.get(key)).not.toContain("dataUrl")
+    expect(documents.get(key)).not.toContain("blob:")
+    root.dispose()
+  })
+
  test("relocates a previous key into canonical storage", () => {
    localStorage.setItem("server.v3", JSON.stringify({ list: ["https://example.com"] }))

    const [state] = persisted(
      { ...Persist.global("server"), previousKey: "server.v3" },
-      createStore({ list: [] as string[] }),
+      Schema.Struct({ list: Schema.mutable(Schema.Array(Schema.String)) }),
+      { list: [] },
      platform,
    )

@@ -66,3 +66,41 @@ test("enables sidebar motion only after custom width hydration", async () => {
    })
  })
 })
+
+test("recovers malformed preferences independently and keeps the filter transient", async () => {
+  const root = createPanel()
+  root.state.setFilter("transient")
+  read?.(JSON.stringify({ sidebarOpened: false, sidebarWidth: "wide", expandMode: "invalid", filter: "stored" }))
+  await root.ready
+  expect(root.state.sidebarOpened()).toBeFalse()
+  expect(root.state.sidebarWidth()).toBe(240)
+  expect(root.state.expandMode()).toBe("collapse")
+  expect(root.state.filter()).toBe("transient")
+  root.dispose()
+})
+
+test.each([0, 199, 481, null])("rejects invalid persisted sidebar width %p", async (sidebarWidth) => {
+  const root = createPanel()
+  read?.(JSON.stringify({ sidebarWidth, expandMode: "expand" }))
+  await root.ready
+  expect(root.state.sidebarWidth()).toBe(240)
+  expect(root.state.sidebarOpened()).toBeTrue()
+  expect(root.state.expandMode()).toBe("expand")
+  root.state.resizeSidebar(1000)
+  expect(root.state.sidebarWidth()).toBe(480)
+  root.state.resizeSidebar(0)
+  expect(root.state.sidebarWidth()).toBe(200)
+  root.dispose()
+})
+
+function createPanel() {
+  return createRoot((dispose) => {
+    const state = createReviewPanelState(platform)
+    const ready = new Promise<void>((resolve) => {
+      createEffect(() => {
+        if (state.sidebarTransition()) resolve()
+      })
+    })
+    return { dispose, state, ready }
+  })
+}
@@ -0,0 +1,166 @@
+import { describe, expect, test } from "bun:test"
+import { Schema, SchemaGetter } from "effect"
+import { createComputed, createRoot } from "solid-js"
+import type { Platform } from "@/runtime/platform/platform"
+import { Persist, persisted } from "@/runtime/persistence/storage"
+import { Persistence } from "@/runtime/persistence/schema"
+
+const Current = Schema.Struct({
+  enabled: Schema.Boolean,
+  label: Schema.String,
+})
+const initial = { enabled: true, label: "default" }
+const Stored = Persistence.migrate(
+  Current,
+  Schema.Struct({ oldLabel: Schema.optional(Schema.String), label: Schema.optional(Schema.String) }).pipe(
+    Schema.decode({
+      decode: SchemaGetter.transform((value) =>
+        value.oldLabel === undefined ? value : { ...value, label: value.oldLabel },
+      ),
+      encode: SchemaGetter.passthrough(),
+    }),
+  ),
+)
+
+const web: Platform = {
+  platform: "web",
+  openExternal: () => undefined,
+  restart: async () => undefined,
+  notify: async () => undefined,
+}
+
+function desktop() {
+  const values = new Map<string, string>()
+  const platform: Platform = {
+    ...web,
+    platform: "desktop",
+    windowID: "schema-test",
+    openDirectoryPickerDialog: async () => null,
+    storage: (name) => ({
+      getItem: async (key) => values.get(`${name}:${key}`) ?? null,
+      setItem: async (key, value) => void values.set(`${name}:${key}`, value),
+      removeItem: async (key) => void values.delete(`${name}:${key}`),
+    }),
+  }
+  return { values, platform }
+}
+
+describe("schema-backed persistence", () => {
+  test("migrates sync storage and writes only the current representation", () => {
+    const target = Persist.global("schema-sync")
+    const key = `${target.storage}:${target.key}`
+    localStorage.setItem(key, JSON.stringify({ oldLabel: "saved" }))
+    createRoot((dispose) => {
+      const [state, setState, , ready] = persisted(target, Stored, initial, web)
+      expect(ready.promise).toBeUndefined()
+      expect(state).toEqual({ enabled: true, label: "saved" })
+      expect(JSON.parse(localStorage.getItem(key)!)).toEqual({ enabled: true, label: "saved" })
+      setState("enabled", false)
+      expect(JSON.parse(localStorage.getItem(key)!)).toEqual({ enabled: false, label: "saved" })
+      dispose()
+    })
+  })
+
+  test("recovers invalid fields and strips fields outside the schema", () => {
+    const target = Persist.global("schema-invalid-field")
+    localStorage.setItem(
+      `${target.storage}:${target.key}`,
+      JSON.stringify({ enabled: "false", label: "kept", extra: 1 }),
+    )
+    createRoot((dispose) => {
+      const [state] = persisted(target, Stored, initial, web)
+      expect(state).toEqual({ enabled: true, label: "kept" })
+      dispose()
+    })
+  })
+
+  test("malformed JSON falls back to a typed initial state", () => {
+    const target = Persist.global("schema-invalid-json")
+    localStorage.setItem(`${target.storage}:${target.key}`, '{"label":"\\x"}')
+    createRoot((dispose) => {
+      const [state] = persisted(target, Stored, { enabled: false, label: "initial" }, web)
+      expect(state).toEqual({ enabled: false, label: "initial" })
+      expect(localStorage.getItem(`${target.storage}:${target.key}`)).toBeNull()
+      dispose()
+    })
+  })
+
+  test("relocates and canonicalizes desktop state before becoming ready", async () => {
+    const storage = desktop()
+    storage.values.set("undefined:old-schema", JSON.stringify({ oldLabel: "desktop" }))
+    const root = createRoot((dispose) => ({
+      dispose,
+      state: persisted(
+        { ...Persist.global("schema-desktop"), previousKey: "old-schema" },
+        Stored,
+        initial,
+        storage.platform,
+      ),
+    }))
+    try {
+      expect(root.state[3]()).toBe(false)
+      await root.state[3].promise
+      expect(root.state[0]).toEqual({ enabled: true, label: "desktop" })
+      expect(storage.values.has("undefined:old-schema")).toBe(false)
+      expect(JSON.parse(storage.values.get("opencode.global.dat:schema-desktop")!)).toEqual({
+        enabled: true,
+        label: "desktop",
+      })
+      root.state[1]("label", "changed")
+      expect(JSON.parse(storage.values.get("opencode.global.dat:schema-desktop")!)).toEqual({
+        enabled: true,
+        label: "changed",
+      })
+    } finally {
+      root.dispose()
+    }
+  })
+
+  test("a late desktop read does not overwrite an edit made while loading", async () => {
+    const pending = Promise.withResolvers<string | null>()
+    const storage = desktop()
+    storage.platform.storage = () => ({
+      getItem: () => pending.promise,
+      setItem: async () => undefined,
+      removeItem: async () => undefined,
+    })
+    const root = createRoot((dispose) => ({
+      dispose,
+      state: persisted(Persist.global("schema-late"), Stored, initial, storage.platform),
+    }))
+    try {
+      root.state[1]("label", "new edit")
+      pending.resolve(JSON.stringify({ oldLabel: "old state" }))
+      await root.state[3].promise
+      expect(root.state[0].label).toBe("new edit")
+    } finally {
+      root.dispose()
+    }
+  })
+
+  test("cross-window updates use the same migration and validation boundary", async () => {
+    const target = { ...Persist.global("schema-sync-channel"), sync: true }
+    const channel = new BroadcastChannel(`opencode.persist:${target.storage}:${target.key}`)
+    const received = Promise.withResolvers<void>()
+    const values: unknown[] = []
+    const root = createRoot((dispose) => {
+      const [state] = persisted(target, Stored, initial, web)
+      createComputed(() => {
+        values.push({ enabled: state.enabled, label: state.label })
+        if (state.label === "from another window") received.resolve()
+      })
+      return { dispose, state }
+    })
+    try {
+      channel.postMessage({ key: target.key, newValue: JSON.stringify({ enabled: "false", label: "recovered" }) })
+      channel.postMessage({ key: target.key, newValue: JSON.stringify({ oldLabel: "from another window" }) })
+      await received.promise
+      expect(root.state).toEqual({ enabled: true, label: "from another window" })
+      expect(values).toContainEqual({ enabled: true, label: "recovered" })
+      expect(values).toContainEqual({ enabled: true, label: "from another window" })
+    } finally {
+      channel.close()
+      root.dispose()
+    }
+  })
+})
@@ -54,7 +54,7 @@ export function format(
    plugin.state.status !== "active" || !plugin.features.tui
      ? []
      : plugin.source.type === "package"
-        ? [{ target: plugin.source.package, source: "advertised" as const }]
+        ? [{ target: plugin.source.target, source: "advertised" as const }]
        : plugin.source.type === "local"
          ? [{ target: path.dirname(plugin.source.path), source: "advertised" as const }]
          : [],
@@ -73,7 +73,7 @@ export function format(

 function name(plugin: PluginInfo) {
  if (plugin.id) return plugin.id
-  if (plugin.source.type === "package") return plugin.source.package
+  if (plugin.source.type === "package") return plugin.source.target
  if (plugin.source.type === "local") return plugin.source.path
  return plugin.source.type
 }
@@ -9,12 +9,12 @@ test("formats server and TUI plugins in sections without builtins", () => {
        { id: "opencode.agent", source: { type: "builtin" }, state: { status: "active" }, features: { server: true } },
        {
          id: "acme.dual",
-          source: { type: "package", package: "acme-plugin@1.0.0" },
+          source: { type: "package", target: "acme-plugin@1.0.0" },
          state: { status: "active" },
          features: { server: true, tui: true },
        },
        {
-          source: { type: "package", package: "broken-plugin" },
+          source: { type: "package", target: "broken-plugin" },
          state: { status: "failed", error: "broken" },
          features: { server: true },
        },
@@ -198,7 +198,13 @@ test("Node distribution honors the compile-time CLI name", async () => {
      "--test-name-pattern",
      "^Node distribution resolves the published npm package$",
    ],
-    { cwd: path.join(import.meta.dir, ".."), stdout: "ignore", stderr: "pipe" },
+    {
+      cwd: path.join(import.meta.dir, ".."),
+      stdout: "ignore",
+      stderr: "pipe",
+      // Bun 1.4 can reuse cached modules compiled with different --define values.
+      env: { ...process.env, BUN_RUNTIME_TRANSPILER_CACHE_PATH: "0" },
+    },
  )
  const [code, stderr] = await Promise.all([child.exited, new Response(child.stderr).text()])
  expect(code, stderr).toBe(0)
@@ -88,8 +88,16 @@ export type PluginListInput = {
 export type PluginListOutput = { readonly location: Location.Info; readonly data: ReadonlyArray<Plugin.Info> }
 export type PluginListOperation<E = never> = (input?: PluginListInput) => Effect.Effect<PluginListOutput, E>

+export type PluginUpdateInput = {
+  readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  readonly target: string
+}
+export type PluginUpdateOutput = void
+export type PluginUpdateOperation<E = never> = (input: PluginUpdateInput) => Effect.Effect<PluginUpdateOutput, E>
+
 export interface PluginApi<E = never> {
  readonly list: PluginListOperation<E>
+  readonly update: PluginUpdateOperation<E>
 }

 export type SessionListInput = {
@@ -15,6 +15,8 @@ import type {
  AgentGetOutput,
  PluginListInput,
  PluginListOutput,
+  PluginUpdateInput,
+  PluginUpdateOutput,
  SessionListInput,
  SessionListOutput,
  SessionStatsInput,
@@ -322,7 +324,17 @@ const EndpointPluginList = (raw: RawClient["server.plugin"]) => (input?: PluginL
    raw["plugin.list"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)),
  )

-const adaptGroupPlugin = (raw: RawClient["server.plugin"]) => ({ list: EndpointPluginList(raw) })
+const EndpointPluginUpdate = (raw: RawClient["server.plugin"]) => (input: PluginUpdateInput) =>
+  preserveEffect<PluginUpdateOutput>()(
+    raw["plugin.update"]({ query: { location: input["location"] }, payload: { target: input["target"] } }).pipe(
+      Effect.mapError(mapClientError),
+    ),
+  )
+
+const adaptGroupPlugin = (raw: RawClient["server.plugin"]) => ({
+  list: EndpointPluginList(raw),
+  update: EndpointPluginUpdate(raw),
+})

 const EndpointSessionList = (raw: RawClient["server.session"]) => (input?: SessionListInput) =>
  preserveEffect<SessionListOutput>()(
@@ -9,6 +9,8 @@ import type {
  AgentGetOutput,
  PluginListInput,
  PluginListOutput,
+  PluginUpdateInput,
+  PluginUpdateOutput,
  SessionListInput,
  SessionListOutput,
  SessionStatsInput,
@@ -466,6 +468,19 @@ export function make(options: ClientOptions) {
          },
          requestOptions,
        ),
+      update: (input: PluginUpdateInput, requestOptions?: RequestOptions) =>
+        request<PluginUpdateOutput>(
+          {
+            method: "POST",
+            path: `/api/plugin/update`,
+            query: { location: input["location"] },
+            body: { target: input["target"] },
+            successStatus: 204,
+            declaredStatuses: [400, 503, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
    },
    session: {
      list: (input?: SessionListInput, requestOptions?: RequestOptions) =>
@@ -12,7 +12,7 @@ export type PermissionEffect = "allow" | "deny" | "ask"

 export type PluginSource =
  | { type: "builtin" }
-  | { type: "package"; package: string }
+  | { type: "package"; target: string; version?: string; outdated?: true }
  | { type: "local"; path: string }
  | { type: "sdk" }

@@ -2354,6 +2354,14 @@ export type AgentNotFoundError = {
 export const isAgentNotFoundError = (value: unknown): value is AgentNotFoundError =>
  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "AgentNotFoundError"

+export type ServiceUnavailableError = {
+  readonly _tag: "ServiceUnavailableError"
+  readonly message: string
+  readonly service?: string | undefined
+}
+export const isServiceUnavailableError = (value: unknown): value is ServiceUnavailableError =>
+  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ServiceUnavailableError"
+
 export type InvalidCursorError = { readonly _tag: "InvalidCursorError"; readonly message: string }
 export const isInvalidCursorError = (value: unknown): value is InvalidCursorError =>
  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "InvalidCursorError"
@@ -2415,14 +2423,6 @@ export type SkillNotFoundError = {
 export const isSkillNotFoundError = (value: unknown): value is SkillNotFoundError =>
  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "SkillNotFoundError"

-export type ServiceUnavailableError = {
-  readonly _tag: "ServiceUnavailableError"
-  readonly message: string
-  readonly service?: string | undefined
-}
-export const isServiceUnavailableError = (value: unknown): value is ServiceUnavailableError =>
-  typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ServiceUnavailableError"
-
 export type SessionBusyError = {
  readonly _tag: "SessionBusyError"
  readonly sessionID: string
@@ -2582,6 +2582,15 @@ export type PluginListOutput = {
  data: Array<PluginInfo>
 }

+export type PluginUpdateInput = {
+  readonly location?: {
+    readonly location?: { readonly directory?: string | undefined; readonly workspace?: string | undefined } | undefined
+  }["location"]
+  readonly target: { readonly target: string }["target"]
+}
+
+export type PluginUpdateOutput = void
+
 export type SessionListInput = {
  readonly workspace?: {
    readonly workspace?: string | undefined
@@ -79,15 +79,19 @@ const docTags = (schema: JsonSchema): Array<string> => {
 }

 // Neutralize `*\/` so model-provided schema text cannot terminate generated documentation.
-const jsdoc = (description: string | undefined, tags: ReadonlyArray<string>, pad: string): string => {
-  const lines = [...(description === undefined ? [] : description.split("\n")), ...tags].map((line) =>
-    line.replaceAll("*/", "* /").replace(/\s+$/, ""),
-  )
+const jsdoc = (description: string | undefined, summary: string, pad: string): string => {
+  const lines = (description ?? "").split("\n").map((line) => line.replace(/\s+$/, ""))
  while (lines.length > 0 && lines[0]!.trim() === "") lines.shift()
  while (lines.length > 0 && lines[lines.length - 1]!.trim() === "") lines.pop()
-  if (lines.length === 0) return ""
-  if (lines.length === 1) return `${pad}/** ${lines[0]} */\n`
-  const body = lines.map((line) => `${pad} *${line === "" ? "" : ` ${line}`}`).join("\n")
+  const inline = lines.length === 1 ? `${lines[0]}${lines[0].endsWith(".") ? "" : "."} ${summary}` : summary
+  const content =
+    summary && lines.length === 1 && !summary.includes("\n") && pad.length + inline.length + 7 <= 120
+      ? [inline]
+      : [...lines, ...(summary ? summary.split("\n") : [])]
+  if (content.length === 0) return ""
+  const escaped = content.map((line) => line.replaceAll("*/", "* /"))
+  if (escaped.length === 1 && pad.length + escaped[0].length + 7 <= 120) return `${pad}/** ${escaped[0]} */\n`
+  const body = escaped.map((line) => `${pad} *${line === "" ? "" : ` ${line}`}`).join("\n")
  return `${pad}/**\n${body}\n${pad} */\n`
 }

@@ -167,7 +171,7 @@ const renderSchema = (
    if (properties.length === 0 && indexType === undefined) return "{}"
    const pad = "  ".repeat(depth + 1)
    const lines = properties.map(
-      (entry) => `${jsdoc(entry[1].description, docTags(entry[1]), pad)}${pad}${field(entry)},`,
+      (entry) => `${jsdoc(entry[1].description, docTags(entry[1]).join(" "), pad)}${pad}${field(entry)},`,
    )
    if (indexType !== undefined) lines.push(`${pad}[key: string]: ${indexType},`)
    return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`
@@ -36,7 +36,7 @@ const lookupOrder = Tool.make({
 })

 describe("pretty signature rendering", () => {
-  test("described fields get JSDoc comments; undescribed and untagged fields get none", () => {
+  test("described fields get compact JSDoc; undescribed and unconstrained fields get none", () => {
    expect(inputTypeScript(listIssues, true)).toBe(
      [
        "{",
@@ -44,16 +44,9 @@ describe("pretty signature rendering", () => {
        "  owner: string,",
        "  /** Cursor from the previous response's pageInfo */",
        "  after?: string,",
-        "  /**",
-        "   * Results per page",
-        "   * @default 30",
-        "   */",
+        "  /** Results per page. @default 30 */",
        "  perPage?: number,",
-        "  /**",
-        "   * Filter by labels",
-        "   * @minItems 1",
-        "   * @maxItems 10",
-        "   */",
+        "  /** Filter by labels. @minItems 1 @maxItems 10 */",
        "  labels?: Array<string>,",
        '  state?: "open" | "closed",',
        "}",
@@ -105,7 +98,7 @@ describe("pretty signature rendering", () => {
    )
  })

-  test("constraints TypeScript cannot express surface as JSDoc tags", () => {
+  test("constraints and annotations share compact tagged JSDoc", () => {
    const pretty = jsonSchemaToTypeScript(
      {
        type: "object",
@@ -119,19 +112,10 @@ describe("pretty signature rendering", () => {
    )
    expect(pretty).toContain("  /** @deprecated */\n  legacy?: string")
    expect(pretty).toContain("  /** @format uri */\n  homepage?: string")
-    expect(pretty).toContain(
-      [
-        "  /**",
-        '   * @default ["a","b"]',
-        "   * @minItems 2",
-        "   * @maxItems 5",
-        "   */",
-        "  tags?: Array<string>",
-      ].join("\n"),
-    )
+    expect(pretty).toContain('  /** @default ["a","b"] @minItems 2 @maxItems 5 */\n  tags?: Array<string>')
  })

-  test("skips an unserializable default rather than emitting a broken tag", () => {
+  test("skips an unserializable default rather than emitting a broken summary", () => {
    const pretty = jsonSchemaToTypeScript(
      { type: "object", properties: { size: { type: "number", default: 1n } } },
      true,
@@ -151,9 +135,18 @@ describe("pretty signature rendering", () => {
    [{ type: "array", minItems: 0 }, "@minItems 0", "Array<unknown>"],
    [{ type: "array", maxItems: 0 }, "@maxItems 0", "Array<unknown>"],
    [{ type: "array", uniqueItems: true }, "@uniqueItems true", "Array<unknown>"],
-  ] as const)("renders constraint %j without changing the compact type", (value, tag, type) => {
+    [{ type: "string", minLength: 0, maxLength: 0 }, "@minLength 0 @maxLength 0", "string"],
+    [{ type: "array", minItems: 0, maxItems: 0 }, "@minItems 0 @maxItems 0", "Array<unknown>"],
+    [
+      { type: "array", minItems: 1, maxItems: 10, uniqueItems: true },
+      "@minItems 1 @maxItems 10 @uniqueItems true",
+      "Array<unknown>",
+    ],
+  ] as const)("renders constraint %j without changing the compact type", (value, summary, type) => {
    const schema = { type: "object", properties: { value } }
-    expect(jsonSchemaToTypeScript(schema, true)).toBe(["{", `  /** ${tag} */`, `  value?: ${type},`, "}"].join("\n"))
+    expect(jsonSchemaToTypeScript(schema, true)).toBe(
+      ["{", `  /** ${summary} */`, `  value?: ${type},`, "}"].join("\n"),
+    )
    expect(jsonSchemaToTypeScript(schema)).toBe(`{ value?: ${type} }`)
  })

@@ -188,30 +181,19 @@ describe("pretty signature rendering", () => {
    )
  })

-  test.each([false, null, ""])("preserves default %j alongside constraint tags", (value) => {
+  test.each([false, null, ""])("preserves default %j alongside constraints", (value) => {
    expect(jsonSchemaToTypeScript({ properties: { value: { default: value, minLength: 0 } } }, true)).toContain(
-      `   * @default ${JSON.stringify(value)}\n   * @minLength 0\n`,
+      `  /** @default ${JSON.stringify(value)} @minLength 0 */\n`,
    )
  })

-  test("escapes comment terminators in tag values", () => {
+  test("escapes comment terminators in summary values", () => {
    expect(
      jsonSchemaToTypeScript(
        { properties: { value: { type: "string", default: "*/", format: "*/", pattern: "^a*/b$" } } },
        true,
      ),
-    ).toBe(
-      [
-        "{",
-        "  /**",
-        '   * @default "* /"',
-        "   * @format * /",
-        "   * @pattern ^a* /b$",
-        "   */",
-        "  value?: string,",
-        "}",
-      ].join("\n"),
-    )
+    ).toBe(["{", '  /** @default "* /" @format * / @pattern ^a* /b$ */', "  value?: string,", "}"].join("\n"))
  })

  test("neutralizes */ inside descriptions so nothing closes the comment early", () => {
@@ -236,6 +218,88 @@ describe("pretty signature rendering", () => {
    )
  })

+  test("preserves inclusive and exclusive numeric bounds together", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        {
+          properties: {
+            value: {
+              type: "integer",
+              minimum: -10,
+              maximum: 10,
+              exclusiveMinimum: -5,
+              exclusiveMaximum: 5,
+              multipleOf: 2,
+            },
+          },
+        },
+        true,
+      ),
+    ).toContain(
+      "  /** @integer @minimum -10 @maximum 10 @exclusiveMinimum -5 @exclusiveMaximum 5 @multipleOf 2 */\n  value?: number,",
+    )
+  })
+
+  test.each([
+    ["Maximum attempts", "Maximum attempts."],
+    ["Maximum attempts.", "Maximum attempts."],
+    ["Maximum attempts!", "Maximum attempts!."],
+  ])("combines a short description (%s) with its summary", (description, expected) => {
+    expect(
+      jsonSchemaToTypeScript(
+        { properties: { attempts: { description, type: "integer", minimum: 1, default: 3 } } },
+        true,
+      ),
+    ).toContain(`  /** ${expected} @default 3 @integer @minimum 1 */\n`)
+  })
+
+  test("keeps multiline descriptions intact and appends a compact summary", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        {
+          properties: {
+            attempts: {
+              description: "\nMaximum attempts\n\nIncludes the initial request.\n",
+              type: "integer",
+              minimum: 1,
+            },
+          },
+        },
+        true,
+      ),
+    ).toBe(
+      [
+        "{",
+        "  /**",
+        "   * Maximum attempts",
+        "   *",
+        "   * Includes the initial request.",
+        "   * @integer @minimum 1",
+        "   */",
+        "  attempts?: number,",
+        "}",
+      ].join("\n"),
+    )
+  })
+
+  test("uses a block for long descriptions without truncating or rewriting them", () => {
+    const description = "A detailed description. ".repeat(8).trim()
+    expect(jsonSchemaToTypeScript({ properties: { name: { type: "string", description, minLength: 1 } } }, true)).toBe(
+      ["{", "  /**", `   * ${description}`, "   * @minLength 1", "   */", "  name?: string,", "}"].join("\n"),
+    )
+  })
+
+  test("preserves pattern backslashes and prefixes every line of multiline summary values", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        { properties: { value: { type: "string", pattern: "^\\d+\n*/$", default: "a\nb" } } },
+        true,
+      ),
+    ).toBe(
+      ["{", "  /**", '   * @default "a\\nb" @pattern ^\\d+', "   * * /$", "   */", "  value?: string,", "}"].join("\n"),
+    )
+  })
+
  test("stays total on cyclic $refs and pathological nesting in both modes", () => {
    const cyclic = {
      $ref: "#/$defs/Node",
@@ -486,22 +550,11 @@ describe("JSDoc signatures in catalogs and search results", () => {
    })
    const type = [
      "{",
-      "  /**",
-      "   * @integer",
-      "   * @minimum 0",
-      "   * @maximum 10",
-      "   */",
+      "  /** @integer @minimum 0 @maximum 10 */",
      "  count: number,",
-      "  /**",
-      "   * @minLength 1",
-      "   * @maxLength 20",
-      "   * @pattern ^[a-z]+$",
-      "   */",
+      "  /** @minLength 1 @maxLength 20 @pattern ^[a-z]+$ */",
      "  name: string,",
-      "  /**",
-      "   * @minItems 1",
-      "   * @maxItems 5",
-      "   */",
+      "  /** @minItems 1 @maxItems 5 */",
      "  labels: Array<string>,",
      "}",
    ].join("\n")
@@ -522,7 +575,7 @@ describe("JSDoc signatures in catalogs and search results", () => {
    return result.value as { items: Array<{ path: string; signature: string }>; remaining: number }
  }

-  test("a raw JSON Schema (MCP-style) tool's result signature carries field JSDoc and tags", async () => {
+  test("a raw JSON Schema (MCP-style) tool's result signature carries field JSDoc and summaries", async () => {
    const { items } = await search("list issues repository")
    const item = items.find(({ path }) => path === "tools.github.list_issues")!
    expect(item.signature).toBe(
@@ -532,16 +585,9 @@ describe("JSDoc signatures in catalogs and search results", () => {
        "  owner: string,",
        "  /** Cursor from the previous response's pageInfo */",
        "  after?: string,",
-        "  /**",
-        "   * Results per page",
-        "   * @default 30",
-        "   */",
+        "  /** Results per page. @default 30 */",
        "  perPage?: number,",
-        "  /**",
-        "   * Filter by labels",
-        "   * @minItems 1",
-        "   * @maxItems 10",
-        "   */",
+        "  /** Filter by labels. @minItems 1 @maxItems 10 */",
        "  labels?: Array<string>,",
        '  state?: "open" | "closed",',
        "}): Promise<unknown>",
@@ -7,7 +7,6 @@ import { FSUtil } from "@opencode-ai/util/fs-util"
 import { Global } from "@opencode-ai/util/global"
 import { Location } from "./location.js"
 import { Project } from "./project.js"
-import { ProjectMarkers } from "./project/markers.js"
 import { AbsolutePath } from "./schema.js"

 export const Kind = Schema.Literals(["file", "directory"])
@@ -81,7 +80,6 @@ const layer = Layer.effect(
  Effect.gen(function* () {
    const fs = yield* FSUtil.Service
    const location = yield* Location.Service
-    const markers = yield* ProjectMarkers.Service

    const resolve = Effect.fnUntraced(function* (input: ResolveInput) {
      const absolute = resolvePath(location.directory, input.path)
@@ -113,7 +111,7 @@ const layer = Layer.effect(
          resource: externalResource,
          save: slash(
            path.join(
-              (yield* Project.root(fs, AbsolutePath.make(externalDirectory), markers.targets())) ?? externalDirectory,
+              (yield* Project.root(fs, AbsolutePath.make(externalDirectory))) ?? externalDirectory,
              "*",
            ),
          ),
@@ -128,5 +126,5 @@ const layer = Layer.effect(
 export const node = makeLocationNode({
  service: Service,
  layer,
-  deps: [FSUtil.node, Location.node, ProjectMarkers.node],
+  deps: [FSUtil.node, Location.node],
 })
@@ -10,7 +10,6 @@ export { Info, Ref, response }

 export interface Interface extends Info {
  readonly vcs?: Project.Vcs
-  readonly vcsBackend?: string
 }

 export class Service extends Context.Service<Service, Interface>()("@opencode/Location") {}
@@ -28,7 +27,6 @@ const layer = (ref: Ref, options?: { readonly discovery?: boolean }) =>
        workspaceID: ref.workspaceID,
        project: { id: resolved.id, directory: resolved.directory, canonical: resolved.canonical },
        vcs: resolved.vcs,
-        vcsBackend: resolved.vcsBackend,
      })
    }),
  )
@@ -30,7 +30,7 @@ import { Permission } from "./permission.js"

 export interface Interface {
  readonly activate: (
-    plugins: readonly Versioned[],
+    plugins: readonly Generation[],
    failures?: readonly Failure[],
  ) => Effect.Effect<void>
  readonly list: () => Effect.Effect<Plugin.Info[]>
@@ -38,8 +38,8 @@ export interface Interface {

 type Failure = Plugin.Info & { readonly state: Extract<Plugin.State, { readonly status: "failed" }> }

-export type Versioned = PluginDefinition & {
-  readonly version: string
+export type Generation = PluginDefinition & {
+  readonly revision: string
  readonly source?: Plugin.Source
  readonly features?: Plugin.Features
 }
@@ -52,11 +52,11 @@ const layer = Layer.effect(
    const bus = yield* Bus.Service
    const kv = yield* KV.Service
    const scope = yield* Scope.make()
-    const active = new Map<Plugin.ID, { readonly plugin: Versioned; readonly scope: Scope.Closeable }>()
+    const active = new Map<Plugin.ID, { readonly plugin: Generation; readonly scope: Scope.Closeable }>()
    const lock = Semaphore.makeUnsafe(1)
    let inventory: Plugin.Info[] = []
    let host: Parameters<PluginDefinition["effect"]>[0]
-    const load = Effect.fnUntraced(function* (plugin: Versioned) {
+    const load = Effect.fnUntraced(function* (plugin: Generation) {
      const child = yield* Scope.fork(scope)
      const inherit = yield* State.inherit()
      const loaded = yield* Effect.suspend(() =>
@@ -83,7 +83,7 @@ const layer = Layer.effect(
    })

    const activate = Effect.fn("Plugin.activate")(function* (
-      plugins: readonly Versioned[],
+      plugins: readonly Generation[],
      failures: readonly Failure[] = [],
    ) {
      const definitions = plugins.map((plugin) => ({ ...plugin, id: Plugin.ID.make(plugin.id) }))
@@ -99,10 +99,14 @@ const layer = Layer.effect(
            active.size === definitions.length &&
            Array.from(active.values()).every((entry, index) => {
              const definition = definitions[index]
-              return entry.plugin.id === definition?.id && entry.plugin.version === definition.version
+              return entry.plugin.id === definition?.id && entry.plugin.revision === definition.revision
            })
          ) {
-            const nextInventory = [...Array.from(active.values(), (entry) => activeInfo(entry.plugin)), ...failures]
+            for (const definition of definitions) {
+              const entry = active.get(definition.id)
+              if (entry) active.set(definition.id, { ...entry, plugin: definition })
+            }
+            const nextInventory = [...definitions.map(activeInfo), ...failures]
            if (JSON.stringify(inventory) === JSON.stringify(nextInventory)) return
            inventory = nextInventory
            yield* bus.publish(Plugin.Event.Updated, {})
@@ -174,7 +178,7 @@ const layer = Layer.effect(
  }),
 )

-function activeInfo(plugin: Versioned): Plugin.Info {
+function activeInfo(plugin: Generation): Plugin.Info {
  return {
    id: Plugin.ID.make(plugin.id),
    source: plugin.source ?? { type: "builtin" },
@@ -3,7 +3,7 @@ export * as InstancePlugins from "./instance.js"
 import type { Plugin } from "@opencode-ai/plugin/effect/plugin"
 import { Context, Layer } from "effect"
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
-import type { Versioned } from "../plugin.js"
+import type { Generation } from "../plugin.js"

 /**
 * Holds the plugins one instance is born with. Unlike the host-global
@@ -13,16 +13,13 @@ import type { Versioned } from "../plugin.js"
 * for the instance's lifetime; runtime dynamism lives inside plugins through
 * the container transform/reload APIs.
 *
- * Limitations: `vcs` marker declarations in an instance list are not seen by
- * `ProjectMarkers` (it is global and runs during project resolution, before
- * the instance exists — unlike `SdkPlugins`, whose declarations it consumes
- * directly), and config plugin operations may disable instance plugins by id,
- * matching `SdkPlugins` behavior.
+ * Config plugin operations may disable instance plugins by id, matching
+ * `SdkPlugins` behavior.
 */
 export type List = readonly Plugin[]

 export interface Interface {
-  readonly all: () => readonly Versioned[]
+  readonly all: () => readonly Generation[]
 }

 export class Service extends Context.Service<Service, Interface>()("@opencode/InstancePlugins") {}
@@ -33,8 +30,8 @@ export const node = makeLocationNode({
  deps: [],
 })

-// The constant version is load-bearing: the plugin registry treats an
-// unchanged (id, version) pair as the same plugin across activations, which
+// The constant revision is load-bearing: the plugin registry treats an
+// unchanged (id, revision) pair as the same plugin across activations, which
 // is only correct because a bound list never changes after creation.
 // `source: "sdk"` means host-contributed; an instance list is the
 // per-instance form of the same channel.
@@ -44,7 +41,7 @@ export function bound(plugins: List) {
    throw new Error(`duplicate instance plugin ids: ${duplicates.map((plugin) => plugin.id).join(", ")}`)
  }
  const stamped = plugins.map(
-    (plugin): Versioned => ({ ...plugin, version: "instance", source: { type: "sdk" } }),
+    (plugin): Generation => ({ ...plugin, revision: "instance", source: { type: "sdk" } }),
  )
  return Layer.succeed(Service, Service.of({ all: () => stamped }))
 }
@@ -26,7 +26,6 @@ import { ConfigShellPlugin } from "../config/plugin/shell.js"
 import { ConfigSnapshotPlugin } from "../config/plugin/snapshot.js"
 import { ConfigSkillPlugin } from "../config/plugin/skill.js"
 import { ConfigToolOutputPlugin } from "../config/plugin/tool-output.js"
-import { ConfigPluginSource } from "../config/plugin/source.js"
 import { ConfigWebSearchPlugin } from "../config/plugin/websearch.js"
 import { Bus } from "../bus.js"
 import { Environment } from "../environment/index.js"
@@ -97,7 +96,6 @@ const services = Effect.fn("PluginInternal.services")(function* () {
  const command = yield* Command.Service
  const config = yield* Config.Service
  const credential = yield* Credential.Service
-  const pluginSources = yield* ConfigPluginSource.Service
  const bus = yield* Bus.Service
  const environment = yield* Environment.Service
  const mutation = yield* FileMutation.Service
@@ -141,7 +139,6 @@ const services = Effect.fn("PluginInternal.services")(function* () {
    Context.make(Command.Service, command),
    Context.make(Config.Service, config),
    Context.make(Credential.Service, credential),
-    Context.make(ConfigPluginSource.Service, pluginSources),
    Context.make(Bus.Service, bus),
    Context.make(Environment.Service, environment),
    Context.make(FileMutation.Service, mutation),
@@ -192,7 +189,6 @@ export const requirements = LayerNode.group([
  Command.node,
  Config.node,
  Credential.node,
-  ConfigPluginSource.node,
  Bus.node,
  Environment.node,
  FileMutation.node,
@@ -287,7 +283,6 @@ export const list = Effect.fn("PluginInternal.list")(function* () {
    plugins.map(
      (plugin): Plugin => ({
        id: plugin.id,
-        vcs: plugin.vcs,
        effect: (host) => plugin.effect(host).pipe(Effect.provide(context)),
      }),
    )
@@ -8,23 +8,17 @@ import { readdir } from "node:fs/promises"
 import path from "path"
 import { pathToFileURL } from "url"
 import type { ConfigPluginSource } from "../config/plugin/source.js"
-import type { Versioned } from "../plugin.js"
+import type { Generation } from "../plugin.js"
 import { PluginPromise } from "./promise.js"

-const Discovery = Schema.Struct({
-  id: Schema.optional(Schema.String),
-  markers: Schema.Array(Schema.String),
-})
 const Definition = Schema.Struct({
  default: Schema.Union([
    Schema.Struct({
      id: Schema.String,
-      vcs: Schema.optional(Discovery),
      effect: Schema.declare<Plugin["effect"]>((input): input is Plugin["effect"] => typeof input === "function"),
    }),
    Schema.Struct({
      id: Schema.String,
-      vcs: Schema.optional(Discovery),
      setup: Schema.declare<Parameters<typeof PluginPromise.fromPromise>[0]["setup"]>(
        (input): input is Parameters<typeof PluginPromise.fromPromise>[0]["setup"] => typeof input === "function",
      ),
@@ -34,13 +28,17 @@ const Definition = Schema.Struct({

 export const load = Effect.fn("PluginModule.load")(function* (
  operation: Extract<ConfigPluginSource.Operation, { type: "add" }>,
+  options?: { readonly install?: boolean },
 ) {
  const npm = yield* Npm.Service
  const local = path.isAbsolute(operation.target)
-  const installed = local
-    ? { entrypoint: pathToFileURL(operation.target).href }
-    : yield* npm.add(operation.target, { subpaths: ["server", ""] })
+  const installed: Npm.EntryPoint = local
+    ? { directory: path.dirname(operation.target), entrypoint: pathToFileURL(operation.target).href }
+    : options?.install === false
+      ? yield* npm.resolve(operation.target, { subpaths: ["server", ""] })
+      : yield* npm.add(operation.target, { subpaths: ["server", ""] })
  const entrypoint = installed.entrypoint
+  if (!local && options?.install === false && !entrypoint) return { pending: true as const }
  if (!entrypoint) return yield* Effect.fail(new Error(`Plugin entrypoint not found: ${operation.target}`))
  // Bun currently ignores query parameters when caching file:// imports.
  const target = typeof Bun !== "undefined" ? operation.target.replaceAll("\\", "/") : entrypoint
@@ -63,13 +61,16 @@ export const load = Effect.fn("PluginModule.load")(function* (
  return {
    id: plugin.id,
    features,
-    vcs: plugin.vcs,
-    version: JSON.stringify(operation),
+    revision: JSON.stringify([operation, installed.revision]),
    source: path.isAbsolute(operation.target)
      ? { type: "local" as const, path: operation.target }
-      : { type: "package" as const, package: operation.target },
+      : {
+          type: "package" as const,
+          target: operation.target,
+          ...(installed.version ? { version: installed.version } : {}),
+        },
    effect: (host) => plugin.effect({ ...host, options: operation.options }),
-  } satisfies Versioned
+  } satisfies Generation
 })

 function localFeatures(entrypoint: string) {
@@ -4,7 +4,7 @@ import type { Plugin } from "@opencode-ai/plugin/effect/plugin"
 import { Context, Effect, Layer } from "effect"
 import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { Bus } from "../bus.js"
-import type { Versioned } from "../plugin.js"
+import type { Generation } from "../plugin.js"

 export const Updated = Bus.ephemeral({ type: "sdk.plugin.updated", schema: {} })

@@ -21,7 +21,7 @@ export const Updated = Bus.ephemeral({ type: "sdk.plugin.updated", schema: {} })
 */
 export interface Interface {
  readonly register: (plugin: Plugin) => Effect.Effect<void>
-  readonly all: () => readonly Versioned[]
+  readonly all: () => readonly Generation[]
 }

 export class Service extends Context.Service<Service, Interface>()("@opencode/SdkPlugins") {}
@@ -30,12 +30,12 @@ export const layer = Layer.effect(
  Service,
  Effect.gen(function* () {
    const bus = yield* Bus.Service
-    const plugins = new Map<string, Versioned>()
+    const plugins = new Map<string, Generation>()
    let revision = 0
    return Service.of({
      register: (plugin) =>
        Effect.sync(() => {
-          plugins.set(plugin.id, { ...plugin, version: String(++revision), source: { type: "sdk" } })
+          plugins.set(plugin.id, { ...plugin, revision: String(++revision), source: { type: "sdk" } })
        }).pipe(Effect.andThen(bus.publish(Updated, {})), Effect.asVoid),
      all: () => [...plugins.values()],
    })
@@ -3,10 +3,11 @@
 export * as SkillPlugin from "./skill.js"

 import { define, type Context } from "@opencode-ai/plugin/effect/plugin"
+import { Document } from "@opencode-ai/schema/config"
 import { Effect } from "effect"
 import { AbsolutePath } from "../schema.js"
 import { Skill } from "../skill.js"
-import { ConfigPluginSource } from "../config/plugin/source.js"
+import { Config } from "../config.js"
 import os from "os"
 import opencodeContent from "./skill/opencode.md" with { type: "text" }
 import reportContent from "./skill/report.md" with { type: "text" }
@@ -68,9 +69,11 @@ const reportContentWithDiagnostics = Effect.fn("SkillPlugin.reportContentWithDia
 })

 const configuredPlugins = Effect.fn("SkillPlugin.configuredPlugins")(function* () {
-  const sources = yield* ConfigPluginSource.Service
-  return (yield* sources.operations())
-    .map((operation) => (operation.type === "remove" ? `-${operation.target}` : operation.target))
+  const config = yield* Config.Service
+  return (yield* config.entries())
+    .filter((entry): entry is Document => entry.type === "document")
+    .flatMap((entry) => entry.info.plugins ?? [])
+    .map((entry) => (typeof entry === "string" ? entry : entry.package))
    .toSorted()
 })

@@ -7,7 +7,10 @@ import { Context, Effect } from "effect"
 * imports: the supervisor reaches PluginRuntime, which depends on Session.
 */
 export interface Interface {
-  /** Wait for the initial plugin generation and startup updates to settle. */
+  /**
+   * Wait for the plugin generation to settle. Use this rarely: blocking reads,
+   * UI startup, or other unrelated work on plugin boot should be avoided.
+   */
  readonly flush: Effect.Effect<void>
 }

@@ -14,17 +14,20 @@ import { PluginInternal } from "./internal.js"
 import { PluginModule } from "./module.js"
 import { SdkPlugins } from "./sdk.js"
 import { Service } from "./supervisor-service.js"
+import { PluginUpdate } from "./update.js"

 const resolve = Effect.fn("PluginSupervisor.resolve")(function* (
-  pre: readonly Plugin.Versioned[],
-  post: readonly Plugin.Versioned[],
+  pre: readonly Plugin.Generation[],
+  post: readonly Plugin.Generation[],
  operations: readonly ConfigPluginSource.Operation[],
+  install: boolean,
 ) {
  const matches = (selector: string, target: string) =>
    selector === "*" || (selector.endsWith(".*") ? target.startsWith(selector.slice(0, -1)) : selector === target)
  const definitions = [...pre, ...post]
  const enabled = new Set(definitions.map((plugin) => plugin.id))
-  const packages = new Map<string, Plugin.Versioned>()
+  const packages = new Map<string, Plugin.Generation>()
+  const pending = new Set<string>()
  const failures = new Map<
    string,
    Plugin.Info & { readonly state: Extract<Plugin.State, { readonly status: "failed" }> }
@@ -51,13 +54,17 @@ const resolve = Effect.fn("PluginSupervisor.resolve")(function* (
      continue
    }

-    const plugin = yield* PluginModule.load(operation).pipe(
+    const plugin = yield* PluginModule.load(operation, { install }).pipe(
      Effect.catchCause((cause) =>
        Effect.logWarning("failed to load plugin", { target: operation.target, cause }).pipe(
          Effect.as({ error: Cause.pretty(cause) }),
        ),
      ),
    )
+    if ("pending" in plugin) {
+      pending.add(operation.target)
+      continue
+    }
    if ("error" in plugin) {
      failures.set(operation.target, {
        source: pluginSource(operation.target),
@@ -80,9 +87,7 @@ const resolve = Effect.fn("PluginSupervisor.resolve")(function* (
      ...post.filter((plugin) => enabled.has(plugin.id)),
    ],
    failures: [...failures.values()],
-    refreshes: [...packages.entries()].flatMap(([target, plugin]) =>
-      !path.isAbsolute(target) && enabled.has(plugin.id) ? [target] : [],
-    ),
+    pending: [...pending],
  }
 })

@@ -94,45 +99,74 @@ export const layer = Layer.effect(
    const instance = yield* InstancePlugins.Service
    const sources = yield* ConfigPluginSource.Service
    const bus = yield* Bus.Service
-    const npm = yield* Npm.Service
+    const updates = yield* PluginUpdate.Service
    const ready = yield* Latch.make()
+    let packages = new Set<string>()
+    let outdated = new Set<string>()
+    let generation = 0
    let observed = 0

    const activate = Effect.fn("PluginSupervisor.activate")(function* () {
+      const current = ++generation
      // Resolve OpenCode's internal plugins with their privileged Location services.
      const internal = yield* PluginInternal.list()
      // Combine internal plugins with host-contributed plugins in boot order.
      // Instance-bound plugins come last: later activation can override earlier
      // container writes, so the instance's explicit choices win over globals.
      const pre = [
-        ...internal.pre.map((plugin) => ({ ...plugin, version: "internal", source: { type: "builtin" as const } })),
+        ...internal.pre.map((plugin) => ({ ...plugin, revision: "internal", source: { type: "builtin" as const } })),
        ...sdk.all(),
        ...instance.all(),
      ]
      const post = internal.post.map((plugin) => ({
        ...plugin,
-        version: "internal",
+        revision: "internal",
        source: { type: "builtin" as const },
      }))
      const operations = yield* sources.operations()
-      // Apply config operations and load enabled package plugins into one ordered generation.
-      const resolved = yield* resolve(pre, post, operations)
-      // Replace the active generation in one scoped, batched activation.
-      yield* registry.activate(resolved.plugins, resolved.failures)
-      if (resolved.refreshes.length) {
-        yield* Effect.forEach(
-          resolved.refreshes,
-          (target) =>
-            npm
-              .add(target, { subpaths: ["server", ""], refresh: true })
-              .pipe(
-                Effect.catchCause((cause) => Effect.logWarning("failed to refresh package plugin", { target, cause })),
-              ),
-          { concurrency: "unbounded", discard: true },
-        ).pipe(Effect.forkDetach)
-      }
+      // Activate everything available locally before waiting on missing package installs.
+      const immediate = yield* resolve(pre, post, operations, false)
+      const source = (source: Plugin.Source) =>
+        source.type === "package" && outdated.has(source.target)
+          ? { ...source, outdated: true as const }
+          : source
+      const apply = (resolved: typeof immediate) =>
+        registry.activate(
+          resolved.plugins.map((plugin) => (plugin.source ? { ...plugin, source: source(plugin.source) } : plugin)),
+          resolved.failures.map((failure) => ({ ...failure, source: source(failure.source) })),
+        )
+      yield* apply(immediate)
+      const resolved = immediate.pending.length ? yield* resolve(pre, post, operations, true) : immediate
+      if (resolved !== immediate) yield* apply(resolved)
+      const loaded = new Set(
+        [...resolved.plugins, ...resolved.failures].flatMap((plugin) =>
+          plugin.source?.type === "package" ? [plugin.source.target] : [],
+        ),
+      )
+      packages = loaded
+      yield* Effect.forEach(
+        loaded,
+        (target) => updates.check(target).pipe(Effect.map((available) => [target, available] as const)),
+        { concurrency: "unbounded" },
+      ).pipe(
+        Effect.flatMap((checked) => {
+          if (current !== generation) return Effect.void
+          const next = new Set(checked.flatMap(([target, available]) => (available ? [target] : [])))
+          if (next.size === outdated.size && [...next].every((target) => outdated.has(target))) return Effect.void
+          outdated = next
+          return apply(resolved)
+        }),
+        Effect.forkScoped({ startImmediately: true }),
+      )
    })
-    const updates = Stream.merge(sources.changes(), bus.subscribe([Event.Updated, SdkPlugins.Updated])).pipe(
+    const reloads = Stream.merge(
+      Stream.merge(sources.changes(), bus.subscribe([Event.Updated, SdkPlugins.Updated])),
+      updates.changes().pipe(
+        Stream.filter((target) => packages.has(target)),
+        Stream.tap((target) => Effect.sync(() => outdated.delete(target))),
+        Stream.map(() => undefined),
+      ),
+    ).pipe(
      // Make accepted work visible to flush before coalescing the burst.
      Stream.mapEffect(() =>
        Effect.gen(function* () {
@@ -142,7 +176,7 @@ export const layer = Layer.effect(
        }),
      ),
    )
-    yield* Stream.concat(Stream.succeed(0), updates).pipe(
+    yield* Stream.concat(Stream.succeed(0), reloads).pipe(
      // Keep observing updates while activation runs, retaining only the latest generation request.
      Stream.buffer({ capacity: 1, strategy: "sliding" }),
      Stream.debounce("100 millis"),
@@ -154,6 +188,7 @@ export const layer = Layer.effect(
      ),
      Effect.forkScoped({ startImmediately: true }),
    )
+    yield* Effect.sleep("24 hours").pipe(Effect.andThen(activate()), Effect.forever, Effect.forkScoped)
    return Service.of({ flush: ready.await })
  }),
 )
@@ -163,6 +198,7 @@ const nodeDeps = [
  SdkPlugins.node,
  InstancePlugins.node,
  ConfigPluginSource.node,
+  PluginUpdate.node,
  Bus.node,
  Npm.node,
  PluginInternal.requirements,
@@ -170,7 +206,7 @@ const nodeDeps = [

 function pluginSource(target: string): Plugin.Source {
  if (path.isAbsolute(target)) return { type: "local", path: target }
-  return { type: "package", package: target }
+  return { type: "package", target }
 }

 export const node = makeLocationNode({ service: Service, layer, deps: nodeDeps })
@@ -0,0 +1,54 @@
+export * as PluginUpdate from "./update.js"
+
+import { Clock, Context, Effect, Layer, Option, PubSub, Stream } from "effect"
+import { Npm } from "@opencode-ai/util/npm"
+import { EffectFlock } from "@opencode-ai/util/effect-flock"
+import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
+import { KeyedMutex } from "../effect/keyed-mutex.js"
+
+const interval = 24 * 60 * 60 * 1_000
+
+export interface Interface {
+  readonly check: (target: string) => Effect.Effect<boolean>
+  readonly update: (target: string) => Effect.Effect<void, Npm.InstallFailedError | EffectFlock.LockError>
+  readonly changes: () => Stream.Stream<string>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/PluginUpdate") {}
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const npm = yield* Npm.Service
+    const locks = KeyedMutex.makeUnsafe<string>()
+    const status = new Map<string, { readonly outdated: boolean; readonly checkedAt: number }>()
+    const changes = yield* PubSub.unbounded<string>()
+
+    return Service.of({
+      check: (target) =>
+        locks.withLock(target)(
+          Effect.gen(function* () {
+            const checkedAt = yield* Clock.currentTimeMillis
+            const current = status.get(target)
+            if (current && checkedAt - current.checkedAt < interval) return current.outdated
+            const outdated = yield* npm.check(target).pipe(
+              Effect.tapCause((cause) => Effect.logWarning("failed to check plugin update", { target, cause })),
+              Effect.option,
+            )
+            const value = Option.getOrElse(outdated, () => current?.outdated ?? false)
+            status.set(target, { outdated: value, checkedAt })
+            return value
+          }),
+        ),
+      update: (target) =>
+        npm.update(target).pipe(
+          Effect.tap(() => Effect.sync(() => status.delete(target))),
+          Effect.tap(() => PubSub.publish(changes, target)),
+          Effect.asVoid,
+        ),
+      changes: () => Stream.fromPubSub(changes),
+    })
+  }),
+)
+
+export const node = makeGlobalNode({ service: Service, layer, deps: [Npm.node] })
@@ -20,7 +20,6 @@ import type { Patch } from "../../vcs/patch.js"

 export const Plugin = define({
  id: "opencode.vcs.git",
-  vcs: { id: "git", markers: [".git"] },
  effect: Effect.fn("VcsGitPlugin")(function* (ctx) {
    const location = yield* Location.Service
    if (location.vcs?.type !== "git") return
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Brendan Allan	461c42f757	refactor(app): restore explicit persistence initial state	2026-09-01 17:41:49 +08:00
Brendan Allan	322bf226ba	test(app): remove leaking UI context mocks	2026-09-01 16:44:14 +08:00
Brendan Allan	66ed350fea	fix(app): preserve persisted state compatibility	2026-09-01 16:34:37 +08:00
Brendan Allan	e65e1ecf59	refactor(app): simplify persistence schema helpers	2026-09-01 16:17:40 +08:00
Brendan Allan	d40b64a6bd	refactor(app): drive persisted state with Effect Schema	2026-09-01 15:19:59 +08:00
opencode-agent[bot]andBrendonovich	71779ae5de	fix(app): scope pane visibility to tabs (#46508 ) Co-authored-by: Brendonovich <14191578+Brendonovich@users.noreply.github.com>	2026-09-01 12:21:42 +08:00
Aiden Cline	4a3e25beab	feat(codemode): compact schema constraint comments (#46521 )	2026-08-31 23:06:49 -05:00
opencode-agent[bot]andrekram1-node	23fde448ec	test(cli): isolate Bun define cache (#46536 ) Co-authored-by: rekram1-node <63023139+rekram1-node@users.noreply.github.com>	2026-08-31 23:01:02 -05:00
opencode-agent[bot]	1137861188	chore: update nix node_modules hashes	2026-09-01 04:00:15 +00:00
Dax Raad	815d4ab9b4	fix(tui): scope connect dialog to location	2026-08-31 23:42:35 -04:00
Dax Raad	5d73a5789f	feat(plugin): support live package updates	2026-08-31 23:35:21 -04:00