fix(tui): use existing palette for stats graph

Co-authored-by: David Hill <iamdavidhill@gmail.com>

bun.lock

@@ -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:",
       },
     },

nix/hashes.json

@@ -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="
   }
 }

packages/app/e2e/regression/file-browser-sidebar-tab-switch.spec.ts

@@ -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}` },
   )
 }

packages/app/e2e/regression/open-file-expand-folder.spec.ts

@@ -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}`)

packages/app/e2e/regression/project-extensions.spec.ts

@@ -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 },
           })),

packages/app/e2e/regression/review-open-file.spec.ts

@@ -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}`)

packages/app/e2e/regression/review-state-persistence.spec.ts

@@ -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")
 

packages/app/e2e/regression/review-tab-switch.spec.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] },
   )
 }
 

packages/app/e2e/regression/review-terminal-bottom.spec.ts

@@ -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 })

packages/app/e2e/regression/settings-loading.spec.ts

@@ -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 },
           },

packages/app/e2e/regression/terminal-composer-focus.spec.ts

@@ -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,
+    },
   )
 }
 

packages/app/e2e/regression/terminal-tab-switch.spec.ts

@@ -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
 }

packages/app/e2e/regression/workspace-accent.spec.ts

@@ -75,11 +75,12 @@ for (const theme of ["light", "dark"] as const) {
         await expectBackground(view.send, "contrast")
         const message = page.locator('[data-slot="user-message-text"]')
         await expect(message).toHaveText("Check this fixture workspace.")
-        await expectBackground(
+        await expectToken(
           message,
-          scenario.accent ? "accent" : theme === "light" ? "layer-02" : "layer-01",
           "background-color",
+          scenario.accent ? "--v2-background-bg-accent" : "--v2-state-bg-info",
         )
+        await expectToken(message, "color", scenario.accent ? "--v2-text-text-contrast" : "--v2-text-text-accent")
       })
     }
 
@@ -245,3 +246,16 @@ async function expectBackground(element: Locator, token: string, property = "bac
   }, token)
   await expect(element).toHaveCSS(property, new RegExp(color.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")))
 }
+
+async function expectToken(element: Locator, property: string, token: string) {
+  const color = await element.evaluate((element, token) => {
+    const probe = document.createElement("span")
+    probe.hidden = true
+    probe.style.color = `var(${token})`
+    element.append(probe)
+    const color = getComputedStyle(probe).color
+    probe.remove()
+    return color
+  }, token)
+  await expect(element).toHaveCSS(property, color)
+}

packages/app/src/providers/catalog/plugin.test.ts

@@ -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 },
       },

packages/app/src/providers/catalog/plugin.ts

@@ -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
 }

packages/app/src/runtime/animated-presence.ts

@@ -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,

packages/app/src/runtime/server/errors.test.ts

@@ -155,6 +155,16 @@ describe("isSessionNotFoundError", () => {
     expect(isSessionNotFoundError(new Error(body.message, { cause: { body, status: 404 } }), body.sessionID)).toBe(true)
   })
 
+  test("matches a structured error stored directly as the cause", () => {
+    const body = {
+      _tag: "SessionNotFoundError",
+      sessionID: "ses_missing",
+      message: "Session not found",
+    } satisfies SessionNotFoundError
+
+    expect(isSessionNotFoundError(new Error("Unknown error", { cause: body }), body.sessionID)).toBe(true)
+  })
+
   test("rejects errors for other sessions and other 404 responses", () => {
     const body = {
       _tag: "SessionNotFoundError",

packages/app/src/runtime/server/errors.ts

@@ -36,10 +36,9 @@ export function formatServerError(error: unknown, translate?: Translator, fallba
 }
 
 function unwrapNamedError(error: unknown): unknown {
-  if (error instanceof Error && error.cause && typeof error.cause === "object" && "body" in error.cause) {
-    return (error.cause as Record<string, unknown>).body
-  }
-  return error
+  if (!(error instanceof Error) || !error.cause || typeof error.cause !== "object") return error
+  if ("body" in error.cause) return (error.cause as Record<string, unknown>).body
+  return error.cause
 }
 
 // Client-synthesized session not-found errors share one constructor and

packages/app/src/session/files/file-tree-v2-model.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test"
-import { buildFileTreeV2Model, flattenFileTreeV2, flattenLiveFileTreeV2 } from "./file-tree-v2-model"
+import { buildFileTreeV2Model, flattenFileTreeV2, flattenLiveFileTreeV2, sortFileTreeV2Paths } from "./file-tree-v2-model"
 import type { FileNode } from "@/runtime/server/types"
 
 describe("buildFileTreeV2Model", () => {
@@ -45,6 +45,33 @@ describe("buildFileTreeV2Model", () => {
   })
 })
 
+describe("sortFileTreeV2Paths", () => {
+  test("orders navigation depth-first with directories before sibling files", () => {
+    const paths = ["README.md", "src/a.ts", "src/lib/z.ts", "docs/guide.md", "src/lib/b.ts"]
+
+    expect(sortFileTreeV2Paths(paths)).toEqual([
+      "docs/guide.md",
+      "src/lib/b.ts",
+      "src/lib/z.ts",
+      "src/a.ts",
+      "README.md",
+    ])
+    expect(paths[0]).toBe("README.md")
+  })
+
+  test("preserves original paths for selection", () => {
+    expect(sortFileTreeV2Paths(["README.md", "src\\lib\\a.ts", "/docs//guide.md/"])).toEqual([
+      "/docs//guide.md/",
+      "src\\lib\\a.ts",
+      "README.md",
+    ])
+  })
+
+  test("handles an empty file list", () => {
+    expect(sortFileTreeV2Paths([])).toEqual([])
+  })
+})
+
 describe("flattenLiveFileTreeV2", () => {
   test("flattens live children using original paths for nested lookups", () => {
     const nodes: Record<string, FileNode[]> = {

packages/app/src/session/files/file-tree-v2-model.ts

@@ -76,6 +76,12 @@ export function flattenFileTreeV2(model: FileTreeV2Model, expanded: (path: strin
   return rows
 }
 
+export function sortFileTreeV2Paths(paths: readonly string[]) {
+  return flattenFileTreeV2(buildFileTreeV2Model(paths), () => true)
+    .filter((row) => row.node.type === "file")
+    .map((row) => row.node.originalPath)
+}
+
 export function flattenLiveFileTreeV2(
   children: (path: string) => readonly FileNode[],
   expanded: (path: string) => boolean,

packages/app/src/session/model.ts

@@ -129,6 +129,7 @@ export function useSessionModel() {
     layout: {
       tabs: layout.tabs,
       view: layout.view,
+      tabKey: layout.tabKey,
     },
     ownership: createSessionOwnership(layout.sessionKey),
     tabs: {

packages/app/src/session/review/panel.tsx

@@ -18,6 +18,7 @@ import type {
   SessionReviewLineComment,
 } from "@opencode-ai/session-ui/session-review"
 import FileTreeV2 from "@/session/files/file-tree-v2"
+import { sortFileTreeV2Paths } from "@/session/files/file-tree-v2-model"
 import { useLanguage } from "@/runtime/i18n/language"
 import { useWorkspaceLocation } from "@/workspaces/location"
 import { useServerSDK } from "@/runtime/server/client"
@@ -83,6 +84,9 @@ export function ReviewPanelView(
     ),
   )
   const searching = createMemo(() => props.state.filter().trim().length > 0)
+  const navigationFiles = createMemo(() =>
+    searching() || props.fileList === "flat" ? filteredFiles() : sortFileTreeV2Paths(filteredFiles()),
+  )
   const kinds = createMemo(() => reviewDiffKinds(diffs()))
   // Changes-only trees omit "M" — every row is already a change; A/D stay visible.
   const treeKinds = createMemo(() => new Map([...kinds()].filter(([, kind]) => kind !== "mix")))
@@ -93,7 +97,7 @@ export function ReviewPanelView(
     if (focus && diffs().some((diff) => diff.file === focus.file)) return focus.file
     const active = props.activeFile
     if (searching()) return active
-    const files = filteredFiles()
+    const files = navigationFiles()
     if (active && files.includes(active)) return active
     return files[0]
   })
@@ -141,7 +145,7 @@ export function ReviewPanelView(
         />
       }
       activeFile={activeDiff()}
-      files={filteredFiles()}
+      files={navigationFiles()}
       onSelectFile={props.onSelectFile}
       diffStyle={props.diffStyle}
       onDiffStyleChange={props.onDiffStyleChange}

packages/app/src/session/screen-layout.ts

@@ -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)

packages/app/src/session/screen.tsx

@@ -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>

packages/app/src/session/session-layout.ts

@@ -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)),
   }
 }

packages/app/src/session/terminal/panel.tsx

@@ -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}
     >

packages/app/src/session/terminal/surface.tsx

@@ -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}

packages/app/src/session/timeline/virtualizer.tsx

@@ -478,7 +478,11 @@ export function createTimelineVirtualizer(input: Input) {
     }
 
     return (
-      <div class="relative w-full h-full min-w-0" data-workspace-session={props.workspaceSession() ? "" : undefined}>
+      <div
+        class="relative w-full h-full min-w-0"
+        data-workspace-session={props.workspaceSession() ? "" : undefined}
+        data-local-session={!props.workspaceSession() ? "" : undefined}
+      >
         <div
           class="absolute left-1/2 -translate-x-1/2 z-[60] pointer-events-none transition-all duration-200 ease-out"
           classList={{

packages/app/src/shell/state/layout.tsx

@@ -59,6 +59,16 @@ export type HomeProjectSelection = { server: ServerConnection.Key; directory?: s
 export type ReviewDiffStyle = "unified" | "split"
 export type ReviewChangeMode = "git" | "branch" | "turn"
 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" }
@@ -508,7 +518,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 +529,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 +560,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 +596,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 +617,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)
             },

packages/app/src/shell/tabs/tabs.test.ts

@@ -2,7 +2,7 @@ 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 { findSessionTab, sessionIDHasOpenTab, tabHref, tabKey, type SessionTab, type Tab } from "./tabs"
 import { migrateTabs } from "./migration"
 import type { ServerConnection } from "@/runtime/server/registry"
 
@@ -48,8 +48,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)

packages/app/src/shell/tabs/tabs.tsx

@@ -46,6 +46,10 @@ export type TabInfo = {
   directory?: string
 }
 
+export type TabPane = "terminal" | "review"
+export type TabPaneSize = "terminalHeight" | "sessionWidth"
+type TabPaneState = Partial<Record<TabPane, boolean> & Record<TabPaneSize, number>>
+
 type RecentTab = {
   key?: string
 }
@@ -62,8 +66,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,6 +75,10 @@ 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,
@@ -89,6 +97,10 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
       Persist.window("tabs.info"),
       createStore<Record<string, TabInfo>>({}),
     )
+    const [panes, setPanes, , panesReady] = persisted(
+      Persist.window("tabs.panes"),
+      createStore<Record<string, TabPaneState>>({}),
+    )
     const [closed, setClosed, , closedReady] = persisted(Persist.window("tabs.closed"), createStore<ClosedTab[]>([]))
     const [pending, setPending] = createStore<Record<string, PendingSession | undefined>>({})
 
@@ -141,6 +153,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 +174,7 @@ export const { use: useTabs, provider: TabsProvider } = createSimpleContext({
             const key = tabKey(tab)
             memory.remove(key)
             removeInfo(key)
+            removePanes(key)
           }
         }
         setStore(() => next)
@@ -162,6 +184,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 +224,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 +518,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 }
   },
 })

packages/app/test-browser/animated-presence-state.test.ts

@@ -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()
+  })
+})

packages/cli/src/commands/handlers/plugin/list.ts

@@ -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
 }

packages/cli/src/commands/handlers/stats.ts

@@ -1,5 +1,7 @@
 import { ClientError, OpenCode, type SessionStatsInfo } from "@opencode-ai/client"
 import { Service } from "@opencode-ai/client/effect/service"
+import { TokenUsage } from "@opencode-ai/schema/token-usage"
+import { activityCalendar } from "@opencode-ai/util/activity-calendar"
 import { Effect, Option } from "effect"
 import { EOL } from "node:os"
 import { Commands } from "../commands"
@@ -91,7 +93,7 @@ type RenderOptions = {
 const colors = terminalPalette()
 
 export function renderStats(stats: SessionStatsInfo, options: RenderOptions) {
-  const totalTokens = tokenTotal(stats.tokens)
+  const totalTokens = TokenUsage.total(stats.tokens)
   const toolTotals = stats.tools.mode === "none" ? undefined : stats.tools.totals
   const terminalTools = toolTotals ? toolTotals.succeeded + toolTotals.failed : 0
   const toolRate = !toolTotals || terminalTools === 0 ? undefined : (toolTotals.succeeded / terminalTools) * 100
@@ -167,43 +169,23 @@ function renderActivity(
   color: boolean,
   width: number,
 ) {
-  const values = new Map(activity.map((day) => [day.date, day.steps]))
-  const rangeStart = dateOrdinal(new Date(from))
-  const rangeEnd = dateOrdinal(new Date(to - 1))
-  const end = new Date(to - 1)
-  end.setHours(12, 0, 0, 0)
-  end.setDate(end.getDate() + (7 - mondayIndex(end) - 1))
-  const start = new Date(from)
-  start.setHours(12, 0, 0, 0)
-  start.setDate(start.getDate() - mondayIndex(start))
-  const maxWeeks = Math.max(1, Math.min(53, width - 4))
-  const totalWeeks = Math.floor((dateOrdinal(end) - dateOrdinal(start)) / 7) + 1
-  const latest = new Date(end)
-  latest.setDate(latest.getDate() - (maxWeeks - 1) * 7)
-  if (start < latest) start.setTime(latest.getTime())
-
-  const active = [...values.values()].filter((value) => value > 0)
-  const levels = [...new Set(active)].sort((a, b) => a - b)
-  const weekStarts = Array.from({ length: Math.floor((dateOrdinal(end) - dateOrdinal(start)) / 7) + 1 }, (_, week) => {
-    const date = new Date(start)
-    date.setDate(date.getDate() + week * 7)
-    return date
-  })
-  const weeks = weekStarts.map((week) =>
-    Array.from({ length: 7 }, (_, day) => {
-      const date = new Date(week)
-      date.setDate(date.getDate() + day)
-      const ordinal = dateOrdinal(date)
-      if (ordinal < rangeStart || ordinal > rangeEnd) return " "
-      return activityGlyph(values.get(dateKey(date)) ?? 0, levels, color)
-    }),
-  )
+  const calendar = activityCalendar({ activity, from, to, maxWeeks: width - 4 })
+  const months = calendar.months
+    .map((month, index) =>
+      (index === calendar.months.length - 1 || month.label.length <= month.span ? month.label : "").padEnd(month.span),
+    )
+    .join("")
+    .trimEnd()
   const weekdays = ["Mo", "Tu", "We", "Th", "Fr", "Sa", "Su"]
   return [
-    style(totalWeeks > maxWeeks ? `activity · last ${maxWeeks} weeks` : "activity", `1;${colors.primary}`, color),
-    `   ${style(monthLabels(weekStarts), "2", color)}`,
+    style(
+      calendar.clipped ? `activity · last ${calendar.weeks.length} weeks` : "activity",
+      `1;${colors.primary}`,
+      color,
+    ),
+    `   ${style(months, "2", color)}`,
     ...weekdays.flatMap((label, day) => [
-      `${style(label, "2", color)} ${weeks.map((week) => week[day]).join("")}`,
+      `${style(label, "2", color)} ${calendar.weeks.map((week) => (week[day].level < 0 ? " " : paintActivity(week[day].level, color))).join("")}`,
       ...(day === weekdays.length - 1 ? [] : [""]),
     ]),
     "",
@@ -238,7 +220,7 @@ function renderModels(stats: SessionStatsInfo, limit: number, width: number) {
           `${item.model.providerID}/${item.model.id}${item.model.variant ? `#${item.model.variant}` : ""}`,
           width,
         ),
-        `  ${formatNumber(tokenTotal(item.tokens))} tokens · ${formatNumber(item.steps)} steps · $${item.cost.toFixed(2)}`,
+        `  ${formatNumber(TokenUsage.total(item.tokens))} tokens · ${formatNumber(item.steps)} steps · $${item.cost.toFixed(2)}`,
       ]),
       ...(more > 0 ? ["", `+${more.toLocaleString("en-US")} more model${more === 1 ? "" : "s"}`] : []),
     ]
@@ -248,7 +230,7 @@ function renderModels(stats: SessionStatsInfo, limit: number, width: number) {
     ...models.map((item) =>
       tableRow(
         `${item.model.providerID}/${item.model.id}${item.model.variant ? `#${item.model.variant}` : ""}`,
-        formatNumber(tokenTotal(item.tokens)),
+        formatNumber(TokenUsage.total(item.tokens)),
         formatNumber(item.steps),
         `$${item.cost.toFixed(2)}`,
       ),
@@ -310,10 +292,6 @@ function truncate(value: string, width: number) {
   return value.length <= width ? value : value.slice(0, width - 1) + "…"
 }
 
-function tokenTotal(tokens: SessionStatsInfo["tokens"]) {
-  return tokens.input + tokens.output + tokens.reasoning + tokens.cache.read + tokens.cache.write
-}
-
 function formatNumber(value: number) {
   if (value >= 1_000_000_000) return `${trimDecimal(value / 1_000_000_000)}b`
   if (value >= 1_000_000) return `${trimDecimal(value / 1_000_000)}m`
@@ -342,13 +320,6 @@ function style(value: string, code: string, color: boolean) {
   return color ? `\x1b[${code}m${value}\x1b[0m` : value
 }
 
-function activityGlyph(value: number, levels: number[], color: boolean) {
-  if (value === 0) return paintActivity(0, color)
-  const index = levels.indexOf(value)
-  const level = Math.max(1, Math.ceil(((index + 1) / levels.length) * 4))
-  return paintActivity(level, color)
-}
-
 function paintActivity(level: number, color: boolean) {
   const glyph = ["·", "░", "▒", "▓", "█"][level]
   if (!color) return glyph
@@ -370,39 +341,3 @@ function terminalPalette() {
     }
   return { primary: "36", activity: ["2;36", "36", "1;36", "1;96"] }
 }
-
-function monthLabels(weeks: Date[]) {
-  const line: string[] = []
-  weeks.reduce((previous, week, index) => {
-    const middle = new Date(week)
-    middle.setDate(middle.getDate() + 3)
-    const month = middle.getMonth()
-    if (month === previous) return previous
-    Intl.DateTimeFormat("en-US", { month: "short" })
-      .format(middle)
-      .split("")
-      .forEach((character, offset) => {
-        line[index + offset] = character
-      })
-    return month
-  }, -1)
-  return Array.from({ length: Math.max(weeks.length, line.length) }, (_, index) => line[index] ?? " ")
-    .join("")
-    .trimEnd()
-}
-
-function mondayIndex(date: Date) {
-  return (date.getDay() + 6) % 7
-}
-
-function dateKey(date: Date) {
-  return [
-    date.getFullYear(),
-    String(date.getMonth() + 1).padStart(2, "0"),
-    String(date.getDate()).padStart(2, "0"),
-  ].join("-")
-}
-
-function dateOrdinal(date: Date) {
-  return Math.floor(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()) / 86_400_000)
-}

packages/cli/test/plugin-list.test.ts

@@ -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 },
         },

packages/cli/test/stats.test.ts

@@ -48,6 +48,20 @@ describe("stats rendering", () => {
     expect(output).not.toContain("$12.34")
   })
 
+  test("renders shared intensity levels and partial month labels", () => {
+    const output = renderStats(
+      {
+        ...stats,
+        range: { from: new Date(2026, 3, 29).getTime(), to: new Date(2026, 4, 20).getTime() },
+        activity: [{ date: "2026-04-29", steps: 1 }],
+      },
+      options(),
+    )
+    expect(output).toContain("    May")
+    expect(output).not.toContain("Apr")
+    expect(output.split(/\r?\n/).find((line) => line.startsWith("We "))).toContain("\u2588")
+  })
+
   test("renders only requested detail tables", () => {
     const output = renderStats(stats, options({ tools: true, cost: true }))
     expect(output).toContain("COST & TOKENS")

packages/cli/test/updater-install.test.ts

@@ -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)

packages/client/src/effect/api/api.ts

@@ -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 = {

packages/client/src/effect/generated/client.ts

@@ -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>()(

packages/client/src/promise/generated/client.ts

@@ -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) =>

packages/client/src/promise/generated/types.ts

@@ -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

packages/codemode/src/tool-schema.ts

@@ -78,16 +78,43 @@ const docTags = (schema: JsonSchema): Array<string> => {
   return tags
 }
 
-// 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 docLines = (schema: JsonSchema, width: number): Array<string> => {
+  const summary = docTags(schema).join(" ")
+  const lines = (schema.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
+  return summary && lines.length === 1 && !summary.includes("\n") && width + inline.length + 7 <= 120
+    ? [inline]
+    : [...lines, ...(summary ? summary.split("\n") : [])]
+}
+
+// Neutralize `*\/` so model-provided schema text cannot terminate generated documentation.
+const jsdoc = (schema: JsonSchema, pad: string): string => {
+  const content = docLines(schema, pad.length)
+  const types = typeof schema.type === "string" ? [schema.type] : (schema.type ?? [])
+
+  const append = (label: string, child: JsonSchema) => {
+    docLines(child, pad.length + label.length + 2).forEach((line, index) => {
+      if (index === 0) {
+        content.push(`${label}: ${line}`)
+        return
+      }
+      content.push(line ? `  ${line}` : "")
+    })
+  }
+
+  // Document only the immediate contents; recursive labels obscure which level a constraint belongs to.
+  if (types.includes("array") && schema.items) append("Each item", schema.items)
+  if ((types.includes("object") || schema.properties) && typeof schema.additionalProperties === "object") {
+    const label = Object.keys(schema.properties ?? {}).length > 0 ? "Each additional value" : "Each value"
+    append(label, schema.additionalProperties)
+  }
+
+  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`
 }
 
@@ -166,9 +193,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)},`,
-    )
+    const lines = properties.map((entry) => `${jsdoc(entry[1], pad)}${pad}${field(entry)},`)
     if (indexType !== undefined) lines.push(`${pad}[key: string]: ${indexType},`)
     return `{\n${lines.join("\n")}\n${"  ".repeat(depth)}}`
   }

packages/codemode/test/signature.test.ts

@@ -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,
@@ -139,6 +123,175 @@ describe("pretty signature rendering", () => {
     expect(pretty).toBe(["{", "  size?: number,", "}"].join("\n"))
   })
 
+  test("labels immediate item and dictionary value metadata above the field", () => {
+    const schema = {
+      properties: {
+        recipients: {
+          type: "array",
+          description: "People to notify",
+          minItems: 1,
+          items: { type: "string", description: "Email address", format: "email" },
+        },
+        scores: { type: "object", additionalProperties: { type: "number", minimum: 0 } },
+        names: { type: "array", items: { type: "string", description: "Display name" } },
+        plain: { type: "object", additionalProperties: { type: "string" } },
+      },
+    }
+    expect(jsonSchemaToTypeScript(schema, true)).toBe(
+      [
+        "{",
+        "  /**",
+        "   * People to notify. @minItems 1",
+        "   * Each item: Email address. @format email",
+        "   */",
+        "  recipients?: Array<string>,",
+        "  /** Each value: @minimum 0 */",
+        "  scores?: {",
+        "    [key: string]: number,",
+        "  },",
+        "  /** Each item: Display name */",
+        "  names?: Array<string>,",
+        "  plain?: {",
+        "    [key: string]: string,",
+        "  },",
+        "}",
+      ].join("\n"),
+    )
+    expect(jsonSchemaToTypeScript(schema)).toBe(
+      "{ recipients?: Array<string>; scores?: { [key: string]: number }; names?: Array<string>; plain?: { [key: string]: string } }",
+    )
+  })
+
+  test("does not apply additional property metadata to named properties", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        {
+          properties: {
+            scores: {
+              type: "object",
+              properties: { title: { type: "string", description: "Score title" } },
+              additionalProperties: { type: "number", minimum: 0 },
+            },
+          },
+        },
+        true,
+      ),
+    ).toBe(
+      [
+        "{",
+        "  /** Each additional value: @minimum 0 */",
+        "  scores?: {",
+        "    /** Score title */",
+        "    title?: string,",
+        "    [key: string]: number,",
+        "  },",
+        "}",
+      ].join("\n"),
+    )
+  })
+
+  test("labels array and dictionary contents in type-array unions", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        {
+          properties: {
+            recipients: { type: ["array", "null"], items: { type: "string", format: "email" } },
+            scores: { type: ["object", "null"], additionalProperties: { type: "number", minimum: 0 } },
+            either: {
+              type: ["array", "object"],
+              items: { type: "string", minLength: 1 },
+              additionalProperties: { type: "number", minimum: 0 },
+            },
+          },
+        },
+        true,
+      ),
+    ).toBe(
+      [
+        "{",
+        "  /** Each item: @format email */",
+        "  recipients?: Array<string> | null,",
+        "  /** Each value: @minimum 0 */",
+        "  scores?: {",
+        "      [key: string]: number,",
+        "    } | null,",
+        "  /**",
+        "   * Each item: @minLength 1",
+        "   * Each value: @minimum 0",
+        "   */",
+        "  either?: Array<string> | {",
+        "      [key: string]: number,",
+        "    },",
+        "}",
+      ].join("\n"),
+    )
+  })
+
+  test("keeps multiline item metadata indented under its label and escapes terminators", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        {
+          properties: {
+            values: {
+              type: "array",
+              minItems: 1,
+              items: { type: "string", description: "\nFirst */ line\n\nSecond line\n", pattern: "^\\d+\n*/$" },
+            },
+          },
+        },
+        true,
+      ),
+    ).toBe(
+      [
+        "{",
+        "  /**",
+        "   * @minItems 1",
+        "   * Each item: First * / line",
+        "   *",
+        "   *   Second line",
+        "   *   @pattern ^\\d+",
+        "   *   * /$",
+        "   */",
+        "  values?: Array<string>,",
+        "}",
+      ].join("\n"),
+    )
+  })
+
+  test("does not flatten nested containers, reference targets, or branches into item metadata", () => {
+    expect(
+      jsonSchemaToTypeScript(
+        {
+          $defs: { Email: { type: "string", format: "email" } },
+          properties: {
+            matrix: { type: "array", items: { type: "array", minItems: 2, items: { type: "integer", minimum: 0 } } },
+            refs: { type: "array", items: { $ref: "#/$defs/Email", description: "Recipient" } },
+            choices: {
+              type: "array",
+              items: {
+                anyOf: [
+                  { type: "string", minLength: 1 },
+                  { type: "number", minimum: 0 },
+                ],
+              },
+            },
+          },
+        },
+        true,
+      ),
+    ).toBe(
+      [
+        "{",
+        "  /** Each item: @minItems 2 */",
+        "  matrix?: Array<Array<number>>,",
+        "  /** Each item: Recipient */",
+        "  refs?: Array<string>,",
+        "  choices?: Array<string | number>,",
+        "}",
+      ].join("\n"),
+    )
+  })
+
   test.each([
     [{ type: "number", minimum: 0 }, "@minimum 0", "number"],
     [{ type: "number", maximum: 0 }, "@maximum 0", "number"],
@@ -151,9 +304,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 +350,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 +387,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",
@@ -460,9 +693,10 @@ describe("JSDoc signatures in catalogs and search results", () => {
         properties: {
           count: { type: "integer", minimum: 0, maximum: 10 },
           name: { type: "string", minLength: 1, maxLength: 20, pattern: "^[a-z]+$" },
-          labels: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 5 },
+          labels: { type: "array", items: { type: "string", minLength: 1 }, minItems: 1, maxItems: 5 },
+          scores: { type: "object", additionalProperties: { type: "integer", minimum: 0 } },
         },
-        required: ["count", "name", "labels"],
+        required: ["count", "name", "labels", "scores"],
       },
     },
     {
@@ -470,7 +704,11 @@ describe("JSDoc signatures in catalogs and search results", () => {
       schema: Schema.Struct({
         count: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(10)),
         name: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(20), Schema.isPattern(/^[a-z]+$/)),
-        labels: Schema.Array(Schema.String).check(Schema.isMinLength(1), Schema.isMaxLength(5)),
+        labels: Schema.Array(Schema.String.check(Schema.isMinLength(1))).check(
+          Schema.isMinLength(1),
+          Schema.isMaxLength(5),
+        ),
+        scores: Schema.Record(Schema.String, Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
       }),
     },
   ])("$source constraints survive input/output catalog and search signatures", async ({ schema }) => {
@@ -480,29 +718,25 @@ describe("JSDoc signatures in catalogs and search results", () => {
           description: "Constrained tool",
           input: schema,
           output: schema,
-          execute: () => Effect.succeed({ count: 1, name: "test", labels: ["test"] }),
+          execute: () => Effect.succeed({ count: 1, name: "test", labels: ["test"], scores: { test: 1 } }),
         }),
       },
     })
     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",
+      "   * Each item: @minLength 1",
       "   */",
       "  labels: Array<string>,",
+      "  /** Each value: @integer @minimum 0 */",
+      "  scores: {",
+      "    [key: string]: number,",
+      "  },",
       "}",
     ].join("\n")
     const signature = `tools.constrained(input: ${type}): Promise<${type}>`
@@ -522,7 +756,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 +766,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>",

packages/core/src/codemode/catalog.ts

@@ -1,19 +1,25 @@
 export * as CodeModeCatalog from "./catalog.js"
 
-import type { Namespace } from "@opencode-ai/schema/tool"
 import { Schema } from "effect"
 
 export const Tool = Schema.Struct({
-  path: Schema.String,
+  type: Schema.Literal("tool"),
+  name: Schema.String,
   description: Schema.String,
   signature: Schema.String,
   pinned: Schema.optionalKey(Schema.Boolean),
 })
 export type Tool = typeof Tool.Type
 
+export type Namespace = {
+  readonly type: "namespace"
+  readonly name: string
+  readonly description?: string
+  readonly tools: ReadonlyArray<Tool | Namespace>
+}
+
 export type Inventory = {
-  readonly tools: ReadonlyArray<Tool>
-  readonly namespaces?: ReadonlyMap<string, Namespace>
+  readonly tools: ReadonlyArray<Tool | Namespace>
 }
 
 const Listing = Schema.Struct({
@@ -47,14 +53,15 @@ const INLINE_BUDGET = 2_000
 // considering shorter listings first until the inline budget is exhausted.
 export function summarize(inventory: Inventory, options: Options = {}): Summary {
   const budget = options.budget ?? INLINE_BUDGET
-  const namespaces = [...Map.groupBy(inventory.tools, (tool) => tool.path.split(".", 1)[0] ?? tool.path)]
+  const flattened = flatten(inventory.tools)
+  const namespaces = [...Map.groupBy(flattened.tools, (tool) => tool.path.split(".", 1)[0] ?? tool.path)]
     .sort(([left], [right]) => {
       if (left < right) return -1
       if (left > right) return 1
       return 0
     })
     .map(([name, namespaceEntries]) => {
-      const description = inventory.namespaces?.get(name)?.description
+      const description = flattened.namespaces.get(name)?.description
       const listings = namespaceEntries
         .map((entry) => {
           const firstLine = entry.description.split("\n", 1)[0]?.trim() ?? ""
@@ -126,12 +133,35 @@ export function summarize(inventory: Inventory, options: Options = {}): Summary
     entries: namespace.listings.filter((listing) => namespace.selectedListings.has(listing)),
   }))
   return {
-    total: inventory.tools.length,
+    total: flattened.tools.length,
     shown: namespaceSummaries.reduce((total, namespace) => total + namespace.entries.length, 0),
     namespaces: namespaceSummaries,
   }
 }
 
+function flatten(entries: ReadonlyArray<Tool | Namespace>, path: ReadonlyArray<string> = []) {
+  const tools: Array<Omit<Tool, "name"> & { readonly path: string }> = []
+  const namespaces = new Map<string, Namespace>()
+  for (const entry of entries) {
+    if (entry.type === "tool") {
+      tools.push({
+        type: "tool",
+        path: [...path, entry.name].join("."),
+        description: entry.description,
+        signature: entry.signature,
+        ...(entry.pinned === undefined ? {} : { pinned: entry.pinned }),
+      })
+      continue
+    }
+    const next = [...path, entry.name]
+    namespaces.set(next.join("."), entry)
+    const nested = flatten(entry.tools, next)
+    tools.push(...nested.tools)
+    for (const [name, namespace] of nested.namespaces) namespaces.set(name, namespace)
+  }
+  return { tools, namespaces }
+}
+
 export function namespaceLine(namespace: typeof NamespaceSummary.Type) {
   const count = namespace.count === 1 ? "1 tool" : `${namespace.count} tools`
   const label =

packages/core/src/codemode/tool.ts

@@ -40,12 +40,14 @@ type CollectedFiles = {
   readonly files: Array<typeof ExecuteFile.Type>
 }
 
-type ToolNode = {
-  tool?: Tool.Tool<never>
+type Node<T> = {
+  tool?: T
   namespace?: ToolNamespace
-  readonly children: Map<string, ToolNode>
+  readonly children: Map<string, Node<T>>
 }
 
+type ToolNode = Node<Tool.Tool<never>>
+
 type Tools = {
   [name: string]: Tool.Tool<never> | Namespace.Namespace<never> | Tools
 }
@@ -162,14 +164,43 @@ export const catalog = (inventory: Inventory) => {
       .filter((registration) => registration.options?.pinned === true)
       .map(qualifiedName),
   )
+  const root: CatalogNode = { children: new Map() }
+  for (const namespace of inventory.namespaces?.values() ?? []) getNode(root, namespace.name).namespace = namespace
+  for (const tool of runtime(inventory, () => Effect.fail(toolError("Execute context is unavailable"))).catalog())
+    getNode(root, tool.path).tool = {
+      type: "tool",
+      name: tool.path.split(".").at(-1) ?? tool.path,
+      description: tool.description,
+      signature: tool.signature,
+      pinned: pinned.has(tool.path),
+    }
   return {
-    tools: runtime(inventory, () => Effect.fail(toolError("Execute context is unavailable")))
-      .catalog()
-      .map((tool) => ({ ...tool, pinned: pinned.has(tool.path) })),
-    ...(inventory.namespaces === undefined ? {} : { namespaces: inventory.namespaces }),
+    tools: renderCatalog(root),
   } satisfies CodeModeCatalog.Inventory
 }
 
+type CatalogNode = Node<CodeModeCatalog.Tool>
+
+function renderCatalog(root: CatalogNode): ReadonlyArray<CodeModeCatalog.Tool | CodeModeCatalog.Namespace> {
+  return Array.from(root.children)
+    .toSorted(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .flatMap(([name, node]) => {
+      const tools = renderCatalog(node)
+      const namespace =
+        node.namespace === undefined && tools.length === 0
+          ? undefined
+          : {
+              type: "namespace" as const,
+              name,
+              ...(node.namespace?.description === undefined ? {} : { description: node.namespace.description }),
+              tools,
+            }
+      if (node.tool === undefined) return namespace === undefined ? [] : [namespace]
+      if (namespace === undefined) return [node.tool]
+      return [node.tool, namespace]
+    })
+}
+
 function runtime(
   inventory: Inventory,
   executeTool: (name: string, tool: Info, input: unknown) => Effect.Effect<unknown, unknown>,
@@ -191,9 +222,9 @@ function runtime(
   return CodeMode.make<typeof tools>({ tools, ...hooks })
 }
 
-function getNode(root: ToolNode, path: string) {
+function getNode<T>(root: Node<T>, path: string) {
   return path.split(".").reduce((parent, name) => {
-    const child: ToolNode = parent.children.get(name) ?? { children: new Map() }
+    const child: Node<T> = parent.children.get(name) ?? { children: new Map() }
     parent.children.set(name, child)
     return child
   }, root)

packages/core/src/location-mutation.ts

@@ -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],
 })

packages/core/src/location.ts

@@ -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,
       })
     }),
   )

packages/core/src/plugin.ts

@@ -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" },

packages/core/src/plugin/instance.ts

@@ -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 }))
 }

packages/core/src/plugin/internal.ts

@@ -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)),
       }),
     )

packages/core/src/plugin/module.ts

@@ -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) {

packages/core/src/plugin/sdk.ts

@@ -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()],
     })

packages/core/src/plugin/skill.ts

@@ -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()
 })
 

packages/core/src/plugin/supervisor-service.ts

@@ -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>
 }
 

packages/core/src/plugin/supervisor.ts

@@ -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 })

packages/core/src/plugin/update.ts

@@ -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] })

packages/core/src/plugin/vcs/git.ts

@@ -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

packages/core/src/plugin/vcs/hg.ts

@@ -24,7 +24,6 @@ import {
 
 export const Plugin = define({
   id: "opencode.vcs.hg",
-  vcs: { id: "hg", markers: [".hg"] },
   effect: Effect.fn("VcsHgPlugin")(function* (ctx) {
     const location = yield* Location.Service
     if (location.vcs?.type !== "hg") return

packages/core/src/project.ts

@@ -13,7 +13,6 @@ import { Git } from "./git.js"
 import { AppProcess } from "@opencode-ai/util/process"
 import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
 import { Hash } from "@opencode-ai/util/hash"
-import { ProjectMarkers } from "./project/markers.js"
 import { ProjectSchema } from "./project/schema.js"
 import { ProjectTable, upsertProject } from "./project/sql.js"
 import { WorktreeTable } from "./worktree/sql.js"
@@ -44,7 +43,6 @@ export interface Resolved {
   // This checkout's main directory; the stored project canonical may be another clone.
   readonly canonical: AbsolutePath
   readonly vcs?: Vcs
-  readonly vcsBackend?: string
 }
 
 // Keep this filesystem-only; permission checks use it and should not execute VCS commands.
@@ -98,7 +96,6 @@ const layer = Layer.effect(
   Effect.gen(function* () {
     const fs = yield* FSUtil.Service
     const git = yield* Git.Service
-    const markers = yield* ProjectMarkers.Service
     const proc = yield* AppProcess.Service
     const bus = yield* Bus.Service
     const db = (yield* Database.Service).db
@@ -172,7 +169,7 @@ const layer = Layer.effect(
               if (candidate.id === item.projectID) return false
               if (!FSUtil.contains(directory, candidate.directory)) return false
               const found = yield* fs
-                .up({ targets: [...markers.targets()], start: candidate.directory, stop: directory, mode: "first" })
+                .up({ targets: [".git", ".hg"], start: candidate.directory, stop: directory, mode: "first" })
                 .pipe(Effect.orElseSucceed(() => []))
               if (!found[0]) return false
               return (yield* fs.resolve(path.dirname(found[0]))) === directory
@@ -318,10 +315,9 @@ const layer = Layer.effect(
 
     const resolve = Effect.fn("Project.resolve")(function* (
       input: AbsolutePath,
-      options?: { readonly discovery?: boolean },
+      _options?: { readonly discovery?: boolean },
     ) {
       const directory = AbsolutePath.make(yield* fs.resolve(input))
-      const marker = yield* markers.discover(directory, options)
       const native = yield* fs.up({ targets: [".git", ".hg"], start: directory, mode: "first" }).pipe(
         Effect.map((matches) => matches[0]),
         Effect.orElseSucceed(() => undefined),
@@ -330,7 +326,7 @@ const layer = Layer.effect(
         native && path.basename(native) === ".git"
           ? yield* git.repo.discover(AbsolutePath.make(path.dirname(native)))
           : undefined
-      if (repo && (!marker || FSUtil.contains(marker.directory, repo.worktree))) {
+      if (repo) {
         const previous = yield* cached(repo.commonDirectory)
         const id = (yield* remote(repo)) ?? previous ?? (yield* rootCommit(repo))
         const canonical =
@@ -346,27 +342,14 @@ const layer = Layer.effect(
           directory: repo.worktree,
           canonical,
           vcs: { type: "git" as const, store: repo.commonDirectory },
-          ...(marker?.directory === repo.worktree && marker.type !== "git" ? { vcsBackend: marker.type } : {}),
         })
       }
 
       const hg = native && path.basename(native) === ".hg" ? yield* hgDiscover(AbsolutePath.make(native)) : undefined
-      if (hg && (!marker || FSUtil.contains(marker.directory, hg.directory))) {
+      if (hg) {
         return yield* persist({
           ...hg,
           canonical: hg.directory,
-          ...(marker?.directory === hg.directory && marker.type !== "hg" ? { vcsBackend: marker.type } : {}),
-        })
-      }
-
-      if (marker) {
-        const previous = yield* cached(marker.marker)
-        return yield* persist({
-          previous,
-          id: previous ?? ID.make(Hash.fast(`vcs-repository:${marker.type}:${marker.marker}`)),
-          directory: marker.directory,
-          canonical: marker.directory,
-          vcs: { type: marker.type, store: marker.marker },
         })
       }
 
@@ -385,5 +368,5 @@ const layer = Layer.effect(
 export const node = makeGlobalNode({
   service: Service,
   layer: layer,
-  deps: [Bus.node, Database.node, FSUtil.node, Git.node, ProjectMarkers.node, AppProcess.node],
+  deps: [Bus.node, Database.node, FSUtil.node, Git.node, AppProcess.node],
 })

packages/core/src/project/markers.ts

@@ -1,191 +0,0 @@
-export * as ProjectMarkers from "./markers.js"
-
-import { FSUtil } from "@opencode-ai/util/fs-util"
-import { Global } from "@opencode-ai/util/global"
-import { Npm } from "@opencode-ai/util/npm"
-import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
-import { Context, Effect, Layer, Option } from "effect"
-import { parse, type ParseError } from "jsonc-parser"
-import path from "path"
-import { fileURLToPath } from "url"
-import type { ConfigPluginSource } from "../config/plugin/source.js"
-import type { Versioned } from "../plugin.js"
-import { PluginModule } from "../plugin/module.js"
-import { PluginSourceDirectory } from "../plugin/source-directory.js"
-import { SdkPlugins } from "../plugin/sdk.js"
-import { AbsolutePath } from "../schema.js"
-
-export interface Match {
-  readonly type: string
-  readonly directory: AbsolutePath
-  readonly marker: AbsolutePath
-}
-
-export interface Interface {
-  readonly discover: (
-    directory: AbsolutePath,
-    options?: { readonly discovery?: boolean },
-  ) => Effect.Effect<Match | undefined>
-  readonly targets: () => readonly string[]
-}
-
-export class Service extends Context.Service<Service, Interface>()("@opencode/ProjectMarkers") {}
-
-const layer = Layer.effect(
-  Service,
-  Effect.gen(function* () {
-    const fs = yield* FSUtil.Service
-    const global = yield* Global.Service
-    const npm = yield* Npm.Service
-    const sdk = yield* SdkPlugins.Service
-    const known = new Set([".git", ".hg"])
-    const loaded = new Map<string, Versioned | undefined>()
-
-    // The filesystem half of discovery: walk up for config, scan plugin
-    // directories, and read configured plugin operations. This is the part a
-    // no-discovery caller must skip — it imports plugin modules.
-    const scanOperations = Effect.fnUntraced(function* (directory: AbsolutePath) {
-      const found = yield* fs
-        .up({ targets: [".opencode", "opencode.json", "opencode.jsonc"], start: directory })
-        .pipe(Effect.orElseSucceed(() => []))
-      const roots = [global.config, ...found.filter((value) => path.basename(value) === ".opencode").toReversed()]
-      const files = [
-        ...["opencode.json", "opencode.jsonc"].map((name) => path.join(global.config, name)),
-        ...found.filter((value) => path.basename(value) !== ".opencode").toReversed(),
-        ...roots.slice(1).flatMap((root) => ["opencode.json", "opencode.jsonc"].map((name) => path.join(root, name))),
-      ]
-      const automatic = yield* Effect.forEach(roots, (root) => PluginSourceDirectory.discover(fs, root)).pipe(
-        Effect.map((entries) => entries.flat()),
-      )
-      const configured = yield* Effect.forEach([...new Set(files)], (file) => read(fs, file)).pipe(
-        Effect.map((entries) => entries.flat()),
-      )
-      return yield* Effect.forEach(
-        [
-          ...automatic.map((target): ConfigPluginSource.Operation => ({ type: "add", target, options: {} })),
-          ...configured,
-        ],
-        (operation) => {
-          if (operation.type === "remove" || !path.isAbsolute(operation.target)) return Effect.succeed(operation)
-          return fs.stat(operation.target).pipe(
-            Effect.map((info) => ({
-              ...operation,
-              mtime: Option.getOrElse(info.mtime, () => new Date(0)).getTime(),
-            })),
-            Effect.orElseSucceed(() => operation),
-          )
-        },
-      )
-    })
-
-    const discover = Effect.fn("ProjectMarkers.discover")(function* (
-      directory: AbsolutePath,
-      options?: { readonly discovery?: boolean },
-    ) {
-      // discovery: false skips the config scan and its plugin module loading;
-      // sdk-declared vcs markers are host-explicit, not ambient, so they stay.
-      const operations = options?.discovery === false ? [] : yield* scanOperations(directory)
-      const declarations = new Map<string, { readonly id: string; readonly markers: readonly string[] }>()
-
-      for (const plugin of sdk.all()) {
-        if (!plugin.vcs) continue
-        declarations.set(plugin.id, { id: plugin.vcs.id ?? plugin.id, markers: plugin.vcs.markers })
-      }
-
-      for (const operation of operations) {
-        if (operation.type === "remove") {
-          for (const id of declarations.keys()) {
-            if (
-              operation.target === "*" ||
-              (operation.target.endsWith(".*") ? id.startsWith(operation.target.slice(0, -1)) : operation.target === id)
-            ) {
-              declarations.delete(id)
-            }
-          }
-          continue
-        }
-        if (operation.target === "*" || operation.target.endsWith(".*") || operation.target.startsWith("opencode."))
-          continue
-        const key = JSON.stringify(operation)
-        const plugin = loaded.has(key)
-          ? loaded.get(key)
-          : yield* PluginModule.load(operation).pipe(
-              Effect.provideService(Npm.Service, npm),
-              Effect.catchCause((cause) =>
-                Effect.logDebug("failed to discover plugin repository markers", {
-                  target: operation.target,
-                  cause,
-                }).pipe(Effect.as(undefined)),
-              ),
-              Effect.tap((value) => Effect.sync(() => loaded.set(key, value))),
-            )
-        if (!plugin?.vcs) continue
-        declarations.set(plugin.id, { id: plugin.vcs.id ?? plugin.id, markers: plugin.vcs.markers })
-      }
-
-      const markers = new Map<string, string>()
-      for (const declaration of declarations.values()) {
-        if (!/^[a-z][a-z0-9._-]*$/.test(declaration.id)) continue
-        for (const marker of declaration.markers) {
-          if (!marker || marker === "." || marker === ".." || /[\\/]/.test(marker)) continue
-          known.add(marker)
-          markers.set(marker, declaration.id)
-        }
-      }
-      if (!markers.size) return undefined
-
-      const marker = yield* fs.up({ targets: [...markers.keys()], start: directory, mode: "first" }).pipe(
-        Effect.map((entries) => entries[0]),
-        Effect.orElseSucceed(() => undefined),
-      )
-      if (!marker) return undefined
-      const type = markers.get(path.basename(marker))
-      if (!type) return undefined
-      return {
-        type,
-        directory: AbsolutePath.make(path.dirname(marker)),
-        marker: AbsolutePath.make(marker),
-      } satisfies Match
-    })
-
-    return Service.of({ discover, targets: () => [...known] })
-  }),
-)
-
-function read(fs: FSUtil.Interface, file: string): Effect.Effect<ConfigPluginSource.Operation[]> {
-  return Effect.gen(function* () {
-    const source = yield* fs.readFileStringSafe(file).pipe(Effect.orElseSucceed(() => undefined))
-    if (!source) return []
-    const errors: ParseError[] = []
-    const document: unknown = parse(source, errors, { allowTrailingComma: true })
-    if (errors.length || typeof document !== "object" || document === null || !("plugins" in document)) return []
-    if (!Array.isArray(document.plugins)) return []
-    return document.plugins.flatMap<ConfigPluginSource.Operation>((entry) => {
-      if (typeof entry === "string" && entry.startsWith("-")) {
-        return [{ type: "remove", target: entry.slice(1) }]
-      }
-      if (
-        typeof entry !== "string" &&
-        (typeof entry !== "object" || entry === null || !("package" in entry) || typeof entry.package !== "string")
-      ) {
-        return []
-      }
-      const target = typeof entry === "string" ? entry : entry.package
-      const options =
-        typeof entry !== "string" && "options" in entry && typeof entry.options === "object" && entry.options !== null
-          ? Object.fromEntries(Object.entries(entry.options))
-          : {}
-      if (target.startsWith("file://")) return [{ type: "add", target: fileURLToPath(target), options }]
-      if (target.startsWith("./") || target.startsWith("../")) {
-        return [{ type: "add", target: path.resolve(path.dirname(file), target), options }]
-      }
-      return [{ type: "add", target, options }]
-    })
-  })
-}
-
-export const node = makeGlobalNode({
-  service: Service,
-  layer,
-  deps: [FSUtil.node, Global.node, Npm.node, SdkPlugins.node],
-})

packages/core/src/session/stats.ts

@@ -8,6 +8,7 @@ import { Project } from "@opencode-ai/schema/project"
 import { Provider } from "@opencode-ai/schema/provider"
 import { SessionEvent } from "@opencode-ai/schema/session-event"
 import { ToolMode } from "@opencode-ai/schema/session-stats"
+import { TokenUsage } from "@opencode-ai/schema/token-usage"
 import { Database } from "../database/database.js"
 import { EventTable } from "../event/sql.js"
 import { SessionMessageTable, SessionTable } from "./sql.js"
@@ -341,7 +342,7 @@ export const get = Effect.fn("SessionStats.get")(function* (input: Input = {}) {
     streak: longestStreak(days.map(([date]) => date)),
     activity: days.map(([date, steps]) => ({ date, steps })),
     models: [...models.values()]
-      .sort((a, b) => tokenTotal(b.tokens) - tokenTotal(a.tokens))
+      .sort((a, b) => TokenUsage.total(b.tokens) - TokenUsage.total(a.tokens))
       .map((model) => ({ ...model, cost: Money.USD.make(model.cost) })),
   }
 })
@@ -378,10 +379,6 @@ function addTokens(target: Tokens, source: Tokens) {
   target.cache.write += source.cache.write
 }
 
-function tokenTotal(tokens: Tokens) {
-  return tokens.input + tokens.output + tokens.reasoning + tokens.cache.read + tokens.cache.write
-}
-
 function addToolStatus(
   target: { calls: number; succeeded: number; failed: number; unfinished: number },
   status: string | null,

packages/core/src/vcs.ts

@@ -82,7 +82,7 @@ const layer = Layer.effect(
     })
     const selected = () => {
       const value = state.get()
-      const id = value.selection ?? location.vcsBackend ?? vcs?.type
+      const id = value.selection ?? vcs?.type
       return id ? value.providers.get(id) : undefined
     }
     const protect = <A>(provider: VcsDefinition, operation: string, effect: Effect.Effect<A, unknown>, fallback: A) =>

packages/core/test/codemode.test.ts

@@ -10,7 +10,8 @@ describe("CodeMode", () => {
   it.effect("owns registrations, execute, and catalog materialization", () =>
     Effect.gen(function* () {
       const tools = yield* Tool.Service
-      yield* tools.transform((draft) =>
+      yield* tools.transform((draft) => {
+        draft.namespace({ name: "empty", description: "No tools registered yet" })
         draft.add({
           name: "echo",
           description: "Echo text",
@@ -18,21 +19,27 @@ describe("CodeMode", () => {
           output: Schema.String,
           options: { pinned: true },
           execute: ({ text }) => Effect.succeed({ output: text }),
-        }),
-      )
+        })
+      })
 
       const snapshot = yield* tools.snapshot()
       expect(snapshot.definitions.some((tool) => tool.name === "execute")).toBe(true)
       expect(snapshot.codeModeCatalog).toStrictEqual({
         tools: [
           {
-            path: "echo",
+            type: "tool",
+            name: "echo",
             description: "Echo text",
             signature: "tools.echo(input: {\n  text: string,\n}): Promise<string>",
             pinned: true,
           },
+          {
+            type: "namespace",
+            name: "empty",
+            description: "No tools registered yet",
+            tools: [],
+          },
         ],
-        namespaces: new Map(),
       })
     }).pipe(
       Effect.scoped,

packages/core/test/codemode/catalog.test.ts

@@ -3,7 +3,8 @@ import { CodeModeCatalog } from "@opencode-ai/core/codemode/catalog"
 import { CodeModeInstructions } from "@opencode-ai/core/codemode/instructions"
 
 const entry = (path: string, description: string, signature?: string, pinned = false): CodeModeCatalog.Tool => ({
-  path,
+  type: "tool",
+  name: path,
   description,
   signature: signature ?? `tools.${path}(input: {\n  q: string,\n}): Promise<string>`,
   pinned,
@@ -15,12 +16,12 @@ const lookup = entry(
   "tools.orders.lookup(input: {\n  id: string,\n}): Promise<{\n  id: string,\n  status: string,\n}>",
 )
 
-const render = (tools: ReadonlyArray<CodeModeCatalog.Tool>, budget?: number) =>
+const render = (tools: CodeModeCatalog.Inventory["tools"], budget?: number) =>
   CodeModeInstructions.render(CodeModeCatalog.summarize({ tools }, budget === undefined ? {} : { budget }))
 
 const update = (
-  previous: ReadonlyArray<CodeModeCatalog.Tool>,
-  current: ReadonlyArray<CodeModeCatalog.Tool>,
+  previous: CodeModeCatalog.Inventory["tools"],
+  current: CodeModeCatalog.Inventory["tools"],
   budget?: number,
 ) =>
   CodeModeInstructions.update(
@@ -103,10 +104,10 @@ describe("CodeModeCatalog.summarize", () => {
     const listingCost = Math.round(`  - ${tool.signature} // One`.length / 4)
     const namespaceCost = Math.round(CodeModeCatalog.namespaceLine({ name: "alpha", count: 1, entries: [] }).length / 4)
     const description = "A namespace description that stays visible beyond the available tool budget"
