refactor(ai): unify prompt cache configuration

bun.lock

@@ -88,6 +88,7 @@
         "@tanstack/solid-query": "5.91.4",
         "@tanstack/solid-virtual": "catalog:",
         "@thisbeyond/solid-dnd": "0.7.5",
+        "diff": "catalog:",
         "effect": "catalog:",
         "fuzzysort": "catalog:",
         "ghostty-web": "github:anomalyco/ghostty-web#83c0a07b8628b748aed073b232cb4b52a6ca11c1",
@@ -383,6 +384,7 @@
         "@opencode-ai/ai": "workspace:*",
         "@opencode-ai/codemode": "workspace:*",
         "@opencode-ai/effect-drizzle-sqlite": "workspace:*",
+        "@opencode-ai/effect-sqlite-node": "workspace:*",
         "@opencode-ai/plugin": "workspace:*",
         "@opencode-ai/schema": "workspace:*",
         "@opencode-ai/util": "workspace:*",
@@ -403,6 +405,7 @@
         "ignore": "7.0.5",
         "immer": "11.1.4",
         "jsonc-parser": "3.3.1",
+        "semver": "^7.6.3",
         "tree-sitter-bash": "0.25.0",
         "tree-sitter-powershell": "0.25.10",
         "turndown": "7.2.0",
@@ -424,6 +427,7 @@
         "@tsconfig/bun": "catalog:",
         "@types/bun": "catalog:",
         "@types/node": "catalog:",
+        "@types/semver": "catalog:",
         "@types/turndown": "5.0.5",
         "@types/which": "3.0.4",
         "drizzle-kit": "catalog:",

packages/ai/example/tutorial.ts

