fix(server): install registry plugins under npm 12

npm 12 rejects the reviewed tarball URL by default. Allow remote
artifacts only at the staging root while preserving the reviewed
version, URL and integrity checks. Read npm pack filenames so the
fixture registry supports the npm 12 output shape.

Closes #7794

Co-authored-by: 3ae3ae <ogyshjsm@naver.com>

.github/workflows/desktop-release.yml

@@ -135,32 +135,6 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      # Backport electron-builder#10172 to the pinned build tool only.
-      # Remove this step when app-builder-lib is upgraded to a release containing it.
-      - name: Repair temporary keychain password in signing tool
-        shell: bash
-        run: |
-          node <<'KEYCHAIN_FIX'
-          const fs = require('node:fs');
-          const path = require('node:path');
-          const manifestPath = require.resolve('app-builder-lib/package.json');
-          if (JSON.parse(fs.readFileSync(manifestPath, 'utf8')).version !== '26.8.1') {
-            throw new Error('Reassess/remove the signing backport for the new app-builder-lib version');
-          }
-          const sourcePath = path.join(path.dirname(manifestPath), 'out/codeSign/macCodeSign.js');
-          let source = fs.readFileSync(sourcePath, 'utf8');
-          const replacements = [
-            ['importCerts(keychainFile, certPaths, cscPasswords)', 'importCerts(keychainFile, certPaths, cscPasswords, keychainPassword)'],
-            ['importCerts(keychainFile, paths, keyPasswords)', 'importCerts(keychainFile, paths, keyPasswords, keychainPassword)'],
-            ['["set-key-partition-list", "-S", "apple-tool:,apple:", "-s", "-k", password, keychainFile]', '["set-key-partition-list", "-S", "apple-tool:,apple:", "-s", "-k", keychainPassword, keychainFile]'],
-          ];
-          for (const [before, after] of replacements) {
-            if (source.split(before).length !== 2) throw new Error('Unexpected signing tool source; refusing to patch');
-            source = source.replace(before, after);
-          }
-          fs.writeFileSync(sourcePath, source);
-          KEYCHAIN_FIX
-
       - name: Set desktop package version from tag
         shell: bash
         run: |

.oxlintrc.json