-    const namespaces = new Map([["alpha", { name: "alpha", description }]])
+    const namespace = { type: "namespace" as const, name: "alpha", description, tools: [tool] }
 
     expect(CodeModeCatalog.summarize({ tools: [tool] }, { budget: namespaceCost + listingCost }).shown).toBe(1)
-    const catalog = CodeModeCatalog.summarize({ tools: [tool], namespaces }, { budget: namespaceCost + listingCost })
+    const catalog = CodeModeCatalog.summarize({ tools: [namespace] }, { budget: namespaceCost + listingCost })
     expect(catalog.shown).toBe(0)
     expect(catalog.namespaces[0]?.description).toBe(description)
     expect(CodeModeInstructions.render(catalog)).toContain(`- alpha (1 tool, none shown) // ${description}`)
@@ -136,8 +137,8 @@ describe("CodeModeInstructions.render", () => {
     )
     expect(partial).not.toContain("surrounding top-level agent tools")
     expect(partial).toContain("- search(input: {")
-    expect(partial).toContain("  /**\n   * @integer\n   * @exclusiveMinimum 0\n   */\n  limit?: number,")
-    expect(partial).toContain("  /**\n   * @integer\n   * @minimum 0\n   */\n  offset?: number,")
+    expect(partial).toContain("  /** @integer @exclusiveMinimum 0 */\n  limit?: number,")
+    expect(partial).toContain("  /** @integer @minimum 0 */\n  offset?: number,")
     expect(partial).not.toContain("tools.orders.lookup(input:")
   })
 