@@ -33,9 +33,10 @@ const model = OpenAI.configure({
 //
 //   - `generation`: common controls such as max tokens, temperature, topP/topK,
 //     penalties, seed, and stop sequences.
+//   - `cache`: provider-neutral prompt caching behavior and cache affinity.
 //   - `providerOptions`: namespaced provider-native behavior. For example,
-//     OpenAI cache keys and store behavior, Anthropic thinking, Gemini thinking
-//     config, or OpenRouter routing/reasoning.
+//     OpenAI store behavior, Anthropic thinking, Gemini thinking config, or
+//     OpenRouter routing/reasoning.
 //   - `http`: last-resort serializable overlays for final request body, headers,
 //     and query params. Prefer typed `providerOptions` when a field is stable.
 //
@@ -45,9 +46,7 @@ const request = LLM.request({
   system: "You are concise and practical.",
   prompt: "Tell me a joke",
   generation: { maxTokens: 80, temperature: 0.7 },
-  providerOptions: {
-    openai: { promptCacheKey: "tutorial-joke" },
-  },
+  cache: { mode: "auto", key: "tutorial-joke" },
 })
 
 // 3. `generate` sends the request and collects the event stream into one

packages/ai/src/cache-policy.ts

@@ -10,16 +10,16 @@
 //
 // Manual `cache: CacheHint` placements on individual parts are preserved and
 // count against the four-breakpoint budget; auto only fills remaining slots.
-import { CacheHint, type CachePolicy, type CachePolicyObject } from "./schema/options"
+import { CacheHint, type CacheExplicit, type CachePolicy } from "./schema/options"
 import { LLMRequest, Message, ToolDefinition, type ContentPart } from "./schema/messages"
 
-const AUTO: CachePolicyObject = {
+const AUTO: Omit<CacheExplicit, "mode" | "key"> = {
   tools: true,
   system: true,
   messages: { tail: 1 },
 }
 
-const NONE: CachePolicyObject = {}
+const NONE: Omit<CacheExplicit, "mode" | "key"> = {}
 const BREAKPOINT_CAP = 4
 
 // Resolution rules:
@@ -29,8 +29,8 @@ const BREAKPOINT_CAP = 4
 //   - "auto"      → tools + first/last system + final message boundary.
 //   - "none"      → no auto placement; manual `CacheHint`s still flow.
 //   - object form → exactly what the caller asked for.
-const resolve = (policy: CachePolicy | undefined): CachePolicyObject => {
-  if (policy === undefined || policy === "auto") return AUTO
+const resolve = (policy: CachePolicy | undefined): Omit<CacheExplicit, "mode" | "key"> => {
+  if (policy === undefined || (policy !== "none" && policy.mode === "auto")) return AUTO
   if (policy === "none") return NONE
   return policy
 }
@@ -103,7 +103,7 @@ const markMessageAt = (
 
 const markMessages = (
   messages: ReadonlyArray<Message>,
-  strategy: NonNullable<CachePolicyObject["messages"]>,
+  strategy: NonNullable<CacheExplicit["messages"]>,
   hint: CacheHint,
   budget: Budget,
 ): ReadonlyArray<Message> => {
@@ -133,7 +133,11 @@ const countHints = (request: LLMRequest) =>
 
 export const applyCachePolicy = (request: LLMRequest): LLMRequest => {
   if (!RESPECTS_INLINE_HINTS.has(request.model.route.id)) return request
-  if (request.model.route.id === "openrouter" && (request.cache === undefined || request.cache === "auto")) return request
+  if (
+    request.model.route.id === "openrouter" &&
+    (request.cache === undefined || (request.cache !== "none" && request.cache.mode === "auto"))
+  )
+    return request
   const policy = resolve(request.cache)
   if (!policy.tools && !policy.system && !policy.messages) return request
 

packages/ai/src/protocols/open-responses.ts

@@ -3,6 +3,7 @@ import type { Content } from "@opencode-ai/schema/tool"
 import { HttpTransport } from "../route/transport"
 import { Protocol } from "../route/protocol"
 import {
+  cacheKey,
   LLMError,
   LLMEvent,
   Usage,
@@ -542,7 +543,7 @@ const lowerOptions = (request: LLMRequest) => {
   return {
     ...(options.instructions ? { instructions: options.instructions } : {}),
     ...(options.store !== undefined ? { store: options.store } : {}),
-    ...(options.promptCacheKey ? { prompt_cache_key: options.promptCacheKey } : {}),
+    ...(cacheKey(request.cache) ? { prompt_cache_key: cacheKey(request.cache) } : {}),
     ...(options.include ? { include: options.include } : {}),
     ...(options.reasoningEffort || options.reasoningSummary
       ? { reasoning: { effort: options.reasoningEffort, summary: options.reasoningSummary } }

packages/ai/src/protocols/utils/open-responses-options.ts

@@ -33,7 +33,6 @@ export const ServiceTierSchema = Schema.Literals(ServiceTiers)
 export interface Resolved {
   readonly instructions?: string
   readonly store?: boolean
-  readonly promptCacheKey?: string
   readonly reasoningEffort?: string
   readonly reasoningSummary?: "auto" | "concise" | "detailed"
   readonly include?: ReadonlyArray<ResponseIncludable>
@@ -50,7 +49,6 @@ export const resolve = (request: LLMRequest): Resolved => {
   return {
     instructions: typeof input?.instructions === "string" ? input.instructions : undefined,
     store: typeof input?.store === "boolean" ? input.store : undefined,
-    promptCacheKey: typeof input?.promptCacheKey === "string" ? input.promptCacheKey : undefined,
     reasoningEffort: typeof input?.reasoningEffort === "string" ? input.reasoningEffort : undefined,
     reasoningSummary:
       reasoningSummary === "auto" || reasoningSummary === "concise" || reasoningSummary === "detailed"

packages/ai/src/providers/open-responses-options.ts

@@ -5,7 +5,6 @@ export interface OpenResponsesOptionsInput {
   readonly [key: string]: unknown
   readonly instructions?: string
   readonly store?: boolean
-  readonly promptCacheKey?: string
   readonly reasoningEffort?: ReasoningEffort
   readonly reasoningSummary?: "auto" | "concise" | "detailed"
   readonly include?: ReadonlyArray<ResponseIncludable>

packages/ai/src/providers/openai-options.ts

@@ -17,7 +17,6 @@ const openAIProviderOptions = (options: OpenAIOptionsInput | undefined): Provide
   const openai = Object.fromEntries(
     definedEntries({
       store: options?.store,
-      promptCacheKey: options?.promptCacheKey,
       reasoningEffort: options?.reasoningEffort,
       reasoningSummary: options?.reasoningSummary,
       include: options?.include,

packages/ai/src/providers/openrouter.ts

@@ -4,7 +4,7 @@ import { Endpoint } from "../route/endpoint"
 import { Framing } from "../route/framing"
 import { Protocol } from "../route/protocol"
 import { AuthOptions, type ProviderAuthOption } from "../route/auth-options"
-import { ProviderID, type CacheHint, type ModelID, type ProviderOptions } from "../schema"
+import { cacheKey, ProviderID, type CacheHint, type ModelID, type ProviderOptions } from "../schema"
 import type { ProviderPackage } from "../provider-package"
 import * as OpenAICompatibleProfiles from "./openai-compatible-profile"
 import * as OpenAIChat from "../protocols/openai-chat"
@@ -55,7 +55,6 @@ export interface OpenRouterOptions {
   readonly debug?: Readonly<{ echo_upstream_body?: boolean }>
   readonly models?: ReadonlyArray<string>
   readonly plugins?: ReadonlyArray<OpenRouterPlugin>
-  readonly promptCacheKey?: string
   readonly provider?: OpenRouterProviderRouting
   readonly reasoning?: Readonly<{
     enabled?: boolean
@@ -122,6 +121,7 @@ export const protocol = Protocol.make({
             ...body,
             messages,
             ...bodyOptions(request.providerOptions?.openrouter),
+            ...(cacheKey(request.cache) ? { prompt_cache_key: cacheKey(request.cache) } : {}),
           } as OpenRouterBody
         }),
       ),
@@ -161,7 +161,6 @@ const bodyOptions = (input: unknown) => {
     ...(isRecord(debug) ? { debug } : {}),
     ...(typeof user === "string" ? { user } : {}),
     ...(isRecord(reasoning) ? { reasoning } : {}),
-    ...(typeof promptCacheKey === "string" ? { prompt_cache_key: promptCacheKey } : {}),
   }
 }
 

packages/ai/src/schema/options.ts

@@ -256,18 +256,17 @@ export class CacheHint extends Schema.Class<CacheHint>("LLM.CacheHint")({
   ttlSeconds: Schema.optional(Schema.Number),
 }) {}
 
-// Auto-placement policy for prompt caching. The protocol-neutral lowering step
-// reads this and injects `CacheHint`s at the configured boundaries; the
-// per-protocol body builders then translate those hints into wire markers as
-// usual. `"auto"` is the recommended default for agent loops — it places
-// breakpoints at the last tool definition, the first and last distinct system
-// parts, and the conversation tail. The rolling message breakpoint keeps a
-// prior cache entry within Anthropic/Bedrock's 20-block lookback during long
-// tool loops.
-//
-// Pass `"none"` to opt out entirely (the legacy behavior). Pass the granular
-// object form to override individual choices.
-export const CachePolicyObject = Schema.Struct({
+const CacheKey = { key: Schema.optional(Schema.String) }
+
+export const CacheAuto = Schema.Struct({
+  mode: Schema.Literal("auto"),
+  ...CacheKey,
+})
+export type CacheAuto = Schema.Schema.Type<typeof CacheAuto>
+
+export const CacheExplicit = Schema.Struct({
+  mode: Schema.Literal("explicit"),
+  ...CacheKey,
   tools: Schema.optional(Schema.Boolean),
   system: Schema.optional(Schema.Boolean),
   messages: Schema.optional(
@@ -279,7 +278,12 @@ export const CachePolicyObject = Schema.Struct({
   ),
   ttlSeconds: Schema.optional(Schema.Number),
 })
-export type CachePolicyObject = Schema.Schema.Type<typeof CachePolicyObject>
+export type CacheExplicit = Schema.Schema.Type<typeof CacheExplicit>
 
-export const CachePolicy = Schema.Union([Schema.Literal("auto"), Schema.Literal("none"), CachePolicyObject])
+// Omitted configuration uses automatic provider behavior and OpenCode's
+// automatic breakpoint placement where required. `"none"` sends no cache key
+// or explicit controls; providers may still cache implicitly.
+export const CachePolicy = Schema.Union([Schema.Literal("none"), CacheAuto, CacheExplicit])
 export type CachePolicy = Schema.Schema.Type<typeof CachePolicy>
+
+export const cacheKey = (cache: CachePolicy | undefined) => (cache && cache !== "none" ? cache.key : undefined)

packages/ai/test/cache-policy.test.ts

@@ -64,7 +64,7 @@ describe("applyCachePolicy", () => {
             Message.assistant("assistant reply"),
             Message.user("latest user message"),
           ],
-          cache: "auto",
+          cache: { mode: "auto" },
         }),
       )
 
@@ -93,7 +93,7 @@ describe("applyCachePolicy", () => {
           model: openaiModel,
           system: "Sys",
           prompt: "hi",
-          cache: "auto",
+          cache: { mode: "auto" },
         }),
       )
 
@@ -112,7 +112,7 @@ describe("applyCachePolicy", () => {
           model: geminiModel,
           system: "Sys",
           prompt: "hi",
-          cache: "auto",
+          cache: { mode: "auto" },
         }),
       )
 
@@ -133,7 +133,7 @@ describe("applyCachePolicy", () => {
           ],
           tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
           messages: [Message.user("first user"), Message.assistant("reply"), Message.user("latest user")],
-          cache: "auto",
+          cache: { mode: "auto" },
         }),
       )
 
@@ -183,7 +183,7 @@ describe("applyCachePolicy", () => {
           system: "Sys",
           tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
           prompt: "hi",
-          cache: { tools: true },
+          cache: { mode: "explicit", tools: true },
         }),
       )
 
@@ -204,7 +204,7 @@ describe("applyCachePolicy", () => {
             { type: "text", text: "last system" },
           ],
           prompt: "hi",
-          cache: "auto",
+          cache: { mode: "auto" },
         }),
       )
 
@@ -233,7 +233,7 @@ describe("applyCachePolicy", () => {
         ],
         tools: [{ name: "t1", description: "t1", inputSchema: { type: "object", properties: {} } }],
         prompt: "hi",
-        cache: "auto",
+          cache: { mode: "auto" },
       })
       const applied = applyCachePolicy(request)
       expect(applied.tools[0]?.cache).toBeDefined()
@@ -267,7 +267,7 @@ describe("applyCachePolicy", () => {
           model: anthropicModel,
           system: "Sys",
           prompt: "hi",
-          cache: { system: true, ttlSeconds: 3600 },
+          cache: { mode: "explicit", system: true, ttlSeconds: 3600 },
         }),
       )
 
@@ -283,7 +283,7 @@ describe("applyCachePolicy", () => {
         LLM.request({
           model: anthropicModel,
           messages: [Message.user("u1"), Message.assistant("a1"), Message.user("u2"), Message.assistant("a2")],
-          cache: { messages: { tail: 2 } },
+          cache: { mode: "explicit", messages: { tail: 2 } },
         }),
       )
 
@@ -301,7 +301,7 @@ describe("applyCachePolicy", () => {
         LLM.request({
           model: anthropicModel,
           messages: [Message.user("u1"), Message.assistant("a1"), Message.user("u2")],
-          cache: { messages: "latest-assistant" },
+          cache: { mode: "explicit", messages: "latest-assistant" },
         }),
       )
 

packages/ai/test/provider-options/cloudflare.types.ts

@@ -3,11 +3,11 @@ import { CloudflareWorkersAI } from "../../src/providers"
 
 const model = CloudflareWorkersAI.configure({ accountId: "account", apiKey: "test" }).model("model")
 
-LLM.request({ model, prompt: "Hello", providerOptions: { openai: { promptCacheKey: "cache" } } })
+LLM.request({ model, prompt: "Hello", cache: { mode: "auto", key: "cache" } })
 
 LLM.request({
   model,
   prompt: "Hello",
-  // @ts-expect-error Cloudflare's OpenAI-compatible prompt cache key must be a string.
-  providerOptions: { openai: { promptCacheKey: 1 } },
+  // @ts-expect-error Prompt cache keys must be strings.
+  cache: { mode: "auto", key: 1 },
 })

packages/ai/test/provider/openai-responses-cache.recorded.test.ts

@@ -20,7 +20,7 @@ const cacheRequest = LLM.request({
   system: LARGE_CACHEABLE_SYSTEM,
   prompt: "Say hi.",
   generation: { maxTokens: 16, temperature: 0 },
-  providerOptions: { openai: { promptCacheKey: "recorded-cache-test" } },
+  cache: { mode: "auto", key: "recorded-cache-test" },
 })
 
 const recorded = recordedTests({

packages/ai/test/provider/openai-responses.test.ts

@@ -680,9 +680,9 @@ describe("OpenAI Responses route", () => {
         LLM.request({
           model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).model("gpt-5.2"),
           prompt: "think",
+          cache: { mode: "auto", key: "session_123" },
           providerOptions: {
             openai: {
-              promptCacheKey: "session_123",
               reasoningEffort: "high",
               reasoningSummary: "auto",
               include: ["reasoning.encrypted_content"],
@@ -801,17 +801,16 @@ describe("OpenAI Responses route", () => {
     }),
   )
 
-  it.effect("request OpenAI provider options override route defaults", () =>
+  it.effect("maps the request prompt cache key", () =>
     Effect.gen(function* () {
       const prepared = yield* compileRequest(
         LLM.request({
           model: OpenAI.configure({
             baseURL: "https://api.openai.test/v1/",
             apiKey: "test",
-            providerOptions: { openai: { promptCacheKey: "model_cache" } },
           }).model("gpt-4.1-mini"),
           prompt: "no cache",
-          providerOptions: { openai: { promptCacheKey: "request_cache" } },
+          cache: { mode: "auto", key: "request_cache" },
         }),
       )
 

packages/ai/test/provider/openrouter.test.ts

@@ -43,7 +43,7 @@ describe("OpenRouter", () => {
           ],
           tools: [{ name: "lookup", description: "Lookup", inputSchema: { type: "object", properties: {} } }],
           prompt: "Hello",
-          cache: { tools: true, system: true, messages: { tail: 1 } },
+          cache: { mode: "explicit", tools: true, system: true, messages: { tail: 1 } },
         }),
       )
 
@@ -123,7 +123,7 @@ describe("OpenRouter", () => {
       const prepared = yield* compileRequest(
         LLM.request({
           model: OpenRouter.configure({ apiKey: "test-key" }).model("anthropic/claude-sonnet-4.6"),
-          cache: { messages: "latest-assistant" },
+          cache: { mode: "explicit", messages: "latest-assistant" },
           messages: [Message.user("Think"), Message.assistant([{ type: "reasoning", text: "Reasoning" }])],
         }),
       )
@@ -162,7 +162,6 @@ describe("OpenRouter", () => {
               openrouter: {
                 usage: true,
                 reasoning: { effort: "high" },
-                promptCacheKey: "session_123",
                 models: ["anthropic/claude-sonnet-4.6", "google/gemini-3.1-pro"],
                 provider: { order: ["anthropic", "google"], require_parameters: true },
                 plugins: [{ id: "response-healing" }],
@@ -174,6 +173,7 @@ describe("OpenRouter", () => {
             },
           }).model("anthropic/claude-3.7-sonnet:thinking"),
           prompt: "Think briefly.",
+          cache: { mode: "auto", key: "session_123" },
         }),
       )
 

packages/cli/src/commands/commands.ts

@@ -133,6 +133,7 @@ export const Commands = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCO
       description: "Manage plugins",
       commands: [Spec.make("list", { description: "List active plugins" })],
     }),
+    Spec.make("migrate", { description: "Migrate v1 data to v2" }),
     Spec.make("mini", {
       description: "Start the minimal interactive interface",
       params: {

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

@@ -0,0 +1,5 @@
+import { Effect } from "effect"
+import { Commands } from "../commands"
+import { Runtime } from "../../framework/runtime"
+
+export default Runtime.handler(Commands.commands.migrate, (_input) => Effect.log("No migrations to run."))

packages/cli/src/config/migrate.ts

@@ -116,6 +116,13 @@ export function migrateV1(legacy: TuiConfigV1.Info | undefined, kv: Record<strin
               : { grouping: kv.exploration_grouping ? ("auto" as const) : ("none" as const) }),
           },
         }),
+    ...(kv.dismissed_getting_started === undefined
+      ? {}
+      : {
+          hints: {
+            onboarding: !kv.dismissed_getting_started,
+          },
+        }),
     ...(kv.animations_enabled === undefined ? {} : { animations: kv.animations_enabled }),
     ...(legacy?.mouse === undefined ? {} : { mouse: legacy.mouse }),
   }

packages/cli/src/index.ts

@@ -35,6 +35,7 @@ const Handlers = Runtime.handlers(Commands, {
   plugin: {
     list: () => import("./commands/handlers/plugin/list"),
   },
+  migrate: () => import("./commands/handlers/migrate"),
   mini: () => import("./commands/handlers/mini"),
   run: () => import("./commands/handlers/run"),
   pair: () => import("./commands/handlers/pair"),

packages/cli/src/run/run.ts

@@ -235,6 +235,10 @@ async function renderToolError(part: SessionMessageAssistantTool, directory: str
   UI.println(UI.Style.TEXT_NORMAL + "✗", UI.Style.TEXT_NORMAL + `${info.title} failed`)
 }
 
+function warning(message: string) {
+  UI.println(UI.Style.TEXT_WARNING_BOLD + "!", UI.Style.TEXT_NORMAL, message)
+}
+
 function errorMessage(error: unknown) {
   if (error instanceof Error) return error.message
   if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string")

packages/cli/test/config.test.ts

@@ -74,12 +74,12 @@ test("migrates tui and kv config into cli.json", async () => {
       terminal: { title: false },
       prompt: { editor: false, paste: "full" },
       session: { sidebar: "hide", scrollbar: true, thinking: "show", grouping: "none" },
+      hints: { onboarding: false },
       animations: false,
       mouse: false,
     })
     expect(config).not.toHaveProperty("skipped_version")
     expect(config).not.toHaveProperty("which_key")
-    expect(config).not.toHaveProperty("hints")
     expect((await Bun.file(path.join(directory, "cli.json")).json()).keybinds).toEqual({ leader: "ctrl+o" })
     expect(await Bun.file(path.join(directory, "cli.json")).exists()).toBe(true)
     expect(await Bun.file(path.join(directory, "tui.json")).exists()).toBe(true)

packages/core/package.json

@@ -56,6 +56,7 @@
     "@tsconfig/bun": "catalog:",
     "@types/bun": "catalog:",
     "@types/node": "catalog:",
+    "@types/semver": "catalog:",
     "@types/turndown": "5.0.5",
     "@types/which": "3.0.4",
     "@parcel/watcher-darwin-arm64": "2.5.1",
@@ -99,6 +100,7 @@
     "@ff-labs/fff-node": "0.10.1",
     "@opencode-ai/codemode": "workspace:*",
     "@opencode-ai/effect-drizzle-sqlite": "workspace:*",
+    "@opencode-ai/effect-sqlite-node": "workspace:*",
     "@opencode-ai/ai": "workspace:*",
     "@opencode-ai/schema": "workspace:*",
     "@opencode-ai/plugin": "workspace:*",
@@ -120,6 +122,7 @@
     "immer": "11.1.4",
     "ignore": "7.0.5",
     "jsonc-parser": "3.3.1",
+    "semver": "^7.6.3",
     "turndown": "7.2.0",
     "tree-sitter-bash": "0.25.0",
     "tree-sitter-powershell": "0.25.10",

packages/core/src/aisdk-native.ts

@@ -108,6 +108,7 @@ function mapOpenRouterOptions(settings: Readonly<Record<string, unknown>>) {
           "extraBody",
           "fetch",
           "headers",
+          "promptCacheKey",
           "timeout",
         ].includes(key),
     ),
@@ -124,7 +125,6 @@ function mapXAIOptions(settings: Readonly<Record<string, unknown>>) {
   const options = {
     ...(typeof settings.reasoningEffort === "string" ? { reasoningEffort: settings.reasoningEffort } : {}),
     ...(typeof settings.store === "boolean" ? { store: settings.store } : {}),
-    ...(typeof settings.promptCacheKey === "string" ? { promptCacheKey: settings.promptCacheKey } : {}),
   }
   if (Object.keys(options).length === 0) return {}
   return { providerOptions: { xai: options } }

packages/core/src/control-plane/move-session.ts

@@ -0,0 +1,181 @@
+export * as MoveSession from "./move-session"
+
+import { Context, DateTime, Effect, Layer, Schema } from "effect"
+import { makeGlobalNode } from "@opencode-ai/util/effect/app-node"
+import { FSUtil } from "@opencode-ai/util/fs-util"
+import { Git } from "../git"
+import { Global } from "@opencode-ai/util/global"
+import { Project } from "../project"
+import { Session } from "../session"
+import { SessionExecution } from "../session/execution"
+import { SessionSchema } from "../session/schema"
+import { SessionStore } from "../session/store"
+import { AbsolutePath } from "../schema"
+import path from "path"
+
+export const Destination = Schema.Struct({
+  directory: AbsolutePath,
+}).annotate({ identifier: "MoveSession.Destination" })
+export type Destination = typeof Destination.Type
+
+export const Input = Schema.Struct({
+  sessionID: SessionSchema.ID,
+  destination: Destination,
+  moveChanges: Schema.optional(Schema.Boolean),
+}).annotate({ identifier: "MoveSession.Input" })
+export type Input = typeof Input.Type
+
+export class DestinationProjectMismatchError extends Schema.TaggedErrorClass<DestinationProjectMismatchError>()(
+  "MoveSession.DestinationProjectMismatchError",
+  {
+    expected: Project.ID,
+    actual: Project.ID,
+  },
+) {}
+
+export class DestinationNotFoundError extends Schema.TaggedErrorClass<DestinationNotFoundError>()(
+  "MoveSession.DestinationNotFoundError",
+  { directory: AbsolutePath },
+) {}
+
+export class DestinationNotDirectoryError extends Schema.TaggedErrorClass<DestinationNotDirectoryError>()(
+  "MoveSession.DestinationNotDirectoryError",
+  { directory: AbsolutePath },
+) {}
+
+export class ApplyChangesError extends Schema.TaggedErrorClass<ApplyChangesError>()("MoveSession.ApplyChangesError", {
+  message: Schema.String,
+}) {}
+
+export class CaptureChangesError extends Schema.TaggedErrorClass<CaptureChangesError>()(
+  "MoveSession.CaptureChangesError",
+  {
+    message: Schema.String,
+  },
+) {}
+
+export class ResetSourceChangesError extends Schema.TaggedErrorClass<ResetSourceChangesError>()(
+  "MoveSession.ResetSourceChangesError",
+  {
+    directory: AbsolutePath,
+    message: Schema.String,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {}
+
+export type Error =
+  | Session.NotFoundError
+  | DestinationProjectMismatchError
+  | DestinationNotFoundError
+  | DestinationNotDirectoryError
+  | Session.DestinationNotFoundError
+  | Session.DestinationNotDirectoryError
+  | CaptureChangesError
+  | ApplyChangesError
+  | ResetSourceChangesError
+
+export interface Interface {
+  readonly moveSession: (input: Input) => Effect.Effect<void, Error>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/ControlPlaneMoveSession") {}
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const git = yield* Git.Service
+    const fs = yield* FSUtil.Service
+    const global = yield* Global.Service
+    const project = yield* Project.Service
+    const sessions = yield* SessionStore.Service
+    const session = yield* Session.Service
+    const execution = yield* SessionExecution.Service
+
+    const moveSession = Effect.fn("MoveSession.moveSession")(function* (input: Input) {
+      const current = yield* sessions.get(input.sessionID)
+      if (!current) return yield* new Session.NotFoundError({ sessionID: input.sessionID })
+      const value = input.destination.directory.trim()
+      const expanded = value === "~" ? global.home : value.startsWith("~/") ? path.join(global.home, value.slice(2)) : value
+      const directory = AbsolutePath.make(path.resolve(current.location.directory, expanded))
+      const destinationInfo = yield* fs.stat(directory).pipe(Effect.catch(() => Effect.succeed(undefined)))
+      if (!destinationInfo) return yield* new DestinationNotFoundError({ directory })
+      if (destinationInfo.type !== "Directory") return yield* new DestinationNotDirectoryError({ directory })
+      if (current.location.directory === directory) return
+
+      const source = yield* project.resolve(current.location.directory)
+      const destination = yield* project.resolve(directory)
+      if (input.moveChanges && current.projectID !== destination.id) {
+        return yield* new DestinationProjectMismatchError({ expected: current.projectID, actual: destination.id })
+      }
+      // A move must not race active execution: a mid-drain relocation would let
+      // the source Location dispatch a request assembled under stale instructions
+      // and history. Serialize like removal does — stop the drain, then move.
+      yield* execution.interrupt(input.sessionID)
+      yield* execution.awaitIdle(input.sessionID)
+
+      const moveChanges = input.moveChanges && source.directory !== destination.directory
+      const sourceRepository = moveChanges ? yield* git.repo.discover(current.location.directory) : undefined
+      if (moveChanges && !sourceRepository)
+        return yield* new CaptureChangesError({ message: "Source is not a Git repository" })
+      const patch = sourceRepository
+        ? yield* git.change
+            .capture({ repository: sourceRepository, path: current.location.directory })
+            .pipe(Effect.mapError((error) => new CaptureChangesError({ message: error.message })))
+        : Git.ChangeSet.make("")
+      if (patch) {
+        const repository = yield* git.repo.discover(directory)
+        if (!repository) return yield* new ApplyChangesError({ message: "Destination is not a Git repository" })
+        yield* git.change
+          .apply({ repository, path: directory, changes: patch })
+          .pipe(Effect.mapError((error) => new ApplyChangesError({ message: error.message })))
+      }
+
+      yield* session.move({
+        sessionID: input.sessionID,
+        directory,
+      })
+
+      if (patch) {
+        const repository = yield* git.repo.discover(current.location.directory)
+        if (!repository)
+          return yield* new ResetSourceChangesError({
+            directory: current.location.directory,
+            message: "Source is not a Git repository",
+          })
+        yield* git.change
+          .discard({
+            repository,
+            path: current.location.directory,
+            index: "preserve",
+            untracked: "remove",
+          })
+          .pipe(
+            Effect.mapError(
+              (error) =>
+                new ResetSourceChangesError({
+                  directory: current.location.directory,
+                  message: error.message,
+                  cause: error.cause,
+                }),
+            ),
+          )
+      }
+    })
+
+    return Service.of({ moveSession })
+  }),
+)
+
+export const node = makeGlobalNode({
+  service: Service,
+  layer,
+  deps: [
+    FSUtil.node,
+    Git.node,
+    Global.node,
+    Project.node,
+    Session.node,
+    SessionStore.node,
+    SessionExecution.node,
+  ],
+})

packages/core/src/location-services.ts

@@ -148,3 +148,6 @@ export function buildLocationServiceMap(
     ),
   )
 }
+
+// This is temporary for backwards compatibility
+export const locationServiceMapLayer = buildLocationServiceMap()

packages/core/src/plugin/layer-map.example.ts

@@ -0,0 +1,94 @@
+export * as LayerMapExample from "./layer-map.example"
+
+import { Context, Effect, Layer, LayerMap } from "effect"
+import { Npm } from "@opencode-ai/util/npm"
+
+/**
+ * Tutorial: split global services from context-specific services.
+ *
+ * Use this pattern when part of the app should be constructed once at the app edge,
+ * while another part should be cached per request/project/workspace key.
+ *
+ * In this example:
+ * - Npm.Service is the global service. It is not keyed by request context and should
+ *   be provided once by the application runtime.
+ * - ConfigService is context-specific. It is built from a RequestContext key and is
+ *   cached by LayerMap for that key.
+ * - ConfigServiceMap.layer owns the cache. Provide it once globally, then each
+ *   request can provide ConfigServiceMap.get(context) to select the right instance.
+ *
+ * Lifetime model:
+ * - ConfigServiceMap.layer has the app/global lifetime and depends on Npm.Service.
+ * - ConfigServiceMap.get(context) has the request/context lifetime and provides
+ *   ConfigService for exactly that context key.
+ * - The cached ConfigService entry stays alive while something is using it. Once idle,
+ *   it remains cached for idleTimeToLive, then its scope is finalized.
+ * - invalidate(context) removes the cache entry for future lookups. Active users keep
+ *   running on the old instance; the next lookup can create a fresh instance.
+ *
+ * Key model:
+ * - Keys can be strings, structs, classes, arrays, etc.
+ * - Prefer primitive or immutable keys. Effect uses Hash / Equal semantics for cache
+ *   lookup, so mutating an object after it has been used as a key is a bug.
+ */
+
+export type RequestContext = {
+  readonly directory: string
+  readonly workspace: string
+}
+
+export class RequestContextRef extends Context.Service<RequestContextRef, RequestContext>()(
+  "@opencode/example/RequestContextRef",
+) {}
+
+export interface ConfigServiceShape {
+  readonly directory: string
+  readonly workspace: string
+  readonly nextUse: () => Effect.Effect<number>
+  readonly which: Npm.Interface["which"]
+}
+
+export class ConfigService extends Context.Service<ConfigService, ConfigServiceShape>()(
+  "@opencode/example/ConfigService",
+) {}
+
+const configServiceLayer = Layer.effect(
+  ConfigService,
+  Effect.gen(function* () {
+    const context = yield* RequestContextRef
+    const npm = yield* Npm.Service
+
+    let useCount = 0
+
+    return ConfigService.of({
+      directory: context.directory,
+      workspace: context.workspace,
+      nextUse: () => Effect.succeed(++useCount),
+      which: npm.which,
+    })
+  }),
+)
+
+export class ConfigServiceMap extends LayerMap.Service<ConfigServiceMap>()("@opencode/example/ConfigServiceMap", {
+  lookup: (context: RequestContext) =>
+    configServiceLayer.pipe(Layer.provide(Layer.succeed(RequestContextRef, RequestContextRef.of(context)))),
+  idleTimeToLive: "5 minutes",
+}) {}
+
+export const appLayer = ConfigServiceMap.layer
+
+export const readConfig = Effect.fn("LayerMapExample.readConfig")(function* () {
+  const config = yield* ConfigService
+
+  return {
+    directory: config.directory,
+    workspace: config.workspace,
+    useCount: yield* config.nextUse(),
+  }
+})
+
+export const handleRequest = Effect.fn("LayerMapExample.handleRequest")(function* (context: RequestContext) {
+  return yield* readConfig().pipe(Effect.provide(ConfigServiceMap.get(context)))
+})
+
+export const invalidateContext = (context: RequestContext) => ConfigServiceMap.invalidate(context)

packages/core/src/plugin/runtime.ts

@@ -120,6 +120,7 @@ export const providerLayerWithCell = (cell: Cell) =>
   )
 
 export const layer = layerWithCell(defaultCell)
+export const providerLayer = providerLayerWithCell(defaultCell)
 
 export const node = makeGlobalNode({ service: Service, layer, deps: [] })
 

packages/core/src/session/compaction.ts

@@ -10,6 +10,7 @@ import { llmClient } from "../effect/app-node-platform"
 import { SessionEvent } from "./event"
 import type { SessionMessage } from "./message"
 import { SessionModelHeaders } from "./model-headers"
+import { SessionPromptCacheKey } from "./prompt-cache-key"
 import { App } from "../app"
 import { SessionRunnerModel } from "./runner/model"
 import { SessionSchema } from "./schema"
@@ -257,6 +258,7 @@ const make = (dependencies: Dependencies) => {
       .stream(
         LLM.request({
           model: plan.model,
+          cache: { mode: "auto", key: SessionPromptCacheKey.make(plan.session.id) },
           http: { headers: SessionModelHeaders.make(plan.session, dependencies.app) },
           messages: [Message.user(plan.prompt)],
           tools: [],

packages/core/src/session/generate-node.ts

@@ -11,6 +11,7 @@ import { SessionContext } from "./context"
 import { SessionGenerate } from "./generate"
 import { SessionHistory } from "./history"
 import { SessionModelHeaders } from "./model-headers"
+import { SessionPromptCacheKey } from "./prompt-cache-key"
 import { SessionRunnerModel } from "./runner/model"
 import PROMPT_DEFAULT from "./runner/prompt/base.txt"
 import { toLLMMessages } from "./runner/to-llm-message"
@@ -31,9 +32,6 @@ export const layer = Layer.effect(
         const model = yield* models.resolve(selection.session)
         const history = yield* SessionHistory.preview(database.db, selection.session.id, selection.instructions)
         const providerMetadataKey = model.model.route.providerMetadataKey ?? model.model.provider
-        const promptCacheKey = /^ses_[0-9a-f]{64}$/.test(selection.session.id)
-          ? selection.session.id.slice(4)
-          : selection.session.id
         const tools = selection.tools
         const toolDefinitions = tools.definitions
         const toolsByName = new Map(toolDefinitions.map((tool) => [tool.name, tool]))
@@ -71,7 +69,7 @@ export const layer = Layer.effect(
           LLM.request({
             model: model.model,
             http: { headers: SessionModelHeaders.make(selection.session, app) },
-            providerOptions: { [providerMetadataKey]: { promptCacheKey } },
+            cache: { mode: "auto", key: SessionPromptCacheKey.make(selection.session.id) },
             system: contextEvent.system,
             messages: contextEvent.messages,
             tools: hookedTools,

packages/core/src/session/model-request.ts

@@ -14,6 +14,7 @@ import { QuestionTool } from "../tool/plugin/question"
 import { Tool } from "../tool"
 import { SessionContext } from "./context"
 import { SessionModelHeaders } from "./model-headers"
+import { SessionPromptCacheKey } from "./prompt-cache-key"
 import { PromptCacheDiagnostics } from "./prompt-cache-diagnostics"
 import { MAX_STEPS_PROMPT } from "./runner/max-steps"
 import PROMPT_DEFAULT from "./runner/prompt/base.txt"
@@ -183,7 +184,6 @@ export const layer = Layer.effect(
       // The final Step keeps definitions available to protocols with native "none",
       // preserving their prompt cache prefix. Calls are still rejected at execution.
       const tools = input.context.tools
-      const promptCacheKey = /^ses_[0-9a-f]{64}$/.test(session.id) ? session.id.slice(4) : session.id
       const system = [agent.info.system ? agent.info.system : PROMPT_DEFAULT, input.context.initial]
         .filter((part) => part.length > 0)
         .map(SystemPart.make)
@@ -213,7 +213,7 @@ export const layer = Layer.effect(
         http: {
           headers: SessionModelHeaders.make(session, app),
         },
-        providerOptions: { [providerMetadataKey]: { promptCacheKey } },
+        cache: { mode: "auto", key: SessionPromptCacheKey.make(session.id) },
         system: contextEvent.system,
         messages: boundImages(unsupportedParts(contextEvent.messages, resolved.capabilities)),
         tools: hookedTools,

packages/core/src/session/prompt-cache-key.ts

@@ -0,0 +1,6 @@
+export * as SessionPromptCacheKey from "./prompt-cache-key"
+
+import { SessionSchema } from "./schema"
+
+export const make = (sessionID: SessionSchema.ID) =>
+  /^ses_[0-9a-f]{64}$/.test(sessionID) ? sessionID.slice(4) : sessionID

packages/core/src/session/title.ts

@@ -12,6 +12,7 @@ import { llmClient } from "../effect/app-node-platform"
 import { SessionEvent } from "./event"
 import { SessionHistory } from "./history"
 import { SessionModelHeaders } from "./model-headers"
+import { SessionPromptCacheKey } from "./prompt-cache-key"
 import { SessionRunnerModel } from "./runner/model"
 import { SessionSchema } from "./schema"
 import { SessionUsage } from "./usage"
@@ -80,6 +81,7 @@ const make = (dependencies: Dependencies) => {
       .stream(
         LLM.request({
           model: resolved.model,
+          cache: { mode: "auto", key: SessionPromptCacheKey.make(session.id) },
           http: { headers: SessionModelHeaders.make(session, dependencies.app) },
           system: agent.system,
           messages: [Message.user(firstUser.text)],

packages/core/src/v1/config/console-state.ts

@@ -0,0 +1,16 @@
+export * as ConfigConsoleStateV1 from "./console-state"
+
+import { Schema } from "effect"
+import { NonNegativeInt } from "../../schema"
+
+export class ConsoleState extends Schema.Class<ConsoleState>("ConsoleState")({
+  consoleManagedProviders: Schema.mutable(Schema.Array(Schema.String)),
+  activeOrgName: Schema.optional(Schema.String),
+  switchableOrgCount: NonNegativeInt,
+}) {}
+
+export const emptyConsoleState: ConsoleState = ConsoleState.make({
+  consoleManagedProviders: [],
+  activeOrgName: undefined,
+  switchableOrgCount: 0,
+})

packages/core/test/aisdk-native.test.ts

@@ -13,7 +13,6 @@ describe("AISDKNative", () => {
         models: ["anthropic/claude-sonnet-4.6"],
         provider: { only: ["anthropic"], require_parameters: true },
         reasoning: { effort: "high" },
-        promptCacheKey: "session_123",
         future_option: { enabled: true },
       }),
     ).toEqual({
@@ -24,7 +23,6 @@ describe("AISDKNative", () => {
             models: ["anthropic/claude-sonnet-4.6"],
             provider: { only: ["anthropic"], require_parameters: true },
             reasoning: { effort: "high" },
-            promptCacheKey: "session_123",
             future_option: { enabled: true },
           },
         },
@@ -105,7 +103,6 @@ describe("AISDKNative", () => {
         baseURL: "https://xai.example/v1",
         reasoningEffort: "custom",
         store: true,
-        promptCacheKey: "cache-key",
       }),
     ).toEqual({
       package: "@opencode-ai/ai/providers/xai",
@@ -116,7 +113,6 @@ describe("AISDKNative", () => {
           xai: {
             reasoningEffort: "custom",
             store: true,
-            promptCacheKey: "cache-key",
           },
         },
       },

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

@@ -0,0 +1,291 @@
+import { describe, expect } from "bun:test"
+import { $ } from "bun"
+import fs from "fs/promises"
+import path from "path"
+import { eq } from "drizzle-orm"
+import { Effect, Layer } from "effect"
+import { MoveSession } from "@opencode-ai/core/control-plane/move-session"
+import { Database } from "@opencode-ai/core/database/database"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { LayerNode } from "@opencode-ai/util/effect/layer-node"
+import { Bus } from "@opencode-ai/core/bus"
+import { Job } from "@opencode-ai/core/job"
+import { Project } from "@opencode-ai/core/project"
+import { ProjectDirectories } from "@opencode-ai/core/project/directories"
+import { AbsolutePath } from "@opencode-ai/core/schema"
+import { Session } from "@opencode-ai/core/session"
+import { SessionExecution } from "@opencode-ai/core/session/execution"
+import { SessionProjector } from "@opencode-ai/core/session/projector"
+import { SessionTable } from "@opencode-ai/core/session/sql"
+import { SessionStore } from "@opencode-ai/core/session/store"
+import { tmpdir } from "./fixture/tmpdir"
+import { testEffect } from "./lib/effect"
+
+// Records the execution serialization a move must perform before relocating.
+const executionCalls: string[] = []
+const recordingExecution = Layer.succeed(
+  SessionExecution.Service,
+  SessionExecution.Service.of({
+    active: Effect.succeed(new Set()),
+    resume: () => Effect.void,
+    wake: () => Effect.void,
+    interrupt: (sessionID) => Effect.sync(() => void executionCalls.push(`interrupt:${sessionID}`)),
+    awaitIdle: (sessionID) => Effect.sync(() => void executionCalls.push(`awaitIdle:${sessionID}`)),
+  }),
+)
+
+const it = testEffect(
+  AppNodeBuilder.build(
+    LayerNode.group([
+      MoveSession.node,
+      Database.node,
+      Bus.node,
+      ProjectDirectories.node,
+      Project.node,
+      Session.node,
+      SessionProjector.node,
+      SessionStore.node,
+    ]),
+    [[SessionExecution.node, recordingExecution]],
+  ),
+)
+
+function abs(input: string) {
+  return AbsolutePath.make(input)
+}
+
+async function initRepo(directory: string) {
+  await $`git init`.cwd(directory).quiet()
+  await $`git config core.autocrlf false`.cwd(directory).quiet()
+  await $`git config core.fsmonitor false`.cwd(directory).quiet()
+  await $`git config commit.gpgsign false`.cwd(directory).quiet()
+  await $`git config user.email test@opencode.test`.cwd(directory).quiet()
+  await $`git config user.name Test`.cwd(directory).quiet()
+  await fs.writeFile(path.join(directory, "tracked.txt"), "initial\n")
+  await $`git add tracked.txt`.cwd(directory).quiet()
+  await $`git commit -m root`.cwd(directory).quiet()
+}
+
+describe("MoveSession", () => {
+  it.live("moves session changes to another project directory", () =>
+    Effect.gen(function* () {
+      const root = yield* Effect.acquireRelease(
+        Effect.promise(() => tmpdir()),
+        (dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
+      )
+      yield* Effect.promise(() => initRepo(root.path))
+      const source = abs(yield* Effect.promise(() => fs.realpath(root.path)))
+      const destination = abs(`${root.path}-move-destination`)
+      yield* Effect.addFinalizer(() =>
+        Effect.promise(() => fs.rm(destination, { recursive: true, force: true })).pipe(Effect.ignore),
+      )
+      yield* Effect.promise(() => $`git worktree add --detach ${destination} HEAD`.cwd(root.path).quiet())
+      const moved = abs(yield* Effect.promise(() => fs.realpath(destination)))
+      yield* Effect.promise(() => fs.writeFile(path.join(source, "tracked.txt"), "changed\n"))
+      yield* Effect.promise(() => fs.writeFile(path.join(source, "untracked.txt"), "new\n"))
+
+      const projectID = (yield* Project.Service.use((service) => service.resolve(source))).id
+      const sessionID = Session.ID.make("ses_move")
+      const { db } = yield* Database.Service
+      yield* db
+        .insert(SessionTable)
+        .values({
+          id: sessionID,
+          project_id: projectID,
+          slug: "move",
+          directory: source,
+          title: "move",
+          version: "test",
+          time_created: 1,
+          time_updated: 1,
+        })
+        .run()
+        .pipe(Effect.orDie)
+
+      executionCalls.length = 0
+      yield* MoveSession.Service.use((service) =>
+        service.moveSession({ sessionID, destination: { directory: moved }, moveChanges: true }),
+      )
+
+      // The move stops active execution before any relocation side effect.
+      expect(executionCalls).toEqual([`interrupt:${sessionID}`, `awaitIdle:${sessionID}`])
+      expect(yield* Effect.promise(() => fs.readFile(path.join(moved, "tracked.txt"), "utf8"))).toBe("changed\n")
+      expect(yield* Effect.promise(() => fs.readFile(path.join(moved, "untracked.txt"), "utf8"))).toBe("new\n")
+      expect(yield* Effect.promise(() => fs.readFile(path.join(source, "tracked.txt"), "utf8"))).toBe("initial\n")
+      expect(yield* Effect.promise(() => Bun.file(path.join(source, "untracked.txt")).exists())).toBe(false)
+      expect(
+        yield* db
+          .select({ directory: SessionTable.directory, path: SessionTable.path })
+          .from(SessionTable)
+          .where(eq(SessionTable.id, sessionID))
+          .get(),
+      ).toEqual({ directory: moved, path: "" })
+    }),
+  )
+
+  it.live("moves within a checkout without transferring existing changes", () =>
+    Effect.gen(function* () {
+      const root = yield* Effect.acquireRelease(
+        Effect.promise(() => tmpdir()),
+        (dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
+      )
+      yield* Effect.promise(() => initRepo(root.path))
+      const source = abs(yield* Effect.promise(() => fs.realpath(root.path)))
+      const destination = abs(path.join(source, "packages"))
+      yield* Effect.promise(() => fs.writeFile(path.join(source, "tracked.txt"), "changed\n"))
+      yield* Effect.promise(() => fs.writeFile(path.join(source, "untracked.txt"), "new\n"))
+
+      const projectID = (yield* Project.Service.use((service) => service.resolve(source))).id
+      const sessionID = Session.ID.make("ses_move_nested")
+      const { db } = yield* Database.Service
+      yield* db
+        .insert(SessionTable)
+        .values({
+          id: sessionID,
+          project_id: projectID,
+          slug: "move-nested",
+          directory: source,
+          title: "move nested",
+          version: "test",
+          time_created: 1,
+          time_updated: 1,
+        })
+        .run()
+        .pipe(Effect.orDie)
+
+      const missing = yield* Session.Service.use((service) =>
+        service.move({ sessionID, directory: abs("packages") }).pipe(Effect.flip),
+      )
+      expect(missing._tag).toBe("Session.DestinationNotFoundError")
+      yield* Effect.promise(() => fs.mkdir(destination))
+
+      yield* MoveSession.Service.use((service) =>
+        service.moveSession({ sessionID, destination: { directory: abs("packages") }, moveChanges: true }),
+      )
+
+      expect(yield* Effect.promise(() => fs.readFile(path.join(source, "tracked.txt"), "utf8"))).toBe("changed\n")
+      expect(yield* Effect.promise(() => fs.readFile(path.join(source, "untracked.txt"), "utf8"))).toBe("new\n")
+      expect(
+        yield* db
+          .select({ directory: SessionTable.directory, path: SessionTable.path })
+          .from(SessionTable)
+          .where(eq(SessionTable.id, sessionID))
+          .get(),
+      ).toEqual({ directory: destination, path: "packages" })
+    }),
+  )
+
+  it.live("moves a session to another project", () =>
+    Effect.gen(function* () {
+      const root = yield* Effect.acquireRelease(
+        Effect.promise(() => tmpdir()),
+        (dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
+      )
+      yield* Effect.promise(() => initRepo(root.path))
+      const source = abs(yield* Effect.promise(() => fs.realpath(root.path)))
+      const destination = abs(`${root.path}-other-project`)
+      yield* Effect.acquireRelease(
+        Effect.promise(() => fs.mkdir(destination, { recursive: true })),
+        () => Effect.promise(() => fs.rm(destination, { recursive: true, force: true })),
+      )
+
+      const projectID = (yield* Project.Service.use((service) => service.resolve(source))).id
+      const destinationProjectID = (yield* Project.Service.use((service) => service.resolve(destination))).id
+      const sessionID = Session.ID.make("ses_move_project")
+      const { db } = yield* Database.Service
+      yield* db
+        .insert(SessionTable)
+        .values({
+          id: sessionID,
+          project_id: projectID,
+          slug: "move-project",
+          directory: source,
+          title: "move project",
+          version: "test",
+          time_created: 1,
+          time_updated: 1,
+        })
+        .run()
+        .pipe(Effect.orDie)
+
+      yield* Session.Service.use((service) =>
+        service.move({ sessionID, directory: destination }),
+      )
+
+      expect(
+        yield* db
+          .select({ projectID: SessionTable.project_id, directory: SessionTable.directory })
+          .from(SessionTable)
+          .where(eq(SessionTable.id, sessionID))
+          .get(),
+      ).toEqual({ projectID: destinationProjectID, directory: destination })
+    }),
+  )
+
+  it.live("moves nested session changes without cleaning unrelated files", () =>
+    Effect.gen(function* () {
+      const root = yield* Effect.acquireRelease(
+        Effect.promise(() => tmpdir()),
+        (dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
+      )
+      yield* Effect.promise(() => initRepo(root.path))
+      const source = abs(yield* Effect.promise(() => fs.realpath(root.path)))
+      const sourceDirectory = abs(path.join(source, "packages"))
+      yield* Effect.promise(() => fs.mkdir(sourceDirectory))
+      yield* Effect.promise(() => fs.writeFile(path.join(sourceDirectory, "tracked.txt"), "initial\n"))
+      yield* Effect.promise(() => fs.writeFile(path.join(sourceDirectory, "staged.txt"), "initial\n"))
+      yield* Effect.promise(() => $`git add packages/tracked.txt packages/staged.txt`.cwd(source).quiet())
+      yield* Effect.promise(() => $`git commit -m packages`.cwd(source).quiet())
+      const destination = abs(`${root.path}-move-nested-destination`)
+      yield* Effect.addFinalizer(() =>
+        Effect.promise(() => fs.rm(destination, { recursive: true, force: true })).pipe(Effect.ignore),
+      )
+      yield* Effect.promise(() => $`git worktree add --detach ${destination} HEAD`.cwd(source).quiet())
+      const moved = abs(path.join(yield* Effect.promise(() => fs.realpath(destination)), "packages"))
+      yield* Effect.promise(() => fs.writeFile(path.join(sourceDirectory, "tracked.txt"), "changed\n"))
+      yield* Effect.promise(() => fs.writeFile(path.join(sourceDirectory, "staged.txt"), "staged\n"))
+      yield* Effect.promise(() => $`git add packages/staged.txt`.cwd(source).quiet())
+      yield* Effect.promise(() => fs.writeFile(path.join(sourceDirectory, "untracked.txt"), "new\n"))
+      yield* Effect.promise(() => fs.writeFile(path.join(source, "tracked.txt"), "unrelated\n"))
+      yield* Effect.promise(() => fs.writeFile(path.join(source, "untracked.txt"), "unrelated\n"))
+
+      const projectID = (yield* Project.Service.use((service) => service.resolve(source))).id
+      const sessionID = Session.ID.make("ses_move_nested_checkout")
+      const { db } = yield* Database.Service
+      yield* db
+        .insert(SessionTable)
+        .values({
+          id: sessionID,
+          project_id: projectID,
+          slug: "move-nested-checkout",
+          directory: sourceDirectory,
+          title: "move nested checkout",
+          version: "test",
+          time_created: 1,
+          time_updated: 1,
+        })
+        .run()
+        .pipe(Effect.orDie)
+
+      yield* MoveSession.Service.use((service) =>
+        service.moveSession({ sessionID, destination: { directory: moved }, moveChanges: true }),
+      )
+
+      expect(yield* Effect.promise(() => fs.readFile(path.join(moved, "tracked.txt"), "utf8"))).toBe("changed\n")
+      expect(yield* Effect.promise(() => fs.readFile(path.join(moved, "staged.txt"), "utf8"))).toBe("staged\n")
+      expect(yield* Effect.promise(() => fs.readFile(path.join(moved, "untracked.txt"), "utf8"))).toBe("new\n")
+      expect(yield* Effect.promise(() => fs.readFile(path.join(sourceDirectory, "tracked.txt"), "utf8"))).toBe(
+        "initial\n",
+      )
+      expect(yield* Effect.promise(() => Bun.file(path.join(sourceDirectory, "untracked.txt")).exists())).toBe(false)
+      expect(yield* Effect.promise(() => fs.readFile(path.join(sourceDirectory, "staged.txt"), "utf8"))).toBe(
+        "staged\n",
+      )
+      expect(yield* Effect.promise(() => $`git status --porcelain -- packages/staged.txt`.cwd(source).text())).toBe(
+        "M  packages/staged.txt\n",
+      )
+      expect(yield* Effect.promise(() => fs.readFile(path.join(source, "tracked.txt"), "utf8"))).toBe("unrelated\n")
+      expect(yield* Effect.promise(() => fs.readFile(path.join(source, "untracked.txt"), "utf8"))).toBe("unrelated\n")
+    }),
+  )
+})

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

@@ -235,6 +235,7 @@ it.effect("manual compaction summarizes short context instead of no-op", () =>
     expect(Array.from(yield* Fiber.join(delta)).map((event) => event.data.text)).toEqual(["manual summary"])
 
     expect(requests).toHaveLength(1)
+    expect(requests[0]?.cache).toEqual({ mode: "auto", key: sessionID })
     expect(requests[0]?.http?.headers).toEqual({
       "x-session-affinity": sessionID,
       "X-Session-Id": sessionID,

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

@@ -287,7 +287,7 @@ it.effect("generates from fresh settled Session context without durable mutation
     expect(requests[0]?.system[0]?.text).toBe("Hooked system")
     expect(requests[0]?.system.map((part) => part.text)).toContain("Initial context")
     expect(requests[0]?.http?.headers).toMatchObject({ "X-Session-Id": sessionID })
-    expect(requests[0]?.providerOptions).toMatchObject({ openai: { promptCacheKey: sessionID } })
+    expect(requests[0]?.cache).toEqual({ mode: "auto", key: sessionID })
     const instructionUpdates = requests[0]?.messages.flatMap((message) =>
       message.role === "system"
         ? message.content.flatMap((content) => (content.type === "text" ? [content.text] : []))

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

@@ -3210,7 +3210,7 @@ describe("SessionRunnerLLM", () => {
       yield* stream.started
 
       expect(requests).toHaveLength(2)
-      expect(requests.map((request) => request.providerOptions?.openai?.promptCacheKey)).toEqual([
+      expect(requests.map((request) => (request.cache !== "none" ? request.cache?.key : undefined))).toEqual([
         sessionID,
         otherSessionID,
       ])
@@ -3241,7 +3241,7 @@ describe("SessionRunnerLLM", () => {
       yield* session.resume(longSessionID)
       yield* session.resume(otherLongSessionID)
 
-      const keys = requests.map((request) => request.providerOptions?.openai?.promptCacheKey)
+      const keys = requests.map((request) => (request.cache !== "none" ? request.cache?.key : undefined))
       expect(keys).toEqual([longSessionID.slice(4), otherLongSessionID.slice(4)])
       expect(keys.every((key) => typeof key === "string" && key.length === 64)).toBe(true)
       expect(keys[0]).not.toBe(keys[1])

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

@@ -153,6 +153,7 @@ it.effect("generates a title from the sole user message and renames the session"
     yield* title.generateForFirstPrompt(sessionID)
 
     expect(requests).toHaveLength(1)
+    expect(requests[0]?.cache).toEqual({ mode: "auto", key: sessionID })
     expect(requests[0]?.http?.headers).toEqual({
       "x-session-affinity": sessionID,
       "X-Session-Id": sessionID,

packages/theme/src/tui/index.ts

@@ -45,7 +45,6 @@ export type {
   StatefulColor,
 } from "./types.js"
 export { DEFAULT_CATEGORICAL, DEFAULT_THEME } from "./defaults.js"
-export { expandTheme } from "./expand.js"
 export { migrateV1 } from "./v1-migrate.js"
 export { resolveTheme, resolveThemeDocument, themeDecodeError } from "./resolve.js"
 export { selectTheme, selectThemeMode, supportsThemeMode, themeModes } from "./select.js"

packages/tui/package.json

@@ -93,6 +93,7 @@
     "@opentui/solid": "catalog:",
     "@solid-primitives/event-bus": "1.1.2",
     "clipboardy": "4.0.0",
+    "diff": "catalog:",
     "effect": "catalog:",
     "fuzzysort": "catalog:",
     "get-east-asian-width": "catalog:",

packages/tui/src/app.tsx

@@ -72,9 +72,9 @@ import { ThemeErrorToast } from "./component/theme-error-toast"
 import { ThemeProvider, useTheme, useThemes } from "./context/theme"
 import { Home } from "./routes/home"
 import { Session } from "./routes/session"
-import { PromptHistoryProvider } from "./prompt/history"
-import { FrecencyProvider } from "./prompt/frecency"
-import { PromptStashProvider } from "./prompt/stash"
+import { PromptHistoryProvider } from "./component/prompt/history"
+import { FrecencyProvider } from "./component/prompt/frecency"
+import { PromptStashProvider } from "./component/prompt/stash"
 import { Toast, ToastProvider, useToast } from "./ui/toast"
 import { isFallbackTitle } from "@opencode-ai/util/session-title-fallback"
 import * as Model from "./util/model"

packages/tui/src/attention.ts

@@ -5,6 +5,7 @@ import type {
   TuiAttentionNotifyResult,
   TuiAttentionNotifySkipReason,
   TuiAttentionWhen,
+  TuiKV,
   TuiAttentionSoundName,
   TuiAttentionSoundPack,
   TuiAttentionSoundPackInfo,
@@ -114,6 +115,8 @@ export function createTuiAttention(input: {
   renderer: AttentionRenderer
   config: Pick<Config.Resolved, "attention">
   update?: Config.Interface["update"]
+  /** @deprecated Ignored. Sound-pack persistence uses CLI config. */
+  kv?: TuiKV
   audio?: Pick<typeof TuiAudio, "loadSoundFile" | "play">
 }): TuiAttentionHost {
   let focus: FocusState = "unknown"

packages/tui/src/audio.ts

@@ -1,4 +1,4 @@
-import { Audio, type AudioErrorContext, type AudioPlayOptions, type AudioSound } from "@opentui/core"
+import { Audio, type AudioErrorContext, type AudioPlayOptions, type AudioSound, type AudioVoice } from "@opentui/core"
 import { readFile } from "node:fs/promises"
 
 let audio: Audio | null | undefined
@@ -42,6 +42,10 @@ export function play(sound: AudioSound, options?: AudioPlayOptions) {
   return current.play(sound, options)
 }
 
+export function stopVoice(voice: AudioVoice) {
+  return audio?.stopVoice(voice) ?? false
+}
+
 export function dispose() {
   audio?.dispose()
   audio = undefined

packages/tui/src/component/dialog-config.tsx

@@ -43,6 +43,15 @@ export const settings: Setting[] = [
     labels: ["off", "on"],
     keywords: ["motion", "effects"],
   },
+  {
+    title: "Onboarding",
+    category: "Appearance",
+    path: ["hints", "onboarding"],
+    default: true,
+    values: [false, true],
+    labels: ["off", "on"],
+    keywords: ["hints", "getting started", "guidance"],
+  },
   {
     title: "Sidebar",
     category: "Session",

packages/tui/src/component/dialog-stash.tsx

@@ -4,7 +4,7 @@ import { createMemo, createSignal } from "solid-js"
 import { Locale } from "../util/locale"
 import { Keymap } from "../context/keymap"
 import { useTheme } from "../context/theme"
-import { usePromptStash, type StashEntry } from "../prompt/stash"
+import { usePromptStash, type StashEntry } from "./prompt/stash"
 
 function getRelativeTime(timestamp: number): string {
   const now = Date.now()

packages/tui/src/component/prompt/frecency.tsx

@@ -0,0 +1 @@
+export * from "../../prompt/frecency"

packages/tui/src/component/prompt/history.tsx

@@ -0,0 +1 @@
+export * from "../../prompt/history"

packages/tui/src/component/prompt/stash.tsx

@@ -0,0 +1 @@
+export * from "../../prompt/stash"

packages/tui/src/component/session-tabs.tsx

@@ -6,7 +6,6 @@ import { useSessionTabs } from "../context/session-tabs"
 import { useTheme, useThemes } from "../context/theme"
 import {
   adaptiveSessionTabLayout,
-  moveSessionTab,
   NEW_SESSION_TAB_TITLE,
   sessionTabComplete,
   seedSessionTabMotion,
@@ -49,10 +48,6 @@ export function SessionTabs(props: { controller?: SessionTabsController; animati
   const animations = () => props.animations ?? config.animations ?? true
   const [hovered, setHovered] = createSignal<string>()
   const [dragging, setDragging] = createSignal<string>()
-  // A drag reorders a local preview and persists one move on release instead of writing
-  // per slot crossing; the preview holds after release until the store reflects the move,
-  // so the strip never flashes the pre-drag order while the write is in flight.
-  const [preview, setPreview] = createSignal<{ sessionID: string; index: number }>()
   let strip: { screenX: number } | undefined
   const hueStep = () => (mode() === "light" ? 800 : 200)
   const accent = () => theme.hue.accent[hueStep()]
@@ -60,18 +55,7 @@ export function SessionTabs(props: { controller?: SessionTabsController; animati
   const idleNumber = () => tint(theme.text.subdued, theme.background.default, 0.35)
   const newTab = () => tabs.newTab?.() ?? false
   const activeID = createMemo(() => (newTab() ? NEW_SESSION_TAB.sessionID : tabs.current()))
-  const ordered = createMemo(() => {
-    const pending = preview()
-    if (!pending) return tabs.tabs()
-    return moveSessionTab(tabs.tabs(), pending.sessionID, pending.index)
-  })
-  const items = createMemo(() => (newTab() ? [...ordered(), NEW_SESSION_TAB] : ordered()))
-  createEffect(() => {
-    const pending = preview()
-    if (!pending || dragging()) return
-    const index = tabs.tabs().findIndex((tab) => tab.sessionID === pending.sessionID)
-    if (index === -1 || index === Math.min(pending.index, tabs.tabs().length - 1)) setPreview(undefined)
-  })
+  const items = createMemo(() => (newTab() ? [...tabs.tabs(), NEW_SESSION_TAB] : tabs.tabs()))
   const layout = createMemo((previous: ReturnType<typeof adaptiveSessionTabLayout> | undefined) =>
     adaptiveSessionTabLayout(items(), activeID(), dimensions().width, previous?.start),
   )
@@ -295,8 +279,6 @@ export function SessionTabs(props: { controller?: SessionTabsController; animati
           // keeping sloppy clicks indistinguishable from clean ones.
           const release = () => {
             setDragging(undefined)
-            const pending = preview()
-            if (pending?.sessionID === tab.sessionID) tabs.move(pending.sessionID, pending.index)
             if (tab === NEW_SESSION_TAB) return
             tabs.select(tab.sessionID)
           }
@@ -313,8 +295,7 @@ export function SessionTabs(props: { controller?: SessionTabsController; animati
               onMouseDrag={(event) => {
                 if (tab === NEW_SESSION_TAB) return
                 const slot = slotAt(event.x)
-                if (slot !== undefined && slot !== tabNumber() - 1)
-                  setPreview({ sessionID: tab.sessionID, index: slot })
+                if (slot !== undefined && slot !== tabNumber() - 1) tabs.move(tab.sessionID, slot)
               }}
               onMouseDragEnd={release}
             >
@@ -360,9 +341,6 @@ export function SessionTabs(props: { controller?: SessionTabsController; animati
                   fg={closeColor()}
                   selectable={false}
                   onMouseUp={(event) => {
-                    // The close mark only renders while hovered; without motion events a click can
-                    // land here first, and must select the tab instead of closing it invisibly.
-                    if (hovered() !== tab.sessionID) return
                     event.stopPropagation()
                     tabs.close(tab === NEW_SESSION_TAB ? undefined : tab.sessionID)
                   }}

packages/tui/src/config/index.tsx

@@ -162,6 +162,11 @@ export const Info = Schema.Struct({
       }),
     }),
   ).annotate({ description: "Mini transcript presentation settings" }),
+  hints: Schema.optional(
+    Schema.Struct({
+      onboarding: Schema.optional(Schema.Boolean).annotate({ description: "Show getting-started guidance" }),
+    }),
+  ).annotate({ description: "In-product guidance settings" }),
   debug: Schema.optional(
     Schema.Struct({
       devtools: Schema.optional(Schema.Boolean).annotate({ description: "Show the DevTools debug bar" }),
@@ -262,3 +267,7 @@ export function useConfig() {
   if (!value) throw new Error("ConfigProvider is missing")
   return value
 }
+
+export function useConfigOptional() {
+  return useContext(ConfigContext)
+}

packages/tui/src/config/v1/keybind.ts

@@ -105,6 +105,8 @@ export const Definitions = {
   session_compact: keybind("<leader>c", "Compact the session"),
   session_queued_prompts: keybind("<leader>q", "View pending work"),
   session_child_first: keybind("down", "Toggle subagent picker"),
+  session_child_cycle: keybind("right", "Go to next child session"),
+  session_child_cycle_reverse: keybind("left", "Go to previous child session"),
   session_parent: keybind("up", "Go to parent session"),
   session_pin_toggle: keybind("ctrl+f", "Pin or unpin session in the session list"),
   session_quick_switch_1: keybind("<leader>1", "Switch to session in quick slot 1"),
@@ -306,6 +308,8 @@ export const CommandMap = {
   session_compact: "session.compact",
   session_queued_prompts: "session.queued_prompts",
   session_child_first: "session.child.first",
+  session_child_cycle: "session.child.next",
+  session_child_cycle_reverse: "session.child.previous",
   session_parent: "session.parent",
   session_pin_toggle: "session.pin.toggle",
   session_quick_switch_1: "session.quick_switch.1",

packages/tui/src/context/session-tabs-model.ts

@@ -29,11 +29,9 @@ export function openSessionTab(tabs: SessionTab[], tab: SessionTab): SessionTab[
   return tabs.map((item, position) => (position === index ? { ...item, title: tab.title } : item))
 }
 
-export function closeSessionTab(tabs: SessionTab[], sessionID: string) {
+export function closeSessionTab(tabs: readonly SessionTab[], sessionID: string) {
   const index = tabs.findIndex((tab) => tab.sessionID === sessionID)
-  // Like openSessionTab and moveSessionTab, a no-op returns the same reference so callers can
-  // detect it by identity.
-  if (index === -1) return { tabs, next: undefined }
+  if (index === -1) return { tabs: [...tabs], next: undefined }
   return {
     tabs: tabs.filter((tab) => tab.sessionID !== sessionID),
     next: tabs[index + 1]?.sessionID ?? tabs[index - 1]?.sessionID,
@@ -89,13 +87,9 @@ export function cycleSessionTab(tabs: readonly SessionTab[], active: string | un
   return tabs[(start + direction + tabs.length) % tabs.length]
 }
 
-// In-memory navigation history is bounded so a long-lived TUI does not accumulate one entry per
-// session switch forever; the oldest entries fall off first.
-const SESSION_TAB_HISTORY_LIMIT = 100
-
 export function recordSessionTabHistory(history: SessionTabHistory, sessionID: string): SessionTabHistory {
   if (history.entries[history.index] === sessionID) return history
-  const entries = [...history.entries.slice(0, history.index + 1), sessionID].slice(-SESSION_TAB_HISTORY_LIMIT)
+  const entries = [...history.entries.slice(0, history.index + 1), sessionID]
   return { entries, index: entries.length - 1 }
 }
 

packages/tui/src/context/session-tabs.tsx

@@ -73,8 +73,7 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
     function update(mutation: (draft: TabsState) => void) {
       const scope = config.tabs?.scope ?? "global"
       void updateStore((draft) => mutation(scope === "cwd" ? (draft.cwd[paths.cwd] ??= empty()) : draft.global)).catch(
-        // Failed writes lose only tab layout, but silence would hide tabs resetting every launch.
-        (error) => console.error("Failed to persist session tabs", error),
+        () => {},
       )
     }
 
@@ -223,7 +222,7 @@ export const { use: useSessionTabs, provider: SessionTabsProvider } = createSimp
     function remove(sessionID: string, navigate: boolean) {
       const target = root(sessionID)
       const closed = closeSessionTab(state().tabs, target)
-      if (closed.tabs === state().tabs) return
+      if (closed.tabs.length === state().tabs.length) return
       const selected = navigate && current() === target
       const previous = selected
         ? moveSessionTabHistory(recordSessionTabHistory(history, target), closed.tabs, target, -1)

packages/tui/src/editor-zed.ts

@@ -194,6 +194,10 @@ export function resolveZedDbPath() {
   return candidates.find((item) => isFile(item))
 }
 
+export function isZedTerminal() {
+  return process.env.ZED_TERM === "true" || process.env.TERM_PROGRAM?.toLowerCase() === "zed"
+}
+
 function isFile(item: string) {
   try {
     return statSync(item).isFile()
@@ -216,6 +220,11 @@ function zedWorkspacePaths(value: string | null) {
   return value.split(/\r?\n/).filter(Boolean)
 }
 
+export function offsetToPosition(text: string, offset: number) {
+  const stringOffset = utf8ByteOffsetToStringIndex(text, offset)
+  return offsetsToSelection(text, stringOffset, stringOffset).start
+}
+
 function utf8ByteOffsetToStringIndex(text: string, byteOffset: number) {
   if (byteOffset <= 0) return 0
 

packages/tui/src/feature-plugins/sidebar/lsp.tsx

@@ -0,0 +1,21 @@
+import { Plugin, usePlugin } from "@opencode-ai/plugin/tui"
+
+function View() {
+  const context = usePlugin()
+  const theme = context.theme
+  return (
+    <box>
+      <text fg={theme.text.default}>
+        <b>LSP</b>
+      </text>
+      <text fg={theme.text.subdued}>LSP status unavailable</text>
+    </box>
+  )
+}
+
+export default Plugin.define({
+  id: "opencode.sidebar-lsp",
+  setup(context) {
+    context.ui.slot("sidebar.content", () => <View />)
+  },
+})

packages/tui/src/feature-plugins/system/diff-viewer-file-tree-utils.ts

@@ -141,6 +141,22 @@ export function moveFileTreeSelectionToParent(rows: readonly FileTreeRow[], sele
   return rows.findLast((item, itemIndex) => itemIndex < index && item.depth < row.depth)?.id ?? selected
 }
 
+export function moveFileTreeSelectionToFile(
+  rows: readonly FileTreeRow[],
+  selected: number | undefined,
+  offset: number,
+) {
+  const fileRows = rows.filter((row) => row.fileIndex !== undefined)
+  if (fileRows.length === 0) return undefined
+  const selectedIndex = selected === undefined ? -1 : rows.findIndex((row) => row.id === selected)
+  if (selectedIndex === -1) return offset < 0 ? fileRows[fileRows.length - 1]!.id : fileRows[0]!.id
+  const next =
+    offset < 0
+      ? fileRows.findLast((row) => rows.findIndex((item) => item.id === row.id) < selectedIndex)
+      : fileRows.find((row) => rows.findIndex((item) => item.id === row.id) > selectedIndex)
+  return next?.id ?? (offset < 0 ? fileRows[0]!.id : fileRows[fileRows.length - 1]!.id)
+}
+
 export function fileTreeFileSelection(tree: FileTree, fileIndex: number) {
   const node = tree.nodes.find((item) => item.kind === "file" && item.fileIndex === fileIndex)
   if (!node) return undefined

packages/tui/src/logo.ts

@@ -7,3 +7,5 @@ export const go = {
   left: ["    ", "█▀▀▀", "█_^█", "▀▀▀▀"],
   right: ["    ", "█▀▀█", "█__█", "▀▀▀▀"],
 }
+
+export const marks = "_^~,"

packages/tui/src/plugin/builtins.ts

@@ -2,6 +2,7 @@ import HomeFooter from "../feature-plugins/home/footer"
 import PromptFooter from "../feature-plugins/prompt/footer"
 import SidebarContext from "../feature-plugins/sidebar/context"
 import SidebarFooter from "../feature-plugins/sidebar/footer"
+import SidebarLsp from "../feature-plugins/sidebar/lsp"
 import SidebarMcp from "../feature-plugins/sidebar/mcp"
 import DiffViewer from "../feature-plugins/system/diff-viewer"
 import Notifications from "../feature-plugins/system/notifications"
@@ -13,6 +14,7 @@ export const builtins = [
   PromptFooter,
   SidebarContext,
   SidebarMcp,
+  SidebarLsp,
   SidebarFooter,
   Notifications,
   Plugins,

packages/tui/src/routes/session/index.tsx

@@ -887,6 +887,22 @@ export function Session() {
         dialog.clear()
       },
     },
+    {
+      title: "Next subagent",
+      id: "session.child.next",
+      group: "Session",
+      palette: undefined,
+      enabled: !!session()?.parentID,
+      run: () => unavailable("Subagent navigation"),
+    },
+    {
+      title: "Previous subagent",
+      id: "session.child.previous",
+      group: "Session",
+      palette: undefined,
+      enabled: !!session()?.parentID,
+      run: () => unavailable("Subagent navigation"),
+    },
   ])
 
   const commands = createMemo(() =>
@@ -1909,6 +1925,122 @@ function UserMessage(props: { message: SessionMessageUser }) {
   )
 }
 
+function AssistantMessage(props: { message: SessionMessageAssistant; last: boolean }) {
+  const ctx = use()
+  const local = useLocal()
+  const theme = useTheme("elevated")
+  const model = createMemo(
+    () =>
+      ctx
+        .models()
+        .find((model) => model.providerID === props.message.model.providerID && model.id === props.message.model.id)
+        ?.name ?? `${props.message.model.providerID}/${props.message.model.id}`,
+  )
+
+  const final = createMemo(() => {
+    return props.message.finish && !["tool-calls", "unknown"].includes(props.message.finish)
+  })
+
+  const duration = createMemo(() => {
+    if (!final()) return 0
+    if (!props.message.time.completed) return 0
+    return props.message.time.completed - props.message.time.created
+  })
+
+  const exploration = createMemo(() => {
+    const grouped = new Map<string, { first: boolean; parts: SessionMessageAssistantTool[]; active: boolean }>()
+    if (!ctx.groupExploration()) return grouped
+    const runs = props.message.content
+      .map((part) =>
+        part.type === "tool" &&
+        ["read", "glob", "grep"].includes(toolDisplay(part.name)) &&
+        part.state.status !== "streaming"
+          ? part
+          : undefined,
+      )
+      .reduce<SessionMessageAssistantTool[][]>(
+        (runs, part) => {
+          if (part) runs[runs.length - 1].push(part)
+          if (!part && runs[runs.length - 1].length) runs.push([])
+          return runs
+        },
+        [[]],
+      )
+      .filter((run) => run.length > 0)
+    for (const run of runs) {
+      const summary = {
+        parts: run,
+        active: false,
+      }
+      run.forEach((part, index) => grouped.set(part.id, { ...summary, first: index === 0 }))
+    }
+    return grouped
+  })
+
+  return (
+    <>
+      <For each={props.message.content}>
+        {(content, index) => (
+          <Switch>
+            <Match when={content.type === "text"}>
+              <TextPart
+                part={content as SessionMessageAssistantText}
+                last={index() === props.message.content.length - 1}
+              />
+            </Match>
+            <Match when={content.type === "reasoning"}>
+              <ReasoningPart
+                part={content as SessionMessageAssistantReasoning}
+                message={props.message}
+                last={index() === props.message.content.length - 1}
+              />
+            </Match>
+            <Match when={content.type === "tool"}>
+              <Show when={exploration().get((content as SessionMessageAssistantTool).id)?.first !== false}>
+                <Show
+                  when={exploration().get((content as SessionMessageAssistantTool).id)}
+                  fallback={<ToolPart part={content as SessionMessageAssistantTool} />}
+                >
+                  {(summary) => <ExplorationSummary {...summary()} />}
+                </Show>
+              </Show>
+            </Match>
+          </Switch>
+        )}
+      </For>
+      <Show when={props.message.error}>
+        <box
+          border={["left"]}
+          paddingTop={1}
+          paddingBottom={1}
+          paddingLeft={2}
+          backgroundColor={theme.background.default}
+          customBorderChars={SplitBorder.customBorderChars}
+          borderColor={theme.text.feedback.error.default}
+        >
+          <text fg={theme.text.subdued}>{errorMessage(props.message.error)}</text>
+        </box>
+      </Show>
+      <AssistantRetry retry={props.message.retry} />
+      <Switch>
+        <Match when={props.last || final() || props.message.error}>
+          <box paddingLeft={3}>
+            <text>
+              <span style={{ fg: props.message.error ? theme.text.subdued : local.agent.color(props.message.agent) }}>
+                {Locale.titlecase(props.message.agent)}
+              </span>
+              <span style={{ fg: theme.text.subdued }}> · {model()}</span>
+              <Show when={duration()}>
+                <span style={{ fg: theme.text.subdued }}> · {Locale.duration(duration())}</span>
+              </Show>
+            </text>
+          </box>
+        </Match>
+      </Switch>
+    </>
+  )
+}
+
 function AssistantRetry(props: { retry: SessionMessageAssistant["retry"] }) {
   const theme = useTheme()
   return (
@@ -1924,6 +2056,40 @@ function AssistantRetry(props: { retry: SessionMessageAssistant["retry"] }) {
   )
 }
 
+function ExplorationSummary(props: { parts: SessionMessageAssistantTool[]; active: boolean }) {
+  const theme = useTheme()
+  const pathFormatter = usePathFormatter()
+  const label = (part: SessionMessageAssistantTool) => {
+    const input = typeof part.state.input === "string" ? {} : part.state.input
+    const tool = toolDisplay(part.name)
+    if (tool === "read") return `Read ${pathFormatter.format(stringValue(input.path))}`
+    if (tool === "glob") return `Glob "${stringValue(input.pattern)}"`
+    return `Grep "${stringValue(input.pattern)}"`
+  }
+  return (
+    <box flexDirection="column">
+      <InlineToolRow
+        icon="✱"
+        color={theme.text.subdued}
+        complete={!props.active}
+        pending="Exploring"
+        spinner={props.active}
+      >
+        {props.active ? "Exploring" : "Explored"}
+      </InlineToolRow>
+      <For each={props.parts}>
+        {(part, index) => (
+          <box paddingLeft={5}>
+            <text fg={part.state.status === "error" ? theme.text.feedback.error.default : theme.text.subdued}>
+              {index() === props.parts.length - 1 ? "└" : "├"} {label(part)}
+            </text>
+          </box>
+        )}
+      </For>
+    </box>
+  )
+}
+
 const INLINE_TOOL_ICON_WIDTH = 2
 
 function ReasoningPart(props: {
@@ -2788,6 +2954,10 @@ export function isBackgroundSubagent(
   return status === "completed" && metadata.status === "running"
 }
 
+export function formatSubagentRetry(attempt: number, message: string) {
+  return `Retrying (attempt ${attempt}) · ${message}`
+}
+
 type ExecuteCall = { tool: string; status: "running" | "completed" | "error"; input?: Record<string, unknown> }
 
 function executeCalls(value: unknown): ExecuteCall[] {

packages/tui/src/ui/dialog-alert.tsx

@@ -1,7 +1,7 @@
 import { TextAttributes } from "@opentui/core"
 import { Keymap } from "../context/keymap"
 import { useTheme } from "../context/theme"
-import { useDialog } from "./dialog"
+import { useDialog, type DialogContext } from "./dialog"
 
 export type DialogAlertProps = {
   title: string
@@ -56,3 +56,12 @@ export function DialogAlert(props: DialogAlertProps) {
     </box>
   )
 }
+
+DialogAlert.show = (dialog: DialogContext, title: string, message: string) => {
+  return new Promise<void>((resolve) => {
+    dialog.replace(
+      () => <DialogAlert title={title} message={message} onConfirm={() => resolve()} />,
+      () => resolve(),
+    )
+  })
+}

packages/tui/src/ui/dialog-confirm.tsx

@@ -1,7 +1,7 @@
 import { TextAttributes } from "@opentui/core"
 import { Keymap } from "../context/keymap"
 import { useTheme } from "../context/theme"
-import { useDialog } from "./dialog"
+import { useDialog, type DialogContext } from "./dialog"
 import { createStore } from "solid-js/store"
 import { For } from "solid-js"
 import { Locale } from "../util/locale"
@@ -17,6 +17,8 @@ export type DialogConfirmProps = {
   }
 }
 
+export type DialogConfirmResult = boolean | undefined
+
 export function DialogConfirm(props: DialogConfirmProps) {
   const dialog = useDialog()
   const theme = useTheme("elevated")
@@ -91,3 +93,20 @@ export function DialogConfirm(props: DialogConfirmProps) {
     </box>
   )
 }
+
+DialogConfirm.show = (dialog: DialogContext, title: string, message: string, label?: DialogConfirmProps["label"]) => {
+  return new Promise<DialogConfirmResult>((resolve) => {
+    dialog.replace(
+      () => (
+        <DialogConfirm
+          title={title}
+          message={message}
+          onConfirm={() => resolve(true)}
+          onCancel={() => resolve(false)}
+          label={label}
+        />
+      ),
+      () => resolve(undefined),
+    )
+  })
+}

packages/tui/src/ui/fade-file-path.tsx

@@ -0,0 +1,56 @@
+import type { RGBA } from "@opentui/core"
+import { createEffect, createMemo, createSignal, Show } from "solid-js"
+import { useConfig } from "../config"
+import { tint } from "../theme/color"
+import { createAnimatable, tween } from "./animation"
+import { FilePath } from "./file-path"
+
+// FilePath that crossfades when its value changes: the old path fades to the
+// background, the text swaps at the midpoint, and the new path fades back in.
+// The initial value renders immediately; only subsequent changes animate.
+export function FadeFilePath(props: {
+  value: string | undefined
+  maxWidth: number
+  fg: RGBA
+  bg: RGBA
+  basenameFg?: RGBA
+}) {
+  const config = useConfig().data
+  const fade = createAnimatable(
+    { front: 1 },
+    {
+      enabled: () => config.animations ?? true,
+      transition: tween({ duration: 0.3 }),
+    },
+  )
+  const [text, setText] = createSignal(props.value)
+  const [previous, setPrevious] = createSignal<string>()
+
+  createEffect((current: string | undefined) => {
+    const next = props.value
+    if (next === undefined || next === current) return current
+    setText(next)
+    if (current === undefined) return next
+    setPrevious(current)
+    fade.jump({ front: 0 })
+    fade.animate({ front: 1 })
+    return next
+  }, props.value)
+
+  const display = createMemo(() => (previous() !== undefined && fade.value().front < 0.5 ? previous() : text()))
+  const fg = createMemo(() => {
+    if (previous() === undefined || fade.value().front >= 1) return props.fg
+    return tint(props.bg, props.fg, Math.abs(fade.value().front * 2 - 1))
+  })
+
+  return (
+    <Show when={display() !== undefined}>
+      <FilePath
+        value={display() ?? ""}
+        maxWidth={props.maxWidth}
+        fg={fg()}
+        basenameFg={fade.value().front >= 1 ? props.basenameFg : undefined}
+      />
+    </Show>
+  )
+}

packages/tui/src/util/error.ts

@@ -143,3 +143,40 @@ export function errorMessage(error: unknown): string {
   if (formatted) return formatted
   return "unknown error"
 }
+
+export function errorData(error: unknown) {
+  if (error instanceof Error) {
+    return {
+      type: error.name,
+      message: errorMessage(error),
+      stack: error.stack,
+      cause: error.cause === undefined ? undefined : errorFormat(error.cause),
+      formatted: errorFormat(error),
+    }
+  }
+
+  if (!isRecord(error)) {
+    return {
+      type: typeof error,
+      message: errorMessage(error),
+      formatted: errorFormat(error),
+    }
+  }
+
+  const data = Object.getOwnPropertyNames(error).reduce<Record<string, unknown>>((acc, key) => {
+    const value = error[key]
+    if (value === undefined) return acc
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      acc[key] = value
+      return acc
+    }
+    // oxlint-disable-next-line no-base-to-string -- intentional coercion of arbitrary error properties
+    acc[key] = value instanceof Error ? value.message : String(value)
+    return acc
+  }, {})
+
+  if (typeof data.message !== "string") data.message = errorMessage(error)
+  if (typeof data.type !== "string") data.type = error.constructor?.name
+  data.formatted = errorFormat(error)
+  return data
+}

packages/tui/src/util/format.ts

@@ -0,0 +1,20 @@
+export function formatDuration(secs: number) {
+  if (secs <= 0) return ""
+  if (secs < 60) return `${secs}s`
+  if (secs < 3600) {
+    const mins = Math.floor(secs / 60)
+    const remaining = secs % 60
+    return remaining > 0 ? `${mins}m ${remaining}s` : `${mins}m`
+  }
+  if (secs < 86400) {
+    const hours = Math.floor(secs / 3600)
+    const remaining = Math.floor((secs % 3600) / 60)
+    return remaining > 0 ? `${hours}h ${remaining}m` : `${hours}h`
+  }
+  if (secs < 604800) {
+    const days = Math.floor(secs / 86400)
+    return days === 1 ? "~1 day" : `~${days} days`
+  }
+  const weeks = Math.floor(secs / 604800)
+  return weeks === 1 ? "~1 week" : `~${weeks} weeks`
+}

packages/tui/src/util/locale.ts

@@ -16,6 +16,19 @@ export function datetime(input: number): string {
   return `${localTime} · ${localDate}`
 }
 
+export function todayTimeOrDateTime(input: number): string {
+  const date = new Date(input)
+  const now = new Date()
+  const isToday =
+    date.getFullYear() === now.getFullYear() && date.getMonth() === now.getMonth() && date.getDate() === now.getDate()
+
+  if (isToday) {
+    return time(input)
+  } else {
+    return datetime(input)
+  }
+}
+
 export function number(num: number): string {
   if (num >= 1000000) {
     return (num / 1000000).toFixed(1) + "M"
@@ -95,4 +108,9 @@ export function truncateMiddle(str: string, maxLength: number = 35): string {
   return str.slice(0, keepStart) + ellipsis + str.slice(-keepEnd)
 }
 
+export function pluralize(count: number, singular: string, plural: string): string {
+  const template = count === 1 ? singular : plural
+  return template.replace("{}", count.toString())
+}
+
 export * as Locale from "./locale"

packages/tui/src/util/presentation.ts

@@ -1,4 +1,7 @@
-import { logo } from "../logo"
+const logo = {
+  left: ["                   ", "█▀▀█ █▀▀█ █▀▀█ █▀▀▄", "█__█ █__█ █^^^ █__█", "▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀~~▀"],
+  right: ["             ▄     ", "█▀▀▀ █▀▀█ █▀▀█ █▀▀█", "█___ █__█ █__█ █^^^", "▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀"],
+}
 
 const reset = "\x1b[0m"
 const bold = "\x1b[1m"

packages/tui/src/util/revert-diff.ts

@@ -0,0 +1,18 @@
+import { parsePatch } from "diff"
+
+export function getRevertDiffFiles(diffText: string) {
+  if (!diffText) return []
+
+  try {
+    return parsePatch(diffText).map((patch) => {
+      const filename = [patch.newFileName, patch.oldFileName].find((item) => item && item !== "/dev/null") ?? "unknown"
+      return {
+        filename: filename.replace(/^[ab]\//, ""),
+        additions: patch.hunks.reduce((sum, hunk) => sum + hunk.lines.filter((line) => line.startsWith("+")).length, 0),
+        deletions: patch.hunks.reduce((sum, hunk) => sum + hunk.lines.filter((line) => line.startsWith("-")).length, 0),
+      }
+    })
+  } catch {
+    return []
+  }
+}

packages/tui/test/cli/tui/inline-tool-wrap-snapshot.test.tsx

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, test } from "bun:test"
 import { For } from "solid-js"
 import { testRender, type JSX } from "@opentui/solid"
 import {
+  formatSubagentRetry,
   InlineToolRow,
   isBackgroundSubagent,
   parseApplyPatchFiles,
@@ -197,6 +198,10 @@ describe("TUI inline tool wrapping", () => {
     ).toEqual([{ message: "valid", range: { start: { line: 2, character: 3 } } }])
   })
 
+  test("keeps retry status ahead of wrapping messages", () => {
+    expect(formatSubagentRetry(2, "Rate limited by provider")).toBe("Retrying (attempt 2) · Rate limited by provider")
+  })
+
   test("labels only detached or async subagents as background", () => {
     expect(isBackgroundSubagent({ status: "running" }, "running")).toBeFalse()
     expect(isBackgroundSubagent({ status: "running" }, "completed")).toBeTrue()

packages/tui/test/context/session-tabs-model.test.ts

@@ -80,11 +80,6 @@ describe("session tabs", () => {
     expect(closeSessionTab([{ sessionID: "a" }], "a").next).toBeUndefined()
   })
 
-  test("closing an unknown session returns the same tabs reference", () => {
-    const tabs = [{ sessionID: "a" }, { sessionID: "b" }]
-    expect(closeSessionTab(tabs, "missing").tabs).toBe(tabs)
-  })
-
   test("cycles through a filtered tab set in either direction", () => {
     const tabs = ["a", "c", "e"].map((sessionID) => ({ sessionID }))
     expect(cycleSessionTab(tabs, "c", 1)?.sessionID).toBe("e")
@@ -127,15 +122,6 @@ describe("session tabs", () => {
     expect(recordSessionTabHistory(history, "b")).toBe(history)
   })
 
-  test("drops the oldest history entries beyond the limit", () => {
-    const sessions = Array.from({ length: 150 }, (_, index) => `session-${index}`)
-    const history = sessions.reduce(recordSessionTabHistory, { entries: [], index: -1 })
-
-    expect(history.entries.length).toBe(100)
-    expect(history.entries[0]).toBe("session-50")
-    expect(history.entries[history.index]).toBe("session-149")
-  })
-
   test("returns to the latest history entry when no tab is active", () => {
     const tabs = ["a", "b"].map((sessionID) => ({ sessionID }))
     const history = ["a", "b"].reduce(recordSessionTabHistory, { entries: [], index: -1 })

packages/tui/test/context/session-tabs.test.tsx

@@ -1,8 +1,8 @@
 /** @jsxImportSource @opentui/solid */
-import { afterAll, expect, test } from "bun:test"
+import { expect, test } from "bun:test"
 import type { OpenCodeEvent } from "@opencode-ai/client"
 import { testRender } from "@opentui/solid"
-import { mkdtempSync, readdirSync, rmSync, watch } from "fs"
+import { mkdtempSync, rmSync, watch } from "fs"
 import { tmpdir } from "os"
 import path from "path"
 import { ConfigProvider } from "../../src/config"
@@ -25,32 +25,8 @@ async function wait(fn: () => boolean | Promise<boolean>, timeout = 2_000) {
   }
 }
 
-// State directories are removed after the whole suite instead of per test: persistence writes are
-// fire-and-forget behind a file lock, so a teardown-time removal races any still-queued write.
-const stateDirs: string[] = []
-
-afterAll(async () => {
-  for (const dir of stateDirs) {
-    // Drain any lock still held by a late write before deleting the tree beneath it.
-    await wait(() => {
-      try {
-        return readdirSync(path.join(dir, "test", "locks")).length === 0
-      } catch {
-        return true
-      }
-    }).catch(() => undefined)
-    rmSync(dir, { recursive: true, force: true })
-  }
-})
-
-function stateDir(prefix: string) {
-  const dir = mkdtempSync(path.join(tmpdir(), prefix))
-  stateDirs.push(dir)
-  return dir
-}
-
 async function renderSessionTabs(initialSessionID: string, options?: { state?: string; title?: string }) {
-  const state = options?.state ?? stateDir("opencode-session-tabs-")
+  const state = options?.state ?? mkdtempSync(path.join(tmpdir(), "opencode-session-tabs-"))
   const events = createEventStream()
   const calls = createFetch((url) => {
     if (url.pathname !== `/api/session/${initialSessionID}`) return
@@ -108,6 +84,7 @@ async function renderSessionTabs(initialSessionID: string, options?: { state?: s
     emit: (event: OpenCodeEvent) => events.emit({ ...event, location: { directory } }),
     destroy() {
       app.renderer.destroy()
+      if (!options?.state) rmSync(state, { recursive: true, force: true })
     },
   }
 }
@@ -128,7 +105,7 @@ test("stores session tabs globally by default", async () => {
 })
 
 test("concurrent TUIs do not alternate shared tab titles from divergent session caches", async () => {
-  const state = stateDir("opencode-session-tabs-shared-")
+  const state = mkdtempSync(path.join(tmpdir(), "opencode-session-tabs-shared-"))
   let titled: Awaited<ReturnType<typeof renderSessionTabs>> | undefined
   let untitled: Awaited<ReturnType<typeof renderSessionTabs>> | undefined
 
@@ -167,6 +144,7 @@ test("concurrent TUIs do not alternate shared tab titles from divergent session
   } finally {
     titled?.destroy()
     untitled?.destroy()
+    rmSync(state, { recursive: true, force: true })
   }
 })
 

packages/tui/test/feature-plugins/diff-viewer-file-tree-utils.test.ts

@@ -6,6 +6,7 @@ import {
   flattenFileTree,
   moveFileTreeSelection,
   moveFileTreeSelectionToFirstChild,
+  moveFileTreeSelectionToFile,
   moveFileTreeSelectionToParent,
   movePatchFileIndex,
   orderedPatchFileIndexes,
@@ -218,6 +219,25 @@ describe("diff viewer file tree utilities", () => {
     expect(moveFileTreeSelectionToParent(rows, undefined)).toBeUndefined()
   })
 
+  test("moves file selection relative to the highlighted row", () => {
+    const rows = flattenFileTree(
+      buildFileTree([{ file: "src/config/tui.ts" }, { file: "src/session/index.ts" }, { file: "README.md" }]),
+    )
+    const config = rows.find((row) => row.kind === "directory" && row.name === "config")!
+    const session = rows.find((row) => row.kind === "directory" && row.name === "session")!
+    const tui = rows.find((row) => row.name === "tui.ts")!
+    const index = rows.find((row) => row.name === "index.ts")!
+    const readme = rows.find((row) => row.name === "README.md")!
+
+    expect(moveFileTreeSelectionToFile(rows, undefined, 1)).toBe(tui.id)
+    expect(moveFileTreeSelectionToFile(rows, undefined, -1)).toBe(readme.id)
+    expect(moveFileTreeSelectionToFile(rows, config.id, 1)).toBe(tui.id)
+    expect(moveFileTreeSelectionToFile(rows, session.id, -1)).toBe(tui.id)
+    expect(moveFileTreeSelectionToFile(rows, tui.id, 1)).toBe(index.id)
+    expect(moveFileTreeSelectionToFile(rows, index.id, -1)).toBe(tui.id)
+    expect(moveFileTreeSelectionToFile(rows, readme.id, 1)).toBe(readme.id)
+  })
+
   test("selects a file tree node and expands its parents for a patch file", () => {
     const tree = buildFileTree([{ file: "src/config/tui.ts" }, { file: "src/session/index.ts" }, { file: "README.md" }])
     const selection = fileTreeFileSelection(tree, 1)

packages/tui/test/keymap.test.tsx

@@ -46,7 +46,7 @@ test("legacy page key aliases compile as page keys", async () => {
 
 test("formats navigation keys as arrows", async () => {
   let read = () => ({}) as Record<string, string>
-  const commands = ["session.parent", "session.child.first"]
+  const commands = ["session.parent", "session.child.first", "session.child.previous", "session.child.next"]
 
   function Harness() {
     const shortcuts = Keymap.useShortcuts()
@@ -68,6 +68,8 @@ test("formats navigation keys as arrows", async () => {
     expect(read()).toEqual({
       "session.parent": "↑",
       "session.child.first": "↓",
+      "session.child.previous": "←",
+      "session.child.next": "→",
     })
   } finally {
     app.renderer.destroy()

packages/tui/test/mini/fixture/footer-api.ts

@@ -3,10 +3,6 @@ import type { FooterApi, FooterEvent, RunPrompt, StreamCommit } from "../../../s
 export function createFooterApiFixture(input: { events?: FooterEvent[]; commits?: StreamCommit[] } = {}) {
   const prompts = new Set<(input: RunPrompt) => void>()
   const closes = new Set<() => void>()
-  let ready!: () => void
-  const promptReady = new Promise<void>((resolve) => {
-    ready = resolve
-  })
   const events = input.events ?? []
   const commits = input.commits ?? []
   const calls: Array<{ type: "event"; value: FooterEvent } | { type: "commit"; value: StreamCommit }> = []
@@ -18,7 +14,6 @@ export function createFooterApiFixture(input: { events?: FooterEvent[]; commits?
     },
     onPrompt(fn) {
       prompts.add(fn)
-      ready()
       return () => prompts.delete(fn)
     },
     onClose(fn) {
@@ -55,12 +50,9 @@ export function createFooterApiFixture(input: { events?: FooterEvent[]; commits?
     events,
     commits,
     calls,
-    promptReady,
     submit(text: string, mode?: RunPrompt["mode"]) {
-      if (prompts.size === 0) return false
       const prompt: RunPrompt = mode ? { text, parts: [], mode } : { text, parts: [] }
       for (const fn of [...prompts]) fn(prompt)
-      return true
     },
   }
 }

packages/tui/test/mini/runtime.test.ts

@@ -55,9 +55,6 @@ describe("run interactive runtime", () => {
     const api = ui.api
     const selected = defer<Awaited<ReturnType<typeof sdk.model.default>>>()
     const catalogLoaded = defer<void>()
-    const defaultModelReloaded = defer<void>()
-    const modelShown = defer<void>()
-    const turnStarted = defer<void>()
     const model = catalogModel({
       id: "resolved",
       providerID: "test",
@@ -72,17 +69,7 @@ describe("run interactive runtime", () => {
       providers: [catalogProvider("test", "Test Provider")],
       models: [model],
     })
-    let defaultModelCalls = 0
-    const defaultModel = spyOn(sdk.model, "default").mockImplementation(() => {
-      defaultModelCalls++
-      if (defaultModelCalls === 2) defaultModelReloaded.resolve()
-      return selected.promise
-    })
-    const emit = api.event.bind(api)
-    api.event = (event) => {
-      emit(event)
-      if (event.type === "model") modelShown.resolve()
-    }
+    const defaultModel = spyOn(sdk.model, "default").mockImplementation(() => selected.promise)
 
     const task = runInteractiveDeferredMode(
       {
@@ -123,7 +110,6 @@ describe("run interactive runtime", () => {
               runPromptTurn: async (input) => {
                 turnAgent = input.agent
                 turnModel = input.model
-                turnStarted.resolve()
                 api.close()
               },
               queuePromptTurn: async () => {},
@@ -147,8 +133,8 @@ describe("run interactive runtime", () => {
       location: { directory: "/tmp", project: { id: "pro-1", directory: "/tmp", canonical: "/tmp" } },
       data: model,
     })
-    await defaultModelReloaded.promise
-    await modelShown.promise
+    while (defaultModel.mock.calls.length < 2) await Bun.sleep(0)
+    while (!events.some((event) => event.type === "model")) await Bun.sleep(0)
     expect(events).toContainEqual({
       type: "model",
       model: "Resolved Model · Test Provider",
@@ -156,9 +142,8 @@ describe("run interactive runtime", () => {
     })
     expect(lifecycle.onCycleVariant?.()).toMatchObject({ status: "variant low", variant: "low" })
     lifecycle.onAgentSelect?.("review")
-    await ui.promptReady
-    expect(ui.submit("hello")).toBe(true)
-    await turnStarted.promise
+    ui.submit("hello")
+    while (!turnModel) await Bun.sleep(0)
     expect(turnAgent).toBe("review")
     expect(turnModel).toEqual({ providerID: "test", modelID: "resolved" })
     await task

packages/tui/test/util/error.test.ts

@@ -1,16 +1,25 @@
 import { describe, expect, test } from "bun:test"
-import { errorFormat, errorMessage } from "../../src/util/error"
+import { errorData, errorFormat, errorMessage } from "../../src/util/error"
 
 describe("util.error", () => {
   test("formats native Error instances", () => {
     const err = new Error("boom")
     expect(errorMessage(err)).toBe("boom")
     expect(errorFormat(err)).toContain("boom")
+
+    const data = errorData(err)
+    expect(data.type).toBe("Error")
+    expect(data.message).toBe("boom")
+    expect(String(data.formatted)).toContain("boom")
   })
 
   test("extracts message from record-like values", () => {
     const err = { message: "bad input", code: "E_BAD" }
     expect(errorMessage(err)).toBe("bad input")
+
+    const data = errorData(err)
+    expect(data.message).toBe("bad input")
+    expect(data.code).toBe("E_BAD")
   })
 
   test("never returns bare {} for opaque object errors", () => {
@@ -32,5 +41,9 @@ describe("util.error", () => {
     }
 
     expect(errorMessage(err)).toBe("ResolveMessage: Cannot resolve module")
+
+    const data = errorData(err)
+    expect(data.message).toBe("ResolveMessage: Cannot resolve module")
+    expect(String(data.formatted)).toContain("ResolveMessage")
   })
 })

packages/tui/test/util/format.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test"
+import { formatDuration } from "../../src/util/format"
+
+describe("util.format", () => {
+  describe("formatDuration", () => {
+    test("returns empty string for zero or negative values", () => {
+      expect(formatDuration(0)).toBe("")
+      expect(formatDuration(-1)).toBe("")
+      expect(formatDuration(-100)).toBe("")
+    })
+
+    test("formats seconds under a minute", () => {
+      expect(formatDuration(1)).toBe("1s")
+      expect(formatDuration(30)).toBe("30s")
+      expect(formatDuration(59)).toBe("59s")
+    })
+
+    test("formats minutes under an hour", () => {
+      expect(formatDuration(60)).toBe("1m")
+      expect(formatDuration(61)).toBe("1m 1s")
+      expect(formatDuration(90)).toBe("1m 30s")
+      expect(formatDuration(120)).toBe("2m")
+      expect(formatDuration(330)).toBe("5m 30s")
+      expect(formatDuration(3599)).toBe("59m 59s")
+    })
+
+    test("formats hours under a day", () => {
+      expect(formatDuration(3600)).toBe("1h")
+      expect(formatDuration(3660)).toBe("1h 1m")
+      expect(formatDuration(7200)).toBe("2h")
+      expect(formatDuration(8100)).toBe("2h 15m")
+      expect(formatDuration(86399)).toBe("23h 59m")
+    })
+
+    test("formats days under a week", () => {
+      expect(formatDuration(86400)).toBe("~1 day")
+      expect(formatDuration(172800)).toBe("~2 days")
+      expect(formatDuration(259200)).toBe("~3 days")
+      expect(formatDuration(604799)).toBe("~6 days")
+    })
+
+    test("formats weeks", () => {
+      expect(formatDuration(604800)).toBe("~1 week")
+      expect(formatDuration(1209600)).toBe("~2 weeks")
+      expect(formatDuration(1609200)).toBe("~2 weeks")
+    })
+
+    test("handles boundary values correctly", () => {
+      expect(formatDuration(59)).toBe("59s")
+      expect(formatDuration(60)).toBe("1m")
+      expect(formatDuration(3599)).toBe("59m 59s")
+      expect(formatDuration(3600)).toBe("1h")
+      expect(formatDuration(86399)).toBe("23h 59m")
+      expect(formatDuration(86400)).toBe("~1 day")
+      expect(formatDuration(604799)).toBe("~6 days")
+      expect(formatDuration(604800)).toBe("~1 week")
+    })
+  })
+})

packages/tui/test/util/revert-diff.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test"
+import { getRevertDiffFiles } from "../../src/util/revert-diff"
+
+describe("revert diff", () => {
+  test("prefers the actual file path over /dev/null for added and deleted files", () => {
+    const files = getRevertDiffFiles(`diff --git a/new.txt b/new.txt
+new file mode 100644
+index 0000000..3b18e51
+--- /dev/null
++++ b/new.txt
+@@ -0,0 +1 @@
++new content
+diff --git a/old.txt b/old.txt
+deleted file mode 100644
+index 3b18e51..0000000
+--- a/old.txt
++++ /dev/null
+@@ -1 +0,0 @@
+-old content
+`)
+
+    expect(files).toEqual([
+      {
+        filename: "new.txt",
+        additions: 1,
+        deletions: 0,
+      },
+      {
+        filename: "old.txt",
+        additions: 0,
+        deletions: 1,
+      },
+    ])
+  })
+})