refactor(app): simplify local pairing screen

refactor(app): trim pairing comments and tests
docs: describe the pairing link
2026-09-19 23:27:36 +00:00 · 2026-09-19 19:26:26 +05:30 · 2026-09-19 18:42:13 +05:30 · 2026-09-19 18:39:52 +05:30 · 2026-09-19 18:39:52 +05:30 · 2026-09-19 18:39:52 +05:30
119 changed files with 1966 additions and 773 deletions
@@ -184,7 +184,6 @@ const table = sqliteTable("session", {
 - Keep `SessionRunner`, model resolution, tool registry, permissions, and filesystem Location-scoped. Omitted `Location.workspaceID` means implicit-local placement; explicit workspace identity remains reserved for future placement semantics.
 - Preserve one explicit `llm.stream(request)` call per Physical Attempt and reload projected history before durable continuation. A logical Step may use generic pre-output retries, one full-context retry after continuation rejection, incomplete-stream continuation, or one overflow-compaction rebuild. Generic retries retain the logical step number and do not consume another agent-step allowance. Do not delegate orchestration to an in-memory tool loop.
 - Keep local Session drains process-local until clustering is implemented. `SessionRunCoordinator` joins explicit same-Session resumes, coalesces prompt wakeups, and allows different Sessions to run concurrently. A write-ahead execution claim marks a process-local busy period for restart recovery: terminal completion, failure, or user interruption releases it, while shutdown interruption and process death preserve it. Startup recovery resumes claimed top-level Sessions with durable per-execution attempt accounting. The claim is a recovery marker, not clustered ownership, fencing, or an exactly-once guarantee.
- Keep native compaction mechanisms out of `SessionCompaction`. Plugins register `native` strategies through the `SessionCompaction` editor that turn a prepared request into a replacement window (the built-in `NativeCompactionPlugin` handles `@opencode/ai` compaction operations); later registrations win. Core owns the provider-mode decision, route provenance, the retry policy, overflow recovery, interruption, usage accounting, and checkpoint persistence.
 - Keep delivery vocabulary explicit. Prompts steer by default. At safe step boundaries, steered compaction takes priority up to the first steered move control; other steers retain enqueue order. At an idle boundary, steers take priority; otherwise exactly one queued item delivers before the runner reevaluates continuation. Inbox items may be cancelled or changed between queue and steer before delivery. Promoting new user input resets the selected agent's step allowance; a batch of steers resets it once.
 - One step is one logical LLM call; its durable record covers only the model-visible span. Do not write "provider turn", and do not use bare "turn" for a single call: "turn" is reserved for the future assistant-turn unit containing all steps from prompt promotion until the session would go idle.
 - Keep event replay ownership separate from clustered Session execution ownership.
@@ -32,7 +32,7 @@
    },
    "packages/ai": {
      "name": "@opencode/ai",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@aws-sdk/credential-providers": "3.1057.0",
        "@opencode/schema": "workspace:*",
@@ -54,7 +54,7 @@
    },
    "packages/app": {
      "name": "@opencode/app",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@corvu/drawer": "catalog:",
        "@dnd-kit/abstract": "0.5.0",
@@ -93,6 +93,7 @@
        "solid-js": "catalog:",
        "solid-presence": "0.2.0",
        "tailwindcss": "4.3.3",
+        "uqr": "0.1.3",
      },
      "devDependencies": {
        "@happy-dom/global-registrator": "20.0.11",
@@ -113,7 +114,7 @@
    },
    "packages/cli": {
      "name": "@opencode/cli",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "bin": {
        "opencode2": "./bin/opencode2.cjs",
      },
@@ -177,7 +178,7 @@
    },
    "packages/client": {
      "name": "@opencode/client",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opencode/protocol": "workspace:*",
        "@opencode/schema": "workspace:*",
@@ -203,7 +204,7 @@
    },
    "packages/codemode": {
      "name": "@opencode/codemode",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "acorn": "8.15.0",
        "effect": "catalog:",
@@ -217,7 +218,7 @@
    },
    "packages/console/app": {
      "name": "@opencode/console-app",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@cloudflare/vite-plugin": "1.15.2",
        "@ibm/plex": "6.4.1",
@@ -253,7 +254,7 @@
    },
    "packages/console/core": {
      "name": "@opencode/console-core",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@aws-sdk/client-sts": "3.782.0",
        "@jsx-email/render": "1.1.1",
@@ -280,7 +281,7 @@
    },
    "packages/console/function": {
      "name": "@opencode/console-function",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@openauthjs/openauth": "0.0.0-20250322224806",
        "@opencode/console-core": "workspace:*",
@@ -297,7 +298,7 @@
    },
    "packages/console/mail": {
      "name": "@opencode/console-mail",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@jsx-email/all": "2.2.3",
        "@jsx-email/cli": "1.4.3",
@@ -321,7 +322,7 @@
    },
    "packages/console/support": {
      "name": "@opencode/console-support",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@cloudflare/vite-plugin": "1.15.2",
        "@opencode/console-core": "workspace:*",
@@ -341,7 +342,7 @@
    },
    "packages/core": {
      "name": "@opencode/core",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@ai-sdk/cohere": "3.0.27",
        "@ai-sdk/gateway": "3.0.104",
@@ -409,7 +410,7 @@
    },
    "packages/desktop": {
      "name": "@opencode/desktop",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@zip.js/zip.js": "2.7.62",
        "electron-context-menu": "4.1.2",
@@ -456,11 +457,12 @@
        "@lydell/node-pty-linux-x64": "1.2.0-beta.12",
        "@lydell/node-pty-win32-arm64": "1.2.0-beta.12",
        "@lydell/node-pty-win32-x64": "1.2.0-beta.12",
+        "msgpackr-extract": "3.0.4",
      },
    },
    "packages/enterprise": {
      "name": "@opencode/enterprise",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@hono/standard-validator": "catalog:",
        "@opencode-ai/sdk": "1.18.21",
@@ -497,7 +499,7 @@
    },
    "packages/function": {
      "name": "@opencode/function",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@octokit/auth-app": "8.0.1",
        "@octokit/rest": "catalog:",
@@ -513,7 +515,7 @@
    },
    "packages/http-recorder": {
      "name": "@opencode/http-recorder",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@effect/platform-node-shared": "4.0.0-rc.112",
      },
