test(app): verify pairing sheet autofocus

Root-owned dialogs could not present over a sibling native dialog on iOS. Use the existing app-wide sheet stack for both native presentation forms, and release the underlying keyboard when a new sheet opens.

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.10.2 - 2026-09-30
+
+### Fixed
+
+- Fixed OpenCode v2 turns longer than five minutes failing with `UND_ERR_HEADERS_TIMEOUT` ([#5674](https://github.com/getpaseo/paseo/pull/5674))
+- Fixed the context meter staying empty during OpenCode v2 turns and disappearing after them ([#5710](https://github.com/getpaseo/paseo/pull/5710) by [@mcowger](https://github.com/mcowger))
+- Fixed OpenCode v2 question cards showing only the header and offering no typed answer ([#5679](https://github.com/getpaseo/paseo/pull/5679))
+- Fixed OpenCode v2 patch edits from GPT models showing as a raw Patch card instead of an edit diff ([#5696](https://github.com/getpaseo/paseo/pull/5696))
+- Fixed completed OpenCode v2 edits showing no diff ([#5609](https://github.com/getpaseo/paseo/pull/5609))
+
 ## 0.10.1 - 2026-09-29
 
 ### Added

docs/agent-lifecycle.md

@@ -34,8 +34,8 @@ workflows all live in the CLI process, and the completion notification that woul
 agent never arrives. A runtime that dies mid-turn is reported by whatever is draining its stream, but
 between turns nothing is watching, so the agent sits at `idle` looking healthy while its background
 work is gone. Report that exit as a turn failure so the agent lands in `error` with a timeline entry.
-Only the Claude provider does this today; the others still report a death only when a turn happens to
-be in flight.
+Claude and OMP report exits between turns. OMP relaunches from its session file on the next prompt;
+the unfinished turn is lost.
 
 ### Cancellation
 

docs/design.md

@@ -193,7 +193,7 @@ Terminology:
 
 Loading is inline by default. `<LoadingSpinner size={14} color={foregroundMuted} />` sits next to the thing it relates to (`packages/app/src/screens/settings/providers-section.tsx:227-231`). Page-level loading is a centered `<LoadingSpinner size="large">` (`packages/app/src/screens/sessions-screen.tsx:69-72`). Card-level loading is a single short line, not a spinner. In-row dropdown items use `<DropdownMenuItem status="pending" pendingLabel="Removing...">`; the menu item handles its own pending state.
 
-Empty states are short noun phrases. Centered, muted, one or two lines. Sessions screen pairs the empty noun with a single ghost button to navigate back (`packages/app/src/screens/sessions-screen.tsx:74-81`); that pairing is the maximum elaboration. Illustrations and CTAs disguised as empty states are wrong.
+Screen-level empty states use a centered, muted noun phrase and at most one ghost button (`packages/app/src/screens/sessions-screen.tsx`). Sidebar list empty states use a quiet bordered card with a left-aligned `sm` title, a muted `sm` description, and `xs` `<Button>` actions. Use `secondary` for the primary action and `outline` for a secondary action (`packages/app/src/components/sidebar/empty-states.tsx`). Keep both forms short and free of illustrations.
 
 Inline errors are a single sentence in `palette.red[300]` `xs`, sitting under the field or inside the card it relates to (`packages/app/src/screens/settings/providers-section.tsx:115-119`).
 

docs/providers.md

@@ -99,6 +99,8 @@ Pi RPC extension UI dialog requests (`select`, `input`, `editor`, `confirm`) are
 
 OpenCode adapters target v1.14.46 and v2.0.10. V2 rejects binaries older than the tested 2.0.10 SDK at runtime selection. Runtime selection uses the configured command and environment. A recognized version is cached until provider configuration reload; a failed, timed-out, or unrecognized probe retains the v1 path and retries detection on the next operation. Load v2 code and materialize its plugin only after positive v2 selection; v1 sessions remain undecorated. Keep upstream SDK types inside the version-specific adapter. OpenCode owns storage migration; a missing native session must fail resume rather than create a replacement. V2 has no native archive/unarchive operation: archiving affects Paseo only. V1 retains native archiving.
 
+Use OpenCode v2 execution events to trigger turn completion, with active-state and durable-log reconciliation after admission, reconnect, and while a turn remains active. Do not use `session.wait`: a healthy turn exceeding Node's HTTP headers deadline produces a transport error while OpenCode keeps working. The live event feed has no replay, and shutdown interruption preserves the previous idle outcome, so the session snapshot alone cannot recover missed execution events. Quiet streams are healthy: v2 heartbeats are SSE comments, not application events.
+
 V2.0.4 also removed the activation endpoint that gated a cold location, and a cold location registers its config-derived commands, skills, and providers asynchronously. Wait until `plugin.list` returns a populated inventory before reading the catalog or commands; an empty inventory means the location is still warming. Fail when the readiness deadline expires, including when an inventory request stalls.
 
 Paseo installs its OpenCode tool bridge through `OPENCODE_CONFIG_CONTENT`. V1 accepts a plugin file; v2 silently skips configured files and requires a package directory with a server entry point. Both versions use the daemon's private loopback bridge for caller-scoped tools. Bridge context lives only in daemon memory and is removed when the Paseo session closes. The content-addressed plugin artifacts contain no session data or secrets. V2 also needs this plugin when native Paseo tools are disabled: its prompt API has no structured-output format, so the plugin supplies a schema-validated final-answer tool.

packages/app/e2e/browser/codex-speed.spec.ts

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { expect, test, type Page } from "../support/fixtures";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import { openAgentRoute } from "../support/helpers/mock-agent";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { connectDaemonClient } from "../support/helpers/daemon-client-loader";
+
+// This fixture catalog advertises Ultrafast on Sol; another model offers Fast only.
+// The real daemon discovers both through the same Codex model/list boundary.
+test.use({
+  e2eDaemonConfig: {
+    version: 1,
+    agents: {
+      providers: {
+        codex: {
+          enabled: true,
+          command: [process.execPath, path.resolve("e2e/fixtures/catalog-codex.mjs")],
+        },
+        claude: { enabled: false },
+        copilot: { enabled: false },
+        opencode: { enabled: false },
+        pi: { enabled: false },
+        omp: { enabled: false },
+      },
+    },
+  },
+});
+
+async function openSpeedSelector(page: Page): Promise<void> {
+  const speed = page.getByRole("button", { name: /^(Select speed|Speed: .+)$/ });
+  const features = page.getByRole("button", { name: "Open agent features", exact: true });
+  const modelSettings = page.getByRole("button", { name: /^Select model \(/ });
+  await expect(speed.or(features).or(modelSettings).filter({ visible: true }).first()).toBeVisible({
+    timeout: 30_000,
+  });
+  if (!(await speed.isVisible())) {
+    if (await features.isVisible()) await features.click();
+    else await modelSettings.click();
+  }
+  await expect(speed).toBeVisible({ timeout: 30_000 });
+  await speed.click();
+  await expect(page.getByText("Normal", { exact: true }).last()).toBeVisible();
+}
+
+async function selectSpeed(page: Page, label: string): Promise<void> {
+  await page.getByRole("button", { name: label, exact: true }).last().click();
+  const toolbarTrigger = page.getByRole("button", { name: `Speed: ${label}`, exact: true });
+  const sheetTrigger = page.getByRole("button", { name: "Select speed", exact: true });
+  await expect(toolbarTrigger.or(sheetTrigger)).toBeVisible();
+  if (await toolbarTrigger.isVisible()) await expect(toolbarTrigger).toHaveText("");
+  else await expect(sheetTrigger).toContainText(label);
+}
+
+async function expectSpeedChoices(page: Page, choices: string[]): Promise<void> {
+  for (const choice of ["Normal", "Fast", "Ultrafast"]) {
+    const option = page.getByText(choice, { exact: true }).last();
+    if (choices.includes(choice)) {
+      await expect(option).toBeVisible();
+      await expect(option).toBeInViewport({ ratio: 1 });
+    } else await expect(option).not.toBeVisible();
+  }
+}
+
+async function switchAgentModel(agentId: string, modelId: string): Promise<void> {
+  const client = await connectDaemonClient<
+    Pick<DaemonClient, "setAgentModel" | "close" | "connect">
+  >({
+    clientIdPrefix: "codex-speed-model",
+  });
+  try {
+    await client.setAgentModel(agentId, modelId);
+  } finally {
+    await client.close();
+  }
+}
+
+for (const viewport of [
+  { name: "desktop", width: 1280, height: 850 },
+  { name: "compact", width: 390, height: 844 },
+]) {
+  test(`Codex catalog drives speed choices on ${viewport.name}`, async ({ page }, testInfo) => {
+    test.setTimeout(180_000);
+    await page.setViewportSize(viewport);
+    const workspace = await seedWorkspace({ repoPrefix: "codex-speed-" });
+    try {
+      const agent = await workspace.client.createAgent({
+        provider: "codex",
+        cwd: workspace.repoPath,
+        workspaceId: workspace.workspaceId,
+        title: "Speed settings",
+        model: "gpt-6.1-sol",
+        modeId: "full-access",
+        initialPrompt: "Get ready to work on this project.",
+      });
+      await openAgentRoute(page, { workspaceId: workspace.workspaceId, agentId: agent.id });
+      if (viewport.name === "desktop") {
+        const trigger = page.getByRole("button", { name: "Speed: Normal", exact: true });
+        await expect(trigger).toBeVisible({ timeout: 30_000 });
+        await expect(trigger).toHaveText("");
+        await page.screenshot({ path: testInfo.outputPath("desktop-normal-trigger.png") });
+      }
+      await openSpeedSelector(page);
+      await expectSpeedChoices(page, ["Normal", "Fast", "Ultrafast"]);
+      await page.screenshot({ path: testInfo.outputPath(`${viewport.name}-speed-options.png`) });
+      await selectSpeed(page, "Ultrafast");
+      await openSpeedSelector(page);
+      await expectSpeedChoices(page, ["Normal", "Fast", "Ultrafast"]);
+      await page.screenshot({
+        path: testInfo.outputPath(`${viewport.name}-ultrafast-selected.png`),
+      });
+      await selectSpeed(page, "Normal");
+      if (viewport.name === "desktop") {
+        await switchAgentModel(agent.id, "gpt-6-sol");
+        await openSpeedSelector(page);
+        await expectSpeedChoices(page, ["Normal", "Fast"]);
+        await page.screenshot({ path: testInfo.outputPath("desktop-fast-only.png") });
+      }
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+}

packages/app/e2e/browser/content-width.spec.ts

@@ -0,0 +1,70 @@
+import { test } from "../support/fixtures";
+import {
+  expectContentColumnWidth,
+  expectCustomContentWidthSetting,
+  expectDefaultContentWidthSetting,
+  openAppearanceSettings,
+  resetContentWidth,
+  setContentWidth,
+} from "../support/helpers/content-width";
+import { openFileExplorer, openFileFromExplorer } from "../support/helpers/file-explorer";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+
+const ULTRAWIDE_VIEWPORT = { width: 2560, height: 1080 };
+
+test("widens chat and Markdown files to the chosen content width and resets to the default", async ({
+  page,
+}, testInfo) => {
+  test.setTimeout(120_000);
+  const agent = await seedMockAgentWorkspace({
+    repoPrefix: "content-width-",
+    title: "Content width",
+    initialPrompt: "Write a long paragraph.",
+  });
+
+  try {
+    await agent.client.waitForFinish(agent.agentId, 30_000);
+    await page.setViewportSize(ULTRAWIDE_VIEWPORT);
+    const assistantMessage = page.getByTestId("assistant-message").first();
+    const markdownPreview = page.getByTestId("markdown-preview-frame").first();
+
+    await test.step("chat starts at the default width", async () => {
+      await openAgentRoute(page, agent);
+      await expectContentColumnWidth(assistantMessage, { max: 820 });
+    });
+
+    await test.step("settings show the default without a reset", async () => {
+      await openAppearanceSettings(page);
+      await expectDefaultContentWidthSetting(page, 820);
+    });
+
+    await test.step("a custom width is saved and offers a reset", async () => {
+      await setContentWidth(page, 1600);
+      await expectCustomContentWidthSetting(page, 1600);
+      await page.screenshot({ path: testInfo.outputPath("settings-custom-width.png") });
+    });
+
+    await test.step("chat and Markdown files use the custom width", async () => {
+      await openAgentRoute(page, agent);
+      await expectContentColumnWidth(assistantMessage, { min: 1200, max: 1600 });
+      await page.screenshot({ path: testInfo.outputPath("chat-custom-width.png") });
+
+      await openFileExplorer(page);
+      await openFileFromExplorer(page, "README.md");
+      await expectContentColumnWidth(markdownPreview, { min: 1200, max: 1600 });
+      await page.screenshot({ path: testInfo.outputPath("markdown-custom-width.png") });
+    });
+
+    await test.step("reset returns to the default without storing it", async () => {
+      await openAppearanceSettings(page);
+      await resetContentWidth(page);
+      await expectDefaultContentWidthSetting(page, 820);
+
+      await openAgentRoute(page, agent);
+      await expectContentColumnWidth(assistantMessage, { max: 820 });
+      await page.screenshot({ path: testInfo.outputPath("chat-default-width.png") });
+    });
+  } finally {
+    await agent.cleanup();
+  }
+});

packages/app/e2e/browser/host-confirmation.spec.ts

@@ -0,0 +1,51 @@
+import { test, expect } from "../support/fixtures";
+import { openSettings } from "../support/helpers/app";
+import { expectAppRoute } from "../support/helpers/route-assertions";
+import {
+  buildPairingLink,
+  cancelHostConfirmation,
+  connectToConfirmedHost,
+  expectHostConfirmationFor,
+  expectHostInHostPicker,
+  hostConfirmation,
+  openPairingLink,
+  saveLinkedHostBeforeLoad,
+  type LinkedHost,
+} from "../support/helpers/host-confirmation";
+
+// An unreachable relay: the link saves the host without connecting first.
+const linkedHost: LinkedHost = {
+  serverId: "srv_link_confirmation",
+  relayEndpoint: "127.0.0.1:59998",
+  daemonPublicKeyB64: "bGlua0NvbmZpcm1hdGlvbktleQ",
+};
+
+test("a pairing link for a new host asks before saving it", async ({ page }) => {
+  const link = buildPairingLink(linkedHost);
+
+  await test.step("Cancel saves nothing and stays on the page", async () => {
+    await openPairingLink(page, link);
+    await expectHostConfirmationFor(page, linkedHost);
+    await cancelHostConfirmation(page);
+    await expectAppRoute(page, "/settings/general");
+    await expectHostInHostPicker(page, linkedHost.serverId, "not listed");
+  });
+
+  await test.step("Connect saves the host and opens a project", async () => {
+    await openPairingLink(page, link);
+    await expectHostConfirmationFor(page, linkedHost);
+    await connectToConfirmedHost(page);
+    await expectAppRoute(page, "/open-project");
+    await openSettings(page);
+    await expectHostInHostPicker(page, linkedHost.serverId, "listed");
+  });
+});
+
+test("a pairing link for a saved host connects without asking", async ({ page }) => {
+  await saveLinkedHostBeforeLoad(page, linkedHost);
+
+  await openPairingLink(page, buildPairingLink(linkedHost));
+
+  await expectAppRoute(page, "/open-project", { timeout: 30_000 });
+  await expect(hostConfirmation(page)).toHaveCount(0);
+});

packages/app/e2e/browser/usage-composer-pill.spec.ts

@@ -1,11 +1,7 @@
 import type { UsageReportEntry } from "@getpaseo/protocol/messages";
 import { expect, test, type Page } from "../support/fixtures";
 import { expectComposerVisible, submitMessage } from "../support/helpers/composer";
-import {
-  openAgentRoute,
-  seedMockAgentWorkspace,
-  seedRunningMockAgentWorkspace,
-} from "../support/helpers/mock-agent";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
 import { installUsageReportsFixture } from "../support/helpers/usage-reports";
 
 const REPORT_ID = "fixture:fixture-account";
@@ -46,30 +42,6 @@ async function openMockAgent(page: Page) {
 }
 
 test.describe("usage composer pill", () => {
-  test("shows the report when an existing running chat opens", async ({ page }) => {
-    test.setTimeout(180_000);
-    const usage = await installUsageReportsFixture(page, {
-      agentReportIds: [REPORT_ID],
-      lists: [[agentEntry(42)]],
-    });
-    const session = await seedRunningMockAgentWorkspace({
-      repoPrefix: "usage-running-",
-      title: "Running usage pill",
-      initialPrompt: "Show usage during the turn.",
-      model: "one-minute-stream",
-    });
-    try {
-      await openAgentRoute(page, session);
-      await expectComposerVisible(page);
-      await expect(page.getByTestId("usage-composer-pill")).toContainText("42%", {
-        timeout: 20_000,
-      });
-      expect(usage.agentRequests()[0]).toEqual({ agentId: session.agentId });
-    } finally {
-      await session.cleanup();
-    }
-  });
-
   test("opens the cached report without a request and shows when it was fetched", async ({
     page,
   }) => {

packages/app/e2e/browser/worktree-restore.spec.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { existsSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import path from "node:path";
 import {
   restoreArchivedWorkspace,
@@ -354,6 +355,88 @@ test.describe("Worktree restore", () => {
       .toBeNull();
   });
 
+  test("restores a branchless workspace so its archived agent can be used again", async ({
+    page,
+  }) => {
+    const project = await openProjectViaDaemon(worktreeClient, tempRepo.path);
+    createdProjectIds.add(project.projectKey);
+    const backingWorktree = await createWorktreeViaDaemon(worktreeClient, {
+      cwd: tempRepo.path,
+      slug: `branchless-${randomUUID().slice(0, 8)}`,
+    });
+    createdProjectIds.add(backingWorktree.projectKey);
+    createdWorktreeDirectories.add(backingWorktree.workspaceDirectory);
+
+    execFileSync("git", ["switch", "--detach", "main"], {
+      cwd: backingWorktree.workspaceDirectory,
+      stdio: "pipe",
+    });
+    const created = await worktreeClient.createWorkspace({
+      source: { kind: "directory", path: backingWorktree.workspaceDirectory },
+      title: "Sample workspace",
+    });
+    if (!created.workspace) {
+      throw new Error(created.error ?? "Could not create the branchless workspace");
+    }
+    const workspaceId = created.workspace.id;
+    const agent = await createIdleAgent(client, {
+      cwd: backingWorktree.workspaceDirectory,
+      workspaceId,
+      title: "Archived agent",
+    });
+
+    await archiveWorkspaceFromDaemon(worktreeClient, backingWorktree.workspaceDirectory, {
+      scope: "worktree",
+    });
+    await expect
+      .poll(() => existsSync(backingWorktree.workspaceDirectory), { timeout: 30_000 })
+      .toBe(false);
+    await expect.poll(() => fetchAgentArchivedAt(client, agent.id)).not.toBeNull();
+
+    await gotoAppShell(page);
+    await waitForSidebarHydration(page);
+    await openSessions(page);
+    await page.getByTestId(`agent-row-${getServerId()}-${agent.id}`).click();
+    await expect(page.getByText("Workspace archived", { exact: true })).toBeVisible();
+    await expect(
+      page.getByText(
+        "Restore Sample workspace to return to its agents. A new branch will start from the saved base or the repository default.",
+        { exact: true },
+      ),
+    ).toBeVisible();
+    await captureBranchlessRestoreStep(page, "01-restore-workspace.png");
+
+    await page.getByRole("button", { name: "Restore", exact: true }).click();
+    await expect
+      .poll(() => existsSync(backingWorktree.workspaceDirectory), { timeout: 30_000 })
+      .toBe(true);
+    await expect(page.getByRole("button", { name: "Unarchive", exact: true })).toBeVisible({
+      timeout: 30_000,
+    });
+    await captureBranchlessRestoreStep(page, "02-unarchive-agent.png");
+
+    await page.getByRole("button", { name: "Unarchive", exact: true }).click();
+    await expect.poll(() => fetchAgentArchivedAt(client, agent.id)).toBeNull();
+    await expect(page.getByRole("textbox", { name: "Message agent..." })).toBeEditable();
+    await captureBranchlessRestoreStep(page, "03-agent-ready.png");
+
+    const restoredHead = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd: backingWorktree.workspaceDirectory,
+      encoding: "utf8",
+    }).trim();
+    const defaultHead = execFileSync("git", ["rev-parse", "main"], {
+      cwd: tempRepo.path,
+      encoding: "utf8",
+    }).trim();
+    expect(restoredHead).toBe(defaultHead);
+    expect(
+      execFileSync("git", ["branch", "--show-current"], {
+        cwd: backingWorktree.workspaceDirectory,
+        encoding: "utf8",
+      }).trim(),
+    ).toMatch(/^restored\//);
+  });
+
   test("restore failure stays visible and permits a successful retry", async ({ page }) => {
     const { agent, worktree } = await openArchivedWorkspaceFromHistory(page, "restore-retry");
     const displacedProjectPath = `${tempRepo.path}-temporarily-unavailable`;
@@ -422,6 +505,12 @@ test.describe("Worktree restore", () => {
   });
 });
 
+async function captureBranchlessRestoreStep(page: Page, filename: string): Promise<void> {
+  const screenshotDirectory = path.join(tmpdir(), "paseo-branchless-restore-evidence");
+  mkdirSync(screenshotDirectory, { recursive: true });
+  await page.screenshot({ path: path.join(screenshotDirectory, filename), fullPage: true });
+}
+
 function commitRestorableChange(cwd: string): void {
   writeFileSync(path.join(cwd, "restored-change.txt"), "preserved after restore\n");
   execFileSync("git", ["add", "restored-change.txt"], { cwd, stdio: "pipe" });

packages/app/e2e/fixtures/catalog-codex.mjs

@@ -0,0 +1,88 @@
+import readline from "node:readline";
+import { randomUUID } from "node:crypto";
+
+const fast = { id: "priority", name: "Fast", description: "Faster processing, increased usage" };
+const ultra = {
+  id: "ultrafast",
+  name: "Ultrafast",
+  description: "Lowest latency, increased usage",
+};
+const models = [
+  { id: "gpt-6.1-sol", displayName: "GPT-6.1 Sol", isDefault: true, serviceTiers: [fast, ultra] },
+  { id: "gpt-6-sol", displayName: "GPT-6 Sol", serviceTiers: [fast] },
+].map((model) =>
+  Object.assign(model, {
+    model: model.id,
+    defaultReasoningEffort: "medium",
+    supportedReasoningEfforts: [{ reasoningEffort: "medium", description: "Medium" }],
+  }),
+);
+
+function send(message) {
+  process.stdout.write(JSON.stringify(message) + "\n");
+}
+function respond(method, params) {
+  switch (method) {
+    case "initialize":
+      return {};
+    case "model/list":
+      return { data: models };
+    case "config/read":
+      return { config: { model: models[0].id, model_reasoning_effort: "medium" } };
+    case "collaborationMode/list":
+      return { data: [] };
+    case "skills/list":
+      return { data: [] };
+    case "thread/list":
+    case "thread/loaded/list":
+      return { data: [] };
+    case "thread/start":
+      return { thread: { id: randomUUID() }, model: params.model };
+    case "thread/resume":
+      return { thread: { id: params.threadId } };
+    case "thread/read":
+      return { thread: { id: params.threadId, turns: [] } };
+    case "turn/start": {
+      const turnId = randomUUID();
+      setTimeout(() => {
+        send({
+          method: "turn/started",
+          params: { threadId: params.threadId, turn: { id: turnId } },
+        });
+        send({
+          method: "item/completed",
+          params: {
+            threadId: params.threadId,
+            turnId,
+            item: {
+              id: randomUUID(),
+              type: "agentMessage",
+              text: "Ready to work on this project.",
+            },
+          },
+        });
+        send({
+          method: "turn/completed",
+          params: { threadId: params.threadId, turn: { id: turnId, status: "completed" } },
+        });
+      }, 50);
+      return { turn: { id: turnId } };
+    }
+    default:
+      throw new Error(`Unsupported Codex fixture request: ${method}`);
+  }
+}
+
+if (process.argv.includes("--version")) {
+  console.log("codex-cli 0.159.0");
+} else {
+  readline.createInterface({ input: process.stdin }).on("line", (line) => {
+    const request = JSON.parse(line);
+    if (request.id === undefined) return;
+    try {
+      send({ id: request.id, result: respond(request.method, request.params ?? {}) });
+    } catch (error) {
+      send({ id: request.id, error: { code: -32601, message: error.message } });
+    }
+  });
+}

packages/app/e2e/mobile/modal-sheet/README.md

@@ -90,3 +90,48 @@ a failed provider tap leaves its modal open, so dismiss it before the next run.
 journeys remain outside the default mobile suite, alongside the compact sheet journeys above.
 
 Keep generated screenshots, recordings, and run logs outside the repository.
+
+## Stacked adaptive sheets
+
+`stacked-pairing.ad` opens the welcome screen's pairing sheet and then the root-mounted host
+confirmation. It first types without tapping the input to verify autofocus, then cancels the
+confirmation, closes and reopens the underlying sheet, confirms again,
+and completes the password retry. `stacked-settings.ad` checks the same return and retry through
+Settings → add host → Direct connection → Advanced. Run both on phones and tablets so both the
+bottom sheet and centered dialog are exercised.
+
+Use a fresh English app with notification permission granted and first-use keyboard prompts
+already dismissed. Load this checkout from an isolated Metro. Start an isolated password-protected
+daemon and a local Wrangler relay with `--var 'PASEO_RELAY_UPSTREAM:'`; the checked-in upstream
+setting otherwise forwards traffic to the hosted relay, which drops password rejection replies.
+Set `PAIRING_LINK` to the daemon's `relay://` URI with an intentionally incorrect `password` query
+parameter, and `PASSWORD` to its correct password. This exercises password retry even while the
+daemon accepts relay connections with no credential.
+
+```sh
+agent-device replay packages/app/e2e/mobile/modal-sheet/stacked-pairing.ad \
+  --state-dir "$SHEET_QA_DEVICE_STATE" --session stacked-ipad --platform ios \
+  --udid "$SHEET_QA_IOS_UDID" \
+  --env PAIRING_LINK="$SHEET_QA_LINK" --env PASSWORD="$SHEET_QA_PASSWORD" \
+  --env OUT="$SHEET_QA_OUTPUT"
+```
+
+For Settings, first open Settings with Add host visible. With a saved host, open Switch host
+first. Use a second loopback spelling
+(`localhost` instead of `127.0.0.1`) for the same local relay so the saved host asks for confirmation
+of its changed connection. Pass that link to `stacked-settings.ad` with the same arguments.
+For an app with no saved hosts, use the original link; Add host is visible directly in Settings.
+
+Android uses the same journeys: copy each script outside the repository, change its context's
+`platform=ios` to `platform=android`, and pass `--serial` instead of `--udid`. Reverse both Metro
+(including the port advertised by its manifest) and the local relay ports. Keep driver state,
+artifacts, and sessions separate from other runs. These host-dependent journeys remain outside the
+default mobile suite, alongside the existing modal-sheet scripts.
+
+On iPhone, bulk replacement or bulk keyboard entry of the advanced URI field triggers a
+repeated-update error with both the parent and stacked-sheet implementations. Entering the complete
+URI one character at a time passed with both implementations; faster typing remains unverified.
+On iPad, replacing the field a second time appends text. For this Settings journey, use the
+native clipboard Paste menu, then continue the assertions manually. Dismiss the password keyboard
+with Done to submit when the Connect button is below the keyboard. The welcome pairing regression
+runs end to end without these adjustments.

packages/app/e2e/mobile/modal-sheet/stacked-pairing.ad

@@ -0,0 +1,50 @@
+# Fresh English app at Welcome, local relay host with PASSWORD, see README.md.
+# Run on phones and tablets: the confirmation lives at the root, outside the pairing sheet.
+context platform=ios timeout=180000 retries=0
+env APP_ID=sh.paseo.debug
+
+open "${APP_ID}"
+wait "id=\"welcome-paste-pairing-link\"" 20000
+screenshot "${OUT}/01-welcome.png"
+press "id=\"welcome-paste-pairing-link\""
+wait stable
+# Type without tapping the input: opening the sheet must retain its autofocus.
+wait "id=\"pair-link-input\"" 10000
+type "relay://"
+wait "id=\"pair-link-input\" value=\"relay://\"" 5000
+screenshot "${OUT}/20-pairing-autofocus-without-tap.png"
+fill "id=\"pair-link-input\"" "${PAIRING_LINK}"
+wait stable
+screenshot "${OUT}/02-pairing-input.png"
+press "id=\"pair-link-submit\""
+wait stable
+wait "id=\"host-confirmation-connect\"" 10000
+screenshot "${OUT}/03-confirmation-on-top.png"
+press "id=\"host-confirmation-cancel\""
+wait stable
+wait "id=\"pair-link-submit\" enabled=true" 10000
+screenshot "${OUT}/04-cancel-returns-to-pairing.png"
+# Close and reopen the underlying sheet, then edit it and submit again.
+press "id=\"pair-link-cancel\""
+wait stable
+wait "id=\"welcome-paste-pairing-link\"" 10000
+screenshot "${OUT}/05-underlying-sheet-closes.png"
+press "id=\"welcome-paste-pairing-link\""
+wait stable
+wait "id=\"pair-link-input\"" 10000
+fill "id=\"pair-link-input\"" "${PAIRING_LINK}"
+wait stable
+press "id=\"pair-link-submit\""
+wait stable
+wait "id=\"host-confirmation-connect\"" 10000
+screenshot "${OUT}/06-confirmation-reopens.png"
+press "id=\"host-confirmation-connect\""
+wait stable
+wait "id=\"pair-link-password-input\"" 20000
+screenshot "${OUT}/07-password-after-connect.png"
+fill "id=\"pair-link-password-input\"" "${PASSWORD}"
+wait stable
+press "id=\"pair-link-submit\""
+wait stable
+wait text "Open a folder on your machine" 30000
+screenshot "${OUT}/08-connected.png"

packages/app/e2e/mobile/modal-sheet/stacked-settings.ad

@@ -0,0 +1,46 @@
+# Settings with Add host visible: no saved hosts, or the host picker already open.
+context platform=ios timeout=180000 retries=0
+env APP_ID=sh.paseo.debug
+open "${APP_ID}"
+wait "id=\"settings-add-host\"" 20000
+screenshot "${OUT}/09-settings.png"
+press "id=\"settings-add-host\""
+wait stable
+wait "id=\"add-host-method-direct\"" 10000
+screenshot "${OUT}/10-add-host-methods.png"
+press "id=\"add-host-method-direct\""
+wait stable
+press "id=\"direct-host-advanced-toggle\""
+wait stable
+fill "id=\"direct-host-uri-input\"" "${PAIRING_LINK}"
+wait stable
+screenshot "${OUT}/11-add-host-relay-input.png"
+press "id=\"direct-host-submit\""
+wait stable
+wait "id=\"host-confirmation-connect\"" 10000
+screenshot "${OUT}/12-add-host-confirmation-on-top.png"
+press "id=\"host-confirmation-cancel\""
+wait stable
+wait "id=\"direct-host-submit\" enabled=true" 10000
+screenshot "${OUT}/13-cancel-returns-to-add-host.png"
+# Editing the underlying sheet proves it still accepts input after closing the top sheet.
+fill "id=\"direct-host-uri-input\"" "${PAIRING_LINK}"
+wait stable
+press "id=\"direct-host-submit\""
+wait stable
+wait "id=\"host-confirmation-connect\"" 10000
+screenshot "${OUT}/14-add-host-confirmation-reopens.png"
+press "id=\"host-confirmation-connect\""
+wait stable
+wait "id=\"direct-password-input\"" 20000
+screenshot "${OUT}/15-add-host-password.png"
+fill "id=\"direct-password-input\"" "${PASSWORD}"
+wait stable
+press "id=\"direct-host-submit\""
+wait stable
+open "${APP_ID}" "paseo://settings"
+wait "label=\"Connections\"" 10000
+press "label=\"Connections\""
+wait stable
+wait "id=\"host-page-connections-card\"" 30000
+screenshot "${OUT}/16-settings-connected.png"

packages/app/e2e/support/helpers/content-width.ts

@@ -0,0 +1,63 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+import { openSettings } from "./app";
+import { openSettingsSection } from "./settings";
+
+const APP_SETTINGS_KEY = "@paseo:app-settings";
+
+function contentWidthInput(page: Page): Locator {
+  return page.getByLabel("Content width in pixels", { exact: true });
+}
+
+function resetContentWidthButton(page: Page): Locator {
+  return page.getByRole("button", { name: "Reset content width to default", exact: true });
+}
+
+export async function openAppearanceSettings(page: Page): Promise<void> {
+  await openSettings(page);
+  await openSettingsSection(page, "appearance");
+}
+
+export async function setContentWidth(page: Page, width: number): Promise<void> {
+  const input = contentWidthInput(page);
+  await input.fill(String(width));
+  await input.press("Tab");
+}
+
+export async function resetContentWidth(page: Page): Promise<void> {
+  await resetContentWidthButton(page).click();
+}
+
+export async function expectDefaultContentWidthSetting(page: Page, width: number): Promise<void> {
+  await expect(contentWidthInput(page)).toHaveValue(String(width));
+  await expect(resetContentWidthButton(page)).toHaveCount(0);
+  await expect.poll(() => readStoredContentWidth(page)).toBeNull();
+}
+
+export async function expectCustomContentWidthSetting(page: Page, width: number): Promise<void> {
+  await expect(contentWidthInput(page)).toHaveValue(String(width));
+  await expect(resetContentWidthButton(page)).toBeVisible();
+  await expect.poll(() => readStoredContentWidth(page)).toBe(width);
+}
+
+/** Asserts the rendered width of a content-column element stays within `max` and above `min`. */
+export async function expectContentColumnWidth(
+  element: Locator,
+  bounds: { min?: number; max: number },
+): Promise<void> {
+  await expect(element).toBeVisible({ timeout: 30_000 });
+  await expect
+    .poll(async () => (await element.boundingBox())?.width ?? 0)
+    .toBeLessThanOrEqual(bounds.max);
+  await expect
+    .poll(async () => (await element.boundingBox())?.width ?? 0)
+    .toBeGreaterThan(bounds.min ?? 0);
+}
+
+async function readStoredContentWidth(page: Page): Promise<unknown> {
+  return page.evaluate((key) => {
+    const raw = localStorage.getItem(key);
+    return raw === null
+      ? undefined
+      : (JSON.parse(raw) as { contentMaxWidth?: unknown }).contentMaxWidth;
+  }, APP_SETTINGS_KEY);
+}

packages/app/e2e/support/helpers/host-confirmation.ts

@@ -0,0 +1,95 @@
+import { expect, type Locator, type Page } from "@playwright/test";
+
+const EXTRA_HOSTS_KEY = "@paseo:e2e-extra-hosts";
+
+export interface LinkedHost {
+  serverId: string;
+  relayEndpoint: string;
+  daemonPublicKeyB64: string;
+}
+
+/**
+ * A pairing link that opens on the settings page. `/` redirects to
+ * `/open-project` on its own, so starting in settings leaves the pairing link
+ * as the only thing that can move the app to `/open-project`.
+ */
+export function buildPairingLink(host: LinkedHost): string {
+  const offer = {
+    v: 2,
+    serverId: host.serverId,
+    daemonPublicKeyB64: host.daemonPublicKeyB64,
+    relay: { endpoint: host.relayEndpoint, useTls: false },
+  };
+  const encoded = Buffer.from(JSON.stringify(offer), "utf8").toString("base64url");
+  return `/settings/general#offer=${encoded}`;
+}
+
+/** Loads the app from a pairing link, the way opening the link in a browser does. */
+export async function openPairingLink(page: Page, link: string): Promise<void> {
+  // Leave the link's page first so the link always loads the app from scratch.
+  await page.goto("/");
+  await page.goto(link);
+}
+
+/** Saves a relay host before the app loads, as if it had been paired in an earlier session. */
+export async function saveLinkedHostBeforeLoad(page: Page, host: LinkedHost): Promise<void> {
+  await page.goto("/");
+  const nowIso = new Date().toISOString();
+  const connectionId = `relay:${host.relayEndpoint}`;
+  const savedHost = {
+    serverId: host.serverId,
+    label: host.serverId,
+    connections: [
+      {
+        id: connectionId,
+        type: "relay",
+        relayEndpoint: host.relayEndpoint,
+        useTls: false,
+        daemonPublicKeyB64: host.daemonPublicKeyB64,
+      },
+    ],
+    preferredConnectionId: connectionId,
+    createdAt: nowIso,
+    updatedAt: nowIso,
+  };
+  await page.evaluate(({ key, hosts }) => localStorage.setItem(key, JSON.stringify(hosts)), {
+    key: EXTRA_HOSTS_KEY,
+    hosts: [savedHost],
+  });
+}
+
+export function hostConfirmation(page: Page): Locator {
+  return page.getByTestId("host-confirmation");
+}
+
+export async function expectHostConfirmationFor(page: Page, host: LinkedHost): Promise<void> {
+  const sheet = hostConfirmation(page);
+  await expect(sheet.getByText("Connect to this host?", { exact: true })).toBeVisible({
+    timeout: 30_000,
+  });
+  await expect(sheet.getByTestId("host-confirmation-server-id")).toHaveText(host.serverId);
+  await expect(sheet.getByTestId("host-confirmation-relay")).toHaveText(host.relayEndpoint);
+}
+
+export async function cancelHostConfirmation(page: Page): Promise<void> {
+  await hostConfirmation(page).getByRole("button", { name: "Cancel", exact: true }).click();
+  await expect(hostConfirmation(page)).toHaveCount(0);
+}
+
+export async function connectToConfirmedHost(page: Page): Promise<void> {
+  await hostConfirmation(page).getByRole("button", { name: "Connect", exact: true }).click();
+  await expect(hostConfirmation(page)).toHaveCount(0);
+}
+
+/** Checks the host picker on the settings page the app is already showing. */
+export async function expectHostInHostPicker(
+  page: Page,
+  serverId: string,
+  expected: "listed" | "not listed",
+): Promise<void> {
+  await page.getByTestId("settings-host-picker").click();
+  await expect(page.getByTestId(`settings-host-picker-item-${serverId}`)).toHaveCount(
+    expected === "listed" ? 1 : 0,
+  );
+  await page.keyboard.press("Escape");
+}

packages/app/src/agent-stream/strategy-web.test.tsx

@@ -1,6 +1,7 @@
 /**
  * @vitest-environment jsdom
  */
+import { DEFAULT_CONTENT_MAX_WIDTH } from "@/styles/theme";
 import React from "react";
 import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
@@ -144,6 +145,7 @@ describe("createWebStreamStrategy", () => {
             listStyle: null,
             baseListContentContainerStyle: null,
             forwardListContentContainerStyle: null,
+            contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
           })}
         </>,
       );
@@ -187,6 +189,7 @@ describe("createWebStreamStrategy", () => {
           listStyle: null,
           baseListContentContainerStyle: null,
           forwardListContentContainerStyle: null,
+          contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
         }),
       );
     });
@@ -233,6 +236,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -291,6 +295,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     const unrevised = {
       contentById: new Set<string>(),
@@ -354,6 +359,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -429,6 +435,7 @@ describe("createWebStreamStrategy", () => {
           listStyle: null,
           baseListContentContainerStyle: null,
           forwardListContentContainerStyle: null,
+          contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
         }),
       );
     });
@@ -473,6 +480,7 @@ describe("createWebStreamStrategy", () => {
           listStyle: null,
           baseListContentContainerStyle: null,
           forwardListContentContainerStyle: null,
+          contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
         }),
       );
     });
@@ -553,6 +561,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -646,6 +655,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -755,6 +765,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -860,6 +871,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -959,6 +971,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -1056,6 +1069,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -1175,6 +1189,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     container = document.createElement("div");
     document.body.appendChild(container);
@@ -1408,6 +1423,7 @@ describe("createWebStreamStrategy", () => {
       listStyle: null,
       baseListContentContainerStyle: null,
       forwardListContentContainerStyle: null,
+      contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
     };
     const renderWithActivity = (active: boolean, input: StreamRenderInput = renderInput) => (
       <RetainedPanelActivity active={active}>{strategy.render(input)}</RetainedPanelActivity>

packages/app/src/agent-stream/strategy-web.tsx

@@ -303,6 +303,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     hasOlderHistory,
     olderHistoryProgressKey,
     scrollEnabled,
+    contentMaxWidth,
     isMobileBreakpoint,
   } = props;
   const historyVirtualized = useRevisedHistoryRows(
@@ -403,7 +404,7 @@ function WebStreamViewport(props: StreamRenderInput & { isMobileBreakpoint: bool
     getItemKey: (index: number) => segments.historyVirtualized[index]?.id ?? index,
     estimateSize: (index: number) => {
       const row = segments.historyVirtualized[index];
-      return row ? estimateStreamItemHeight(row) : 120;
+      return row ? estimateStreamItemHeight(row, contentMaxWidth) : 120;
     },
     measureElement: measureVirtualElement,
     rangeExtractor,

packages/app/src/agent-stream/strategy.ts

@@ -92,6 +92,8 @@ export interface StreamRenderInput {
   listStyle: StyleProp<ViewStyle>;
   baseListContentContainerStyle: StyleProp<ViewStyle>;
   forwardListContentContainerStyle: StyleProp<ViewStyle>;
+  // The chat column's max width. The web viewport estimates unmeasured row heights with it.
+  contentMaxWidth: number;
 }
 
 export interface ResolveStreamRenderStrategyInput {

packages/app/src/agent-stream/turn-footer.tsx

@@ -1,7 +1,6 @@
 import React, { memo, useCallback, useMemo, type ReactNode } from "react";
 import { View } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
-import { MAX_CONTENT_WIDTH } from "@/constants/layout";
 import { SPACING, type Theme } from "@/styles/theme";
 import type { TurnTiming } from "@/timeline/turn-time";
 import type { StreamItem } from "@/types/stream";
@@ -215,7 +214,7 @@ function TurnFooterRow({ children }: { children: ReactNode }) {
 const stylesheet = StyleSheet.create((theme) => ({
   streamItemWrapper: {
     width: "100%",
-    maxWidth: MAX_CONTENT_WIDTH,
+    maxWidth: theme.contentMaxWidth,
     alignSelf: "center",
     paddingHorizontal: theme.spacing[2],
   },

packages/app/src/agent-stream/view.tsx

@@ -23,7 +23,7 @@ import {
   type ViewStyle,
 } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
-import { MAX_CONTENT_WIDTH, useIsCompactFormFactor } from "@/constants/layout";
+import { useIsCompactFormFactor } from "@/constants/layout";
 import { useMutation } from "@tanstack/react-query";
 import Animated, { FadeIn, FadeOut } from "react-native-reanimated";
 import { Check, ChevronDown, X } from "lucide-react-native";
@@ -55,7 +55,7 @@ import { useSessionStore } from "@/stores/session-store";
 import { useRevealedText } from "@/hooks/use-revealed-text";
 import { useFileExplorerActions } from "@/hooks/use-file-explorer-actions";
 import { useLoadOlderAgentHistory } from "@/hooks/use-load-older-agent-history";
-import { useSettings } from "@/hooks/use-settings";
+import { resolveContentMaxWidth, useSettings } from "@/hooks/use-settings";
 import type { ToastApi } from "@/components/toast-host";
 import { returnToTimelineTail } from "./timeline-tail-navigation";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
@@ -349,6 +349,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
     const autoExpandReasoning = useSettings((settings) => settings.autoExpandReasoning);
     const toolCallDetailLevel = useSettings((settings) => settings.toolCallDetailLevel);
     const chatOutlineEnabled = useSettings((settings) => settings.chatOutlineEnabled);
+    const contentMaxWidth = useSettings(resolveContentMaxWidth);
     const viewportRef = useRef<StreamViewportHandle | null>(null);
     const pendingClientMessageIds = useMemo(
       () => new Set(pendingMessageSubmissions.map((submission) => submission.clientMessageId)),
@@ -1129,6 +1130,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
                 listStyle: stylesheet.list,
                 baseListContentContainerStyle: stylesheet.listContentContainer,
                 forwardListContentContainerStyle: stylesheet.forwardListContentContainer,
+                contentMaxWidth,
               })}
             </MessageOuterSpacingProvider>
             <ChatOutlineRail
@@ -1622,7 +1624,7 @@ const stylesheet = StyleSheet.create((theme) => ({
   },
   contentWrapper: {
     width: "100%",
-    maxWidth: MAX_CONTENT_WIDTH,
+    maxWidth: theme.contentMaxWidth,
     alignSelf: "center",
     paddingHorizontal: theme.spacing[2],
   },
@@ -1643,7 +1645,7 @@ const stylesheet = StyleSheet.create((theme) => ({
   },
   streamItemWrapper: {
     width: "100%",
-    maxWidth: MAX_CONTENT_WIDTH,
+    maxWidth: theme.contentMaxWidth,
     alignSelf: "center",
     paddingHorizontal: theme.spacing[2],
   },

packages/app/src/agent-stream/web-virtualization.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { DEFAULT_CONTENT_MAX_WIDTH } from "@/styles/theme";
 import type { StreamItem } from "@/types/stream";
 import {
   clearAssistantImageMetadataCache,
@@ -123,8 +124,8 @@ describe("splitWebVirtualizedHistory", () => {
 
 describe("estimateStreamItemHeight", () => {
   it("uses compact estimates for collapsed tool sequence rows", () => {
-    expect(estimateStreamItemHeight(toolCall("tool", 1))).toBe(40);
-    expect(estimateStreamItemHeight(thought("thought", 2))).toBe(40);
+    expect(estimateStreamItemHeight(toolCall("tool", 1), DEFAULT_CONTENT_MAX_WIDTH)).toBe(40);
+    expect(estimateStreamItemHeight(thought("thought", 2), DEFAULT_CONTENT_MAX_WIDTH)).toBe(40);
   });
 
   it("uses a larger estimate for user messages with image attachments", () => {
@@ -146,7 +147,7 @@ describe("estimateStreamItemHeight", () => {
       ],
     };
 
-    expect(estimateStreamItemHeight(item)).toBe(220);
+    expect(estimateStreamItemHeight(item, DEFAULT_CONTENT_MAX_WIDTH)).toBe(220);
   });
 
   it("uses cached assistant image metadata when available", () => {
@@ -165,7 +166,7 @@ describe("estimateStreamItemHeight", () => {
       timestamp: createTimestamp(2),
     };
 
-    expect(estimateStreamItemHeight(item)).toBeGreaterThan(220);
+    expect(estimateStreamItemHeight(item, DEFAULT_CONTENT_MAX_WIDTH)).toBeGreaterThan(220);
   });
 });
 

packages/app/src/agent-stream/web-virtualization.ts

@@ -58,12 +58,12 @@ export interface WebVirtualizedHistoryWindow {
   mountedEntries: IndexedStreamItem[];
 }
 
-export function estimateStreamItemHeight(item: StreamItem): number {
+export function estimateStreamItemHeight(item: StreamItem, contentMaxWidth: number): number {
   switch (item.kind) {
     case "user_message":
       return item.images && item.images.length > 0 ? 220 : 96;
     case "assistant_message":
-      return estimateAssistantMessageHeightFromCache(item.text) ?? 220;
+      return estimateAssistantMessageHeightFromCache(item.text, contentMaxWidth) ?? 220;
     case "tool_call":
       return COLLAPSED_TOOL_SEQUENCE_ROW_HEIGHT_ESTIMATE;
     case "thought":

packages/app/src/app/_layout.tsx

@@ -45,6 +45,7 @@ import { WorkspaceSetupDialog } from "@/components/workspace-setup-dialog";
 import { WorkspaceShortcutTargetsSubscriber } from "@/components/workspace-shortcut-targets-subscriber";
 import { FloatingPanelPortalHost } from "@/components/ui/floating-panel-portal";
 import { HostChooserModal, useHostChooser } from "@/hosts/host-chooser";
+import { HostConfirmationSheet } from "@/hosts/host-confirmation-sheet";
 import {
   getIsElectronRuntime,
   HEADER_INNER_HEIGHT,
@@ -606,6 +607,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
         <CommandCenter />
         <AddProjectFlowHost />
         <HostChooserModal />
+        <HostConfirmationSheet />
         <ProviderSettingsHost />
         <WorkspaceSetupDialog />
         <KeyboardShortcutsDialog />

packages/app/src/app/pair-scan.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
 import { Pressable, Text, View } from "react-native";
 import { useLocalSearchParams, useRouter, type Href } from "expo-router";
@@ -7,10 +7,12 @@ import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { CameraView, useCameraPermissions } from "expo-camera";
 import type { BarcodeScanningResult, BarcodeSettings } from "expo-camera";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
+import { openPairScan } from "@/hosts/pair-scan-model";
 import { buildHostRootRoute, buildSettingsHostRoute } from "@/utils/host-routes";
 import { isWeb } from "@/constants/platform";
 import { BackHeader } from "@/components/headers/back-header";
 import { PairLinkModal } from "@/components/pair-link-modal";
+import { Button } from "@/components/ui/button";
 
 const styles = StyleSheet.create((theme) => ({
   container: {
@@ -73,6 +75,9 @@ const styles = StyleSheet.create((theme) => ({
     borderBottomWidth: 4,
     borderBottomRightRadius: 12,
   },
+  scanAgainButton: {
+    marginTop: theme.spacing[6],
+  },
   helperText: {
     marginTop: theme.spacing[6],
     color: theme.colors.foregroundMuted,
@@ -108,16 +113,6 @@ const styles = StyleSheet.create((theme) => ({
   },
 }));
 
-function extractOfferUrlFromScan(result: BarcodeScanningResult): string | null {
-  const raw = typeof result.data === "string" ? result.data.trim() : "";
-  if (!raw) return null;
-
-  if (raw.includes("#offer=") || raw.includes("#connect=") || raw.startsWith("relay://"))
-    return raw;
-
-  return null;
-}
-
 export default function PairScanScreen() {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
@@ -129,9 +124,6 @@ export default function PairScanScreen() {
   const source = typeof params.source === "string" ? params.source : "settings";
 
   const [permission, requestPermission] = useCameraPermissions();
-  const [isPairing, setIsPairing] = useState(false);
-  const [scanError, setScanError] = useState<string | null>(null);
-  const [passwordOfferUrl, setPasswordOfferUrl] = useState<string | null>(null);
 
   const navigateToPairedHost = useCallback(
     (serverId: string) => {
@@ -144,6 +136,19 @@ export default function PairScanScreen() {
     [router, source],
   );
 
+  const [scan] = useState(() =>
+    openPairScan({
+      importConnectionLink: (link) =>
+        getHostRuntimeStore().importConnectionLink(
+          link,
+          source === "onboarding" ? "hostRoot" : "hostSettings",
+        ),
+      onConnected: navigateToPairedHost,
+    }),
+  );
+  const scanState = useSyncExternalStore(scan.subscribe, scan.getState, scan.getState);
+  useEffect(() => () => scan.close(), [scan]);
+
   const closeToSource = useCallback(() => {
     try {
       router.back();
@@ -159,30 +164,12 @@ export default function PairScanScreen() {
   }, [permission, requestPermission]);
 
   const handleScan = useCallback(
-    (result: BarcodeScanningResult) => {
-      if (isPairing) return;
-      const offerUrl = extractOfferUrlFromScan(result);
-      if (!offerUrl) return;
-
-      const store = getHostRuntimeStore();
-      if (passwordOfferUrl) return;
-      setIsPairing(true);
-      setScanError(null);
-      void store
-        .importConnectionLink(offerUrl, source === "onboarding" ? "hostRoot" : "hostSettings")
-        .then((outcome) => {
-          if (outcome.status === "connected") navigateToPairedHost(outcome.serverId);
-          else setPasswordOfferUrl(offerUrl);
-          return outcome;
-        })
-        .catch((error) => setScanError(error instanceof Error ? error.message : String(error)))
-        .finally(() => setIsPairing(false));
-    },
-    [isPairing, navigateToPairedHost, passwordOfferUrl, source],
+    (result: BarcodeScanningResult) =>
+      scan.scan(typeof result.data === "string" ? result.data : ""),
+    [scan],
   );
 
   const handleRouterBack = useCallback(() => router.back(), [router]);
-  const closePasswordModal = useCallback(() => setPasswordOfferUrl(null), []);
   const savePasswordPairing = useCallback(
     ({ serverId }: { serverId: string }) => navigateToPairedHost(serverId),
     [navigateToPairedHost],
@@ -240,24 +227,38 @@ export default function PairScanScreen() {
               barcodeScannerSettings={BARCODE_SCANNER_SETTINGS}
               onBarcodeScanned={handleScan}
             />
-            <View style={styles.overlay} pointerEvents="none">
+            <View style={styles.overlay} pointerEvents="box-none">
               <View style={styles.scanFrame}>
                 <View style={[styles.corner, styles.cornerTL]} />
                 <View style={[styles.corner, styles.cornerTR]} />
                 <View style={[styles.corner, styles.cornerBL]} />
                 <View style={[styles.corner, styles.cornerBR]} />
               </View>
-              {isPairing ? <Text style={helperTextStyle}>{t("pairing.scan.pairing")}</Text> : null}
-              {scanError ? <Text style={helperTextStyle}>{scanError}</Text> : null}
+              {scanState.status === "pairing" ? (
+                <Text style={helperTextStyle}>{t("pairing.scan.pairing")}</Text>
+              ) : null}
+              {scanState.status === "stopped" && scanState.error ? (
+                <Text style={helperTextStyle}>{scanState.error}</Text>
+              ) : null}
+              {scanState.status === "stopped" ? (
+                <Button
+                  style={styles.scanAgainButton}
+                  onPress={scan.scanAgain}
+                  testID="pair-scan-again"
+                >
+                  {t("pairing.connectionMethods.scanQr.title")}
+                </Button>
+              ) : null}
             </View>
           </View>
         )}
       </View>
       <PairLinkModal
-        visible={passwordOfferUrl !== null}
-        initialUrl={passwordOfferUrl ?? undefined}
-        initialPasswordRequired
-        onClose={closePasswordModal}
+        visible={scanState.status === "passwordRequired"}
+        passwordRequired={
+          scanState.status === "passwordRequired" ? scanState.passwordRequired : undefined
+        }
+        onClose={scan.closePassword}
         onSaved={savePasswordPairing}
       />
     </View>

packages/app/src/appearance/apply.test.ts

@@ -37,6 +37,7 @@ interface FakeTheme {
     "4xl": number;
   };
   lineHeight: { diff: number };
+  contentMaxWidth: number;
   colors: { foreground: string; syntax: Record<string, string> };
 }
 
@@ -56,6 +57,7 @@ function makeFakeTheme(): FakeTheme {
       "4xl": 26,
     },
     lineHeight: { diff: 22 },
+    contentMaxWidth: 820,
     colors: { foreground: "#fff", syntax: {} },
   };
 }
@@ -67,6 +69,7 @@ function makeInput(overrides: Partial<AppearanceInput> = {}): AppearanceInput {
     uiBaseFontSize: 14,
     contentFontSize: 15,
     codeFontSize: 12,
+    contentMaxWidth: 820,
     syntaxTheme: "one",
     ...overrides,
   };
@@ -102,6 +105,12 @@ describe("applyAppearance", () => {
     ]);
   });
 
+  it("patches the content max width into the theme", () => {
+    applyAppearance(makeInput({ contentMaxWidth: 1600 }));
+
+    expect(runCapturedUpdater().contentMaxWidth).toBe(1600);
+  });
+
   it("resolves an empty UI font family to the default stack", () => {
     applyAppearance(makeInput({ uiFontFamily: "" }));
 

packages/app/src/appearance/apply.ts

@@ -17,6 +17,7 @@ export interface AppearanceInput {
   uiBaseFontSize: number; // already clamped
   contentFontSize: number; // already clamped
   codeFontSize: number; // already clamped
+  contentMaxWidth: number; // already clamped, default resolved
   syntaxTheme: SyntaxThemeId;
 }
 
@@ -55,7 +56,7 @@ function scaleFontSize(
  * always current and makes ordering vs `setTheme`/`setAdaptiveThemes` irrelevant.
  *
  * The updater preserves the active theme wholesale (surfaces, accents,
- * terminal) and only patches the font ramp and syntax palette.
+ * terminal) and only patches the font ramp, content width, and syntax palette.
  * `updateTheme` replaces the stored theme rather than merging, so we spread
  * `...t` first.
  */
@@ -86,6 +87,7 @@ export function applyAppearance(input: AppearanceInput): void {
           fontFamily,
           fontSize,
           lineHeight,
+          contentMaxWidth: input.contentMaxWidth,
           colors: { ...t.colors, syntax: resolveSyntaxColors(input.syntaxTheme, t.colorScheme) },
         };
       }
@@ -94,6 +96,7 @@ export function applyAppearance(input: AppearanceInput): void {
         fontFamily,
         fontSize,
         lineHeight,
+        contentMaxWidth: input.contentMaxWidth,
         colors: { ...t.colors, syntax: resolveSyntaxColors(input.syntaxTheme, t.colorScheme) },
       };
     });

packages/app/src/appearance/provider.tsx

@@ -8,7 +8,12 @@ import {
   useState,
 } from "react";
 import { UnistylesRuntime } from "react-native-unistyles";
-import { DEFAULT_THEME_PREFERENCE, useAppSettings, type AppSettings } from "@/hooks/use-settings";
+import {
+  DEFAULT_THEME_PREFERENCE,
+  resolveContentMaxWidth,
+  useAppSettings,
+  type AppSettings,
+} from "@/hooks/use-settings";
 import {
   rememberPluginThemeHost,
   usePluginThemeCatalog,
@@ -68,6 +73,7 @@ export function AppearanceProvider({ children }: { children: ReactNode }) {
       uiBaseFontSize: settings.uiBaseFontSize,
       contentFontSize: settings.contentFontSize,
       codeFontSize: settings.codeFontSize,
+      contentMaxWidth: resolveContentMaxWidth({ contentMaxWidth: settings.contentMaxWidth }),
       syntaxTheme: settings.syntaxTheme,
     });
     setHasAppliedAppearance(true);
@@ -80,6 +86,7 @@ export function AppearanceProvider({ children }: { children: ReactNode }) {
     settings.uiBaseFontSize,
     settings.contentFontSize,
     settings.codeFontSize,
+    settings.contentMaxWidth,
     settings.syntaxTheme,
   ]);
 

packages/app/src/components/adaptive-modal-sheet.tsx

@@ -1,8 +1,8 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import type { ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { useTranslation } from "react-i18next";
-import { Modal, Platform, Pressable, Text, View } from "react-native";
+import { Keyboard, Pressable, Text, View } from "react-native";
 import type { DimensionValue, StyleProp, ViewStyle } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
@@ -19,7 +19,6 @@ import {
   type BottomSheetBackgroundProps,
 } from "@gorhom/bottom-sheet";
 import Animated, { useAnimatedStyle } from "react-native-reanimated";
-import { GestureHandlerRootView } from "react-native-gesture-handler";
 import { ArrowLeft, Search, X } from "lucide-react-native";
 import {
   IsolatedBottomSheetModal,
@@ -75,11 +74,15 @@ export interface SheetHeader {
 
 const SCROLL_CONTENT_GROW = { flexGrow: 1 };
 const ABSOLUTE_FILL_STYLE = { ...StyleSheet.absoluteFillObject };
+const NATIVE_DIALOG_SNAP_POINTS = ["100%"];
 
 const styles = StyleSheet.create((theme) => ({
-  nativeModalRoot: {
+  nativeDialogSurface: {
     flex: 1,
   },
+  nativeDialogBackground: {
+    backgroundColor: "transparent",
+  },
   desktopOverlay: {
     ...StyleSheet.absoluteFillObject,
     backgroundColor: "rgba(0,0,0,0.55)",
@@ -471,7 +474,7 @@ export interface AdaptiveModalSheetProps {
   contentStyle?: StyleProp<ViewStyle>;
   /** Size compact sheet content to the live snap height instead of its largest snap point. */
   sizeContentToCurrentSnapPoint?: boolean;
-  /** Re-establishes caller-owned contexts inside the compact bottom-sheet portal. */
+  /** Re-establishes caller-owned contexts inside the native or compact sheet portal. */
   contextBridge?: ContextBridge | null;
 }
 
@@ -526,26 +529,26 @@ export function AdaptiveModalSheet({
     () => ({ backgroundColor: theme.colors.palette.zinc[600] }),
     [theme.colors.palette.zinc],
   );
+  useEffect(() => {
+    if (!isWeb && visible) {
+      // A newly opened sheet owns input. A keyboard belonging to the sheet below
+      // would cover controls in the new sheet, which has no focused input yet.
+      Keyboard.dismiss();
+    }
+  }, [visible]);
+
   const { sheetRef, handleSheetChange, handleSheetDismiss } = useIsolatedBottomSheetVisibility({
     visible,
-    isEnabled: isMobile,
+    isEnabled: isMobile || !isWeb,
     onClose,
   });
   const [shouldRenderWeb, setShouldRenderWeb] = useState(visible);
   const [isWebClosing, setIsWebClosing] = useState(false);
   const modalLayer = useGlobalWebOverlayLayer("modal", isWeb && !isMobile && shouldRenderWeb);
-  const nativeModalDismissNotifiedRef = useRef(!visible);
   const handleDismiss = useCallback(() => {
     handleSheetDismiss();
     onDismiss?.();
   }, [handleSheetDismiss, onDismiss]);
-  const notifyNativeModalDismiss = useCallback(() => {
-    if (nativeModalDismissNotifiedRef.current) {
-      return;
-    }
-    nativeModalDismissNotifiedRef.current = true;
-    onDismiss?.();
-  }, [onDismiss]);
 
   const renderBackdrop = useCallback(
     (props: React.ComponentProps<typeof BottomSheetBackdrop>) => (
@@ -592,12 +595,6 @@ export function AdaptiveModalSheet({
     onKeyDown: handleWebOverlayKeyDown,
   });
 
-  useEffect(() => {
-    if (visible) {
-      nativeModalDismissNotifiedRef.current = false;
-    }
-  }, [visible]);
-
   useEffect(() => {
     if (!isWeb || isMobile) return;
     if (visible) {
@@ -615,12 +612,6 @@ export function AdaptiveModalSheet({
     return () => window.clearTimeout(timeout);
   }, [visible, isMobile, onDismiss, shouldRenderWeb]);
 
-  useEffect(() => {
-    if (isWeb || isMobile || visible || Platform.OS !== "android") return;
-    const timeout = setTimeout(notifyNativeModalDismiss, 0);
-    return () => clearTimeout(timeout);
-  }, [visible, isMobile, notifyNativeModalDismiss]);
-
   if (isMobile) {
     const sheetContent = (
       <>
@@ -725,18 +716,28 @@ export function AdaptiveModalSheet({
   }
 
   return (
-    <Modal
-      transparent
-      animationType="fade"
-      visible={visible}
-      onRequestClose={onClose}
-      onDismiss={notifyNativeModalDismiss}
-      hardwareAccelerated
+    // Both native presentations share Gorhom's app-wide stack. Independent RN Modals
+    // present from their React ancestor's controller, so a root-owned sibling dialog
+    // cannot present while that controller already has a dialog open on iOS.
+    <IsolatedBottomSheetModal
+      ref={sheetRef}
+      contextBridge={contextBridge}
+      snapPoints={NATIVE_DIALOG_SNAP_POINTS}
+      index={0}
+      enableDynamicSizing={false}
+      onChange={handleSheetChange}
+      onDismiss={handleDismiss}
+      handleComponent={null}
+      backgroundStyle={styles.nativeDialogBackground}
+      enablePanDownToClose={false}
+      enableHandlePanningGesture={false}
+      enableContentPanningGesture={false}
+      keyboardBehavior="extend"
+      keyboardBlurBehavior="restore"
+      accessible={false}
+      presentation={presentation}
     >
-      {/* Android Modal opens a separate window outside the app's gesture root. */}
-      <GestureHandlerRootView style={styles.nativeModalRoot}>
-        {desktopContent}
-      </GestureHandlerRootView>
-    </Modal>
+      <View style={styles.nativeDialogSurface}>{desktopContent}</View>
+    </IsolatedBottomSheetModal>
   );
 }

packages/app/src/components/add-host-modal.tsx

@@ -294,11 +294,23 @@ export interface AddHostModalProps {
 }
 
 export function AddHostModal({ visible, onClose, onCancel, onSaved }: AddHostModalProps) {
+  return (
+    <AddHostModalContent
+      key={String(visible)}
+      visible={visible}
+      onClose={onClose}
+      onCancel={onCancel}
+      onSaved={onSaved}
+    />
+  );
+}
+
+function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostModalProps) {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const daemons = useHosts();
-  const { probeAndUpsertDirectConnection, probeAndUpsertConnectionFromOfferUrl } =
-    useHostMutations();
+  const { probeAndUpsertDirectConnection, beginLinkPairing } = useHostMutations();
+  const [linkPairing] = useState(() => beginLinkPairing());
   const isMobile = useIsCompactFormFactor();
 
   const [isSaving, setIsSaving] = useState(false);
@@ -313,18 +325,6 @@ export function AddHostModal({ visible, onClose, onCancel, onSaved }: AddHostMod
   const [inputResetKey, bumpInputResetKey] = useReducer((key: number) => key + 1, 0);
   const advancedTarget = useRef(new PairingTargetTracker("", true));
 
-  const clearInput = useCallback(() => {
-    setHost("");
-    setPort("6767");
-    setUseTls(false);
-    setPassword("");
-    setIsPasswordVisible(false);
-    setIsAdvancedOpen(false);
-    setAdvancedUri("");
-    advancedTarget.current = new PairingTargetTracker("", true);
-    bumpInputResetKey();
-  }, []);
-
   const connectIcon = useMemo(
     () => <Link2 size={16} color={theme.colors.accentForeground} />,
     [theme.colors.accentForeground],
@@ -358,29 +358,25 @@ export function AddHostModal({ visible, onClose, onCancel, onSaved }: AddHostMod
   );
   const header = useMemo<SheetHeader>(() => ({ title: t("pairing.direct.title") }), [t]);
 
+  // Each open mounts a fresh form (see AddHostModal), so closing needs no reset.
   const handleClose = useCallback(() => {
     if (isSaving) return;
-    clearInput();
-    setErrorMessage("");
     onClose();
-  }, [isSaving, clearInput, onClose]);
+  }, [isSaving, onClose]);
 
   const handleCancel = useCallback(() => {
     if (isSaving) return;
-    clearInput();
-    setErrorMessage("");
     (onCancel ?? onClose)();
-  }, [isSaving, clearInput, onCancel, onClose]);
+  }, [isSaving, onCancel, onClose]);
 
   const handleSaveRelay = useCallback(
     async (relayUri: string) => {
       try {
         setIsSaving(true);
         setErrorMessage("");
-        const { profile, serverId, hostname } = await probeAndUpsertConnectionFromOfferUrl(
-          relayUri,
-          password || undefined,
-        );
+        const result = await linkPairing.submit(relayUri, password || undefined);
+        if (result.status === "cancelled") return;
+        const { profile, serverId, hostname } = result;
         const isNewHost = !daemons.some((daemon) => daemon.serverId === serverId);
         onSaved?.({ profile, serverId, hostname, isNewHost });
         handleClose();
@@ -396,9 +392,9 @@ export function AddHostModal({ visible, onClose, onCancel, onSaved }: AddHostMod
       daemons,
       directConnectionLabels.invalidConnection,
       handleClose,
+      linkPairing,
       onSaved,
       password,
-      probeAndUpsertConnectionFromOfferUrl,
     ],
   );
 

packages/app/src/components/archived-agent-callout.tsx

@@ -2,7 +2,7 @@ import { useCallback, useState } from "react";
 import { View, Text } from "react-native";
 import { useTranslation } from "react-i18next";
 import { StyleSheet } from "react-native-unistyles";
-import { FOOTER_HEIGHT, MAX_CONTENT_WIDTH } from "@/constants/layout";
+import { FOOTER_HEIGHT } from "@/constants/layout";
 import { useHostRuntimeClient, useHostRuntimeIsConnected } from "@/runtime/host-runtime";
 import { KeyboardTranslateView } from "@/keyboard/shift";
 import { Button } from "@/components/ui/button";
@@ -77,7 +77,7 @@ const styles = StyleSheet.create((theme: Theme) => ({
   },
   inputAreaContent: {
     width: "100%",
-    maxWidth: MAX_CONTENT_WIDTH,
+    maxWidth: theme.contentMaxWidth,
   },
   callout: {
     flexDirection: "row",

packages/app/src/components/pair-link-modal.tsx

@@ -5,7 +5,7 @@ import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { Link } from "lucide-react-native";
 import type { HostProfile } from "@/types/host-connection";
-import { useHosts, useHostMutations } from "@/runtime/host-runtime";
+import { useHosts, useHostMutations, type PasswordRequiredPairing } from "@/runtime/host-runtime";
 import { parseRelayConnectionUri } from "@/utils/daemon-endpoints";
 import { parseConnectionOfferFromUrl } from "@getpaseo/protocol/connection-offer";
 import { AdaptiveModalSheet, AdaptiveTextInput, type SheetHeader } from "./adaptive-modal-sheet";
@@ -62,8 +62,8 @@ const styles = StyleSheet.create((theme) => ({
 
 export interface PairLinkModalProps {
   visible: boolean;
-  initialUrl?: string;
-  initialPasswordRequired?: boolean;
+  /** Continues a confirmed pairing whose host asked for a password. */
+  passwordRequired?: PasswordRequiredPairing;
   onClose: () => void;
   onCancel?: () => void;
   onSaved?: (result: {
@@ -76,18 +76,16 @@ export interface PairLinkModalProps {
 
 export function PairLinkModal({
   visible,
-  initialUrl,
-  initialPasswordRequired = false,
+  passwordRequired,
   onClose,
   onCancel,
   onSaved,
 }: PairLinkModalProps) {
   return (
     <PairLinkModalContent
-      key={`${visible}:${initialUrl ?? ""}:${initialPasswordRequired}`}
+      key={`${visible}:${passwordRequired?.link ?? ""}`}
       visible={visible}
-      initialUrl={initialUrl}
-      initialPasswordRequired={initialPasswordRequired}
+      passwordRequired={passwordRequired}
       onClose={onClose}
       onCancel={onCancel}
       onSaved={onSaved}
@@ -97,8 +95,7 @@ export function PairLinkModal({
 
 function PairLinkModalContent({
   visible,
-  initialUrl,
-  initialPasswordRequired = false,
+  passwordRequired,
   onClose,
   onCancel,
   onSaved,
@@ -106,7 +103,9 @@ function PairLinkModalContent({
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const daemons = useHosts();
-  const { probeAndUpsertConnectionFromOfferUrl } = useHostMutations();
+  const { beginLinkPairing } = useHostMutations();
+  const [pairing] = useState(() => passwordRequired?.pairing ?? beginLinkPairing());
+  const initialUrl = passwordRequired?.link;
   const isMobile = useIsCompactFormFactor();
 
   const offerUrlRef = useRef(initialUrl ?? "");
@@ -115,7 +114,7 @@ function PairLinkModalContent({
   const [isSaving, setIsSaving] = useState(false);
   const [errorMessage, setErrorMessage] = useState("");
   const [password, setPassword] = useState("");
-  const [needsPassword, setNeedsPassword] = useState(initialPasswordRequired);
+  const [needsPassword, setNeedsPassword] = useState(passwordRequired !== undefined);
   const [passwordResetKey, resetPasswordInput] = useReducer((key: number) => key + 1, 0);
 
   const clearInput = useCallback(() => {
@@ -162,10 +161,9 @@ function PairLinkModalContent({
       try {
         setIsSaving(true);
         setErrorMessage("");
-        const { profile, serverId, hostname } = await probeAndUpsertConnectionFromOfferUrl(
-          raw,
-          password || undefined,
-        );
+        const result = await pairing.submit(raw, password || undefined);
+        if (result.status === "cancelled") return;
+        const { profile, serverId, hostname } = result;
         const isNewHost = !daemons.some((daemon) => daemon.serverId === serverId);
         onSaved?.({ profile, serverId, hostname, isNewHost });
         handleClose();
@@ -184,16 +182,7 @@ function PairLinkModalContent({
         setIsSaving(false);
       }
     },
-    [
-      daemons,
-      handleClose,
-      isMobile,
-      isSaving,
-      onSaved,
-      password,
-      t,
-      probeAndUpsertConnectionFromOfferUrl,
-    ],
+    [daemons, handleClose, isMobile, isSaving, onSaved, password, t, pairing],
   );
 
   const handleChangeOfferUrl = useCallback((next: string) => {

packages/app/src/components/sidebar/empty-states.tsx

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { type ReactNode, useCallback } from "react";
 import { Import, Plus } from "lucide-react-native";
 import { useTranslation } from "react-i18next";
 import { Text, View } from "react-native";
@@ -6,6 +6,28 @@ import { StyleSheet } from "react-native-unistyles";
 import { Button } from "@/components/ui/button";
 import { useSidebarViewStore } from "@/stores/sidebar-view-store";
 
+function SidebarEmptyStateCard({
+  testID,
+  title,
+  description,
+  children,
+}: {
+  testID: string;
+  title: string;
+  description: string;
+  children: ReactNode;
+}) {
+  return (
+    <View style={styles.card} testID={testID}>
+      <View style={styles.copy}>
+        <Text style={styles.title}>{title}</Text>
+        <Text style={styles.description}>{description}</Text>
+      </View>
+      <View style={styles.actions}>{children}</View>
+    </View>
+  );
+}
+
 /**
  * The two things the sidebar's workspace list says when it has no rows.
  *
@@ -27,13 +49,15 @@ export function SidebarFilterEmptyState() {
   }, [clearLabelFilter, clearProjectFilters]);
 
   return (
-    <View style={styles.container} testID="sidebar-filter-empty-state">
-      <Text style={styles.title}>{t("sidebar.filterEmpty.title")}</Text>
-      <Text style={styles.description}>{t("sidebar.filterEmpty.description")}</Text>
-      <Button variant="ghost" size="sm" onPress={clearFilters}>
+    <SidebarEmptyStateCard
+      testID="sidebar-filter-empty-state"
+      title={t("sidebar.filterEmpty.title")}
+      description={t("sidebar.filterEmpty.description")}
+    >
+      <Button variant="secondary" size="xs" onPress={clearFilters}>
         {t("sidebar.filterEmpty.clear")}
       </Button>
-    </View>
+    </SidebarEmptyStateCard>
   );
 }
 
@@ -47,40 +71,44 @@ export function SidebarProjectEmptyState({
   const { t } = useTranslation();
 
   return (
-    <View style={styles.container} testID="sidebar-project-empty-state">
-      <Text style={styles.title}>{t("sidebar.project.empty.title")}</Text>
-      <Text style={styles.description}>{t("sidebar.project.empty.description")}</Text>
-      <Button variant="ghost" size="sm" leftIcon={Plus} onPress={onAddProject}>
+    <SidebarEmptyStateCard
+      testID="sidebar-project-empty-state"
+      title={t("sidebar.project.empty.title")}
+      description={t("sidebar.project.empty.description")}
+    >
+      <Button variant="secondary" size="xs" leftIcon={Plus} onPress={onAddProject}>
         {t("sidebar.actions.addProject")}
       </Button>
-      <Button variant="ghost" size="sm" leftIcon={Import} onPress={onImportSession}>
+      <Button variant="outline" size="xs" leftIcon={Import} onPress={onImportSession}>
         {t("importSession.title")}
       </Button>
-    </View>
+    </SidebarEmptyStateCard>
   );
 }
 
 const styles = StyleSheet.create((theme) => ({
-  container: {
-    marginHorizontal: theme.spacing[2],
-    marginTop: theme.spacing[4],
-    paddingTop: theme.spacing[6],
-    paddingBottom: theme.spacing[4],
-    paddingHorizontal: theme.spacing[4],
+  card: {
+    marginTop: theme.spacing[3],
+    padding: theme.spacing[4],
+    borderWidth: 1,
+    borderColor: theme.colors.border,
     borderRadius: theme.borderRadius.lg,
-    backgroundColor: theme.colors.surface0,
-    alignItems: "center",
-    gap: theme.spacing[3],
+  },
+  copy: {
+    gap: theme.spacing[1],
+  },
+  actions: {
+    flexDirection: "row",
+    gap: theme.spacing[2],
+    marginTop: theme.spacing[4],
   },
   title: {
     color: theme.colors.foreground,
     fontSize: theme.fontSize.sm,
-    fontWeight: theme.fontWeight.medium,
-    textAlign: "center",
+    fontWeight: theme.fontWeight.normal,
   },
   description: {
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.sm,
-    textAlign: "center",
   },
 }));

packages/app/src/composer/agent-controls/index.tsx

@@ -1357,6 +1357,10 @@ function DesktopFeatureItem({
   if (feature.type === "select") {
     const FeatureIcon = getAgentFeatureIcon(feature.icon);
     const selectedOption = feature.options.find((o) => o.id === feature.value);
+    const iconOnly = feature.desktopTrigger === "icon";
+    const tooltip = iconOnly
+      ? `${feature.label}: ${selectedOption?.label ?? feature.label}`
+      : getFeatureTooltip(feature);
     return (
       <>
         <Tooltip delayDuration={0} enabledOnDesktop enabledOnMobile={false}>
@@ -1367,15 +1371,16 @@ function DesktopFeatureItem({
               surface="toolbar"
               label={feature.label}
               value={selectedOption?.label ?? feature.label}
+              showToolbarLabel={!iconOnly}
               open={openSelector === featureSelector}
               disabled={disabled}
               onPress={handleSelectPress}
-              accessibilityLabel={getFeatureTooltip(feature)}
+              accessibilityLabel={tooltip}
               testID={`agent-feature-${feature.id}`}
             />
           </TooltipTrigger>
           <TooltipContent side="top" align="center" offset={8}>
-            <Text style={styles.tooltipText}>{getFeatureTooltip(feature)}</Text>
+            <Text style={styles.tooltipText}>{tooltip}</Text>
           </TooltipContent>
         </Tooltip>
         <Combobox

packages/app/src/composer/dock/index.native.tsx

@@ -2,7 +2,8 @@ import { ComposerDockBackground } from "./internal/background";
 export { ComposerDockBackground } from "./internal/background";
 import { ScrollView } from "@/components/ui/scroll-view";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { HEADER_INNER_HEIGHT, MAX_CONTENT_WIDTH } from "@/constants/layout";
+import { HEADER_INNER_HEIGHT } from "@/constants/layout";
+import { resolveContentMaxWidth, useAppSettings } from "@/hooks/use-settings";
 import { KeyboardTranslateView } from "@/keyboard/shift";
 import { createContext, useCallback, useContext, type ReactNode } from "react";
 import { View, type LayoutChangeEvent, type ViewProps, StyleSheet } from "react-native";
@@ -89,6 +90,7 @@ export function ComposerDock({
   centered = false,
 }: ComposerDockProps) {
   const insets = useSafeAreaInsets();
+  const contentMaxWidth = resolveContentMaxWidth(useAppSettings().settings);
   // Preserve the existing centered form's visual balance on tablets.
   const bottomInset = centered ? HEADER_INNER_HEIGHT + 24 : 0;
   if (centered) {
@@ -98,7 +100,7 @@ export function ComposerDock({
         bottomInset={bottomInset}
         centered
       >
-        <KeyboardTranslateView style={dockStyles.centered}>
+        <KeyboardTranslateView style={[dockStyles.centered, { maxWidth: contentMaxWidth }]}>
           <ComposerViewportContent style={dockStyles.composer}>
             <ScrollView style={dockStyles.setup} keyboardShouldPersistTaps="handled">
               {content}
@@ -137,13 +139,15 @@ export function ComposerDock({
   );
 }
 
+// Plain React Native styles: these land on Reanimated views, which must not carry
+// theme-driven Unistyles (docs/unistyles.md). The content width arrives inline.
 const dockStyles = StyleSheet.create({
   viewport: { flex: 1, overflow: "hidden" },
   surface: { flex: 1 },
   content: { flex: 1, justifyContent: "flex-end" },
   composer: { width: "100%", flexShrink: 1 },
   centeredViewport: { flex: 1, alignItems: "center", justifyContent: "center" },
-  centered: { flexShrink: 1, width: "100%", maxWidth: MAX_CONTENT_WIDTH },
+  centered: { flexShrink: 1, width: "100%" },
   // Reserve the composer's own capped height before the setup scroll view shrinks.
   centeredComposer: { width: "100%", flexShrink: 0 },
   setup: { flexGrow: 0, flexShrink: 1, minHeight: 0 },

packages/app/src/composer/dock/index.tsx

@@ -1,8 +1,9 @@
 export { ComposerDockBackground } from "./internal/background";
 import { ScrollView } from "@/components/ui/scroll-view";
 import type { ReactNode } from "react";
-import { View, StyleSheet } from "react-native";
-import { HEADER_INNER_HEIGHT, MAX_CONTENT_WIDTH } from "@/constants/layout";
+import { View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { HEADER_INNER_HEIGHT } from "@/constants/layout";
 
 interface ComposerDockProps {
   children: [ReactNode, ReactNode, ReactNode?];
@@ -35,7 +36,7 @@ export function ComposerDock({
   );
 }
 
-const styles = StyleSheet.create({
+const styles = StyleSheet.create((theme) => ({
   surface: { flex: 1, overflow: "hidden" },
   content: { flex: 1, justifyContent: "flex-end" },
   composer: { width: "100%", flexShrink: 1 },
@@ -45,7 +46,7 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     paddingBottom: HEADER_INNER_HEIGHT + 24,
   },
-  form: { flexShrink: 1, width: "100%", maxWidth: MAX_CONTENT_WIDTH },
+  form: { flexShrink: 1, width: "100%", maxWidth: theme.contentMaxWidth },
   centeredComposer: { flexShrink: 0 },
   setup: { flexGrow: 0, flexShrink: 1, minHeight: 0 },
-});
+}));

packages/app/src/composer/draft/workspace-tab.tsx

@@ -40,11 +40,7 @@ import {
   useWorkspaceAttachmentsStore,
 } from "@/attachments/workspace-attachments-store";
 import type { UserMessageImageAttachment } from "@/types/stream";
-import {
-  COMPACT_FORM_FACTOR_WIDTH,
-  MAX_CONTENT_WIDTH,
-  useIsCompactFormFactor,
-} from "@/constants/layout";
+import { COMPACT_FORM_FACTOR_WIDTH, useIsCompactFormFactor } from "@/constants/layout";
 import { isWeb } from "@/constants/platform";
 import {
   buildWorkspaceTabPersistenceKey,
@@ -737,7 +733,7 @@ const styles = StyleSheet.create((theme) => ({
   },
   importPillContent: {
     width: "100%",
-    maxWidth: MAX_CONTENT_WIDTH,
+    maxWidth: theme.contentMaxWidth,
     flexDirection: "row",
   },
   errorContainer: {

packages/app/src/composer/index.tsx

@@ -41,7 +41,7 @@ import {
   Paperclip,
 } from "lucide-react-native";
 import * as Clipboard from "expo-clipboard";
-import { FOOTER_HEIGHT, MAX_CONTENT_WIDTH } from "@/constants/layout";
+import { FOOTER_HEIGHT } from "@/constants/layout";
 import {
   AgentControls,
   DraftAgentControls,
@@ -2542,7 +2542,7 @@ const styles = StyleSheet.create((theme: Theme) => ({
   inputAreaContent: {
     flexShrink: 1,
     width: "100%",
-    maxWidth: MAX_CONTENT_WIDTH,
+    maxWidth: theme.contentMaxWidth,
     gap: theme.spacing[3],
   },
   messageInputContainer: {

packages/app/src/composer/tracks.tsx

@@ -11,7 +11,6 @@ import {
 } from "@/components/ui/menu";
 import { StatusRing } from "@/components/status-ring";
 import { STATUS_RING_HALO_INSET } from "@/components/status-ring/geometry";
-import { MAX_CONTENT_WIDTH } from "@/constants/layout";
 import { isWeb } from "@/constants/platform";
 import { getStatusDotColor } from "@/utils/status-dot-color";
 import { STATUS_INDICATOR_FILLED_DOT_SIZE } from "@/utils/status-indicator-geometry";
@@ -328,7 +327,7 @@ const styles = StyleSheet.create((theme) => {
     },
     track: {
       width: "100%",
-      maxWidth: MAX_CONTENT_WIDTH,
+      maxWidth: theme.contentMaxWidth,
       flexDirection: "row",
       alignItems: "center",
       gap: theme.spacing[1],

packages/app/src/constants/layout.ts

@@ -11,8 +11,6 @@ export const HEADER_INNER_HEIGHT_MOBILE = 56;
 export const WORKSPACE_SECONDARY_HEADER_HEIGHT = 36;
 export const HEADER_TOP_PADDING_MOBILE = 8;
 
-// Max width for chat content (stream view, input area, new agent form)
-export const MAX_CONTENT_WIDTH = 820;
 export const COMPACT_FORM_FACTOR_WIDTH = 500;
 
 // Settings uses the canonical desktop list + detail layout. Its sidebar and

packages/app/src/file-pane/markdown-preview/index.tsx

@@ -2,7 +2,6 @@ import { useMemo } from "react";
 import { Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import { MarkdownRenderer } from "@/components/markdown/renderer";
-import { MAX_CONTENT_WIDTH } from "@/constants/layout";
 import { parseMarkdownPreviewDocument } from "./document";
 
 export function FileMarkdownPreview({ source }: { source: string }) {
@@ -10,7 +9,7 @@ export function FileMarkdownPreview({ source }: { source: string }) {
 
   return (
     <View style={styles.outerGutter}>
-      <View style={styles.readingFrame}>
+      <View style={styles.readingFrame} testID="markdown-preview-frame">
         {document.frontMatter.length > 0 ? (
           <View style={styles.frontMatterTable} testID="markdown-front-matter">
             {document.frontMatter.map((row, index) => (
@@ -49,7 +48,7 @@ const styles = StyleSheet.create((theme) => ({
   },
   readingFrame: {
     width: "100%",
-    maxWidth: MAX_CONTENT_WIDTH,
+    maxWidth: theme.contentMaxWidth,
     alignSelf: "center",
     paddingHorizontal: theme.spacing[2],
   },

packages/app/src/hooks/use-settings/index.ts

@@ -17,22 +17,27 @@ import {
   DEFAULT_CLIENT_SETTINGS,
   DEFAULT_CODE_FONT_SIZE,
   DEFAULT_CONTENT_FONT_SIZE,
+  DEFAULT_CONTENT_MAX_WIDTH,
   DEFAULT_TERMINAL_SCROLLBACK_LINES,
   DEFAULT_THEME_PREFERENCE,
   DEFAULT_UI_BASE_FONT_SIZE,
   MAX_CODE_FONT_SIZE,
   MAX_CONTENT_FONT_SIZE,
+  MAX_CONTENT_MAX_WIDTH,
   MAX_TERMINAL_SCROLLBACK_LINES,
   MAX_UI_BASE_FONT_SIZE,
   MIN_CODE_FONT_SIZE,
   MIN_CONTENT_FONT_SIZE,
+  MIN_CONTENT_MAX_WIDTH,
   MIN_TERMINAL_SCROLLBACK_LINES,
   MIN_UI_BASE_FONT_SIZE,
   loadAppSettingsFromStorage as loadAppSettingsFromStoragePure,
   loadSettingsFromStorage as loadSettingsFromStoragePure,
   normalizeAppSettings,
   parseClampedFontSize,
+  parseContentMaxWidth,
   parseTerminalScrollbackLines,
+  resolveContentMaxWidth,
   sanitizeFontFamily,
   saveAppSettings as saveAppSettingsPure,
   type AppSettings,
@@ -56,19 +61,24 @@ export {
   DEFAULT_CLIENT_SETTINGS,
   DEFAULT_CODE_FONT_SIZE,
   DEFAULT_CONTENT_FONT_SIZE,
+  DEFAULT_CONTENT_MAX_WIDTH,
   DEFAULT_TERMINAL_SCROLLBACK_LINES,
   DEFAULT_THEME_PREFERENCE,
   DEFAULT_UI_BASE_FONT_SIZE,
   MAX_CODE_FONT_SIZE,
   MAX_CONTENT_FONT_SIZE,
+  MAX_CONTENT_MAX_WIDTH,
   MAX_TERMINAL_SCROLLBACK_LINES,
   MAX_UI_BASE_FONT_SIZE,
   MIN_CODE_FONT_SIZE,
   MIN_CONTENT_FONT_SIZE,
+  MIN_CONTENT_MAX_WIDTH,
   MIN_TERMINAL_SCROLLBACK_LINES,
   MIN_UI_BASE_FONT_SIZE,
   parseClampedFontSize,
+  parseContentMaxWidth,
   parseTerminalScrollbackLines,
+  resolveContentMaxWidth,
   sanitizeFontFamily,
 };
 export type {

packages/app/src/hooks/use-settings/storage.test.ts

@@ -14,6 +14,7 @@ import {
   loadSettingsFromStorage,
   parseClampedFontSize,
   parseTerminalScrollbackLines,
+  resolveContentMaxWidth,
   saveAppSettings,
   type SettingsDeps,
 } from "./storage";
@@ -22,7 +23,7 @@ import {
   DEFAULT_SIDEBAR_ROW_ITEMS,
   SIDEBAR_ROW_ITEMS,
 } from "@/components/sidebar/display-preferences/row-items";
-import { THEME_OPTIONS } from "@/styles/theme";
+import { DEFAULT_CONTENT_MAX_WIDTH, THEME_OPTIONS } from "@/styles/theme";
 
 const LEGACY_SETTINGS_KEY = "@paseo:settings";
 
@@ -955,3 +956,49 @@ describe("parseClampedFontSize", () => {
     expect(parseClampedFontSize("abc", { min: 11, max: 24 })).toBeNull();
   });
 });
+
+describe("content max width", () => {
+  it("follows the current default until the user picks a width", async () => {
+    const deps = makeDeps();
+    const queryClient = new QueryClient();
+
+    await saveAppSettings({ queryClient, updates: { codeFontSize: 14 }, deps });
+
+    const stored = JSON.parse(deps.storage.entries.get(APP_SETTINGS_KEY) ?? "null");
+    expect(stored.contentMaxWidth).toBeNull();
+    expect(resolveContentMaxWidth(await loadAppSettingsFromStorage(deps))).toBe(
+      DEFAULT_CONTENT_MAX_WIDTH,
+    );
+  });
+
+  it("keeps a picked width and returns to the default when reset", async () => {
+    const deps = makeDeps();
+    const queryClient = new QueryClient();
+
+    await saveAppSettings({ queryClient, updates: { contentMaxWidth: 1600 }, deps });
+    expect(resolveContentMaxWidth(await loadAppSettingsFromStorage(deps))).toBe(1600);
+
+    await saveAppSettings({ queryClient, updates: { contentMaxWidth: null }, deps });
+    expect(JSON.parse(deps.storage.entries.get(APP_SETTINGS_KEY) ?? "null").contentMaxWidth).toBe(
+      null,
+    );
+    expect(resolveContentMaxWidth(await loadAppSettingsFromStorage(deps))).toBe(
+      DEFAULT_CONTENT_MAX_WIDTH,
+    );
+  });
+
+  it("clamps stored widths and drops malformed ones to the default", async () => {
+    const load = (contentMaxWidth: unknown) =>
+      loadAppSettingsFromStorage(
+        makeDeps({
+          storage: createInMemoryKeyValueStorage({
+            [APP_SETTINGS_KEY]: JSON.stringify({ contentMaxWidth }),
+          }),
+        }),
+      );
+
+    expect((await load(100_000)).contentMaxWidth).toBe(4000);
+    expect((await load(10)).contentMaxWidth).toBe(600);
+    expect((await load("wide")).contentMaxWidth).toBeNull();
+  });
+});

packages/app/src/hooks/use-settings/storage.ts

@@ -15,6 +15,7 @@ import {
 } from "@/components/sidebar/display-preferences/row-items";
 import { isNative } from "@/constants/platform";
 import {
+  DEFAULT_CONTENT_MAX_WIDTH,
   FONT_SIZE,
   PLUGIN_THEME_PREFERENCE,
   THEME_OPTIONS,
@@ -63,6 +64,9 @@ export const DEFAULT_CODE_FONT_SIZE = 12; // == FONT_SIZE.code
 export const MIN_CODE_FONT_SIZE = 9;
 export const MAX_CODE_FONT_SIZE = 22; // line-height 1.5×22=33 stays safe
 export const MAX_FONT_FAMILY_LENGTH = 200;
+export { DEFAULT_CONTENT_MAX_WIDTH };
+export const MIN_CONTENT_MAX_WIDTH = 600;
+export const MAX_CONTENT_MAX_WIDTH = 4000;
 
 export interface AppSettings {
   theme: ThemePreference;
@@ -78,6 +82,8 @@ export interface AppSettings {
   uiBaseFontSize: number; // clamped px, platform default 14 or 15
   contentFontSize: number; // clamped px, platform default 15 or 16
   codeFontSize: number; // clamped px, default 12
+  /** Max width of chat and markdown content in px; null follows the current default. */
+  contentMaxWidth: number | null;
   syntaxTheme: SyntaxThemeId; // default "one"
   workspaceTitleSource: WorkspaceTitleSource;
   sidebarWorkspaceTrailing: SidebarWorkspaceTrailing;
@@ -132,6 +138,7 @@ export const DEFAULT_CLIENT_SETTINGS: AppSettings = {
   uiBaseFontSize: DEFAULT_UI_BASE_FONT_SIZE,
   contentFontSize: DEFAULT_CONTENT_FONT_SIZE,
   codeFontSize: DEFAULT_CODE_FONT_SIZE,
+  contentMaxWidth: null,
   syntaxTheme: "one",
   workspaceTitleSource: "title",
   sidebarWorkspaceTrailing: "diff",
@@ -218,6 +225,10 @@ const StoredAppSettingsSchema = z
     codeFontSize: clampedNumber(MIN_CODE_FONT_SIZE, MAX_CODE_FONT_SIZE).catch(
       DEFAULT_CODE_FONT_SIZE,
     ),
+    contentMaxWidth: z
+      .null()
+      .or(clampedNumber(MIN_CONTENT_MAX_WIDTH, MAX_CONTENT_MAX_WIDTH))
+      .catch(null),
     syntaxTheme: z.string().refine(isSyntaxThemeId).catch("one"),
     workspaceTitleSource: z.enum(["title", "branch"]).catch("title"),
     sidebarWorkspaceTrailing: z.enum(["diff", "timestamp", "none"]).catch("diff"),
@@ -457,6 +468,14 @@ export function parseTerminalScrollbackLines(value: unknown): number | null {
   );
 }
 
+export function parseContentMaxWidth(value: unknown): number | null {
+  return parseClampedFontSize(value, { min: MIN_CONTENT_MAX_WIDTH, max: MAX_CONTENT_MAX_WIDTH });
+}
+
+export function resolveContentMaxWidth(settings: Pick<AppSettings, "contentMaxWidth">): number {
+  return settings.contentMaxWidth ?? DEFAULT_CONTENT_MAX_WIDTH;
+}
+
 export function parseClampedFontSize(
   value: unknown,
   bounds: { min: number; max: number },

packages/app/src/hosts/host-confirmation-sheet.tsx

@@ -0,0 +1,109 @@
+import { useCallback, useMemo } from "react";
+import { Text, View } from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { useTranslation } from "react-i18next";
+import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
+import { Button } from "@/components/ui/button";
+import { settingsStyles } from "@/styles/settings";
+import { useHostConfirmation } from "@/runtime/host-runtime";
+
+/** Shows the host confirmation the host runtime is waiting on. Mount once at the app root. */
+export function HostConfirmationSheet() {
+  const { t } = useTranslation();
+  const { pending, answer } = useHostConfirmation();
+
+  const cancel = useCallback(() => answer(false), [answer]);
+  const connect = useCallback(() => answer(true), [answer]);
+  const header = useMemo<SheetHeader>(() => ({ title: t("pairing.hostConfirmation.title") }), [t]);
+
+  if (!pending) return null;
+
+  return (
+    <AdaptiveModalSheet header={header} visible onClose={cancel} testID="host-confirmation">
+      <Text style={styles.confirmText}>
+        {pending.kind === "changedConnection"
+          ? t("pairing.hostConfirmation.descriptionChanged")
+          : t("pairing.hostConfirmation.description")}
+      </Text>
+      <View style={settingsStyles.card}>
+        <DetailRow
+          label={t("pairing.hostConfirmation.hostLabel")}
+          value={pending.serverId}
+          testID="host-confirmation-server-id"
+        />
+        <DetailRow
+          label={t("pairing.hostConfirmation.fingerprintLabel")}
+          value={pending.keyFingerprint}
+          testID="host-confirmation-fingerprint"
+          showBorder
+        />
+        <DetailRow
+          label={t("pairing.hostConfirmation.relayLabel")}
+          value={pending.relayEndpoint}
+          testID="host-confirmation-relay"
+          showBorder
+        />
+      </View>
+      <View style={styles.confirmActions}>
+        <Button
+          variant="secondary"
+          size="sm"
+          style={FLEX_1_STYLE}
+          onPress={cancel}
+          testID="host-confirmation-cancel"
+        >
+          {t("common.actions.cancel")}
+        </Button>
+        <Button
+          variant="default"
+          size="sm"
+          style={FLEX_1_STYLE}
+          onPress={connect}
+          testID="host-confirmation-connect"
+        >
+          {t("pairing.hostConfirmation.connect")}
+        </Button>
+      </View>
+    </AdaptiveModalSheet>
+  );
+}
+
+function DetailRow({
+  label,
+  value,
+  showBorder = false,
+  testID,
+}: {
+  label: string;
+  value: string;
+  showBorder?: boolean;
+  testID?: string;
+}) {
+  return (
+    <View style={[settingsStyles.row, showBorder && settingsStyles.rowBorder]}>
+      <View style={settingsStyles.rowContent}>
+        <Text style={settingsStyles.rowTitle}>{label}</Text>
+        <Text style={settingsStyles.rowHint} selectable testID={testID}>
+          {value}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+// Same shape as the remove-host and remove-connection confirm sheets in
+// screens/settings/host-page.tsx.
+const styles = StyleSheet.create((theme) => ({
+  confirmText: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.base,
+  },
+  confirmActions: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[2],
+    marginTop: theme.spacing[4],
+  },
+}));
+
+const FLEX_1_STYLE = { flex: 1 };

packages/app/src/hosts/pair-scan-model.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ConnectionLinkImport, LinkPairing } from "@/runtime/host-runtime";
+import { openPairScan, type PairScanModel } from "./pair-scan-model";
+
+const LINK = "https://app.paseo.sh/#offer=abc";
+const PAIRING: LinkPairing = { submit: async () => ({ status: "cancelled" }) };
+
+/** The host runtime's side of a scan: each import resolves with the next queued outcome. */
+function createScanner(outcomes: Array<ConnectionLinkImport | Error>) {
+  const imports: string[] = [];
+  const connected: string[] = [];
+  const scan = openPairScan({
+    importConnectionLink: async (link) => {
+      imports.push(link);
+      const outcome = outcomes.shift();
+      if (!outcome) throw new Error("No outcome queued for this import");
+      if (outcome instanceof Error) throw outcome;
+      return outcome;
+    },
+    onConnected: (serverId) => connected.push(serverId),
+  });
+  return { scan, imports, connected };
+}
+
+async function settled(scan: PairScanModel): Promise<void> {
+  await vi.waitFor(() => expect(scan.getState().status).not.toBe("pairing"));
+}
+
+describe("openPairScan", () => {
+  it("stops scanning after Cancel until the user scans again", async () => {
+    const { scan, imports } = createScanner([{ status: "cancelled" }, { status: "cancelled" }]);
+
+    scan.scan(LINK);
+    await settled(scan);
+
+    // The code is still in front of the camera.
+    scan.scan(LINK);
+    scan.scan(LINK);
+    await Promise.resolve();
+    expect(imports).toEqual([LINK]);
+    expect(scan.getState()).toEqual({ status: "stopped", error: null });
+
+    scan.scanAgain();
+    scan.scan(LINK);
+    await settled(scan);
+    expect(imports).toEqual([LINK, LINK]);
+  });
+
+  it("starts one attempt per code while pairing, and ignores codes that are not pairing links", async () => {
+    const { scan, imports, connected } = createScanner([
+      { status: "connected", serverId: "srv_scan" },
+    ]);
+
+    scan.scan("https://example.com/not-a-pairing-link");
+    expect(scan.getState()).toEqual({ status: "scanning" });
+
+    scan.scan(LINK);
+    scan.scan(LINK);
+    await settled(scan);
+
+    expect(imports).toEqual([LINK]);
+    expect(connected).toEqual(["srv_scan"]);
+    scan.scan(LINK);
+    expect(imports).toEqual([LINK]);
+  });
+
+  it("ends the attempt when the password prompt closes", async () => {
+    const { scan, imports } = createScanner([
+      { status: "password_required", link: LINK, pairing: PAIRING },
+    ]);
+
+    scan.scan(LINK);
+    await settled(scan);
+    expect(scan.getState()).toEqual({
+      status: "passwordRequired",
+      passwordRequired: { link: LINK, pairing: PAIRING },
+    });
+    scan.scan(LINK);
+
+    scan.closePassword();
+    scan.scan(LINK);
+
+    expect(scan.getState()).toEqual({ status: "stopped", error: null });
+    expect(imports).toEqual([LINK]);
+  });
+
+  it("stops with the error when an attempt fails", async () => {
+    const { scan, imports } = createScanner([new Error("Server disconnected")]);
+
+    scan.scan(LINK);
+    await settled(scan);
+    scan.scan(LINK);
+
+    expect(scan.getState()).toEqual({ status: "stopped", error: "Server disconnected" });
+    expect(imports).toEqual([LINK]);
+  });
+
+  it("does not navigate for an attempt that finishes after the screen closed", async () => {
+    let finish: (outcome: ConnectionLinkImport) => void = () => {};
+    const connected: string[] = [];
+    const scan = openPairScan({
+      importConnectionLink: () =>
+        new Promise((resolve) => {
+          finish = resolve;
+        }),
+      onConnected: (serverId) => connected.push(serverId),
+    });
+
+    scan.scan(LINK);
+    scan.close();
+    finish({ status: "connected", serverId: "srv_scan" });
+    await Promise.resolve();
+
+    expect(connected).toEqual([]);
+  });
+});

packages/app/src/hosts/pair-scan-model.ts

@@ -0,0 +1,103 @@
+import type { ConnectionLinkImport, PasswordRequiredPairing } from "@/runtime/host-runtime";
+
+/**
+ * One visit to the QR scan screen. The camera reports every frame that shows
+ * a code, so an attempt that ends (Cancel on the host confirmation, a closed
+ * password prompt, or an error) stops scanning until the user taps scan again.
+ * Without that, the code still in front of the camera starts a new attempt on
+ * the next frame.
+ */
+export type PairScanState =
+  | { status: "scanning" }
+  | { status: "pairing" }
+  | { status: "passwordRequired"; passwordRequired: PasswordRequiredPairing }
+  | { status: "stopped"; error: string | null }
+  | { status: "connected" };
+
+export interface PairScanModel {
+  getState: () => PairScanState;
+  subscribe: (listener: () => void) => () => void;
+  /** Data from a QR code the camera saw. Only a scanning session starts an attempt. */
+  scan: (data: string) => void;
+  /** The user asked to scan again after an attempt ended. */
+  scanAgain: () => void;
+  /** The user closed the password prompt, which ends the attempt. */
+  closePassword: () => void;
+  close: () => void;
+}
+
+export interface PairScanDependencies {
+  importConnectionLink: (link: string) => Promise<ConnectionLinkImport>;
+  onConnected: (serverId: string) => void;
+}
+
+export function openPairScan(deps: PairScanDependencies): PairScanModel {
+  let state: PairScanState = { status: "scanning" };
+  let closed = false;
+  const listeners = new Set<() => void>();
+
+  function publish(next: PairScanState): void {
+    if (closed) return;
+    state = next;
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+
+  async function pair(link: string): Promise<void> {
+    publish({ status: "pairing" });
+    try {
+      const outcome = await deps.importConnectionLink(link);
+      if (closed) return;
+      if (outcome.status === "connected") {
+        publish({ status: "connected" });
+        deps.onConnected(outcome.serverId);
+        return;
+      }
+      if (outcome.status === "password_required") {
+        const { link: passwordLink, pairing } = outcome;
+        publish({ status: "passwordRequired", passwordRequired: { link: passwordLink, pairing } });
+        return;
+      }
+      publish({ status: "stopped", error: null });
+    } catch (error) {
+      publish({ status: "stopped", error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    scan(data) {
+      if (state.status !== "scanning") return;
+      const link = pairingLinkFromScan(data);
+      if (!link) return;
+      void pair(link);
+    },
+    scanAgain() {
+      if (state.status !== "stopped") return;
+      publish({ status: "scanning" });
+    },
+    closePassword() {
+      if (state.status !== "passwordRequired") return;
+      publish({ status: "stopped", error: null });
+    },
+    close() {
+      closed = true;
+      listeners.clear();
+    },
+  };
+}
+
+function pairingLinkFromScan(data: string): string | null {
+  const raw = data.trim();
+  if (raw.includes("#offer=") || raw.includes("#connect=") || raw.startsWith("relay://")) {
+    return raw;
+  }
+  return null;
+}

packages/app/src/i18n/resources/ar.ts

@@ -439,7 +439,9 @@ export const ar: TranslationResources = {
       recovery: {
         archivedTitle: "مساحة العمل مؤرشفة",
         restoreDescription:
-          "تمت أرشفة {{workspaceName}} وإزالة شجرة العمل الخاصة بها. استعد الفرع {{branch}} لفتحها مجددًا.",
+          "استعد {{workspaceName}} للعودة إلى وكلائها. ستستخدم شجرة العمل الفرع {{branch}}.",
+        restoreWithoutBranchDescription:
+          "استعد {{workspaceName}} للعودة إلى وكلائها. سيبدأ فرع جديد من الفرع الأساسي المحفوظ أو الفرع الافتراضي للمستودع.",
         unarchiveDescription: "{{workspaceName}} مؤرشفة. ألغِ أرشفتها لفتحها مجددًا.",
         restoreAction: "استعادة",
         unarchiveAction: "إلغاء الأرشفة",
@@ -1619,6 +1621,17 @@ export const ar: TranslationResources = {
       title: "كلمة المرور لـ {{host}}",
       label: "كلمة مرور المضيف",
     },
+    hostConfirmation: {
+      title: "الاتصال بهذا المضيف؟",
+      description:
+        "سيتمكن هذا المضيف من تشغيل تعليمات برمجية في هذا التطبيق والوصول إلى مضيفيك الآخرين المتصلين. اتصل فقط إذا كنت تعرفه.",
+      descriptionChanged:
+        "يغيّر هذا الرابط طريقة اتصالك بهذا المضيف. سيتمكن المضيف من تشغيل تعليمات برمجية في هذا التطبيق والوصول إلى مضيفيك الآخرين المتصلين. اتصل فقط إذا كنت تعرفه.",
+      hostLabel: "المضيف",
+      fingerprintLabel: "بصمة المفتاح",
+      relayLabel: "المُرحّل",
+      connect: "اتصال",
+    },
     connectionMethods: {
       title: "إضافة اتصال",
       direct: {
@@ -2191,6 +2204,14 @@ export const ar: TranslationResources = {
         codeSizeHint: "يُستخدم للكود والفروقات ومخرجات الطرفية",
         codeSizeAccessibility: "حجم خط الكود",
       },
+      layout: {
+        title: "التخطيط",
+        contentWidth: "عرض المحتوى",
+        contentWidthHint: "أقصى عرض للمحادثة وملفات Markdown على الشاشات العريضة",
+        contentWidthAccessibility: "عرض المحتوى بالبكسل",
+        reset: "إعادة تعيين",
+        resetAccessibility: "إعادة عرض المحتوى إلى الافتراضي",
+      },
       syntax: {
         title: "بناء الجملة",
         highlightTheme: "تسليط الضوء على الموضوع",

packages/app/src/i18n/resources/en.ts

@@ -436,7 +436,9 @@ export const en = {
       recovery: {
         archivedTitle: "Workspace archived",
         restoreDescription:
-          "{{workspaceName}} was archived and its worktree was removed. Restore branch {{branch}} to open it again.",
+          "Restore {{workspaceName}} to return to its agents. Its worktree will use branch {{branch}}.",
+        restoreWithoutBranchDescription:
+          "Restore {{workspaceName}} to return to its agents. A new branch will start from the saved base or the repository default.",
         unarchiveDescription: "{{workspaceName}} is archived. Unarchive it to open it again.",
         restoreAction: "Restore",
         unarchiveAction: "Unarchive",
@@ -1644,6 +1646,17 @@ export const en = {
       title: "Password for {{host}}",
       label: "Host password",
     },
+    hostConfirmation: {
+      title: "Connect to this host?",
+      description:
+        "This host will be able to run code in this app and reach your other connected hosts. Only connect if you recognize it.",
+      descriptionChanged:
+        "This link changes how you connect to this host. The host will be able to run code in this app and reach your other connected hosts. Only connect if you recognize it.",
+      hostLabel: "Host",
+      fingerprintLabel: "Key fingerprint",
+      relayLabel: "Relay",
+      connect: "Connect",
+    },
     connectionMethods: {
       title: "Add connection",
       direct: {
@@ -2315,6 +2328,14 @@ export const en = {
         codeSizeHint: "Used for code, diffs, and terminal output",
         codeSizeAccessibility: "Code font size",
       },
+      layout: {
+        title: "Layout",
+        contentWidth: "Content width",
+        contentWidthHint: "Max width of chat and Markdown files on wide screens",
+        contentWidthAccessibility: "Content width in pixels",
+        reset: "Reset",
+        resetAccessibility: "Reset content width to default",
+      },
       syntax: {
         title: "Syntax",
         highlightTheme: "Highlight theme",

packages/app/src/i18n/resources/es.ts

@@ -444,7 +444,9 @@ export const es: TranslationResources = {
       recovery: {
         archivedTitle: "Espacio de trabajo archivado",
         restoreDescription:
-          "{{workspaceName}} se archivó y se eliminó su worktree. Restaura la rama {{branch}} para volver a abrirlo.",
+          "Restaura {{workspaceName}} para volver a sus agentes. Su worktree usará la rama {{branch}}.",
+        restoreWithoutBranchDescription:
+          "Restaura {{workspaceName}} para volver a sus agentes. Se creará una rama nueva desde la base guardada o la rama predeterminada del repositorio.",
         unarchiveDescription:
           "{{workspaceName}} está archivado. Desarchívalo para volver a abrirlo.",
         restoreAction: "Restaurar",
@@ -1665,6 +1667,17 @@ export const es: TranslationResources = {
       title: "Contraseña de {{host}}",
       label: "Contraseña del host",
     },
+    hostConfirmation: {
+      title: "¿Conectar con este host?",
+      description:
+        "Este host podrá ejecutar código en esta app y acceder a tus otros hosts conectados. Conéctate solo si lo reconoces.",
+      descriptionChanged:
+        "Este enlace cambia cómo te conectas a este host. El host podrá ejecutar código en esta app y acceder a tus otros hosts conectados. Conéctate solo si lo reconoces.",
+      hostLabel: "Host",
+      fingerprintLabel: "Huella de la clave",
+      relayLabel: "Relay",
+      connect: "Conectar",
+    },
     connectionMethods: {
       title: "Agregar conexión",
       direct: {
@@ -2245,6 +2258,14 @@ export const es: TranslationResources = {
         codeSizeHint: "Se usa en código, diferencias y la salida del terminal",
         codeSizeAccessibility: "Tamaño de fuente del código",
       },
+      layout: {
+        title: "Diseño",
+        contentWidth: "Ancho del contenido",
+        contentWidthHint: "Ancho máximo del chat y de los archivos Markdown en pantallas anchas",
+        contentWidthAccessibility: "Ancho del contenido en píxeles",
+        reset: "Restablecer",
+        resetAccessibility: "Restablecer el ancho del contenido",
+      },
       syntax: {
         title: "Sintaxis",
         highlightTheme: "Tema destacado",

packages/app/src/i18n/resources/fr.ts

@@ -445,7 +445,9 @@ export const fr: TranslationResources = {
       recovery: {
         archivedTitle: "Espace de travail archivé",
         restoreDescription:
-          "{{workspaceName}} a été archivé et son worktree supprimé. Restaurez la branche {{branch}} pour le rouvrir.",
+          "Restaurez {{workspaceName}} pour retrouver ses agents. Son worktree utilisera la branche {{branch}}.",
+        restoreWithoutBranchDescription:
+          "Restaurez {{workspaceName}} pour retrouver ses agents. Une nouvelle branche partira de la base enregistrée ou de la branche par défaut du dépôt.",
         unarchiveDescription: "{{workspaceName}} est archivé. Désarchivez-le pour le rouvrir.",
         restoreAction: "Restaurer",
         unarchiveAction: "Désarchiver",
@@ -1669,6 +1671,17 @@ export const fr: TranslationResources = {
       title: "Mot de passe pour {{host}}",
       label: "Mot de passe de l’hôte",
     },
+    hostConfirmation: {
+      title: "Se connecter à cet hôte ?",
+      description:
+        "Cet hôte pourra exécuter du code dans cette application et accéder à vos autres hôtes connectés. Connectez-vous uniquement si vous le reconnaissez.",
+      descriptionChanged:
+        "Ce lien modifie la façon dont vous vous connectez à cet hôte. L'hôte pourra exécuter du code dans cette application et accéder à vos autres hôtes connectés. Connectez-vous uniquement si vous le reconnaissez.",
+      hostLabel: "Hôte",
+      fingerprintLabel: "Empreinte de la clé",
+      relayLabel: "Relais",
+      connect: "Se connecter",
+    },
     connectionMethods: {
       title: "Ajouter une connexion",
       direct: {
@@ -2248,6 +2261,14 @@ export const fr: TranslationResources = {
         codeSizeHint: "Utilisée pour le code, les diffs et la sortie du terminal",
         codeSizeAccessibility: "Taille de la police du code",
       },
+      layout: {
+        title: "Mise en page",
+        contentWidth: "Largeur du contenu",
+        contentWidthHint: "Largeur maximale du chat et des fichiers Markdown sur les grands écrans",
+        contentWidthAccessibility: "Largeur du contenu en pixels",
+        reset: "Réinitialiser",
+        resetAccessibility: "Réinitialiser la largeur du contenu",
+      },
       syntax: {
         title: "Syntaxe",
         highlightTheme: "Thème de surbrillance",

packages/app/src/i18n/resources/ja.ts

@@ -444,7 +444,9 @@ export const ja: TranslationResources = {
       recovery: {
         archivedTitle: "ワークスペースはアーカイブ済みです",
         restoreDescription:
-          "{{workspaceName}} はアーカイブされ、worktree が削除されました。ブランチ {{branch}} を復元して再度開きます。",
+          "{{workspaceName}} を復元してエージェントに戻ります。worktree ではブランチ {{branch}} を使用します。",
+        restoreWithoutBranchDescription:
+          "{{workspaceName}} を復元してエージェントに戻ります。保存されたベース、またはリポジトリのデフォルトブランチから新しいブランチを作成します。",
         unarchiveDescription:
           "{{workspaceName}} はアーカイブされています。再度開くにはアーカイブを解除してください。",
         restoreAction: "復元",
@@ -1636,6 +1638,17 @@ export const ja: TranslationResources = {
       title: "{{host}} のパスワード",
       label: "ホストのパスワード",
     },
+    hostConfirmation: {
+      title: "このホストに接続しますか？",
+      description:
+        "このホストはこのアプリ内でコードを実行し、接続中の他のホストにアクセスできるようになります。心当たりがある場合のみ接続してください。",
+      descriptionChanged:
+        "このリンクはこのホストへの接続方法を変更します。ホストはこのアプリ内でコードを実行し、接続中の他のホストにアクセスできるようになります。心当たりがある場合のみ接続してください。",
+      hostLabel: "ホスト",
+      fingerprintLabel: "鍵のフィンガープリント",
+      relayLabel: "リレー",
+      connect: "接続",
+    },
     connectionMethods: {
       title: "接続を追加",
       direct: {
@@ -2211,6 +2224,14 @@ export const ja: TranslationResources = {
         codeSizeHint: "コード、差分、ターミナル出力に使用されます",
         codeSizeAccessibility: "コードフォントサイズ",
       },
+      layout: {
+        title: "レイアウト",
+        contentWidth: "コンテンツ幅",
+        contentWidthHint: "ワイド画面でのチャットと Markdown ファイルの最大幅",
+        contentWidthAccessibility: "コンテンツ幅 (ピクセル)",
+        reset: "リセット",
+        resetAccessibility: "コンテンツ幅をデフォルトに戻す",
+      },
       syntax: {
         title: "構文ハイライト",
         highlightTheme: "ハイライトテーマ",

packages/app/src/i18n/resources/ko.ts

@@ -440,7 +440,9 @@ export const ko: TranslationResources = {
       recovery: {
         archivedTitle: "워크스페이스가 보관되었습니다",
         restoreDescription:
-          "{{workspaceName}}가 보관되고 워크트리가 제거되었습니다. 다시 열려면 {{branch}} 브랜치를 복원하세요.",
+          "{{workspaceName}}를 복원하여 에이전트로 돌아갑니다. 워크트리는 {{branch}} 브랜치를 사용합니다.",
+        restoreWithoutBranchDescription:
+          "{{workspaceName}}를 복원하여 에이전트로 돌아갑니다. 저장된 기반 브랜치 또는 저장소 기본 브랜치에서 새 브랜치를 만듭니다.",
         unarchiveDescription: "{{workspaceName}}가 보관되었습니다. 다시 열려면 보관을 취소하세요.",
         restoreAction: "복원",
         unarchiveAction: "보관 취소",
@@ -1629,6 +1631,17 @@ export const ko: TranslationResources = {
       title: "{{host}}의 비밀번호",
       label: "호스트 비밀번호",
     },
+    hostConfirmation: {
+      title: "이 호스트에 연결할까요?",
+      description:
+        "이 호스트는 이 앱에서 코드를 실행하고 연결된 다른 호스트에 접근할 수 있게 됩니다. 알고 있는 호스트인 경우에만 연결하세요.",
+      descriptionChanged:
+        "이 링크는 이 호스트에 연결하는 방식을 변경합니다. 호스트는 이 앱에서 코드를 실행하고 연결된 다른 호스트에 접근할 수 있게 됩니다. 알고 있는 호스트인 경우에만 연결하세요.",
+      hostLabel: "호스트",
+      fingerprintLabel: "키 지문",
+      relayLabel: "릴레이",
+      connect: "연결",
+    },
     connectionMethods: {
       title: "연결 추가",
       direct: {
@@ -2202,6 +2215,14 @@ export const ko: TranslationResources = {
         codeSizeHint: "코드, diff 및 터미널 출력에 사용됩니다",
         codeSizeAccessibility: "코드 글꼴 크기",
       },
+      layout: {
+        title: "레이아웃",
+        contentWidth: "콘텐츠 너비",
+        contentWidthHint: "와이드 화면에서 채팅과 Markdown 파일의 최대 너비",
+        contentWidthAccessibility: "콘텐츠 너비(픽셀)",
+        reset: "재설정",
+        resetAccessibility: "콘텐츠 너비를 기본값으로 재설정",
+      },
       syntax: {
         title: "구문",
         highlightTheme: "강조 테마",

packages/app/src/i18n/resources/pt-BR.ts

@@ -443,7 +443,9 @@ export const ptBR: TranslationResources = {
       recovery: {
         archivedTitle: "Workspace arquivado",
         restoreDescription:
-          "{{workspaceName}} foi arquivado e sua worktree foi removida. Restaure a branch {{branch}} para abri-lo novamente.",
+          "Restaure {{workspaceName}} para voltar aos seus agentes. A worktree usará a branch {{branch}}.",
+        restoreWithoutBranchDescription:
+          "Restaure {{workspaceName}} para voltar aos seus agentes. Uma nova branch partirá da base salva ou da branch padrão do repositório.",
         unarchiveDescription:
           "{{workspaceName}} está arquivado. Desarquive-o para abri-lo novamente.",
         restoreAction: "Restaurar",
@@ -1650,6 +1652,17 @@ export const ptBR: TranslationResources = {
       title: "Senha de {{host}}",
       label: "Senha do host",
     },
+    hostConfirmation: {
+      title: "Conectar a este host?",
+      description:
+        "Este host poderá executar código neste app e acessar seus outros hosts conectados. Conecte apenas se você o reconhecer.",
+      descriptionChanged:
+        "Este link muda como você se conecta a este host. O host poderá executar código neste app e acessar seus outros hosts conectados. Conecte apenas se você o reconhecer.",
+      hostLabel: "Host",
+      fingerprintLabel: "Impressão da chave",
+      relayLabel: "Relay",
+      connect: "Conectar",
+    },
     connectionMethods: {
       title: "Adicionar conexão",
       direct: {
@@ -2226,6 +2239,14 @@ export const ptBR: TranslationResources = {
         codeSizeHint: "Usado em código, diffs e saída do terminal",
         codeSizeAccessibility: "Tamanho da fonte de código",
       },
+      layout: {
+        title: "Layout",
+        contentWidth: "Largura do conteúdo",
+        contentWidthHint: "Largura máxima do chat e dos arquivos Markdown em telas largas",
+        contentWidthAccessibility: "Largura do conteúdo em pixels",
+        reset: "Redefinir",
+        resetAccessibility: "Redefinir a largura do conteúdo",
+      },
       syntax: {
         title: "Sintaxe",
         highlightTheme: "Tema de destaque",

packages/app/src/i18n/resources/ru.ts

@@ -443,7 +443,9 @@ export const ru: TranslationResources = {
       recovery: {
         archivedTitle: "Рабочая область в архиве",
         restoreDescription:
-          "Рабочее пространство «{{workspaceName}}» было архивировано, а его worktree удалён. Восстановите ветку {{branch}}, чтобы снова открыть рабочее пространство.",
+          "Восстановите «{{workspaceName}}», чтобы вернуться к его агентам. Worktree будет использовать ветку {{branch}}.",
+        restoreWithoutBranchDescription:
+          "Восстановите «{{workspaceName}}», чтобы вернуться к его агентам. Новая ветка будет создана от сохранённой базовой или ветки репозитория по умолчанию.",
         unarchiveDescription:
           "Рабочее пространство «{{workspaceName}}» находится в архиве. Разархивируйте его, чтобы снова открыть.",
         restoreAction: "Восстановить",
@@ -1648,6 +1650,17 @@ export const ru: TranslationResources = {
       title: "Пароль для {{host}}",
       label: "Пароль хоста",
     },
+    hostConfirmation: {
+      title: "Подключиться к этому хосту?",
+      description:
+        "Этот хост сможет выполнять код в приложении и обращаться к другим вашим подключённым хостам. Подключайтесь, только если узнаёте его.",
+      descriptionChanged:
+        "Эта ссылка меняет способ подключения к этому хосту. Хост сможет выполнять код в приложении и обращаться к другим вашим подключённым хостам. Подключайтесь, только если узнаёте его.",
+      hostLabel: "Хост",
+      fingerprintLabel: "Отпечаток ключа",
+      relayLabel: "Реле",
+      connect: "Подключить",
+    },
     connectionMethods: {
       title: "Добавить подключение",
       direct: {
@@ -2231,6 +2244,14 @@ export const ru: TranslationResources = {
         codeSizeHint: "Используется для кода, диффов и вывода терминала",
         codeSizeAccessibility: "Размер шрифта кода",
       },
+      layout: {
+        title: "Макет",
+        contentWidth: "Ширина содержимого",
+        contentWidthHint: "Максимальная ширина чата и файлов Markdown на широких экранах",
+        contentWidthAccessibility: "Ширина содержимого в пикселях",
+        reset: "Сбросить",
+        resetAccessibility: "Сбросить ширину содержимого",
+      },
       syntax: {
         title: "Синтаксис",
         highlightTheme: "Тема подсветки",

packages/app/src/i18n/resources/zh-CN.ts

@@ -439,7 +439,9 @@ export const zhCN: TranslationResources = {
       recovery: {
         archivedTitle: "Workspace 已归档",
         restoreDescription:
-          "{{workspaceName}} 已归档，其 worktree 已移除。恢复分支 {{branch}} 以重新打开。",
+          "恢复 {{workspaceName}} 以返回其中的代理。worktree 将使用分支 {{branch}}。",
+        restoreWithoutBranchDescription:
+          "恢复 {{workspaceName}} 以返回其中的代理。新分支将从保存的基准分支或仓库默认分支创建。",
         unarchiveDescription: "{{workspaceName}} 已归档。取消归档以重新打开。",
         restoreAction: "恢复",
         unarchiveAction: "取消归档",
@@ -1602,6 +1604,16 @@ export const zhCN: TranslationResources = {
       title: "{{host}} 的密码",
       label: "主机密码",
     },
+    hostConfirmation: {
+      title: "连接到此主机？",
+      description: "此主机将能在此应用中运行代码，并访问你其他已连接的主机。仅在你认识它时才连接。",
+      descriptionChanged:
+        "此链接会改变你连接此主机的方式。该主机将能在此应用中运行代码，并访问你其他已连接的主机。仅在你认识它时才连接。",
+      hostLabel: "主机",
+      fingerprintLabel: "密钥指纹",
+      relayLabel: "中继",
+      connect: "连接",
+    },
     connectionMethods: {
       title: "添加连接",
       direct: {
@@ -2166,6 +2178,14 @@ export const zhCN: TranslationResources = {
         codeSizeHint: "用于代码、差异和终端输出",
         codeSizeAccessibility: "代码字号",
       },
+      layout: {
+        title: "布局",
+        contentWidth: "内容宽度",
+        contentWidthHint: "宽屏上聊天和 Markdown 文件的最大宽度",
+        contentWidthAccessibility: "内容宽度（像素）",
+        reset: "重置",
+        resetAccessibility: "将内容宽度重置为默认值",
+      },
       syntax: {
         title: "语法",
         highlightTheme: "高亮主题",

packages/app/src/panels/agent-panel.tsx

@@ -38,11 +38,7 @@ import { getProviderIcon } from "@/components/provider-icons";
 import { useToastHost, type ToastApi, type ToastState } from "@/components/toast-host";
 import type { WorkspaceComposerAttachment } from "@/attachments/types";
 import { useWorkspaceAttachmentScopeKey } from "@/attachments/workspace-attachments-store";
-import {
-  COMPACT_FORM_FACTOR_WIDTH,
-  MAX_CONTENT_WIDTH,
-  useIsCompactFormFactor,
-} from "@/constants/layout";
+import { COMPACT_FORM_FACTOR_WIDTH, useIsCompactFormFactor } from "@/constants/layout";
 import { isNative, isWeb } from "@/constants/platform";
 import { useAgentAttentionClear } from "@/hooks/use-agent-attention-clear";
 import { useAgentInputDraft, type AgentInputDraft } from "@/composer/draft/input-draft";
@@ -1750,7 +1746,7 @@ const styles = StyleSheet.create((theme) => ({
   },
   timelineSyncCalloutContent: {
     width: "100%",
-    maxWidth: MAX_CONTENT_WIDTH,
+    maxWidth: theme.contentMaxWidth,
   },
   timelineSyncCallout: {
     flexDirection: "row",

packages/app/src/runtime/host-confirmation.ts

@@ -0,0 +1,97 @@
+import type { ConnectionOffer } from "@getpaseo/protocol/connection-offer";
+import {
+  hostHasConnection,
+  relayConnectionFromOffer,
+  type HostProfile,
+} from "@/types/host-connection";
+
+/**
+ * The question shown before a pairing link adds a host that is not saved, or
+ * changes the key, relay, or TLS setting of a saved one.
+ */
+export interface HostConfirmationRequest {
+  /** Identifies this question, so an answer shown for it never answers a newer one. */
+  id: number;
+  serverId: string;
+  /** Grouped daemon public key the user can compare with the one their daemon shows. */
+  keyFingerprint: string;
+  relayEndpoint: string;
+  kind: "newHost" | "changedConnection";
+}
+
+interface PendingConfirmation {
+  request: HostConfirmationRequest;
+  resolve: (approved: boolean) => void;
+}
+
+/**
+ * Owns the one host confirmation the app is waiting on. The host runtime asks
+ * through `confirmLink`; the view reads `getPending` and replies with `answer`.
+ * A question waits until it is answered, whether or not a view is showing it.
+ */
+export class HostConfirmations {
+  private pending: PendingConfirmation | null = null;
+  private nextRequestId = 1;
+  private listeners = new Set<() => void>();
+
+  getPending(): HostConfirmationRequest | null {
+    return this.pending?.request ?? null;
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Answers the request with `requestId`; an answer for any other request is ignored. */
+  answer(requestId: number, approved: boolean): void {
+    const current = this.pending;
+    if (!current || current.request.id !== requestId) return;
+    this.pending = null;
+    this.emit();
+    current.resolve(approved);
+  }
+
+  /** Resolves true without asking when the link matches a saved host exactly. */
+  confirmLink(offer: ConnectionOffer, savedHosts: HostProfile[]): Promise<boolean> {
+    const connection = relayConnectionFromOffer(offer);
+    const savedHost = savedHosts.find((host) => host.serverId === offer.serverId);
+    if (savedHost && hostHasConnection(savedHost, connection)) return Promise.resolve(true);
+    return this.ask({
+      id: this.nextRequestId++,
+      serverId: offer.serverId,
+      keyFingerprint: formatDaemonKeyFingerprint(connection.daemonPublicKeyB64),
+      relayEndpoint: connection.relayEndpoint,
+      kind: savedHost ? "changedConnection" : "newHost",
+    });
+  }
+
+  private ask(request: HostConfirmationRequest): Promise<boolean> {
+    // One question at a time: a newer one cancels the unanswered one.
+    this.pending?.resolve(false);
+    return new Promise<boolean>((resolve) => {
+      this.pending = { request, resolve };
+      this.emit();
+    });
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+}
+
+/**
+ * Shows the key material itself (not a re-hash) in groups of four. Keys longer
+ * than 16 characters show only their first and last 8, so two keys that share
+ * both ends show the same value.
+ */
+function formatDaemonKeyFingerprint(daemonPublicKeyB64: string): string {
+  const normalized = daemonPublicKeyB64.replace(/[^A-Za-z0-9]/g, "");
+  const group = (value: string): string => value.replace(/(.{4})/g, "$1 ").trim();
+  if (normalized.length <= 16) return group(normalized);
+  return `${group(normalized.slice(0, 8))} … ${group(normalized.slice(-8))}`;
+}

packages/app/src/runtime/host-runtime.test.ts

@@ -31,6 +31,7 @@ import type { ReplicaRow, ReplicaRowStore } from "./replica-cache/row-store";
 
 import { subscriptionFixture } from "./subscription-fixture";
 import { readDesktopManagedLocalCredential } from "@/desktop/daemon/local-credential";
+import type { HostConfirmationRequest } from "./host-confirmation";
 
 it("requests the managed connection credential through desktop main without a web hint", async () => {
   const requests: string[] = [];
@@ -507,6 +508,63 @@ function makeConnectedProbeClient(latencyMs: number): FakeDaemonClient {
   return client;
 }
 
+/**
+ * Answers every host confirmation the store asks, the way the sheet does, and
+ * records each request.
+ */
+function answerHostConfirmations(
+  store: HostRuntimeStore,
+  answer: boolean | ((request: HostConfirmationRequest, index: number) => boolean),
+): HostConfirmationRequest[] {
+  const requests: HostConfirmationRequest[] = [];
+  store.subscribeHostConfirmation(() => {
+    const pending = store.getPendingHostConfirmation();
+    if (!pending) return;
+    requests.push(pending);
+    store.answerHostConfirmation(
+      pending.id,
+      typeof answer === "function" ? answer(pending, requests.length - 1) : answer,
+    );
+  });
+  return requests;
+}
+
+function requirePendingConfirmation(store: HostRuntimeStore): HostConfirmationRequest {
+  const pending = store.getPendingHostConfirmation();
+  if (!pending) throw new Error("Expected a pending host confirmation");
+  return pending;
+}
+
+function createPairingStore(
+  input: {
+    hostname?: string;
+    password?: string;
+    connectAttempts?: string[];
+    serverIdForHost?: (host: HostProfile) => string;
+    storage?: HostRuntimeStorage;
+  } = {},
+): HostRuntimeStore {
+  return new HostRuntimeStore({
+    storage: input.storage ?? createMemoryHostRuntimeStorage(),
+    deps: {
+      createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
+      connectToDaemon: async ({ host, connection }) => {
+        input.connectAttempts?.push(connection.id);
+        if (input.password && host.password !== input.password) {
+          throw new DaemonAuthenticationError("password_required");
+        }
+        return {
+          client: makeConnectedProbeClient(5) as unknown as DaemonClient,
+          serverId: input.serverIdForHost?.(host) ?? host.serverId,
+          hostname: input.hostname ?? "paired",
+        };
+      },
+      getClientId: async () => "cid_pairing",
+      readInitialConnectionHint: () => null,
+    },
+  });
+}
+
 function createMemoryHostRuntimeStorage(entries: Record<string, string> = {}): HostRuntimeStorage {
   const values = new Map(Object.entries(entries));
   return {
@@ -3547,19 +3605,10 @@ describe("HostRuntimeStore", () => {
   });
 
   it("uses the advertised hostname when adding a relay host from a pairing offer", async () => {
-    const store = new HostRuntimeStore({
-      deps: {
-        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
-        connectToDaemon: async ({ host }) => ({
-          client: makeConnectedProbeClient(5) as unknown as DaemonClient,
-          serverId: host.serverId,
-          hostname: host.label ?? null,
-        }),
-        getClientId: async () => "cid_test_runtime",
-      },
-    });
+    const store = createPairingStore({ hostname: "mbp" });
+    answerHostConfirmations(store, true);
 
-    await store.upsertConnectionFromOffer(makeOffer(), "mbp");
+    await store.beginLinkPairing().submit(encodeOfferUrl(makeOffer()));
 
     const pairedHost = store.getHosts().find((host) => host.serverId === "srv_offer");
     expect(pairedHost?.label).toBe("mbp");
@@ -3568,27 +3617,14 @@ describe("HostRuntimeStore", () => {
   });
 
   it("stores relay TLS from a pairing offer", async () => {
-    const store = new HostRuntimeStore({
-      deps: {
-        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
-        connectToDaemon: async ({ host }) => ({
-          client: makeConnectedProbeClient(5) as unknown as DaemonClient,
-          serverId: host.serverId,
-          hostname: host.label ?? null,
-        }),
-        getClientId: async () => "cid_test_runtime",
-      },
-    });
+    const store = createPairingStore();
+    answerHostConfirmations(store, true);
 
-    await store.upsertConnectionFromOffer(
-      makeOffer({
-        relay: {
-          endpoint: "relay.example.com:443",
-          useTls: true,
-        },
-      }),
-      "tls relay",
-    );
+    await store
+      .beginLinkPairing()
+      .submit(
+        encodeOfferUrl(makeOffer({ relay: { endpoint: "relay.example.com:443", useTls: true } })),
+      );
 
     const pairedHost = store.getHosts().find((host) => host.serverId === "srv_offer");
     expect(pairedHost?.connections).toEqual([
@@ -3605,17 +3641,8 @@ describe("HostRuntimeStore", () => {
   });
 
   it("uses TLS for old pairing URLs that omit relay TLS on port 443", async () => {
-    const store = new HostRuntimeStore({
-      deps: {
-        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
-        connectToDaemon: async ({ host }) => ({
-          client: makeConnectedProbeClient(5) as unknown as DaemonClient,
-          serverId: host.serverId,
-          hostname: host.label ?? null,
-        }),
-        getClientId: async () => "cid_test_runtime",
-      },
-    });
+    const store = createPairingStore();
+    answerHostConfirmations(store, true);
     const oldPairingUrl = encodeOfferUrl({
       v: 2,
       serverId: "srv_offer",
@@ -3623,7 +3650,7 @@ describe("HostRuntimeStore", () => {
       relay: { endpoint: "relay.paseo.sh:443" },
     });
 
-    await store.upsertConnectionFromOfferUrl(oldPairingUrl, "old relay");
+    await store.importConnectionLink(oldPairingUrl, "openProject");
 
     const pairedHost = store.getHosts().find((host) => host.serverId === "srv_offer");
     expect(pairedHost?.connections).toEqual([
@@ -3640,54 +3667,266 @@ describe("HostRuntimeStore", () => {
   });
 
   it("probes a pairing link immediately and saves only after admission", async () => {
-    const store = new HostRuntimeStore({
-      deps: {
-        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
-        connectToDaemon: async ({ host }) => {
-          if (host.password !== "correct-password")
-            throw new DaemonAuthenticationError("password_required");
-          return {
-            client: makeConnectedProbeClient(5) as unknown as DaemonClient,
-            serverId: host.serverId,
-            hostname: "paired host",
-          };
-        },
-        getClientId: async () => "cid_pairing",
-      },
-    });
+    const store = createPairingStore({ password: "correct-password" });
+    answerHostConfirmations(store, true);
     const offerUrl = encodeOfferUrl(makeOffer());
-    await expect(store.probeAndUpsertConnectionFromOfferUrl(offerUrl)).rejects.toThrow(
-      "Password required",
-    );
+    const pairing = store.beginLinkPairing();
+
+    await expect(pairing.submit(offerUrl)).rejects.toThrow("Password required");
     expect(store.getHosts()).toHaveLength(0);
-    const result = await store.probeAndUpsertConnectionFromOfferUrl(offerUrl, "correct-password");
-    expect(result.serverId).toBe("srv_offer");
+    const result = await pairing.submit(offerUrl, "correct-password");
+    expect(result).toMatchObject({ status: "connected", serverId: "srv_offer" });
     expect(store.getHosts()[0]?.password).toBe("correct-password");
     store.syncHosts([]);
   });
 
-  it("preserves the existing host label when re-pairing an existing relay host", async () => {
-    const store = new HostRuntimeStore({
-      deps: {
-        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
-        connectToDaemon: async ({ host }) => ({
-          client: makeConnectedProbeClient(5) as unknown as DaemonClient,
-          serverId: host.serverId,
-          hostname: host.label ?? null,
-        }),
-        getClientId: async () => "cid_test_runtime",
+  it("asks before a pairing link adds a new host, and Cancel saves and connects nothing", async () => {
+    const connectAttempts: string[] = [];
+    const store = createPairingStore({ connectAttempts });
+    const requests = answerHostConfirmations(store, false);
+    const offerUrl = encodeOfferUrl(makeOffer());
+    const relayLink = "relay://relay.example:443/srv_relay?key=AAAA&ssl=true";
+
+    // `#offer=` in the app URL, then a QR scan, then the pair-link and add-host modals.
+    await expect(store.importConnectionLink(offerUrl, "openProject")).resolves.toEqual({
+      status: "cancelled",
+    });
+    await expect(store.importConnectionLink(offerUrl, "hostRoot")).resolves.toEqual({
+      status: "cancelled",
+    });
+    await expect(store.beginLinkPairing().submit(offerUrl)).resolves.toEqual({
+      status: "cancelled",
+    });
+    await expect(store.beginLinkPairing().submit(relayLink)).resolves.toEqual({
+      status: "cancelled",
+    });
+
+    expect(requests).toEqual([
+      ...Array.from({ length: 3 }, () => ({
+        id: expect.any(Number),
+        serverId: "srv_offer",
+        keyFingerprint: "pkte stof fer",
+        relayEndpoint: "relay.paseo.sh:443",
+        kind: "newHost",
+      })),
+      {
+        id: expect.any(Number),
+        serverId: "srv_relay",
+        keyFingerprint: "AAAA",
+        relayEndpoint: "relay.example:443",
+        kind: "newHost",
       },
-      storage: createMemoryHostRuntimeStorage(),
-    });
+    ]);
+    expect(store.getHosts()).toEqual([]);
+    expect(connectAttempts).toEqual([]);
+    store.syncHosts([]);
+  });
 
-    await store.upsertRelayConnection({
+  it("connects a saved host from a matching pairing link without asking", async () => {
+    const store = createPairingStore();
+    const requests = answerHostConfirmations(store, true);
+    const offerUrl = encodeOfferUrl(makeOffer());
+    await store.beginLinkPairing().submit(offerUrl);
+    expect(requests).toHaveLength(1);
+
+    await expect(store.importConnectionLink(offerUrl, "openProject")).resolves.toEqual({
+      status: "connected",
       serverId: "srv_offer",
-      relayEndpoint: "relay.paseo.sh:443",
-      daemonPublicKeyB64: "pk_test_offer",
-      label: "Custom name",
+    });
+    await expect(store.importConnectionLink(offerUrl, "hostRoot")).resolves.toEqual({
+      status: "connected",
+      serverId: "srv_offer",
+    });
+    await expect(store.beginLinkPairing().submit(offerUrl)).resolves.toMatchObject({
+      status: "connected",
     });
 
-    await store.upsertConnectionFromOffer(makeOffer(), "mbp");
+    expect(requests).toHaveLength(1);
+    expect(store.getHosts()).toHaveLength(1);
+    store.syncHosts([]);
+  });
+
+  it("asks when a pairing link changes a saved host's key, relay, or TLS setting", async () => {
+    const store = createPairingStore();
+    const requests = answerHostConfirmations(store, (_request, index) => index === 0);
+    await store.beginLinkPairing().submit(encodeOfferUrl(makeOffer()));
+    const savedHosts = store.getHosts();
+
+    const changedLinks = [
+      makeOffer({ daemonPublicKeyB64: "pk_other_key" }),
+      makeOffer({ relay: { endpoint: "relay.example:443", useTls: false } }),
+      makeOffer({ relay: { endpoint: "relay.paseo.sh:443", useTls: true } }),
+    ].map(encodeOfferUrl);
+    for (const link of changedLinks) {
+      await expect(store.importConnectionLink(link, "openProject")).resolves.toEqual({
+        status: "cancelled",
+      });
+      await expect(store.beginLinkPairing().submit(link)).resolves.toEqual({
+        status: "cancelled",
+      });
+    }
+
+    expect(requests.map((request) => request.kind)).toEqual([
+      "newHost",
+      ...Array.from({ length: 6 }, () => "changedConnection"),
+    ]);
+    expect(store.getHosts()).toEqual(savedHosts);
+    store.syncHosts([]);
+  });
+
+  it("asks once per pairing flow and link when the host asks for a password", async () => {
+    const store = createPairingStore({ password: "correct-password" });
+    const requests = answerHostConfirmations(store, (_request, index) => index < 2);
+    const offerUrl = encodeOfferUrl(makeOffer());
+    const pairing = store.beginLinkPairing();
+
+    await expect(pairing.submit(offerUrl)).rejects.toThrow("Password required");
+    await expect(pairing.submit(offerUrl, "wrong-password")).rejects.toThrow();
+    expect(requests).toHaveLength(1);
+
+    // A new pairing flow for the same link asks again.
+    await expect(store.beginLinkPairing().submit(offerUrl, "wrong-password")).rejects.toThrow();
+    expect(requests).toHaveLength(2);
+
+    await expect(pairing.submit(offerUrl, "correct-password")).resolves.toMatchObject({
+      status: "connected",
+    });
+    expect(requests).toHaveLength(2);
+    expect(store.getHosts()[0]).toMatchObject({
+      serverId: "srv_offer",
+      password: "correct-password",
+    });
+
+    // A different link in the same flow asks again.
+    const otherKeyUrl = encodeOfferUrl(makeOffer({ daemonPublicKeyB64: "pk_other_key" }));
+    await expect(pairing.submit(otherKeyUrl, "correct-password")).resolves.toEqual({
+      status: "cancelled",
+    });
+    expect(requests).toHaveLength(3);
+    store.syncHosts([]);
+  });
+
+  it("continues a scanned link's password retry without asking again", async () => {
+    const store = createPairingStore({ password: "correct-password" });
+    const requests = answerHostConfirmations(store, true);
+    const link = "relay://relay.example:443/srv_pair?key=AAAA&ssl=true";
+
+    const outcome = await store.importConnectionLink(link, "hostRoot");
+    expect(outcome).toMatchObject({ status: "password_required", link });
+    expect(store.getHosts()).toHaveLength(0);
+    if (outcome.status !== "password_required") throw new Error("expected password_required");
+
+    await outcome.pairing.submit(outcome.link, "correct-password");
+    expect(requests).toHaveLength(1);
+    expect(store.getHosts()[0]).toMatchObject({
+      serverId: "srv_pair",
+      password: "correct-password",
+    });
+    store.syncHosts([]);
+  });
+
+  it("keeps a host confirmation pending until it is answered, and a newer one cancels it", async () => {
+    const store = createPairingStore();
+    const first = store.importConnectionLink(encodeOfferUrl(makeOffer()), "openProject");
+    await vi.waitFor(() =>
+      expect(store.getPendingHostConfirmation()).toMatchObject({ serverId: "srv_offer" }),
+    );
+
+    const second = store.importConnectionLink(
+      encodeOfferUrl(makeOffer({ serverId: "srv_second" })),
+      "openProject",
+    );
+    await expect(first).resolves.toEqual({ status: "cancelled" });
+    await vi.waitFor(() =>
+      expect(store.getPendingHostConfirmation()).toMatchObject({ serverId: "srv_second" }),
+    );
+
+    store.answerHostConfirmation(requirePendingConfirmation(store).id, true);
+    await expect(second).resolves.toEqual({ status: "connected", serverId: "srv_second" });
+    expect(store.getPendingHostConfirmation()).toBeNull();
+    expect(store.getHosts().map((host) => host.serverId)).toEqual(["srv_second"]);
+    store.syncHosts([]);
+  });
+
+  it("ignores an answer for a host confirmation that a newer one replaced", async () => {
+    const store = createPairingStore();
+    const first = store.importConnectionLink(encodeOfferUrl(makeOffer()), "openProject");
+    await vi.waitFor(() =>
+      expect(store.getPendingHostConfirmation()).toMatchObject({ serverId: "srv_offer" }),
+    );
+    const firstRequest = requirePendingConfirmation(store);
+    const second = store.importConnectionLink(
+      encodeOfferUrl(makeOffer({ serverId: "srv_second" })),
+      "openProject",
+    );
+    await expect(first).resolves.toEqual({ status: "cancelled" });
+
+    // Connect tapped on the first sheet as the second link arrives.
+    store.answerHostConfirmation(firstRequest.id, true);
+
+    const secondRequest = requirePendingConfirmation(store);
+    expect(secondRequest.serverId).toBe("srv_second");
+    store.answerHostConfirmation(secondRequest.id, false);
+    await expect(second).resolves.toEqual({ status: "cancelled" });
+    expect(store.getHosts()).toEqual([]);
+  });
+
+  it("waits for saved hosts to load before deciding whether a pairing link asks", async () => {
+    const savedHost = makeHost({
+      serverId: "srv_offer",
+      connections: [
+        {
+          id: "relay:relay.paseo.sh:443",
+          type: "relay",
+          relayEndpoint: "relay.paseo.sh:443",
+          useTls: false,
+          daemonPublicKeyB64: "pk_test_offer",
+        },
+      ],
+    });
+    const store = createPairingStore({
+      storage: createMemoryHostRuntimeStorage({
+        "@paseo:daemon-registry": JSON.stringify([savedHost]),
+        "@paseo:e2e": "1",
+      }),
+    });
+    const requests = answerHostConfirmations(store, true);
+
+    await expect(
+      store.importConnectionLink(encodeOfferUrl(makeOffer()), "openProject"),
+    ).resolves.toEqual({ status: "connected", serverId: "srv_offer" });
+
+    expect(requests).toEqual([]);
+    expect(store.getHosts().map((host) => host.serverId)).toEqual(["srv_offer"]);
+    store.syncHosts([]);
+  });
+
+  it("adds hosts by address and the default localhost without asking", async () => {
+    const store = createPairingStore({
+      serverIdForHost: (host) =>
+        host.connections[0]?.type === "directTcp" ? `srv_${host.connections[0].endpoint}` : "",
+    });
+    const requests = answerHostConfirmations(store, false);
+
+    await store.boot();
+    await store.probeAndUpsertDirectConnection({ endpoint: "10.0.0.5:6767" });
+
+    expect(requests).toEqual([]);
+    expect(store.getHosts().map((host) => host.serverId)).toEqual([
+      "srv_localhost:6767",
+      "srv_10.0.0.5:6767",
+    ]);
+    store.syncHosts([]);
+  });
+
+  it("preserves the existing host label when re-pairing an existing relay host", async () => {
+    const store = createPairingStore({ hostname: "mbp" });
+    answerHostConfirmations(store, true);
+
+    await store.beginLinkPairing().submit(encodeOfferUrl(makeOffer()));
+    await store.renameHost("srv_offer", "Custom name");
+
+    await store.beginLinkPairing().submit(encodeOfferUrl(makeOffer()));
 
     const pairedHost = store.getHosts().find((host) => host.serverId === "srv_offer");
     expect(pairedHost?.label).toBe("Custom name");
@@ -3963,35 +4202,6 @@ describe("HostRuntimeStore initial connection hint bootstrap", () => {
     expect(probeAttempts).toBe(attemptsBeforeRetry);
     store.syncHosts([]);
   });
-  it("imports a pairing link after a password retry in the add flow", async () => {
-    const store = new HostRuntimeStore({
-      storage: createMemoryHostRuntimeStorage(),
-      deps: {
-        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
-        connectToDaemon: async ({ host }) => {
-          if (host.password !== "correct-password")
-            throw new DaemonAuthenticationError("password_required");
-          return {
-            client: makeConnectedProbeClient(5) as unknown as DaemonClient,
-            serverId: host.serverId,
-            hostname: "paired",
-          };
-        },
-        getClientId: async () => "cid_link_import",
-      },
-    });
-    const link = "relay://relay.example:443/srv_pair?key=AAAA&ssl=true";
-    await expect(store.importConnectionLink(link, "hostRoot")).resolves.toEqual({
-      status: "password_required",
-    });
-    expect(store.getHosts()).toHaveLength(0);
-    await store.probeAndUpsertConnectionFromOfferUrl(link, "correct-password");
-    expect(store.getHosts()[0]).toMatchObject({
-      serverId: "srv_pair",
-      password: "correct-password",
-    });
-    store.syncHosts([]);
-  });
   it("imports a deep link without waiting for admission, then leaves a rejected saved host red", async () => {
     const store = new HostRuntimeStore({
       storage: createMemoryHostRuntimeStorage(),
@@ -4003,6 +4213,7 @@ describe("HostRuntimeStore initial connection hint bootstrap", () => {
         getClientId: async () => "cid_deep_link",
       },
     });
+    answerHostConfirmations(store, true);
     const link = "relay://relay.example:443/srv_deep?key=AAAA&ssl=true";
     await expect(store.importConnectionLink(link, "openProject")).resolves.toEqual({
       status: "connected",
@@ -4017,6 +4228,38 @@ describe("HostRuntimeStore initial connection hint bootstrap", () => {
     expect(store.getSnapshot("srv_deep")?.connectionStatus).toBe("error");
     store.syncHosts([]);
   });
+  it("stops connecting to a host removed while its first probe is pending", async () => {
+    useHostRuntimeClock();
+    const firstProbe = createDeferred<void>();
+    let connectCalls = 0;
+    const store = new HostRuntimeStore({
+      storage: createMemoryHostRuntimeStorage(),
+      deps: {
+        createClient: () => new FakeDaemonClient() as unknown as DaemonClient,
+        connectToDaemon: async ({ host }) => {
+          connectCalls += 1;
+          if (connectCalls === 1) await firstProbe.promise;
+          return {
+            client: makeConnectedProbeClient(5) as unknown as DaemonClient,
+            serverId: host.serverId,
+            hostname: host.label ?? null,
+          };
+        },
+        getClientId: async () => "cid_test_removed_host",
+      },
+    });
+    await store.upsertDirectConnection({ serverId: "srv_removed", endpoint: "lan:6767" });
+    await vi.waitFor(() => expect(connectCalls).toBe(1));
+
+    await store.removeHost("srv_removed");
+    firstProbe.resolve();
+    await vi.advanceTimersByTimeAsync(60_000);
+
+    expect(connectCalls).toBe(1);
+    expect(store.getSnapshot("srv_removed")).toBeNull();
+    expect(useSessionStore.getState().sessions["srv_removed"]).toBeUndefined();
+  });
+
   it("saves and reconnects a rejected saved host after changing its password", async () => {
     const store = new HostRuntimeStore({
       storage: createMemoryHostRuntimeStorage(),

packages/app/src/runtime/host-runtime.ts

@@ -14,6 +14,7 @@ import {
   normalizeStoredHostProfile,
   upsertHostConnectionInProfiles,
   registryHasConnection,
+  relayConnectionFromOffer,
   StoredHostRegistrySchema,
   type HostConnection,
   type HostProfile,
@@ -29,6 +30,7 @@ import {
 } from "@/utils/daemon-endpoints";
 import { resolveAppVersion } from "@/utils/app-version";
 import { ConnectionOfferSchema, type ConnectionOffer } from "@getpaseo/protocol/connection-offer";
+import { HostConfirmations, type HostConfirmationRequest } from "./host-confirmation";
 import { shouldUseDesktopDaemon } from "@/desktop/daemon/desktop-daemon";
 import { isWeb } from "@/constants/platform";
 import { connectToDaemon, getConnectionAuthFailureReason } from "@/utils/test-daemon-connection";
@@ -89,6 +91,27 @@ export type HostRuntimeConnectionStatus = "idle" | "connecting" | "online" | "of
 export type PairingNavigationTarget = "openProject" | "hostRoot" | "hostSettings";
 export type HostRegistryStatus = "loading" | "ready";
 
+/** One pairing flow started with `HostRuntimeStore.beginLinkPairing`. */
+export interface LinkPairing {
+  /** Probes the linked host and saves it. Connection and password errors throw. */
+  submit(link: string, password?: string): Promise<LinkPairingResult>;
+}
+
+export type LinkPairingResult =
+  | { status: "connected"; profile: HostProfile; serverId: string; hostname: string | null }
+  | { status: "cancelled" };
+
+/** A pairing link the user confirmed whose host then asked for a password. */
+export interface PasswordRequiredPairing {
+  link: string;
+  pairing: LinkPairing;
+}
+
+export type ConnectionLinkImport =
+  | { status: "connected"; serverId: string }
+  | ({ status: "password_required" } & PasswordRequiredPairing)
+  | { status: "cancelled" };
+
 export type ActiveConnection =
   | { type: "directTcp"; endpoint: string; display: string }
   | { type: "directSocket"; endpoint: string; display: "socket" }
@@ -677,8 +700,15 @@ export class HostRuntimeController {
         connectionId: options.initialConnection.connectionId,
         existingClient: options.initialConnection.existingClient,
       });
+      if (!this.started) {
+        return;
+      }
     }
     await this.runProbeCycleNow();
+    // stop() can run while startup is pending; a stopped controller never probes again.
+    if (!this.started) {
+      return;
+    }
     if (options?.autoProbe !== false) {
       this.probeIntervalHandle = setInterval(() => {
         void this.runProbeCycleNow();
@@ -1408,6 +1438,13 @@ function readConfiguredLocalDaemonOverride(): string | null {
   return value && value.length > 0 ? value : null;
 }
 
+function isSameLinkedConnection(left: ConnectionOffer, right: ConnectionOffer): boolean {
+  return (
+    left.serverId === right.serverId &&
+    equal(relayConnectionFromOffer(left), relayConnectionFromOffer(right))
+  );
+}
+
 function parseOfferConnectionUrl(input: string): { offer: ConnectionOffer; password?: string } {
   if (input.trim().startsWith("relay://") || input.includes("#connect=")) {
     return parseRelayConnectionUri(input);
@@ -1469,6 +1506,8 @@ export class HostRuntimeStore {
   private timelineReplicaByServer = new Map<string, TimelineReplica>();
   private configuredOverrideBootstrapInFlight: Promise<void> | null = null;
   private bootPromise: Promise<void> | null = null;
+  private registryLoad: Promise<void> | null = null;
+  private readonly hostConfirmations = new HostConfirmations();
   private storage: HostRuntimeStorage;
   private replicaCache: ReplicaCache;
   private readonly revokePushNotifications: typeof revokePushNotifications;
@@ -1519,8 +1558,7 @@ export class HostRuntimeStore {
 
   private async runBoot(): Promise<void> {
     const override = readConfiguredLocalDaemonOverride();
-    await this.loadFromStorage();
-    this.markHostRegistryLoaded();
+    await this.loadRegistry();
 
     let isE2E: string | null = null;
     try {
@@ -1553,6 +1591,13 @@ export class HostRuntimeStore {
     }
   }
 
+  private loadRegistry(): Promise<void> {
+    if (!this.registryLoad) {
+      this.registryLoad = this.loadFromStorage().then(() => this.markHostRegistryLoaded());
+    }
+    return this.registryLoad;
+  }
+
   private async loadFromStorage(): Promise<void> {
     let shouldPersistHosts = false;
     let profiles: HostProfile[] = [];
@@ -1879,7 +1924,7 @@ export class HostRuntimeStore {
     });
   }
 
-  async upsertRelayConnection(input: {
+  private async upsertRelayConnection(input: {
     serverId: string;
     relayEndpoint: string;
     useTls?: boolean;
@@ -1912,51 +1957,91 @@ export class HostRuntimeStore {
     return profile;
   }
 
-  async upsertConnectionFromOffer(
+  // A pairing link (a URL, a QR code, or a pasted link) asks the user to
+  // confirm when it adds a new host or changes a saved host's key, relay, or
+  // TLS setting. The answer needs the saved hosts, so it waits for them to load.
+  private async confirmLink(offer: ConnectionOffer): Promise<boolean> {
+    await this.loadRegistry();
+    return this.hostConfirmations.confirmLink(offer, this.hosts);
+  }
+
+  getPendingHostConfirmation(): HostConfirmationRequest | null {
+    return this.hostConfirmations.getPending();
+  }
+
+  subscribeHostConfirmation(listener: () => void): () => void {
+    return this.hostConfirmations.subscribe(listener);
+  }
+
+  answerHostConfirmation(requestId: number, approved: boolean): void {
+    this.hostConfirmations.answer(requestId, approved);
+  }
+
+  /**
+   * Starts one pairing flow, such as one open pairing modal. Once the user
+   * confirms a link, submitting the same link again in this flow (the
+   * password retry) does not ask again. A new flow asks again.
+   */
+  beginLinkPairing(): LinkPairing {
+    let approvedOffer: ConnectionOffer | null = null;
+    return {
+      submit: async (link, password) => {
+        const { offer, password: linkPassword } = parseOfferConnectionUrl(link);
+        if (!approvedOffer || !isSameLinkedConnection(approvedOffer, offer)) {
+          if (!(await this.confirmLink(offer))) return { status: "cancelled" };
+          approvedOffer = offer;
+        }
+        const result = await this.probeAndUpsertOffer(offer, password ?? linkPassword);
+        return { status: "connected", ...result };
+      },
+    };
+  }
+
+  async importConnectionLink(
+    url: string,
+    target: PairingNavigationTarget,
+  ): Promise<ConnectionLinkImport> {
+    if (target === "openProject") {
+      const { offer, password } = parseOfferConnectionUrl(url);
+      if (!(await this.confirmLink(offer))) return { status: "cancelled" };
+      const profile = await this.upsertConnectionFromOffer(offer, undefined, password);
+      return { status: "connected", serverId: profile.serverId };
+    }
+    const pairing = this.beginLinkPairing();
+    try {
+      const result = await pairing.submit(url);
+      if (result.status === "cancelled") return result;
+      return { status: "connected", serverId: result.serverId };
+    } catch (error) {
+      if (!getConnectionAuthFailureReason(error)) throw error;
+      return { status: "password_required", link: url, pairing };
+    }
+  }
+
+  private async upsertConnectionFromOffer(
     offer: ConnectionOffer,
     label?: string,
     password?: string,
   ): Promise<HostProfile> {
-    // COMPAT(oldRelayOfferTls): added in v0.1.73, remove after 2026-11-10.
-    const useTls = offer.relay.useTls ?? shouldUseTlsForDefaultHostedRelay(offer.relay.endpoint);
+    const connection = relayConnectionFromOffer(offer);
     return this.upsertRelayConnection({
       serverId: offer.serverId,
-      relayEndpoint: offer.relay.endpoint,
-      useTls,
-      daemonPublicKeyB64: offer.daemonPublicKeyB64,
+      relayEndpoint: connection.relayEndpoint,
+      useTls: connection.useTls,
+      daemonPublicKeyB64: connection.daemonPublicKeyB64,
       label,
       password,
     });
   }
 
-  async upsertConnectionFromOfferUrl(
-    offerUrlOrFragment: string,
-    label?: string,
-    password?: string,
-  ): Promise<HostProfile> {
-    const parsed = parseOfferConnectionUrl(offerUrlOrFragment);
-    return this.upsertConnectionFromOffer(parsed.offer, label, password ?? parsed.password);
-  }
-
-  async probeAndUpsertConnectionFromOfferUrl(
-    offerUrlOrFragment: string,
-    password?: string,
+  private async probeAndUpsertOffer(
+    offer: ConnectionOffer,
+    password: string | undefined,
   ): Promise<{ profile: HostProfile; serverId: string; hostname: string | null }> {
-    const parsed = parseOfferConnectionUrl(offerUrlOrFragment);
-    const offer = parsed.offer;
-    const credential = password ?? parsed.password;
-    const useTls = offer.relay.useTls ?? shouldUseTlsForDefaultHostedRelay(offer.relay.endpoint);
-    const relayEndpoint = normalizeHostPort(offer.relay.endpoint);
-    const connection: HostConnection = {
-      id: useTls ? `relay:wss:${relayEndpoint}` : `relay:${relayEndpoint}`,
-      type: "relay",
-      relayEndpoint,
-      useTls,
-      daemonPublicKeyB64: offer.daemonPublicKeyB64,
-    };
+    const connection = relayConnectionFromOffer(offer);
     const probeHost: HostProfile = {
       serverId: offer.serverId,
-      ...(credential ? { password: credential } : {}),
+      ...(password ? { password } : {}),
       label: offer.serverId,
       appearance: defaultHostAppearance(),
       lifecycle: {},
@@ -1967,27 +2052,10 @@ export class HostRuntimeStore {
     };
     const { client, hostname } = await this.deps.connectToDaemon({ host: probeHost, connection });
     await client.close().catch(() => undefined);
-    const profile = await this.upsertConnectionFromOffer(offer, hostname ?? undefined, credential);
+    const profile = await this.upsertConnectionFromOffer(offer, hostname ?? undefined, password);
     return { profile, serverId: offer.serverId, hostname };
   }
 
-  async importConnectionLink(
-    url: string,
-    target: PairingNavigationTarget,
-  ): Promise<{ status: "connected"; serverId: string } | { status: "password_required" }> {
-    if (target === "openProject") {
-      const profile = await this.upsertConnectionFromOfferUrl(url);
-      return { status: "connected", serverId: profile.serverId };
-    }
-    try {
-      const { serverId } = await this.probeAndUpsertConnectionFromOfferUrl(url);
-      return { status: "connected", serverId };
-    } catch (error) {
-      if (!getConnectionAuthFailureReason(error)) throw error;
-      return { status: "password_required" };
-    }
-  }
-
   async upsertConnectionFromListen(input: {
     listenAddress: string;
     serverId: string;
@@ -2735,6 +2803,29 @@ export function useHostRegistryLoaded(): boolean {
   );
 }
 
+export function useHostConfirmation(): {
+  pending: HostConfirmationRequest | null;
+  answer: (approved: boolean) => void;
+} {
+  const store = getHostRuntimeStore();
+  const pending = useSyncExternalStore(
+    (onStoreChange) => store.subscribeHostConfirmation(onStoreChange),
+    () => store.getPendingHostConfirmation(),
+    () => store.getPendingHostConfirmation(),
+  );
+  // The answer is bound to the request this render shows, so a tap never
+  // answers a request that replaced it.
+  return useMemo(
+    () => ({
+      pending,
+      answer: (approved: boolean) => {
+        if (pending) store.answerHostConfirmation(pending.id, approved);
+      },
+    }),
+    [pending, store],
+  );
+}
+
 export interface HostMutations {
   upsertDirectConnection: (input: {
     serverId: string;
@@ -2755,24 +2846,7 @@ export interface HostMutations {
     daemonPort?: number;
     label?: string;
   }) => Promise<{ profile: HostProfile; serverId: string; hostname: string | null }>;
-  upsertRelayConnection: (input: {
-    serverId: string;
-    relayEndpoint: string;
-    useTls?: boolean;
-    daemonPublicKeyB64: string;
-    label?: string;
-    password?: string;
-  }) => Promise<HostProfile>;
-  upsertConnectionFromOffer: (offer: ConnectionOffer, label?: string) => Promise<HostProfile>;
-  upsertConnectionFromOfferUrl: (
-    offerUrlOrFragment: string,
-    label?: string,
-    password?: string,
-  ) => Promise<HostProfile>;
-  probeAndUpsertConnectionFromOfferUrl: (
-    offerUrlOrFragment: string,
-    password?: string,
-  ) => Promise<{ profile: HostProfile; serverId: string; hostname: string | null }>;
+  beginLinkPairing: () => LinkPairing;
   renameHost: (serverId: string, label: string) => Promise<void>;
   setHostColor: (serverId: string, color: HostColor) => Promise<void>;
   setHostBadgeDisplay: (serverId: string, badgeDisplay: HostBadgeDisplay) => Promise<void>;
@@ -2787,12 +2861,7 @@ export function useHostMutations(): HostMutations {
       upsertDirectConnection: (input) => store.upsertDirectConnection(input),
       probeAndUpsertDirectConnection: (input) => store.probeAndUpsertDirectConnection(input),
       probeAndUpsertRemoteSshConnection: (input) => store.probeAndUpsertRemoteSshConnection(input),
-      upsertRelayConnection: (input) => store.upsertRelayConnection(input),
-      upsertConnectionFromOffer: (offer, label) => store.upsertConnectionFromOffer(offer, label),
-      upsertConnectionFromOfferUrl: (url, label, password) =>
-        store.upsertConnectionFromOfferUrl(url, label, password),
-      probeAndUpsertConnectionFromOfferUrl: (url, password) =>
-        store.probeAndUpsertConnectionFromOfferUrl(url, password),
+      beginLinkPairing: () => store.beginLinkPairing(),
       renameHost: (serverId, label) => store.renameHost(serverId, label),
       setHostColor: (serverId, color) => store.setHostColor(serverId, color),
       setHostBadgeDisplay: (serverId, badgeDisplay) =>

packages/app/src/screens/settings/appearance/appearance-section.tsx

@@ -1,4 +1,4 @@
-import { Fragment, useCallback, useEffect, useMemo, useState } from "react";
+import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { TFunction } from "i18next";
 import { useTranslation } from "react-i18next";
 import { Text, View } from "react-native";
@@ -18,7 +18,11 @@ import {
 import { DropdownTrigger } from "@/components/ui/dropdown-trigger";
 import { SettingsSection } from "@/components/settings/headings/settings-section";
 import { useContributedThemes } from "@/appearance/provider";
-import { EditingTextInput as TextInput } from "@/components/ui/text-input";
+import { Button } from "@/components/ui/button";
+import {
+  EditingTextInput as TextInput,
+  type EditingTextInputHandle,
+} from "@/components/ui/text-input";
 import {
   MAX_CODE_FONT_SIZE,
   MAX_CONTENT_FONT_SIZE,
@@ -27,6 +31,8 @@ import {
   MIN_CONTENT_FONT_SIZE,
   MIN_UI_BASE_FONT_SIZE,
   parseClampedFontSize,
+  parseContentMaxWidth,
+  resolveContentMaxWidth,
   sanitizeFontFamily,
   useAppSettings,
   type AppSettings,
@@ -326,6 +332,74 @@ function FontSizeRow({
   );
 }
 
+// ---------------------------------------------------------------------------
+// Content width: numeric field (commit on blur/submit) + reset to the default
+// ---------------------------------------------------------------------------
+
+interface ContentWidthRowProps {
+  value: AppSettings["contentMaxWidth"];
+  onChange: (value: AppSettings["contentMaxWidth"]) => void;
+}
+
+function ContentWidthRow({ value, onChange }: ContentWidthRowProps) {
+  const { t } = useTranslation();
+  const width = resolveContentMaxWidth({ contentMaxWidth: value });
+  // The field is uncontrolled, so a saved or reset width is written into it directly.
+  const input = useRef<EditingTextInputHandle>(null);
+
+  useEffect(() => {
+    input.current?.replaceText(String(width));
+  }, [width]);
+
+  const commit = useCallback(() => {
+    const next = parseContentMaxWidth(input.current?.getText()) ?? width;
+    input.current?.replaceText(String(next));
+    // Typing the width already in effect keeps following the default.
+    if (next !== width) {
+      onChange(next);
+    }
+  }, [onChange, width]);
+
+  const reset = useCallback(() => {
+    onChange(null);
+  }, [onChange]);
+
+  return (
+    <View style={settingsStyles.row}>
+      <View style={settingsStyles.rowContent}>
+        <Text style={settingsStyles.rowTitle}>{t("settings.appearance.layout.contentWidth")}</Text>
+        <Text style={settingsStyles.rowHint}>
+          {t("settings.appearance.layout.contentWidthHint")}
+        </Text>
+      </View>
+      <View style={styles.sizeField}>
+        {value === null ? null : (
+          <Button
+            variant="ghost"
+            size="sm"
+            onPress={reset}
+            accessibilityLabel={t("settings.appearance.layout.resetAccessibility")}
+          >
+            {t("settings.appearance.layout.reset")}
+          </Button>
+        )}
+        <TextInput
+          ref={input}
+          initialValue={String(width)}
+          onBlur={commit}
+          onSubmitEditing={commit}
+          keyboardType="number-pad"
+          inputMode="numeric"
+          selectTextOnFocus
+          style={styles.widthInput}
+          accessibilityLabel={t("settings.appearance.layout.contentWidthAccessibility")}
+        />
+        <Text style={styles.unit}>px</Text>
+      </View>
+    </View>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Syntax highlight theme picker (commits immediately)
 // ---------------------------------------------------------------------------
@@ -440,6 +514,13 @@ export function AppearanceSection() {
     [selectPluginTheme],
   );
 
+  const handleContentMaxWidthChange = useCallback(
+    (contentMaxWidth: AppSettings["contentMaxWidth"]) => {
+      void updateSettings({ contentMaxWidth });
+    },
+    [updateSettings],
+  );
+
   const handleSyntaxThemeChange = useCallback(
     (syntaxTheme: SyntaxThemeId) => {
       void updateSettings({ syntaxTheme });
@@ -603,6 +684,14 @@ export function AppearanceSection() {
           />
         </View>
       </SettingsSection>
+      <SettingsSection title={t("settings.appearance.layout.title")}>
+        <View style={settingsStyles.card}>
+          <ContentWidthRow
+            value={settings.contentMaxWidth}
+            onChange={handleContentMaxWidthChange}
+          />
+        </View>
+      </SettingsSection>
       <SettingsSection title={t("settings.appearance.syntax.title")}>
         <View style={settingsStyles.card}>
           <SyntaxRow value={settings.syntaxTheme} onChange={handleSyntaxThemeChange} />
@@ -668,6 +757,19 @@ const styles = StyleSheet.create((theme) => ({
     fontSize: theme.fontSize.base,
     textAlign: "right",
   },
+  widthInput: {
+    width: 80,
+    minHeight: 36,
+    paddingVertical: theme.spacing[2],
+    paddingHorizontal: theme.spacing[3],
+    borderRadius: theme.borderRadius.md,
+    borderWidth: theme.borderWidth[1],
+    borderColor: theme.colors.border,
+    backgroundColor: theme.colors.surface2,
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.base,
+    textAlign: "right",
+  },
   unit: {
     color: theme.colors.foregroundMuted,
     fontSize: theme.fontSize.base,

packages/app/src/screens/workspace/workspace-route-state-views.tsx

@@ -126,15 +126,21 @@ function ArchivedWorkspaceRecovery({
   if (recovery.phase === "failed") {
     actionLabel = t("common.actions.retry");
   }
-  const description =
-    recovery.recovery.action === "restore"
-      ? t("workspace.route.recovery.restoreDescription", {
-          workspaceName: recovery.recovery.workspaceName,
-          branch: recovery.recovery.branch,
-        })
-      : t("workspace.route.recovery.unarchiveDescription", {
-          workspaceName: recovery.recovery.workspaceName,
-        });
+  let description: string;
+  if (recovery.recovery.action === "restore" && recovery.recovery.branch) {
+    description = t("workspace.route.recovery.restoreDescription", {
+      workspaceName: recovery.recovery.workspaceName,
+      branch: recovery.recovery.branch,
+    });
+  } else if (recovery.recovery.action === "restore") {
+    description = t("workspace.route.recovery.restoreWithoutBranchDescription", {
+      workspaceName: recovery.recovery.workspaceName,
+    });
+  } else {
+    description = t("workspace.route.recovery.unarchiveDescription", {
+      workspaceName: recovery.recovery.workspaceName,
+    });
+  }
 
   return (
     <View style={styles.emptyState}>

packages/app/src/styles/theme.ts

@@ -642,7 +642,10 @@ export const DEFAULT_MONO_FONT_STACK: string = Platform.select({
   web: "SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace",
 });
 
-// `fontSize`, `fontFamily`, and `lineHeight` are deliberately widened to plain
+// Chat and markdown content column; the appearance updater patches the user's width in.
+export const DEFAULT_CONTENT_MAX_WIDTH = 820;
+
+// `fontSize`, `fontFamily`, `lineHeight`, and `contentMaxWidth` are deliberately widened to plain
 // `number`/`string` (not narrowed by `as const`) so the appearance updater can patch
 // them at runtime via `UnistylesRuntime.updateTheme`. The remaining tokens keep their
 // literal types.
@@ -651,6 +654,7 @@ interface CommonTheme {
   fontSize: Record<keyof typeof FONT_SIZE, number>;
   fontFamily: { ui: string; mono: string };
   lineHeight: Record<keyof typeof LINE_HEIGHT, number>;
+  contentMaxWidth: number;
   iconSize: typeof ICON_SIZE;
   fontWeight: typeof FONT_WEIGHT;
   borderRadius: typeof BORDER_RADIUS;
@@ -663,6 +667,7 @@ const commonTheme: CommonTheme = {
   fontSize: FONT_SIZE,
   fontFamily: { ui: DEFAULT_UI_FONT_STACK, mono: DEFAULT_MONO_FONT_STACK },
   lineHeight: LINE_HEIGHT,
+  contentMaxWidth: DEFAULT_CONTENT_MAX_WIDTH,
   iconSize: ICON_SIZE,
   fontWeight: FONT_WEIGHT,
   borderRadius: BORDER_RADIUS,

packages/app/src/types/host-connection.ts

@@ -1,6 +1,8 @@
+import type { ConnectionOffer } from "@getpaseo/protocol/connection-offer";
 import {
   normalizeHostPort,
   normalizeLoopbackToLocalhost,
+  shouldUseTlsForDefaultHostedRelay,
 } from "@getpaseo/protocol/daemon-endpoints";
 import {
   DirectTcpHostConnectionSchema,
@@ -354,6 +356,19 @@ export function connectionFromListen(listen: string): HostConnection | null {
   }
 }
 
+export function relayConnectionFromOffer(offer: ConnectionOffer): RelayHostConnection {
+  // COMPAT(oldRelayOfferTls): added in v0.1.73, remove after 2026-11-10.
+  const useTls = offer.relay.useTls ?? shouldUseTlsForDefaultHostedRelay(offer.relay.endpoint);
+  const relayEndpoint = normalizeHostPort(offer.relay.endpoint);
+  return {
+    id: useTls ? `relay:wss:${relayEndpoint}` : `relay:${relayEndpoint}`,
+    type: "relay",
+    relayEndpoint,
+    useTls,
+    daemonPublicKeyB64: offer.daemonPublicKeyB64.trim(),
+  };
+}
+
 export function createRemoteSshHostConnection(input: {
   host: string;
   sshPort?: number;

packages/app/src/usage/queries.ts

@@ -31,13 +31,8 @@ function usageReportsQueryKey(serverId: string) {
   return ["usage", "reports", serverId] as const;
 }
 
-function agentUsageQueryKey(
-  serverId: string,
-  agentId: string,
-  model: string | null,
-  isRunning: boolean,
-) {
-  return ["usage", "agent", serverId, agentId, model, isRunning] as const;
+function agentUsageQueryKey(serverId: string, agentId: string, model: string | null) {
+  return ["usage", "agent", serverId, agentId, model] as const;
 }
 
 function requireClient(serverId: string) {
@@ -165,7 +160,8 @@ export function useUsageByHost(): {
 /**
  * The usage report for the account an agent is spending. The daemon resolves the
  * report ID, which is re-resolved when the model changes (a new key) and when a
- * turn completes (a new query key). The report itself is read from the shared cache.
+ * turn completes (the query is paused while the agent runs, and its data is always
+ * stale, so resuming refetches). The report itself is read from the shared cache.
  */
 export function useAgentUsage(
   serverId: string,
@@ -180,10 +176,10 @@ export function useAgentUsage(
     }),
   );
   const identity = useFetchQuery({
-    queryKey: agentUsageQueryKey(serverId, agentId, model, isRunning),
+    queryKey: agentUsageQueryKey(serverId, agentId, model),
     queryFn: async () =>
       (await requireClient(serverId).resolveAgentUsageReport({ agentId })).reportId,
-    enabled: isConnected && isSupported,
+    enabled: isConnected && isSupported && !isRunning,
     dataShape: "value",
     staleTimeMs: 0,
   });

packages/app/src/utils/assistant-image-metadata.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it } from "vitest";
+import { DEFAULT_CONTENT_MAX_WIDTH } from "@/styles/theme";
 import {
   clearAssistantImageMetadataCache,
   estimateAssistantMessageHeightFromCache,
@@ -52,6 +53,7 @@ describe("assistant image metadata", () => {
     expect(
       estimateAssistantMessageHeightFromCache(
         "Here is the screenshot\n\n![Screenshot](https://example.com/landscape.png)",
+        DEFAULT_CONTENT_MAX_WIDTH,
       ),
     ).toBeGreaterThan(220);
   });
@@ -60,8 +62,14 @@ describe("assistant image metadata", () => {
     const source = `data:image/png;base64,${"a".repeat(512)}`;
     setAssistantImageMetadata({ source }, { width: 1200, height: 800 });
 
-    const imageOnlyHeight = estimateAssistantMessageHeightFromCache(`![Screenshot](${source})`);
-    const mixedHeight = estimateAssistantMessageHeightFromCache(`Text\n\n![Screenshot](${source})`);
+    const imageOnlyHeight = estimateAssistantMessageHeightFromCache(
+      `![Screenshot](${source})`,
+      DEFAULT_CONTENT_MAX_WIDTH,
+    );
+    const mixedHeight = estimateAssistantMessageHeightFromCache(
+      `Text\n\n![Screenshot](${source})`,
+      DEFAULT_CONTENT_MAX_WIDTH,
+    );
 
     expect(imageOnlyHeight).toBeGreaterThan(220);
     expect(mixedHeight).toBeGreaterThan(imageOnlyHeight ?? 0);

packages/app/src/utils/assistant-image-metadata.ts

@@ -1,4 +1,3 @@
-import { MAX_CONTENT_WIDTH } from "@/constants/layout";
 import { resolveAssistantImageSource } from "@/utils/assistant-image-source";
 import { createImageSourceCacheKey } from "@/attachments/utils";
 
@@ -14,7 +13,7 @@ const ASSISTANT_IMAGE_METADATA_CACHE_LIMIT = 500;
 const ASSISTANT_IMAGE_PARSE_CACHE_LIMIT = 500;
 
 const MARKDOWN_IMAGE_PATTERN = /!\[[^\]]*]\((<[^>]+>|[^)\n]+)\)/g;
-const ASSISTANT_IMAGE_ESTIMATE_WIDTH = MAX_CONTENT_WIDTH - 8;
+const ASSISTANT_IMAGE_INSET = 8;
 const ASSISTANT_IMAGE_MIN_HEIGHT = 160;
 const ASSISTANT_IMAGE_BLOCK_GAP = 24;
 const ASSISTANT_MESSAGE_BASE_HEIGHT = 96;
@@ -177,7 +176,10 @@ export function extractAssistantImageSources(markdown: string): string[] {
   return parsed.sources;
 }
 
-export function estimateAssistantMessageHeightFromCache(markdown: string): number | null {
+export function estimateAssistantMessageHeightFromCache(
+  markdown: string,
+  contentMaxWidth: number,
+): number | null {
   const parsed = assistantImageParseCache.get(markdown) ?? parseAssistantImageMarkdown(markdown);
   if (parsed.sources.length === 0) {
     return null;
@@ -189,7 +191,7 @@ export function estimateAssistantMessageHeightFromCache(markdown: string): numbe
     .map((metadata) =>
       Math.max(
         ASSISTANT_IMAGE_MIN_HEIGHT,
-        Math.round(ASSISTANT_IMAGE_ESTIMATE_WIDTH / metadata.aspectRatio),
+        Math.round((contentMaxWidth - ASSISTANT_IMAGE_INSET) / metadata.aspectRatio),
       ),
     );
 

packages/app/src/utils/assistant-message-height-estimate.test.ts

@@ -1,4 +1,5 @@
 import { beforeEach, describe, expect, it } from "vitest";
+import { DEFAULT_CONTENT_MAX_WIDTH } from "@/styles/theme";
 import {
   clearAssistantMessageHeightEstimateCache,
   estimateAssistantMessageHeightFromCache,
@@ -27,7 +28,21 @@ describe("assistant message height estimate", () => {
       height: 41.1,
     });
 
-    expect(estimateAssistantMessageHeightFromCache("First paragraph\n\nSecond paragraph")).toBe(97);
+    expect(
+      estimateAssistantMessageHeightFromCache(
+        "First paragraph\n\nSecond paragraph",
+        DEFAULT_CONTENT_MAX_WIDTH,
+      ),
+    ).toBe(97);
+  });
+
+  it("reads block heights measured at the configured content width", () => {
+    setAssistantMarkdownBlockHeight({ block: "Wide paragraph", width: 1584, height: 20 });
+
+    expect(estimateAssistantMessageHeightFromCache("Wide paragraph", 1600)).toBe(44);
+    expect(
+      estimateAssistantMessageHeightFromCache("Wide paragraph", DEFAULT_CONTENT_MAX_WIDTH),
+    ).toBeNull();
   });
 
   it("falls back to image metadata when markdown blocks are not measured", () => {
@@ -41,6 +56,7 @@ describe("assistant message height estimate", () => {
     expect(
       estimateAssistantMessageHeightFromCache(
         "Here is the screenshot\n\n![Screenshot](https://example.com/landscape.png)",
+        DEFAULT_CONTENT_MAX_WIDTH,
       ),
     ).toBeGreaterThan(220);
   });

packages/app/src/utils/assistant-message-height-estimate.ts

@@ -1,9 +1,8 @@
-import { MAX_CONTENT_WIDTH } from "@/constants/layout";
 import { estimateAssistantMessageHeightFromCache as estimateAssistantImageMessageHeightFromCache } from "@/utils/assistant-image-metadata";
 import { splitMarkdownBlocks } from "@/utils/split-markdown-blocks";
 
 const ASSISTANT_MARKDOWN_BLOCK_HEIGHT_CACHE_LIMIT = 1000;
-const ASSISTANT_MARKDOWN_BLOCK_ESTIMATE_WIDTH = MAX_CONTENT_WIDTH - 16;
+const ASSISTANT_MARKDOWN_BLOCK_INSET = 16;
 const ASSISTANT_MESSAGE_VERTICAL_PADDING = 24;
 const ASSISTANT_MARKDOWN_BLOCK_GAP = 12;
 
@@ -78,7 +77,10 @@ export function setAssistantMarkdownBlockHeight(input: {
   return height;
 }
 
-function estimateAssistantMarkdownBlockHeightFromCache(markdown: string): number | null {
+function estimateAssistantMarkdownBlockHeightFromCache(
+  markdown: string,
+  contentMaxWidth: number,
+): number | null {
   const blocks = splitMarkdownBlocks(markdown);
   if (blocks.length === 0) {
     return null;
@@ -88,7 +90,7 @@ function estimateAssistantMarkdownBlockHeightFromCache(markdown: string): number
   for (const block of blocks) {
     const key = createMarkdownBlockHeightKey({
       block,
-      width: ASSISTANT_MARKDOWN_BLOCK_ESTIMATE_WIDTH,
+      width: contentMaxWidth - ASSISTANT_MARKDOWN_BLOCK_INSET,
     });
     const cachedHeight = key ? assistantMarkdownBlockHeightCache.get(key) : undefined;
     if (cachedHeight === undefined) {
@@ -104,10 +106,13 @@ function estimateAssistantMarkdownBlockHeightFromCache(markdown: string): number
   );
 }
 
-export function estimateAssistantMessageHeightFromCache(markdown: string): number | null {
+export function estimateAssistantMessageHeightFromCache(
+  markdown: string,
+  contentMaxWidth: number,
+): number | null {
   return (
-    estimateAssistantMarkdownBlockHeightFromCache(markdown) ??
-    estimateAssistantImageMessageHeightFromCache(markdown)
+    estimateAssistantMarkdownBlockHeightFromCache(markdown, contentMaxWidth) ??
+    estimateAssistantImageMessageHeightFromCache(markdown, contentMaxWidth)
   );
 }
 

packages/cli/src/commands/agent/open.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander";
 import { connectToDaemon } from "../../utils/client.js";
+import type { AgentDeepLinkTarget } from "@getpaseo/protocol/agent-deep-link";
 import { openDesktopWithAgent } from "../open.js";
 import type {
   CommandError,
@@ -30,10 +31,21 @@ export function addOpenOptions(command: Command): Command {
     .option("--server <server-id>", "Server ID (defaults to the local daemon)");
 }
 
-async function resolveServerId(options: CommandOptions): Promise<string> {
+function toOpenError(err: unknown): CommandError {
+  if (err && typeof err === "object" && "code" in err) {
+    return err as CommandError;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return { code: "OPEN_FAILED", message: `Failed to open agent: ${message}` };
+}
+
+async function resolveAgentTarget(
+  agentId: string,
+  options: CommandOptions,
+): Promise<AgentDeepLinkTarget> {
   const explicitServerId = typeof options.server === "string" ? options.server.trim() : "";
   if (explicitServerId) {
-    return explicitServerId;
+    return { serverId: explicitServerId, agentId };
   }
 
   const client = await connectToDaemon({ target: options.daemonTarget });
@@ -46,7 +58,19 @@ async function resolveServerId(options: CommandOptions): Promise<string> {
       };
       throw error;
     }
-    return serverId;
+
+    const fetchResult = await client.fetchAgent({ agentId });
+    if (!fetchResult) {
+      const error: CommandError = {
+        code: "AGENT_NOT_FOUND",
+        message: `Agent not found: ${agentId}`,
+        details: 'Use "paseo ls" to list available agents',
+      };
+      throw error;
+    }
+    return { serverId, agentId: fetchResult.agent.id };
+  } catch (err) {
+    throw toOpenError(err);
   } finally {
     await client.close().catch(() => {});
   }
@@ -66,12 +90,12 @@ export async function runOpenCommand(
     throw error;
   }
 
-  const serverId = await resolveServerId(options);
-  await openDesktopWithAgent({ serverId, agentId });
+  const target = await resolveAgentTarget(agentId, options);
+  await openDesktopWithAgent(target);
 
   return {
     type: "single",
-    data: { agentId, serverId, status: "opened" },
+    data: { ...target, status: "opened" },
     schema: openAgentSchema,
   };
 }

packages/cli/tests/42-agent-open.test.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env npx tsx
+
+import assert from "node:assert";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { runPaseoCli, startTestDaemon } from "./helpers/test-daemon.ts";
+
+console.log("=== Agent Open Command Tests ===\n");
+
+if (process.platform !== "linux") {
+  console.log("Skipped: the fake Desktop app is a Linux AppImage path.");
+  process.exit(0);
+}
+
+const daemon = await startTestDaemon();
+
+// runPaseoCli sets HOME to the daemon's home, where the CLI looks for
+// ~/Applications/Paseo.AppImage on Linux. The fake app records its launch.
+const launchRecord = join(daemon.paseoHome, "desktop-launches.txt");
+const fakeDesktop = join(daemon.paseoHome, "Applications", "Paseo.AppImage");
+await mkdir(join(daemon.paseoHome, "Applications"), { recursive: true });
+await writeFile(fakeDesktop, `#!/bin/sh\necho "$@" >> "${launchRecord}"\n`);
+await chmod(fakeDesktop, 0o755);
+
+try {
+  {
+    console.log("Test 1: an unknown agent ID fails without opening Desktop");
+    const result = await runPaseoCli(daemon, [
+      "agent",
+      "open",
+      "does-not-exist",
+      "--host",
+      `127.0.0.1:${daemon.port}`,
+      "--json",
+    ]);
+
+    assert.notStrictEqual(result.exitCode, 0, "open should fail for an unknown agent");
+    assert.match(JSON.parse(result.stderr).error.message, /Agent not found: does-not-exist/);
+    // Give a wrongly spawned detached app time to write its record.
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    assert.ok(
+      !existsSync(launchRecord),
+      `Desktop should not open, but was launched with: ${existsSync(launchRecord) ? await readFile(launchRecord, "utf8") : ""}`,
+    );
+    console.log("✓ unknown agent ID fails without opening Desktop\n");
+  }
+} finally {
+  await daemon.stop();
+}
+
+console.log("=== All agent open tests passed ===");

packages/desktop/src/daemon/daemon-manager.test.ts

@@ -125,6 +125,36 @@ describe("daemon-manager commands", () => {
     });
   });
 
+  it("reports a stopped daemon without launching the CLI when no local daemon runs", async () => {
+    mkdirSync(mocks.paseoHome);
+    writeFileSync(path.join(mocks.paseoHome, "server-id"), "srv_existing\n");
+    mocks.runExternalCliJsonCommand.mockResolvedValue({
+      home: mocks.paseoHome,
+      pid: null,
+      startedAt: null,
+      listen: null,
+      hostname: null,
+      localDaemon: "stopped",
+      desktopManaged: false,
+      connectedDaemon: "not_probed",
+    });
+
+    const status = await createDaemonCommandHandlers().desktop_daemon_status();
+
+    expect(status).toMatchObject({ serverId: "", status: "stopped", pid: null });
+    expect(mocks.runExternalCliJsonCommand).not.toHaveBeenCalled();
+  });
+
+  it("reports an errored daemon when the local daemon state cannot be read", async () => {
+    mkdirSync(mocks.paseoHome);
+    writeFileSync(path.join(mocks.paseoHome, "paseo.pid"), "garbage");
+
+    const status = await createDaemonCommandHandlers().desktop_daemon_status();
+
+    expect(status).toMatchObject({ serverId: "", status: "errored", pid: null });
+    expect(status.error).toBeTruthy();
+  });
+
   it("returns a local credential only for its live managed daemon listen", async () => {
     mkdirSync(mocks.paseoHome);
     const token = "a".repeat(43);

packages/desktop/src/daemon/daemon-manager.ts

@@ -224,6 +224,12 @@ export async function resolveDesktopDaemonStatus(): Promise<DesktopDaemonStatus>
   const home = getPaseoHome();
 
   try {
+    // The app polls this while no local daemon runs. Answer that case in-process,
+    // since launching the CLI once per poll keeps spawning processes while idle.
+    if (!(await readDaemonInstance(home))) {
+      return statusFromDaemonProbe({ localDaemon: "stopped" }, home);
+    }
+
     const payload = (await runExternalCliJsonCommand([
       "daemon",
       "status",
@@ -234,7 +240,7 @@ export async function resolveDesktopDaemonStatus(): Promise<DesktopDaemonStatus>
     return statusFromDaemonProbe(payload, home);
   } catch (error) {
     const errorMessage = error instanceof Error ? error.message : String(error);
-    logDesktopDaemonLifecycle("resolveStatus CLI command failed", { error: errorMessage });
+    logDesktopDaemonLifecycle("resolveStatus failed", { error: errorMessage });
     return {
       serverId: "",
       status: "errored",

packages/desktop/src/features/browser-capture.test.ts

@@ -29,7 +29,7 @@ function harness(guest: BrowserCaptureGuest | null = null) {
 describe("browser capture service", () => {
   it("validates and rounds guest-relative bounds before capture", async () => {
     const capturePage = vi.fn(async () => image());
-    const { service } = harness({ isDestroyed: () => false, capturePage });
+    const { service } = harness({ isDestroyed: () => false, getZoomFactor: () => 1, capturePage });
 
     await expect(
       service.capture({
@@ -41,9 +41,25 @@ describe("browser capture service", () => {
     expect(capturePage).toHaveBeenCalledWith({ x: 0, y: 9, width: 20, height: 11 });
   });
 
+  it("captures the selected element when the page is zoomed", async () => {
+    const capturePage = vi.fn(async () => image());
+    const { service } = harness({
+      isDestroyed: () => false,
+      getZoomFactor: () => 1.2,
+      capturePage,
+    });
+
+    await service.capture({
+      browserId: "browser-1",
+      hostWebContentsId: 42,
+      rect: { x: 300, y: 200, width: 120, height: 60 },
+    });
+    expect(capturePage).toHaveBeenCalledWith({ x: 360, y: 240, width: 144, height: 72 });
+  });
+
   it("rejects invalid or unavailable captures without touching the guest", async () => {
     const capturePage = vi.fn(async () => image());
-    const { service } = harness({ isDestroyed: () => false, capturePage });
+    const { service } = harness({ isDestroyed: () => false, getZoomFactor: () => 1, capturePage });
 
     await expect(
       service.capture({ browserId: "browser-1", hostWebContentsId: 42, rect: { width: 0 } }),

packages/desktop/src/features/browser-capture.ts

@@ -5,6 +5,7 @@ export interface BrowserCaptureImage {
 
 export interface BrowserCaptureGuest<TImage extends BrowserCaptureImage = BrowserCaptureImage> {
   isDestroyed(): boolean;
+  getZoomFactor(): number;
   capturePage(rect: BrowserCaptureRect): Promise<TImage>;
 }
 
@@ -40,7 +41,9 @@ export interface BrowserCaptureService {
   copy(payload: unknown): Promise<boolean>;
 }
 
-function captureRect(value: unknown): BrowserCaptureRect | null {
+// The renderer measures the element in page CSS pixels, while capturePage
+// takes device-independent pixels, so the page zoom scales the region.
+function captureRect(value: unknown, zoomFactor: number): BrowserCaptureRect | null {
   if (!value || typeof value !== "object") return null;
   const record = value as Record<string, unknown>;
   const coordinates = [record.x, record.y, record.width, record.height];
@@ -51,7 +54,9 @@ function captureRect(value: unknown): BrowserCaptureRect | null {
   ) {
     return null;
   }
-  const [x, y, width, height] = coordinates as number[];
+  const [x, y, width, height] = (coordinates as number[]).map(
+    (coordinate) => coordinate * zoomFactor,
+  );
   if (width <= 0 || height <= 0) return null;
   return {
     x: Math.max(0, Math.round(x)),
@@ -80,8 +85,9 @@ export function createBrowserCaptureService<TImage extends BrowserCaptureImage>(
     async capture({ browserId, hostWebContentsId, rect }) {
       if (typeof browserId !== "string" || browserId.trim().length === 0) return null;
       const guest = dependencies.findGuest(browserId, hostWebContentsId);
-      const bounds = captureRect(rect);
-      if (!guest || guest.isDestroyed() || !bounds) return null;
+      if (!guest || guest.isDestroyed()) return null;
+      const bounds = captureRect(rect, guest.getZoomFactor());
+      if (!bounds) return null;
       try {
         const image = await guest.capturePage(bounds);
         return image.isEmpty() ? null : image.toDataURL();

packages/protocol/src/agent-feature-schemas.test.ts

@@ -49,6 +49,22 @@ describe("agent feature schemas", () => {
     expect(parsed.value).toBe("flex");
   });
 
+  it.each(["icon", "label"])(
+    "preserves the %s desktop trigger for any select feature",
+    (desktopTrigger) => {
+      const feature = {
+        type: "select",
+        id: "custom-feature",
+        label: "Custom setting",
+        icon: "gauge",
+        value: "first",
+        options: [{ id: "first", label: "First" }],
+        desktopTrigger,
+      };
+      expect(AgentFeatureSchema.parse(feature)).toEqual(feature);
+    },
+  );
+
   it("rejects invalid features", () => {
     const invalidDiscriminator = AgentFeatureSchema.safeParse({
       type: "slider",

packages/protocol/src/agent-types.ts

@@ -145,6 +145,8 @@ export interface AgentFeatureSelect {
   description?: string;
   tooltip?: string;
   icon?: string;
+  /** Desktop toolbar presentation; omitted means labeled. Mobile selectors stay labeled. */
+  desktopTrigger?: "icon" | "label";
   value: string | null;
   options: AgentSelectOption[];
 }

packages/protocol/src/messages.ts

@@ -301,6 +301,7 @@ export const AgentFeatureSelectSchema = z.object({
   description: z.string().optional(),
   tooltip: z.string().optional(),
   icon: z.string().optional(),
+  desktopTrigger: z.enum(["icon", "label"]).optional(),
   value: z.string().nullable(),
   options: z.array(AgentSelectOptionSchema),
 });

packages/server/src/server/agent/agent-manager.ts

@@ -50,7 +50,6 @@ import {
   type AgentTimelineItem,
   type AgentUsage,
   type AgentRuntimeInfo,
-  type UsageReference,
   type ImportedTimelineEntry,
   type ImportableProviderSession,
   type ListImportableSessionsOptions,
@@ -1168,24 +1167,6 @@ export class AgentManager {
     return agent ? { ...agent } : null;
   }
 
-  async resolveUsageReference(
-    id: string,
-  ): Promise<{ found: boolean; reference: UsageReference | null }> {
-    const agent = this.getAgent(id);
-    const stored = agent?.session ? null : await this.registry?.get(id);
-    const source = stored ?? agent;
-    if (!source) return { found: false, reference: null };
-    const config = stored ? buildStoredAgentConfig(stored) : agent!.config;
-    const reference =
-      (await this.clients.get(source.provider)?.resolveUsageReference?.({
-        config,
-        runtimeInfo: source.runtimeInfo ?? null,
-        persistence: source.persistence ?? null,
-        session: agent?.session ?? null,
-      })) ?? null;
-    return { found: true, reference };
-  }
-
   async waitForAgentClose(agentId: string): Promise<void> {
     // Loading during reload must wait for the replacement, not resume another writer.
     await this.lifecycleMutationTails.get(agentId);

packages/server/src/server/agent/agent-sdk-types.ts

@@ -1,4 +1,7 @@
 import type {
+  AgentFeature,
+  AgentFeatureSelect,
+  AgentFeatureToggle,
   AgentProviderNotice,
   AgentTaskItem,
   JsonValue,
@@ -8,7 +11,13 @@ import type {
 import type { AgentAttachment } from "@getpaseo/protocol/messages";
 import type { PaseoToolCatalog } from "./tools/types.js";
 
-export type { AgentProviderNotice, AgentTaskItem };
+export type {
+  AgentFeature,
+  AgentFeatureSelect,
+  AgentFeatureToggle,
+  AgentProviderNotice,
+  AgentTaskItem,
+};
 
 export type AgentProvider = string;
 
@@ -156,29 +165,6 @@ export interface AgentCreateConfigUnattendedInput {
   availableModes: AgentMode[];
 }
 
-export interface AgentFeatureToggle {
-  type: "toggle";
-  id: string;
-  label: string;
-  description?: string;
-  tooltip?: string;
-  icon?: string;
-  value: boolean;
-}
-
-export interface AgentFeatureSelect {
-  type: "select";
-  id: string;
-  label: string;
-  description?: string;
-  tooltip?: string;
-  icon?: string;
-  value: string | null;
-  options: AgentSelectOption[];
-}
-
-export type AgentFeature = AgentFeatureToggle | AgentFeatureSelect;
-
 export interface AgentCapabilityFlags {
   [capability: string]: boolean | undefined;
   supportsStreaming: boolean;
@@ -673,6 +659,8 @@ export interface AgentSession {
   /** New provider-owned rows to commit on registration. streamHistory must also
    * replay them at their original timestamps; restored sessions omit old rows. */
   readonly initialTimeline?: ImportedTimelineEntry[];
+  /** Resolved at fetch time because model and credentials may change during a session. */
+  getUsageReference?(): Promise<UsageReference | null>;
   run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
   startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<{ turnId: string }>;
   steerActiveTurn?(prompt: AgentPromptInput, options: SteerActiveTurnOptions): Promise<SteerResult>;
@@ -748,13 +736,6 @@ export interface ResolveAgentDefaultModeInput {
 export interface AgentClient {
   readonly provider: AgentProvider;
   readonly capabilities: AgentCapabilityFlags;
-  /** Account used by the agent. Resolving this must not start or load a session. */
-  resolveUsageReference?(input: {
-    config: AgentSessionConfig;
-    runtimeInfo: AgentRuntimeInfo | null;
-    persistence: AgentPersistenceHandle | null;
-    session: AgentSession | null;
-  }): Promise<UsageReference | null>;
   createSession(
     config: AgentSessionConfig,
     launchContext?: AgentLaunchContext,

packages/server/src/server/agent/plugin-provider.test.ts

@@ -406,12 +406,7 @@ describe("PluginAgentClientRegistry", () => {
       cwd: "/workspace",
     });
     try {
-      expect(
-        await client.resolveUsageReference?.({
-          config: { provider: harness.registration.id, cwd: "/workspace" },
-          session,
-        }),
-      ).toBeNull();
+      expect(await session.getUsageReference?.()).toBeNull();
       expect(harness.inputs.some((input) => input.type === "session.usage_reference")).toBe(false);
     } finally {
       await session.close();

packages/server/src/server/agent/plugin-provider.ts

@@ -897,15 +897,6 @@ class PluginAgentClient implements AgentClient {
     return agentCapabilities(this.runtime.negotiatedCapabilities);
   }
 
-  async resolveUsageReference({
-    session,
-  }: {
-    config: AgentSessionConfig;
-    session: AgentSession | null;
-  }) {
-    return session instanceof PluginAgentSession ? session.getPluginUsageReference() : null;
-  }
-
   async createSession(
     config: AgentSessionConfig,
     launchContext?: AgentLaunchContext,
@@ -1105,7 +1096,7 @@ class PluginAgentSession implements AgentSession {
     return agentCapabilities(this.bridge.negotiatedCapabilities);
   }
 
-  getPluginUsageReference(): Promise<UsageReference | null> {
+  getUsageReference(): Promise<UsageReference | null> {
     return this.bridge.getUsageReference();
   }
 

packages/server/src/server/agent/provider-registry.ts

@@ -458,6 +458,7 @@ export function wrapSessionProvider(provider: AgentProvider, inner: AgentSession
       }
     },
     getRuntimeInfo: async () => mapRuntimeInfo(provider, await inner.getRuntimeInfo()),
+    getUsageReference: inner.getUsageReference?.bind(inner),
     getAvailableModes: () => inner.getAvailableModes(),
     getCurrentMode: () => inner.getCurrentMode(),
     setMode: (modeId) => inner.setMode(modeId),
@@ -489,28 +490,13 @@ function wrapClientProvider(
   const listFeatures = inner.listFeatures?.bind(inner);
   const archiveNativeSession = inner.archiveNativeSession?.bind(inner);
   const unarchiveNativeSession = inner.unarchiveNativeSession?.bind(inner);
-  // An alias's live session can carry launch env that is fresher than stored config.
-  const sessions = new WeakMap<AgentSession, AgentSession>();
-  const wrapSession = (session: AgentSession) => {
-    const wrapped = wrapSessionProvider(provider, session);
-    sessions.set(wrapped, session);
-    return wrapped;
-  };
 
   return {
     provider,
     capabilities: inner.capabilities,
-    resolveUsageReference: inner.resolveUsageReference
-      ? ({ config, runtimeInfo, persistence, session }) =>
-          inner.resolveUsageReference!({
-            config: { ...config, provider: inner.provider },
-            runtimeInfo,
-            persistence,
-            session: session ? (sessions.get(session) ?? null) : null,
-          })
-      : undefined,
     createSession: async (config, launchContext) =>
-      wrapSession(
+      wrapSessionProvider(
+        provider,
         await inner.createSession(
           {
             ...config,
@@ -520,7 +506,8 @@ function wrapClientProvider(
         ),
       ),
     resumeSession: async (handle, overrides, launchContext, options) =>
-      wrapSession(
+      wrapSessionProvider(
+        provider,
         await inner.resumeSession(
           {
             ...handle,
@@ -582,7 +569,7 @@ function wrapClientProvider(
           }
           return {
             ...imported,
-            session: wrapSession(imported.session),
+            session: wrapSessionProvider(provider, imported.session),
             config: {
               ...imported.config,
               provider,

packages/server/src/server/agent/providers/acp-agent.test.ts

@@ -224,17 +224,8 @@ function createSessionWithConfig(
 
 test("ACP usage reference uses the provider ID", async () => {
   for (const provider of ["copilot", "cursor", "kimi", "custom-source"]) {
-    const client = new ACPAgentClient({
-      provider,
-      logger: createTestLogger(),
-      defaultCommand: ["unused"],
-    });
-    expect(
-      await client.resolveUsageReference({
-        config: { provider, cwd: "/tmp/paseo-acp-test" },
-        session: null,
-      }),
-    ).toEqual({ source: provider, input: {} });
+    const session = createSessionWithConfig({ provider });
+    expect(await session.getUsageReference()).toEqual({ source: provider, input: {} });
   }
 });
 

packages/server/src/server/agent/providers/acp-agent.ts

@@ -882,9 +882,6 @@ function isACPCreateConfigUnattended(input: AgentCreateConfigUnattendedInput): b
 export class ACPAgentClient implements AgentClient {
   readonly provider: string;
   readonly capabilities: AgentCapabilityFlags;
-  async resolveUsageReference() {
-    return { source: this.provider, input: {} };
-  }
   readonly resolveCreateConfig = resolveACPCreateConfig;
   readonly isCreateConfigUnattended = isACPCreateConfigUnattended;
 
@@ -1636,6 +1633,10 @@ export class ACPAgentSession implements AgentSession, ACPClient {
   readonly provider: string;
   readonly capabilities: AgentCapabilityFlags;
 
+  async getUsageReference() {
+    return { source: this.provider, input: {} };
+  }
+
   private readonly logger: Logger;
   private readonly runtimeSettings?: ProviderRuntimeSettings;
   private readonly defaultCommand: [string, ...string[]];

packages/server/src/server/agent/providers/claude/agent.test.ts

@@ -531,16 +531,16 @@ describe("ClaudeAgentClient binary resolution", () => {
   const logger = createTestLogger();
 
   test("Claude usage reference follows CLAUDE_CONFIG_DIR and excludes API overrides", async () => {
-    const config = { provider: "claude", cwd: process.cwd() };
-    const client = new ClaudeAgentClient({
-      logger,
-      runtimeSettings: { env: { CLAUDE_CONFIG_DIR: "/accounts/second" } },
-      resolveBinary: async () => "/test/claude/bin",
-    });
-    expect(await client.resolveUsageReference?.({ config, session: null })).toEqual({
+    const client = new ClaudeAgentClient({ logger, resolveBinary: async () => "/test/claude/bin" });
+    const session = await client.createSession(
+      { provider: "claude", cwd: process.cwd() },
+      { env: { CLAUDE_CONFIG_DIR: "/accounts/second" } },
+    );
+    expect(await session.getUsageReference?.()).toEqual({
       source: "claude",
       input: { configDir: "/accounts/second" },
     });
+    await session.close();
   });
 
   test.each(["ANTHROPIC_BASE_URL", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"])(
@@ -548,15 +548,14 @@ describe("ClaudeAgentClient binary resolution", () => {
     async (name) => {
       const client = new ClaudeAgentClient({
         logger,
-        runtimeSettings: { env: { [name]: "override" } },
         resolveBinary: async () => "/test/claude/bin",
       });
-      expect(
-        await client.resolveUsageReference?.({
-          config: { provider: "claude", cwd: process.cwd() },
-          session: null,
-        }),
-      ).toBeNull();
+      const session = await client.createSession(
+        { provider: "claude", cwd: process.cwd() },
+        { env: { [name]: "override" } },
+      );
+      expect(await session.getUsageReference?.()).toBeNull();
+      await session.close();
     },
   );
 
@@ -570,16 +569,15 @@ describe("ClaudeAgentClient binary resolution", () => {
         },
       },
     });
-    const client = registry["work-claude"].createClient(logger);
-    expect(
-      await client.resolveUsageReference?.({
-        config: { provider: "work-claude", cwd: process.cwd() },
-        session: null,
-      }),
-    ).toEqual({
+    const session = await registry["work-claude"].createClient(logger).createSession({
+      provider: "work-claude",
+      cwd: process.cwd(),
+    });
+    expect(await session.getUsageReference?.()).toEqual({
       source: "claude",
       input: { configDir: "/accounts/work" },
     });
+    await session.close();
   });
 
   test("resolves the installed Claude Code version", async () => {

packages/server/src/server/agent/providers/claude/agent.ts

@@ -1519,15 +1519,6 @@ export class ClaudeAgentClient implements AgentClient {
     this.rewindSdk = options.rewindSdk ?? realClaudeRewindSdk;
   }
 
-  async resolveUsageReference() {
-    const env = createProviderEnv({ baseEnv: process.env, runtimeSettings: this.runtimeSettings });
-    if (env.ANTHROPIC_BASE_URL || env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN) return null;
-    return {
-      source: "claude",
-      input: { configDir: env.CLAUDE_CONFIG_DIR || path.join(env.HOME || homedir(), ".claude") },
-    };
-  }
-
   resolveConfiguredModel(model: AgentModelDefinition): AgentModelDefinition {
     return resolveConfiguredClaudeModel(model);
   }
@@ -2051,6 +2042,15 @@ class ClaudeAgentSession implements AgentSession {
   readonly provider = "claude" as const;
   readonly capabilities = CLAUDE_CAPABILITIES;
 
+  async getUsageReference() {
+    const env = this.buildSdkEnv();
+    if (env.ANTHROPIC_BASE_URL || env.ANTHROPIC_API_KEY || env.ANTHROPIC_AUTH_TOKEN) return null;
+    return {
+      source: "claude",
+      input: { configDir: env.CLAUDE_CONFIG_DIR || path.join(env.HOME || homedir(), ".claude") },
+    };
+  }
+
   private readonly config: ClaudeAgentConfig;
   private readonly launchEnv?: Record<string, string>;
   private readonly agentId?: string;

packages/server/src/server/agent/providers/codex-app-server-agent.features.test.ts

@@ -19,6 +19,41 @@ interface CollaborationModeRecord {
   developer_instructions?: string | null;
 }
 
+const TEST_SPEED_MODELS = [
+  "gpt-6-astra",
+  "gpt-6.1-sol",
+  "gpt-6-sol",
+  "gpt-6-luna",
+  "gpt-5.6",
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
+  "gpt-5.5",
+  "gpt-5.4",
+].map((id) => ({
+  id,
+  isDefault: id === "gpt-5.4",
+  defaultReasoningEffort: "medium",
+  serviceTiers: [{ id: "priority", name: "Fast", description: "Faster processing" }],
+}));
+
+function speedFeature(value: string) {
+  return {
+    type: "select",
+    id: "service_tier",
+    label: "Speed",
+    description: "Choose processing speed. Faster tiers increase usage.",
+    tooltip: "Select speed",
+    icon: "zap",
+    desktopTrigger: "icon",
+    value,
+    options: [
+      { id: "default", label: "Normal", isDefault: true },
+      { id: "priority", label: "Fast" },
+    ],
+  };
+}
+
 const TEST_COLLABORATION_MODES: CollaborationModeRecord[] = [
   {
     name: "Code",
@@ -65,7 +100,7 @@ function createConfig(overrides: Partial<AgentSessionConfig> = {}): AgentSession
 
 function createSessionHarness(
   configOverrides: Partial<AgentSessionConfig> = {},
-  options: { logger?: pino.Logger } = {},
+  options: { logger?: pino.Logger; models?: unknown[] } = {},
 ): {
   session: CodexFeaturesTestSession;
   appServer: FakeCodexAppServer;
@@ -73,6 +108,7 @@ function createSessionHarness(
   const config = createConfig(configOverrides);
   const appServer = createFakeCodexAppServer({
     "collaborationMode/list": () => ({ data: TEST_COLLABORATION_MODES }),
+    "model/list": () => ({ data: options.models ?? TEST_SPEED_MODELS }),
   });
   const session = new CodexAppServerAgentSession(
     { ...config, provider: CODEX_PROVIDER },
@@ -85,7 +121,7 @@ function createSessionHarness(
 
 async function createConnectedSession(
   configOverrides: Partial<AgentSessionConfig> = {},
-  options: { logger?: pino.Logger } = {},
+  options: { logger?: pino.Logger; models?: unknown[] } = {},
 ): Promise<{
   session: CodexFeaturesTestSession;
   appServer: FakeCodexAppServer;
@@ -97,8 +133,169 @@ async function createConnectedSession(
 }
 
 describe("Codex app-server provider features", () => {
+  test("GPT-6.1 Sol offers catalog speed tiers and sends Ultrafast", async () => {
+    const { session, appServer } = await createConnectedSession(
+      { model: "gpt-6.1-sol" },
+      {
+        models: [
+          {
+            id: "gpt-6.1-sol",
+            serviceTiers: [
+              { id: "priority", name: "Fast", description: "Faster processing" },
+              { id: "ultrafast", name: "Ultrafast", description: "Lowest latency" },
+            ],
+          },
+        ],
+      },
+    );
+    try {
+      expect(session.features).toContainEqual(
+        expect.objectContaining({
+          id: "service_tier",
+          type: "select",
+          value: "default",
+          options: [
+            { id: "default", label: "Normal", isDefault: true },
+            { id: "priority", label: "Fast" },
+            { id: "ultrafast", label: "Ultrafast" },
+          ],
+        }),
+      );
+      await session.setFeature?.("service_tier", "ultrafast");
+      await session.startTurn("hello");
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+        serviceTier: "ultrafast",
+      });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("new models and service tiers work without a Paseo catalog update", async () => {
+    const { session, appServer } = await createConnectedSession(
+      { model: "future-codex-model" },
+      {
+        models: [
+          {
+            id: "future-codex-model",
+            serviceTiers: [
+              { id: "future-tier", name: "Future speed", description: "A newly advertised tier" },
+            ],
+          },
+        ],
+      },
+    );
+    try {
+      expect(session.features).toContainEqual(
+        expect.objectContaining({
+          id: "service_tier",
+          options: [
+            { id: "default", label: "Normal", isDefault: true },
+            { id: "future-tier", label: "Future speed" },
+          ],
+        }),
+      );
+      await session.setFeature?.("service_tier", "future-tier");
+      await session.startTurn("hello");
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+        model: "future-codex-model",
+        serviceTier: "future-tier",
+      });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test.each(["priority", "ultrafast"])(
+    "restores %s and Normal explicitly overrides an existing thread tier",
+    async (tier) => {
+      const { session, appServer } = await createConnectedSession(
+        { model: "future-model", featureValues: { service_tier: tier } },
+        {
+          models: [
+            {
+              id: "future-model",
+              serviceTiers: [
+                { id: "priority", name: "Fast", description: "Fast processing" },
+                { id: "ultrafast", name: "Ultrafast", description: "Ultra processing" },
+              ],
+            },
+          ],
+        },
+      );
+      try {
+        expect(session.features).toContainEqual(
+          expect.objectContaining({ id: "service_tier", value: tier }),
+        );
+        await session.getRuntimeInfo();
+        await session.setFeature?.("service_tier", "default");
+        await session.startTurn("hello");
+        await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+          serviceTier: "default",
+        });
+      } finally {
+        await session.close();
+      }
+    },
+  );
+
+  test("rejects unadvertised tiers and non-string values", async () => {
+    const { session } = await createConnectedSession();
+    try {
+      for (const value of ["ultrafast", "bogus", true, null]) {
+        await expect(session.setFeature?.("service_tier", value)).rejects.toThrow(
+          "is not available",
+        );
+      }
+      expect(session.features).toContainEqual(
+        expect.objectContaining({ id: "service_tier", value: "default" }),
+      );
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("switching to a model without the selected tier resets speed", async () => {
+    const { session, appServer } = await createConnectedSession(
+      { model: "ultra-model", featureValues: { service_tier: "ultrafast" } },
+      {
+        models: [
+          {
+            id: "ultra-model",
+            serviceTiers: [{ id: "ultrafast", name: "Ultrafast", description: "Ultra processing" }],
+          },
+          ...TEST_SPEED_MODELS,
+        ],
+      },
+    );
+    try {
+      await session.setModel("gpt-6.1-sol");
+      expect(session.features).toContainEqual(
+        expect.objectContaining({ id: "service_tier", value: "default" }),
+      );
+      await session.startTurn("hello");
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({ serviceTier: "default" });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("maps legacy Fast commands to the catalog's request id", async () => {
+    const { session, appServer } = await createConnectedSession();
+    try {
+      await session.setFeature?.("fast_mode", true);
+      await session.startTurn("hello");
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+        serviceTier: "priority",
+      });
+    } finally {
+      await session.close();
+    }
+  });
+
   test.each([
     "gpt-6-astra",
+    "gpt-6.1-sol",
     "gpt-6-sol",
     "gpt-6-luna",
     "gpt-5.6",
@@ -112,15 +309,15 @@ describe("Codex app-server provider features", () => {
     try {
       expect(session.features).toContainEqual(
         expect.objectContaining({
-          id: "fast_mode",
-          value: false,
+          id: "service_tier",
+          value: "default",
         }),
       );
-      await session.setFeature?.("fast_mode", true);
+      await session.setFeature?.("service_tier", "priority");
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         model,
-        serviceTier: "fast",
+        serviceTier: "priority",
       });
     } finally {
       await session.close();
@@ -149,8 +346,8 @@ describe("Codex app-server provider features", () => {
         `Codex fast mode is not available for model '${model}'`,
       );
       await session.startTurn("hello");
-      await expect(appServer.waitForTurnStart()).resolves.not.toMatchObject({
-        serviceTier: expect.anything(),
+      await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+        serviceTier: "default",
       });
     } finally {
       await session.close();
@@ -165,8 +362,8 @@ describe("Codex app-server provider features", () => {
     try {
       expect(session.features).toContainEqual(
         expect.objectContaining({
-          id: "fast_mode",
-          value: true,
+          id: "service_tier",
+          value: "priority",
         }),
       );
       await session.setModel("gpt-5.6-sol");
@@ -174,26 +371,18 @@ describe("Codex app-server provider features", () => {
       await session.startTurn("hello");
       await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
         model: "gpt-6-astra",
-        serviceTier: "fast",
+        serviceTier: "priority",
       });
     } finally {
       await session.close();
     }
   });
 
-  test("features returns fast and plan toggles when supported", async () => {
+  test("features returns speed selector and plan toggle when supported", async () => {
     const { session } = await createConnectedSession();
 
     expect(session.features).toEqual([
-      {
-        type: "toggle",
-        id: "fast_mode",
-        label: "Fast",
-        description: "Priority inference at increased usage",
-        tooltip: "Toggle fast mode",
-        icon: "zap",
-        value: false,
-      },
+      speedFeature("default"),
       {
         type: "toggle",
         id: "plan_mode",
@@ -205,19 +394,11 @@ describe("Codex app-server provider features", () => {
       },
     ]);
 
-    await session.setFeature?.("fast_mode", true);
+    await session.setFeature?.("service_tier", "priority");
     await session.setFeature?.("plan_mode", true);
 
     expect(session.features).toEqual([
-      {
-        type: "toggle",
-        id: "fast_mode",
-        label: "Fast",
-        description: "Priority inference at increased usage",
-        tooltip: "Toggle fast mode",
-        icon: "zap",
-        value: true,
-      },
+      speedFeature("priority"),
       {
         type: "toggle",
         id: "plan_mode",
@@ -265,23 +446,23 @@ describe("Codex app-server provider features", () => {
     ]);
 
     await session.startTurn("hello");
-    await expect(appServer.waitForTurnStart()).resolves.not.toMatchObject({
-      serviceTier: expect.anything(),
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+      serviceTier: "default",
     });
   });
 
-  test("setFeature('fast_mode', true) sets serviceTier to fast", async () => {
+  test("selecting Fast sends the catalog service tier", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("fast_mode", true);
+    await session.setFeature?.("service_tier", "priority");
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
-      serviceTier: "fast",
+      serviceTier: "priority",
     });
   });
 
-  test("setFeature('fast_mode', false) clears serviceTier to null", async () => {
+  test("legacy Fast off explicitly selects Normal", async () => {
     const { session, appServer } = await createConnectedSession({
       featureValues: { fast_mode: true },
     });
@@ -289,8 +470,8 @@ describe("Codex app-server provider features", () => {
     await session.setFeature?.("fast_mode", false);
     await session.startTurn("hello");
 
-    await expect(appServer.waitForTurnStart()).resolves.not.toMatchObject({
-      serviceTier: expect.anything(),
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+      serviceTier: "default",
     });
   });
 
@@ -330,15 +511,7 @@ describe("Codex app-server provider features", () => {
     });
 
     expect(session.features).toEqual([
-      {
-        type: "toggle",
-        id: "fast_mode",
-        label: "Fast",
-        description: "Priority inference at increased usage",
-        tooltip: "Toggle fast mode",
-        icon: "zap",
-        value: true,
-      },
+      speedFeature("priority"),
       {
         type: "toggle",
         id: "plan_mode",
@@ -352,7 +525,7 @@ describe("Codex app-server provider features", () => {
 
     await session.startTurn("hello");
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
-      serviceTier: "fast",
+      serviceTier: "priority",
       collaborationMode: expect.objectContaining({
         mode: "plan",
       }),
@@ -362,11 +535,11 @@ describe("Codex app-server provider features", () => {
   test("startTurn includes serviceTier when fast mode is enabled", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("fast_mode", true);
+    await session.setFeature?.("service_tier", "priority");
     await session.startTurn("hello");
 
     await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
-      serviceTier: "fast",
+      serviceTier: "priority",
     });
   });
 
@@ -388,7 +561,7 @@ describe("Codex app-server provider features", () => {
       msg: "Starting Codex app-server turn",
       model: "gpt-5.4",
       modeId: "auto",
-      serviceTier: "fast",
+      serviceTier: "priority",
       cwd: "/tmp/codex-fast-mode-test",
     });
     expect(JSON.stringify(entry)).not.toContain(prompt);
@@ -397,7 +570,7 @@ describe("Codex app-server provider features", () => {
   test("setModel clears fast mode when switching to an unsupported model", async () => {
     const { session, appServer } = await createConnectedSession();
 
-    await session.setFeature?.("fast_mode", true);
+    await session.setFeature?.("service_tier", "priority");
     await session.setModel("gpt-3.5-turbo");
 
     expect(session.features).toEqual([
@@ -413,8 +586,8 @@ describe("Codex app-server provider features", () => {
     ]);
     await session.startTurn("hello");
 
-    await expect(appServer.waitForTurnStart()).resolves.not.toMatchObject({
-      serviceTier: expect.anything(),
+    await expect(appServer.waitForTurnStart()).resolves.toMatchObject({
+      serviceTier: "default",
     });
   });
 

packages/server/src/server/agent/providers/codex-app-server-agent.test.ts

@@ -172,18 +172,41 @@ function createSession(
 }
 
 test("Codex usage reference follows CODEX_HOME and excludes custom base URLs", async () => {
-  const config = createConfig();
-  const client = new CodexAppServerAgentClient(createTestLogger(), {
-    env: { CODEX_HOME: "/accounts/second" },
-  });
-  expect(await client.resolveUsageReference({ config, session: null })).toEqual({
+  const session = new CodexAppServerAgentSession(
+    createConfig(),
+    null,
+    createTestLogger(),
+    () => {
+      throw new Error("unused");
+    },
+    {},
+    false,
+    false,
+    false,
+    undefined,
+    "interactive",
+    { CODEX_HOME: "/accounts/second" },
+  );
+  expect(await session.getUsageReference()).toEqual({
     source: "codex",
     input: { codexHome: "/accounts/second" },
   });
-  const custom = new CodexAppServerAgentClient(createTestLogger(), {
-    env: { CODEX_HOME: "/accounts/second", OPENAI_BASE_URL: "https://example.test" },
-  });
-  expect(await custom.resolveUsageReference({ config, session: null })).toBeNull();
+  const custom = new CodexAppServerAgentSession(
+    createConfig(),
+    null,
+    createTestLogger(),
+    () => {
+      throw new Error("unused");
+    },
+    {},
+    false,
+    false,
+    false,
+    undefined,
+    "interactive",
+    { CODEX_HOME: "/accounts/second", OPENAI_BASE_URL: "https://example.test" },
+  );
+  expect(await custom.getUsageReference()).toBeNull();
 });
 
 function createProviderWithFakeAppServer(
@@ -637,6 +660,7 @@ async function withCustomCodexProviderHome<T>(
     session: AgentSession;
     readCaptured: () => CapturedFakeCodexRecord[];
   }) => Promise<T>,
+  providerPrompts: Record<string, string> = {},
 ): Promise<T> {
   const tempDir = await mkdtemp(path.join(tmpdir(), "codex-provider-home-"));
   const daemonCodexHome = path.join(tempDir, "daemon-codex-home");
@@ -653,6 +677,9 @@ async function withCustomCodexProviderHome<T>(
     path.join(providerCodexHome, "prompts", "probe-profile.md"),
     "---\ndescription: Provider home prompt\n---\nfrom the provider home\n",
   );
+  for (const [name, content] of Object.entries(providerPrompts)) {
+    writeFileSync(path.join(providerCodexHome, "prompts", `${name}.md`), content);
+  }
   writeFileSync(
     fakeAppServerPath,
     `
@@ -730,11 +757,21 @@ async function listPromptCommandsFromCustomCodexHome(): Promise<string[]> {
   });
 }
 
-async function runPromptFromCustomCodexHome(prompt: string): Promise<CapturedFakeCodexRecord[]> {
+async function runPromptFromCustomCodexHome(
+  prompt: string,
+  providerPrompts: Record<string, string> = {},
+): Promise<CapturedFakeCodexRecord[]> {
   return withCustomCodexProviderHome(async ({ session, readCaptured }) => {
     await session.startTurn(prompt);
     return readCaptured();
-  });
+  }, providerPrompts);
+}
+
+async function expandCustomPrompt(template: string, args: string): Promise<string> {
+  const records = await runPromptFromCustomCodexHome(`/prompts:template ${args}`, { template });
+  const turnStart = records.find((record) => record.method === "turn/start");
+  const params = turnStart?.params as { input: Array<{ text: string }> };
+  return params.input[0].text;
 }
 
 function capturedThreadStartConfig(records: CapturedFakeCodexRecord[]): unknown {
@@ -767,6 +804,7 @@ let buffer = "";
 function resultFor(method, params) {
   if (method === "initialize") return {};
   if (method === "collaborationMode/list") return { data: [] };
+  if (method === "model/list") return { data: [] };
   if (method === "skills/list") {
     const cwds = params && params.cwds;
     const projectCwd = ${JSON.stringify(projectCwd)};
@@ -1133,6 +1171,36 @@ describe("Codex app-server provider", () => {
     }
   });
 
+  test("keeps the default effort when a session without one is resumed after a restart", async () => {
+    const beforeRestart = createFakeCodexAppServer();
+    const firstSession = await createProviderWithFakeAppServer(beforeRestart).createSession(
+      createConfig({ thinkingOptionId: undefined }),
+    );
+    await firstSession.startTurn("first turn");
+    await expect(beforeRestart.waitForTurnStart()).resolves.toMatchObject({ effort: "medium" });
+    const handle = firstSession.describePersistence()!;
+    await firstSession.close();
+
+    const afterRestart = createFakeCodexAppServer();
+    // The daemon resumes with the stored agent config, which never recorded an effort.
+    const resumed = await createProviderWithFakeAppServer(afterRestart).resumeSession(handle, {
+      model: "gpt-5.4",
+      thinkingOptionId: undefined,
+    });
+
+    try {
+      await expect(resumed.getRuntimeInfo()).resolves.toMatchObject({
+        thinkingOptionId: "medium",
+      });
+      await resumed.startTurn("turn after restart");
+      await expect(afterRestart.waitForTurnStart()).resolves.toMatchObject({ effort: "medium" });
+      beforeRestart.assertNoErrors();
+      afterRestart.assertNoErrors();
+    } finally {
+      await resumed.close();
+    }
+  });
+
   test("preapproves only granted tools on the injected Codex MCP server", async () => {
     const session = createSession({
       modeId: undefined,
@@ -1897,6 +1965,66 @@ describe("Codex app-server provider", () => {
     await session.close();
   });
 
+  test("rewinds a legacy conversation with a bounded fork on Codex without thread/rollback", async () => {
+    const appServer = createFakeCodexAppServer({
+      initialize: () => ({ userAgent: "paseo/0.159.0 (Ubuntu 26.4.0; x86_64) (paseo; 0)" }),
+      "thread/read": () => ({
+        thread: { id: "thread-1", historyMode: "legacy", turns: [] },
+      }),
+      "thread/rollback": () => ({
+        __jsonRpcError: {
+          code: -32600,
+          message: "Invalid request: unknown variant `thread/rollback`",
+        },
+      }),
+    });
+    const session = new CodexAppServerAgentSession(
+      createConfig({ cwd: "/workspace/project" }),
+      null,
+      createTestLogger(),
+      async () => appServer.child,
+    );
+
+    await session.startTurn("remember first");
+    emitCodexUserMessage(appServer, {
+      id: "codex-first",
+      text: "remember first",
+      turnId: "turn-first",
+    });
+    appServer.completeTurn();
+    await session.startTurn("remember second");
+    emitCodexUserMessage(appServer, {
+      id: "codex-second",
+      text: "remember second",
+      turnId: "turn-second",
+    });
+    appServer.completeTurn();
+
+    await session.revertConversation({ messageId: "codex-second" });
+
+    const forkRequests = appServer
+      .requests()
+      .filter((request) => request.method === "thread/fork")
+      .map((request) => request.params);
+    expect(forkRequests).toEqual([
+      {
+        threadId: "thread-1",
+        beforeTurnId: "turn-second",
+        cwd: "/workspace/project",
+        model: "gpt-5.4",
+        serviceTier: null,
+        excludeTurns: false,
+        persistExtendedHistory: true,
+      },
+    ]);
+    expect(appServer.recordedRollbacks).toEqual([]);
+    await expect(session.getRuntimeInfo()).resolves.toMatchObject({
+      sessionId: "forked-thread",
+    });
+    appServer.assertNoErrors();
+    await session.close();
+  });
+
   test("rewinds a paginated conversation through the public session capability", async () => {
     const appServer = createFakeCodexAppServer({
       "thread/read": () => ({
@@ -2162,7 +2290,12 @@ describe("Codex app-server provider", () => {
       throw new Error(`resumeSession timed out; thread requests: ${threadRequests.join(", ")}`);
     }
 
-    expect(threadRequests).toEqual(["config/read", "thread/loaded/list", "thread/resume"]);
+    expect(threadRequests).toEqual([
+      "model/list",
+      "config/read",
+      "thread/loaded/list",
+      "thread/resume",
+    ]);
     expect(outcome).toBe("rejected");
     appServer.assertNoErrors();
   });
@@ -2336,6 +2469,71 @@ describe("Codex app-server provider", () => {
     });
   });
 
+  test("keeps an output field named properties as a field", () => {
+    const input = {
+      type: "object",
+      properties: { properties: { type: "string" } },
+      required: ["properties"],
+      additionalProperties: false,
+    };
+
+    expect(normalizeCodexOutputSchema(input)).toEqual(input);
+  });
+
+  test("normalizes schemas under keywords and leaves literal values alone", () => {
+    const literal = { type: "object", properties: { type: "string" } };
+    const input = {
+      type: "object",
+      properties: {
+        result: { $ref: "#/$defs/result" },
+        choice: { anyOf: [{ type: "object", properties: { id: { type: "string" } } }] },
+      },
+      $defs: {
+        properties: { type: "string" },
+        result: {
+          type: "object",
+          properties: { value: { type: "string" } },
+          default: literal,
+          examples: [literal],
+          enum: [literal],
+          const: literal,
+        },
+      },
+    };
+
+    expect(normalizeCodexOutputSchema(input)).toEqual({
+      type: "object",
+      properties: {
+        result: { $ref: "#/$defs/result" },
+        choice: {
+          anyOf: [
+            {
+              type: "object",
+              properties: { id: { type: "string" } },
+              required: ["id"],
+              additionalProperties: false,
+            },
+          ],
+        },
+      },
+      required: ["result", "choice"],
+      additionalProperties: false,
+      $defs: {
+        properties: { type: "string" },
+        result: {
+          type: "object",
+          properties: { value: { type: "string" } },
+          default: literal,
+          examples: [literal],
+          enum: [literal],
+          const: literal,
+          required: ["value"],
+          additionalProperties: false,
+        },
+      },
+    });
+  });
+
   test("passes a normalized output schema to turn/start", async () => {
     const session = createSession();
     const request = vi.fn(async (method: string) => {
@@ -2461,6 +2659,29 @@ describe("Codex app-server provider", () => {
     expect(JSON.stringify(turnStart?.params)).toContain("from the provider home");
   });
 
+  test("inserts custom prompt arguments literally", async () => {
+    await expect(
+      expandCustomPrompt("Implement this exact request: $ARGUMENTS", "Preserve $1 unchanged"),
+    ).resolves.toBe("Implement this exact request: Preserve $1 unchanged");
+    await expect(
+      expandCustomPrompt("Treat this as literal replacement text: $VALUE.", 'VALUE="$&"'),
+    ).resolves.toBe("Treat this as literal replacement text: $&.");
+    await expect(expandCustomPrompt("$1 then $2", '"$2" two')).resolves.toBe("$2 then two");
+    await expect(expandCustomPrompt("$A and $B", 'A="$B" B=b')).resolves.toBe("$B and b");
+    await expect(
+      expandCustomPrompt("$ARGUMENTS", "keep __CODEX_DOLLAR_PLACEHOLDER__ as typed"),
+    ).resolves.toBe("keep __CODEX_DOLLAR_PLACEHOLDER__ as typed");
+  });
+
+  test("expands custom prompt placeholders and escapes", async () => {
+    await expect(
+      expandCustomPrompt("$1/$2 $NAME costs $$5, all: $ARGUMENTS, $MISSING", "one NAME=n two"),
+    ).resolves.toBe("one/two n costs $5, all: one NAME=n two, $MISSING");
+    await expect(
+      expandCustomPrompt("$$ARGUMENTS $$1 $$NAME $9|$NAME_SUFFIX", "first NAME=value"),
+    ).resolves.toBe("$ARGUMENTS $1 $NAME |$NAME_SUFFIX");
+  });
+
   test("deduplicates Codex skill slash commands returned from multiple skill roots", async () => {
     const commands = await listCommandsFromFakeCodex([
       {

packages/server/src/server/agent/providers/codex-app-server-agent.ts

@@ -73,7 +73,12 @@ import {
 import { createPathEquivalenceMatcher } from "../../../utils/path.js";
 import { spawnProcess } from "../../../utils/spawn.js";
 import { extractCodexTerminalSessionId, nonEmptyString } from "./tool-call-mapper-utils.js";
-import { buildCodexFeatures, codexModelSupportsFastMode } from "./codex-feature-definitions.js";
+import {
+  buildCodexFeatures,
+  CodexServiceTierSchema,
+  readCodexServiceTier,
+  type CodexServiceTier,
+} from "./codex-feature-definitions.js";
 import {
   CodexAppServerClient,
   CodexAppServerRpcError,
@@ -169,6 +174,9 @@ const CODEX_PLAN_IMPLEMENTATION_PROMPT_PREFIX =
 // (and the /goal slash command) when the binary is too old.
 const CODEX_GOALS_MIN_VERSION: readonly [number, number, number] = [0, 128, 0];
 const CODEX_AUTO_REVIEW_MIN_VERSION: readonly [number, number, number] = [0, 115, 0];
+// Codex removed `thread/rollback` in 0.156.0, so rewinding a legacy thread there
+// has to fork before the target turn instead.
+const CODEX_THREAD_ROLLBACK_REMOVED_VERSION: readonly [number, number, number] = [0, 156, 0];
 
 function parseCodexVersion(versionOutput: string): [number, number, number] | null {
   const match = versionOutput.match(/(\d+)\.(\d+)\.(\d+)/);
@@ -189,6 +197,15 @@ function codexVersionAtLeast(
   return true;
 }
 
+// The initialize userAgent starts with `<client>/<codex version>`. An agent we
+// cannot parse is treated as an older server that still has rollback.
+function codexServerHasThreadRollback(userAgent: unknown): boolean {
+  return (
+    typeof userAgent !== "string" ||
+    !codexVersionAtLeast(userAgent, CODEX_THREAD_ROLLBACK_REMOVED_VERSION)
+  );
+}
+
 type GoalSubcommand =
   | { kind: "set"; objective: string }
   | { kind: "pause" }
@@ -365,19 +382,67 @@ function isObjectSchemaNode(schema: Record<string, unknown>): boolean {
   );
 }
 
-function normalizeCodexOutputSchemaNode(schema: unknown, schemaPath: string): unknown {
+// Keywords whose value maps names to schemas.
+const SCHEMA_MAP_KEYWORDS = [
+  "properties",
+  "patternProperties",
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+] as const;
+
+// Keywords whose value is a schema or an array of schemas.
+const SUBSCHEMA_KEYWORDS = [
+  "items",
+  "prefixItems",
+  "additionalItems",
+  "contains",
+  "additionalProperties",
+  "unevaluatedProperties",
+  "unevaluatedItems",
+  "propertyNames",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "not",
+  "if",
+  "then",
+  "else",
+] as const;
+
+function normalizeCodexOutputSubschema(schema: unknown, schemaPath: string): unknown {
   if (Array.isArray(schema)) {
     return schema.map((entry, index) =>
       normalizeCodexOutputSchemaNode(entry, `${schemaPath}[${index}]`),
     );
   }
+  return normalizeCodexOutputSchemaNode(schema, schemaPath);
+}
+
+function normalizeCodexOutputSchemaNode(schema: unknown, schemaPath: string): unknown {
   if (!isSchemaRecord(schema)) {
     return schema;
   }
 
-  const normalized: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(schema)) {
-    normalized[key] = normalizeCodexOutputSchemaNode(value, `${schemaPath}.${key}`);
+  const normalized: Record<string, unknown> = { ...schema };
+  for (const keyword of SCHEMA_MAP_KEYWORDS) {
+    const schemas = schema[keyword];
+    if (isSchemaRecord(schemas)) {
+      normalized[keyword] = Object.fromEntries(
+        Object.entries(schemas).map(([name, child]) => [
+          name,
+          normalizeCodexOutputSchemaNode(child, `${schemaPath}.${keyword}.${name}`),
+        ]),
+      );
+    }
+  }
+  for (const keyword of SUBSCHEMA_KEYWORDS) {
+    if (keyword in schema) {
+      normalized[keyword] = normalizeCodexOutputSubschema(
+        schema[keyword],
+        `${schemaPath}.${keyword}`,
+      );
+    }
   }
 
   if (!isObjectSchemaNode(normalized)) {
@@ -786,25 +851,21 @@ function expandCodexCustomPrompt(template: string, args: string | undefined): st
     positional.push(token);
   }
 
-  const dollarPlaceholder = "__CODEX_DOLLAR_PLACEHOLDER__";
-  let out = template.split("$$").join(dollarPlaceholder);
+  // Match every placeholder in one pass, so inserted argument text is never expanded again.
+  const namedPlaceholders = Object.keys(named)
+    .sort((a, b) => b.length - a.length)
+    .map((key) => `${escapeRegExp(key)}\\b`);
+  const placeholder = new RegExp(
+    `\\$(${["\\$", "ARGUMENTS", "[1-9]", ...namedPlaceholders].join("|")})`,
+    "g",
+  );
 
-  out = out.split("$ARGUMENTS").join(trimmedArgs);
-
-  for (let i = 1; i <= 9; i += 1) {
-    const value = positional[i - 1] ?? "";
-    out = out.split(`$${i}`).join(value);
-  }
-
-  const namedKeys = Object.keys(named).sort((a, b) => b.length - a.length);
-  for (const key of namedKeys) {
-    const value = named[key] ?? "";
-    const re = new RegExp(`\\$${escapeRegExp(key)}\\b`, "g");
-    out = out.replace(re, value);
-  }
-
-  out = out.split(dollarPlaceholder).join("$");
-  return out;
+  return template.replace(placeholder, (match, name: string) => {
+    if (name === "$") return "$";
+    if (name === "ARGUMENTS") return trimmedArgs;
+    if (/^[1-9]$/.test(name)) return positional[Number(name) - 1] ?? "";
+    return named[name] ?? match;
+  });
 }
 
 interface CodexMcpServerConfig {
@@ -885,6 +946,7 @@ interface CodexModel {
   model?: string;
   defaultReasoningEffort?: string;
   supportedReasoningEfforts?: CodexReasoningEffortEntry[];
+  serviceTiers?: CodexServiceTier[];
 }
 
 const CodexModelListResponseSchema = z.object({
@@ -892,6 +954,7 @@ const CodexModelListResponseSchema = z.object({
     .array(
       z.object({
         id: z.string(),
+        serviceTiers: z.array(CodexServiceTierSchema).optional(),
         displayName: z.string().optional(),
         description: z.string().optional(),
         isDefault: z.boolean().optional(),
@@ -3377,12 +3440,14 @@ export class CodexAppServerAgentSession implements AgentSession {
     cancelRequested: boolean;
   } | null = null;
   private client: CodexAppServerClient | null = null;
+  private threadRollbackAvailable = true;
   private readonly subscribers = new Set<(event: AgentStreamEvent) => void>();
   private nextTurnOrdinal = 0;
   private activeForegroundTurnId: string | null = null;
   private activeClientMessageId: string | null = null;
   private cachedRuntimeInfo: AgentRuntimeInfo | null = null;
-  private serviceTier: "fast" | null = null;
+  private serviceTier: string | null = null;
+  private speedModels: CodexModel[] = [];
   private planModeEnabled = false;
   private historyPending = false;
   private persistedHistory: PersistedTimelineEntry[] = [];
@@ -3456,6 +3521,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     private readonly autoReviewEnabled: boolean = false,
     private readonly agentId?: string,
     private readonly initialResumePurpose: "interactive" | "history" = "interactive",
+    private readonly usageEnv: NodeJS.ProcessEnv = process.env,
   ) {
     this.logger = logger.child({
       module: "agent",
@@ -3472,9 +3538,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.asyncQuestions = new CodexAsyncQuestions(resumeHandle?.metadata?.asyncQuestions);
     this.codexHome = deps.codexHome ?? resolveCodexHomeDir(process.env);
     this.config.thinkingOptionId = normalizeCodexThinkingOptionId(this.config.thinkingOptionId);
-    if (this.config.featureValues?.fast_mode && codexModelSupportsFastMode(this.config.model)) {
-      this.serviceTier = "fast";
-    }
+    this.serviceTier = readCodexServiceTier(this.config.featureValues);
     if (this.config.featureValues?.plan_mode) {
       this.planModeEnabled = true;
     }
@@ -3485,14 +3549,25 @@ export class CodexAppServerAgentSession implements AgentSession {
     }
   }
 
+  async getUsageReference() {
+    if (this.usageEnv.OPENAI_BASE_URL) return null;
+    return {
+      source: "codex",
+      input: {
+        codexHome:
+          this.usageEnv.CODEX_HOME || path.join(this.usageEnv.HOME || os.homedir(), ".codex"),
+      },
+    };
+  }
+
   get id(): string | null {
     return this.currentThreadId;
   }
 
   get features(): AgentFeature[] {
     return buildCodexFeatures({
-      modelId: this.config.model,
-      fastModeEnabled: this.serviceTier === "fast",
+      serviceTiers: this.currentServiceTiers(),
+      serviceTier: this.serviceTier ?? "default",
       planModeEnabled: this.planModeEnabled,
       planModeAvailable: this.hasPlanCollaborationMode(),
     });
@@ -3545,9 +3620,15 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.registerRequestHandlers();
 
     try {
-      await client.request("initialize", buildCodexAppServerInitializeParams());
+      const initialized = toObjectRecord(
+        await client.request("initialize", buildCodexAppServerInitializeParams()),
+      );
+      this.threadRollbackAvailable = codexServerHasThreadRollback(initialized?.userAgent);
       client.notify("initialized", {});
 
+      this.speedModels =
+        CodexModelListResponseSchema.parse(await client.request("model/list", {})).data ?? [];
+      this.reconcileServiceTier();
       await this.loadResolvedWorkspaceWrite();
       await this.loadCollaborationModes();
       await this.loadSkills();
@@ -3555,6 +3636,7 @@ export class CodexAppServerAgentSession implements AgentSession {
       if (this.currentThreadId) {
         await this.ensureThreadLoaded();
         await this.loadPersistedHistory(this.client);
+        await this.applyDefaultModelAndThinking();
       }
 
       if (this.closed) {
@@ -3751,18 +3833,30 @@ export class CodexAppServerAgentSession implements AgentSession {
     this.resolvedCollaborationMode = this.resolveCollaborationMode();
   }
 
-  private applyFeatureValue(featureId: "fast_mode" | "plan_mode", value: boolean): void {
-    this.config.featureValues = {
-      ...this.config.featureValues,
-      [featureId]: value,
-    };
+  private currentServiceTiers(): CodexServiceTier[] {
+    const selectedModel = this.config.model
+      ? this.speedModels.find(
+          (model) => model.id === this.config.model || model.model === this.config.model,
+        )
+      : (this.speedModels.find((model) => model.isDefault) ?? this.speedModels[0]);
+    return selectedModel?.serviceTiers ?? [];
+  }
 
-    if (featureId === "fast_mode") {
-      this.serviceTier = value ? "fast" : null;
-      this.cachedRuntimeInfo = null;
-      return;
+  private reconcileServiceTier(): void {
+    const tiers = this.currentServiceTiers();
+    // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once saved Fast preferences have migrated.
+    if (this.serviceTier === "fast" && !tiers.some((tier) => tier.id === "fast")) {
+      this.serviceTier = tiers.find((tier) => tier.name.toLowerCase() === "fast")?.id ?? null;
     }
+    if (this.serviceTier !== "default" && !tiers.some((tier) => tier.id === this.serviceTier)) {
+      this.serviceTier = null;
+    }
+    const { fast_mode: _legacyFast, ...values } = this.config.featureValues ?? {};
+    this.config.featureValues = { ...values, service_tier: this.serviceTier ?? "default" };
+  }
 
+  private applyFeatureValue(featureId: "plan_mode", value: boolean): void {
+    this.config.featureValues = { ...this.config.featureValues, [featureId]: value };
     this.planModeEnabled = value;
     this.refreshResolvedCollaborationMode();
     this.cachedRuntimeInfo = null;
@@ -4093,9 +4187,7 @@ export class CodexAppServerAgentSession implements AgentSession {
     if (thinkingOptionId) {
       params.effort = thinkingOptionId;
     }
-    if (this.serviceTier) {
-      params.serviceTier = this.serviceTier;
-    }
+    params.serviceTier = this.serviceTier ?? "default";
     if (this.resolvedCollaborationMode) {
       params.collaborationMode = {
         mode: this.resolvedCollaborationMode.mode,
@@ -4513,9 +4605,7 @@ export class CodexAppServerAgentSession implements AgentSession {
 
   async setModel(modelId: string | null): Promise<void> {
     this.config.model = modelId ?? undefined;
-    if (!codexModelSupportsFastMode(this.config.model)) {
-      this.serviceTier = null;
-    }
+    this.reconcileServiceTier();
     this.refreshResolvedCollaborationMode();
     this.cachedRuntimeInfo = null;
   }
@@ -4530,13 +4620,27 @@ export class CodexAppServerAgentSession implements AgentSession {
   }
 
   async setFeature(featureId: string, value: unknown): Promise<void> {
+    // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once clients use service_tier.
     if (featureId === "fast_mode") {
-      if (Boolean(value) && !codexModelSupportsFastMode(this.config.model)) {
+      const fast = this.currentServiceTiers().find((tier) => tier.name.toLowerCase() === "fast");
+      if (value && !fast)
         throw new Error(
           `Codex fast mode is not available for model '${this.config.model ?? "default"}'`,
         );
+      return this.setFeature("service_tier", value ? fast!.id : "default");
+    }
+    if (featureId === "service_tier") {
+      if (
+        typeof value !== "string" ||
+        (value !== "default" && !this.currentServiceTiers().some((tier) => tier.id === value))
+      ) {
+        throw new Error(
+          `Codex speed '${String(value)}' is not available for model '${this.config.model ?? "default"}'`,
+        );
       }
-      this.applyFeatureValue("fast_mode", Boolean(value));
+      this.serviceTier = value;
+      this.reconcileServiceTier();
+      this.cachedRuntimeInfo = null;
       return;
     }
     if (featureId === "plan_mode") {
@@ -4839,6 +4943,7 @@ export class CodexAppServerAgentSession implements AgentSession {
       serviceTier: this.serviceTier,
       config: this.buildCodexInnerConfig(),
       userMessageTurns: this.codexUserMessageTurns(),
+      threadRollbackAvailable: this.threadRollbackAvailable,
       setThreadId: async (threadId) => {
         this.currentThreadId = threadId;
         this.cachedRuntimeInfo = null;
@@ -5152,13 +5257,21 @@ export class CodexAppServerAgentSession implements AgentSession {
     return { model, thinkingOptionId };
   }
 
+  // A session without a model or effort runs on Codex's configured defaults, whether its
+  // thread is new or resumed after a restart.
+  private async applyDefaultModelAndThinking(): Promise<string> {
+    const { model, thinkingOptionId } = await this.resolveModelAndThinking();
+    this.config.model = model;
+    this.reconcileServiceTier();
+    this.config.thinkingOptionId = thinkingOptionId;
+    return model;
+  }
+
   private async ensureThread(): Promise<void> {
     if (!this.client) return;
     if (this.currentThreadId) return;
 
-    const { model, thinkingOptionId } = await this.resolveModelAndThinking();
-    this.config.model = model;
-    this.config.thinkingOptionId = thinkingOptionId;
+    const model = await this.applyDefaultModelAndThinking();
 
     const { params, approvalPolicy, sandbox } = this.buildThreadStartRequest(model);
     const rawResponse = await this.client.request("thread/start", params);
@@ -7028,15 +7141,6 @@ export class CodexAppServerAgentClient implements AgentClient {
     private readonly deps: CodexAppServerAgentDeps = {},
   ) {}
 
-  async resolveUsageReference() {
-    const env = buildCodexAppServerEnv(this.runtimeSettings);
-    if (env.OPENAI_BASE_URL) return null;
-    return {
-      source: "codex",
-      input: { codexHome: env.CODEX_HOME || path.join(env.HOME || os.homedir(), ".codex") },
-    };
-  }
-
   private sessionDeps(launchEnv: Record<string, string> | undefined): CodexAppServerAgentDeps {
     return {
       ...this.deps,
@@ -7158,6 +7262,7 @@ export class CodexAppServerAgentClient implements AgentClient {
       autoReviewEnabled,
       launchContext?.agentId,
       "interactive",
+      buildCodexAppServerEnv(this.runtimeSettings, launchContext?.env),
     );
     await session.connect();
     return session;
@@ -7190,6 +7295,7 @@ export class CodexAppServerAgentClient implements AgentClient {
       autoReviewEnabled,
       launchContext?.agentId,
       options?.purpose ?? "interactive",
+      buildCodexAppServerEnv(this.runtimeSettings, launchContext?.env),
     );
     await session.connect();
     return session;

packages/server/src/server/agent/providers/codex-feature-definitions.ts

@@ -1,27 +1,33 @@
 import type { AgentFeature, AgentFeatureToggle } from "../agent-sdk-types.js";
 
-// Codex Fast is distinct from API Priority processing. Keep model support aligned with
-// https://developers.openai.com/codex/speed and https://developers.openai.com/codex/models.
-const CODEX_FAST_MODE_SUPPORTED_MODELS = new Set([
-  "gpt-6-astra",
-  "gpt-6-sol",
-  "gpt-6-luna",
-  "gpt-5.6",
-  "gpt-5.6-sol",
-  "gpt-5.6-terra",
-  "gpt-5.6-luna",
-  "gpt-5.5",
-  "gpt-5.4",
-]);
+import { z } from "zod";
 
-export const CODEX_FAST_MODE_FEATURE: Omit<AgentFeatureToggle, "value"> = {
-  type: "toggle",
-  id: "fast_mode",
-  label: "Fast",
-  description: "Priority inference at increased usage",
-  tooltip: "Toggle fast mode",
-  icon: "zap",
-};
+export const CodexServiceTierSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+});
+export type CodexServiceTier = z.infer<typeof CodexServiceTierSchema>;
+
+function buildCodexSpeedFeature(tiers: CodexServiceTier[], value: string): AgentFeature[] {
+  if (tiers.length === 0) return [];
+  return [
+    {
+      type: "select",
+      id: "service_tier",
+      label: "Speed",
+      description: "Choose processing speed. Faster tiers increase usage.",
+      tooltip: "Select speed",
+      icon: "zap",
+      desktopTrigger: "icon",
+      value,
+      options: [
+        { id: "default", label: "Normal", isDefault: true },
+        ...tiers.map((tier) => ({ id: tier.id, label: tier.name })),
+      ],
+    },
+  ];
+}
 
 export const CODEX_PLAN_MODE_FEATURE: Omit<AgentFeatureToggle, "value"> = {
   type: "toggle",
@@ -32,40 +38,22 @@ export const CODEX_PLAN_MODE_FEATURE: Omit<AgentFeatureToggle, "value"> = {
   icon: "list-todo",
 };
 
-function normalizeCodexModelId(modelId: string | null | undefined): string | null {
-  const normalized = typeof modelId === "string" ? modelId.trim() : "";
-  return normalized.length > 0 ? normalized : null;
-}
-
-export function codexModelSupportsFastMode(modelId: string | null | undefined): boolean {
-  const normalizedModelId = normalizeCodexModelId(modelId);
-  if (!normalizedModelId) {
-    return false;
-  }
-  return CODEX_FAST_MODE_SUPPORTED_MODELS.has(normalizedModelId);
-}
-
 export function buildCodexFeatures(input: {
-  modelId: string | null | undefined;
-  fastModeEnabled: boolean;
+  serviceTiers: CodexServiceTier[];
+  serviceTier: string;
   planModeEnabled: boolean;
   planModeAvailable?: boolean;
 }): AgentFeature[] {
-  const features: AgentFeature[] = [];
-
-  if (codexModelSupportsFastMode(input.modelId)) {
-    features.push({
-      ...CODEX_FAST_MODE_FEATURE,
-      value: input.fastModeEnabled,
-    });
-  }
-
+  const features = buildCodexSpeedFeature(input.serviceTiers, input.serviceTier);
   if (input.planModeAvailable !== false) {
-    features.push({
-      ...CODEX_PLAN_MODE_FEATURE,
-      value: input.planModeEnabled,
-    });
+    features.push({ ...CODEX_PLAN_MODE_FEATURE, value: input.planModeEnabled });
   }
-
   return features;
 }
+
+export function readCodexServiceTier(values: Record<string, unknown> | undefined): string | null {
+  const tier = values?.service_tier;
+  if (typeof tier === "string") return tier;
+  // COMPAT(codexFastPreference): added in v0.10.0, remove after 2027-03-29 once saved Fast preferences have migrated.
+  return values?.fast_mode ? "fast" : null;
+}

packages/server/src/server/agent/providers/codex/rewind.test.ts

@@ -96,6 +96,7 @@ describe("Codex Rewind", () => {
       model: "gpt-5.4-mini",
       serviceTier: null,
       userMessageTurns,
+      threadRollbackAvailable: true,
       setThreadId: (threadId) => {
         reboundThreadId = threadId;
       },
@@ -131,6 +132,7 @@ describe("Codex Rewind", () => {
       threadId: "source-thread",
       messageId: "codex-second",
       userMessageTurns,
+      threadRollbackAvailable: true,
       setThreadId: (threadId) => {
         reboundThreadId = threadId;
       },
@@ -175,6 +177,7 @@ describe("Codex Rewind", () => {
       model: "gpt-5.4-mini",
       serviceTier: null,
       userMessageTurns,
+      threadRollbackAvailable: true,
       setThreadId: (threadId) => {
         reboundThreadId = threadId;
       },
@@ -218,6 +221,7 @@ describe("Codex Rewind", () => {
         model: "gpt-5.4-mini",
         serviceTier: null,
         userMessageTurns,
+        threadRollbackAvailable: true,
         setThreadId: (threadId) => {
           reboundThreadId = threadId;
         },
@@ -239,6 +243,7 @@ describe("Codex Rewind", () => {
         threadId: "source-thread",
         messageId: "missing-message",
         userMessageTurns,
+        threadRollbackAvailable: true,
         setThreadId: () => undefined,
       }),
     ).rejects.toThrow("Codex could not find user message missing-message");

packages/server/src/server/agent/providers/codex/rewind.ts

@@ -69,6 +69,7 @@ export async function revertCodexConversation(input: {
   serviceTier?: string | null;
   config?: Record<string, unknown> | null;
   userMessageTurns: CodexUserMessageTurnIndex;
+  threadRollbackAvailable: boolean;
   setThreadId: (threadId: string) => void | Promise<void>;
 }): Promise<void> {
   if (!input.threadId) {
@@ -98,8 +99,10 @@ export async function revertCodexConversation(input: {
     persistExtendedHistory: true,
   };
 
-  const historyMode = await readCodexThreadHistoryMode(input.client, input.threadId);
-  if (historyMode === "paginated") {
+  if (
+    !input.threadRollbackAvailable ||
+    (await readCodexThreadHistoryMode(input.client, input.threadId)) === "paginated"
+  ) {
     if (!targetTurn.turnId) {
       throw new Error(`Codex could not find the turn containing user message ${input.messageId}`);
     }
@@ -111,7 +114,8 @@ export async function revertCodexConversation(input: {
     return;
   }
 
-  // Fork is non-destructive: the old thread file stays on disk and remains
+  // Legacy threads on Codex before 0.156 fork and then roll back. Fork is
+  // non-destructive: the old thread file stays on disk and remains
   // recoverable with `codex resume <old-uuid>` if the rewind target was wrong.
   const forked = await forkCodexThread(input.client, forkParams);
   const forkedThreadId = forked.thread.id;

packages/server/src/server/agent/providers/codex/tool-call-mapper.test.ts

@@ -656,6 +656,29 @@ describe("codex tool-call mapper", () => {
     });
   });
 
+  it.each([
+    {
+      type: "commandExecution",
+      id: "codex-declined-command",
+      status: "declined",
+      command: "printf ok > /outside/permission.txt",
+      cwd: "/tmp/repo",
+      aggregatedOutput: null,
+      exitCode: null,
+    },
+    {
+      type: "fileChange",
+      id: "codex-declined-patch",
+      status: "declined",
+      changes: [],
+    },
+  ])("settles a declined $type as failed instead of running", (threadItem) => {
+    const item = expectMapped(mapCodexToolCallFromThreadItem(threadItem));
+
+    expect(item.callId).toBe(threadItem.id);
+    expect(item.status).toBe("failed");
+  });
+
   it("maps unknown tools to unknown detail with raw payloads", () => {
     const item = expectMapped(
       mapCodexToolCallEnvelope({

packages/server/src/server/agent/providers/omp/agent.history-purpose.test.ts

@@ -0,0 +1,64 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, test } from "vitest";
+
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import type { AgentPersistenceHandle } from "../../agent-sdk-types.js";
+import { OmpAgentClient } from "./agent.js";
+import { FakeOmp } from "./test-utils/fake-omp.js";
+
+test("archived OMP history replays messages and todos without leaving a runtime", async () => {
+  const directory = await mkdtemp(join(tmpdir(), "paseo-omp-history-purpose-"));
+  const sessionFile = join(directory, "session.jsonl");
+  const entries = [
+    { type: "session", id: "root", parentId: null },
+    {
+      type: "message",
+      id: "user-1",
+      parentId: "root",
+      message: { role: "user", content: "make a plan" },
+    },
+    {
+      type: "message",
+      id: "todo-1",
+      parentId: "user-1",
+      message: {
+        role: "toolResult",
+        toolName: "todo",
+        toolCallId: "call-1",
+        content: [{ type: "text", text: "one task" }],
+        details: {
+          phases: [{ name: "Tasks", tasks: [{ content: "Check history", status: "pending" }] }],
+        },
+      },
+    },
+  ];
+  await writeFile(sessionFile, entries.map((entry) => JSON.stringify(entry)).join("\n"));
+  const runtime = new FakeOmp();
+  const client = new OmpAgentClient({ logger: createTestLogger(), runtime });
+  const handle: AgentPersistenceHandle = {
+    provider: "omp",
+    sessionId: "history-1",
+    nativeHandle: sessionFile,
+    metadata: { cwd: directory },
+  };
+
+  const session = await client.resumeSession(handle, undefined, undefined, { purpose: "history" });
+  const events = [];
+  try {
+    for await (const event of session.streamHistory()) events.push(event);
+  } finally {
+    await session.close();
+  }
+
+  expect(runtime.recordedLaunches).toHaveLength(0);
+  expect(events).toContainEqual({
+    type: "timeline",
+    provider: "omp",
+    item: {
+      type: "todo",
+      items: [{ text: "Check history", status: "pending", completed: false }],
+    },
+  });
+});

packages/server/src/server/agent/providers/omp/agent.test.ts

@@ -1,9 +1,10 @@
 import { describe, expect, test } from "vitest";
 import { setImmediate as waitForImmediate } from "node:timers/promises";
 import { mkdtempSync, mkdirSync, rmSync } from "node:fs";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import path, { join } from "node:path";
 
 import type { AgentStreamEvent } from "../../agent-sdk-types.js";
 import type { PaseoToolCatalog } from "../../tools/types.js";
@@ -13,6 +14,9 @@ import type { OmpUsagePollScheduler } from "./usage-poller.js";
 import { resolveOmpProviderParams } from "./provider-config.js";
 import { OmpRuntimeEventSchema } from "./rpc-types.js";
 import { OmpHarness } from "./test-utils/omp-harness.js";
+import { OmpAgentClient } from "./agent.js";
+import { FakeOmp } from "./test-utils/fake-omp.js";
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
 
 const TURN_LIFECYCLE_EVENTS = new Set<AgentStreamEvent["type"]>([
   "turn_started",
@@ -47,6 +51,26 @@ test("OMP ready timeout defaults to 20 seconds and RPC timeout overrides both",
     rpcTimeoutMs: 90_000,
   });
 });
+
+test("OMP import uses the runtime's custom agent directory without a configured sessionDir", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "paseo-omp-import-dir-"));
+  const agentDir = path.join(root, "agent");
+  const sessionFile = path.join(agentDir, "sessions", "project", "session.jsonl");
+  await mkdir(path.dirname(sessionFile), { recursive: true });
+  await writeFile(
+    sessionFile,
+    JSON.stringify({ type: "session", id: "custom-dir", cwd: root, timestamp: "2026-09-28" }),
+  );
+  const client = new OmpAgentClient({
+    logger: createTestLogger(),
+    runtime: new FakeOmp(),
+    runtimeSettings: { env: { PI_CODING_AGENT_DIR: agentDir } },
+  });
+
+  expect(await client.listImportableSessions({ cwd: root })).toEqual([
+    expect.objectContaining({ providerHandleId: sessionFile }),
+  ]);
+});
 class ManualIdleScheduler implements OmpProviderIdleScheduler {
   private readonly retries: Array<() => void> = [];
   private readonly waiters: Array<{ count: number; resolve: () => void }> = [];
@@ -194,20 +218,14 @@ describe("OMP agent client and session", () => {
         expires: Date.now() + 60_000,
       }),
     );
-    db.prepare("INSERT INTO cache (key, value, expires_at) VALUES (?, ?, ?)").run(
-      "session:sticky:openai-codex:omp-session-1",
-      JSON.stringify({ type: "oauth", credentialId: 1 }),
-      Math.floor(Date.now() / 1000) + 100,
-    );
     db.close();
     try {
-      const env = {
+      const omp = new OmpHarness();
+      await omp.start({}, undefined, {
         OMP_PROFILE: "",
         PI_CODING_AGENT_DIR: agentDir,
         XDG_DATA_HOME: "",
-      };
-      const omp = new OmpHarness({ env });
-      await omp.start({}, undefined, env);
+      });
       const runtime = omp.runtime();
       runtime.state = { ...runtime.state, model: { provider: "openai-codex", id: "codex-model" } };
       const requestsBefore = runtime.getStateRequestCount;
@@ -222,20 +240,6 @@ describe("OMP agent client and session", () => {
         input: { accessToken: "claude-fixture" },
       });
       expect(runtime.getStateRequestCount).toBe(requestsBefore + 2);
-      const beforeClosed = runtime.getStateRequestCount;
-      expect(
-        await omp.getStoredUsageReference("openai-codex/codex-model", "omp-session-1"),
-      ).toEqual({
-        source: "codex",
-        input: { accessToken: "codex-fixture", accountId: "codex-account" },
-      });
-      expect(
-        await omp.getStoredUsageReference("openai-codex/codex-model", "omp-session-1", null),
-      ).toEqual({
-        source: "codex",
-        input: { accessToken: "codex-fixture", accountId: "codex-account" },
-      });
-      expect(runtime.getStateRequestCount).toBe(beforeClosed);
       await omp.close();
     } finally {
       rmSync(home, { recursive: true, force: true });
@@ -255,7 +259,7 @@ describe("OMP agent client and session", () => {
       [expect.objectContaining({ name: "create_agent" })],
     ]);
     expect(omp.capabilities()).toMatchObject({
-      supportsMcpServers: false,
+      supportsMcpServers: true,
       supportsNativePaseoTools: true,
     });
   });
@@ -267,6 +271,26 @@ describe("OMP agent client and session", () => {
     expect(omp.launchConfiguration().argv).toEqual(expect.arrayContaining(["--thinking", "max"]));
   });
 
+  test("launches with auto thinking when auto is selected", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ thinkingOptionId: "auto" });
+
+    expect(omp.launchConfiguration().argv).toEqual(expect.arrayContaining(["--thinking", "auto"]));
+  });
+
+  test("keeps auto thinking when resuming a session", async () => {
+    const omp = new OmpHarness();
+    await omp.resume(
+      {
+        user: { id: "user-auto", text: "continue" },
+        assistant: { id: "assistant-auto", text: "ready" },
+      },
+      { thinkingOptionId: "auto" },
+    );
+
+    expect(omp.launchConfiguration().argv).toEqual(expect.arrayContaining(["--thinking", "auto"]));
+  });
+
   test("launches with write approval mode", async () => {
     const omp = new OmpHarness();
     await omp.start({ modeId: "write" });
@@ -463,6 +487,182 @@ describe("OMP agent client and session", () => {
     await expect(completion).resolves.toMatchObject({ finalText: "first done" });
   });
 
+  test("fails a turn when the provider idle gate passes its deadline", async () => {
+    const scheduler = new ManualIdleScheduler();
+    const omp = new OmpHarness({ providerIdleScheduler: scheduler, providerIdleDeadlineMs: 1 });
+    await omp.start();
+    const { completion } = await omp.startPromptUntilProviderIdle("first", "first done", {
+      isStreaming: true,
+      isCompacting: false,
+    });
+    await scheduler.waitForWaits(1);
+    omp.runtime().emit({
+      type: "tool_execution_start",
+      toolCallId: "tool-at-deadline",
+      toolName: "bash",
+      args: { command: "sleep 30" },
+    });
+    expect(omp.runningToolCallIds()).toEqual(["tool-at-deadline"]);
+    await new Promise((resolve) => setTimeout(resolve, 2));
+    scheduler.retry();
+    await expect(completion).rejects.toThrow(/provider idle/i);
+    expect(omp.runningToolCallIds()).toEqual([]);
+  });
+
+  test("steers a running turn and correlates a template-expanded echo exactly once", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    const session = omp.requireSession();
+    const { turnId } = await session.startTurn("first", { clientMessageId: "client-first" });
+    const runtime = omp.runtime();
+    runtime.beginTurn();
+    runtime.acceptPrompt("first", "native-first");
+    await expect(
+      session.steerActiveTurn?.("expand template", {
+        expectedTurnId: turnId,
+        clientMessageId: "client-steer",
+      }),
+    ).resolves.toEqual({ status: "accepted" });
+    runtime.acceptPrompt("expanded prompt", "native-steer");
+    runtime.acceptPrompt("expanded prompt", "native-steer");
+    expect(omp.timeline().filter((item) => item.type === "user_message")).toEqual([
+      expect.objectContaining({ messageId: "native-first", clientMessageId: "client-first" }),
+      expect.objectContaining({ messageId: "native-steer", clientMessageId: "client-steer" }),
+    ]);
+  });
+
+  test("reports a rejected steer as unavailable", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    const session = omp.requireSession();
+    const { turnId } = await session.startTurn("first");
+    omp.runtime().steerError = new Error("extension command cannot be steered");
+    await expect(
+      session.steerActiveTurn?.("extension input", { expectedTurnId: turnId }),
+    ).resolves.toEqual({ status: "unavailable" });
+  });
+
+  test("propagates an OMP steer transport timeout", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    const session = omp.requireSession();
+    const { turnId } = await session.startTurn("first");
+    const timeout = new Error(
+      "OMP RPC request timed out phase=steer elapsedMs=60000 timeoutMs=60000",
+    );
+    omp.runtime().steerError = timeout;
+    await expect(session.steerActiveTurn?.("second", { expectedTurnId: turnId })).rejects.toBe(
+      timeout,
+    );
+  });
+
+  test("shows OMP's fallback model without persisting it as the selected model", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ model: "openrouter/google/gemini-3.8-flash" });
+    const runtime = omp.runtime();
+    runtime.state = {
+      ...runtime.state,
+      model: { provider: "openrouter", id: "google/gemini-3.8-flash" },
+    };
+    runtime.emit({
+      type: "retry_fallback_applied",
+      from: "openrouter/google/gemini-3.8-flash",
+      to: "openrouter/other/model",
+      role: "primary",
+    });
+    runtime.state = { ...runtime.state, model: { provider: "openrouter", id: "other/model" } };
+    runtime.state = { ...runtime.state, fastModeEnabled: true, fastModeActive: false };
+    runtime.emit({ type: "model_changed" });
+    await waitForImmediate();
+    expect(omp.eventTypes()).toContain("model_changed");
+    expect((await omp.requireSession().getRuntimeInfo()).model).toBe("openrouter/other/model");
+    expect(omp.requireSession().describePersistence()?.metadata?.model).toBe(
+      "openrouter/google/gemini-3.8-flash",
+    );
+    expect(omp.requireSession().features).toEqual([
+      expect.objectContaining({
+        value: true,
+        description: expect.stringMatching(/does not apply/i),
+      }),
+    ]);
+  });
+
+  test("Fast stays selected when OMP says it is inactive for the current model", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ model: "openrouter/google/gemini-3.8-flash" });
+    const session = omp.requireSession();
+    omp.runtime().fastModeResult = { enabled: true, active: false };
+    await session.setFeature?.("fast_mode", true);
+    expect(omp.runtime().setFastModeRequests).toEqual([true]);
+    expect(session.features).toEqual([
+      expect.objectContaining({
+        id: "fast_mode",
+        value: true,
+        description: expect.stringMatching(/does not apply to this model/i),
+        tooltip: expect.stringMatching(/does not apply to this model/i),
+      }),
+    ]);
+  });
+
+  test("shows Fast only when OMP reports its state fields", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    const session = omp.requireSession();
+    const {
+      fastModeEnabled: _enabled,
+      fastModeActive: _active,
+      ...olderState
+    } = omp.runtime().state;
+    omp.runtime().state = olderState;
+    await session.getRuntimeInfo();
+    expect(session.features).toEqual([]);
+    await expect(session.setFeature?.("fast_mode", true)).rejects.toThrow(/unavailable/i);
+    omp.runtime().state = { ...olderState, fastModeEnabled: false, fastModeActive: false };
+    await session.getRuntimeInfo();
+    expect(session.features).toHaveLength(1);
+  });
+
+  test("switching model refreshes whether Fast applies", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ model: "openrouter/google/gemini-3.8-flash" });
+    const session = omp.requireSession();
+    omp.runtime().fastModeResult = { enabled: true, active: true };
+    await session.setFeature?.("fast_mode", true);
+    expect(session.features).toEqual([expect.objectContaining({ value: true })]);
+
+    omp.runtime().setModelResult = { provider: "openrouter", id: "other/model" };
+    omp.runtime().queueStateReports([
+      {
+        ...omp.runtime().state,
+        model: omp.runtime().setModelResult,
+        fastModeEnabled: true,
+        fastModeActive: false,
+      },
+    ]);
+    await session.setModel?.("openrouter/other/model");
+    expect(session.features).toEqual([
+      expect.objectContaining({
+        value: true,
+        description: expect.stringMatching(/does not apply/i),
+      }),
+    ]);
+  });
+
+  test("restores Fast from the initial OMP state on create and resume", async () => {
+    const created = new OmpHarness();
+    await created.start({ featureValues: { fast_mode: true } });
+    expect(created.runtime().setFastModeRequests).toEqual([true]);
+    expect(created.runtime().getStateRequestCount).toBe(1);
+
+    const resumed = new OmpHarness();
+    await resumed.resume(
+      { user: { id: "user-1", text: "hello" }, assistant: { id: "assistant-1", text: "hi" } },
+      { featureValues: { fast_mode: true } },
+    );
+    expect(resumed.runtime().setFastModeRequests).toEqual([true]);
+    expect(resumed.runtime().getStateRequestCount).toBe(1);
+  });
+
   test("does not complete on OMP's extension-notice agent_end", async () => {
     const omp = new OmpHarness();
     await omp.start();
@@ -535,13 +735,162 @@ describe("OMP agent client and session", () => {
         message: "Background job DocsSmokeTwo completed",
       },
     ]);
-    // Non-notice custom messages still fall through as assistant messages.
-    expect(omp.timeline().filter((item) => item.type === "assistant_message")).toMatchObject([
-      { text: "done" },
-      { text: "plain custom status text" },
+    // Non-notice custom messages still fall through as assistant messages with
+    // their own id so the stream coalescer never glues them onto the open reply.
+    expect(omp.timeline().filter((item) => item.type === "assistant_message")).toEqual([
+      { type: "assistant_message", text: "done", messageId: "omp-assistant-1" },
+      { type: "assistant_message", text: "plain custom status text", messageId: "omp-custom-1" },
     ]);
   });
 
+  test("shows a concise error for a failed tool while keeping shell output", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    omp.emit({
+      type: "tool_execution_start",
+      toolCallId: "failed-shell",
+      toolName: "bash",
+      args: { command: "false" },
+    });
+    omp.emit({
+      type: "tool_execution_end",
+      toolCallId: "failed-shell",
+      toolName: "bash",
+      result: {
+        content: [{ type: "text", text: "Command exited with code 1" }],
+        details: {},
+        isError: true,
+        exitCode: 1,
+      },
+      isError: true,
+    });
+    expect(omp.timeline().at(-1)).toMatchObject({
+      type: "tool_call",
+      status: "failed",
+      error: "Command exited with code 1",
+      detail: { type: "shell", command: "false", exitCode: 1 },
+    });
+  });
+
+  test("uses the exit message when a failed shell has no output", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    omp.emit({
+      type: "tool_execution_start",
+      toolCallId: "empty-shell",
+      toolName: "bash",
+      args: { command: "false" },
+    });
+    omp.emit({
+      type: "tool_execution_end",
+      toolCallId: "empty-shell",
+      toolName: "bash",
+      result: {
+        content: [
+          {
+            type: "text",
+            text: "(no output)\n\nWall time: 0.02 seconds\n\nCommand exited with code 1",
+          },
+        ],
+        isError: true,
+      },
+      isError: true,
+    });
+    expect(omp.timeline().at(-1)).toMatchObject({ error: "Command exited with code 1" });
+  });
+
+  test("does not duplicate the typed invocation for a live skill expansion", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    await omp.runPromptWithCustomMessage(
+      "hello",
+      {
+        role: "custom",
+        content: "[IMPORTANT] Full skill body",
+        customType: "skill-prompt",
+        attribution: "user",
+        details: { name: "commit" },
+        display: true,
+        id: "skill-1",
+      },
+      "done",
+    );
+    expect(omp.timeline().filter((item) => item.type === "user_message")).toEqual([
+      { type: "user_message", text: "hello", messageId: "user-1" },
+    ]);
+    expect(omp.timeline()).not.toContainEqual(
+      expect.objectContaining({ text: "[IMPORTANT] Full skill body" }),
+    );
+  });
+
+  test.each([
+    { kind: "initial", priorPrompt: false },
+    { kind: "follow-up", priorPrompt: true },
+  ])("correlates a $kind skill invocation without a user echo", async ({ priorPrompt }) => {
+    const omp = new OmpHarness();
+    await omp.start();
+    if (priorPrompt) {
+      await omp.runPrompt("Reply OK", "OK");
+    }
+
+    const typed = "/skill:tldr Summarize: hi.";
+    const runtime = omp.runtime();
+    const promptStarted = runtime.nextPrompt();
+    const run = omp.requireSession().run(typed, { clientMessageId: "client-skill" });
+    await promptStarted;
+    runtime.beginTurn();
+    runtime.emit({
+      type: "message_end",
+      message: {
+        role: "custom",
+        content: "[IMPORTANT] Full skill body",
+        customType: "skill-prompt",
+        attribution: "user",
+        details: { name: "tldr", args: "Summarize: hi." },
+        display: true,
+        id: "skill-1",
+      },
+    });
+    runtime.streamAssistantText("done");
+    runtime.finishTurn();
+    await run;
+
+    expect(omp.timeline().filter((item) => item.type === "user_message")).toEqual([
+      ...(priorPrompt ? [{ type: "user_message", text: "Reply OK", messageId: "user-1" }] : []),
+      { type: "user_message", text: typed, clientMessageId: "client-skill" },
+    ]);
+  });
+
+  test("marks an OMP web search details error as failed even without isError", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    omp.emit({
+      type: "tool_execution_start",
+      toolCallId: "search-failed",
+      toolName: "web_search",
+      args: { query: "Paseo" },
+    });
+    omp.emit({
+      type: "tool_execution_end",
+      toolCallId: "search-failed",
+      toolName: "web_search",
+      result: {
+        content: [{ type: "text", text: "Error: All web search providers failed" }],
+        details: {
+          response: { provider: "mojeek", sources: [] },
+          error: "All web search providers failed",
+        },
+      },
+      isError: false,
+    });
+    expect(omp.timeline().at(-1)).toMatchObject({
+      type: "tool_call",
+      status: "failed",
+      error: "All web search providers failed",
+      detail: { type: "search", query: "Paseo" },
+    });
+  });
+
   test("does not complete a queued model turn from OMP's local-only hint", async () => {
     const omp = new OmpHarness();
     await omp.start();
@@ -560,6 +909,28 @@ describe("OMP agent client and session", () => {
     expect(omp.completedTurnCount()).toBe(1);
   });
 
+  test("completes a no-turn notify with one notification and no assistant text", async () => {
+    const scheduler = new ManualNoTurnScheduler();
+    const omp = new OmpHarness({ noTurnScheduler: scheduler });
+    await omp.start();
+    const prompt = await omp.startPromptWithFalseLocalOnlyResult("/autoresearch off");
+    omp.emit({
+      type: "extension_ui_request",
+      id: "local-notify",
+      method: "notify",
+      message: "Autoresearch mode disabled",
+      notifyType: "info",
+    });
+
+    scheduler.settle();
+    await expect(prompt.completion).resolves.toMatchObject({ finalText: "" });
+    expect(omp.completedTurnCount()).toBe(1);
+    expect(omp.timeline().filter((item) => item.type === "notification")).toEqual([
+      { type: "notification", level: "info", message: "Autoresearch mode disabled" },
+    ]);
+    expect(omp.timeline().filter((item) => item.type === "assistant_message")).toEqual([]);
+  });
+
   test("waits for a delayed queued model turn after OMP's local-only result", async () => {
     const omp = new OmpHarness();
     await omp.start();
@@ -679,6 +1050,33 @@ describe("OMP agent client and session", () => {
     ]);
   });
 
+  test("shows OMP notifications during a turn and while idle with their levels", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    await omp.startTurn("work");
+    omp.runtime().beginTurn();
+    omp.emit({
+      type: "extension_ui_request",
+      id: "n1",
+      method: "notify",
+      message: "Working",
+      notifyType: "warning",
+    });
+    omp.runtime().finishTurn();
+    omp.emit({
+      type: "extension_ui_request",
+      id: "n2",
+      method: "notify",
+      message: "Done",
+      notifyType: "info",
+    });
+    expect(omp.timeline().filter((item) => item.type === "notification")).toEqual([
+      { type: "notification", level: "warning", message: "Working" },
+      { type: "notification", level: "info", message: "Done" },
+    ]);
+    expect(omp.timeline().filter((item) => item.type === "assistant_message")).toEqual([]);
+  });
+
   test("maps legacy select options without descriptions and preserves ordinary responses", async () => {
     const omp = new OmpHarness();
     await omp.start();
@@ -744,41 +1142,6 @@ describe("OMP agent client and session", () => {
     ]);
   });
 
-  test("preserves combined selection descriptions and freeform sentinel behavior", async () => {
-    const omp = new OmpHarness();
-    await omp.start();
-    omp.emit({
-      type: "tool_execution_start",
-      toolCallId: "ask-user-1",
-      toolName: "ask_user",
-      args: { allowComment: true, allowFreeform: true, allowMultiple: false },
-    });
-    omp.emit({
-      type: "extension_ui_request",
-      id: "select-combined",
-      method: "select",
-      title: "Choose",
-      options: ["First", "✏️ Type custom response..."],
-      optionDetails: [{ description: "First detail" }, { description: "ignored" }],
-    });
-
-    const combinedInput = omp.pendingPermissions()[0]?.input;
-    expect(combinedInput?.questions?.[0]?.options).toStrictEqual([
-      { label: "First", description: "First detail" },
-    ]);
-    expect(combinedInput).toMatchObject({
-      questions: [{ allowOther: true }, { header: "Comment" }],
-    });
-    await omp.respondToPermission("select-combined", {
-      behavior: "allow",
-      updatedInput: { answers: { Response: "custom", Comment: "note" } },
-    });
-    expect(omp.extensionUiResponses()).toContainEqual({
-      id: "select-combined",
-      response: { value: "✏️ Type custom response..." },
-    });
-  });
-
   test("exposes OMP modes and commands through the domain session", async () => {
     const omp = new OmpHarness();
     omp.queueCommands([{ name: "review", description: "Review changes", source: "skill" }]);
@@ -795,10 +1158,99 @@ describe("OMP agent client and session", () => {
         expect.objectContaining({ name: "review", kind: "skill" }),
       ]),
     );
+    await expect(omp.setMode("ask")).resolves.toBeUndefined();
+    await expect(omp.currentMode()).resolves.toBe("ask");
+    expect(omp.runtimeLaunches()[1]?.argv).toContain("--approval-mode");
+    expect(omp.runtimeLaunches()[1]?.argv).toContain("always-ask");
+  });
+
+  test("restarts the same conversation after an idle process exit", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ modeId: "full" });
+    const previousId = omp.runtime().state.sessionId;
+    omp.processExit("OMP RPC process exited with code null and signal SIGKILL\nBun crashed");
+    expect(omp.turnFailures()).toEqual([
+      "OMP RPC process exited with code null and signal SIGKILL\nBun crashed",
+    ]);
+
+    await omp.startTurn("remember the conversation");
+    expect(omp.runtimeLaunches()).toHaveLength(2);
+    expect(omp.runtimeLaunches()[1]?.session).toBe("/tmp/omp-session");
+    expect(omp.runtime().state.sessionId).toBe(previousId);
+    expect(omp.threadStartedSessionIds()).toEqual([]);
+    expect(omp.runtime().prompts).toEqual([
+      { message: "remember the conversation", imageCount: 0 },
+    ]);
+  });
+
+  test("reports a mid-turn process exit and resumes on the following prompt", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    await omp.requireStartTurn("sleep 30");
+    omp.runtime().beginTurn();
+    omp.processExit("OMP RPC process exited with code 137 and signal null\nOOM");
+    expect(omp.turnFailures()).toEqual([
+      "OMP RPC process exited with code 137 and signal null\nOOM",
+    ]);
+    await omp.startTurn("continue");
+    expect(omp.runtimeLaunches()).toHaveLength(2);
+    expect(omp.runtime().prompts).toEqual([{ message: "continue", imageCount: 0 }]);
+  });
+
+  test("reports an immediate relaunch failure without retrying in a loop", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    omp.processExit("OMP RPC process exited with code null and signal SIGKILL");
+    omp.failNextStart(new Error("Bun failed during startup"));
+    await omp.startTurn("continue");
+    expect(omp.turnFailures()).toEqual([
+      "OMP RPC process exited with code null and signal SIGKILL",
+      "Bun failed during startup",
+    ]);
+    expect(omp.runtimeLaunches()).toHaveLength(1);
+  });
+
+  test("closes a replacement process if the session closes during relaunch", async () => {
+    const omp = new OmpHarness();
+    await omp.start();
+    omp.processExit("OMP RPC process exited with code 1 and signal null");
+    const turn = omp.startTurnDetached("continue");
+    await omp.close();
+    await turn;
+    await waitForImmediate();
+    expect(omp.runtimeSessions().every((session) => session.closed)).toBe(true);
+  });
+
+  test("announces a fresh native session when an internal agent recovers", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ internal: true });
+    const previousId = omp.runtime().state.sessionId;
+    omp.processExit("OMP RPC process exited with code 1 and signal null");
+    await omp.startTurn("continue");
+    expect(omp.runtimeLaunches()[1]?.argv).toContain("--no-session");
+    expect(omp.runtime().state.sessionId).not.toBe(previousId);
+    expect(omp.threadStartedSessionIds()).toEqual([omp.runtime().state.sessionId]);
+  });
+
+  test("leaves the current approval mode in place when relaunch fails", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ modeId: "full" });
+    omp.failNextStart(new Error("OMP launch failed"));
+    await expect(omp.setMode("ask")).rejects.toThrow("OMP launch failed");
+    expect(await omp.currentMode()).toBe("full");
+    expect(omp.runtimeLaunches()).toHaveLength(1);
+  });
+
+  test("rejects a running approval-mode change until the turn ends", async () => {
+    const omp = new OmpHarness();
+    await omp.start({ modeId: "full" });
+    await omp.requireStartTurn("work");
     await expect(omp.setMode("ask")).resolves.toEqual({
       type: "warning",
-      message: "Start a new OMP session to change approval mode",
+      message: "Change approval mode once the current turn ends",
     });
+    expect(omp.runtimeLaunches()).toHaveLength(1);
+    expect(await omp.currentMode()).toBe("full");
   });
 
   test("rewinds natively, interrupts, and shuts down", async () => {