@@ -406,10 +406,7 @@
     {
       "files": [
         "packages/app/src/app/_layout.tsx",
-        "packages/app/src/app/pair-scan.tsx",
         "packages/app/src/components/adaptive-modal-sheet.tsx",
-        "packages/app/src/components/add-host-method-modal.tsx",
-        "packages/app/src/components/add-host-modal.tsx",
         "packages/app/src/components/agent-list.tsx",
         "packages/app/src/components/agent-status-dot.tsx",
         "packages/app/src/components/attachment-lightbox.tsx",
@@ -428,7 +425,6 @@
         "packages/app/src/components/hosts/host-picker.tsx",
         "packages/app/src/components/icons/paseo-logo.tsx",
         "packages/app/src/components/left-sidebar.tsx",
-        "packages/app/src/components/pair-link-modal.tsx",
         "packages/app/src/components/plan-card.tsx",
         "packages/app/src/components/provider-diagnostic-sheet.tsx",
         "packages/app/src/components/question-form-card.tsx",
@@ -543,14 +539,10 @@
         "packages/app/src/agent-skills/selection-sheet.tsx",
         "packages/app/src/agent-stream/chat-outline/rail.web.tsx",
         "packages/app/src/agent-stream/view.tsx",
-        "packages/app/src/app/pair-scan.tsx",
         "packages/app/src/changelog/internal/changelog-sheet.tsx",
         "packages/app/src/command-center/command-center.tsx",
         "packages/app/src/components/adaptive-modal-sheet.tsx",
-        "packages/app/src/components/add-host-method-modal.tsx",
-        "packages/app/src/components/add-host-modal.tsx",
         "packages/app/src/components/add-project-flow.tsx",
-        "packages/app/src/components/add-remote-ssh-host-modal.tsx",
         "packages/app/src/components/agent-list.tsx",
         "packages/app/src/components/app-diagnostic-sheet.tsx",
         "packages/app/src/components/attachment-lightbox.tsx",

docs/connected-hosts.md

@@ -74,7 +74,10 @@ registrations remain inspectable; a changed destination requires explicit identi
 
 Both daemons advertise `connectedHosts`; the shared link additionally requires `hostMultiplexing`.
 A completes capability and pinned-identity checks on each physical recovery before admitting channels. There is no local fallback. An older daemon continues to serve existing local
-operations; requesting this feature gives update guidance.
+operations; requesting this feature gives update guidance. The registry retries an older destination
+with capped backoff, so it comes online once updated. Self, duplicate, changed-identity, and
+authentication failures stay in `error` until an update changes the connection, `enabled`, or
+`replaceIdentity`, or A restarts.
 
 Disposing a routed API releases its observations and session. It does not remove the saved host or
 affect sibling API scopes. Disposing the origin cascades to its derived scopes. Observations restore

docs/design.md

@@ -35,7 +35,7 @@ The authored interface ramp uses a 14px base. New native installs default to 15p
 Weight has three tiers, applied by role:
 
 - **Screen titles** — the title in app chrome — use `<ScreenTitle>` (`packages/app/src/components/headers/screen-title.tsx`), which renders `fontSize.base` at weight `400` on compact and `300` on desktop. The New workspace hero is the only larger product title; it uses `fontSize["2xl"]` (`packages/app/src/screens/new-workspace-screen.tsx`).
-- **Structural labels** use `fontWeight.medium`. This applies to section labels above a stack of rows (`packages/app/src/components/agent-list.tsx:519-523`, `packages/app/src/components/keyboard-shortcuts-dialog.tsx:63-67`), form field labels above an input inside a modal (`packages/app/src/components/add-host-modal.tsx:19-23`, `packages/app/src/components/pair-link-modal.tsx:24-28`), the title at the top of a modal/sheet/dialog (`packages/app/src/components/adaptive-modal-sheet.tsx:90-94`, `packages/app/src/components/ui/combobox.tsx:1607-1611`, `packages/app/src/components/welcome-screen.tsx:48-53`), action button labels in tight components such as the sidebar callout actions (`packages/app/src/components/sidebar-callout.tsx:218-221`), and inline data emphasis on dense metadata rows (`packages/app/src/components/git-diff-pane.tsx:2322-2327`, `packages/app/src/components/file-explorer-pane.tsx:1115-1122`).
+- **Structural labels** use `fontWeight.medium`. This applies to section labels above a stack of rows (`packages/app/src/components/agent-list.tsx:519-523`, `packages/app/src/components/keyboard-shortcuts-dialog.tsx:63-67`), form field labels above an input inside a modal (`packages/app/src/hosts/add-host/internal/add-host-modal.tsx:19-23`, `packages/app/src/hosts/add-host/internal/pair-link-modal.tsx:24-28`), the title at the top of a modal/sheet/dialog (`packages/app/src/components/adaptive-modal-sheet.tsx:90-94`, `packages/app/src/components/ui/combobox.tsx:1607-1611`, `packages/app/src/components/welcome-screen.tsx:48-53`), action button labels in tight components such as the sidebar callout actions (`packages/app/src/components/sidebar-callout.tsx:218-221`), and inline data emphasis on dense metadata rows (`packages/app/src/components/git-diff-pane.tsx:2322-2327`, `packages/app/src/components/file-explorer-pane.tsx:1115-1122`).
 - **Content** uses `fontWeight.normal`. This applies to settings rows (`packages/app/src/styles/settings.ts`), sidebar primary list-item titles (`packages/app/src/components/sidebar-workspace-list.tsx:2680-2686`, `packages/app/src/components/agent-list.tsx:572-578`), `<Button>` text (`packages/app/src/components/ui/button.tsx:80-84`), `<StatusBadge>` text (`packages/app/src/components/ui/status-badge.tsx:56-60`), and `<SidebarCallout>` titles (`packages/app/src/components/sidebar-callout.tsx:175-180`).
 
 The rule, condensed: text that _names_ a surface or a group is `medium`. Text that lives _inside_ a surface or a group is `normal`. Top-of-screen titles are `<ScreenTitle>`, which is lighter still.
@@ -102,7 +102,7 @@ Five primitives. The pick is determined by option count, the need to search, and
 
 `<ContextMenu>` is for right-click and long-press on a target. The row is the trigger; there is no visible affordance. Used for incidental actions on workspace rows in the sidebar (`packages/app/src/components/sidebar-workspace-list.tsx`).
 
-`<AdaptiveModalSheet>` is for a focused task. Multi-field forms (`packages/app/src/components/add-host-modal.tsx`, `packages/app/src/components/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`), confirmations with detail, anything that earns a backdrop. Bottom sheet on compact, centered card on desktop. Raw `Modal` is wrong for any of these.
+`<AdaptiveModalSheet>` is for a focused task. Multi-field forms (`packages/app/src/hosts/add-host/internal/add-host-modal.tsx`, `packages/app/src/hosts/add-host/internal/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`), confirmations with detail, anything that earns a backdrop. Bottom sheet on compact, centered card on desktop. Raw `Modal` is wrong for any of these.
 
 `<AdaptiveModalSheet>` owns the presentation. Its content inset — the gutter that puts sheet content on the same rails as the sheet header — and compact bottom safe-area padding are the sheet's, not the caller's. A caller declares layout intent through `contentStyle` and never branches on form factor to add its own margins. If a sheet's first snap point is shorter than its header, content, and safe-area clearance, raise that snap point rather than moving the sheet container.
 
@@ -114,7 +114,7 @@ Three themes is `DropdownMenu`. Thirty hosts is `Combobox`. A label and a value
 
 ## 7. Density and rhythm
 
-Settings detail pages, the projects detail page, and any list+detail content sit inside a centered, max-width 720 column (`packages/app/src/screens/settings-screen.tsx`, `packages/app/src/screens/projects-screen.tsx`). Lines stay readable, the eye does not have to track wide horizontal distances. Form modals carry their own narrower content frame (`packages/app/src/components/add-host-modal.tsx`).
+Settings detail pages, the projects detail page, and any list+detail content sit inside a centered, max-width 720 column (`packages/app/src/screens/settings-screen.tsx`, `packages/app/src/screens/projects-screen.tsx`). Lines stay readable, the eye does not have to track wide horizontal distances. Form modals carry their own narrower content frame (`packages/app/src/hosts/add-host/internal/add-host-modal.tsx`).
 
 Workspace and chat surfaces use the full width — these are working surfaces, not reading surfaces. The composer carries `MAX_CONTENT_WIDTH` from `packages/app/src/constants/layout.ts` to keep lines readable while letting the workspace pane fill the rest.
 
@@ -278,7 +278,7 @@ New status pills use `<StatusBadge>`. Identity, shortcut, and interactive link b
 | List+detail (compact stack, desktop sidebar+pane)   | `packages/app/src/screens/settings-screen.tsx`, `packages/app/src/screens/projects-screen.tsx`                                                                                                                                                                                                           |
 | Detail card+row                                     | `packages/app/src/screens/settings/host-page.tsx`, `packages/app/src/screens/settings/providers-section.tsx`                                                                                                                                                                                             |
 | Section grouping inside a card list                 | `packages/app/src/screens/settings/settings-section.tsx`                                                                                                                                                                                                                                                 |
-| Form modal (label + input fields, primary + cancel) | `packages/app/src/components/add-host-modal.tsx`, `packages/app/src/components/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`                                                                                                                                              |
+| Form modal (label + input fields, primary + cancel) | `packages/app/src/hosts/add-host/internal/add-host-modal.tsx`, `packages/app/src/hosts/add-host/internal/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`                                                                                                                    |
 | Destructive confirmation                            | `confirmDialog` invoked from `packages/app/src/screens/settings/host-page.tsx:541-547`                                                                                                                                                                                                                   |
 | Centered hero / first-run                           | `packages/app/src/components/welcome-screen.tsx`                                                                                                                                                                                                                                                         |
 | Sidebar list (workspaces, hosts)                    | `packages/app/src/components/sidebar-workspace-list.tsx`, `packages/app/src/components/left-sidebar.tsx`                                                                                                                                                                                                 |

docs/expo-router.md

@@ -58,6 +58,12 @@ restore the same workspace and could repeat the crash.
 
 ## App-Wide Route Hops
 
+Keep Add host in `hosts/add-host`, opened through `useAddHost()`. It is an in-place
+flow; callers choose what happens after success. Settings opts into the new host’s
+Overview. Do not send callers to Settings with an `addHost` query parameter: a
+retained route replays that request when appearance changes remount its content.
+The flow provider and sheet host stay outside appearance keys so open drafts survive.
+
 When app-wide routes such as `/new`, `/settings`, or `/sessions` navigate back
 into a host workspace, use `navigateToWorkspace()`. Do not make the caller
 branch on its current route.

docs/plugins.md

@@ -357,9 +357,27 @@ keys are stored under a `param.` prefix; plugins never see it and may use any ke
 `openScreen` validates its input once (`parsePluginOpenScreenInput`); code past it trusts the
 params.
 
-RPC contracts validate inputs and outputs in both the app and plugin subprocess. `useRpc` returns a
-typed async function. Use the host-provided `@tanstack/react-query` for request state and caching;
-Paseo gives each plugin installation its own query client.
+RPC and subscription contracts validate inputs, outputs, and events in both the app and plugin
+subprocess. `useRpc` returns a typed async function. Use the host-provided `@tanstack/react-query`
+for request state and caching; Paseo gives each plugin installation its own query client.
+
+A subscription is a session-owned observation (`plugin-rpc` delivery family): the session that
+subscribed owns its lifetime, so release, disconnect, plugin stop, and reload need no plugin code.
+Each subscriber gets its own handler call in the subprocess; there is no fan-out or replay. The
+runtime buffers pushes until the session has sent `plugin.rpc.subscribe.response`, so a client
+never sees an event for an unknown subscription. The app installation's lifetime aborts every
+subscription its surfaces left open, and a reload replaces the installation, which resubscribes
+mounted hooks.
+
+The byte rule (a top-level `Uint8Array` is binary, a nested one is a validation error) is checked
+once per hop by `assertPluginWireValue`. Bytes ride plugin binary frames, opcodes `0x20`-`0x2f`
+(`packages/protocol/src/binary-frames/plugin.ts`); nothing on the path copies or re-encodes them,
+and `plugin-subscriptions.perf.e2e.test.ts` locks that. Keep it that way: never stringify a plugin
+payload for a log, and the client's bootstrap buffer holds bytes only until the first observer
+attaches. Binary outputs reach only clients that send `pluginBinaryPayloads`. A binary input
+frame (`0x22`) becomes a synthetic `plugin.rpc.invoke.request` and runs through the normal message
+path, so it is authorized like any other invoke. The author contract, including the native upload
+limit, is in [stream events from the daemon](../public-docs/plugins/reference.md#subscriptions).
 
 `usePaseo()` and the handler's `{ paseo }` context expose the same `PaseoApi`: projects,
 workspaces, agents, terminals, providers, and daemon config. They do not expose connection lifecycle.

nix/desktop-package.nix

@@ -127,7 +127,7 @@ buildNpmPackage {
         # The Nix output is not a distributable DMG, so leave it unsigned and
         # disable the hardened runtime that requires a matching signature.
         CSC_IDENTITY_AUTO_DISCOVERY=false \
-          ../../node_modules/.bin/electron-builder \
+          npm exec --offline -- electron-builder \
             --config electron-builder.yml \
             --dir \
             --mac \

nix/npm-deps.hash

@@ -1 +1 @@
-sha256-CeT2PtYIAFwvBC9LIku8VkTl0pvKxYzSCn0QW2ManfU=
+sha256-KN/AVZV/o0TleLLpmggSrdJqjFDJ/NJYVHiC54xb4jQ=

packages/app/e2e/browser/add-project-flow.spec.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { test, expect } from "../support/fixtures";
 import {
   addProjectFlow,
+  chooseAddHostFromProjectFlow,
   addProjectFlowBack,
   addProjectFlowHost,
   addProjectFlowInput,
@@ -19,6 +20,7 @@ import {
 } from "../support/helpers/add-project-flow";
 import { gotoAppShell } from "../support/helpers/app";
 import {
+  disconnectAllHostsAndReload,
   addConnectedHostAndReload,
   addConnectedHostsAndReload,
   addOfflineHostAndReload,
@@ -69,6 +71,19 @@ async function expectProjectHasNoWorkspaces(projectId: string): Promise<void> {
 test.describe("Add Project command-center flow", () => {
   test.describe.configure({ timeout: 180_000 });
 
+  test("Add host replaces the project dialog when no hosts are connected", async ({ page }) => {
+    await gotoAppShell(page);
+    await disconnectAllHostsAndReload(page);
+    await openAddProjectHostSelection(page);
+    const originalUrl = page.url();
+    await chooseAddHostFromProjectFlow(page);
+    await expect(addProjectFlow(page)).toBeHidden();
+    await expect(
+      page.getByRole("button", { name: "Direct connection", exact: true }),
+    ).toBeVisible();
+    await expect(page).toHaveURL(originalUrl);
+  });
+
   test("method selection shows the daemon's available project sources without search", async ({
     page,
   }) => {

packages/app/e2e/browser/composer-recall.spec.ts

@@ -3,7 +3,7 @@ import {
   composerLocator,
   expectComposerDraft,
   expectComposerVisible,
-  submitMessage,
+  fillComposerDraft,
   typeIntoFocusedComposer,
 } from "../support/helpers/composer";
 import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
@@ -12,8 +12,14 @@ function userMessages(page: Page) {
   return page.getByTestId("user-message");
 }
 
+async function sendDraftWhenReady(page: Page) {
+  await expect(page.getByRole("button", { name: "Send message", exact: true })).toBeEnabled();
+  await pressInComposer(page, "Enter");
+}
+
 async function sendAndWaitForMessage(page: Page, text: string, expectedCount: number) {
-  await submitMessage(page, text);
+  await fillComposerDraft(page, text);
+  await sendDraftWhenReady(page);
   await expect(userMessages(page)).toHaveCount(expectedCount, { timeout: 30_000 });
   await expectComposerDraft(page, "");
 }
@@ -49,7 +55,7 @@ test.describe("Composer recall", () => {
       await pressInComposer(page, "ArrowUp");
       await expectComposerDraft(page, "add tests for login");
 
-      await pressInComposer(page, "Enter");
+      await sendDraftWhenReady(page);
       await expect(userMessages(page)).toHaveCount(3, { timeout: 30_000 });
       await expect(userMessages(page).last()).toContainText("add tests for login");
     } finally {

packages/app/e2e/browser/file-explorer-context-actions.spec.ts

@@ -294,10 +294,17 @@ test("creates, renames, copies, and deletes entries through the file explorer",
 
   await entry("renamed.txt").click({ button: "right" });
   const deleteAction = page.getByTestId(/file-explorer-row-\d+-delete$/);
-  const deleteLabelColor = await deleteAction
-    .getByText("Delete", { exact: true })
-    .evaluate((element) => getComputedStyle(element).color);
-  await expect(deleteAction.locator("svg")).toHaveCSS("stroke", deleteLabelColor);
+  await expect
+    .poll(async () => {
+      const labelColor = await deleteAction
+        .getByText("Delete", { exact: true })
+        .evaluate((element) => getComputedStyle(element).color);
+      const iconColor = await deleteAction
+        .locator("svg")
+        .evaluate((element) => getComputedStyle(element).stroke);
+      return labelColor !== "" && iconColor === labelColor;
+    })
+    .toBe(true);
   const cancelledConfirmation = new Promise<string>((resolve) => {
     page.once("dialog", async (dialog) => {
       const message = dialog.message();

packages/app/e2e/browser/new-workspace-entry.spec.ts

@@ -122,10 +122,14 @@ test.describe("New workspace entry points", () => {
       });
       const hostTrigger = page.getByTestId("host-picker-trigger");
       await expect(hostTrigger).toContainText("localhost", { timeout: 30_000 });
+      const originalUrl = page.url();
       await hostTrigger.click();
       await expect(page.getByTestId("new-workspace-host-picker-add-host")).toBeVisible();
       await page.getByTestId("new-workspace-host-picker-add-host").click();
-      await expect(page).toHaveURL(/\/settings\/general\?addHost=/);
+      await expect(
+        page.getByRole("button", { name: "Direct connection", exact: true }),
+      ).toBeVisible();
+      await expect(page).toHaveURL(originalUrl);
     } finally {
       await seeded.cleanup();
     }

packages/app/e2e/browser/plugin-subscription-examples.spec.ts

@@ -0,0 +1,79 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, test, type Page } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import { openCommandCenter } from "../support/helpers/command-center";
+import { connectNewWorkspaceDaemonClient } from "../support/helpers/new-workspace";
+import { copyPluginExample } from "../support/helpers/plugin-fixture";
+import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
+import { getServerId } from "../support/helpers/server-id";
+import {
+  switchWorkspaceViaSidebar,
+  waitForWorkspaceInSidebar,
+} from "../support/helpers/workspace-ui";
+
+async function runCommand(page: Page, title: string): Promise<void> {
+  const panel = await openCommandCenter(page);
+  await panel.getByTestId("command-center-input").fill(title);
+  await panel.getByRole("button", { name: title, exact: true }).click();
+  await expect(panel).not.toBeVisible();
+}
+
+/** Installs a plugin example, opens a seeded workspace, and runs `exercise` against them. */
+async function withExample(
+  page: Page,
+  example: { name: string; id: string },
+  exercise: (workspace: SeededWorkspace) => Promise<void>,
+): Promise<void> {
+  const client = await connectNewWorkspaceDaemonClient({ ownProjects: false });
+  const previous = await client.getDaemonConfig();
+  const copy = await copyPluginExample(example.name);
+  const workspace = await seedWorkspace({ repoPrefix: `${example.name}-` });
+  try {
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(copy.directory);
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await gotoAppShell(page);
+    const target = { serverId: getServerId(), workspaceId: workspace.workspaceId };
+    await waitForWorkspaceInSidebar(page, target);
+    await switchWorkspaceViaSidebar({ page, ...target });
+    await exercise(workspace);
+  } finally {
+    try {
+      await client.removePlugin(example.id);
+    } finally {
+      await client.patchDaemonConfig({ pluginsEnabled: previous.config.pluginsEnabled });
+      await workspace.cleanup();
+      await client.close();
+      await copy.cleanup();
+    }
+  }
+}
+
+test.describe("plugin subscriptions", () => {
+  test.describe.configure({ timeout: 180_000 });
+
+  test("a panel follows events the daemon pushes as files change", async ({ page }) => {
+    await withExample(page, { name: "diff-watch", id: "diff-watch" }, async (workspace) => {
+      await runCommand(page, "Open live changes");
+      await expect(page.getByText("No changes", { exact: true })).toBeVisible();
+
+      await writeFile(path.join(workspace.repoPath, "pushed.txt"), "from the test\n");
+      await expect(page.getByText("1 file changed", { exact: true })).toBeVisible();
+      await expect(page.getByText("pushed.txt", { exact: true })).toBeVisible();
+    });
+  });
+
+  test("a panel plays streamed bytes and sends bytes back", async ({ page }) => {
+    await withExample(page, { name: "media-stream", id: "media-stream" }, async () => {
+      await runCommand(page, "Open media stream");
+      await expect(page.getByText("live", { exact: true })).toBeVisible();
+      await expect(page.getByText(/^[1-9]\d* video frames/)).toBeVisible();
+
+      await page.getByRole("button", { name: "Send this frame back", exact: true }).click();
+      await expect(
+        page.getByText(/^The daemon received [1-9]\d* bytes, sha256 [0-9a-f]{12}$/),
+      ).toBeVisible();
+    });
+  });
+});

packages/app/e2e/browser/question-prompt-pagination.spec.ts

@@ -108,10 +108,7 @@ test.describe("Question option text", () => {
     }
   });
 
-  test("selecting description text never answers, and the label still does", async ({
-    page,
-    context,
-  }) => {
+  test("selecting description text keeps the question open", async ({ page, context }) => {
     test.setTimeout(180_000);
     const { session, card } = await openLinkedQuestions(page, context);
     try {
@@ -120,16 +117,13 @@ test.describe("Question option text", () => {
 
       await dragAcross(page, description);
       await expect.poll(() => selectedText(page)).toBe(DONE_DESCRIPTION);
-      await expectChecked(done, false);
-
       await description.getByText("Logs are at", { exact: false }).dblclick({
         position: { x: 4, y: 4 },
       });
       await expect.poll(() => selectedText(page)).toBe("Logs");
       await expectCurrentQuestion(page, { index: 1, total: 2, question: LINKED_QUESTION });
-      await expectChecked(done, false);
-
-      await done.getByText("Done", { exact: true }).click();
+      await expectChecked(done, true);
+      await continueToNextQuestion(page);
       await expectCurrentQuestion(page, { index: 2, total: 2, question: CHECKS_QUESTION });
       await openQuestion(page, { index: 1, total: 2 });
       await expectChecked(done, true);
@@ -138,11 +132,17 @@ test.describe("Question option text", () => {
     }
   });
 
-  test("double-clicking a single-select label answers once", async ({ page, context }) => {
+  test("double-clicking a single-select label selects once without advancing", async ({
+    page,
+    context,
+  }) => {
     test.setTimeout(180_000);
     const { session, card } = await openLinkedQuestions(page, context);
     try {
       await card.getByRole("radio", { name: "Done" }).getByText("Done", { exact: true }).dblclick();
+      await expectCurrentQuestion(page, { index: 1, total: 2, question: LINKED_QUESTION });
+      await expectChecked(card.getByRole("radio", { name: "Done" }), true);
+      await continueToNextQuestion(page);
 
       await expectCurrentQuestion(page, { index: 2, total: 2, question: CHECKS_QUESTION });
       await expectChecked(card.getByRole("checkbox", { name: "Lint" }), false);
@@ -154,14 +154,12 @@ test.describe("Question option text", () => {
     }
   });
 
-  test("multi-select description links and selection leave the option unchanged", async ({
-    page,
-    context,
-  }) => {
+  test("multi-select descriptions support links and text selection", async ({ page, context }) => {
     test.setTimeout(180_000);
     const { session, card } = await openLinkedQuestions(page, context);
     try {
       await card.getByRole("radio", { name: "Done" }).getByText("Done", { exact: true }).click();
+      await continueToNextQuestion(page);
       await expectCurrentQuestion(page, { index: 2, total: 2, question: CHECKS_QUESTION });
 
       const lint = card.getByRole("checkbox", { name: "Lint" });
@@ -177,18 +175,16 @@ test.describe("Question option text", () => {
 
       await dragAcross(page, description);
       await expect.poll(() => selectedText(page)).toBe(LINT_DESCRIPTION);
-      await expectChecked(lint, false);
-
       await description.getByText("Rules:", { exact: false }).dblclick({
         position: { x: 4, y: 4 },
       });
       await expect.poll(() => selectedText(page)).toBe("Rules");
-      await expectChecked(lint, false);
+      await expectChecked(lint, true);
 
       await typecheck.getByText("Typecheck", { exact: true }).dblclick();
       await expectChecked(typecheck, true);
       await lint.getByText("Lint", { exact: true }).click();
-      await expectChecked(lint, true);
+      await expectChecked(lint, false);
     } finally {
       await session.cleanup();
     }
@@ -268,6 +264,7 @@ test.describe("Question prompt pagination", () => {
       await expectQuestionHidden(page, SUCCESS_QUESTION);
 
       await chooseQuestionOption(page, "App");
+      await continueToNextQuestion(page);
       await expectCurrentQuestion(page, {
         index: 2,
         total: TOTAL_QUESTIONS,
@@ -288,6 +285,7 @@ test.describe("Question prompt pagination", () => {
         preview: 'flags.enabled("new-surface")',
       });
       await chooseQuestionOption(page, "Behind feature flag");
+      await continueToNextQuestion(page);
       await expectCurrentQuestion(page, {
         index: 3,
         total: TOTAL_QUESTIONS,
@@ -466,7 +464,9 @@ retryTest(
     retryTest.setTimeout(180_000);
     const card = page.getByTestId("question-form-card");
     await chooseQuestionOption(page, "App");
+    await continueToNextQuestion(page);
     await chooseQuestionOption(page, "Behind feature flag");
+    await continueToNextQuestion(page);
     await fillQuestionAnswer(page, {
       question: SUCCESS_QUESTION,
       answer: "Preserve my answers after a failed submission.",
@@ -520,7 +520,9 @@ retryTest(
     const card = page.getByTestId("question-form-card");
     questionClient.releaseFirstResponse();
     await chooseQuestionOption(page, "App");
+    await continueToNextQuestion(page);
     await chooseQuestionOption(page, "Behind feature flag");
+    await continueToNextQuestion(page);
     await fillQuestionAnswer(page, {
       question: SUCCESS_QUESTION,
       answer: "Start with the internal team.",

packages/app/e2e/browser/settings-host-page.spec.ts

@@ -1,3 +1,8 @@
+import {
+  openGlobalNewWorkspaceComposer,
+  fillNewWorkspaceDraft,
+  expectNewWorkspaceDraft,
+} from "../support/helpers/new-workspace";
 import { readFile, mkdir, rename, rm } from "node:fs/promises";
 import path from "node:path";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
@@ -273,3 +278,71 @@ test("restart recovery host controls persist the opt-out and custom prompt", asy
   await expectRestartRecoveryPrompt(page, "Continue the interrupted work.");
   await editRestartRecoveryPrompt(page, "Resume working.");
 });
+
+test("sidebar Add host preserves its caller and stays closed after theme changes", async ({
+  page,
+}) => {
+  await gotoAppShell(page);
+  await expect(page).toHaveURL(/\/open-project$/);
+  const originalUrl = page.url();
+  await openSidebarAddHost(page);
+  await expect(page).toHaveURL(originalUrl);
+  await closeAddHostAndChangeTheme(page);
+  await expect(page.getByRole("button", { name: "Direct connection", exact: true })).toBeHidden();
+  await expect(page).toHaveURL(originalUrl);
+});
+
+async function openSidebarAddHost(page: import("@playwright/test").Page) {
+  await page.getByRole("button", { name: "Hosts", exact: true }).click();
+  await page.getByRole("button", { name: "Add host", exact: true }).click();
+  await expect(page.getByRole("button", { name: "Direct connection", exact: true })).toBeVisible();
+}
+
+async function closeAddHostAndChangeTheme(page: import("@playwright/test").Page) {
+  await page.getByRole("button", { name: "Close", exact: true }).click();
+  await expect(page.getByRole("button", { name: "Direct connection", exact: true })).toBeHidden();
+  await page.keyboard.press("Control+Alt+t");
+}
+
+test("sidebar Add host completes without navigating", async ({ page }) => {
+  await gotoAppShell(page);
+  await expect(page).toHaveURL(/\/open-project$/);
+  const originalUrl = page.url();
+  await openSidebarAddHost(page);
+  await connectToTestHost(page);
+  await expect(page).toHaveURL(originalUrl);
+  await expect(page.getByRole("button", { name: "Hosts", exact: true })).toBeVisible();
+});
+
+test("Settings Add host opens the saved host Overview", async ({ page }) => {
+  await gotoAppShell(page);
+  await openSettings(page);
+  await addDirectHostFromSettings(page, { host: "127.0.0.1", port: Number(getE2EDaemonPort()) });
+  await expectSettingsHeader(page, "Overview");
+  await expect(page).toHaveURL(new RegExp(`/settings/hosts/${getServerId()}/host$`));
+});
+
+test("New workspace Add host preserves the prompt after connecting", async ({ page }) => {
+  await gotoAppShell(page);
+  await openGlobalNewWorkspaceComposer(page);
+  await fillNewWorkspaceDraft(page, "Keep this unfinished prompt while I add a host.");
+  const originalUrl = page.url();
+  await openNewWorkspaceAddHost(page);
+  await expect(page).toHaveURL(originalUrl);
+  await connectToTestHost(page);
+  await expect(page).toHaveURL(originalUrl);
+  await expectNewWorkspaceDraft(page, "Keep this unfinished prompt while I add a host.");
+});
+
+async function openNewWorkspaceAddHost(page: import("@playwright/test").Page) {
+  await page.getByTestId("host-picker-trigger").click();
+  await page.getByRole("button", { name: "Add host", exact: true }).click();
+}
+
+async function connectToTestHost(page: import("@playwright/test").Page) {
+  await page.getByRole("button", { name: "Direct connection", exact: true }).click();
+  await page.getByRole("textbox", { name: "Host", exact: true }).fill("127.0.0.1");
+  await page.getByRole("textbox", { name: "Port", exact: true }).fill(String(getE2EDaemonPort()));
+  await page.getByRole("button", { name: "Connect", exact: true }).click();
+  await expect(page.getByTestId("add-host-modal")).toBeHidden({ timeout: 30_000 });
+}

packages/app/e2e/support/helpers/add-project-flow.ts

@@ -113,3 +113,7 @@ export async function expectAddProjectResultVisible(page: Page, text: string): P
     })
     .toBe(true);
 }
+
+export async function chooseAddHostFromProjectFlow(page: Page): Promise<void> {
+  await page.getByRole("button", { name: /Add host.*No connected hosts/ }).click();
+}

packages/app/e2e/support/helpers/hosts.ts

@@ -273,3 +273,25 @@ export async function reloadPreservingHostRegistry(page: Page): Promise<void> {
   );
   await page.reload();
 }
+
+export async function disconnectAllHostsAndReload(page: Page): Promise<void> {
+  await page.evaluate(
+    ({ registryKey, nonceKey, disableSeedKey }) => {
+      const nonce = localStorage.getItem(nonceKey);
+      if (!nonce) throw new Error("Expected the e2e seed nonce");
+      const hosts = JSON.parse(localStorage.getItem(registryKey) ?? "[]");
+      for (const host of hosts) {
+        host.connections = [{ id: "offline", type: "directTcp", endpoint: "127.0.0.1:59999" }];
+        host.preferredConnectionId = "offline";
+      }
+      localStorage.setItem(registryKey, JSON.stringify(hosts));
+      localStorage.setItem(disableSeedKey, nonce);
+    },
+    {
+      registryKey: REGISTRY_KEY,
+      nonceKey: SEED_NONCE_KEY,
+      disableSeedKey: DISABLE_DEFAULT_SEED_ONCE_KEY,
+    },
+  );
+  await page.reload();
+}

packages/app/src/agent-stream/presentation.test.ts

@@ -69,6 +69,9 @@ function installProbe(
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
   };
 }
 

packages/app/src/app/_layout.tsx

@@ -1,3 +1,4 @@
+import { AddHostProvider, AddHostFlowHost } from "@/hosts/add-host";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { useActiveWorkspaceSelection } from "@/stores/navigation-active-workspace-store";
 import { useIsExplorerSidebarOpen } from "@/workspace-tabs/explorer-sidebar";
@@ -465,6 +466,7 @@ function AppContainer({ children, chromeEnabled: chromeEnabledOverride }: AppCon
   const surface = (
     <View style={layoutStyles.surfaceFill}>
       {workspaceChrome}
+      <AddHostFlowHost />
       <AppearanceStyleBoundary>
         {!isCompactLayout && appChromeLayout.sidebarToggleOwner === "window" ? (
           <WindowChromeRegion corners="top-left">
@@ -805,7 +807,6 @@ function RootStack() {
         <Stack.Screen name="open-project" />
         <Stack.Screen name="sessions" />
         <Stack.Screen name="schedules" />
-        <Stack.Screen name="pair-scan" />
       </Stack.Protected>
       <Stack.Screen name="h/[serverId]" />
       <Stack.Screen name="settings/hosts/[serverId]/index" />
@@ -890,11 +891,13 @@ function RootAppTree() {
     <GestureHandlerRootView style={flexStyle}>
       <View style={layoutStyles.surfaceFill}>
         <LucideProvider strokeWidth={ICON_STROKE_WIDTH}>
-          <RootProviders>
-            <RuntimeProviders>
-              <AppShell />
-            </RuntimeProviders>
-          </RootProviders>
+          <AddHostProvider>
+            <RootProviders>
+              <RuntimeProviders>
+                <AppShell />
+              </RuntimeProviders>
+            </RootProviders>
+          </AddHostProvider>
         </LucideProvider>
       </View>
     </GestureHandlerRootView>

packages/app/src/app/settings/[section].tsx

@@ -35,10 +35,9 @@ function SettingsDaemonRedirect() {
 }
 
 export default function SettingsSectionRoute() {
-  const params = useLocalSearchParams<{ section?: string; addHost?: string }>();
+  const params = useLocalSearchParams<{ section?: string }>();
   const rawSection = typeof params.section === "string" ? params.section : "";
   const section: SettingsSectionSlug = isSettingsSectionSlug(rawSection) ? rawSection : "general";
-  const openAddHostIntent = typeof params.addHost === "string" ? params.addHost : null;
   const view = useMemo(() => ({ kind: "section" as const, section }), [section]);
 
   // COMPAT(settingsDaemonRedirect): added 2026-07-08, remove after 2027-01-08.
@@ -50,5 +49,5 @@ export default function SettingsSectionRoute() {
     );
   }
 
-  return <SettingsScreen view={view} openAddHostIntent={openAddHostIntent} />;
+  return <SettingsScreen view={view} />;
 }

packages/app/src/components/add-project-flow.tsx

@@ -1,3 +1,4 @@
+import { useAddHost } from "@/hosts/add-host";
 import { Modal } from "@/components/ui/modal";
 import { usePanelStore } from "@/stores/panel-store";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
@@ -92,7 +93,7 @@ import { useRecommendedProjectPaths } from "@/stores/session-store-hooks";
 import type { AddProjectFlowRequest } from "@/stores/add-project-flow-store";
 import type { Theme } from "@/styles/theme";
 import { shortenPath } from "@/utils/shorten-path";
-import { buildNewWorkspaceRoute, buildSettingsAddHostRoute } from "@/utils/host-routes";
+import { buildNewWorkspaceRoute } from "@/utils/host-routes";
 
 interface AddProjectFlowProps {
   request: AddProjectFlowRequest;
@@ -325,6 +326,7 @@ function setPageStatus(
 // The product flow is intentionally one cohesive page-stack state machine.
 // eslint-disable-next-line complexity
 export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
+  const addHost = useAddHost();
   const hosts = useHosts();
   const hostIds = useMemo(() => hosts.map((host) => host.serverId), [hosts]);
   const connectionStatuses = useHostRuntimeConnectionStatuses(hostIds);
@@ -616,9 +618,9 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
           icon: Plus,
           testID: "add-project-flow-add-host",
           select: () => {
+            // The native project Modal must release its window before the root sheet opens.
             onClose();
-            usePanelStore.getState().showMobileAgent();
-            router.push(buildSettingsAddHostRoute(Date.now()));
+            addHost();
           },
         });
       }
@@ -717,6 +719,7 @@ export function AddProjectFlow({ request, onClose }: AddProjectFlowProps) {
     directoryPaths,
     githubQuery.data,
     host,
+    addHost,
     onClose,
     openAddedProject,
     page,

packages/app/src/components/left-sidebar.tsx

@@ -1,3 +1,4 @@
+import { useAddHost } from "@/hosts/add-host";
 import { router } from "expo-router";
 import {
   CircleGauge,
@@ -62,7 +63,7 @@ import { usePanelStore } from "@/stores/panel-store";
 import { useOwnsWindowChromeCorner, WindowChromeSafeArea } from "@/utils/desktop-window";
 import { useCloseAgentListGesture } from "@/mobile-panels/gestures";
 import { MobilePanelOverlay } from "@/mobile-panels/presentation";
-import { buildSettingsAddHostRoute, buildSettingsRoute } from "@/utils/host-routes";
+import { buildSettingsRoute } from "@/utils/host-routes";
 import { openHostOverview } from "@/navigation/settings-navigation";
 import { UsageSidebarItem, UsageSidebarRoot, useUsageSummary, useOpenSidebarUsage } from "@/usage";
 import { SidebarAgentListSkeleton } from "./sidebar-agent-list-skeleton";
@@ -177,14 +178,8 @@ export const LeftSidebar = memo(function LeftSidebar({ active }: { active: boole
     router.push(buildSettingsRoute());
   }, []);
 
-  const handleAddHostMobile = useCallback(() => {
-    showMobileAgent();
-    router.push(buildSettingsAddHostRoute(Date.now()));
-  }, [showMobileAgent]);
-
-  const handleAddHostDesktop = useCallback(() => {
-    router.push(buildSettingsAddHostRoute(Date.now()));
-  }, []);
+  const handleAddHostMobile = useAddHost();
+  const handleAddHostDesktop = handleAddHostMobile;
 
   const handleOpenHostSettingsMobile = useCallback(
     (serverId: string) => {

packages/app/src/components/markdown/renderer.test.ts

@@ -130,6 +130,186 @@ it("preserves empty table cells while escaping spoilers in cell text", () => {
   );
 });
 
+it("renders a table directly after a paragraph through the library parser", async () => {
+  const source = "**Notes**\n| Item | Detail |\n| --- | --- |\n| A | one |\n| B | two |";
+  const separated = "**Notes**\n\n| Item | Detail |\n| --- | --- |\n| A | one |\n| B | two |";
+  const flags = { hardSoftBreaks: true, latexMath: false };
+  const expected = await parseMarkdown(separated, flags);
+  expect(expected.children?.map((node) => node.type)).toEqual(["Paragraph", "Table"]);
+  expect(await parseMarkdown(prepareMarkdownSource(source).render(), flags)).toEqual(expected);
+});
+
+it.each([
+  [
+    "a quote",
+    "> Notes\n> | Item |\n> | --- |\n> | A |",
+    "> Notes\n>\n> | Item |\n> | --- |\n> | A |",
+    ["Document", ["Blockquote", "Paragraph", "Table"]],
+  ],
+  [
+    "a list item",
+    "- Notes\n  | Item |\n  | --- |\n  | A |\n- Next",
+    "- Notes\n\n  | Item |\n  | --- |\n  | A |\n- Next",
+    ["Document", ["UnorderedList", ["ListItem", "Paragraph", "Table"], ["ListItem", "Paragraph"]]],
+  ],
+  [
+    "a quoted list item",
+    "> - Notes\n>   | Item |\n>   | --- |\n>   | A |",
+    "> - Notes\n>\n>   | Item |\n>   | --- |\n>   | A |",
+    ["Document", ["Blockquote", ["UnorderedList", ["ListItem", "Paragraph", "Table"]]]],
+  ],
+  [
+    "a quote inside a list item",
+    "- > Notes\n  > | Item |\n  > | --- |\n  > | A |",
+    "- > Notes\n  >\n  > | Item |\n  > | --- |\n  > | A |",
+    ["Document", ["UnorderedList", ["ListItem", ["Blockquote", "Paragraph", "Table"]]]],
+  ],
+  [
+    "aligned columns without outer pipes",
+    "Notes\nItem | Detail\n:--- | ---:\nA | one",
+    "Notes\n\nItem | Detail\n:--- | ---:\nA | one",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "an entity at the start of a header without outer pipes",
+    "Notes\nAT&T | Detail\n--- | ---\nA | one",
+    "Notes\n\nAT\\&T | Detail\n--- | ---\nA | one",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "a local image at the start of a header without outer pipes",
+    "Notes\n![Local](assets/a.png) | Detail\n--- | ---\nA | one",
+    "Notes\n\nLocal | Detail\n--- | ---\nA | one",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "CRLF lines",
+    "Notes\r\n| Item |\r\n| --- |\r\n| A |",
+    "Notes\r\n\r\n| Item |\r\n| --- |\r\n| A |",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "CR lines",
+    "Notes\r| Item |\r| --- |\r| A |",
+    "Notes\r\r| Item |\r| --- |\r| A |",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "a quote with CRLF lines",
+    "> Notes\r\n> | Item |\r\n> | --- |\r\n> | A |",
+    "> Notes\r\n>\r\n> | Item |\r\n> | --- |\r\n> | A |",
+    ["Document", ["Blockquote", "Paragraph", "Table"]],
+  ],
+  [
+    "a list item with CRLF lines",
+    "- Notes\r\n  | Item |\r\n  | --- |\r\n  | A |\r\n- Next",
+    "- Notes\r\n\r\n  | Item |\r\n  | --- |\r\n  | A |\r\n- Next",
+    ["Document", ["UnorderedList", ["ListItem", "Paragraph", "Table"], ["ListItem", "Paragraph"]]],
+  ],
+  [
+    "a quote with CR lines",
+    "> Notes\r> | Item |\r> | --- |\r> | A |",
+    "> Notes\r>\r> | Item |\r> | --- |\r> | A |",
+    ["Document", ["Blockquote", "Paragraph", "Table"]],
+  ],
+  [
+    "a list item with CR lines",
+    "- Notes\r  | Item |\r  | --- |\r  | A |\r- Next",
+    "- Notes\r\r  | Item |\r  | --- |\r  | A |\r- Next",
+    ["Document", ["UnorderedList", ["ListItem", "Paragraph", "Table"], ["ListItem", "Paragraph"]]],
+  ],
+  [
+    "a non-interrupting ordered marker with tildes",
+    "Intro\n2. ~~~\n   Notes\n   | A |\n   | --- |\n   | x |",
+    "Intro\n2. ~~~\n   Notes\n\n   | A |\n   | --- |\n   | x |",
+    ["Document", "Paragraph", "Table"],
+  ],
+  [
+    "a non-interrupting ordered marker with backticks",
+    "Notes\n2. ```\n   | Item |\n   | --- |\n   | A |",
+    "Notes\n2. ```\n\n   | Item |\n   | --- |\n   | A |",
+    ["Document", "Paragraph", "Table"],
+  ],
+])("preserves tables after paragraphs in %s", async (_name, source, separated, expected) => {
+  const rendered = prepareMarkdownSource(source).render();
+  expect(rendered).toEqual(separated);
+  const flags = { hardSoftBreaks: true, latexMath: false };
+  function blocks(node: ASTNode): unknown {
+    if (node.type === "Paragraph" || node.type === "Table") return node.type;
+    return [node.type, ...(node.children ?? []).map(blocks)];
+  }
+  expect(blocks(await parseMarkdown(rendered, flags))).toEqual(expected);
+});
+
+it.each([
+  [
+    "a literal backslash",
+    "Notes\\\n| Item |\n| --- |\n| A |",
+    "Notes\\\n\n| Item |\n| --- |\n| A |",
+    "Notes\\",
+  ],
+  [
+    "an entity and literal backslash with LF lines",
+    "AT&T\\\n| Item |\n| --- |\n| A |",
+    "AT\\&T\\\n\n| Item |\n| --- |\n| A |",
+    "AT&T\\",
+  ],
+  [
+    "an entity and literal backslash with CRLF lines",
+    "AT&T\\\r\n| Item |\r\n| --- |\r\n| A |",
+    "AT\\&T\\\r\n\r\n| Item |\r\n| --- |\r\n| A |",
+    "AT&T\\",
+  ],
+  [
+    "an entity and literal backslash with CR lines",
+    "AT&T\\\r| Item |\r| --- |\r| A |",
+    "AT\\&T\\\r\r| Item |\r| --- |\r| A |",
+    "AT&T\\",
+  ],
+])(
+  "preserves paragraph text before an interrupting table in %s",
+  async (_name, source, separated, text) => {
+    const rendered = prepareMarkdownSource(source).render();
+    expect(rendered).toEqual(separated);
+    const tree = await parseMarkdown(rendered, { hardSoftBreaks: true, latexMath: false });
+    expect(tree.children?.map((node) => node.type)).toEqual(["Paragraph", "Table"]);
+    expect(tree.children?.[0]?.children?.map((node) => node.content).join("")).toEqual(text);
+  },
+);
+
+it.each([
+  "```yaml\n---\nkey: value\n---\n```\n",
+  "~~~md\n| Item |\n| --- |\n| A |\n~~~\n",
+  "````md\n```\n| Item |\n| --- |\n```\n`````\n",
+  "> ```md\n> | Item |\n> | --- |\n> ```\n",
+  "> ```md\n> Code\n",
+  "- ```md\n  Code\n",
+  "    ```\n\n",
+  "```not`a-fence\n",
+])("renders a table after a fence without changing its code: %s", async (prefix) => {
+  const table = "| Item |\n| --- |\n| A |";
+  const rendered = prepareMarkdownSource(`${prefix}Notes\n${table}`).render();
+  expect(rendered).toEqual(`${prefix}Notes\n\n${table}`);
+  const tree = await parseMarkdown(rendered, { hardSoftBreaks: true, latexMath: false });
+  expect(tree.children?.slice(-2).map((node) => node.type)).toEqual(["Paragraph", "Table"]);
+});
+
+it.each([
+  "| Item | Detail |\n| --- | --- |\n" + "| A | one |\n".repeat(100),
+  "Notes\n\n| Item | Detail |\n| --- | --- |\n" + "| A | one |\n".repeat(100),
+  "Notes\n\n| Item |\n| --- |\n| A |",
+  "| Item |\n| --- |\n| A |",
+  "```md\nNotes\n| Item |\n| --- |\n| A |\n```",
+  "```yaml\n---\nkey: value\n---\n```",
+  "```yaml\n---\nkey: value",
+  "~~~md\n| Item |\n| --- |\n| A |\n~~~",
+  "````md\n```\n| Item |\n| --- |\n```\n````",
+  "    Notes\n    | Item |\n    | --- |\n    | A |",
+  "Notes\n| Item | Detail |\n| --- |\n| A |",
+])("leaves separated tables and table-like text unchanged: %s", (source) => {
+  expect(prepareMarkdownSource(source).render()).toEqual(source);
+});
+
 it.each([
   "src/components/message.tsx",
   "C:\\repo\\file.ts",

packages/app/src/components/markdown/source.ts

@@ -138,6 +138,10 @@ export function prepareMarkdownSource(
     !source.includes("![") &&
     !source.includes("||") &&
     !source.includes("&") &&
+    // Match content, header, and delimiter lines; quote-only lines count as blank.
+    !/^[\t >]*[^\t >\r\n][^\r\n]*(?:\r\n|\r|\n)[^\r\n]+(?:\r\n|\r|\n)(?=[\t >:|-]*\|)[\t >|]*:?-[-\t :|]*$/m.test(
+      source,
+    ) &&
     !(workspaceRoot && source.includes("]("))
   ) {
     return { images, ...metadata, render: () => source };
@@ -212,11 +216,25 @@ export function prepareMarkdownSource(
       if (lineEnd < end) split(lineEnd);
     }
   }
-  function visit(node: Nodes) {
-    const start = node.position?.start.offset;
-    const end = node.position?.end.offset;
-    if (start !== undefined && end !== undefined) {
+  function visit(node: Nodes, previous?: Nodes) {
+    const position = node.position;
+    if (position?.start.offset !== undefined && position.end.offset !== undefined) {
+      const start = position.start.offset;
+      const end = position.end.offset;
       if (node.type === "paragraph") splitStandaloneImages(node, start, end);
+      if (
+        node.type === "table" &&
+        previous?.type === "paragraph" &&
+        previous.position?.end.line === position.start.line - 1
+      ) {
+        // MD4C only recognizes a table header on the first line of a paragraph.
+        const lineStart =
+          Math.max(source.lastIndexOf("\n", start - 1), source.lastIndexOf("\r", start - 1)) + 1;
+        const newline = source.slice(lineStart - 2, lineStart).replace(/[^\r\n]/g, "");
+        const blank = source.slice(lineStart, start).replace(/[^>]/g, " ").trimEnd();
+        const boundary = lineStart - newline.length;
+        edits.push({ start: boundary, end: lineStart, text: `${newline}${blank}${newline}` });
+      }
       if (node.type === "link") {
         const title = workspaceHoverTitle(node, source.slice(start, end), workspaceRoot);
         if (title !== null)
@@ -244,7 +262,8 @@ export function prepareMarkdownSource(
         if (text !== source.slice(start, end)) edits.push({ start, end, text });
       }
     }
-    if ("children" in node) node.children.forEach(visit);
+    if ("children" in node)
+      node.children.forEach((child, index) => visit(child, node.children[index - 1]));
   }
   visit(getTree());
   return {

packages/app/src/components/question-form-card.browser.test.tsx

@@ -39,7 +39,10 @@ afterEach(() => {
   }
 });
 
-function buildPermission(question: Record<string, unknown>): PendingPermission {
+function buildPermission(
+  question: Record<string, unknown>,
+  following: Record<string, unknown>[] = [],
+): PendingPermission {
   return {
     key: "perm-1",
     agentId: "agent-1",
@@ -48,12 +51,12 @@ function buildPermission(question: Record<string, unknown>): PendingPermission {
       provider: "claude",
       name: "AskUserQuestion",
       kind: "question",
-      input: { questions: [question] },
+      input: { questions: [question, ...following] },
     },
   };
 }
 
-function mountCard(question: Record<string, unknown>) {
+function mountCard(question: Record<string, unknown>, following: Record<string, unknown>[] = []) {
   const onRespond = vi.fn<(response: AgentPermissionResponse) => void>();
   const container = document.createElement("div");
   document.body.appendChild(container);
@@ -61,7 +64,7 @@ function mountCard(question: Record<string, unknown>) {
   act(() =>
     root.render(
       <QuestionFormCard
-        permission={buildPermission(question)}
+        permission={buildPermission(question, following)}
         onRespond={onRespond}
         isResponding={false}
         responseError={null}
@@ -71,10 +74,14 @@ function mountCard(question: Record<string, unknown>) {
   mounted.push({ root, container });
 
   const view = within(container);
-  const optionRole = question.multiSelect ? "checkbox" : "radio";
   const otherInput = () =>
     view.getByRole<HTMLInputElement>("textbox", { name: String(question.question) });
-  const check = (label: string) => act(() => view.getByRole(optionRole, { name: label }).click());
+  const check = (label: string) =>
+    act(() =>
+      (
+        view.queryByRole("radio", { name: label }) ?? view.getByRole("checkbox", { name: label })
+      ).click(),
+    );
   const type = (text: string) => {
     const input = otherInput();
     const valueSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
@@ -90,7 +97,7 @@ function mountCard(question: Record<string, unknown>) {
     if (!response || response.behavior !== "allow") throw new Error("card did not submit");
     return (response.updatedInput as { answers: Record<string, string> }).answers;
   };
-  return { check, type, otherInput, submit, submittedAnswers };
+  return { check, type, otherInput, submit, submittedAnswers, view, onRespond };
 }
 
 const multiSelectQuestion = {
@@ -154,3 +161,31 @@ describe("QuestionFormCard other answers", () => {
     expect(card.submittedAnswers()).toEqual({ Provider: "Codex" });
   });
 });
+
+describe("QuestionFormCard explicit navigation", () => {
+  it("keeps a picked option visible until Next and submits only on Submit", () => {
+    const card = mountCard(singleSelectQuestion, [multiSelectQuestion]);
+    card.check("Codex");
+    expect(card.view.getByRole("radio", { name: "Codex" }).getAttribute("aria-checked")).toBe(
+      "true",
+    );
+    expect(card.onRespond).not.toHaveBeenCalled();
+    act(() => card.view.getByRole("button", { name: "Next" }).click());
+    card.check("Apple");
+    expect(card.onRespond).not.toHaveBeenCalled();
+    card.submit();
+    expect(card.submittedAnswers()).toEqual({ Provider: "Codex", Fruits: "Apple" });
+  });
+
+  it("selects an option when its description is clicked without submitting", () => {
+    const card = mountCard({
+      ...singleSelectQuestion,
+      options: [{ label: "Codex", description: "Use this provider" }],
+    });
+    act(() => card.view.getByText("Use this provider").click());
+    expect(card.view.getByRole("radio", { name: "Codex" }).getAttribute("aria-checked")).toBe(
+      "true",
+    );
+    expect(card.onRespond).not.toHaveBeenCalled();
+  });
+});

packages/app/src/components/question-form-card.tsx

@@ -43,20 +43,16 @@ const IS_WEB = isWeb;
 // drag to the preview's nested scroll, so lines past a cap would be unreachable.
 const OPTION_PREVIEW_MAX_HEIGHT = IS_WEB ? 240 : undefined;
 
-// Web clicks that must not answer: a link in the label, anything in the description, and the
-// second click of a double-click, which would otherwise land on the next question's options.
-function isNonAnsweringClick(event: GestureResponderEvent, description: View | null): boolean {
+// Links are independent actions. Ignore repeat clicks so double-click text selection
+// toggles an option only once.
+function isNonAnsweringClick(event: GestureResponderEvent): boolean {
   if (!IS_WEB) return false;
   const click = event.nativeEvent as unknown as MouseEvent;
   if (click.detail > 1) return true;
   const target = click.target as Element | null;
-  const descriptionElement = description as unknown as Element | null;
-  return Boolean(target?.closest("a") || descriptionElement?.contains(target));
+  return Boolean(target?.closest("a"));
 }
 
-// The description is selectable text, so a touch on it belongs to the text, not the option.
-const claimResponder = () => true;
-
 function getQuestionInputPlaceholder({
   question,
   answerPlaceholder,
@@ -92,10 +88,9 @@ function QuestionOptionRow({
 }: QuestionOptionRowProps) {
   const { theme } = useUnistyles();
 
-  const descriptionRef = useRef<View>(null);
   const handlePress = useCallback(
     (event: GestureResponderEvent) => {
-      if (isNonAnsweringClick(event, descriptionRef.current)) return;
+      if (isNonAnsweringClick(event)) return;
       onToggle(qIndex, optIndex, multiSelect);
     },
     [onToggle, qIndex, optIndex, multiSelect],
@@ -152,11 +147,7 @@ function QuestionOptionRow({
         <View style={styles.optionTextBlock}>
           <MarkdownRenderer text={option.label} compact muted={!isSelected} selectable={false} />
           {option.description ? (
-            <View
-              ref={descriptionRef}
-              testID="question-form-option-description"
-              onStartShouldSetResponder={claimResponder}
-            >
+            <View testID="question-form-option-description">
               <MarkdownRenderer text={option.description} compact muted />
             </View>
           ) : null}
@@ -413,12 +404,8 @@ export function QuestionFormCard({
         });
         otherInputRef.current?.replaceText("");
       }
-
-      if (!multiSelect && next.size > 0 && qIndex === activeQuestionIndex && questions) {
-        setActiveQuestionIndex(Math.min(qIndex + 1, questions.length - 1));
-      }
     },
-    [activeQuestionIndex, otherTexts, questions, selections],
+    [otherTexts, selections],
   );
 
   const setOtherText = useCallback(

packages/app/src/components/welcome-screen.tsx

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { useAddHost } from "@/hosts/add-host";
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
 import { Pressable, Text, View, ScrollView } from "react-native";
 import { useRouter } from "expo-router";
@@ -12,11 +13,7 @@ import {
   Terminal,
 } from "lucide-react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import type { HostProfile } from "@/types/host-connection";
 import { getHostRuntimeStore, isHostRuntimeConnected, useHosts } from "@/runtime/host-runtime";
-import { AddHostModal } from "./add-host-modal";
-import { AddRemoteSshHostModal } from "./add-remote-ssh-host-modal";
-import { PairLinkModal } from "./pair-link-modal";
 import { Button } from "@/components/ui/button";
 import { resolveAppVersion } from "@/utils/app-version";
 import { formatVersionWithPrefix } from "@/desktop/updates/desktop-updates";
@@ -162,20 +159,13 @@ function useAnyHostOnline(serverIds: string[]): string | null {
   );
 }
 
-export interface WelcomeScreenProps {
-  onHostAdded?: (profile: HostProfile) => void;
-}
-
-export function WelcomeScreen({ onHostAdded }: WelcomeScreenProps) {
+export function WelcomeScreen() {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
   const router = useRouter();
   const appVersion = resolveAppVersion();
   const appVersionText = formatVersionWithPrefix(appVersion);
-  const [isDirectOpen, setIsDirectOpen] = useState(false);
-  const [isRemoteSshOpen, setIsRemoteSshOpen] = useState(false);
-  const [isPasteLinkOpen, setIsPasteLinkOpen] = useState(false);
   const hosts = useHosts();
   const anyOnlineServerId = useAnyHostOnline(hosts.map((h) => h.serverId));
 
@@ -196,23 +186,10 @@ export function WelcomeScreen({ onHostAdded }: WelcomeScreenProps) {
     router.push("/settings");
   }, [router]);
 
-  const handleOpenDirect = useCallback(() => setIsDirectOpen(true), []);
-  const handleCloseDirect = useCallback(() => setIsDirectOpen(false), []);
-  const handleOpenRemoteSsh = useCallback(() => setIsRemoteSshOpen(true), []);
-  const handleCloseRemoteSsh = useCallback(() => setIsRemoteSshOpen(false), []);
-  const handleOpenPasteLink = useCallback(() => setIsPasteLinkOpen(true), []);
-  const handleClosePasteLink = useCallback(() => setIsPasteLinkOpen(false), []);
-  const handleScanQr = useCallback(() => {
-    router.push("/pair-scan?source=onboarding");
-  }, [router]);
-
-  const handleHostSaved = useCallback(
-    ({ profile }: { profile: HostProfile; serverId: string }) => {
-      onHostAdded?.(profile);
-      finishOnboarding();
-    },
-    [onHostAdded, finishOnboarding],
-  );
+  const handleOpenDirect = useAddHost({ method: "direct", onAdded: finishOnboarding });
+  const handleOpenRemoteSsh = useAddHost({ method: "ssh", onAdded: finishOnboarding });
+  const handleOpenPasteLink = useAddHost({ method: "link", onAdded: finishOnboarding });
+  const handleScanQr = useAddHost({ method: "scan", onAdded: finishOnboarding });
 
   const actions: WelcomeAction[] =
     isWeb || isFdroidBuild
@@ -316,24 +293,6 @@ export function WelcomeScreen({ onHostAdded }: WelcomeScreenProps) {
           </Button>
         </View>
         <Text style={styles.versionLabel}>{appVersionText}</Text>
-
-        <AddHostModal
-          visible={isDirectOpen}
-          onClose={handleCloseDirect}
-          onSaved={handleHostSaved}
-        />
-
-        <AddRemoteSshHostModal
-          visible={isRemoteSshOpen}
-          onClose={handleCloseRemoteSsh}
-          onSaved={handleHostSaved}
-        />
-
-        <PairLinkModal
-          visible={isPasteLinkOpen}
-          onClose={handleClosePasteLink}
-          onSaved={handleHostSaved}
-        />
       </ScrollView>
     </View>
   );

packages/app/src/hosts/add-host/index.tsx

@@ -0,0 +1,89 @@
+import { createContext, useCallback, useContext, useState, useMemo, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { useStore } from "zustand";
+import { AddHostMethodModal } from "./internal/add-host-method-modal";
+import { AddHostModal } from "./internal/add-host-modal";
+import { AddRemoteSshHostModal } from "./internal/add-remote-ssh-host-modal";
+import { PairLinkModal } from "./internal/pair-link-modal";
+import { AdaptiveModalSheet } from "@/components/adaptive-modal-sheet";
+import { PairScanContent } from "./internal/scan";
+import { createAddHostFlow, type AddHostOptions, type AddHostSession } from "./internal/model";
+
+const Context = createContext<ReturnType<typeof createAddHostFlow> | null>(null);
+
+/** Owns the flow outside screen and appearance lifetimes. Callers own success navigation. */
+export function AddHostProvider({ children }: { children: ReactNode }) {
+  const [flow] = useState(createAddHostFlow);
+  return <Context.Provider value={flow}>{children}</Context.Provider>;
+}
+
+export function AddHostFlowHost() {
+  const flow = useContext(Context);
+  if (!flow) throw new Error("AddHostFlowHost requires AddHostProvider");
+  const session = useStore(flow.store, (state) => state.session);
+  return session ? <AddHostSessionView key={session.id} session={session} /> : null;
+}
+
+export function useAddHost({ method, onAdded }: AddHostOptions = {}) {
+  const flow = useContext(Context);
+  if (!flow) throw new Error("useAddHost requires AddHostProvider");
+  return useCallback(() => flow.open({ method, onAdded }), [flow, method, onAdded]);
+}
+
+function AddHostSessionView({ session }: { session: AddHostSession }) {
+  const { t } = useTranslation();
+  const method = useStore(session.step, (state) => state.method);
+  const back = useCallback(() => session.choose(null), [session]);
+  const direct = useCallback(() => session.choose("direct"), [session]);
+  const ssh = useCallback(() => session.choose("ssh"), [session]);
+  const link = useCallback(() => session.choose("link"), [session]);
+  const scan = useCallback(() => session.choose("scan"), [session]);
+  const scanned = useCallback((serverId: string) => session.complete({ serverId }), [session]);
+  const header = useMemo(
+    () => ({ title: t("pairing.scan.title"), back: { onPress: back } }),
+    [t, back],
+  );
+  return (
+    <>
+      <AddHostMethodModal
+        visible={method === null}
+        onClose={session.close}
+        onDirectConnection={direct}
+        onRemoteSsh={ssh}
+        onPasteLink={link}
+        onScanQr={scan}
+      />
+      <AddHostModal
+        visible={method === "direct"}
+        onClose={session.close}
+        onCancel={back}
+        onSaved={session.complete}
+      />
+      <AddRemoteSshHostModal
+        visible={method === "ssh"}
+        onClose={session.close}
+        onCancel={back}
+        onSaved={session.complete}
+      />
+      <PairLinkModal
+        visible={method === "link"}
+        onClose={session.close}
+        onCancel={back}
+        onSaved={session.complete}
+      />
+      {method === "scan" ? (
+        <AdaptiveModalSheet
+          header={header}
+          visible
+          onClose={session.close}
+          scrollable={false}
+          snapPoints={SCAN_SNAP_POINTS}
+          desktopHeight="85%"
+        >
+          <PairScanContent onConnected={scanned} onClose={back} />
+        </AdaptiveModalSheet>
+      ) : null}
+    </>
+  );
+}
+const SCAN_SNAP_POINTS = ["90%"];

packages/app/src/hosts/add-host/internal/add-host-method-modal.tsx

@@ -1,9 +1,10 @@
+import { PressHighlight } from "@/components/ui/press-highlight";
 import { useCallback, useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import { Pressable, Text, View } from "react-native";
+import { Text, View } from "react-native";
 import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { QrCode, Link2, ClipboardPaste, Terminal } from "lucide-react-native";
-import { AdaptiveModalSheet, type SheetHeader } from "./adaptive-modal-sheet";
+import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 import { isFdroidBuild } from "@/constants/build-profile";
 import { isNative } from "@/constants/platform";
 import { isElectronRuntime } from "@/desktop/host";
@@ -84,7 +85,7 @@ export function AddHostMethodModal({
       onClose={onClose}
       testID="add-host-method-modal"
     >
-      <Pressable
+      <PressHighlight
         style={styles.option}
         onPress={handleDirect}
         accessibilityRole="button"
@@ -98,10 +99,10 @@ export function AddHostMethodModal({
             {t("pairing.connectionMethods.direct.description")}
           </Text>
         </View>
-      </Pressable>
+      </PressHighlight>
 
       {isElectronRuntime() ? (
-        <Pressable
+        <PressHighlight
           style={styles.option}
           onPress={handleRemoteSsh}
           accessibilityRole="button"
@@ -115,11 +116,11 @@ export function AddHostMethodModal({
               {t("pairing.connectionMethods.remoteSsh.description")}
             </Text>
           </View>
-        </Pressable>
+        </PressHighlight>
       ) : null}
 
       {isNative && !isFdroidBuild ? (
-        <Pressable
+        <PressHighlight
           style={styles.option}
           onPress={handleScan}
           accessibilityRole="button"
@@ -132,10 +133,10 @@ export function AddHostMethodModal({
               {t("pairing.connectionMethods.scanQr.description")}
             </Text>
           </View>
-        </Pressable>
+        </PressHighlight>
       ) : null}
 
-      <Pressable
+      <PressHighlight
         style={styles.option}
         onPress={handlePaste}
         accessibilityRole="button"
@@ -149,7 +150,7 @@ export function AddHostMethodModal({
             {t("pairing.connectionMethods.pasteLink.description")}
           </Text>
         </View>
-      </Pressable>
+      </PressHighlight>
     </AdaptiveModalSheet>
   );
 }

packages/app/src/hosts/add-host/internal/add-host-modal.tsx

@@ -1,17 +1,22 @@
+import { PressHighlight } from "@/components/ui/press-highlight";
 import { useCallback, useMemo, useReducer, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
-import { Alert, Pressable, Text, View } from "react-native";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { Alert, Text, View } from "react-native";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { Check, ChevronDown, ChevronRight, Eye, EyeOff, Link2 } from "lucide-react-native";
 import type { HostProfile } from "@/types/host-connection";
 import { useHosts, useHostMutations } from "@/runtime/host-runtime";
 import { parseConnectionUri, serializeConnectionUri } from "@/utils/daemon-endpoints";
-import { buildConnectionFailureCopy } from "./connection-failure-copy";
-import { AdaptiveModalSheet, AdaptiveTextInput, type SheetHeader } from "./adaptive-modal-sheet";
+import { buildConnectionFailureCopy } from "@/components/connection-failure-copy";
+import {
+  AdaptiveModalSheet,
+  AdaptiveTextInput,
+  type SheetHeader,
+} from "@/components/adaptive-modal-sheet";
 import { Button } from "@/components/ui/button";
-import { PairingTargetTracker } from "./pair-link-credentials";
-import { buildDirectConnectionUri } from "./direct-connection-host";
+import { PairingTargetTracker } from "@/components/pair-link-credentials";
+import { buildDirectConnectionUri } from "@/components/direct-connection-host";
 
 const FLEX_ONE_STYLE = { flex: 1 } as const;
 
@@ -188,7 +193,6 @@ export function AddHostModal({ visible, onClose, onCancel, onSaved }: AddHostMod
 }
 
 function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostModalProps) {
-  const { theme } = useUnistyles();
   const { t } = useTranslation();
   const daemons = useHosts();
   const { probeAndUpsertDirectConnection, beginLinkPairing } = useHostMutations();
@@ -207,10 +211,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
   const [inputResetKey, bumpInputResetKey] = useReducer((key: number) => key + 1, 0);
   const advancedTarget = useRef(new PairingTargetTracker("", true));
 
-  const connectIcon = useMemo(
-    () => <Link2 size={16} color={theme.colors.accentForeground} />,
-    [theme.colors.accentForeground],
-  );
+  const connectIcon = useMemo(() => <ThemedLink2 size={16} />, []);
   const hostFieldStyle = useMemo(() => [styles.field, styles.hostField], []);
   const portFieldStyle = useMemo(() => [styles.field, styles.portField], []);
   const checkboxStyle = useMemo(
@@ -415,8 +416,8 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
     setIsAdvancedOpen(false);
   }, [advancedUri, directConnectionLabels, host, isAdvancedOpen, password, port, useTls]);
 
-  const AdvancedIcon = isAdvancedOpen ? ChevronDown : ChevronRight;
-  const PasswordIcon = isPasswordVisible ? EyeOff : Eye;
+  const AdvancedIcon = isAdvancedOpen ? ThemedChevronDown : ThemedChevronRight;
+  const PasswordIcon = isPasswordVisible ? ThemedEyeOff : ThemedEye;
 
   return (
     <AdaptiveModalSheet
@@ -430,7 +431,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
       <View style={styles.portRow}>
         <View style={hostFieldStyle}>
           <Text style={styles.label}>{t("pairing.direct.fields.host")}</Text>
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="direct-host-input"
             nativeID="direct-host-input"
             accessibilityLabel={t("pairing.direct.fields.host")}
@@ -438,7 +439,6 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             resetKey={`direct-host-${inputResetKey}`}
             onChangeText={setHost}
             placeholder="localhost"
-            placeholderTextColor={theme.colors.foregroundMuted}
             style={styles.input}
             autoCapitalize="none"
             autoCorrect={false}
@@ -449,7 +449,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
         </View>
         <View style={portFieldStyle}>
           <Text style={styles.label}>{t("pairing.direct.fields.port")}</Text>
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="direct-port-input"
             nativeID="direct-port-input"
             accessibilityLabel={t("pairing.direct.fields.port")}
@@ -457,7 +457,6 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             resetKey={`direct-port-${inputResetKey}`}
             onChangeText={setPort}
             placeholder="6767"
-            placeholderTextColor={theme.colors.foregroundMuted}
             style={styles.input}
             autoCapitalize="none"
             autoCorrect={false}
@@ -469,7 +468,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
         </View>
       </View>
 
-      <Pressable
+      <PressHighlight
         style={styles.checkboxRow}
         onPress={handleToggleUseTls}
         disabled={isSaving}
@@ -482,17 +481,17 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
         <View style={checkboxStyle}>
           {useTls ? (
             <View testID="direct-ssl-toggle-checked">
-              <Check size={14} color={theme.colors.accentForeground} />
+              <ThemedCheck size={14} />
             </View>
           ) : null}
         </View>
         <Text style={styles.label}>{t("pairing.direct.fields.useSsl")}</Text>
-      </Pressable>
+      </PressHighlight>
 
       <View style={styles.field}>
         <Text style={styles.label}>{t("pairing.direct.fields.password")}</Text>
         <View style={styles.passwordRow}>
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="direct-password-input"
             nativeID="direct-password-input"
             accessibilityLabel={t("pairing.direct.fields.password")}
@@ -500,7 +499,6 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             resetKey={`direct-password-${inputResetKey}`}
             onChangeText={setPassword}
             placeholder={t("pairing.direct.fields.optional")}
-            placeholderTextColor={theme.colors.foregroundMuted}
             style={passwordInputStyle}
             autoCapitalize="none"
             autoCorrect={false}
@@ -509,7 +507,7 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             returnKeyType="done"
             onSubmitEditing={handleSubmitEditing}
           />
-          <Pressable
+          <PressHighlight
             style={styles.iconButton}
             onPress={handleTogglePasswordVisibility}
             disabled={isSaving}
@@ -521,13 +519,13 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             }
             testID="direct-password-visibility-toggle"
           >
-            <PasswordIcon size={18} color={theme.colors.foregroundMuted} />
-          </Pressable>
+            <PasswordIcon size={18} />
+          </PressHighlight>
         </View>
       </View>
 
       <View style={styles.field}>
-        <Pressable
+        <PressHighlight
           style={styles.advancedToggle}
           onPress={handleToggleAdvanced}
           disabled={isSaving}
@@ -537,11 +535,11 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
           }
           testID="direct-host-advanced-toggle"
         >
-          <AdvancedIcon size={16} color={theme.colors.foregroundMuted} />
+          <AdvancedIcon size={16} />
           <Text style={styles.advancedText}>{t("pairing.direct.advanced.label")}</Text>
-        </Pressable>
+        </PressHighlight>
         {isAdvancedOpen ? (
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="direct-host-uri-input"
             nativeID="direct-host-uri-input"
             accessibilityLabel={t("pairing.direct.fields.connectionUri")}
@@ -549,7 +547,6 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
             resetKey={`direct-host-uri-${inputResetKey}`}
             onChangeText={handleChangeAdvancedUri}
             placeholder="tcp://localhost:6767?ssl=true"
-            placeholderTextColor={theme.colors.foregroundMuted}
             style={styles.input}
             autoCapitalize="none"
             autoCorrect={false}
@@ -585,3 +582,23 @@ function AddHostModalContent({ visible, onClose, onCancel, onSaved }: AddHostMod
     </AdaptiveModalSheet>
   );
 }
+
+const ThemedLink2 = withUnistyles(Link2, (theme) => ({ color: theme.colors.accentForeground }));
+
+const ThemedCheck = withUnistyles(Check, (theme) => ({ color: theme.colors.accentForeground }));
+
+const ThemedChevronDown = withUnistyles(ChevronDown, (theme) => ({
+  color: theme.colors.foregroundMuted,
+}));
+
+const ThemedChevronRight = withUnistyles(ChevronRight, (theme) => ({
+  color: theme.colors.foregroundMuted,
+}));
+
+const ThemedEye = withUnistyles(Eye, (theme) => ({ color: theme.colors.foregroundMuted }));
+
+const ThemedEyeOff = withUnistyles(EyeOff, (theme) => ({ color: theme.colors.foregroundMuted }));
+
+const ThemedAdaptiveTextInput = withUnistyles(AdaptiveTextInput, (theme) => ({
+  placeholderTextColor: theme.colors.foregroundMuted,
+}));

packages/app/src/hosts/add-host/internal/add-remote-ssh-host-modal.tsx

@@ -1,7 +1,7 @@
+import { PressHighlight } from "@/components/ui/press-highlight";
 import { useCallback, useMemo, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import {
-  Pressable,
   Text,
   View,
   type PressableStateCallbackType,
@@ -23,7 +23,7 @@ import {
 import type { EditingTextInputHandle } from "@/components/ui/text-input";
 import { useIsCompactFormFactor } from "@/constants/layout";
 import { DaemonConnectionTestError } from "@/utils/test-daemon-connection";
-import { AdaptiveModalSheet, type SheetHeader } from "./adaptive-modal-sheet";
+import { AdaptiveModalSheet, type SheetHeader } from "@/components/adaptive-modal-sheet";
 
 const FLEX_ONE_STYLE = { flex: 1 } as const;
 const ThemedTerminal = withUnistyles(Terminal);
@@ -174,11 +174,11 @@ export function AddRemoteSshHostModal({
     }
 
     clear();
-    onClose();
     onSaved?.({
       ...result,
       isNewHost: !hosts.some((profile) => profile.serverId === result.serverId),
     });
+    onClose();
   }, [clear, hosts, isSaving, onClose, onSaved, probeAndUpsertRemoteSshConnection, t]);
   const handleTargetChange = useCallback((value: string) => {
     targetRef.current = value;
@@ -260,7 +260,7 @@ export function AddRemoteSshHostModal({
               onSubmitEditing={handleSubmit}
             />
           </View>
-          <Pressable
+          <PressHighlight
             style={iconButtonStyle}
             onPress={handleTogglePasswordVisibility}
             disabled={isSaving}
@@ -273,7 +273,7 @@ export function AddRemoteSshHostModal({
             testID="remote-ssh-password-visibility-toggle"
           >
             {isPasswordVisible ? <ThemedEyeOff size={18} /> : <ThemedEye size={18} />}
-          </Pressable>
+          </PressHighlight>
         </View>
       </Field>
       <View style={styles.actions}>

packages/app/src/hosts/add-host/internal/model.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { createAddHostFlow } from "./model";
+
+describe("add host flow", () => {
+  it("closes before notifying the consumer and ignores duplicate completion", () => {
+    const flow = createAddHostFlow();
+    const added: string[] = [];
+    flow.open({
+      onAdded: (serverId) => {
+        expect(flow.store.getState().session).toBeNull();
+        added.push(serverId);
+      },
+    });
+    const session = flow.store.getState().session!;
+    session.choose("direct");
+    session.complete({ serverId: "new-host" });
+    session.complete({ serverId: "new-host" });
+    expect(added).toEqual(["new-host"]);
+  });
+
+  it("cancels without a success action and accepts a fresh request", () => {
+    const flow = createAddHostFlow();
+    const added: string[] = [];
+    flow.open({ onAdded: (id) => added.push(id) });
+    const cancelled = flow.store.getState().session!;
+    cancelled.choose("scan");
+    cancelled.close();
+    expect(flow.store.getState().session).toBeNull();
+    flow.open({ method: "link" });
+    const current = flow.store.getState().session!;
+    cancelled.complete({ serverId: "late-result" });
+    cancelled.close();
+    expect(flow.store.getState().session).toBe(current);
+    expect(current.step.getState()).toEqual({ method: "link" });
+    expect(added).toEqual([]);
+    current.complete({ serverId: "new-host" });
+    expect(flow.store.getState().session).toBeNull();
+  });
+
+  it("returns to method selection within the same request", () => {
+    const flow = createAddHostFlow();
+    flow.open();
+    const session = flow.store.getState().session!;
+    session.choose("ssh");
+    session.choose(null);
+    expect(flow.store.getState().session).toBe(session);
+    expect(session.step.getState()).toEqual({ method: null });
+  });
+});

packages/app/src/hosts/add-host/internal/model.ts

@@ -0,0 +1,47 @@
+import { createStore, type StoreApi } from "zustand/vanilla";
+
+export type AddHostMethod = "direct" | "ssh" | "link" | "scan";
+export interface AddHostOptions {
+  method?: AddHostMethod;
+  onAdded?: (serverId: string) => void;
+}
+
+export interface AddHostSession {
+  id: number;
+  step: StoreApi<{ method: AddHostMethod | null }>;
+  choose(method: AddHostMethod | null): void;
+  close(): void;
+  complete(result: { serverId: string }): void;
+}
+
+export function createAddHostFlow() {
+  const store = createStore<{ session: AddHostSession | null }>(() => ({ session: null }));
+  let nextId = 0;
+  function createSession(options: AddHostOptions) {
+    const step = createStore<{ method: AddHostMethod | null }>(() => ({
+      method: options.method ?? null,
+    }));
+    const session = {
+      id: ++nextId,
+      step,
+      choose(method: AddHostMethod | null) {
+        step.setState({ method });
+      },
+      close() {
+        if (store.getState().session === session) store.setState({ session: null });
+      },
+      complete({ serverId }: { serverId: string }) {
+        if (store.getState().session !== session) return;
+        session.close();
+        options.onAdded?.(serverId);
+      },
+    };
+    return session;
+  }
+  return {
+    store,
+    open(options: AddHostOptions = {}) {
+      store.setState({ session: createSession(options) });
+    },
+  };
+}

packages/app/src/hosts/add-host/internal/pair-link-modal.tsx

@@ -1,16 +1,20 @@
 import { useCallback, useMemo, useReducer, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { Alert, Text, View } from "react-native";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { StyleSheet, withUnistyles } 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, 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";
+import {
+  AdaptiveModalSheet,
+  AdaptiveTextInput,
+  type SheetHeader,
+} from "@/components/adaptive-modal-sheet";
 import { getConnectionAuthFailureReason } from "@/utils/test-daemon-connection";
-import { PairingTargetTracker } from "./pair-link-credentials";
+import { PairingTargetTracker } from "@/components/pair-link-credentials";
 import { Button } from "@/components/ui/button";
 import type { EditingTextInputHandle } from "@/components/ui/text-input";
 
@@ -100,7 +104,6 @@ function PairLinkModalContent({
   onCancel,
   onSaved,
 }: PairLinkModalProps) {
-  const { theme } = useUnistyles();
   const { t } = useTranslation();
   const daemons = useHosts();
   const { beginLinkPairing } = useHostMutations();
@@ -126,10 +129,7 @@ function PairLinkModalContent({
     resetPasswordInput();
   }, []);
 
-  const pairIcon = useMemo(
-    () => <Link size={16} color={theme.colors.accentForeground} />,
-    [theme.colors.accentForeground],
-  );
+  const pairIcon = useMemo(() => <ThemedLink size={16} />, []);
 
   const handleClose = useCallback(() => {
     if (isSaving) return;
@@ -212,7 +212,7 @@ function PairLinkModalContent({
 
       <View style={styles.field}>
         <Text style={styles.label}>{t("pairing.link.label")}</Text>
-        <AdaptiveTextInput
+        <ThemedAdaptiveTextInput
           ref={inputRef}
           initialValue={initialUrl}
           testID="pair-link-input"
@@ -220,7 +220,6 @@ function PairLinkModalContent({
           accessibilityLabel={t("pairing.link.label")}
           onChangeText={handleChangeOfferUrl}
           placeholder="https://app.paseo.sh/#offer=..."
-          placeholderTextColor={theme.colors.foregroundMuted}
           style={styles.input}
           autoFocus
           autoCapitalize="none"
@@ -235,7 +234,7 @@ function PairLinkModalContent({
           <Text style={styles.label}>
             {t("pairing.hostPassword.title", { host: parsedHostLabel(offerUrlRef.current) })}
           </Text>
-          <AdaptiveTextInput
+          <ThemedAdaptiveTextInput
             testID="pair-link-password-input"
             resetKey={`pair-link-password-${passwordResetKey}`}
             accessibilityLabel={t("pairing.hostPassword.label")}
@@ -274,3 +273,9 @@ function PairLinkModalContent({
     </AdaptiveModalSheet>
   );
 }
+
+const ThemedLink = withUnistyles(Link, (theme) => ({ color: theme.colors.accentForeground }));
+
+const ThemedAdaptiveTextInput = withUnistyles(AdaptiveTextInput, (theme) => ({
+  placeholderTextColor: theme.colors.foregroundMuted,
+}));

packages/app/src/hosts/add-host/internal/scan.tsx

@@ -1,17 +1,14 @@
 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";
+import { Text, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { StyleSheet, useUnistyles } from "react-native-unistyles";
+import { StyleSheet } 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 { openPairScan } from "./pair-scan-model";
 import { isWeb } from "@/constants/platform";
-import { BackHeader } from "@/components/headers/back-header";
-import { PairLinkModal } from "@/components/pair-link-modal";
+import { PairLinkModal } from "./pair-link-modal";
 import { Button } from "@/components/ui/button";
 
 const styles = StyleSheet.create((theme) => ({
@@ -113,50 +110,26 @@ const styles = StyleSheet.create((theme) => ({
   },
 }));
 
-export default function PairScanScreen() {
-  const { theme } = useUnistyles();
+export function PairScanContent({
+  onConnected,
+  onClose,
+}: {
+  onConnected: (serverId: string) => void;
+  onClose: () => void;
+}) {
   const { t } = useTranslation();
   const insets = useSafeAreaInsets();
-  const router = useRouter();
-  const params = useLocalSearchParams<{
-    source?: string;
-  }>();
-  const source = typeof params.source === "string" ? params.source : "settings";
-
   const [permission, requestPermission] = useCameraPermissions();
 
-  const navigateToPairedHost = useCallback(
-    (serverId: string) => {
-      if (source === "onboarding") {
-        router.replace(buildHostRootRoute(serverId));
-        return;
-      }
-      router.replace(buildSettingsHostRoute(serverId));
-    },
-    [router, source],
-  );
-
   const [scan] = useState(() =>
     openPairScan({
-      importConnectionLink: (link) =>
-        getHostRuntimeStore().importConnectionLink(
-          link,
-          source === "onboarding" ? "hostRoot" : "hostSettings",
-        ),
-      onConnected: navigateToPairedHost,
+      importConnectionLink: (link) => getHostRuntimeStore().importConnectionLink(link, "hostRoot"),
+      onConnected,
     }),
   );
   const scanState = useSyncExternalStore(scan.subscribe, scan.getState, scan.getState);
   useEffect(() => () => scan.close(), [scan]);
 
-  const closeToSource = useCallback(() => {
-    try {
-      router.back();
-    } catch {
-      router.replace("/" as Href);
-    }
-  }, [router]);
-
   useEffect(() => {
     if (isWeb) return;
     if (permission && permission.granted) return;
@@ -169,35 +142,29 @@ export default function PairScanScreen() {
     [scan],
   );
 
-  const handleRouterBack = useCallback(() => router.back(), [router]);
   const savePasswordPairing = useCallback(
-    ({ serverId }: { serverId: string }) => navigateToPairedHost(serverId),
-    [navigateToPairedHost],
+    ({ serverId }: { serverId: string }) => onConnected(serverId),
+    [onConnected],
   );
   const handleRequestPermission = useCallback(() => {
     void requestPermission();
   }, [requestPermission]);
 
   const bodyStyle = useMemo(
-    () => [styles.body, { paddingBottom: insets.bottom + theme.spacing[6] }],
-    [insets.bottom, theme.spacing],
-  );
-  const helperTextStyle = useMemo(
-    () => [styles.helperText, { color: theme.colors.foreground }],
-    [theme.colors.foreground],
+    () => [styles.body, { paddingBottom: insets.bottom + 24 }],
+    [insets.bottom],
   );
 
   if (isWeb) {
     return (
       <View style={styles.container}>
-        <BackHeader title={t("pairing.scan.title")} onBack={handleRouterBack} />
         <View style={bodyStyle}>
           <View style={styles.permissionCard}>
             <Text style={styles.permissionTitle}>{t("pairing.scan.webUnavailableTitle")}</Text>
             <Text style={styles.permissionBody}>{t("pairing.scan.webUnavailableBody")}</Text>
-            <Pressable style={styles.permissionButton} onPress={closeToSource}>
-              <Text style={styles.permissionButtonText}>{t("pairing.scan.backToSettings")}</Text>
-            </Pressable>
+            <Button style={styles.permissionButton} onPress={onClose}>
+              <Text style={styles.permissionButtonText}>{t("common.actions.back")}</Text>
+            </Button>
           </View>
         </View>
       </View>
@@ -208,16 +175,14 @@ export default function PairScanScreen() {
 
   return (
     <View style={styles.container}>
-      <BackHeader title={t("pairing.scan.title")} onBack={closeToSource} />
-
       <View style={bodyStyle}>
         {!granted ? (
           <View style={styles.permissionCard}>
             <Text style={styles.permissionTitle}>{t("pairing.scan.cameraPermissionTitle")}</Text>
             <Text style={styles.permissionBody}>{t("pairing.scan.cameraPermissionBody")}</Text>
-            <Pressable style={styles.permissionButton} onPress={handleRequestPermission}>
+            <Button style={styles.permissionButton} onPress={handleRequestPermission}>
               <Text style={styles.permissionButtonText}>{t("pairing.scan.grantPermission")}</Text>
-            </Pressable>
+            </Button>
           </View>
         ) : (
           <View style={styles.cameraWrap}>
@@ -235,10 +200,10 @@ export default function PairScanScreen() {
                 <View style={[styles.corner, styles.cornerBR]} />
               </View>
               {scanState.status === "pairing" ? (
-                <Text style={helperTextStyle}>{t("pairing.scan.pairing")}</Text>
+                <Text style={styles.helperText}>{t("pairing.scan.pairing")}</Text>
               ) : null}
               {scanState.status === "stopped" && scanState.error ? (
-                <Text style={helperTextStyle}>{scanState.error}</Text>
+                <Text style={styles.helperText}>{scanState.error}</Text>
               ) : null}
               {scanState.status === "stopped" ? (
                 <Button

packages/app/src/hosts/host-chooser.tsx

@@ -1,12 +1,11 @@
+import { useAddHost } from "@/hosts/add-host";
 import { Modal } from "@/components/ui/modal";
-import { usePanelStore } from "@/stores/panel-store";
 import { createElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Pressable, ScrollView, Text, View, type PressableStateCallbackType } from "react-native";
 import {
   EditingTextInput as TextInput,
   type EditingTextInputHandle,
 } from "@/components/ui/text-input";
-import { router } from "expo-router";
 import { Server } from "lucide-react-native";
 import { create } from "zustand";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
@@ -20,7 +19,6 @@ import {
 } from "@/lib/overlay-root";
 import { useHosts } from "@/runtime/host-runtime";
 import { orderHostsLocalFirst, type HostProfile } from "@/types/host-connection";
-import { buildSettingsAddHostRoute } from "@/utils/host-routes";
 
 type HostFilter = (host: HostProfile) => boolean;
 type HostChoiceHandler = (serverId: string) => void | Promise<void>;
@@ -65,6 +63,7 @@ function matchesHostQuery(host: HostProfile, query: string): boolean {
 }
 
 export function useHostChooser() {
+  const addHost = useAddHost();
   const hosts = useHosts();
   const localServerId = useLocalDaemonServerId();
   const open = useHostChooserStore((state) => state.open);
@@ -76,13 +75,7 @@ export function useHostChooser() {
       );
 
       if (availableHosts.length === 0) {
-        (
-          input.onNoHosts ??
-          (() => {
-            usePanelStore.getState().showMobileAgent();
-            router.push(buildSettingsAddHostRoute(Date.now()));
-          })
-        )();
+        (input.onNoHosts ?? addHost)();
         return false;
       }
 
@@ -98,7 +91,7 @@ export function useHostChooser() {
       });
       return true;
     },
-    [hosts, localServerId, open],
+    [hosts, localServerId, open, addHost],
   );
 }
 

packages/app/src/plugins/buttons/model.test.ts

@@ -17,6 +17,9 @@ function installation(): InstalledPlugin {
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     cleanup: () => undefined,
     settingsScreens: [],
     surfaces: [],

packages/app/src/plugins/catalog-sync-model.test.ts

@@ -153,6 +153,9 @@ function harness() {
         openPanel() {},
         addComposerPill: () => ({ update() {}, remove() {} }),
         addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
       };
     },
   });

packages/app/src/plugins/client-runtime.ts

@@ -2,6 +2,7 @@ import { createPlayAudio, type AudioEngine } from "@/audio";
 import { getHostRuntimeStore } from "@/runtime/host-runtime";
 import { createPluginHosts } from "./hosts";
 import type { PluginClientOpenPanelOptions } from "@getpaseo/plugin/client";
+import { subscribePluginRpc } from "@getpaseo/plugin/client/host";
 import {
   createPluginAgentActionContext,
   createPluginCapabilities,
@@ -36,6 +37,8 @@ export function createPluginClientRuntime(
     openPanel(panelId, options) {
       openClientPanel({ installation, state, panelId, options });
     },
+    subscribe: (contract, input, onEvent, options) =>
+      subscribePluginRpc(contract, installation.subscribe, input, onEvent, options),
   };
 }
 

packages/app/src/plugins/command-center/contributions.test.ts

@@ -71,6 +71,9 @@ function plugin(onAgentSelect: AgentCommandItem["onSelect"]): InstalledPlugin {
         clientType: "cli",
       }),
     ),
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     invoke: async (method: string, input: unknown) => {
       expect(method).toBe("review.inspect");
       return { value: inspect.input.parse(input).value + 1 };

packages/app/src/plugins/evaluate.ts

@@ -111,6 +111,7 @@ export type PluginClientRuntime = Pick<
   | "openScreen"
   | "openSurface"
   | "openPanel"
+  | "subscribe"
   | "addComposerPill"
   | "addHeaderButton"
 > & { hosts: ReturnType<typeof createPluginHosts> };

packages/app/src/plugins/installation-provider.test.tsx

@@ -29,6 +29,9 @@ function installation(invoked: string[]): InstalledPlugin {
       invoked.push(method);
       return { state: "green" };
     },
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     queryClient: new QueryClient(),
     cleanup: () => undefined,
     settingsScreens: [],

packages/app/src/plugins/installation-provider.tsx

@@ -18,7 +18,7 @@ export function PluginInstallationProvider({
   return (
     <QueryClientProvider client={plugin.queryClient}>
       <PaseoApiProvider paseo={plugin.paseo}>
-        <PluginRpcProvider invoke={plugin.invoke}>
+        <PluginRpcProvider invoke={plugin.invoke} subscribe={plugin.subscribe}>
           <PluginTranslationProvider runtime={plugin.i18n}>{children}</PluginTranslationProvider>
         </PluginRpcProvider>
       </PaseoApiProvider>

packages/app/src/plugins/registry-lifecycle.test.ts

@@ -62,6 +62,9 @@ function registry(
         openPanel: () => {},
         addComposerPill: () => ({ update() {}, remove() {} }),
         addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
       };
     },
   });

packages/app/src/plugins/registry-requirements.test.ts

@@ -39,6 +39,9 @@ function registry(version: string) {
         openPanel() {},
         addComposerPill: () => ({ update() {}, remove() {} }),
         addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
       };
     },
   });

packages/app/src/plugins/registry.ts

@@ -8,6 +8,7 @@ import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { assertPluginCompatibility } from "@getpaseo/protocol/plugin-requirements";
 import { resolveAppVersion } from "@/utils/app-version";
 import { createPluginClientRuntime } from "./client-runtime";
+import { createPluginSubscribe } from "./subscriptions";
 import { runPluginClientBundle } from "./evaluate";
 import type { InstalledPlugin } from "./types";
 
@@ -89,12 +90,18 @@ export class PluginRegistry {
           return [existing];
         }
         const client = options.client;
+        const lifetime = new AbortController();
         installation = {
-          lifetime: new AbortController(),
+          lifetime,
           locale: this.dependencies.localeSource.getLocale(),
           i18n: new PluginTranslationRuntime(this.dependencies.localeSource),
           paseo: createPaseoApi(client),
           invoke: (method, input) => client.invokePluginRpc(entry.id, method, input),
+          subscribe: createPluginSubscribe({
+            client,
+            pluginId: entry.id,
+            lifetime: lifetime.signal,
+          }),
           id: entry.id,
           serverId,
           clientBundle: entry.clientBundle,

packages/app/src/plugins/sidebar-groups.test.ts

@@ -26,6 +26,9 @@ function installed(
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     settingsScreens: [],
     surfaces: [{ id: "surface", title: "Surface", Component: () => null }],
     sidebarItems: {

packages/app/src/plugins/subscriptions.test.ts

@@ -0,0 +1,189 @@
+import { defineSubscription } from "@getpaseo/plugin";
+import type { PluginSubscriptionClosed } from "@getpaseo/plugin/client";
+import { subscribePluginRpc } from "@getpaseo/plugin/client/host";
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { SubscriptionObserver } from "@getpaseo/client";
+import type { SessionOutboundMessage } from "@getpaseo/protocol/messages";
+import { expect, it } from "vitest";
+import { z } from "zod";
+import { createPluginSubscribe } from "./subscriptions";
+
+const changes = defineSubscription({
+  name: "diff.watch",
+  input: z.object({ ref: z.string() }),
+  event: z.union([z.instanceof(Uint8Array), z.object({ path: z.string() })]),
+});
+
+type Observed = Parameters<DaemonClient["observePluginRpc"]>;
+
+/** One host-side subscription as the daemon client exposes it, driven by the test. */
+class HostSubscription {
+  readonly released: Promise<void>;
+  isReleased = false;
+  private observer: SubscriptionObserver<never> | null = null;
+  private accept!: () => void;
+  private refuse!: (error: Error) => void;
+  private markReleased!: () => void;
+  readonly ready = new Promise<never>((resolve, reject) => {
+    this.accept = () => resolve({ requestId: "r", subscriptionId: "s" } as never);
+    this.refuse = reject;
+  });
+
+  constructor(
+    readonly method: string,
+    readonly input: unknown,
+    readonly signal: AbortSignal | undefined,
+  ) {
+    void this.ready.catch(() => undefined);
+    this.released = new Promise((resolve) => {
+      this.markReleased = resolve;
+    });
+    signal?.addEventListener("abort", () => void this.release(), { once: true });
+  }
+
+  handle() {
+    return {
+      subscriptionId: "s",
+      ready: this.ready,
+      subscribe: (observer: SubscriptionObserver<never>) => {
+        this.observer = observer;
+        return () => undefined;
+      },
+      release: () => this.release(),
+    };
+  }
+
+  acknowledge() {
+    this.accept();
+  }
+
+  refuseWith(error: Error) {
+    this.refuse(error);
+    this.observer?.error?.(error);
+  }
+
+  event(event: unknown) {
+    this.observer?.update({
+      type: "plugin.rpc.event",
+      payload: { subscriptionId: "s", event },
+    } as SessionOutboundMessage);
+  }
+
+  bytes(payload: Uint8Array) {
+    this.observer?.binary?.(payload);
+  }
+
+  closed(error?: string) {
+    this.observer?.update({
+      type: "plugin.rpc.closed",
+      payload: { subscriptionId: "s", ...(error ? { error } : {}) },
+    } as SessionOutboundMessage);
+  }
+
+  async release() {
+    this.isReleased = true;
+    this.markReleased();
+  }
+}
+
+/** An installation's subscribe on a host the test drives, and what one subscriber observed. */
+function installation() {
+  const subscriptions: HostSubscription[] = [];
+  const client = {
+    observePluginRpc: (...[pluginId, method, input, options]: Observed) => {
+      expect(pluginId).toBe("diffs");
+      const subscription = new HostSubscription(method, input, options?.signal);
+      subscriptions.push(subscription);
+      return subscription.handle() as unknown as ReturnType<DaemonClient["observePluginRpc"]>;
+    },
+  };
+  const lifetime = new AbortController();
+  const subscribe = createPluginSubscribe({ client, pluginId: "diffs", lifetime: lifetime.signal });
+  function open(ref: string, signal?: AbortSignal) {
+    const received: string[] = [];
+    const closed: PluginSubscriptionClosed[] = [];
+    const handle = subscribePluginRpc(
+      changes,
+      subscribe,
+      { ref },
+      (event) =>
+        received.push(event instanceof Uint8Array ? `bytes:${[...event]}` : `path:${event.path}`),
+      { signal, onClosed: (result) => closed.push(result) },
+    );
+    return { handle, received, closed, host: subscriptions[subscriptions.length - 1]! };
+  }
+  return { open, lifetime };
+}
+
+it("delivers JSON and byte events in order and releases the host subscription", async () => {
+  const { open } = installation();
+  const { handle, received, closed, host } = open("main");
+  expect(host.method).toBe("diff.watch");
+  expect(host.input).toEqual({ ref: "main" });
+  host.acknowledge();
+  await handle.ready;
+
+  host.event({ path: "a.ts" });
+  host.bytes(new Uint8Array([1, 2]));
+  expect(received).toEqual(["path:a.ts", "bytes:1,2"]);
+
+  handle();
+  await host.released;
+  expect(closed).toEqual([]);
+});
+
+it("reports a refusal, a failure after going live, and a clean close", async () => {
+  const { open } = installation();
+  const refused = open("a");
+  refused.host.refuseWith(new Error("no such ref"));
+  await expect(refused.handle.ready).rejects.toThrow("no such ref");
+  expect(refused.closed).toEqual([{ error: new Error("no such ref") }]);
+
+  const failed = open("b");
+  failed.host.acknowledge();
+  await failed.handle.ready;
+  failed.host.closed("Plugin stopped: diffs");
+  expect(failed.closed).toEqual([{ error: new Error("Plugin stopped: diffs") }]);
+  await failed.host.released;
+
+  // A handler that returns at once closes in the same tick the host accepts it.
+  const finished = open("c");
+  finished.host.acknowledge();
+  finished.host.closed();
+  await expect(finished.handle.ready).resolves.toBeUndefined();
+  expect(finished.closed).toEqual([{}]);
+});
+
+it("closes a subscription whose event fails the contract and drops what follows", async () => {
+  const { open } = installation();
+  const { handle, received, closed, host } = open("a");
+  host.acknowledge();
+  await handle.ready;
+  host.event({ path: 3 });
+  host.event({ path: "late.ts" });
+  expect(received).toEqual([]);
+  expect(closed).toEqual([
+    { error: new Error("Plugin subscription diff.watch sent an invalid event") },
+  ]);
+  await host.released;
+});
+
+it("releases on its signal, on its remover, and when the installation stops", async () => {
+  const { open, lifetime } = installation();
+  const controller = new AbortController();
+  const bySignal = open("a", controller.signal);
+  bySignal.host.acknowledge();
+  await bySignal.handle.ready;
+  controller.abort();
+  await bySignal.host.released;
+
+  const byRemover = open("b");
+  byRemover.handle();
+  await byRemover.host.released;
+
+  const byLifetime = open("c");
+  byLifetime.host.event({ path: "a.ts" });
+  expect(byLifetime.received).toEqual(["path:a.ts"]);
+  lifetime.abort();
+  await byLifetime.host.released;
+});

packages/app/src/plugins/subscriptions.ts

@@ -0,0 +1,52 @@
+import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import type { PluginSubscribe } from "@getpaseo/plugin/client/host";
+
+/**
+ * Plugin subscriptions on the installation's client. The client re-subscribes after a reconnect;
+ * the installation's lifetime releases whatever its surfaces left open.
+ */
+export function createPluginSubscribe(input: {
+  client: Pick<DaemonClient, "observePluginRpc">;
+  pluginId: string;
+  lifetime: AbortSignal;
+}): PluginSubscribe {
+  const { client, pluginId, lifetime } = input;
+  return (method, subscriptionInput, observer) => {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    lifetime.addEventListener("abort", abort, { once: true });
+    controller.signal.addEventListener(
+      "abort",
+      () => lifetime.removeEventListener("abort", abort),
+      { once: true },
+    );
+    if (lifetime.aborted) controller.abort();
+    const subscription = client.observePluginRpc(pluginId, method, subscriptionInput, {
+      signal: controller.signal,
+    });
+    subscription.subscribe({
+      snapshot: () => undefined,
+      update: (message) => {
+        if (message.type === "plugin.rpc.event") observer.event(message.payload.event);
+        else if (message.type === "plugin.rpc.closed") {
+          controller.abort();
+          const error = message.payload.error;
+          observer.closed(error === undefined ? undefined : new Error(error));
+        }
+      },
+      binary: (payload) => observer.event(payload),
+      error: (error) => {
+        controller.abort();
+        observer.closed(error instanceof Error ? error : new Error(String(error)));
+      },
+    });
+    const release = () => {
+      controller.abort();
+      return subscription.release();
+    };
+    return Object.assign(() => void release().catch(() => undefined), {
+      ready: subscription.ready.then(() => undefined),
+      release,
+    });
+  };
+}

packages/app/src/plugins/surface-contribution.test.ts

@@ -26,6 +26,9 @@ function installation(
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     cleanup: () => undefined,
     settingsScreens: [],
     surfaces: surfaces.map((id) => ({ id, title: id, Component: () => null })),

packages/app/src/plugins/theme.test.ts

@@ -56,6 +56,9 @@ function installed(serverId: string, themes: PluginThemeContribution[]): Install
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     settingsScreens: [],
     surfaces: [],
     sidebarItems: { header: [], footer: [] },

packages/app/src/plugins/timeline/model.test.ts

@@ -18,6 +18,9 @@ function plugin(input: {
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     cleanup: () => {},
     settingsScreens: [],
     surfaces: [],

packages/app/src/plugins/timeline/projection.test.ts

@@ -14,6 +14,45 @@ function thought(text: string, status: "loading" | "ready" = "loading"): StreamI
 }
 
 describe("plugin timeline projection", () => {
+  it.each(["message", "finished", "errored", "permission-required", "closed"] as const)(
+    "preserves immutable agent-message provenance for %s cards",
+    (event) => {
+      const agentMessage = {
+        event,
+        sender: { id: "remote::reviewer", title: "QA question-timing #7014/#7000/#6809" },
+        text: "The original message, including **Markdown**.",
+      };
+      const source: StreamItem = {
+        kind: "tool_call",
+        id: "message-1",
+        timestamp: new Date("2026-01-01T00:00:00.000Z"),
+        payload: {
+          source: "agent",
+          data: {
+            provider: "codex",
+            callId: "delivery-1",
+            name: "agent_message",
+            status: "completed",
+            error: null,
+            detail: { type: "plain_text", text: agentMessage.text, icon: "bot" },
+            agentMessage,
+          },
+        },
+      };
+      const inspect: TimelineItemTransform = ({ item }) => {
+        expect(item.type).toBe("tool_call");
+        if (item.type !== "tool_call") throw new Error("Expected a tool call");
+        expect(item.agentMessage).toEqual(agentMessage);
+        expect(item.agentMessage).not.toBe(agentMessage);
+        expect(Object.isFrozen(item.agentMessage)).toBe(true);
+        expect(Object.isFrozen(item.agentMessage?.sender)).toBe(true);
+        return undefined;
+      };
+      expect(projectPluginTimelineItems([source], inspect)).toEqual([source]);
+      expect(Object.isFrozen(agentMessage.sender)).toBe(false);
+    },
+  );
+
   it("does not expose mutable tool detail from stream state", () => {
     const detail = { type: "read" as const, filePath: "/repo/original.ts" };
     const source: StreamItem = {

packages/app/src/plugins/timeline/projection.ts

@@ -22,13 +22,14 @@ function cloneAndFreeze<T>(value: T): T {
 }
 
 function sourceToolCallTimelineItem(data: AgentToolCallData): ToolCallTimelineItem {
-  const { callId, name, status, error, detail, metadata } = data;
+  const { callId, name, status, error, detail, metadata, agentMessage } = data;
   const base = {
     type: "tool_call" as const,
     callId,
     name,
     detail,
     ...(metadata ? { metadata } : {}),
+    ...(agentMessage ? { agentMessage } : {}),
   };
   switch (status) {
     case "running":

packages/app/src/plugins/types.ts

@@ -71,6 +71,8 @@ export interface InstalledPlugin extends EvaluatedPlugin {
   paseo: PaseoApi;
   /** Calls one of the plugin's server RPC methods on its host. */
   invoke(method: string, input: unknown): Promise<unknown>;
+  /** Subscribes to one of the plugin's server subscriptions; released with the lifetime. */
+  subscribe: import("@getpaseo/plugin/client/host").PluginSubscribe;
   serverId: string;
   requirements?: PluginRequirements;
   clientBundle: string;

packages/app/src/plugins/workspace-panels/resolution.test.ts

@@ -15,6 +15,9 @@ function installed(): InstalledPlugin {
     queryClient: new QueryClient(),
     paseo: {} as InstalledPlugin["paseo"],
     invoke: async () => undefined,
+    subscribe: () => {
+      throw new Error("Subscriptions are not used here");
+    },
     cleanup: () => {},
     settingsScreens: [],
     surfaces: [],

packages/app/src/screens/new-workspace-screen.tsx

@@ -1,3 +1,4 @@
+import { useAddHost } from "@/hosts/add-host";
 import type {
   CreateAgentRequestOptions,
   CreateWorkspaceRequestOptions,
@@ -8,7 +9,6 @@ import { getHostRuntimeStore } from "@/runtime/host-runtime";
 import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
 import type { ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import { router } from "expo-router";
 import { Text, View } from "react-native";
 import { StyleSheet } from "react-native-unistyles";
 import { createNameId } from "mnemonic-id";
@@ -62,7 +62,6 @@ import type { KeyboardActionId } from "@/keyboard/keyboard-action-dispatcher";
 import { useFormPreferences } from "@/hooks/use-form-preferences";
 import type { CreateAgentInitialValues } from "@/hooks/use-agent-form-state";
 import { toErrorMessage } from "@/utils/error-messages";
-import { buildSettingsAddHostRoute } from "@/utils/host-routes";
 import {
   getHostProjectId,
   getWorktreeSupportForHostProject,
@@ -1166,9 +1165,7 @@ export function NewWorkspaceScreen({
     openAddProjectPicker(selectedServerId);
   }, [openAddProjectPicker, selectedServerId]);
 
-  const handleAddHost = useCallback(() => {
-    router.push(buildSettingsAddHostRoute(Date.now()));
-  }, []);
+  const handleAddHost = useAddHost();
 
   const openPicker = useCallback(() => {
     setPickerOpen(true);

packages/app/src/screens/settings-screen.tsx

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useAddHost } from "@/hosts/add-host";
+import { useCallback, useMemo, useRef, useState } from "react";
 import type { ComponentType, ReactNode } from "react";
 import {
   Alert,
@@ -74,10 +75,6 @@ import { WindowChromeRegion, WindowChromeSafeArea } from "@/utils/desktop-window
 import { confirmDialog } from "@/utils/confirm-dialog";
 import { BackHeader } from "@/components/headers/back-header";
 import { PageLayout } from "@/components/page-layout";
-import { AddHostMethodModal } from "@/components/add-host-method-modal";
-import { AddHostModal } from "@/components/add-host-modal";
-import { AddRemoteSshHostModal } from "@/components/add-remote-ssh-host-modal";
-import { PairLinkModal } from "@/components/pair-link-modal";
 import { KeyboardShortcutsSection } from "@/screens/settings/keyboard-shortcuts-section";
 import { EditorSection } from "@/screens/settings/editor-section";
 import { FilesSection } from "@/screens/settings/files-section";
@@ -1089,21 +1086,15 @@ function SettingsSidebar({
 
 export interface SettingsScreenProps {
   view: SettingsView;
-  openAddHostIntent?: string | null;
 }
 
-export default function SettingsScreen({ view, openAddHostIntent = null }: SettingsScreenProps) {
+export default function SettingsScreen({ view }: SettingsScreenProps) {
   const router = useRouter();
   const { t } = useTranslation();
   const voiceAudioEngine = useVoiceAudioEngineOptional();
   const { settings, isLoading: settingsLoading, updateSettings } = useAppSettings();
-  const [isAddHostMethodVisible, setIsAddHostMethodVisible] = useState(false);
-  const [isDirectHostVisible, setIsDirectHostVisible] = useState(false);
-  const [isRemoteSshVisible, setIsRemoteSshVisible] = useState(false);
-  const [isPasteLinkVisible, setIsPasteLinkVisible] = useState(false);
   const [isPlaybackTestRunning, setIsPlaybackTestRunning] = useState(false);
   const [playbackTestResult, setPlaybackTestResult] = useState<string | null>(null);
-  const lastOpenedAddHostIntentRef = useRef<string | null>(null);
   const isDesktopApp = isElectronRuntime();
   const appVersion = resolveAppVersion();
   const appVersionText = formatVersionWithPrefix(appVersion);
@@ -1164,50 +1155,10 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     }
   }, [isPlaybackTestRunning, t, voiceAudioEngine]);
 
-  const closeAddConnectionFlow = useCallback(() => {
-    setIsAddHostMethodVisible(false);
-    setIsDirectHostVisible(false);
-    setIsRemoteSshVisible(false);
-    setIsPasteLinkVisible(false);
-  }, []);
-
-  const goBackToAddConnectionMethods = useCallback(() => {
-    setIsDirectHostVisible(false);
-    setIsRemoteSshVisible(false);
-    setIsPasteLinkVisible(false);
-    setIsAddHostMethodVisible(true);
-  }, []);
-
-  const handleAddHost = useCallback(() => {
-    setIsAddHostMethodVisible(true);
-  }, []);
-
-  useEffect(() => {
-    if (!openAddHostIntent || lastOpenedAddHostIntentRef.current === openAddHostIntent) {
-      return;
-    }
-    lastOpenedAddHostIntentRef.current = openAddHostIntent;
-    handleAddHost();
-  }, [handleAddHost, openAddHostIntent]);
-
-  const handleSelectDirectConnection = useCallback(() => {
-    setIsAddHostMethodVisible(false);
-    setIsDirectHostVisible(true);
-  }, []);
-
-  const handleSelectRemoteSsh = useCallback(() => {
-    setIsAddHostMethodVisible(false);
-    setIsRemoteSshVisible(true);
-  }, []);
-
-  const handleSelectPasteLink = useCallback(() => {
-    setIsAddHostMethodVisible(false);
-    setIsPasteLinkVisible(true);
-  }, []);
-
   const handleHostAdded = useCallback(
-    ({ serverId }: { serverId: string }) => {
-      const target = buildSettingsHostSectionRoute(serverId, "connections");
+    (serverId: string) => {
+      selectSettingsHost(serverId);
+      const target = buildSettingsHostSectionRoute(serverId, "host");
       if (isCompactLayout) {
         router.push(target);
       } else {
@@ -1217,6 +1168,8 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     [isCompactLayout, router],
   );
 
+  const handleAddHost = useAddHost({ onAdded: handleHostAdded });
+
   const handleSelectSection = useCallback(
     (section: SettingsSectionSlug) => {
       const target = buildSettingsSectionRoute(section);
@@ -1272,14 +1225,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     [activeHostServerId, handleAddHost, isCompactLayout, router],
   );
 
-  const handleScanQr = useCallback(() => {
-    closeAddConnectionFlow();
-    router.push({
-      pathname: "/pair-scan",
-      params: { source: "settings" },
-    });
-  }, [closeAddConnectionFlow, router]);
-
   const handleHostRemoved = useCallback(() => {
     const fallback = buildSettingsSectionRoute("general");
     if (isCompactLayout) {
@@ -1388,37 +1333,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
     );
   }
 
-  const addHostModals = (
-    <>
-      <AddHostMethodModal
-        visible={isAddHostMethodVisible}
-        onClose={closeAddConnectionFlow}
-        onDirectConnection={handleSelectDirectConnection}
-        onRemoteSsh={handleSelectRemoteSsh}
-        onPasteLink={handleSelectPasteLink}
-        onScanQr={handleScanQr}
-      />
-      <AddHostModal
-        visible={isDirectHostVisible}
-        onClose={closeAddConnectionFlow}
-        onCancel={goBackToAddConnectionMethods}
-        onSaved={handleHostAdded}
-      />
-      <AddRemoteSshHostModal
-        visible={isRemoteSshVisible}
-        onClose={closeAddConnectionFlow}
-        onCancel={goBackToAddConnectionMethods}
-        onSaved={handleHostAdded}
-      />
-      <PairLinkModal
-        visible={isPasteLinkVisible}
-        onClose={closeAddConnectionFlow}
-        onCancel={goBackToAddConnectionMethods}
-        onSaved={handleHostAdded}
-      />
-    </>
-  );
-
   // Mobile root: full-screen sidebar-as-list.
   if (isCompactLayout && view.kind === "root") {
     return (
@@ -1436,7 +1350,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
             layout="mobile"
           />
         </ScrollView>
-        {addHostModals}
       </View>
     );
   }
@@ -1447,7 +1360,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
         <PageLayout title={detailTitle} onBack={handleBackFromDetail}>
           {content}
         </PageLayout>
-        {addHostModals}
       </View>
     );
   }
@@ -1482,7 +1394,6 @@ export default function SettingsScreen({ view, openAddHostIntent = null }: Setti
           </View>
         </WindowChromeRegion>
       </View>
-      {addHostModals}
     </View>
   );
 }

packages/app/src/terminal/runtime/terminal-emulator-runtime.browser.test.ts

@@ -717,11 +717,13 @@ describe("terminal emulator runtime in a real browser", () => {
     { name: "DA1-zero", bytes: "\x1b[0c" },
     { name: "DA2", bytes: "\x1b[>c" },
     { name: "DA3", bytes: "\x1b[=c" },
+    { name: "XTVERSION", bytes: "\x1b[>q" },
     { name: "DSR-5", bytes: "\x1b[5n" },
     { name: "DSR-6", bytes: "\x1b[6n" },
     { name: "DSR-?6", bytes: "\x1b[?6n" },
     { name: "DECRQM", bytes: "\x1b[1$p" },
     { name: "DECRQM-?", bytes: "\x1b[?1$p" },
+    { name: "DECRQSS", bytes: "\x1bP$qm\x1b\\" },
     { name: "OSC-10-foreground-color", bytes: "\x1b]10;?\x07" },
     { name: "OSC-11-background-color", bytes: "\x1b]11;?\x07" },
     { name: "OSC-12-cursor-color", bytes: "\x1b]12;?\x07" },

packages/app/src/terminal/runtime/terminal-emulator-runtime.ts

@@ -647,6 +647,7 @@ export class TerminalEmulatorRuntime {
       terminal.parser.registerCsiHandler({ final: "c" }, () => true);
       terminal.parser.registerCsiHandler({ prefix: ">", final: "c" }, () => true);
       terminal.parser.registerCsiHandler({ prefix: "=", final: "c" }, () => true);
+      terminal.parser.registerCsiHandler({ prefix: ">", final: "q" }, () => true);
       terminal.parser.registerCsiHandler({ final: "n" }, () => true);
       terminal.parser.registerCsiHandler({ prefix: "?", final: "n" }, () => true);
       terminal.parser.registerCsiHandler({ final: "R" }, () => true);
@@ -655,6 +656,7 @@ export class TerminalEmulatorRuntime {
         { prefix: "?", intermediates: "$", final: "p" },
         () => true,
       );
+      terminal.parser.registerDcsHandler({ intermediates: "$", final: "q" }, () => true);
       for (const code of [10, 11, 12]) {
         terminal.parser.registerOscHandler(code, (data) => data.trim() === "?");
       }

packages/app/src/utils/host-routes.test.ts

@@ -8,7 +8,6 @@ import {
   buildOpenProjectRoute,
   resolveKnownHostRoute,
   buildSessionsRoute,
-  buildSettingsAddHostRoute,
   buildProjectSettingsRoute,
   buildProjectsSettingsRoute,
   decodeFilePathFromPathSegment,
@@ -185,14 +184,6 @@ describe("workspace route parsing", () => {
 });
 
 describe("projects settings routes", () => {
-  it("buildSettingsAddHostRoute opens settings with the add-host flag", () => {
-    expect(buildSettingsAddHostRoute()).toBe("/settings/general?addHost=1");
-  });
-
-  it("buildSettingsAddHostRoute accepts a repeatable intent id", () => {
-    expect(buildSettingsAddHostRoute("retry 1")).toBe("/settings/general?addHost=retry%201");
-  });
-
   it("buildProjectsSettingsRoute scopes the list to a host", () => {
     expect(buildProjectsSettingsRoute("host a")).toBe("/settings/hosts/host%20a/projects");
   });

packages/app/src/utils/host-routes.ts

@@ -553,10 +553,6 @@ export function buildSettingsSectionRoute(section: SettingsSectionSlug) {
   return `/settings/${section}` as const;
 }
 
-export function buildSettingsAddHostRoute(intentId: string | number = "1") {
-  return `/settings/general?addHost=${encodeURIComponent(String(intentId))}` as const;
-}
-
 export function buildSettingsHostRoute(serverId: string) {
   const normalized = trimNonEmpty(serverId);
   if (!normalized) {

packages/client/src/connection/index.ts

@@ -144,6 +144,7 @@ export const DEFAULT_CLIENT_CAPABILITIES = {
   [CLIENT_CAPS.pluginTimelineItems]: true,
   [CLIENT_CAPS.workspaceSetupBlocked]: true,
   [CLIENT_CAPS.workspaceSetupObservation]: true,
+  [CLIENT_CAPS.pluginBinaryPayloads]: true,
   [CLIENT_CAPS.explicitEventSubscriptions]: true,
 } satisfies Record<Exclude<ClientCapability, typeof CLIENT_CAPS.browserHost>, true>;
 

packages/client/src/connection/owned.test.ts

@@ -83,6 +83,26 @@ test("cancellation before the ID waits for bootstrap and releases exactly that I
   expect(c.released).toEqual(["cancelled"]);
 });
 
+test("a release right after the host accepts still reports the subscription as accepted", async () => {
+  const c = connection();
+  const handle = c.observe();
+  c.requests[0]!("closing");
+  const released = handle.release();
+  await expect(handle.ready).resolves.toMatchObject({ subscriptionId: "closing" });
+  await released;
+  expect(c.released).toEqual(["closing"]);
+});
+
+test("a release before the host accepts rejects ready", async () => {
+  const c = connection();
+  const handle = c.observe();
+  const released = handle.release();
+  await expect(handle.ready).rejects.toThrow("Subscription released");
+  c.requests[0]!("late");
+  await released;
+  expect(c.released).toEqual(["late"]);
+});
+
 test("surviving handles use new remote IDs after reconnect and released handles stay gone", async () => {
   const c = connection();
   const a = c.observe();

packages/client/src/connection/owned.ts

@@ -5,6 +5,8 @@ export type SubscriptionSnapshot<T> = T & { subscriptionId: string };
 export interface SubscriptionObserver<T> {
   snapshot(snapshot: T): void;
   update(message: SessionOutboundMessage): void;
+  /** A binary frame the host addressed to this subscription; the payload is a view. */
+  binary?(payload: Uint8Array): void;
   error?(error: unknown): void;
 }
 
@@ -20,9 +22,12 @@ interface Registration {
   start(): void;
   disconnected(): void;
   receive(message: SessionOutboundMessage): void;
+  receiveBinary(payload: Uint8Array): void;
   release(): Promise<void>;
 }
 
+type Update = { message: SessionOutboundMessage } | { binary: Uint8Array };
+
 export interface OwnedSubscriptionsHost {
   release(subscriptionId: string): Promise<void>;
   failed(error: unknown): void;
@@ -50,7 +55,7 @@ export class OwnedSubscriptions {
     let teardown: Promise<void> | null = null;
     let disposed = false;
     let overflow = false;
-    const buffered: SessionOutboundMessage[] = [];
+    const buffered: Update[] = [];
     const observers = new Set<SubscriptionObserver<SubscriptionSnapshot<T>>>();
     let resolve!: (snapshot: SubscriptionSnapshot<T>) => void;
     let reject!: (error: unknown) => void;
@@ -60,12 +65,10 @@ export class OwnedSubscriptions {
     });
     void ready.catch(() => {});
 
-    const deliver = (
-      observer: SubscriptionObserver<SubscriptionSnapshot<T>>,
-      message?: SessionOutboundMessage,
-    ) => {
+    const deliver = (observer: SubscriptionObserver<SubscriptionSnapshot<T>>, update?: Update) => {
       try {
-        if (message) observer.update(message);
+        if (update && "binary" in update) observer.binary?.(update.binary);
+        else if (update) observer.update(update.message);
         else if (snapshot) observer.snapshot(snapshot);
       } catch (error) {
         this.host.failed(error);
@@ -78,6 +81,13 @@ export class OwnedSubscriptions {
       this.routes.delete(released);
       await this.host.release(released);
     };
+    const buffer = (update: Update) => {
+      if (buffered.length < MAX_BOOTSTRAP_UPDATES && !overflow) buffered.push(update);
+      else {
+        buffered.length = 0;
+        overflow = true;
+      }
+    };
     const registration: Registration = {
       start: () => {
         if (disposed || pending || id || !this.connected) return;
@@ -128,12 +138,14 @@ export class OwnedSubscriptions {
       },
       receive: (message) => {
         if (disposed || ("payload" in message && Object.is(message.payload, snapshot))) return;
-        if (buffered.length < MAX_BOOTSTRAP_UPDATES && !overflow) buffered.push(message);
-        else {
-          buffered.length = 0;
-          overflow = true;
-        }
-        for (const observer of observers) deliver(observer, message);
+        buffer({ message });
+        for (const observer of observers) deliver(observer, { message });
+      },
+      receiveBinary: (payload) => {
+        if (disposed) return;
+        // Bytes wait only for the first observer; retaining them after would hold every frame.
+        if (observers.size === 0) buffer({ binary: payload });
+        for (const observer of observers) deliver(observer, { binary: payload });
       },
       release: () => {
         if (teardown) return teardown;
@@ -142,7 +154,9 @@ export class OwnedSubscriptions {
         observers.clear();
         buffered.length = 0;
         if (id) this.routes.delete(id);
-        reject(new Error("Subscription released"));
+        // A host that already accepted keeps `ready` resolved, even if released in the same tick.
+        if (snapshot) resolve(snapshot);
+        else reject(new Error("Subscription released"));
         teardown = (async () => {
           await pending;
           await releaseId();
@@ -174,7 +188,7 @@ export class OwnedSubscriptions {
             .catch(this.host.failed);
         } else {
           deliver(observer);
-          for (const message of buffered) deliver(observer, message);
+          for (const update of buffered) deliver(observer, update);
         }
         return () => {
           observers.delete(observer);
@@ -205,6 +219,10 @@ export class OwnedSubscriptions {
       this.routes.get(payload.subscriptionId)?.receive(message);
   }
 
+  receiveBinary(subscriptionId: string, payload: Uint8Array): void {
+    this.routes.get(subscriptionId)?.receiveBinary(payload);
+  }
+
   restore(): void {
     this.connected = true;
     for (const registration of this.registrations) registration.start();

packages/client/src/daemon-client.test.ts

@@ -1106,6 +1106,7 @@ test("advertises client capabilities in hello", async () => {
       terminal_chunked_replay: true,
       timeline_notifications: true,
       plugin_timeline_items: true,
+      plugin_binary_payloads: true,
       workspace_setup_blocked: true,
       workspace_setup_observation: true,
       hello_rejection: true,

packages/client/src/daemon-client.ts

@@ -164,6 +164,11 @@ import {
   FileTransferOpcode,
   TerminalStreamOpcode,
   type FileTransferFrame,
+  assertPluginWireValue,
+  decodePluginFrame,
+  encodePluginInputFrame,
+  isPluginFrameOpcode,
+  PluginFrameOpcode,
 } from "@getpaseo/protocol/binary-frames/index";
 import {
   createRelayE2eeTransportFactory,
@@ -2260,6 +2265,8 @@ export class DaemonClient {
     timeout?: number;
     select: (msg: SessionOutboundMessage) => T | null;
     options?: { skipQueue?: boolean };
+    /** Sends the request in another form, such as a binary frame; defaults to `message`. */
+    transmit?: () => Promise<void>;
   }): Promise<T> {
     const wire = this.owned.prepareRequest(params.message);
     const timeout = params.timeout ?? DEFAULT_SESSION_RPC_TIMEOUT_MS;
@@ -2290,7 +2297,9 @@ export class DaemonClient {
     // The response deadline still applies while the transport waits for drain.
     void promise.catch(() => undefined);
     try {
-      const sent = this.sendSessionMessageOrThrow(wire.message);
+      const sent = params.transmit
+        ? params.transmit()
+        : this.sendSessionMessageOrThrow(wire.message);
       const result = await Promise.race([promise, sent.then(() => promise)]);
       if (result.kind === "error") throw result.error;
       return result.value;
@@ -2313,12 +2322,14 @@ export class DaemonClient {
     responseType: TResponseType;
     options?: { skipQueue?: boolean };
     selectPayload?: (payload: CorrelatedResponsePayload<TResponseType>) => TResult | null;
+    transmit?: () => Promise<void>;
   }): Promise<TResult> {
     return this.sendRequest({
       requestId: params.requestId,
       message: params.message,
       timeout: params.timeout,
       options: params.options,
+      ...(params.transmit ? { transmit: params.transmit } : {}),
       select: (msg) => {
         const correlated = msg as CorrelatedResponseMessage;
         if (correlated.type !== params.responseType) {
@@ -2650,6 +2661,7 @@ export class DaemonClient {
         resetSource = false;
         if (query.type === "workspace.setup.subscribe.request")
           this.requireWorkspaceSetupObservation();
+        if (query.type === "plugin.rpc.subscribe.request") this.requirePluginSubscriptions();
         const requestId = this.createRequestId(options?.requestId);
         const request = SessionInboundMessageSchema.parse({ ...query, requestId });
         try {
@@ -6197,22 +6209,59 @@ export class DaemonClient {
     return payload.plugin;
   }
 
+  /**
+   * A `Uint8Array` input or output crosses the wire as a binary frame. Any other value is JSON and
+   * must not contain a `Uint8Array`.
+   */
   async invokePluginRpc(pluginId: string, method: string, input: unknown): Promise<unknown> {
+    assertPluginWireValue(input, "input");
     const requestId = this.createRequestId();
-    const payload = await this.sendCorrelatedSessionRequest({
-      requestId,
-      message: {
-        type: "plugin.rpc.invoke.request",
+    if (!(input instanceof Uint8Array)) {
+      const payload = await this.sendCorrelatedSessionRequest({
         requestId,
-        pluginId,
-        method,
-        input,
-      },
+        message: {
+          type: "plugin.rpc.invoke.request",
+          requestId,
+          pluginId,
+          method,
+          input,
+        },
+        responseType: "plugin.rpc.invoke.response",
+      });
+      return payload.output;
+    }
+    this.requirePluginSubscriptions();
+    const frame = encodePluginInputFrame({ requestId, pluginId, method, payload: input });
+    const payload = await this.sendCorrelatedRequest({
+      requestId,
+      message: { type: "plugin.rpc.invoke.request", requestId, pluginId, method, input: null },
       responseType: "plugin.rpc.invoke.response",
+      options: { skipQueue: true },
+      transmit: () => this.sendBinaryFrame(frame),
     });
     return payload.output;
   }
 
+  /** One subscription to a plugin subscription handler; events arrive as updates and binary. */
+  observePluginRpc(
+    pluginId: string,
+    method: string,
+    input: unknown,
+    options?: { signal?: AbortSignal },
+  ): OwnedSubscription<CorrelatedResponsePayload<"plugin.rpc.subscribe.response">> {
+    assertPluginWireValue(input, "input");
+    return this.observe(
+      "plugin.rpc.subscribe.response",
+      { type: "plugin.rpc.subscribe.request", pluginId, method, input },
+      options,
+    );
+  }
+
+  private requirePluginSubscriptions(): void {
+    if (this.lastServerInfoMessage?.features?.pluginSubscriptions !== true)
+      throw new Error("Update the host to use plugin subscriptions and binary plugin RPC");
+  }
+
   async respondToPermissionAndWait(
     agentId: string,
     requestId: string,
@@ -6975,6 +7024,23 @@ export class DaemonClient {
     }
   }
 
+  private handlePluginFrame(rawBytes: Uint8Array): void {
+    const frame = decodePluginFrame(rawBytes);
+    this.consecutiveLivenessFailures = 0;
+    this.runtimeMetrics?.recordBinaryFrame("plugin", rawBytes.byteLength, 0);
+    if (frame?.opcode === PluginFrameOpcode.Event) {
+      this.owned.receiveBinary(frame.subscriptionId, frame.payload);
+      return;
+    }
+    if (frame?.opcode === PluginFrameOpcode.Output) {
+      // The binary form of plugin.rpc.invoke.response.
+      this.resolveWaiters({
+        type: "plugin.rpc.invoke.response",
+        payload: { requestId: frame.requestId, output: frame.payload },
+      });
+    }
+  }
+
   private tryHandleBinaryFrame(rawBytes: Uint8Array): boolean {
     const hostFrame = decodeHostRouteFrame(rawBytes);
     if (rawBytes[0] === HOST_ROUTE_OPCODE && !hostFrame) {
@@ -6986,6 +7052,10 @@ export class DaemonClient {
       for (const handler of this.hostFrameListeners) handler(hostFrame);
       return true;
     }
+    if (isPluginFrameOpcode(rawBytes[0])) {
+      this.handlePluginFrame(rawBytes);
+      return true;
+    }
     const fileFrame = decodeFileTransferFrame(rawBytes);
     if (fileFrame) {
       this.traceInstant("paseo.ws.message.inbound", {

packages/client/src/node/index.ts

@@ -204,15 +204,16 @@ export function createHostTransportFactory(
 }
 export function createHostClient(
   connection: string,
-  config: Omit<DaemonClientConfig, "url" | "transportFactory"> & HostTransportOptions,
+  config: Omit<DaemonClientConfig, "url"> & HostTransportOptions,
   budget?: HostTransportBudget,
 ): DaemonClient {
   const target = parseHostTarget(connection);
-  const { webSocketAgent, ...clientConfig } = config;
+  const { webSocketAgent, transportFactory, ...clientConfig } = config;
   return new DaemonClient({
     ...clientConfig,
     url: "ws://host-connector/ws",
     ...(target.password ? { password: target.password } : {}),
-    transportFactory: createHostTransportFactory(connection, budget, { webSocketAgent }),
+    transportFactory:
+      transportFactory ?? createHostTransportFactory(connection, budget, { webSocketAgent }),
   });
 }

packages/desktop/e2e/browser-tabs.e2e.mjs

@@ -12,6 +12,7 @@ import { fileURLToPath } from "node:url";
 import { experimental_createMCPClient } from "ai";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { chromium } from "playwright";
+import { expect } from "@playwright/test";
 import { hideDeveloperToasts } from "../../app/e2e/support/developer-ui.mjs";
 import { runAppearanceFontSizeRegression } from "./appearance-font-size.electron.mjs";
 import { runAdaptiveThemeRegression } from "./appearance-theme.electron.mjs";
@@ -198,6 +199,20 @@ async function waitForDesktopStatus(page) {
   );
 }
 
+async function settleDesktopStartup(page) {
+  await expect(
+    page.getByRole("button", { name: "Desktop browser workspace 1", exact: true }),
+  ).toBeVisible({ timeout: timeoutMs });
+  // The dev launcher supplies its package directory as an open-project request.
+  // Before the local host connects, that request opens the connection prompt.
+  // Finish startup before exercising the unrelated Settings/browser workflows.
+  const connectionPrompt = page.getByTestId("add-host-method-modal");
+  if (await connectionPrompt.isVisible()) {
+    await connectionPrompt.getByRole("button", { name: "Close", exact: true }).click();
+    await expect(connectionPrompt).toBeHidden();
+  }
+}
+
 async function startTargetPage() {
   const server = createServer((_request, response) => {
     response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
@@ -1208,6 +1223,7 @@ async function main() {
     const page = await waitForAppPage(browser, expoPort);
     await hideDeveloperToasts(page);
     const status = await waitForDesktopStatus(page);
+    await settleDesktopStartup(page);
 
     const checkPluginLinks = () =>
       runPluginLinksRegression({

packages/desktop/package.json

@@ -41,7 +41,7 @@
     "@types/node": "24.6.0",
     "@types/ws": "^8.5.14",
     "electron": "44.2.0",
-    "electron-builder": "26.8.1",
+    "electron-builder": "26.18.0",
     "typescript": "5.9.3",
     "unzip-crx-3": "^0.2.0",
     "vitest": "^4.1.6",

packages/plugin/src/boundaries.test.ts

@@ -323,3 +323,68 @@ describe("agent session reload SDK boundary", () => {
     ).toEqual([]);
   });
 });
+
+describe("plugin subscription SDK boundary", () => {
+  it("types contracts, overloaded handlers, the client hook, and the client entry handle", () => {
+    expect(
+      typeErrors(`
+      import { defineRpc, defineSubscription, type SubscriptionEvent, type SubscriptionInput } from "@getpaseo/plugin";
+      import type { PluginClientContext } from "@getpaseo/plugin/client";
+      import { useRpc, useSubscription } from "@getpaseo/plugin/client";
+      import type { PluginServerContext, PluginSubscriptionContext } from "@getpaseo/plugin/server";
+      import { z } from "zod";
+      const diffWatch = defineSubscription({
+        name: "diff.watch",
+        input: z.object({ a: z.string(), b: z.string() }),
+        event: z.object({ path: z.string(), status: z.enum(["added", "modified", "deleted"]) }),
+      });
+      const frames = defineSubscription({
+        name: "screen.capture",
+        input: z.object({ display: z.number() }),
+        event: z.union([z.instanceof(Uint8Array), z.object({ type: z.literal("resized"), width: z.number() })]),
+      });
+      const thumbnail = defineRpc({ name: "thumbnail.render", input: z.object({ path: z.string() }), output: z.instanceof(Uint8Array) });
+      const input: SubscriptionInput<typeof diffWatch> = { a: "main", b: "HEAD" };
+      const event: SubscriptionEvent<typeof diffWatch> = { path: "a.ts", status: "added" };
+      function server(server: PluginServerContext) {
+        server.handle(diffWatch, ({ a, b }, { push, signal, paseo }: PluginSubscriptionContext<SubscriptionEvent<typeof diffWatch>>) => {
+          const pushed: Promise<void> = push({ path: a + b, status: "modified" });
+          // @ts-expect-error events follow the contract
+          void push({ path: 1, status: "modified" });
+          signal.addEventListener("abort", () => undefined, { once: true });
+        });
+        server.handle(frames, async (_input, { push }) => {
+          await push(new Uint8Array(4));
+          await push({ type: "resized", width: 2 });
+        });
+        server.handle(thumbnail, ({ path }) => new Uint8Array(path.length));
+        // @ts-expect-error subscription handlers receive push, not an output
+        server.handle(diffWatch, () => ({ path: "a", status: "added" as const }) as unknown as number);
+      }
+      function Panel() {
+        const state = useSubscription(diffWatch, { a: "main", b: "HEAD" }, (change) => {
+          const status: "added" | "modified" | "deleted" = change.status;
+        });
+        if (state.status === "error") state.error.message;
+        // @ts-expect-error the hook has no ready state, only live
+        if (state.status === "ready") return null;
+        useSubscription(frames, { display: 1 }, (event) => {
+          if (event instanceof Uint8Array) event.byteLength;
+          else event.width;
+        });
+        const render = useRpc(thumbnail);
+        void render({ path: "x" }).then((png: Uint8Array) => png.byteLength);
+        return null;
+      }
+      function client(client: PluginClientContext) {
+        const controller = new AbortController();
+        const remover = client.subscribe(diffWatch, { a: "main", b: "HEAD" }, (change) => change.path, { signal: controller.signal });
+        const ready: Promise<void> = remover.ready;
+        const released: Promise<void> = remover.release();
+        remover();
+        return () => {};
+      }
+    `),
+    ).toEqual([]);
+  });
+});

packages/plugin/src/client/contracts.ts

@@ -4,7 +4,13 @@ import type { PaseoApi } from "@getpaseo/client";
 import type { AgentTimelineItem, JsonValue } from "@getpaseo/protocol/agent-types";
 import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
 import type { PluginFile } from "./file.js";
-import type { PluginRpcContract } from "../rpc.js";
+import type {
+  PluginRpcContract,
+  PluginSubscribeOptions,
+  PluginSubscriptionContract,
+  PluginSubscriptionHandle,
+  PluginWireInput,
+} from "../rpc.js";
 import type {
   PluginButtonRegistration,
   PluginHeaderButtonContribution,
@@ -203,6 +209,16 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl
     contribution: PluginTimelineRendererContribution<Schema>,
   ): PluginCleanup;
   openPanel(id: string, options: PluginClientOpenPanelOptions): void;
+  /**
+   * Subscribes to a plugin subscription on this client's host. Paseo re-subscribes after a
+   * reconnect and releases what is left when the plugin stops.
+   */
+  subscribe<InputSchema extends ZodType, EventSchema extends ZodType>(
+    contract: PluginSubscriptionContract<InputSchema, EventSchema>,
+    input: PluginWireInput<ZodInput<InputSchema>>,
+    onEvent: (event: ZodOutput<EventSchema>) => void,
+    options?: PluginSubscribeOptions,
+  ): PluginSubscriptionHandle;
 }
 
 export type PluginClientContribution = (client: PluginClientContext) => PluginCleanup;
@@ -295,7 +311,7 @@ export interface PluginCommandCapabilities {
   paseo: PaseoApi;
   rpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
     contract: PluginRpcContract<InputSchema, OutputSchema>,
-    input: ZodInput<InputSchema>,
+    input: PluginWireInput<ZodInput<InputSchema>>,
   ): Promise<ZodOutput<OutputSchema>>;
   openScreen(input: PluginOpenScreenInput): void;
   /** @deprecated Use `openScreen`. */

packages/plugin/src/client/host.ts

@@ -8,7 +8,7 @@ export {
 import type { PluginAttachmentSourceContribution } from "../contracts.js";
 import { PluginRpcProvider } from "./rpc-context.js";
 import { PaseoApiProvider } from "./paseo-context.js";
-import { callPluginRpc } from "../rpc.js";
+import { callPluginRpc, subscribePluginRpc, type PluginSubscriptionObserver } from "../rpc.js";
 
 export async function searchPluginAttachments(
   source: PluginAttachmentSourceContribution<PluginText>,
@@ -19,7 +19,9 @@ export async function searchPluginAttachments(
   return PluginAttachmentSearchPayloadSchema.parseAsync(output);
 }
 
-export { callPluginRpc, PaseoApiProvider, PluginRpcProvider };
+export { callPluginRpc, subscribePluginRpc, PaseoApiProvider, PluginRpcProvider };
+export type { PluginSubscriptionObserver };
+export type { PluginSubscribe } from "./rpc-context.js";
 
 export {
   PluginTranslationRuntime,

packages/plugin/src/client/index.ts

@@ -71,7 +71,12 @@ export {
 } from "./file.js";
 export { usePaseo } from "./paseo-context.js";
 export { useAgent, useWorkspace } from "./client-state.js";
-export { useRpc } from "./rpc-context.js";
+export { useRpc, useSubscription, type PluginSubscriptionState } from "./rpc-context.js";
+export type {
+  PluginSubscribeOptions,
+  PluginSubscriptionClosed,
+  PluginSubscriptionHandle,
+} from "../rpc.js";
 import type { SettingsDefinition } from "../settings.js";
 import type { SettingsState } from "./contracts.js";
 import type { ZodType } from "zod";

packages/plugin/src/client/rpc-context.tsx

@@ -1,9 +1,34 @@
-import { createContext, useCallback, useContext, useMemo, type ReactNode } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
-import { callPluginRpc, type PluginRpcContract } from "../rpc.js";
+import {
+  callPluginRpc,
+  subscribePluginRpc,
+  type PluginRpcContract,
+  type PluginSubscriptionContract,
+  type PluginSubscriptionHandle,
+  type PluginSubscriptionObserver,
+  type PluginWireInput,
+} from "../rpc.js";
+import { shallowEqual } from "./shallow.js";
+
+export type PluginSubscribe = (
+  method: string,
+  input: unknown,
+  observer: PluginSubscriptionObserver,
+) => PluginSubscriptionHandle;
 
 export interface PluginRpcContextValue {
   invoke(method: string, input: unknown): Promise<unknown>;
+  subscribe: PluginSubscribe;
 }
 
 const PluginRpcContext = createContext<PluginRpcContextValue | null>(null);
@@ -15,22 +40,100 @@ export function usePluginRpcContextValue(): PluginRpcContextValue | null {
 export function PluginRpcProvider({
   children,
   invoke,
+  subscribe,
 }: {
   children: ReactNode;
   invoke(method: string, input: unknown): Promise<unknown>;
+  subscribe: PluginSubscribe;
 }) {
-  const value = useMemo(() => ({ invoke }), [invoke]);
+  const value = useMemo(() => ({ invoke, subscribe }), [invoke, subscribe]);
   return <PluginRpcContext.Provider value={value}>{children}</PluginRpcContext.Provider>;
 }
 
 export function useRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
   contract: PluginRpcContract<InputSchema, OutputSchema>,
-): (input: ZodInput<InputSchema>) => Promise<ZodOutput<OutputSchema>> {
+): (input: PluginWireInput<ZodInput<InputSchema>>) => Promise<ZodOutput<OutputSchema>> {
   const context = usePluginRpcContextValue();
   if (!context) throw new Error("useRpc must run inside a contributed plugin surface");
 
   return useCallback(
-    (input: ZodInput<InputSchema>) => callPluginRpc(contract, context.invoke, input),
+    (input: PluginWireInput<ZodInput<InputSchema>>) =>
+      callPluginRpc(contract, context.invoke, input),
     [context, contract],
   );
 }
+
+export type PluginSubscriptionState =
+  | { status: "connecting" }
+  | { status: "live" }
+  /** The plugin's handler finished. The hook subscribes again when `input` changes. */
+  | { status: "closed" }
+  | { status: "error"; error: Error };
+
+/**
+ * Subscribes while the component is mounted. Re-subscribes when `input` changes by shallow
+ * comparison; `onEvent` always runs the latest callback.
+ */
+export function useSubscription<InputSchema extends ZodType, EventSchema extends ZodType>(
+  contract: PluginSubscriptionContract<InputSchema, EventSchema>,
+  input: PluginWireInput<ZodInput<InputSchema>>,
+  onEvent: (event: ZodOutput<EventSchema>) => void,
+): PluginSubscriptionState {
+  const context = usePluginRpcContextValue();
+  if (!context) throw new Error("useSubscription must run inside a contributed plugin surface");
+  const subscribe = context.subscribe;
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  const stableInput = useShallowStable(input);
+  const [state, setState] = useState<PluginSubscriptionState>({ status: "connecting" });
+
+  useEffect(() => {
+    let active = true;
+    setState({ status: "connecting" });
+    let handle: PluginSubscriptionHandle;
+    try {
+      handle = subscribePluginRpc(
+        contract,
+        subscribe,
+        stableInput,
+        (event) => onEventRef.current(event),
+        {
+          onClosed: ({ error }) => {
+            if (active) setState(error ? { status: "error", error } : CLOSED);
+          },
+        },
+      );
+    } catch (error) {
+      setState({ status: "error", error: toError(error) });
+      return;
+    }
+    handle.ready.then(
+      () => {
+        if (active) setState((current) => (current.status === "connecting" ? LIVE : current));
+        return undefined;
+      },
+      (error: unknown) => {
+        if (active) setState({ status: "error", error: toError(error) });
+      },
+    );
+    return () => {
+      active = false;
+      handle();
+    };
+  }, [contract, subscribe, stableInput]);
+
+  return state;
+}
+
+const LIVE: PluginSubscriptionState = { status: "live" };
+const CLOSED: PluginSubscriptionState = { status: "closed" };
+
+function useShallowStable<Value>(value: Value): Value {
+  const ref = useRef(value);
+  if (!shallowEqual(ref.current, value)) ref.current = value;
+  return ref.current;
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

packages/plugin/src/client/runtime-context-bridge.tsx

@@ -26,7 +26,7 @@ export function usePluginRuntimeContextBridge(): PluginRuntimeContextBridge {
       );
       return (
         <PaseoApiProvider paseo={paseo}>
-          <PluginRpcProvider invoke={rpc.invoke}>
+          <PluginRpcProvider invoke={rpc.invoke} subscribe={rpc.subscribe}>
             <PluginTranslationProvider runtime={translations}>{content}</PluginTranslationProvider>
           </PluginRpcProvider>
         </PaseoApiProvider>

packages/plugin/src/index.ts

@@ -19,7 +19,16 @@ export {
   type PluginAttachmentItem,
   type PluginAttachmentSearchPayload,
 } from "./attachments.js";
-export { defineRpc, type PluginRpcContract, type RpcInput, type RpcOutput } from "./rpc.js";
+export {
+  defineRpc,
+  defineSubscription,
+  type PluginRpcContract,
+  type PluginSubscriptionContract,
+  type RpcInput,
+  type RpcOutput,
+  type SubscriptionEvent,
+  type SubscriptionInput,
+} from "./rpc.js";
 
 export type { PluginText, PluginMessage } from "./text.js";
 export {

packages/plugin/src/rpc.ts

@@ -9,6 +9,12 @@ export interface PluginRpcContract<
   output: OutputSchema;
 }
 
+/**
+ * `z.instanceof(Uint8Array)` infers `Uint8Array<ArrayBuffer>`; values crossing the wire accept any
+ * `Uint8Array`, including a `Buffer` or a view of a shared buffer.
+ */
+export type PluginWireInput<Value> = Value extends Uint8Array ? Uint8Array : Value;
+
 export type RpcInput<Contract extends PluginRpcContract> = ZodOutput<Contract["input"]>;
 export type RpcOutput<Contract extends PluginRpcContract> = ZodInput<Contract["output"]>;
 
@@ -31,9 +37,99 @@ export function defineRpc<InputSchema extends ZodType, OutputSchema extends ZodT
 export async function callPluginRpc<InputSchema extends ZodType, OutputSchema extends ZodType>(
   contract: PluginRpcContract<InputSchema, OutputSchema>,
   invoke: (method: string, input: unknown) => Promise<unknown>,
-  input: ZodInput<InputSchema>,
+  input: PluginWireInput<ZodInput<InputSchema>>,
 ): Promise<ZodOutput<OutputSchema>> {
   const parsedInput = await contract.input.parseAsync(input);
   const output = await invoke(contract.name, parsedInput);
   return contract.output.parseAsync(output);
 }
+
+export interface PluginSubscriptionContract<
+  InputSchema extends ZodType = ZodType,
+  EventSchema extends ZodType = ZodType,
+> {
+  name: string;
+  input: InputSchema;
+  event: EventSchema;
+}
+
+export type SubscriptionInput<Contract extends PluginSubscriptionContract> = ZodOutput<
+  Contract["input"]
+>;
+export type SubscriptionEvent<Contract extends PluginSubscriptionContract> = ZodOutput<
+  Contract["event"]
+>;
+
+interface SubscriptionDefinition<InputSchema extends ZodType, EventSchema extends ZodType> {
+  name: string;
+  input: InputSchema;
+  event: EventSchema;
+}
+
+export function defineSubscription<InputSchema extends ZodType, EventSchema extends ZodType>(
+  definition: SubscriptionDefinition<InputSchema, EventSchema>,
+): PluginSubscriptionContract<InputSchema, EventSchema> {
+  const name = definition.name.trim();
+  if (!RPC_NAME.test(name)) throw new Error(`Invalid plugin subscription: ${definition.name}`);
+  return { ...definition, name };
+}
+
+/** One subscription from a client surface. Calling it or `release()` ends it. */
+export type PluginSubscriptionHandle = (() => void) & {
+  /** Resolves once the plugin acknowledged the subscription; rejects if it refused. */
+  readonly ready: Promise<void>;
+  release(): Promise<void>;
+};
+
+export interface PluginSubscriptionObserver {
+  event(event: unknown): void;
+  closed(error?: Error): void;
+}
+
+export interface PluginSubscriptionClosed {
+  /** Set when the plugin's handler failed, the plugin stopped, or an event failed validation. */
+  error?: Error;
+}
+
+export interface PluginSubscribeOptions {
+  /** Aborting releases the subscription. */
+  signal?: AbortSignal;
+  /** Runs once when the daemon closes the subscription. Not called after a release. */
+  onClosed?: (closed: PluginSubscriptionClosed) => void;
+}
+
+export function subscribePluginRpc<InputSchema extends ZodType, EventSchema extends ZodType>(
+  contract: PluginSubscriptionContract<InputSchema, EventSchema>,
+  subscribe: (
+    method: string,
+    input: unknown,
+    observer: PluginSubscriptionObserver,
+  ) => PluginSubscriptionHandle,
+  input: PluginWireInput<ZodInput<InputSchema>>,
+  onEvent: (event: ZodOutput<EventSchema>) => void,
+  options: PluginSubscribeOptions = {},
+): PluginSubscriptionHandle {
+  // The plugin parses the input into the schema's output, so it receives the input as given.
+  contract.input.parse(input);
+  let closed = false;
+  function close(error?: Error) {
+    if (closed) return;
+    closed = true;
+    options.onClosed?.(error ? { error } : {});
+  }
+  const handle = subscribe(contract.name, input, {
+    event(event) {
+      if (closed) return;
+      const parsed = contract.event.safeParse(event);
+      if (parsed.success) return onEvent(parsed.data);
+      handle();
+      close(new Error(`Plugin subscription ${contract.name} sent an invalid event`));
+    },
+    closed: close,
+  });
+  if (options.signal) {
+    if (options.signal.aborted) handle();
+    else options.signal.addEventListener("abort", () => handle(), { once: true });
+  }
+  return handle;
+}

packages/plugin/src/server/contracts.ts

@@ -1,6 +1,6 @@
 import type { PaseoApi } from "@getpaseo/client";
 import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
-import type { PluginRpcContract } from "../rpc.js";
+import type { PluginRpcContract, PluginSubscriptionContract, PluginWireInput } from "../rpc.js";
 import type { PluginCleanup } from "../contracts.js";
 import type { ProviderRegistration } from "./provider.js";
 import type { UsageSourceRegistration } from "./usage.js";
@@ -10,6 +10,18 @@ export interface PluginHandlerContext {
   paseo: PaseoApi;
 }
 
+/** What a subscription handler receives beside its input. */
+export interface PluginSubscriptionContext<Event = unknown> extends PluginHandlerContext {
+  /**
+   * Sends one event to this subscriber. A `Uint8Array` event travels as a binary frame; any other
+   * event is JSON and must not contain a `Uint8Array`. Resolves once the event left the plugin
+   * process. Events pushed after `signal` aborts are dropped.
+   */
+  push(event: Event): Promise<void>;
+  /** Aborts when the subscriber releases, disconnects, or the plugin stops. */
+  signal: AbortSignal;
+}
+
 export type PluginSettingsState<Schema extends ZodType> =
   | {
       status: "ready";
@@ -31,12 +43,24 @@ export interface PluginServerContext extends PluginLifecycleRegistration {
   registerSettings<Schema extends ZodType>(
     definition: import("../settings.js").SettingsDefinition<Schema>,
   ): PluginSettings<Schema>;
+  /**
+   * Serves a subscription. The handler starts the work and returns; the subscription stays open
+   * until `signal` aborts. A handler that throws refuses the subscription. When it returns a
+   * promise, settling the promise closes the subscription, with the rejection as its error.
+   */
+  handle<InputSchema extends ZodType, EventSchema extends ZodType>(
+    contract: PluginSubscriptionContract<InputSchema, EventSchema>,
+    handler: (
+      input: ZodOutput<InputSchema>,
+      context: PluginSubscriptionContext<PluginWireInput<ZodInput<EventSchema>>>,
+    ) => void | Promise<void>,
+  ): void;
   handle<InputSchema extends ZodType, OutputSchema extends ZodType>(
     contract: PluginRpcContract<InputSchema, OutputSchema>,
     handler: (
       input: ZodOutput<InputSchema>,
       context: PluginHandlerContext,
-    ) => ZodInput<OutputSchema> | Promise<ZodInput<OutputSchema>>,
+    ) => PluginWireInput<ZodInput<OutputSchema>> | Promise<PluginWireInput<ZodInput<OutputSchema>>>,
   ): void;
   registerProvider(provider: ProviderRegistration): void;
   registerUsageSource(source: UsageSourceRegistration): void;

packages/plugin/src/server/index.ts

@@ -11,6 +11,7 @@ export type {
   PluginServerContribution,
   PluginSettings,
   PluginSettingsState,
+  PluginSubscriptionContext,
 } from "./contracts.js";
 export type {
   PluginHooks,

packages/protocol/src/binary-frames/demux.ts

@@ -4,6 +4,7 @@ import {
   FileTransferOpcode,
   type FileTransferFrame,
 } from "./file-transfer.js";
+import { decodePluginFrame, PluginFrameOpcode, type PluginFrame } from "./plugin.js";
 import {
   decodeTerminalStreamFrame,
   TerminalStreamOpcode,
@@ -13,7 +14,8 @@ import {
 export type BinaryFrame =
   | { kind: "host_route"; frame: HostRouteFrame }
   | { kind: "terminal"; frame: TerminalStreamFrame }
-  | { kind: "file_transfer"; frame: FileTransferFrame };
+  | { kind: "file_transfer"; frame: FileTransferFrame }
+  | { kind: "plugin"; frame: PluginFrame };
 
 export function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
   switch (bytes[0]) {
@@ -38,6 +40,12 @@ export function decodeBinaryFrame(bytes: Uint8Array): BinaryFrame | null {
       const frame = decodeFileTransferFrame(bytes);
       return frame ? { kind: "file_transfer", frame } : null;
     }
+    case PluginFrameOpcode.Event:
+    case PluginFrameOpcode.Output:
+    case PluginFrameOpcode.Input: {
+      const frame = decodePluginFrame(bytes);
+      return frame ? { kind: "plugin", frame } : null;
+    }
     default:
       return null;
   }

packages/protocol/src/binary-frames/index.ts

@@ -2,3 +2,4 @@ export * from "./demux.js";
 export * from "./file-transfer.js";
 export * from "./terminal.js";
 export * from "./host-route.js";
+export * from "./plugin.js";

packages/protocol/src/binary-frames/plugin.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  assertPluginWireValue,
+  decodeBinaryFrame,
+  decodePluginFrame,
+  encodePluginEventFrame,
+  encodePluginInputFrame,
+  encodePluginOutputFrame,
+  FileTransferOpcode,
+  MAX_PLUGIN_PAYLOAD_BYTES,
+  MAX_ROUTED_PAYLOAD_BYTES,
+  PluginFrameOpcode,
+  TerminalStreamOpcode,
+} from "./index.js";
+
+describe("plugin binary frames", () => {
+  it("uses the reserved plugin opcode range", () => {
+    for (const opcode of Object.values(PluginFrameOpcode)) {
+      expect(opcode).toBeGreaterThanOrEqual(0x20);
+      expect(opcode).toBeLessThanOrEqual(0x2f);
+      expect(Object.values(TerminalStreamOpcode)).not.toContain(opcode);
+      expect(Object.values(FileTransferOpcode)).not.toContain(opcode);
+    }
+  });
+
+  it("frames a subscription event as opcode, id length, id, and the untouched payload", () => {
+    const payload = new Uint8Array([9, 8, 7]);
+    const frame = encodePluginEventFrame("sub-1", payload);
+    expect([...frame]).toEqual([0x20, 5, ...new TextEncoder().encode("sub-1"), 9, 8, 7]);
+    expect(decodeBinaryFrame(frame)).toEqual({
+      kind: "plugin",
+      frame: { opcode: PluginFrameOpcode.Event, subscriptionId: "sub-1", payload },
+    });
+  });
+
+  it("decodes payloads as views into the received buffer", () => {
+    const frame = encodePluginOutputFrame("req-1", new Uint8Array([1, 2, 3, 4]));
+    const decoded = decodePluginFrame(frame);
+    if (decoded?.opcode !== PluginFrameOpcode.Output) throw new Error("Expected an output frame");
+    expect(decoded.requestId).toBe("req-1");
+    expect(decoded.payload.buffer).toBe(frame.buffer);
+    expect([...decoded.payload]).toEqual([1, 2, 3, 4]);
+  });
+
+  it("frames an RPC input with the plugin and method in its header", () => {
+    const frame = encodePluginInputFrame({
+      requestId: "req-2",
+      pluginId: "uploads",
+      method: "upload.store",
+      payload: new Uint8Array([5, 6]),
+    });
+    expect(decodePluginFrame(frame)).toEqual({
+      opcode: PluginFrameOpcode.Input,
+      requestId: "req-2",
+      pluginId: "uploads",
+      method: "upload.store",
+      payload: new Uint8Array([5, 6]),
+    });
+  });
+
+  it("rejects truncated frames", () => {
+    expect(decodePluginFrame(new Uint8Array([0x20]))).toBeNull();
+    expect(decodePluginFrame(new Uint8Array([0x20, 9, 1]))).toBeNull();
+    expect(decodePluginFrame(new Uint8Array([0x22, 1, 65, 0, 40]))).toBeNull();
+  });
+});
+
+describe("the plugin byte rule", () => {
+  it("accepts JSON values and a top-level Uint8Array", () => {
+    expect(() => assertPluginWireValue({ a: [1, "b", null] }, "event")).not.toThrow();
+    expect(() => assertPluginWireValue(new Uint8Array(4), "event")).not.toThrow();
+  });
+
+  it("rejects bytes that would not fit in one frame with the largest header", () => {
+    const bytes = new Uint8Array(MAX_PLUGIN_PAYLOAD_BYTES + 1);
+    expect(() => assertPluginWireValue(bytes.subarray(1), "event")).not.toThrow();
+    expect(() => assertPluginWireValue(bytes, "event")).toThrow(
+      `event is ${MAX_PLUGIN_PAYLOAD_BYTES + 1} bytes; one value carries at most ${MAX_PLUGIN_PAYLOAD_BYTES} bytes`,
+    );
+    const frame = encodePluginInputFrame({
+      requestId: "r".repeat(255),
+      pluginId: "p",
+      method: "m".repeat(0xffff - 30),
+      payload: bytes.subarray(1),
+    });
+    expect(frame.byteLength).toBeLessThanOrEqual(MAX_ROUTED_PAYLOAD_BYTES);
+  });
+
+  it("rejects bytes nested in a value and names the rule and the path", () => {
+    expect(() => assertPluginWireValue({ frames: [{ data: new Uint8Array(1) }] }, "event")).toThrow(
+      "event.frames[0].data is a Uint8Array. Bytes cross the wire only as the whole value: send the Uint8Array itself, or encode it into the value.",
+    );
+  });
+});

packages/protocol/src/binary-frames/plugin.ts

@@ -0,0 +1,152 @@
+import { MAX_ROUTED_PAYLOAD_BYTES } from "./host-route.js";
+
+/**
+ * Plugin values that are a `Uint8Array` travel as binary frames. Opcodes 0x20-0x2f are
+ * reserved for plugin traffic. Every frame is `[opcode][id length u8][id]...` and the payload
+ * is the rest of the frame, decoded as a view so no hop copies it.
+ */
+export const PluginFrameOpcode = {
+  /** `[0x20][id length][subscriptionId][payload]`: a subscription event. */
+  Event: 0x20,
+  /** `[0x21][id length][requestId][payload]`: an RPC output; no JSON response follows. */
+  Output: 0x21,
+  /** `[0x22][id length][requestId][header length u16][header JSON][payload]`: an RPC input. */
+  Input: 0x22,
+} as const;
+
+export type PluginFrameOpcode = (typeof PluginFrameOpcode)[keyof typeof PluginFrameOpcode];
+
+/** The largest frame header: an input's opcode, ID and header JSON, each at its maximum length. */
+const MAX_PLUGIN_FRAME_HEADER_BYTES = 2 + 0xff + 2 + 0xffff;
+
+/** The largest `Uint8Array` a plugin value carries, so its frame fits in one routed message. */
+export const MAX_PLUGIN_PAYLOAD_BYTES = MAX_ROUTED_PAYLOAD_BYTES - MAX_PLUGIN_FRAME_HEADER_BYTES;
+
+export type PluginFrame =
+  | { opcode: typeof PluginFrameOpcode.Event; subscriptionId: string; payload: Uint8Array }
+  | { opcode: typeof PluginFrameOpcode.Output; requestId: string; payload: Uint8Array }
+  | {
+      opcode: typeof PluginFrameOpcode.Input;
+      requestId: string;
+      pluginId: string;
+      method: string;
+      payload: Uint8Array;
+    };
+
+export function isPluginFrameOpcode(value: number | undefined): value is PluginFrameOpcode {
+  return (
+    value === PluginFrameOpcode.Event ||
+    value === PluginFrameOpcode.Output ||
+    value === PluginFrameOpcode.Input
+  );
+}
+
+export function encodePluginEventFrame(subscriptionId: string, payload: Uint8Array): Uint8Array {
+  return encodeFrame(PluginFrameOpcode.Event, subscriptionId, new Uint8Array(0), payload);
+}
+
+export function encodePluginOutputFrame(requestId: string, payload: Uint8Array): Uint8Array {
+  return encodeFrame(PluginFrameOpcode.Output, requestId, new Uint8Array(0), payload);
+}
+
+export function encodePluginInputFrame(input: {
+  requestId: string;
+  pluginId: string;
+  method: string;
+  payload: Uint8Array;
+}): Uint8Array {
+  const header = new TextEncoder().encode(
+    JSON.stringify({ pluginId: input.pluginId, method: input.method }),
+  );
+  if (header.byteLength > 0xffff) throw new RangeError("Plugin input header is too long");
+  const prefix = new Uint8Array(2 + header.byteLength);
+  new DataView(prefix.buffer).setUint16(0, header.byteLength);
+  prefix.set(header, 2);
+  return encodeFrame(PluginFrameOpcode.Input, input.requestId, prefix, input.payload);
+}
+
+export function decodePluginFrame(bytes: Uint8Array): PluginFrame | null {
+  const opcode = bytes[0];
+  if (bytes.byteLength < 2 || !isPluginFrameOpcode(opcode)) return null;
+  const idLength = bytes[1];
+  if (idLength === 0 || idLength > bytes.byteLength - 2) return null;
+  const id = new TextDecoder().decode(bytes.subarray(2, 2 + idLength));
+  const body = bytes.subarray(2 + idLength);
+  if (opcode === PluginFrameOpcode.Event) return { opcode, subscriptionId: id, payload: body };
+  if (opcode === PluginFrameOpcode.Output) return { opcode, requestId: id, payload: body };
+  if (body.byteLength < 2) return null;
+  const headerLength = new DataView(body.buffer, body.byteOffset, body.byteLength).getUint16(0);
+  if (headerLength > body.byteLength - 2) return null;
+  const header = decodeInputHeader(body.subarray(2, 2 + headerLength));
+  if (!header) return null;
+  return { opcode, requestId: id, ...header, payload: body.subarray(2 + headerLength) };
+}
+
+function encodeFrame(
+  opcode: PluginFrameOpcode,
+  id: string,
+  prefix: Uint8Array,
+  payload: Uint8Array,
+): Uint8Array {
+  const idBytes = new TextEncoder().encode(id);
+  if (idBytes.byteLength === 0) throw new RangeError("Plugin frame ID is required");
+  if (idBytes.byteLength > 0xff) throw new RangeError("Plugin frame ID is too long");
+  const headerLength = 2 + idBytes.byteLength + prefix.byteLength;
+  const frame = new Uint8Array(headerLength + payload.byteLength);
+  frame[0] = opcode;
+  frame[1] = idBytes.byteLength;
+  frame.set(idBytes, 2);
+  frame.set(prefix, 2 + idBytes.byteLength);
+  frame.set(payload, headerLength);
+  return frame;
+}
+
+function decodeInputHeader(bytes: Uint8Array): { pluginId: string; method: string } | null {
+  try {
+    const header: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    if (typeof header !== "object" || header === null) return null;
+    const pluginId = Reflect.get(header, "pluginId");
+    const method = Reflect.get(header, "method");
+    if (typeof pluginId !== "string" || typeof method !== "string" || !pluginId || !method)
+      return null;
+    return { pluginId, method };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The byte rule: a plugin value is either a `Uint8Array`, sent as a binary frame, or a JSON value
+ * with no `Uint8Array` inside it. Checks object structure only; never reads the bytes.
+ */
+export function assertPluginWireValue(value: unknown, label: string): void {
+  if (value instanceof Uint8Array) {
+    if (value.byteLength > MAX_PLUGIN_PAYLOAD_BYTES)
+      throw new RangeError(
+        `${label} is ${value.byteLength} bytes; one value carries at most ${MAX_PLUGIN_PAYLOAD_BYTES} bytes`,
+      );
+    return;
+  }
+  const nested = findNestedBytes(value, label);
+  if (nested)
+    throw new TypeError(
+      `${nested} is a Uint8Array. Bytes cross the wire only as the whole value: send the Uint8Array itself, or encode it into the value.`,
+    );
+}
+
+function findNestedBytes(value: unknown, path: string): string | null {
+  if (value instanceof Uint8Array) return path;
+  if (typeof value !== "object" || value === null) return null;
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index += 1) {
+      const found = findNestedBytes(value[index], `${path}[${index}]`);
+      if (found) return found;
+    }
+    return null;
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    const found = findNestedBytes(entry, `${path}.${key}`);
+    if (found) return found;
+  }
+  return null;
+}

packages/protocol/src/client-capabilities.ts

@@ -46,6 +46,9 @@ export const CLIENT_CAPS = {
   // COMPAT(pluginTimelineItems): added in v0.8.0, remove after 2027-03-07 once client floor >= v0.8.0.
   pluginTimelineItems: "plugin_timeline_items",
   workspaceSetupObservation: "workspace_setup_observation",
+  // COMPAT(pluginBinaryPayloads): added in v0.15.0, remove after 2027-05-02 once client floor >= v0.15.0.
+  // The daemon sends plugin RPC outputs as binary opcode 0x21 only to clients that decode it.
+  pluginBinaryPayloads: "plugin_binary_payloads",
   // COMPAT(workspaceSetupBlocked): added in v0.8.0, remove after 2027-03-07 once client floor >= v0.8.0.
   workspaceSetupBlocked: "workspace_setup_blocked",
   browserHost: "browser_host",

packages/protocol/src/messages.plugins.test.ts

@@ -372,3 +372,43 @@ it("npm metadata leaves legacy plugin rows parseable without extending their clo
     payload: { requestId: "npm", plugins: [plugin] },
   });
 });
+
+describe("plugin subscription protocol", () => {
+  it("parses a subscribe request and its response", () => {
+    const request = {
+      type: "plugin.rpc.subscribe.request",
+      requestId: "r1",
+      pluginId: "diff-watch",
+      method: "diff.watch",
+      input: { a: "main", b: "HEAD" },
+    };
+    expect(SessionInboundMessageSchema.parse(request)).toEqual(request);
+    const response = {
+      type: "plugin.rpc.subscribe.response",
+      payload: { requestId: "r1", subscriptionId: "s1" },
+    };
+    expect(SessionOutboundMessageSchema.parse(response)).toEqual(response);
+  });
+
+  it("parses JSON events and closes with and without an error", () => {
+    for (const message of [
+      { type: "plugin.rpc.event", payload: { subscriptionId: "s1", event: { path: "a.ts" } } },
+      { type: "plugin.rpc.closed", payload: { subscriptionId: "s1" } },
+      { type: "plugin.rpc.closed", payload: { subscriptionId: "s1", error: "boom" } },
+    ]) {
+      expect(SessionOutboundMessageSchema.parse(message)).toEqual(message);
+    }
+  });
+
+  it("advertises the feature as an optional flag", () => {
+    const status = {
+      type: "status",
+      payload: {
+        status: "server_info",
+        serverId: "srv",
+        features: { pluginSubscriptions: true },
+      },
+    };
+    expect(StatusMessageSchema.parse(status)).toMatchObject(status);
+  });
+});

packages/protocol/src/messages.ts

@@ -1606,6 +1606,14 @@ export const PluginRpcInvokeRequestSchema = z.object({
   input: z.unknown(),
 });
 
+export const PluginRpcSubscribeRequestSchema = z.object({
+  type: z.literal("plugin.rpc.subscribe.request"),
+  requestId: z.string(),
+  pluginId: PluginIdSchema,
+  method: z.string().min(1),
+  input: z.unknown(),
+});
+
 export const AgentTimelineAppendRequestSchema = z.object({
   type: z.literal("agent.timeline.append.request"),
   requestId: z.string(),
@@ -3339,6 +3347,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
   PluginDisableRequestSchema,
   PluginRemoveRequestSchema,
   PluginRpcInvokeRequestSchema,
+  PluginRpcSubscribeRequestSchema,
   AgentTimelineAppendRequestSchema,
   AgentSkillsGetStatusRequestSchema,
   AgentSkillsReconcileRequestSchema,
@@ -3739,6 +3748,8 @@ export const ServerInfoStatusPayloadSchema = z
         pluginThemes: z.boolean().optional(),
         pluginSettings: z.boolean().optional(),
         pluginTimelineItems: z.boolean().optional(),
+        // COMPAT(pluginSubscriptions): added in v0.15.0, remove gate after 2027-05-02.
+        pluginSubscriptions: z.boolean().optional(),
         // COMPAT(skillManagement): added in v0.4.0, remove gate after 2027-08-16.
         skillManagement: z.boolean().optional(),
         // COMPAT(idleRuntimeCleanupSetting): added in v0.13.0, remove gate after 2027-04-26.
@@ -6962,6 +6973,22 @@ export const PluginRpcInvokeResponseSchema = z.object({
   }),
 });
 
+export const PluginRpcSubscribeResponseSchema = z.object({
+  type: z.literal("plugin.rpc.subscribe.response"),
+  payload: z.object({ requestId: z.string(), subscriptionId: z.string() }),
+});
+
+/** A JSON subscription event. A `Uint8Array` event rides as binary opcode 0x20 instead. */
+export const PluginRpcEventSchema = z.object({
+  type: z.literal("plugin.rpc.event"),
+  payload: z.object({ subscriptionId: z.string(), event: z.unknown() }),
+});
+
+export const PluginRpcClosedSchema = z.object({
+  type: z.literal("plugin.rpc.closed"),
+  payload: z.object({ subscriptionId: z.string(), error: z.string().optional() }),
+});
+
 export const AgentTimelineAppendResponseSchema = z.object({
   type: z.literal("agent.timeline.append.response"),
   payload: z.object({
@@ -7035,6 +7062,9 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
   PluginDisableResponseSchema,
   PluginRemoveResponseSchema,
   PluginRpcInvokeResponseSchema,
+  PluginRpcSubscribeResponseSchema,
+  PluginRpcEventSchema,
+  PluginRpcClosedSchema,
   AgentTimelineAppendResponseSchema,
   AgentSkillsGetStatusResponseSchema,
   AgentSkillsReconcileResponseSchema,

packages/relay/src/e2e.test.ts

@@ -56,6 +56,9 @@ function spawnRelayDevServer(port: number): ChildProcess {
       wranglerCliPath,
       "dev",
       "--local",
+      // Local execution still inherits production vars; exercise the local Durable Object.
+      "--var",
+      "PASEO_RELAY_UPSTREAM:",
       "--ip",
       "127.0.0.1",
       "--port",

packages/server/package.json

@@ -89,7 +89,7 @@
     "speech:transcribe:local": "tsx scripts/transcribe-local-wav.ts",
     "test": "npm run test:unit && npm run test:integration",
     "test:unit": "vitest run --fileParallelism --exclude \"**/*.e2e.test.ts\"",
-    "test:integration": "vitest run --maxWorkers=1 src/server/git-filename-diffs.e2e.test.ts src/server/daemon-e2e/checkout-diff-content.e2e.test.ts src/server/daemon-e2e/filesystem.e2e.test.ts src/server/daemon-e2e/file-download.e2e.test.ts src/server/daemon-e2e/cli-logs-follow.e2e.test.ts src/server/creation/creation.e2e.test.ts src/server/daemon-e2e/creation-status.e2e.test.ts src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts src/server/workspace-create-worktree-source.e2e.test.ts src/server/daemon-e2e/models.e2e.test.ts src/server/daemon-e2e/live-preferences.e2e.test.ts src/server/daemon-e2e/oversized-message.e2e.test.ts src/server/agent/model-catalog.e2e.test.ts src/server/plugins/plugin-paseo-api.e2e.test.ts src/server/plugins/usage-sources.e2e.test.ts src/server/plugins/lifecycle.e2e.test.ts src/server/connected-hosts/hosts.e2e.test.ts src/server/owned-subscriptions.e2e.test.ts && vitest run --maxWorkers=1 src/server/agent/providers/omp/history.e2e.test.ts src/server/daemon-e2e/git-operations.e2e.test.ts src/server/session.create-agent-worktree-autoarchive.e2e.test.ts src/server/agent/providers/opencode-bridge.local.e2e.test.ts src/server/daemon-e2e/relay-transport.e2e.test.ts -t \"merges into|creates a worktree and auto-archives both|versioned runtime|oversized attachments|connected hosts|password-protected daemon refuses|replays selected OMP history\"",
+    "test:integration": "vitest run --maxWorkers=1 src/server/git-filename-diffs.e2e.test.ts src/server/daemon-e2e/checkout-diff-content.e2e.test.ts src/server/daemon-e2e/create-agent-mode.e2e.test.ts src/server/daemon-e2e/filesystem.e2e.test.ts src/server/daemon-e2e/file-download.e2e.test.ts src/server/daemon-e2e/cli-logs-follow.e2e.test.ts src/server/creation/creation.e2e.test.ts src/server/daemon-e2e/creation-status.e2e.test.ts src/server/daemon-e2e/terminal-workspace-sdk.e2e.test.ts src/server/daemon-e2e/terminal-worker-lifecycle.e2e.test.ts src/server/workspace-create-worktree-source.e2e.test.ts src/server/daemon-e2e/models.e2e.test.ts src/server/daemon-e2e/live-preferences.e2e.test.ts src/server/daemon-e2e/oversized-message.e2e.test.ts src/server/agent/model-catalog.e2e.test.ts src/server/plugins/plugin-paseo-api.e2e.test.ts src/server/plugins/usage-sources.e2e.test.ts src/server/plugins/lifecycle.e2e.test.ts src/server/connected-hosts/hosts.e2e.test.ts src/server/owned-subscriptions.e2e.test.ts && vitest run --maxWorkers=1 src/server/agent/providers/omp/history.e2e.test.ts src/server/daemon-e2e/git-operations.e2e.test.ts src/server/session.create-agent-worktree-autoarchive.e2e.test.ts src/server/agent/providers/opencode-bridge.local.e2e.test.ts src/server/daemon-e2e/relay-transport.e2e.test.ts -t \"merges into|creates a worktree and auto-archives both|versioned runtime|oversized attachments|connected hosts|password-protected daemon refuses|replays selected OMP history\"",
     "test:hub-cli-contract": "vitest run --maxWorkers=1 src/server/hub/hub-cli-contract.test.ts",
     "test:integration:all": "npm run test:e2e",
     "test:integration:real": "vitest run real.e2e.test.ts",

packages/server/src/server/agent/create-agent-mode.test.ts

@@ -78,7 +78,7 @@ describe("resolveAndValidateCreateAgentMode", () => {
         availableModes: OPENCODE_MODES,
       }),
     ).toThrow(
-      "cannot inherit mode 'bypassPermissions' from caller (provider 'claude') for new agent (provider 'opencode'). Pass an explicit mode. Available modes for 'opencode': build, plan",
+      "cannot inherit mode 'bypassPermissions' from caller (provider 'claude') for new agent (provider 'opencode'). Pass an explicit mode in settings.modeId. Available modes for 'opencode': build, plan",
     );
   });
 
@@ -92,7 +92,7 @@ describe("resolveAndValidateCreateAgentMode", () => {
         availableModes: CODEX_MODES,
       }),
     ).toThrow(
-      "cannot inherit mode '<none>' from caller (provider 'opencode') for new agent (provider 'codex'). Pass an explicit mode. Available modes for 'codex': auto, full-access",
+      "cannot inherit mode '<none>' from caller (provider 'opencode') for new agent (provider 'codex'). Pass an explicit mode in settings.modeId. Available modes for 'codex': auto, full-access",
     );
   });
 
@@ -180,7 +180,7 @@ describe("resolveAndValidateCreateAgentMode", () => {
         targetUnattendedMode: "full-access",
       }),
     ).toThrow(
-      "cannot inherit mode 'default' from caller (provider 'claude') for new agent (provider 'codex'). Pass an explicit mode. Available modes for 'codex': auto, full-access",
+      "cannot inherit mode 'default' from caller (provider 'claude') for new agent (provider 'codex'). Pass an explicit mode in settings.modeId. Available modes for 'codex': auto, full-access",
     );
   });
 
@@ -195,7 +195,7 @@ describe("resolveAndValidateCreateAgentMode", () => {
         targetUnattendedMode: undefined,
       }),
     ).toThrow(
-      "cannot inherit mode 'bypassPermissions' from caller (provider 'claude') for new agent (provider 'zai-custom'). Pass an explicit mode. Available modes for 'zai-custom': unknown",
+      "cannot inherit mode 'bypassPermissions' from caller (provider 'claude') for new agent (provider 'zai-custom'). Pass an explicit mode in settings.modeId. Available modes for 'zai-custom': unknown",
     );
   });
 

packages/server/src/server/agent/create-agent-mode.ts

@@ -77,7 +77,7 @@ export function resolveAndValidateCreateAgentMode(
   }
 
   throw new Error(
-    `cannot inherit mode '${formatCreateConfigParentMode(parent)}' from ${formatCreateConfigParentSource(parent)} for new agent (provider '${targetProvider}'). Pass an explicit mode. Available modes for '${targetProvider}': ${listModes(availableModes)}`,
+    `cannot inherit mode '${formatCreateConfigParentMode(parent)}' from ${formatCreateConfigParentSource(parent)} for new agent (provider '${targetProvider}'). Pass an explicit mode in settings.modeId. Available modes for '${targetProvider}': ${listModes(availableModes)}`,
   );
 }
 

packages/server/src/server/agent/providers/claude/agent.error-result.test.ts

@@ -0,0 +1,190 @@
+import { expect, test } from "vitest";
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import { collectSessionTurnEvents } from "../test-utils/session-stream-adapter.js";
+import { ClaudeAgentClient } from "./agent.js";
+import type { ClaudeQueryFactory } from "./query.js";
+
+const LIMIT = "You've hit your session limit · resets 5:20pm (Asia/Singapore)";
+
+interface ScriptedTurn {
+  // An API error reply as Claude Code writes it: a synthetic assistant message with `error`.
+  errorReply?: string;
+  // Assistant text the model wrote before or after it.
+  before?: string;
+  after?: string;
+  isError: boolean;
+  usage?: {
+    inputTokens: number;
+    cachedInputTokens: number;
+    outputTokens: number;
+    totalCostUsd: number;
+  };
+}
+
+// A query dependency that speaks Claude Code's stream interface, one scripted turn per prompt.
+function scriptedQuery(turns: ScriptedTurn[]): ClaudeQueryFactory {
+  return ({ prompt }) => {
+    let index = 0;
+    const assistant = (id: string, text: string, error?: string) => ({
+      type: "assistant",
+      session_id: "error-session",
+      parent_tool_use_id: null,
+      uuid: id,
+      message: {
+        id,
+        role: "assistant",
+        model: error ? "<synthetic>" : "claude-opus-5-5",
+        content: [{ type: "text", text }],
+        stop_reason: "stop_sequence",
+        usage: { input_tokens: 0, output_tokens: 0 },
+      },
+      ...(error ? { error } : {}),
+    });
+    const messages = (async function* () {
+      if (typeof prompt === "string") throw new Error("Expected streaming input");
+      for await (const _message of prompt) {
+        const turn = turns[index];
+        index += 1;
+        yield {
+          type: "system",
+          subtype: "init",
+          session_id: "error-session",
+          permissionMode: "default",
+          model: "claude-opus-5-5",
+        };
+        if (turn.before) yield assistant(`before-${index}`, turn.before);
+        if (turn.errorReply) yield assistant(`error-${index}`, turn.errorReply, "rate_limit");
+        if (turn.after) yield assistant(`after-${index}`, turn.after);
+        yield {
+          type: "result",
+          subtype: "success",
+          session_id: "error-session",
+          duration_ms: 1,
+          duration_api_ms: 0,
+          is_error: turn.isError,
+          num_turns: 1,
+          result: turn.isError ? (turn.errorReply ?? "") : (turn.after ?? turn.errorReply ?? ""),
+          stop_reason: "stop_sequence",
+          total_cost_usd: turn.usage?.totalCostUsd ?? 0,
+          usage: {
+            input_tokens: turn.usage?.inputTokens ?? 0,
+            output_tokens: turn.usage?.outputTokens ?? 0,
+            cache_read_input_tokens: turn.usage?.cachedInputTokens ?? 0,
+          },
+          modelUsage: {},
+          permission_denials: [],
+          uuid: `result-${index}`,
+        };
+      }
+    })();
+    return Object.assign(messages, {
+      close: () => {
+        void messages.return();
+      },
+      interrupt: async () => undefined,
+      setModel: async () => undefined,
+      setPermissionMode: async () => undefined,
+      supportedModels: async () => [],
+      supportedCommands: async () => [],
+    }) as ReturnType<ClaudeQueryFactory>;
+  };
+}
+
+async function runTurns(turns: ScriptedTurn[]) {
+  const client = new ClaudeAgentClient({
+    logger: createTestLogger(),
+    queryFactory: scriptedQuery(turns),
+    resolveBinary: async () => process.execPath,
+  });
+  const session = await client.createSession({
+    provider: "claude",
+    cwd: process.cwd(),
+  });
+  try {
+    const results = [];
+    for (const [index] of turns.entries()) {
+      results.push(await collectSessionTurnEvents(session, `turn ${index + 1}`));
+    }
+    return results;
+  } finally {
+    await session.close();
+  }
+}
+
+function assistantTexts(events: Awaited<ReturnType<typeof runTurns>>[number]): string[] {
+  return events.flatMap((event) =>
+    event.type === "timeline" && event.item.type === "assistant_message" ? [event.item.text] : [],
+  );
+}
+
+function terminal(events: Awaited<ReturnType<typeof runTurns>>[number]) {
+  return events.find(
+    (event) =>
+      event.type === "turn_completed" ||
+      event.type === "turn_failed" ||
+      event.type === "turn_canceled",
+  );
+}
+
+test("a turn Claude Code ends on an API error fails with the error, shown once", async () => {
+  const [limited, overloaded, next] = await runTurns([
+    { errorReply: LIMIT, isError: true },
+    {
+      before: "Checking the deploy doc.",
+      errorReply: "API Error: 529 Overloaded",
+      isError: true,
+    },
+    { after: "Done.", isError: false },
+  ]);
+
+  expect(terminal(limited)).toMatchObject({
+    type: "turn_failed",
+    error: LIMIT,
+  });
+  expect(assistantTexts(limited)).toEqual([]);
+
+  expect(terminal(overloaded)).toMatchObject({
+    type: "turn_failed",
+    error: "API Error: 529 Overloaded",
+  });
+  expect(assistantTexts(overloaded)).toEqual(["Checking the deploy doc."]);
+
+  // The session keeps working after a failed turn.
+  expect(terminal(next)).toMatchObject({ type: "turn_completed" });
+  expect(assistantTexts(next)).toEqual(["Done."]);
+});
+
+test("a failed turn retains its final token counts and cost", async () => {
+  const usage = {
+    inputTokens: 120,
+    cachedInputTokens: 80,
+    outputTokens: 30,
+    totalCostUsd: 0.012,
+  };
+  const [failed] = await runTurns([
+    { before: "Checking the deploy doc.", errorReply: LIMIT, isError: true, usage },
+  ]);
+
+  expect(failed).toContainEqual(
+    expect.objectContaining({ type: "usage_updated", usage: expect.objectContaining(usage) }),
+  );
+  expect(terminal(failed)).toMatchObject({ type: "turn_failed", error: LIMIT });
+  expect(assistantTexts(failed)).toEqual(["Checking the deploy doc."]);
+});
+
+test("an error reply the turn moves past is still shown", async () => {
+  const [recovered, completed] = await runTurns([
+    {
+      errorReply: "API Error: 529 Overloaded",
+      after: "Recovered.",
+      isError: false,
+    },
+    { errorReply: LIMIT, isError: false },
+  ]);
+
+  expect(terminal(recovered)).toMatchObject({ type: "turn_completed" });
+  expect(assistantTexts(recovered)).toEqual(["API Error: 529 Overloaded", "Recovered."]);
+
+  expect(terminal(completed)).toMatchObject({ type: "turn_completed" });
+  expect(assistantTexts(completed)).toEqual([LIMIT]);
+});

packages/server/src/server/agent/providers/claude/agent.import-titles.test.ts

@@ -1,3 +1,4 @@
+import { constants as bufferConstants } from "node:buffer";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -236,4 +237,64 @@ describe("importing a renamed Claude session", () => {
 
     await expect(importSession(sessionId)).rejects.toThrow();
   });
+
+  test("reads the rename from a transcript too large to hold as one string", async () => {
+    const sessionId = "oversized-transcript";
+    const projectDir = claudeProjectDirSync(SESSION_CWD, { configDir });
+    await fs.mkdir(projectDir, { recursive: true });
+    const transcript = path.join(projectDir, `${sessionId}.jsonl`);
+    // A hole stands in for the long session this used to fail on: the file only
+    // has to be longer than a string can be, and the rename sits at its end.
+    await fs.writeFile(transcript, "");
+    await fs.truncate(transcript, bufferConstants.MAX_STRING_LENGTH + 1);
+    await fs.appendFile(
+      transcript,
+      `\n${[
+        userRecord({ sessionId, content: "Trace the slow query" }),
+        { type: "custom-title", customTitle: "Slow query hunt", sessionId },
+      ]
+        .map((record) => JSON.stringify(record))
+        .join("\n")}\n`,
+    );
+
+    const imported = await importSession(sessionId);
+
+    expect(imported.config.title).toBe("Slow query hunt");
+  });
+
+  test("reads the rename from behind more records than one read covers", async () => {
+    const sessionId = "late-records-rename";
+    await writeSession({
+      sessionId,
+      records: [
+        userRecord({ sessionId, content: "Review this project" }),
+        { type: "custom-title", customTitle: "Scrollback review", sessionId },
+        // One record longer than a single read, then enough records to leave the
+        // rename several reads back from the end of the file.
+        userRecord({ sessionId, content: "x".repeat(128 * 1024) }),
+        ...Array.from({ length: 64 }, (_, index) =>
+          userRecord({ sessionId, content: `${"y".repeat(4 * 1024)} ${index}` }),
+        ),
+      ],
+    });
+
+    const imported = await importSession(sessionId);
+
+    expect(imported.config.title).toBe("Scrollback review");
+  });
+
+  test("imports a large record after the last rename without repeatedly copying it", async () => {
+    const sessionId = "large-record-after-rename";
+    await writeSession({
+      sessionId,
+      records: [
+        { type: "custom-title", customTitle: "Large attachment review", sessionId },
+        userRecord({ sessionId, content: "x".repeat(96 * 1024 * 1024) }),
+      ],
+    });
+
+    const imported = await importSession(sessionId);
+
+    expect(imported.config.title).toBe("Large attachment review");
+  });
 });

packages/server/src/server/agent/providers/claude/agent.runtime-info.test.ts

@@ -0,0 +1,48 @@
+import pino from "pino";
+import { describe, expect, test } from "vitest";
+
+import { ClaudeAgentClient } from "./agent.js";
+
+describe("Claude runtime info before a turn", () => {
+  const client = new ClaudeAgentClient({ logger: pino({ level: "silent" }) });
+
+  test("reports the explicitly configured model before the first turn", async () => {
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-haiku-5-5",
+    });
+    try {
+      expect(await session.getRuntimeInfo()).toMatchObject({ model: "claude-haiku-5-5" });
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("reports the persisted configured model after rebuilding an idle session", async () => {
+    const session = await client.resumeSession({
+      provider: "claude",
+      sessionId: "runtime-model-before-turn",
+      metadata: { cwd: process.cwd(), model: "claude-haiku-5-5" },
+    });
+    try {
+      expect(await session.getRuntimeInfo()).toMatchObject({
+        sessionId: "runtime-model-before-turn",
+        model: "claude-haiku-5-5",
+      });
+      expect((await session.getRuntimeInfo()).model).toBe("claude-haiku-5-5");
+      expect((await session.getRuntimeInfo()).extra?.runtimeModel).toBeUndefined();
+    } finally {
+      await session.close();
+    }
+  });
+
+  test("leaves the model unknown when Claude will choose its default", async () => {
+    const session = await client.createSession({ provider: "claude", cwd: process.cwd() });
+    try {
+      expect((await session.getRuntimeInfo()).model).toBeNull();
+    } finally {
+      await session.close();
+    }
+  });
+});

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

@@ -2389,6 +2389,12 @@ class ClaudeAgentSession implements AgentSession {
   private mainTurnInFlight = false;
   private foregroundHasVisibleActivity = false;
   private activeTurnHasAssistantText = false;
+  /**
+   * The reply Claude Code writes when a turn stops on an API error ("You've hit your session
+   * limit", "API Error: 529 ..."), held back until the result says whether the turn failed: a
+   * failed turn shows the same text as its error, so showing both would repeat it.
+   */
+  private withheldErrorReply: AgentTimelineItem[] = [];
   private readonly contextUsage: ClaudeContextUsageState;
   private userMessageIds: string[] = [];
   private readonly emittedUserMessageIds = new Set<string>();
@@ -2460,7 +2466,7 @@ class ClaudeAgentSession implements AgentSession {
     const info: AgentRuntimeInfo = {
       provider: "claude",
       sessionId: this.claudeSessionId,
-      model: this.lastOptionsModel,
+      model: this.lastOptionsModel ?? this.config.model ?? null,
       modeId: this.currentMode ?? null,
       ...(this.lastRuntimeModel
         ? {
@@ -2531,6 +2537,7 @@ class ClaudeAgentSession implements AgentSession {
     this.activeForegroundTurnId = turnId;
     this.foregroundHasVisibleActivity = false;
     this.activeTurnHasAssistantText = false;
+    this.withheldErrorReply = [];
     this.contextUsage.beginTurn();
     this.transitionTurnState("foreground", "foreground turn started");
     this.clearRecentStderr();
@@ -4419,6 +4426,21 @@ class ClaudeAgentSession implements AgentSession {
               }) satisfies AgentStreamEvent,
           );
 
+    if (!readClaudeParentToolUseId(message)) {
+      if (message.type === "assistant" && message.error) {
+        this.withheldErrorReply.push(...assistantTimelineEvents.map((event) => event.item));
+        return messageEvents;
+      }
+      if (
+        message.type === "assistant" ||
+        message.type === "user" ||
+        message.type === "stream_event"
+      ) {
+        const released: AgentStreamEvent[] = [];
+        this.releaseWithheldErrorReply(released);
+        return [...released, ...messageEvents, ...assistantTimelineEvents];
+      }
+    }
     return [...messageEvents, ...assistantTimelineEvents];
   }
 
@@ -4966,6 +4988,23 @@ class ClaudeAgentSession implements AgentSession {
     events: AgentStreamEvent[],
   ): void {
     const usage = this.convertUsage(message);
+    // Claude Code reports a turn that stopped on an API error (a usage limit, an overloaded or
+    // rejected request) as `success` with `is_error`, carrying the error text in `result`.
+    if (message.subtype === "success" && message.is_error) {
+      const withheld = this.withheldErrorReply;
+      this.withheldErrorReply = [];
+      const resultText = typeof message.result === "string" ? message.result.trim() : "";
+      const withheldText = withheld
+        .map((item) => (item.type === "assistant_message" ? item.text : ""))
+        .join("\n")
+        .trim();
+      if (usage) events.push({ type: "usage_updated", provider: "claude", usage });
+      events.push(...this.sidechainTracker.finishAll("failed"));
+      events.push(this.buildTurnFailedEvent(resultText || withheldText || "Claude run failed"));
+      return;
+    }
+    const releasedErrorReply = this.withheldErrorReply.length > 0;
+    this.releaseWithheldErrorReply(events);
     if (message.subtype === "success") {
       events.push(...this.sidechainTracker.finishAll("completed"));
       // Built-in slash commands (e.g. /voice, /usage, "Unknown command: …")
@@ -4975,7 +5014,12 @@ class ClaudeAgentSession implements AgentSession {
       // accounting from provider gateways does not duplicate streamed output.
       const resultText = typeof message.result === "string" ? message.result.trim() : "";
       const outputTokens = message.usage?.output_tokens;
-      if (resultText.length > 0 && outputTokens === 0 && !this.activeTurnHasAssistantText) {
+      if (
+        resultText.length > 0 &&
+        outputTokens === 0 &&
+        !this.activeTurnHasAssistantText &&
+        !releasedErrorReply
+      ) {
         events.push({
           type: "timeline",
           provider: "claude",
@@ -4997,6 +5041,14 @@ class ClaudeAgentSession implements AgentSession {
     events.push(this.buildTurnFailedEvent(errorMessage));
   }
 
+  private releaseWithheldErrorReply(events: AgentStreamEvent[]): void {
+    if (this.withheldErrorReply.length === 0) return;
+    for (const item of this.withheldErrorReply) {
+      events.push({ type: "timeline", item, provider: "claude" });
+    }
+    this.withheldErrorReply = [];
+  }
+
   private createClaudeSessionChangedNotice(
     oldSessionId: string,
     newSessionId: string,
@@ -6853,40 +6905,79 @@ function normalizeClaudeSessionTitle(title: string | null): string | null {
 }
 
 const CLAUDE_CUSTOM_TITLE_TYPE = "custom-title";
+const CLAUDE_CUSTOM_TITLE_NEEDLE = Buffer.from(`"${CLAUDE_CUSTOM_TITLE_TYPE}"`);
+const CLAUDE_TITLE_SCAN_CHUNK_BYTES = 64 * 1024;
+
+function readClaudeCustomTitleFromRecord(record: Buffer): string | null {
+  // The needle also matches a prompt that quotes it, so a record still has to
+  // parse as a `custom-title` entry carrying a usable name. Records without the
+  // needle are never decoded, so a long one costs a byte search and nothing more.
+  if (!record.includes(CLAUDE_CUSTOM_TITLE_NEEDLE)) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(record.toString("utf8").trim());
+  } catch {
+    return null;
+  }
+  const entry = toObjectRecord(parsed);
+  if (!entry || entry.isSidechain || entry.type !== CLAUDE_CUSTOM_TITLE_TYPE) {
+    return null;
+  }
+  return normalizeClaudeSessionTitle(
+    typeof entry.customTitle === "string" ? entry.customTitle : null,
+  );
+}
 
 /**
  * The `custom-title` record is re-emitted every time the session is saved, so
- * the current name is the last usable one in the file. Searching backwards finds it without
- * walking the transcript, which matters because sessions reach tens of
- * megabytes.
+ * the current name is the last usable one in the file. Reading backwards a chunk
+ * at a time finds it without walking the transcript, which matters because
+ * sessions reach tens of megabytes, and never holds the file as one string, so a
+ * transcript past V8's maximum string length still imports.
  */
-function readLastClaudeCustomTitle(content: string): string | null {
-  const needle = `"${CLAUDE_CUSTOM_TITLE_TYPE}"`;
-  let at = content.lastIndexOf(needle);
-  while (at >= 0) {
-    const lineStart = content.lastIndexOf("\n", at) + 1;
-    const lineEnd = content.indexOf("\n", at);
-    const line = lineEnd === -1 ? content.slice(lineStart) : content.slice(lineStart, lineEnd);
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(line.trim());
-    } catch {
-      parsed = undefined;
-    }
-    const entry = toObjectRecord(parsed);
-    if (entry && !entry.isSidechain && entry.type === CLAUDE_CUSTOM_TITLE_TYPE) {
-      const title = normalizeClaudeSessionTitle(
-        typeof entry.customTitle === "string" ? entry.customTitle : null,
+async function readLastClaudeCustomTitle(filePath: string): Promise<string | null> {
+  const handle = await fsPromises.open(filePath, "r");
+  try {
+    const stats = await handle.stat();
+    if (!stats.isFile()) {
+      // Opening a directory succeeds on Windows even though reading it does not,
+      // so reject the way reading the transcript as a file would.
+      throw Object.assign(
+        new Error(`EISDIR: illegal operation on a directory, read '${filePath}'`),
+        { code: "EISDIR", path: filePath },
       );
-      if (title) {
-        return title;
-      }
     }
-    // The needle also matches a prompt that quotes it, and a record can carry no
-    // usable name, so keep looking backwards for one that does.
-    at = at <= 0 ? -1 : content.lastIndexOf(needle, at - 1);
+    let end = stats.size;
+    // Retain unfinished record pieces in reverse file order. Assemble each
+    // complete record once, so a large tool/image record costs linear work.
+    let pieces: Buffer[] = [];
+    while (end > 0) {
+      const length = Math.min(CLAUDE_TITLE_SCAN_CHUNK_BYTES, end);
+      const chunk = Buffer.alloc(length);
+      await handle.read(chunk, 0, length, end - length);
+      let recordEnd = chunk.length;
+      for (
+        let at = chunk.lastIndexOf(10);
+        at >= 0;
+        at = at === 0 ? -1 : chunk.lastIndexOf(10, at - 1)
+      ) {
+        pieces.push(chunk.subarray(at + 1, recordEnd));
+        const record = Buffer.concat(pieces.toReversed());
+        const title = readClaudeCustomTitleFromRecord(record);
+        if (title) return title;
+        pieces = [];
+        recordEnd = at;
+      }
+      if (recordEnd > 0) pieces.push(chunk.subarray(0, recordEnd));
+      end -= length;
+    }
+    // The first record in the file has no newline in front of it.
+    return readClaudeCustomTitleFromRecord(Buffer.concat(pieces.toReversed()));
+  } finally {
+    await handle.close();
   }
-  return null;
 }
 
 function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
@@ -6898,9 +6989,8 @@ async function readClaudeRenamedSessionTitle(input: {
   sessionId: string;
   configDir: string;
 }): Promise<string | null> {
-  let content: string;
   try {
-    content = await fsPromises.readFile(await claudeTranscriptPath(input), "utf8");
+    return await readLastClaudeCustomTitle(await claudeTranscriptPath(input));
   } catch (error) {
     // A session with no transcript on disk has no rename to carry over. Every
     // other read failure is a real fault and stays explicit.
@@ -6909,7 +6999,6 @@ async function readClaudeRenamedSessionTitle(input: {
     }
     throw error;
   }
-  return readLastClaudeCustomTitle(content);
 }
 
 function normalizeImportablePromptPreview(text: string): string | null {

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

@@ -150,6 +150,15 @@ function isCodexAlreadyUnarchivedError(error: unknown, threadId: string): boolea
 
 const TURN_START_TIMEOUT_MS = 90 * 1000;
 const INTERRUPT_TIMEOUT_MS = 2_000;
+// `turn/interrupt` ends a turn but leaves the shell commands it started running.
+// Each terminate is bounded by the first constant. A turn start waits for the
+// interrupted turn's commands to end, at most the interrupt's own bound plus one
+// terminate's and a margin, so it gives up only when a request outlives its timeout.
+const INTERRUPTED_TURN_TERMINATE_TIMEOUT_MS = 2_000;
+const INTERRUPTED_TURN_CLEANUP_WAIT_MS =
+  INTERRUPT_TIMEOUT_MS + INTERRUPTED_TURN_TERMINATE_TIMEOUT_MS + 500;
+// Turns whose commands are remembered; older turns are forgotten first.
+const INTERRUPTED_TURN_TRACKED_TURNS = 16;
 const CODEX_PROVIDER = "codex" as const;
 // These native provider identities belong to Codex, not to an older custom
 // Paseo provider. Never include them in a custom provider's legacy import scan.
@@ -3476,6 +3485,14 @@ export class CodexAppServerAgentSession implements AgentSession {
   private pendingFileChangeOutputDeltas = new Map<string, string[]>();
   private pendingAssistantMessageBoundary = false;
   private terminalCommandByProcessId = new Map<string, string>();
+  // The root thread's still-running command process ids, keyed by the native turn that
+  // started them. Codex's `thread/backgroundTerminals/list` carries no turn, so
+  // `item/started` is the only record of which turn owns a process.
+  private terminalProcessIdsByTurnId = new Map<
+    string,
+    { processIds: Set<string>; terminatedProcessIds: Set<string>; interruptAccepted: boolean }
+  >();
+  private interruptedTurnCleanup: Promise<void> | null = null;
   private pendingUnlabeledTerminalInteractions = new Map<
     string,
     Array<{ callId: string; stdin: string | null }>
@@ -4431,6 +4448,9 @@ export class CodexAppServerAgentSession implements AgentSession {
         hasDeveloperInstructions: turnStart.hasDeveloperInstructions,
         hasCodexConfig: turnStart.hasCodexConfig,
       });
+      // The interrupted turn's commands end before this turn begins, so none of them
+      // outlives it into the new turn.
+      await this.waitForInterruptedTurnCleanup();
       if (pendingStart.cancelRequested) {
         throw new Error("Codex turn start was interrupted before reaching Codex");
       }
@@ -5036,15 +5056,27 @@ export class CodexAppServerAgentSession implements AgentSession {
     if (!turnId || (foregroundTurnId && this.activeForegroundTurnId !== foregroundTurnId)) {
       throw new Error("Cannot interrupt Codex before turn/started identifies the active turn");
     }
+    const client = this.client;
+    const threadId = this.currentThreadId;
+    const interruptRequest = client.request(
+      "turn/interrupt",
+      {
+        threadId,
+        turnId,
+      },
+      INTERRUPT_TIMEOUT_MS,
+    );
+    // Once Codex accepts the interrupt, end the commands this turn started. Registered
+    // before the await, so a turn start racing this interrupt waits for it. An already-idle
+    // turn was not interrupted, and what it left running stays.
+    this.trackInterruptedTurnCleanup(
+      interruptRequest.then(
+        () => this.endInterruptedTurnProcesses(client, threadId, turnId),
+        () => undefined,
+      ),
+    );
     try {
-      await this.client.request(
-        "turn/interrupt",
-        {
-          threadId: this.currentThreadId,
-          turnId,
-        },
-        INTERRUPT_TIMEOUT_MS,
-      );
+      await interruptRequest;
     } catch (error) {
       if (!isCodexAlreadyIdleInterrupt(error)) {
         throw error;
@@ -5085,6 +5117,137 @@ export class CodexAppServerAgentSession implements AgentSession {
     return !this.client.hasPendingRequests();
   }
 
+  // Remember which turn started a command, so an interrupt ends that turn's commands and
+  // no other turn's. Only the root thread's: a subagent's commands live on its own thread.
+  // A command that starts after its turn's interrupt was accepted is ended as soon as it
+  // is seen.
+  private recordTurnTerminalProcess(
+    parsed: Extract<ParsedCodexNotification, { kind: "item_started" | "item_completed" }>,
+  ): void {
+    const processId = parsed.item.processId;
+    if (
+      parsed.source !== "item" ||
+      !parsed.turnId ||
+      !parsed.threadId ||
+      parsed.threadId !== this.currentThreadId ||
+      typeof processId !== "string" ||
+      !processId ||
+      normalizeCodexThreadItemType(
+        typeof parsed.item.type === "string" ? parsed.item.type : undefined,
+      ) !== "commandExecution"
+    ) {
+      return;
+    }
+    const record = this.terminalProcessIdsByTurnId.get(parsed.turnId);
+    if (parsed.kind === "item_completed") {
+      // Only a completed command has exited. A failed one can still be running:
+      // Codex reports an interrupted turn's live command as failed.
+      if (parsed.item.status === "completed") record?.processIds.delete(processId);
+      return;
+    }
+    const current = record ?? this.getTurnTerminalRecord(parsed.turnId);
+    current.processIds.add(processId);
+    if (current.interruptAccepted && this.client) {
+      this.trackInterruptedTurnCleanup(
+        this.endInterruptedTurnProcesses(this.client, parsed.threadId, parsed.turnId),
+      );
+    }
+  }
+
+  // An accepted interrupt needs a record even before any of its turn's commands is seen:
+  // an `item/started` can still be queued behind an earlier notification's conversion.
+  private getTurnTerminalRecord(turnId: string) {
+    const existing = this.terminalProcessIdsByTurnId.get(turnId);
+    if (existing) return existing;
+    const record = {
+      processIds: new Set<string>(),
+      terminatedProcessIds: new Set<string>(),
+      interruptAccepted: false,
+    };
+    this.terminalProcessIdsByTurnId.set(turnId, record);
+    for (const oldestTurnId of this.terminalProcessIdsByTurnId.keys()) {
+      if (this.terminalProcessIdsByTurnId.size <= INTERRUPTED_TURN_TRACKED_TURNS) break;
+      this.terminalProcessIdsByTurnId.delete(oldestTurnId);
+    }
+    return record;
+  }
+
+  // A later sweep joins the pending one, so a turn start waits for both.
+  private trackInterruptedTurnCleanup(cleanup: Promise<void>): void {
+    const tracked = Promise.all([this.interruptedTurnCleanup, cleanup])
+      .then(() => undefined)
+      .finally(() => {
+        if (this.interruptedTurnCleanup === tracked) this.interruptedTurnCleanup = null;
+      });
+    this.interruptedTurnCleanup = tracked;
+  }
+
+  // Terminate each process the interrupted turn started, by its own id, once each.
+  // `thread/backgroundTerminals/clean` is never used: it ends every terminal on the thread,
+  // an earlier turn's included. A process already gone answers `terminated: false`. Never
+  // rejects; failures are logged.
+  private async endInterruptedTurnProcesses(
+    client: CodexAppServerClient,
+    threadId: string | null,
+    turnId: string,
+  ): Promise<void> {
+    if (!threadId) return;
+    const record = this.getTurnTerminalRecord(turnId);
+    record.interruptAccepted = true;
+    const processIds = [...record.processIds].filter(
+      (processId) => !record.terminatedProcessIds.has(processId),
+    );
+    for (const processId of processIds) record.terminatedProcessIds.add(processId);
+    const logContext = { agentId: this.agentId, provider: CODEX_PROVIDER, threadId, turnId };
+    await Promise.all(
+      processIds.map(async (processId) => {
+        try {
+          const response = await client.request(
+            "thread/backgroundTerminals/terminate",
+            { threadId, processId },
+            INTERRUPTED_TURN_TERMINATE_TIMEOUT_MS,
+          );
+          this.logger.info(
+            { ...logContext, processId, terminated: toObjectRecord(response)?.terminated ?? null },
+            "provider.codex.interrupt.terminal_terminated",
+          );
+        } catch (error) {
+          this.logger.warn(
+            { ...logContext, processId, err: error },
+            "provider.codex.interrupt.terminal_terminate_failed",
+          );
+        }
+      }),
+    );
+  }
+
+  // A new turn starts only after every pending sweep of interrupted turns' commands has
+  // ended, or after the bound, whichever is first.
+  private async waitForInterruptedTurnCleanup(): Promise<void> {
+    if (!this.interruptedTurnCleanup) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const timedOut = await Promise.race([
+      (async () => {
+        while (this.interruptedTurnCleanup) await this.interruptedTurnCleanup;
+        return false;
+      })(),
+      new Promise<boolean>((resolve) => {
+        timer = setTimeout(() => resolve(true), INTERRUPTED_TURN_CLEANUP_WAIT_MS);
+      }),
+    ]);
+    clearTimeout(timer);
+    if (timedOut) {
+      this.logger.warn(
+        {
+          agentId: this.agentId,
+          provider: CODEX_PROVIDER,
+          waitMs: INTERRUPTED_TURN_CLEANUP_WAIT_MS,
+        },
+        "provider.codex.interrupt.terminal_cleanup_timed_out",
+      );
+    }
+  }
+
   async close(): Promise<void> {
     this.closed = true;
     this.clearPendingPermissions();
@@ -6209,6 +6372,11 @@ export class CodexAppServerAgentSession implements AgentSession {
       return;
     }
     this.completePendingRootCompactions();
+    // What a turn that was not interrupted leaves running, it left on purpose; no later
+    // interrupt may end it.
+    if (parsed.status !== "interrupted" && this.currentTurnId) {
+      this.terminalProcessIdsByTurnId.delete(this.currentTurnId);
+    }
     if (parsed.status === "failed") {
       this.emitEvent({
         type: "turn_failed",
@@ -6613,6 +6781,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   private async handleItemCompletedNotification(
     parsed: Extract<ParsedCodexNotification, { kind: "item_completed" }>,
   ): Promise<void> {
+    this.recordTurnTerminalProcess(parsed);
     // Codex emits mirrored lifecycle notifications via both `codex/event/item_*`
     // and canonical `item/*`. Render ordinary items only from the canonical
     // channel, but accept a legacy-only child announcement so it can establish
@@ -6775,6 +6944,7 @@ export class CodexAppServerAgentSession implements AgentSession {
   private async handleItemStartedNotification(
     parsed: Extract<ParsedCodexNotification, { kind: "item_started" }>,
   ): Promise<void> {
+    this.recordTurnTerminalProcess(parsed);
     if (shouldIgnoreMirroredLifecycleItem(parsed.source, parsed.item)) {
       return;
     }

packages/server/src/server/agent/providers/codex-interrupted-turn-terminals.test.ts

@@ -0,0 +1,374 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import type { AgentSession } from "../agent-sdk-types.js";
+import { createTestLogger } from "../../../test-utils/test-logger.js";
+import { CodexAppServerAgentSession } from "./codex-app-server-agent.js";
+import {
+  createFakeCodexAppServer,
+  type FakeCodexAppServer,
+  waitForNextEvent,
+  waitForTimelineToolCall,
+} from "./codex/test-utils/fake-app-server.js";
+
+const THREAD = "thread-1";
+const TERMINATE = "thread/backgroundTerminals/terminate";
+
+type Handler = (params: unknown) => unknown;
+
+function deferred<T = void>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
+}
+
+function paramsOf(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? (value as Record<string, unknown>) : {};
+}
+
+let sessions: AgentSession[] = [];
+
+afterEach(async () => {
+  for (const session of sessions) await session.close().catch(() => undefined);
+  sessions = [];
+});
+
+/**
+ * A Codex app-server whose interrupt ends the turn the way Codex does: an `interrupted`
+ * turn completion, then the response. `terminate` answers per process.
+ */
+function createHarness(
+  options: {
+    terminate?: (processId: string) => unknown;
+    interruptResponse?: (completeTurn: () => void) => unknown;
+  } = {},
+) {
+  const handlers: Record<string, Handler> = {
+    "turn/interrupt": () => {
+      const completeTurn = () =>
+        appServer.completeTurn({ threadId: THREAD, status: "interrupted" });
+      if (options.interruptResponse) return options.interruptResponse(completeTurn);
+      completeTurn();
+      return {};
+    },
+    [TERMINATE]: (params) =>
+      options.terminate?.(String(paramsOf(params).processId)) ?? { terminated: true },
+  };
+  const appServer: FakeCodexAppServer = createFakeCodexAppServer(handlers);
+  const session = new CodexAppServerAgentSession(
+    {
+      provider: "codex",
+      cwd: "/workspace/project",
+      modeId: "auto",
+      model: "gpt-5.4",
+    },
+    null,
+    createTestLogger(),
+    async () => appServer.child,
+  );
+  sessions.push(session);
+
+  function requests(method: string): Record<string, unknown>[] {
+    return appServer
+      .requests()
+      .filter((message) => message.method === method && "id" in message)
+      .map((message) => paramsOf(message.params));
+  }
+
+  function terminated(): string[] {
+    return requests(TERMINATE)
+      .map((params) => String(params.processId))
+      .sort();
+  }
+
+  // Starts a turn and lets Codex identify it as `nativeTurnId`.
+  async function startTurn(prompt: string, nativeTurnId: string): Promise<void> {
+    const before = requests("turn/start").length;
+    const started = session.startTurn(prompt);
+    await vi.waitFor(() => expect(requests("turn/start")).toHaveLength(before + 1), {
+      timeout: 5_000,
+    });
+    const turnStarted = waitForNextEvent(session, "turn_started");
+    appServer.startsTurn({ threadId: THREAD, turnId: nativeTurnId });
+    await started;
+    await turnStarted;
+  }
+
+  async function runsCommand(params: { turnId: string; processId: string }): Promise<void> {
+    const itemId = `exec-${params.processId}`;
+    const shown = waitForTimelineToolCall(session, itemId);
+    appServer.startsTerminalCommand({
+      threadId: THREAD,
+      turnId: params.turnId,
+      itemId,
+      processId: params.processId,
+      command: `sleep ${params.processId}`,
+    });
+    await shown;
+  }
+
+  async function completesTurn(): Promise<void> {
+    const completed = waitForNextEvent(session, "turn_completed");
+    appServer.completeTurn({ threadId: THREAD });
+    await completed;
+  }
+
+  // Interrupts the running turn and waits for the session to report it canceled, as a
+  // caller does before it starts the next turn: Codex notifications are handled in order
+  // but asynchronously, so the interrupt's answer can arrive before the turn has ended.
+  async function interrupts(): Promise<void> {
+    const canceled = waitForNextEvent(session, "turn_canceled");
+    await session.interrupt();
+    await canceled;
+  }
+
+  return {
+    appServer,
+    session,
+    requests,
+    terminated,
+    startTurn,
+    runsCommand,
+    completesTurn,
+    interrupts,
+  };
+}
+
+// Turn A leaves a server running on purpose and completes. Turn B starts two
+// commands, and a subagent on its own thread starts a third, then B is interrupted.
+async function interruptTurnB(harness: ReturnType<typeof createHarness>): Promise<void> {
+  await harness.startTurn("start a server", "native-A");
+  await harness.runsCommand({ turnId: "native-A", processId: "101" });
+  await harness.completesTurn();
+
+  await harness.startTurn("run two commands", "native-B");
+  await harness.runsCommand({ turnId: "native-B", processId: "201" });
+  // A subagent thread's command shows no row here; the next command's row shows it
+  // was read, because notifications are read in order.
+  harness.appServer.startsTerminalCommand({
+    threadId: "child-thread",
+    turnId: "native-B",
+    itemId: "exec-209",
+    processId: "209",
+    command: "sleep 209",
+  });
+  await harness.runsCommand({ turnId: "native-B", processId: "202" });
+  await harness.interrupts();
+}
+
+describe("an interrupted Codex turn's commands end before the next turn", () => {
+  test("terminates exactly the processes the interrupted turn started, by id, and never cleans", async () => {
+    const harness = createHarness();
+    await interruptTurnB(harness);
+    await harness.startTurn("correction", "native-C");
+
+    expect(harness.terminated()).toEqual(["201", "202"]);
+    expect(harness.requests(TERMINATE).every((params) => params.threadId === THREAD)).toBe(true);
+    // `clean` would end every terminal on the thread, an earlier turn's included.
+    expect(
+      harness.appServer
+        .requests()
+        .filter((message) => String(message.method).startsWith("thread/backgroundTerminals/"))
+        .map((message) => message.method),
+    ).toEqual([TERMINATE, TERMINATE]);
+    harness.appServer.assertNoErrors();
+  });
+
+  test("leaves the next turn's commands running when Codex starts that turn before acknowledging the interrupt", async () => {
+    const acknowledge = deferred();
+    const harness = createHarness({
+      // Codex ends B, starts a turn of its own (a goal continuation), and only then
+      // answers the interrupt.
+      interruptResponse: (completeTurn) => {
+        completeTurn();
+        return acknowledge.promise.then(() => ({}));
+      },
+    });
+    await harness.startTurn("run two commands", "native-B");
+    await harness.runsCommand({ turnId: "native-B", processId: "201" });
+    await harness.runsCommand({ turnId: "native-B", processId: "202" });
+    const interrupting = harness.session.interrupt();
+    await vi.waitFor(() => expect(harness.requests("turn/interrupt")).toHaveLength(1));
+    const autonomousTurn = waitForNextEvent(harness.session, "turn_started");
+    harness.appServer.startsTurn({ threadId: THREAD, turnId: "native-C" });
+    await autonomousTurn;
+    await harness.runsCommand({ turnId: "native-C", processId: "301" });
+
+    acknowledge.resolve();
+    await interrupting;
+    await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202"]));
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    expect(harness.terminated()).toEqual(["201", "202"]);
+  });
+
+  test("sends the next turn/start only after the terminates are answered", async () => {
+    const answer = deferred();
+    const harness = createHarness({
+      terminate: () => answer.promise.then(() => ({ terminated: true })),
+    });
+    await interruptTurnB(harness);
+    const next = harness.startTurn("correction", "native-C");
+    await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202"]));
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    expect(harness.requests("turn/start")).toHaveLength(2);
+
+    answer.resolve();
+    await next;
+    expect(harness.requests("turn/start")).toHaveLength(3);
+  });
+
+  test.each(["initial", "late"] as const)(
+    "tracks both cleanup sweeps when the %s answer arrives first",
+    async (answeredFirst) => {
+      const first = deferred();
+      const second = deferred();
+      const harness = createHarness({
+        terminate: (processId) =>
+          (processId === "201" ? first : second).promise.then(() => ({ terminated: true })),
+      });
+      await harness.startTurn("run commands", "native-B");
+      await harness.runsCommand({ turnId: "native-B", processId: "201" });
+      await harness.interrupts();
+      await vi.waitFor(() => expect(harness.terminated()).toEqual(["201"]));
+      const next = harness.startTurn("correction", "native-C");
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(harness.requests("turn/start")).toHaveLength(1);
+      // The next turn is already waiting when another process is announced.
+      harness.appServer.startsTerminalCommand({
+        threadId: THREAD,
+        turnId: "native-B",
+        itemId: "late-202",
+        processId: "202",
+        command: "sleep 202",
+      });
+      harness.appServer.startsTerminalCommand({
+        threadId: THREAD,
+        turnId: "native-B",
+        itemId: "duplicate-202",
+        processId: "202",
+        command: "sleep 202",
+      });
+      await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202"]));
+      (answeredFirst === "initial" ? first : second).resolve();
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      expect(harness.requests("turn/start")).toHaveLength(1);
+      (answeredFirst === "initial" ? second : first).resolve();
+      await next;
+      expect(harness.terminated()).toEqual(["201", "202"]);
+      // Accepted state survives the completed sweep and a newer foreground turn.
+      harness.appServer.startsTerminalCommand({
+        threadId: THREAD,
+        turnId: "native-B",
+        itemId: "late-203",
+        processId: "203",
+        command: "sleep 203",
+      });
+      await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202", "203"]));
+      harness.appServer.assertNoErrors();
+    },
+  );
+
+  test("keeps the first sweep pending when a late sweep answers before the next start", async () => {
+    const first = deferred();
+    const harness = createHarness({
+      terminate: (processId) =>
+        processId === "201"
+          ? first.promise.then(() => ({ terminated: true }))
+          : { terminated: true },
+    });
+    await harness.startTurn("run commands", "native-B");
+    await harness.runsCommand({ turnId: "native-B", processId: "201" });
+    await harness.interrupts();
+    harness.appServer.startsTerminalCommand({
+      threadId: THREAD,
+      turnId: "native-B",
+      itemId: "late-202",
+      processId: "202",
+      command: "sleep 202",
+    });
+    await vi.waitFor(() => expect(harness.terminated()).toEqual(["201", "202"]));
+    const next = harness.startTurn("correction", "native-C");
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(harness.requests("turn/start")).toHaveLength(1);
+    first.resolve();
+    await next;
+    harness.appServer.assertNoErrors();
+  });
+
+  test("forgets completed commands but retains failed commands at interrupt", async () => {
+    const harness = createHarness();
+    await harness.startTurn("run commands", "native-B");
+    for (const processId of ["201", "202"]) {
+      await harness.runsCommand({ turnId: "native-B", processId });
+      harness.appServer.child.stdout.write(
+        JSON.stringify({
+          method: "item/completed",
+          params: {
+            threadId: THREAD,
+            turnId: "native-B",
+            item: {
+              id: `exec-${processId}`,
+              type: "commandExecution",
+              processId,
+              command: `sleep ${processId}`,
+              status: processId === "201" ? "completed" : "failed",
+              exitCode: processId === "201" ? 0 : null,
+            },
+          },
+        }) + "\n",
+      );
+    }
+    // A following command's row is a barrier for both completion handlers.
+    await harness.runsCommand({ turnId: "native-B", processId: "203" });
+    await harness.interrupts();
+    await harness.startTurn("correction", "native-C");
+    expect(harness.terminated()).toEqual(["202", "203"]);
+    harness.appServer.assertNoErrors();
+  });
+
+  test("retains accepted interrupts for only the latest sixteen turns", async () => {
+    const harness = createHarness();
+    for (let index = 0; index < 17; index++) {
+      await harness.startTurn("run a command", `native-${index}`);
+      await harness.interrupts();
+    }
+    await harness.startTurn("correction", "native-current");
+    harness.appServer.startsTerminalCommand({
+      threadId: THREAD,
+      turnId: "native-0",
+      itemId: "evicted-201",
+      processId: "201",
+      command: "sleep 201",
+    });
+    harness.appServer.startsTerminalCommand({
+      threadId: THREAD,
+      turnId: "native-16",
+      itemId: "retained-202",
+      processId: "202",
+      command: "sleep 202",
+    });
+    await harness.runsCommand({ turnId: "native-current", processId: "301" });
+    expect(harness.terminated()).toEqual(["202"]);
+    harness.appServer.assertNoErrors();
+  });
+
+  test("a failing or unanswered terminate does not block or fail the next turn", async () => {
+    const harness = createHarness({
+      // 201 is refused while the next turn waits; 202 is never answered.
+      terminate: (processId) =>
+        processId === "201"
+          ? new Promise((resolve) => setTimeout(resolve, 300)).then(() => ({
+              __jsonRpcError: { code: -32600, message: "invalid background terminal process id" },
+            }))
+          : new Promise(() => {}),
+    });
+    await interruptTurnB(harness);
+    const startedAt = Date.now();
+    await harness.startTurn("correction", "native-C");
+
+    expect(Date.now() - startedAt).toBeLessThan(5_000);
+    expect(harness.requests("turn/start")).toHaveLength(3);
+    expect(harness.terminated()).toEqual(["201", "202"]);
+  }, 15_000);
+});