@@ -209,12 +210,10 @@ describe("CodeModeInstructions.update", () => {
 
   test("restates namespace descriptions when they change", () => {
     const previous = CodeModeCatalog.summarize({
-      tools: [echo],
-      namespaces: new Map([["notes", { name: "notes", description: "Old description" }]]),
+      tools: [{ type: "namespace", name: "notes", description: "Old description", tools: [echo] }],
     })
     const current = CodeModeCatalog.summarize({
-      tools: [echo],
-      namespaces: new Map([["notes", { name: "notes", description: "New description" }]]),
+      tools: [{ type: "namespace", name: "notes", description: "New description", tools: [echo] }],
     })
     const text = CodeModeInstructions.update(previous, current)
     expect(text).toContain("This catalog supersedes the previous Code Mode tool catalog.")

packages/core/test/codemode/instructions.test.ts

@@ -10,13 +10,15 @@ import { it } from "../lib/effect"
 import { readInitial, readUpdate } from "../lib/instructions"
 
 const echo: CodeModeCatalog.Tool = {
-  path: "notes.echo",
+  type: "tool",
+  name: "notes.echo",
   description: "Echo text",
   signature: "tools.notes.echo(input: {\n  text: string,\n}): Promise<string>",
 }
 
 const lookup: CodeModeCatalog.Tool = {
-  path: "orders.lookup",
+  type: "tool",
+  name: "orders.lookup",
   description: "Look up an order",
   signature: "tools.orders.lookup(input: {\n  id: string,\n}): Promise<unknown>",
 }

packages/core/test/config/plugin.test.ts

@@ -20,7 +20,7 @@ import { PluginSupervisor } from "@opencode-ai/core/plugin/supervisor"
 import { Model } from "@opencode-ai/core/model"
 import { Provider } from "@opencode-ai/core/provider"
 import { AbsolutePath } from "@opencode-ai/core/schema"
-import { Effect, Fiber, Layer, Logger, Schedule, Stream } from "effect"
+import { Effect, Fiber, Layer, Logger, Option, Schedule, Stream } from "effect"
 import { Database } from "../../src/database/database"
 import { tmpdir } from "../fixture/tmpdir"
 import { tempGlobalLayer } from "../fixture/global"
@@ -37,38 +37,79 @@ const staticIt = testEffect(
     Global.node.replace(tempGlobalLayer),
   ]),
 )
-const refreshNpm = makeGlobalNode({
+const outdatedNpm = makeGlobalNode({
   service: Npm.Service,
   layer: Layer.effect(
     Npm.Service,
     Effect.gen(function* () {
       const global = yield* Global.Service
-      const directory = path.join(global.tmp, "background-refresh-plugin")
-      const installed = { directory, entrypoint: pathToFileURL(path.join(directory, "index.js")).href }
+      const directory = path.join(global.tmp, "outdated-plugin")
+      let version = "1.0.0"
+      const installed = () => ({
+        directory,
+        entrypoint: pathToFileURL(path.join(directory, "index.js")).href,
+        version,
+        revision: version,
+      })
+      yield* Effect.promise(async () => {
+        await fs.mkdir(directory, { recursive: true })
+        await Bun.write(path.join(directory, "index.js"), 'export default { id: "outdated-plugin", setup() {} }')
+      })
       return Npm.Service.of({
-        add: (_pkg, options) =>
-          options?.refresh
-            ? Effect.gen(function* () {
-                yield* Effect.promise(() => Bun.write(path.join(directory, "refresh-requested"), ""))
-                yield* waitForFile(path.join(directory, "refresh-release")).pipe(Effect.orDie)
-                yield* Effect.promise(() => Bun.write(path.join(directory, "refresh-finished"), ""))
-                return installed
-              })
-            : Effect.succeed(installed),
-        resolve: () => Effect.succeed(installed),
+        add: () => Effect.sync(installed),
+        resolve: () => Effect.sync(installed),
+        check: () => Effect.sync(() => version === "1.0.0"),
+        update: () => Effect.sync(() => (version = "1.1.0")).pipe(Effect.map(installed)),
         which: () => Effect.succeed(undefined),
       })
     }),
   ),
   deps: [Global.node],
 })
-const refreshIt = testEffect(
+const updateIt = testEffect(
   AppNodeBuilder.build(
     LayerNode.group([Database.node, Bus.node, SdkPlugins.node, LocationServiceMap.node, Global.node]),
-    [Global.node.replace(tempGlobalLayer), Npm.node.replace(refreshNpm)],
+    [Global.node.replace(tempGlobalLayer), Npm.node.replace(outdatedNpm)],
+  ),
+)
+const coldNpm = makeGlobalNode({
+  service: Npm.Service,
+  layer: Layer.effect(
+    Npm.Service,
+    Effect.gen(function* () {
+      const global = yield* Global.Service
+      const directory = path.join(global.tmp, "cold-plugin")
+      const started = path.join(directory, "started")
+      const release = path.join(directory, "release")
+      const entry = { directory, entrypoint: pathToFileURL(path.join(directory, "index.js")).href, revision: "1" }
+      let installed = false
+      yield* Effect.promise(async () => {
+        await fs.mkdir(directory, { recursive: true })
+        await Bun.write(path.join(directory, "index.js"), 'export default { id: "cold-plugin", setup() {} }')
+      })
+      return Npm.Service.of({
+        add: () =>
+          Effect.gen(function* () {
+            yield* Effect.promise(() => Bun.write(started, ""))
+            yield* waitForFile(release).pipe(Effect.orDie)
+            installed = true
+            return entry
+          }),
+        resolve: () => Effect.sync(() => (installed ? entry : { directory })),
+        check: () => Effect.succeed(false),
+        update: () => Effect.succeed(entry),
+        which: () => Effect.succeed(undefined),
+      })
+    }),
+  ),
+  deps: [Global.node],
+})
+const coldIt = testEffect(
+  AppNodeBuilder.build(
+    LayerNode.group([Database.node, Bus.node, SdkPlugins.node, LocationServiceMap.node, Global.node]),
+    [Global.node.replace(tempGlobalLayer), Npm.node.replace(coldNpm)],
   ),
 )
-
 describe("PluginSupervisor config", () => {
   it.live("applies selectors in order", () =>
     withLocation(
@@ -463,46 +504,40 @@ describe("PluginSupervisor config", () => {
     }),
   )
 
-  refreshIt.live("refreshes active package plugins after setup without blocking flush", () =>
-    Effect.gen(function* () {
-      const global = yield* Global.Service
-      const directory = path.join(global.tmp, "background-refresh-plugin")
-      const activated = path.join(directory, "activated")
-      const release = path.join(directory, "release")
-      const refreshed = path.join(directory, "refresh-requested")
-      const refreshRelease = path.join(directory, "refresh-release")
-      const refreshFinished = path.join(directory, "refresh-finished")
-      yield* Effect.promise(async () => {
-        await fs.mkdir(directory, { recursive: true })
-        await fs.writeFile(
-          path.join(directory, "index.js"),
-          `export default {
-            id: "background-refresh-plugin",
-            async setup() {
-              await Bun.write(${JSON.stringify(activated)}, "")
-              while (!(await Bun.file(${JSON.stringify(release)}).exists())) await Bun.sleep(10)
-            },
-          }`,
+  updateIt.live("marks active package plugins as outdated after a background check", () =>
+    withLocation(
+      { plugins: ["outdated-plugin"] },
+      Effect.gen(function* () {
+        yield* ready()
+        const plugins = yield* Plugin.Service
+        const source = yield* Effect.suspend(() => plugins.list()).pipe(
+          Effect.map((items) => items.find((item) => item.id === "outdated-plugin")?.source),
+          Effect.filterOrFail((source) => source?.type === "package" && source.outdated === true),
+          Effect.retry(Schedule.spaced("10 millis")),
+          Effect.timeout("2 seconds"),
         )
-      })
-
-      yield* withLocation(
-        { plugins: ["background-refresh-plugin"] },
-        Effect.gen(function* () {
-          yield* waitForFile(activated)
-          yield* Effect.sleep("100 millis")
-          expect(yield* Effect.promise(() => Bun.file(refreshed).exists())).toBeFalse()
-          yield* Effect.promise(() => Bun.write(release, ""))
-          yield* waitForFile(refreshed)
-          yield* ready().pipe(Effect.timeout("2 seconds"))
-          yield* Effect.promise(() => Bun.write(refreshRelease, ""))
-          yield* waitForFile(refreshFinished)
-          const plugins = yield* Plugin.Service
-          expect((yield* plugins.list()).map((plugin) => String(plugin.id))).toContain("background-refresh-plugin")
-        }),
-      )
-    }),
+        expect(source).toEqual({ type: "package", target: "outdated-plugin", version: "1.0.0", outdated: true })
+      }),
+    ),
   )
+
+  coldIt.live("activates available plugins before a missing package finishes installing", () =>
+    withLocation(
+      { plugins: ["cold-plugin"] },
+      Effect.gen(function* () {
+        const global = yield* Global.Service
+        yield* waitForFile(path.join(global.tmp, "cold-plugin", "started"))
+        const plugins = yield* Plugin.Service
+        expect((yield* plugins.list()).map((plugin) => String(plugin.id))).toContain("opencode.provider.openai")
+        const supervisor = yield* PluginSupervisor.Service
+        expect(Option.isNone(yield* supervisor.flush.pipe(Effect.timeoutOption("20 millis")))).toBeTrue()
+        yield* Effect.promise(() => Bun.write(path.join(global.tmp, "cold-plugin", "release"), ""))
+        yield* supervisor.flush.pipe(Effect.timeout("2 seconds"))
+        expect((yield* plugins.list()).map((plugin) => String(plugin.id))).toContain("cold-plugin")
+      }),
+    ),
+  )
+
 })
 
 const ready = Effect.fnUntraced(function* () {

packages/core/test/fixture/prompt-location.ts

@@ -30,7 +30,9 @@ export const promptLocationNode = makeGlobalNode({
                   replacements: [Bus.node.replace(Layer.succeed(Bus.Service, bus))],
                 }),
                 Layer.succeed(FSUtil.Service, fs),
-                Layer.succeed(PluginSupervisor.Service, { flush: Effect.void }),
+                Layer.succeed(PluginSupervisor.Service, {
+                  flush: Effect.void,
+                }),
                 Layer.mock(Reference.Service, { refresh: () => Effect.void }),
               ),
             ),

packages/core/test/lib/tool.ts

@@ -1,4 +1,5 @@
 import { Agent } from "@opencode-ai/core/agent"
+import { CodeModeCatalog } from "@opencode-ai/core/codemode/catalog"
 import type { Permission } from "@opencode-ai/core/permission"
 import { SessionMessage } from "@opencode-ai/core/session/message"
 import { toSessionError } from "@opencode-ai/core/session/to-session-error"
@@ -16,6 +17,9 @@ export const toolIdentity = {
 export const toolDefinitions = (registry: Tool.Interface, permissions?: Permission.Ruleset) =>
   registry.snapshot(permissions).pipe(Effect.map((toolSet) => toolSet.definitions))
 
+export const codeModeListings = (catalog: CodeModeCatalog.Inventory) =>
+  CodeModeCatalog.summarize(catalog, { budget: Infinity }).namespaces.flatMap((namespace) => namespace.entries)
+
 export function waitForTool(registry: Tool.Interface, name: string, remaining = 1000): Effect.Effect<void, Error> {
   return Effect.gen(function* () {
     if ((yield* toolDefinitions(registry)).some((tool) => tool.name === name)) return
@@ -35,7 +39,8 @@ export function waitForCodeModeTool(
 ): Effect.Effect<Tool.Snapshot, Error> {
   return Effect.gen(function* () {
     const toolSet = yield* registry.snapshot()
-    if (toolSet.codeModeCatalog?.tools.some((tool) => tool.path === path)) return toolSet
+    if (toolSet.codeModeCatalog && codeModeListings(toolSet.codeModeCatalog).some((tool) => tool.path === path))
+      return toolSet
     if (remaining === 0) {
       return yield* Effect.fail(new Error(`Timed out waiting for Code Mode tool: ${path}`))
     }

packages/core/test/location-layer.test.ts

@@ -940,7 +940,7 @@ describe("LocationServiceMap", () => {
                 })
                 .pipe(Effect.asVoid),
           })
-          yield* plugins.activate([{ ...reviewer, version: "1" }])
+          yield* plugins.activate([{ ...reviewer, revision: "1" }])
 
           const agents = yield* Agent.Service
           expect(yield* agents.get(Agent.ID.make("reviewer"))).toMatchObject({

packages/core/test/mcp.test.ts

@@ -46,7 +46,7 @@ import { imagePassthrough } from "./lib/image"
 import { location } from "./fixture/location"
 import { tmpdirScoped } from "./fixture/tmpdir"
 import { hostEnvironmentLayer, recordingEnvironmentLayer } from "./fixture/environment"
-import { executeTool, toolDefinitions, toolIdentity, waitForTool } from "./lib/tool"
+import { codeModeListings, executeTool, toolDefinitions, toolIdentity, waitForTool } from "./lib/tool"
 
 let assertion: Deferred.Deferred<Permission.AssertInput> | undefined
 let decision: Effect.Effect<void, Permission.Error> = Effect.void
@@ -1764,7 +1764,7 @@ it.effect("advertises MCP output schemas to Code Mode", () =>
       "direct_media",
       "execute",
     ])
-    expect(toolSet.codeModeCatalog?.tools.find((tool) => tool.path === "demo.search")?.signature).toContain(
+    expect(codeModeListings(toolSet.codeModeCatalog!).find((tool) => tool.path === "demo.search")?.line).toContain(
       "ok: boolean",
     )
     expect(execute?.description).not.toContain("tools.demo.search")
@@ -1784,7 +1784,7 @@ it.effect("forwards the invoking session through direct and Code Mode MCP tools"
     expect(toolSet.definitions.find((tool) => tool.name === "direct_lookup")?.inputSchema).not.toHaveProperty(
       "properties.sessionID",
     )
-    expect(toolSet.codeModeCatalog?.tools.find((tool) => tool.path === "demo.search")?.signature).not.toContain(
+    expect(codeModeListings(toolSet.codeModeCatalog!).find((tool) => tool.path === "demo.search")?.line).not.toContain(
       "sessionID",
     )
 
@@ -1830,7 +1830,7 @@ it.effect("returns content-only MCP results through Code Mode", () =>
     yield* registration.flush
     const toolSet = yield* registry.snapshot()
 
-    expect(toolSet.codeModeCatalog?.tools.some((tool) => tool.path === "demo.status")).toBe(true)
+    expect(codeModeListings(toolSet.codeModeCatalog!).some((tool) => tool.path === "demo.status")).toBe(true)
 
     const execution = yield* toolSet.execute({
       sessionID: Session.ID.make("ses_mcp_content_only"),
@@ -1916,7 +1916,7 @@ it.effect("waits for permission before calling an MCP tool", () =>
     const registration = yield* McpTool.Service
     yield* registration.flush
     const toolSet = yield* registry.snapshot()
-    expect(toolSet.codeModeCatalog?.tools.some((tool) => tool.path === "demo.search")).toBe(true)
+    expect(codeModeListings(toolSet.codeModeCatalog!).some((tool) => tool.path === "demo.search")).toBe(true)
 
     const fiber = yield* toolSet
       .execute({
@@ -1960,7 +1960,7 @@ it.effect("does not call MCP when permission is blocked", () =>
     const registration = yield* McpTool.Service
     yield* registration.flush
     const toolSet = yield* registry.snapshot()
-    expect(toolSet.codeModeCatalog?.tools.some((tool) => tool.path === "demo.search")).toBe(true)
+    expect(codeModeListings(toolSet.codeModeCatalog!).some((tool) => tool.path === "demo.search")).toBe(true)
 
     const execution = yield* toolSet.execute({
       sessionID: Session.ID.make("ses_mcp_blocked"),

packages/core/test/npm.test.ts

@@ -55,6 +55,58 @@ async function createGitFixture(directory: string) {
   return { repository, commit }
 }
 
+async function createRegistryFixture(directory: string) {
+  const tarballs = new Map<string, Uint8Array>()
+  for (const version of ["1.0.0", "1.1.0"]) {
+    const root = path.join(directory, version)
+    await fs.mkdir(path.join(root, "package"), { recursive: true })
+    await writePackage(path.join(root, "package"), {
+      name: "@fixture/registry-plugin",
+      version,
+      exports: "./index.js",
+    })
+    await Bun.write(path.join(root, "package", "index.js"), `export const version = "${version}"\n`)
+    await Bun.$`tar -czf ${path.join(root, "package.tgz")} -C ${root} package`
+    tarballs.set(version, await Bun.file(path.join(root, "package.tgz")).bytes())
+  }
+  const state = { latest: "1.0.0" }
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch(request) {
+      const url = new URL(request.url)
+      if (decodeURIComponent(url.pathname) === "/@fixture/registry-plugin")
+        return Response.json({
+          name: "@fixture/registry-plugin",
+          "dist-tags": { latest: state.latest },
+          versions: Object.fromEntries(
+            [...tarballs.keys()].map((version) => [
+              version,
+              { name: "@fixture/registry-plugin", version, dist: { tarball: `${url.origin}/${version}.tgz` } },
+            ]),
+          ),
+        })
+      const tarball = tarballs.get(url.pathname.slice(1).replace(".tgz", ""))
+      return tarball ? new Response(tarball) : new Response("missing", { status: 404 })
+    },
+  })
+  return {
+    state,
+    async configure(cache: string, spec: string) {
+      const root = path.join(cache, "npm", await Npm.cacheKey(spec))
+      await fs.mkdir(root, { recursive: true })
+      await Bun.write(
+        path.join(root, ".npmrc"),
+        `@fixture:registry=${server.url}\ncache=${path.join(directory, "npm-cache")}\nfetch-retries=0\naudit=false\n`,
+      )
+      return root
+    },
+    async [Symbol.asyncDispose]() {
+      await server.stop(true)
+    },
+  }
+}
+
 describe("Npm.sanitize", () => {
   test("keeps normal scoped package specs unchanged", () => {
     expect(Npm.sanitize("@opencode/acme")).toBe("@opencode/acme")
@@ -98,10 +150,12 @@ describe("Npm.isInstallablePackage", () => {
 })
 
 describe("Npm.cacheKey", () => {
-  test("preserves registry keys and hashes Git specs", async () => {
+  test("canonicalizes registry keys and hashes Git specs", async () => {
     expect(await Npm.cacheKey("@opencode/acme@1.0.0")).toBe(Npm.sanitize("@opencode/acme@1.0.0"))
+    expect(await Npm.cacheKey("plugin")).toBe(Npm.sanitize("plugin@latest"))
+    expect(await Npm.cacheKey("@opencode/acme")).toBe(Npm.sanitize("@opencode/acme@latest"))
     const spec = "git+ssh://git@github.com/acme/plugin.git#main"
-    expect(await Npm.cacheKey(spec)).toMatch(/^git-[a-f0-9]{64}$/)
+    expect(await Npm.cacheKey(spec)).toMatch(/^git-plugin-[a-f0-9]{12}$/)
     expect(await Npm.cacheKey(spec)).toBe(await Npm.cacheKey(spec))
     expect(await Npm.cacheKey(`${spec}-other`)).not.toBe(await Npm.cacheKey(spec))
   })
@@ -114,8 +168,9 @@ describe("Npm.add", () => {
     const directory = path.join(
       tmp.path,
       "cache",
-      "packages",
-      Npm.sanitize(spec),
+      "npm",
+      await Npm.cacheKey(spec),
+      "1000",
       "node_modules",
       "@fixture",
       "provider",
@@ -136,7 +191,7 @@ describe("Npm.add", () => {
   test("falls back to the original spec when parsing fails", async () => {
     await using tmp = await tmpdir()
     const spec = "fixture provider"
-    const directory = path.join(tmp.path, "cache", "packages", Npm.sanitize(spec), "node_modules", spec)
+    const directory = path.join(tmp.path, "cache", "npm", Npm.sanitize(spec), "1000", "node_modules", spec)
     await fs.mkdir(directory, { recursive: true })
     await writePackage(directory, { name: spec, exports: "./index.js" })
     await Bun.write(path.join(directory, "index.js"), "export const fixture = true\n")
@@ -164,7 +219,7 @@ describe("Npm.add", () => {
     await Bun.write(path.join(tmp.path, "fixture-provider", "tui.js"), "export const tui = true\n")
 
     const spec = `fixture-provider@file:${path.join(tmp.path, "fixture-provider")}`
-    await fs.mkdir(path.join(tmp.path, "cache", "packages", Npm.sanitize(spec)), { recursive: true })
+    await fs.mkdir(path.join(tmp.path, "cache", "npm", Npm.sanitize(spec)), { recursive: true })
 
     const entries = await Effect.gen(function* () {
       const npm = yield* Npm.Service
@@ -198,12 +253,14 @@ describe("Npm.add", () => {
       }).pipe(Effect.scoped, Effect.provide(npmLayer(cache)), Effect.runPromise)
 
       expect(entries.added.entrypoint).toEndWith("/index.js")
+      expect(entries.added.version).toBe(fixture.commit)
       expect(entries.cached).toEqual(entries.added)
       expect(entries.resolved).toEqual(entries.added)
       expect(
         await fs.stat(path.join(path.dirname(entries.added.directory), "fixture-dependency", "package.json")),
       ).toBeTruthy()
-      expect(entries.added.directory).toContain(path.join("packages", await Npm.cacheKey(spec), "node_modules"))
+      expect(entries.added.directory).toContain(path.join("npm", await Npm.cacheKey(spec)))
+      expect(entries.added.directory).toContain("node_modules")
     }
   })
 
@@ -223,8 +280,8 @@ describe("Npm.add", () => {
     ).toBeTruthy()
   })
 
-  // Several real Git installs and refreshes exceed Bun's default timeout on Windows.
-  test("refreshes mutable Git packages once per service lifetime and preserves pinned or cached installs", async () => {
+  // Several real Git installs and updates exceed Bun's default timeout on Windows.
+  test("checks and updates mutable Git packages without changing pinned installs", async () => {
     await using tmp = await tmpdir()
     const fixture = await createGitFixture(tmp.path)
     const cache = path.join(tmp.path, "cache")
@@ -232,37 +289,38 @@ describe("Npm.add", () => {
     const mutable = `git+${repository}#fixture-branch`
     const pinned = `git+${repository}#${fixture.commit}`
 
-    const first = await Effect.gen(function* () {
+    const result = await Effect.gen(function* () {
       const npm = yield* Npm.Service
       const mutableEntry = yield* npm.add(mutable)
-      const pinnedEntry = yield* npm.add(pinned, { refresh: true })
+      const pinnedEntry = yield* npm.add(pinned)
       yield* Effect.promise(async () => {
         await Bun.write(path.join(fixture.repository, "index.js"), 'export default { root: "second" }\n')
         await Bun.$`git -C ${fixture.repository} add .`
         await Bun.$`git -C ${fixture.repository} -c user.name=fixture -c user.email=fixture@example.com commit -qm second`
       })
-      yield* npm.add(mutable, { refresh: true })
-      return { mutable: mutableEntry, pinned: pinnedEntry }
-    }).pipe(Effect.scoped, Effect.provide(npmLayer(cache)), Effect.runPromise)
-    expect(await Bun.file(path.join(first.mutable.directory, "index.js")).text()).toContain("root: true")
-    expect(await Bun.file(path.join(first.pinned.directory, "index.js")).text()).toContain("root: true")
-
-    const second = await Effect.gen(function* () {
-      const npm = yield* Npm.Service
+      const before = yield* Effect.promise(() => Bun.file(path.join(mutableEntry.directory, "index.js")).text())
+      const outdated = yield* npm.check(mutable)
+      const pinnedOutdated = yield* npm.check(pinned)
+      const unchanged = yield* Effect.promise(() => Bun.file(path.join(mutableEntry.directory, "index.js")).text())
+      const updated = yield* npm.update(mutable)
+      const pinnedUpdated = yield* npm.update(pinned)
       return {
-        mutable: yield* npm.add(mutable, { refresh: true }),
-        pinned: yield* npm.add(pinned, { refresh: true }),
+        before,
+        outdated,
+        pinnedOutdated,
+        unchanged,
+        updated: yield* Effect.promise(() => Bun.file(path.join(updated.directory, "index.js")).text()),
+        pinned: yield* Effect.promise(() => Bun.file(path.join(pinnedUpdated.directory, "index.js")).text()),
+        current: yield* npm.check(mutable),
       }
     }).pipe(Effect.scoped, Effect.provide(npmLayer(cache)), Effect.runPromise)
-    expect(await Bun.file(path.join(second.mutable.directory, "index.js")).text()).toContain('root: "second"')
-    expect(await Bun.file(path.join(second.pinned.directory, "index.js")).text()).toContain("root: true")
-
-    await fs.rename(fixture.repository, `${fixture.repository}-offline`)
-    const offline = await Effect.gen(function* () {
-      const npm = yield* Npm.Service
-      return yield* npm.add(mutable, { refresh: true })
-    }).pipe(Effect.scoped, Effect.provide(npmLayer(cache)), Effect.runPromise)
-    expect(await Bun.file(path.join(offline.directory, "index.js")).text()).toContain('root: "second"')
+    expect(result.before).toContain("root: true")
+    expect(result.outdated).toBeTrue()
+    expect(result.pinnedOutdated).toBeFalse()
+    expect(result.unchanged).toContain("root: true")
+    expect(result.updated).toContain('root: "second"')
+    expect(result.pinned).toContain("root: true")
+    expect(result.current).toBeFalse()
   }, 30_000)
 })
 
@@ -271,7 +329,7 @@ describe("Npm.resolve", () => {
     await using tmp = await tmpdir()
     const cache = path.join(tmp.path, "cache")
     const spec = "fixture-plugin@1.0.0"
-    const directory = path.join(cache, "packages", Npm.sanitize(spec), "node_modules", "fixture-plugin")
+    const directory = path.join(cache, "npm", Npm.sanitize(spec), "1000", "node_modules", "fixture-plugin")
     const missing = await Effect.gen(function* () {
       const npm = yield* Npm.Service
       return yield* npm.resolve(spec, { subpaths: ["tui"] })
@@ -291,5 +349,56 @@ describe("Npm.resolve", () => {
       return yield* npm.resolve(spec, { subpaths: ["tui"] })
     }).pipe(Effect.scoped, Effect.provide(npmLayer(cache)), Effect.runPromise)
     expect(resolved.entrypoint).toEndWith("/tui.js")
+    expect(resolved.version).toBe("1.0.0")
+  })
+})
+
+describe("Npm.check and Npm.update", () => {
+  test("checks registry targets without mutation and explicitly updates mutable targets", async () => {
+    await using tmp = await tmpdir()
+    await using registry = await createRegistryFixture(tmp.path)
+    const cache = path.join(tmp.path, "cache")
+    const mutable = "@fixture/registry-plugin@latest"
+    const pinned = "@fixture/registry-plugin@1.0.0"
+    const root = await registry.configure(cache, mutable)
+    await registry.configure(cache, pinned)
+
+    const result = await Effect.gen(function* () {
+      const npm = yield* Npm.Service
+      const installed = yield* npm.add(mutable)
+      yield* npm.add(pinned)
+      const current = yield* npm.check(mutable)
+      registry.state.latest = "1.1.0"
+      const outdated = yield* npm.check(mutable)
+      const pinnedOutdated = yield* npm.check(pinned)
+      const before = yield* Effect.promise(() => Bun.file(path.join(installed.directory, "index.js")).text())
+      yield* Effect.promise(() => Promise.all([fs.mkdir(path.join(root, "1")), fs.mkdir(path.join(root, "2"))]))
+      const updated = yield* npm.update(mutable)
+      const unchanged = yield* npm.update(mutable)
+      return {
+        current,
+        outdated,
+        pinnedOutdated,
+        before,
+        after: yield* Effect.promise(() => Bun.file(path.join(updated.directory, "index.js")).text()),
+        version: updated.version,
+        changedDirectory: installed.directory !== updated.directory,
+        unchangedDirectory: unchanged.directory === updated.directory,
+        generations: yield* Effect.promise(() => fs.readdir(root)),
+        updated: yield* npm.check(mutable),
+      }
+    }).pipe(Effect.scoped, Effect.provide(npmLayer(cache)), Effect.runPromise)
+
+    expect(result.current).toBeFalse()
+    expect(result.outdated).toBeTrue()
+    expect(result.pinnedOutdated).toBeFalse()
+    expect(result.before).toContain('version = "1.0.0"')
+    expect(result.after).toContain('version = "1.1.0"')
+    expect(result.version).toBe("1.1.0")
+    expect(result.changedDirectory).toBeTrue()
+    expect(result.unchangedDirectory).toBeTrue()
+    expect(result.generations).not.toContain("1")
+    expect(result.generations).not.toContain("2")
+    expect(result.updated).toBeFalse()
   })
 })

packages/core/test/plugin.test.ts

@@ -24,7 +24,7 @@ const it = testEffect(PluginTestLayer)
 
 class Secret extends Context.Service<Secret, string>()("@opencode/test/PluginSecret") {}
 
-const versioned = <R>(plugin: EffectPlugin.Plugin<R>, version = "1") => ({ ...plugin, version })
+const generation = <R>(plugin: EffectPlugin.Plugin<R>, revision = "1") => ({ ...plugin, revision })
 
 describe("Plugin", () => {
   it.effect("routes experimental terminal reads through the runtime cell without wrapping results", () =>
@@ -81,7 +81,7 @@ describe("Plugin", () => {
       const location = yield* Location.Service
       const seen: Location.Info[] = []
       yield* plugins.activate([
-        versioned(
+        generation(
           EffectPlugin.define({
             id: "location-context",
             effect: (ctx) =>
@@ -215,7 +215,7 @@ describe("Plugin", () => {
             .pipe(Effect.asVoid),
       })
 
-      yield* plugins.activate([versioned(provider)])
+      yield* plugins.activate([generation(provider)])
       expect(yield* vcs.info()).toEqual({ branch: { current: "feature" } })
       expect(yield* vcs.branches()).toEqual(["feature"])
 
@@ -224,7 +224,7 @@ describe("Plugin", () => {
     }),
   )
 
-  it.effect("replaces plugins by ID and version", () =>
+  it.effect("replaces plugins by ID and revision", () =>
     Effect.gen(function* () {
       const plugins = yield* Plugin.Service
       const agents = yield* Agent.Service
@@ -250,24 +250,24 @@ describe("Plugin", () => {
               .pipe(Effect.asVoid),
         })
 
-      yield* plugins.activate([versioned(managed(), "1")])
+      yield* plugins.activate([generation(managed(), "1")])
 
       expect((yield* agents.get(Agent.ID.make("configured")))?.description).toBe("first")
 
       description = "second"
-      yield* plugins.activate([versioned(managed(), "2")])
+      yield* plugins.activate([generation(managed(), "2")])
       expect((yield* agents.get(Agent.ID.make("configured")))?.description).toBe("second")
 
       description = "third"
-      yield* plugins.activate([versioned(managed(), "2")])
+      yield* plugins.activate([generation(managed(), "2")])
       expect(updates).toBe(2)
       expect((yield* agents.get(Agent.ID.make("configured")))?.description).toBe("second")
 
       yield* plugins.activate(
-        [versioned(managed(), "2")],
+        [generation(managed(), "2")],
         [
           {
-            source: { type: "package", package: "broken" },
+            source: { type: "package", target: "broken" },
             state: { status: "failed", error: "failed to resolve" },
             features: { server: true },
           },
@@ -288,7 +288,7 @@ describe("Plugin", () => {
       const agents = yield* Agent.Service
       const bus = yield* Bus.Service
       const definitions = ["first", "second"].map((id) =>
-        versioned(
+        generation(
           EffectPlugin.define({
             id,
             effect: (ctx) => ctx.agent.transform((draft) => draft.update(id, () => {})),
@@ -315,17 +315,36 @@ describe("Plugin", () => {
     }),
   )
 
+  it.effect("updates inventory metadata without restarting an unchanged generation", () =>
+    Effect.gen(function* () {
+      const plugins = yield* Plugin.Service
+      let loads = 0
+      const plugin = {
+        id: "metadata",
+        revision: "1",
+        source: { type: "package" as const, target: "fixture" },
+        effect: () => Effect.sync(() => loads++),
+      }
+
+      yield* plugins.activate([plugin])
+      yield* plugins.activate([{ ...plugin, source: { ...plugin.source, outdated: true } }])
+
+      expect(loads).toBe(1)
+      expect((yield* plugins.list())[0]?.source).toEqual({ type: "package", target: "fixture", outdated: true })
+    }),
+  )
+
   it.effect("rejects duplicate IDs before replacing active plugins", () =>
     Effect.gen(function* () {
       const plugins = yield* Plugin.Service
       const active = Plugin.ID.make("active")
       const duplicate = "duplicate"
-      yield* plugins.activate([{ id: active, version: "1", effect: () => Effect.void }])
+      yield* plugins.activate([{ id: active, revision: "1", effect: () => Effect.void }])
 
       const result = yield* plugins
         .activate([
-          { id: duplicate, version: "1", effect: () => Effect.void },
-          { id: duplicate, version: "1", effect: () => Effect.void },
+          { id: duplicate, revision: "1", effect: () => Effect.void },
+          { id: duplicate, revision: "1", effect: () => Effect.void },
         ])
         .pipe(Effect.exit)
 
@@ -340,7 +359,7 @@ describe("Plugin", () => {
     Effect.gen(function* () {
       const plugins = yield* Plugin.Service
       yield* plugins.activate([
-        { id: "rpc-plugin", version: "1", features: { rpc: true }, effect: () => Effect.void },
+        { id: "rpc-plugin", revision: "1", features: { rpc: true }, effect: () => Effect.void },
       ])
 
       expect(yield* plugins.list()).toEqual([
@@ -378,7 +397,7 @@ describe("Plugin", () => {
         },
       })
 
-      yield* plugins.activate([versioned(good), versioned(bad)])
+      yield* plugins.activate([generation(good), generation(bad)])
       expect(yield* plugins.list()).toEqual([
         {
           id: Plugin.ID.make("good"),
@@ -396,7 +415,7 @@ describe("Plugin", () => {
       expect((yield* agents.get(Agent.ID.make("configured")))?.description).toBe("loaded")
 
       fail = false
-      yield* plugins.activate([versioned(good), versioned(bad, "2")])
+      yield* plugins.activate([generation(good), generation(bad, "2")])
       expect(yield* plugins.list()).toEqual([
         {
           id: Plugin.ID.make("good"),
@@ -422,7 +441,7 @@ describe("Plugin", () => {
       yield* plugins.activate([
         {
           id: "partial-tools",
-          version: "1",
+          revision: "1",
           effect: (ctx) =>
             Effect.gen(function* () {
               yield* ctx.tool.transform((draft) => {
@@ -488,8 +507,8 @@ describe("Plugin", () => {
           }),
       })
 
-      yield* plugins.activate([versioned(previous)])
-      yield* plugins.activate([versioned(replacement, "2")])
+      yield* plugins.activate([generation(previous)])
+      yield* plugins.activate([generation(replacement, "2")])
 
       expect(yield* plugins.list()).toEqual([
         {
@@ -527,8 +546,8 @@ describe("Plugin", () => {
         effect: () => Effect.die(new Error("replacement failed")),
       })
 
-      yield* plugins.activate([versioned(previous)])
-      yield* plugins.activate([versioned(replacement, "2")])
+      yield* plugins.activate([generation(previous)])
+      yield* plugins.activate([generation(replacement, "2")])
 
       expect(yield* plugins.list()).toEqual([
         {
@@ -549,7 +568,7 @@ describe("Plugin", () => {
       yield* plugins.activate(
         ["first", "second"].map((id) => ({
           id,
-          version: "1",
+          revision: "1",
           effect: () => Effect.addFinalizer(() => Effect.sync(() => closed.push(id))),
         })),
       )
@@ -573,7 +592,7 @@ describe("Plugin", () => {
           ),
       })
 
-      yield* plugins.activate([versioned(plugin)]).pipe(Effect.provideService(Secret, "secret"))
+      yield* plugins.activate([generation(plugin)]).pipe(Effect.provideService(Secret, "secret"))
 
       expect(visible).toBe(false)
     }),
@@ -586,7 +605,7 @@ describe("Plugin", () => {
       yield* plugins.activate(
         ["a", "a:b", "雪"].map((id) => ({
           id,
-          version: "1",
+          revision: "1",
           effect: (context: EffectPlugin.Context) => Effect.sync(() => storage.set(id, context.storage)),
         })),
       )
@@ -648,7 +667,7 @@ describe("Plugin", () => {
             .pipe(Effect.orDie),
       })
 
-      yield* plugins.activate([versioned(plugin)])
+      yield* plugins.activate([generation(plugin)])
       expect((yield* registry.snapshot()).definitions.map((tool) => tool.name)).toContain("plugin_tool")
 
       yield* plugins.activate([])
@@ -680,7 +699,7 @@ describe("Plugin", () => {
             .pipe(Effect.orDie),
       })
 
-      yield* plugins.activate([versioned(plugin)])
+      yield* plugins.activate([generation(plugin)])
 
       expect((yield* registry.snapshot()).definitions.map((tool) => tool.name)).toEqual([
         "context7_look_up",
@@ -759,7 +778,7 @@ describe("Plugin", () => {
           }),
       })
 
-      yield* plugins.activate([versioned(plugin)])
+      yield* plugins.activate([generation(plugin)])
 
       const toolSet = yield* registry.snapshot()
       const execution = yield* toolSet.execute({
@@ -817,7 +836,7 @@ describe("Plugin", () => {
           }),
       })
 
-      yield* plugins.activate([versioned(plugin)])
+      yield* plugins.activate([generation(plugin)])
 
       const toolSet = yield* registry.snapshot()
       const failure = yield* toolSet

packages/core/test/plugin/fixture.ts

@@ -38,6 +38,8 @@ const npmLayer = Layer.succeed(
   Npm.Service.of({
     add: () => Effect.succeed({ directory: "", entrypoint: undefined }),
     resolve: () => Effect.succeed({ directory: "", entrypoint: undefined }),
+    check: () => Effect.succeed(false),
+    update: () => Effect.succeed({ directory: "", entrypoint: undefined }),
     which: () => Effect.undefined,
   }),
 )

packages/core/test/plugin/module.test.ts

@@ -15,13 +15,15 @@ test("loads cached plugin packages without requesting a refresh", async () => {
         add: (_pkg, options) =>
           Effect.sync(() => {
             calls.push(options)
-            return { directory: path.dirname(entrypoint), entrypoint: pathToFileURL(entrypoint).href }
+            return { directory: path.dirname(entrypoint), entrypoint: pathToFileURL(entrypoint).href, version: "1.2.3" }
           }),
         resolve: (_pkg, options) =>
           Effect.sync(() => {
             calls.push(options)
             return { directory: path.dirname(entrypoint), entrypoint: pathToFileURL(entrypoint).href }
           }),
+        check: () => Effect.die(new Error("Unexpected check")),
+        update: () => Effect.die(new Error("Unexpected update")),
         which: () => Effect.die(new Error("Unexpected which")),
       }),
     ),
@@ -30,5 +32,6 @@ test("loads cached plugin packages without requesting a refresh", async () => {
 
   expect(plugin.id).toBe("config-effect-plugin")
   expect(plugin.features).toEqual({ tui: true, rpc: true })
+  expect(plugin.source).toEqual({ type: "package", target: "fixture-plugin", version: "1.2.3" })
   expect(calls).toEqual([{ subpaths: ["server", ""] }, { subpaths: ["tui"] }, { subpaths: ["rpc"] }])
 })

packages/core/test/plugin/promise.test.ts

@@ -18,6 +18,7 @@ import { Tool } from "@opencode-ai/core/tool"
 import { Provider } from "@opencode-ai/core/provider"
 import { Project } from "@opencode-ai/core/project"
 import { Workspace } from "@opencode-ai/core/workspace"
+import { codeModeListings } from "../lib/tool"
 import { AbsolutePath } from "@opencode-ai/core/schema"
 import { define } from "@opencode-ai/plugin/promise/plugin"
 import type { Info } from "@opencode-ai/plugin/promise/tool"
@@ -167,7 +168,7 @@ describe("fromPromise", () => {
         }),
       )
 
-      yield* plugins.activate([{ ...adapted, version: "1" }])
+      yield* plugins.activate([{ ...adapted, revision: "1" }])
     }),
   )
 
@@ -981,7 +982,7 @@ describe("fromPromise", () => {
 
       const snapshot = yield* registry.snapshot()
       expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["execute"])
-      expect(snapshot.codeModeCatalog?.tools.map((tool) => tool.path)).toEqual(["acme.hello"])
+      expect(codeModeListings(snapshot.codeModeCatalog!).map((tool) => tool.path)).toEqual(["acme.hello"])
       expect(original.definitions.map((tool) => tool.name)).toEqual(["acme_hello", "execute"])
       expect(
         yield* snapshot.execute({

packages/core/test/plugin/provider-dynamic.test.ts

@@ -24,6 +24,8 @@ function npmEntrypoint(entrypoint?: string) {
   return Npm.Service.of({
     add: () => Effect.succeed({ directory: "", entrypoint }),
     resolve: () => Effect.succeed({ directory: "", entrypoint }),
+    check: () => Effect.succeed(false),
+    update: () => Effect.succeed({ directory: "", entrypoint }),
     which: () => Effect.undefined,
   })
 }

packages/core/test/plugin/provider-sap-ai-core.test.ts

@@ -16,6 +16,8 @@ const it = testEffect(PluginTestLayer)
 const npm = Npm.Service.of({
   add: () => Effect.succeed({ directory: "", entrypoint: undefined }),
   resolve: () => Effect.succeed({ directory: "", entrypoint: undefined }),
+  check: () => Effect.succeed(false),
+  update: () => Effect.succeed({ directory: "", entrypoint: undefined }),
   which: () => Effect.undefined,
 })
 

packages/core/test/plugin/rpc-effect.test.ts

@@ -39,7 +39,7 @@ it.effect("Effect plugins register, call, and publish RPCs independently of plug
     yield* plugins.activate([
       {
         id: "implementer",
-        version: "1",
+        revision: "1",
         effect: (ctx) =>
           Effect.gen(function* () {
             const registration = yield* ctx.rpc.register(Echo, {
@@ -51,7 +51,7 @@ it.effect("Effect plugins register, call, and publish RPCs independently of plug
       },
       {
         id: "consumer",
-        version: "1",
+        revision: "1",
         effect: (ctx) =>
           Effect.gen(function* () {
             expect(yield* ctx.rpc(Echo).echo("hello")).toBe("hello!")
@@ -78,7 +78,7 @@ it.effect("failed plugin setup removes RPC overrides and restores the previous i
     yield* plugins.activate([
       {
         id: "implementer",
-        version: "1",
+        revision: "1",
         effect: (ctx) =>
           ctx.rpc
             .register(Echo, {
@@ -91,7 +91,7 @@ it.effect("failed plugin setup removes RPC overrides and restores the previous i
     yield* plugins.activate([
       {
         id: "implementer",
-        version: "2",
+        revision: "2",
         effect: (ctx) =>
           ctx.rpc
             .register(Echo, {

packages/core/test/plugin/rpc-promise.test.ts

@@ -84,7 +84,7 @@ describe("Promise plugin RPC", () => {
         }),
       )
 
-      yield* plugins.activate([{ ...adapted, version: "1" }])
+      yield* plugins.activate([{ ...adapted, revision: "1" }])
       expect(yield* plugins.list()).toMatchObject([{ id: adapted.id, state: { status: "active" } }])
     }),
   )
@@ -141,7 +141,7 @@ describe("Promise plugin RPC", () => {
         }),
       )
 
-      yield* plugins.activate([{ ...adapted, version: "1" }])
+      yield* plugins.activate([{ ...adapted, revision: "1" }])
       expect(yield* plugins.list()).toMatchObject([{ id: adapted.id, state: { status: "active" } }])
     }),
   )
@@ -197,7 +197,7 @@ describe("Promise plugin RPC", () => {
         }),
       )
       yield* plugins
-        .activate([{ ...adapted, version: "1" }])
+        .activate([{ ...adapted, revision: "1" }])
         .pipe(Effect.provideService(Logger.CurrentLoggers, new Set([logger])))
       expect(yield* plugins.list()).toMatchObject([{ id: adapted.id, state: { status: "active" } }])
       yield* plugins.activate([])
@@ -279,7 +279,7 @@ describe("Promise plugin RPC", () => {
         }),
       )
 
-      yield* plugins.activate([{ ...adapted, version: "1" }])
+      yield* plugins.activate([{ ...adapted, revision: "1" }])
       expect(yield* plugins.list()).toMatchObject([{ id: adapted.id, state: { status: "active" } }])
       const active = yield* Effect.promise(() => subscriptions.promise)
       yield* plugins.activate([])

packages/core/test/plugin/skill.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect } from "bun:test"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
-import { ConfigPluginSource } from "@opencode-ai/core/config/plugin/source"
+import { Config } from "@opencode-ai/core/config"
+import { Document, Info } from "@opencode-ai/schema/config"
 import { Effect, Layer, Stream } from "effect"
 import { SkillPlugin } from "@opencode-ai/core/plugin/skill"
 import { Skill } from "@opencode-ai/core/skill"
@@ -8,10 +9,13 @@ import { testEffect } from "../lib/effect"
 import { host } from "./host"
 
 const it = testEffect(AppNodeBuilder.build(Skill.node))
-const sources = (operations: readonly ConfigPluginSource.Operation[] = []) =>
+const config = (plugins: Info["plugins"] = []) =>
   Layer.succeed(
-    ConfigPluginSource.Service,
-    ConfigPluginSource.Service.of({ operations: () => Effect.succeed(operations), changes: () => Stream.never }),
+    Config.Service,
+    Config.Service.of({
+      entries: () => Effect.succeed([new Document({ type: "document", info: new Info({ plugins }) })]),
+      changes: () => Stream.never,
+    }),
   )
 
 describe("SkillPlugin.Plugin", () => {
@@ -27,7 +31,7 @@ describe("SkillPlugin.Plugin", () => {
             reload: skill.reload,
           },
         }),
-      ).pipe(Effect.provide(sources()))
+      ).pipe(Effect.provide(config()))
       const skills = yield* skill.list()
       const report = skills.find((item) => item.id === "report")
 
@@ -67,11 +71,11 @@ describe("SkillPlugin.Plugin", () => {
       expect(report?.content).toContain("- Active plugins: -disabled, local.ts, package-plugin, package-plugin")
     }).pipe(
       Effect.provide(
-        sources([
-          { type: "add", target: "package-plugin", options: {} },
-          { type: "remove", target: "disabled" },
-          { type: "add", target: "local.ts", options: {}, mtime: 1 },
-          { type: "add", target: "package-plugin", options: { enabled: true } },
+        config([
+          "package-plugin",
+          "-disabled",
+          "local.ts",
+          { package: "package-plugin", options: { enabled: true } },
         ]),
       ),
     ),

packages/core/test/plugin/update.test.ts

@@ -0,0 +1,51 @@
+import { expect } from "bun:test"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { PluginUpdate } from "@opencode-ai/core/plugin/update"
+import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
+import { Npm } from "@opencode-ai/util/npm"
+import { Effect, Fiber, Layer, Option, Stream } from "effect"
+import { testEffect } from "../lib/effect"
+
+const checks: string[] = []
+const npm = makeGlobalNode({
+  service: Npm.Service,
+  layer: Layer.succeed(
+    Npm.Service,
+    Npm.Service.of({
+      add: () => Effect.die("unused add"),
+      resolve: () => Effect.die("unused resolve"),
+      check: (target) => Effect.sync(() => checks.push(target)).pipe(Effect.as(true)),
+      update: () => Effect.succeed({ directory: "" }),
+      which: () => Effect.die("unused which"),
+    }),
+  ),
+  deps: [],
+})
+
+const it = testEffect(AppNodeBuilder.build(PluginUpdate.node, [Npm.node.replace(npm)]))
+
+it.effect("caches checks by target", () =>
+  Effect.gen(function* () {
+    checks.length = 0
+    const updates = yield* PluginUpdate.Service
+    const first = yield* updates.check("fixture")
+    const second = yield* updates.check("fixture")
+
+    expect(checks).toEqual(["fixture"])
+    expect(first).toBeTrue()
+    expect(second).toBeTrue()
+  }),
+)
+
+it.effect("publishes successful package updates", () =>
+  Effect.gen(function* () {
+    const updates = yield* PluginUpdate.Service
+    const changed = yield* updates
+      .changes()
+      .pipe(Stream.take(1), Stream.runHead, Effect.forkScoped({ startImmediately: true }))
+
+    yield* updates.update("fixture")
+
+    expect(Option.getOrUndefined(yield* Fiber.join(changed))).toBe("fixture")
+  }),
+)

packages/core/test/project.test.ts

@@ -170,106 +170,6 @@ describe("Project.resolve", () => {
     }),
   )
 
-  it.live("discovers repository markers from automatically loaded plugins", () =>
-    Effect.gen(function* () {
-      const tmp = yield* Effect.acquireRelease(
-        Effect.promise(() => tmpdir()),
-        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-      )
-      yield* Effect.promise(async () => {
-        await fs.mkdir(path.join(tmp.path, ".opencode", "plugins"), { recursive: true })
-        await fs.mkdir(path.join(tmp.path, ".svn"))
-        await fs.mkdir(path.join(tmp.path, "nested", "directory"), { recursive: true })
-        await Bun.write(
-          path.join(tmp.path, ".opencode", "plugins", "svn.ts"),
-          'export default { id: "svn", vcs: { markers: [".svn"] }, setup() {} }',
-        )
-      })
-      const project = yield* Project.Service
-
-      const result = yield* project.resolve(abs(path.join(tmp.path, "nested", "directory")))
-
-      expect(result.directory).toBe(abs(tmp.path))
-      expect(result.canonical).toBe(abs(tmp.path))
-      expect(result.vcs).toEqual({ type: "svn", store: abs(path.join(tmp.path, ".svn")) })
-      expect(result.id).not.toBe(Project.ID.global)
-      expect((yield* project.list()).find((item) => item.id === result.id)?.vcs).toBe("svn")
-    }),
-  )
-
-  it.live("discovers repository markers from configured plugin files", () =>
-    Effect.gen(function* () {
-      const tmp = yield* Effect.acquireRelease(
-        Effect.promise(() => tmpdir()),
-        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-      )
-      yield* Effect.promise(async () => {
-        await fs.mkdir(path.join(tmp.path, ".pijul"))
-        await Bun.write(path.join(tmp.path, "opencode.jsonc"), '{ "plugins": ["./pijul.ts"] }')
-        await Bun.write(
-          path.join(tmp.path, "pijul.ts"),
-          'export default { id: "custom.pijul", vcs: { id: "pijul", markers: [".pijul"] }, setup() {} }',
-        )
-      })
-      const project = yield* Project.Service
-
-      const result = yield* project.resolve(abs(tmp.path))
-
-      expect(result.directory).toBe(abs(tmp.path))
-      expect(result.vcs?.type).toBe("pijul")
-    }),
-  )
-
-  it.live("prefers a nested plugin repository over its parent git repository", () =>
-    Effect.gen(function* () {
-      const tmp = yield* Effect.acquireRelease(
-        Effect.promise(() => tmpdir()),
-        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-      )
-      const nested = path.join(tmp.path, "nested")
-      yield* Effect.promise(async () => {
-        await initRepo(tmp.path, { commit: true })
-        await fs.mkdir(path.join(tmp.path, ".opencode", "plugins"), { recursive: true })
-        await fs.mkdir(path.join(nested, ".svn"), { recursive: true })
-        await Bun.write(
-          path.join(tmp.path, ".opencode", "plugins", "svn.ts"),
-          'export default { id: "svn", vcs: { markers: [".svn"] }, setup() {} }',
-        )
-      })
-      const project = yield* Project.Service
-
-      const result = yield* project.resolve(abs(nested))
-
-      expect(result.directory).toBe(abs(nested))
-      expect(result.vcs?.type).toBe("svn")
-    }),
-  )
-
-  it.live("preserves git identity when a plugin marker shares its repository", () =>
-    Effect.gen(function* () {
-      const tmp = yield* Effect.acquireRelease(
-        Effect.promise(() => tmpdir()),
-        (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-      )
-      yield* Effect.promise(async () => {
-        await initRepo(tmp.path, { commit: true })
-        await fs.mkdir(path.join(tmp.path, ".opencode", "plugins"), { recursive: true })
-        await fs.mkdir(path.join(tmp.path, ".jj"))
-        await Bun.write(
-          path.join(tmp.path, ".opencode", "plugins", "jj.ts"),
-          'export default { id: "jj", vcs: { markers: [".jj"] }, setup() {} }',
-        )
-      })
-      const project = yield* Project.Service
-
-      const result = yield* project.resolve(abs(tmp.path))
-
-      expect(result.id).toBe(Project.ID.make(yield* Effect.promise(() => rootCommit(tmp.path))))
-      expect(result.vcs?.type).toBe("git")
-      expect(result.vcsBackend).toBe("jj")
-    }),
-  )
-
   it.live("repository markers override markerless directory projects", () =>
     Effect.gen(function* () {
       const tmp = yield* Effect.acquireRelease(

packages/core/test/session-generate.test.ts

@@ -118,7 +118,8 @@ const tools = Layer.mock(Tool.Service, {
       codeModeCatalog: {
         tools: [
           {
-            path: "captured.lookup",
+            type: "tool",
+            name: "captured.lookup",
             description: "Captured Code Mode catalog",
             signature: "tools.captured.lookup(input: {}): Promise<string>",
           },

packages/core/test/session-prompt.test.ts

@@ -114,7 +114,9 @@ const locations = (references: Layer.Layer<Reference.Service>) =>
                     }),
                     Layer.succeed(
                       PluginSupervisor.Service,
-                      PluginSupervisor.Service.of({ flush: Effect.sync(() => (ready = true)) }),
+                      PluginSupervisor.Service.of({
+                        flush: Effect.sync(() => (ready = true)),
+                      }),
                     ),
                   ),
                 ),

packages/core/test/session-skill.test.ts

@@ -52,7 +52,9 @@ const locations = makeGlobalNode({
               get: (id) => Effect.succeed(id === info.id ? info : undefined),
               list: () => Effect.succeed([info]),
             }),
-            Layer.succeed(PluginSupervisor.Service, { flush: Effect.void }),
+            Layer.succeed(PluginSupervisor.Service, {
+              flush: Effect.void,
+            }),
             Layer.mock(Reference.Service, { refresh: () => Effect.void }),
           ),
         ),

packages/core/test/tool-registry.test.ts

@@ -14,7 +14,7 @@ import { State } from "@opencode-ai/core/state"
 import { Tool } from "@opencode-ai/core/tool"
 import type { Info } from "@opencode-ai/schema/tool"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
-import { executeTool, toolDefinitions } from "./lib/tool"
+import { codeModeListings, executeTool, toolDefinitions } from "./lib/tool"
 import { Deferred, Effect, Exit, Fiber, Layer, Logger, Schema, SchemaGetter, SchemaIssue, Scope } from "effect"
 import { TestClock } from "effect/testing"
 import { z } from "zod"
@@ -247,7 +247,9 @@ describe("Tool", () => {
       yield* update.dispose
       expect((yield* executeTool(service, call("acme_echo"))).output).toEqual({ text: "refreshed" })
       yield* Scope.close(scope, Exit.void)
-      expect((yield* service.snapshot()).codeModeCatalog?.tools.map((tool) => tool.path)).toEqual(["hidden"])
+      expect(codeModeListings((yield* service.snapshot()).codeModeCatalog!).map((tool) => tool.path)).toEqual([
+        "hidden",
+      ])
 
       yield* service.transform((draft) =>
         draft.update("acme_echo", (tool) => {
@@ -502,7 +504,7 @@ describe("Tool", () => {
 
       const snapshot = yield* service.snapshot()
       expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["execute"])
-      expect(snapshot.codeModeCatalog?.tools.map((tool) => tool.path)).toEqual([
+      expect(codeModeListings(snapshot.codeModeCatalog!).map((tool) => tool.path)).toEqual([
         "-lookup",
         "123",
         "123._private.-tools.2d_get_scene",
@@ -542,7 +544,9 @@ describe("Tool", () => {
 
       const snapshot = yield* service.snapshot()
       expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["first", "execute"])
-      expect(snapshot.codeModeCatalog?.tools.map((tool) => tool.path)).toEqual(["invalid__namespace.second"])
+      expect(codeModeListings(snapshot.codeModeCatalog!).map((tool) => tool.path)).toEqual([
+        "invalid__namespace.second",
+      ])
     }),
   )
 
@@ -560,17 +564,32 @@ describe("Tool", () => {
 
       const snapshot = yield* service.snapshot()
       expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["registry_direct", "execute"])
-      expect(snapshot.codeModeCatalog?.tools.map((tool) => tool.path)).toEqual([
+      expect(codeModeListings(snapshot.codeModeCatalog!).map((tool) => tool.path)).toEqual([
         "legacy.plain",
         "registry.search",
         "registry.search.sales",
       ])
-      expect(snapshot.codeModeCatalog?.namespaces).toEqual(
-        new Map([
-          ["registry", { name: "registry", description: "Package publishing and discovery" }],
-          ["registry.search", { name: "registry.search", description: "Pricing operations" }],
-        ]),
-      )
+      expect(snapshot.codeModeCatalog?.tools).toEqual([
+        {
+          type: "namespace",
+          name: "legacy",
+          tools: [expect.objectContaining({ type: "tool", name: "plain" })],
+        },
+        {
+          type: "namespace",
+          name: "registry",
+          description: "Package publishing and discovery",
+          tools: [
+            expect.objectContaining({ type: "tool", name: "search" }),
+            {
+              type: "namespace",
+              name: "search",
+              description: "Pricing operations",
+              tools: [expect.objectContaining({ type: "tool", name: "sales" })],
+            },
+          ],
+        },
+      ])
       const result = yield* snapshot.execute({
         ...call("execute"),
         call: {
@@ -615,7 +634,7 @@ describe("Tool", () => {
       })
 
       const snapshot = yield* service.snapshot()
-      expect(snapshot.codeModeCatalog?.tools.map((tool) => tool.path)).toEqual(["pricing", "pricing.sales"])
+      expect(codeModeListings(snapshot.codeModeCatalog!).map((tool) => tool.path)).toEqual(["pricing", "pricing.sales"])
       const result = yield* snapshot.execute({
         ...call("execute"),
         call: {
@@ -664,7 +683,7 @@ describe("Tool", () => {
       ])
       const snapshot = yield* service.snapshot()
       expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["healthy", "execute"])
-      expect(snapshot.codeModeCatalog?.tools.map((tool) => tool.path)).toEqual(["codemode"])
+      expect(codeModeListings(snapshot.codeModeCatalog!).map((tool) => tool.path)).toEqual(["codemode"])
       expect((yield* snapshot.execute(call("phone_type")).pipe(Effect.flip)).message).toBe("Unknown tool: phone_type")
     }).pipe(Effect.provide(Logger.layer([logger])))
   })
@@ -729,7 +748,7 @@ describe("Tool", () => {
 
       const snapshot = yield* service.snapshot()
       expect(snapshot.definitions.map((tool) => tool.name)).toEqual(["execute"])
-      expect(snapshot.codeModeCatalog?.tools[0]?.signature).toContain("tools.echo")
+      expect(codeModeListings(snapshot.codeModeCatalog!)[0]?.line).toContain("tools.echo")
     }),
   )
 
@@ -1192,7 +1211,7 @@ describe("Tool", () => {
       }).pipe(Scope.provide(scope))
       const toolSet = yield* service.snapshot()
       const execute = toolSet.definitions.find((tool) => tool.name === "execute")
-      expect(toolSet.codeModeCatalog?.tools[0]?.signature).toContain("tools.echo")
+      expect(codeModeListings(toolSet.codeModeCatalog!)[0]?.line).toContain("tools.echo")
       expect(execute?.description).toContain("confined Code Mode runtime")
       expect(execute?.description).not.toContain("Echo text")
       yield* Scope.close(scope, Exit.void)

packages/plugin/src/effect/plugin.ts

@@ -2,7 +2,6 @@ import type { ExperimentalApi, GenerateApi, PluginApi } from "@opencode-ai/clien
 import type { Location } from "@opencode-ai/schema/location"
 import type { Effect, Scope } from "effect"
 import type { PluginOptions } from "../options.js"
-import type { VcsDiscovery } from "../vcs.js"
 import type { App } from "../app.js"
 import type { AgentDomain } from "./agent.js"
 import type { AISDKDomain } from "./aisdk.js"
@@ -38,7 +37,7 @@ export interface Context {
   readonly mcp: MCPDomain
   readonly generate: GenerateApi<unknown>
   readonly permission: PermissionDomain
-  readonly plugin: PluginApi<unknown>
+  readonly plugin: Pick<PluginApi<unknown>, "list">
   readonly reference: ReferenceDomain
   readonly rpc: RpcDomain
   readonly session: SessionDomain
@@ -52,7 +51,6 @@ export interface Context {
 
 export interface Plugin<R = Scope.Scope> {
   readonly id: string
-  readonly vcs?: VcsDiscovery
   readonly effect: (context: Context) => Effect.Effect<void, never, R>
 }
 

packages/plugin/src/promise/adapter.ts

@@ -214,7 +214,6 @@ function compileEndpoint(endpoint: HttpApiEndpoint.Top) {
 export function fromPromise(plugin: Plugin) {
   return define({
     id: plugin.id,
-    vcs: plugin.vcs,
     effect: (host) =>
       Effect.gen(function* () {
         const [{ ClientApi }, { OpenCodeEvent }] = yield* Effect.promise(() =>

packages/plugin/src/promise/plugin.ts

@@ -2,7 +2,6 @@ import type { OpenCodeClient } from "@opencode-ai/client"
 import type { GenerateApi, PluginApi } from "@opencode-ai/client/promise/api"
 import type { Location } from "@opencode-ai/schema/location"
 import type { PluginOptions } from "../options.js"
-import type { VcsDiscovery } from "../vcs.js"
 import type { App } from "../app.js"
 import type { AgentDomain } from "./agent.js"
 import type { AISDKDomain } from "./aisdk.js"
@@ -38,7 +37,7 @@ export interface Context {
   readonly mcp: MCPDomain
   readonly generate: GenerateApi
   readonly permission: PermissionDomain
-  readonly plugin: PluginApi
+  readonly plugin: Pick<PluginApi, "list">
   readonly reference: ReferenceDomain
   readonly rpc: RpcDomain
   readonly session: SessionDomain
@@ -54,7 +53,6 @@ export type Cleanup = () => Promise<void> | void
 
 export interface Plugin {
   readonly id: string
-  readonly vcs?: VcsDiscovery
   readonly setup: (context: Context) => Promise<Cleanup | void> | Cleanup | void
 }
 

packages/plugin/src/vcs.ts

@@ -1,4 +0,0 @@
-export interface VcsDiscovery {
-  readonly id?: string
-  readonly markers: readonly string[]
-}

packages/plugin/test/contract-identity.test.ts

@@ -61,13 +61,6 @@ test.each([
   ])
 })
 
-test.each([
-  ["effect", Plugin.Plugin.define({ id: "svn", vcs: { markers: [".svn"] }, effect: () => Effect.void })],
-  ["promise", PromisePlugin.Plugin.define({ id: "svn", vcs: { markers: [".svn"] }, setup() {} })],
-])("%s plugin definitions retain repository markers", (_name, plugin) => {
-  expect(plugin.vcs).toEqual({ markers: [".svn"] })
-})
-
 test("tui entrypoint exposes the plugin definition", () => {
   const plugin = TuiPlugin.Plugin.define({ id: "demo", setup() {} })
   expect(plugin.id).toBe("demo")

packages/protocol/openapi.json

@@ -486,6 +486,116 @@
         "summary": "List plugins"
       }
     },
+    "/api/plugin/update": {
+      "post": {
+        "tags": ["plugin"],
+        "operationId": "v2.plugin.update",
+        "parameters": [
+          {
+            "name": "location",
+            "in": "query",
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "directory": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "workspace": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            },
+            "required": false,
+            "style": "deepObject",
+            "explode": true
+          }
+        ],
+        "security": [],
+        "responses": {
+          "204": {
+            "description": "<No Content>"
+          },
+          "400": {
+            "description": "InvalidRequestError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                    },
+                    {
+                      "$ref": "#/components/schemas/InvalidRequestErrorEncoded"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "UnauthorizedError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UnauthorizedErrorEncoded"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "ServiceUnavailableError",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ServiceUnavailableErrorEncoded"
+                }
+              }
+            }
+          }
+        },
+        "description": "Update one package plugin and notify active locations to reload it.",
+        "summary": "Update plugin",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "target": {
+                    "type": "string"
+                  }
+                },
+                "required": ["target"],
+                "additionalProperties": false
+              }
+            }
+          },
+          "required": true
+        }
+      }
+    },
     "/api/session": {
       "get": {
         "tags": ["session"],
@@ -16593,11 +16703,18 @@
                 "type": "string",
                 "enum": ["package"]
               },
-              "package": {
+              "target": {
                 "type": "string"
+              },
+              "version": {
+                "type": "string"
+              },
+              "outdated": {
+                "type": "boolean",
+                "enum": [true]
               }
             },
-            "required": ["type", "package"],
+            "required": ["type", "target"],
             "additionalProperties": false
           },
           {

packages/protocol/src/groups/plugin.ts

@@ -1,7 +1,8 @@
 import { Location } from "@opencode-ai/schema/location"
 import { Plugin } from "@opencode-ai/schema/plugin"
 import { Schema } from "effect"
-import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi"
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi"
+import { InvalidRequestError, ServiceUnavailableError } from "../errors.js"
 import { LocationQuery, locationQueryOpenApi } from "./location.js"
 
 export const PluginGroup = HttpApiGroup.make("server.plugin")
@@ -19,6 +20,22 @@ export const PluginGroup = HttpApiGroup.make("server.plugin")
         }),
       ),
   )
+  .add(
+    HttpApiEndpoint.post("plugin.update", "/api/plugin/update", {
+      query: LocationQuery,
+      payload: Schema.Struct({ target: Schema.String }),
+      success: HttpApiSchema.NoContent,
+      error: [InvalidRequestError, ServiceUnavailableError],
+    })
+      .annotateMerge(locationQueryOpenApi)
+      .annotateMerge(
+        OpenApi.annotations({
+          identifier: "v2.plugin.update",
+          summary: "Update plugin",
+          description: "Update one package plugin and notify active locations to reload it.",
+        }),
+      ),
+  )
   .annotateMerge(
     OpenApi.annotations({
       title: "plugin",

packages/schema/src/plugin.ts

@@ -9,7 +9,12 @@ export type ID = typeof ID.Type
 
 export const Source = Schema.Union([
   Schema.Struct({ type: Schema.Literal("builtin") }),
-  Schema.Struct({ type: Schema.Literal("package"), package: Schema.String }),
+  Schema.Struct({
+    type: Schema.Literal("package"),
+    target: Schema.String,
+    version: Schema.String.pipe(optional),
+    outdated: Schema.Literal(true).pipe(optional),
+  }),
   Schema.Struct({ type: Schema.Literal("local"), path: Schema.String }),
   Schema.Struct({ type: Schema.Literal("sdk") }),
 ]).annotate({ identifier: "Plugin.Source" })

packages/schema/src/token-usage.ts

@@ -12,3 +12,7 @@ export const Info = Schema.Struct({
     write: Schema.Finite,
   }),
 }).annotate({ identifier: "TokenUsage.Info" })
+
+export function total(tokens: Info) {
+  return tokens.input + tokens.output + tokens.reasoning + tokens.cache.read + tokens.cache.write
+}

packages/schema/test/plugin.test.ts

@@ -4,7 +4,7 @@ import { Plugin } from "../src/plugin.js"
 
 test("embeds plugin state with a status discriminator", () => {
   const decode = Schema.decodeUnknownSync(Plugin.Info)
-  const source = { type: "package" as const, package: "acme" }
+  const source = { type: "package" as const, target: "acme", version: "1.2.3" }
   const features = { server: true as const }
 
   expect(decode({ id: "acme", source, features, state: { status: "active" } })).toEqual({
@@ -18,4 +18,8 @@ test("embeds plugin state with a status discriminator", () => {
     features,
     state: { status: "failed", error: "broken" },
   })
+  expect(decode({ source: { ...source, outdated: true }, features, state: { status: "active" } }).source).toEqual({
+    ...source,
+    outdated: true,
+  })
 })

packages/schema/test/token-usage.test.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test"
+import { TokenUsage } from "../src/token-usage.js"
+
+test("totals every token category", () => {
+  expect(TokenUsage.total({ input: 1, output: 2, reasoning: 4, cache: { read: 8, write: 16 } })).toBe(31)
+})
+
+test("supports zero and large usage totals without rounding", () => {
+  expect(TokenUsage.total({ input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } })).toBe(0)
+  expect(
+    TokenUsage.total({
+      input: 1_000_000_000,
+      output: 2_000_000_000,
+      reasoning: 3,
+      cache: { read: 4_000_000_000, write: 5 },
+    }),
+  ).toBe(7_000_000_008)
+})

packages/server/src/handlers/generate.ts

@@ -7,15 +7,6 @@ import { Global } from "@opencode-ai/util/global"
 import { Effect } from "effect"
 import { HttpApiBuilder } from "effect/unstable/httpapi"
 import { Api } from "../api"
-import { pluginReadiness } from "./plugin-readiness"
-
-const flushPlugins = pluginReadiness(
-  () =>
-    new ServiceUnavailableError({
-      message: "Model catalog initialization timed out",
-      service: "model.catalog",
-    }),
-)
 
 export const GenerateHandler = HttpApiBuilder.group(Api, "server.generate", (handlers) =>
   Effect.gen(function* () {
@@ -25,7 +16,6 @@ export const GenerateHandler = HttpApiBuilder.group(Api, "server.generate", (han
     return handlers.handle(
       "generate.text",
       Effect.fn("server.generate.text")(function* (request) {
-        yield* flushPlugins
         const generate = yield* Generate.Service
         const text = yield* generate
           .text(request.payload)

packages/server/src/handlers/model.ts

@@ -1,18 +1,8 @@
 import { Catalog } from "@opencode-ai/core/catalog"
-import { ServiceUnavailableError } from "@opencode-ai/protocol/errors"
 import { Effect } from "effect"
 import { HttpApiBuilder } from "effect/unstable/httpapi"
 import { Api } from "../api"
 import { response } from "../location"
-import { pluginReadiness } from "./plugin-readiness"
-
-const flushPlugins = pluginReadiness(
-  () =>
-    new ServiceUnavailableError({
-      message: "Model catalog initialization timed out",
-      service: "model.catalog",
-    }),
-)
 
 export const ModelHandler = HttpApiBuilder.group(Api, "server.model", (handlers) =>
   Effect.gen(function* () {
@@ -20,7 +10,6 @@ export const ModelHandler = HttpApiBuilder.group(Api, "server.model", (handlers)
       .handle(
         "model.list",
         Effect.fn(function* () {
-          yield* flushPlugins
           const catalog = yield* Catalog.Service
           return yield* response(catalog.model.available())
         }),
@@ -28,7 +17,6 @@ export const ModelHandler = HttpApiBuilder.group(Api, "server.model", (handlers)
       .handle(
         "model.default",
         Effect.fn(function* () {
-          yield* flushPlugins
           const catalog = yield* Catalog.Service
           return yield* response(catalog.model.default())
         }),

packages/server/src/handlers/plugin-readiness.ts

@@ -1,13 +0,0 @@
-import { PluginSupervisor } from "@opencode-ai/core/plugin/supervisor"
-import { ServiceUnavailableError } from "@opencode-ai/protocol/errors"
-import { Effect } from "effect"
-
-export function pluginReadiness(error: () => ServiceUnavailableError) {
-  return PluginSupervisor.Service.pipe(
-    Effect.flatMap((plugins) => plugins.flush),
-    Effect.timeoutOrElse({
-      duration: "5 seconds",
-      orElse: () => Effect.fail(error()),
-    }),
-  )
-}