@@ -532,7 +534,7 @@
    },
    "packages/httpapi-codegen": {
      "name": "@opencode/httpapi-codegen",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "effect": "catalog:",
        "prettier": "3.6.2",
@@ -545,7 +547,7 @@
    },
    "packages/latex": {
      "name": "@opencode/latex",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opencode/plugin": "workspace:*",
        "@opentui/core": "catalog:",
@@ -559,7 +561,7 @@
    },
    "packages/merman": {
      "name": "@opencode/merman",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opencode/plugin": "workspace:*",
        "@opentui/core": "catalog:",
@@ -574,7 +576,7 @@
    },
    "packages/plugin": {
      "name": "@opencode/plugin",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@ai-sdk/provider": "3.0.8",
        "@opencode/ai": "workspace:*",
@@ -613,7 +615,7 @@
    },
    "packages/plugin-browser": {
      "name": "@opencode/plugin-browser",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opencode/plugin": "workspace:*",
        "@opencode/schema": "workspace:*",
@@ -643,7 +645,7 @@
    },
    "packages/protocol": {
      "name": "@opencode/protocol",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opencode/schema": "workspace:*",
        "effect": "catalog:",
@@ -658,7 +660,7 @@
    },
    "packages/schema": {
      "name": "@opencode/schema",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@standard-schema/spec": "catalog:",
        "effect": "catalog:",
@@ -682,7 +684,7 @@
    },
    "packages/sdk": {
      "name": "@opencode/sdk",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opencode/client": "workspace:*",
        "@opencode/core": "workspace:*",
@@ -703,7 +705,7 @@
    },
    "packages/server": {
      "name": "@opencode/server",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@effect/platform-node": "catalog:",
        "@effect/platform-node-shared": "catalog:",
@@ -725,7 +727,7 @@
    },
    "packages/session-ui": {
      "name": "@opencode/session-ui",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@kobalte/core": "catalog:",
        "@opencode/client": "workspace:*",
@@ -760,7 +762,7 @@
    },
    "packages/simulation": {
      "name": "@opencode/simulation",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opencode/ai": "workspace:*",
        "@opencode/core": "workspace:*",
@@ -780,7 +782,7 @@
    },
    "packages/stats/app": {
      "name": "@opencode/stats-app",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@ibm/plex": "6.4.1",
        "@kobalte/core": "catalog:",
@@ -814,7 +816,7 @@
    },
    "packages/stats/core": {
      "name": "@opencode/stats-core",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@aws-sdk/client-athena": "3.933.0",
        "@planetscale/database": "1.19.0",
@@ -833,7 +835,7 @@
    },
    "packages/stats/server": {
      "name": "@opencode/stats-server",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@aws-sdk/client-firehose": "3.933.0",
        "@effect/platform-node": "catalog:",
@@ -879,7 +881,7 @@
    },
    "packages/theme": {
      "name": "@opencode/theme",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opentui/core": "catalog:",
        "effect": "catalog:",
@@ -893,7 +895,7 @@
    },
    "packages/tui": {
      "name": "@opencode/tui",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@opencode/client": "workspace:*",
        "@opencode/core": "workspace:*",
@@ -928,7 +930,7 @@
    },
    "packages/ui": {
      "name": "@opencode/ui",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@kobalte/core": "catalog:",
        "@pierre/diffs": "catalog:",
@@ -963,7 +965,7 @@
    },
    "packages/util": {
      "name": "@opencode/util",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@effect/opentelemetry": "catalog:",
        "@effect/platform-node": "catalog:",
@@ -996,7 +998,7 @@
    },
    "packages/web": {
      "name": "@opencode/web",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "@astrojs/cloudflare": "12.6.3",
        "@astrojs/markdown-remark": "6.3.1",
@@ -1037,7 +1039,7 @@
    },
    "services/update": {
      "name": "@opencode/update",
-      "version": "2.0.8",
+      "version": "2.0.7",
      "dependencies": {
        "jose": "6.0.11",
        "semver": "catalog:",
@@ -1,8 +1,8 @@
 {
  "nodeModules": {
-    "x86_64-linux": "sha256-TlCPtuIvTNF01fLI0yHCLzVkx53yF9xxvAObDMGeo8M=",
-    "aarch64-linux": "sha256-aEjyPIXHeA5w1iZXbPKJAOIJQBfXg+LAx/y7C5uFz4g=",
-    "aarch64-darwin": "sha256-lthMTio2qNy+H2tL9cAPmqC41O+wdSADI61cnW4dIb0=",
-    "x86_64-darwin": "sha256-ONFbRQnwzOYHo0Pyh327QfJG2uzqzNEn/SS2vbYYMdM="
+    "x86_64-linux": "sha256-U9IuP/ev6w4urvogOwQyl3rdumY6W4YaY18NkFaOVHU=",
+    "aarch64-linux": "sha256-Wc8OT2DRZpVo56KaoGE0Hsj1NDknakbWXO9w2qy6j+0=",
+    "aarch64-darwin": "sha256-wAea8+jajnMDxZ6XJL+Hsrf0621hwtBtWyD1+dS45dE=",
+    "x86_64-darwin": "sha256-g8PCNBSV6rO+VQjKU9AtYqj+r18o+fhLDXEQq+X2EZ4="
  }
 }
@@ -2,7 +2,7 @@
  "$schema": "https://json.schemastore.org/package.json",
  "name": "opencode",
  "description": "AI-powered development tool",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "private": true,
  "type": "module",
  "packageManager": "bun@1.4.2",
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "name": "@opencode/ai",
  "type": "module",
  "license": "MIT",
@@ -8,7 +8,7 @@ import { OpenResponsesOptions } from "./utils/open-responses-options.js"
 export type ReasoningEffort = OpenResponsesOptions.ReasoningEffort

 const Options = Schema.Struct({
-  reasoningEffort: Schema.optional(OpenResponsesOptions.ReasoningEffort),
+  reasoningEffort: OpenResponsesOptions.Options.fields.reasoningEffort,
  enableThinking: Schema.optional(Schema.Boolean),
  thinkingBudget: Schema.optional(Schema.Int),
  preserveThinking: Schema.optional(Schema.Boolean),
@@ -19,7 +19,7 @@ const Options = Schema.Struct({
    }),
  ),
  toolStream: Schema.optional(Schema.Boolean),
-  parallelToolCalls: Schema.optional(Schema.Boolean),
+  parallelToolCalls: OpenResponsesOptions.Options.fields.parallelToolCalls,
  repetitionPenalty: Schema.optional(Schema.Number),
  responseFormat: Schema.optional(
    Schema.Struct({
@@ -6,9 +6,9 @@ import { OpenResponsesOptions } from "./utils/open-responses-options.js"
 import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js"

 const Options = Schema.Struct({
-  reasoningEffort: Schema.optional(OpenResponsesOptions.ReasoningEffort),
+  reasoningEffort: OpenResponsesOptions.Options.fields.reasoningEffort,
  enableThinking: Schema.optional(Schema.Boolean),
-  store: Schema.optional(Schema.Boolean),
+  store: OpenResponsesOptions.Options.fields.store,
  previousResponseId: Schema.optional(Schema.String),
  conversation: Schema.optional(Schema.String),
 })
@@ -1,5 +1,5 @@
 import { Buffer } from "node:buffer"
-import { Effect, Option, Schema, SchemaGetter } from "effect"
+import { Effect, Option, Schema } from "effect"
 import { Tool } from "@opencode/schema/tool"
 import { Route } from "../route/client.js"
 import { Auth } from "../route/auth.js"
@@ -21,12 +21,11 @@ import {
  type JsonSchema,
  type MediaPart,
  type ProviderMetadata,
-  type ProviderOptions,
  type ToolCallPart,
  type ToolDefinition,
  type ToolResultPart,
 } from "../schema/index.js"
-import { JsonObject, knownString, optionalArray, optionalNull, ProviderShared } from "./shared.js"
+import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { classifyProviderFailure } from "../provider-error.js"
 import { effortUpdate, resolveEffortUpdates } from "../effort-updates.js"
 import * as Cache from "./utils/cache.js"
@@ -53,10 +52,57 @@ const SSE_EVENTS = new Set([
 ])
 export const framing = Framing.sseEvents(SSE_EVENTS)

-export type ThinkingBlockBinding = typeof AnthropicThinkingBlockBinding.Type
-export type ThinkingInput = typeof Thinking.Encoded
-/** Caller-facing provider options; unknown keys are accepted and ignored. `Options.Type` is the wire-ready form. */
-export type OptionsInput = ProviderOptions & typeof Options.Encoded
+export type ThinkingBlockBinding = {
+  readonly prefix_mismatch_behavior?: "error" | "drop_block" | (string & {})
+}
+
+export type ThinkingInput =
+  | {
+      readonly type: "adaptive"
+      readonly display?: "summarized" | "omitted"
+      readonly block_binding?: ThinkingBlockBinding
+    }
+  | {
+      readonly type: "disabled"
+    }
+  | ({
+      readonly type: "enabled"
+      readonly display?: "summarized" | "omitted"
+      readonly block_binding?: ThinkingBlockBinding
+    } & (
+      | { readonly budgetTokens: number; readonly budget_tokens?: number }
+      | { readonly budgetTokens?: number; readonly budget_tokens: number }
+    ))
+
+export interface OptionsInput {
+  /** Advanced in-band compaction. The caller owns checkpoint persistence and recovery. */
+  readonly contextManagement?: ContextManagement
+  readonly [key: string]: unknown
+  readonly thinking?: ThinkingInput
+  readonly effort?: string
+  readonly service_tier?: "auto" | "standard_only"
+  readonly serviceTier?: "auto" | "standard_only"
+  // SDK Metadata:2649 {user_id?: string | null}
+  readonly metadata?: { readonly user_id?: string | null }
+  // SDK MessageCreateParamsContainer:2596 ContainerParams|string
+  readonly container?:
+    | string
+    | { readonly id?: string | null; readonly skills?: ReadonlyArray<Record<string, unknown>> | null }
+  readonly inference_geo?: string | null
+  readonly inferenceGeo?: string | null
+  readonly cache_control?: { readonly type: "ephemeral"; readonly ttl?: "5m" | "1h" }
+  readonly cacheControl?: { readonly type: "ephemeral"; readonly ttl?: "5m" | "1h" }
+  // SDK OutputConfig:2684 {effort, format: JSONOutputFormat}
+  readonly output_config?: {
+    readonly effort?: string | null
+    readonly format?: { readonly type: "json_schema"; readonly schema: Record<string, unknown> } | null
+  }
+  readonly outputConfig?: {
+    readonly effort?: string | null
+    readonly format?: { readonly type: "json_schema"; readonly schema: Record<string, unknown> } | null
+  }
+}
+
 export type ProviderOptionsInput = OptionsInput

 export const ContextManagement = Schema.Struct({
@@ -83,7 +129,6 @@ const AnthropicCacheControl = Schema.Struct({
  type: Schema.tag("ephemeral"),
  ttl: Schema.optional(Schema.Literals(["5m", "1h"])),
 })
-const AnthropicServiceTier = Schema.Literals(["auto", "standard_only"])

 const AnthropicTextBlock = Schema.Struct({
  type: Schema.tag("text"),
@@ -272,21 +317,25 @@ const AnthropicToolChoice = Schema.Union([
 ])

 const AnthropicThinkingBlockBinding = Schema.Struct({
-  prefix_mismatch_behavior: Schema.optional(knownString<"error" | "drop_block">()),
+  prefix_mismatch_behavior: Schema.optional(Schema.String),
 })

-const AnthropicThinkingFields = {
-  display: Schema.optional(Schema.Literals(["summarized", "omitted"])),
-  block_binding: Schema.optional(AnthropicThinkingBlockBinding),
-}
-const AnthropicThinkingEnabled = Schema.Struct({
-  type: Schema.tag("enabled"),
-  budget_tokens: Schema.Number,
-  ...AnthropicThinkingFields,
-})
-const AnthropicThinkingAdaptive = Schema.Struct({ type: Schema.tag("adaptive"), ...AnthropicThinkingFields })
-const AnthropicThinkingDisabled = Schema.Struct({ type: Schema.tag("disabled") })
-const AnthropicThinking = Schema.Union([AnthropicThinkingEnabled, AnthropicThinkingAdaptive, AnthropicThinkingDisabled])
+const AnthropicThinking = Schema.Union([
+  Schema.Struct({
+    type: Schema.tag("enabled"),
+    budget_tokens: Schema.Number,
+    display: Schema.optional(Schema.Literals(["summarized", "omitted"])),
+    block_binding: Schema.optional(AnthropicThinkingBlockBinding),
+  }),
+  Schema.Struct({
+    type: Schema.tag("adaptive"),
+    display: Schema.optional(Schema.Literals(["summarized", "omitted"])),
+    block_binding: Schema.optional(AnthropicThinkingBlockBinding),
+  }),
+  Schema.Struct({
+    type: Schema.tag("disabled"),
+  }),
+])
 type AnthropicThinking = typeof AnthropicThinking.Type

 // SDK OutputConfig:2684 {effort?: "low"|"medium"|"high"|"xhigh"|"max"|null, format?: JSONOutputFormat:2399}
@@ -311,53 +360,6 @@ const AnthropicContainer = Schema.Union([
  }),
 ])

-// =============================================================================
-// Provider Options
-// =============================================================================
-// Callers spell the budget as `budgetTokens` or the wire `budget_tokens`; the
-// keys are disjoint per variant so the input type requires exactly one and the
-// transform can narrow on it. Decoding straight to the wire block keeps the
-// alias out of the rest of the file.
-const ThinkingEnabledInput = Schema.Union([
-  Schema.Struct({ type: Schema.tag("enabled"), budgetTokens: Schema.Number, ...AnthropicThinkingFields }),
-  Schema.Struct({ type: Schema.tag("enabled"), budget_tokens: Schema.Number, ...AnthropicThinkingFields }),
-]).pipe(
-  Schema.decodeTo(AnthropicThinkingEnabled, {
-    decode: SchemaGetter.transform((input) => ({
-      type: "enabled" as const,
-      budget_tokens: "budgetTokens" in input ? input.budgetTokens : input.budget_tokens,
-      display: input.display,
-      block_binding: input.block_binding,
-    })),
-    encode: SchemaGetter.passthrough({ strict: false }),
-  }),
-)
-const Thinking = Schema.Union([ThinkingEnabledInput, AnthropicThinkingAdaptive, AnthropicThinkingDisabled])
-
-const OutputConfigInput = Schema.Struct({
-  effort: optionalNull(Schema.String),
-  format: optionalNull(AnthropicJsonOutputFormat),
-})
-
-// Both key spellings are accepted; `fromRequest` prefers the snake_case one.
-const Options = Schema.Struct({
-  /** Advanced in-band compaction. The caller owns checkpoint persistence and recovery. */
-  contextManagement: Schema.optional(ContextManagement),
-  thinking: Schema.optional(Thinking),
-  effort: Schema.optional(Schema.String),
-  service_tier: Schema.optional(AnthropicServiceTier),
-  serviceTier: Schema.optional(AnthropicServiceTier),
-  metadata: Schema.optional(AnthropicMetadata),
-  container: Schema.optional(AnthropicContainer),
-  inference_geo: optionalNull(Schema.String),
-  inferenceGeo: optionalNull(Schema.String),
-  cache_control: Schema.optional(AnthropicCacheControl),
-  cacheControl: Schema.optional(AnthropicCacheControl),
-  output_config: Schema.optional(OutputConfigInput),
-  outputConfig: Schema.optional(OutputConfigInput),
-})
-const decodeOptions = ProviderShared.validateWith(Schema.decodeUnknownEffect(Options))
-
 const AnthropicBodyFields = {
  context_management: Schema.optional(
    Schema.Struct({
@@ -389,7 +391,7 @@ const AnthropicBodyFields = {
  container: Schema.optional(Schema.NullOr(AnthropicContainer)),
  inference_geo: Schema.optional(Schema.NullOr(Schema.String)),
  metadata: Schema.optional(AnthropicMetadata),
-  service_tier: Schema.optional(AnthropicServiceTier),
+  service_tier: Schema.optional(Schema.Literals(["auto", "standard_only"])),
 }
 export const AnthropicMessagesBody = Schema.Struct(AnthropicBodyFields)
 export type AnthropicMessagesBody = Schema.Schema.Type<typeof AnthropicMessagesBody>
@@ -999,6 +1001,64 @@ const lowerMessages = Effect.fn("AnthropicMessages.lowerMessages")(function* (
  return messages
 })

+const resolveOptions = Effect.fn("AnthropicMessages.resolveOptions")(function* (request: LLMRequest) {
+  const input = request.providerOptions as Record<string, unknown> | undefined
+  const rawServiceTier =
+    (input as Record<string, unknown> | undefined)?.service_tier ??
+    (input as Record<string, unknown> | undefined)?.serviceTier
+  const service_tier =
+    rawServiceTier === "auto" || rawServiceTier === "standard_only"
+      ? (rawServiceTier as "auto" | "standard_only")
+      : undefined
+  const rawMetadata = (input as Record<string, unknown> | undefined)?.metadata
+  const metadata =
+    ProviderShared.isRecord(rawMetadata) && (typeof rawMetadata.user_id === "string" || rawMetadata.user_id === null)
+      ? { user_id: rawMetadata.user_id as string | null }
+      : undefined
+  const container =
+    typeof (input as Record<string, unknown> | undefined)?.container === "string" ||
+    ProviderShared.isRecord((input as Record<string, unknown> | undefined)?.container)
+      ? ((input as Record<string, unknown>).container as
+          | string
+          | { id?: string | null; skills?: ReadonlyArray<Record<string, unknown>> | null })
+      : undefined
+  const rawInferenceGeo =
+    (input as Record<string, unknown> | undefined)?.inference_geo ??
+    (input as Record<string, unknown> | undefined)?.inferenceGeo
+  const inference_geo = typeof rawInferenceGeo === "string" ? rawInferenceGeo : undefined
+  const rawCacheControl =
+    (input as Record<string, unknown> | undefined)?.cache_control ??
+    (input as Record<string, unknown> | undefined)?.cacheControl
+  const cache_control =
+    ProviderShared.isRecord(rawCacheControl) && rawCacheControl.type === "ephemeral"
+      ? (rawCacheControl as { type: "ephemeral"; ttl?: "5m" | "1h" })
+      : undefined
+  const rawOutputConfig =
+    (input as Record<string, unknown> | undefined)?.output_config ??
+    (input as Record<string, unknown> | undefined)?.outputConfig
+  const outputConfigEffort =
+    typeof (input as Record<string, unknown> | undefined)?.effort === "string"
+      ? ((input as Record<string, unknown>).effort as string)
+      : ProviderShared.isRecord(rawOutputConfig) && typeof rawOutputConfig.effort === "string"
+        ? (rawOutputConfig.effort as string)
+        : undefined
+  const outputConfigFormat =
+    ProviderShared.isRecord(rawOutputConfig) && ProviderShared.isRecord(rawOutputConfig.format)
+      ? (rawOutputConfig.format as { type: "json_schema"; schema: Record<string, unknown> })
+      : undefined
+  const thinking = yield* resolveThinking(input?.thinking)
+  return {
+    thinking: applyThinkingBindingDefault(request.model, thinking),
+    effort: outputConfigEffort,
+    format: outputConfigFormat,
+    service_tier,
+    metadata,
+    container,
+    inference_geo,
+    cache_control,
+  }
+})
+
 // Accept gateway namespaces and Vertex suffixes without treating a snapshot date as a minor version.
 const claudeVersion = (id: string) => {
  const match = /(?:^|[./])claude-(?<family>[a-z]+)-(?<major>\d+)(?:[.-](?<minor>\d{1,2}))?(?:$|[-:@])/.exec(
@@ -1037,12 +1097,35 @@ const applyThinkingBindingDefault = (model: LLMRequest["model"], thinking: Anthr
  }
 }

+const resolveThinking = Effect.fn("AnthropicMessages.resolveThinking")(function* (input: unknown) {
+  if (!ProviderShared.isRecord(input)) return undefined
+  if (input.type === "disabled") return { type: "disabled" as const }
+  if (input.type !== "adaptive" && input.type !== "enabled") return undefined
+  const block_binding = yield* ProviderShared.validateWith(
+    Schema.decodeUnknownEffect(Schema.UndefinedOr(AnthropicThinkingBlockBinding)),
+  )(input.block_binding)
+  const display =
+    input.display === "summarized" || input.display === "omitted"
+      ? (input.display as "summarized" | "omitted")
+      : undefined
+  if (input.type === "adaptive") return { type: "adaptive" as const, display, block_binding }
+  const budget =
+    typeof input.budgetTokens === "number"
+      ? input.budgetTokens
+      : typeof input.budget_tokens === "number"
+        ? input.budget_tokens
+        : undefined
+  if (budget === undefined)
+    return yield* ProviderShared.invalidRequest("Anthropic thinking provider option requires budgetTokens")
+  return { type: "enabled" as const, budget_tokens: budget, display, block_binding }
+})
+
 const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (request: LLMRequest) {
-  const options = yield* decodeOptions(request.providerOptions ?? {})
-  const management = options.contextManagement
-  const outputConfig = options.output_config ?? options.outputConfig
-  const format = outputConfig?.format ?? undefined
-  const updates = resolveEffortUpdates(request, options.effort ?? outputConfig?.effort ?? undefined)
+  const management = yield* ProviderShared.validateWith(
+    Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)),
+  )(request.providerOptions?.contextManagement)
+  const options = yield* resolveOptions(request)
+  const updates = resolveEffortUpdates(request, options.effort)
  const generation = request.generation
  const toolSchemaCompatibility = request.model.compatibility?.toolSchema
  // Allocate the 4-breakpoint budget in invalidation order: tools → system →
@@ -1078,7 +1161,12 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
    )
  }
  const output_config =
-    updates.effort === undefined && format === undefined ? undefined : { effort: updates.effort, format }
+    updates.effort === undefined && options.format === undefined
+      ? undefined
+      : {
+          ...(updates.effort === undefined ? {} : { effort: updates.effort }),
+          ...(options.format === undefined ? {} : { format: options.format }),
+        }
  const body = {
    model: request.model.id,
    system,
@@ -1091,14 +1179,14 @@ const fromRequest = Effect.fn("AnthropicMessages.fromRequest")(function* (reques
    top_p: generation?.topP,
    top_k: generation?.topK,
    stop_sequences: generation?.stop,
-    thinking: applyThinkingBindingDefault(request.model, options.thinking),
+    thinking: options.thinking,
    output_config,
    // top-level passthrough per SDK MessageCreateParamsBase:4638,4643,4649,4654,4670
-    cache_control: options.cache_control ?? options.cacheControl,
+    cache_control: options.cache_control,
    container: options.container,
-    inference_geo: options.inference_geo ?? options.inferenceGeo ?? undefined,
+    inference_geo: options.inference_geo,
    metadata: options.metadata,
-    service_tier: options.service_tier ?? options.serviceTier,
+    service_tier: options.service_tier,
  }
  if (!management) return body
  return {
@@ -14,13 +14,12 @@ import {
  type LLMRequest,
  type MediaPart,
  type ProviderMetadata,
-  type ProviderOptions,
  type TextPart,
  type ToolCallPart,
  type ToolDefinition,
 } from "../schema/index.js"
 import { classifyProviderFailure } from "../provider-error.js"
-import { JsonObject, knownString, lenient, optionalArray, optionalNull, ProviderShared } from "./shared.js"
+import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js"
 import { GeminiToolSchema } from "./utils/gemini-tool-schema.js"
 import { Lifecycle } from "./utils/lifecycle.js"
 import { ToolSchemaProjection } from "./utils/tool-schema.js"
@@ -51,8 +50,35 @@ const omitsFunctionCallIds = (modelID: string) => {
  return match !== null && Number(match[1]) < 3
 }

-/** Caller-facing provider options; unknown keys are accepted and ignored. */
-export type OptionsInput = ProviderOptions & typeof Options.Encoded
+export interface OptionsInput {
+  readonly [key: string]: unknown
+  readonly cachedContent?: string
+  readonly safetySettings?: ReadonlyArray<{
+    readonly category:
+      | "HARM_CATEGORY_UNSPECIFIED"
+      | "HARM_CATEGORY_HATE_SPEECH"
+      | "HARM_CATEGORY_DANGEROUS_CONTENT"
+      | "HARM_CATEGORY_HARASSMENT"
+      | "HARM_CATEGORY_SEXUALLY_EXPLICIT"
+      | "HARM_CATEGORY_CIVIC_INTEGRITY"
+      | (string & {})
+    readonly threshold:
+      | "HARM_BLOCK_THRESHOLD_UNSPECIFIED"
+      | "BLOCK_LOW_AND_ABOVE"
+      | "BLOCK_MEDIUM_AND_ABOVE"
+      | "BLOCK_ONLY_HIGH"
+      | "BLOCK_NONE"
+      | "OFF"
+      | (string & {})
+  }>
+  readonly serviceTier?: "standard" | "flex" | "priority" | (string & {})
+  readonly thinkingConfig?: {
+    readonly thinkingBudget?: number
+    readonly includeThoughts?: boolean
+    readonly thinkingLevel?: "minimal" | "low" | "medium" | "high" | (string & {})
+  }
+}
+
 export type ProviderOptionsInput = OptionsInput

 // =============================================================================
@@ -135,50 +161,17 @@ const GeminiToolConfig = Schema.Struct({
  }),
 })

-const GeminiThinkingLevel = knownString<"minimal" | "low" | "medium" | "high">()
 const GeminiThinkingConfig = Schema.Struct({
  thinkingBudget: Schema.optional(Schema.Number),
  includeThoughts: Schema.optional(Schema.Boolean),
-  thinkingLevel: Schema.optional(GeminiThinkingLevel),
+  thinkingLevel: Schema.optional(Schema.String),
 })

 const GeminiSafetySetting = Schema.Struct({
-  category: knownString<
-    | "HARM_CATEGORY_UNSPECIFIED"
-    | "HARM_CATEGORY_HATE_SPEECH"
-    | "HARM_CATEGORY_DANGEROUS_CONTENT"
-    | "HARM_CATEGORY_HARASSMENT"
-    | "HARM_CATEGORY_SEXUALLY_EXPLICIT"
-    | "HARM_CATEGORY_CIVIC_INTEGRITY"
-  >(),
-  threshold: knownString<
-    | "HARM_BLOCK_THRESHOLD_UNSPECIFIED"
-    | "BLOCK_LOW_AND_ABOVE"
-    | "BLOCK_MEDIUM_AND_ABOVE"
-    | "BLOCK_ONLY_HIGH"
-    | "BLOCK_NONE"
-    | "OFF"
-  >(),
+  category: Schema.String,
+  threshold: Schema.String,
 })

-// =============================================================================
-// Provider Options
-// =============================================================================
-// Malformed fields are dropped rather than failing the request; a `thinkingConfig`
-// object that omits `includeThoughts` asks for thoughts.
-const GeminiThinkingConfigInput = Schema.Struct({
-  thinkingBudget: lenient(Schema.Number),
-  includeThoughts: lenient(Schema.Boolean),
-  thinkingLevel: lenient(GeminiThinkingLevel),
-})
-const Options = Schema.Struct({
-  cachedContent: lenient(Schema.String),
-  safetySettings: lenient(Schema.Array(GeminiSafetySetting)),
-  serviceTier: lenient(knownString<"standard" | "flex" | "priority">()),
-  thinkingConfig: lenient(GeminiThinkingConfigInput),
-})
-const decodeOptions = ProviderShared.validateWith(Schema.decodeUnknownEffect(Options))
-
 const GeminiGenerationConfig = Schema.Struct({
  maxOutputTokens: Schema.optional(Schema.Number),
  temperature: Schema.optional(Schema.Number),
@@ -438,11 +431,44 @@ const lowerMessages = Effect.fn("Gemini.lowerMessages")(function* (request: LLMR
  return contents
 })

+const resolveOptions = (request: LLMRequest) => {
+  const input = request.providerOptions
+  const value = input?.thinkingConfig
+  const thinkingConfig = {
+    thinkingBudget:
+      ProviderShared.isRecord(value) && typeof value.thinkingBudget === "number" ? value.thinkingBudget : undefined,
+    includeThoughts:
+      ProviderShared.isRecord(value) && typeof value.includeThoughts === "boolean"
+        ? value.includeThoughts
+        : ProviderShared.isRecord(value)
+          ? true
+          : undefined,
+    thinkingLevel:
+      ProviderShared.isRecord(value) && typeof value.thinkingLevel === "string" ? value.thinkingLevel : undefined,
+  }
+  return {
+    cachedContent: typeof input?.cachedContent === "string" ? input.cachedContent : undefined,
+    safetySettings: mapSafetySettings(input?.safetySettings),
+    serviceTier: typeof input?.serviceTier === "string" ? input.serviceTier : undefined,
+    thinkingConfig: Object.values(thinkingConfig).some((item) => item !== undefined) ? thinkingConfig : undefined,
+  }
+}
+
+function mapSafetySettings(value: unknown) {
+  if (!Array.isArray(value)) return undefined
+  const settings = value.flatMap((item) =>
+    ProviderShared.isRecord(item) && typeof item.category === "string" && typeof item.threshold === "string"
+      ? [{ category: item.category, threshold: item.threshold }]
+      : [],
+  )
+  return settings
+}
+
 const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMRequest) {
  const flattened = ProviderShared.flattenToolRequest(request)
  const hasTools = flattened.tools.length > 0
  const generation = request.generation
-  const options = yield* decodeOptions(request.providerOptions ?? {})
+  const options = resolveOptions(request)
  const toolSchemaCompatibility = request.model.compatibility?.toolSchema
  const generationConfig = {
    maxOutputTokens: generation?.maxTokens,
@@ -453,10 +479,7 @@ const fromRequest = Effect.fn("Gemini.fromRequest")(function* (request: LLMReque
    presencePenalty: generation?.presencePenalty,
    seed: generation?.seed,
    stopSequences: generation?.stop,
-    thinkingConfig:
-      options.thinkingConfig === undefined
-        ? undefined
-        : { ...options.thinkingConfig, includeThoughts: options.thinkingConfig.includeThoughts ?? true },
+    thinkingConfig: options.thinkingConfig,
  }

  return {
@@ -1,6 +1,6 @@
 import { Buffer } from "node:buffer"
 import { Tool } from "@opencode/schema/tool"
-import { Effect, Option, Schema, Stream } from "effect"
+import { Effect, Schema, Stream } from "effect"
 import * as Sse from "effect/unstable/encoding/Sse"
 import { Headers, HttpClientRequest, HttpClientResponse } from "effect/unstable/http"
 import {
@@ -29,16 +29,6 @@ const isJson = Schema.is(Schema.Json)
 export const JsonObject = Schema.Record(Schema.String, Schema.Unknown)
 export const optionalArray = <const S extends Schema.Top>(schema: S) => Schema.optional(Schema.Array(schema))
 export const optionalNull = <const S extends Schema.Top>(schema: S) => Schema.optional(Schema.NullOr(schema))
-/** Optional field whose malformed value decodes to `undefined` instead of failing the enclosing struct. */
-export const lenient = <const S extends Schema.Top>(schema: S) =>
-  Schema.optionalKey(
-    Schema.UndefinedOr(schema).pipe(Schema.catchDecoding(() => Effect.succeed(Option.some(undefined)))),
-  )
-/** Provider-defined string enum: known values for autocomplete, any string accepted at runtime. */
-export const knownString = <Known extends string>() =>
-  Schema.declare<Known | (string & {})>((value): value is Known | (string & {}) => typeof value === "string", {
-    expected: "string",
-  })

 export const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64

@@ -1,6 +1,5 @@
-import { Schema } from "effect"
+import { Option, Schema } from "effect"
 import { ReasoningEffort, ReasoningEfforts, type LLMRequest } from "../../schema/index.js"
-import { lenient } from "../shared.js"

 export { ReasoningEffort, ReasoningEfforts }

@@ -50,22 +49,21 @@ export const StreamOptions = Schema.Struct({
  includeObfuscation: Schema.optional(Schema.Boolean),
 })

-// Malformed options are dropped one at a time so a bad `topLogprobs` cannot discard `store` or `reasoningEffort`.
 export const Options = Schema.Struct({
-  store: lenient(Schema.Boolean),
-  metadata: lenient(Schema.Record(Schema.String, Schema.String)),
-  safetyIdentifier: lenient(Schema.String),
-  streamOptions: lenient(StreamOptions),
-  topLogprobs: lenient(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 20 }))),
-  reasoningEffort: lenient(ReasoningEffort),
-  reasoningSummary: lenient(Schema.Literals(["auto", "concise", "detailed"])),
-  include: lenient(Schema.Array(ResponseIncludableSchema)),
-  textVerbosity: lenient(TextVerbositySchema),
-  serviceTier: lenient(ServiceTierSchema),
-  truncation: lenient(TruncationSchema),
-  allowedTools: lenient(AllowedTools),
-  maxToolCalls: lenient(Schema.Int),
-  parallelToolCalls: lenient(Schema.Boolean),
+  store: Schema.optional(Schema.Boolean),
+  metadata: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+  safetyIdentifier: Schema.optional(Schema.String),
+  streamOptions: Schema.optional(StreamOptions),
+  topLogprobs: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 20 }))),
+  reasoningEffort: Schema.optional(ReasoningEffort),
+  reasoningSummary: Schema.optional(Schema.Literals(["auto", "concise", "detailed"])),
+  include: Schema.optional(Schema.Array(ResponseIncludableSchema)),
+  textVerbosity: Schema.optional(TextVerbositySchema),
+  serviceTier: Schema.optional(ServiceTierSchema),
+  truncation: Schema.optional(TruncationSchema),
+  allowedTools: Schema.optional(AllowedTools),
+  maxToolCalls: Schema.optional(Schema.Int),
+  parallelToolCalls: Schema.optional(Schema.Boolean),
 })
 export type Options = typeof Options.Type

@@ -73,10 +71,11 @@ export type Resolved = Omit<Options, "allowedTools"> & {
  readonly allowedTools?: AllowedTools & { readonly mode: NonNullable<AllowedTools["mode"]> }
 }

-const decodeOptions = Schema.decodeUnknownSync(Options)
+const decodeOptions = Schema.decodeUnknownOption(Options)

 export const resolve = (request: LLMRequest): Resolved => {
-  const input = decodeOptions(request.providerOptions ?? {})
+  const input = Option.getOrUndefined(decodeOptions(request.providerOptions))
+  if (!input) return {}
  return {
    ...input,
    include: input.include?.length ? input.include : undefined,
@@ -166,71 +166,7 @@ describe("Anthropic Messages route", () => {
        }),
      ).pipe(Effect.flip)

-      expect(error.reason._tag).toBe("InvalidRequest")
-      expect(error.message).toContain("budgetTokens")
-    }),
-  )
-
-  it.effect("lowers passthrough provider options and accepts either key spelling", () =>
-    Effect.gen(function* () {
-      const snake = yield* compileRequest(
-        LLMRequest.update(request, {
-          providerOptions: {
-            service_tier: "auto",
-            metadata: { user_id: "user_1" },
-            container: { id: "container_1" },
-            inference_geo: "us",
-            cache_control: { type: "ephemeral", ttl: "1h" },
-            output_config: { format: { type: "json_schema", schema: { type: "object" } } },
-          },
-        }),
-      )
-      const camel = yield* compileRequest(
-        LLMRequest.update(request, {
-          providerOptions: {
-            serviceTier: "standard_only",
-            container: "container_2",
-            inferenceGeo: "eu",
-            cacheControl: { type: "ephemeral" },
-            outputConfig: { effort: "low" },
-          },
-        }),
-      )
-
-      expect(snake.body).toMatchObject({
-        service_tier: "auto",
-        metadata: { user_id: "user_1" },
-        container: { id: "container_1" },
-        inference_geo: "us",
-        cache_control: { type: "ephemeral", ttl: "1h" },
-        output_config: { format: { type: "json_schema", schema: { type: "object" } } },
-      })
-      expect(camel.body).toMatchObject({
-        service_tier: "standard_only",
-        container: "container_2",
-        inference_geo: "eu",
-        cache_control: { type: "ephemeral" },
-        output_config: { effort: "low" },
-      })
-    }),
-  )
-
-  it.effect("ignores unknown provider options and rejects malformed known ones", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(LLMRequest.update(request, { providerOptions: { unknownOption: true } }))
-      const malformed = [
-        { service_tier: "fast" },
-        { metadata: { user_id: 42 } },
-        { cache_control: { type: "ephemeral", ttl: "2h" } },
-        { output_config: { format: { type: "text" } } },
-        { thinking: { type: "automatic" } },
-      ]
-      const errors = yield* Effect.forEach(malformed, (providerOptions) =>
-        compileRequest(LLMRequest.update(request, { providerOptions })).pipe(Effect.flip),
-      )
-
-      expect(prepared.body).not.toHaveProperty("unknownOption")
-      expect(errors.map((error) => error.reason._tag)).toEqual(malformed.map(() => "InvalidRequest"))
+      expect(error.message).toContain("Anthropic thinking provider option requires budgetTokens")
    }),
  )

@@ -248,21 +248,6 @@ describe("OpenAI Chat route", () => {
    }),
  )

-  it.effect("keeps valid Chat options when a sibling option is malformed", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model: OpenAI.configure({ baseURL: "https://api.openai.test/v1/", apiKey: "test" }).chat("gpt-4o-mini"),
-          prompt: "think",
-          providerOptions: { store: true, reasoningEffort: "max", topLogprobs: 25 },
-        }),
-      )
-
-      expect(prepared.body.store).toBe(true)
-      expect(prepared.body.reasoning_effort).toBe("max")
-    }),
-  )
-
  it.effect("maps the request prompt cache key when the compatibility flag is set", () =>
    Effect.gen(function* () {
      const prepared = yield* compileRequest(
@@ -1945,30 +1945,6 @@ describe("OpenAI Responses route", () => {
    }),
  )

-  it.effect("drops a malformed provider option without discarding its siblings", () =>
-    Effect.gen(function* () {
-      const prepared = yield* compileRequest(
-        LLM.request({
-          model,
-          prompt: "hi",
-          providerOptions: {
-            topLogprobs: 25,
-            metadata: { tenant: 7 },
-            reasoningEffort: "high",
-            serviceTier: "priority",
-            maxToolCalls: 4,
-          },
-        }),
-      )
-
-      expect(prepared.body.top_logprobs).toBeUndefined()
-      expect(prepared.body.metadata).toBeUndefined()
-      expect(prepared.body.reasoning).toEqual({ effort: "high" })
-      expect(prepared.body.service_tier).toBe("priority")
-      expect(prepared.body.max_tool_calls).toBe(4)
-    }),
-  )
-
  it.effect("accepts the full ResponseIncludable union", () =>
    Effect.gen(function* () {
      const prepared = yield* compileRequest(
@@ -0,0 +1,83 @@
+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?data=${encodeURIComponent(JSON.stringify({ username: "opencode", password }))}`)
+  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 hosted app hands HTTP-only pairing links over to the server's own web UI", async ({ page, baseURL }) => {
+  const dev = new URL(baseURL ?? "http://127.0.0.1:3000").origin
+  const hosted = "https://app.opencode.ai"
+  const lan = "http://192.168.1.20:49374"
+  // Serve the dev build under the hosted HTTPS origin so mixed-content rules apply to the page.
+  await page.route(`${hosted}/**`, async (route) => {
+    const response = await page.request.fetch(route.request().url().replace(hosted, dev))
+    await route.fulfill({ response })
+  })
+  await page.route(`${lan}/**`, (route) =>
+    route.fulfill({ status: 200, contentType: "text/html", body: "<title>served</title>" }),
+  )
+  const requests: string[] = []
+  await page.route("**/api/**", async (route) => {
+    requests.push(route.request().url())
+    await route.abort()
+  })
+  const info = { urls: [lan], username: "opencode", password: "lan-secret" }
+  const fragment = Buffer.from(JSON.stringify(info)).toString("base64url")
+
+  await page.goto(`${hosted}/connect#${fragment}`)
+  await expect(page.getByRole("heading", { name: "This server is on a local network" })).toBeVisible()
+  await expect(page.getByText(lan, { exact: true })).toBeVisible()
+  expect(requests).toEqual([])
+
+  await page.getByRole("button", { name: "Open on local network" }).click()
+  await expect(page).toHaveURL(`${lan}/connect#${fragment}`)
+})
+
+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([])
+})
@@ -1,6 +1,6 @@
 {
  "name": "@opencode/app",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "description": "",
  "type": "module",
  "exports": {
@@ -93,6 +93,7 @@
    "remeda": "catalog:",
    "solid-js": "catalog:",
    "solid-presence": "0.2.0",
-    "tailwindcss": "4.3.3"
+    "tailwindcss": "4.3.3",
+    "uqr": "0.1.3"
  }
 }
@@ -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 } from "@solidjs/router"
+import { type BaseRouterProps, Router, useLocation } from "@solidjs/router"
 import { QueryClient, QueryClientProvider } from "@tanstack/solid-query"
-import { type Component, createRenderEffect, ErrorBoundary, type JSX, type ParentProps } from "solid-js"
+import { type Component, createRenderEffect, ErrorBoundary, type JSX, type ParentProps, Show } from "solid-js"
 import { Dynamic } from "solid-js/web"
 import { CommandProvider } from "@/shell/commands/command"
 import { DesktopCommands } from "@/shell/commands/desktop"
@@ -107,21 +107,29 @@ 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) => (
-    <TabsProvider>
-      <GlobalProvider>
+  const Root = (rootProps: ParentProps) => {
+    const location = useLocation()
+    // Pairing saves credentials before mounting any server connections or health checks.
+    return (
+      <>
        <BodyTypography />
-        <CommandProvider>
-          <DesktopCommands />
-          <SshRestore />
-          <HighlightsProvider>
-            {props.children}
-            {rootProps.children}
-          </HighlightsProvider>
-        </CommandProvider>
-      </GlobalProvider>
-    </TabsProvider>
-  )
+        <Show when={location.pathname !== "/connect"} fallback={rootProps.children}>
+          <TabsProvider>
+            <GlobalProvider>
+              <CommandProvider>
+                <DesktopCommands />
+                <SshRestore />
+                <HighlightsProvider>
+                  {props.children}
+                  {rootProps.children}
+                </HighlightsProvider>
+              </CommandProvider>
+            </GlobalProvider>
+          </TabsProvider>
+        </Show>
+      </>
+    )
+  }

  return (
    <ServersProvider
@@ -1,10 +1,9 @@
-import { createEffect, createMemo, createResource, createSignal, For, onCleanup, onMount, Show, type JSX } from "solid-js"
+import { createEffect, createMemo, createSignal, For, onCleanup, onMount, Show, type JSX } from "solid-js"
 import { createStore } from "solid-js/store"
 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 { useI18n } from "@opencode/ui/context/i18n"
 import { Button } from "@opencode/ui/button"
@@ -546,21 +545,17 @@ export function ComposerAttachments(props: {
                      </AttachmentCard>
                    }
                  >
-                    {(image) => {
-                      // Restored drafts and history carry image ids only; bytes load when shown.
-                      const [url] = createResource(() => image().blob, resolveBlobUrl)
-                      return (
-                        <>
-                          <img
-                            src={url() ?? ""}
-                            alt={attachment.filename}
-                            class="w-[58px] h-[46px] rounded-[6px] object-cover"
-                            onClick={() => props.onAttachmentClick?.(attachment)}
-                          />
-                          <div class="absolute inset-0 rounded-[6px] shadow-[inset_0_0_0_0.5px_var(--v2-border-border-base)] pointer-events-none" />
-                        </>
-                      )
-                    }}
+                    {(image) => (
+                      <>
+                    <img
+                      src={image().blob.url}
+                      alt={attachment.filename}
+                      class="w-[58px] h-[46px] rounded-[6px] object-cover"
+                      onClick={() => props.onAttachmentClick?.(attachment)}
+                    />
+                    <div class="absolute inset-0 rounded-[6px] shadow-[inset_0_0_0_0.5px_var(--v2-border-border-base)] pointer-events-none" />
+                      </>
+                    )}
                  </Show>
                </Tooltip>
                <button
@@ -11,7 +11,6 @@ import { useLanguage } from "@/runtime/i18n/language"
 import { useLayout } from "@/shell/state/layout"
 import { usePlatform } from "@/runtime/platform/platform"
 import { useWorkspaceLocation } from "@/workspaces/location"
-import { resolveBlobUrl } from "@/runtime/persistence/drafts"
 import { useData, useServer } from "@/runtime/server/current"
 import { createSessionTabs } from "@/session/helpers"
 import { showToast } from "@/shell/notifications/toast"
@@ -323,9 +322,7 @@ export function createComposerModel(adapter: ComposerAdapter, options?: { queue?
    },
    openAttachment: (attachment) => {
      if (attachment.type !== "image") return
-      void resolveBlobUrl(attachment.blob).then((src) => {
-        if (src) dialog.show(() => createComponent(ImagePreview, { src, alt: attachment.filename }))
-      })
+      dialog.show(() => createComponent(ImagePreview, { src: attachment.blob.url, alt: attachment.filename }))
    },
    openContext(key) {
      const item = controller.contextItem(key)
@@ -136,7 +136,7 @@ describe("composer persistence schemas", () => {
    ).toEqual(value)
  })

-  test("migrates inline images, keeps store references without a URL, and never encodes dataUrl", () => {
+  test("migrates inline images but never encodes dataUrl or unresolved references", () => {
    const value = Schema.decodeUnknownSync(
      Persistence.withInitial(ComposerStore, { prompt: DEFAULT_PROMPT, context: { items: [] } }),
    )({
@@ -149,16 +149,12 @@ describe("composer persistence schemas", () => {
        { ...image, blob: { id: "missing" }, dataUrl: "data:image/png;base64,YQ==" },
      ],
    })
-    expect(value.prompt).toHaveLength(6)
+    expect(value.prompt).toHaveLength(3)
    expect(value.prompt[0]).toEqual({
      ...image,
      sourcePath: "/image.png",
      blob: { id: "data:image/png;base64,YQ==", url: "data:image/png;base64,YQ==" },
    })
-    // Bytes still in the draft store resolve on use; a non-blob URL is discarded in favour of the id.
-    expect(value.prompt[3]).toEqual({ ...image, blob: { id: "missing", url: "" } })
-    expect(value.prompt[4]).toEqual({ ...image, blob: { id: "bad", url: "" } })
-    expect(value.prompt[5]).toEqual({ ...image, blob: { id: "missing", url: "" } })
    const encoded = Schema.encodeSync(ComposerStore)(value)
    expect(JSON.stringify(encoded)).not.toContain("dataUrl")
    expect(
@@ -61,12 +61,11 @@ const ImageFields = {
 }
 const Image = Persistence.struct({
  ...ImageFields,
-  // An empty URL is an image whose bytes are still in the draft store; see `resolveBlobUrl`.
-  blob: Schema.Struct({ id: Schema.NonEmptyString, url: Schema.String.check(Schema.isPattern(/^(blob:|data:|$)/)) }),
+  blob: Schema.Struct({ id: Schema.NonEmptyString, url: Schema.String.check(Schema.isPattern(/^(blob:|data:)/)) }),
 })

-// Draft storage keeps content-addressed blobs in the store until an image is shown or sent; a
-// reference without a URL resolves through `resolveBlobUrl`. Legacy inline data remains usable.
+// Draft storage hydrates content-addressed blobs before this codec runs. Legacy
+// inline data remains usable, but unresolved references are not renderable.
 export const ImageAttachmentPart = Schema.Struct({
  ...ImageFields,
  blob: Persistence.optional(
@@ -88,15 +88,6 @@ describe("prompt state initialization", () => {
          start: 5,
          end: 12,
        },
-        // A reference without a usable URL keeps its id; the bytes resolve from the draft store on use.
-        {
-          type: "image",
-          id: "missing-blob",
-          filename: "missing.png",
-          mime: "image/png",
-          blob: { id: "content-hash-without-a-url", url: "" },
-        },
-        { type: "image", id: "invalid-url", filename: "invalid.png", mime: "image/png", blob: { id: "hash", url: "" } },
        {
          type: "image",
          id: "legacy",
@@ -8,7 +8,7 @@ import type { ComposerAdapter, ComposerDelivery, ComposerSelection, ComposerSess
 import { createComposerSubmission } from "./submission-state"
 import { buildPromptRequest } from "./request"
 import { setCursorPosition } from "./editor/dom"
-import { blobDataUrl, resolveBlobUrl } from "@/runtime/persistence/drafts"
+import { blobDataUrl } from "@/runtime/persistence/drafts"
 import { isAttachment } from "./prompt-parts"
 import type { ModelSelection } from "@/providers/models/selection"

@@ -59,22 +59,12 @@ export function createComposerSubmit(input: ComposerSubmitInput) {
        selection: item.selection ? { ...item.selection } : undefined,
      })),
    })
-    const read = readSubmission(input, submission.prompt, submission.context, options?.alternate ?? false)
-    if (!read) {
+    const value = readSubmission(input, submission.prompt, submission.context, options?.alternate ?? false)
+    if (!value) {
      if (input.adapter.working() && input.adapter.kind === "active-session") void input.adapter.interrupt()
      return
    }
    if (submitting.has(input.adapter.state)) return
-    // Images restored from a draft or history carry ids only; the optimistic message shows their URLs.
-    const value = {
-      ...read,
-      images: await Promise.all(
-        read.images.map(async (image) => ({
-          ...image,
-          blob: { ...image.blob, url: (await resolveBlobUrl(image.blob)) ?? image.blob.url },
-        })),
-      ),
-    }
    submitting.add(input.adapter.state)
    const comments = input.comments.capture()
    // Capture command intent before starting a session in a worktree whose catalog has not loaded.
@@ -440,6 +440,44 @@ export const dict = {
    "No camera is available to this browser. Enter your connection details manually.",
  "server.connect.camera.error":
    "Could not open the camera. Allow camera access or enter your connection details manually.",
+  "server.connect.local.title": "This server is on a local network",
+  "server.connect.local.description":
+    "This page can't reach HTTP servers on your local network. Open the server's own web interface to continue on this device.",
+  "server.connect.local.open": "Open on local network",
+  "server.connect.local.loopback.title": "This server only listens on localhost",
+  "server.connect.local.loopback.description":
+    "Other devices can't reach a server that only listens on localhost. Opening it will only work on the computer running OpenCode.",
+  "server.connect.local.loopback.open": "Open on this computer",
+  "server.connect.local.loopback.fix": "Run this command on your computer, then pair again.",
+  "command.server.pair": "Pair device",
+  "settings.pairing.title": "Pairing",
+  "settings.pairing.connection": "Local Network",
+  "pair.local.description": "View connection details and a QR code to connect a device on the same network.",
+  "pair.local.open": "Show details",
+  "pair.screenActive.title": "Keep screen active",
+  "pair.screenActive.description": "Prevent this computer’s display from sleeping while OpenCode is running.",
+  "pair.screenActive.error": "Could not update the screen activity setting. Try again.",
+  "pair.qr.open": "Show details",
+  "pair.tailscale.enable": "Enable Tailscale",
+  "pair.tailscale.serve": "Tailscale Serve",
+  "pair.description": "Connect another device to this machine's OpenCode server.",
+  "pair.loading": "Loading connection details…",
+  "pair.qr": "Pairing QR code",
+  "pair.copy": "Copy details",
+  "pair.copy.error": "Could not copy pairing details. Try again.",
+  "pair.urls": "URLs",
+  "pair.username": "Username",
+  "pair.password": "Password",
+  "pair.error": "Could not update pairing details. Try again.",
+  "pair.tailscale.open": "Share with Tailscale",
+  "pair.tailscale.opening": "Enabling Tailscale Serve…",
+  "pair.tailscale.title": "Tailscale",
+  "pair.tailscale.description": "Use Tailscale Serve to share this server over HTTPS with devices on your tailnet.",
+  "pair.tailscale.checking": "Checking Tailscale Serve…",
+  "pair.tailscale.inactive": "This server is not shared with Tailscale yet.",
+  "pair.tailscale.error": "Could not load Tailscale Serve status. Try again.",
+  "pair.tailscale.disable": "Disable",
+  "pair.tailscale.disabling": "Disabling Tailscale Serve…",
  "dialog.server.edit.title": "Edit server",
  "dialog.server.default.title": "Default server",
  "dialog.server.default.description":
@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test"
-import { createDraftStore, draftTextChunk, draftTextThreshold, resolveBlobUrl } from "./drafts"
+import { createDraftStore, draftTextChunk, draftTextThreshold } from "./drafts"

 function memoryDriver() {
  const documents = new Map<string, string>()
@@ -287,34 +287,15 @@ describe("draft store image retention", () => {
    expect(await released(store, 5, shared.url)).toBe(true)
  })

-  test("loading a document pins the images it references without fetching their bytes", async () => {
+  test("loading a document pins the images it references", async () => {
    const { memory, store } = fresh()
-    const reads: string[] = []
-    const getBlob = memory.driver.getBlob
-    memory.driver.getBlob = (id) => {
-      reads.push(id)
-      return getBlob(id)
-    }
    const id = await memory.driver.putBlob(image(6))
    memory.documents.set("loaded", JSON.stringify({ prompt: [{ type: "image", blob: { id } }] }))
-    const loaded = JSON.parse((await store.getItem("loaded"))!).prompt[0].blob
-    expect(loaded).toEqual({ id })
-    expect(reads).toEqual([])
-    // The first consumer that shows or sends the image loads it; the pin from the load keeps it.
-    const url = (await resolveBlobUrl(loaded))!
-    expect(url.startsWith("blob:")).toBe(true)
-    expect(reads).toEqual([id])
-    expect(await resolveBlobUrl(loaded)).toBe(url)
-    expect(reads).toEqual([id])
+    const url = JSON.parse((await store.getItem("loaded"))!).prompt[0].blob.url
    await tick()
    expect(await released(store, 6, url)).toBe(false)
    await store.removeItem("loaded")
    await tick()
    expect(await released(store, 6, url)).toBe(true)
  })
-
-  test("a reference to bytes the store no longer holds resolves to nothing", async () => {
-    fresh()
-    expect(await resolveBlobUrl({ id: "gone" })).toBeUndefined()
-  })
 })
@@ -42,18 +42,6 @@ const refs = new Map<string, Set<string>>()
 // Image ids that were restored under a different id (a store without WebCrypto assigns fresh
 // ones); live references still carry the original.
 const aliases = new Map<string, string>()
-// Fetches image bytes from the store created last. Documents load without their bytes; a consumer
-// that renders or sends an image resolves its URL through here, so a history full of large
-// attachments costs nothing at startup.
-let loader: ((id: string) => Promise<string | undefined>) | undefined
-
-/** The object URL for an image reference, loading its bytes from the draft store on first use. */
-export function resolveBlobUrl(blob: { id: string; url?: string }) {
-  if (blob.url) return Promise.resolve(blob.url)
-  const existing = retained.get(aliases.get(blob.id) ?? blob.id)
-  if (existing) return Promise.resolve(existing.url)
-  return loader?.(blob.id) ?? Promise.resolve(undefined)
-}

 function blobUrl(id: string, blob: Blob, grace?: number) {
  const existing = retained.get(id)
@@ -132,7 +120,7 @@ export function createDraftStore(driver: Driver, options: { grace?: number } = {
  const loading = new Map<string, Promise<string | undefined>>()
  const loadBlobUrl = (id: string) => {
    const existing = retained.get(id)
-    if (existing) return Promise.resolve(existing.url)
+    if (existing) return existing.url
    const pending = loading.get(id)
    if (pending) return pending
    const next = driver
@@ -142,7 +130,6 @@ export function createDraftStore(driver: Driver, options: { grace?: number } = {
    loading.set(id, next)
    return next
  }
-  loader = loadBlobUrl
  const putBlob = async (blob: Blob) => {
    const id = await driver.putBlob(blob)
    return { id, url: blobUrl(id, blob, grace) }
@@ -234,11 +221,9 @@ export function createDraftStore(driver: Driver, options: { grace?: number } = {
      if (ref.kind === "text" && Array.isArray(ref.ids)) {
        return (await Promise.all(ref.ids.map((id) => loadChunk(String(id))))).join("")
      }
-      // Bytes stay in the store until something renders or sends the image (see resolveBlobUrl);
-      // only an image already pinned in this page gets its URL back immediately.
      if (typeof ref.id === "string") {
-        const url = retained.get(aliases.get(ref.id) ?? ref.id)?.url
-        return { ...item, blob: url ? { id: ref.id, url } : { id: ref.id } }
+        const url = await loadBlobUrl(ref.id)
+        if (url) return { ...item, blob: { id: ref.id, url } }
      }
    }
    return Object.fromEntries(
@@ -438,9 +423,7 @@ function referenced(json: string) {

 export async function blobDataUrl(blob: BlobReference, mime: string) {
  const kept = retained.get(aliases.get(blob.id) ?? blob.id)
-  const url = kept ? undefined : await resolveBlobUrl(blob)
-  if (!kept && !url) throw new Error(`Attachment ${blob.id} has no stored bytes`)
-  const data = kept ? kept.blob : await fetch(url!).then((response) => response.blob())
+  const data = kept ? kept.blob : await fetch(blob.url).then((response) => response.blob())
  return new Promise<string>((resolve, reject) => {
    const reader = new FileReader()
    reader.addEventListener("error", () => reject(reader.error))
@@ -22,6 +22,12 @@ type SaveFilePickerOptions = { title?: string; defaultPath?: string }
 type PlatformName = "web" | "desktop"
 type DesktopOS = "macos" | "windows" | "linux"

+export type PairingInfo = {
+  readonly urls: readonly string[]
+  readonly username: "opencode"
+  readonly password: string
+}
+
 export type FatalRendererErrorLog = {
  error: string
  url: string
@@ -101,6 +107,10 @@ type PlatformBase = {
  /** Allow native pinch/Ctrl-scroll zoom gestures (desktop only) */
  setPinchZoomEnabled?(enabled: boolean): Promise<void> | void

+  /** Prevent the local display from sleeping while the desktop app is running. */
+  getKeepScreenActive?(): Promise<boolean>
+  setKeepScreenActive?(enabled: boolean): Promise<void>
+
  /** Run a desktop-only menu action from the app chrome */
  runDesktopMenuAction?(action: DesktopMenuAction): Promise<void> | void

@@ -124,6 +134,15 @@ type PlatformBase = {

  /** Native browser pane hosted by the platform (desktop only). */
  browserPane?: BrowserPanePlatform
+
+  /** Pair another device with the local desktop server. */
+  pair?: {
+    info(): Promise<PairingInfo>
+    tailscaleAvailable(): Promise<boolean>
+    tailscaleStatus(): Promise<PairingInfo | null>
+    openTailscale(): Promise<PairingInfo>
+    disableTailscale(): Promise<void>
+  }
 }

 export type Platform = PlatformBase &
@@ -7,6 +7,10 @@ export function isMixedContent(page: string, address: string) {
  const url = new URL(normalized)
  if (url.protocol !== "http:") return false
  // Secure Contexts treats loopback HTTP origins as potentially trustworthy.
+  return !isLoopback(url)
+}
+
+export function isLoopback(url: URL) {
  const host = url.hostname.replace(/\.$/, "")
-  return !(host === "localhost" || host.endsWith(".localhost") || host === "[::1]" || /^127(?:\.\d+){3}$/.test(host))
+  return host === "localhost" || host.endsWith(".localhost") || host === "[::1]" || /^127(?:\.\d+){3}$/.test(host)
 }
@@ -0,0 +1,86 @@
+import { describe, expect, test } from "bun:test"
+import { decodePairingCode, decodePairingScan, decodePairingUrl, pairingUrl } from "./pairing"
+
+describe("pairing URL", () => {
+  test("pairs with the current origin using credentials without server URLs", () => {
+    const info = { username: "opencode" as const, password: "a+b & café" }
+    const origin = "https://computer.tailnet.ts.net:49709"
+    const url = new URL(pairingUrl(info, origin))
+
+    expect(url.origin).toBe(origin)
+    expect(url.pathname).toBe("/connect")
+    expect(JSON.parse(url.searchParams.get("data") ?? "")).toEqual(info)
+    expect(decodePairingUrl(url.search, origin)).toEqual({ urls: [origin], password: info.password })
+    expect(decodePairingCode(JSON.stringify(info))).toBeUndefined()
+  })
+
+  test("encodes the pairing JSON in the data query parameter and decodes it", () => {
+    const info = {
+      urls: ["http://192.168.1.2:4096"],
+      username: "opencode" as const,
+      password: "a+b & café",
+    }
+    const url = new URL(pairingUrl(info, "https://example.com"))
+
+    expect(url.origin).toBe("https://example.com")
+    expect(url.pathname).toBe("/connect")
+    expect(url.searchParams.get("data")).toBe(JSON.stringify(info))
+    expect(decodePairingUrl(url.search)).toEqual({
+      urls: ["http://192.168.1.2:4096"],
+      password: "a+b & café",
+    })
+  })
+
+  test("defaults to the hosted app for desktop pairing", () => {
+    expect(new URL(pairingUrl({ urls: [], username: "opencode", password: "secret" })).origin).toBe(
+      "https://app.opencode.ai",
+    )
+  })
+
+  test("accepts CLI base64url fragments", () => {
+    const value = { urls: ["http://localhost:4096"], username: "opencode", password: "a+b & café" }
+    expect(decodePairingUrl(`#${Buffer.from(JSON.stringify(value)).toString("base64url")}`)).toEqual({
+      urls: value.urls,
+      password: value.password,
+    })
+  })
+
+  test("rejects invalid query data", () => {
+    expect(decodePairingUrl("?data=invalid")).toBeUndefined()
+    expect(decodePairingUrl("?other=value")).toBeUndefined()
+  })
+
+  test("accepts legacy JSON fragments", () => {
+    const value = { urls: ["http://localhost:4096"], username: "opencode", password: "secret" }
+    expect(decodePairingUrl(`#${encodeURIComponent(JSON.stringify(value))}`)).toEqual({
+      urls: value.urls,
+      password: value.password,
+    })
+  })
+
+  test("rejects an invalid fragment", () => {
+    expect(decodePairingUrl("#not-a-pairing-code")).toBeUndefined()
+  })
+})
+
+describe("pairing scan", () => {
+  const info = {
+    urls: ["http://192.168.1.2:49374", "http://127.0.0.1:49374"],
+    username: "opencode" as const,
+    password: "a+b & café",
+  }
+  const decoded = { urls: info.urls, password: info.password }
+
+  test("decodes raw JSON, desktop query links, and the CLI fragment link", () => {
+    expect(decodePairingScan(JSON.stringify(info))).toEqual(decoded)
+    expect(decodePairingScan(pairingUrl(info, "http://192.168.1.2:49374"))).toEqual(decoded)
+    const encoded = Buffer.from(JSON.stringify(info)).toString("base64url")
+    expect(decodePairingScan(`https://app.opencode.ai/connect#${encoded}`)).toEqual(decoded)
+  })
+
+  test("rejects URLs without pairing data and non-http schemes", () => {
+    expect(decodePairingScan("http://192.168.1.2:49374/connect")).toBeUndefined()
+    expect(decodePairingScan("opencode-ios://connect?password=secret")).toBeUndefined()
+    expect(decodePairingScan("not a code")).toBeUndefined()
+  })
+})
@@ -3,7 +3,7 @@ import { normalizeServerUrl } from "@/runtime/server/registry"

 const pairing = Schema.fromJsonString(
  Schema.Struct({
-    urls: Schema.Array(Schema.String),
+    urls: Schema.optional(Schema.Array(Schema.String)),
    username: Schema.Literal("opencode"),
    password: Schema.String,
  }),
@@ -19,10 +19,46 @@ export function serverAddress(value: string) {
  return normalized
 }

-export function decodePairingCode(value: string) {
+export function decodePairingCode(value: string, origin?: string) {
  const result = Schema.decodeUnknownOption(pairing)(value)
  if (Option.isNone(result)) return
-  const urls = [...new Set(result.value.urls.map(serverAddress).filter((url) => url !== undefined))]
+  const urls = [
+    ...new Set(
+      (result.value.urls ?? (origin ? [origin] : [])).map(serverAddress).filter((url) => url !== undefined),
+    ),
+  ]
  if (!urls.length) return
  return { urls, password: result.value.password }
 }
+
+export function pairingUrl(
+  value: { urls?: readonly string[]; username: "opencode"; password: string },
+  host = "https://app.opencode.ai",
+) {
+  return `${new URL("/connect", host)}?data=${encodeURIComponent(JSON.stringify(value))}`
+}
+
+export function decodePairingScan(value: string) {
+  const url = URL.parse(value)
+  if (!url || (url.protocol !== "http:" && url.protocol !== "https:")) return decodePairingCode(value)
+  return decodePairingUrl(url.search, url.origin) ?? decodePairingUrl(url.hash)
+}
+
+export function decodePairingUrl(value: string, origin?: string) {
+  if (value.startsWith("?")) {
+    const data = new URLSearchParams(value).get("data")
+    return data === null ? undefined : decodePairingCode(data, origin)
+  }
+  const encoded = value.startsWith("#") ? value.slice(1) : value
+  if (!encoded) return
+  const legacy = new URLSearchParams(`value=${encoded}`).get("value") ?? ""
+  if (legacy.startsWith("{")) return decodePairingCode(legacy)
+  if (!/^[A-Za-z0-9_-]+$/.test(encoded) || encoded.length % 4 === 1) return
+  const binary = atob(
+    encoded
+      .replaceAll("-", "+")
+      .replaceAll("_", "/")
+      .padEnd(Math.ceil(encoded.length / 4) * 4, "="),
+  )
+  return decodePairingCode(new TextDecoder().decode(Uint8Array.from(binary, (char) => char.charCodeAt(0))))
+}
@@ -3,11 +3,11 @@ import { onCleanup, onMount, Show } from "solid-js"
 import { createStore } from "solid-js/store"
 import { Button } from "@opencode/ui/button"
 import { useLanguage } from "@/runtime/i18n/language"
-import { decodePairingCode } from "./pairing"
+import { decodePairingScan } from "./pairing"
 import "./scanner.css"

 export function PairingScanner(props: {
-  onScan: (value: NonNullable<ReturnType<typeof decodePairingCode>>) => void
+  onScan: (value: NonNullable<ReturnType<typeof decodePairingScan>>) => void
  onCancel: () => void
 }) {
  const language = useLanguage()
@@ -22,7 +22,7 @@ export function PairingScanner(props: {
    const scanner = new QrScanner(
      video,
      (result) => {
-        const pairing = decodePairingCode(result.data)
+        const pairing = decodePairingScan(result.data)
        if (!pairing) {
          setState("error", language.t("server.connect.scan.invalid"))
          return
@@ -9,19 +9,28 @@ import { usePlatform } from "@/runtime/platform/platform"
 import { useCheckServerHealth } from "@/runtime/server/health"
 import { useServers } from "@/runtime/server/registry"
 import { serverAddress } from "./pairing"
-import { isMixedContent } from "./browser"
+import type { decodePairingCode } from "./pairing"
+import { isLoopback, isMixedContent } from "./browser"
 import { createCameraAvailability } from "./camera"
 import "./screen.css"

 const PairingScanner = lazy(() => import("./scanner").then((module) => ({ default: module.PairingScanner })))

-export function ConnectServerScreen() {
+export function ConnectServerScreen(
+  props: { pairing?: NonNullable<ReturnType<typeof decodePairingCode>>; onConnect?: () => void } = {},
+) {
  const language = useLanguage()
  const platform = usePlatform()
  const servers = useServers()
  const check = useCheckServerHealth()
  const camera = createCameraAvailability()
-  const [state, setState] = createStore({ url: "", password: "", urls: [] as string[], error: "", scanning: false })
+  const [state, setState] = createStore({
+    url: props.pairing?.urls[0] ?? "",
+    password: props.pairing?.password ?? "",
+    urls: props.pairing?.urls ?? ([] as string[]),
+    error: "",
+    scanning: false,
+  })
  const connectionError = () =>
    language.t(
      platform.platform === "web" && isMixedContent(location.href, state.url)
@@ -42,6 +51,7 @@ export function ConnectServerScreen() {
        return
      }
      servers.add({ type: "http", http })
+      props.onConnect?.()
    },
    onError: () => setState("error", connectionError()),
  }))
@@ -164,3 +174,37 @@ export function ConnectServerScreen() {
    </main>
  )
 }
+
+export function ConnectLocalScreen(props: { urls: readonly string[] }) {
+  const language = useLanguage()
+  const target = props.urls[0]
+  const loopback = isLoopback(new URL(target))
+  return (
+    <main data-component="connect-server" aria-labelledby="server-connect-title">
+      <div class="server-connect-content">
+        <div class="server-connect-brand" role="img" aria-label="OpenCode">
+          <Wordmark />
+        </div>
+        <header>
+          <h1 id="server-connect-title">
+            {language.t(loopback ? "server.connect.local.loopback.title" : "server.connect.local.title")}
+          </h1>
+          <p>{language.t(loopback ? "server.connect.local.loopback.description" : "server.connect.local.description")}</p>
+        </header>
+        <Button
+          variant="contrast"
+          size="large"
+          onClick={() => location.assign(`${new URL("/connect", target)}${location.search}${location.hash}`)}
+        >
+          {language.t(loopback ? "server.connect.local.loopback.open" : "server.connect.local.open")}
+        </Button>
+        <footer>
+          <Show when={loopback}>
+            <p>{language.t("server.connect.local.loopback.fix")}</p>
+          </Show>
+          <code dir="ltr">{loopback ? "opencode service set hostname 0.0.0.0" : target}</code>
+        </footer>
+      </div>
+    </main>
+  )
+}
@@ -7,6 +7,7 @@ export const pageIcons = {
  appearance: "appearance",
  notifications: "notifications",
  shortcuts: "keyboard",
+  pairing: "server",
  projects: "folder",
  workspaces: "outline-worktree",
  providers: "providers",
@@ -22,6 +23,7 @@ export const pageLabels = {
  appearance: "settings.general.section.appearance",
  notifications: "settings.tab.notifications",
  shortcuts: "settings.shortcuts.title",
+  pairing: "settings.pairing.title",
  projects: "settings.tab.projects",
  workspaces: "settings.tab.workspaces",
  providers: "settings.providers.title",
@@ -0,0 +1,303 @@
+import { Button } from "@opencode/ui/button"
+import { useDialog } from "@opencode/ui/context/dialog"
+import { Dialog, DialogBody, DialogHeader, DialogTitleGroup } from "@opencode/ui/dialog"
+import { Icon } from "@opencode/ui/icon"
+import { Switch } from "@opencode/ui/switch"
+import { Tooltip } from "@opencode/ui/tooltip"
+import { useMutation, useQuery, useQueryClient } from "@tanstack/solid-query"
+import { createEffect, createMemo, onCleanup, Show } from "solid-js"
+import { renderSVG } from "uqr"
+import { useLanguage } from "@/runtime/i18n/language"
+import { usePlatform, type PairingInfo } from "@/runtime/platform/platform"
+import { pairingUrl } from "@/servers/connect/pairing"
+import { SettingsList } from "@/settings/list"
+import { SettingsRow } from "@/settings/row"
+
+export function SettingsPairing() {
+  const language = useLanguage()
+  const dialog = useDialog()
+  const platform = usePlatform()
+  const queryClient = useQueryClient()
+  const pair = platform.pair
+  if (!pair) return null
+  const local = useQuery(() => ({
+    queryKey: ["pairing", "local"],
+    queryFn: pair.info,
+  }))
+  // Reading pending query data would suspend the entire settings surface.
+  const localInfo = () => (local.isSuccess ? local.data : undefined)
+  const localHost = createMemo(() =>
+    localInfo()?.urls.find((value) => {
+      const host = new URL(value).hostname
+      return (
+        host !== "localhost" &&
+        !host.endsWith(".localhost") &&
+        !host.startsWith("127.") &&
+        host !== "[::1]" &&
+        host !== "0.0.0.0" &&
+        host !== "[::]"
+      )
+    }),
+  )
+  const screenActive = useQuery(() => ({
+    queryKey: ["pairing", "screen-active"],
+    queryFn: () => platform.getKeepScreenActive!(),
+    enabled: !!platform.getKeepScreenActive,
+  }))
+  const screenActivity = useMutation(() => ({
+    mutationFn: async (enabled: boolean) => platform.setKeepScreenActive?.(enabled),
+    onSuccess: (_, enabled) => queryClient.setQueryData(["pairing", "screen-active"], enabled),
+  }))
+  const tailscale = useQuery(() => ({
+    queryKey: ["pairing", "tailscale-available"],
+    queryFn: pair.tailscaleAvailable,
+  }))
+  const tailscaleStatus = useQuery(() => ({
+    queryKey: ["pairing", "tailscale-status"],
+    queryFn: pair.tailscaleStatus,
+    enabled: tailscale.isSuccess && tailscale.data === true,
+  }))
+  const tailscaleServe = useMutation(() => ({
+    mutationFn: pair.openTailscale,
+    onSuccess: (value) => queryClient.setQueryData(["pairing", "tailscale-status"], value),
+  }))
+  const tailscaleDisable = useMutation(() => ({
+    mutationFn: pair.disableTailscale,
+    onSuccess: () => queryClient.setQueryData(["pairing", "tailscale-status"], null),
+  }))
+  const tailscaleInfo = () => (tailscaleStatus.isSuccess ? tailscaleStatus.data : undefined)
+
+  return (
+    <>
+      <div class="settings-tab-header">
+        <div class="settings-tab-header-row">
+          <div class="flex flex-col gap-1">
+            <h2 class="settings-tab-title">{language.t("settings.pairing.title")}</h2>
+            <span class="text-11-regular text-v2-text-text-muted">{language.t("pair.description")}</span>
+          </div>
+        </div>
+      </div>
+
+      <div class="settings-tab-body settings-tab-body--sectioned">
+        <section class="settings-section" aria-label={language.t("settings.pairing.connection")}>
+          <SettingsList>
+            <SettingsRow
+              title={language.t("settings.pairing.connection")}
+              description={language.t("pair.local.description")}
+            >
+              <Button
+                variant="neutral"
+                disabled={!localHost()}
+                onClick={() =>
+                  dialog.push(() => (
+                    <DialogPairing
+                      title={language.t("settings.pairing.connection")}
+                      info={localInfo()}
+                      host={localHost()}
+                    />
+                  ))
+                }
+              >
+                {language.t("pair.local.open")}
+              </Button>
+            </SettingsRow>
+            <Show when={platform.getKeepScreenActive && platform.setKeepScreenActive}>
+              <div data-action="settings-keep-screen-active">
+                <SettingsRow
+                  title={language.t("pair.screenActive.title")}
+                  description={language.t("pair.screenActive.description")}
+                >
+                  <Switch
+                    hideLabel
+                    checked={screenActive.isSuccess && screenActive.data}
+                    disabled={screenActive.isPending || !!screenActive.error || screenActivity.isPending}
+                    onChange={(enabled) => screenActivity.mutate(enabled)}
+                  >
+                    {language.t("pair.screenActive.title")}
+                  </Switch>
+                </SettingsRow>
+              </div>
+            </Show>
+          </SettingsList>
+          <Show when={screenActive.error || screenActivity.error}>
+            <p class="text-text-danger-base" role="alert">
+              {language.t("pair.screenActive.error")}
+            </p>
+          </Show>
+          <Show when={local.error}>
+            <p class="text-text-danger-base" role="alert">
+              {language.t("pair.error")}
+            </p>
+          </Show>
+        </section>
+
+        <Show when={tailscale.isSuccess && tailscale.data === true}>
+          <section class="settings-section" aria-label={language.t("pair.tailscale.title")}>
+            <Show
+              when={tailscaleInfo()}
+              fallback={
+                <>
+                  <h3 class="settings-section-title">{language.t("pair.tailscale.title")}</h3>
+                  <SettingsList>
+                    <div class="flex min-h-24 flex-col items-center justify-center gap-3 px-4 py-6">
+                      <Button
+                        variant="neutral"
+                        disabled={!localInfo() || tailscaleStatus.isPending || tailscaleServe.isPending}
+                        aria-busy={tailscaleServe.isPending}
+                        onClick={() => tailscaleServe.mutate()}
+                      >
+                        <svg class="size-4 shrink-0" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+                          <g opacity="0.3">
+                            <circle cx="3" cy="3" r="3" />
+                            <circle cx="12" cy="3" r="3" />
+                            <circle cx="21" cy="3" r="3" />
+                            <circle cx="3" cy="21" r="3" />
+                            <circle cx="21" cy="21" r="3" />
+                          </g>
+                          <circle cx="3" cy="12" r="3" />
+                          <circle cx="12" cy="12" r="3" />
+                          <circle cx="21" cy="12" r="3" />
+                          <circle cx="12" cy="21" r="3" />
+                        </svg>
+                        {language.t(tailscaleServe.isPending ? "pair.tailscale.opening" : "pair.tailscale.enable")}
+                      </Button>
+                      <span class="text-center text-[13px] leading-text-base text-v2-text-text-muted">
+                        {language.t("pair.tailscale.description")}
+                      </span>
+                    </div>
+                  </SettingsList>
+                </>
+              }
+            >
+              <h3 class="settings-section-title">{language.t("pair.tailscale.title")}</h3>
+              <SettingsList>
+                <SettingsRow
+                  title={language.t("pair.tailscale.serve")}
+                  description={language.t("pair.tailscale.description")}
+                >
+                  <div class="flex flex-col items-end gap-2">
+                    <Button
+                      variant="neutral"
+                      disabled={!tailscaleInfo() || tailscaleDisable.isPending}
+                      onClick={() =>
+                        dialog.push(() => (
+                          <DialogPairing
+                            title={language.t("pair.tailscale.title")}
+                            info={tailscaleInfo()}
+                            host={tailscaleInfo()?.urls[0]}
+                          />
+                        ))
+                      }
+                    >
+                      {language.t("pair.qr.open")}
+                    </Button>
+                    <Button
+                      variant="neutral"
+                      disabled={
+                        !localInfo() ||
+                        tailscaleStatus.isPending ||
+                        tailscaleServe.isPending ||
+                        tailscaleDisable.isPending
+                      }
+                      onClick={() => tailscaleDisable.mutate()}
+                    >
+                      {language.t("pair.tailscale.disable")}
+                    </Button>
+                  </div>
+                </SettingsRow>
+              </SettingsList>
+            </Show>
+            <Show when={tailscaleStatus.error || tailscaleServe.error || tailscaleDisable.error}>
+              <p class="text-text-danger-base" role="alert">
+                {language.t("pair.tailscale.error")}
+              </p>
+            </Show>
+          </section>
+        </Show>
+      </div>
+    </>
+  )
+}
+
+function DialogPairing(props: { title: string; info: PairingInfo | null | undefined; host?: string }) {
+  const language = useLanguage()
+  const platform = usePlatform()
+  const url = createMemo(() => {
+    if (!props.info) return
+    const host = props.host ?? (platform.platform === "web" ? location.origin : undefined)
+    return pairingUrl(
+      {
+        urls: host ? [host] : props.info.urls.slice(0, 1),
+        username: props.info.username,
+        password: props.info.password,
+      },
+      host,
+    )
+  })
+  const origin = createMemo(() => {
+    const value = url()
+    if (!value) return
+    return new URL(value).origin
+  })
+  const copy = useMutation(() => ({
+    mutationFn: async () => {
+      const value = url()
+      if (!value) return
+      await (platform.writeClipboardText?.(value) ?? navigator.clipboard.writeText(value))
+    },
+  }))
+  createEffect(() => {
+    if (!copy.isSuccess) return
+    const timeout = setTimeout(() => copy.reset(), 2000)
+    onCleanup(() => clearTimeout(timeout))
+  })
+  const qr = createMemo(() => {
+    const value = url()
+    if (!value) return
+    return renderSVG(value, { border: 4, blackColor: "currentColor", whiteColor: "transparent" })
+  })
+
+  return (
+    <Dialog fit containerClass="max-w-[min(400px,calc(100vw-32px),calc(100dvh-180px))]">
+      <DialogHeader>
+        <DialogTitleGroup title={props.title} description={language.t("pair.description")} />
+      </DialogHeader>
+      <DialogBody class="flex flex-col gap-4 px-4 pb-4">
+        <Show when={props.info}>
+          <div
+            class="aspect-square w-full shrink-0 rounded-[6px] bg-v2-background-bg-base p-6 text-v2-text-text-base [&>svg]:size-full"
+            role="img"
+            aria-label={language.t("pair.qr")}
+            innerHTML={qr()}
+          />
+          <div class="flex min-w-0 justify-center pb-2">
+            <Tooltip
+              class="min-w-0 max-w-full"
+              value={language.t(copy.isSuccess ? "common.copied" : "pair.copy")}
+              placement="top"
+              forceOpen={copy.isSuccess ? true : undefined}
+            >
+              <button
+                type="button"
+                class="inline-flex min-h-8 max-w-full select-none items-center justify-center gap-2 rounded-[6px] px-2 py-1 text-[13px] font-[440] leading-text-compact tracking-[-0.04px] text-v2-text-text-muted transition-colors hover:bg-v2-background-bg-layer-02 hover:text-v2-text-text-base focus-visible:bg-v2-background-bg-layer-02 focus-visible:outline-none disabled:opacity-50"
+                disabled={copy.isPending}
+                aria-label={language.t("pair.copy")}
+                onClick={() => copy.mutate()}
+              >
+                <Icon name={copy.isSuccess ? "check" : "copy"} size="small" class="shrink-0" />
+                <bdi dir="ltr" class="min-w-0 break-all text-start">
+                  {origin()}
+                </bdi>
+              </button>
+            </Tooltip>
+          </div>
+        </Show>
+        <Show when={copy.error}>
+          <p class="text-text-danger-base" role="alert">
+            {language.t("pair.copy.error")}
+          </p>
+        </Show>
+      </DialogBody>
+    </Dialog>
+  )
+}
@@ -20,6 +20,20 @@ export const clientSettings: Entry<SettingsRootTab>[] = [
  { tab: "appearance", label: "settings.general.section.appearance" },
  { tab: "notifications", label: "settings.tab.notifications" },
  { tab: "shortcuts", label: "settings.shortcuts.title", keywords: "keybind keyboard hotkey" },
+  {
+    tab: "pairing",
+    label: "settings.pairing.title",
+    keywords: "pair device qr tailscale",
+    available: "desktop",
+  },
+  {
+    tab: "pairing",
+    label: "pair.screenActive.title",
+    description: "pair.screenActive.description",
+    target: "settings-keep-screen-active",
+    keywords: "display sleep awake local",
+    available: "desktop",
+  },
  { tab: "experimental", label: "settings.tab.experimental" },
  { tab: "about", label: "settings.tab.about", keywords: "version license credits" },
  { tab: "general", label: "settings.general.row.language.title", target: "settings-language" },
@@ -3,6 +3,7 @@ import { useDialog } from "@opencode/ui/context/dialog"
 import { createEffect, createMemo, on, onCleanup, onMount, Show, Switch, Match, type Accessor } from "solid-js"
 import { createStore } from "solid-js/store"
 import { useLanguage } from "@/runtime/i18n/language"
+import { usePlatform } from "@/runtime/platform/platform"
 import { useLayout } from "@/shell/state/layout"
 import { useTabs } from "@/shell/tabs/tabs"
 import { displayName } from "@/shell/layout/helpers"
@@ -18,6 +19,7 @@ import { SettingsAppearance } from "./appearance/appearance"
 import { SettingsExperimental } from "./experimental/experimental"
 import { SettingsKeybinds } from "./keybinds/keybinds"
 import { SettingsNotifications } from "./notifications/notifications"
+import { SettingsPairing } from "./pairing/pairing"
 import { SettingsProviders } from "./providers/providers"
 import { SettingsModels } from "./models/models"
 import { SettingsServerGeneral } from "./servers/servers"
@@ -41,6 +43,7 @@ const rootClientTabs = [
  { value: "appearance", icon: pageIcons.appearance, label: "settings.general.section.appearance" },
  { value: "notifications", icon: pageIcons.notifications, label: "settings.tab.notifications" },
  { value: "shortcuts", icon: pageIcons.shortcuts, label: "settings.tab.shortcuts" },
+  { value: "pairing", icon: pageIcons.pairing, label: "settings.pairing.title" },
 ] as const

 const serverTabs = [
@@ -187,6 +190,7 @@ function RootSettings() {
  const tabs = useTabs()
  const servers = useServerCollectionController()
  const inventory = useSettingsServers()
+  const platform = usePlatform()
  const [state, setState] = createStore({ worktreeFilterReset: 0 })
  const list = servers.collection.items
  const singleEntry = createMemo(() => (inventory().length === 1 ? inventory()[0] : undefined))
@@ -216,7 +220,11 @@ function RootSettings() {
      <DialogServer mode="add" onSave={(server) => surface.openServer(ServerConnection.key(server))} />
    ))
  const groups = createMemo<SettingsNavGroup[]>(() => [
-    { items: rootClientTabs.map((item) => ({ ...item, label: language.t(item.label) })) },
+    {
+      items: rootClientTabs
+        .filter((item) => item.value !== "pairing" || !!platform.pair)
+        .map((item) => ({ ...item, label: language.t(item.label) })),
+    },
    ...(multiple()
      ? [
          {
@@ -282,6 +290,9 @@ function RootSettings() {
      <Tabs.Content value="shortcuts" class="settings-panel">
        <SettingsKeybinds active={surface.view().tab === "shortcuts"} autofocus={!surface.search.state.selected} />
      </Tabs.Content>
+      <Tabs.Content value="pairing" class="settings-panel">
+        <SettingsPairing />
+      </Tabs.Content>
      <Tabs.Content value="experimental" class="settings-panel">
        <SettingsExperimental />
      </Tabs.Content>
@@ -11,6 +11,7 @@ export type SettingsRootTab =
  | "appearance"
  | "notifications"
  | "shortcuts"
+  | "pairing"
  | "projects"
  | "workspaces"
  | "providers"
@@ -44,6 +45,7 @@ const rootTabs: Record<SettingsRootTab, true> = {
  appearance: true,
  notifications: true,
  shortcuts: true,
+  pairing: true,
  projects: true,
  workspaces: true,
  providers: true,
@@ -4,6 +4,7 @@ import { useCommand, type CommandOption } from "./command"
 import { useDialog } from "@opencode/ui/context/dialog"
 import { DialogSsh } from "@/servers/ssh/dialog"
 import { useUpdaterAction } from "@/shell/updates/action"
+import { useSettingsSurface } from "@/settings/surface"

 export function DesktopCommands() {
  const command = useCommand()
@@ -40,3 +41,25 @@ export function DesktopCommands() {

  return null
 }
+
+export function DesktopPairingCommand() {
+  const command = useCommand()
+  const language = useLanguage()
+  const platform = usePlatform()
+  const settings = useSettingsSurface()
+
+  command.register("desktop-pairing", () =>
+    platform.platform === "desktop" && platform.pair
+      ? [
+          {
+            id: "server.pair",
+            title: language.t("command.server.pair"),
+            category: language.t("command.category.server"),
+            onSelect: () => settings.open("pairing"),
+          },
+        ]
+      : [],
+  )
+
+  return null
+}
@@ -1,5 +1,5 @@
-import { Route, useParams } from "@solidjs/router"
-import { createMemo, lazy, Show, Suspense, type ParentProps } from "solid-js"
+import { Route, useNavigate, useParams } from "@solidjs/router"
+import { createMemo, lazy, onMount, Show, Suspense, type ParentProps } from "solid-js"
 import { Home } from "@/home/route"
 import { ServerProvider } from "@/runtime/server/current"
 import { useGlobal } from "@/runtime/server/runtime"
@@ -10,6 +10,8 @@ import { LayoutProvider } from "@/shell/state/layout"
 import { SettingsSurfaceProvider } from "@/settings/surface"
 import Shell from "@/shell/shell"
 import { requireServerKey } from "./session"
+import { decodePairingUrl } from "@/servers/connect/pairing"
+import { DesktopPairingCommand } from "@/shell/commands/desktop"

 export const File = lazy(() => import("@opencode/session-ui/file").then((module) => ({ default: module.File })))
 const loadSessionRoute = () => Promise.all([import("@/session/route"), File.preload()]).then(([module]) => module)
@@ -18,6 +20,9 @@ const SettingsScreen = lazy(() => import("@/settings/shell").then((module) => ({
 const ConnectServerScreen = lazy(() =>
  import("@/servers/connect/screen").then((module) => ({ default: module.ConnectServerScreen })),
 )
+const ConnectLocalScreen = lazy(() =>
+  import("@/servers/connect/screen").then((module) => ({ default: module.ConnectLocalScreen })),
+)
 const TargetSessionRouteContent = lazy(() =>
  loadSessionRoute().then((module) => ({ default: module.TargetSessionRouteContent })),
 )
@@ -26,6 +31,7 @@ export function preloadRoute(url: string) {
  const pathname = url.split(/[?#]/, 1)[0]
  if (pathname === "/new-session") return DraftRoute.preload().then(() => undefined)
  if (pathname === "/settings") return SettingsScreen.preload().then(() => undefined)
+  if (pathname === "/connect") return ConnectServerScreen.preload().then(() => undefined)
  if (/^\/server\/[^/]+\/session\/[^/]+$/.test(pathname))
    return TargetSessionRouteContent.preload().then(() => undefined)
  return Promise.resolve()
@@ -33,32 +39,53 @@ export function preloadRoute(url: string) {

 export function AppRoutes() {
  return (
-    <Route component={AppLayout}>
-      <Route path="/" component={Home} />
-      <Route path="/settings" component={SettingsScreen} />
-      <Route
-        path="/server/:serverKey/session/:id"
-        component={() => (
-          <SessionRouteFrame>
-            <Suspense
-              fallback={
-                <div class="flex min-h-0 flex-1 px-2 pb-[var(--shell-bottom-inset,8px)] pt-[var(--shell-top-inset,8px)]">
-                  <SessionPanelFrame raised />
-                </div>
-              }
-            >
-              <TargetServerRoute>
-                <TargetSessionRouteContent />
-              </TargetServerRoute>
-            </Suspense>
-          </SessionRouteFrame>
-        )}
-      />
-      <Route path="/new-session" component={DraftRoute} />
-    </Route>
+    <>
+      <Route path="/connect" component={ConnectRoute} />
+      <Route component={AppLayout}>
+        <Route path="/" component={Home} />
+        <Route path="/settings" component={SettingsScreen} />
+        <Route
+          path="/server/:serverKey/session/:id"
+          component={() => (
+            <SessionRouteFrame>
+              <Suspense
+                fallback={
+                  <div class="flex min-h-0 flex-1 px-2 pb-[var(--shell-bottom-inset,8px)] pt-[var(--shell-top-inset,8px)]">
+                    <SessionPanelFrame raised />
+                  </div>
+                }
+              >
+                <TargetServerRoute>
+                  <TargetSessionRouteContent />
+                </TargetServerRoute>
+              </Suspense>
+            </SessionRouteFrame>
+          )}
+        />
+        <Route path="/new-session" component={DraftRoute} />
+      </Route>
+    </>
  )
 }

+function ConnectRoute() {
+  const navigate = useNavigate()
+  const servers = useServers()
+  const pairing = decodePairingUrl(location.search, location.origin) ?? decodePairingUrl(location.hash)
+  // From the hosted https page, http is mixed content and loopback is the scanning device itself.
+  const url =
+    pairing?.urls.find((item) => item === location.origin) ??
+    pairing?.urls.find((item) => location.protocol !== "https:" || item.startsWith("https:"))
+  onMount(() => {
+    if (!pairing || !url) return
+    servers.add({ type: "http", http: { url, password: pairing.password } })
+    navigate("/", { replace: true })
+  })
+  if (!pairing) return <ConnectServerScreen onConnect={() => navigate("/", { replace: true })} />
+  if (!url) return <ConnectLocalScreen urls={pairing.urls} />
+  return null
+}
+
 function TargetServerRoute(props: ParentProps) {
  const params = useParams<{ serverKey: string }>()
  const global = useGlobal()
@@ -79,6 +106,7 @@ function AppLayout(props: ParentProps) {
    <Show when={servers.list.length > 0} fallback={<ConnectServerScreen />}>
      <LayoutProvider>
        <SettingsSurfaceProvider>
+          <DesktopPairingCommand />
          <BrowserAttachmentsProvider>
            <Shell>{props.children}</Shell>
          </BrowserAttachmentsProvider>
@@ -10,6 +10,10 @@ test("settings has its own layout route", () => {
  expect(currentRoute("/settings", "")).toEqual({ type: "settings" })
 })

+test("connect has its own layout route", () => {
+  expect(currentRoute("/connect", "")).toEqual({ type: "connect" })
+})
+
 describe("layout persistence", () => {
  const schema = Persistence.withInitial(layoutPersistence, initialLayout(ServerConnection.Key.make("local")))
  const decode = Schema.decodeUnknownSync(schema)
@@ -67,6 +67,7 @@ export type TabPanes = {
 export type LayoutRoute =
  | { type: "home" }
  | { type: "settings" }
+  | { type: "connect" }
  | { type: "draft"; draftID: string }
  | { type: "session"; sessionId: string; server: ServerConnection.Key }

@@ -106,6 +107,7 @@ export const currentRoute = (pathname: string, search: string): LayoutRoute => {
  const parts = pathname.split("/").filter(Boolean)
  if (parts.length === 0) return { type: "home" }
  if (parts[0] === "settings") return { type: "settings" }
+  if (parts[0] === "connect") return { type: "connect" }

  if (parts[0] === "new-session") {
    const draftID = new URLSearchParams(search).get("draftId")
@@ -303,6 +303,7 @@ export function Titlebar(props: {
                  return
                }
                case "settings":
+                case "connect":
                case "home": {
                  const selection = layout.home.selection()
                  const conn =
@@ -1,6 +1,6 @@
 import { expect, test } from "bun:test"
 import { resolveObjectURL } from "node:buffer"
-import { createDraftStore, resolveBlobUrl } from "@/runtime/persistence/drafts"
+import { createDraftStore } from "@/runtime/persistence/drafts"

 function fixture(id: string, getBlob: () => Promise<Blob | null>) {
  const documents = new Map([
@@ -20,19 +20,7 @@ function fixture(id: string, getBlob: () => Promise<Blob | null>) {
  return { store, documents }
 }

-test("loading history and a draft reads no image bytes", async () => {
-  let reads = 0
-  const { store } = fixture("history-cache-lazy", async () => {
-    reads++
-    return new Blob(["shared screenshot"])
-  })
-  const [history, draft] = await Promise.all([store.getItem("history"), store.getItem("draft")])
-  expect(JSON.parse(history!).entries[0].prompt[0].blob).toEqual({ id: "history-cache-lazy" })
-  expect(JSON.parse(draft!).prompt[0].blob).toEqual({ id: "history-cache-lazy" })
-  expect(reads).toBe(0)
-})
-
-test("deduplicates concurrent resolves without invalidating either live reference", async () => {
+test("deduplicates concurrent history and draft reads without invalidating either live reference", async () => {
  const pending = Promise.withResolvers<Blob | null>()
  const started = Promise.withResolvers<void>()
  let reads = 0
@@ -41,33 +29,55 @@ test("deduplicates concurrent resolves without invalidating either live referenc
    started.resolve()
    return pending.promise
  })
-  await store.getItem("history")
-  const first = resolveBlobUrl({ id: "history-cache-concurrent" })
-  const second = resolveBlobUrl({ id: "history-cache-concurrent" })
+  const history = store.getItem("history")
+  const draft = store.getItem("draft")
  await started.promise
  pending.resolve(new Blob(["shared screenshot"]))
-  const [a, b] = await Promise.all([first, second])
-  expect(a).toBe(b!)
+  const [saved, active] = await Promise.all([history, draft])
+  const reference = JSON.parse(saved!).entries[0].prompt[0].blob
+  expect(JSON.parse(active!).prompt[0].blob).toEqual(reference)
  expect(reads).toBe(1)
  await store.removeItem("history")
-  expect(await resolveObjectURL(a!)?.text()).toBe("shared screenshot")
-  expect(await resolveBlobUrl({ id: "history-cache-concurrent" })).toBe(a!)
+  expect(await resolveObjectURL(reference.url)?.text()).toBe("shared screenshot")
+  expect(JSON.parse((await store.getItem("draft"))!).prompt[0].blob).toEqual(reference)
  expect(reads).toBe(1)
 })

-test("a document re-read while its image is live gets the URL back without a read", async () => {
+test("hydrates repeated references once within one history document", async () => {
+  let reads = 0
+  const { store, documents } = fixture("history-cache-repeated", async () => {
+    reads++
+    return new Blob(["repeated screenshot"])
+  })
+  documents.set(
+    "history",
+    JSON.stringify({
+      entries: Array.from({ length: 100 }, () => ({
+        prompt: [{ type: "image", blob: { id: "history-cache-repeated" } }],
+      })),
+    }),
+  )
+  const value = JSON.parse((await store.getItem("history"))!)
+  expect(value.entries).toHaveLength(100)
+  expect(
+    new Set(value.entries.map((entry: { prompt: { blob: { url: string } }[] }) => entry.prompt[0].blob.url)).size,
+  ).toBe(1)
+  expect(reads).toBe(1)
+})
+
+test("reuses a live URL on remount but reads the latest document", async () => {
  let reads = 0
  const { store, documents } = fixture("history-cache-remount", async () => {
    reads++
    return new Blob(["saved screenshot"])
  })
-  const url = await resolveBlobUrl({ id: "history-cache-remount" })
+  const first = JSON.parse((await store.getItem("history"))!)
  const changed = JSON.parse(documents.get("history")!)
  changed.entries[0].prompt.unshift({ type: "text", content: "new admission" })
  documents.set("history", JSON.stringify(changed))
  const second = JSON.parse((await store.getItem("history"))!)
  expect(second.entries[0].prompt[0].content).toBe("new admission")
-  expect(second.entries[0].prompt[1].blob).toEqual({ id: "history-cache-remount", url })
+  expect(second.entries[0].prompt[1].blob).toEqual(first.entries[0].prompt[0].blob)
  expect(reads).toBe(1)
 })

@@ -79,34 +89,33 @@ test("reuses a just-stored attachment without a round trip", async () => {
  })
  const reference = await store.putBlob(new Blob(["pending admission"]))
  expect(JSON.parse((await store.getItem("draft"))!).prompt[0].blob).toEqual(reference)
-  expect(await resolveBlobUrl({ id: reference.id })).toBe(reference.url)
  expect(reads).toBe(0)
  expect(await resolveObjectURL(reference.url)?.text()).toBe("pending admission")
 })

 test("does not retain a missing blob result", async () => {
  let reads = 0
-  fixture("history-cache-missing", async () => (++reads === 1 ? null : new Blob(["arrived"])))
-  expect(await resolveBlobUrl({ id: "history-cache-missing" })).toBeUndefined()
-  expect(await resolveBlobUrl({ id: "history-cache-missing" })).toStartWith("blob:")
+  const { store } = fixture("history-cache-missing", async () => (++reads === 1 ? null : new Blob(["arrived"])))
+  expect(JSON.parse((await store.getItem("draft"))!).prompt[0].blob.url).toBeUndefined()
+  expect(JSON.parse((await store.getItem("draft"))!).prompt[0].blob.url).toStartWith("blob:")
  expect(reads).toBe(2)
 })

 test("retries after a failed blob read", async () => {
  let reads = 0
-  fixture("history-cache-failure", async () => {
+  const { store } = fixture("history-cache-failure", async () => {
    if (++reads === 1) throw new Error("temporary storage failure")
    return new Blob(["recovered"])
  })
-  await expect(resolveBlobUrl({ id: "history-cache-failure" })).rejects.toThrow("temporary storage failure")
-  expect(await resolveBlobUrl({ id: "history-cache-failure" })).toStartWith("blob:")
+  await expect(store.getItem("history")).rejects.toThrow("temporary storage failure")
+  expect(JSON.parse((await store.getItem("history"))!).entries[0].prompt[0].blob.url).toStartWith("blob:")
  expect(reads).toBe(2)
 })

 test("keeps different blob IDs independent", async () => {
  const reads: string[] = []
-  createDraftStore({
-    get: async () => null,
+  const store = createDraftStore({
+    get: async () => JSON.stringify(["history-cache-first", "history-cache-second"].map((id) => ({ blob: { id } }))),
    set: async () => [],
    remove: async () => {},
    putBlob: async () => "unused",
@@ -115,8 +124,10 @@ test("keeps different blob IDs independent", async () => {
      return new Blob([id])
    },
  })
-  const urls = await Promise.all(["history-cache-first", "history-cache-second"].map((id) => resolveBlobUrl({ id })))
-  expect(urls[0]).not.toBe(urls[1])
-  expect(await Promise.all(urls.map((url) => resolveObjectURL(url!)?.text()))).toEqual(reads)
+  const value = JSON.parse((await store.getItem("history"))!)
+  expect(value[0].blob.url).not.toBe(value[1].blob.url)
+  expect(
+    await Promise.all(value.map((item: { blob: { url: string } }) => resolveObjectURL(item.blob.url)?.text())),
+  ).toEqual(reads)
  expect(reads).toEqual(["history-cache-first", "history-cache-second"])
 })
@@ -5,7 +5,7 @@ import { Schema } from "effect"
 import type { Platform } from "@/runtime/platform/platform"
 import { createComposerReady, createComposerState } from "@/composer/state"
 import { ServerScope } from "@/runtime/server/scope"
-import { createDraftStore, resolveBlobUrl } from "@/runtime/persistence/drafts"
+import { createDraftStore } from "@/runtime/persistence/drafts"
 import { flushPersisted } from "@/runtime/persistence/persist"
 import { Persist, persisted } from "@/runtime/persistence/storage"

@@ -103,11 +103,15 @@ describe("prompt persistence", () => {
      }),
    }))
    await root.session.ready.promise
-    // Bytes stay in the store until the image is shown or sent.
    expect(root.session.current()).toEqual([
-      { type: "image", id: "image", filename: "image.png", mime: "image/png", blob: { id: "composer-image", url: "" } },
+      {
+        type: "image",
+        id: "image",
+        filename: "image.png",
+        mime: "image/png",
+        blob: { id: "composer-image", url: expect.stringMatching(/^blob:/) },
+      },
    ])
-    expect(await resolveBlobUrl(root.session.current()[0]!.blob)).toStartWith("blob:")
    root.session.set([{ type: "text", content: "hello", start: 0, end: 5 }, ...root.session.current()])
    flushPersisted()
    await Bun.sleep(0)
@@ -233,7 +237,7 @@ describe("prompt persistence", () => {
  })
 })

-test("moves image data URLs into blobs and resolves object URLs on demand", async () => {
+test("moves image data URLs into blobs and hydrates object URLs", async () => {
  const documents = new Map<string, string>()
  const blobs = new Map<string, Blob>()
  const store = createDraftStore({
@@ -254,8 +258,8 @@ test("moves image data URLs into blobs and resolves object URLs on demand", asyn
  await store.setItem("prompt", JSON.stringify({ prompt: [{ type: "image", dataUrl: "data:image/png;base64,YQ==" }] }))
  expect(documents.get("prompt")).not.toContain("dataUrl")
  const value = JSON.parse((await store.getItem("prompt"))!)
-  expect(value.prompt[0].blob).toEqual({ id: "1" })
-  expect(await resolveBlobUrl(value.prompt[0].blob)).toStartWith("blob:")
+  expect(value.prompt[0].blob.id).toBe("1")
+  expect(value.prompt[0].blob.url).toStartWith("blob:")
 })

 test("does not let delayed blob migration overwrite a newer draft", async () => {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/cli",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "type": "module",
  "license": "MIT",
  "bin": {
@@ -2,6 +2,7 @@ import { EOL } from "os"
 import { Effect, Option } from "effect"
 import { Service } from "@opencode/client/effect/service"
 import { OpenCode } from "@opencode/client/promise"
+import { base64Encode } from "@opencode/util/encode"
 import { renderUnicodeCompact } from "uqr"
 import { Commands } from "../commands"
 import { Runtime } from "../../framework/runtime"
@@ -18,6 +19,8 @@ export default Runtime.handler(
          OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) }).server.info(),
        )).urls
    const info = { urls, username: "opencode", password }
+    // Fragment, not query: the credential must never reach app.opencode.ai.
+    const link = `https://app.opencode.ai/connect#${base64Encode(JSON.stringify(info))}`
    process.stdout.write(
      [
        "",
@@ -28,11 +31,13 @@ export default Runtime.handler(
        "",
        "  Scan to pair",
        "",
-        renderUnicodeCompact(JSON.stringify(info), { border: 2 })
+        renderUnicodeCompact(link, { border: 2 })
          .split(EOL)
          .map((line) => "  " + line)
          .join(EOL),
        "",
+        `  Link      ${link}`,
+        "",
      ].join(EOL) + EOL,
    )

@@ -10,18 +10,16 @@ export const handler = Effect.fn("cli.web-ui.handler")(function* (options?: { re
    ? Effect.succeed(options.assets)
    : yield* Effect.cached(load().pipe(Effect.provideService(FileSystem.FileSystem, fileSystem)))
  return <E, R>(api: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>) =>
-    api.pipe(
-      Effect.catchIf(isRouteNotFound, () =>
-        HttpServerRequest.HttpServerRequest.pipe(
-          Effect.flatMap((request) => {
-            const url = new URL(request.url, "http://localhost")
-            if (url.pathname === "/api" || url.pathname.startsWith("/api/"))
-              return Effect.succeed(HttpServerResponse.empty({ status: 404 }))
-            return assets.pipe(Effect.flatMap((files) => serveUI(request, url, files)))
-          }),
-        ),
-      ),
-    )
+    Effect.gen(function* () {
+      const request = yield* HttpServerRequest.HttpServerRequest
+      const url = new URL(request.url, "http://localhost")
+      // Serve the web shell before API authentication so /connect can load credentials in JavaScript.
+      if (url.pathname === "/api" || url.pathname.startsWith("/api/") || url.pathname === "/openapi.json")
+        return yield* api.pipe(
+          Effect.catchIf(isRouteNotFound, () => Effect.succeed(HttpServerResponse.empty({ status: 404 }))),
+        )
+      return yield* assets.pipe(Effect.flatMap((files) => serveUI(request, url, files)))
+    })
 })

 function serveUI(request: HttpServerRequest.HttpServerRequest, url: URL, assets: AssetMap) {
@@ -1,4 +1,5 @@
 import { NodeFileSystem, NodeHttpServer } from "@effect/platform-node"
+import { ServerProcess } from "@opencode/server/process"
 import { afterAll, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
 import { HttpServer, HttpServerError, HttpServerRequest, HttpServerResponse } from "effect/unstable/http"
@@ -7,11 +8,69 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import path from "node:path"
 import { WebUi } from "../src/services/web-ui"
+import { it } from "../../core/test/lib/effect"

 const root = await mkdtemp(path.join(tmpdir(), "opencode-web-ui-"))
 afterAll(() => rm(root, { recursive: true, force: true }))

 describe("web UI", () => {
+  it.live("serves the web shell and assets before server authentication", () =>
+    Effect.gen(function* () {
+      const transform = yield* WebUi.handler({
+        assets: {
+          "index.html": "<html><body>connect</body></html>",
+          "_assets/app.js": "console.log('connect')",
+          "_assets/app.css": "body { color: black; }",
+          "icons/icon.svg": "<svg></svg>",
+          "font.woff2": new Uint8Array([0, 1, 2, 255]),
+          "sw.js": "service worker",
+        },
+      })
+      const server = yield* ServerProcess.start<never, never>(
+        { hostname: "127.0.0.1", port: 0, password: "secret", database: { path: ":memory:" } },
+        undefined,
+        transform,
+      )
+      const origin = HttpServer.formatAddress(server.address)
+      yield* Effect.forEach(
+        [
+          "/",
+          "/connect?data=%7B%7D",
+          "/workspace/example",
+          "/_assets/app.js",
+          "/_assets/app.css",
+          "/icons/icon.svg",
+          "/font.woff2",
+          "/sw.js",
+        ],
+        (pathname) =>
+          Effect.gen(function* () {
+            yield* Effect.forEach(["GET", "HEAD"], (method) =>
+              Effect.gen(function* () {
+                const response = yield* Effect.promise(() => fetch(new URL(pathname, origin), { method }))
+                expect(response.status).toBe(200)
+                expect(response.headers.get("www-authenticate")).toBeNull()
+                yield* Effect.promise(() => response.arrayBuffer())
+              }),
+            )
+          }),
+      )
+      yield* Effect.forEach(["/api", "/api/info", "/api/event", "/api/missing", "/openapi.json"], (pathname) =>
+        Effect.gen(function* () {
+          const response = yield* Effect.promise(() => fetch(new URL(pathname, origin)))
+          expect(response.status).toBe(401)
+          expect(response.headers.get("www-authenticate")).toBe('Basic realm="Secure Area"')
+          yield* Effect.promise(() => response.arrayBuffer())
+        }),
+      )
+      const response = yield* Effect.promise(() =>
+        fetch(new URL("/api/info", origin), { headers: { authorization: `Basic ${btoa("opencode:secret")}` } }),
+      )
+      expect(response.status).toBe(200)
+      expect(yield* Effect.promise(() => response.json())).toHaveProperty("pid")
+    }).pipe(Effect.provide(NodeFileSystem.layer)),
+  )
+
  test("falls back from API routes to assets and the SPA index", async () => {
    const index = path.join(root, "index.html")
    const asset = path.join(root, "app.js")
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/client",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "type": "module",
  "license": "MIT",
  "repository": {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/codemode",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "description": "Effect-native confined code execution over schema-described tools",
  "type": "module",
  "license": "MIT",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode/console-app",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/console-core",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "private": true,
  "type": "module",
  "license": "MIT",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode/console-function",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "$schema": "https://json.schemastore.org/package.json",
  "private": true,
  "type": "module",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode/console-mail",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "dependencies": {
    "@jsx-email/all": "2.2.3",
    "@jsx-email/cli": "1.4.3",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode/console-support",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "name": "@opencode/core",
  "type": "module",
  "license": "MIT",
@@ -1,29 +0,0 @@
-export * as NativeCompactionPlugin from "./compaction.js"
-
-import { LLMClient, Message } from "@opencode/ai"
-import { define } from "@opencode/plugin/effect/plugin"
-import { Effect } from "effect"
-import { SessionCompaction } from "../session/compaction.js"
-import type { PluginInternal } from "./internal.js"
-
-export const Plugin = define({
-  id: "opencode.compaction.native",
-  effect: Effect.fn("NativeCompactionPlugin")(function* () {
-    const llm = yield* LLMClient.Service
-    const compaction = yield* SessionCompaction.Service
-    yield* compaction.transform((editor) => {
-      editor.native((input) => {
-        const request = input.request
-        if (LLMClient.canCompact(request, { mechanism: "trigger" }))
-          return Effect.gen(function* () {
-            const retained = yield* input.retained
-            const result = yield* llm.compact(request, { ...input.options, mechanism: "trigger" })
-            return { replacement: [...retained, Message.assistant(result.checkpoint)], usage: result.usage }
-          })
-        if (LLMClient.canCompact(request))
-          return llm.compact(request, { mechanism: "endpoint", http: input.options.http })
-        return undefined
-      })
-    })
-  }),
-} satisfies PluginInternal.InternalPlugin)
@@ -1,6 +1,5 @@
 export * as PluginInternal from "./internal.js"

-import { LLMClient } from "@opencode/ai"
 import type { Plugin } from "@opencode/plugin/effect/plugin"
 import { LayerNode } from "@opencode/util/effect/layer-node"
 import { httpClient } from "@opencode/util/effect/app-node-platform"
@@ -13,7 +12,6 @@ import { Provider } from "../provider.js"
 import { Command } from "../command.js"
 import { Config } from "../config.js"
 import { Credential } from "../credential.js"
-import { llmClient } from "../effect/app-node-platform.js"
 import { ConfigAgentPlugin } from "../config/plugin/agent.js"
 import { ConfigCommandPlugin } from "../config/plugin/command.js"
 import { ConfigCompactionPlugin } from "../config/plugin/compaction.js"
@@ -86,7 +84,6 @@ import { WriteTool } from "../tool/plugin/write.js"
 import { AgentPlugin } from "./agent.js"
 import BrowserPlugin from "@opencode/plugin-browser"
 import { CommandPlugin } from "./command.js"
-import { NativeCompactionPlugin } from "./compaction.js"
 import { IdentityPlugin } from "./identity.js"
 import { PlanPlugin } from "./plan.js"
 import { ModelsDevPlugin } from "./models-dev.js"
@@ -123,7 +120,6 @@ const services = [
  Integration.Service,
  Job.Service,
  KV.Service,
-  LLMClient.Service,
  Location.Service,
  ModelsDev.Service,
  Mcp.Service,
@@ -175,7 +171,6 @@ export const requirements = LayerNode.group([
  Integration.node,
  Job.node,
  KV.node,
-  llmClient,
  Location.node,
  ModelsDev.node,
  Mcp.node,
@@ -217,7 +212,6 @@ const pre = [
  SkillPlugin.Plugin,
  VcsHgPlugin.Plugin,
  ModelsDevPlugin,
-  NativeCompactionPlugin.Plugin,
  ...ProviderPlugins,
  ...WebSearchPlugins,
  PatchTool.Plugin,
@@ -10,9 +10,7 @@ import {
  LLMRequest,
  Message,
  type ContentPart,
-  type Usage,
 } from "@opencode/ai"
-import type { StreamOptions } from "@opencode/ai/route"
 import type { SessionCompactionResult } from "@opencode/plugin/effect/session"
 import { SessionError } from "@opencode/schema/session-error"
 import { Context, Effect, Layer, Stream } from "effect"
@@ -93,25 +91,8 @@ export type Settings = {
  tokens: number
 }

-export type NativeInput = {
-  readonly request: LLMRequest
-  readonly options: StreamOptions
-  /** Whole, real user messages within the retained-token allowance, for checkpoint-only mechanisms. */
-  readonly retained: Effect.Effect<ReadonlyArray<Message>>
-}
-
-export type NativeResult = {
-  readonly replacement: ReadonlyArray<Message>
-  readonly usage?: Usage
-}
-
-/** Returns the provider's replacement window, or `undefined` when this strategy has no mechanism for the route. */
-export type NativeStrategy = (input: NativeInput) => Effect.Effect<NativeResult, AIError> | undefined
-
 export type Editor = {
  configure: (settings: Partial<Settings>) => void
-  /** Later registrations take precedence. */
-  native: (strategy: NativeStrategy) => void
 }

 export type AutoInput = {
@@ -399,18 +380,15 @@ export const layer = Layer.effect(
    const llm = yield* LLMClient.Service
    const db = (yield* Database.Service).db

-    const state = State.create<Settings & { readonly native: NativeStrategy[] }, Editor>({
+    const state = State.create<Settings, Editor>({
      name: "session-compaction",
-      initial: () => ({ auto: true, buffer: DEFAULT_BUFFER, tokens: DEFAULT_KEEP_TOKENS, native: [] }),
+      initial: () => ({ auto: true, buffer: DEFAULT_BUFFER, tokens: DEFAULT_KEEP_TOKENS }),
      editor: (editor) => ({
        configure: (settings) => {
          if (settings.auto !== undefined) editor.auto = settings.auto
          if (settings.buffer !== undefined) editor.buffer = settings.buffer
          if (settings.tokens !== undefined) editor.tokens = settings.tokens
        },
-        native: (strategy) => {
-          editor.native.push(strategy)
-        },
      }),
    })
    const failed = Effect.fnUntraced(function* (input: SessionEvent.Compaction.Failed["data"]) {
@@ -526,23 +504,6 @@ export const layer = Layer.effect(
        return yield* reject(
          "Provider compaction requires the endpoint in provider/model settings, not a model.request rewrite",
        )
-      const native = state
-        .get()
-        .native.toReversed()
-        .map((strategy) =>
-          strategy({
-            request,
-            options: prepared.options,
-            retained: original(context.session.id).pipe(
-              Effect.map((messages) => retainUsers(messages, context.model, state.get().tokens)),
-            ),
-          }),
-        )
-        .find((effect) => effect !== undefined)
-      if (!native)
-        return yield* reject(
-          `No plugin provides native compaction for ${request.model.provider}/${request.model.route.id}`,
-        )
      const transient = SessionRunnerRetry.transient(yield* SessionRunnerRetry.policy(context.session.id), {
        agent: context.agent.id,
        model: context.model.ref,
@@ -553,7 +514,25 @@ export const layer = Layer.effect(
        Effect.gen(function* () {
          // Transient provider failures retry like any other request; only a known automatic overflow permits
          // local recovery, and nothing is installed until the provider returns a checkpoint.
-          const result = yield* restore(native.pipe(transient))
+          const result = yield* restore(
+            Effect.gen(function* () {
+              if (LLMClient.canCompact(request, { mechanism: "trigger" })) {
+                const retained = retainUsers(yield* original(context.session.id), context.model, state.get().tokens)
+                const result = yield* llm
+                  .compact(request, { ...prepared.options, mechanism: "trigger" })
+                  .pipe(transient)
+                return { replacement: [...retained, Message.assistant(result.checkpoint)], usage: result.usage }
+              }
+              if (LLMClient.canCompact(request))
+                return yield* llm
+                  .compact(request, { mechanism: "endpoint", http: prepared.options.http })
+                  .pipe(transient)
+              // Model resolution admits provider policies only for routes with a compaction operation.
+              return yield* Effect.die(
+                new Error(`${request.model.provider}/${request.model.route.id} has no compaction operation`),
+              )
+            }),
+          )
          const usage = result.usage ? SessionUsage.record(result.usage, context.model.cost) : undefined
          if (usage)
            yield* bus.publish(SessionEvent.UsageRecorded, {
@@ -22,18 +22,16 @@ const writePackage = (dir: string, pkg: Record<string, unknown>) =>
 const npmLayer = (cache: string) =>
  AppNodeBuilder.build(Npm.node, [Global.node.replace(Global.layerWith({ cache, state: path.join(cache, "state") }))])

-async function createGitFixture(directory: string, prepare = false) {
+async function createGitFixture(directory: string) {
  const repository = path.join(directory, "repository")
  await fs.mkdir(path.join(repository, "dependency"), { recursive: true })
  await writePackage(repository, {
    name: "fixture-git-plugin",
    exports: "./index.js",
    dependencies: { "fixture-dependency": "file:./dependency" },
-    ...(prepare ? { scripts: { prepare: "bun prepare.ts" } } : {}),
  })
  await writePackage(path.join(repository, "dependency"), { name: "fixture-dependency", exports: "./index.js" })
  await Bun.write(path.join(repository, "index.js"), "export default { root: true }\n")
-  if (prepare) await Bun.write(path.join(repository, "prepare.ts"), 'await Bun.write("prepared.txt", "ready\\n")\n')
  await Bun.write(path.join(repository, "dependency", "index.js"), "export const dependency = true\n")

  const subdirectory = path.join(repository, "packages", "subdirectory-plugin")
@@ -250,19 +248,6 @@ describe("Npm.add", () => {
    expect(entries.added.directory).toContain("node_modules")
  })

-  test("installs Git packages with prepare scripts", async () => {
-    await using tmp = await tmpdir()
-    const fixture = await createGitFixture(tmp.path, true)
-    const spec = `git+file://${fixture.repository}#${fixture.commit}`
-
-    const entry = await Effect.gen(function* () {
-      const npm = yield* Npm.Service
-      return yield* npm.add(spec)
-    }).pipe(Effect.scoped, Effect.provide(npmLayer(path.join(tmp.path, "cache"))), Effect.runPromise)
-
-    await expect(Bun.file(path.join(entry.directory, "prepared.txt")).text()).resolves.toBe("ready\n")
-  })
-
  test("installs a Git package from an npm ::path: subdirectory", async () => {
    await using tmp = await tmpdir()
    const fixture = await createGitFixture(tmp.path)
@@ -1,5 +1,5 @@
 import { expect, test } from "bun:test"
-import { LLMClient, LanguageModel, Message, ToolDefinition, Usage } from "@opencode/ai"
+import { LLMClient, LanguageModel, Message, ToolDefinition } from "@opencode/ai"
 import { OpenAI } from "@opencode/ai/providers"
 import { Agent } from "@opencode/core/agent"
 import { Bus } from "@opencode/core/bus"
@@ -7,7 +7,6 @@ import { Database } from "@opencode/core/database/database"
 import { AppNodeBuilder } from "@opencode/core/effect/app-node-builder"
 import { llmClient } from "@opencode/core/effect/app-node-platform"
 import { Instructions } from "@opencode/core/instructions/index"
-import { NativeCompactionPlugin } from "@opencode/core/plugin/compaction"
 import { PluginHooks } from "@opencode/core/plugin/hooks"
 import { Project } from "@opencode/core/project"
 import { ProjectTable } from "@opencode/core/project/sql"
@@ -27,7 +26,6 @@ import { SessionStore } from "@opencode/core/session/store"
 import { LayerNode } from "@opencode/util/effect/layer-node"
 import { DateTime, Deferred, Effect, Fiber, Schema } from "effect"
 import { testEffect } from "./lib/effect"
-import { host } from "./plugin/host"

 const it = testEffect(
  AppNodeBuilder.build(
@@ -46,8 +44,7 @@ const it = testEffect(
  ),
 )

-const setup = Effect.fnUntraced(function* (options: { endpoint?: boolean; plugin?: boolean } = {}) {
-  const endpoint = options.endpoint ?? false
+const setup = Effect.fnUntraced(function* (endpoint = false) {
  const db = (yield* Database.Service).db
  const bus = yield* Bus.Service
  const inbox = yield* SessionInbox.Service
@@ -188,7 +185,6 @@ const setup = Effect.fnUntraced(function* (options: { endpoint?: boolean; plugin
    render: { initial: String, changed: (_previous, value) => value, removed: () => "removed" },
  })
  yield* InstructionState.prepare(db, bus, instructions, sessionID)
-  if (options.plugin !== false) yield* NativeCompactionPlugin.Plugin.effect(host())
  yield* hooks.register("session", "model.request", (event) =>
    Effect.sync(() => {
      event.headers["x-test-hook"] = event.kind
@@ -265,7 +261,6 @@ const setup = Effect.fnUntraced(function* (options: { endpoint?: boolean; plugin
    store,
    hooks,
    model,
-    compaction,
  }
 })

@@ -353,7 +348,7 @@ it.live(

 it.live("manual and automatic endpoint compaction keep the provider replacement unchanged", () =>
  Effect.gen(function* () {
-    const fixture = yield* setup({ endpoint: true })
+    const fixture = yield* setup(true)
    yield* fixture.prompt("Original user")
    expect(yield* fixture.compact).toEqual({ status: "completed" })
    expect(yield* fixture.automatic).toEqual({ status: "completed" })
@@ -450,31 +445,6 @@ it.live("rejects request-hook route rewrites before provider compaction", () =>
  }),
 )

-it.live("provider compaction fails without a native strategy and persists a registered strategy's window", () =>
-  Effect.gen(function* () {
-    const fixture = yield* setup({ plugin: false })
-    yield* fixture.prompt("Original user")
-    expect(yield* fixture.compact).toMatchObject({
-      status: "failed",
-      error: { type: "provider.unsupported-operation", message: expect.stringContaining("openai/openai-responses") },
-    })
-    yield* fixture.compaction.transform((editor) => {
-      editor.native(() =>
-        Effect.succeed({
-          replacement: [Message.assistant("plugin window")],
-          usage: new Usage({ nonCachedInputTokens: 20, outputTokens: 4 }),
-        }),
-      )
-    })
-    expect(yield* fixture.compact).toEqual({ status: "completed" })
-    expect(fixture.state.calls).toBe(0)
-    const installed = yield* fixture.checkpoint
-    expect(installed.provenance).toEqual(SessionProviderContext.provenance(fixture.model)!)
-    expect(SessionProviderContext.decode(installed)).toEqual([Message.assistant("plugin window")])
-    expect(yield* fixture.store.get(fixture.sessionID)).toMatchObject({ tokens: { input: 20, output: 4 } })
-  }),
-)
-
 test("retained user budget counts attachments and drops whole oldest messages", () => {
  const model = SessionRunnerModel.resolved(OpenAI.responses("gpt-5.4-mini"), {
    capabilities: { tools: true, input: ["text", "image"], output: ["text"] },
@@ -56,7 +56,6 @@ import { Plugin } from "@opencode/core/plugin"
 import { PluginHooks } from "@opencode/core/plugin/hooks"
 import { OptimizePlugin } from "@opencode/core/plugin/optimize"
 import { IdentityPlugin } from "@opencode/core/plugin/identity"
-import { NativeCompactionPlugin } from "@opencode/core/plugin/compaction"
 import { QuestionTool } from "@opencode/core/tool/plugin/question"
 import { Agent } from "@opencode/core/agent"
 import { Config } from "@opencode/core/config"
@@ -471,7 +470,6 @@ const layer = Layer.unwrap(
        Config.node,
        Snapshot.node,
        SessionCompaction.node,
-        LayerNodePlatform.llmClient,
        SessionRunnerLLM.node,
        SessionExecution.node,
        Session.node,
@@ -525,7 +523,6 @@ const setup = Effect.gen(function* () {
    discard: true,
  })
  yield* IdentityPlugin.Plugin.effect(pluginHost)
-  yield* NativeCompactionPlugin.Plugin.effect(pluginHost)
  yield* agents.transform((editor) =>
    editor.update(Agent.ID.make("build"), (agent) => {
      agent.mode = "primary"
@@ -48,8 +48,7 @@ test("does not package external copies of bundled dependencies", () => {
  expect(pkg.devDependencies.effect).toBe("catalog:")
  expect(pkg.devDependencies["@effect/platform-node"]).toBe("catalog:")
  expect(pkg.devDependencies["drizzle-orm"]).toBe("catalog:")
-  // IPC crosses the port by structured clone; no MessagePack runtime or native accelerator ships.
-  expect(Object.keys(pkg.optionalDependencies)).not.toContain("msgpackr-extract")
+  expect(pkg.optionalDependencies["msgpackr-extract"]).toBe("3.0.4")
 })

 test("keeps PTY binaries without stale native packaging", () => {
@@ -102,6 +101,6 @@ test("bundles one Effect runtime and Drizzle while keeping native dependencies e
  expect(imports).toContain("node:sqlite")
  expect(chunks.some((chunk) => chunk.dynamicImports.includes("@zip.js/zip.js"))).toBe(true)
  expect(imports).toContain(`@lydell/node-pty-${process.platform}-${process.arch}`)
-  expect(modules.some((id) => id.includes("/node_modules/msgpackr"))).toBe(false)
-  expect(chunks.some((chunk) => chunk.code.includes("msgpackr"))).toBe(false)
+  expect(modules.some((id) => id.includes("/node_modules/msgpackr-extract/"))).toBe(false)
+  expect(chunks.some((chunk) => chunk.code.includes("msgpackr-extract"))).toBe(true)
 }, 30_000)
@@ -58,9 +58,9 @@ const require = __cjs_mod__.createRequire(import.meta.url);
        },
      },
      externalizeDeps: {
-        // Bundle the Effect family together.
+        // Bundle the Effect family together; native MessagePack acceleration stays optional and external.
        exclude: ["effect", "@effect/platform-node", "@effect/platform-node-shared", "drizzle-orm"],
-        include: [nodePtyPkg],
+        include: [nodePtyPkg, "msgpackr-extract"],
      },
    },
    plugins: [
@@ -1,7 +1,7 @@
 {
  "name": "@opencode/desktop",
  "private": true,
-  "version": "2.0.8",
+  "version": "2.0.7",
  "type": "module",
  "license": "MIT",
  "homepage": "https://opencode.ai",
@@ -68,6 +68,7 @@
    "@lydell/node-pty-linux-arm64": "1.2.0-beta.12",
    "@lydell/node-pty-linux-x64": "1.2.0-beta.12",
    "@lydell/node-pty-win32-arm64": "1.2.0-beta.12",
-    "@lydell/node-pty-win32-x64": "1.2.0-beta.12"
+    "@lydell/node-pty-win32-x64": "1.2.0-beta.12",
+    "msgpackr-extract": "3.0.4"
  }
 }
@@ -45,6 +45,10 @@ function selectOptions(): DevOptions {
 async function prepareServer(source: ServerSource) {
  if (source.type === "download")
    return downloadCliToResources(source.version, windowsify("resources/opencode-cli-dev"))
+  await $`bun run --cwd ${join(import.meta.dirname, "../../app")} build`.env({
+    ...process.env,
+    VITE_OPENCODE_SERVER_MODE: "origin",
+  })
  process.env.OPENCODE_DESKTOP_CLI_DEV = join(import.meta.dirname, "../../cli")
  await $`bun run --cwd ${process.env.OPENCODE_DESKTOP_CLI_DEV} --define=OPENCODE_VERSION=${JSON.stringify(process.env.OPENCODE_VERSION)} src/index.ts --version`
  if (process.platform !== "win32") return
@@ -5,6 +5,7 @@ import { AppRpcs } from "../../shared/ipc-rpc"
 import { openExternalURL } from "../files"
 import { checkAppExists, resolveAppPath } from "../files/apps"
 import { setForceFocus } from "../native/debug"
+import { createScreenActivity } from "../native/screen-activity"
 import { showCliInstaller } from "../native/install-cli"
 import { DesktopLogging, scoped } from "../native/logging"
 import { createMenu, sendMenuCommand } from "../native/menu"
@@ -17,6 +18,8 @@ import { DesktopCli } from "../service/desktop-cli"
 import { SidecarCredentials } from "../service/sidecar-credentials"
 import { getDefaultServerUrl, setDefaultServerUrl } from "../service/server-settings"
 import { Updater } from "../updater"
+import { DesktopStorage } from "../storage"
+import { createPairing } from "../service/pairing"
 import { getLastFocusedWindow, setBackgroundColor } from "../windows"
 import { sender } from "./context"

@@ -28,6 +31,10 @@ export const appHandlers = AppRpcs.toLayer(
    const desktopCli = yield* DesktopCli.Service
    const updater = yield* Updater.Service
    const logging = yield* DesktopLogging.Service
+    const storage = yield* DesktopStorage.Service
+    const screenActivity = createScreenActivity(storage)
+    yield* Effect.addFinalizer(() => Effect.sync(screenActivity.dispose))
+    const pairing = createPairing(storage)
    const runFork = Effect.runForkWith(yield* Effect.context())
    return AppRpcs.of({
      AppAwaitInitialization: () => background.connection.pipe(Effect.map(SidecarCredentials.ready)),
@@ -68,6 +75,14 @@ export const appHandlers = AppRpcs.toLayer(
          })
        }),
      AppRelaunch: () => Effect.sync(lifecycle.relaunch),
+      AppPairInfo: () => pair(pairing.info),
+      AppGetKeepScreenActive: () => Effect.sync(screenActivity.get),
+      AppSetKeepScreenActive: ({ enabled }) =>
+        Effect.try(() => screenActivity.set(enabled)).pipe(Effect.mapError(String)),
+      AppPairTailscaleAvailable: () => Effect.promise(pairing.tailscaleAvailable),
+      AppPairTailscaleStatus: () => pair(pairing.tailscaleStatus),
+      AppPairOpenTailscale: () => pair(pairing.openTailscale),
+      AppPairDisableTailscale: () => pair(pairing.disableTailscale),
    })
  }),
 )
@@ -75,3 +90,10 @@ export const appHandlers = AppRpcs.toLayer(
 function promise<A>(evaluate: () => A | Promise<A>) {
  return Effect.tryPromise(async () => evaluate()).pipe(Effect.orDie)
 }
+
+function pair<A>(evaluate: () => Promise<A>) {
+  return Effect.tryPromise({
+    try: evaluate,
+    catch: (cause) => (cause instanceof Error ? cause.message : String(cause)),
+  })
+}
@@ -3,22 +3,17 @@ import { EventEmitter } from "node:events"
 import { MessageChannel } from "node:worker_threads"
 import type { MessagePortMain, WebContents } from "electron"
 import { Context, Effect, Layer, ManagedRuntime, Option, Queue, Schema, Stream } from "effect"
-import { Rpc, RpcClient, RpcClientError, RpcGroup, RpcMessage, RpcServer } from "effect/unstable/rpc"
-import { Transferable } from "effect/unstable/workers"
+import { Rpc, RpcClient, RpcClientError, RpcGroup, RpcMessage, RpcSerialization, RpcServer } from "effect/unstable/rpc"
 import { IpcPortHandoff, IpcServerProtocolLive } from "./ipc-transport"

 describe("desktop RPC transport", () => {
  test("keeps multiple renderer ports independent", async () => {
-    let received: unknown
    const handlers = TestRpcs.toLayer(
      Effect.gen(function* () {
        const handoff = yield* IpcPortHandoff
        return TestRpcs.of({
          "test.focused": (_request, context) => Effect.succeed(handoff.sender(context.client.id)?.id === 1),
-          "test.blob.put": ({ data }) => {
-            received = data
-            return Effect.succeed([...data].join(","))
-          },
+          "test.blob.put": ({ data }) => Effect.succeed([...data].join(",")),
          "test.blob.get": () => Effect.succeed(new Uint8Array([3, 1, 4])),
          "test.events": () => Stream.make(new TestEvent({ value: "session.new" })),
        })
@@ -39,8 +34,6 @@ describe("desktop RPC transport", () => {
    expect(focused).toBe(true)
    expect(unfocused).toBe(false)
    expect(await putBlob(firstClient, new Uint8Array([2, 7, 1]))).toBe("2,7,1")
-    // Binary payloads arrive as bytes, not as base64 text.
-    expect(received).toBeInstanceOf(Uint8Array)
    expect(await getBlob(firstClient)).toEqual(new Uint8Array([3, 1, 4]))
    expect(await firstEvent(firstClient)).toEqual(new TestEvent({ value: "session.new" }))

@@ -61,8 +54,8 @@ describe("desktop RPC transport", () => {
 class TestEvent extends Schema.TaggedClass<TestEvent>()("TestEvent", { value: Schema.String }) {}
 const TestRpcs = RpcGroup.make(
  Rpc.make("test.focused", { success: Schema.Boolean }),
-  Rpc.make("test.blob.put", { payload: { data: Transferable.Uint8Array }, success: Schema.String }),
-  Rpc.make("test.blob.get", { success: Transferable.Uint8Array }),
+  Rpc.make("test.blob.put", { payload: { data: Schema.Uint8Array }, success: Schema.String }),
+  Rpc.make("test.blob.get", { success: Schema.Uint8Array }),
  Rpc.make("test.events", { success: TestEvent, stream: true }),
 )
 type TestRpcClient = RpcClient.FromGroup<typeof TestRpcs, RpcClientError.RpcClientError>
@@ -116,9 +109,13 @@ function clientProtocol(port: MessagePort) {
    RpcClient.Protocol,
    RpcClient.Protocol.make(
      Effect.fnUntraced(function* (writeResponse, clientIds) {
+        const serialization = yield* RpcSerialization.RpcSerialization
+        const parser = serialization.makeUnsafe()
        const inbound = yield* Queue.unbounded<RpcMessage.FromServerEncoded>()
        const onMessage = (event: MessageEvent) =>
-          Queue.offerUnsafe(inbound, event.data as RpcMessage.FromServerEncoded)
+          parser
+            .decode(event.data)
+            .forEach((message) => Queue.offerUnsafe(inbound, message as RpcMessage.FromServerEncoded))
        port.addEventListener("message", onMessage)
        port.start()
        yield* Effect.addFinalizer(() =>
@@ -134,15 +131,18 @@ function clientProtocol(port: MessagePort) {
          Effect.forkScoped,
        )
        return {
-          codecFor: Schema.toCodecJson,
+          codecFor: serialization.codecFor,
          send: (_clientId: number, request: RpcMessage.FromClientEncoded) =>
-            Effect.sync(() => port.postMessage(request)),
+            Effect.sync(() => {
+              const encoded = parser.encode(request)
+              if (encoded !== undefined) port.postMessage(encoded)
+            }),
          supportsAck: true,
          supportsTransferables: false,
        }
      }),
    ),
-  )
+  ).pipe(Layer.provide(RpcSerialization.layerMsgPack))
 }

 function sender(id: number) {
@@ -1,12 +1,14 @@
 import type { MessagePortMain, WebContents } from "electron"
-import { Context, Effect, Layer, Option, Queue, Schema, Stream } from "effect"
-import { RpcMessage, RpcServer } from "effect/unstable/rpc"
+import { Context, Effect, Layer, Option, Queue, Stream } from "effect"
+import { RpcMessage, RpcSerialization, RpcServer } from "effect/unstable/rpc"
+import { createIpcCodec } from "../shared/ipc-codec"
 import { bindIpcEvents } from "./ipc-events"

 type PortBinding = {
  readonly id: number
  readonly sender: WebContents
  readonly port: MessagePortMain
+  readonly parser: ReturnType<typeof createIpcCodec>
  readonly onMessage: (event: Electron.MessageEvent) => void
  readonly onClose: () => void
  readonly unbindEvents: Effect.Effect<void>
@@ -19,9 +21,6 @@ type Handoff = {

 export class IpcPortHandoff extends Context.Service<IpcPortHandoff, Handoff>()("opencode/desktop/IpcPortHandoff") {}

-// Messages cross the port by structured clone, like Effect's worker protocol: no serialization
-// layer, so binary payloads stay binary and nothing is packed into a shared buffer. Electron's
-// MessagePortMain can only transfer ports, so byte payloads are cloned in both directions.
 export const IpcServerProtocolLive = Layer.unwrap(
  Effect.gen(function* () {
    const handoffs = yield* Queue.unbounded<readonly [WebContents, MessagePortMain]>()
@@ -32,6 +31,7 @@ export const IpcServerProtocolLive = Layer.unwrap(
      RpcServer.Protocol,
      RpcServer.Protocol.make(
        Effect.fnUntraced(function* (writeRequest) {
+          const serialization = yield* RpcSerialization.RpcSerialization
          const disconnects = yield* Queue.unbounded<number>()
          const inbound = yield* Queue.unbounded<readonly [number, RpcMessage.FromClientEncoded]>()
          const runFork = Effect.runForkWith(yield* Effect.context())
@@ -59,12 +59,21 @@ export const IpcServerProtocolLive = Layer.unwrap(
            }

            const id = nextClientId++
+            const parser = createIpcCodec(serialization)
            const onMessage = (event: Electron.MessageEvent) => {
-              Queue.offerUnsafe(inbound, [id, event.data as RpcMessage.FromClientEncoded] as const)
+              try {
+                parser
+                  .decode(event.data)
+                  .forEach((message) =>
+                    Queue.offerUnsafe(inbound, [id, message as RpcMessage.FromClientEncoded] as const),
+                  )
+              } catch {
+                return
+              }
            }
            const onClose = () => runFork(disconnect(id))
            const unbindEvents = yield* bindIpcEvents(sender.id)
-            const binding = { id, sender, port, onMessage, onClose, unbindEvents }
+            const binding = { id, sender, port, parser, onMessage, onClose, unbindEvents }
            bindings.set(id, binding)
            senderBindings.set(sender.id, id)
            port.on("message", onMessage)
@@ -84,11 +93,14 @@ export const IpcServerProtocolLive = Layer.unwrap(
          yield* Effect.addFinalizer(() => Effect.forEach([...bindings.keys()], disconnect, { discard: true }))

          return {
-            codecFor: Schema.toCodecJson,
+            codecFor: serialization.codecFor,
            disconnects,
            send: (clientId, response) =>
              Effect.sync(() => {
-                bindings.get(clientId)?.port.postMessage(response)
+                const binding = bindings.get(clientId)
+                if (!binding) return
+                const encoded = binding.parser.encode(response)
+                if (encoded !== undefined) binding.port.postMessage(encoded)
              }),
            end: disconnect,
            clientIds: Effect.sync(() => new Set(bindings.keys())),
@@ -112,4 +124,4 @@ export const IpcServerProtocolLive = Layer.unwrap(
      }),
    )
  }),
-)
+).pipe(Layer.provide(RpcSerialization.layerMsgPack))
@@ -0,0 +1,25 @@
+import { powerSaveBlocker } from "electron"
+import type { DesktopStorage } from "../storage"
+import { KEEP_SCREEN_ACTIVE_KEY, SETTINGS_STORE } from "../storage/keys"
+
+export function createScreenActivity(storage: DesktopStorage.Interface) {
+  const state = { blocker: undefined as number | undefined }
+  const dispose = () => {
+    if (state.blocker === undefined) return
+    powerSaveBlocker.stop(state.blocker)
+    state.blocker = undefined
+  }
+  const set = (enabled: boolean) => {
+    if (enabled && state.blocker === undefined) {
+      state.blocker = powerSaveBlocker.start("prevent-display-sleep")
+    }
+    if (!enabled) dispose()
+    storage.state.set(SETTINGS_STORE, KEEP_SCREEN_ACTIVE_KEY, JSON.stringify(enabled))
+  }
+  if (storage.state.get(SETTINGS_STORE, KEEP_SCREEN_ACTIVE_KEY) === "true") set(true)
+  return {
+    get: () => state.blocker !== undefined && powerSaveBlocker.isStarted(state.blocker),
+    set,
+    dispose,
+  }
+}
@@ -43,7 +43,7 @@ const connect = Effect.fn("BackgroundService.connect")(function* (mode: "initial
          ? path.join(app.getPath("userData"), "opencode", "service-local.json")
          : undefined,
      version,
-      command: [...cli.command, "serve", "--service", ...(isolated ? ["--port", "0"] : [])],
+      command: [...cli.command, "serve", "--service", ...(isolated ? ["--hostname", "0.0.0.0", "--port", "0"] : [])],
      onStart: (reason, previousVersion) =>
        runFork(Effect.logInfo("v2 CLI background service starting", { reason, previousVersion })),
    }),
@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test"
+import { tailscaleUrls } from "./pairing"
+
+describe("Tailscale Serve output", () => {
+  test("extracts and deduplicates HTTPS addresses", () => {
+    expect(
+      tailscaleUrls(`
+Available within your tailnet:
+https://computer.example.ts.net/
+|-- https://computer.example.ts.net
+|--> http://127.0.0.1:4096
+`),
+    ).toEqual(["https://computer.example.ts.net"])
+  })
+
+  test("ignores non-HTTPS addresses", () => {
+    expect(tailscaleUrls("http://computer:80\ntcp://100.64.0.1:443")).toEqual([])
+  })
+
+  test("selects only the OpenCode HTTPS port", () => {
+    expect(
+      tailscaleUrls(
+        "https://computer.example.ts.net\nhttps://computer.example.ts.net:8443\nhttps://computer.example.ts.net:49152",
+        49152,
+      ),
+    ).toEqual(["https://computer.example.ts.net:49152"])
+  })
+})
@@ -0,0 +1,164 @@
+import { eq } from "drizzle-orm"
+import { execFile } from "node:child_process"
+import { constants } from "node:fs"
+import { access } from "node:fs/promises"
+import { createServer } from "node:net"
+import { promisify } from "node:util"
+import type { DesktopStorage } from "../storage"
+import { pairing } from "../storage/schema"
+import { SidecarCredentials } from "./sidecar-credentials"
+
+const tailscalePortKey = "tailscale_https_port"
+const execFileAsync = promisify(execFile)
+
+export function createPairing(storage: DesktopStorage.Interface) {
+  let tailscale: Promise<string | undefined> | undefined
+  const getTailscale = () => (tailscale ??= resolveTailscale())
+  let tailscalePort: Promise<number> | undefined
+  const storedTailscalePort = () => {
+    const value = storage.db
+      .select({ value: pairing.value })
+      .from(pairing)
+      .where(eq(pairing.key, tailscalePortKey))
+      .get()?.value
+    if (!value) return
+    const port = Number(value)
+    if (Number.isInteger(port) && port > 0 && port <= 65_535) return port
+  }
+  const getTailscalePort = () => (tailscalePort ??= Promise.resolve(storedTailscalePort() ?? availablePort()))
+  const saveTailscalePort = (port: number) =>
+    storage.db
+      .insert(pairing)
+      .values({ key: tailscalePortKey, value: String(port) })
+      .onConflictDoUpdate({ target: pairing.key, set: { value: String(port) } })
+      .run()
+
+  const requireCredentials = () => {
+    const credentials = SidecarCredentials.get()
+    if (!credentials) throw new Error("The local desktop server is not ready")
+    return credentials
+  }
+  const readInfo = async (credentials: ReturnType<typeof requireCredentials>) => {
+    const { OpenCode } = await import("@opencode/client/promise")
+    const info = await OpenCode.make({
+      baseUrl: credentials.url,
+      headers: credentials.password
+        ? { Authorization: `Basic ${Buffer.from(`opencode:${credentials.password}`).toString("base64")}` }
+        : undefined,
+    }).server.info()
+    return { urls: info.urls, username: "opencode" as const, password: credentials.password ?? "" }
+  }
+  const info = () => readInfo(requireCredentials())
+  const serveTailscale = async (executable: string, port: number) => {
+    const credentials = requireCredentials()
+    const local = await readInfo(credentials)
+    const endpoint = new URL(credentials.url)
+    const options = { env: { ...process.env, TAILSCALE_BE_CLI: "1" }, windowsHide: true }
+    const served = await execFileAsync(
+      executable,
+      ["serve", `--https=${port}`, "--bg", "--yes", `http://127.0.0.1:${endpoint.port}`],
+      options,
+    )
+    saveTailscalePort(port)
+    const direct = tailscaleUrls(`${served.stdout}\n${served.stderr}`, port)
+    const urls = direct.length
+      ? direct
+      : tailscaleUrls(
+          await execFileAsync(executable, ["serve", "status"], options).then(
+            (result) => `${result.stdout}\n${result.stderr}`,
+          ),
+          port,
+        )
+    if (!urls.length) throw new Error("Tailscale Serve did not report an HTTPS address")
+    return { ...local, urls: [...urls, ...local.urls] }
+  }
+
+  return {
+    info,
+    async tailscaleAvailable() {
+      return (await getTailscale()) !== undefined
+    },
+    async tailscaleStatus() {
+      const executable = await getTailscale()
+      const port = storedTailscalePort()
+      if (!executable || !port) return null
+      return serveTailscale(executable, port)
+    },
+    async openTailscale() {
+      const executable = await getTailscale()
+      if (!executable) throw new Error("Tailscale is not installed")
+      return serveTailscale(executable, await getTailscalePort())
+    },
+    async disableTailscale() {
+      const executable = await getTailscale()
+      const port = storedTailscalePort()
+      if (!executable || !port) return
+      await execFileAsync(executable, ["serve", `--https=${port}`, "--yes", "off"], {
+        env: { ...process.env, TAILSCALE_BE_CLI: "1" },
+        windowsHide: true,
+      })
+      storage.db.delete(pairing).where(eq(pairing.key, tailscalePortKey)).run()
+      tailscalePort = undefined
+    },
+  }
+}
+
+async function resolveTailscale() {
+  const candidates =
+    process.platform === "darwin"
+      ? [
+          "/Applications/Tailscale.app/Contents/MacOS/Tailscale",
+          ...(process.env.HOME ? [`${process.env.HOME}/Applications/Tailscale.app/Contents/MacOS/Tailscale`] : []),
+          "/opt/homebrew/bin/tailscale",
+          "/usr/local/bin/tailscale",
+        ]
+      : []
+  const installed = (
+    await Promise.all(
+      candidates.map((file) =>
+        access(file, constants.X_OK).then(
+          () => file,
+          () => undefined,
+        ),
+      ),
+    )
+  ).find((file) => file !== undefined)
+  if (installed) return installed
+  const result = await execFileAsync(process.platform === "win32" ? "where.exe" : "which", ["tailscale"], {
+    windowsHide: true,
+  }).then(
+    (value) => value.stdout,
+    () => undefined,
+  )
+  return result
+    ?.split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean)
+}
+
+export function tailscaleUrls(output: string, port?: number) {
+  return [
+    ...new Set(
+      (output.match(/https:\/\/[^\s|]+/g) ?? [])
+        .map((value) => URL.parse(value.replace(/[),;]+$/, "")))
+        .filter((url): url is URL => url?.protocol === "https:" && (port === undefined || url.port === String(port)))
+        .map((url) => url.href.replace(/\/$/, "")),
+    ),
+  ]
+}
+
+function availablePort() {
+  return new Promise<number>((resolve, reject) => {
+    const server = createServer()
+    server.once("error", reject)
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address()
+      if (address === null || typeof address === "string") {
+        server.close()
+        reject(new Error("Could not allocate a Tailscale HTTPS port"))
+        return
+      }
+      server.close((error) => (error ? reject(error) : resolve(address.port)))
+    })
+  })
+}
@@ -14,7 +14,7 @@ const tables = (db: ReturnType<typeof drizzle>) =>
 describe("database", () => {
  test("bootstraps every table on a fresh database and is idempotent", () => {
    const database = openDatabase(":memory:")
-    expect(tables(database.db)).toEqual(["blob", "document", "migration", "state"])
+    expect(tables(database.db)).toEqual(["blob", "document", "migration", "pairing", "state"])
    expect(migrate(database.db)).toEqual([])
    database.close()
  })
@@ -26,7 +26,7 @@ describe("database", () => {
    )
    const db = drizzle({ client: native })
    expect(migrate(db)).toEqual(migrations.map((migration) => migration.id))
-    expect(tables(db)).toEqual(["blob", "document", "migration", "state"])
+    expect(tables(db)).toEqual(["blob", "document", "migration", "pairing", "state"])
    expect(db.all<{ value: string }>(sql`SELECT value FROM document`)).toEqual([{ value: "v" }])
    expect(migrate(db)).toEqual([])
  })
@@ -98,10 +98,8 @@ export function createDraftStore(
      orphans = true
      return id
    },
-    getBlob(id: string): Uint8Array<ArrayBuffer> | null {
-      const data = db.select({ data: blobs.data }).from(blobs).where(eq(blobs.id, id)).get()?.data
-      // node:sqlite allocates a dedicated ArrayBuffer per BLOB column value.
-      return data ? (data as Uint8Array<ArrayBuffer>) : null
+    getBlob(id: string): Uint8Array | null {
+      return db.select({ data: blobs.data }).from(blobs).where(eq(blobs.id, id)).get()?.data ?? null
    },
    flush: writer.flush,
    close: writer.close,
@@ -3,5 +3,6 @@ export const DEFAULT_SERVER_URL_KEY = "defaultServerUrl"
 export const FIRST_LAUNCH_ONBOARDING_COMPLETE_KEY = "firstLaunchOnboardingComplete"
 export const WSL_SERVERS_KEY = "wslServers"
 export const PINCH_ZOOM_ENABLED_KEY = "pinchZoomEnabled"
+export const KEEP_SCREEN_ACTIVE_KEY = "keepScreenActive"
 export const BACKGROUND_COLOR_KEY = "backgroundColor"
 export const WINDOW_IDS_KEY = "windowIds"
@@ -18,4 +18,8 @@ export const migrations = [
    id: "20260907031611_blob-touched",
    statements: ["ALTER TABLE `blob` ADD `touched_at` integer DEFAULT 0 NOT NULL;"],
  },
+  {
+    id: "20260915071310_pairing-state",
+    statements: ["CREATE TABLE `pairing` (\n\t`key` text PRIMARY KEY,\n\t`value` text NOT NULL\n);"],
+  },
 ]
@@ -0,0 +1,4 @@
+CREATE TABLE `pairing` (
+	`key` text PRIMARY KEY,
+	`value` text NOT NULL
+);
@@ -0,0 +1,174 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "id": "bfb5a007-b9ab-4835-be4e-45f0bd6d3ddb",
+  "prevIds": [
+    "53c65132-8703-42d6-8464-64356145dfb4"
+  ],
+  "ddl": [
+    {
+      "name": "blob",
+      "entityType": "tables"
+    },
+    {
+      "name": "document",
+      "entityType": "tables"
+    },
+    {
+      "name": "pairing",
+      "entityType": "tables"
+    },
+    {
+      "name": "state",
+      "entityType": "tables"
+    },
+    {
+      "type": "text",
+      "notNull": false,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "id",
+      "entityType": "columns",
+      "table": "blob"
+    },
+    {
+      "type": "blob",
+      "notNull": true,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "data",
+      "entityType": "columns",
+      "table": "blob"
+    },
+    {
+      "type": "integer",
+      "notNull": true,
+      "autoincrement": false,
+      "default": "0",
+      "generated": null,
+      "name": "touched_at",
+      "entityType": "columns",
+      "table": "blob"
+    },
+    {
+      "type": "text",
+      "notNull": false,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "key",
+      "entityType": "columns",
+      "table": "document"
+    },
+    {
+      "type": "text",
+      "notNull": true,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "value",
+      "entityType": "columns",
+      "table": "document"
+    },
+    {
+      "type": "text",
+      "notNull": false,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "key",
+      "entityType": "columns",
+      "table": "pairing"
+    },
+    {
+      "type": "text",
+      "notNull": true,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "value",
+      "entityType": "columns",
+      "table": "pairing"
+    },
+    {
+      "type": "text",
+      "notNull": true,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "name",
+      "entityType": "columns",
+      "table": "state"
+    },
+    {
+      "type": "text",
+      "notNull": true,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "key",
+      "entityType": "columns",
+      "table": "state"
+    },
+    {
+      "type": "text",
+      "notNull": true,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "value",
+      "entityType": "columns",
+      "table": "state"
+    },
+    {
+      "type": "integer",
+      "notNull": true,
+      "autoincrement": false,
+      "default": null,
+      "generated": null,
+      "name": "updated_at",
+      "entityType": "columns",
+      "table": "state"
+    },
+    {
+      "columns": [
+        "name",
+        "key"
+      ],
+      "nameExplicit": false,
+      "name": "state_pk",
+      "entityType": "pks",
+      "table": "state"
+    },
+    {
+      "columns": [
+        "id"
+      ],
+      "nameExplicit": false,
+      "name": "blob_pk",
+      "table": "blob",
+      "entityType": "pks"
+    },
+    {
+      "columns": [
+        "key"
+      ],
+      "nameExplicit": false,
+      "name": "document_pk",
+      "table": "document",
+      "entityType": "pks"
+    },
+    {
+      "columns": [
+        "key"
+      ],
+      "nameExplicit": false,
+      "name": "pairing_pk",
+      "table": "pairing",
+      "entityType": "pks"
+    }
+  ],
+  "renames": []
+}
@@ -27,3 +27,10 @@ export const state = sqliteTable(
  },
  (table) => [primaryKey({ columns: [table.name, table.key] })],
 )
+
+// Main-process pairing integration state. Tailscale Serve persists its configuration, and this
+// remembers which HTTPS port belongs to OpenCode so it can be recovered without touching other routes.
+export const pairing = sqliteTable("pairing", {
+  key: text().primaryKey(),
+  value: text().notNull(),
+})
@@ -15,6 +15,7 @@ import type {
  ServerReadyData,
  TitlebarTheme,
 } from "../shared/ipc-contract"
+import type { PairingInfo } from "../shared/ipc-rpc/app"

 export type WslServersAPI = WslServersPlatform
 export type UpdaterAPI = {
@@ -87,4 +88,11 @@ export type ElectronAPI = {
  setForceFocus(enabled: boolean): Promise<void>
  recordFatalRendererError(error: FatalRendererError): Promise<void>
  setNativeTranslations(bundle: DesktopNativeBundle): Promise<void>
+  pairInfo(): Promise<typeof PairingInfo.Type>
+  getKeepScreenActive(): Promise<boolean>
+  setKeepScreenActive(enabled: boolean): Promise<void>
+  pairTailscaleAvailable(): Promise<boolean>
+  pairTailscaleStatus(): Promise<typeof PairingInfo.Type | null>
+  pairOpenTailscale(): Promise<typeof PairingInfo.Type>
+  pairDisableTailscale(): Promise<void>
 }
@@ -149,4 +149,11 @@ export const api: ElectronAPI = {
  setForceFocus: (enabled) => invoke("AppSetForceFocus", { enabled }),
  recordFatalRendererError: (error) => invoke("AppRecordFatalRendererError", { error }),
  setNativeTranslations: (bundle) => invoke("AppSetNativeTranslations", { value: bundle }),
+  pairInfo: () => invoke("AppPairInfo").then(mutable),
+  getKeepScreenActive: () => invoke("AppGetKeepScreenActive"),
+  setKeepScreenActive: (enabled) => invoke("AppSetKeepScreenActive", { enabled }),
+  pairTailscaleAvailable: () => invoke("AppPairTailscaleAvailable"),
+  pairTailscaleStatus: () => invoke("AppPairTailscaleStatus").then(mutable),
+  pairOpenTailscale: () => invoke("AppPairOpenTailscale").then(mutable),
+  pairDisableTailscale: () => invoke("AppPairDisableTailscale"),
 }
@@ -1,5 +1,6 @@
-import { Context, Effect, Layer, ManagedRuntime, Queue, Schema, Stream } from "effect"
-import { RpcClient, RpcMessage } from "effect/unstable/rpc"
+import { Context, Effect, Layer, ManagedRuntime, Queue, Stream } from "effect"
+import { RpcClient, RpcMessage, RpcSerialization } from "effect/unstable/rpc"
+import { createIpcCodec } from "../shared/ipc-codec"
 import { DesktopRpcs, type DesktopRpcClient } from "../shared/ipc-rpc"
 import type { DesktopEvent } from "../shared/ipc-rpc/events"
 import { IpcTransportPort } from "../shared/ipc-transport"
@@ -79,17 +80,22 @@ export function listen<Tag extends EventTag>(tag: Tag, listener: (value: EventVa
  }
 }

-// Structured clone over the port, like Effect's worker protocol: no serialization layer, so binary
-// payloads stay binary. Buffers are cloned rather than transferred: Electron's MessagePortMain
-// drops transferred ArrayBuffers, so a request carrying one would never arrive.
 function clientProtocol(value: MessagePort) {
  return Layer.effect(
    RpcClient.Protocol,
    RpcClient.Protocol.make(
      Effect.fnUntraced(function* (writeResponse, clientIds) {
+        const serialization = yield* RpcSerialization.RpcSerialization
+        const parser = createIpcCodec(serialization)
        const inbound = yield* Queue.unbounded<RpcMessage.FromServerEncoded>()
        const onMessage = (event: MessageEvent) => {
-          Queue.offerUnsafe(inbound, event.data as RpcMessage.FromServerEncoded)
+          try {
+            parser
+              .decode(event.data)
+              .forEach((message) => Queue.offerUnsafe(inbound, message as RpcMessage.FromServerEncoded))
+          } catch {
+            return
+          }
        }
        value.addEventListener("message", onMessage)
        value.start()
@@ -106,15 +112,16 @@ function clientProtocol(value: MessagePort) {
          Effect.forkScoped,
        )
        return {
-          codecFor: Schema.toCodecJson,
+          codecFor: serialization.codecFor,
          send: (_clientId, request) =>
            Effect.sync(() => {
-              value.postMessage(request)
+              const encoded = parser.encode(request)
+              if (encoded !== undefined) value.postMessage(encoded)
            }),
          supportsAck: true,
          supportsTransferables: false,
        }
      }),
    ),
-  )
+  ).pipe(Layer.provide(RpcSerialization.layerMsgPack))
 }
@@ -79,6 +79,8 @@ export function createDesktopPlatform(
    windowFullscreen,
    getPinchZoomEnabled: () => api.getPinchZoomEnabled(),
    setPinchZoomEnabled,
+    getKeepScreenActive: () => api.getKeepScreenActive(),
+    setKeepScreenActive: (enabled) => api.setKeepScreenActive(enabled),
    onDragCancel: (callback) => {
      window.addEventListener(DragCancelEvent, callback)
      return () => window.removeEventListener(DragCancelEvent, callback)
@@ -87,6 +89,13 @@ export function createDesktopPlatform(
    checkAppExists: async (appName) => {
      return api.checkAppExists(appName)
    },
+    pair: {
+      info: () => api.pairInfo(),
+      tailscaleAvailable: () => api.pairTailscaleAvailable(),
+      tailscaleStatus: () => api.pairTailscaleStatus(),
+      openTailscale: () => api.pairOpenTailscale(),
+      disableTailscale: () => api.pairDisableTailscale(),
+    },
  }
 }

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test"
+import { RpcSerialization } from "effect/unstable/rpc"
+import { createIpcCodec, ipcLargeMessageBytes } from "./ipc-codec"
+
+type Serialization = RpcSerialization.RpcSerialization["Service"]
+
+const msgpack = RpcSerialization.makeMsgPack()
+
+function counting(serialization: Serialization) {
+  let created = 0
+  const counted: Serialization = {
+    ...serialization,
+    makeUnsafe: () => {
+      created++
+      return serialization.makeUnsafe()
+    },
+  }
+  return { created: () => created, serialization: counted }
+}
+
+describe("ipc codec", () => {
+  test("posts an exact-size buffer instead of a view into the shared target", () => {
+    const codec = createIpcCodec(msgpack)
+    // The msgpack target starts at 8 KiB, so a view would drag a larger backing store along.
+    const encoded = codec.encode({ _tag: "Request", id: "1", tag: "Ping", payload: {} })
+    expect(encoded).toBeInstanceOf(Uint8Array)
+    const bytes = encoded as Uint8Array
+    expect(bytes.byteOffset).toBe(0)
+    expect(bytes.buffer.byteLength).toBe(bytes.byteLength)
+  })
+
+  test("copies Node Buffers, whose slice is only a view", () => {
+    const backing = new ArrayBuffer(1024 * 1024)
+    const view = Buffer.from(backing, 16, 32)
+    view.fill(7)
+    const stub: Serialization = { ...msgpack, makeUnsafe: () => ({ decode: () => [], encode: () => view }) }
+    const encoded = createIpcCodec(stub).encode({}) as Uint8Array
+    expect(encoded.buffer).not.toBe(backing)
+    expect(encoded.buffer.byteLength).toBe(32)
+    expect([...encoded]).toEqual(Array(32).fill(7))
+  })
+
+  test("replaces the encoder after a large message and keeps the decoder", () => {
+    const spy = counting(msgpack)
+    const codec = createIpcCodec(spy.serialization)
+    expect(spy.created()).toBe(2)
+    codec.encode({ small: true })
+    expect(spy.created()).toBe(2)
+    codec.encode({ large: "x".repeat(ipcLargeMessageBytes) })
+    expect(spy.created()).toBe(3)
+    codec.decode(codec.encode({ after: 1 }) as Uint8Array)
+    expect(spy.created()).toBe(3)
+  })
+
+  test("round-trips messages through the wrapped serialization", () => {
+    const client = createIpcCodec(msgpack)
+    const server = createIpcCodec(msgpack)
+    const message = { _tag: "Request", id: "7", tag: "DraftsSet", payload: { key: "k", value: "v" } }
+    expect(server.decode(client.encode(message) as Uint8Array)).toEqual([message])
+  })
+})
@@ -0,0 +1,25 @@
+import type { RpcSerialization } from "effect/unstable/rpc"
+
+// After a message this large the encoder is replaced so its grown target buffer can be collected.
+export const ipcLargeMessageBytes = 1024 * 1024
+
+// The MessagePack parser packs into one shared, grow-only target buffer and returns a view into it.
+// Posting that view structured-clones the whole backing buffer, so after one large message every
+// later message (even a 55-byte ack) would copy the full grown buffer across processes on each
+// send. Encoding through this wrapper posts an exact-size copy instead. Decoding keeps a single
+// parser for the connection: record structures the peer defined inline must stay known.
+export function createIpcCodec(serialization: RpcSerialization.RpcSerialization["Service"]) {
+  const decoder = serialization.makeUnsafe()
+  let encoder = serialization.makeUnsafe()
+  return {
+    decode: (bytes: Uint8Array | string) => decoder.decode(bytes),
+    encode(message: unknown) {
+      const encoded = encoder.encode(message)
+      if (!(encoded instanceof Uint8Array)) return encoded
+      // Not `.slice()`: in the main process the packer hands out a Node Buffer, whose slice is a view.
+      const copy = new Uint8Array(encoded)
+      if (copy.byteLength > ipcLargeMessageBytes) encoder = serialization.makeUnsafe()
+      return copy
+    },
+  }
+}
@@ -5,6 +5,12 @@ const ServerReadyData = Schema.Struct({
  url: Schema.String,
 })

+export const PairingInfo = Schema.Struct({
+  urls: Schema.Array(Schema.String),
+  username: Schema.Literal("opencode"),
+  password: Schema.String,
+})
+
 export const AppAwaitInitialization = Rpc.make("AppAwaitInitialization", { success: ServerReadyData })
 export const AppReconnectService = Rpc.make("AppReconnectService", { success: ServerReadyData })
 export const AppConsumeInitialDeepLinks = Rpc.make("AppConsumeInitialDeepLinks", {
@@ -53,6 +59,19 @@ export const AppSetNativeTranslations = Rpc.make("AppSetNativeTranslations", {
  payload: { value: Schema.Unknown },
 })
 export const AppRelaunch = Rpc.make("AppRelaunch")
+export const AppPairInfo = Rpc.make("AppPairInfo", { success: PairingInfo, error: Schema.String })
+export const AppPairTailscaleAvailable = Rpc.make("AppPairTailscaleAvailable", { success: Schema.Boolean })
+export const AppPairTailscaleStatus = Rpc.make("AppPairTailscaleStatus", {
+  success: Schema.NullOr(PairingInfo),
+  error: Schema.String,
+})
+export const AppPairOpenTailscale = Rpc.make("AppPairOpenTailscale", { success: PairingInfo, error: Schema.String })
+export const AppPairDisableTailscale = Rpc.make("AppPairDisableTailscale", { error: Schema.String })
+export const AppGetKeepScreenActive = Rpc.make("AppGetKeepScreenActive", { success: Schema.Boolean })
+export const AppSetKeepScreenActive = Rpc.make("AppSetKeepScreenActive", {
+  payload: { enabled: Schema.Boolean },
+  error: Schema.String,
+})
 export const AppRpcs = RpcGroup.make(
  AppAwaitInitialization,
  AppReconnectService,
@@ -69,4 +88,11 @@ export const AppRpcs = RpcGroup.make(
  AppRecordFatalRendererError,
  AppSetNativeTranslations,
  AppRelaunch,
+  AppPairInfo,
+  AppPairTailscaleAvailable,
+  AppPairTailscaleStatus,
+  AppPairOpenTailscale,
+  AppPairDisableTailscale,
+  AppGetKeepScreenActive,
+  AppSetKeepScreenActive,
 )
@@ -1,6 +1,5 @@
 import { Schema } from "effect"
 import { Rpc, RpcGroup } from "effect/unstable/rpc"
-import { Transferable } from "effect/unstable/workers"

 const OptionalString = Schema.optional(Schema.String)
 const PickerOptions = Schema.Struct({
@@ -19,7 +18,7 @@ const PickedFiles = Schema.Struct({
  token: Schema.String,
  files: Schema.Array(Schema.Struct({ path: Schema.String, name: Schema.String, size: Schema.Number })),
 })
-const ClipboardImage = Schema.Struct({ buffer: Transferable.Uint8Array, width: Schema.Number, height: Schema.Number })
+const ClipboardImage = Schema.Struct({ buffer: Schema.Uint8Array, width: Schema.Number, height: Schema.Number })

 export const FilesOpenDirectoryPicker = Rpc.make("FilesOpenDirectoryPicker", {
  payload: { options: Schema.optional(PickerOptions) },
@@ -31,7 +30,7 @@ export const FilesOpenFilePicker = Rpc.make("FilesOpenFilePicker", {
 })
 export const FilesReadPickedFile = Rpc.make("FilesReadPickedFile", {
  payload: { token: Schema.String, path: Schema.String },
-  success: Transferable.Uint8Array,
+  success: Schema.Uint8Array,
 })
 export const FilesReleasePickedFiles = Rpc.make("FilesReleasePickedFiles", {
  payload: { token: Schema.String },
@@ -1,6 +1,5 @@
 import { Schema } from "effect"
 import { Rpc, RpcGroup } from "effect/unstable/rpc"
-import { Transferable } from "effect/unstable/workers"

 export const StorageItems = Rpc.make("StorageItems", {
  payload: { name: Schema.String },
@@ -25,12 +24,12 @@ export const DraftsSet = Rpc.make("DraftsSet", {
 })
 export const DraftsDelete = Rpc.make("DraftsDelete", { payload: { key: Schema.String } })
 export const DraftsPutBlob = Rpc.make("DraftsPutBlob", {
-  payload: { data: Transferable.Uint8Array },
+  payload: { data: Schema.Uint8Array },
  success: Schema.String,
 })
 export const DraftsGetBlob = Rpc.make("DraftsGetBlob", {
  payload: { id: Schema.String },
-  success: Schema.NullOr(Transferable.Uint8Array),
+  success: Schema.NullOr(Schema.Uint8Array),
 })

 export const StorageRpcs = RpcGroup.make(
@@ -1,6 +1,6 @@
 {
  "name": "@opencode/enterprise",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "private": true,
  "type": "module",
  "license": "MIT",
@@ -1,6 +1,6 @@
 {
  "name": "@opencode/function",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "$schema": "https://json.schemastore.org/package.json",
  "private": true,
  "type": "module",
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "name": "@opencode/http-recorder",
  "description": "Record and replay Effect HTTP and WebSocket traffic with deterministic cassettes",
  "type": "module",
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/httpapi-codegen",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "private": true,
  "type": "module",
  "exports": {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/latex",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "private": true,
  "type": "module",
  "exports": {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/merman",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "private": true,
  "type": "module",
  "exports": {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/plugin-browser",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "description": "OpenCode's desktop browser plugin",
  "type": "module",
  "license": "MIT",
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/plugin",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "type": "module",
  "license": "MIT",
  "scripts": {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/protocol",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "type": "module",
  "license": "MIT",
  "repository": {
@@ -1,7 +1,7 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
  "name": "@opencode/schema",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "type": "module",
  "license": "MIT",
  "repository": {
@@ -1,6 +1,6 @@
 {
  "$schema": "https://json.schemastore.org/package.json",
-  "version": "2.0.8",
+  "version": "2.0.7",
  "name": "@opencode/sdk",
  "type": "module",
  "license": "MIT",
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Shoubhit Dash	f9b2f88800	refactor(app): simplify local pairing screen	2026-09-19 19:26:26 +05:30
Shoubhit Dash	8471930f89	refactor(app): trim pairing comments and tests	2026-09-19 18:42:13 +05:30
Shoubhit Dash	9f5ea6bb7f	docs: describe the pairing link	2026-09-19 18:39:52 +05:30
Shoubhit Dash	8ae6eac751	feat(cli): pair with an app.opencode.ai link	2026-09-19 18:39:52 +05:30
Shoubhit Dash	e5657b88c0	feat(app): hand off local network pairing links to the server	2026-09-19 18:39:52 +05:30
Shoubhit Dash	a23edd0094	feat(app): accept pairing links in the qr scanner	2026-09-19 18:39:48 +05:30
Brendonovich	b70d006aa1	chore: merge v2 into device pairing	2026-09-18 08:00:41 +00:00
Brendan Allan	5aabcf324d	feat(desktop): add device pairing over local networks and Tailscale	2026-09-16 14:42:28 +08:00