refactor(app): use downward undo icon for move back

refactor(prompt): compact move back controls
feat(prompt): move queued prompts back to input
2026-09-24 17:47:34 +00:00 · 2026-09-24 15:11:09 +00:00 · 2026-09-24 15:03:34 +00:00 · 2026-09-24 13:37:27 +00:00 · 2026-09-24 18:34:14 +05:30 · 2026-09-24 18:28:48 +05:30
465 changed files with 42477 additions and 4377 deletions
@@ -32,7 +32,7 @@
    },
    "packages/ai": {
      "name": "@opencode/ai",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@aws-sdk/credential-providers": "3.1057.0",
        "@opencode/schema": "workspace:*",
@@ -54,7 +54,7 @@
    },
    "packages/app": {
      "name": "@opencode/app",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@corvu/drawer": "catalog:",
        "@dnd-kit/abstract": "0.5.0",
@@ -112,7 +112,7 @@
    },
    "packages/cli": {
      "name": "@opencode/cli",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "bin": {
        "opencode": "./bin/opencode.cjs",
        "opencode2": "./bin/opencode2.cjs",
@@ -177,7 +177,7 @@
    },
    "packages/client": {
      "name": "@opencode/client",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opencode/protocol": "workspace:*",
        "@opencode/schema": "workspace:*",
@@ -203,7 +203,7 @@
    },
    "packages/codemode": {
      "name": "@opencode/codemode",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "acorn": "8.15.0",
        "effect": "catalog:",
@@ -216,7 +216,7 @@
    },
    "packages/console/app": {
      "name": "@opencode/console-app",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@cloudflare/vite-plugin": "1.15.2",
        "@ibm/plex": "6.4.1",
@@ -252,7 +252,7 @@
    },
    "packages/console/core": {
      "name": "@opencode/console-core",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@aws-sdk/client-sts": "3.782.0",
        "@jsx-email/render": "1.1.1",
@@ -279,7 +279,7 @@
    },
    "packages/console/function": {
      "name": "@opencode/console-function",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@openauthjs/openauth": "0.0.0-20250322224806",
        "@opencode/console-core": "workspace:*",
@@ -296,7 +296,7 @@
    },
    "packages/console/mail": {
      "name": "@opencode/console-mail",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@jsx-email/all": "2.2.3",
        "@jsx-email/cli": "1.4.3",
@@ -320,7 +320,7 @@
    },
    "packages/console/support": {
      "name": "@opencode/console-support",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@cloudflare/vite-plugin": "1.15.2",
        "@opencode/console-core": "workspace:*",
@@ -340,7 +340,7 @@
    },
    "packages/core": {
      "name": "@opencode/core",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@ai-sdk/cohere": "3.0.27",
        "@ai-sdk/gateway": "3.0.104",
@@ -368,7 +368,7 @@
        "drizzle-orm": "catalog:",
        "effect": "catalog:",
        "fuzzysort": "3.1.0",
-        "gitlab-ai-provider": "6.16.0",
+        "gitlab-ai-provider": "6.18.0",
        "google-auth-library": "10.5.0",
        "gray-matter": "4.0.3",
        "htmlparser2": "8.0.2",
@@ -408,7 +408,7 @@
    },
    "packages/desktop": {
      "name": "@opencode/desktop",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@zip.js/zip.js": "2.7.62",
        "electron-context-menu": "5.0.0",
@@ -457,7 +457,7 @@
    },
    "packages/enterprise": {
      "name": "@opencode/enterprise",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@hono/standard-validator": "catalog:",
        "@opencode-ai/sdk": "1.18.21",
@@ -494,7 +494,7 @@
    },
    "packages/function": {
      "name": "@opencode/function",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@octokit/auth-app": "8.0.1",
        "@octokit/rest": "catalog:",
@@ -510,7 +510,7 @@
    },
    "packages/http-recorder": {
      "name": "@opencode/http-recorder",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@effect/platform-node-shared": "4.0.0-rc.112",
      },
@@ -529,7 +529,7 @@
    },
    "packages/httpapi-codegen": {
      "name": "@opencode/httpapi-codegen",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "effect": "catalog:",
        "prettier": "3.6.2",
@@ -542,7 +542,7 @@
    },
    "packages/latex": {
      "name": "@opencode/latex",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opencode/plugin": "workspace:*",
        "@opentui/core": "catalog:",
@@ -556,7 +556,7 @@
    },
    "packages/merman": {
      "name": "@opencode/merman",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opencode/plugin": "workspace:*",
        "@opentui/core": "catalog:",
@@ -571,7 +571,7 @@
    },
    "packages/plugin": {
      "name": "@opencode/plugin",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@ai-sdk/provider": "3.0.8",
        "@opencode/ai": "workspace:*",
@@ -610,7 +610,7 @@
    },
    "packages/plugin-browser": {
      "name": "@opencode/plugin-browser",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opencode/plugin": "workspace:*",
        "@opencode/schema": "workspace:*",
@@ -640,7 +640,7 @@
    },
    "packages/protocol": {
      "name": "@opencode/protocol",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opencode/schema": "workspace:*",
        "effect": "catalog:",
@@ -655,7 +655,7 @@
    },
    "packages/schema": {
      "name": "@opencode/schema",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@standard-schema/spec": "catalog:",
        "effect": "catalog:",
@@ -679,7 +679,7 @@
    },
    "packages/sdk": {
      "name": "@opencode/sdk",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opencode/client": "workspace:*",
        "@opencode/core": "workspace:*",
@@ -700,7 +700,7 @@
    },
    "packages/server": {
      "name": "@opencode/server",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@effect/platform-node": "catalog:",
        "@effect/platform-node-shared": "catalog:",
@@ -722,7 +722,7 @@
    },
    "packages/session-ui": {
      "name": "@opencode/session-ui",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@kobalte/core": "catalog:",
        "@opencode/client": "workspace:*",
@@ -757,7 +757,7 @@
    },
    "packages/simulation": {
      "name": "@opencode/simulation",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opencode/ai": "workspace:*",
        "@opencode/core": "workspace:*",
@@ -777,7 +777,7 @@
    },
    "packages/stats/app": {
      "name": "@opencode/stats-app",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@ibm/plex": "6.4.1",
        "@kobalte/core": "catalog:",
@@ -811,7 +811,7 @@
    },
    "packages/stats/core": {
      "name": "@opencode/stats-core",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@aws-sdk/client-athena": "3.933.0",
        "@planetscale/database": "1.19.0",
@@ -830,7 +830,7 @@
    },
    "packages/stats/server": {
      "name": "@opencode/stats-server",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@aws-sdk/client-firehose": "3.933.0",
        "@effect/platform-node": "catalog:",
@@ -876,7 +876,7 @@
    },
    "packages/theme": {
      "name": "@opencode/theme",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opentui/core": "catalog:",
        "effect": "catalog:",
@@ -890,7 +890,7 @@
    },
    "packages/tui": {
      "name": "@opencode/tui",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@opencode/client": "workspace:*",
        "@opencode/core": "workspace:*",
@@ -925,7 +925,7 @@
    },
    "packages/ui": {
      "name": "@opencode/ui",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@kobalte/core": "catalog:",
        "@pierre/diffs": "catalog:",
@@ -960,7 +960,7 @@
    },
    "packages/util": {
      "name": "@opencode/util",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@effect/opentelemetry": "catalog:",
        "@effect/platform-node": "catalog:",
@@ -997,7 +997,7 @@
    },
    "packages/web": {
      "name": "@opencode/web",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "@astrojs/cloudflare": "12.6.3",
        "@astrojs/markdown-remark": "6.3.1",
@@ -1038,7 +1038,7 @@
    },
    "services/update": {
      "name": "@opencode/update",
-      "version": "2.0.15",
+      "version": "2.0.16",
      "dependencies": {
        "jose": "6.0.11",
        "semver": "catalog:",
@@ -4114,7 +4114,7 @@

    "github-slugger": ["github-slugger@2.0.0", "", {}, "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw=="],

-    "gitlab-ai-provider": ["gitlab-ai-provider@6.16.0", "", { "dependencies": { "@anthropic-ai/sdk": "^0.71.0", "@anycable/core": "^0.9.2", "graphql-request": "^6.1.0", "isomorphic-ws": "^5.0.0", "openai": "^6.16.0", "socket.io-client": "^4.8.1", "vscode-jsonrpc": "^8.2.1", "zod": "^3.25.76" }, "peerDependencies": { "@ai-sdk/provider": ">=3.0.0", "@ai-sdk/provider-utils": ">=4.0.0" } }, "sha512-HMC3sKgWYaYSsgm86Cnq2e6laHlYkhiFQ6rFD5qsVghv9//6h4Ofr7j5R2KjQx9Hl8EBercPsmzjoEjEN7dX5Q=="],
+    "gitlab-ai-provider": ["gitlab-ai-provider@6.18.0", "", { "dependencies": { "@anthropic-ai/sdk": "^0.71.0", "@anycable/core": "^0.9.2", "graphql-request": "^6.1.0", "isomorphic-ws": "^5.0.0", "openai": "^6.16.0", "socket.io-client": "^4.8.1", "vscode-jsonrpc": "^8.2.1", "zod": "^3.25.76" }, "peerDependencies": { "@ai-sdk/provider": ">=3.0.0", "@ai-sdk/provider-utils": ">=4.0.0" } }, "sha512-dXTXkNt1SFCL7jGlqazHL6iUJEug21qq0tx2s+Tui7jWNUqIAHEzY9WY1+PnZlhxvB56jPPBcFAT0attpjnopg=="],

    "glob": ["glob@13.0.5", "", { "dependencies": { "minimatch": "^10.2.1", "minipass": "^7.1.2", "path-scurry": "^2.0.0" } }, "sha512-BzXxZg24Ibra1pbQ/zE7Kys4Ua1ks7Bn6pKLkVPZ9FZe4JQS6/Q7ef3LG1H+k7lUf5l4T3PLSyYyYJVYUvfgTw=="],

@@ -1,8 +1,8 @@
 {
  "nodeModules": {
-    "x86_64-linux": "sha256-LQ1GAz1qF4R5P4j/kkgUygsQvxm7KStVlMf24nmyq44=",
-    "aarch64-linux": "sha256-PsNR3VaClA1O1vSE0z/Hb3XRT1pb6PvNRXuK+giIx6s=",
-    "aarch64-darwin": "sha256-7VCS+GT7tDYAMgqNCnLh1zvHAZkLTnJJ4vtfM88ruT8=",
-    "x86_64-darwin": "sha256-HyxXjiFVd8vcKvSb/BuHAY5Jj3MGgdXEvuhDuglp4ss="
+    "x86_64-linux": "sha256-+Clo0VPDdruHSoBNvV/wKAM8iR6HJPtB00oa8yl9ujU=",
+    "aarch64-linux": "sha256-4wU5v36GTXjwyt5ls4FH+5G43Ujd+dKVSJR21w3lhbA=",
+    "aarch64-darwin": "sha256-pThjoD6baddQ6biy7k1ByXwGwLAeWe/+w0tcYmt1uWs=",
+    "x86_64-darwin": "sha256-bCBl63CqBiqilb+YdaOLBYYZx/yf47c1aqgDOkgdegg="
  }
 }
@@ -2,7 +2,7 @@
  "$schema": "https://json.schemastore.org/package.json",
  "name": "opencode",
  "description": "AI-powered development tool",
-  "version": "2.0.15",
+  "version": "2.0.16",
  "private": true,
  "type": "module",
  "packageManager": "bun@1.4.2",
@@ -55,7 +55,7 @@ const request = LLM.request({
  prompt: "Say hello.",
 })

-const response = yield * LLMClient.generate(request)
+const response = yield * LLMClient.generate(request) // inside Effect.gen
 ```

 `LLM.request(...)` builds an `LLMRequest`. `LLMClient.generate(...)` reads the executable route carried by `request.model.route`, builds the provider-native body, asks the route's transport for a real `HttpClientRequest.HttpClientRequest`, sends it through `RequestExecutor.Service`, parses the provider stream into common `LLMEvent`s, and finally returns an `LLMResponse`.
@@ -98,7 +98,7 @@ When a provider supports multiple physical transports, selection remains executi

 Media does not fit the SSE-frames-to-event-state-machine LLM route. `MediaRoute.make(...)` (`src/route/media.ts`) composes a `MediaProtocol` kind with `Endpoint` and `Auth` and owns the transport plumbing: `http` option merging, URL/query rendering, auth headers, JSON vs multipart encoding, and handing the response back to the protocol. `MediaProtocol.inline` (`src/route/media-protocol.ts`) is `body.from(request)` plus `response.decode(response, context)`; use `MediaProtocol.decodeJson` / `text` / `bytes` so decode failures retain the raw body and HTTP context. `Generation` (`src/generation.ts`) is the provider-neutral handle for a queued generation over a `GenerationRoute` (`status`, `result`, `cancel`, `pollHint`). Image protocol files follow the same section order as LLM protocols and declare unsupported common fields once through `MediaInput.rejectUnsupported`.

-`MediaProtocol.queued` is the submit-then-poll kind every video route uses: `start` (body + decode into `{ token, snapshot }`), `status`, `result`, and optional `cancel`, each addressed by a route-owned `token` whose `Schema.Codec` makes it serializable. `MediaRoute.inline` and `MediaRoute.queued` compose the two kinds with `Endpoint` and `Auth`; the queued route decodes the token once at the boundary (`start` output or `resume` input) and closes over it in a token-free `GenerationRoute` (`status`/`result`/`cancel` are plain Effects), so `Generation` never sees the token's shape and only carries the encoded JSON for persistence. Polls reuse the route's auth and deployment headers plus the request's `http` overlay after `start`, and resolve relative paths against the route base URL (provider-issued absolute URLs such as fal's `status_url` pass through). `result` is always its own GET even when the provider returns output inside the status document, so `Generation.await` behaves the same after `start` and after `resume`. `PollContext.auth` carries only what `Auth` added so protocols can hand download credentials to output assets as transient `Media.Asset.headers` (Veo) — never part of `source` or JSON. Status strings map through a per-protocol `STATUS` table via `MediaProtocol.status`; terminal generations without output fail through `output.ended` / `output.contentPolicy` with the provider document on `reason.body`. `Generation.AwaitOptions` (`{ poll?: Poll }`) is the one options type for `await`, `events`, `Video.generate`, and `Video.stream`.
+`MediaProtocol.queued` is the submit-then-poll kind every video route uses: `start` (body + decode into `{ token, snapshot }`), `status`, `result`, and optional `cancel`, each addressed by a route-owned `token` whose `Schema.Codec` makes it serializable. `MediaRoute.inline` and `MediaRoute.queued` compose the two kinds with `Endpoint` and `Auth`; the queued route decodes the token once at the boundary (`start` output or `resume` input) and closes over it in a token-free `GenerationRoute` (`status`/`result`/`cancel` are plain Effects), so `Generation` never sees the token's shape and only carries the encoded JSON for persistence. Polls reuse the route's auth and deployment headers plus the request's `http` overlay after `start`, and resolve relative paths against the route base URL (provider-issued absolute URLs such as fal's `status_url` pass through). `result` is always its own GET even when the provider returns output inside the status document, so `Generation.await` behaves the same after `start` and after `resume`. `PollContext.auth` carries only what `Auth` added so protocols can hand download credentials to output assets as transient `Media.Asset.headers` (Veo) — never part of `source` or JSON. Status strings map through a per-protocol `STATUS` table via `MediaProtocol.status`; terminal generations without output fail through `output.ended` / `output.contentPolicy` with the provider document on `reason.body`. `GenerationAwaitOptions` (`AwaitOptions` in `src/generation.ts`, `{ poll?: Poll }`) is the one options type for `await`, `events`, `Video.generate`, and `Video.stream`.

 `MediaProtocol.stream` is the incremental kind every speech route uses, with the same discipline as LLM protocols. `MediaRoute.stream` submits the caller's request as `MediaProtocol.Addressed<Request>` (`{ ...request, mode }`, `mode: "generate" | "stream"`), so one provider stays one protocol: `body.from`, the endpoint path, and `frames` read `request.mode` to pick the body, path, and framing. `frames(bytes, context)` returns frames — `Framing.sse`, `Framing.lines`, `Framing.document` (a single-document response shaped like a streamed record), or the raw `bytes` for chunked audio. `initial()` is fresh per-response parser state; `step` folds each frame into it and emits modality events; `finish(state, context)` runs once after the last frame with the request, body, and observed `http` (header-only usage lives there) and emits exactly one terminal event or fails with `MediaProtocol.incomplete`. Keep parser state to real accumulators and derive anything the request or body determines in `finish`. `generate` runs the same stream and folds it with the modality's `collect`. Request-derived URL parameters go on the body's `query` (array values repeat the parameter), applied before route and caller `http.query`. Decode frames with `MediaProtocol.decodeFrame` and raise stream-time failures with `MediaProtocol.frameError` (the frame stays on `reason.body`); protocols never thread HTTP context, because the route fills `reason.http` on stream errors that lack it. Speech protocols share `protocols/utils/speech-stream.ts` for deltas, timestamps, voice ids, PCM and container descriptions, and the terminal asset.

@@ -1,11 +1,10 @@
 # @opencode/ai

-Schema-first language model and image-generation APIs built with Effect.
+Schema-first APIs for text, images, video, speech, and transcription, built with Effect.

 ```ts
-import { Effect, Layer } from "effect"
-import { LLM, LLMClient } from "@opencode/ai"
-import { RequestExecutor } from "@opencode/ai/route"
+import { Effect } from "effect"
+import { AIClient, LLM } from "@opencode/ai"
 import { OpenAI } from "@opencode/ai/providers"

 const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
@@ -18,23 +17,23 @@ const request = LLM.request({
 })

 const program = Effect.gen(function* () {
-  const response = yield* LLMClient.generate(request)
+  const response = yield* LLM.generate(request)
  console.log(response.text)
 })

-const llmLayer = LLMClient.layer.pipe(Layer.provide(RequestExecutor.fetchLayer))
-
-await Effect.runPromise(program.pipe(Effect.provide(llmLayer)))
+// Every modality client plus the HTTP request executor; `AIClient.layerWith(executor)` swaps the executor.
+await Effect.runPromise(program.pipe(Effect.provide(AIClient.layer)))
 ```

-Run `LLMClient.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses, Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.
+Run `LLM.stream(request)` instead of `generate` when you want incremental `LLMEvent`s. The event stream is provider-neutral — same shape across OpenAI Chat, OpenAI Responses,
+Anthropic Messages, Gemini, Bedrock Converse, and any OpenAI-compatible deployment.

-The same configured facade names image models. `Image.request` resolves the provider's image route from the ref and
-returns `Media.Asset`s with lazily decoded bytes:
+The same configured facade names image, video, speech, and transcription models. `Image.generate` resolves the
+provider's image route from the model and returns `Media.Asset`s with lazily decoded bytes:

 ```ts
 import { NodeFileSystem } from "@effect/platform-node"
-import { Image, ImageClient, Media } from "@opencode/ai"
+import { Image, Media } from "@opencode/ai"

 const image = Effect.gen(function* () {
  const response = yield* Image.generate({
@@ -46,13 +45,28 @@ const image = Effect.gen(function* () {
  yield* Media.write(response.image, "./garden.png")
 })

-// `asset.bytes()` / `Media.write` also need the executor, so merge it into the environment instead of hiding it.
-const imageLayer = ImageClient.layer.pipe(Layer.provideMerge(RequestExecutor.fetchLayer))
-
-await Effect.runPromise(image.pipe(Effect.provide(imageLayer), Effect.provide(NodeFileSystem.layer)))
+// `Media.file` / `Media.write` use the Effect `FileSystem` service; provide your platform's layer.
+await Effect.runPromise(image.pipe(Effect.provide(AIClient.layer), Effect.provide(NodeFileSystem.layer)))
 ```

-Prefer promises? `@opencode/ai/promise` exposes the same LLM and image APIs over one managed runtime:
+Advanced: each client also has its own `layer`, which requires `RequestExecutor.Service`. Compose client layers with
+`Layer.provideMerge`, not `Layer.provide`: `asset.bytes()`, `Media.write`, and Gemini's `media` output parts need the
+executor too, and hiding it fails type-checking with `RequestExecutorService` left in the requirements.
+
+To share a policy such as logging across every client, wrap the executor once with `RequestExecutor.middleware`:
+
+```ts
+import { RequestExecutor } from "@opencode/ai/route"
+
+const logged = RequestExecutor.middleware((request, next) =>
+  Effect.log(`${request.method} ${request.url}`).pipe(Effect.andThen(next(request))),
+)
+
+const everything = AIClient.layerWith(logged) // or AI.make({ layer: logged })
+```
+
+Prefer promises? `@opencode/ai/promise` exposes the same LLM and media APIs over one managed runtime, plus asset
+helpers; `ai.file` and `ai.write` load `node:fs/promises` on first use, so no Effect `FileSystem` is needed:

 ```ts
 import { AI } from "@opencode/ai/promise"
@@ -60,6 +74,7 @@ import { AI } from "@opencode/ai/promise"
 const ai = AI.make()
 const text = await ai.llm.generate({ model: openai.responses("gpt-4o-mini"), prompt: "Say hello." })
 const generated = await ai.image.generate({ model: openai.image("gpt-image-2"), prompt: "A lighthouse" })
+await ai.write(generated.image, "./lighthouse.png") // also ai.file(path), ai.bytes(asset), ai.base64(asset), ai.materialize(asset)
 for await (const event of ai.llm.stream({ model: openai.responses("gpt-4o-mini"), prompt: "Stream hello." })) {
  // LLMEvent
 }
@@ -322,10 +337,9 @@ and `moonshot/responses`; each exports `model(modelID, settings)`.
 MiniMax defaults to its Messages API and reads `MINIMAX_API_KEY` when `apiKey` is omitted:

 ```ts
-import { Effect, Layer } from "effect"
-import { LLM, LLMClient } from "@opencode/ai"
+import { Effect } from "effect"
+import { AIClient, LLM } from "@opencode/ai"
 import { MiniMax } from "@opencode/ai/providers"
-import { RequestExecutor } from "@opencode/ai/route"

 const minimax = MiniMax.configure({ apiKey: process.env.MINIMAX_API_KEY })
 const request = LLM.request({
@@ -335,8 +349,7 @@ const request = LLM.request({
  generation: { maxTokens: 1536 },
 })

-const layer = LLMClient.layer.pipe(Layer.provide(RequestExecutor.fetchLayer))
-const response = await Effect.runPromise(LLMClient.generate(request).pipe(Effect.provide(layer)))
+const response = await Effect.runPromise(LLM.generate(request).pipe(Effect.provide(AIClient.layer)))
 console.log(response.text)
 ```

@@ -405,14 +418,14 @@ Use `Image.generate` for one-off generation or editing:
 import { Image, Media } from "@opencode/ai"

 const generation = Image.generate({
-  model: meta("muse-image-1.0"),
+  model: meta.image("muse-image-1.0"),
  prompt: "A flat black square on a white background.",
  n: 1,
  providerOptions: { reasoningStrength: "low" },
 })

 const edit = Image.generate({
-  model: meta("muse-image-1.0"),
+  model: meta.image("muse-image-1.0"),
  prompt: "Make the square purple.",
  images: [Media.bytes(imageBytes, "image/webp")],
  format: "png",
@@ -459,6 +472,25 @@ const program = Effect.gen(function* () {
 })
 ```

+Common fields are portable in shape, not in support. Unsupported fields fail with a typed `AIError` before any network
+call rather than being dropped, so check this table before swapping only the `model`:
+
+| Provider              | `n` | `size`    | `aspectRatio` | `seed` | `format` | `images`                  | `mask`              |
+| --------------------- | --- | --------- | ------------- | ------ | -------- | ------------------------- | ------------------- |
+| OpenAI                | ✓¹  | ✓         | ✗             | ✗      | ✓        | ✓                         | ✓                   |
+| Google (Gemini)       | 1   | ✗         | ✓             | ✓      | ✗        | ✓ (no public URLs)        | ✗                   |
+| xAI                   | ✓   | ✗         | ✓             | ✗      | ✗        | ✓                         | ✗                   |
+| Z.ai                  | ✗   | ✓         | ✗             | ✗      | ✗        | ✗                         | ✗                   |
+| Meta                  | ✓   | ✓ (hint)  | ✗             | ✗      | ✓        | ✓                         | ✗                   |
+| Black Forest Labs     | 1   | per model | per model     | ✓      | ✓        | per model (1–8)           | `flux-pro-1.0-fill` |
+| fal                   | ✓   | per model | per model     | ✓      | ✓        | 1 (several on `/edit`)    | ✓                   |
+| Replicate             | ✗   | ✗         | ✗             | ✗      | ✗        | ✗ (use `providerOptions`) | ✗                   |
+| Stability `image`     | 1   | ✗         | ✓             | ✓      | ✓        | 1 (not on `core`)         | ✗                   |
+| Stability `upscale()` | ✗   | ✗         | ✗             | ✓      | ✓        | exactly 1 (required)      | ✗                   |
+
+✓ lowers natively; ✗ fails whenever the field is set (including `n: 1`); `1` means `n > 1` fails. ¹ `Image.stream` on OpenAI generates one image. fal
+rejects `size` and `aspectRatio` together; which one a fal or BFL model takes depends on the model.
+
 `Media.Asset` is the one asset type shared by image requests, image responses, LLM messages, and tool results.
 `asset.source` is the serializable `Media.Source` (`bytes`, `base64`, `url`, or `ref`); `asset.bytes()`,
 `asset.base64()`, and `asset.dataUrl()` decode or download lazily and cache; `asset.materialize()` pulls a `url`
@@ -468,9 +500,8 @@ asset into owned bytes before the provider URL expires. Construct assets with `M
 Pass ordered image inputs to the same method for editing, composition, or image-conditioned generation:

 ```ts
-const response =
-  yield *
-  Image.generate({
+const composed = Effect.gen(function* () {
+  const response = yield* Image.generate({
    model,
    prompt: "Combine these product photos into one studio scene",
    images: [
@@ -481,23 +512,25 @@ const response =
    providerOptions,
    http,
  })
+  return response.images
+})
 ```

 `Media.ref(provider, id)` represents provider file handles such as OpenAI file IDs or Gemini Files URIs; routes
-only forward refs that belong to their own provider. Raw strings are not accepted as image inputs, avoiding
-ambiguity between base64, URLs, and provider IDs. Empty or omitted `images` uses text-to-image generation; a
-non-empty array selects the provider's edit behavior without enforcing provider image-count limits locally. OpenAI
+only forward refs that belong to their own provider (OpenAI, xAI, and Gemini images accept them). No shipped route
+returns a ref yet, and `asset.bytes()` / `materialize()` on a ref fail by design. Raw strings are not accepted as
+image inputs, avoiding ambiguity between base64, URLs, and provider IDs. Empty or omitted `images` uses text-to-image generation; a
+non-empty array selects the provider's edit behavior (see the table above for routes that limit the count). OpenAI
 uses multipart for byte/data-URL edits and its JSON reference body for URL or file-ID edits. The common `mask`
 field selects inpainting; routes that cannot honor it fail with `UnsupportedOperation`:

 ```ts
-yield *
-  Image.generate({
-    model: openai.image("gpt-image-2"),
-    prompt,
-    images: [Media.bytes(sourceBytes, "image/png")],
-    mask: Media.bytes(maskBytes, "image/png"),
-  })
+const inpainted = Image.generate({
+  model: openai.image("gpt-image-2"),
+  prompt,
+  images: [Media.bytes(sourceBytes, "image/png")],
+  mask: Media.bytes(maskBytes, "image/png"),
+})
 ```

 On multipart requests, `http.body` can override option fields but not structural `model`, `prompt`, `image[]`,
@@ -508,31 +541,31 @@ not accept image inputs. These cases fail with a typed `AIError` before network
 Provider-native image options belong to each request. Raw `http.body` fields have final precedence over them:

 ```ts
-yield *
-  Image.generate({
-    model: openai.image("gpt-image-2"),
-    prompt,
-    providerOptions: { quality: "medium" },
-    http,
-  })
+const medium = Image.generate({
+  model: openai.image("gpt-image-2"),
+  prompt,
+  providerOptions: { quality: "medium" },
+  http,
+})
 ```

 xAI image models use the same request API with xAI-native controls:

 ```ts
-yield *
-  Image.generate({
-    model: XAI.configure({ apiKey })("any-model-id"),
-    prompt,
-    n: 2,
-    aspectRatio: "16:9",
-    providerOptions: {
-      resolution: "1k",
-      responseFormat: "b64_json",
-      future_option: true,
-    },
-    http,
-  })
+import { XAI } from "@opencode/ai/providers"
+
+const xai = Image.generate({
+  model: XAI.configure({ apiKey }).image("any-model-id"),
+  prompt,
+  n: 2,
+  aspectRatio: "16:9",
+  providerOptions: {
+    resolution: "1k",
+    responseFormat: "b64_json",
+    future_option: true,
+  },
+  http,
+})
 ```

 Google's current Gemini image models use the same direct API:
@@ -542,7 +575,7 @@ import { Google } from "@opencode/ai/providers"

 const googleProgram = Effect.gen(function* () {
  const response = yield* Image.generate({
-    model: Google.configure({ apiKey })("any-model-id"),
+    model: Google.configure({ apiKey }).image("any-model-id"),
    prompt: "A robot tending a rooftop garden",
    aspectRatio: "16:9",
    seed: 42,
@@ -567,17 +600,18 @@ their mapped aliases, and `http.body` is the final deep overlay. The selected mo
 Z.ai image models infer open Z.ai-native options from the selected model:

 ```ts
-yield *
-  Image.generate({
-    model: ZAI.configure({ apiKey })("any-model-id"),
-    prompt,
-    providerOptions: {
-      quality: "hd",
-      userID: "user-123",
-      future_option: true,
-    },
-    http,
-  })
+import { ZAI } from "@opencode/ai/providers"
+
+const zai = Image.generate({
+  model: ZAI.configure({ apiKey }).image("any-model-id"),
+  prompt,
+  providerOptions: {
+    quality: "hd",
+    userID: "user-123",
+    future_option: true,
+  },
+  http,
+})
 ```

 Z.ai does not include trustworthy MIME metadata for output URLs, so generated images use
@@ -591,12 +625,14 @@ and emits `image-partial` events before each final `image`; `Image.generate` kee
 `dall-e-*` models do not stream and fail typed:

 ```ts
-yield *
-  Image.stream({
-    model: openai.image("gpt-image-2"),
-    prompt: "A lighthouse at dusk",
-    providerOptions: { partialImages: 2 },
-  }).pipe(Stream.runForEach((event) => (ImageEvent.is.imagePartial(event) ? showPreview(event.image) : Effect.void)))
+import { Stream } from "effect"
+import { ImageEvent } from "@opencode/ai"
+
+const previews = Image.stream({
+  model: openai.image("gpt-image-2"),
+  prompt: "A lighthouse at dusk",
+  providerOptions: { partialImages: 2 },
+}).pipe(Stream.runForEach((event) => (ImageEvent.is.imagePartial(event) ? showPreview(event.image) : Effect.void)))
 ```

 The provider may send fewer previews than requested when the final image is ready first.
@@ -612,13 +648,20 @@ import { BlackForestLabs, Stability } from "@opencode/ai/providers"

 const bfl = BlackForestLabs.configure({ apiKey: process.env.BFL_API_KEY })

-const generation = yield * Image.start({ model: bfl.image("flux-2-pro"), prompt, size: "1024x768" })
-persist(generation.token)
+const submit = Effect.gen(function* () {
+  const generation = yield* Image.start({ model: bfl.image("flux-2-pro"), prompt, size: "1024x768" })
+  persist({ provider: "black-forest-labs", modelID: "flux-2-pro", token: generation.token })
+})

-const resumed = yield * Image.resume(bfl.image("flux-2-pro"), loadToken())
-const response = yield * resumed.await({ poll: { interval: "2 seconds" } })
+const finish = Effect.gen(function* () {
+  const saved = load()
+  const resumed = yield* Image.resume(bfl.image(saved.modelID), saved.token)
+  return yield* resumed.await({ poll: { interval: "2 seconds" } })
+})
 ```

+The token carries no route identity, so persist the provider and model ID alongside it: `resume` needs the model.
+
 - **Black Forest Labs** — results are downloaded before returning, because `result.sample` expires in 10 minutes.
 - **Replicate** — inputs are model-defined, so only `prompt` lowers: sizing, count, seed, format, and files go in
  `providerOptions` under the model's names, with files as `Media.Asset` (data URLs up to 256 KB, larger by URL).
@@ -628,12 +671,13 @@ const response = yield * resumed.await({ poll: { interval: "2 seconds" } })

 ```ts
 const stability = Stability.configure({ apiKey: process.env.STABILITY_API_KEY })
-const upscaled =
-  yield *
-  Image.generate(
-    { model: stability.upscale(), prompt: "A lighthouse", images: [yield * Media.file("./small.png")] },
+const upscaled = Effect.gen(function* () {
+  const small = yield* Media.file("./small.png")
+  return yield* Image.generate(
+    { model: stability.upscale(), prompt: "A lighthouse", images: [small] },
    { poll: { interval: "5 seconds" } },
  )
+})
 ```

 Imagen is not available: Google shut it down on the Gemini API, and Vertex discontinued the Imagen 4 models on
@@ -666,8 +710,8 @@ Common fields (`frames`, `references`, `video`, `durationSeconds`, `aspectRatio`
 under `providerOptions`, inferred from the selected model.

 ```ts
-import { Video, VideoClient } from "@opencode/ai"
-import { Google } from "@opencode/ai/providers"
+import { Video } from "@opencode/ai"
+import { Google, Runway } from "@opencode/ai/providers"

 const google = Google.configure({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY })

@@ -696,6 +740,7 @@ const controlled = Effect.gen(function* () {
  generation.id // provider operation / task / request id
  generation.status // "queued" | "running" | "completed" | "failed" | "cancelled" | "expired"
  generation.token // route-owned JSON: `{ operation }`, `{ requestID }`, `{ taskID }`, or fal's follow-up URLs
+  // The token carries no route identity: persist the provider and model ID alongside it, since `resume` needs the model.
  const saved = JSON.stringify(generation.token)

  const resumed = yield* Video.resume(google.video("veo-3.1-generate-preview"), JSON.parse(saved))
@@ -706,8 +751,8 @@ const controlled = Effect.gen(function* () {
 const events = Video.stream({ model: Runway.configure({ apiKey }).video("gen4.5"), prompt }, { poll })
 ```

-`VideoClient.layer` needs `RequestExecutor.Service`, and status polls, result fetches, cancels, and asset downloads
-all run through the same executor with the route's auth. `Generation.await` and `Generation.events` fail with a
+Status polls, result fetches, cancels, and asset downloads all run through the same request executor with the route's
+auth. `Generation.await` and `Generation.events` fail with a
 `Timeout` reason when `poll.timeout` (default 10 minutes) elapses. Failed,
 cancelled, and expired generations fail typed with the provider's terminal document on `reason.body`; moderation
 outcomes (Veo `raiMediaFilteredReasons`, xAI `respect_moderation`, Runway `SAFETY.*` codes) surface as `notices` when
@@ -726,15 +771,18 @@ Provider notes:
 - **Runway** expects pixel ratios in `aspectRatio` for most models (`"1280:720"`), pins `X-Runway-Version`, reports
  `usage: { type: "credits" }`, and its output URLs expire after 24–48 hours.

-The promise client exposes the same surface: `ai.video.start(...)` resolves to a handle with `await`, `refresh`,
-`cancel`, and `token`; `ai.video.generate`, `ai.video.resume(model, token)`, and `ai.video.stream` mirror the Effect
-API.
+The promise client exposes the same surface: `ai.video.start(...)` resolves to a handle with `await`, `events`,
+`result`, `refresh`, `cancel`, and `token`; `ai.video.generate`, `ai.video.resume(model, token)`, and
+`ai.video.stream` mirror the Effect API. The handle's `status` and `progress` are a snapshot from when it was
+created; `refresh()` resolves to a new handle.

 ```ts
 import { ai } from "@opencode/ai/promise"

 const generation = await ai.video.start({ model, prompt })
-const video = await generation.await({ poll: { interval: 10_000 }, signal })
+for await (const event of generation.events({ poll: { interval: 10_000 } })) console.log(event.type)
+const video = await generation.result({ signal })
+await ai.write(video.video, "./kite.mp4")
 ```

 ## Speech generation
@@ -786,7 +834,6 @@ ElevenLabs and Cartesia. `{ id }` selects an OpenAI custom voice (`{ id: "voice_
 plain string elsewhere. There is no cross-provider voice catalog. `format` is the container-level word (`mp3`, `wav`,
 `pcm`, `opus`, `aac`, `flac`); sample rates and bitrates live under `providerOptions`, and a value the route cannot
 produce fails as `UnsupportedOperation`. Streams buffer every chunk so `finish` can carry the whole clip.
-`SpeechClient.layer` needs `RequestExecutor.Service`.

 Provider notes:

@@ -814,7 +861,7 @@ The promise client mirrors the Effect API; `ai.speech.stream` is an `AsyncIterab
 import { ai } from "@opencode/ai/promise"

 const response = await ai.speech.generate({ model, text: "Hello from OpenCode.", voice: "coral" })
-await Bun.write("hello.mp3", await ai.run(response.audio.bytes()))
+await ai.write(response.audio, "hello.mp3")

 for await (const event of ai.speech.stream({ model, text: "Hello from OpenCode.", voice: "coral" })) {
  if (event.type === "audio-delta") player.write(event.chunk)
@@ -831,6 +878,7 @@ facades. Common fields (`language`, `prompt`, `timestamps: "none" | "segment" |
 natively or fail with a typed `AIError` before any network call; a route may return more than asked.

 ```ts
+import { Console, Effect, Stream } from "effect"
 import { Media, Transcription, TranscriptionEvent } from "@opencode/ai"
 import { AssemblyAI, Deepgram, OpenAI } from "@opencode/ai/providers"

@@ -857,7 +905,7 @@ const program = Effect.gen(function* () {
    Stream.runDrain,
  )

-  // Queued: persist the token, resume from another process, and await.
+  // Queued: persist the token with the provider and model ID (the token alone cannot pick the model), resume, and await.
  const model = AssemblyAI.configure({ apiKey }).transcription("universal-3-5-pro")
  const generation = yield* Transcription.start({ model, audio })
  const resumed = yield* Transcription.resume(model, JSON.parse(JSON.stringify(generation.token)))
@@ -866,7 +914,7 @@ const program = Effect.gen(function* () {
 ```

 Inline routes emit only `finish` from `stream` (no faked deltas); queued routes emit `generation-queued` /
-`generation-progress` before it. `TranscriptionClient.layer` needs `RequestExecutor.Service`.
+`generation-progress` before it.

 Provider notes:

@@ -878,6 +926,7 @@ Provider notes:
 The promise client mirrors the Effect API:

 ```ts
+const audio = await ai.file("./call.mp3")
 const text = (await ai.transcription.generate({ model, audio })).text
 for await (const event of ai.transcription.stream({ model, audio })) if (event.type === "text-delta") write(event.delta)
 const generation = await ai.transcription.start({ model: assemblyai, audio })
@@ -897,7 +946,8 @@ const transcript = await generation.await({ poll: { interval: 3_000 } })
 - **`Generation`** — provider-neutral handle for an in-flight media generation (`await`, `refresh`, `cancel`, `events`) used by queued media routes.
 - **`Speech.request` / `Speech.generate` / `Speech.stream`** — text-to-speech through a provider-neutral request; `SpeechClient` is its Effect service and layer.
 - **`Transcription.request` / `generate` / `stream` / `start` / `resume`** — speech-to-text over inline, streaming, and queued routes; `TranscriptionClient` is its Effect service and layer.
- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, and `transcription` as Promise / `AsyncIterable` APIs.
+- **`AIClient.layer` / `AIClient.layerWith(executor)`** — every modality client plus the request executor in one layer.
+- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, `speech`, and `transcription` as Promise / `AsyncIterable` APIs, plus `file`, `write`, `bytes`, `base64`, and `materialize` for assets.

 ## Testing

@@ -960,11 +1010,13 @@ This is different from prompt caching, server-side history storage, or truncatio
 Prefer this operation, where supported, when the application owns compaction policy and durable context updates.

 ```ts
-const result = yield * LLMClient.compact(request)
-const next = LLMRequest.update(request, {
-  messages: result.replacement,
+const compacted = Effect.gen(function* () {
+  const result = yield* LLMClient.compact(request)
+  const next = LLMRequest.update(request, {
+    messages: result.replacement,
+  })
+  return yield* LLMClient.generate(next)
 })
-const response = yield * LLMClient.generate(next)
 ```

 `replacement` replaces the complete input window. Do not append it to the original transcript or extract only the encrypted item: the provider may retain additional messages in its output. Retained user and assistant messages remain ordinary messages with typed text, media, or reasoning parts, in their original order. Provider-specific message IDs, status, and phase use `providerMetadata`, not a raw output array hidden in an assistant message. Unsupported returned item types fail explicitly.
@@ -980,16 +1032,16 @@ The input must still fit the model's context window. Explicit compaction is not
 OpenAI Responses also exposes a separate, explicitly selected mechanism:

 ```ts
-const result =
-  yield *
-  LLMClient.compact(request, {
+const checkpoint = Effect.gen(function* () {
+  const result = yield* LLMClient.compact(request, {
    mechanism: "trigger",
    webSocket, // Optional: without it, the request uses HTTP/SSE.
  })

-result.checkpoint // Successful encrypted CompactionPart.
-result.responseID
-result.usage
+  result.checkpoint // Successful encrypted CompactionPart.
+  result.responseID
+  result.usage
+})
 ```

 This appends a native `compaction_trigger` control item to the full input and sends a normal Responses request, with tools and instructions retained, `stream: true`, `store: false`, and parallel tool calls enabled. It removes normal-answer text/output-format controls, forced tool choices, output-token/tool-call limits, and automatic `context_management`. Body overlays cannot replace `input` or supply `previous_response_id`/`conversation`; the complete canonical history is required for safe stateless replay. Request metadata, auth, headers, query parameters, service tier, and supported prompt-cache settings are preserved.
@@ -1003,9 +1055,11 @@ The supplied WebSocket executor can reuse a compatible append baseline for the c
 Trigger support is separate from endpoint support. Only the OpenAI Responses route advertises it; Azure, xAI, Chat, and compatible Responses routes do not inherit it. Untyped calls still fail before sending: missing route capabilities return `UnsupportedOperation`, while unknown mechanism names and invalid inputs return `InvalidRequest`. Dynamic callers must narrow for the selected mechanism:

 ```ts
-if (LLMClient.canCompact(request, { mechanism: "trigger" })) {
-  const result = yield * LLMClient.compact(request, { mechanism: "trigger" })
-}
+const narrowed = Effect.gen(function* () {
+  if (LLMClient.canCompact(request, { mechanism: "trigger" })) {
+    const result = yield* LLMClient.compact(request, { mechanism: "trigger" })
+  }
+})
 ```

 This capability describes protocol implementation, **not universal availability on OpenAI API deployments**. The host application owns subscription/deployment eligibility, OAuth, endpoint selection, and deployment-specific headers. Local protocol/socket tests do not establish live provider support.
@@ -1014,9 +1068,10 @@ This capability describes protocol implementation, **not universal availability

 `providerOptions.contextManagement` lets the provider decide when to compact during an ordinary `generate` or `stream` call. This is an advanced option for callers that own persistence and recovery: persist the complete assistant message, including its checkpoint, before continuing. Enabling the option does not provide durable checkpoint storage, interruption recovery, or model-switch policy. Keep the prior context until a successful checkpoint has been persisted.

-Inside an `Effect.gen`, enable OpenAI compaction with typed provider options:
+Enable OpenAI compaction with typed provider options:

 ```ts
+import { Effect } from "effect"
 import { LLM, LLMClient, LLMRequest, Message } from "@opencode/ai"
 import { OpenAI } from "@opencode/ai/providers"

@@ -1027,9 +1082,11 @@ const request = LLM.request({
    contextManagement: [{ type: "compaction", compactThreshold: 200_000 }],
  },
 })
-const response = yield * LLMClient.generate(request)
-const next = LLMRequest.update(request, {
-  messages: [...request.messages, response.message, Message.user("Continue")],
+const continued = Effect.gen(function* () {
+  const response = yield* LLMClient.generate(request)
+  return LLMRequest.update(request, {
+    messages: [...request.messages, response.message, Message.user("Continue")],
+  })
 })
 ```

@@ -1257,7 +1314,7 @@ Compose a route with `Route.make({ protocol, endpoint, auth, framing, ... })`. T

 ## Effect

-This package is built on Effect. Public methods return `Effect` or `Stream`; provide `LLMClient.layer` for LLM dispatch and `ImageClient.layer` for image dispatch, then import the provider/protocol modules for the routes you use. The example at `example/tutorial.ts` is a runnable walkthrough.
+This package is built on Effect. Public methods return `Effect` or `Stream`; provide `AIClient.layer` (or `AIClient.layerWith(executor)`) for every modality, then import the provider/protocol modules for the routes you use. The example at `example/tutorial.ts` is a runnable walkthrough.

 ## See also

@@ -1,6 +1,6 @@
 # Media generation in `@opencode/ai` — public API direction

-Status: phases 1–3 implemented (Speech and Transcription); phases 4–5 proposal.
+Status: phases 1–4 implemented (through Image queued routes and partial images); phase 5 proposal.

 ## Goal

@@ -54,7 +54,7 @@ Speech.request({ model: openai.speech("gpt-4o-mini-tts"), text })
 Transcription.request({ model: openai.transcription("gpt-4o-transcribe"), audio })
 ```

-The request namespace and the selector share one word (`Image.request` + `.image(...)`). That redundancy is accepted: a callable facade returning a lazily resolved ref would be a second way to construct the same model, and the type machinery to infer `providerOptions` through it is not worth one word. Where a provider has two routes for one modality, the selectors stay explicit (`openai.chat`, `stability.image` inline vs `stability.upscale()` queued), and one default per modality per provider is part of the facade definition (OpenAI image → Images API, Google image → Gemini-native; Imagen is shut down, so there is no `google.imagen`). Provider package entrypoints keep `model(modelID, settings)` per modality-specific path, e.g. `@opencode/ai/providers/openai/responses`.
+The request namespace and the selector share one word (`Image.request` + `.image(...)`). That redundancy is accepted: a callable facade returning a lazily resolved ref would be a second way to construct the same model, and the type machinery to infer `providerOptions` through it is not worth one word. Where a provider has two routes for one modality, the selectors stay explicit (`openai.chat`, `stability.image` inline vs `stability.upscale()` queued), and one default per modality per provider is part of the facade definition (OpenAI image → Images API, Google image → Gemini-native; Imagen is shut down, so there is no `google.imagen`). The facade selector (`openai.image(id)`) is the public path for media models. Modality-specific package entrypoints (`model(modelID, settings)` beside today's LLM paths such as `@opencode/ai/providers/openai/responses`) are deferred until Core has a modality-aware model resolver; Core's resolver accepts only `LanguageModel` today.

 ### `Media` — the asset type

@@ -86,10 +86,18 @@ class Media.Asset {

 Media.bytes(data, mediaType?)      Media.base64(data, mediaType?)
 Media.url(url, options?)           Media.ref(provider, id)
-Media.file(path)                   // Bun/Node: reads + sniffs; Effect FileSystem variant for layers
-Media.write(asset, path)           // convenience, uses FileSystem
+Media.file(path)                   // Effect<Asset, AIError, FileSystem>: reads + sniffs
+Media.write(asset, path)           // Effect<void, AIError, FileSystem | RequestExecutor.Service>
 ```

+`Media.file` and `Media.write` stay Effect-only: bring your platform's `FileSystem` layer. The Promise client owns the
+runtime path: `ai.file(path)` and `ai.write(asset, path)` read and write through `node:fs/promises` (loaded on first
+use) with the same media-type sniffing and `InvalidRequest` failures, and `ai.bytes`, `ai.base64`, and
+`ai.materialize` run the asset methods in its runtime.
+
+A `ref` source is accepted as input only by routes whose provider issues file handles. No shipped route produces one
+yet, so `bytes()` and `materialize()` on a ref fail by design until a producer exists.
+
 Raw-PCM outputs (Gemini TTS, Cartesia raw, Deepgram WS) carry `info.encoding/sampleRate/channels` because there is no container header.

 ### Modality namespaces
@@ -104,28 +112,32 @@ import { OpenAI, Google, ElevenLabs, Fal } from "@opencode/ai/providers"
 #### Image

 ```ts
-const request = Image.request({
-  model: openai.image("gpt-image-2"),
-  prompt: "A robot tending a rooftop garden",
-  images: [Media.file("./ref.png")],           // references / edit sources
-  mask: Media.file("./mask.png"),
-  n: 2,
-  size: "1536x1024",                            // or aspectRatio: "3:2"
-  seed: 7,
-  format: "webp",
-  providerOptions: { quality: "high", background: "transparent" },   // typed per model
+Effect.gen(function* () {
+  const request = Image.request({
+    model: openai.image("gpt-image-2"),
+    prompt: "A robot tending a rooftop garden",
+    images: [yield* Media.file("./ref.png")],     // references / edit sources
+    mask: yield* Media.file("./mask.png"),
+    n: 2,
+    size: "1536x1024",                            // OpenAI sizes by pixels; Gemini/xAI take aspectRatio instead
+    format: "webp",
+    providerOptions: { quality: "high", background: "transparent" },   // typed per model
+  })
+
+  const response = yield* Image.generate(request) // ImageResponse
+  response.image                                  // Media.Asset (first)
+  response.images                                 // Media.Asset[]
+  response.usage                                  // Usage union (see below)
+  response.notices                                // moderation / partial-result notices
+
+  Image.stream(request)                           // Stream<ImageEvent>
+  // ImageEvent: generation-queued | generation-progress | image-partial { index, image } | image { index, image } | finish { usage }
 })
-
-const response = yield* Image.generate(request)   // ImageResponse
-response.image                                    // Media.Asset (first)
-response.images                                   // Media.Asset[]
-response.usage                                    // Usage union (see below)
-response.notices                                  // moderation / partial-result notices
-
-yield* Image.stream(request)                      // Stream<ImageEvent>
-// ImageEvent: generation-queued | generation-progress | image-partial { index, image } | image { index, image } | finish { usage }
 ```

+`size` and `aspectRatio` are not interchangeable; each route rejects fields it cannot lower — see the README's Image
+portability matrix.
+
 Editing is not a separate function; `images`/`mask` on the request select the edit path in the route (OpenAI `/images/edits`, Gemini multimodal parts, xAI `/images/edits`). Routes that cannot honor `mask` fail with `Unsupported`.

 `ImageRoute` is the inline | stream | queued union, dispatched on `route.kind`. `Image.stream` on a streaming route emits `image-partial` previews before each `image`; on a queued route it emits `generation-queued` / `generation-progress` observations, then the result's `image` and `finish` events.
@@ -135,40 +147,43 @@ Editing is not a separate function; `images`/`mask` on the request select the ed
 Shipped in phase 2 (`src/video.ts`, `src/video-client.ts`, protocols `google-video`, `xai-video`, `fal-video`, `runway-video`).

 ```ts
-const request = Video.request({
-  model: google.video("veo-3.1-generate-preview"),
-  prompt: "Panning wide shot of a calico kitten sleeping in the sunshine",
-  frames: { first: Media.file("./start.png"), last: Media.file("./end.png") },
-  references: [Media.file("./style.png")],
-  video: Media.bytes(previous, "video/mp4"),    // edit / extend source
-  durationSeconds: 8,
-  aspectRatio: "16:9",
-  resolution: "1080p",
-  audio: true,
-  n: 1,
-  seed: 7,
-  negativePrompt: "text, watermark",            // common, not provider-native
-  providerOptions: { personGeneration: "allow_adult" },
+Effect.gen(function* () {
+  const request = Video.request({
+    model: google.video("veo-3.1-generate-preview"),
+    prompt: "Panning wide shot of a calico kitten sleeping in the sunshine",
+    frames: { first: yield* Media.file("./start.png"), last: yield* Media.file("./end.png") },
+    references: [yield* Media.file("./style.png")],
+    video: Media.bytes(previous, "video/mp4"),    // edit / extend source
+    durationSeconds: 8,
+    aspectRatio: "16:9",
+    resolution: "1080p",
+    audio: true,
+    n: 1,
+    seed: 7,
+    negativePrompt: "text, watermark",            // common, not provider-native
+    providerOptions: { personGeneration: "allow_adult" },
+  })
+
+  // Simple: wait for it.
+  const response = yield* Video.generate(request, { poll: { interval: "10 seconds", timeout: "10 minutes" } })
+  response.video                                     // Media.Asset: url with expiresAt (+ transient `headers` for Veo downloads)
+  response.usage                                     // credits on Runway; the other three report none
+  response.notices                                   // Veo raiMediaFilteredReasons → filtered, xAI respect_moderation → moderated
+  yield* response.video.materialize()                // pull bytes before the URL expires
+
+  // Explicit generation control.
+  const generation = yield* Video.start(request)     // Generation<VideoResponse>
+  generation.id; generation.status; generation.progress; generation.position; generation.token
+  yield* generation.await({ poll })                  // VideoResponse
+  yield* generation.cancel()                         // fal PUT cancel_url, Runway DELETE /tasks/{id}; no-op for Veo and xAI
+
+  // Resume from another process. The token is validated against the route's codec and refreshed once. It carries no
+  // route identity, so persist the provider and model ID alongside it: `resume` needs the model.
+  const resumed = yield* Video.resume(model, JSON.parse(saved))
+
+  // Progress as a stream.
+  Video.stream(request, { poll })                    // Stream<VideoEvent>: generation-queued { id, position } | generation-progress { id, progress } | video { index, video } | finish { usage, notices }
 })
-
-// Simple: wait for it.
-const response = yield* Video.generate(request, { poll: { interval: "10 seconds", timeout: "10 minutes" } })
-response.video                                     // Media.Asset: url with expiresAt (+ transient `headers` for Veo downloads)
-response.usage                                     // credits on Runway; the other three report none
-response.notices                                   // Veo raiMediaFilteredReasons → filtered, xAI respect_moderation → moderated
-yield* response.video.materialize()                // pull bytes before the URL expires
-
-// Explicit generation control.
-const generation = yield* Video.start(request)     // Generation<VideoResponse>
-generation.id; generation.status; generation.progress; generation.position; generation.token
-yield* generation.await({ poll })                  // VideoResponse
-yield* generation.cancel()                         // fal PUT cancel_url, Runway DELETE /tasks/{id}; no-op for Veo and xAI
-
-// Resume from another process. The token is validated against the route's codec and refreshed once.
-const resumed = yield* Video.resume(model, JSON.parse(saved))
-
-// Progress as a stream.
-yield* Video.stream(request, { poll })             // Stream<VideoEvent>: generation-queued { id, position } | generation-progress { id, progress } | video { index, video } | finish { usage, notices }
 ```

 Tokens are route-owned JSON: Veo `{ operation }`, xAI `{ requestID }`, Runway `{ taskID }`, fal
@@ -330,12 +345,12 @@ class Generation<Response> {
  readonly expiresAt?: number
  refresh(): Effect<Generation<Response>, AIError>
  result(): Effect<Response, AIError>
-  await(options?: AwaitOptions): Effect<Response, AIError>
+  await(options?: GenerationAwaitOptions): Effect<Response, AIError>
  cancel(): Effect<void, AIError>
-  events(options?: AwaitOptions): Stream<GenerationEvent, AIError>   // fails with Timeout past poll.timeout, checked per observation
+  events(options?: GenerationAwaitOptions): Stream<GenerationEvent, AIError>   // fails with Timeout past poll.timeout, checked per observation
 }

-AwaitOptions = { poll?: Poll }
+GenerationAwaitOptions = { poll?: Poll }
 Poll = { interval?: Duration; timeout?: Duration; schedule?: Schedule }   // route may override from provider hints (`openai-poll-after-ms`)
 ```

@@ -365,15 +380,17 @@ const ai = AI.make()                                // ManagedRuntime over Reque
 // AI.make({ layer }) to inject a custom executor / recorder / middleware

 const image = await ai.image.generate({ model, prompt })
-await image.image.bytes()
+await ai.bytes(image.image)                         // also ai.base64, ai.materialize, ai.write(asset, path)
+const reference = await ai.file("./ref.png")

 for await (const event of ai.speech.stream({ model, text, voice })) { … }

-const generation = await ai.video.start({ model, prompt })
+const generation = await ai.video.start({ model, prompt })    // snapshot handle; refresh() returns a new one
+for await (const event of generation.events({ poll: { interval: 10_000 } })) { … }
 const video = await generation.await({ poll: { interval: 10_000 }, signal })
-const resumed = ai.video.resume(model, JSON.parse(saved))
+const resumed = await ai.video.resume(model, JSON.parse(saved)) // persist provider + model ID with the token

-const text = await ai.llm.generate({ model, prompt })   // closes today's gap: LLM has no promise API either
+const text = await ai.llm.generate({ model, prompt })
 for await (const event of ai.llm.stream(request)) { … }

 await ai.dispose()
@@ -401,9 +418,9 @@ Existing facades gain per-modality selectors; the modality routes each facade pr
 | `Runway` | | | ✓ | | | |
 | `Luma`, `Kling`, `MiniMax` | | per provider | | | | |

-New facades follow the existing one-file-per-provider rule. Package entrypoints are modality-specific, such as `@opencode/ai/providers/openai/images`, and return the concrete model.
+New facades follow the existing one-file-per-provider rule. The facade selector is the public path for media models; modality-specific package entrypoints (for example `@opencode/ai/providers/openai/images`) are deferred until Core has a modality-aware model resolver.

-`ImageModel<Options>` already gives typed `providerOptions` per model; `VideoModel`, `SpeechModel`, `TranscriptionModel` follow the same generic. A shared `MediaModel` union is what `Generation` and the promise client key on.
+`ImageModel<Options>` gives typed `providerOptions` per model; `VideoModel`, `SpeechModel`, and `TranscriptionModel` follow the same generic. They share an internal `MediaModel` base class (ids, route, `http` overlays) that is not part of the public exports; `Generation` and the promise client work with the concrete modality models.

 ### Routes and protocols

@@ -1,18 +1,7 @@
-import { Config, Effect, Formatter, Layer, Schema, Stream } from "effect"
+import { Config, Effect, Formatter, Schema, Stream } from "effect"
 import { NodeFileSystem } from "@effect/platform-node"
-import {
-  Image,
-  ImageClient,
-  LLM,
-  LLMClient,
-  LLMRequest,
-  Media,
-  Message,
-  ProviderID,
-  Tool,
-  ToolRuntime,
-} from "@opencode/ai"
-import { Route, Auth, Endpoint, Framing, Protocol, RequestExecutor } from "@opencode/ai/route"
+import { AIClient, Image, LLM, LLMRequest, Media, Message, ProviderID, Tool, ToolRuntime } from "@opencode/ai"
+import { Route, Auth, Endpoint, Framing, Protocol } from "@opencode/ai/route"
 import { OpenAI } from "@opencode/ai/providers"

 /**
@@ -243,12 +232,10 @@ const generateImage = Effect.gen(function* () {
  yield* Media.write(response.image, "tutorial-image.jpg").pipe(Effect.provide(NodeFileSystem.layer))
 })

-// Provide the LLM runtime and the HTTP request executor once. Keep one path
-// enabled at a time so the tutorial can demonstrate generate, stream, or
+// Provide every modality client and the HTTP request executor once with
+// `AIClient.layer` (`AIClient.layerWith(executor)` swaps the executor). Keep one
+// path enabled at a time so the tutorial can demonstrate generate, stream, or
 // tool-loop behavior without spending tokens on every example.
-const requestExecutorLayer = RequestExecutor.fetchLayer
-const llmClientLayer = LLMClient.layer.pipe(Layer.provide(requestExecutorLayer))
-const imageClientLayer = ImageClient.layer.pipe(Layer.provide(requestExecutorLayer))

 const program = Effect.gen(function* () {
  // yield* generateOnce
@@ -257,6 +244,6 @@ const program = Effect.gen(function* () {
  // yield* generateDynamicObject.pipe(Effect.andThen((response) => Effect.sync(() => console.log(response.object))))
  // yield* generateImage
  yield* streamWithTools
-}).pipe(Effect.provide(Layer.mergeAll(requestExecutorLayer, llmClientLayer, imageClientLayer)))
+}).pipe(Effect.provide(AIClient.layer))

 Effect.runPromise(program)
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "2.0.15",
+  "version": "2.0.16",
  "name": "@opencode/ai",
  "type": "module",
  "license": "MIT",
@@ -0,0 +1,24 @@
+import { Layer } from "effect"
+import { ImageClient } from "./image-client.js"
+import { LLMClient } from "./route/client.js"
+import { RequestExecutor } from "./route/executor.js"
+import { SpeechClient } from "./speech-client.js"
+import { TranscriptionClient } from "./transcription-client.js"
+import { VideoClient } from "./video-client.js"
+
+/** Every modality client over `executor`, which stays in the output so `asset.bytes()` and `Media.write` resolve. */
+export const layerWith = <E, R>(executor: Layer.Layer<RequestExecutor.Service, E, R>) =>
+  Layer.mergeAll(
+    LLMClient.layer,
+    ImageClient.layer,
+    VideoClient.layer,
+    SpeechClient.layer,
+    TranscriptionClient.layer,
+  ).pipe(Layer.provideMerge(executor))
+
+/** Every modality client plus the executor over `RequestExecutor.fetchLayer`: the one layer most programs need. */
+export const layer = layerWith(RequestExecutor.fetchLayer)
+
+export type Services = Layer.Success<typeof layer>
+
+export * as AIClient from "./ai-client.js"
@@ -86,7 +86,7 @@ export const layer: Layer.Layer<Service, never, RequestExecutor.Service> = Layer
    })
  }),
 )
-export const fetchLayer = layer.pipe(Layer.provide(RequestExecutor.fetchLayer))
+export const fetchLayer = layer.pipe(Layer.provideMerge(RequestExecutor.fetchLayer))

 export const EvaluationClient = {
  Service,
@@ -30,7 +30,9 @@ export interface Interface {
  ) => Effect.Effect<Generation<ImageResponse>, AIError>
 }

-export class Service extends Context.Service<Service, Interface>()("@opencode/ImageClient") {}
+export class ImageClientService extends Context.Service<ImageClientService, Interface>()("@opencode/ImageClient") {}
+export const Service = ImageClientService
+export type Service = ImageClientService

 export const generate = <Options extends ImageOptions>(
  request: ImageRequestFor<Options>,
@@ -1,3 +1,4 @@
+export { AIClient } from "./ai-client.js"
 export { LLMClient } from "./route/client.js"
 export { ImageClient } from "./image-client.js"
 export { Auth } from "./route/auth.js"
@@ -8,7 +9,7 @@ export type {
  RouteLanguageModelInput,
  RouteRoutedLanguageModelInput,
  Interface as LLMClientShape,
-  Service as LLMClientService,
+  LLMClientService,
 } from "./route/client.js"
 export * from "./schema/index.js"
 export {
@@ -6,7 +6,7 @@ import { ProviderID } from "./schema/ids.js"
 import { AIError, HttpContext, InvalidProviderOutputError, InvalidRequestError } from "./schema/errors.js"
 import { ProviderMetadata } from "./schema/options.js"
 import { Service } from "./route/executor-service.js"
-import { detectMediaType, extensionMediaType } from "./utils/media-type.js"
+import { detectMediaType, fileMediaType } from "./utils/media-type.js"

 export { detectMediaType } from "./utils/media-type.js"

@@ -309,7 +309,7 @@ export const file = (path: string, options?: AssetOptions): Effect.Effect<Asset,
    const data = yield* fs
      .readFile(path)
      .pipe(Effect.mapError((cause) => invalid(`Failed to read media file ${path}`, cause)))
-    return bytes(data, detectMediaType(data) ?? extensionMediaType(path), options)
+    return bytes(data, fileMediaType(data, path), options)
  })

 /** Materialize an asset and write its bytes through `FileSystem`. */
@@ -1,14 +1,14 @@
 import { Effect, Layer, ManagedRuntime, Stream } from "effect"
-import type { AwaitOptions, Generation, Snapshot } from "./generation.js"
+import { AIClient } from "./ai-client.js"
+import type { AwaitOptions, Event, Generation, Snapshot } from "./generation.js"
 import { Image, ImageModel, ImageRequest, type ImageOptions, type ImageRequestInput } from "./image.js"
-import { ImageClient } from "./image-client.js"
 import { LLM } from "./index.js"
-import { LLMClient } from "./route/client.js"
+import { Media } from "./media.js"
+import { tryRequest } from "./media-model.js"
 import { RequestExecutor } from "./route/executor.js"
-import { LanguageModel, LLMRequest } from "./schema/index.js"
+import { AIError, InvalidRequestError, LanguageModel, LLMRequest } from "./schema/index.js"
 import type { RequestInput } from "./llm.js"
 import { Speech, SpeechModel, SpeechRequest, type SpeechRequestInput } from "./speech.js"
-import { SpeechClient } from "./speech-client.js"
 import {
  Transcription,
  TranscriptionModel,
@@ -16,17 +16,16 @@ import {
  type TranscriptionOptions,
  type TranscriptionRequestInput,
 } from "./transcription.js"
-import { TranscriptionClient } from "./transcription-client.js"
+import { fileMediaType } from "./utils/media-type.js"
 import { Video, VideoModel, VideoRequest, type VideoOptions, type VideoRequestInput } from "./video.js"
-import { VideoClient } from "./video-client.js"

 /**
 * Promise-first entrypoint for scripts and non-Effect callers. One `ManagedRuntime` hosts the LLM, image, video, speech,
 * and transcription clients over a request executor; every method runs the corresponding Effect API and rethrows
- * `AIError` unchanged.
+ * `AIError` unchanged. `file` and `write` load `node:fs/promises` on first use, so importing this module does not.
 */
 export interface Options {
-  /** Executor layer; defaults to `RequestExecutor.fetchLayer`. Inject a recorder or middleware here. */
+  /** Executor layer; defaults to `RequestExecutor.fetchLayer`. Inject a recorder or `RequestExecutor.middleware(fn)` here. */
  readonly layer?: Layer.Layer<RequestExecutor.Service>
 }

@@ -34,19 +33,20 @@ export interface RunOptions {
  readonly signal?: AbortSignal
 }

-export type Services =
-  | Layer.Success<typeof LLMClient.layer>
-  | Layer.Success<typeof ImageClient.layer>
-  | Layer.Success<typeof VideoClient.layer>
-  | Layer.Success<typeof SpeechClient.layer>
-  | Layer.Success<typeof TranscriptionClient.layer>
-  | RequestExecutor.Service
+export type Services = AIClient.Services

-/** Promise view of a `Generation`: its snapshot plus `await`, `refresh`, and `cancel` returning promises. */
+/**
+ * Promise view of a `Generation`. Its fields are a snapshot taken when the handle was created; `refresh()` resolves to a
+ * new handle rather than updating this one.
+ */
 export type GenerationHandle<Response> = Snapshot & {
  /** Serializable JSON; pass it back to `resume` from another process. */
  readonly token: unknown
  readonly await: (options?: AwaitOptions & RunOptions) => Promise<Response>
+  /** Status observations until the first terminal one, polling like `await`; abort ends iteration without throwing. */
+  readonly events: (options?: AwaitOptions & RunOptions) => AsyncIterable<Event>
+  /** The result without polling; fails when the generation has not completed. */
+  readonly result: (options?: RunOptions) => Promise<Response>
  readonly refresh: (options?: RunOptions) => Promise<GenerationHandle<Response>>
  readonly cancel: (options?: RunOptions) => Promise<void>
 }
@@ -65,17 +65,9 @@ const abortEffect = (signal: AbortSignal | undefined) =>
      })

 export const make = (options: Options = {}) => {
-  const runtime = ManagedRuntime.make(
-    Layer.mergeAll(
-      LLMClient.layer,
-      ImageClient.layer,
-      VideoClient.layer,
-      SpeechClient.layer,
-      TranscriptionClient.layer,
-    ).pipe(Layer.provideMerge(options.layer ?? RequestExecutor.fetchLayer)),
-  )
+  const runtime = ManagedRuntime.make(AIClient.layerWith(options.layer ?? RequestExecutor.fetchLayer))

-  /** Run any package Effect (for example `asset.bytes()`) inside this runtime. */
+  /** Run any package Effect (for example `LLMClient.compact(...)`) inside this runtime. */
  const run = <A, E>(effect: Effect.Effect<A, E, Services>, options?: RunOptions) =>
    runtime.runPromise(effect, { signal: options?.signal })

@@ -95,12 +87,15 @@ export const make = (options: Options = {}) => {
    ...generation.snapshot,
    token: generation.token,
    await: (options) => run(generation.await({ poll: options?.poll }), options),
+    events: (options) => iterate(generation.events({ poll: options?.poll }), options),
+    result: (options) => run(generation.result(), options),
    refresh: (options) => run(generation.refresh(), options).then(handle),
    cancel: (options) => run(generation.cancel(), options),
  })

  // The typed `generate`/`stream` overloads take a concrete input or a request, not the union; normalize once here.
-  const llmRequest = (input: RequestInput | LLMRequest) => (input instanceof LLMRequest ? input : LLM.request(input))
+  const llmRequest = (input: RequestInput | LLMRequest) =>
+    input instanceof LLMRequest ? Effect.succeed(input) : tryRequest(() => LLM.request(input))
  const imageRequest = (input: ImageRequestInput | ImageRequest) =>
    input instanceof ImageRequest ? input : Image.request(input)
  const videoRequest = (input: VideoRequestInput | VideoRequest) =>
@@ -112,12 +107,48 @@ export const make = (options: Options = {}) => {

  return {
    run,
+    /** Decoded asset bytes, downloading `url` sources through the executor. */
+    bytes: (asset: Media.Asset, options?: RunOptions) => run(asset.bytes(), options),
+    base64: (asset: Media.Asset, options?: RunOptions) => run(asset.base64(), options),
+    /** Pull a `url` asset into owned bytes before the provider URL expires. */
+    materialize: (asset: Media.Asset, options?: RunOptions) => run(asset.materialize(), options),
+    /** Read a file into an asset like `Media.file`: sniffed media type, then the extension's. */
+    file: async (path: string, options?: Media.AssetOptions & RunOptions) => {
+      const { readFile } = await import("node:fs/promises")
+      return run(
+        Effect.tryPromise({
+          try: (signal) => readFile(path, { signal }),
+          catch: (cause) => fileError(`Failed to read media file ${path}`, cause),
+        }).pipe(
+          Effect.map((buffer) => {
+            const data = new Uint8Array(buffer)
+            return Media.bytes(data, fileMediaType(data, path), options)
+          }),
+        ),
+        options,
+      )
+    },
+    /** Write an asset's bytes like `Media.write`, downloading `url` sources through the executor. */
+    write: async (asset: Media.Asset, path: string, options?: RunOptions) => {
+      const { writeFile } = await import("node:fs/promises")
+      return run(
+        asset.bytes().pipe(
+          Effect.flatMap((data) =>
+            Effect.tryPromise({
+              try: (signal) => writeFile(path, data, { signal }),
+              catch: (cause) => fileError(`Failed to write media file ${path}`, cause),
+            }),
+          ),
+        ),
+        options,
+      )
+    },
    llm: {
      request: LLM.request,
      generate: <const Model extends LanguageModel>(input: RequestInput<Model> | LLMRequest, options?: RunOptions) =>
-        run(LLM.generate(llmRequest(input)), options),
+        run(Effect.flatMap(llmRequest(input), LLM.generate), options),
      stream: <const Model extends LanguageModel>(input: RequestInput<Model> | LLMRequest, options?: RunOptions) =>
-        iterate(LLM.stream(llmRequest(input)), options),
+        iterate(Stream.unwrap(Effect.map(llmRequest(input), LLM.stream)), options),
    },
    image: {
      request: Image.request,
@@ -186,6 +217,9 @@ export const make = (options: Options = {}) => {

 export type Client = ReturnType<typeof make>

+const fileError = (message: string, cause: unknown) =>
+  new AIError({ reason: new InvalidRequestError({ message, cause }) })
+
 /** Default client over `RequestExecutor.fetchLayer` for scripts; the runtime builds its layer on first use. */
 export const ai = make()

@@ -1034,7 +1034,6 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
  const format = outputConfig?.format ?? undefined
  const updates = resolveEffortUpdates(request, options.effort ?? outputConfig?.effort ?? undefined)
  const generation = request.generation
-  const toolSchemaCompatibility = request.model.compatibility?.toolSchema
  // Allocate the 4-breakpoint budget in invalidation order: tools → system →
  // messages. Tools live highest in the cache hierarchy, so when callers
  // over-mark we keep their tool hints and shed the message-tail ones first.
@@ -1044,11 +1043,7 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
    flattened.tools.length === 0
      ? undefined
      : flattened.tools.map((tool) =>
-          lowerTool(
-            breakpoints,
-            tool,
-            ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility),
-          ),
+          lowerTool(breakpoints, tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model)),
        )
  // Anthropic rejects tool_choice when tools are absent; "none" is only meaningful with tools present.
  const toolChoice = tools === undefined || !request.toolChoice ? undefined : yield* lowerToolChoice(request.toolChoice)
@@ -11,7 +11,7 @@ import {
  type FinishReasonDetails,
  type JsonSchema,
  type LLMRequest,
-  type LanguageModelToolSchemaCompatibility,
+  type LanguageModel,
  type ProviderMetadata,
  type ReasoningPart,
  type ToolCallPart,
@@ -230,13 +230,13 @@ const lowerToolSpec = (tool: ToolDefinition, inputSchema: JsonSchema): BedrockTo
 })

 const lowerTools = (
-  compatibility: LanguageModelToolSchemaCompatibility | undefined,
+  model: LanguageModel,
  breakpoints: BedrockCache.Breakpoints,
  tools: ReadonlyArray<ToolDefinition>,
 ): BedrockTool[] => {
  const result: BedrockTool[] = []
  for (const tool of tools) {
-    result.push(lowerToolSpec(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, compatibility)))
+    result.push(lowerToolSpec(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, model)))
    const cachePoint = BedrockCache.block(breakpoints, tool.cache)
    if (cachePoint) result.push(cachePoint)
  }
@@ -440,7 +440,7 @@ const fromRequest = Effect.fn("BedrockConverse.fromRequest")(function* (request:
  const toolConfig = (() => {
    if (flattened.tools.length === 0) return undefined
    return {
-      tools: lowerTools(request.model.compatibility?.toolSchema, breakpoints, flattened.tools),
+      tools: lowerTools(request.model, breakpoints, flattened.tools),
      // Converse has no native "none". Keep definitions stable for prompt
      // caching and omit only the unsupported choice.
      toolChoice,
@@ -10,8 +10,8 @@ import {
  LLMEvent,
  Usage,
  type FinishReason,
-  type JsonSchema,
  type LLMRequest,
+  type LanguageModel,
  type MediaPart,
  type ProviderMetadata,
  type ProviderOptions,
@@ -23,7 +23,6 @@ import { classifyProviderFailure } from "../provider-error.js"
 import { Media } from "../media.js"
 import { JsonObject, knownString, lenient, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { GeminiGenerateContent } from "./utils/gemini-generate-content.js"
-import { GeminiToolSchema } from "./utils/gemini-tool-schema.js"
 import { Lifecycle } from "./utils/lifecycle.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"

@@ -133,7 +132,7 @@ const GeminiSystemInstruction = Schema.Struct({
 const GeminiFunctionDeclaration = Schema.Struct({
  name: Schema.String,
  description: Schema.String,
-  parameters: Schema.optional(JsonObject),
+  parametersJsonSchema: JsonObject,
 })

 const GeminiTool = Schema.Struct({
@@ -266,36 +265,15 @@ interface ParserState {
  readonly seenCallIds?: ReadonlySet<string>
 }

-// =============================================================================
-// Tool Schema Conversion
-// =============================================================================
-// Tool-schema conversion has two distinct concerns:
-//
-// 1. Sanitize — fix common authoring mistakes Gemini rejects: integer/number
-//    enums (must be strings), `required` entries that don't match a property,
-//    untyped arrays (`items` must be present), and `properties`/`required`
-//    keys on non-object scalars. Mirrors OpenCode's historical Gemini rules.
-//
-// 2. Project — lossy mapping from JSON Schema to Gemini's schema dialect:
-//    drop empty root parameter schemas while preserving nested empty objects,
-//    expand type arrays into `anyOf`, derive `nullable: true` from null members,
-//    coerce `const` to `[const]` enum, recurse properties/items, and propagate
-//    only an allowlisted set of keys (description, required, format, type,
-//    nullable, enum, properties, items, allOf, anyOf, oneOf, minLength).
-//    Anything outside the allowlist (e.g. `additionalProperties`, `$ref`) is
-//    silently dropped.
-//
-// Sanitize runs first, then project. The implementation lives in
-// `utils/gemini-tool-schema` so this protocol keeps the same shape as the other
-// provider protocols.
-
 // =============================================================================
 // Request Lowering
 // =============================================================================
-const lowerTool = (tool: ToolDefinition, inputSchema: JsonSchema) => ({
+// Tool schemas go in `parametersJsonSchema`, which accepts standard JSON Schema. Gemini's schema
+// rules are this API's default, including for tuned endpoints whose IDs do not name Gemini.
+const lowerTool = (tool: ToolDefinition, model: LanguageModel) => ({
  name: tool.name,
  description: tool.description,
-  parameters: GeminiToolSchema.convert(inputSchema),
+  parametersJsonSchema: ToolSchemaProjection.modelCompatibility(tool.inputSchema, model, "gemini"),
 })

 const lowerToolConfig = (toolChoice: NonNullable<LLMRequest["toolChoice"]>) =>
@@ -465,7 +443,6 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
  const hasTools = flattened.tools.length > 0
  const generation = request.generation
  const options = yield* decodeOptions(request.providerOptions ?? {})
-  const toolSchemaCompatibility = request.model.compatibility?.toolSchema
  const generationConfig = {
    maxOutputTokens: generation?.maxTokens,
    temperature: generation?.temperature,
@@ -491,9 +468,7 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
    tools: hasTools
      ? [
          {
-            functionDeclarations: flattened.tools.map((tool) =>
-              lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility)),
-            ),
+            functionDeclarations: flattened.tools.map((tool) => lowerTool(tool, request.model)),
          },
        ]
      : undefined,
@@ -107,7 +107,7 @@ const fromRequest = Effect.fn("MetaResponses.fromRequest")(function* (request: L
                return yield* OpenResponses.lowerTool(
                  NAME,
                  tool,
-                  ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model.compatibility?.toolSchema),
+                  ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model),
                )
              return yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(NativeTool))(tool.native.meta)
            }),
@@ -818,7 +818,6 @@ export const fromRequestWithAdapter = Effect.fn("OpenResponses.fromRequestWithAd
  adapter: ProviderAdapter,
 ) {
  const projected = ProviderShared.flattenToolRequest(request)
-  const toolSchemaCompatibility = request.model.compatibility?.toolSchema
  return {
    ...(yield* lowerConversation(projected.request, adapter)),
    ...lowerGeneration(request),
@@ -828,11 +827,7 @@ export const fromRequestWithAdapter = Effect.fn("OpenResponses.fromRequestWithAd
        : yield* Effect.forEach(projected.tools, (tool) =>
            tool.native !== undefined && adapter.nativeTool
              ? adapter.nativeTool(tool.native)
-              : lowerTool(
-                  adapter.name,
-                  tool,
-                  ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility),
-                ),
+              : lowerTool(adapter.name, tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model)),
          ),
    tool_choice:
      allowedToolChoice(request) ??
@@ -803,7 +803,6 @@ export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (
      `OpenAI Chat reasoning field conflicts with reserved field ${reasoningField}`,
    )
  const generation = request.generation
-  const toolSchemaCompatibility = request.model.compatibility?.toolSchema
  const flattened = ProviderShared.flattenToolRequest(request)
  const provider = String(request.model.provider)
  const baseURL = request.model.route.endpoint.baseURL
@@ -829,7 +828,7 @@ export const fromRequest = Effect.fn("OpenAIChat.fromRequest")(function* (
        : flattened.tools.map((tool) =>
            lowerTool(
              tool,
-              ToolSchemaProjection.modelCompatibility(tool.inputSchema, toolSchemaCompatibility),
+              ToolSchemaProjection.modelCompatibility(tool.inputSchema, request.model),
              options,
              supportsStrictMode,
            ),
@@ -5,7 +5,14 @@ import { Auth } from "../route/auth.js"
 import { Endpoint } from "../route/endpoint.js"
 import { Protocol } from "../route/protocol.js"
 import { HttpTransport } from "../route/transport/index.js"
-import { LLMRequest, mergeJsonRecords, type JsonSchema, type ToolDefinition, type ToolEntry } from "../schema/index.js"
+import {
+  LLMRequest,
+  mergeJsonRecords,
+  type JsonSchema,
+  type LanguageModel,
+  type ToolDefinition,
+  type ToolEntry,
+} from "../schema/index.js"
 import { resolveEffortUpdates } from "../effort-updates.js"
 import { OpenResponses } from "./open-responses.js"
 import { OpenResponsesOptions } from "./utils/open-responses-options.js"
@@ -170,12 +177,9 @@ const lowerTool = Effect.fn("OpenAIResponses.lowerTool")(function* (tool: ToolDe

 // Native namespaces hold only function tools, so deeper levels flatten into
 // the leaf names the same way non-native protocols flatten the whole tree.
-const lowerToolEntry = Effect.fn("OpenAIResponses.lowerToolEntry")(function* (
-  tool: ToolEntry,
-  compatibility: Parameters<typeof ToolSchemaProjection.modelCompatibility>[1],
-) {
+const lowerToolEntry = Effect.fn("OpenAIResponses.lowerToolEntry")(function* (tool: ToolEntry, model: LanguageModel) {
  if (tool.type === "tool")
-    return yield* lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, compatibility))
+    return yield* lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, model))
  // OpenAI requires a namespace description; fall back to a generic one so a
  // missing description never blocks the request.
  return {
@@ -183,7 +187,7 @@ const lowerToolEntry = Effect.fn("OpenAIResponses.lowerToolEntry")(function* (
    name: tool.name,
    description: tool.description ?? `Tools in the ${tool.name} namespace.`,
    tools: yield* Effect.forEach(ProviderShared.flattenTools(tool.tools), (leaf) =>
-      OpenResponses.lowerTool(NAME, leaf, ToolSchemaProjection.modelCompatibility(leaf.inputSchema, compatibility)),
+      OpenResponses.lowerTool(NAME, leaf, ToolSchemaProjection.modelCompatibility(leaf.inputSchema, model)),
    ),
  }
 })
@@ -207,7 +211,6 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
  )(request.providerOptions?.contextManagement)
  const options = OpenResponsesOptions.resolve(request)
  const updates = resolveEffortUpdates(request, options.reasoningEffort)
-  const toolSchemaCompatibility = request.model.compatibility?.toolSchema
  return yield* decodeBody({
    ...(yield* OpenResponses.lowerConversation(updates.request, adapter)),
    ...OpenResponses.lowerGeneration(request, { ...options, reasoningEffort: updates.effort }),
@@ -215,7 +218,7 @@ const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request:
    tools:
      request.tools.length === 0
        ? undefined
-        : yield* Effect.forEach(request.tools, (tool) => lowerToolEntry(tool, toolSchemaCompatibility)),
+        : yield* Effect.forEach(request.tools, (tool) => lowerToolEntry(tool, request.model)),
    tool_choice:
      request.tools.length === 0
        ? undefined
@@ -18,7 +18,11 @@ const PCM_SAMPLE_RATE = 24000
 // 1. Public model input
 // ---------------------------------------------------------------------------

-export type OpenAISpeechOptions = Record<string, unknown>
+/** `voice`, `instructions`, `speed`, and `format` are common request fields; other native body fields pass through. */
+export type OpenAISpeechOptions = {
+  /** Defaults to `"sse"` in `stream` mode on models that support it; the merged value selects the response framing. */
+  readonly stream_format?: "sse" | "audio"
+} & Record<string, unknown>

 export type Request = SpeechRequestFor<OpenAISpeechOptions>

@@ -211,7 +211,8 @@ export const mediaReference = (
  if (provider !== undefined && asset.source.type === "ref" && asset.source.provider === provider)
    return Effect.succeed({ type: "ref", value: asset.source.id })
  const accepted = provider === undefined ? "" : `, and ${provider} references`
-  return Effect.fail(invalidRequest(`${label} accepts inline bytes, data URLs, http(s) URLs${accepted}`))
+  const got = asset.source.type === "ref" ? `; got ${asset.source.provider}:${asset.source.id}` : ""
+  return Effect.fail(invalidRequest(`${label} accepts inline bytes, data URLs, http(s) URLs${accepted}${got}`))
 }

 /**
@@ -0,0 +1,77 @@
+import type { JsonSchema } from "../../schema/index.js"
+import { isRecord } from "../../utils/record.js"
+
+// Gemini's `parametersJsonSchema` accepts standard JSON Schema, but rejects a few shapes that
+// published tool schemas commonly contain. Rewrite only those and send everything else unchanged.
+const SCHEMA_MAPS = new Set([
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "dependencies",
+])
+const VALUES = new Set(["const", "default", "enum", "examples", "dependentRequired"])
+
+const mapValues = (record: Record<string, unknown>, map: (value: unknown, key: string) => unknown) =>
+  Object.fromEntries(Object.entries(record).map(([key, value]) => [key, map(value, key)]))
+
+const normalizeNode = (schema: unknown): unknown => {
+  if (Array.isArray(schema)) return schema.map(normalizeNode)
+  if (!isRecord(schema)) return schema
+  const properties = isRecord(schema.properties) ? schema.properties : undefined
+  return Object.fromEntries(
+    Object.entries(schema).flatMap(([key, value]) => {
+      if (VALUES.has(key)) return [[key, value]]
+      if (SCHEMA_MAPS.has(key) && isRecord(value)) return [[key, mapValues(value, normalizeNode)]]
+      // `required` may only name declared properties.
+      if (key === "required" && properties && Array.isArray(value))
+        return [[key, value.filter((name) => typeof name === "string" && Object.hasOwn(properties, name))]]
+      // Draft-04 boolean exclusive bounds become the numeric form.
+      if (key === "exclusiveMinimum" && typeof value === "boolean")
+        return value && typeof schema.minimum === "number" ? [[key, schema.minimum]] : []
+      if (key === "exclusiveMaximum" && typeof value === "boolean")
+        return value && typeof schema.maximum === "number" ? [[key, schema.maximum]] : []
+      if (key === "minimum" && schema.exclusiveMinimum === true) return []
+      if (key === "maximum" && schema.exclusiveMaximum === true) return []
+      // Draft-07 tuples (`items` array plus `additionalItems`) are `prefixItems` plus `items` in 2020-12.
+      if (key === "items" && Array.isArray(value)) return [["prefixItems", value.map(normalizeNode)]]
+      if (key === "additionalItems" && Array.isArray(schema.items)) return [["items", normalizeNode(value)]]
+      return [[key, normalizeNode(value)]]
+    }),
+  )
+}
+
+// Gemini accepts a recursive `$ref` only when the loop passes through an optional property or
+// potentially empty array `items`. Replace other self-references with an unconstrained schema.
+const cutLoops = (schema: unknown, target: string, safe: boolean): unknown => {
+  if (Array.isArray(schema)) return schema.map((item) => cutLoops(item, target, safe))
+  if (!isRecord(schema)) return schema
+  if (schema.$ref === target && !safe) return {}
+  const required = Array.isArray(schema.required) ? schema.required : []
+  return mapValues(schema, (value, key) => {
+    if (VALUES.has(key)) return value
+    if (key === "items") return cutLoops(value, target, safe || !(Number(schema.minItems) > 0))
+    if (key === "properties" && isRecord(value))
+      return mapValues(value, (child, name) => cutLoops(child, target, safe || !required.includes(name)))
+    if (SCHEMA_MAPS.has(key) && isRecord(value)) return mapValues(value, (child) => cutLoops(child, target, safe))
+    return cutLoops(value, target, safe)
+  })
+}
+
+export const normalize = (schema: JsonSchema): JsonSchema => {
+  const normalized = normalizeNode(schema)
+  if (!isRecord(normalized)) return {}
+  const result = cutLoops(
+    mapValues(normalized, (value, key) =>
+      (key === "$defs" || key === "definitions") && isRecord(value)
+        ? mapValues(value, (def, name) => cutLoops(def, `#/${key}/${name}`, false))
+        : value,
+    ),
+    "#",
+    false,
+  )
+  return isRecord(result) ? result : {}
+}
+
+export * as GeminiJsonSchema from "./gemini-json-schema.js"
@@ -1,119 +0,0 @@
-import { isRecord } from "../../utils/record.js"
-
-// Gemini accepts a JSON Schema-like dialect for tool parameters, but rejects a
-// handful of common JSON Schema shapes. Keep this projection isolated so the
-// Gemini protocol file still reads like the other protocol modules.
-const SCHEMA_INTENT_KEYS = [
-  "type",
-  "properties",
-  "items",
-  "prefixItems",
-  "enum",
-  "const",
-  "$ref",
-  "additionalProperties",
-  "patternProperties",
-  "required",
-  "not",
-  "if",
-  "then",
-  "else",
-]
-
-const hasCombiner = (schema: unknown) =>
-  isRecord(schema) && (Array.isArray(schema.anyOf) || Array.isArray(schema.oneOf) || Array.isArray(schema.allOf))
-
-const hasSchemaIntent = (schema: unknown) =>
-  isRecord(schema) && (hasCombiner(schema) || SCHEMA_INTENT_KEYS.some((key) => key in schema))
-
-const sanitizeNode = (schema: unknown): unknown => {
-  if (!isRecord(schema)) return Array.isArray(schema) ? schema.map(sanitizeNode) : schema
-
-  const result: Record<string, unknown> = Object.fromEntries(
-    Object.entries(schema).map(([key, value]) => [
-      key,
-      key === "enum" && Array.isArray(value) ? value.map(String) : sanitizeNode(value),
-    ]),
-  )
-
-  if (Array.isArray(result.enum) && (result.type === "integer" || result.type === "number")) result.type = "string"
-
-  const properties = result.properties
-  if (result.type === "object" && isRecord(properties) && Array.isArray(result.required)) {
-    result.required = result.required.filter((field) => typeof field === "string" && field in properties)
-  }
-
-  if (result.type === "array" && !hasCombiner(result)) {
-    result.items = result.items ?? {}
-    if (isRecord(result.items) && !hasSchemaIntent(result.items)) result.items = { ...result.items, type: "string" }
-  }
-
-  if (typeof result.type === "string" && result.type !== "object" && !hasCombiner(result)) {
-    delete result.properties
-    delete result.required
-  }
-
-  return result
-}
-
-const emptyObjectSchema = (schema: Record<string, unknown>) =>
-  schema.type === "object" &&
-  (!isRecord(schema.properties) || Object.keys(schema.properties).length === 0) &&
-  !schema.additionalProperties
-
-const projectNode = (schema: unknown, nested = false): Record<string, unknown> | undefined => {
-  if (!isRecord(schema)) return undefined
-  if (!nested && emptyObjectSchema(schema)) return undefined
-  const types = Array.isArray(schema.type) ? schema.type.filter((type) => type !== "null") : undefined
-  const anyOf = Array.isArray(schema.anyOf) ? schema.anyOf : undefined
-  const hasNullAnyOf = anyOf?.some((item) => isRecord(item) && item.type === "null") ?? false
-  const anyOfTypes = hasNullAnyOf ? anyOf?.filter((item) => !isRecord(item) || item.type !== "null") : anyOf
-  const flattenedAnyOf = hasNullAnyOf && anyOfTypes?.length === 1 ? projectNode(anyOfTypes[0], true) : undefined
-  const result = Object.fromEntries(
-    [
-      ["description", schema.description],
-      ["required", schema.required],
-      ["format", schema.format],
-      ["type", types ? (types.length === 0 ? "null" : undefined) : schema.type],
-      [
-        "nullable",
-        (Array.isArray(schema.type) && schema.type.includes("null") && types && types.length > 0) || hasNullAnyOf
-          ? true
-          : undefined,
-      ],
-      ["enum", schema.const !== undefined ? [schema.const] : schema.enum],
-      [
-        "properties",
-        isRecord(schema.properties)
-          ? Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [key, projectNode(value, true)]))
-          : undefined,
-      ],
-      [
-        "items",
-        Array.isArray(schema.items)
-          ? schema.items.map((item) => projectNode(item, true))
-          : schema.items === undefined
-            ? undefined
-            : projectNode(schema.items, true),
-      ],
-      ["allOf", Array.isArray(schema.allOf) ? schema.allOf.map((item) => projectNode(item, true)) : undefined],
-      [
-        "anyOf",
-        anyOfTypes
-          ? hasNullAnyOf && anyOfTypes.length === 1
-            ? undefined
-            : anyOfTypes.map((item) => projectNode(item, true))
-          : types && types.length > 0
-            ? types.map((type) => ({ type }))
-            : undefined,
-      ],
-      ["oneOf", Array.isArray(schema.oneOf) ? schema.oneOf.map((item) => projectNode(item, true)) : undefined],
-      ["minLength", schema.minLength],
-    ].filter((entry) => entry[1] !== undefined),
-  )
-  return flattenedAnyOf ? { ...result, ...flattenedAnyOf } : result
-}
-
-export const convert = (schema: unknown) => projectNode(sanitizeNode(schema))
-
-export * as GeminiToolSchema from "./gemini-tool-schema.js"
@@ -1,6 +1,6 @@
-import type { JsonSchema, LanguageModelToolSchemaCompatibility } from "../../schema/index.js"
+import type { JsonSchema, LanguageModel, LanguageModelSanitizerCompatibility } from "../../schema/index.js"
 import { isRecord } from "../../utils/record.js"
-import { GeminiToolSchema } from "./gemini-tool-schema.js"
+import { GeminiJsonSchema } from "./gemini-json-schema.js"

 const tupleItemsSchema = (items: ReadonlyArray<unknown>) => {
  const projected = items.map(moonshotNode)
@@ -46,18 +46,29 @@ const moonshot = (schema: JsonSchema): JsonSchema => {
 const openAI = (schema: JsonSchema): JsonSchema => schema
 const responses = openAI

-const gemini = (schema: JsonSchema): JsonSchema => GeminiToolSchema.convert(schema) ?? {}
+const gemini = GeminiJsonSchema.normalize

+const MODEL_NAMES = [
+  [/gemini/i, "gemini"],
+  [/kimi/i, "moonshot"],
+] as const
+
+// An explicit `sanitizer` wins, and `none` opts out. Otherwise the protocol's own default
+// applies (the Gemini API always uses Gemini's rules), then the model name selects the family's rules
+// so models reached through gateways and OpenAI-compatible endpoints get the same handling.
 const modelCompatibility = (
  schema: JsonSchema,
-  compatibility: LanguageModelToolSchemaCompatibility | undefined,
+  model: LanguageModel,
+  protocolDefault?: LanguageModelSanitizerCompatibility,
 ): JsonSchema => {
-  if (compatibility === undefined) return schema
-  switch (compatibility) {
+  switch (model.compatibility?.sanitizer ?? protocolDefault ?? MODEL_NAMES.find(([name]) => name.test(model.id))?.[1]) {
    case "gemini":
      return gemini(schema)
    case "moonshot":
      return moonshot(schema)
+    case "none":
+    case undefined:
+      return schema
  }
 }

@@ -113,19 +113,19 @@ export const configure = (input: Config = {}) => {
        supportsStore: false,
        supportsStrictMode: false,
        supportsPromptCacheKey: true,
-        toolSchema: "moonshot",
+        sanitizer: "moonshot",
        reasoningField: "reasoning_content",
      },
    })
  const messages = (modelID: string | ModelID) =>
    messagesRoute.with(defaults).model<MessagesOptionsInput>({
      id: modelID,
-      compatibility: { requireSignature: false, toolSchema: "moonshot" },
+      compatibility: { requireSignature: false, sanitizer: "moonshot" },
    })
  const responses = (modelID: string | ModelID) =>
    responsesRoute
      .with(defaults)
-      .model<ResponsesOptionsInput>({ id: modelID, compatibility: { toolSchema: "moonshot" } })
+      .model<ResponsesOptionsInput>({ id: modelID, compatibility: { sanitizer: "moonshot" } })
  return { id, model: chat, chat, messages, responses, configure }
 }

@@ -1,12 +1,15 @@
-import { Config, Effect, Redacted } from "effect"
+import { Config, Effect, Option, Redacted } from "effect"
 import { Headers } from "effect/unstable/http"
-import { AuthenticationError, InvalidRequestError, AIError, type HttpOptions } from "../schema/index.js"
+import { AuthenticationError, AIError, type HttpOptions } from "../schema/index.js"

 export class MissingCredentialError extends Error {
  readonly _tag = "MissingCredentialError"

-  constructor(readonly source: string) {
-    super(`Missing auth credential: ${source}`)
+  constructor(
+    readonly source: string,
+    message = `Missing auth credential: ${source}`,
+  ) {
+    super(message)
  }
 }

@@ -89,7 +92,14 @@ export const optional = (secret: Secret | undefined, source = "optional value")
    ? credential(Effect.fail(new MissingCredentialError(source)))
    : credentialFromSecret(secret, source)

-export const config = (name: string) => credentialFromSecret(Config.redacted(name), name)
+export const config = (name: string) =>
+  credential(
+    Effect.gen(function* () {
+      const secret = yield* Config.option(Config.redacted(name))
+      if (Option.isSome(secret) && Redacted.value(secret.value) !== "") return secret.value
+      return yield* Effect.fail(new MissingCredentialError(name, `${name} is not set`))
+    }),
+  )

 export const effect = (load: Effect.Effect<Redacted.Redacted, CredentialError>) => credential(load)

@@ -145,15 +155,10 @@ export function scheme(name: string, source?: Secret | Credential) {
 }

 const toAIError = (error: AuthError): AIError => {
-  if (error instanceof MissingCredentialError || error instanceof Config.ConfigError) {
-    return new AIError({
-      reason:
-        error instanceof MissingCredentialError
-          ? new AuthenticationError({ message: error.message, cause: error })
-          : new InvalidRequestError({ message: `Failed to resolve auth config: ${error.message}`, cause: error }),
-    })
-  }
-  return error
+  if (error instanceof AIError) return error
+  const message =
+    error instanceof MissingCredentialError ? error.message : `Failed to resolve auth config: ${error.message}`
+  return new AIError({ reason: new AuthenticationError({ message, cause: error }) })
 }

 export const toEffect =
@@ -261,7 +261,9 @@ const unsupportedCompaction = (request: LLMRequest, mechanism: string | undefine
  })
 }

-export class Service extends Context.Service<Service, Interface>()("@opencode/LLMClient") {}
+export class LLMClientService extends Context.Service<LLMClientService, Interface>()("@opencode/LLMClient") {}
+export const Service = LLMClientService
+export type Service = LLMClientService

 const resolveRequestOptions = (request: LLMRequest) => {
  const messages = normalizeToolHistory(request.messages)
@@ -19,4 +19,8 @@ export type HttpMiddleware = (
  handler: HttpHandler,
 ) => Effect.Effect<HttpClientResponse.HttpClientResponse, Error>

-export class Service extends Context.Service<Service, Interface>()("@opencode/AI/RequestExecutor") {}
+export class RequestExecutorService extends Context.Service<RequestExecutorService, Interface>()(
+  "@opencode/AI/RequestExecutor",
+) {}
+export const Service = RequestExecutorService
+export type Service = RequestExecutorService
@@ -255,4 +255,20 @@ export const layer: Layer.Layer<Service, never, HttpClient.HttpClient> = Layer.e

 export const fetchLayer = layer.pipe(Layer.provide(FetchHttpClient.layer))

+/** Run `fn` on every request: it sees the raw response before status classification, inside middleware already on `executor`, and outside per-call middleware. */
+export const middleware = (fn: HttpMiddleware, executor: Layer.Layer<Service> = fetchLayer): Layer.Layer<Service> =>
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const inner = yield* Service
+      return Service.of({
+        execute: (request, next) =>
+          inner.execute(
+            request,
+            next === undefined ? fn : (input, handler) => fn(input, (forwarded) => next(forwarded, handler)),
+          ),
+      })
+    }),
+  ).pipe(Layer.provide(executor))
+
 export * as RequestExecutor from "./executor.js"
@@ -7,7 +7,7 @@ export type {
  RouteDefaultsInput,
  AnyRoute,
  Interface as LLMClientShape,
-  Service as LLMClientService,
+  LLMClientService,
  StreamOptions,
  CompactMethod,
  CompactionOperations,
@@ -152,8 +152,9 @@ export const ReasoningEffort = Schema.declare<ReasoningEffort>(
  { title: "ReasoningEffort" },
 )

-export const LanguageModelToolSchemaCompatibility = Schema.Literals(["gemini", "moonshot"])
-export type LanguageModelToolSchemaCompatibility = Schema.Schema.Type<typeof LanguageModelToolSchemaCompatibility>
+/** Tool schema sanitizer for a model family. `none` opts out of the protocol and model-name defaults. */
+export const LanguageModelSanitizerCompatibility = Schema.Literals(["gemini", "moonshot", "none"])
+export type LanguageModelSanitizerCompatibility = Schema.Schema.Type<typeof LanguageModelSanitizerCompatibility>

 export const LanguageModelMaxTokensFieldCompatibility = Schema.Literals(["max_completion_tokens", "max_tokens"])
 export type LanguageModelMaxTokensFieldCompatibility = Schema.Schema.Type<
@@ -163,7 +164,7 @@ export type LanguageModelMaxTokensFieldCompatibility = Schema.Schema.Type<
 export class LanguageModelCompatibility extends Schema.Class<LanguageModelCompatibility>(
  "LLM.LanguageModelCompatibility",
 )({
-  toolSchema: Schema.optional(LanguageModelToolSchemaCompatibility),
+  sanitizer: Schema.optional(LanguageModelSanitizerCompatibility),
  reasoningField: Schema.optional(Schema.String),
  /** Require every assistant message to include its reasoning field, even when empty. */
  requireReasoning: Schema.optional(Schema.Boolean),
@@ -12,7 +12,9 @@ export interface Interface {
  ) => Stream.Stream<SpeechEvent, AIError>
 }

-export class Service extends Context.Service<Service, Interface>()("@opencode/SpeechClient") {}
+export class SpeechClientService extends Context.Service<SpeechClientService, Interface>()("@opencode/SpeechClient") {}
+export const Service = SpeechClientService
+export type Service = SpeechClientService

 export const generate = <Options extends SpeechOptions>(
  request: SpeechRequestFor<Options>,
@@ -30,7 +30,11 @@ export interface Interface {
  ) => Effect.Effect<Generation<TranscriptionResponse>, AIError>
 }

-export class Service extends Context.Service<Service, Interface>()("@opencode/TranscriptionClient") {}
+export class TranscriptionClientService extends Context.Service<TranscriptionClientService, Interface>()(
+  "@opencode/TranscriptionClient",
+) {}
+export const Service = TranscriptionClientService
+export type Service = TranscriptionClientService

 export const generate = <Options extends TranscriptionOptions>(
  request: TranscriptionRequestFor<Options>,
@@ -48,9 +48,12 @@ const EXTENSIONS: Readonly<Record<string, string>> = {
  csv: "text/csv",
 }

-export const extensionMediaType = (path: string): string | undefined =>
+const extensionMediaType = (path: string): string | undefined =>
  EXTENSIONS[path.slice(path.lastIndexOf(".") + 1).toLowerCase()]

+/** Media type of a file's contents: sniffed magic bytes, then the path's extension. */
+export const fileMediaType = (bytes: Uint8Array, path: string) => detectMediaType(bytes) ?? extensionMediaType(path)
+
 const EXTENSION_ALIASES: Readonly<Record<string, string>> = {
  "audio/mp3": "mp3",
  "audio/m4a": "m4a",
@@ -29,7 +29,9 @@ export interface Interface {
  ) => Stream.Stream<VideoEvent, AIError>
 }

-export class Service extends Context.Service<Service, Interface>()("@opencode/VideoClient") {}
+export class VideoClientService extends Context.Service<VideoClientService, Interface>()("@opencode/VideoClient") {}
+export const Service = VideoClientService
+export type Service = VideoClientService

 export const start = <Options extends VideoOptions>(
  request: VideoRequestFor<Options>,
@@ -92,6 +92,15 @@ describe("Auth", () => {
    }),
  )

+  it.effect("reports a missing config credential as Authentication naming the variable", () =>
+    Effect.gen(function* () {
+      const error = yield* Auth.toEffect(Auth.config("OPENAI_API_KEY").bearer())(input).pipe(withEnv({}), Effect.flip)
+
+      expect(error.reason._tag).toBe("Authentication")
+      expect(error.message).toContain("OPENAI_API_KEY is not set")
+    }),
+  )
+
  it.effect("can intentionally leave auth untouched", () =>
    Effect.gen(function* () {
      const headers = yield* Auth.none.apply(input)
@@ -1,11 +1,11 @@
 import { describe, expect } from "bun:test"
-import { Deferred, Effect, Fiber, Ref, Stream } from "effect"
+import { Deferred, Effect, Fiber, Layer, Ref, Stream } from "effect"
 import { Headers, HttpClientError, HttpClientRequest } from "effect/unstable/http"
 import { LLM, AIError, HttpContext, InvalidProviderOutputError, TransportError } from "../src/index.js"
 import { LLMClient, RequestExecutor, WebSocketTransport, type WebSocketChannelExecutor } from "../src/route.js"
 import { route } from "../src/protocols/openai-chat.js"
 import { configure } from "../src/providers/openai.js"
-import { dynamicResponse, fixedResponse, systemError } from "./lib/http.js"
+import { dynamicResponse, fixedResponse, handlerLayer, systemError } from "./lib/http.js"
 import { deltaChunk } from "./lib/openai-chunks.js"
 import { sseEvents, sseRaw } from "./lib/sse.js"
 import { it } from "./lib/effect.js"
@@ -195,6 +195,26 @@ describe("RequestExecutor", () => {
    ),
  )

+  it.effect("runs shared middleware outside per-call middleware", () => {
+    const calls: Array<string> = []
+    const record = (name: string) => Effect.sync(() => calls.push(name))
+    const base = RequestExecutor.layer.pipe(
+      Layer.provide(handlerLayer((input) => record("handler").pipe(Effect.as(input.respond("ok"))))),
+    )
+    return Effect.gen(function* () {
+      const executor = yield* RequestExecutor.Service
+      yield* executor.execute(request, (input, next) => record("per-call").pipe(Effect.andThen(next(input))))
+      expect(calls).toEqual(["outer", "per-call", "handler"])
+      calls.length = 0
+      yield* executor.execute(request)
+      expect(calls).toEqual(["outer", "handler"])
+    }).pipe(
+      Effect.provide(
+        RequestExecutor.middleware((input, next) => record("outer").pipe(Effect.andThen(next(input))), base),
+      ),
+    )
+  })
+
  it.effect("classifies context overflow responses", () =>
    Effect.gen(function* () {
      const executor = yield* RequestExecutor.Service
@@ -1,8 +1,11 @@
 import { describe, expect, test } from "bun:test"
+import { Effect, Layer } from "effect"
 import {
+  AIClient,
  AIError,
  Generation,
  Image,
+  ImageClient,
  LanguageModel,
  LLM,
  LLMClient,
@@ -11,10 +14,11 @@ import {
  Speech,
  SpeechClient,
  SpeechEvent,
+  TranscriptionClient,
  Video,
  VideoClient,
 } from "@opencode/ai"
-import { Route, Protocol, WebSocketTransport } from "@opencode/ai/route"
+import { Route, Protocol, RequestExecutor, WebSocketTransport } from "@opencode/ai/route"
 import { Provider as ProviderSubpath } from "@opencode/ai/provider"
 import {
  AssemblyAI,
@@ -76,6 +80,28 @@ describe("public exports", () => {
    expect(EvaluationClient.fetchLayer).toBeDefined()
  })

+  test("AIClient.layerWith shares one executor across every client", async () => {
+    let built = 0
+    const counting = Layer.effect(
+      RequestExecutor.Service,
+      Effect.sync(() => {
+        built++
+        return RequestExecutor.Service.of({ execute: () => Effect.die("unexpected request") })
+      }),
+    )
+    await Effect.runPromise(
+      Effect.gen(function* () {
+        yield* LLMClient.Service
+        yield* ImageClient.Service
+        yield* VideoClient.Service
+        yield* SpeechClient.Service
+        yield* TranscriptionClient.Service
+        yield* RequestExecutor.Service
+      }).pipe(Effect.provide(AIClient.layerWith(counting))),
+    )
+    expect(built).toBe(1)
+  })
+
  test("route barrel exposes route-authoring APIs", () => {
    expect(Route.make).toBeFunction()
    expect(Protocol.make).toBeFunction()
@@ -1,28 +0,0 @@
-{
-  "version": 1,
-  "metadata": {
-    "name": "gemini/streams-text",
-    "recordedAt": "2026-04-28T21:18:47.483Z",
-    "tags": ["prefix:gemini", "provider:google", "protocol:gemini"]
-  },
-  "interactions": [
-    {
-      "transport": "http",
-      "request": {
-        "method": "POST",
-        "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse",
-        "headers": {
-          "content-type": "application/json"
-        },
-        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"Reply with exactly: Hello!\"}]}],\"systemInstruction\":{\"parts\":[{\"text\":\"You are concise.\"}]},\"generationConfig\":{\"maxOutputTokens\":80,\"temperature\":0}}"
-      },
-      "response": {
-        "status": 200,
-        "headers": {
-          "content-type": "text/event-stream"
-        },
-        "body": "data: {\"candidates\": [{\"content\": {\"parts\": [{\"text\": \"Hello!\"}],\"role\": \"model\"},\"finishReason\": \"STOP\",\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 11,\"candidatesTokenCount\": 2,\"totalTokenCount\": 29,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 11}],\"thoughtsTokenCount\": 16},\"modelVersion\": \"gemini-2.5-flash\",\"responseId\": \"NyTxaczMAZ-b_uMP6u--iQg\"}\r\n\r\n"
-      }
-    }
-  ]
-}
@@ -1,28 +0,0 @@
-{
-  "version": 1,
-  "metadata": {
-    "name": "gemini/streams-tool-call",
-    "recordedAt": "2026-04-28T21:18:48.285Z",
-    "tags": ["prefix:gemini", "provider:google", "protocol:gemini", "tool"]
-  },
-  "interactions": [
-    {
-      "transport": "http",
-      "request": {
-        "method": "POST",
-        "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse",
-        "headers": {
-          "content-type": "application/json"
-        },
-        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"Call get_weather with city exactly Paris.\"}]}],\"systemInstruction\":{\"parts\":[{\"text\":\"Call tools exactly as requested.\"}]},\"tools\":[{\"functionDeclarations\":[{\"name\":\"get_weather\",\"description\":\"Get current weather for a city.\",\"parameters\":{\"required\":[\"city\"],\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}}}}]}],\"toolConfig\":{\"functionCallingConfig\":{\"mode\":\"ANY\",\"allowedFunctionNames\":[\"get_weather\"]}},\"generationConfig\":{\"maxOutputTokens\":80,\"temperature\":0}}"
-      },
-      "response": {
-        "status": 200,
-        "headers": {
-          "content-type": "text/event-stream"
-        },
-        "body": "data: {\"candidates\": [{\"content\": {\"parts\": [{\"functionCall\": {\"name\": \"get_weather\",\"args\": {\"city\": \"Paris\"}},\"thoughtSignature\": \"CiQBDDnWx5RcSsS1UMbykQ5HWlrMu6wrxXGUhmZ0uRKLaMhDZaEKXwEMOdbHVoJAlfbOQyKB378pDZ/gkjWr3HP+dWw1us1kMG22g4G3oJvuTq/SrWS+7KYtSlvOxCKhW2l/2/TczpyGyGmANmsusDcxF1SKOYA5/8Hg0nI24MAlT3+91V/MCoUBAQw51seClFLy3E71v2H44F1kpmjgz8FeTRZofrjbaazfrT+w8Yxgdr3UgGagLMY4OadZemQTWckq9IAqRum78hrBg6NGtQvn15SbtfTNqI4PcxX/+qPo4/g4/ZT5kVORDhVqO8BVP/RA5GQ3ce3sRK8hSkvQlXSoXIPpHh6x7hBezIGXzw==\"}],\"role\": \"model\"},\"finishReason\": \"STOP\",\"index\": 0,\"finishMessage\": \"Model generated function call(s).\"}],\"usageMetadata\": {\"promptTokenCount\": 55,\"candidatesTokenCount\": 15,\"totalTokenCount\": 115,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 55}],\"thoughtsTokenCount\": 45},\"modelVersion\": \"gemini-2.5-flash\",\"responseId\": \"NyTxaYuTJ_OW_uMPgIPKgAg\"}\r\n\r\n"
-      }
-    }
-  ]
-}
@@ -7,7 +7,7 @@
      "protocol:gemini"
    ],
    "name": "google-vertex/calls-a-tool",
-    "recordedAt": "2026-09-22T03:46:29.725Z"
+    "recordedAt": "2026-09-24T01:06:19.246Z"
  },
  "interactions": [
    {
@@ -18,14 +18,14 @@
        "headers": {
          "content-type": "application/json"
        },
-        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"What is the weather in Paris? Use the lookup_weather tool.\"}]}],\"tools\":[{\"functionDeclarations\":[{\"name\":\"lookup_weather\",\"description\":\"Look up the current weather for a city\",\"parameters\":{\"required\":[\"city\"],\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}}}}]}]}"
+        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"What is the weather in Paris? Use the lookup_weather tool.\"}]}],\"tools\":[{\"functionDeclarations\":[{\"name\":\"lookup_weather\",\"description\":\"Look up the current weather for a city\",\"parametersJsonSchema\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"]}}]}]}"
      },
      "response": {
        "status": 200,
        "headers": {
          "content-type": "text/event-stream"
        },
-        "body": "data: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"functionCall\": {\"name\": \"lookup_weather\",\"args\": {\"city\": \"Paris\"},\"id\": \"call_28936\"},\"thoughtSignature\": \"AY89a1/MVeBxtwu9l/96clFobOrrd7Q5MTf5o8/A22fc++1EsFYVeCFx9WCGmJ+D3yW3FWlRXKtJECYfprSoxixCSOYBNiV9g8/IkejbAxF26k1vxTsHkoqts0O2s8GqqBSRAavJfKQ/taTRbPuIq+b+RKZ8SDJFoWDnFjXpdS5S164uJTjmgs4ALd8oB1oQRycMsTbAY51TmkcNUnhARpjKQfqiizz4KfSRFjx7xDnza0v4jj73m2GV86eLDhVT7trIT+Dl5DsJt6RBLOE2Amse54mcpIbsYaANlY1YDU6FKuUBqnuwpl0OfhMXwWuYMogv1tH/0rTXsqNwmHyt/b9ZZXqYCdFXpMGt8udmoZ0d\"}]}}],\"usageMetadata\": {\"trafficType\": \"ON_DEMAND\"},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-22T03:46:28.953809Z\",\"responseId\": \"FPqxatGbOsSorb8PtY2z8Q4\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"text\": \"\"}]},\"finishReason\": \"STOP\"}],\"usageMetadata\": {\"promptTokenCount\": 39,\"candidatesTokenCount\": 16,\"totalTokenCount\": 93,\"trafficType\": \"ON_DEMAND\",\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 39}],\"candidatesTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 16}],\"thoughtsTokenCount\": 38},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-22T03:46:28.953809Z\",\"responseId\": \"FPqxatGbOsSorb8PtY2z8Q4\"}\r\n\r\n"
+        "body": "data: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"functionCall\": {\"name\": \"lookup_weather\",\"args\": {\"city\": \"Paris\"},\"id\": \"call_554608\"},\"thoughtSignature\": \"AY89a19hRAmVFgUw7vo3hvQF7VpSnCGYSRXo34+yjCySmgHtvL/4LEf6V2F12glreaWUixVINDFWR+DLprZZxayR8gb+wZMWssV0Cbv1fDPYV6qxggRiLEKnG6A7UY+vmhXUO5IAtL06Ud24IYd+3QI0T05gzSnwqy7Uotw9J5B8LSr76MvbDncgyeWcBhZSpxxi2XPJxZqR6N/7gwxRSW3KMBp0CKHnU4MF+t0fN1oQ2uSWCxQAYW0nq8TQL6nYYgShN35VeGJ5+UvJ8OIYC0COQ1u/VNdqmJs2uRs3dHGzXzDSWdb/lIcqtzyKRLsIa7RWYmF1xZhEQZkXGGf9yco8e1OOovYhR/cEwE2+aw1scl3Deg2+D2R1PiFwwoZuMV+lIj3IwNexjLd56ZO/7QpzaX2K97b11duH4mBjgfG0x7c3+r9raD17quokhgW1ffoPiXiaemvD6mA84kkDIc4jxSnwNwuVxTgUkEwswub1C1lrlnzzeLHjnMvdopdHIViDsdcfRnXkhIwGyvr+QBSuz7yF1V/Vw+9MxYVVNM/7eQPpMxjJHpHTBMWqtzkC9zE6wK2iWr49AJm8ZpMS8a9uhW0OAksUslv5gvWKDEecaufO/66w+xltgnvDh2NVJuthULuG+nWnxGRq4ZbX00s3p0/J1vqQZcLsi37RpAs75g==\"}]}}],\"usageMetadata\": {\"trafficType\": \"ON_DEMAND\"},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-24T01:06:18.093130Z\",\"responseId\": \"ine0asrXBbui3dAPpNDS8QE\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"text\": \"\"}]},\"finishReason\": \"STOP\"}],\"usageMetadata\": {\"promptTokenCount\": 39,\"candidatesTokenCount\": 16,\"totalTokenCount\": 156,\"trafficType\": \"ON_DEMAND\",\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 39}],\"candidatesTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 16}],\"thoughtsTokenCount\": 101},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-24T01:06:18.093130Z\",\"responseId\": \"ine0asrXBbui3dAPpNDS8QE\"}\r\n\r\n"
      }
    }
  ]
@@ -7,7 +7,7 @@
      "protocol:gemini"
    ],
    "name": "google-vertex/continues-after-a-tool-result",
-    "recordedAt": "2026-09-22T03:46:30.691Z"
+    "recordedAt": "2026-09-24T01:06:20.321Z"
  },
  "interactions": [
    {
@@ -18,14 +18,14 @@
        "headers": {
          "content-type": "application/json"
        },
-        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"What is the weather in Paris?\"}]},{\"role\":\"model\",\"parts\":[{\"functionCall\":{\"id\":\"call_paris_1\",\"name\":\"lookup_weather\",\"args\":{\"city\":\"Paris\"}},\"thoughtSignature\":\"skip_thought_signature_validator\"}]},{\"role\":\"user\",\"parts\":[{\"functionResponse\":{\"id\":\"call_paris_1\",\"name\":\"lookup_weather\",\"response\":{\"name\":\"lookup_weather\",\"content\":\"18C, light rain\"}}}]}],\"tools\":[{\"functionDeclarations\":[{\"name\":\"lookup_weather\",\"description\":\"Look up the current weather for a city\",\"parameters\":{\"required\":[\"city\"],\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}}}}]}]}"
+        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"What is the weather in Paris?\"}]},{\"role\":\"model\",\"parts\":[{\"functionCall\":{\"id\":\"call_paris_1\",\"name\":\"lookup_weather\",\"args\":{\"city\":\"Paris\"}},\"thoughtSignature\":\"skip_thought_signature_validator\"}]},{\"role\":\"user\",\"parts\":[{\"functionResponse\":{\"id\":\"call_paris_1\",\"name\":\"lookup_weather\",\"response\":{\"name\":\"lookup_weather\",\"content\":\"18C, light rain\"}}}]}],\"tools\":[{\"functionDeclarations\":[{\"name\":\"lookup_weather\",\"description\":\"Look up the current weather for a city\",\"parametersJsonSchema\":{\"type\":\"object\",\"properties\":{\"city\":{\"type\":\"string\"}},\"required\":[\"city\"]}}]}]}"
      },
      "response": {
        "status": 200,
        "headers": {
          "content-type": "text/event-stream"
        },
-        "body": "data: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"text\": \"The weather\"}]}}],\"usageMetadata\": {\"trafficType\": \"ON_DEMAND\"},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-22T03:46:29.830958Z\",\"responseId\": \"Ffqxau7bMoCOrb8P_Iu5sA0\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"text\": \" in Paris is currently 18°C with light rain.\"}]}}],\"usageMetadata\": {\"trafficType\": \"ON_DEMAND\"},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-22T03:46:29.830958Z\",\"responseId\": \"Ffqxau7bMoCOrb8P_Iu5sA0\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"text\": \"\",\"thoughtSignature\": \"AY89a18aVI8Uxr2VaOI822u0DyuQdy4B00uhLnjqYb5Qb6Mkscccm018knLtYThB5UX8dRv1VFsORSQ0Qo6Gx9RCng2AK9EPce7p\"}]},\"finishReason\": \"STOP\"}],\"usageMetadata\": {\"promptTokenCount\": 59,\"candidatesTokenCount\": 15,\"totalTokenCount\": 74,\"trafficType\": \"ON_DEMAND\",\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 59}],\"candidatesTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 15}]},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-22T03:46:29.830958Z\",\"responseId\": \"Ffqxau7bMoCOrb8P_Iu5sA0\"}\r\n\r\n"
+        "body": "data: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"text\": \"The weather\"}]}}],\"usageMetadata\": {\"trafficType\": \"ON_DEMAND\"},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-24T01:06:19.664329Z\",\"responseId\": \"i3e0aonGKPCnrb8Pm97yiQs\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"text\": \" in Paris is currently 18°C with light rain.\"}]}}],\"usageMetadata\": {\"trafficType\": \"ON_DEMAND\"},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-24T01:06:19.664329Z\",\"responseId\": \"i3e0aonGKPCnrb8Pm97yiQs\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"role\": \"model\",\"parts\": [{\"text\": \"\",\"thoughtSignature\": \"AY89a19mRwbMV0dQccZShfDptLQ20vI7Rg/LSyPDwW1Wt62fQvRT/2nUWW13cMmgYbd2VGGtrZIbnj+hxHMZt1NK2RyJIkg/FB13\"}]},\"finishReason\": \"STOP\"}],\"usageMetadata\": {\"promptTokenCount\": 59,\"candidatesTokenCount\": 15,\"totalTokenCount\": 74,\"trafficType\": \"ON_DEMAND\",\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 59}],\"candidatesTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 15}]},\"modelVersion\": \"gemini-3.5-flash\",\"createTime\": \"2026-09-24T01:06:19.664329Z\",\"responseId\": \"i3e0aonGKPCnrb8Pm97yiQs\"}\r\n\r\n"
      }
    }
  ]
@@ -1,9 +1,16 @@
 {
  "version": 1,
  "metadata": {
-    "tags": ["prefix:pdf", "pdf", "provider:google", "protocol:gemini", "tool", "tool-result"],
+    "tags": [
+      "prefix:pdf",
+      "pdf",
+      "provider:google",
+      "protocol:gemini",
+      "tool",
+      "tool-result"
+    ],
    "name": "pdf/gemini-tool-result",
-    "recordedAt": "2026-07-22T18:21:59.606Z"
+    "recordedAt": "2026-09-24T01:06:23.498Z"
  },
  "interactions": [
    {
@@ -14,14 +21,14 @@
        "headers": {
          "content-type": "application/json"
        },
-        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"Use read_pdf with path verification.pdf and return the verification code.\"}]}],\"systemInstruction\":{\"parts\":[{\"text\":\"Call read_pdf exactly once with path verification.pdf, then reply only with the verification code from its PDF.\"}]},\"tools\":[{\"functionDeclarations\":[{\"name\":\"read_pdf\",\"description\":\"Read the attached PDF.\",\"parameters\":{\"required\":[\"path\"],\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}}}}]}],\"generationConfig\":{\"maxOutputTokens\":256,\"temperature\":0}}"
+        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"Use read_pdf with path verification.pdf and return the verification code.\"}]}],\"systemInstruction\":{\"parts\":[{\"text\":\"Call read_pdf exactly once with path verification.pdf, then reply only with the verification code from its PDF.\"}]},\"tools\":[{\"functionDeclarations\":[{\"name\":\"read_pdf\",\"description\":\"Read the attached PDF.\",\"parametersJsonSchema\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"],\"additionalProperties\":false}}]}],\"generationConfig\":{\"maxOutputTokens\":256,\"temperature\":0}}"
      },
      "response": {
        "status": 200,
        "headers": {
          "content-type": "text/event-stream"
        },
-        "body": "data: {\"candidates\": [{\"content\": {\"parts\": [{\"functionCall\": {\"name\": \"read_pdf\",\"args\": {\"path\": \"verification.pdf\"},\"id\": \"58shgmez\"},\"thoughtSignature\": \"EqkCCqYCARFNMg/JrCTv5i3zYENFBVpZNFL3pbzJmi5Eu387ncF703xFMB4pwyaP7a1gi49EqBhCI2hWOpesU5nZQOLAhGgExKGa2GM+HzpEB5g62r0NFblm/BGkVZaImTuHR7bytfRC5jHQlHKo4OS27OLUVjvkMkBIYsvjhDErY7niERbXJVpyxTVqUf1GgZMSu8kC9/5WDlMs9xVKNT/6KMW4PhhSR9nXg4KZUa+bC03/ydhsWWgBa5aLCgvTq7WPj217xIsmUkSiRedIffPsUSNjYdMHUvWi8bOlvM1veEEP6GIfv5h9gXXzjnHbEHfQxV8PZuBAyY7iM6nqyfkJNdkZ1HdB7DXMBsMsRN6SgrIrFoXX2WaGrkoEI5tdZx1t/gdwF1jEVT6k\"}],\"role\": \"model\"},\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 81,\"candidatesTokenCount\": 18,\"totalTokenCount\": 151,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 81}],\"thoughtsTokenCount\": 52,\"serviceTier\": \"standard\"},\"modelVersion\": \"gemini-3.5-flash\",\"responseId\": \"RAphaui3OaSHz7IPy8Kb4Ak\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"parts\": [{\"text\": \"\"}],\"role\": \"model\"},\"finishReason\": \"STOP\",\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 81,\"candidatesTokenCount\": 18,\"totalTokenCount\": 151,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 81}],\"thoughtsTokenCount\": 52,\"serviceTier\": \"standard\"},\"modelVersion\": \"gemini-3.5-flash\",\"responseId\": \"RAphaui3OaSHz7IPy8Kb4Ak\"}\r\n\r\n"
+        "body": "data: {\"candidates\": [{\"content\": {\"parts\": [{\"functionCall\": {\"name\": \"read_pdf\",\"args\": {\"path\": \"verification.pdf\"},\"id\": \"call_475949\"},\"thoughtSignature\": \"Et4CCtsCAWkUfRPfQWeGIEQ/AhexY97IZoK8aNLr2EbW3nufnAXpa1y74z7qH1Tdk20j5EC57BSBbdy5u6xFHNomzZhGFVmdVlhgZFXGSO8F8K4t8rqQWUJZSDH4dFaC95KpUTfp5CAMepbOuc/dGLgXfVsSV0e/HvUcdWKoEz8Jlsgk59nexqSsdl/kGzuuIeW6zS5r8JHus+PfRzvSgua4B9OpDU9WWPCJZu93NLbXJELbZ330h7CP+uxXoo1Puu0KSrvLman8Geoc0nagMx895L0gO3CsbB+PpijQ6Pt6YAaiv1V2MeOCUKCYUpk+77MjC6RnsTFTRaJYJ5PPkniuRKedp/DF1aMj7nGxQ6BpHOMq9mjw2zlH3I2kJi1wqm+amVz30vTHa31xTH88w+IUc1yNdLAzdVJV+/+0mqw8bLweSjSHFxZN0NIv6aczAIS5stoGobNDO4bRGDETH3Q=\"}],\"role\": \"model\"},\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 81,\"candidatesTokenCount\": 18,\"totalTokenCount\": 152,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 81}],\"thoughtsTokenCount\": 53,\"serviceTier\": \"standard\"},\"modelVersion\": \"gemini-3.5-flash\",\"responseId\": \"jHe0apWcM92aqtsP8t2LyAg\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"parts\": [{\"text\": \"\"}],\"role\": \"model\"},\"finishReason\": \"STOP\",\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 81,\"candidatesTokenCount\": 18,\"totalTokenCount\": 152,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 81}],\"thoughtsTokenCount\": 53,\"serviceTier\": \"standard\"},\"modelVersion\": \"gemini-3.5-flash\",\"responseId\": \"jHe0apWcM92aqtsP8t2LyAg\"}\r\n\r\n"
      }
    },
    {
@@ -32,14 +39,14 @@
        "headers": {
          "content-type": "application/json"
        },
-        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"Use read_pdf with path verification.pdf and return the verification code.\"}]},{\"role\":\"model\",\"parts\":[{\"functionCall\":{\"id\":\"58shgmez\",\"name\":\"read_pdf\",\"args\":{\"path\":\"verification.pdf\"}},\"thoughtSignature\":\"EqkCCqYCARFNMg/JrCTv5i3zYENFBVpZNFL3pbzJmi5Eu387ncF703xFMB4pwyaP7a1gi49EqBhCI2hWOpesU5nZQOLAhGgExKGa2GM+HzpEB5g62r0NFblm/BGkVZaImTuHR7bytfRC5jHQlHKo4OS27OLUVjvkMkBIYsvjhDErY7niERbXJVpyxTVqUf1GgZMSu8kC9/5WDlMs9xVKNT/6KMW4PhhSR9nXg4KZUa+bC03/ydhsWWgBa5aLCgvTq7WPj217xIsmUkSiRedIffPsUSNjYdMHUvWi8bOlvM1veEEP6GIfv5h9gXXzjnHbEHfQxV8PZuBAyY7iM6nqyfkJNdkZ1HdB7DXMBsMsRN6SgrIrFoXX2WaGrkoEI5tdZx1t/gdwF1jEVT6k\"}]},{\"role\":\"user\",\"parts\":[{\"functionResponse\":{\"id\":\"58shgmez\",\"name\":\"read_pdf\",\"response\":{\"name\":\"read_pdf\",\"content\":\"PDF read successfully\"},\"parts\":[{\"inlineData\":{\"mimeType\":\"application/pdf\",\"data\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\"}}]}}]}],\"systemInstruction\":{\"parts\":[{\"text\":\"Call read_pdf exactly once with path verification.pdf, then reply only with the verification code from its PDF.\"}]},\"tools\":[{\"functionDeclarations\":[{\"name\":\"read_pdf\",\"description\":\"Read the attached PDF.\",\"parameters\":{\"required\":[\"path\"],\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}}}}]}],\"generationConfig\":{\"maxOutputTokens\":256,\"temperature\":0}}"
+        "body": "{\"contents\":[{\"role\":\"user\",\"parts\":[{\"text\":\"Use read_pdf with path verification.pdf and return the verification code.\"}]},{\"role\":\"model\",\"parts\":[{\"functionCall\":{\"id\":\"call_475949\",\"name\":\"read_pdf\",\"args\":{\"path\":\"verification.pdf\"}},\"thoughtSignature\":\"Et4CCtsCAWkUfRPfQWeGIEQ/AhexY97IZoK8aNLr2EbW3nufnAXpa1y74z7qH1Tdk20j5EC57BSBbdy5u6xFHNomzZhGFVmdVlhgZFXGSO8F8K4t8rqQWUJZSDH4dFaC95KpUTfp5CAMepbOuc/dGLgXfVsSV0e/HvUcdWKoEz8Jlsgk59nexqSsdl/kGzuuIeW6zS5r8JHus+PfRzvSgua4B9OpDU9WWPCJZu93NLbXJELbZ330h7CP+uxXoo1Puu0KSrvLman8Geoc0nagMx895L0gO3CsbB+PpijQ6Pt6YAaiv1V2MeOCUKCYUpk+77MjC6RnsTFTRaJYJ5PPkniuRKedp/DF1aMj7nGxQ6BpHOMq9mjw2zlH3I2kJi1wqm+amVz30vTHa31xTH88w+IUc1yNdLAzdVJV+/+0mqw8bLweSjSHFxZN0NIv6aczAIS5stoGobNDO4bRGDETH3Q=\"}]},{\"role\":\"user\",\"parts\":[{\"functionResponse\":{\"id\":\"call_475949\",\"name\":\"read_pdf\",\"response\":{\"name\":\"read_pdf\",\"content\":\"PDF read successfully\"},\"parts\":[{\"inlineData\":{\"mimeType\":\"application/pdf\",\"data\":\"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9LaWRzIFszIDAgUl0gL0NvdW50IDEgPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MTIgNzkyXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSA1IDAgUiA+PiA+PiAvQ29udGVudHMgNCAwIFIgPj4KZW5kb2JqCjQgMCBvYmoKPDwgL0xlbmd0aCA3NSA+PgpzdHJlYW0KQlQKL0YxIDE4IFRmCjcyIDcyMCBUZAooUERGIGNhc3NldHRlIHZlcmlmaWNhdGlvbiBjb2RlOiBPUkNISUQtNzM5MSkgVGoKRVQKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjw8IC9UeXBlIC9Gb250IC9TdWJ0eXBlIC9UeXBlMSAvQmFzZUZvbnQgL0hlbHZldGljYSA+PgplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMjQxIDAwMDAwIG4gCjAwMDAwMDAzNjUgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0MzUKJSVFT0YK\"}}]}}]}],\"systemInstruction\":{\"parts\":[{\"text\":\"Call read_pdf exactly once with path verification.pdf, then reply only with the verification code from its PDF.\"}]},\"tools\":[{\"functionDeclarations\":[{\"name\":\"read_pdf\",\"description\":\"Read the attached PDF.\",\"parametersJsonSchema\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"],\"additionalProperties\":false}}]}],\"generationConfig\":{\"maxOutputTokens\":256,\"temperature\":0}}"
      },
      "response": {
        "status": 200,
        "headers": {
          "content-type": "text/event-stream"
        },
-        "body": "data: {\"candidates\": [{\"content\": {\"parts\": [{\"text\": \"ORCHID-7391\"}],\"role\": \"model\"},\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 123,\"candidatesTokenCount\": 8,\"totalTokenCount\": 184,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 123}],\"thoughtsTokenCount\": 53,\"serviceTier\": \"standard\"},\"modelVersion\": \"gemini-3.5-flash\",\"responseId\": \"RgphaoL6CMjQz7IPjOnEmQI\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"parts\": [{\"text\": \"\",\"thoughtSignature\": \"EqECCp4CARFNMg9obBl8O6iU9lawUIWiE+1vztZm9NtaT9FuyJz343hd9ruz+xPco4Q1DY1GF81ZiSI2ElBkt8Wfwsqtix9LNGSMvbZhhk/ZnB54t05M/Dft1kujcMvEdZUWUI/jWaJ349tO1bKVH9MacG5+gl0n4y8DwyQZSV3xIcet547drSkcA/TM03RB+yj1/dcLHsvUjmv9EnO897vZgO2Dk4tbZ2NyCtOeQ3JKVhUTLg2pjkGk+POCNiOdESWiUzxdQKw9LiV6nnzi071tXNiMeVimq6d7xAzRVNapI2uXynvn9Uk3eyn85purOFa8cKriK9oD6vcyGMqgd9+gu2m3to0IHqd7o+2YSr1m5qV1xT1R2/WRQEtb1b1AuOAU6w==\"}],\"role\": \"model\"},\"finishReason\": \"STOP\",\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 1277,\"candidatesTokenCount\": 8,\"totalTokenCount\": 1338,\"promptTokensDetails\": [{\"modality\": \"IMAGE\",\"tokenCount\": 1102},{\"modality\": \"TEXT\",\"tokenCount\": 175}],\"thoughtsTokenCount\": 53,\"serviceTier\": \"standard\"},\"modelVersion\": \"gemini-3.5-flash\",\"responseId\": \"RgphaoL6CMjQz7IPjOnEmQI\"}\r\n\r\n"
+        "body": "data: {\"candidates\": [{\"content\": {\"parts\": [{\"text\": \"ORCHID-7391\"}],\"role\": \"model\"},\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 123,\"candidatesTokenCount\": 8,\"totalTokenCount\": 184,\"promptTokensDetails\": [{\"modality\": \"TEXT\",\"tokenCount\": 123}],\"thoughtsTokenCount\": 53,\"serviceTier\": \"standard\"},\"modelVersion\": \"gemini-3.5-flash\",\"responseId\": \"jXe0ar7CNdjBqtsPqMm2oAs\"}\r\n\r\ndata: {\"candidates\": [{\"content\": {\"parts\": [{\"text\": \"\",\"thoughtSignature\": \"EtcCCtQCAWkUfRM3dQjvavztF1qActLo1mpXoGlWdQ+qUpKf1DdrmgWIT1nm70cm+yGf4pj6UU9fhKU+/y+ScUv1IJrb3c3yU5X2/CGzcN/DeRhxuvuXRaGxtWi4GIu2nFr3oJrAOnJnh/kosgiqixwQ3EK6/0jdE2HOqxu7jImvozaVcR9OiVGgAHRwmDYtB6K+6/jMVjORBKB4nZp8MTb3IWaiN6soO+FiWRgl3etnnJhkJb6eBHhHmLW8qxyOmVwRII3Gtm5jJbxGND/aZSpxlBvfBpGfbJQJIfNQDs+sXeQpuZh8SZUVRgVAZyOrqbVS1vRq8kODaBvDHKuTr0Qo9RpGGGo0npaYooP663omHDhm7Uu5plFwAVYR5G4z11my6efbHE1WvbcCgg6deqMFf6BX0SzzgPovB3p+giuHVwjD7gyYS3sdw/txxYPkY3+H/gWchf0FGw==\"}],\"role\": \"model\"},\"finishReason\": \"STOP\",\"index\": 0}],\"usageMetadata\": {\"promptTokenCount\": 696,\"candidatesTokenCount\": 8,\"totalTokenCount\": 757,\"promptTokensDetails\": [{\"modality\": \"IMAGE\",\"tokenCount\": 520},{\"modality\": \"TEXT\",\"tokenCount\": 176}],\"thoughtsTokenCount\": 53,\"serviceTier\": \"standard\"},\"modelVersion\": \"gemini-3.5-flash\",\"responseId\": \"jXe0ar7CNdjBqtsPqMm2oAs\"}\r\n\r\n"
      }
    }
  ]
@@ -149,7 +149,7 @@ describe("llm constructors", () => {
    const updated = LanguageModel.update(base, {
      route: responsesRoute,
      defaults: { generation: { maxTokens: 20 } },
-      compatibility: { toolSchema: "gemini", requireFinishReason: false },
+      compatibility: { sanitizer: "gemini", requireFinishReason: false },
    })
    const updatedInput = LanguageModel.input(updated)

@@ -157,7 +157,7 @@ describe("llm constructors", () => {
    expect(String(updated.id)).toBe("fake-model")
    expect(updated.route).toBe(responsesRoute)
    expect(updated.defaults?.generation).toEqual({ maxTokens: 20 })
-    expect(updated.compatibility).toEqual({ toolSchema: "gemini", requireFinishReason: false })
+    expect(updated.compatibility).toEqual({ sanitizer: "gemini", requireFinishReason: false })
    expect(updatedInput.defaults).toBe(updated.defaults)
    expect(updatedInput.compatibility).toBe(updated.compatibility)
    expect(String(updatedInput.provider)).toBe("fake")
@@ -172,14 +172,14 @@ describe("llm constructors", () => {
        providerOptions: { parallelToolCalls: false },
        http: { body: { extra_body: true } },
      },
-      compatibility: { toolSchema: "moonshot" },
+      compatibility: { sanitizer: "moonshot" },
    })
    const request = LLM.request({ model, prompt: "Say hello." })

    expect(request.model.defaults?.generation).toEqual({ maxTokens: 1_024, stop: ["END"] })
    expect(request.model.defaults?.providerOptions).toEqual({ parallelToolCalls: false })
    expect(request.model.defaults?.http).toEqual({ body: { extra_body: true } })
-    expect(request.model.compatibility).toEqual({ toolSchema: "moonshot" })
+    expect(request.model.compatibility).toEqual({ sanitizer: "moonshot" })
    expect(request.generation).toBeUndefined()
    expect(request.providerOptions).toBeUndefined()
    expect(request.http).toBeUndefined()
@@ -1,4 +1,7 @@
 import { describe, expect, test } from "bun:test"
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
 import { Effect, Layer } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
 import { AIError, LLMEvent, Media, SpeechEvent, TranscriptionEvent } from "../src/index.js"
@@ -182,6 +185,36 @@ describe("AI promise client", () => {
    await ai.dispose()
  })

+  test("observes a started generation's events and fetches its result", async () => {
+    const ai = AI.make({ layer: executor([]) })
+    const model = Runway.configure({ apiKey: "test", baseURL: "https://runway.test/v1" }).video("gen4.5")
+    const generation = await ai.video.start({ model, prompt: "A kite" })
+
+    const events: Array<string> = []
+    for await (const event of generation.events({ poll: { interval: 10 } })) events.push(event.type)
+    expect(events).toEqual(["generation-progress", "generation-finished"])
+    expect(generation.status).toBe("queued")
+    expect((await generation.result()).video.source).toMatchObject({ url: "https://runway.test/out.mp4" })
+    await ai.dispose()
+  })
+
+  test("reads, writes, and decodes assets without leaving promises", async () => {
+    const ai = AI.make({ layer: executor([]) })
+    const dir = await mkdtemp(join(tmpdir(), "ai-promise-"))
+    try {
+      const png = Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3])
+      await Bun.write(join(dir, "source.bin"), png)
+
+      const asset = await ai.file(join(dir, "source.bin"))
+      expect(asset.mediaType).toBe("image/png")
+      await ai.write(asset, join(dir, "copy.png"))
+      expect(await ai.bytes(await ai.file(join(dir, "copy.png")))).toEqual(png)
+    } finally {
+      await rm(dir, { recursive: true })
+      await ai.dispose()
+    }
+  })
+
  test("generates, streams, and starts transcriptions over the same runtime", async () => {
    const ai = AI.make({ layer: executor([]) })
    const audio = Media.url("https://audio.test/hello.mp3")
@@ -233,6 +266,12 @@ describe("AI promise client", () => {
    expect(failure).toBeInstanceOf(AIError)
    expect(failure instanceof AIError && failure.reason.http?.status).toBe(404)

+    const invalid = await ai.llm
+      // @ts-expect-error Invalid input must reject with AIError, not throw synchronously.
+      .generate({ model: openai.responses("gpt-5"), messages: [{ role: "bogus" }] })
+      .catch((error: unknown) => error)
+    expect(invalid instanceof AIError && invalid.reason._tag).toBe("InvalidRequest")
+
    const controller = new AbortController()
    controller.abort()
    const aborted = await ai.llm
@@ -381,7 +381,7 @@ describe("Gemini route", () => {
              {
                name: "lookup",
                description: "Lookup data",
-                parameters: { type: "object", properties: { query: { type: "string" } } },
+                parametersJsonSchema: { type: "object", properties: { query: { type: "string" } } },
              },
            ],
          },
@@ -676,7 +676,7 @@ describe("Gemini route", () => {
    }),
  )

-  it.effect("sanitizes integer enums, dangling required, untyped arrays, and scalar object keys", () =>
+  it.effect("normalizes the JSON Schema shapes Gemini rejects", () =>
    Effect.gen(function* () {
      const prepared = yield* compileRequest(
        LLM.request({
@@ -689,11 +689,32 @@ describe("Gemini route", () => {
              description: "Lookup data",
              inputSchema: {
                type: "object",
-                required: ["status", "missing"],
+                required: ["ttl", "items", "parent", "missing"],
                properties: {
-                  status: { type: "integer", enum: [1, 2] },
-                  tags: { type: "array" },
-                  name: { type: "string", properties: { ignored: { type: "string" } }, required: ["ignored"] },
+                  ttl: { type: "number", minimum: 0, exclusiveMinimum: true, maximum: 60, exclusiveMaximum: false },
+                  pair: { type: "array", items: [{ type: "string" }, { type: "integer" }], additionalItems: false },
+                  items: { type: "array", items: { type: "string" } },
+                  required: { type: "boolean" },
+                  params: { $ref: "#/$defs/Json" },
+                  tree: { $ref: "#/$defs/Node" },
+                  chain: { $ref: "#/$defs/Link" },
+                  batch: { $ref: "#/$defs/Batch" },
+                  self: { $ref: "#" },
+                  parent: { $ref: "#" },
+                  cart: { type: "object", default: { items: ["a"] } },
+                },
+                dependentRequired: { items: ["ttl"] },
+                $defs: {
+                  Json: {
+                    anyOf: [
+                      { type: "string" },
+                      { type: "array", items: { $ref: "#/$defs/Json" } },
+                      { type: "object", additionalProperties: { $ref: "#/$defs/Json" } },
+                    ],
+                  },
+                  Node: { type: "object", properties: { child: { $ref: "#/$defs/Node" } } },
+                  Link: { type: "object", required: ["next"], properties: { next: { $ref: "#/$defs/Link" } } },
+                  Batch: { type: "array", minItems: 1, items: { $ref: "#/$defs/Batch" } },
                },
              },
            },
@@ -701,24 +722,35 @@ describe("Gemini route", () => {
        }),
      )

-      expect(prepared.body).toMatchObject({
-        tools: [
-          {
-            functionDeclarations: [
-              {
-                parameters: {
-                  type: "object",
-                  required: ["status"],
-                  properties: {
-                    status: { type: "string", enum: ["1", "2"] },
-                    tags: { type: "array", items: { type: "string" } },
-                    name: { type: "string" },
-                  },
-                },
-              },
+      expect(prepared.body.tools?.[0]?.functionDeclarations[0]?.parametersJsonSchema).toEqual({
+        type: "object",
+        required: ["ttl", "items", "parent"],
+        properties: {
+          ttl: { type: "number", exclusiveMinimum: 0, maximum: 60 },
+          pair: { type: "array", prefixItems: [{ type: "string" }, { type: "integer" }], items: false },
+          items: { type: "array", items: { type: "string" } },
+          required: { type: "boolean" },
+          params: { $ref: "#/$defs/Json" },
+          tree: { $ref: "#/$defs/Node" },
+          chain: { $ref: "#/$defs/Link" },
+          batch: { $ref: "#/$defs/Batch" },
+          self: { $ref: "#" },
+          parent: {},
+          cart: { type: "object", default: { items: ["a"] } },
+        },
+        dependentRequired: { items: ["ttl"] },
+        $defs: {
+          Json: {
+            anyOf: [
+              { type: "string" },
+              { type: "array", items: { $ref: "#/$defs/Json" } },
+              { type: "object", additionalProperties: {} },
            ],
          },
-        ],
+          Node: { type: "object", properties: { child: { $ref: "#/$defs/Node" } } },
+          Link: { type: "object", required: ["next"], properties: { next: {} } },
+          Batch: { type: "array", minItems: 1, items: {} },
+        },
      })
    }),
  )
@@ -751,7 +783,7 @@ describe("Gemini route", () => {
            {
              name: "configure",
              description: "Configure the operation",
-              parameters: {
+              parametersJsonSchema: {
                type: "object",
                required: ["options"],
                properties: {
@@ -765,55 +797,38 @@ describe("Gemini route", () => {
    }),
  )

-  it.effect("projects Gemini type arrays without narrowing their allowed values", () =>
+  it.effect("sends standard JSON Schema tool parameters unchanged", () =>
    Effect.gen(function* () {
+      const inputSchema = {
+        type: "object",
+        required: ["level"],
+        properties: {
+          level: { type: "integer", enum: [1, 2, 3] },
+          status: { type: ["number", "string"], description: "Status filter" },
+          maybe: { anyOf: [{ type: "string" }, { type: "null" }] },
+          kind: { const: "fixed" },
+          mode: { enum: ["fast", "safe"] },
+          tags: { type: "array" },
+          env: { type: "object", additionalProperties: { type: "string" } },
+          action: {
+            oneOf: [
+              { type: "object", properties: { type: { const: "move" }, to: { type: "string" } } },
+              { type: "object", properties: { type: { const: "delete" } } },
+            ],
+          },
+          item: { $ref: "#/$defs/Item" },
+        },
+        $defs: { Item: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+      }
      const prepared = yield* compileRequest(
        LLM.request({
          model,
          prompt: "Use the tool.",
-          tools: [
-            {
-              name: "filter",
-              description: "Filter values",
-              inputSchema: {
-                type: "object",
-                properties: {
-                  status: { type: ["number", "string"], description: "Status filter" },
-                  maybe: { type: ["string", "null"] },
-                  nothing: { type: ["null"] },
-                  explicit: { anyOf: [{ type: "string" }, { type: "null" }] },
-                  choice: { anyOf: [{ type: "string" }, { type: "number" }, { type: "null" }] },
-                },
-              },
-            },
-          ],
+          tools: [{ name: "filter", description: "Filter values", inputSchema }],
        }),
      )

-      expect(prepared.body.tools?.[0]?.functionDeclarations[0]?.parameters).toEqual({
-        type: "object",
-        properties: {
-          status: {
-            description: "Status filter",
-            anyOf: [{ type: "number" }, { type: "string" }],
-          },
-          maybe: {
-            nullable: true,
-            anyOf: [{ type: "string" }],
-          },
-          nothing: {
-            type: "null",
-          },
-          explicit: {
-            type: "string",
-            nullable: true,
-          },
-          choice: {
-            anyOf: [{ type: "string" }, { type: "number" }],
-            nullable: true,
-          },
-        },
-      })
+      expect(prepared.body.tools?.[0]?.functionDeclarations[0]?.parametersJsonSchema).toEqual(inputSchema)
    }),
  )

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { HttpClientRequest } from "effect/unstable/http"
-import { LLM, Message, ToolCallPart } from "../../src/index.js"
+import { LanguageModel, LLM, Message, ToolCallPart } from "../../src/index.js"
 import { GoogleVertex, GoogleVertexChat, GoogleVertexMessages, GoogleVertexResponses } from "../../src/providers.js"
 import { LLMClient } from "../../src/route.js"
 import { compileRequest } from "../../src/route/client.js"
@@ -414,6 +414,37 @@ describe("Google Vertex providers", () => {
    }),
  )

+  it.effect("applies Gemini schema rules to the Gemini API and Gemini models unless opted out", () =>
+    Effect.gen(function* () {
+      const vertex = { accessToken: "vertex-token", location: "us-central1", project: "vertex-project" }
+      const inputSchema = { type: "object", required: ["query", "missing"], properties: { query: { type: "string" } } }
+      const request = (model: Parameters<typeof LLM.request>[0]["model"]) =>
+        compileRequest(
+          LLM.request({
+            model,
+            prompt: "Use the tool.",
+            tools: [{ name: "lookup", description: "Lookup.", inputSchema }],
+          }),
+        )
+
+      const normalized = { ...inputSchema, required: ["query"] }
+      const tunedModel = GoogleVertex.configure(vertex).model("endpoints/1234567890")
+      const tuned = yield* request(tunedModel)
+      expect(tuned.body.tools?.[0]?.functionDeclarations[0]?.parametersJsonSchema).toEqual(normalized)
+      const optedOut = yield* request(LanguageModel.update(tunedModel, { compatibility: { sanitizer: "none" } }))
+      expect(optedOut.body.tools?.[0]?.functionDeclarations[0]?.parametersJsonSchema).toEqual(inputSchema)
+      const geminiChat = yield* request(GoogleVertexChat.configure(vertex).model("google/gemini-3.8-flash"))
+      expect(geminiChat.body.tools?.[0]?.function.parameters).toEqual(normalized)
+
+      const chat = yield* request(GoogleVertexChat.configure(vertex).model("deepseek-ai/deepseek-v3.2-maas"))
+      expect(chat.body.tools?.[0]?.function.parameters).toEqual(inputSchema)
+      const responses = yield* request(GoogleVertexResponses.configure(vertex).model("xai/grok-4.20-reasoning"))
+      expect(responses.body.tools?.[0]).toMatchObject({ parameters: inputSchema })
+      const messages = yield* request(GoogleVertexMessages.configure(vertex).model("claude-sonnet-4-6"))
+      expect(messages.body.tools?.[0]).toMatchObject({ input_schema: inputSchema })
+    }),
+  )
+
  it.effect("routes tuned Gemini models through their deployed endpoint", () =>
    Effect.gen(function* () {
      const response = yield* LLMClient.generate(
@@ -60,33 +60,51 @@ describe("tool schema projections", () => {
    })
  })

-  test("gemini handles numeric enums, dangling required fields, untyped arrays, and scalar object keys", () => {
-    expect(
-      ToolSchemaProjection.gemini({
+  it.effect("selects tool schema handling from the model name unless compatibility is explicit", () =>
+    Effect.gen(function* () {
+      const route = OpenAIChat.route.with({
+        endpoint: { baseURL: "https://api.openai.test/v1/" },
+        auth: Auth.bearer("test"),
+      })
+      const original = {
        type: "object",
-        required: ["status", "missing"],
-        properties: {
-          status: { type: "integer", enum: [1, 2] },
-          tags: { type: "array" },
-          name: { type: "string", properties: { ignored: { type: "string" } }, required: ["ignored"] },
-        },
-      }),
-    ).toEqual({
-      type: "object",
-      required: ["status"],
-      properties: {
-        status: { type: "string", enum: ["1", "2"] },
-        tags: { type: "array", items: { type: "string" } },
-        name: { type: "string" },
-      },
-    })
-  })
+        required: ["mode", "missing"],
+        properties: { mode: { enum: ["fast", "safe"] } },
+      }
+      const parameters = (model: ReturnType<typeof route.model>) =>
+        compileRequest(
+          LLM.request({
+            model,
+            prompt: "Use the tool.",
+            tools: [{ name: "lookup", description: "Lookup data.", inputSchema: original }],
+          }),
+        ).pipe(Effect.map((prepared) => prepared.body.tools?.[0]?.function.parameters))
+      const gemini = { ...original, required: ["mode"] }
+      const moonshot = { ...original, properties: { mode: { type: "string", enum: ["fast", "safe"] } } }
+
+      expect(yield* parameters(route.model({ id: "google/Gemini-3.8-Flash" }))).toEqual(gemini)
+      expect(
+        yield* parameters(route.model({ id: "my-tuned-endpoint", compatibility: { sanitizer: "gemini" } })),
+      ).toEqual(gemini)
+      expect(
+        yield* parameters(route.model({ id: "google/gemini-3.8-flash", compatibility: { sanitizer: "moonshot" } })),
+      ).toEqual(moonshot)
+      expect(yield* parameters(route.model({ id: "moonshotai/Kimi-K3" }))).toEqual(moonshot)
+      expect(
+        yield* parameters(route.model({ id: "google/gemini-3.8-flash", compatibility: { sanitizer: "none" } })),
+      ).toEqual(original)
+      expect(
+        yield* parameters(route.model({ id: "moonshotai/Kimi-K3", compatibility: { sanitizer: "none" } })),
+      ).toEqual(original)
+      expect(yield* parameters(route.model({ id: "gpt-6-luna" }))).toEqual(original)
+    }),
+  )

  it.effect("applies model compatibility without changing schema semantics", () =>
    Effect.gen(function* () {
      const model = OpenAIChat.route
        .with({ endpoint: { baseURL: "https://api.openai.test/v1/" }, auth: Auth.bearer("test") })
-        .model({ id: "kimi-k2", compatibility: { toolSchema: "moonshot" } })
+        .model({ id: "kimi-k2", compatibility: { sanitizer: "moonshot" } })
      const prepared = yield* compileRequest(
        LLM.request({
          model,
@@ -533,6 +533,7 @@ describe("Video / fal", () => {
        "InvalidRequest",
      ])
      expect(errors[1].message).toContain("end_image_url")
+      expect(errors[4].message).toContain("; got fal:handle")
    }).pipe(Effect.provide(layer(() => Effect.die("unsupported input reached the network")))),
  )
 })
@@ -33,6 +33,7 @@
 - When migrating existing copy to i18n, preserve the English text byte-for-byte unless the task explicitly requests a copy change.
 - NEVER change existing English text or English keys to facilitate translation. English is intentional, designer-written source copy; adapt locale-specific translations and i18n mechanics around it.
 - Keep locale complexity behind the shared typed i18n APIs. Feature and component code should use `language.t(...)` for ordinary copy and `language.plural(baseKey, count, params)` for count-sensitive copy. It must not inspect the locale, call `Intl.PluralRules`, construct or select plural-category keys such as `.one` or `.other`, or branch on locale-specific grammar.
+- Do not compose translated count phrases or sentence fragments in feature components. Add a focused language-context operation that owns plural selection and composition when one UI concept needs coordinated keys.
 - Prefer complete translated phrases. Do not concatenate grammatical fragments or make call sites assemble sentences. Keep placeholders to irreducible dynamic values such as names, paths, and counts.
 - If a translation cannot be expressed by the current API, deepen the shared language/UI i18n module so one typed call owns locale selection, plural resolution, fallback, and interpolation. Do not leak that machinery into product code.
 - Do not translate from model knowledge alone. Verify terminology and grammar with Unicode CLDR locale/plural data, Microsoft Localization Style Guides and terminology, Apple localization/style guidance and localized platform UI, Mozilla localization style guides, Mozilla Pontoon, and the Firefox localization corpus at `github.com/mozilla-l10n/firefox-l10n`.
@@ -94,9 +94,10 @@ In Vite development mode, `origin` uses `VITE_OPENCODE_SERVER_HOST` / `VITE_OPEN
 (default: `http://localhost:4096`) instead of the frontend origin. Both modes restore user-added servers
 from storage. Desktop provides the local server it discovers or starts through native initialization.

-With no configured servers, the app shows a full-screen connection form. Enter a server address and password,
-or choose **Scan QR code** to open the camera and read the pairing code from `opencode pair`.
-Scanning fills the form and immediately attempts to connect. Failed connections leave the details available
+With no configured servers, or when the only server rejects the saved credentials, the app shows a full-screen
+connection form. Enter a server address and password, paste a link from `opencode pair`, or choose
+**Scan QR code** to read its QR code. Pairing links are single-use; the app exchanges them for a session token
+and immediately attempts to connect. Failed connections leave the details available
 to edit and retry with **Connect**. Credentials are checked before saving the server. Camera access requires
 HTTPS (or localhost) and browser permission. Saved offline servers continue to use the normal app UI.

@@ -106,7 +107,7 @@ When the service is exposed through an HTTPS reverse proxy, advertise its extern
 opencode pair --url https://opencode.example.com
 ```

-This replaces the addresses printed and encoded in the QR code while retaining the local service password.
+This replaces the addresses in the printed links and QR code.
 The proxy URL must reach the OpenCode API, not just the frontend. For separate frontend and API processes,
 route `/api` to the service while preserving the `/api` prefix. No machine-specific app or CLI build is required.

@@ -122,6 +122,40 @@ story("does not mask or pad controls when they fit", async ({ mount }) => {
  await expect(controls).toHaveCSS("padding-inline-end", "0px")
 })

+story("grows suggestions while preserving visible timeline context", async ({ mount }) => {
+  const component = await mount("opencode-composer-flow--constrained-command-suggestions")
+  const boundary = component.locator('[data-slot="composer-suggestion-boundary-story"]')
+  const suggestions = component.locator('[data-component="composer-suggestions"]')
+
+  await expect(suggestions).toHaveCSS("max-height", "166px")
+  await expect(suggestions).toHaveCSS("scroll-padding-bottom", "18px")
+  await expect.poll(() => suggestions.evaluate((element) => element.scrollHeight > element.clientHeight)).toBe(true)
+  await expect
+    .poll(async () => {
+      const menu = await suggestions.boundingBox()
+      const items = await suggestions.locator("[data-suggestion-id]").evaluateAll((elements) =>
+        elements.map((element) => {
+          const rect = element.getBoundingClientRect()
+          return { top: rect.top, bottom: rect.bottom }
+        }),
+      )
+      if (!menu) return false
+      const bottom = menu.y + menu.height
+      return items.some((item) => item.top < bottom && item.bottom > bottom)
+    })
+    .toBe(true)
+
+  await boundary.evaluate((element) => {
+    element.style.height = "400px"
+  })
+  await expect(suggestions).toHaveCSS("max-height", "306px")
+})
+
+story("ignores a detached suggestion boundary", async ({ mount }) => {
+  const component = await mount("opencode-composer-flow--detached-command-suggestion-boundary")
+  await expect(component.locator('[data-component="composer-suggestions"]')).toHaveCSS("max-height", "306px")
+})
+
 // ThemeProvider writes resolved token values into a <style> block, so toggling data-color-scheme by hand
 // leaves every --v2-* variable at its previous value. Switch themes through the Storybook global instead.
 for (const [theme, background] of [
@@ -180,6 +214,23 @@ for (const draft of ["empty-draft", "multiline-draft", "mixed-attachments"]) {
  })
 }

+story.describe("touch attachments", () => {
+  story.use({ hasTouch: true, isMobile: true, viewport: { width: 390, height: 844 } })
+
+  story("keeps attachment remove buttons visible without hover", async ({ mount, page }) => {
+    const component = await mount("opencode-composer-flow--mixed-attachments")
+    expect(await page.evaluate(() => matchMedia("(hover: none)").matches)).toBe(true)
+
+    const remove = component.getByRole("button", { name: "Remove attachment", exact: true })
+    await expect(remove).not.toHaveCount(0)
+    for (const button of await remove.all()) await expect(button).toHaveCSS("opacity", "1")
+
+    const count = await remove.count()
+    await remove.first().tap()
+    await expect(remove).toHaveCount(count - 1)
+  })
+})
+
 story("renders a draft once and supports editing, caret restoration, and failure recovery", async ({ mount, page }) => {
  await page.addInitScript(() => {
    const replace = Element.prototype.replaceChildren
@@ -0,0 +1,19 @@
+import { expect, story } from "../../storybook/playwright/story"
+
+story("shows question navigation shortcuts", async ({ mount, page }) => {
+  const component = await mount("app-current-session-surface--question-request")
+  const shortcut = await page.evaluate(() => (/Mac|iPhone|iPad|iPod/.test(navigator.platform) ? "⌘⏎" : "Ctrl+⏎"))
+  const next = component.getByRole("button", { name: "Next", exact: true })
+  await expect(next.locator('[data-slot="question-submit-shortcut"]')).toHaveText(shortcut)
+  await next.click()
+  await expect(component.getByRole("button", { name: "Submit", exact: true })).toContainText(shortcut)
+  const back = component.getByRole("button", { name: "Back", exact: true })
+  const backShortcut = await page.evaluate(() => (/Mac|iPhone|iPad|iPod/.test(navigator.platform) ? "⌘[" : "Alt+←"))
+  await expect(back).toHaveText("Back")
+  await back.hover()
+  await expect(page.getByRole("tooltip")).toContainText(backShortcut)
+  await page.keyboard.press(
+    await page.evaluate(() => (/Mac|iPhone|iPad|iPod/.test(navigator.platform) ? "Meta+[" : "Alt+ArrowLeft")),
+  )
+  await expect(next).toBeVisible()
+})
@@ -158,6 +158,10 @@ for (const direction of ["ltr", "rtl"]) {
    story(`fits narrow and wide layouts in ${direction}, ${theme}`, async ({ mount, page }, testInfo) => {
      await page.setViewportSize({ width: 900, height: 900 })
      const component = await mount("settings-timeline-detail--interactive", { globals: { direction, theme } })
+      await expect(component.locator('[data-slot="timeline-detail-scale"]')).toHaveCSS("margin-top", "16px")
+      const advanced = component.locator('[data-slot="timeline-detail-advanced"]')
+      await expect(advanced).toHaveCSS("margin-top", "0px")
+      await expect(advanced).toHaveCSS("padding-top", "8px")
      await expect(component.locator('[data-slot="timeline-detail-summary"]')).toHaveCSS(
        "color",
        await component
@@ -177,28 +181,46 @@ for (const direction of ["ltr", "rtl"]) {
        ),
      )
      if (theme === "light") {
-        await expect(track.locator("span").first()).toHaveCSS("background-image", "none")
+        await expect(track.locator("span").last()).toHaveCSS("background-image", "none")
        await expect(track).toHaveCSS(
          "--timeline-detail-marker-background",
          await track.evaluate((element) => getComputedStyle(element).getPropertyValue("--v2-grey-500").trim()),
        )
      }
      if (theme === "dark") {
-        await expect(track.locator("span").first()).not.toHaveCSS("background-image", "none")
+        await expect(track.locator("span").last()).not.toHaveCSS("background-image", "none")
      }
      await page.screenshot({ path: testInfo.outputPath(`timeline-${theme}-${direction}.png`) })
      const list = component.locator('[data-slot="timeline-detail-list"]')
+      const columns = component.locator('[data-slot="timeline-detail-columns"]')
      await expect(component.locator('[data-slot="timeline-detail-categories"]')).toHaveCSS("margin-top", "0px")
+      const advancedTrigger = component.getByRole("button", { name: "Advanced", exact: true })
+      expect(
+        await advancedTrigger.evaluate((element) => {
+          const trigger = element.getBoundingClientRect()
+          const heading = document
+            .querySelector('[data-slot="timeline-detail-columns"] > :nth-child(2)')!
+            .getBoundingClientRect()
+          return Math.abs(trigger.y + trigger.height / 2 - (heading.y + heading.height / 2))
+        }),
+      ).toBeLessThan(1)
+      expect(
+        await list.evaluate((element) => {
+          const list = element.getBoundingClientRect()
+          const trigger = document
+            .querySelector('[data-slot="timeline-detail-advanced"] > [data-slot="collapsible-trigger"]')!
+            .getBoundingClientRect()
+          return list.y - trigger.bottom
+        }),
+      ).toBe(8)
      for (const [column, field] of [
        [2, "placement"],
        [3, "details"],
      ] as const) {
-        const heading = await component
-          .locator(`[data-slot="timeline-detail-columns"] > :nth-child(${column})`)
-          .evaluate((element) => {
-            const rect = element.getBoundingClientRect()
-            return rect.x + rect.width / 2
-          })
+        const heading = await columns.locator(`> :nth-child(${column})`).evaluate((element) => {
+          const rect = element.getBoundingClientRect()
+          return rect.x + rect.width / 2
+        })
        const toggle = await component
          .locator(`[data-category="shell"][data-field="${field}"] [data-slot="switch-control"]`)
          .evaluate((element) => {
@@ -207,7 +229,7 @@ for (const direction of ["ltr", "rtl"]) {
          })
        expect(Math.abs(heading - toggle)).toBeLessThan(1)
      }
-      await expect(component.locator('[data-slot="timeline-detail-activity"]').first()).toHaveCSS("gap", "12px")
+      await expect(component.locator('[data-slot="timeline-detail-activity"]').first()).toHaveCSS("gap", "8px")
      for (const width of [900, 320]) {
        await page.setViewportSize({ width, height: 900 })
        await expect(component.getByRole("switch", { name: "Shell grouped", exact: true })).toBeVisible()
@@ -227,6 +249,7 @@ for (const direction of ["ltr", "rtl"]) {

        const slider = component.getByRole("slider", { name: "Timeline detail" })
        const track = component.locator('[data-slot="timeline-detail-track"]')
+        await expect(slider).not.toHaveCSS("cursor", "pointer")
        expect(await track.evaluate((element) => element.getBoundingClientRect().width)).toBe(
          await component
            .locator('[data-slot="timeline-detail-scale"]')
@@ -237,6 +260,11 @@ for (const direction of ["ltr", "rtl"]) {
        for (const position of [0, 1, 2, 3, 4]) {
          if (position > 0) await slider.press("ArrowUp")
          await expect(track).toHaveCSS("--timeline-detail-progress", `${position * 25}%`)
+          await expect(track.locator("span[data-selected]")).toHaveCount(position + 1)
+          await expect(track.locator("span").nth(position)).toHaveCSS(
+            "background-color",
+            await track.evaluate((element) => getComputedStyle(element, "::before").backgroundColor),
+          )
          const fill = await track.evaluate((element) => {
            const style = getComputedStyle(element, "::before")
            return {
@@ -0,0 +1,87 @@
+import type { SessionMessageInfo } from "@opencode/client/promise"
+import { base64Encode } from "@opencode/util/encode"
+import { expect, test } from "@playwright/test"
+import { mockOpenCodeServer } from "../utils/mock-server"
+import { expectSessionTitle } from "../utils/waits"
+
+const directory = "C:/OpenCode/ArtifactReopen"
+const projectID = "proj_artifact_reopen"
+const sessionID = "ses_artifact_reopen"
+const title = "Artifact reopen"
+const server = `http://${process.env.PLAYWRIGHT_SERVER_HOST ?? "127.0.0.1"}:${process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"}`
+const messages = [
+  { id: "msg_prompt", type: "user", text: "Write the shopping list", time: { created: 1 } },
+  {
+    id: "msg_reply",
+    type: "assistant",
+    agent: "build",
+    model: { id: "test", providerID: "opencode" },
+    content: [{ type: "text", text: "Updated [shopping.txt](shopping.txt)." }],
+    time: { created: 2, completed: 3 },
+  },
+] satisfies SessionMessageInfo[]
+
+test.use({ viewport: { width: 1440, height: 900 } })
+
+test("rereads a file each time an artifact link opens it", async ({ page }) => {
+  const file = { content: "first draft" }
+  await mockOpenCodeServer(page, {
+    directory,
+    project: {
+      id: projectID,
+      worktree: directory,
+      canonical: directory,
+      vcs: "git",
+      name: "artifact-reopen",
+      time: { created: 1, updated: 1 },
+      sandboxes: [],
+    },
+    provider: {
+      all: [
+        {
+          id: "opencode",
+          name: "OpenCode",
+          models: { test: { id: "test", name: "Test", variants: {}, limit: { context: 200_000 } } },
+        },
+      ],
+      connected: ["opencode"],
+      default: { providerID: "opencode", modelID: "test" },
+    },
+    sessions: [
+      {
+        id: sessionID,
+        slug: "artifact-reopen",
+        projectID,
+        directory,
+        title,
+        agent: "build",
+        model: { id: "test", providerID: "opencode" },
+        version: "dev",
+        time: { created: 1, updated: 3 },
+      },
+    ],
+    fileList: () => [],
+    fileContent: (path) => (path === "shopping.txt" ? file : ""),
+    pageMessages: () => ({ items: messages }),
+  })
+
+  await page.goto(`/server/${base64Encode(server)}/session/${sessionID}`)
+  await expectSessionTitle(page, title)
+
+  const link = page.getByRole("link", { name: "shopping.txt", exact: true })
+  const panel = page.locator("#review-panel")
+  const tab = panel.getByRole("tab", { name: "shopping.txt" })
+
+  await link.click()
+  await expect(tab).toHaveAttribute("aria-selected", "true")
+  await expect(panel.getByText("first draft", { exact: true })).toBeVisible()
+
+  file.content = "second draft"
+  await tab.locator("..").getByRole("button", { name: "Close tab" }).click()
+  await expect(tab).toHaveCount(0)
+
+  await link.click()
+  await expect(tab).toHaveAttribute("aria-selected", "true")
+  await expect(panel.getByText("second draft", { exact: true })).toBeVisible()
+  await expect(panel.getByText("first draft", { exact: true })).toHaveCount(0)
+})
@@ -1,337 +1,22 @@
-import { expect, test, type Page } from "@playwright/test"
-import { mockOpenCodeServer, currentSession } from "../utils/mock-server"
-import { openWithDirection } from "../utils/direction"
+import { expect, test } from "@playwright/test"
+import { mockOpenCodeServer } from "../utils/mock-server"
+import { expectAppVisible } from "../utils/waits"

-const directory = "/workspace/summary-project"
-const workspace = "/workspace/existing-worktree"
-const createdWorkspace = "/workspace/created-worktree"
 const draftID = "draft_summary"
-const secondDraftID = "draft_summary_other"
+const directory = "/workspace/summary-project"
 const server = `http://${process.env.PLAYWRIGHT_SERVER_HOST ?? "127.0.0.1"}:${process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"}`
-const draftPath = `/new-session?draftId=${draftID}`

-for (const rtl of [false, true]) {
-  test(`new session summary shows project extensions and follows workspace selection in ${rtl ? "rtl" : "ltr"}`, async ({
-    page,
-  }, testInfo) => {
-    const mock = await openDraft(page, "main", { direction: rtl ? "rtl" : "ltr" })
-    await expect(page.locator("html")).toHaveAttribute("dir", rtl ? "rtl" : "ltr")
-    await expect(page.locator("html")).toHaveAttribute("lang", "en")
-    const trigger = page.getByRole("button", { name: "Session details", exact: true })
-    await expect
-      .poll(async () => {
-        const button = await trigger.boundingBox()
-        const view = await page.locator('[data-component="new-session"]').boundingBox()
-        if (!button || !view) return false
-        const gap = rtl ? button.x - view.x : view.x + view.width - button.x - button.width
-        return Math.abs(gap - 12) <= 1 && Math.abs(button.y + button.height / 2 - view.y - 24) <= 1
-      })
-      .toBe(true)
-    await trigger.click()
-    const summary = page.getByRole("dialog", { name: "Session details", exact: true })
-    await expect(summary.getByRole("button", { name: "summary-project", exact: true })).toHaveAttribute(
-      "aria-expanded",
-      "true",
-    )
-    await expect(summary.getByRole("button", { name: "Extensions", exact: true })).toHaveAttribute(
-      "aria-expanded",
-      "true",
-    )
-    await expect
-      .poll(async () => {
-        const button = await trigger.boundingBox()
-        const project = await summary.locator('[data-section="project"]').boundingBox()
-        const server = await summary.locator('[data-section="server"]').boundingBox()
-        if (!button || !project || !server) return
-        return {
-          top: project.y - button.y - button.height,
-          cards: server.y - project.y - project.height,
-        }
-      })
-      .toEqual({ top: 12, cards: 8 })
-    await testInfo.attach(`new-session-summary-${rtl ? "rtl" : "ltr"}`, {
-      body: await page.screenshot(),
-      contentType: "image/png",
-    })
-    for (const [name, item] of [
-      ["MCP", "summary-mcp"],
-      ["Plugins", "project-plugin"],
-      ["Skills", "summary-skill"],
-      ["LSP", "typescript"],
-    ]) {
-      await summary.getByRole("button", { name, exact: true }).click()
-      await expect(page.getByRole("dialog", { name, exact: true }).getByText(item, { exact: true })).toBeVisible()
-    }
-    await page.keyboard.press("Escape")
-    await summary.getByRole("button", { name: "Local repository", exact: true }).click()
-    const worktreeMenu = page.getByRole("menu", { name: "Local repository", exact: true })
-    await expect
-      .poll(async () => {
-        const menu = await worktreeMenu.boundingBox()
-        const panel = await summary.locator('[data-component="session-summary-panel"]').boundingBox()
-        if (!menu || !panel) return false
-        return rtl ? menu.x >= panel.x + panel.width : menu.x + menu.width <= panel.x
-      })
-      .toBe(true)
-    await expect(page.getByRole("menuitem", { name: "existing-worktree", exact: true })).toBeHidden()
-    await worktreeMenu.getByRole("menuitem", { name: "Worktree", exact: true }).press(rtl ? "ArrowLeft" : "ArrowRight")
-    await expect(page.getByRole("menu", { name: "Worktree", exact: true })).toBeVisible()
-    await page.keyboard.press("Enter")
-    await expect(summary.getByRole("button", { name: "existing-worktree", exact: true })).toBeVisible()
-    await summary.getByRole("button", { name: "MCP", exact: true }).click()
-    const mcp = page.getByRole("dialog", { name: "MCP", exact: true })
-    const toggle = mcp.getByRole("switch", { name: "summary-mcp", exact: true })
-    await expect(toggle).not.toBeChecked()
-    await expect(toggle).toBeEnabled()
-    await mcp.getByText("summary-mcp", { exact: true }).click()
-    await expect(toggle).toBeChecked()
-    await expect(toggle).toBeEnabled()
-    expect(mock.calls).toEqual([{ type: "mcp", directory: workspace, enabled: true }])
-    expect(mock.status.get(directory)).toBe("connected")
-    await summary.getByRole("button", { name: "Plugins", exact: true }).click()
-    await expect(
-      page.getByRole("dialog", { name: "Plugins", exact: true }).getByText("workspace-plugin", { exact: true }),
-    ).toBeVisible()
-  })
-}
-
-test("non-Git folders show their status without offering worktree actions", async ({ page }) => {
-  await openDraft(page, "main", { git: false })
-  await page.getByRole("button", { name: "Session details", exact: true }).click()
-  const summary = page.getByRole("dialog", { name: "Session details", exact: true })
-  await expect(summary.getByText("No Git", { exact: true })).toBeVisible()
-  await expect(summary.getByRole("button", { name: "Local repository", exact: true })).toHaveCount(0)
-  await expect(summary.getByRole("button", { name: "New worktree", exact: true })).toHaveCount(0)
-  await summary.getByRole("button", { name: "MCP", exact: true }).click()
-  await expect(
-    page.getByRole("dialog", { name: "MCP", exact: true }).getByRole("switch", { name: "summary-mcp", exact: true }),
-  ).toBeEnabled()
-})
-
-test("submits locally after changing a new worktree draft to Local", async ({ page }) => {
-  const mock = await openDraft(page, "create", { currentDirectory: workspace })
-  await page.getByRole("button", { name: "New worktree", exact: true }).click()
-  await page.getByRole("menuitem", { name: "Local repository", exact: true }).click()
-  await page.locator('[data-component="composer-editor"]').fill("Run locally")
-  await page.locator('[data-action="composer-submit"]').click()
-  await expect.poll(() => mock.calls.find((call) => call.type === "session")?.directory).toBe(directory)
-})
-
-test("new worktree MCP choices persist per draft and apply before the first prompt", async ({ page }, testInfo) => {
-  const mock = await openDraft(page, "create")
-  await page.locator('[data-component="composer-editor"]').fill("Use my selected MCPs")
-  await page.getByRole("button", { name: "Session details", exact: true }).click()
-  await page.getByRole("button", { name: "MCP", exact: true }).click()
-  const menu = page.getByRole("dialog", { name: "MCP", exact: true })
-  await expect(menu.locator('[data-slot="mcp-preview-hint"]')).toHaveText("Applies when the worktree is created")
-  await expect(menu).toHaveCSS("opacity", "1")
-  await testInfo.attach("new-worktree-mcp-preview", { body: await page.screenshot(), contentType: "image/png" })
-  const toggle = menu.getByRole("switch", { name: "summary-mcp", exact: true })
-  await expect(toggle).toBeChecked()
-  await menu.getByText("summary-mcp", { exact: true }).click()
-  await expect(toggle).not.toBeChecked()
-  expect(mock.calls).toEqual([])
-  await expect
-    .poll(() =>
-      page.evaluate(
-        () =>
-          JSON.parse(localStorage.getItem("opencode.window.browser.dat:tabs") ?? "[]").find(
-            (tab: { draftID?: string }) => tab.draftID === "draft_summary",
-          )?.mcp?.states,
-      ),
-    )
-    .toEqual({ "summary-mcp": false })
-
-  await page.goto(`/new-session?draftId=${secondDraftID}`)
-  await page.getByRole("button", { name: "Session details", exact: true }).click()
-  await page.getByRole("button", { name: "MCP", exact: true }).click()
-  await expect(toggle).toBeChecked()
-  await page.goto(draftPath)
-  await page.getByRole("button", { name: "Session details", exact: true }).click()
-  await page.getByRole("button", { name: "MCP", exact: true }).click()
-  await expect(toggle).not.toBeChecked()
-  expect(mock.calls).toEqual([])
-  await page.keyboard.press("Escape")
-  await page.keyboard.press("Escape")
-  await expect(page.locator('[data-component="composer-editor"]')).toHaveText("Use my selected MCPs")
-  await page.locator('[data-action="composer-submit"]').click()
-  await expect.poll(() => mock.prompts.length).toBe(1)
-  expect(mock.calls).toEqual([
-    { type: "worktree", directory },
-    { type: "mcp", directory: createdWorkspace, enabled: false },
-    { type: "session", directory: createdWorkspace },
-    { type: "prompt", directory: createdWorkspace },
-  ])
-  expect(mock.prompts[0].body.text).toBe("Use my selected MCPs")
-  expect(mock.status.get(directory)).toBe("connected")
-})
-
-test("the first prompt waits for a live MCP toggle", async ({ page }) => {
-  const mock = await openDraft(page)
-  const release = Promise.withResolvers<void>()
-  mock.state.hold = release.promise
-  await page.locator('[data-component="composer-editor"]').fill("Wait for the MCP update")
-  await page.getByRole("button", { name: "Session details", exact: true }).click()
-  await page.getByRole("button", { name: "MCP", exact: true }).click()
-  const menu = page.getByRole("dialog", { name: "MCP", exact: true })
-  await expect(menu.getByRole("switch", { name: "summary-mcp", exact: true })).toBeEnabled()
-  try {
-    await menu.getByText("summary-mcp", { exact: true }).click()
-    await expect.poll(() => mock.calls.length).toBe(1)
-    await page.keyboard.press("Escape")
-    await page.keyboard.press("Escape")
-    await page.locator('[data-action="composer-submit"]').click()
-    await expect(page).toHaveURL(draftPath)
-    expect(mock.calls).toEqual([{ type: "mcp", directory, enabled: false }])
-    expect(mock.prompts).toEqual([])
-  } finally {
-    release.resolve()
-  }
-  await expect.poll(() => mock.prompts.length).toBe(1)
-  expect(mock.calls).toEqual([
-    { type: "mcp", directory, enabled: false },
-    { type: "session", directory },
-    { type: "prompt", directory },
-  ])
-})
-
-test("changing worktrees does not wait for another directory's pending MCP update", async ({ page }) => {
-  const mock = await openDraft(page)
-  const release = Promise.withResolvers<void>()
-  mock.state.hold = release.promise
-  mock.state.holdDirectory = directory
-  await page.locator('[data-component="composer-editor"]').fill("Run in the selected worktree")
-  await page.getByRole("button", { name: "Session details", exact: true }).click()
-  const summary = page.getByRole("dialog", { name: "Session details", exact: true })
-  await summary.getByRole("button", { name: "MCP", exact: true }).click()
-  const menu = page.getByRole("dialog", { name: "MCP", exact: true })
-  try {
-    await expect(menu.getByRole("switch", { name: "summary-mcp", exact: true })).toBeEnabled()
-    await menu.getByText("summary-mcp", { exact: true }).click()
-    await expect.poll(() => mock.calls.length).toBe(1)
-    await page.keyboard.press("Escape")
-    await summary.getByRole("button", { name: "Local repository", exact: true }).click()
-    await page.getByRole("menuitem", { name: "Worktree", exact: true }).click()
-    await page.getByRole("menuitem", { name: "existing-worktree", exact: true }).click()
-    await summary.getByRole("button", { name: "MCP", exact: true }).click()
-    const toggle = menu.getByRole("switch", { name: "summary-mcp", exact: true })
-    await expect(toggle).toBeEnabled()
-    await expect(toggle).not.toBeChecked()
-    await menu.getByText("summary-mcp", { exact: true }).click()
-    await expect(toggle).toBeChecked()
-    await expect(toggle).toBeEnabled()
-    await page.keyboard.press("Escape")
-    await page.keyboard.press("Escape")
-    await page.locator('[data-action="composer-submit"]').click()
-    await expect.poll(() => mock.prompts.length).toBe(1)
-    expect(mock.calls.find((call) => call.type === "session")?.directory).toBe(workspace)
-    expect(mock.status.get(directory)).toBe("connected")
-  } finally {
-    release.resolve()
-  }
-})
-
-test("failed MCP preparation restores the draft and reuses the created worktree", async ({ page }) => {
-  const mock = await openDraft(page, "create")
-  mock.state.fail = true
-  await page.locator('[data-component="composer-editor"]').fill("Keep this prompt on failure")
-  await page.getByRole("button", { name: "Session details", exact: true }).click()
-  await page.getByRole("button", { name: "MCP", exact: true }).click()
-  await page.getByRole("dialog", { name: "MCP", exact: true }).getByText("summary-mcp", { exact: true }).click()
-  await page.keyboard.press("Escape")
-  await page.keyboard.press("Escape")
-  await page.locator('[data-action="composer-submit"]').click()
-  await expect(page.getByText("Request failed", { exact: true })).toBeVisible()
-  await expect(page).toHaveURL(draftPath)
-  await expect(page.locator('[data-component="composer-editor"]')).toHaveText("Keep this prompt on failure")
-  await expect(page.getByRole("button", { name: "created-worktree", exact: true })).toBeVisible()
-  expect(mock.prompts).toEqual([])
-  expect(mock.calls.map((call) => call.type)).toEqual(["worktree", "mcp"])
-  mock.state.fail = false
-  await expect(page.locator('[data-action="composer-submit"]')).toBeEnabled()
-  await page.locator('[data-action="composer-submit"]').click()
-  await expect.poll(() => mock.prompts.length).toBe(1)
-  expect(mock.calls.filter((call) => call.type === "worktree")).toHaveLength(1)
-  expect(mock.status.get(createdWorkspace)).toBe("disabled")
-  expect(mock.prompts[0].body.text).toBe("Keep this prompt on failure")
-})
-
-test("new worktree sign-in completes before the draft can send", async ({ page, context }) => {
-  const mock = await openDraft(page, "create")
-  mock.status.set(createdWorkspace, "needs_auth")
-  const attempts: string[] = []
-  await context.route("https://auth.example.test/**", (route) => route.fulfill({ body: "Sign in" }))
-  await page.route("**/api/integration/**", (route) => {
-    if (route.request().method() === "OPTIONS") return route.fallback()
-    if (route.request().method() === "POST") {
-      attempts.push(new URL(route.request().url()).searchParams.get("location[directory]") ?? "")
-      return route.fulfill({
-        json: { location: { directory: createdWorkspace }, data: { url: "https://auth.example.test/authorize" } },
-      })
-    }
-    return route.fulfill({
-      json: {
-        location: { directory: createdWorkspace },
-        data: {
-          id: "summary-oauth",
-          methods: [{ id: "oauth", type: "oauth" }],
-        },
-      },
-    })
-  })
-  await page.locator('[data-component="composer-editor"]').fill("Wait for my sign-in")
-  await page.getByRole("button", { name: "Session details", exact: true }).click()
-  await page.getByRole("button", { name: "MCP", exact: true }).click()
-  const menu = page.getByRole("dialog", { name: "MCP", exact: true })
-  const toggle = menu.getByRole("switch", { name: "summary-mcp", exact: true })
-  await expect(toggle).toBeChecked()
-  await menu.getByText("summary-mcp", { exact: true }).click()
-  await expect(toggle).not.toBeChecked()
-  await menu.getByText("summary-mcp", { exact: true }).click()
-  await expect(toggle).toBeChecked()
-  await page.keyboard.press("Escape")
-  await page.keyboard.press("Escape")
-  const popup = page.waitForEvent("popup")
-  await page.locator('[data-action="composer-submit"]').click()
-  await expect(await popup).toHaveURL("https://auth.example.test/authorize")
-  await expect(page).toHaveURL(draftPath)
-  await expect(page.locator('[data-component="composer-editor"]')).toHaveText("Wait for my sign-in")
-  expect(attempts).toEqual([createdWorkspace])
-  expect(mock.prompts).toEqual([])
-  mock.status.set(createdWorkspace, "connected")
-  await page.locator('[data-action="composer-submit"]').click()
-  await expect.poll(() => mock.prompts.length).toBe(1)
-  expect(mock.calls.filter((call) => call.type === "worktree")).toHaveLength(1)
-  expect(attempts).toHaveLength(1)
-})
-
-async function openDraft(
-  page: Page,
-  worktree = "main",
-  options: { git?: boolean; direction?: "ltr" | "rtl"; currentDirectory?: string } = {},
-) {
-  const currentDirectory = options.currentDirectory ?? directory
-  const project = {
-    id: "proj_new_summary",
-    worktree: directory,
-    name: "summary-project",
-    vcs: options.git === false ? undefined : "git",
-    time: { created: 1, updated: 1 },
-    sandboxes: [workspace],
-  }
-  const sessions: ReturnType<typeof currentSession>[] = []
-  const status = new Map<string, string>([
-    [directory, "connected"],
-    [workspace, "disabled"],
-    [createdWorkspace, "connected"],
-  ])
-  const calls: { type: string; directory: string; enabled?: boolean }[] = []
-  const prompts: { sessionID: string; body: Record<string, unknown> }[] = []
-  const state: { fail: boolean; hold?: Promise<void>; holdDirectory?: string } = { fail: false }
+test("does not show session details on the new session screen", async ({ page }, testInfo) => {
  await mockOpenCodeServer(page, {
-    directory: currentDirectory,
-    project,
-    sessions,
+    directory,
+    project: {
+      id: "proj_new_summary",
+      worktree: directory,
+      vcs: "git",
+      name: "summary-project",
+      time: { created: 1, updated: 1 },
+      sandboxes: [],
+    },
    provider: {
      all: [
        {
@@ -343,148 +28,28 @@ async function openDraft(
      connected: ["opencode"],
      default: { providerID: "opencode", modelID: "summary-model" },
    },
+    sessions: [],
    pageMessages: () => ({ items: [] }),
-    onPrompt(input) {
-      const session = sessions.find((session) => session.id === input.sessionID)
-      if (!session?.location.directory) throw new Error("Prompt arrived before session creation")
-      calls.push({ type: "prompt", directory: session.location.directory })
-      prompts.push(input)
-    },
  })
-  if (options.git === false) {
-    await page.route(
-      (url) => url.pathname === "/api/vcs",
-      (route) => route.fulfill({ json: { location: { directory }, data: { branch: {} } } }),
-    )
-  }
-  await page.route(/\/api\/(?:experimental\/)?mcp(?:[/?]|$)/, async (route) => {
-    if (route.request().method() === "OPTIONS") return route.fallback()
-    const url = new URL(route.request().url())
-    const target = url.searchParams.get("location[directory]") ?? directory
-    if (route.request().method() === "POST") {
-      const enabled = url.pathname.endsWith("/connect")
-      calls.push({ type: "mcp", directory: target, enabled })
-      if (!state.holdDirectory || state.holdDirectory === target) await state.hold
-      if (state.fail) return route.fulfill({ status: 500, json: { message: "MCP fixture failed" } })
-      status.set(target, enabled ? "connected" : "disabled")
-      return route.fulfill({ status: 204 })
-    }
-    return route.fulfill({
-      json: {
-        location: { directory: target },
-        data:
-          url.pathname === "/api/mcp/resource"
-            ? { resources: [], templates: [] }
-            : [
-                {
-                  name: "summary-mcp",
-                  integrationID: "summary-oauth",
-                  status: { status: status.get(target) ?? "connected" },
-                },
-              ],
-      },
-    })
-  })
-  await page.route(
-    (url) => url.pathname === "/api/location",
-    (route) =>
-      route.fulfill({
-        json: {
-          directory: new URL(route.request().url()).searchParams.get("location[directory]") ?? directory,
-          project: { id: project.id, directory, canonical: directory },
-        },
-      }),
-  )
-  await page.route(
-    (url) => url.pathname === "/api/plugin",
-    (route) => {
-      const target = new URL(route.request().url()).searchParams.get("location[directory]") ?? directory
-      const id = target === directory ? "project-plugin" : "workspace-plugin"
-      return route.fulfill({
-        json: {
-          location: { directory: target },
-          data: [{ id, source: { type: "package", target: id }, features: {}, state: { status: "active" } }],
-        },
-      })
-    },
-  )
-  await page.route(
-    (url) => url.pathname === "/api/skill",
-    (route) =>
-      route.fulfill({
-        json: {
-          location: { directory: new URL(route.request().url()).searchParams.get("location[directory]") ?? directory },
-          data: [
-            {
-              id: "summary-skill",
-              name: "summary-skill",
-              path: "/skills/summary/SKILL.md",
-              content: "Summary skill",
-            },
-          ],
-        },
-      }),
-  )
-  await page.route(
-    (url) => url.pathname === "/api/config",
-    (route) =>
-      route.fulfill({
-        json: [{ type: "document", info: { lsp: { typescript: { command: ["typescript-language-server"] } } } }],
-      }),
-  )
-  await page.route(
-    (url) => url.pathname === "/api/worktree",
-    (route) => {
-      if (route.request().method() !== "POST") return route.fallback()
-      calls.push({ type: "worktree", directory })
-      project.sandboxes.push(createdWorkspace)
-      return route.fulfill({ json: { directory: createdWorkspace } })
-    },
-  )
-  await page.route(
-    (url) => url.pathname === "/api/session",
-    (route) => {
-      if (route.request().method() !== "POST") return route.fallback()
-      const body: { id: string; location: { directory: string } } = route.request().postDataJSON()
-      calls.push({ type: "session", directory: body.location.directory })
-      const session = currentSession(
-        { ...body, projectID: project.id, title: "Created summary session" },
-        body.location.directory,
-      )
-      sessions.push(session)
-      return route.fulfill({ json: { data: session } })
-    },
-  )
  await page.addInitScript(
-    ({ directory, currentDirectory, server, draftID, secondDraftID, worktree }) => {
-      if (!localStorage.getItem("opencode.global.dat:server"))
-        localStorage.setItem(
-          "opencode.global.dat:server",
-          JSON.stringify({
-            projects: { local: [{ worktree: directory, expanded: true }] },
-            lastProject: { local: directory },
-          }),
-        )
-      if (!localStorage.getItem("opencode.window.browser.dat:tabs"))
-        localStorage.setItem(
-          "opencode.window.browser.dat:tabs",
-          JSON.stringify([
-            { type: "draft", draftID, server, directory: currentDirectory, worktree },
-            { type: "draft", draftID: secondDraftID, server, directory: currentDirectory, worktree },
-          ]),
-        )
+    ({ directory, draftID, server }) => {
+      localStorage.setItem(
+        "opencode.global.dat:server",
+        JSON.stringify({
+          projects: { local: [{ worktree: directory, expanded: true }] },
+          lastProject: { local: directory },
+        }),
+      )
+      localStorage.setItem(
+        "opencode.window.browser.dat:tabs",
+        JSON.stringify([{ type: "draft", draftID, server, directory }]),
+      )
    },
-    { directory, currentDirectory, server, draftID, secondDraftID, worktree },
+    { directory, draftID, server },
  )
-  if (options.direction) await openWithDirection(page, draftPath, options.direction)
-  if (!options.direction) await page.goto(draftPath)
-  await expect(page.locator('[data-component="composer-editor"]')).toBeEditable()
-  await expect(page.locator('[data-action="composer-model"]')).toContainText("Summary Model")
-  if (options.git === false) await expect(page.getByText("No Git", { exact: true })).toBeVisible()
-  if (options.git !== false) {
-    await expect(
-      page.getByRole("button", { name: worktree === "create" ? "New worktree" : "Local", exact: true }),
-    ).toBeVisible()
-  }
-  return { calls, prompts, status, state }
-}
+
+  await page.goto(`/new-session?draftId=${draftID}`)
+  await expectAppVisible(page.locator('[data-component="composer-editor"]'))
+  await expect(page.getByRole("button", { name: "Session details", exact: true })).toHaveCount(0)
+  await testInfo.attach("new-session-without-summary", { body: await page.screenshot(), contentType: "image/png" })
+})
@@ -1,54 +0,0 @@
-import { expect, test } from "@playwright/test"
-
-test("pairs locally without checking the server and authenticates subsequent requests", async ({ page, baseURL }) => {
-  const origin = new URL(baseURL ?? "http://127.0.0.1:3000").origin
-  const password = "pairing-secret"
-  const authorization = `Basic ${Buffer.from(`opencode:${password}`).toString("base64")}`
-  const requests: { origin: string; authorization: string | undefined }[] = []
-  await page.addInitScript((origin) => {
-    if (localStorage.getItem("opencode.global.dat:server")) return
-    localStorage.setItem(
-      "opencode.global.dat:server",
-      JSON.stringify({ list: [{ type: "http", http: { url: origin, password: "old-password" } }] }),
-    )
-  }, origin)
-  await page.route("**/api/**", async (route) => {
-    requests.push({
-      origin: new URL(route.request().url()).origin,
-      authorization: route.request().headers().authorization,
-    })
-    // Pairing must succeed even when the API is unavailable.
-    await route.fulfill({ status: 503, contentType: "application/json", body: "{}" })
-  })
-
-  await page.goto(`/connect#${Buffer.from(JSON.stringify({ username: "opencode", password })).toString("base64url")}`)
-  await expect(page).toHaveURL(`${origin}/`)
-  await expect(page.getByRole("button", { name: "Home", exact: true })).toBeVisible()
-  await expect
-    .poll(() => page.evaluate(() => JSON.parse(localStorage.getItem("opencode.global.dat:server") ?? "{}").list))
-    .toEqual([{ type: "http", http: { url: origin, password } }])
-  await expect.poll(() => requests.filter((request) => request.origin === origin).length).toBeGreaterThan(0)
-  expect(
-    requests.filter((request) => request.origin === origin).every((request) => request.authorization === authorization),
-  ).toBe(true)
-
-  requests.length = 0
-  await page.reload()
-  await expect(page.getByRole("button", { name: "Home", exact: true })).toBeVisible()
-  await expect.poll(() => requests.filter((request) => request.origin === origin).length).toBeGreaterThan(0)
-  expect(
-    requests.filter((request) => request.origin === origin).every((request) => request.authorization === authorization),
-  ).toBe(true)
-})
-
-test("the unpaired page loads without starting server requests", async ({ page }) => {
-  const requests: string[] = []
-  await page.route("**/api/**", async (route) => {
-    requests.push(route.request().url())
-    await route.abort()
-  })
-  await page.goto("/connect")
-  await expect(page.getByRole("heading", { name: "Connect to a server" })).toBeVisible()
-  await expect(page.getByLabel("Password", { exact: true })).toBeEditable()
-  expect(requests).toEqual([])
-})
@@ -96,7 +96,7 @@ for (const field of [
    expect(patches).toEqual(field.patches)

    await settings.getByRole("tab", { name: "Worktrees", exact: true }).click()
-    await settings.getByRole("tab", { name: project.name, exact: true }).click()
+    await settings.getByRole("tab", { name: "General", exact: true }).click()
    if (field.name === "color") {
      await expect(settings.getByRole("button", { name: "Select orange color", exact: true })).toHaveAttribute(
        "aria-pressed",
@@ -37,11 +37,6 @@ for (const direction of ["ltr", "rtl"] as const) {
          "opencode.global.dat:language",
          JSON.stringify({ locale: direction === "rtl" ? "ar" : "en" }),
        )
-        const settings = JSON.parse(localStorage.getItem("settings.v3") ?? "{}")
-        localStorage.setItem(
-          "settings.v3",
-          JSON.stringify({ ...settings, general: { ...settings.general, showProjectIcon: false } }),
-        )
      }, direction)
      await page.setViewportSize({ width: workspace ? 900 : 1440, height: 900 })
      await page.goto(stressSessionHref(fixture.targetID))
@@ -64,7 +59,7 @@ for (const direction of ["ltr", "rtl"] as const) {
      await trigger.click()

      const menu = page.getByRole("menu", { name: project.name, exact: true })
-      const settings = menu.getByRole("menuitem", { name: "Edit project", exact: true })
+      const settings = menu.getByRole("menuitem", { name: copy["project.settings.title"], exact: true })
      const projectItem = menu.getByRole("menuitem", { name: project.name, exact: true })
      await expect(trigger).toHaveAttribute("aria-expanded", "true")
      await expect(page.getByRole("tooltip")).toBeHidden()
@@ -74,7 +69,7 @@ for (const direction of ["ltr", "rtl"] as const) {
      await expect(menu.getByText(directory, { exact: true })).toHaveAttribute("dir", "ltr")
      await expect(menu.locator('use[href="#opencode-v2-icon-folder"]')).toHaveCount(1)
      await expect(menu).toHaveCSS("direction", direction)
-      await expect(menu.getByRole("menuitem")).toHaveText([project.name, directory, "Edit project"])
+      await expect(menu.getByRole("menuitem")).toHaveText([project.name, directory, copy["project.settings.title"]])
      await expect(menu.getByRole("menuitem", { name: directory, exact: true })).toBeDisabled()
      await expect(settings).toBeEnabled()
      await expect
@@ -203,11 +198,11 @@ for (const direction of ["ltr", "rtl"] as const) {
      const settingsScreen = page.getByTestId("settings-screen")
      await expect(settingsScreen.getByRole("heading", { name: project.name, exact: true })).toBeVisible()
      await expect(
-        settingsScreen.getByRole("textbox", { name: en["project.settings.name.title"], exact: true }),
+        settingsScreen.getByRole("textbox", { name: copy["project.settings.name.title"], exact: true }),
      ).toHaveValue(project.name)
      await expect(menu).toBeHidden()
-      await settingsScreen.getByRole("button", { name: en["settings.backToProjects"], exact: true }).click()
-      await settingsScreen.getByRole("button", { name: en["settings.backToApp"], exact: true }).click()
+      await settingsScreen.getByRole("button", { name: copy["settings.backToProjects"], exact: true }).click()
+      await settingsScreen.getByRole("button", { name: copy["settings.backToApp"], exact: true }).click()
      await expect(settingsScreen).toBeHidden()
      await expect(header.getByRole("heading")).toHaveText(fixture.expected.targetTitle)

@@ -1,5 +1,5 @@
 import { expect, test, type Page } from "@playwright/test"
-import type { OpenCodeEvent, SessionMessageInfo } from "@opencode/client/promise"
+import type { OpenCodeEvent, SessionInboxInfo, SessionMessageInfo } from "@opencode/client/promise"
 import { base64Encode } from "@opencode/util/encode"
 import { mockOpenCodeServer } from "../utils/mock-server"
 import { expectAppVisible } from "../utils/waits"
@@ -14,7 +14,12 @@ type InboxRow = {
  sessionID: string
  time: { created: number }
  type: "user"
-  payload: { text: string; metadata?: Record<string, unknown> }
+  payload: {
+    text: string
+    metadata?: Record<string, unknown>
+    files?: Extract<SessionInboxInfo, { type: "user" }>["payload"]["files"]
+    agents?: Extract<SessionInboxInfo, { type: "user" }>["payload"]["agents"]
+  }
  delivery: "steer" | "queue"
 }

@@ -29,7 +34,7 @@ function createQueueMock(seed: string[], messages: SessionMessageInfo[] = []) {
  }))
  const events: OpenCodeEvent[] = []
  const prompts: Record<string, unknown>[] = []
-  const changes: { inboxID: string; action: "cancel" | "steer" }[] = []
+  const changes: { inboxID: string; action: "cancel" | "steer" | "queue" }[] = []
  const log: string[] = []
  let sequence = 0
  const emit = <Type extends OpenCodeEvent["type"]>(
@@ -234,6 +239,113 @@ test("editing restores the existing draft and replaces only the original queue p
  expect(mock.log[0]).toBe("prompt:queue")
 })

+test("Move Back cancels only the selected queued prompt and focuses the restored input", async ({ page }) => {
+  const mock = createQueueMock(["first queued prompt", "second queued prompt", "third queued prompt"])
+  const view = await openSession(page, mock)
+  await expect(view.rows).toHaveCount(3)
+
+  const row = view.rows.filter({ hasText: "second queued prompt" })
+  const actions = row.locator('[data-slot="session-queue-actions"] button')
+  await expect(actions).toHaveCount(3)
+  expect(
+    await actions.evaluateAll((buttons) =>
+      buttons.map((button) => button.getAttribute("aria-label") ?? button.textContent?.trim()),
+    ),
+  ).toEqual(["Steer", "Move Back", "Remove"])
+  const moveBack = row.getByRole("button", { name: "Move Back" })
+  await expect(moveBack).toHaveText("")
+  await expect(moveBack.locator("svg use")).toHaveAttribute("href", "#opencode-v2-icon-arrow-undo-down")
+  await moveBack.hover()
+  await expect(page.getByRole("tooltip")).toHaveText("Move Back")
+  await moveBack.click()
+  await expect(view.rows.locator('[data-action="session-queue-edit"]')).toHaveText([
+    "first queued prompt",
+    "third queued prompt",
+  ])
+  await expect(view.input).toHaveText("second queued prompt")
+  await expect(view.input).toBeFocused()
+  expect(mock.changes).toEqual([{ inboxID: "inb_seed_2", action: "cancel" }])
+  expect(mock.prompts).toEqual([])
+})
+
+test("Move Back preserves an existing draft and restores inline attachments", async ({ page }) => {
+  const mock = createQueueMock(["queued with image"])
+  mock.rows[0].payload.files = [
+    {
+      data: "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4z8DwHwAFgAI/ScL/nwAAAABJRU5ErkJggg==",
+      mime: "image/png",
+      source: { type: "inline" },
+      name: "shot.png",
+    },
+  ]
+  const view = await openSession(page, mock)
+  await view.input.fill("my draft")
+  await view.rows.getByRole("button", { name: "Move Back" }).click()
+  await expect(view.input).toHaveText("my draft")
+  expect(mock.changes).toEqual([])
+
+  await view.input.fill("")
+  await view.rows.getByRole("button", { name: "Move Back" }).click()
+  await expect(view.rows).toHaveCount(0)
+  await expect(view.input).toHaveText("queued with image")
+  await expect(view.input).toBeFocused()
+  await expect(view.composer.getByRole("img", { name: "shot.png" })).toBeVisible()
+  expect(mock.changes).toEqual([{ inboxID: "inb_seed_1", action: "cancel" }])
+})
+
+test("Move Back stays usable with a long queue on a narrow screen", async ({ page }, testInfo) => {
+  await page.setViewportSize({ width: 390, height: 844 })
+  const text = "Review the detailed error report and check every step of the retry path ".repeat(4)
+  const mock = createQueueMock([text, ...Array.from({ length: 6 }, (_, index) => `queued follow-up ${index + 1}`)])
+  const view = await openSession(page, mock)
+  await expect(view.rows).toHaveCount(7)
+  const row = view.rows.filter({ hasText: text })
+  await row.getByRole("button", { name: "Move Back" }).hover()
+  await expect(page.getByRole("tooltip")).toHaveText("Move Back")
+  await page.screenshot({ path: testInfo.outputPath("move-back-narrow-queue.png") })
+  await row.getByRole("button", { name: "Move Back" }).click()
+  await expect(view.rows).toHaveCount(6)
+  await expect(view.input).toHaveText(text)
+  await expect(view.input).toBeFocused()
+  expect(mock.changes).toEqual([{ inboxID: "inb_seed_1", action: "cancel" }])
+})
+
+test("Move Back preserves mentioned file and agent references on resubmission", async ({ page }) => {
+  const mock = createQueueMock(["inspect @main.ts with @build"])
+  mock.rows[0].payload.files = [
+    {
+      data: "aGk=",
+      mime: "text/plain",
+      source: { type: "uri", uri: "file:///repo/main.ts" },
+      name: "main.ts",
+      mention: { start: 8, end: 16, text: "@main.ts" },
+    },
+  ]
+  mock.rows[0].payload.agents = [{ name: "build", mention: { start: 22, end: 28, text: "@build" } }]
+  const view = await openSession(page, mock)
+  await view.rows.getByRole("button", { name: "Move Back" }).click()
+  await expect(view.input).toHaveText("inspect @main.ts with @build")
+  await view.input.press("Enter")
+  await expect.poll(() => mock.prompts.length).toBe(1)
+  expect(mock.prompts[0].files).toMatchObject([
+    { uri: "data:text/plain;base64,aGk=", mention: { text: "@main.ts", start: 8, end: 16 } },
+  ])
+  expect(mock.prompts[0].agents).toMatchObject([{ name: "build", mention: { text: "@build" } }])
+})
+
+test("Move Back does not discard hidden file context", async ({ page }) => {
+  const mock = createQueueMock(["inspect this file"])
+  mock.rows[0].payload.files = [
+    { data: "aGk=", mime: "text/plain", source: { type: "uri", uri: "file:///repo/main.ts" }, name: "main.ts" },
+  ]
+  const view = await openSession(page, mock)
+  await view.rows.getByRole("button", { name: "Move Back" }).click()
+  await expect(page.getByText("Edit this prompt in the queue to preserve its file context")).toBeVisible()
+  await expect(view.rows).toHaveCount(1)
+  await expect(view.input).toHaveText("")
+  expect(mock.changes).toEqual([])
+})
+
 for (const delivery of ["steer", "queue"] as const) {
  test(`keeps finished tools above a pending ${delivery === "queue" ? "queue-to-steer" : "steer"} follow-up`, async ({
    page,
@@ -284,7 +396,13 @@ for (const delivery of ["steer", "queue"] as const) {
    await expect(thinking).toHaveCount(0)

    // The next assistant step still belongs to U1: U2 has been admitted, not delivered.
-    mock.emit("session.step.started", { sessionID, assistantMessageID: assistantID, agent: "build", model, started: Date.now() })
+    mock.emit("session.step.started", {
+      sessionID,
+      assistantMessageID: assistantID,
+      agent: "build",
+      model,
+      started: Date.now(),
+    })
    for (const tool of [
      { id: "tool_queue_read", name: "read", input: { path: "src/queue.ts" } },
      { id: "tool_queue_grep", name: "grep", input: { pattern: "retry", path: "src" } },
@@ -309,7 +427,10 @@ for (const delivery of ["steer", "queue"] as const) {
    const tools = page.locator('[data-timeline-part-ids="tool_queue_read,tool_queue_grep"]')
    await expect(tools).toBeVisible()
    await expect(tools).toHaveText(/^Used\s*2\s*Read, Grep$/)
-    await expect(tools.locator('[data-slot="basic-tool-tool-title"]')).toHaveText("Read, Grep")
+    await expect(tools.locator('[data-component="context-tool-group-trigger"]')).toHaveAttribute(
+      "aria-label",
+      "Used 2 Read, Grep",
+    )
    await expect(thinking).toHaveCount(0)
    await expect(pending).toBeVisible()
    expect(mock.rows.map((row) => ({ id: row.id, delivery: row.delivery }))).toEqual([
@@ -4,8 +4,7 @@ import { mockStressTimeline, stressSessionHref } from "../performance/timeline/t
 import { openWithDirection } from "../utils/direction"

 for (const direction of ["ltr", "rtl"] as const) {
-  test(`summary slides the conversation into spare space and back in ${direction}`, async ({ page }, testInfo) => {
-    await page.clock.install({ time: new Date("2026-09-10T12:00:00Z") })
+  test(`summary overlays the conversation without shifting it in ${direction}`, async ({ page }, testInfo) => {
    await page.setViewportSize({ width: 1440, height: 900 })
    await mockStressTimeline(page)
    await openWithDirection(page, stressSessionHref(fixture.targetID), direction)
@@ -18,7 +17,6 @@ for (const direction of ["ltr", "rtl"] as const) {
    )
    const content = page.locator("[data-timeline-virtual-content]")
    const composer = page.locator('[data-component="session-composer-dock"] > div')
-    const panel = page.locator('[data-slot="session-chat-panel"]')
    const summary = page.getByRole("dialog", { name: "Session details", exact: true })
    await expect(row).toBeInViewport()
    await expect(row).toHaveCSS("width", "1000px")
@@ -26,103 +24,43 @@ for (const direction of ["ltr", "rtl"] as const) {
    const dock = await composer.boundingBox()
    expect(before).not.toBeNull()
    expect(dock).not.toBeNull()
-    await content.evaluate((element) => {
-      element.setAttribute("data-summary-motion", "")
-      for (const type of ["transitionrun", "transitionend"]) {
-        element.addEventListener(type, (event) => {
-          if (event.target !== element || (event as TransitionEvent).propertyName !== "translate") return
-          element.setAttribute("data-summary-motion", `${element.getAttribute("data-summary-motion")}${type},`)
-        })
-      }
-    })
+    await expect(content).toHaveCSS("translate", "none")
+    await expect(composer).toHaveCSS("translate", "none")
    await testInfo.attach(`summary-${direction}-centered`, { body: await page.screenshot(), contentType: "image/png" })
    await trigger.click()
-    await expect(content).toHaveAttribute("data-summary-motion", "transitionrun,transitionend,")
+    await expect(summary).toBeVisible()
    await expect
      .poll(async () => {
        const message = await row.boundingBox()
        const details = await summary.boundingBox()
-        const chat = await panel.boundingBox()
-        if (!message || !details || !chat) return false
-        return (
-          message.x >= chat.x &&
-          message.x + message.width <= chat.x + chat.width &&
-          (direction === "ltr" ? message.x + message.width < details.x : message.x > details.x + details.width)
-        )
+        if (!message || !details) return 0
+        return Math.min(message.x + message.width, details.x + details.width) - Math.max(message.x, details.x)
      })
-      .toBe(true)
+      .toBeGreaterThan(0)
    await expect(row).toHaveCSS("width", "1000px")
    await expect
      .poll(async () => {
        const message = await row.boundingBox()
        const input = await composer.boundingBox()
        if (!message || !input || !before || !dock) return Infinity
-        return Math.abs(message.x - before.x - (input.x - dock.x))
+        return Math.max(Math.abs(message.x - before.x), Math.abs(input.x - dock.x))
      })
      .toBeLessThan(1)
-    await expect
-      .poll(() =>
-        content.evaluate((element) => element.parentElement!.scrollWidth - element.parentElement!.clientWidth),
-      )
-      .toBe(0)
-    await testInfo.attach(`summary-${direction}-shifted`, { body: await page.screenshot(), contentType: "image/png" })
+    await expect(content).toHaveCSS("translate", "none")
+    await expect(composer).toHaveCSS("translate", "none")
+    await testInfo.attach(`summary-${direction}-overlay`, { body: await page.screenshot(), contentType: "image/png" })

-    await page.clock.pauseAt(new Date("2026-09-10T12:01:00Z"))
-    const shifted = await content.evaluate((element) => getComputedStyle(element).translate)
-    await content.evaluate((element) => element.setAttribute("data-summary-motion", ""))
-    // Keep issuing resize events before the idle timer expires, including crossing the width cutoff.
-    for (const width of [1520, 1280, 1800]) {
-      await page.setViewportSize({ width, height: 900 })
-      await expect(panel).toHaveAttribute("data-summary-resizing", "true")
-      await page.clock.runFor(100)
-      await expect(content).toHaveCSS("translate", shifted)
-      await expect(composer).toHaveCSS("translate", shifted)
-      await expect(content).toHaveAttribute("data-summary-motion", "")
-    }
-    await page.clock.resume()
-    await expect(panel).toHaveAttribute("data-summary-resizing", "false")
-    await expect(content).toHaveAttribute("data-summary-motion", "transitionrun,transitionend,")
-    await expect(content).not.toHaveCSS("translate", shifted)
-    await page.setViewportSize({ width: 1440, height: 900 })
-    await expect(panel).toHaveAttribute("data-summary-resizing", "false")
-    await expect(content).toHaveCSS("translate", shifted)
-
-    await content.evaluate((element) => element.setAttribute("data-summary-motion", ""))
    await page.keyboard.press("Escape")
    await expect(summary).toBeHidden()
-    await expect(content).toHaveAttribute("data-summary-motion", "transitionrun,transitionend,")
    await expect.poll(async () => Math.abs((await row.boundingBox())!.x - before!.x)).toBeLessThan(1)
    await expect(trigger).toBeFocused()

    await trigger.click()
    await expect(summary.getByRole("button", { name: "Extensions", exact: true })).toBeVisible()
-    // Cross the actual chat-panel breakpoint, including any surrounding shell width.
-    const shell = 1440 - (await panel.boundingBox())!.width
-    await page.setViewportSize({ width: 1320 + shell, height: 900 })
-    await expect.poll(async () => (await panel.boundingBox())!.width).toBe(1320)
-    await expect
-      .poll(async () => {
-        const message = (await row.boundingBox())!
-        const details = (await summary.boundingBox())!
-        return direction === "ltr" ? details.x - message.x - message.width : message.x - details.x - details.width
-      })
-      .toBeGreaterThan(0)
-    await page.setViewportSize({ width: 1319 + shell, height: 900 })
-    await expect(content).toHaveCSS("translate", "none")
-    await expect(row).toHaveCSS("width", "1000px")
-    await expect(summary).toBeVisible()
-
    await page.setViewportSize({ width: 1800, height: 900 })
-    await expect(panel).toHaveAttribute("data-summary-resizing", "false")
    await expect(content).toHaveCSS("translate", "none")
+    await expect(composer).toHaveCSS("translate", "none")
    await expect(summary).toBeVisible()
-
-    await page.emulateMedia({ reducedMotion: "reduce" })
-    await page.setViewportSize({ width: 1440, height: 900 })
-    await expect(content).toHaveCSS("transition-duration", "0s")
-    await page.keyboard.press("Escape")
-    await expect(content).toHaveCSS("translate", "none")
-    await expect.poll(async () => Math.abs((await row.boundingBox())!.x - before!.x)).toBeLessThan(1)
  })
 }

@@ -111,7 +111,10 @@ test.describe("regression: session timeline local row state", () => {
      const id = `prt_patch_${count}`
      events.push(...toolEvents({ ...part, id, callID: id }))
      await expect(summary).toHaveAccessibleName(`Used ${count} Patch`)
-      await expect(summary.locator('[data-slot="basic-tool-tool-title"]')).toHaveText("Patch")
+      await expect(summary.locator('[data-component="context-tool-group-trigger"]')).toHaveAttribute(
+        "aria-label",
+        `Used ${count} Patch`,
+      )
      await expect(group).toHaveAttribute("data-timeline-part-ids", new RegExp(`${id}$`))
      await expect(trigger).toHaveAttribute("aria-expanded", String(count === 2))
      await expect(summary).toHaveAttribute("aria-expanded", "true")
@@ -16,9 +16,9 @@ for (const locale of ["de", "ar"] as const) {
    })

    const group = page.locator(`[data-timeline-part-ids="${ids.join(",")}"]`)
-    const names = locale === "de" ? "Lesen, Glob" : "\u0642\u0631\u0627\u0621\u0629, Glob"
-    await expect(group.getByRole("button")).toHaveAccessibleName(`Used 2 ${names}`)
-    await expect(group.locator('[data-slot="basic-tool-tool-title"]')).toHaveText(names)
+    const label = locale === "de" ? "2 Lesen und Glob verwendet" : "استُخدمت 2 أداتان: \u2068قراءة وGlob\u2069"
+    await expect(group.getByRole("button")).toHaveAccessibleName(label)
+    await expect(group.locator('[data-component="context-tool-group-trigger"]')).toHaveAttribute("aria-label", label)
    await expect(page.locator("html")).toHaveAttribute("lang", locale)
  })
 }
@@ -48,7 +48,10 @@ test("expands a mixed collapsed tool stack without expanding its individual call
  const summary = group.getByRole("button", { name: "Used 4 Shell, Agent, Patch", exact: true })
  await expect(summary).toHaveAttribute("aria-expanded", "false")
  await expect(summary).toHaveCSS("height", "28px")
-  await expect(summary.locator('[data-slot="basic-tool-tool-title"]')).toHaveText("Shell, Agent, Patch")
+  await expect(summary.locator('[data-component="context-tool-group-trigger"]')).toHaveAttribute(
+    "aria-label",
+    "Used 4 Shell, Agent, Patch",
+  )
  await expect(summary.locator('[data-component="tag"]')).toHaveCount(0)
  await summary.click()
  await expect(summary).toHaveAttribute("aria-expanded", "true")
@@ -76,7 +79,10 @@ test("leaves tools expanded by settings outside the collapsed stack", async ({ p
  await expect(page.locator('[data-timeline-part-id="prt_expanded_shell"]')).toBeVisible()
  const group = page.locator('[data-timeline-part-ids="prt_collapsed_patch,prt_collapsed_read"]')
  await expect(group.getByRole("button", { name: "Used 2 Patch, Read", exact: true })).toBeVisible()
-  await expect(group.locator('[data-slot="basic-tool-tool-title"]')).toHaveText("Patch, Read")
+  await expect(group.locator('[data-component="context-tool-group-trigger"]')).toHaveAttribute(
+    "aria-label",
+    "Used 2 Patch, Read",
+  )
  await expect(page.locator('[data-timeline-spacing="tool"]')).toHaveCSS("padding-top", "8px")
 })

@@ -67,8 +67,7 @@ test("an inventory event updates the open all-project worktree list", async ({ p
  await settings.getByRole("tab", { name: "Worktrees", exact: true }).click()
  await expect(settings.getByText(sandboxes[0], { exact: true })).toBeVisible()
  const listed = page.waitForResponse(
-    (response) =>
-      new URL(response.url()).pathname === "/api/worktree" && response.request().method() === "GET",
+    (response) => new URL(response.url()).pathname === "/api/worktree" && response.request().method() === "GET",
  )
  inventory.push({ directory: discovered, strategy: "git" })
  events.push({
@@ -99,6 +98,51 @@ test("settings has its own route and returns through app history", async ({ page
  await expect(home).toHaveAttribute("aria-pressed", "true")
 })

+test("settings page survives refresh", async ({ page }) => {
+  const settings = page.getByTestId("settings-screen")
+  const appearance = settings.getByRole("tab", { name: "Appearance", exact: true })
+
+  await appearance.click()
+  await expect(page).toHaveURL("/settings?tab=appearance")
+  await expect(appearance).toHaveAttribute("aria-selected", "true")
+
+  await page.reload()
+
+  await expect(settings).toBeVisible()
+  await expect(appearance).toHaveAttribute("aria-selected", "true")
+  await expect(page).toHaveURL("/settings?tab=appearance")
+})
+
+test("another server's settings page survives refresh", async ({ page }) => {
+  const remote = "http://127.0.0.1:4097"
+  await page.addInitScript(
+    (input) => {
+      localStorage.setItem(
+        "opencode.global.dat:server",
+        JSON.stringify({
+          list: [{ type: "http", http: { url: input.remote } }],
+          projects: { local: [{ worktree: input.directory, expanded: true }] },
+        }),
+      )
+    },
+    { directory, remote },
+  )
+  const settings = page.getByTestId("settings-screen")
+  const url = (value: URL) =>
+    value.pathname === "/settings" &&
+    value.searchParams.get("server") === remote &&
+    value.searchParams.get("tab") === "providers"
+
+  await page.goto(`/settings?server=${encodeURIComponent(remote)}&tab=providers`)
+  await expect(settings.getByRole("heading", { name: "Providers", exact: true })).toBeVisible()
+  await expect(page).toHaveURL(url)
+
+  await page.reload()
+
+  await expect(settings.getByRole("heading", { name: "Providers", exact: true })).toBeVisible()
+  await expect(page).toHaveURL(url)
+})
+
 test("single-server settings expose scoped pages without a server picker", async ({ page }) => {
  const settings = page.getByTestId("settings-screen")
  await expect(settings.getByRole("tab", { name: "Server", exact: true })).toBeVisible()
@@ -134,10 +178,53 @@ test("project settings open as a nested autosaving view", async ({ page }) => {
  await settings.getByRole("button", { name: "Settings demo", exact: true }).click()

  await expect(settings.getByRole("button", { name: "Back to projects", exact: true })).toBeVisible()
-  await expect(settings.getByRole("tab", { name: "Settings demo", exact: true })).toBeVisible()
+  await expect(settings.getByRole("tab", { name: "General", exact: true })).toBeVisible()
  await expect(settings.getByRole("tab", { name: "Worktrees", exact: true })).toBeVisible()
  await expect(settings.getByRole("tab", { name: "Extensions", exact: true })).toBeVisible()
  await expect(settings.getByRole("tab", { name: "Scripts", exact: true })).toHaveCount(0)
+  await expect(settings.getByTitle(directory)).toHaveCount(0)
+  const projectIcon = settings.locator('.settings-tab-header [data-component="project-avatar-v2"]')
+  await expect(projectIcon).toHaveCSS("width", "32px")
+  const projectOptions = settings
+    .locator(".settings-tab-header")
+    .getByRole("button", { name: "More options", exact: true })
+  await expect(projectOptions).toHaveCSS("width", "28px")
+  await expect
+    .poll(
+      async () =>
+        new Set(
+          await Promise.all(
+            [
+              settings.getByRole("button", { name: "Back to projects", exact: true }),
+              settings.getByRole("heading", { name: "Settings demo", exact: true }),
+              projectIcon,
+              projectOptions,
+            ].map((item) =>
+              item.evaluate((element) => {
+                const bounds = element.getBoundingClientRect()
+                return Math.round(bounds.top + bounds.height / 2)
+              }),
+            ),
+          ),
+        ).size,
+    )
+    .toBe(1)
+  await expect
+    .poll(async () => {
+      const back = await settings
+        .getByRole("button", { name: "Back to projects", exact: true })
+        .evaluate((element) => element.getBoundingClientRect().top)
+      const general = await settings
+        .getByRole("tab", { name: "General", exact: true })
+        .evaluate((element) => element.getBoundingClientRect().top)
+      return Math.round(general - back)
+    })
+    .toBe(72)
+  await projectOptions.click()
+  const projectMenu = page.getByRole("menu")
+  await expect(projectMenu.getByRole("menuitem")).toHaveText(["Clear notifications", "Close"])
+  await page.keyboard.press("Escape")
+  await expect(projectMenu).toBeHidden()

  const name = settings.getByRole("textbox", { name: "Project name", exact: true })
  const saved = page.waitForRequest(
@@ -146,7 +233,8 @@ test("project settings open as a nested autosaving view", async ({ page }) => {
  await name.fill("Renamed project")
  await name.blur()
  expect((await saved).postDataJSON()).toEqual({ name: "Renamed project" })
-  await expect(settings.getByRole("tab", { name: "Renamed project", exact: true })).toBeVisible()
+  await expect(settings.getByRole("tab", { name: "General", exact: true })).toBeVisible()
+  await expect(settings.getByRole("heading", { name: "Renamed project", exact: true })).toBeVisible()

  const startup = settings.getByRole("textbox", { name: "Worktree startup script", exact: true })
  const scriptSaved = page.waitForRequest(
@@ -156,7 +244,19 @@ test("project settings open as a nested autosaving view", async ({ page }) => {
  await startup.blur()
  expect((await scriptSaved).postDataJSON()).toEqual({ commands: { start: "bun install" } })

+  const server = `http://${process.env.PLAYWRIGHT_SERVER_HOST ?? "127.0.0.1"}:${process.env.PLAYWRIGHT_SERVER_PORT ?? "4096"}`
  await settings.getByRole("tab", { name: "Worktrees", exact: true }).click()
+  await expect(settings.getByRole("heading", { name: "Worktrees", exact: true })).toBeVisible()
+  await expect(page).toHaveURL(
+    (url) =>
+      url.pathname === "/settings" &&
+      url.searchParams.get("server") === server &&
+      url.searchParams.get("project") === directory &&
+      url.searchParams.get("tab") === "workspaces",
+  )
+
+  await page.reload()
+
  await expect(settings.getByRole("heading", { name: "Worktrees", exact: true })).toBeVisible()
  await page.keyboard.press("Escape")
  await expect(settings.getByRole("heading", { name: "Projects", exact: true })).toBeVisible()
@@ -226,7 +326,7 @@ test("recording a new session shortcut stays in settings until recording finishe
  await page.keyboard.press("Control+t")

  await expect(binding).toHaveText("Ctrl+T")
-  await expect(page).toHaveURL("/settings")
+  await expect(page).toHaveURL("/settings?tab=shortcuts")
  await expect(page.locator("[data-titlebar-tab]")).toHaveCount(0)
  await page.keyboard.press("Control+t")
  await expect(page).toHaveURL(/\/new-session\?draftId=.+$/)
@@ -56,7 +56,6 @@ for (const viewport of [
        "Models",
        "Extensions",
        "Server",
-        "Experimental",
        "About",
      ]) {
        if (viewport.width >= 816) await settings.getByRole("tab", { name, exact: true }).click()
@@ -5,7 +5,7 @@ for (const colorScheme of ["light", "dark"] as const) {
  test.describe(colorScheme, () => {
    test.use({ colorScheme, contextOptions: { reducedMotion: "reduce" } })

-    test("project card edges stay inside the settings scrollport", async ({ page }, info) => {
+    test("project list actions and edges stay inside the settings scrollport", async ({ page }, info) => {
      const projects = ["rebase", "dinocms", "opencode", "Playground"].map((name, index) => ({
        id: `project-${index}`,
        name,
@@ -20,10 +20,18 @@ for (const colorScheme of ["light", "dark"] as const) {
        sessions: [],
        pageMessages: () => ({ items: [] }),
        provider: { all: [], connected: [], default: {} },
+        fileList: () => [],
      })
      await page.route("**/api/project", (route) =>
        route.fulfill({ json: projects, headers: { "access-control-allow-origin": "*" } }),
      )
+      await page.route("**/api/project/project-0", async (route) => {
+        const update = route.request().postDataJSON()
+        await route.fulfill({
+          json: { ...projects[0], ...update },
+          headers: { "access-control-allow-origin": "*" },
+        })
+      })
      await page.addInitScript((projects) => {
        localStorage.setItem(
          "opencode.global.dat:server",
@@ -40,18 +48,76 @@ for (const colorScheme of ["light", "dark"] as const) {
      const panel = settings.getByRole("tabpanel")
      await expect(panel.getByText("rebase", { exact: true })).toBeVisible()
      await expect(panel.getByText("Playground", { exact: true })).toBeVisible()
+      await expect(panel.getByRole("button", { name: "Add project", exact: true })).toBeVisible()
+      const list = panel.getByRole("list")
+      await expect(list.getByRole("listitem")).toHaveCount(4)
+      const projectButton = panel.getByRole("button", { name: "rebase", exact: true })
+      const projectCard = list.getByRole("listitem").filter({ hasText: "rebase" })
+      const projectName = projectButton.getByText("rebase", { exact: true })
+      await expect(projectName).toHaveCSS("font-weight", "530")
+      await expect(projectName).toHaveCSS("line-height", "20px")
+      await expect(projectButton.getByText("/projects/rebase", { exact: true })).toHaveCount(0)
+      await expect
+        .poll(() =>
+          list.evaluate((group) => {
+            const icons = Array.from(group.querySelectorAll('[data-component="project-avatar-v2"]'))
+            const first = icons.at(0)?.getBoundingClientRect()
+            const last = icons.at(-1)?.getBoundingClientRect()
+            const bounds = group.getBoundingClientRect()
+            if (!first || !last) return []
+            return [first.top - bounds.top, bounds.bottom - last.bottom, first.left - bounds.left]
+          }),
+        )
+        .toEqual([16, 16, 16])
+      await expect
+        .poll(() =>
+          list
+            .locator(".settings-project-row-shell")
+            .filter({ hasText: "rebase" })
+            .evaluate((row) => {
+              const group = row.parentElement
+              if (!group) return 0
+              return (
+                row.getBoundingClientRect().left -
+                group.getBoundingClientRect().left +
+                Number.parseFloat(getComputedStyle(row, "::after").insetInlineStart)
+              )
+            }),
+        )
+        .toBe(16)
+      const chevron = projectButton.locator('svg:has(use[href="#opencode-v2-icon-chevron-right"])')
+      await expect(chevron).toHaveCount(0)
+      const hoverColor = await projectCard.evaluate((element) => {
+        const probe = document.createElement("div")
+        probe.style.backgroundColor = "var(--v2-background-bg-layer-02)"
+        element.append(probe)
+        const color = getComputedStyle(probe).backgroundColor
+        probe.remove()
+        return color
+      })
+      await projectCard.hover()
+      await expect(projectCard).toHaveCSS("background-color", hoverColor)
+      const more = projectCard.getByRole("button", { name: "More options", exact: true })
+      await more.click()
+      const menu = page.getByRole("menu")
+      await expect(menu.getByRole("menuitem")).toHaveText(["Edit", "Rename", "Clear notifications", "Close"])
+      await menu.getByRole("menuitem", { name: "Close", exact: true }).hover()
+      await expect(projectCard).toHaveCSS("background-color", hoverColor)
+      await expect(menu.getByRole("separator")).toHaveCount(1)
+      await menu.getByRole("menuitem", { name: "Edit", exact: true }).click()
+      await expect(panel.getByRole("heading", { name: "rebase", exact: true })).toBeVisible()
+      await settings.getByRole("button", { name: "Back to projects", exact: true }).click()
+      await expect(panel.getByRole("heading", { name: "Projects", exact: true })).toBeVisible()
      await page.evaluate(() => document.fonts.ready)

      for (const width of [1280, 1050, 960, 720, 600]) {
        await page.setViewportSize({ width, height: 720 })
        await page.mouse.move(0, 0)
        await page.screenshot({ path: info.outputPath(`projects-${width}.png`), animations: "disabled" })
-        // Raised cards paint a half-pixel border outside their box. The scrollport
-        // must leave room for that border and the soft shadow on both sides.
+        // Each project card stays fully inside every horizontal clip ancestor.
        await expect
          .poll(() =>
-            panel.getByText("rebase", { exact: true }).evaluate((label) => {
-              const row = label.parentElement!.parentElement!
+            projectCard.evaluate((row) => {
              const bounds = row.getBoundingClientRect()
              const clips = []
              for (let parent = row.parentElement; parent; parent = parent.parentElement) {
@@ -73,11 +139,45 @@ for (const colorScheme of ["light", "dark"] as const) {
      await settings.getByRole("button", { name: "Back to projects", exact: true }).click()
      await expect(panel.getByText("rebase", { exact: true })).toBeVisible()

+      const secondProject = panel.getByRole("button", { name: "dinocms", exact: true })
+      await list
+        .getByRole("listitem")
+        .filter({ hasText: "dinocms" })
+        .getByRole("button", { name: "More options", exact: true })
+        .click()
+      await page.getByRole("menuitem", { name: "Close", exact: true }).click()
+      await expect(secondProject).toHaveCount(0)
+
      await page.setViewportSize({ width: 1280, height: 260 })
      await panel.getByText("rebase", { exact: true }).hover()
      await page.mouse.wheel(0, 400)
      await expect(panel.getByText("Playground", { exact: true })).toBeInViewport({ ratio: 1 })
      await expect(panel.getByRole("heading", { name: "Projects", exact: true })).toBeInViewport({ ratio: 1 })
+
+      await page.setViewportSize({ width: 1280, height: 720 })
+      await more.click()
+      await menu.getByRole("menuitem", { name: "Rename", exact: true }).click()
+      const rename = panel.getByRole("textbox", { name: "Rename", exact: true })
+      await expect(rename).toBeFocused()
+      await expect(rename).toHaveValue("rebase")
+      await expect(rename).toHaveCSS("border-radius", "0px")
+      await rename.fill("Renamed project")
+      const renamed = page.waitForRequest(
+        (request) => request.method() === "PATCH" && new URL(request.url()).pathname === "/api/project/project-0",
+      )
+      await rename.press("Enter")
+      expect((await renamed).postDataJSON()).toEqual({ name: "Renamed project" })
+      await expect(panel.getByRole("button", { name: "Renamed project", exact: true })).toBeVisible()
+
+      await panel.getByRole("button", { name: "Add project", exact: true }).click()
+      const picker = page.getByRole("dialog", { name: "Open project", exact: true })
+      await picker.getByRole("combobox").fill("/projects/added")
+      await picker.getByRole("combobox").press("Enter")
+      const selectFolder = picker.getByRole("button", { name: "Select folder", exact: true })
+      await expect(selectFolder).toBeEnabled()
+      await selectFolder.click()
+      await expect(picker).toBeHidden()
+      await expect(panel.getByRole("heading", { name: "added", exact: true })).toBeVisible()
    })
  })
 }
@@ -30,6 +30,19 @@ function projectList(count: number) {
  }))
 }

+async function persistProjects(page: Page, projects: ReturnType<typeof projectList>) {
+  await page.evaluate((projects) => {
+    const value = JSON.parse(localStorage.getItem("opencode.global.dat:server") ?? "{}")
+    localStorage.setItem(
+      "opencode.global.dat:server",
+      JSON.stringify({
+        ...value,
+        projects: { ...value.projects, local: projects.map((project) => ({ worktree: project.canonical })) },
+      }),
+    )
+  }, projects)
+}
+
 function ui(page: Page) {
  const settings = page.getByTestId("settings-screen")
  return {
@@ -50,6 +63,14 @@ test.use({ viewport: { width: 1280, height: 900 } })
 test.beforeEach(async ({ page }) => {
  await mockOpenCodeServer(page, config)
  await page.route("https://api.github.com/**", (route) => route.fulfill({ json: [] }))
+  await page.addInitScript((directory) => {
+    const value = JSON.parse(localStorage.getItem("opencode.global.dat:server") ?? "{}")
+    if (value.projects?.local) return
+    localStorage.setItem(
+      "opencode.global.dat:server",
+      JSON.stringify({ ...value, projects: { ...value.projects, local: [{ worktree: directory, expanded: true }] } }),
+    )
+  }, directory)
  await page.goto("/")
  if ((page.viewportSize()?.width ?? 1280) < 800) await page.getByRole("button", { name: "Tabs", exact: true }).click()
  await page.getByRole("button", { name: "Settings", exact: true }).click()
@@ -156,7 +177,7 @@ test("empty queries keep the closing quote beside the ellipsis while typing and
  await expect(status).toHaveText('No results for "zzzzzzzzzzx"')
 })

-test("Models and Shortcuts autofocus their filters on normal navigation", async ({ page }) => {
+test("Models and Shortcuts leave focus on navigation", async ({ page }) => {
  const view = ui(page)
  for (const entry of [
    { tab: "Models", search: "Search models" },
@@ -164,7 +185,7 @@ test("Models and Shortcuts autofocus their filters on normal navigation", async
    { tab: "Models", search: "Search models" },
  ]) {
    await view.settings.getByRole("tab", { name: entry.tab, exact: true }).click()
-    await expect(view.settings.getByRole("searchbox", { name: entry.search, exact: true })).toBeFocused()
+    await expect(view.settings.getByRole("searchbox", { name: entry.search, exact: true })).not.toBeFocused()
  }
  await view.search.fill("shortcuts")
  const result = view.results.getByRole("option", { name: "Keyboard shortcuts", exact: true })
@@ -172,6 +193,172 @@ test("Models and Shortcuts autofocus their filters on normal navigation", async
  await expect(result).toBeFocused()
 })

+test("Shortcuts search keeps focus while filtering", async ({ page }) => {
+  const view = ui(page)
+  await view.settings.getByRole("tab", { name: "Shortcuts", exact: true }).click()
+  const search = view.settings.getByRole("searchbox", { name: "Search shortcuts", exact: true })
+  await search.press("p")
+  await expect(search).toBeFocused()
+  await page.keyboard.type("alette")
+  await expect(search).toHaveValue("palette")
+  await expect(view.settings.getByText("Command palette", { exact: true })).toBeVisible()
+})
+
+test("section searches share controls and hierarchical Escape behavior", async ({ page }) => {
+  const projects = projectList(8)
+  await page.route("**/api/project", (route) => route.fulfill({ json: projects }))
+  await persistProjects(page, projects)
+  await page.reload()
+  const view = ui(page)
+
+  for (const [index, entry] of [
+    { tab: "Projects", label: "Search projects", query: "missing-project" },
+    { tab: "Shortcuts", label: "Search shortcuts", query: "missing-shortcut" },
+    { tab: "Models", label: "Search models", query: "missing-model" },
+  ].entries()) {
+    if (index > 0) {
+      await page.getByRole("button", { name: "Settings", exact: true }).click()
+      await expect(view.settings).toBeVisible()
+    }
+    await view.settings.getByRole("tab", { name: entry.tab, exact: true }).click()
+    const field = view.settings.locator('[data-component="settings-filter-search"]')
+    const search = field.getByRole("searchbox", { name: entry.label, exact: true })
+    await expect(field).toHaveCount(1)
+    await expect(field.locator('[data-slot="text-input-v2-leading-icon"]')).toBeVisible()
+    await expect(search).not.toBeFocused()
+
+    await page.keyboard.type(entry.query)
+    await expect(search).toBeFocused()
+    await expect(search).toHaveValue(entry.query)
+    await expect(view.settings.getByText(`No results for "${entry.query}"`, { exact: true })).toBeVisible()
+    const clear = field.getByRole("button", { name: "Clear", exact: true })
+    await expect(clear).toHaveAttribute("data-variant", "clear")
+    await clear.click()
+    await expect(search).toHaveValue("")
+    await expect(search).toBeFocused()
+
+    await search.fill(`${entry.query} `.repeat(20))
+    await search.press("End")
+    await expect(search).toHaveAttribute("data-overflow-start", "true")
+    await search.press("Home")
+    await expect(search).toHaveAttribute("data-overflow-start", "false")
+    await expect(search).toHaveAttribute("data-overflow-end", "true")
+    await search.press("Escape")
+    await expect(search).toHaveValue("")
+    await expect(search).toBeFocused()
+    await expect(view.settings).toBeVisible()
+
+    await search.press("Escape")
+    await expect(search).not.toBeFocused()
+    await expect(view.settings).toBeFocused()
+    await expect(view.settings).toBeVisible()
+
+    await page.keyboard.press("Escape")
+    await expect(view.settings).toBeHidden()
+    await expect(page).toHaveURL("/")
+  }
+})
+
+for (const count of [7, 8]) {
+  test(`Projects search uses the full list threshold with ${count} projects`, async ({ page }) => {
+    const inventory = projectList(count)
+    await page.route("**/api/project", (route) => route.fulfill({ json: inventory }))
+    await persistProjects(page, inventory)
+    await page.reload()
+    const view = ui(page)
+    await view.search.fill("OpenCode")
+    await expect(view.results.getByRole("option")).toHaveCount(count)
+    await view.search.clear()
+    await view.settings.getByRole("tab", { name: "Projects", exact: true }).click()
+    const search = view.settings.getByRole("searchbox", { name: "Search projects", exact: true })
+    const projects = view.settings.getByRole("button", { name: /^OpenCode / })
+    await expect(projects).toHaveCount(count)
+    if (count === 7) {
+      await expect(search).toHaveCount(0)
+      return
+    }
+    await expect(search).not.toBeFocused()
+    await search.fill("  CODE 06  ")
+    await expect(projects).toHaveCount(1)
+    await expect(projects).toHaveAccessibleName("OpenCode 06")
+    await expect(search).toBeVisible()
+    await search.fill("missing-project")
+    await expect(projects).toHaveCount(0)
+    await expect(view.settings.getByText('No results for "missing-project"', { exact: true })).toBeVisible()
+    await view.settings.getByRole("button", { name: "Clear", exact: true }).click()
+    await expect(search).toBeFocused()
+    await expect(projects).toHaveCount(count)
+    await view.settings.getByRole("tab", { name: "Models", exact: true }).click()
+    await view.settings.getByRole("tab", { name: "Projects", exact: true }).click()
+    await expect(search).not.toBeFocused()
+    await search.fill("OpenCode 06")
+    await projects.click()
+    await expect(view.settings.getByRole("heading", { name: "OpenCode 06", exact: true })).toBeVisible()
+  })
+}
+
+test("Projects shows an add action in its empty state", async ({ page }) => {
+  await page.route("**/api/project", (route) => route.fulfill({ json: [] }))
+  await persistProjects(page, [])
+  await page.reload()
+  const view = ui(page)
+  await view.settings.getByRole("tab", { name: "Projects", exact: true }).click()
+  await expect(view.settings.getByText("No projects yet", { exact: true })).toBeVisible()
+  await expect(view.settings.getByText("Add a project to get started", { exact: true })).toBeVisible()
+  const emptyCard = view.settings.locator('[data-component="settings-project-empty-card"]')
+  await expect(emptyCard).toHaveCSS("border-radius", "8px")
+  await expect(emptyCard).toHaveCSS("padding-top", "96px")
+  await expect(emptyCard).toHaveCSS("padding-bottom", "96px")
+  const emptyBackground = await emptyCard.evaluate((element) => {
+    const probe = document.createElement("div")
+    probe.style.background =
+      "color-mix(in oklab, var(--v2-background-bg-base) 50%, var(--v2-background-bg-layer-01))"
+    element.append(probe)
+    const color = getComputedStyle(probe).backgroundColor
+    probe.remove()
+    return color
+  })
+  await expect(emptyCard).toHaveCSS("background-color", emptyBackground)
+  const add = view.settings.getByRole("button", { name: "Add project", exact: true })
+  await expect(add).toHaveCount(1)
+  await add.click()
+  const picker = page.getByRole("dialog", { name: "Open project", exact: true })
+  await expect(picker).toBeVisible()
+  await picker.getByRole("button", { name: "Cancel", exact: true }).click()
+  await expect(picker).toBeHidden()
+})
+
+test("a single project uses the full grouped hover surface", async ({ page }) => {
+  const view = ui(page)
+  await view.settings.getByRole("tab", { name: "Projects", exact: true }).click()
+  const list = view.settings.getByRole("list")
+  const project = list.getByRole("listitem")
+  await expect(project).toHaveCount(1)
+  await expect
+    .poll(() =>
+      project.evaluate((item) => {
+        const row = item.getBoundingClientRect()
+        const group = item.parentElement?.parentElement?.getBoundingClientRect()
+        if (!group) return []
+        return [row.top - group.top, row.left - group.left, group.right - row.right, group.bottom - row.bottom]
+      }),
+    )
+    .toEqual([0, 0, 0, 0])
+})
+
+test("Projects search renders with a qualifying persisted inventory", async ({ page }) => {
+  const projects = projectList(8)
+  await page.route("**/api/project", (route) => route.fulfill({ json: projects }))
+  await persistProjects(page, projects)
+  await page.reload()
+  const view = ui(page)
+  const search = view.settings.getByRole("searchbox", { name: "Search projects", exact: true })
+  await view.settings.getByRole("tab", { name: "Projects", exact: true }).click()
+  await expect(search).toBeVisible()
+  await expect(search).not.toBeFocused()
+  await expect(view.settings.getByRole("button", { name: /^OpenCode / })).toHaveCount(8)
+})
+
 test("all indexed client controls resolve to visible production controls", async ({ page }) => {
  const view = ui(page)
  for (const entry of clientSettings.filter((entry) => entry.target && !entry.available)) {
@@ -207,11 +394,13 @@ test("qualified project results preserve query and selection on return", async (
 })

 test("returning from a project restores a scrolled result list", async ({ page }) => {
+  const projects = projectList(30)
  await page.route("**/api/project", (route) =>
    route.fulfill({
-      json: projectList(30),
+      json: projects,
    }),
  )
+  await persistProjects(page, projects)
  await page.reload()
  const view = ui(page)
  await view.search.fill("OpenCode")
@@ -313,14 +502,17 @@ test("multi-server results navigate to the named server and hide search in neste
      body: Buffer.from(await response.arrayBuffer()),
    })
  })
-  await page.addInitScript(
-    (server) =>
-      localStorage.setItem(
-        "opencode.global.dat:server",
-        JSON.stringify({ list: [{ type: "http", displayName: "Build server", http: { url: server } }] }),
-      ),
-    server,
-  )
+  await page.addInitScript((server) => {
+    const value = JSON.parse(localStorage.getItem("opencode.global.dat:server") ?? "{}")
+    localStorage.setItem(
+      "opencode.global.dat:server",
+      JSON.stringify({
+        ...value,
+        list: [{ type: "http", displayName: "Build server", http: { url: server } }],
+        projects: { ...value.projects, [server]: [{ worktree: "/remote/opencode", expanded: true }] },
+      }),
+    )
+  }, server)
  await page.reload()
  const view = ui(page)
  await view.search.fill("MCPs")
@@ -335,6 +527,13 @@ test("multi-server results navigate to the named server and hide search in neste
  await view.results.getByRole("option").click()
  await expect(view.settings.getByRole("searchbox", { name: "Search models", exact: true })).toBeFocused()
  await view.settings.getByRole("button", { name: "Back to settings", exact: true }).click()
+  await view.search.fill("Build server projects")
+  await view.results.getByRole("option").click()
+  await expect(view.settings.getByRole("heading", { name: "Projects", exact: true })).toBeVisible()
+  await expect(view.settings.getByRole("button", { name: "Add project", exact: true })).toBeVisible()
+  await expect(view.settings.getByRole("list").getByRole("listitem")).toHaveCount(1)
+  await expect(view.settings.getByRole("button", { name: "OpenCode", exact: true })).toBeVisible()
+  await view.settings.getByRole("button", { name: "Back to settings", exact: true }).click()
  await view.search.fill("Build server OpenCode name")
  await expect(view.results.getByRole("option")).toHaveCount(1)
  await view.results.getByRole("option").click()
@@ -8,8 +8,13 @@ const directory = "C:/OpenCode/SubagentNavigation"
 const projectID = "proj_subagent_navigation"
 const parentID = "ses_subagent_parent"
 const childID = "ses_subagent_child"
+const grandchildID = "ses_subagent_grandchild"
+const greatGrandchildID = "ses_subagent_great_grandchild"
 const parentTitle = "Parent session"
 const childTitle = "Subagent child session"
+const grandchildTitle = "Nested subagent session"
+const greatGrandchildTitle =
+  "Deep research subagent session investigating a very long chain of agent registry failures and navigation breadcrumbs"
 // Child session pages derive their heading from the task part that spawned them.
 const taskDescription = "Inspect child navigation"

@@ -25,6 +30,60 @@ test("navigates to a subagent child session missing from the session list", asyn
  await expect(page.getByRole("button", { name: "Toggle review", exact: true })).toBeVisible()
 })

+test("opens a directly linked nested subagent in its root session tab", async ({ page }) => {
+  await setup(page, undefined, 1)
+  await page.goto(sessionHref(grandchildID), { waitUntil: "domcontentloaded" })
+
+  await expect(page.locator('[data-slot="session-title-parent"]')).toHaveText(childTitle)
+  await expect(page.locator('[data-slot="session-title-child"]')).toHaveText(grandchildTitle)
+  const tabs = page.locator('[data-slot="titlebar-tabs"] [data-titlebar-tab-slot]')
+  await expect(tabs.locator(`a[href="${sessionHref(grandchildID)}"]`)).toHaveCount(1)
+  await expect(tabs).toHaveCount(1)
+  await expect(tabs.locator('[data-slot="tab-title"]')).toHaveText(parentTitle)
+})
+
+test("shows the full ancestor path and navigates to an earlier subagent", async ({ page }) => {
+  await setup(page, undefined, 2)
+  await page.goto(sessionHref(greatGrandchildID), { waitUntil: "domcontentloaded" })
+
+  await expect(page.locator("[data-timeline-virtual-content]")).toBeAttached()
+  const header = page.locator("[data-session-title]")
+  await expect(header.locator('[data-slot="session-title-ancestor"]')).toHaveText([parentTitle, childTitle])
+  await expect(header.locator('[data-slot="session-title-parent"]')).toHaveText(grandchildTitle)
+  await expect(header.getByRole("heading", { name: greatGrandchildTitle })).toBeVisible()
+
+  await header.getByRole("button", { name: childTitle, exact: true }).click()
+  await expect(page).toHaveURL(sessionHref(childID))
+  await expect(page.locator("[data-session-title]").getByRole("heading", { name: childTitle })).toBeVisible()
+  await expect(page.locator('[data-slot="titlebar-tabs"] [data-titlebar-tab-slot]')).toHaveCount(1)
+})
+
+test("keeps the active nested session visible in a narrow desktop header", async ({ page }) => {
+  await page.setViewportSize({ width: 820, height: 720 })
+  await setup(page, undefined, 2)
+  await page.goto(sessionHref(greatGrandchildID), { waitUntil: "domcontentloaded" })
+
+  const header = page.locator("[data-session-title]")
+  const heading = header.getByRole("heading", { name: greatGrandchildTitle })
+  const separator = header.locator('[data-slot="session-title-ancestors"] + [data-slot="session-title-separator"]')
+  await expect(header.locator('[data-slot="session-title-ancestor"]')).toHaveText([parentTitle, childTitle])
+  await expect(heading).toBeInViewport()
+  await expect(separator).toBeInViewport()
+  const bounds = await heading.boundingBox()
+  expect(bounds).not.toBeNull()
+  expect(bounds!.x + bounds!.width).toBeLessThanOrEqual(820)
+
+  await page.evaluate(() => document.documentElement.setAttribute("dir", "rtl"))
+  await expect(heading).toBeInViewport()
+  await expect(separator).toBeInViewport()
+
+  const root = header.locator(`[data-slot="session-title-ancestor"][data-session-id="${parentID}"]`)
+  await root.focus()
+  await expect(root).toBeFocused()
+  await root.press("Enter")
+  await expect(page).toHaveURL(sessionHref(parentID))
+})
+
 test("returns to the parent session with Escape", async ({ page }) => {
  await setup(page)
  await openChildFromParent(page)
@@ -144,7 +203,7 @@ test("shows the not found fallback when the viewed session is deleted", async ({
  await expect(page.getByRole("heading", { name: taskDescription })).toHaveCount(0)
 })

-async function setup(page: Page, events?: () => OpenCodeEvent[]) {
+async function setup(page: Page, events?: () => OpenCodeEvent[], nestedDepth: 0 | 1 | 2 = 0) {
  await mockOpenCodeServer(page, {
    directory,
    project: {
@@ -168,7 +227,14 @@ async function setup(page: Page, events?: () => OpenCodeEvent[]) {
      connected: ["opencode"],
      default: { providerID: "opencode", modelID: "claude-opus-4-6" },
    },
-    sessions: [session(parentID, parentTitle, 1700000000000), childSession()],
+    sessions: [
+      session(parentID, parentTitle, 1700000000000),
+      childSession(),
+      ...(nestedDepth >= 1 ? [session(grandchildID, grandchildTitle, 1700000002000, { parentID: childID })] : []),
+      ...(nestedDepth >= 2
+        ? [session(greatGrandchildID, greatGrandchildTitle, 1700000003000, { parentID: grandchildID })]
+        : []),
+    ],
    pageMessages: (sessionID) => ({ items: sessionID === parentID ? parentMessages() : [] }),
    events,
    eventRetry: events ? 16 : undefined,
@@ -154,13 +154,13 @@ test("mobile drawer exposes close controls and navigates between tabs", async ({
  }
 })

-test("vertical tabs show project details, resize, and navigate", async ({ page }) => {
+test("vertical tabs resize and navigate without retired project labels", async ({ page }) => {
  await mockServer(page)
  await page.addInitScript(
    ({ server, sessionA, sessionB }) => {
      localStorage.setItem(
        "settings.v3",
-        JSON.stringify({ appearance: { tabLayout: "vertical", showProjectName: true }, general: { showStatus: true } }),
+        JSON.stringify({ appearance: { tabLayout: "vertical" }, general: { showStatus: true } }),
      )
      localStorage.setItem(
        "opencode.window.browser.dat:tabs",
@@ -183,7 +183,7 @@ test("vertical tabs show project details, resize, and navigate", async ({ page }
  await expect(sidebar).toHaveCSS("width", "260px")
  await expect(tabA).toContainText(sessionA.title)
  await expect(tabB).toContainText(sessionB.title)
-  await expect(tabB.locator('[data-slot="tab-project"]')).toHaveText("tab-project")
+  await expect(tabB.locator('[data-slot="tab-project"]')).toHaveCount(0)
  await expect(
    sidebar.getByRole("button", { name: "Home", exact: true }).getByText("Home", { exact: true }),
  ).toBeVisible()
@@ -209,7 +209,7 @@ test("vertical tabs show project details, resize, and navigate", async ({ page }
  await page.mouse.move(box.x + box.width / 2 - 80, box.y + box.height / 2)
  await page.mouse.up()
  await expect(sidebar).toHaveCSS("width", "180px")
-  await expect(tabB.locator('[data-slot="tab-project"]')).toHaveText("tab-project")
+  await expect(tabB.locator('[data-slot="tab-project"]')).toHaveCount(0)

  const resized = await handle.boundingBox()
  if (!resized) throw new Error("resized vertical tab handle has no bounding box")
@@ -432,7 +432,7 @@ for (const profile of [
  })
 }

-test("dedicated experimental settings control vertical tab details", async ({ page }) => {
+test("preferences control vertical tab layout and hide empty experimental settings", async ({ page }) => {
  await mockServer(page)
  await page.addInitScript(
    ({ server, sessionA }) => {
@@ -452,15 +452,20 @@ test("dedicated experimental settings control vertical tab details", async ({ pa
  await expect(settings).toBeVisible()
  await expect(settings.getByRole("tablist").getByText("OpenCode Desktop", { exact: true })).toHaveCount(0)
  await expect(settings.getByRole("tablist").getByText(/^v\d+\./)).toHaveCount(0)
-  await settings.getByRole("tab", { name: "Appearance" }).click()
-  await expect(settings.getByRole("heading", { name: "Appearance", exact: true })).toBeVisible()
-  await expect(settings.locator('[data-action="settings-tab-layout"]')).toHaveCount(0)
+  await expect(settings.getByRole("heading", { name: "Preferences", exact: true })).toBeVisible()
+  await expect(settings.getByRole("tab", { name: "Experimental", exact: true })).toHaveCount(0)
  await expect(settings.getByRole("switch", { name: "Show project names", exact: true })).toHaveCount(0)
-  await settings.getByRole("tab", { name: "Experimental", exact: true }).click()
-  await expect(settings.getByRole("heading", { name: "Experimental", level: 2, exact: true })).toBeVisible()

+  const language = settings.locator('[data-action="settings-language"]')
  const layout = settings.locator('[data-action="settings-tab-layout"]')
+  await expect(language).toBeVisible()
  await expect(layout).toContainText("Horizontal")
+  await expect
+    .poll(async () => {
+      const [languageBox, layoutBox] = await Promise.all([language.boundingBox(), layout.boundingBox()])
+      return !!languageBox && !!layoutBox && layoutBox.y > languageBox.y
+    })
+    .toBe(true)
  await layout.click()
  await page.getByRole("option", { name: "Vertical" }).click()

@@ -469,42 +474,38 @@ test("dedicated experimental settings control vertical tab details", async ({ pa
  await expect(page.locator('[data-slot="titlebar-tabs"]')).toHaveCount(0)
  const projectNames = page.locator('[data-slot="vertical-tabs-sidebar"] [data-slot="tab-project"]')
  await expect(projectNames).toHaveCount(0)
-  const projectNameSwitch = settings.getByRole("switch", { name: "Show project names", exact: true })
-  await settings.locator('[data-action="settings-show-project-name"] [data-slot="switch-control"]').click()
-  await expect(projectNameSwitch).toBeChecked()
-  await expect(projectNames).toHaveText(["tab-project"])
  await expect(settings.getByRole("complementary")).toHaveCSS("width", "240px")

  await page.setViewportSize({ width: 920, height: 720 })
  await expect(page.locator('[data-slot="vertical-tabs-sidebar"]')).toHaveCSS("width", "260px")
  await expect(settings.getByRole("tablist")).toBeHidden()
-  await expect(settings.getByRole("button", { name: "Experimental", exact: true })).toBeVisible()
+  await expect(settings.getByRole("button", { name: "Preferences", exact: true })).toBeVisible()

  await page.setViewportSize({ width: 800, height: 720 })
  await expect(settings.getByRole("tablist")).toBeHidden()
-  await expect(settings.getByRole("button", { name: "Experimental", exact: true })).toBeVisible()
+  await expect(settings.getByRole("button", { name: "Preferences", exact: true })).toBeVisible()

  await page.setViewportSize({ width: 390, height: 720 })
-  await settings.getByRole("button", { name: "Experimental", exact: true }).click()
+  await settings.getByRole("button", { name: "Preferences", exact: true }).click()
+  await expect(page.getByRole("menuitemradio", { name: "Experimental", exact: true })).toHaveCount(0)
  await page.getByRole("menuitemradio", { name: "Appearance", exact: true }).click()
  await expect(settings.getByRole("heading", { name: "Appearance", exact: true })).toBeVisible()
  await expect(layout).toHaveCount(0)
  await settings.getByRole("button", { name: "Appearance", exact: true }).click()
-  await page.getByRole("menuitemradio", { name: "Experimental", exact: true }).click()
-  await expect(settings.getByRole("heading", { name: "Experimental", level: 2, exact: true })).toBeVisible()
+  await page.getByRole("menuitemradio", { name: "Preferences", exact: true }).click()
+  await expect(settings.getByRole("heading", { name: "Preferences", level: 2, exact: true })).toBeVisible()
  await expect(layout).toContainText("Vertical")
-  await expect(projectNameSwitch).toBeChecked()
  await settings.evaluate((element) => element.setAttribute("dir", "rtl"))
-  await expect(settings.getByRole("button", { name: "Experimental", exact: true })).toBeInViewport()
+  await expect(settings.getByRole("button", { name: "Preferences", exact: true })).toBeInViewport()

  await page.setViewportSize({ width: 390, height: 360 })
-  await expect(settings.getByRole("button", { name: "Experimental", exact: true })).toBeInViewport()
+  await expect(settings.getByRole("button", { name: "Preferences", exact: true })).toBeInViewport()

  // Reload the UI-selected preference without seeding settings storage.
  await page.reload()
  const href = `/server/${base64Encode(server)}/session/${sessionA.id}`
  await page.getByRole("button", { name: "Tabs", exact: true }).click()
-  await expect(page.locator('[data-slot="mobile-tabs-drawer"] [data-slot="tab-project"]')).toHaveText(["tab-project"])
+  await expect(page.locator('[data-slot="mobile-tabs-drawer"] [data-slot="tab-project"]')).toHaveCount(0)
  await expect(
    page
      .locator('[data-slot="mobile-tabs-drawer"]')
@@ -522,7 +523,7 @@ test("dedicated experimental settings control vertical tab details", async ({ pa
  ).toBeVisible()
  await expect(page.locator('[data-slot="titlebar-tabs"]')).toHaveCount(0)
  await page.keyboard.press("Control+,")
-  await settings.getByRole("tab", { name: "Experimental", exact: true }).click()
+  await expect(settings.getByRole("heading", { name: "Preferences", exact: true })).toBeVisible()
  await expect(layout).toContainText("Vertical")
 })

@@ -1,6 +1,6 @@
 {
  "name": "@opencode/app",
-  "version": "2.0.15",
+  "version": "2.0.16",
  "description": "",
  "type": "module",
  "exports": {
@@ -4,9 +4,9 @@ import { FileComponentProvider } from "@opencode/ui/context/file"
 import { Font } from "@opencode/ui/font"
 import { ThemeProvider } from "@opencode/ui/theme/context"
 import { MetaProvider } from "@solidjs/meta"
-import { type BaseRouterProps, Router, useLocation } from "@solidjs/router"
+import { type BaseRouterProps, Router } from "@solidjs/router"
 import { QueryClient, QueryClientProvider } from "@tanstack/solid-query"
-import { type Component, createRenderEffect, ErrorBoundary, type JSX, type ParentProps, Show } from "solid-js"
+import { type Component, createRenderEffect, ErrorBoundary, type JSX, type ParentProps } from "solid-js"
 import { Dynamic } from "solid-js/web"
 import { CommandProvider } from "@/shell/commands/command"
 import { DesktopCommands } from "@/shell/commands/desktop"
@@ -107,29 +107,21 @@ export function AppInterface(props: {
  // The visual layout lives in the router root so it remains mounted across
  // route changes. Draft and session routes override only their server-bound data
  // providers beneath it.
-  const Root = (rootProps: ParentProps) => {
-    const location = useLocation()
-    // Pairing saves credentials before mounting any server connections or health checks.
-    return (
-      <>
+  const Root = (rootProps: ParentProps) => (
+    <TabsProvider>
+      <GlobalProvider>
        <BodyTypography />
-        <Show when={location.pathname !== "/connect"} fallback={rootProps.children}>
-          <TabsProvider>
-            <GlobalProvider>
-              <CommandProvider>
-                <DesktopCommands />
-                <SshRestore />
-                <HighlightsProvider>
-                  {props.children}
-                  {rootProps.children}
-                </HighlightsProvider>
-              </CommandProvider>
-            </GlobalProvider>
-          </TabsProvider>
-        </Show>
-      </>
-    )
-  }
+        <CommandProvider>
+          <DesktopCommands />
+          <SshRestore />
+          <HighlightsProvider>
+            {props.children}
+            {rootProps.children}
+          </HighlightsProvider>
+        </CommandProvider>
+      </GlobalProvider>
+    </TabsProvider>
+  )

  return (
    <ServersProvider
@@ -47,6 +47,7 @@ export type ComposerDelivery = "steer" | "queue"
 // is loaded in the editor.
 export type ComposerQueue = {
  count: Accessor<number>
+  movingBack: Accessor<boolean>
  // Delivery a plain submit uses right now.
  delivery: Accessor<ComposerDelivery>
  // Delivery offered on Mod+Enter and the toolbar hint button; undefined hides the hint.
@@ -27,7 +27,10 @@ export const uploads = {
    const controller = new AbortController()
    setState("items", (items) => [...items, { ...input, loaded: 0, cancel: () => controller.abort() }])
    try {
-      return await work((loaded) => setState("items", (item) => item.id === input.id, "loaded", loaded), controller.signal)
+      return await work(
+        (loaded) => setState("items", (item) => item.id === input.id, "loaded", loaded),
+        controller.signal,
+      )
    } catch (error) {
      if (controller.signal.aborted) return undefined
      throw error
@@ -101,7 +104,7 @@ function UploadToast(props: { toastId: number; language: ReturnType<typeof useLa
                <button
                  type="button"
                  data-slot="upload-row-cancel"
-                  aria-label={props.language.t("prompt.toast.uploading.cancel")}
+                  aria-label={props.language.t("prompt.toast.uploading.cancelFile", { filename: item.filename })}
                  onClick={() => item.cancel()}
                >
                  <Icon name="outline-xmark" />
@@ -57,6 +57,8 @@ function ComposerStory(props: {
  continueOnStop?: boolean
  longLabels?: boolean
  alternate?: "queue" | "steer"
+  manySuggestions?: boolean
+  suggestionBoundary?: () => HTMLElement | undefined
 }) {
  const [draft, setDraft] = createStore<ComposerPersistedState>({
    prompt: props.prompt ?? [{ type: "text", content: "", start: 0, end: 0 }],
@@ -93,6 +95,15 @@ function ComposerStory(props: {
  const commands: ComposerSuggestion[] = [
    { id: "command.test", kind: "command", label: "/test", trigger: "test", title: "Run tests" },
    { id: "command.review", kind: "command", label: "/review", trigger: "review", title: "Review changes" },
+    ...(props.manySuggestions
+      ? Array.from({ length: 12 }, (_, index) => ({
+          id: `command.example-${index}`,
+          kind: "command" as const,
+          label: `/example-${index}`,
+          trigger: `example-${index}`,
+          title: `Run example ${index}`,
+        }))
+      : []),
  ]
  const context: ComposerSuggestion[] = [
    {
@@ -157,6 +168,7 @@ function ComposerStory(props: {
              alternate: () => props.alternate,
              editing: () => undefined,
              confirmEdit() {},
+              movingBack: () => false,
              cancelEdit() {},
              editFirst: () => false,
            }
@@ -206,7 +218,7 @@ function ComposerStory(props: {
      <output class="text-12-regular text-text-weak" aria-live="polite">
        {story.activity}
      </output>
-      <Composer model={model} borderUnderlay />
+      <Composer model={model} borderUnderlay suggestionBoundary={props.suggestionBoundary} />
    </div>
  )
 }
@@ -273,6 +285,25 @@ export const SlashSuggestions = { render: () => <ComposerStory suggestions="comm

 export const ContextSuggestions = { render: () => <ComposerStory suggestions="context" /> }

+function ConstrainedCommandSuggestionsStory() {
+  let boundary: HTMLDivElement | undefined
+  return (
+    <div class="mx-auto w-full max-w-200">
+      <div ref={boundary} data-slot="composer-suggestion-boundary-story" class="h-60" />
+      <ComposerStory suggestions="command" manySuggestions suggestionBoundary={() => boundary} />
+    </div>
+  )
+}
+
+export const ConstrainedCommandSuggestions = { render: () => <ConstrainedCommandSuggestionsStory /> }
+
+export const DetachedCommandSuggestionBoundary = {
+  render: () => {
+    const detached = document.createElement("div")
+    return <ComposerStory suggestions="command" manySuggestions suggestionBoundary={() => detached} />
+  },
+}
+
 export const RunningAndStopping = { render: () => <ComposerStory working stopping label="Session is running" /> }

 export const SteeringFollowUp = {
@@ -3,7 +3,7 @@ import { Button } from "@opencode/ui/button"
 import { useDialog } from "@opencode/ui/context/dialog"
 import { Icon } from "@opencode/ui/icon"
 import { Keybind } from "@opencode/ui/keybind"
-import { ProviderIcon } from "@opencode/ui/provider-icon"
+import { ProviderModelIcon } from "@/providers/models/provider-group"
 import { Tooltip } from "@opencode/ui/tooltip"
 import { ComposerEditor } from "./editor/editor"
 import { ModelSelectorPopover } from "@/providers/models/select-dialog"
@@ -12,7 +12,13 @@ import { formatKeybind, useCommand } from "@/shell/commands/command"
 import { useLanguage } from "@/runtime/i18n/language"
 import type { ComposerModel } from "./model"

-export function Composer(props: { class?: string; model: ComposerModel; borderUnderlay?: boolean }) {
+export function Composer(props: {
+  class?: string
+  model: ComposerModel
+  borderUnderlay?: boolean
+  readOnly?: boolean
+  suggestionBoundary?: () => HTMLElement | undefined
+}) {
  const dialog = useDialog()
  const command = useCommand()
  const language = useLanguage()
@@ -22,12 +28,14 @@ export function Composer(props: { class?: string; model: ComposerModel; borderUn
      <ComposerEditor
        controller={props.model}
        borderUnderlay={props.borderUnderlay}
+        readOnly={props.readOnly}
        class={props.class}
        modelControlsVisible={!props.model.model.loading}
        attachKeybind={command.keybindParts("file.attach")}
        attachShortcut={command.keybind("file.attach")}
        alternateKeybind={[formatKeybind("mod", language.t), "↵"]}
        exitShellKeybind={[formatKeybind("esc", language.t)]}
+        suggestionBoundary={props.suggestionBoundary}
        modelControl={
          <ComposerModelControl
            loading={props.model.model.loading}
@@ -35,7 +43,7 @@ export function Composer(props: { class?: string; model: ComposerModel; borderUn
            title={language.t("command.model.choose")}
            keybind={command.keybindParts("model.choose")}
            model={props.model.model.selection}
-            providerID={props.model.model.selection.current()?.provider?.id}
+            provider={props.model.model.selection.current()?.provider}
            modelName={props.model.model.selection.current()?.name ?? language.t("dialog.model.select.title")}
            onClose={props.model.restoreFocus}
            onUnpaidClick={() => dialog.show(() => <DialogSelectModelUnpaid model={props.model.model.selection} />)}
@@ -52,7 +60,7 @@ function ComposerModelControl(props: {
  title: string
  keybind: string[]
  model: ComposerModel["model"]["selection"]
-  providerID?: string
+  provider?: { id: string; canonical?: string; name: string }
  modelName: string
  onClose: () => void
  onUnpaidClick: () => void
@@ -60,12 +68,11 @@ function ComposerModelControl(props: {
  const shouldAnimate = createMemo<boolean>((previous) => previous ?? props.loading)
  const content = () => (
    <>
-      <Show when={props.providerID}>
-        {(providerID) => (
-          <ProviderIcon
-            id={providerID()}
-            class="size-4 shrink-0 opacity-40 group-hover:opacity-100 transition-opacity duration-150"
-            style={{ "will-change": "opacity", transform: "translateZ(0)" }}
+      <Show when={props.provider}>
+        {(provider) => (
+          <ProviderModelIcon
+            provider={provider()}
+            class="shrink-0 opacity-40 transition-opacity duration-150 group-hover:opacity-100"
          />
        )}
      </Show>
@@ -11,12 +11,13 @@ import {
  type JSX,
 } from "solid-js"
 import { createStore } from "solid-js/store"
+import { createResizeObserver } from "@solid-primitives/resize-observer"
 import { FileIcon } from "@opencode/ui/file-icon"
 import { Icon } from "@opencode/ui/icon"
 import { IconButton } from "@opencode/ui/icon-button"
 import { createAnimatedPresence } from "@/runtime/animated-presence"
 import { resolveBlobUrl } from "@/runtime/persistence/drafts"
-import { ProviderIcon } from "@opencode/ui/provider-icon"
+import { ProviderModelIcon } from "@/providers/models/provider-group"
 import { useI18n } from "@opencode/ui/context/i18n"
 import { Button } from "@opencode/ui/button"
 import { Keybind } from "@opencode/ui/keybind"
@@ -51,6 +52,12 @@ export type {
 } from "../types"

 export type ComposerMode = "normal" | "shell"
+const COMPOSER_SUGGESTION_MAX_HEIGHT = 320
+const COMPOSER_SUGGESTION_ROW_HEIGHT = 28
+const COMPOSER_SUGGESTION_ROW_PEEK = 18
+const COMPOSER_SUGGESTION_TOP_PADDING = 8
+const COMPOSER_SUGGESTION_SEARCH_HEIGHT = 28
+const COMPOSER_SUGGESTION_CONTEXT_RESERVE = 80

 export type ComposerEditorProps = {
  controller: ComposerEditorModel
@@ -64,6 +71,7 @@ export type ComposerEditorProps = {
  attachShortcut?: string
  alternateKeybind?: string[]
  exitShellKeybind?: string[]
+  suggestionBoundary?: () => HTMLElement | undefined
 }

 export function ComposerEditor(props: ComposerEditorProps) {
@@ -128,6 +136,7 @@ export function ComposerEditor(props: ComposerEditorProps) {
        <ComposerEditorPopover
          emptyLabel={i18n.t("ui.promptInput.noMatchingItems")}
          items={props.controller.suggestions()}
+          boundary={props.suggestionBoundary}
          activeID={state.popover.type === "closed" ? undefined : state.popover.activeID}
          search={
            state.popover.type === "command-menu"
@@ -533,7 +542,7 @@ export function ComposerAttachments(props: {
                <button
                  type="button"
                  onClick={() => props.onCommentRemove?.(comment)}
-                  class="absolute -top-1 -end-1 size-4 rounded-full bg-v2-icon-icon-muted outline-solid outline-1 outline-v2-icon-icon-contrast flex items-center justify-center opacity-0 group-hover:opacity-100 transition-opacity"
+                  class="absolute -top-1 -end-1 size-4 rounded-full bg-v2-icon-icon-muted outline-solid outline-1 outline-v2-icon-icon-contrast flex items-center justify-center hover-reveal group-hover:opacity-100"
                  aria-label={props.removeLabel}
                >
                  <Icon name="outline-xmark" class="text-v2-icon-icon-contrast" />
@@ -580,7 +589,7 @@ export function ComposerAttachments(props: {
                <button
                  type="button"
                  onClick={() => props.onAttachmentRemove(attachment)}
-                  class="absolute -top-1 -end-1 size-4 rounded-full bg-v2-icon-icon-muted outline-solid outline-1 outline-v2-icon-icon-contrast flex items-center justify-center opacity-0 group-hover:opacity-100 transition-opacity"
+                  class="absolute -top-1 -end-1 size-4 rounded-full bg-v2-icon-icon-muted outline-solid outline-1 outline-v2-icon-icon-contrast flex items-center justify-center hover-reveal group-hover:opacity-100"
                  aria-label={props.removeLabel}
                >
                  <Icon name="outline-xmark" class="text-v2-icon-icon-contrast" />
@@ -602,7 +611,7 @@ export function ComposerAttachments(props: {
                <button
                  type="button"
                  onClick={() => props.onUploadCancel?.(upload)}
-                  class="absolute -top-1 -end-1 size-4 rounded-full bg-v2-icon-icon-muted outline-solid outline-1 outline-v2-icon-icon-contrast flex items-center justify-center opacity-0 group-hover:opacity-100 transition-opacity"
+                  class="absolute -top-1 -end-1 size-4 rounded-full bg-v2-icon-icon-muted outline-solid outline-1 outline-v2-icon-icon-contrast flex items-center justify-center hover-reveal group-hover:opacity-100"
                  aria-label={i18n.t("ui.promptInput.cancelUpload")}
                >
                  <Icon name="outline-xmark" class="text-v2-icon-icon-contrast" />
@@ -702,7 +711,7 @@ function ComposerEditorConfiguredSelect(props: {
      current={current()}
      currentIcon={
        <Show when={props.model && providerID()}>
-          <ProviderIcon id={providerID()!} class="size-4 shrink-0 opacity-60" />
+          {(id) => <ProviderModelIcon provider={{ id: id(), name: id() }} class="shrink-0 opacity-60" />}
        </Show>
      }
      onSelect={props.control.onSelect}
@@ -775,18 +784,31 @@ export function ComposerEditorPopover(props: {
    onValueChange: (value: string) => void
    onKeyDown: (event: KeyboardEvent) => void
  }
+  boundary?: () => HTMLElement | undefined
  onActiveChange: (item: ComposerSuggestion) => void
  onSelect: (item: ComposerSuggestion) => void
 }) {
+  const [store, setStore] = createStore({ maxHeight: COMPOSER_SUGGESTION_MAX_HEIGHT })
+  const resize = (height: number) =>
+    setStore("maxHeight", composerSuggestionMaxHeight(height, props.search !== undefined))
+  // A detached boundary (e.g. the previous session's timeline while the next one loads) measures 0px.
+  const boundary = () => {
+    const element = props.boundary?.()
+    return element?.isConnected ? element : undefined
+  }
+  createEffect(() => resize(boundary()?.clientHeight ?? COMPOSER_SUGGESTION_MAX_HEIGHT * 2))
+  createResizeObserver(boundary, (rect) => resize(rect.height))
+
  return (
    <div
      data-component="composer-suggestions"
-      class="absolute inset-x-0 -top-2 z-40 flex max-h-80 -translate-y-full flex-col overflow-auto rounded-xl bg-v2-background-bg-base p-2 shadow-[var(--v2-elevation-raised)] no-scrollbar"
+      class="absolute inset-x-0 -top-2 z-40 flex -translate-y-full scroll-pb-[18px] flex-col overflow-auto rounded-xl bg-v2-background-bg-base p-2 shadow-[var(--v2-elevation-raised)] no-scrollbar"
+      style={{ "max-height": `${store.maxHeight}px` }}
      onMouseDown={(event) => event.preventDefault()}
    >
      <Show when={props.search}>
        {(search) => (
-          <div class="px-2 py-1">
+          <div class="shrink-0 px-2 py-1">
            <input
              ref={(element) => requestAnimationFrame(() => element.focus())}
              value={search().value}
@@ -810,7 +832,7 @@ export function ComposerEditorPopover(props: {
              type="button"
              data-suggestion-id={item.id}
              data-active={props.activeID === item.id ? "" : undefined}
-              class="flex w-full items-center gap-2 rounded-md px-2 py-1 text-start hover:bg-v2-overlay-simple-overlay-hover"
+              class="flex h-7 w-full shrink-0 items-center gap-2 rounded-md px-2 py-1 text-start hover:bg-v2-overlay-simple-overlay-hover"
              classList={{ "bg-v2-overlay-simple-overlay-hover": props.activeID === item.id }}
              onPointerMove={() => props.onActiveChange(item)}
              onClick={() => props.onSelect(item)}
@@ -835,6 +857,19 @@ export function ComposerEditorPopover(props: {
  )
 }

+function composerSuggestionMaxHeight(boundaryHeight: number, search: boolean) {
+  const reserve = Math.min(COMPOSER_SUGGESTION_CONTEXT_RESERVE, boundaryHeight / 4)
+  const limit = Math.min(COMPOSER_SUGGESTION_MAX_HEIGHT, boundaryHeight - reserve)
+  const chrome = COMPOSER_SUGGESTION_TOP_PADDING + (search ? COMPOSER_SUGGESTION_SEARCH_HEIGHT : 0)
+  if (limit < chrome + COMPOSER_SUGGESTION_ROW_HEIGHT + COMPOSER_SUGGESTION_ROW_PEEK) return limit
+  return (
+    chrome +
+    Math.floor((limit - chrome - COMPOSER_SUGGESTION_ROW_PEEK) / COMPOSER_SUGGESTION_ROW_HEIGHT) *
+      COMPOSER_SUGGESTION_ROW_HEIGHT +
+    COMPOSER_SUGGESTION_ROW_PEEK
+  )
+}
+
 // "Steer ⌘⏎" / "Queue ⌘⏎" hint next to the submit button: submits with the
 // delivery opposite to what plain Enter does. Visible only while the queue
 // exposes an alternate (turn running and composer holding a value), so it
@@ -371,6 +371,7 @@ export function createComposerModel(adapter: ComposerAdapter, options?: { queue?
        onSubmit: (submitOptions) => {
          if (!available()) return
          const queue = options?.queue
+          if (queue?.movingBack()) return
          // Confirming an edit re-admits the queued prompt instead of sending
          // the composer value as a new prompt. Enter keeps it queued in
          // place; the alternate action sends it as a steer.
@@ -5,6 +5,8 @@ import { useTabs } from "@/shell/tabs/tabs"
 import { toggleHomeProjectSelection } from "@/shell/layout/helpers"
 import { createEffect, createMemo, startTransition } from "solid-js"
 import type { SessionInfo } from "@opencode/client/promise"
+import { pathKey } from "@/workspaces/path-key"
+import { addProjects } from "./projects/add"

 export function createHomeController() {
  const layout = useLayout()
@@ -41,6 +43,24 @@ export function createHomeController() {
    // Selecting a project is the demand for its worktree inventory: the session filter spans its worktrees.
    void ctx.sync.worktrees.list(id).then(() => ctx.sync.worktrees.refresh(id))
  })
+  createEffect(() => {
+    // The project list is empty until the server store hydrates; clearing the restored
+    // selection against it would persist the loss.
+    if (!servers.hydrated()) return
+    const current = selection()
+    const directory = current.directory
+    if (!directory) return
+    const conn = servers.visible.find((conn) => ServerConnection.key(conn) === current.server)
+    if (!conn) return
+    if (
+      global
+        .ensureServerCtx(conn)
+        .projects.list()
+        .some((project) => pathKey(project.worktree) === pathKey(directory))
+    )
+      return
+    setSelection({ server: current.server })
+  })

  function setSelection(next: HomeProjectSelection) {
    layout.home.setSelection(next)
@@ -99,23 +119,8 @@ export function createHomeController() {
        setSelection(toggleHomeProjectSelection(selection(), key, directory))
      },
      add: (conn: ServerConnection.Any, directories: string[]) => {
-        const directory = directories[0]
+        const directory = addProjects(global.ensureServerCtx(conn), directories)
        if (!directory) return
-        const ctx = global.ensureServerCtx(conn)
-        directories.forEach((item) => {
-          if (ctx.projects.list().some((project) => project.worktree === item)) return
-          const location = { directory: item }
-          void ctx.sdk.api.file
-            .list({ path: ".", location })
-            .then(async (files) => {
-              // TODO: Initialize empty directories when V2 exposes a native Git init API.
-              return ctx.sdk.api.location.get({ location }).then((result) => result.project)
-            })
-            .then((project) => ctx.sync.child(item, { bootstrap: false })[1]("project", project.id))
-            .catch(() => undefined)
-          ctx.projects.open(item)
-        })
-        ctx.projects.touch(directory)
        setSelection({ server: ServerConnection.key(conn), directory })
      },
      openNewSession: () => {
@@ -0,0 +1,19 @@
+import type { ServerCtx } from "@/runtime/server/runtime"
+
+export function addProjects(context: ServerCtx, directories: string[]) {
+  const directory = directories[0]
+  if (!directory) return
+
+  directories.forEach((item) => {
+    if (context.projects.list().some((project) => project.worktree === item)) return
+    const location = { directory: item }
+    void context.sdk.api.file
+      .list({ path: ".", location })
+      .then(() => context.sdk.api.location.get({ location }))
+      .then((value) => context.sync.child(item, { bootstrap: false })[1]("project", value.project.id))
+      .catch(() => undefined)
+    context.projects.open(item)
+  })
+  context.projects.touch(directory)
+  return directory
+}
@@ -17,6 +17,7 @@ import type { HomeController } from "../model"
 import { useGlobal } from "@/runtime/server/runtime"
 import { SessionTransfer } from "@opencode/schema/session-transfer"
 import { useSshAuthenticate } from "@/servers/ssh/authenticate"
+import { useRevealProject } from "./reveal"

 export const HomeServersSchema = Schema.Struct({
  collapsed: Persistence.record(Persistence.fallback(Schema.Boolean, () => false)),
@@ -32,6 +33,7 @@ export function createHomeProjectsController(home: HomeController) {
  const serverManagement = useServerActionsController()
  const global = useGlobal()
  const authenticate = useSshAuthenticate()
+  const revealProject = useRevealProject()
  const [_state, setState, _, ready] = persisted(Persist.global("home.servers"), HomeServersSchema, { collapsed: {} })
  const [state] = createResource(
    () => ready.promise ?? Promise.resolve(),
@@ -42,10 +44,6 @@ export function createHomeProjectsController(home: HomeController) {
    return [project.worktree, ...(project.sandboxes ?? [])]
  }

-  function canRevealProject(conn: ServerConnection.Any) {
-    return platform.platform === "desktop" && !!platform.openPath && ServerConnection.local(conn)
-  }
-
  function choose(conn: ServerConnection.Any) {
    pickDirectory({
      server: conn,
@@ -165,16 +163,8 @@ export function createHomeProjectsController(home: HomeController) {
      move: (conn: ServerConnection.Any, worktree: string, index: number) => {
        home.server.context(conn).projects.move(worktree, index)
      },
-      canReveal: canRevealProject,
-      reveal: (conn: ServerConnection.Any, project: LocalProject) => {
-        if (!platform.openPath || !canRevealProject(conn)) return
-        platform.openPath(project.worktree).catch((cause: unknown) =>
-          showToast({
-            title: language.t("common.requestFailed"),
-            description: errorMessage(cause, language.t("common.requestFailed")),
-          }),
-        )
-      },
+      canReveal: revealProject.available,
+      reveal: revealProject.reveal,
    },
    utility: {
      settings: openSettings,
@@ -0,0 +1,36 @@
+import { useLanguage } from "@/runtime/i18n/language"
+import { usePlatform } from "@/runtime/platform/platform"
+import { ServerConnection } from "@/runtime/server/registry"
+import { displayName, errorMessage } from "@/shell/layout/helpers"
+import type { LocalProject } from "@/shell/state/layout"
+import { showToast } from "@/shell/notifications/toast"
+
+export function useRevealProject() {
+  const language = useLanguage()
+  const platform = usePlatform()
+  const available = (conn: ServerConnection.Any) =>
+    platform.platform === "desktop" && !!platform.revealPath && ServerConnection.local(conn)
+
+  return {
+    available,
+    reveal(conn: ServerConnection.Any, project: LocalProject) {
+      if (!platform.revealPath || !available(conn)) return
+      void platform
+        .revealPath(project.worktree)
+        .then((revealed) => {
+          if (revealed) return
+          showToast({
+            variant: "error",
+            title: language.t("home.project.missing.title"),
+            description: language.t("home.project.missing.description", { name: displayName(project) }),
+          })
+        })
+        .catch((cause: unknown) =>
+          showToast({
+            title: language.t("common.requestFailed"),
+            description: errorMessage(cause, language.t("common.requestFailed")),
+          }),
+        )
+    },
+  }
+}
@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test"
+import { createRoot } from "solid-js"
+import { createAltHold } from "./alt-hold"
+
+describe("createAltHold", () => {
+  test("is active only while Alt is held and resets on blur", () => {
+    let active = () => false
+    let presses = 0
+    const dispose = createRoot((dispose) => {
+      active = createAltHold(true, () => presses++)
+      return dispose
+    })
+
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Alt" }))
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Alt", repeat: true }))
+    expect(active()).toBe(true)
+    expect(presses).toBe(1)
+
+    window.dispatchEvent(new KeyboardEvent("keyup", { key: "Alt" }))
+    expect(active()).toBe(false)
+
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Alt" }))
+    window.dispatchEvent(new Event("blur"))
+    expect(active()).toBe(false)
+    expect(presses).toBe(2)
+    dispose()
+  })
+
+  test("does nothing outside Desktop", () => {
+    let presses = 0
+    const active = createRoot((dispose) => {
+      const value = createAltHold(false, () => presses++)
+      dispose()
+      return value
+    })
+
+    window.dispatchEvent(new KeyboardEvent("keydown", { key: "Alt" }))
+    expect(active()).toBe(false)
+    expect(presses).toBe(0)
+  })
+})
@@ -0,0 +1,19 @@
+import { makeEventListener } from "@solid-primitives/event-listener"
+import { createStore } from "solid-js/store"
+
+export function createAltHold(enabled: boolean, onPress: () => void) {
+  const [state, setState] = createStore({ active: false })
+  if (!enabled) return () => false
+
+  makeEventListener(window, "keydown", (event) => {
+    if (event.key !== "Alt" || state.active) return
+    setState("active", true)
+    onPress()
+  })
+  makeEventListener(window, "keyup", (event) => {
+    if (event.key === "Alt") setState("active", false)
+  })
+  makeEventListener(window, "blur", () => setState("active", false))
+
+  return () => state.active
+}
@@ -26,7 +26,7 @@ import { sessionLabel, sessionTitle } from "@/session/title"
 import { showToast } from "@/shell/notifications/toast"
 import { archiveHomeSession } from "./archive"
 import type { HomeController } from "../model"
-import { buildHomeSessionRecords, homeProjectForSession, type HomeSessionRecord } from "./records"
+import { buildHomeSessionRecords, homeProjectForSession, homeSessionLocation, type HomeSessionRecord } from "./records"

 export type { HomeSessionRecord } from "./records"

@@ -92,6 +92,25 @@ export function createHomeSessionsController(home: HomeController) {
  const groups = createMemo(() => groupSessions(records(), language))
  const prefetched = new Set<string>()

+  const location = (record: HomeSessionRecord) => {
+    const branch = home.server.focusedContext()?.data.location.vcs.info(record.session.location)?.branch.current
+    return homeSessionLocation(record.session.location.directory, branch)
+  }
+
+  const syncLocations = (record?: HomeSessionRecord) => {
+    if (platform.platform !== "desktop") return
+    const ctx = home.server.focusedContext()
+    if (!ctx) return
+    if (record) {
+      void ctx.data.location.vcs.sync(record.session.location).catch(() => undefined)
+      return
+    }
+    const locations = new Map(
+      records().map((record) => [pathKey(record.session.location.directory), record.session.location] as const),
+    )
+    void Promise.allSettled(Array.from(locations.values(), (location) => ctx.data.location.vcs.sync(location)))
+  }
+
  createEffect(() => {
    const ctx = home.server.focusedContext()
    const conn = home.server.focused()
@@ -252,6 +271,13 @@ export function createHomeSessionsController(home: HomeController) {
      loading: () => sessionLoad.isPending,
      searchRecords: allRecords,
    },
+    platform: {
+      desktop: platform.platform === "desktop",
+    },
+    location: {
+      value: location,
+      sync: syncLocations,
+    },
    session: {
      showProjectName: () => !home.project.selected(),
      server: () => home.selection.value().server,
@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test"
 import type { SessionInfo } from "@opencode/client/promise"
 import type { LocalProject } from "@/shell/state/layout"
-import { buildHomeSessionRecords } from "./records"
+import { buildHomeSessionRecords, homeSessionLocation } from "./records"

 const session = (id: string, directory: string, projectID: string) =>
  ({
@@ -59,3 +59,19 @@ describe("buildHomeSessionRecords", () => {
    expect(records[0]?.project.worktree).toBe("/repo/a/packages/app")
  })
 })
+
+describe("homeSessionLocation", () => {
+  test("returns the worktree directory name and branch", () => {
+    expect(homeSessionLocation("/repo/.worktrees/crisp-cactus", "feature/home")).toEqual({
+      worktree: "crisp-cactus",
+      branch: "feature/home",
+    })
+  })
+
+  test("uses the worktree name while branch metadata is unavailable", () => {
+    expect(homeSessionLocation("/repo/.worktrees/crisp-cactus")).toEqual({
+      worktree: "crisp-cactus",
+      branch: undefined,
+    })
+  })
+})
@@ -2,6 +2,7 @@ import type { SessionInfo } from "@opencode/client/promise"
 import type { LocalProject } from "@/shell/state/layout"
 import { compareSessionTime, displayName } from "@/shell/layout/helpers"
 import { pathKey } from "@/workspaces/path-key"
+import { getFilename } from "@opencode/util/path"

 export type HomeSessionRecord = {
  session: SessionInfo
@@ -9,6 +10,10 @@ export type HomeSessionRecord = {
  projectName: string
 }

+export function homeSessionLocation(directory: string, branch?: string) {
+  return { worktree: getFilename(directory) || directory, branch }
+}
+
 export function buildHomeSessionRecords(input: {
  sessions: () => SessionInfo[]
  projectDirectories: () => string[] | undefined
@@ -16,6 +16,9 @@ export function HomeSessions(props: {
          language={props.sessions.copy.language}
          groups={props.sessions.data.groups()}
          loading={props.sessions.data.loading()}
+          desktop={props.sessions.platform.desktop}
+          location={props.sessions.location.value}
+          onRevealLocations={props.sessions.location.sync}
          showProjectName={props.sessions.session.showProjectName()}
          server={server()}
          canCreateSession={props.sessions.session.canCreate()}
@@ -15,6 +15,7 @@ import { ServerConnection } from "@/runtime/server/registry"
 import { SessionTabAvatarView } from "@/shell/layout/session-tab-avatar"
 import { sessionLabel } from "@/session/title"
 import { shouldOpenSessionInBackground } from "./open"
+import { createAltHold } from "./alt-hold"
 import "./view.css"
 import {
  HomeSessionStatusController,
@@ -46,6 +47,9 @@ export type HomeSessionsViewProps = {
  language: ReturnType<typeof useLanguage>
  groups: HomeSessionGroup[]
  loading: boolean
+  desktop: boolean
+  location: (record: HomeSessionRecord) => { worktree: string; branch: string | undefined }
+  onRevealLocations: (record?: HomeSessionRecord) => void
  showProjectName: boolean
  server: ServerConnection.Key
  canCreateSession: boolean
@@ -91,6 +95,8 @@ type HomeSessionRowUI = {

 export function HomeSessionsView(props: HomeSessionsViewProps) {
  const [rowUI, setRowUI] = createStore<HomeSessionRowUI>({ menu: undefined, editor: undefined })
+  const [hover, setHover] = createStore<{ sessionID: string | undefined }>({ sessionID: undefined })
+  const showLocations = createAltHold(props.desktop, props.onRevealLocations)
  return (
    <section
      ref={props.onSetHoverTarget}
@@ -101,7 +107,12 @@ export function HomeSessionsView(props: HomeSessionsViewProps) {
        class="sticky top-0 z-30 shrink-0 bg-v2-background-bg-base pb-1 pt-6 md:pb-3 lg:pt-12"
        onWheel={props.onWheel}
      >
-        <HomeSessionSearch {...props} />
+        <HomeSessionSearch
+          {...props}
+          showLocations={showLocations()}
+          hoveredSession={hover.sessionID}
+          onHoverSession={(sessionID) => setHover("sessionID", sessionID)}
+        />
        <Show when={props.groups.length > 0 && props.canCreateSession}>
          <div class="pointer-events-none absolute right-0 top-[68px] z-20 flex md:top-[84px] lg:top-[108px]">
            <Button
@@ -162,7 +173,17 @@ export function HomeSessionsView(props: HomeSessionsViewProps) {
                          rows would be disposed mid-interaction whenever a
                          sync response lands. */}
                      <Key each={group().sessions} by={(record) => record.session.id}>
-                        {(record) => <HomeSessionRow {...props} record={record()} rowUI={rowUI} setRowUI={setRowUI} />}
+                        {(record) => (
+                          <HomeSessionRow
+                            {...props}
+                            record={record()}
+                            rowUI={rowUI}
+                            setRowUI={setRowUI}
+                            showLocations={showLocations()}
+                            hoveredSession={hover.sessionID}
+                            onHoverSession={(sessionID) => setHover("sessionID", sessionID)}
+                          />
+                        )}
                      </Key>
                    </div>
                  </>
@@ -198,12 +219,7 @@ function HomeSessionLeadingController(props: {
  )
 }

-function HomeSessionLeading(props: {
-  record: HomeSessionRecord
-  open: boolean
-  unread: boolean
-  loading: boolean
-}) {
+function HomeSessionLeading(props: { record: HomeSessionRecord; open: boolean; unread: boolean; loading: boolean }) {
  return (
    <div class="relative shrink-0">
      <Show when={props.open}>
@@ -226,7 +242,13 @@ function HomeSessionLeading(props: {
  )
 }

-function HomeSessionSearch(props: HomeSessionsViewProps) {
+function HomeSessionSearch(
+  props: HomeSessionsViewProps & {
+    showLocations: boolean
+    hoveredSession: string | undefined
+    onHoverSession: (sessionID: string | undefined) => void
+  },
+) {
  return (
    <div class="w-full">
      <div ref={props.onSetSearchRoot} data-component="home-session-search" class="relative z-30 w-full">
@@ -369,9 +391,13 @@ function HomeSessionSearchResultRow(
  props: HomeSessionsViewProps & {
    record: HomeSessionRecord
    selected: boolean
+    showLocations: boolean
+    hoveredSession: string | undefined
+    onHoverSession: (sessionID: string | undefined) => void
  },
 ) {
  const title = createMemo(() => sessionLabel(props.record.session))
+  const location = createMemo(() => props.location(props.record))
  const showProjectName = () => props.showProjectName && props.record.projectName
  const key = () => homeSessionSearchKey(props.record)

@@ -385,14 +411,21 @@ function HomeSessionSearchResultRow(
      role="option"
      aria-selected={props.selected}
      class={`
-        flex h-10 w-full shrink-0 cursor-default items-center gap-2 border-0 py-3 pl-[18px] pr-6 text-left
+        flex h-10 w-full shrink-0 cursor-default items-center border-0 py-3 pl-[18px] pr-6 text-left
        transition-[background-color] duration-[120ms] ease-in-out
        hover:bg-v2-overlay-simple-overlay-hover focus-visible:bg-v2-overlay-simple-overlay-hover focus-visible:outline-none
      `}
      classList={{
        "bg-v2-overlay-simple-overlay-hover": props.selected,
+        "gap-1.5": props.desktop,
+        "gap-2": !props.desktop,
      }}
-      onMouseEnter={() => props.onSearchHighlight(props.record)}
+      onMouseEnter={() => {
+        props.onSearchHighlight(props.record)
+        props.onHoverSession(props.record.session.id)
+        props.onRevealLocations(props.record)
+      }}
+      onMouseLeave={() => props.onHoverSession(undefined)}
      onMouseDown={(event) => {
        if (event.button === 1) event.preventDefault()
      }}
@@ -403,16 +436,22 @@ function HomeSessionSearchResultRow(
        props.onSearchSelect(props.record, { background: true })
      }}
    >
-      <HomeSessionLeadingController
-        server={props.server}
-        isOpenTab={props.isOpenTab}
-        record={props.record}
-      />
+      <HomeSessionLeadingController server={props.server} isOpenTab={props.isOpenTab} record={props.record} />
      <div data-slot="home-session-labels" class="flex min-w-0 flex-1 items-center gap-1.5">
        <HomeSessionTitle title={title()} showProjectName={!!showProjectName()} search />
        <Show when={showProjectName()}>
-          <HomeSessionProjectName name={props.record.projectName} search />
+          <HomeSessionProjectName name={props.record.projectName} trailing={props.desktop} search />
        </Show>
+        <HomeSessionLocation
+          location={location()}
+          show={props.showLocations || props.hoveredSession === props.record.session.id}
+          instantHide={
+            !props.showLocations &&
+            props.hoveredSession !== undefined &&
+            props.hoveredSession !== props.record.session.id
+          }
+          desktop={props.desktop}
+        />
      </div>
    </button>
  )
@@ -445,9 +484,13 @@ function HomeSessionRow(
    record: HomeSessionRecord
    rowUI: HomeSessionRowUI
    setRowUI: SetStoreFunction<HomeSessionRowUI>
+    showLocations: boolean
+    hoveredSession: string | undefined
+    onHoverSession: (sessionID: string | undefined) => void
  },
 ) {
  const title = createMemo(() => sessionLabel(props.record.session))
+  const location = createMemo(() => props.location(props.record))
  const showProjectName = () => props.showProjectName && props.record.projectName
  const sessionID = () => props.record.session.id
  const menu = () => (props.rowUI.menu?.id === sessionID() ? props.rowUI.menu : undefined)
@@ -530,13 +573,10 @@ function HomeSessionRow(
        fallback={
          <div
            data-slot="home-session-editor"
-            class="flex h-10 min-w-0 w-full flex-1 items-center gap-2 py-3 ps-1.5 pe-3 md:ps-3 md:pe-10"
+            class="flex h-10 min-w-0 w-full flex-1 items-center py-3 ps-1.5 pe-3 md:ps-3 md:pe-10"
+            classList={{ "gap-1.5": props.desktop, "gap-2": !props.desktop }}
          >
-            <HomeSessionLeadingController
-              server={props.server}
-              isOpenTab={props.isOpenTab}
-              record={props.record}
-            />
+            <HomeSessionLeadingController server={props.server} isOpenTab={props.isOpenTab} record={props.record} />
            <div data-slot="home-session-labels" class="contents">
              <InlineInput
                data-component="home-session-rename"
@@ -547,7 +587,7 @@ function HomeSessionRow(
                class={`
                block min-w-0 overflow-hidden text-ellipsis whitespace-nowrap text-v2-text-text-base
                [font-weight:530] field-sizing-content outline-none focus:outline-none focus-visible:outline-none
-                ${showProjectName() ? "max-w-[min(70%,480px)] flex-[0_1_auto]" : "flex-[1_1_auto]"}
+                 ${showProjectName() ? "max-w-[min(70%,480px)] flex-[0_1_auto]" : "flex-[1_1_auto]"}
              `}
                style={{ "--inline-input-shadow": "none", "text-align": "start" }}
                onInput={(event) => {
@@ -586,14 +626,20 @@ function HomeSessionRow(
          aria-haspopup="menu"
          aria-expanded={!!menu()}
          class={`
-            flex h-10 min-w-0 w-full flex-1 shrink-0 cursor-default items-center gap-2 rounded-[6px] border-0
+            flex h-10 min-w-0 w-full flex-1 shrink-0 cursor-default items-center rounded-[6px] border-0
            bg-transparent py-3 ps-1.5 pe-3 md:ps-3 md:pe-10 text-start text-v2-text-text-muted [font-weight:530]
            transition-[background-color,color,box-shadow] duration-[120ms] ease-in-out
            hover:bg-v2-overlay-simple-overlay-hover focus-visible:bg-v2-overlay-simple-overlay-hover focus-visible:outline-none
          `}
+          classList={{ "gap-1.5": props.desktop, "gap-2": !props.desktop }}
          onMouseDown={(event) => {
            if (event.button === 1) event.preventDefault()
          }}
+          onMouseEnter={() => {
+            props.onHoverSession(props.record.session.id)
+            props.onRevealLocations(props.record)
+          }}
+          onMouseLeave={() => props.onHoverSession(undefined)}
          onPointerDown={(event) => {
            suppressClick = false
            if (event.pointerType !== "touch") return
@@ -644,16 +690,26 @@ function HomeSessionRow(
            props.onOpenSession(props.record.session, { background: true })
          }}
        >
-          <HomeSessionLeadingController
-            server={props.server}
-            isOpenTab={props.isOpenTab}
-            record={props.record}
-          />
-          <div data-slot="home-session-labels" class="contents">
+          <HomeSessionLeadingController server={props.server} isOpenTab={props.isOpenTab} record={props.record} />
+          <div
+            data-slot="home-session-labels"
+            class="min-w-0 flex-1 items-center gap-1.5"
+            classList={{ flex: props.desktop, contents: !props.desktop }}
+          >
            <HomeSessionTitle title={title()} showProjectName={!!showProjectName()} />
            <Show when={showProjectName()}>
-              <HomeSessionProjectName name={props.record.projectName} />
+              <HomeSessionProjectName name={props.record.projectName} trailing={props.desktop} />
            </Show>
+            <HomeSessionLocation
+              location={location()}
+              show={props.showLocations || props.hoveredSession === props.record.session.id}
+              instantHide={
+                !props.showLocations &&
+                props.hoveredSession !== undefined &&
+                props.hoveredSession !== props.record.session.id
+              }
+              desktop={props.desktop}
+            />
          </div>
        </button>
      </Show>
@@ -746,13 +802,50 @@ function HomeSessionTitle(props: { title: string; showProjectName: boolean; sear
  )
 }

-function HomeSessionProjectName(props: { name: string; search?: boolean }) {
+function HomeSessionLocation(props: {
+  location: { worktree: string; branch: string | undefined }
+  show: boolean
+  instantHide: boolean
+  desktop: boolean
+}) {
+  if (!props.desktop) return null
+  return (
+    <span
+      dir="ltr"
+      aria-hidden={!props.show || undefined}
+      class="flex min-w-0 shrink-0 items-center gap-1.5 overflow-hidden whitespace-nowrap ease-out motion-reduce:transition-none"
+      classList={{
+        "-ms-1.5 max-w-0 opacity-0": !props.show,
+        "max-w-[60%] opacity-100": props.show,
+        "transition-[max-width,opacity] duration-[120ms]": !props.instantHide,
+        "transition-none": props.instantHide,
+      }}
+    >
+      <Icon name="outline-worktree" class="shrink-0 text-v2-icon-icon-muted" />
+      <span class="min-w-0 overflow-hidden text-ellipsis [font-weight:440]">{props.location.worktree}</span>
+      <Show when={props.location.branch}>
+        {(branch) => (
+          <>
+            <Icon name="branch" class="shrink-0 text-v2-icon-icon-muted" />
+            <span class="min-w-0 overflow-hidden text-ellipsis [font-weight:440]">{branch()}</span>
+          </>
+        )}
+      </Show>
+    </span>
+  )
+}
+
+function HomeSessionProjectName(props: { name: string; search?: boolean; trailing?: boolean }) {
  return (
    <span
      data-component="home-session-project-name"
      dir="auto"
-      class="min-w-0 flex-[1_1_auto] overflow-hidden text-ellipsis whitespace-nowrap text-v2-text-text-muted [font-weight:440]"
-      classList={{ "text-[13px] leading-4 tracking-[-0.04px]": !!props.search }}
+      class="min-w-0 overflow-hidden text-ellipsis whitespace-nowrap text-v2-text-text-muted [font-weight:440]"
+      classList={{
+        "flex-[0_1_auto]": !!props.trailing,
+        "flex-[1_1_auto]": !props.trailing,
+        "text-[13px] leading-4 tracking-[-0.04px]": !!props.search,
+      }}
    >
      {props.name}
    </span>
@@ -38,57 +38,6 @@
 }

@layer components {
-  [data-slot="session-chat-panel"] {
-    container-name: session-chat;
-  }
-
-  [data-component="new-session"] {
-    container-type: inline-size;
-    container-name: new-session;
-  }
-
-  [data-slot="session-chat-panel"]
-    :is([data-timeline-virtual-content], [data-component="session-composer-dock"] > div),
-  [data-slot="new-session-content"] {
-    translate: var(--session-summary-resize-translate, var(--session-summary-translate, none));
-    transition: translate 240ms cubic-bezier(0.4, 0, 0.2, 1);
-
-    @media (prefers-reduced-motion: reduce) {
-      transition: none;
-    }
-  }
-
-  [data-slot="session-chat-panel"][data-summary-resizing="true"]
-    :is([data-timeline-virtual-content], [data-component="session-composer-dock"] > div),
-  [data-component="new-session"][data-summary-resizing="true"] [data-slot="new-session-content"] {
-    transition: none;
-  }
-
-  /* Keep the 1000px conversation intact, with 320px for the summary and its gutters.
-     When they overlap, center the conversation in the space that remains beside the summary. */
-  @container session-chat (min-width: 1320px) and (width < 1640px) {
-    [data-slot="session-chat-panel"][data-summary-open="true"]
-      :is([data-timeline-virtual-content], [data-component="session-composer-dock"] > div) {
-      --session-summary-translate: -160px;
-
-      &:dir(rtl) {
-        --session-summary-translate: 160px;
-      }
-    }
-  }
-
-  /* Shift only while centered content overlaps the 280px summary cards and their 16px edge inset:
-     880px + 2 * (280px + 16px) = 1472px. Center it in the remaining space, reserving 320px. */
-  @container new-session (min-width: 1200px) and (width < 1472px) {
-    [data-component="new-session"][data-summary-open="true"] [data-slot="new-session-content"] {
-      --session-summary-translate: -160px;
-
-      &:dir(rtl) {
-        --session-summary-translate: 160px;
-      }
-    }
-  }
-
  [data-slot="session-chat-panel"][data-scrollbar-hidden="true"]
    [data-slot="session-timeline-scroll"]
    > .scroll-view__thumb {
@@ -88,7 +88,7 @@ export default function NewSessionPage(props: { draftId: string }) {
    <div class="relative size-full overflow-hidden flex flex-col">
      {suspendUntilPromptReady()}
      <div class="flex-1 min-h-0 flex flex-col gap-2 px-2 pb-[var(--shell-bottom-inset,8px)] pt-[var(--shell-top-inset,8px)]">
-        <NewSessionView composer={model} project={project} workspace={workspace} mcp={mcp} />
+        <NewSessionView composer={model} project={project} workspace={workspace} />
      </div>
    </div>
  )
@@ -1,64 +0,0 @@
-import { Icon } from "@opencode/ui/icon"
-import { Show } from "solid-js"
-import { useLanguage } from "@/runtime/i18n/language"
-import { ProjectSummaryCard } from "@/session/summary/project-card"
-import { SessionServerPanel } from "@/session/summary/server-panel"
-import type { PromptProject } from "./project/selector"
-import type { DraftMcpControls } from "./mcp"
-import type { NewSessionWorkspaceController } from "./workspace/controller"
-import { PromptWorkspaceSelector } from "./workspace/selector"
-
-export function NewSessionSummary(props: {
-  project?: PromptProject
-  workspace: NewSessionWorkspaceController
-  mcp: DraftMcpControls
-  shown: boolean
-  onChooseProject: () => void
-}) {
-  const language = useLanguage()
-  return (
-    <div data-component="session-summary-panel">
-      <Show
-        when={props.project}
-        fallback={
-          <div class="session-summary-card">
-            <button type="button" class="session-summary-row" onClick={props.onChooseProject}>
-              <Icon name="folder" class="text-v2-icon-icon-muted" />
-              <span class="session-summary-label">{language.t("session.summary.chooseProject")}</span>
-            </button>
-          </div>
-        }
-      >
-        {(project) => (
-          <>
-            <ProjectSummaryCard project={project()}>
-              <Show
-                when={props.workspace.bar.visible()}
-                fallback={
-                  <div class="session-summary-row">
-                    <Icon name="monitor" class="shrink-0 text-v2-icon-icon-muted" />
-                    <span class="session-summary-label">{language.t("session.new.git.none")}</span>
-                  </div>
-                }
-              >
-                <PromptWorkspaceSelector
-                  variant="summary"
-                  value={props.workspace.selection.value()}
-                  projectRoot={props.workspace.project.root()}
-                  workspaces={props.workspace.project.workspaces()}
-                  branches={props.workspace.project.branches()}
-                  branch={props.workspace.bar.branch()}
-                  onChange={props.workspace.selection.set}
-                  onCreate={props.workspace.selection.create}
-                  onSearch={props.workspace.project.searchBranches}
-                  onViewAll={props.workspace.project.openAll}
-                />
-              </Show>
-            </ProjectSummaryCard>
-            <SessionServerPanel directory={props.mcp.directory()} shown={props.shown} mcp={props.mcp.controls} />
-          </>
-        )}
-      </Show>
-    </div>
-  )
-}
@@ -1,10 +1,7 @@
 import { useDialog } from "@opencode/ui/context/dialog"
 import { Tooltip } from "@opencode/ui/tooltip"
 import { Icon } from "@opencode/ui/icon"
-import { Show, Suspense, createMemo, createSignal, lazy, onMount } from "solid-js"
-import { createStore } from "solid-js/store"
-import { makeEventListener } from "@solid-primitives/event-listener"
-import { debounce } from "@solid-primitives/scheduled"
+import { Show, createMemo, createSignal } from "solid-js"
 import { Schema } from "effect"
 import createPresence from "solid-presence"
 import { Composer } from "@/composer/composer"
@@ -24,13 +21,6 @@ import { Persist, persisted } from "@/runtime/persistence/storage"
 import { Persistence } from "@/runtime/persistence/schema"
 import type { NewSessionWorkspaceController } from "./workspace/controller"
 import { NewSessionWordmark } from "./wordmark"
-import { SummaryPopover } from "@/session/summary/popover"
-import type { DraftMcpControls } from "./mcp"
-
-const NewSessionSummary = lazy(async () => {
-  const { NewSessionSummary } = await import("./summary")
-  return { default: NewSessionSummary }
-})

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

@@ -48,23 +38,7 @@ export function NewSessionView(props: {
  composer: ComposerModel
  project: PromptProjectController
  workspace: NewSessionWorkspaceController
-  mcp: DraftMcpControls
 }) {
-  const [store, setStore] = createStore({
-    summary: false,
-    content: undefined as HTMLDivElement | undefined,
-    summaryResizeTranslate: undefined as string | undefined,
-  })
-  const finishWindowResize = debounce(() => setStore("summaryResizeTranslate", undefined), 150)
-  onMount(() => {
-    makeEventListener(window, "resize", () => {
-      if (store.summaryResizeTranslate === undefined) {
-        // Freeze the painted offset, including an in-flight slide, until resizing settles.
-        setStore("summaryResizeTranslate", store.content ? getComputedStyle(store.content).translate : "none")
-      }
-      finishWindowResize()
-    })
-  })
  const [onboarding, setOnboarding, , onboardingReady] = persisted(
    Persist.global("workspace-onboarding"),
    WorkspaceOnboardingSchema,
@@ -79,40 +53,14 @@ export function NewSessionView(props: {
    <div class="@container relative flex flex-col min-h-0 h-full flex-1">
      <div
        data-component="new-session"
-        data-summary-open={store.summary}
-        data-summary-resizing={store.summaryResizeTranslate !== undefined}
-        style={{ "--session-summary-resize-translate": store.summaryResizeTranslate }}
        class="relative flex-1 min-h-0 overflow-hidden rounded-[10px] bg-v2-background-bg-base shadow-[var(--v2-elevation-raised)]"
      >
        <ComposerDropzone
          active={props.composer.state.drag === "active"}
          input={props.composer.model.selection.current()?.capabilities.input}
        />
-        <div
-          data-slot="new-session-summary"
-          class="absolute inset-x-0 top-0 z-20 flex h-12 items-center justify-end px-3"
-        >
-          <SummaryPopover open={store.summary} onOpenChange={(open) => setStore("summary", open)}>
-            <Suspense>
-              <NewSessionSummary
-                project={props.project.selected()}
-                workspace={props.workspace}
-                mcp={props.mcp}
-                shown={store.summary}
-                onChooseProject={() => {
-                  setStore("summary", false)
-                  props.project.add()
-                }}
-              />
-            </Suspense>
-          </SummaryPopover>
-        </div>
        <div class="absolute inset-x-0 top-[25.375%] flex justify-center px-6">
-          <div
-            ref={(element) => setStore("content", element)}
-            data-slot="new-session-content"
-            class={NEW_SESSION_CONTENT_WIDTH}
-          >
+          <div class={NEW_SESSION_CONTENT_WIDTH}>
            <NewSessionWordmark />
            <div class="mt-8 flex flex-col gap-8">
              <Composer model={props.composer} />
@@ -152,6 +100,8 @@ export function NewSessionView(props: {
          </div>
        </div>
        <NewSessionTips
+          selection={props.composer.model.selection}
+          onDone={props.composer.restoreFocus}
          workspaceEligible={
            !!props.project.selected() &&
            props.workspace.bar.visible() &&
@@ -165,7 +115,12 @@ export function NewSessionView(props: {
  )
 }

-function NewSessionTips(props: { workspaceEligible: boolean; onWorkspace: () => void }) {
+function NewSessionTips(props: {
+  selection: ComposerModel["model"]["selection"]
+  onDone: () => void
+  workspaceEligible: boolean
+  onWorkspace: () => void
+}) {
  const language = useLanguage()
  const dialog = useDialog()
  const sdk = useWorkspaceLocation()
@@ -188,9 +143,8 @@ function NewSessionTips(props: { workspaceEligible: boolean; onWorkspace: () =>
  )
  const providerVisible = createMemo(
    () =>
-      providers.ready() &&
      providerReady() &&
-      providers.paid().length === 0 &&
+      providers.anyConnection() === false &&
      Date.now() - providerState.dismissedAt >= providerTipDismissalDuration,
  )
  const tip = createMemo<"workspace" | "provider" | undefined>(() => {
@@ -212,7 +166,9 @@ function NewSessionTips(props: { workspaceEligible: boolean; onWorkspace: () =>
      return
    }
    void import("@/providers/connect/dialog").then(({ DialogConnectProvider }) => {
-      void dialog.show(() => <DialogConnectProvider directory={sdk().directory} />)
+      void dialog.show(() => (
+        <DialogConnectProvider directory={sdk().directory} selection={props.selection} onDone={props.onDone} />
+      ))
    })
  }
  const dismiss = () => {
@@ -194,9 +194,7 @@ export function PromptWorkspaceSelector(props: {
                    }}
                  >
                    <Icon name="outline-worktree" />
-                    <span class="min-w-0 flex-1 truncate">
-                      {language.t("session.new.workspace.existing").replace(/(…|\.{3})$/, "")}
-                    </span>
+                    <span class="min-w-0 flex-1 truncate">{language.t("session.new.workspace.existingLabel")}</span>
                  </Menu.SubTrigger>
                  <Menu.Portal>
                    <Menu.SubContent class="max-h-[66.667dvh] w-[200px] overflow-y-auto !pb-0 [&>[data-component=menu-v2-item]:last-child]:mb-0.5 [@media(max-height:600px)]:max-h-[calc(100dvh-48px)]">
@@ -0,0 +1,19 @@
+import { expect, test } from "bun:test"
+import { consoleProviderGroup, consoleProviderName } from "./console"
+
+test("groups only providers managed by the active Console workspace", () => {
+  const direct = { id: "openai", integrationID: "openai", name: "Anomaly / OpenAI" }
+  const group = consoleProviderGroup([
+    { id: "opencode", integrationID: "opencode", name: "Anomaly / OpenCode" },
+    { id: "console-openai", integrationID: "opencode", name: "Anomaly / OpenAI" },
+    { id: "console-google", integrationID: "opencode", name: "Anomaly / Google" },
+    direct,
+  ])
+
+  expect(group).toBeDefined()
+  if (!group) throw new Error("Expected Console provider group")
+  expect(group.workspace).toBe("Anomaly")
+  expect(group.providers.map((provider) => provider.id)).toEqual(["opencode", "console-openai", "console-google"])
+  expect(consoleProviderName(group, group.providers[1].name)).toBe("OpenAI")
+  expect(group.providers).not.toContain(direct)
+})
@@ -0,0 +1,26 @@
+type Provider = {
+  id: string
+  integrationID?: string
+  name: string
+}
+
+export function consoleProviderGroup<T extends Provider>(providers: readonly T[]) {
+  const root = providers.find((provider) => provider.id === "opencode" && provider.integrationID === "opencode")
+  const suffix = " / OpenCode"
+  if (!root?.name.endsWith(suffix)) return
+  const workspace = root.name.slice(0, -suffix.length).trim()
+  if (!workspace) return
+  const prefix = `${workspace} / `
+  return {
+    root,
+    workspace,
+    prefix,
+    providers: providers.filter(
+      (provider) => provider.integrationID === "opencode" && provider.name.startsWith(prefix),
+    ),
+  }
+}
+
+export function consoleProviderName(group: { prefix: string }, name: string) {
+  return name.startsWith(group.prefix) ? name.slice(group.prefix.length) : name
+}
@@ -16,7 +16,13 @@ export function useIntegrations(directory: Accessor<string | undefined>) {
    })().catch(() => undefined)
  })

+  const location = () => {
+    const value = directory()
+    return value ? { directory: value } : undefined
+  }
+
  return {
-    list: () => data.location.integration.list(directory() ? { directory: directory()! } : undefined) ?? [],
+    ready: () => data.location.integration.list(location()) !== undefined,
+    list: () => data.location.integration.list(location()) ?? [],
  }
 }
@@ -38,11 +38,13 @@ export function useProviders(directory: Accessor<string | undefined>) {
    return normalizeProviderList(provider, model)
  })

+  const ready = () => {
+    const ref = location()
+    return data.location.provider.list(ref) !== undefined && data.location.model.list(ref) !== undefined
+  }
+
  return {
-    ready: () => {
-      const ref = location()
-      return data.location.provider.list(ref) !== undefined && data.location.model.list(ref) !== undefined
-    },
+    ready,
    all: () => providers().all,
    default: () => providers().default,
    // V2 servers list only available providers, so the connectable catalog
@@ -70,6 +72,15 @@ export function useProviders(directory: Accessor<string | undefined>) {
        (v) => Array.from(v),
      )
    },
+    // Any stored or detected connection, or a provider with models beyond the keyless OpenCode catalog.
+    // Undefined until both catalogs load, so callers never mistake loading for a first run.
+    anyConnection: () => {
+      if (!integrations.ready() || !ready()) return undefined
+      if (integrations.list().some((integration) => integration.connections.length > 0)) return true
+      return providers().connected.some(
+        (id) => id !== "opencode" && Object.keys(providers().all.get(id)?.models ?? {}).length > 0,
+      )
+    },
    paid: () => {
      const connected = new Set(providers().connected)
      const paid = [
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
vimtor	7d5f2c978c	refactor(app): use downward undo icon for move back	2026-09-24 15:11:09 +00:00
vimtor	2d8968d7e8	refactor(prompt): compact move back controls	2026-09-24 15:03:34 +00:00
vimtor	9ddd2e1a4c	feat(prompt): move queued prompts back to input	2026-09-24 13:37:27 +00:00
Shoubhit Dash	9810d98bc2	feat(ai): polish media DX with promise file helpers and one client layer (#50978 )	2026-09-24 18:34:14 +05:30
Shoubhit Dash	2caba90a63	feat(app): replace password pairing with one-time links (#50972 )	2026-09-24 18:28:48 +05:30
Shoubhit Dash	eccf0b3b7b	feat(server): pair with one-time connect links (#50970 )	2026-09-24 18:28:48 +05:30
opencode-agent[bot]	808588e9b9	chore(core): refresh bundled models.dev snapshot	2026-09-24 12:20:56 +00:00
Victor Navarro	c35c211460	feat(tui): expose model variant selection to plugins (#51101 )	2026-09-24 14:19:27 +02:00
opencode-agent[bot]andvimtor	efb8e23dcc	fix(tui): move session when recovering missing directory (#51096 ) Co-authored-by: vimtor <36263538+vimtor@users.noreply.github.com>	2026-09-24 13:47:23 +02:00
opencode-agent[bot]andBrendonovich	ad53e39d2e	fix(app): group nested tabs and show full session path (#51064 ) Co-authored-by: Brendonovich <14191578+Brendonovich@users.noreply.github.com>	2026-09-24 08:10:15 +00:00
opencode-agent[bot]	3ddfc15df5	feat(app): show bottom navigation setting on mobile production (#51067 )	2026-09-24 16:09:44 +08:00
opencode	ac2426e103	sync release versions for v2.0.16	2026-09-24 06:34:17 +00:00
opencode-agent[bot]	0bc8b8dbeb	feat(session-ui): show GitHub mark on Markdown links (#51000 )	2026-09-24 14:08:32 +08:00
Luke Parker	dca73ba9e3	fix(app): show composer attachment remove buttons on touch devices (#51047 )	2026-09-24 15:58:30 +10:00
Aiden Cline	318a8c1aba	feat(codemode): add Object.freeze/seal/create/getPrototypeOf and structuredClone (#50834 )	2026-09-24 00:50:54 -05:00
opencode-agent[bot]andiamdavidhill	bee5014f89	feat(app): simplify experimental settings (#49373 ) Co-authored-by: iamdavidhill <1879069+iamdavidhill@users.noreply.github.com>	2026-09-24 15:48:41 +10:00
opencode-agent[bot]andDax	8652729fdb	fix(desktop): identify updater requests (#50445 ) Co-authored-by: Dax <826656+thdxr@users.noreply.github.com>	2026-09-24 15:44:20 +10:00
usrnk1	bfcaf1b0cd	feat(desktop): reveal session workspace metadata (#49793 )	2026-09-24 15:42:21 +10:00
opencode-agent[bot]andjayair	f24fdeca70	fix(app): keep session summary as an overlay (#50386 ) Co-authored-by: jayair <53023+jayair@users.noreply.github.com>	2026-09-24 15:38:06 +10:00
Aiden Cline	dc48655743	fix(codemode): compare with == by IsLooselyEqual and stop deep-walking operands for opaque references (#50830 )	2026-09-24 00:36:41 -05:00
Luke Parker	ab52135b4e	test(app): match settings server param to the e2e server (#51039 )	2026-09-24 15:35:10 +10:00
usrnk1andLukeParkerDev	e31f78af78	feat(desktop): refine tool count spacing (#50356 ) Co-authored-by: LukeParkerDev <10430890+Hona@users.noreply.github.com>	2026-09-24 15:29:27 +10:00
usrnk1andLukeParkerDev	bc3669b97f	feat(desktop): adapt composer command menu height (#49343 ) Co-authored-by: LukeParkerDev <10430890+Hona@users.noreply.github.com>	2026-09-24 15:28:07 +10:00
Luke Parker	7460d855ac	fix(app): reread files when opening a preview (#51036 )	2026-09-24 15:23:46 +10:00
Aiden Cline	683d470fe4	fix(core): report read length and cap limits and long lines (#51011 )	2026-09-24 00:20:52 -05:00
Aiden Cline	ef4938d344	test(ai): remove orphaned Gemini cassettes (#51034 )	2026-09-24 00:17:10 -05:00
Aiden Cline	b098b0e06f	fix(ai): apply Gemini and Kimi schema handling by model name (#51017 )	2026-09-24 00:16:48 -05:00
usrnk1andLukeParkerDev	27dfac3d36	fix(app): preserve settings route on refresh (#50364 ) Co-authored-by: LukeParkerDev <10430890+Hona@users.noreply.github.com>	2026-09-24 14:52:21 +10:00
opencode-agent[bot]andHona	5253661d36	feat(i18n): complete current V2 translation coverage (#50204 ) Co-authored-by: Hona <10430890+Hona@users.noreply.github.com>	2026-09-24 14:44:59 +10:00
Aiden Cline	ff6b8c21e7	feat(core): MCP Code Mode defaults, turn off PostHog's server-side Code Mode (#51029 )	2026-09-23 23:30:12 -05:00
opencode-agent[bot]	8e39040eed	chore: update nix node_modules hashes	2026-09-24 04:24:26 +00:00
usrnk1 David Hill LukeParkerDev	95cfca73b0	feat(desktop): improve settings project management (#49172 ) Co-authored-by: David Hill <iamdavidhill@gmail.com> Co-authored-by: LukeParkerDev <10430890+Hona@users.noreply.github.com>	2026-09-24 14:23:15 +10:00
Vladimir GlafirovandAiden Cline	f0aff6cfe8	feat(core): restore GitLab workflow discovery and add OAuth login (#50422 ) Co-authored-by: Aiden Cline <aidenpcline@gmail.com>	2026-09-23 23:00:52 -05:00
usrnk1andLukeParkerDev	b7d707cd64	feat(app): sign in to OpenCode Console and Go through the device flow (#48501 ) Co-authored-by: LukeParkerDev <10430890+Hona@users.noreply.github.com>	2026-09-24 03:51:35 +00:00
Omkar Chandorkar	b486652067	fix(ui): fix desktop theme background seeds, light contrast, and token typos (#50517 ) Signed-off-by: Omkar Chandorkar <gotenksIN@aospa.co>	2026-09-24 13:51:18 +10:00
Aiden Cline	7d1e212fb5	fix(core): route responses-only Copilot models to the Responses API (#51024 )	2026-09-23 22:30:57 -05:00
Aiden Clineandrekram1-node	2c369a21c9	feat(core): note renamed legacy tools when migrating V1 sessions (#50188 ) Co-authored-by: rekram1-node <rekram1-node@users.noreply.github.com>	2026-09-23 21:29:20 -05:00
opencode-agent[bot]andrekram1-node	f2e73dd03f	fix(tui): open execute details after tool failure (#50921 ) Co-authored-by: rekram1-node <rekram1-node@users.noreply.github.com>	2026-09-23 21:10:18 -05:00
Aiden Cline	88a9688c9c	fix(ai): send Gemini tool schemas as parametersJsonSchema (#51009 )	2026-09-23 20:28:33 -05:00
Luke Parker	8d5eb3bf9c	fix(app): start MCP sign-in from row click (#51001 )	2026-09-24 10:29:32 +10:00
Aiden Clineandrekram1-node	6e0857cc0e	fix: Update condition for OpenAIPlugin to check 'astra' (#50989 ) Co-authored-by: rekram1-node <rekram1-node@users.noreply.github.com>	2026-09-23 17:43:12 -05:00