Merge remote-tracking branch 'origin/main' into fix/gitlab-fork-checkout-8159

fix(gitlab): identify fork checkouts by their source project
Merge request authors do not necessarily own the source fork. Resolve its namespace and repository URLs before naming the checkout and configuring its push remote, retaining the target MR ref when the source returns 404. Co-authored-by: quickwind <wallacewei@live.cn>
2026-11-02 22:52:58 +00:00 · 2026-11-02 09:54:43 +00:00 · 2026-11-02 09:54:18 +00:00 · 2026-11-02 08:59:37 +00:00 · 2026-11-02 15:42:39 +07:00 · 2026-11-02 07:58:56 +00:00
104 changed files with 3738 additions and 922 deletions
@@ -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.
@@ -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();
+    });
+  });
+});
@@ -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.",
@@ -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");
+    },
  };
 }

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

@@ -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 };
@@ -111,6 +111,7 @@ export type PluginClientRuntime = Pick<
  | "openScreen"
  | "openSurface"
  | "openPanel"
+  | "subscribe"
  | "addComposerPill"
  | "addHeaderButton"
 > & { hosts: ReturnType<typeof createPluginHosts> };
@@ -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: [],
@@ -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>
@@ -62,6 +62,9 @@ function registry(
        openPanel: () => {},
        addComposerPill: () => ({ update() {}, remove() {} }),
        addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
      };
    },
  });
@@ -39,6 +39,9 @@ function registry(version: string) {
        openPanel() {},
        addComposerPill: () => ({ update() {}, remove() {} }),
        addHeaderButton: () => ({ update() {}, remove() {} }),
+        subscribe: () => {
+          throw new Error("Subscriptions are not used here");
+        },
      };
    },
  });
@@ -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,
@@ -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: {
@@ -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;
+});
@@ -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,
+    });
+  };
+}
@@ -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 })),
@@ -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: [] },
@@ -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: [],
@@ -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 = {
@@ -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":
@@ -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;
@@ -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: [],
@@ -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>;

@@ -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();
@@ -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();
@@ -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,
@@ -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", {
@@ -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([]);
+  });
+});
@@ -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`. */
@@ -24,17 +24,23 @@ describe("plugin RPC contracts", () => {
    expectTypeOf<RpcOutput<typeof contract>>().toEqualTypeOf<{ value: number }>();
  });

-  it("validates input before invoking the daemon", async () => {
-    let invocations = 0;
-    const invoke = async () => {
-      invocations += 1;
-      return { value: 2 };
+  it("sends input unchanged for the plugin to parse", async () => {
+    let parses = 0;
+    const transformed = defineRpc({
+      name: "transformed",
+      input: z.string().transform((text) => {
+        parses += 1;
+        return Number(text);
+      }),
+      output: z.number(),
+    });
+    const invoke = async (_method: string, input: unknown) => {
+      expect(input).toBe("2");
+      expect(parses).toBe(0);
+      return transformed.input.parseAsync(input);
    };
-
-    await expect(callPluginRpc(contract, invoke, { value: "wrong" })).rejects.toBeInstanceOf(
-      z.ZodError,
-    );
-    expect(invocations).toBe(0);
+    await expect(callPluginRpc(transformed, invoke, "2")).resolves.toBe(2);
+    expect(parses).toBe(1);
  });

  it("validates output before resolving", async () => {
@@ -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,
@@ -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";
@@ -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));
+}
@@ -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>
@@ -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 {
@@ -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,98 @@ 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);
+  const output = await invoke(contract.name, input);
  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;
+}
@@ -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;
@@ -11,6 +11,7 @@ export type {
  PluginServerContribution,
  PluginSettings,
  PluginSettingsState,
+  PluginSubscriptionContext,
 } from "./contracts.js";
 export type {
  PluginHooks,
@@ -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;
  }
@@ -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";
@@ -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.",
+    );
+  });
+});
@@ -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;
+}
@@ -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",
@@ -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);
+  });
+});
@@ -1603,6 +1603,14 @@ export const PluginRpcInvokeRequestSchema = z.object({
  requestId: z.string(),
  pluginId: PluginIdSchema,
  method: z.string().min(1),
+  input: z.unknown().optional(),
+});
+
+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(),
 });

@@ -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.
@@ -6958,10 +6969,26 @@ export const PluginRpcInvokeResponseSchema = z.object({
  type: z.literal("plugin.rpc.invoke.response"),
  payload: z.object({
    requestId: z.string(),
-    output: z.unknown(),
+    output: z.unknown().optional(),
  }),
 });

+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,
@@ -5,7 +5,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
 import type { z } from "zod";
 import { describe, expect, it } from "vitest";
-import { WSOutboundMessageSchema } from "../../src/messages.js";
+import { PluginRpcInvokeResponseSchema, WSOutboundMessageSchema } from "../../src/messages.js";
 import { validateWSOutboundMessage } from "../../src/validation/ws-outbound.js";

 interface GeneratedSchema {
@@ -401,3 +401,8 @@ const SourceSchema = z.object({
    });
  });
 });
+
+it("accepts omitted RPC output so the receiving client can apply schema defaults", () => {
+  const message = { type: "plugin.rpc.invoke.response", payload: { requestId: "default-output" } };
+  expect(PluginRpcInvokeResponseSchema.safeParse(message).success).toBe(true);
+});
@@ -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",
@@ -13,6 +13,11 @@ interface ScriptedTurn {
  before?: string;
  after?: string;
  isError: boolean;
+  subtype?:
+    | "error_max_turns"
+    | "error_during_execution"
+    | "error_max_budget_usd"
+    | "error_max_structured_output_retries";
  usage?: {
    inputTokens: number;
    cachedInputTokens: number;
@@ -57,11 +62,12 @@ function scriptedQuery(turns: ScriptedTurn[]): ClaudeQueryFactory {
        if (turn.after) yield assistant(`after-${index}`, turn.after);
        yield {
          type: "result",
-          subtype: "success",
+          subtype: turn.subtype ?? "success",
          session_id: "error-session",
          duration_ms: 1,
          duration_api_ms: 0,
          is_error: turn.isError,
+          ...(turn.subtype ? { errors: ["Reached maximum number of turns (1)"] } : {}),
          num_turns: 1,
          result: turn.isError ? (turn.errorReply ?? "") : (turn.after ?? turn.errorReply ?? ""),
          stop_reason: "stop_sequence",
@@ -188,3 +194,33 @@ test("an error reply the turn moves past is still shown", async () => {
  expect(terminal(completed)).toMatchObject({ type: "turn_completed" });
  expect(assistantTexts(completed)).toEqual([LIMIT]);
 });
+
+test.each([
+  "error_max_turns",
+  "error_during_execution",
+  "error_max_budget_usd",
+  "error_max_structured_output_retries",
+] as const)("a %s result publishes final usage before failure", async (subtype) => {
+  const usage = {
+    inputTokens: 2,
+    cachedInputTokens: 12577,
+    outputTokens: 110,
+    totalCostUsd: 0.00365537,
+  };
+  const [failed, next] = await runTurns([
+    { before: "Running the command.", isError: true, subtype, usage },
+    { after: "Done.", isError: false },
+  ]);
+
+  // Collection ends at the terminal event, so this also checks ordering.
+  expect(failed).toContainEqual(
+    expect.objectContaining({ type: "usage_updated", usage: expect.objectContaining(usage) }),
+  );
+  expect(terminal(failed)).toMatchObject({
+    type: "turn_failed",
+    error: "Reached maximum number of turns (1)",
+  });
+  expect(assistantTexts(failed)).toEqual(["Running the command."]);
+  expect(terminal(next)).toMatchObject({ type: "turn_completed" });
+  expect(assistantTexts(next)).toEqual(["Done."]);
+});
@@ -5037,6 +5037,7 @@ class ClaudeAgentSession implements AgentSession {
      "errors" in message && Array.isArray(message.errors) && message.errors.length > 0
        ? message.errors.join("\n")
        : "Claude run failed";
+    if (usage) events.push({ type: "usage_updated", provider: "claude", usage });
    events.push(...this.sidechainTracker.finishAll("failed"));
    events.push(this.buildTurnFailedEvent(errorMessage));
  }
@@ -145,6 +145,16 @@ function piAssistantEntry(id: string, parentId: string): PiSessionEntry {
  return { type: "message", id, parentId, message: { role: "assistant", content: [] } };
 }

+// Pi's context path: the entries from the root to the leaf.
+function piBranchTo(entries: PiSessionEntry[], leafId: string): PiSessionEntry[] {
+  const byId = new Map(entries.map((entry) => [entry.id, entry]));
+  const branch: PiSessionEntry[] = [];
+  for (let entry = byId.get(leafId); entry; entry = byId.get(entry.parentId ?? "")) {
+    branch.unshift(entry);
+  }
+  return branch;
+}
+
 function parseEntryCapture(notification: string): unknown {
  const prefix = "PASEO_ENTRY_CAPTURE ";
  expect(notification.startsWith(prefix)).toBe(true);
@@ -1008,7 +1018,7 @@ describe("PiRpcAgentSession", () => {
    const events = new SessionEvents(session);
    const fakeSession = pi.latestSession();
    fakeSession.treeUserEntries = [{ id: "entry-old", parentId: null, text: "old prompt" }];
-    fakeSession.historyUserEntries = fakeSession.treeUserEntries;
+    fakeSession.contextUserEntries = fakeSession.treeUserEntries;

    await session.startTurn("new prompt", { clientMessageId: "client-new" });
    fakeSession.finishSubmittedUserMessage({
@@ -1743,7 +1753,7 @@ describe("PiRpcAgentSession", () => {
    await session.close();
  });

-  test("captures all session user entries as rewind targets, including abandoned branches", async () => {
+  test("captures the session's user entries apart from the ones on the current branch", async () => {
    const pi = new FakePi();
    const session = await createClient(pi).createSession(createConfig());
    onTestFinished(() => session.close());
@@ -1761,6 +1771,7 @@ describe("PiRpcAgentSession", () => {
    const context = {
      sessionManager: {
        getEntries: () => entries,
+        buildContextEntries: () => piBranchTo(entries, "two-reply"),
      },
      ui: { notify: (message: string) => notifications.push(message) },
    };
@@ -1775,6 +1786,10 @@ describe("PiRpcAgentSession", () => {
          { id: "abandoned", parentId: "one-reply", text: "rewound away" },
          { id: "two", parentId: "one-reply", text: "second" },
        ],
+        contextEntries: [
+          { id: "one", parentId: null, text: "first" },
+          { id: "two", parentId: "one-reply", text: "second" },
+        ],
      },
    ]);
  });
@@ -3249,7 +3264,7 @@ describe("PiRpcAgentClient", () => {
      { id: "entry-1", parentId: null, text: "first prompt" },
      { id: "entry-3", parentId: "entry-2", text: "second prompt" },
    ];
-    pi.latestSession().historyUserEntries = pi.latestSession().treeUserEntries;
+    pi.latestSession().contextUserEntries = pi.latestSession().treeUserEntries;

    await session.startTurn("first prompt");
    pi.latestSession().finishTurn({ role: "assistant", content: [] });
@@ -3273,7 +3288,7 @@ describe("PiRpcAgentClient", () => {
      { id: "entry-1", parentId: null, text: "first prompt" },
      { id: "entry-3", parentId: "entry-2", text: "second prompt" },
    ];
-    fakeSession.historyUserEntries = [
+    fakeSession.contextUserEntries = [
      { id: "entry-3", parentId: "entry-2", text: "second prompt" },
    ];

@@ -687,6 +687,8 @@ function createPiPaseoExtensionFile({
 	        requestId,
 	        // Rewind targets: rows can still show entries that a rewind or compaction left off the branch.
 	        treeEntries: toCapturedUserEntries(ctx.sessionManager.getEntries()),
+	        // The entries getMessages() replays, so the nth one is the nth replayed user message.
+	        contextEntries: toCapturedUserEntries(ctx.sessionManager.buildContextEntries()),
 	      }),
 	    "info",
 	  );
@@ -1210,6 +1212,7 @@ export class PiRpcAgentSession implements AgentSession {
  private readonly pendingPromptResults = new Map<string, boolean>();
  private readonly pendingSteerSubmissions: PiPendingSteerSubmission[] = [];
  currentLeafOverrideId: string | null | undefined;
+  private readonly contextUserEntries: PiCapturedEntry[] = [];
  private readonly treeUserEntriesById = new Map<string, PiCapturedEntry>();
  private readonly pendingExtensionResults = new Map<string, PendingExtensionResult>();
  private compactionPromise: Promise<void> | null = null;
@@ -1452,11 +1455,10 @@ export class PiRpcAgentSession implements AgentSession {

  async *streamHistory(): AsyncGenerator<AgentStreamEvent> {
    await this.requestEntryCapture("history");
-    const history = await this.runtimeSession.getHistory();
    yield* streamPiHistory(
      this.provider,
-      history.messages,
-      history.userEntries,
+      await this.runtimeSession.getMessages(),
+      this.contextUserEntries,
      {},
      // At most eight 2 MiB child files per replay; later cards retain their summaries.
      createPiExtensionHost(this.logger, undefined, 16 * 1024 * 1024),
@@ -2008,9 +2010,13 @@ export class PiRpcAgentSession implements AgentSession {
    }
  }

-  private recordCapturedUserEntries(entries: PiCapturedEntry[]): void {
+  private recordCapturedUserEntries(input: {
+    treeEntries: PiCapturedEntry[];
+    contextEntries: PiCapturedEntry[];
+  }): void {
+    this.contextUserEntries.splice(0, this.contextUserEntries.length, ...input.contextEntries);
    this.treeUserEntriesById.clear();
-    for (const entry of entries) {
+    for (const entry of input.treeEntries) {
      this.treeUserEntriesById.set(entry.id, entry);
    }
  }
@@ -2047,7 +2053,10 @@ export class PiRpcAgentSession implements AgentSession {
    if (!payload) {
      return false;
    }
-    this.recordCapturedUserEntries(parseCapturedEntries(payload.treeEntries));
+    this.recordCapturedUserEntries({
+      treeEntries: parseCapturedEntries(payload.treeEntries),
+      contextEntries: parseCapturedEntries(payload.contextEntries),
+    });
    if (typeof payload.requestId === "string") {
      this.resolveExtensionResult(payload.requestId, undefined);
    }
@@ -1,5 +1,3 @@
-import { mkdir, mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
-import path from "node:path";
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { PassThrough } from "node:stream";
@@ -547,102 +545,3 @@ describe("PiCliRuntime", () => {
    await expect(session.abort()).resolves.toBeUndefined();
  });
 });
-
-async function createHistoryTestDirectory(prefix: string): Promise<string> {
-  const artifacts = path.resolve(".artifacts/pi-timeline");
-  await mkdir(artifacts, { recursive: true });
-  return mkdtemp(path.join(artifacts, prefix));
-}
-
-test("reads complete persisted history instead of compacted RPC context", async () => {
-  const root = await createHistoryTestDirectory("runtime-");
-  const file = path.join(root, "session.jsonl");
-  const records = [
-    { type: "session", version: 3, id: "session" },
-    {
-      type: "message",
-      id: "old-user",
-      parentId: "system",
-      message: { role: "user", content: "before compaction" },
-    },
-    {
-      type: "message",
-      id: "old-answer",
-      parentId: "old-user",
-      message: { role: "assistant", content: [{ type: "text", text: "old answer" }] },
-    },
-    { type: "compaction", id: "compact", parentId: "old-answer", summary: "summary" },
-    {
-      type: "message",
-      id: "new-user",
-      parentId: "compact",
-      message: { role: "user", content: "after compaction" },
-    },
-  ];
-  records.splice(1, 0, {
-    type: "message",
-    id: "system",
-    parentId: null,
-    message: { role: "system", content: "private instructions" },
-  });
-  const contents = records.map((row) => JSON.stringify(row)).join("\n");
-  await writeFile(file, contents);
-  const child = createPiChild();
-  onPiCommand(child, (command) =>
-    writePiResponse(
-      child,
-      command,
-      command.type === "get_state" ? { sessionFile: file } : { messages: [records[5].message] },
-    ),
-  );
-  const runtime = await createRuntime(child).startSession({ cwd: root });
-  try {
-    const history = await runtime.getHistory();
-    expect(history.userEntries.map((entry) => entry.id)).toEqual(["old-user", "new-user"]);
-    expect(history.messages).toEqual([records[2].message, records[3].message, records[5].message]);
-    expect(await readFile(file, "utf8")).toBe(contents);
-    await writeFile(
-      file,
-      contents +
-        '\n{"type":"custom","id":"rewind","parentId":"old-answer","customType":"paseo_rewind"}',
-    );
-    expect((await runtime.getHistory()).userEntries.map((entry) => entry.id)).toEqual(["old-user"]);
-    await writeFile(
-      file,
-      contents + '\n{"type":"custom","id":"rewind","parentId":null,"customType":"paseo_rewind"}',
-    );
-    expect((await runtime.getHistory()).messages).toEqual([]);
-    await writeFile(file, contents + '\n{"type":"custom","id":"bad","parentId":"missing"}');
-    await expect(runtime.getHistory()).rejects.toThrow("Missing Pi transcript ancestor");
-  } finally {
-    await runtime.close();
-    await rm(root, { recursive: true, force: true });
-  }
-});
-
-test("permits the unpersisted empty new session but refuses a missing resumed transcript", async () => {
-  const root = await createHistoryTestDirectory("empty-");
-  const file = path.join(root, "not-created.jsonl");
-  const child = createPiChild();
-  onPiCommand(child, (command) =>
-    writePiResponse(child, command, { sessionFile: file, messageCount: 0 }),
-  );
-  const runtime = createRuntime(child);
-  const fresh = await runtime.startSession({ cwd: root });
-  try {
-    expect(await fresh.getHistory()).toEqual({ messages: [], userEntries: [] });
-  } finally {
-    await fresh.close();
-  }
-  const resumedChild = createPiChild();
-  onPiCommand(resumedChild, (command) =>
-    writePiResponse(resumedChild, command, { sessionFile: file, messageCount: 0 }),
-  );
-  const resumed = await createRuntime(resumedChild).startSession({ cwd: root, session: file });
-  try {
-    await expect(resumed.getHistory()).rejects.toThrow("ENOENT");
-  } finally {
-    await resumed.close();
-    await rm(root, { recursive: true, force: true });
-  }
-});
@@ -1,5 +1,3 @@
-import { readFile } from "node:fs/promises";
-import { readPiTranscript, type PiTranscript } from "./transcript.js";
 import { createExternalProcessEnv } from "../../../paseo-env.js";
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { Logger } from "pino";
@@ -18,6 +16,7 @@ import {
  type PiStartSessionInput,
 } from "./runtime.js";
 import type {
+  PiAgentMessage,
  PiModel,
  PiPromptAck,
  PiRpcCommand,
@@ -79,27 +78,18 @@ export class PiCliRuntime implements PiRuntime {
      await process.close(input.signal.reason);
      input.signal.throwIfAborted();
    }
-    return new PiCliRuntimeSession({
-      process,
-      commandsRpcName: this.commandsRpcName,
-      launchEnvironment: launch.env,
-      newSession: input.session === undefined,
-    });
+    return new PiCliRuntimeSession(process, this.commandsRpcName, launch.env);
  }
 }

-interface PiCliRuntimeSessionOptions {
-  process: JsonlRpcProcess;
-  commandsRpcName: string;
-  launchEnvironment: Record<string, string>;
-  newSession: boolean;
-}
-
 class PiCliRuntimeSession implements PiRuntimeSession {
  private readonly subscribers = new Set<(event: PiRuntimeEvent) => void>();

-  constructor(private readonly options: PiCliRuntimeSessionOptions) {
-    const { process } = options;
+  constructor(
+    private readonly process: JsonlRpcProcess,
+    private readonly commandsRpcName: string,
+    private readonly launchEnvironment: Record<string, string>,
+  ) {
    process.onMessage((message) => {
      this.emit(message as PiRuntimeEvent);
    });
@@ -109,7 +99,7 @@ class PiCliRuntimeSession implements PiRuntimeSession {
  }

  get environment(): Record<string, string> {
-    return this.options.launchEnvironment;
+    return this.launchEnvironment;
  }

  onEvent(callback: (event: PiRuntimeEvent) => void): () => void {
@@ -123,7 +113,7 @@ class PiCliRuntimeSession implements PiRuntimeSession {
    message: string,
    images?: Array<{ type: "image"; data: string; mimeType: string }>,
  ): Promise<PiPromptAck> {
-    const { id: requestId, promise } = this.options.process.startRequest({
+    const { id: requestId, promise } = this.process.startRequest({
      type: "prompt",
      message,
      ...(images?.length ? { images } : {}),
@@ -172,23 +162,9 @@ class PiCliRuntimeSession implements PiRuntimeSession {
    return (await this.request({ type: "get_state" })) as PiSessionState;
  }

-  async getHistory(): Promise<PiTranscript> {
-    const state = await this.getState();
-    if (!state.sessionFile) throw new Error("Pi history requires a persisted session file");
-    try {
-      return readPiTranscript(await readFile(state.sessionFile, "utf8"));
-    } catch (error) {
-      // Pi does not create the file until the first conversation message is saved.
-      if (
-        this.options.newSession &&
-        state.messageCount === 0 &&
-        error instanceof Error &&
-        "code" in error &&
-        error.code === "ENOENT"
-      )
-        return { messages: [], userEntries: [] };
-      throw error;
-    }
+  async getMessages(): Promise<PiAgentMessage[]> {
+    const data = (await this.request({ type: "get_messages" })) as { messages?: PiAgentMessage[] };
+    return data.messages ?? [];
  }

  async getAvailableModels(timeoutMs?: number | null): Promise<PiModel[]> {
@@ -239,21 +215,21 @@ class PiCliRuntimeSession implements PiRuntimeSession {
  }

  async getCommands(): Promise<PiRpcSlashCommand[]> {
-    const data = (await this.request({ type: this.options.commandsRpcName })) as {
+    const data = (await this.request({ type: this.commandsRpcName })) as {
      commands?: PiRpcSlashCommand[];
    };
    return data.commands ?? [];
  }

  sendRawFrame(frame: object & { type: string }): void {
-    this.options.process.send(frame);
+    this.process.send(frame);
  }

  respondToExtensionUiRequest(
    id: string,
    response: { value?: string; confirmed?: boolean; cancelled?: boolean },
  ): void {
-    this.options.process.send({ type: "extension_ui_response", id, ...response });
+    this.process.send({ type: "extension_ui_response", id, ...response });
  }

  cancelExtensionUiRequest(id: string): void {
@@ -261,22 +237,22 @@ class PiCliRuntimeSession implements PiRuntimeSession {
  }

  async close(): Promise<void> {
-    await this.options.process.close(new Error("Pi RPC session is closed"));
+    await this.process.close(new Error("Pi RPC session is closed"));
  }

  request(command: PiRpcCommand, timeoutMs?: number | null): Promise<unknown> {
-    return this.options.process.request(command, timeoutMs);
+    return this.process.request(command, timeoutMs);
  }

  private requestStopWork(command: PiRpcCommand): Promise<void> {
-    return this.options.process.requestStopWork(command);
+    return this.process.requestStopWork(command);
  }

  private async waitForCompletion(command: PiRpcCommand): Promise<void> {
    // Pi only replies after its compaction work is durable. Its child process and
    // session close paths already reject pending RPCs, so no elapsed-time failure
    // is useful here.
-    await this.options.process.request(command, JSONL_RPC_NO_TIMEOUT);
+    await this.process.request(command, JSONL_RPC_NO_TIMEOUT);
  }

  private emit(event: PiRuntimeEvent): void {
@@ -1,5 +1,3 @@
-import { buildAgentForkContextAttachment } from "../../activity-curator.js";
-import { readPiTranscript } from "./transcript.js";
 import { describe, expect, test } from "vitest";

 import type { AgentStreamEvent } from "../../agent-sdk-types.js";
@@ -295,235 +293,3 @@ test("replayed Pi images keep their position before the following reply", async
    ),
  ).toEqual(["tool_call", expect.stringContaining("![Image]("), "Image read complete."]);
 });
-
-test("replays both sides of compaction with native IDs and isolates rewound branches", async () => {
-  const records = [
-    { type: "session", version: 3, id: "session" },
-    {
-      type: "message",
-      id: "u1",
-      parentId: null,
-      message: { role: "user", content: "old question" },
-    },
-    {
-      type: "message",
-      id: "a1",
-      parentId: "u1",
-      message: { role: "assistant", content: [{ type: "text", text: "old answer" }] },
-    },
-    { type: "compaction", id: "c1", parentId: "a1", summary: "summary", firstKeptEntryId: "a1" },
-    { type: "message", id: "u2", parentId: "c1", message: { role: "user", content: "follow up" } },
-  ];
-  const decode = (rows: unknown[]) =>
-    readPiTranscript(rows.map((row) => JSON.stringify(row)).join("\n"));
-  const history = decode(records);
-  expect(history.userEntries.map((entry) => entry.id)).toEqual(["u1", "u2"]);
-  expect(history.messages.map((message) => message.role)).toEqual(["user", "assistant", "user"]);
-  expect(await collectHistory(history.messages, history.userEntries)).toHaveLength(3);
-  const rewound = [
-    ...records,
-    { type: "custom", id: "r1", parentId: null, customType: "paseo_rewind" },
-  ];
-  expect(decode(rewound).messages).toEqual([]);
-  const replacement = [
-    ...rewound,
-    {
-      type: "message",
-      id: "u3",
-      parentId: "r1",
-      message: { role: "user", content: "replacement" },
-    },
-  ];
-  expect(decode(replacement).userEntries.map((entry) => entry.id)).toEqual(["u3"]);
-  expect(
-    decode([
-      ...replacement,
-      { type: "custom", id: "r2", parentId: "a1", customType: "paseo_rewind" },
-    ]).userEntries.map((entry) => entry.id),
-  ).toEqual(["u1"]);
-});
-
-test("preserves native custom entries and legacy linear messages without inventing native IDs", async () => {
-  const custom = {
-    type: "custom_message",
-    id: "custom",
-    parentId: null,
-    customType: "notice",
-    content: "visible notice",
-    display: true,
-    details: { key: 1 },
-  };
-  const history = readPiTranscript(
-    [JSON.stringify({ type: "session", version: 3 }), JSON.stringify(custom)].join("\n"),
-  );
-  expect(history.messages).toEqual([{ ...custom, role: "custom" }]);
-  expect(await collectHistory(history.messages, history.userEntries)).toHaveLength(1);
-  const legacy = readPiTranscript(
-    '{"type":"session","version":1}\n{"type":"message","message":{"role":"user","content":"legacy"}}',
-  );
-  expect(legacy.messages).toEqual([{ role: "user", content: "legacy" }]);
-  expect(legacy.userEntries).toEqual([]);
-});
-
-test.each([
-  [{ type: "message", id: "x", parentId: "x", message: { role: "user", content: "cycle" } }],
-  [{ type: "message", id: "x", parentId: "missing", message: { role: "user", content: "orphan" } }],
-  [
-    { type: "custom", id: "x", parentId: null },
-    { type: "custom", id: "x", parentId: null },
-  ],
-  [{ type: "custom", id: "x" }],
-])("rejects corrupt ancestry rather than replaying a plausible branch: %j", (...entries) => {
-  expect(() =>
-    readPiTranscript(
-      [
-        JSON.stringify({ type: "session", version: 3 }),
-        ...entries.map((entry) => JSON.stringify(entry)),
-      ].join("\n"),
-    ),
-  ).toThrow();
-});
-
-test("Fork chat stops at a restored pre-compaction reply on the active branch", async () => {
-  const entries = [
-    { type: "session", version: 3 },
-    {
-      type: "message",
-      id: "u1",
-      parentId: null,
-      message: { role: "user", content: "retained question" },
-    },
-    {
-      type: "message",
-      id: "a1",
-      parentId: "u1",
-      message: { role: "assistant", content: [{ type: "text", text: "retained answer" }] },
-    },
-    {
-      type: "message",
-      id: "abandoned",
-      parentId: "a1",
-      message: { role: "user", content: "abandoned branch" },
-    },
-    { type: "compaction", id: "c1", parentId: "a1", summary: "summary" },
-    {
-      type: "message",
-      id: "later",
-      parentId: "c1",
-      message: { role: "user", content: "later question" },
-    },
-  ];
-  const transcript = readPiTranscript(entries.map((entry) => JSON.stringify(entry)).join("\n"));
-  const events = await collectHistory(transcript.messages, transcript.userEntries);
-  const rows = events
-    .filter((event) => event.type === "timeline")
-    .map((event, index) => ({
-      seq: index + 1,
-      timestamp: "2026-10-31T00:00:00.000Z",
-      item: event.item,
-    }));
-  const fork = buildAgentForkContextAttachment({
-    rows,
-    cursorBoundary: { cursor: { epoch: "test", seq: 2 }, timelineEpoch: "test" },
-  });
-  expect(fork.attachment.text).toContain("retained question");
-  expect(fork.attachment.text).toContain("retained answer");
-  expect(fork.attachment.text).not.toContain("abandoned branch");
-  expect(fork.attachment.text).not.toContain("later question");
-  expect(transcript.userEntries.map((entry) => entry.id)).toEqual(["u1", "later"]);
-});
-
-test("keeps reasoning, image content and tool results across structural entries", async () => {
-  const messages: PiAgentMessage[] = [
-    {
-      role: "user",
-      content: [
-        { type: "image", data: "aGVsbG8=", mimeType: "image/png" },
-        { type: "text", text: "inspect" },
-      ],
-    },
-    {
-      role: "assistant",
-      content: [
-        { type: "thinking", thinking: "consider" },
-        { type: "toolCall", id: "call", name: "read", arguments: { path: "a.txt" } },
-      ],
-    },
-    {
-      role: "toolResult",
-      toolCallId: "call",
-      toolName: "read",
-      content: [{ type: "text", text: "file contents" }],
-    },
-    { role: "assistant", content: [{ type: "text", text: "answer" }] },
-  ];
-  const records = [
-    { type: "session", version: 3 },
-    ...messages.map((message, index) => ({
-      type: "message",
-      id: String(index),
-      parentId: index === 0 ? null : String(index - 1),
-      message,
-    })),
-    { type: "compaction", id: "compact", parentId: "3", summary: "summary" },
-  ];
-  const history = readPiTranscript(records.map((record) => JSON.stringify(record)).join("\n"));
-  expect(history.messages).toEqual(messages);
-  expect(history.userEntries).toEqual([{ id: "0", text: "inspect" }]);
-  expect(await collectHistory(history.messages, history.userEntries)).toEqual(
-    await collectHistory(messages, [{ id: "0", text: "inspect" }]),
-  );
-});
-
-test("traverses native system and summary messages without displaying private context", () => {
-  const roles = [
-    { role: "system", content: "private instructions" },
-    { role: "user", content: "question" },
-    { role: "branchSummary", summary: "branch context" },
-    { role: "compactionSummary", summary: "compacted context" },
-    { role: "system", content: null },
-  ];
-  const rows = [
-    { type: "session", version: 3 },
-    ...roles.map((message, index) => ({
-      type: "message",
-      id: String(index),
-      parentId: index === 0 ? null : String(index - 1),
-      message,
-    })),
-  ];
-  expect(readPiTranscript(rows.map((row) => JSON.stringify(row)).join("\n"))).toEqual({
-    messages: [{ role: "user", content: "question" }],
-    userEntries: [{ id: "1", text: "question" }],
-  });
-});
-
-test("restores surrounding chat when native system content uses text blocks", async () => {
-  const records = [
-    { type: "session", version: 3 },
-    { type: "message", id: "u", parentId: null, message: { role: "user", content: "question" } },
-    {
-      type: "message",
-      id: "s",
-      parentId: "u",
-      message: { role: "system", content: [{ type: "text", text: "private instructions" }] },
-    },
-    {
-      type: "message",
-      id: "a",
-      parentId: "s",
-      message: { role: "assistant", content: [{ type: "text", text: "answer" }] },
-    },
-  ];
-  const history = readPiTranscript(records.map((record) => JSON.stringify(record)).join("\n"));
-  expect(history.messages).toEqual([
-    { role: "user", content: "question" },
-    { role: "assistant", content: [{ type: "text", text: "answer" }] },
-  ]);
-  expect(history.userEntries).toEqual([{ id: "u", text: "question" }]);
-  const events = await collectHistory(history.messages, history.userEntries);
-  expect(events.map((event) => event.item)).toEqual([
-    { type: "user_message", text: "question", messageId: "u" },
-    { type: "assistant_message", text: "answer", messageId: "pi-history-assistant-1" },
-  ]);
-});
@@ -1,5 +1,5 @@
-import type { PiTranscript } from "./transcript.js";
 import type {
+  PiAgentMessage,
  PiModel,
  PiPromptAck,
  PiRpcSlashCommand,
@@ -55,7 +55,7 @@ export interface PiRuntimeSession {
  setAutoCompaction(enabled: boolean): Promise<void>;
  abort(): Promise<void>;
  getState(): Promise<PiSessionState>;
-  getHistory(): Promise<PiTranscript>;
+  getMessages(): Promise<PiAgentMessage[]>;
  getAvailableModels(timeoutMs?: number | null): Promise<PiModel[]>;
  setModel(provider: string, modelId: string): Promise<PiModel>;
  setThinkingLevel(level: string): Promise<void>;
@@ -150,8 +150,8 @@ export class FakePiSession implements PiRuntimeSession {
  readonly rawFrames: Array<object & { type: string }> = [];
  // Every user entry in the session file, including rewound and compacted ones.
  treeUserEntries: FakePiUserEntry[] = [];
-  // Native user entries paired with the complete active-branch history.
-  historyUserEntries: FakePiUserEntry[] = [];
+  // The user entries on the current branch that getMessages() replays.
+  contextUserEntries: FakePiUserEntry[] = [];
  abortRequested = false;
  readonly canceledExtensionUiRequests: string[] = [];
  readonly extensionUiResponses: Array<{
@@ -302,8 +302,8 @@ export class FakePiSession implements PiRuntimeSession {
    return this.state;
  }

-  async getHistory() {
-    return { messages: this.messages, userEntries: this.historyUserEntries };
+  async getMessages(): Promise<PiAgentMessage[]> {
+    return this.messages;
  }

  async getAvailableModels(_timeoutMs?: number | null): Promise<PiModel[]> {
@@ -508,6 +508,7 @@ export class FakePiSession implements PiRuntimeSession {
        reason,
        requestId,
        treeEntries: this.treeUserEntries,
+        contextEntries: this.contextUserEntries,
      })}`,
    });
  }
@@ -1,134 +0,0 @@
-import { z } from "zod";
-import { getUserMessageText, type PiCapturedUserMessageEntry } from "./history-mapper.js";
-import type { PiAgentMessage } from "./rpc-types.js";
-
-export interface PiTranscript {
-  messages: PiAgentMessage[];
-  userEntries: PiCapturedUserMessageEntry[];
-}
-
-const text = z.object({ type: z.literal("text"), text: z.string() }).passthrough();
-const image = z
-  .object({ type: z.literal("image"), data: z.string(), mimeType: z.string() })
-  .passthrough();
-const content = z.union([z.string(), z.array(z.union([text, image]))]);
-const message = z.discriminatedUnion("role", [
-  z
-    .object({ role: z.literal("system"), content: z.union([z.string(), z.array(text)]).nullish() })
-    .passthrough(),
-  z.object({ role: z.literal("branchSummary"), summary: z.string() }).passthrough(),
-  z.object({ role: z.literal("compactionSummary"), summary: z.string() }).passthrough(),
-  z.object({ role: z.literal("user"), content }).passthrough(),
-  z
-    .object({
-      role: z.literal("custom"),
-      content,
-      customType: z.string().optional(),
-      display: z.boolean().optional(),
-      details: z.unknown().optional(),
-    })
-    .passthrough(),
-  z
-    .object({
-      role: z.literal("assistant"),
-      content: z.array(
-        z.union([
-          text,
-          z.object({ type: z.literal("thinking"), thinking: z.string() }).passthrough(),
-          z
-            .object({
-              type: z.literal("toolCall"),
-              id: z.string(),
-              name: z.string(),
-              arguments: z.unknown(),
-            })
-            .passthrough(),
-        ]),
-      ),
-    })
-    .passthrough(),
-  z
-    .object({
-      role: z.literal("toolResult"),
-      toolCallId: z.string(),
-      toolName: z.string(),
-      content: z.unknown(),
-      isError: z.boolean().optional(),
-      details: z.unknown().optional(),
-    })
-    .passthrough(),
-  z
-    .object({
-      role: z.literal("bashExecution"),
-      command: z.string(),
-      output: z.string().optional(),
-      exitCode: z.number().nullable().optional(),
-      cancelled: z.boolean().optional(),
-      timestamp: z.number(),
-    })
-    .passthrough(),
-]);
-const record = z
-  .object({
-    type: z.string(),
-    id: z.string().optional(),
-    parentId: z.string().nullable().optional(),
-    message: z.unknown().optional(),
-  })
-  .passthrough();
-
-/** Select the persisted active ancestry, retaining structural links across compaction. */
-export function readPiTranscript(contents: string): PiTranscript {
-  const records = contents
-    .split("\n")
-    .filter((line) => line.trim())
-    .map((line) => record.parse(JSON.parse(line)));
-  const header = records.shift();
-  if (header?.type !== "session") throw new Error("Pi transcript is missing its session header");
-  const legacy = header.version === 1;
-  const branch = legacy ? records : activeBranch(records);
-  const result: PiTranscript = { messages: [], userEntries: [] };
-  for (const entry of branch) {
-    if (entry.type !== "message" && entry.type !== "custom_message") continue;
-    const parsed = message.parse(
-      entry.type === "custom_message" ? { ...entry, role: "custom" } : entry.message,
-    );
-    // These native context messages had no display mapping in get_messages replay.
-    if (
-      parsed.role === "system" ||
-      parsed.role === "branchSummary" ||
-      parsed.role === "compactionSummary"
-    )
-      continue;
-    result.messages.push(parsed);
-    if (parsed.role === "user" && entry.id)
-      result.userEntries.push({
-        id: entry.id,
-        text: getUserMessageText(parsed.content),
-      });
-  }
-  return result;
-}
-
-function activeBranch(records: z.infer<typeof record>[]): z.infer<typeof record>[] {
-  const byId = new Map<string, (typeof records)[number]>();
-  for (const entry of records) {
-    if (!entry.id || entry.parentId === undefined || byId.has(entry.id))
-      throw new Error("Invalid Pi transcript tree entry");
-    byId.set(entry.id, entry);
-  }
-  const branch: z.infer<typeof record>[] = [];
-  const seen = new Set<string>();
-  let entry = records.at(-1);
-  while (entry) {
-    const id = entry.id!;
-    if (seen.has(id)) throw new Error("Cycle in Pi transcript ancestry");
-    seen.add(id);
-    branch.push(entry);
-    if (entry.parentId === null) break;
-    entry = byId.get(entry.parentId!);
-    if (!entry) throw new Error("Missing Pi transcript ancestor");
-  }
-  branch.reverse();
-  return branch;
-}
@@ -142,6 +142,7 @@ const INBOUND_PERMISSION = {
  "plugin.reload.request": "daemon.manage",
  "plugin.remove.request": "daemon.manage",
  "plugin.rpc.invoke.request": "daemon.manage",
+  "plugin.rpc.subscribe.request": "daemon.manage",
  "plugin.source.install.request": "daemon.manage",
  "plugin.source.status.request": "daemon.manage",
  "plugin.source.update.request": "daemon.manage",
@@ -378,6 +379,9 @@ const OUTBOUND_PERMISSION = {
  "plugin.reload.response": "daemon.manage",
  "plugin.remove.response": "daemon.manage",
  "plugin.rpc.invoke.response": "daemon.manage",
+  "plugin.rpc.subscribe.response": "daemon.manage",
+  "plugin.rpc.event": "daemon.manage",
+  "plugin.rpc.closed": "daemon.manage",
  "plugin.source.install.response": "daemon.manage",
  "plugin.source.status.response": "daemon.manage",
  "plugin.source.update.response": "daemon.manage",
@@ -1,7 +1,5 @@
 import { mkdtempSync, rmSync } from "node:fs";
-import { readdir, mkdir, mkdtemp, writeFile, readFile, rm } from "node:fs/promises";
-import { randomUUID } from "node:crypto";
-import { PiRpcAgentClient } from "../agent/providers/pi/agent.js";
+import { readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import pino from "pino";
@@ -368,213 +366,3 @@ describe("daemon E2E (real pi) - rewind", () => {
    }
  }, 900_000);
 });
-
-test("seeded compacted Pi history survives daemon reload, native rewind and Fork chat", async (context) => {
-  if (!(await canRunRealProvider("pi"))) {
-    context.skip();
-    return;
-  }
-  const artifacts = path.resolve(".artifacts/pi-timeline");
-  await mkdir(artifacts, { recursive: true });
-  const root = await mkdtemp(path.join(artifacts, "daemon-history-"));
-  const cwd = path.join(root, "cwd");
-  await mkdir(cwd);
-  const file = path.join(root, "session.jsonl");
-  const nativeId = randomUUID();
-  const timestamp = new Date().toISOString();
-  const assistant = (text: string) => ({
-    role: "assistant",
-    content: [{ type: "text", text }],
-    api: "openai-completions",
-    provider: "openrouter",
-    model: "google/gemini-2.5-flash-lite",
-    stopReason: "stop",
-    timestamp: Date.now(),
-    usage: {
-      input: 1,
-      output: 1,
-      cacheRead: 0,
-      cacheWrite: 0,
-      totalTokens: 2,
-      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-    },
-  });
-  const records = [
-    { type: "session", version: 3, id: nativeId, cwd, timestamp },
-    {
-      type: "message",
-      id: "system",
-      parentId: null,
-      timestamp,
-      message: {
-        role: "system",
-        content: [{ type: "text", text: "private system context" }],
-        timestamp: Date.now(),
-      },
-    },
-    {
-      type: "message",
-      id: "u1",
-      parentId: "system",
-      timestamp,
-      message: { role: "user", content: "old question", timestamp: Date.now() },
-    },
-    {
-      type: "message",
-      id: "tool-request",
-      parentId: "u1",
-      timestamp,
-      message: {
-        ...assistant(""),
-        content: [
-          { type: "toolCall", id: "read-call", name: "read", arguments: { path: "readme.txt" } },
-        ],
-      },
-    },
-    {
-      type: "message",
-      id: "tool-result",
-      parentId: "tool-request",
-      timestamp,
-      message: {
-        role: "toolResult",
-        toolCallId: "read-call",
-        toolName: "read",
-        content: [{ type: "text", text: "saved tool output" }],
-        isError: false,
-        timestamp: Date.now(),
-      },
-    },
-    {
-      type: "message",
-      id: "a1",
-      parentId: "tool-result",
-      timestamp,
-      message: assistant("old answer"),
-    },
-    {
-      type: "message",
-      id: "abandoned",
-      parentId: "a1",
-      timestamp,
-      message: { role: "user", content: "abandoned question", timestamp: Date.now() },
-    },
-    {
-      type: "compaction",
-      id: "compact",
-      parentId: "a1",
-      timestamp,
-      summary: "old summary",
-      firstKeptEntryId: null,
-      tokensBefore: 50000,
-    },
-    {
-      type: "message",
-      id: "u2",
-      parentId: "compact",
-      timestamp,
-      message: { role: "user", content: "follow up", timestamp: Date.now() },
-    },
-    { type: "message", id: "a2", parentId: "u2", timestamp, message: assistant("new answer") },
-  ];
-  await writeFile(file, records.map((record) => JSON.stringify(record)).join("\n") + "\n");
-  const logger = pino({ level: "silent" });
-  const daemon = await createTestPaseoDaemon({
-    agentClients: { pi: new PiRpcAgentClient({ logger }) },
-    logger,
-    paseoHomeRoot: path.join(root, "home"),
-  });
-  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
-  try {
-    await client.connect();
-    await client.fetchAgents({ subscribe: {} });
-    const imported = await client.importAgent({ provider: "pi", sessionId: file, cwd });
-    const session = { agentId: imported.id, cwd };
-    const expected = { userTexts: ["old question", "follow up"], assistantCount: 2 };
-    expectTimeline(await fetchTimelineItems(client, imported.id), expected);
-    expect(
-      userMessageIdForToken(await fetchTimelineItems(client, imported.id), "old question"),
-    ).toBe("u1");
-    expect(userMessageIdForToken(await fetchTimelineItems(client, imported.id), "follow up")).toBe(
-      "u2",
-    );
-    expect(await runtimeSessionId({ client, daemon }, session)).toBe(nativeId);
-    await client.refreshAgent(imported.id);
-    const restored = await fetchTimelineItems(client, imported.id);
-    expectTimeline(restored, expected);
-    const tools = restored.filter((item) => item.type === "tool_call");
-    expect(tools).toHaveLength(1);
-    expect(tools[0].detail).toEqual({
-      type: "read",
-      filePath: "readme.txt",
-      content: "saved tool output",
-    });
-    expect(
-      restored.filter((item) => item.type === "user_message").map((item) => item.messageId),
-    ).toEqual(["u1", "u2"]);
-    const oldAnswer = restored.find(
-      (item) => item.type === "assistant_message" && item.text === "old answer",
-    );
-    if (oldAnswer?.type !== "assistant_message" || !oldAnswer.messageId)
-      throw new Error("Restored reply missing identity");
-    const beforeFork = await readFile(file, "utf8");
-    const fork = await client.buildAgentForkContext(imported.id, {
-      boundaryMessageId: oldAnswer.messageId,
-    });
-    expect(fork.attachment?.text).toContain("old question");
-    expect(fork.attachment?.text).toContain("old answer");
-    expect(fork.attachment?.text).not.toContain("follow up");
-    expect(fork.attachment?.text).not.toContain("abandoned question");
-    expect(await readFile(file, "utf8")).toBe(beforeFork);
-    const forkFile = path.join(root, "native-fork.jsonl");
-    const forkId = randomUUID();
-    await writeFile(
-      forkFile,
-      [
-        { ...records[0], id: forkId },
-        ...records.slice(1),
-        {
-          type: "custom",
-          id: "fork-leaf",
-          parentId: "a1",
-          timestamp,
-          customType: "paseo_rewind",
-          data: { targetId: "a1" },
-        },
-      ]
-        .map((record) => JSON.stringify(record))
-        .join("\n") + "\n",
-    );
-    const importedFork = await client.importAgent({ provider: "pi", sessionId: forkFile, cwd });
-    expectTimeline(await fetchTimelineItems(client, importedFork.id), {
-      userTexts: ["old question"],
-      assistantCount: 1,
-    });
-    expect(await runtimeSessionId({ client, daemon }, { agentId: importedFork.id, cwd })).toBe(
-      forkId,
-    );
-    expect(await readFile(file, "utf8")).toBe(beforeFork);
-    await client.rewindAgent(imported.id, "u2", "conversation");
-    expectTimeline(await fetchTimelineItems(client, imported.id), {
-      userTexts: ["old question"],
-      assistantCount: 1,
-    });
-    await client.refreshAgent(imported.id);
-    expectTimeline(await fetchTimelineItems(client, imported.id), {
-      userTexts: ["old question"],
-      assistantCount: 1,
-    });
-    expect(await runtimeSessionId({ client, daemon }, session)).toBe(nativeId);
-    await client.rewindAgent(imported.id, "u1", "conversation");
-    await client.refreshAgent(imported.id);
-    expectTimeline(await fetchTimelineItems(client, imported.id), {
-      userTexts: [],
-      assistantCount: 0,
-    });
-    expect(await runtimeSessionId({ client, daemon }, session)).toBe(nativeId);
-  } finally {
-    await client.close();
-    await daemon.close();
-    await rm(root, { recursive: true, force: true });
-  }
-}, 120_000);
@@ -34,7 +34,13 @@ const emptyUsageRuntime = {
  getUsageSourceRegistrations: () => [],
  fetchUsage: async () => undefined,
  discoverUsage: async () => [],
-} satisfies Pick<TestPluginRuntime, "getUsageSourceRegistrations" | "fetchUsage" | "discoverUsage">;
+  startSubscription: () => {
+    throw new Error("No subscriptions in this test");
+  },
+} satisfies Pick<
+  TestPluginRuntime,
+  "getUsageSourceRegistrations" | "fetchUsage" | "discoverUsage" | "startSubscription"
+>;

 async function createPlugin(id: string, source: string): Promise<string> {
  const directory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-service-"));
@@ -25,6 +25,7 @@ import { readPluginManifest } from "./manifest.js";
 import { expandTilde } from "../../utils/path.js";
 import { runPluginBuild } from "./preparation.js";
 import { PluginRuntime } from "./runtime.js";
+import type { PluginRuntimeSubscription } from "./runtime-subscription.js";
 import { BuiltinPluginLoader, type BuiltinPlugin } from "./builtin/index.js";
 import type { PluginProviderMetadata } from "./plugin-process-protocol.js";
 import { readPluginProviderIcon } from "./provider-icon.js";
@@ -48,6 +49,7 @@ interface PluginRuntimePort {
  wait?: PluginLifecycle["wait"];
  catalog: PluginRuntime["catalog"];
  invoke(pluginId: string, method: string, input: unknown): Promise<unknown>;
+  startSubscription: PluginRuntime["startSubscription"];
  getLogs(pluginId: string): PluginLogEntry[];
  clearLogs(pluginId: string): void;
  getProviderRegistrations?(pluginId: string): readonly PluginProviderMetadata[];
@@ -539,6 +541,10 @@ export class PluginService {
    return this.runtime.invoke(pluginId, method, input);
  }

+  subscribePluginRpc(pluginId: string, method: string, input: unknown): PluginRuntimeSubscription {
+    return this.runtime.startSubscription(pluginId, method, input);
+  }
+
  async stopAllPlugins(): Promise<void> {
    this.globalStartsBlocked = true;
    const stopping = this.stopAll();
@@ -60,6 +60,14 @@ export type PluginProcessRequest =
  | { type: "usage.fetch"; requestId: string; sourceId: string; input: unknown }
  | { type: "usage.discover"; requestId: string; sourceId: string; scope: UsageScope }
  | { type: "invoke"; requestId: string; method: string; input: unknown }
+  | {
+      type: "subscribe";
+      requestId: string;
+      subscriptionId: string;
+      method: string;
+      input: unknown;
+    }
+  | { type: "unsubscribe"; subscriptionId: string }
  | {
      type: "provider.connect";
      providerId: string;
@@ -83,6 +91,7 @@ export type PluginProcessMessage =
  | {
      type: "ready";
      methods: string[];
+      subscriptions?: string[];
      providers: PluginProviderMetadata[];
      usageSources?: PluginUsageSourceMetadata[];
      hooks?: string[];
@@ -90,6 +99,8 @@ export type PluginProcessMessage =
  | { type: "result"; requestId: string; output: unknown }
  | { type: "error"; requestId: string; error: string }
  | { type: "fatal"; error: string }
+  | { type: "subscription.event"; subscriptionId: string; event: unknown }
+  | { type: "subscription.closed"; subscriptionId: string; error?: string }
  | {
      type: "provider.connected";
      connectionId: string;
@@ -240,6 +251,16 @@ export const PluginProcessRequestSchema: z.ZodType<PluginProcessRequest> = z.dis
        input: z.unknown(),
      })
      .strict(),
+    z
+      .object({
+        type: z.literal("subscribe"),
+        requestId: z.string().min(1),
+        subscriptionId: z.string().min(1),
+        method: z.string().min(1),
+        input: z.unknown(),
+      })
+      .strict(),
+    z.object({ type: z.literal("unsubscribe"), subscriptionId: z.string().min(1) }).strict(),
    z
      .object({
        type: z.literal("provider.connect"),
@@ -272,6 +293,7 @@ export const PluginProcessMessageSchema: z.ZodType<PluginProcessMessage> = z.dis
      .object({
        type: z.literal("ready"),
        methods: z.array(z.string()),
+        subscriptions: z.array(z.string()).optional(),
        providers: z.array(providerMetadataSchema),
        usageSources: z.array(usageSourceMetadataSchema).optional(),
        hooks: hooksSchema.optional(),
@@ -284,6 +306,20 @@ export const PluginProcessMessageSchema: z.ZodType<PluginProcessMessage> = z.dis
      .object({ type: z.literal("error"), requestId: z.string().min(1), error: z.string() })
      .strict(),
    z.object({ type: z.literal("fatal"), error: z.string() }).strict(),
+    z
+      .object({
+        type: z.literal("subscription.event"),
+        subscriptionId: z.string().min(1),
+        event: z.unknown(),
+      })
+      .strict(),
+    z
+      .object({
+        type: z.literal("subscription.closed"),
+        subscriptionId: z.string().min(1),
+        error: z.string().optional(),
+      })
+      .strict(),
    z
      .object({
        type: z.literal("provider.connected"),
@@ -7,8 +7,21 @@ import {
  type PluginProcessRequest,
 } from "./plugin-process-protocol.js";
 import type { UsageSourceRegistration } from "@getpaseo/plugin/server/usage";
-import type { SettingsDefinition, PluginRpcContract } from "@getpaseo/plugin";
-import type { PluginHandlerContext, PluginServerContribution } from "@getpaseo/plugin/server";
+import type {
+  SettingsDefinition,
+  PluginRpcContract,
+  PluginSubscriptionContract,
+} from "@getpaseo/plugin";
+import type {
+  PluginHandlerContext,
+  PluginServerContext,
+  PluginServerContribution,
+} from "@getpaseo/plugin/server";
+import { assertPluginWireValue } from "@getpaseo/protocol/binary-frames/index";
+import {
+  PluginSubscriptionHandlers,
+  type PluginSubscriptionHandler,
+} from "./subscription-handlers.js";
 import { fileURLToPath } from "node:url";
 import type { ZodType } from "zod";
 import {
@@ -66,6 +79,7 @@ export function createPluginWorker(options: {
    send({ type: "hooks.changed", hooks: hooks.catalog() });
  }, agentTools);
  const handlers = new Map<string, RegisteredRpc>();
+  const subscriptions = new PluginSubscriptionHandlers({ send, sendAndWait });
  const providers = new Map<string, ProviderRegistration>();
  const usageSources = new Map<string, UsageSourceRegistration>();
  const providerConnections = new Map<
@@ -98,12 +112,36 @@ export function createPluginWorker(options: {
    if (!/^[a-z][a-z0-9._-]*$/.test(normalized)) {
      throw new Error(`Invalid plugin RPC method: ${method}`);
    }
-    if (handlers.has(normalized)) {
+    if (handlers.has(normalized) || subscriptions.has(normalized)) {
      throw new Error(`Duplicate plugin RPC method: ${normalized}`);
    }
    return normalized;
  }

+  function registerSubscription(
+    contract: PluginSubscriptionContract,
+    handler: PluginSubscriptionHandler,
+  ): void {
+    if (typeof handler !== "function") {
+      throw new Error(`Plugin subscription ${contract.name} must provide a handler`);
+    }
+    const method = validateMethod(contract.name);
+    subscriptions.register({ ...contract, name: method }, handler);
+  }
+
+  // One name serves either an RPC or a subscription; the contract says which.
+  const handle = ((
+    contract: PluginRpcContract | PluginSubscriptionContract,
+    handler: (input: unknown, context: never) => unknown,
+  ) => {
+    if ("event" in contract) {
+      // The subscription handlers parse the input once and pass the result here.
+      registerSubscription(contract, handler as PluginSubscriptionHandler);
+      return;
+    }
+    register(contract, (input, context) => handler(input, context as never));
+  }) as PluginServerContext["handle"];
+
  function register(contract: PluginRpcContract, handler: RpcHandler): void {
    if (typeof handler !== "function") {
      throw new Error(`Plugin RPC ${contract.name} must provide a handler`);
@@ -284,8 +322,7 @@ export function createPluginWorker(options: {
        )
      : null;
    const contributedCleanup = contribute({
-      handle: (contract, handler) =>
-        register(contract, (input, context) => handler(contract.input.parse(input), context)),
+      handle,
      registerProvider,
      registerUsageSource,
      registerSettings,
@@ -311,6 +348,7 @@ export function createPluginWorker(options: {
    send({
      type: "ready",
      methods: [...handlers.keys()].sort(),
+      subscriptions: subscriptions.catalog(),
      hooks: hooks.catalog(),
      providers: [...providers.values()]
        .sort((left, right) => left.id.localeCompare(right.id))
@@ -327,6 +365,7 @@ export function createPluginWorker(options: {
      .catch((error) => console.error("Plugin API cleanup failed", error));
    hooks.close();
    agentTools.close();
+    subscriptions.releaseAll();
    for (const pending of pendingProviderConnections.values()) pending.tombstoned = true;
    const currentCleanup = cleanup;
    cleanup = null;
@@ -365,7 +404,8 @@ export function createPluginWorker(options: {
      message.type === "provider.status" ||
      message.type === "provider.catalog_key" ||
      message.type === "usage.fetch" ||
-      message.type === "usage.discover"
+      message.type === "usage.discover" ||
+      message.type === "subscribe"
    ) {
      send({ type: "error", requestId: message.requestId, error: "Plugin is stopping" });
    } else if (message.type === "provider.connect") {
@@ -422,6 +462,14 @@ export function createPluginWorker(options: {
    return false;
  }

+  function handleSubscriptionMessage(
+    message: Extract<PluginProcessRequest, { type: "subscribe" | "unsubscribe" }>,
+  ): void {
+    if (message.type === "unsubscribe") subscriptions.release(message.subscriptionId);
+    else if (paseo) subscriptions.start(message, paseo);
+    else send({ type: "error", requestId: message.requestId, error: "Plugin API unavailable" });
+  }
+
  function handleMessage(rawMessage: unknown): void {
    const parsed = PluginProcessRequestSchema.safeParse(rawMessage);
    if (!parsed.success) {
@@ -525,6 +573,11 @@ export function createPluginWorker(options: {
      handleHookMessage(message);
      return;
    }
+    if (message.type === "invoke") invoke(message);
+    else handleSubscriptionMessage(message);
+  }
+
+  function invoke(message: Extract<PluginProcessRequest, { type: "invoke" }>): void {
    const registered = handlers.get(message.method);
    if (!registered) {
      send({
@@ -540,7 +593,10 @@ export function createPluginWorker(options: {
        if (!paseo) throw new Error("Plugin Paseo API is unavailable");
        return registered.handler(input, { paseo });
      })
-      .then((output) => registered.contract.output.parseAsync(output))
+      .then((output: unknown) => {
+        assertPluginWireValue(output, "output");
+        return output;
+      })
      .then(
        (output) => send({ type: "result", requestId: message.requestId, output }),
        (error) =>
@@ -0,0 +1,428 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { WebSocket } from "ws";
+import {
+  DaemonClient,
+  type OwnedSubscription,
+  type WebSocketLike,
+} from "@getpaseo/client/internal/daemon-client";
+import { afterEach, expect, test } from "vitest";
+import { defineRpc } from "@getpaseo/plugin";
+import { callPluginRpc } from "@getpaseo/plugin/client/host";
+import { z } from "zod";
+import { resolveDaemonVersion } from "../daemon-version.js";
+import { createTestPaseoDaemon, type TestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+
+const PLUGIN_ID = "subscriptions";
+
+// Written as an author writes a plugin: one contract per name, handlers that read like English.
+const SERVER_ENTRY = `
+import { defineRpc, defineSubscription } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+
+const ticks = defineSubscription({
+  name: "ticks",
+  input: z.object({ count: z.number().int(), bytes: z.boolean() }),
+  event: z.union([z.instanceof(Uint8Array), z.object({ n: z.number() })]),
+});
+const failing = defineSubscription({
+  name: "failing",
+  input: z.object({ when: z.enum(["before-ack", "after-ack"]) }),
+  event: z.object({}),
+});
+const nestedPush = defineSubscription({
+  name: "nested-push",
+  input: z.object({}),
+  event: z.object({ data: z.instanceof(Uint8Array) }),
+});
+const repeated = defineSubscription({
+  name: "repeated",
+  input: z.object({ times: z.string().transform(Number) }),
+  event: z.string().transform((text) => text.length),
+});
+const transformed = defineRpc({
+  name: "transformed",
+  input: z.object({ when: z.string().transform(async (text) => new Date(text)) }),
+  output: z.object({ n: z.string().transform(async (text) => Number(text)) }),
+});
+const defaulted = defineRpc({ name: "defaulted", input: z.string().default("x"), output: z.string() });
+const defaultedOutput = defineRpc({ name: "defaulted-output", input: z.object({}), output: z.string().default("x") });
+const watchers = defineRpc({
+  name: "watchers",
+  input: z.object({}),
+  output: z.object({ starts: z.number(), active: z.number() }),
+});
+const thumbnail = defineRpc({
+  name: "thumbnail",
+  input: z.object({ size: z.number().int() }),
+  output: z.instanceof(Uint8Array),
+});
+const nestedOutput = defineRpc({
+  name: "nested-output",
+  input: z.object({}),
+  output: z.object({ data: z.instanceof(Uint8Array) }),
+});
+const reverse = defineRpc({
+  name: "reverse",
+  input: z.instanceof(Uint8Array),
+  output: z.instanceof(Uint8Array),
+});
+
+export default function contribute(server: PluginServerContext) {
+  let starts = 0;
+  let active = 0;
+  server.handle(ticks, ({ count, bytes }, { push, signal }) => {
+    starts += 1;
+    active += 1;
+    signal.addEventListener("abort", () => { active -= 1; }, { once: true });
+    for (let n = 0; n < count; n += 1) void push(bytes ? new Uint8Array([n, n + 1]) : { n });
+  });
+  server.handle(failing, ({ when }) => {
+    if (when === "before-ack") throw new Error("refused before acknowledging");
+    return Promise.reject(new Error("failed after acknowledging"));
+  });
+  server.handle(nestedPush, (_input, { push }) => {
+    void push({ data: new Uint8Array(1) }).catch((error) => {
+      console.error("nested push", error.message);
+    });
+  });
+  server.handle(repeated, async ({ times }, { push }) => {
+    await push(typeof times === "number" ? "x".repeat(times) : "input arrived untransformed");
+  });
+  server.handle(transformed, ({ when }) => ({ n: String(when.getUTCFullYear()) }));
+  server.handle(defaulted, (input) => input);
+  server.handle(defaultedOutput, () => undefined);
+  server.handle(watchers, () => ({ starts, active }));
+  server.handle(thumbnail, ({ size }) => Buffer.alloc(size, 7));
+  server.handle(nestedOutput, () => ({ data: new Uint8Array(1) }));
+  server.handle(reverse, (bytes) => Uint8Array.from(bytes).reverse());
+  return () => undefined;
+}
+`;
+
+type Received =
+  | { type: "event"; event: unknown }
+  | { type: "bytes"; bytes: number[] }
+  | { type: "closed"; error?: string };
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+interface Harness {
+  daemon: TestPaseoDaemon;
+  client: DaemonClient;
+  sockets: WebSocket[];
+  close(): Promise<void>;
+}
+
+async function writePlugin(id: string, serverEntry: string): Promise<string> {
+  const pluginDirectory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-subscriptions-"));
+  roots.push(pluginDirectory);
+  await writeFile(
+    path.join(pluginDirectory, "paseo-plugin.json"),
+    JSON.stringify({ id, requirements: { paseo: `>=${resolveDaemonVersion(import.meta.url)}` } }),
+  );
+  await writeFile(path.join(pluginDirectory, "index.server.ts"), serverEntry);
+  return pluginDirectory;
+}
+
+async function startHarness(): Promise<Harness> {
+  const pluginDirectory = await writePlugin(PLUGIN_ID, SERVER_ENTRY);
+  const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
+  const sockets: WebSocket[] = [];
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    clientId: `clid_plugin_subscriptions_${Date.now()}`,
+    appVersion: resolveDaemonVersion(import.meta.url),
+    reconnect: { enabled: true, baseDelayMs: 10, maxDelayMs: 50 },
+    webSocketFactory: (url) => {
+      const socket = new WebSocket(url);
+      sockets.push(socket);
+      return socket as unknown as WebSocketLike;
+    },
+  });
+  await client.connect();
+  await client.patchDaemonConfig({ pluginsEnabled: true });
+  await expect(client.installDirectoryPlugin(pluginDirectory)).resolves.toMatchObject({
+    id: PLUGIN_ID,
+    status: "running",
+  });
+  return {
+    daemon,
+    client,
+    sockets,
+    async close() {
+      await client.close().catch(() => undefined);
+      await daemon.close();
+    },
+  };
+}
+
+function collect(subscription: OwnedSubscription<unknown>): Received[] {
+  const received: Received[] = [];
+  subscription.subscribe({
+    snapshot: () => undefined,
+    update: (message) => {
+      if (message.type === "plugin.rpc.event")
+        received.push({ type: "event", event: message.payload.event });
+      if (message.type === "plugin.rpc.closed")
+        received.push({
+          type: "closed",
+          ...(message.payload.error ? { error: message.payload.error } : {}),
+        });
+    },
+    binary: (payload) => received.push({ type: "bytes", bytes: [...payload] }),
+  });
+  return received;
+}
+
+function watcherCount(client: DaemonClient) {
+  return client.invokePluginRpc(PLUGIN_ID, "watchers", {});
+}
+
+test("a subscription delivers JSON and binary events in order and release aborts its handler", async () => {
+  const harness = await startHarness();
+  const { client } = harness;
+  try {
+    const json = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 3, bytes: false });
+    const jsonEvents = collect(json);
+    await json.ready;
+    const binary = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 2, bytes: true });
+    const binaryEvents = collect(binary);
+    await binary.ready;
+
+    await expect
+      .poll(() => jsonEvents)
+      .toEqual([
+        { type: "event", event: { n: 0 } },
+        { type: "event", event: { n: 1 } },
+        { type: "event", event: { n: 2 } },
+      ]);
+    await expect
+      .poll(() => binaryEvents)
+      .toEqual([
+        { type: "bytes", bytes: [0, 1] },
+        { type: "bytes", bytes: [1, 2] },
+      ]);
+    expect(json.subscriptionId).not.toBe(binary.subscriptionId);
+    await expect(watcherCount(client)).resolves.toEqual({ starts: 2, active: 2 });
+
+    await json.release();
+    await expect(watcherCount(client)).resolves.toEqual({ starts: 2, active: 1 });
+    await binary.release();
+    await expect(watcherCount(client)).resolves.toEqual({ starts: 2, active: 0 });
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("a schema transform runs once: the handler gets the parsed input and the wire carries the pushed event", async () => {
+  const harness = await startHarness();
+  try {
+    const subscription = harness.client.observePluginRpc(PLUGIN_ID, "repeated", { times: "2" });
+    const received = collect(subscription);
+    await subscription.ready;
+    // The client parses "xx" into 2; parsing it on the plugin side too would reject it.
+    await expect.poll(() => received).toEqual([{ type: "event", event: "xx" }, { type: "closed" }]);
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("dropping the connection releases subscriptions and reconnecting runs the handler again", async () => {
+  const harness = await startHarness();
+  const { client, sockets } = harness;
+  try {
+    const subscription = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 1, bytes: false });
+    const events = collect(subscription);
+    await subscription.ready;
+    await expect.poll(() => events).toEqual([{ type: "event", event: { n: 0 } }]);
+    const firstId = subscription.subscriptionId;
+
+    sockets.at(-1)!.terminate();
+    await expect
+      .poll(() => subscription.subscriptionId, { timeout: 10_000 })
+      .toSatisfy((id: unknown) => typeof id === "string" && id !== firstId);
+    await expect
+      .poll(() => events)
+      .toEqual([
+        { type: "event", event: { n: 0 } },
+        { type: "event", event: { n: 0 } },
+      ]);
+    // The first handler's signal aborted when its connection dropped; one handler runs now.
+    await expect(watcherCount(client)).resolves.toEqual({ starts: 2, active: 1 });
+    await subscription.release();
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("a handler that throws before acknowledging rejects; one that fails later closes", async () => {
+  const harness = await startHarness();
+  const { client } = harness;
+  try {
+    const refused = client.observePluginRpc(PLUGIN_ID, "failing", { when: "before-ack" });
+    await expect(refused.ready).rejects.toThrow("refused before acknowledging");
+
+    const later = client.observePluginRpc(PLUGIN_ID, "failing", { when: "after-ack" });
+    const events = collect(later);
+    await later.ready;
+    await expect
+      .poll(() => events)
+      .toEqual([{ type: "closed", error: "failed after acknowledging" }]);
+    await later.release();
+
+    const invalid = client.observePluginRpc(PLUGIN_ID, "ticks", { count: "many" });
+    await expect(invalid.ready).rejects.toThrow();
+    const unknown = client.observePluginRpc(PLUGIN_ID, "watchers", {});
+    await expect(unknown.ready).rejects.toThrow("does not contribute subscription watchers");
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("reloading the plugin closes its subscriptions with an error", async () => {
+  const harness = await startHarness();
+  const { client } = harness;
+  try {
+    const subscription = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 0, bytes: false });
+    const events = collect(subscription);
+    await subscription.ready;
+    await client.reloadPlugin(PLUGIN_ID);
+    await expect
+      .poll(() => events)
+      .toEqual([{ type: "closed", error: `Plugin stopped: ${PLUGIN_ID}` }]);
+    await subscription.release();
+    // The reloaded plugin starts fresh and serves new subscriptions.
+    const again = client.observePluginRpc(PLUGIN_ID, "ticks", { count: 1, bytes: false });
+    const againEvents = collect(again);
+    await again.ready;
+    await expect.poll(() => againEvents).toEqual([{ type: "event", event: { n: 0 } }]);
+    await again.release();
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("RPC bytes ride as binary frames in both directions and nested bytes fail validation", async () => {
+  const harness = await startHarness();
+  const { client } = harness;
+  try {
+    const output = await client.invokePluginRpc(PLUGIN_ID, "thumbnail", { size: 4 });
+    expect(output).toBeInstanceOf(Uint8Array);
+    expect([...(output as Uint8Array)]).toEqual([7, 7, 7, 7]);
+
+    const reversed = await client.invokePluginRpc(PLUGIN_ID, "reverse", new Uint8Array([1, 2, 3]));
+    expect([...(reversed as Uint8Array)]).toEqual([3, 2, 1]);
+
+    await expect(client.invokePluginRpc(PLUGIN_ID, "nested-output", {})).rejects.toThrow(
+      "output.data is a Uint8Array. Bytes cross the wire only as the whole value",
+    );
+    await expect(
+      client.invokePluginRpc(PLUGIN_ID, "reverse", { data: new Uint8Array(1) }),
+    ).rejects.toThrow("input.data is a Uint8Array");
+
+    const nested = client.observePluginRpc(PLUGIN_ID, "nested-push", {});
+    await nested.ready;
+    await expect
+      .poll(async () => JSON.stringify(await client.getPluginLogs(PLUGIN_ID)))
+      .toContain("event.data is a Uint8Array");
+    await nested.release();
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("one name cannot serve both an RPC and a subscription", async () => {
+  const harness = await startHarness();
+  try {
+    const directory = await writePlugin(
+      "collision",
+      `
+import { defineRpc, defineSubscription } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(defineRpc({ name: "watch", input: z.object({}), output: z.null() }), () => null);
+  server.handle(
+    defineSubscription({ name: "watch", input: z.object({}), event: z.object({}) }),
+    () => undefined,
+  );
+  return () => undefined;
+}
+`,
+    );
+    await expect(harness.client.installDirectoryPlugin(directory)).rejects.toThrow(
+      "Duplicate plugin RPC method: watch",
+    );
+  } finally {
+    await harness.close();
+  }
+}, 60_000);
+
+test("plain RPC parses async input and output transforms once at the receiver", async () => {
+  const transformed = defineRpc({
+    name: "transformed",
+    input: z.object({ when: z.string().transform(async (text) => new Date(text)) }),
+    output: z.object({ n: z.string().transform(async (text) => Number(text)) }),
+  });
+
+  const harness = await startHarness();
+  try {
+    await expect(
+      callPluginRpc(
+        transformed,
+        (method, input) => harness.client.invokePluginRpc(PLUGIN_ID, method, input),
+        { when: "2026-01-01T00:00:00.000Z" },
+      ),
+    ).resolves.toEqual({ n: 2026 });
+  } finally {
+    await harness.close();
+  }
+});
+
+test("plain RPC applies a top-level input default in the plugin process", async () => {
+  const contract = defineRpc({
+    name: "defaulted",
+    input: z.string().default("x"),
+    output: z.string(),
+  });
+  const harness = await startHarness();
+  try {
+    await expect(
+      callPluginRpc(
+        contract,
+        (method, input) => harness.client.invokePluginRpc(PLUGIN_ID, method, input),
+        undefined,
+      ),
+    ).resolves.toBe("x");
+  } finally {
+    await harness.close();
+  }
+});
+
+test("plain RPC applies a top-level output default on the client", async () => {
+  const contract = defineRpc({
+    name: "defaulted-output",
+    input: z.object({}),
+    output: z.string().default("x"),
+  });
+  const harness = await startHarness();
+  try {
+    await expect(
+      callPluginRpc(
+        contract,
+        (method, input) => harness.client.invokePluginRpc(PLUGIN_ID, method, input),
+        {},
+      ),
+    ).resolves.toBe("x");
+  } finally {
+    await harness.close();
+  }
+}, 30_000);
@@ -0,0 +1,108 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { DaemonClient } from "@getpaseo/client/internal/daemon-client";
+import { afterEach, expect, test } from "vitest";
+import { resolveDaemonVersion } from "../daemon-version.js";
+import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+
+const PUSH_BYTES = 256 * 1024;
+const TOTAL_BYTES = 100 * 1024 * 1024;
+const PUSHES = TOTAL_BYTES / PUSH_BYTES;
+const MIN_MEGABYTES_PER_SECOND = 200;
+
+// One buffer, pushed until the total is out: what a capture loop looks like.
+const SERVER_ENTRY = `
+import { defineSubscription } from "@getpaseo/plugin";
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { z } from "zod";
+
+const stream = defineSubscription({
+  name: "stream",
+  input: z.object({ pushes: z.number().int(), bytes: z.number().int() }),
+  event: z.instanceof(Uint8Array),
+});
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(stream, async ({ pushes, bytes }, { push, signal }) => {
+    const chunk = new Uint8Array(bytes).fill(7);
+    for (let sent = 0; sent < pushes && !signal.aborted; sent += 1) await push(chunk);
+    await new Promise((resolve) => signal.addEventListener("abort", resolve, { once: true }));
+  });
+  return () => undefined;
+}
+`;
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+test(`a plugin streams ${TOTAL_BYTES / 1024 / 1024} MiB in ${PUSH_BYTES / 1024} KiB pushes at ${MIN_MEGABYTES_PER_SECOND} MB/s without copying per frame`, async () => {
+  const pluginDirectory = await mkdtemp(path.join(tmpdir(), "paseo-plugin-stream-"));
+  roots.push(pluginDirectory);
+  await writeFile(
+    path.join(pluginDirectory, "paseo-plugin.json"),
+    JSON.stringify({
+      id: "stream",
+      requirements: { paseo: `>=${resolveDaemonVersion(import.meta.url)}` },
+    }),
+  );
+  await writeFile(path.join(pluginDirectory, "index.server.ts"), SERVER_ENTRY);
+  const daemon = await createTestPaseoDaemon({ mcpEnabled: false });
+  const client = new DaemonClient({
+    url: `ws://127.0.0.1:${daemon.port}/ws`,
+    clientId: `clid_plugin_stream_${Date.now()}`,
+    appVersion: resolveDaemonVersion(import.meta.url),
+  });
+  try {
+    await client.connect();
+    await client.patchDaemonConfig({ pluginsEnabled: true });
+    await client.installDirectoryPlugin(pluginDirectory);
+
+    let received = 0;
+    let frames = 0;
+    let copied = 0;
+    let finished!: () => void;
+    const done = new Promise<void>((resolve) => {
+      finished = resolve;
+    });
+    const baseline = process.memoryUsage().arrayBuffers;
+    let peak = baseline;
+    const started = performance.now();
+    const subscription = client.observePluginRpc("stream", "stream", {
+      pushes: PUSHES,
+      bytes: PUSH_BYTES,
+    });
+    subscription.subscribe({
+      snapshot: () => undefined,
+      update: () => undefined,
+      binary: (payload) => {
+        received += payload.byteLength;
+        frames += 1;
+        // The payload is a view into the frame the socket received, not a copy of it.
+        if (payload.buffer.byteLength - payload.byteLength > 1024) copied += 1;
+        if (frames % 40 === 0) peak = Math.max(peak, process.memoryUsage().arrayBuffers);
+        if (received >= TOTAL_BYTES) finished();
+      },
+    });
+    await done;
+    const seconds = (performance.now() - started) / 1000;
+    const megabytesPerSecond = TOTAL_BYTES / 1e6 / seconds;
+    process.stderr.write(
+      `[plugin stream] ${frames} frames, ${(TOTAL_BYTES / 1e6).toFixed(1)} MB in ${(seconds * 1000).toFixed(0)} ms: ${megabytesPerSecond.toFixed(0)} MB/s, peak external buffers +${((peak - baseline) / 1024 / 1024).toFixed(1)} MiB\n`,
+    );
+
+    expect(frames).toBe(PUSHES);
+    expect(received).toBe(TOTAL_BYTES);
+    expect(copied).toBe(0);
+    expect(megabytesPerSecond).toBeGreaterThanOrEqual(MIN_MEGABYTES_PER_SECOND);
+    // Memory held while streaming stays bounded by in-flight frames, not by the payload total.
+    expect(peak - baseline).toBeLessThan(TOTAL_BYTES / 2);
+    await subscription.release();
+  } finally {
+    await client.close().catch(() => undefined);
+    await daemon.close();
+  }
+}, 120_000);
@@ -0,0 +1,56 @@
+/** Receives a plugin subscription's events once its owner attached. */
+export interface PluginSubscriptionSink {
+  event(event: unknown): void;
+  /** The plugin ended the subscription, or stopped. Not called after `release()`. */
+  closed(error?: string): void;
+}
+
+/** A started plugin subscription, from the daemon's side of the subprocess. */
+export interface PluginRuntimeSubscription {
+  /** Resolves when the plugin acknowledged; rejects when it refused. */
+  readonly ready: Promise<void>;
+  /** Delivers what arrived so far, then everything that follows. */
+  attach(sink: PluginSubscriptionSink): void;
+  release(): void;
+}
+
+type Pending = { type: "event"; event: unknown } | { type: "closed"; error?: string };
+
+/**
+ * Holds events until the owner attaches, so the owner can answer the subscribe request before
+ * the first event goes out.
+ */
+export class BufferedPluginSubscription {
+  private sink: PluginSubscriptionSink | null = null;
+  private pending: Pending[] = [];
+  private ended = false;
+
+  attach(sink: PluginSubscriptionSink): void {
+    if (this.sink) throw new Error("Plugin subscription is already attached");
+    this.sink = sink;
+    const pending = this.pending;
+    this.pending = [];
+    for (const entry of pending) {
+      if (entry.type === "event") sink.event(entry.event);
+      else sink.closed(entry.error);
+    }
+  }
+
+  event(event: unknown): void {
+    if (this.ended) return;
+    if (this.sink) this.sink.event(event);
+    else this.pending.push({ type: "event", event });
+  }
+
+  closed(error?: string): void {
+    if (this.ended) return;
+    this.ended = true;
+    if (this.sink) this.sink.closed(error);
+    else this.pending.push({ type: "closed", ...(error === undefined ? {} : { error }) });
+  }
+
+  released(): void {
+    this.ended = true;
+    this.pending = [];
+  }
+}
@@ -1399,6 +1399,44 @@ export default function contribute(server: { registerProvider(provider: Provider
    }
  });

+  it("releases a subscription in the plugin when its subscribe times out", async () => {
+    vi.useFakeTimers();
+    try {
+      const directory = await createPlugin(
+        "slow-subscribe",
+        `export default function contribute(plugin: unknown) { void plugin; return () => undefined; }`,
+      );
+      const child = createReloadChild("slow-subscribe", []);
+      const sent: Array<{ type: string; subscriptionId?: string }> = [];
+      const originalSend = child.send.bind(child);
+      child.send = (message, callback) => {
+        sent.push(message);
+        if (message.type !== "initialize") return originalSend(message, callback);
+        callback?.(null);
+        queueMicrotask(() =>
+          child.emitMessage({ type: "ready", methods: [], subscriptions: ["feed"], providers: [] }),
+        );
+        return true;
+      };
+      const runtime = createTestRuntime({ spawnChild: () => child });
+      await runtime.startPlugin("slow-subscribe", directory);
+
+      const subscription = runtime.startSubscription("slow-subscribe", "feed", {});
+      const rejection = subscription.ready.catch((error: Error) => error);
+      await vi.advanceTimersByTimeAsync(30_000);
+      await expect(rejection).resolves.toMatchObject({
+        message: expect.stringContaining("timed out"),
+      });
+      const subscribe = sent.find((message) => message.type === "subscribe");
+      expect(sent).toContainEqual({
+        type: "unsubscribe",
+        subscriptionId: subscribe?.subscriptionId,
+      });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
  it("escalates a plugin that ignores graceful shutdown from TERM to KILL", async () => {
    vi.useFakeTimers();
    try {
@@ -1815,7 +1853,7 @@ export function inspect() { void Surface; return {}; }`,
    await runtime.stopAll();
  });

-  it("rejects a handler result that does not match its RPC output schema", async () => {
+  it("forwards a handler result for the client to validate against its RPC output schema", async () => {
    const directory = await createPlugin(
      "invalid-output",
      `import { z } from "zod";
@@ -1834,7 +1872,9 @@ export default function contribute(plugin: any) {

    await runtime.startPlugin("invalid-output", directory);

-    await expect(runtime.invoke("invalid-output", "broken", {})).rejects.toThrow();
+    await expect(runtime.invoke("invalid-output", "broken", {})).resolves.toEqual({
+      value: "wrong",
+    });
    await runtime.stopAll();
  });

@@ -34,6 +34,10 @@ import type {
  PluginUsageSourceMetadata,
 } from "./plugin-process-protocol.js";
 import { PluginProcessMessageSchema } from "./plugin-process-protocol.js";
+import {
+  BufferedPluginSubscription,
+  type PluginRuntimeSubscription,
+} from "./runtime-subscription.js";
 import { PluginSessionSocket } from "./session-socket.js";
 import { InternalPluginChild } from "./internal-child.js";
 import { evaluateBundle } from "./bundle-evaluator.js";
@@ -75,6 +79,8 @@ interface LoadedPlugin {
  /** Lets a client that already holds this bundle skip downloading it again. */
  clientBundleHash: string;
  methods: ReadonlySet<string>;
+  subscriptionMethods: ReadonlySet<string>;
+  subscriptions: Map<string, BufferedPluginSubscription>;
  hooks: string[];
  providers: readonly PluginProviderMetadata[];
  usageSources: readonly PluginUsageSourceMetadata[];
@@ -514,6 +520,40 @@ export class PluginRuntime {
    return this.request(loaded, { type: "invoke", requestId: randomUUID(), method, input });
  }

+  /** Starts one subscriber's handler in the plugin process. */
+  startSubscription(pluginId: string, method: string, input: unknown): PluginRuntimeSubscription {
+    const loaded = this.plugins.get(pluginId);
+    if (!loaded) throw new Error(`Plugin is not available: ${pluginId}`);
+    if (!loaded.subscriptionMethods.has(method))
+      throw new Error(`Plugin ${pluginId} does not contribute subscription ${method}`);
+    const subscriptionId = randomUUID();
+    const subscription = new BufferedPluginSubscription();
+    loaded.subscriptions.set(subscriptionId, subscription);
+    const ready = this.request(loaded, {
+      type: "subscribe",
+      requestId: randomUUID(),
+      subscriptionId,
+      method,
+      input,
+    }).then(
+      () => undefined,
+      (error: unknown) => {
+        loaded.subscriptions.delete(subscriptionId);
+        throw error;
+      },
+    );
+    return {
+      ready,
+      attach: (sink) => subscription.attach(sink),
+      release: () => {
+        subscription.released();
+        if (!loaded.subscriptions.delete(subscriptionId)) return;
+        if (loaded.child?.connected)
+          void send(loaded.child, { type: "unsubscribe", subscriptionId }).catch(() => undefined);
+      },
+    };
+  }
+
  emit<Name extends keyof PluginHookEvents>(name: Name, event: PluginHookEvents[Name]): void {
    for (const loaded of this.plugins.values()) {
      if (!loaded.hooks.includes(name)) {
@@ -727,6 +767,11 @@ export class PluginRuntime {
          if (message.type === "hook") {
            void send(child, { type: "hook.cancel", requestId }).catch(() => {});
          }
+          // The handler may still start after the daemon gave up on it.
+          if (message.type === "subscribe") {
+            const { subscriptionId } = message;
+            void send(child, { type: "unsubscribe", subscriptionId }).catch(() => {});
+          }
          reject(new Error(`Plugin RPC timed out: ${pluginId}.${message.type}`));
        },
        message.type === "tool.call" ? TOOL_CALL_TIMEOUT_MS : REQUEST_TIMEOUT_MS,
@@ -781,6 +826,8 @@ export class PluginRuntime {
        clientBundleHash: hashClientBundle(clientBundle),
        requirements: manifest.requirements,
        methods: new Set(),
+        subscriptionMethods: new Set(),
+        subscriptions: new Map(),
        hooks: [],
        providers: [],
        usageSources: [],
@@ -911,6 +958,8 @@ export class PluginRuntime {
      clientBundleHash: hashClientBundle(clientBundle),
      requirements,
      methods: new Set(ready.methods),
+      subscriptionMethods: new Set(ready.subscriptions ?? []),
+      subscriptions: new Map(),
      hooks: ready.hooks ?? [],
      providers: ready.providers ?? [],
      usageSources: ready.usageSources ?? [],
@@ -1009,6 +1058,16 @@ export class PluginRuntime {
      this.handleProviderMessage(loaded, message);
      return;
    }
+    if (message.type === "subscription.event") {
+      loaded.subscriptions.get(message.subscriptionId)?.event(message.event);
+      return;
+    }
+    if (message.type === "subscription.closed") {
+      const subscription = loaded.subscriptions.get(message.subscriptionId);
+      loaded.subscriptions.delete(message.subscriptionId);
+      subscription?.closed(message.error);
+      return;
+    }
    if (message.type !== "result" && message.type !== "error") return;
    const pending = loaded.pending.get(message.requestId);
    if (!pending) return;
@@ -1367,12 +1426,16 @@ export class PluginRuntime {
    this.appendLog(loaded.id, "stdout", "[paseo] Plugin stopped");
  }

+  /** Rejects in-flight requests and closes open subscriptions with the reason. */
  private rejectPending(loaded: LoadedPlugin, message: string): void {
    for (const invocation of loaded.pending.values()) {
      clearTimeout(invocation.timeout);
      invocation.reject(new Error(message));
    }
    loaded.pending.clear();
+    const subscriptions = [...loaded.subscriptions.values()];
+    loaded.subscriptions.clear();
+    for (const subscription of subscriptions) subscription.closed(message);
  }

  private appendLog(pluginId: string, stream: PluginLogEntry["stream"], message: string): void {
@@ -0,0 +1,55 @@
+import { defineSubscription } from "@getpaseo/plugin";
+import { subscribePluginRpc } from "@getpaseo/plugin/client/host";
+import type { PluginSubscriptionContext } from "@getpaseo/plugin/server";
+import type { PaseoApi } from "@getpaseo/client";
+import { expect, test } from "vitest";
+import { z } from "zod";
+import type { PluginProcessMessage } from "./plugin-process-protocol.js";
+import { PluginSubscriptionHandlers } from "./subscription-handlers.js";
+
+const lengths = defineSubscription({
+  name: "lengths",
+  input: z.object({ times: z.string().transform(Number) }),
+  event: z.string().transform((text) => text.length),
+});
+
+/** The plugin process's handlers wired to the client helper through the channel between them. */
+function connect(handler: (input: unknown, context: PluginSubscriptionContext) => unknown) {
+  const handlers = new PluginSubscriptionHandlers({
+    send: (message) => deliver(message),
+    sendAndWait: async (message) => deliver(message),
+  });
+  handlers.register(lengths, handler);
+  let observer: Parameters<Parameters<typeof subscribePluginRpc>[1]>[2] | null = null;
+  function deliver(message: PluginProcessMessage) {
+    if (message.type === "subscription.event") observer?.event(message.event);
+    if (message.type === "subscription.closed") observer?.closed();
+  }
+  return (method: string, input: unknown, next: NonNullable<typeof observer>) => {
+    observer = next;
+    handlers.start(
+      { type: "subscribe", requestId: "r", subscriptionId: "s", method, input },
+      {} as PaseoApi,
+    );
+    return Object.assign(() => handlers.release("s"), {
+      ready: Promise.resolve(),
+      release: async () => handlers.release("s"),
+    });
+  };
+}
+
+test("an event schema that transforms is applied once, on the receiving side", async () => {
+  const handled: unknown[] = [];
+  const received: number[] = [];
+  const closed: unknown[] = [];
+  const subscribe = connect(async (input, { push }) => {
+    handled.push(input);
+    await push("abc");
+  });
+  subscribePluginRpc(lengths, subscribe, { times: "2" }, (length) => received.push(length), {
+    onClosed: (result) => closed.push(result),
+  });
+  await expect.poll(() => received).toEqual([3]);
+  expect(handled).toEqual([{ times: 2 }]);
+  expect(closed).toEqual([{}]);
+});
@@ -0,0 +1,132 @@
+import type { PluginSubscriptionContract } from "@getpaseo/plugin";
+import type { PluginSubscriptionContext } from "@getpaseo/plugin/server";
+import type { PaseoApi } from "@getpaseo/client";
+import { assertPluginWireValue } from "@getpaseo/protocol/binary-frames/index";
+import type { PluginProcessMessage, PluginProcessRequest } from "./plugin-process-protocol.js";
+
+export type PluginSubscriptionHandler = (
+  input: unknown,
+  context: PluginSubscriptionContext,
+) => unknown;
+
+interface ActiveSubscription {
+  controller: AbortController;
+}
+
+interface SubscriptionChannel {
+  send(message: PluginProcessMessage): void;
+  sendAndWait(message: PluginProcessMessage): Promise<void>;
+}
+
+type SubscribeRequest = Extract<PluginProcessRequest, { type: "subscribe" }>;
+
+/**
+ * The plugin subprocess side of subscriptions: one handler call per subscriber, an abort signal
+ * that fires on release, and `push` that validates each event and resolves when it left the
+ * process.
+ */
+export class PluginSubscriptionHandlers {
+  private readonly registered = new Map<
+    string,
+    { contract: PluginSubscriptionContract; handler: PluginSubscriptionHandler }
+  >();
+  private readonly active = new Map<string, ActiveSubscription>();
+  private readonly channel: SubscriptionChannel;
+
+  constructor(channel: SubscriptionChannel) {
+    this.channel = channel;
+  }
+
+  has(name: string): boolean {
+    return this.registered.has(name);
+  }
+
+  register(contract: PluginSubscriptionContract, handler: PluginSubscriptionHandler): void {
+    this.registered.set(contract.name, { contract, handler });
+  }
+
+  catalog(): string[] {
+    return [...this.registered.keys()].sort();
+  }
+
+  start(message: SubscribeRequest, paseo: PaseoApi): void {
+    const { requestId, subscriptionId } = message;
+    const registered = this.registered.get(message.method);
+    if (!registered) {
+      this.channel.send({
+        type: "error",
+        requestId,
+        error: `Unknown subscription: ${message.method}`,
+      });
+      return;
+    }
+    const parsed = registered.contract.input.safeParse(message.input);
+    if (!parsed.success) {
+      this.channel.send({
+        type: "error",
+        requestId,
+        error: `Invalid input for ${message.method}: ${parsed.error.message}`,
+      });
+      return;
+    }
+    const controller = new AbortController();
+    const { signal } = controller;
+    let acknowledge = () => {};
+    const acknowledged = new Promise<void>((resolve) => {
+      acknowledge = resolve;
+    });
+    const push = async (event: unknown): Promise<void> => {
+      if (signal.aborted) return;
+      // The receiver parses into the schema's output; sending that output would parse it twice.
+      registered.contract.event.parse(event);
+      assertPluginWireValue(event, "event");
+      // Events pushed while the handler runs follow the acknowledgement.
+      await acknowledged;
+      if (signal.aborted) return;
+      await this.channel.sendAndWait({ type: "subscription.event", subscriptionId, event });
+    };
+    this.active.set(subscriptionId, { controller });
+    let result: unknown;
+    try {
+      result = registered.handler(parsed.data, { paseo, push, signal });
+    } catch (error) {
+      this.active.delete(subscriptionId);
+      controller.abort();
+      this.channel.send({ type: "error", requestId, error: describeError(error) });
+      return;
+    }
+    this.channel.send({ type: "result", requestId, output: null });
+    acknowledge();
+    if (result instanceof Promise)
+      result.then(
+        () => this.close(subscriptionId),
+        (error: unknown) => this.close(subscriptionId, describeError(error)),
+      );
+  }
+
+  /** The daemon released the subscription; it needs no closed message back. */
+  release(subscriptionId: string): void {
+    const active = this.active.get(subscriptionId);
+    if (!active) return;
+    this.active.delete(subscriptionId);
+    active.controller.abort();
+  }
+
+  releaseAll(): void {
+    for (const subscriptionId of this.active.keys()) this.release(subscriptionId);
+  }
+
+  private close(subscriptionId: string, error?: string): void {
+    if (!this.active.has(subscriptionId)) return;
+    this.release(subscriptionId);
+    this.channel.send({
+      type: "subscription.closed",
+      subscriptionId,
+      ...(error === undefined ? {} : { error }),
+    });
+  }
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
@@ -348,6 +348,7 @@ interface SessionForTestOptions {
  messages?: unknown[];
  targetedMessages?: Array<{ source: object; message: SessionOutboundMessage }>;
  binaryMessages?: Uint8Array[];
+  clientCapabilities?: SessionOptions["clientCapabilities"];
  pluginRuntime?: SessionOptions["pluginRuntime"];
  orchestrationSkills?: SessionOptions["orchestrationSkills"];
  workspaceLabelService?: WorkspaceLabelService;
@@ -402,6 +403,7 @@ function createSessionForTest(options: SessionForTestOptions = {}): Session {
            messages.push(message),
        }),
    onBinaryMessage: createBinaryMessageHandler(options.binaryMessages),
+    clientCapabilities: options.clientCapabilities,
    logger,
    downloadTokenStore: options.downloadTokenStore ?? asDownloadTokenStore(),
    pushNotifications: options.pushNotifications ?? asPushNotifications(),
@@ -601,6 +603,64 @@ test("routes plugin requests and releases its owned catalog subscription on clea
  expect(releasePluginSubscription).toHaveBeenCalledOnce();
 });

+test("losing daemon.manage releases the session's plugin subscriptions", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  const release = vi.fn();
+  const pluginRuntime = {
+    subscribe: () => () => {},
+    subscribePluginRpc: () => ({ ready: Promise.resolve(), attach: () => {}, release }),
+  } as unknown as NonNullable<SessionOptions["pluginRuntime"]>;
+  const session = createSessionForTest({ messages, pluginRuntime });
+
+  await session.handleMessage({
+    type: "plugin.rpc.subscribe.request",
+    requestId: "watch",
+    pluginId: "example",
+    method: "screen.capture",
+    input: {},
+  });
+  expect(messages.map((message) => message.type)).toContain("plugin.rpc.subscribe.response");
+  session.setPermissions(["daemon.read"]);
+
+  // Bytes have no outbound permission check, so the stream itself has to end.
+  await vi.waitFor(() => expect(release).toHaveBeenCalledOnce());
+});
+
+test("losing daemon.manage during a plugin RPC withholds its JSON and binary results", async () => {
+  const messages: SessionOutboundMessage[] = [];
+  const binaryMessages: Uint8Array[] = [];
+  const outputs = new Map<string, (output: unknown) => void>();
+  const pluginRuntime = {
+    subscribe: () => () => {},
+    invokePluginRpc: (_pluginId: string, method: string) =>
+      new Promise((resolve) => outputs.set(method, resolve)),
+  } as unknown as NonNullable<SessionOptions["pluginRuntime"]>;
+  const session = createSessionForTest({
+    messages,
+    binaryMessages,
+    pluginRuntime,
+    clientCapabilities: { [CLIENT_CAPS.pluginBinaryPayloads]: true },
+  });
+  const invoke = (method: string) =>
+    session.handleMessage({
+      type: "plugin.rpc.invoke.request",
+      requestId: method,
+      pluginId: "example",
+      method,
+      input: {},
+    });
+
+  const pending = [invoke("capture.json"), invoke("capture.bytes")];
+  await vi.waitFor(() => expect(outputs.size).toBe(2));
+  session.setPermissions(["daemon.read"]);
+  outputs.get("capture.json")?.({ width: 1 });
+  outputs.get("capture.bytes")?.(new Uint8Array([1, 2, 3]));
+  await Promise.all(pending);
+
+  expect(messages.filter((message) => message.type === "plugin.rpc.invoke.response")).toEqual([]);
+  expect(binaryMessages).toEqual([]);
+});
+
 test("leaves out the client bundles a catalog request already holds", async () => {
  const messages: SessionOutboundMessage[] = [];
  const pluginRuntime: NonNullable<SessionOptions["pluginRuntime"]> = {
@@ -50,6 +50,11 @@ import type {
 import { TerminalSessionController } from "../terminal/terminal-session-controller.js";
 import type { TerminalActivity } from "@getpaseo/protocol/terminal-activity";
 import type { BinaryFrame } from "@getpaseo/protocol/binary-frames/index";
+import {
+  encodePluginEventFrame,
+  encodePluginOutputFrame,
+  PluginFrameOpcode,
+} from "@getpaseo/protocol/binary-frames/index";
 import { CursorError } from "./pagination/cursor.js";
 import { SortablePager, type SortSpec } from "./pagination/sortable-pager.js";
 import { matchesAgentHistoryQuery } from "./agent-history-search.js";
@@ -521,6 +526,11 @@ export interface SessionOptions {
    subscribeSettings?(listener: (pluginId: string, settingsId: string) => void): () => void;
    catalog(): Array<{ id: string; clientBundle: string; clientBundleHash?: string }>;
    invokePluginRpc(pluginId: string, method: string, input: unknown): Promise<unknown>;
+    subscribePluginRpc(
+      pluginId: string,
+      method: string,
+      input: unknown,
+    ): import("./plugins/runtime-subscription.js").PluginRuntimeSubscription;
    listUsageReports(options?: {
      forceRefresh?: boolean;
      reportIds?: string[];
@@ -926,7 +936,7 @@ export class Session {
    this.workspaceFilesSession = new WorkspaceFilesSession({
      host: {
        emit: (msg, source) => this.emitForSource(msg, source),
-        emitBinary: (frame, source) => this.emitBinaryForFileTransfer(frame, source),
+        emitBinary: (frame, source) => this.emitBinaryReply(frame, source),
        hasBinaryChannel: () => this.onBinaryMessage !== null,
      },
      downloadTokenStore,
@@ -2221,13 +2231,15 @@ export class Session {
      this.peakInflightRequests = this.inflightRequests;
    }
    try {
-      this.sessionLogger.trace(
-        {
-          messageType: msg.type,
-          payloadBytes: JSON.stringify(msg).length,
-        },
-        "agent.session.inbound",
-      );
+      // Stringifying a binary plugin input costs its size; test logger stubs lack isLevelEnabled.
+      if (this.sessionLogger.isLevelEnabled?.("trace"))
+        this.sessionLogger.trace(
+          {
+            messageType: msg.type,
+            payloadBytes: JSON.stringify(msg).length,
+          },
+          "agent.session.inbound",
+        );
      if (!this.authorization.allowsInbound(msg)) {
        const requestId = sessionRequestId(msg);
        if (requestId) {
@@ -2292,6 +2304,17 @@ export class Session {
          this.sessionLogger.error({ err: error }, "Failed to release revoked browser hosting"),
        );
    }
+    // Binary plugin events skip the outbound permission check, so revocation ends the streams.
+    if (!this.authorization.allowsPermission("daemon.manage")) {
+      void this.delivery
+        .releaseFamily("plugin-rpc")
+        .catch((error) =>
+          this.sessionLogger.error(
+            { err: error },
+            "Failed to release revoked plugin subscriptions",
+          ),
+        );
+    }
  }

  public getPermissions(): DaemonPermission[] {
@@ -2454,6 +2477,7 @@ export class Session {
      this.dispatchOrchestrationSkillsMessage(msg) ??
      this.dispatchPluginDirectoryMessage(msg) ??
      this.dispatchPluginMessage(msg) ??
+      this.dispatchPluginRpcMessage(msg) ??
      this.dispatchHostServiceMessage(msg) ??
      this.dispatchMiscMessage(msg);
    if (promise) await promise;
@@ -2621,21 +2645,98 @@ export class Session {
      });
      return undefined;
    }
+    return undefined;
+  }
+
+  private dispatchPluginRpcMessage(msg: SessionInboundMessage): Promise<void> | undefined {
    if (msg.type === "plugin.rpc.invoke.request") {
      if (!this.pluginRuntime) throw new Error("Plugin service is unavailable");
      return this.pluginRuntime
        .invokePluginRpc(msg.pluginId, msg.method, msg.input)
-        .then((output) => {
-          this.emit({
-            type: "plugin.rpc.invoke.response",
-            payload: { requestId: msg.requestId, output },
-          });
-          return undefined;
-        });
+        .then((output) => this.replyPluginRpc(msg, output));
    }
+    if (msg.type === "plugin.rpc.subscribe.request") return this.subscribePluginRpc(msg);
    return undefined;
  }

+  /** A `Uint8Array` output is the binary form of `plugin.rpc.invoke.response`. */
+  private async replyPluginRpc(
+    request: Extract<SessionInboundMessage, { type: "plugin.rpc.invoke.request" }>,
+    output: unknown,
+  ): Promise<void> {
+    const response: SessionOutboundMessage = {
+      type: "plugin.rpc.invoke.response",
+      payload: { requestId: request.requestId, output },
+    };
+    if (!(output instanceof Uint8Array)) {
+      this.emit(response);
+      return;
+    }
+    // The frame is the binary form of the response, so it needs the response's permission.
+    if (!this.authorization.allowsOutbound(response)) return;
+    if (!this.supports(CLIENT_CAPS.pluginBinaryPayloads) || this.onBinaryMessage === null)
+      throw new Error(
+        `Update Paseo to receive the binary output of plugin RPC ${request.pluginId}.${request.method}`,
+      );
+    await this.emitBinaryReply(
+      encodePluginOutputFrame(request.requestId, output),
+      this.delivery.currentSource,
+    );
+  }
+
+  private async subscribePluginRpc(
+    request: Extract<SessionInboundMessage, { type: "plugin.rpc.subscribe.request" }>,
+  ): Promise<void> {
+    if (!this.pluginRuntime) throw new Error("Plugin service is unavailable");
+    const subscription = this.pluginRuntime.subscribePluginRpc(
+      request.pluginId,
+      request.method,
+      request.input,
+    );
+    const owner = this.delivery.begin("plugin-rpc", undefined, () => subscription.release());
+    try {
+      await subscription.ready;
+    } catch (error) {
+      await owner.release();
+      throw error;
+    }
+    if (owner.signal.aborted) return;
+    this.emit({
+      type: "plugin.rpc.subscribe.response",
+      payload: { requestId: request.requestId, subscriptionId: owner.responseId },
+    });
+    const close = (reason?: string) => {
+      owner.emit({
+        type: "plugin.rpc.closed",
+        payload: {
+          subscriptionId: owner.responseId,
+          ...(reason === undefined ? {} : { error: reason }),
+        },
+      });
+      void owner.release().catch(() => undefined);
+    };
+    subscription.attach({
+      event: (event) => {
+        const message: SessionOutboundMessage = {
+          type: "plugin.rpc.event",
+          payload: { subscriptionId: owner.responseId, event },
+        };
+        if (!(event instanceof Uint8Array)) {
+          owner.emit(message);
+          return;
+        }
+        if (!this.authorization.allowsOutbound(message)) return;
+        if (this.onBinaryMessage === null) {
+          subscription.release();
+          close("This connection cannot carry binary plugin events");
+          return;
+        }
+        owner.emitBinary(encodePluginEventFrame(owner.responseId, event));
+      },
+      closed: close,
+    });
+  }
+
  private dispatchPluginDirectoryMessage(msg: SessionInboundMessage): Promise<void> | undefined {
    if (msg.type === "plugin.source.install.request") {
      if (!this.pluginRuntime) throw new Error("Plugin service is unavailable");
@@ -3272,6 +3373,22 @@ export class Session {
      this.connectedHostSession?.binary(binaryFrame.frame, source);
      return;
    }
+    if (binaryFrame.kind === "plugin") {
+      const frame = binaryFrame.frame;
+      // The binary form of plugin.rpc.invoke.request; it authorizes and replies like the JSON form.
+      if (frame.opcode !== PluginFrameOpcode.Input) return;
+      await this.handleMessage(
+        {
+          type: "plugin.rpc.invoke.request",
+          requestId: frame.requestId,
+          pluginId: frame.pluginId,
+          method: frame.method,
+          input: frame.payload,
+        },
+        source,
+      );
+      return;
+    }
    if (!this.authorization.allowsPermission("workspace.write")) {
      return;
    }
@@ -8690,9 +8807,9 @@ export class Session {
    }
  }

-  private async emitBinaryForFileTransfer(frame: Uint8Array, source?: object): Promise<void> {
+  private async emitBinaryReply(frame: Uint8Array, source?: object): Promise<void> {
    if (source && this.onBinaryMessageToSource) {
-      this.delivery.authorizeFileReply(frame, source);
+      this.delivery.authorizeBinaryReply(frame, source);
      await this.onBinaryMessageToSource(source, frame);
      return;
    }
@@ -56,6 +56,11 @@ export interface OwnedSubscription {
  release(): Promise<void>;
 }

+const BINARY_REPLY_REQUESTS: ReadonlySet<string> = new Set([
+  "file_explorer_request",
+  "plugin.rpc.invoke.request",
+]);
+
 // One registration per context kind; per-session registrations outlive closed sessions in Node.
 const requests = new AsyncLocalStorage<RequestOwner>();
 const projectionSource = new AsyncLocalStorage<ProjectionOwner>();
@@ -394,12 +399,13 @@ export class SessionDelivery {
    if (owner) await this.releaseOwner(owner);
  }

-  authorizeFileReply(frame: Uint8Array, socket: object): void {
+  /** Lets a binary frame answer the current request, for requests whose reply can be bytes. */
+  authorizeBinaryReply(frame: Uint8Array, socket: object): void {
    const owner = this.currentRequest;
    if (
      owner?.active &&
      owner.source.socket === socket &&
-      owner.request.type === "file_explorer_request"
+      BINARY_REPLY_REQUESTS.has(owner.request.type)
    )
      this.proofs.set(frame, owner);
  }
@@ -2066,6 +2066,8 @@ export class VoiceAssistantWebSocketServer {
        pluginThemes: true,
        pluginSettings: true,
        pluginTimelineItems: true,
+        // COMPAT(pluginSubscriptions): added in v0.15.0, remove gate after 2027-05-02.
+        pluginSubscriptions: true,
        // COMPAT(skillManagement): added in v0.4.0, remove gate after 2027-08-16.
        skillManagement: true,
        // COMPAT(idleRuntimeCleanupSetting): added in v0.13.0, remove gate after 2027-04-26.
@@ -806,6 +806,25 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => {
    test("checks out the authoritative GitLab MR ref before a same-named origin branch", async () => {
      const { tempDir, repoDir, paseoHome } = createGitLabMrWithConflictingOriginBranchRepo();
      cleanupPaths.push(tempDir);
+      const sourceRemote = path.join(tempDir, "fork.git");
+      execFileSync("git", ["clone", "--bare", path.join(tempDir, "origin.git"), sourceRemote], {
+        stdio: "pipe",
+      });
+      const mrHead = execFileSync(
+        "git",
+        [
+          `--git-dir=${path.join(tempDir, "origin.git")}`,
+          "rev-parse",
+          "refs/merge-requests/14/head",
+        ],
+        { encoding: "utf8" },
+      ).trim();
+      execFileSync("git", [
+        `--git-dir=${sourceRemote}`,
+        "update-ref",
+        "refs/heads/feature/gitlab-mr",
+        mrHead,
+      ]);
      const gitlab = createGitLabService({
        resolveGlabPath: async () => "/usr/bin/glab",
        resolveRemoteUrl: async () => "git@gitlab.example.com:example-group/example-project.git",
@@ -820,12 +839,23 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => {
                state: "opened",
                source_branch: "feature/gitlab-mr",
                target_branch: "main",
+                author: { username: "mr-author" },
                source_project_id: 202,
                target_project_id: 101,
              }),
              stderr: "",
            };
          }
+          if (args[0] === "api" && args[1] === "projects/202") {
+            return {
+              stdout: JSON.stringify({
+                namespace: { full_path: "team" },
+                ssh_url_to_repo: sourceRemote,
+                http_url_to_repo: "https://gitlab.example.com/team/fork.git",
+              }),
+              stderr: "",
+            };
+          }
          throw new Error(`unexpected glab args: ${args.join(" ")}`);
        },
      });
@@ -843,11 +873,17 @@ describe.skipIf(isPlatform("win32"))("worktree-core POSIX-only", () => {
      expect(result.intent).toMatchObject({
        kind: "checkout-change-request",
        forge: "gitlab",
+        headRepository: "team/fork",
+        localBranchName: "team/feature/gitlab-mr",
        checkoutRefs: [
          { remoteName: "origin", remoteRef: "refs/merge-requests/14/head" },
          { remoteName: "origin", remoteRef: "refs/heads/feature/gitlab-mr" },
        ],
      });
+      expect(result.worktree.branchName).toBe("team/feature/gitlab-mr");
+      expect(getGitConfigValue(result.worktree.worktreePath, "remote.paseo-pr-14.url")).toBe(
+        sourceRemote,
+      );
      expect(readFileSync(path.join(result.worktree.worktreePath, "README.md"), "utf8")).toBe(
        "authoritative merge request head\n",
      );
@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";

+import { resolveWorktreeCreationIntent } from "../server/resolve-worktree-creation-intent.js";
+
 import type { PullRequestCommandStatus } from "./forge-service.js";
 import { GITLAB_ACTIVE_PIPELINE_STATUS_SET } from "@getpaseo/protocol/gitlab-pipeline";
 import type { GitLabStatusFacts } from "./gitlab-facts.js";
@@ -463,9 +465,8 @@ describe("createGitLabService", () => {
  it("maps a same-repo merge request view to a checkout target", async () => {
    const { service, calls } = makeService(() => ok(JSON.stringify(OPEN_MR)));

-    await expect(
-      service.getPullRequestCheckoutTarget?.({ cwd: "/repo", number: 14 }),
-    ).resolves.toEqual({
+    const target = await service.getPullRequestCheckoutTarget?.({ cwd: "/repo", number: 14 });
+    expect(target).toEqual({
      number: 14,
      baseRefName: "main",
      headRefName: "release/v0.4.0",
@@ -479,30 +480,76 @@ describe("createGitLabService", () => {
      isCrossRepository: false,
      headRefKind: "branch",
    });
-    expect(calls[0]).toEqual(["mr", "view", "14", "-F", "json"]);
+    expect(
+      service.buildPrLocalBranchName?.({
+        headRef: target!.headRefName,
+        checkoutTarget: target!,
+      }),
+    ).toBe("release/v0.4.0");
+    expect(calls).toEqual([["mr", "view", "14", "-F", "json"]]);
  });

-  it("marks fork merge request checkout targets as cross-repository", async () => {
-    const { service } = makeService(() =>
-      ok(
-        JSON.stringify({
-          ...OPEN_MR,
-          source_project_id: 202,
-          target_project_id: 101,
-        }),
-      ),
-    );
+  it.each(["contributor", "team"])(
+    "resolves the source project rather than the MR author for %s forks",
+    async (owner) => {
+      const { service, calls } = makeService((args) => {
+        if (args[0] === "api")
+          return ok(
+            JSON.stringify({
+              namespace: { full_path: owner },
+              ssh_url_to_repo: `git@gitlab.example.com:${owner}/fork.git`,
+              http_url_to_repo: `https://gitlab.example.com/${owner}/fork.git`,
+            }),
+          );
+        return ok(
+          JSON.stringify({ ...OPEN_MR, source_project_id: 202, author: { username: "mr-author" } }),
+        );
+      });
+      const intent = await resolveWorktreeCreationIntent(
+        {
+          action: "checkout",
+          checkoutSource: { kind: "change_request", forge: "gitlab", number: 14 },
+        },
+        "/repo",
+        { forge: "gitlab", forgeService: service, resolveDefaultBranch: async () => "main" },
+      );
+      expect(intent).toMatchObject({
+        kind: "checkout-change-request",
+        headRepositoryOwner: owner,
+        headRepository: `${owner}/fork`,
+        pushRemoteUrl: `git@gitlab.example.com:${owner}/fork.git`,
+        localBranchName: `${owner}/release/v0.4.0`,
+        checkoutRefs: [
+          { remoteName: "origin", remoteRef: "refs/merge-requests/14/head" },
+          { remoteName: "origin", remoteRef: "refs/heads/release/v0.4.0" },
+        ],
+      });
+      expect(calls).toEqual([
+        ["mr", "view", "14", "-F", "json"],
+        ["api", "projects/202"],
+      ]);
+    },
+  );

-    await expect(
-      service.getPullRequestCheckoutTarget?.({ cwd: "/repo", number: 14 }),
-    ).resolves.toMatchObject({
-      number: 14,
-      headRefName: "release/v0.4.0",
+  it("keeps the target MR ref usable when its source project is inaccessible", async () => {
+    const { service } = makeService((args) => {
+      if (args[0] === "api") throw { code: 1, stderr: "404 Project Not Found" };
+      return ok(JSON.stringify({ ...OPEN_MR, source_project_id: 202 }));
+    });
+    const target = await service.getPullRequestCheckoutTarget!({ cwd: "/repo", number: 14 });
+    expect(target).toMatchObject({
      isCrossRepository: true,
      headOwnerLogin: null,
      headRepositorySshUrl: null,
      headRepositoryUrl: null,
+      checkoutRefs: [
+        { remoteName: "origin", remoteRef: "refs/merge-requests/14/head" },
+        { remoteName: "origin", remoteRef: "refs/heads/release/v0.4.0" },
+      ],
    });
+    expect(
+      service.buildPrLocalBranchName!({ headRef: target.headRefName, checkoutTarget: target }),
+    ).toBe("pr-14/release/v0.4.0");
  });

  it("creates a merge request and parses the URL and iid from glab output", async () => {
@@ -60,6 +60,7 @@ import {
 } from "@getpaseo/protocol/check-traits";
 import { GITLAB_ACTIVE_PIPELINE_STATUS_SET } from "@getpaseo/protocol/gitlab-pipeline";
 import { isGitLabStatusFacts, type GitLabStatusFacts } from "./gitlab-facts.js";
+import { buildForkLocalBranchName } from "../utils/change-request-checkout.js";

 const GLAB_ENV = {
  GIT_TERMINAL_PROMPT: "0",
@@ -144,6 +145,12 @@ const GitLabPipelineDetailsSchema = z
  })
  .passthrough();

+const GitLabSourceProjectSchema = z.object({
+  namespace: z.object({ full_path: z.string() }),
+  ssh_url_to_repo: z.string(),
+  http_url_to_repo: z.string(),
+});
+
 const GitLabMergeRequestSchema = z
  .object({
    iid: z.number(),
@@ -949,6 +956,16 @@ export function createGitLabService(options: CreateGitLabServiceOptions = {}): F
    return runJson(["mr", "view", ref, "-F", "json"], { cwd }, GitLabMergeRequestSchema);
  }

+  async function loadSourceProject(cwd: string, projectId: number) {
+    try {
+      return await runJson(["api", `projects/${projectId}`], { cwd }, GitLabSourceProjectSchema);
+    } catch (error) {
+      // The target's MR ref remains fetchable even if the source project is private.
+      if (error instanceof GlabCommandError && /\b404\b/.test(error.stderr)) return null;
+      throw error;
+    }
+  }
+
  async function listMergeRequestsBySourceBranch(
    cwd: string,
    sourceBranch: string,
@@ -1183,10 +1200,23 @@ export function createGitLabService(options: CreateGitLabServiceOptions = {}): F
      return mr.source_branch;
    },

+    buildPrLocalBranchName({ headRef, checkoutTarget }) {
+      return buildForkLocalBranchName({ headRef, ...checkoutTarget });
+    },
+
    async getPullRequestCheckoutTarget(
      input: GetPullRequestOptions,
    ): Promise<PullRequestCheckoutTarget> {
      const mr = await viewMergeRequest(input.cwd, String(input.number));
+      const isCrossRepository =
+        mr.source_project_id !== undefined &&
+        mr.source_project_id !== null &&
+        mr.target_project_id !== undefined &&
+        mr.target_project_id !== null &&
+        mr.source_project_id !== mr.target_project_id;
+      const sourceProject = isCrossRepository
+        ? await loadSourceProject(input.cwd, mr.source_project_id!)
+        : null;
      return {
        number: mr.iid,
        baseRefName: mr.target_branch,
@@ -1195,15 +1225,10 @@ export function createGitLabService(options: CreateGitLabServiceOptions = {}): F
          { remoteName: "origin", remoteRef: `refs/merge-requests/${mr.iid}/head` },
          { remoteName: "origin", remoteRef: `refs/heads/${mr.source_branch}` },
        ],
-        headOwnerLogin: null,
-        headRepositorySshUrl: null,
-        headRepositoryUrl: null,
-        isCrossRepository:
-          mr.source_project_id !== undefined &&
-          mr.source_project_id !== null &&
-          mr.target_project_id !== undefined &&
-          mr.target_project_id !== null &&
-          mr.source_project_id !== mr.target_project_id,
+        headOwnerLogin: sourceProject?.namespace.full_path ?? null,
+        headRepositorySshUrl: sourceProject?.ssh_url_to_repo ?? null,
+        headRepositoryUrl: sourceProject?.http_url_to_repo ?? null,
+        isCrossRepository,
        headRefKind: "branch",
      };
    },
@@ -3,7 +3,7 @@ import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "fs"
 import { tmpdir } from "os";
 import { join } from "path";
 import { afterEach, describe, expect, it } from "vitest";
-import { listCheckoutCommits } from "./checkout-git.js";
+import { getCommitFileDiff, listCheckoutCommits } from "./checkout-git.js";
 import { writePaseoWorktreeMetadata } from "./worktree-metadata.js";

 const tempDirs: string[] = [];
@@ -332,6 +332,50 @@ describe("listCheckoutCommits", () => {
    ]);
  });

+  it.each([
+    {
+      label: "without edits",
+      content: "one\ntwo\nthree\nfour\nfive\n",
+      additions: 0,
+      deletions: 0,
+    },
+    { label: "with edits", content: "one\nTWO\nthree\nfour\nfive\n", additions: 1, deletions: 1 },
+  ])(
+    "opens a file moved up out of a directory $label",
+    async ({ content, additions, deletions }) => {
+      const { repoDir } = initRepoOnMain();
+      git(["checkout", "-b", "feature"], repoDir);
+      mkdirSync(join(repoDir, "src", "nested"), { recursive: true });
+      commitFile(repoDir, "src/nested/a.txt", "one\ntwo\nthree\nfour\nfive\n", "Add nested file");
+      git(["mv", "src/nested/a.txt", "src/a.txt"], repoDir);
+      writeFileSync(join(repoDir, "src/a.txt"), content);
+      git(["add", "src/a.txt"], repoDir);
+      commit(repoDir, "Move file up");
+
+      const { commits } = await listCheckoutCommits({ cwd: repoDir });
+
+      const movedCommit = commits[0]!;
+      const movedFile = movedCommit.files[0]!;
+      expect(movedCommit.files).toEqual([
+        {
+          path: "src/a.txt",
+          additions,
+          deletions,
+          status: "renamed",
+        },
+      ]);
+      expect(
+        await getCommitFileDiff({ cwd: repoDir, sha: movedCommit.sha, path: movedFile.path }),
+      ).toMatchObject({
+        path: "src/a.txt",
+        isNew: false,
+        isDeleted: false,
+        additions,
+        deletions,
+      });
+    },
+  );
+
  it("derives status for modified and deleted files", async () => {
    const { repoDir } = initRepoOnMain();
    git(["checkout", "-b", "feature"], repoDir);
@@ -636,6 +636,11 @@ function normalizeNumstatPath(pathField: string): string {
  const braceRenameMatch = pathField.match(/^(.*)\{(.*) => (.*)\}(.*)$/);
  if (braceRenameMatch) {
    const [, prefix, , renamed, suffix] = braceRenameMatch;
+    // Moving out of a directory prints `src/{nested => }/a.ts`, so an empty
+    // destination leaves a separator from each side behind.
+    if (!renamed) {
+      return unquoteGitPath(`${prefix}${suffix.slice(1)}`);
+    }
    return unquoteGitPath(`${prefix}${renamed}${suffix}`);
  }

@@ -0,0 +1,7 @@
+# Live changes
+
+See which files differ from `HEAD` in a workspace panel that updates as you edit. The daemon watches the workspace and pushes the changed-file list to the panel; the panel never polls.
+
+Open **Open live changes** in the Command Center, or pick **Live changes** from the workspace tab menu. Each open panel runs its own watcher, which stops when you close the panel.
+
+The watcher reads the working tree recursively, so a checkout with very large ignored directories makes it slower to start.
@@ -0,0 +1,14 @@
+# Diff watch plugin example
+
+A workspace panel subscribes to a daemon-side watcher and lists the files that differ from `HEAD`,
+updating as files change.
+
+```bash
+paseo plugin add /absolute/path/to/paseo/plugin-examples/diff-watch
+```
+
+- `shared/diff.ts` defines the `diff.watch` subscription contract.
+- `index.server.ts` handles it: an async handler that loops until the subscriber leaves, pushing
+  the file list whenever it changes. A git failure rejects the handler and closes the subscription
+  with that error.
+- `client/diff-panel.tsx` calls `useSubscription` and renders the latest list.
@@ -0,0 +1,65 @@
+import {
+  useSubscription,
+  useWorkspace,
+  type PluginWorkspacePanelProps,
+} from "@getpaseo/plugin/client";
+import { useMemo, useState } from "react";
+import { ScrollView, StyleSheet, Text, View } from "react-native";
+import { diffWatch, type ChangedFile } from "../shared/diff";
+
+const BASE = "HEAD";
+
+export function DiffPanel({ workspaceId, theme, layout }: PluginWorkspacePanelProps) {
+  const cwd = useWorkspace(workspaceId, (workspace) => workspace.directory);
+  const styles = useStyles(theme, layout.compact);
+  if (!cwd) return <Text style={styles.muted}>Workspace unavailable</Text>;
+  return <ChangedFiles cwd={cwd} styles={styles} />;
+}
+
+function ChangedFiles({ cwd, styles }: { cwd: string; styles: ReturnType<typeof useStyles> }) {
+  const [files, setFiles] = useState<ChangedFile[] | null>(null);
+  const subscription = useSubscription(diffWatch, { cwd, from: BASE }, (event) => {
+    setFiles(event.files);
+  });
+  return (
+    <ScrollView style={styles.screen} contentContainerStyle={styles.content}>
+      <Text style={styles.title}>Changes against {BASE}</Text>
+      <Text style={styles.muted}>{describe(subscription, files)}</Text>
+      {files?.map((file) => (
+        <View key={file.path} style={styles.row}>
+          <Text style={styles.status}>{file.status}</Text>
+          <Text style={styles.path} numberOfLines={1}>
+            {file.path}
+          </Text>
+        </View>
+      ))}
+    </ScrollView>
+  );
+}
+
+function describe(
+  subscription: ReturnType<typeof useSubscription>,
+  files: ChangedFile[] | null,
+): string {
+  if (subscription.status === "error") return subscription.error.message;
+  if (subscription.status === "closed") return "Stopped watching";
+  if (!files) return "Reading changes…";
+  if (files.length === 0) return "No changes";
+  return files.length === 1 ? "1 file changed" : `${files.length} files changed`;
+}
+
+function useStyles(theme: PluginWorkspacePanelProps["theme"], compact: boolean) {
+  return useMemo(
+    () =>
+      StyleSheet.create({
+        screen: { flex: 1, backgroundColor: theme.colors.surface0 },
+        content: { padding: compact ? 16 : 24, gap: 8 },
+        title: { color: theme.colors.foreground, fontSize: 18, fontWeight: "600" },
+        muted: { color: theme.colors.foregroundMuted },
+        row: { flexDirection: "row", gap: 12, alignItems: "center" },
+        status: { color: theme.colors.foregroundMuted, width: 72 },
+        path: { color: theme.colors.foreground, flex: 1 },
+      }),
+    [theme, compact],
+  );
+}
@@ -0,0 +1,22 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { DiffPanel } from "./client/diff-panel";
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "changes",
+    title: "Live changes",
+    icon: "GitCompare",
+    context: "workspace",
+    Component: DiffPanel,
+  });
+  client.addCommandCenterItem({
+    id: "open-changes",
+    title: "Open live changes",
+    icon: "GitCompare",
+    context: "workspace",
+    onSelect({ openPanel }) {
+      openPanel("changes");
+    },
+  });
+  return () => {};
+}
@@ -0,0 +1,19 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { readChangedFiles, watchDirectory } from "./server/diff";
+import { diffWatch } from "./shared/diff";
+
+export default function contribute(server: PluginServerContext) {
+  // The handler runs for as long as the panel is subscribed; a git failure closes it with the error.
+  server.handle(diffWatch, async (input, { push, signal }) => {
+    const directory = watchDirectory(input.cwd, signal);
+    let previous = "";
+    while (await directory.settled()) {
+      const files = await readChangedFiles(input);
+      const current = JSON.stringify(files);
+      if (current === previous) continue;
+      previous = current;
+      await push({ type: "changes", files });
+    }
+  });
+  return () => {};
+}
@@ -0,0 +1,6 @@
+{
+  "id": "diff-watch",
+  "requirements": {
+    "paseo": ">=0.15.0-beta.2"
+  }
+}
@@ -0,0 +1,79 @@
+import { watch } from "node:fs";
+import type { SubscriptionInput } from "@getpaseo/plugin";
+import { execCommand } from "@getpaseo/plugin/server";
+import type { ChangedFile, diffWatch } from "../shared/diff";
+
+const SETTLE_MS = 150;
+
+const STATUSES: Record<string, ChangedFile["status"]> = {
+  A: "added",
+  M: "modified",
+  D: "deleted",
+  R: "renamed",
+};
+
+/** Lists changed files the way `git diff --name-status` does, plus untracked files. */
+export async function readChangedFiles({
+  cwd,
+  from,
+  to,
+}: SubscriptionInput<typeof diffWatch>): Promise<ChangedFile[]> {
+  const range = to ? [from, to] : [from];
+  const { stdout } = await execCommand("git", ["diff", "--name-status", "-z", ...range], { cwd });
+  const files = parseNameStatus(stdout);
+  if (!to) {
+    const untracked = await execCommand(
+      "git",
+      ["ls-files", "--others", "--exclude-standard", "-z"],
+      {
+        cwd,
+      },
+    );
+    for (const path of untracked.stdout.split("\0").filter(Boolean))
+      files.push({ path, status: "added" });
+  }
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function parseNameStatus(output: string): ChangedFile[] {
+  const fields = output.split("\0").filter(Boolean);
+  const files: ChangedFile[] = [];
+  for (let index = 0; index < fields.length; index += 1) {
+    const code = fields[index][0];
+    // Renames carry the old path before the new one.
+    if (code === "R") index += 1;
+    const path = fields[index + 1];
+    index += 1;
+    if (path) files.push({ path, status: STATUSES[code] ?? "modified" });
+  }
+  return files;
+}
+
+/** Resolves each time the directory settles after a change, and with false once `signal` aborts. */
+export function watchDirectory(cwd: string, signal: AbortSignal) {
+  let changed = true;
+  let wake: (() => void) | null = null;
+  const watcher = watch(cwd, { recursive: true }, () => {
+    changed = true;
+    wake?.();
+  });
+  signal.addEventListener(
+    "abort",
+    () => {
+      watcher.close();
+      wake?.();
+    },
+    { once: true },
+  );
+  return {
+    async settled(): Promise<boolean> {
+      // The watcher and the abort both wake a wait.
+      if (!changed && !signal.aborted) await new Promise<void>((resolve) => (wake = resolve));
+      wake = null;
+      if (signal.aborted) return false;
+      await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+      changed = false;
+      return !signal.aborted;
+    },
+  };
+}
@@ -0,0 +1,16 @@
+import { defineSubscription } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const ChangedFileSchema = z.object({
+  path: z.string(),
+  status: z.enum(["added", "modified", "deleted", "renamed"]),
+});
+
+export type ChangedFile = z.infer<typeof ChangedFileSchema>;
+
+/** Files that differ between `from` and `to`; without `to`, the working tree. */
+export const diffWatch = defineSubscription({
+  name: "diff.watch",
+  input: z.object({ cwd: z.string(), from: z.string(), to: z.string().optional() }),
+  event: z.object({ type: z.literal("changes"), files: z.array(ChangedFileSchema) }),
+});
@@ -0,0 +1,7 @@
+# Media stream
+
+Watch a moving test pattern and an audio level meter, streamed live from your machine into a workspace panel. Video and audio arrive together on one connection, and the counters show how many frames of each have played.
+
+Open **Open media stream** in the Command Center, or pick **Media stream** from the workspace tab menu. Closing the panel stops the stream.
+
+Press **Send this frame back** to upload the picture on screen to your machine. The panel shows the size and checksum your machine received. A 16 by 9 picture is 432 bytes.
@@ -0,0 +1,17 @@
+# Media stream plugin example
+
+One subscription carries two binary streams. Each pushed `Uint8Array` is a binary frame; its first
+byte says whether it is video, a keyframe, or audio.
+
+```bash
+paseo plugin add /absolute/path/to/paseo/plugin-examples/media-stream
+```
+
+- `shared/media-frames.ts` owns the byte layout: `encodeMediaFrame`, `decodeMediaFrame`, and the
+  `media.stream` contract. `decodeMediaFrame` returns a view, so the panel never copies a payload.
+- `server/test-pattern.ts` is a synthetic source; replace it with a real capture.
+- `index.server.ts` pushes each source callback as a frame and stops the source when the
+  subscription's `signal` aborts.
+- `client/media-panel.tsx` decodes each frame and routes it by opcode.
+- `shared/frame-check.ts` is an RPC whose input is a `Uint8Array`: the panel uploads the picture
+  on screen and `server/frame-check.ts` reports its size and checksum.
@@ -0,0 +1,196 @@
+import { useRpc, useSubscription, type PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
+import type { RpcOutput } from "@getpaseo/plugin";
+import { type UseMutationResult, useMutation } from "@tanstack/react-query";
+import { useCallback, useMemo, useState } from "react";
+import { Pressable, StyleSheet, Text, View } from "react-native";
+import { checkFrame } from "../shared/frame-check";
+import {
+  decodeMediaFrame,
+  MediaOpcode,
+  mediaStream,
+  VIDEO,
+  type MediaFrame,
+} from "../shared/media-frames";
+
+interface Playback {
+  picture: Uint8Array | null;
+  level: number;
+  videoFrames: number;
+  keyframes: number;
+  audioChunks: number;
+  bytes: number;
+}
+
+const EMPTY: Playback = {
+  picture: null,
+  level: 0,
+  videoFrames: 0,
+  keyframes: 0,
+  audioChunks: 0,
+  bytes: 0,
+};
+
+export function MediaPanel({ theme, layout }: PluginWorkspacePanelProps) {
+  const styles = useStyles(theme, layout.compact);
+  const [playback, setPlayback] = useState(EMPTY);
+  const subscription = useSubscription(mediaStream, { source: "test-pattern" }, (bytes) => {
+    const frame = decodeMediaFrame(bytes);
+    if (frame) setPlayback((current) => play(current, frame, bytes.byteLength));
+  });
+  return (
+    <View style={styles.screen}>
+      <Text style={styles.title}>Test pattern</Text>
+      <Text style={styles.muted}>
+        {subscription.status === "error" ? subscription.error.message : subscription.status}
+      </Text>
+      <Picture pixels={playback.picture} cellSize={layout.compact ? 14 : 20} />
+      <LevelMeter level={playback.level} styles={styles} />
+      <Text style={styles.muted}>
+        {playback.videoFrames} video frames ({playback.keyframes} keyframes), {playback.audioChunks}{" "}
+        audio chunks, {(playback.bytes / 1024).toFixed(0)} KiB
+      </Text>
+      <SendFrameBack picture={playback.picture} styles={styles} />
+    </View>
+  );
+}
+
+/** Uploads the picture on screen and shows what the daemon received. */
+function SendFrameBack({
+  picture,
+  styles,
+}: {
+  picture: Uint8Array | null;
+  styles: ReturnType<typeof useStyles>;
+}) {
+  const sendFrame = useRpc(checkFrame);
+  const check = useMutation({ mutationFn: sendFrame });
+  const { mutate } = check;
+  const send = useCallback(() => {
+    if (picture) mutate(picture);
+  }, [mutate, picture]);
+  return (
+    <View style={styles.upload}>
+      <Pressable
+        accessibilityRole="button"
+        disabled={!picture || check.isPending}
+        onPress={send}
+        style={styles.button}
+      >
+        <Text style={styles.buttonText}>Send this frame back</Text>
+      </Pressable>
+      <Text style={styles.muted}>{describeCheck(check)}</Text>
+    </View>
+  );
+}
+
+function describeCheck(
+  check: UseMutationResult<RpcOutput<typeof checkFrame>, Error, Uint8Array>,
+): string {
+  if (check.status === "error") return check.error.message;
+  if (check.status === "success")
+    return `The daemon received ${check.data.bytes} bytes, sha256 ${check.data.sha256.slice(0, 12)}`;
+  return check.status === "pending" ? "Sending…" : "";
+}
+
+function play(current: Playback, frame: MediaFrame, bytes: number): Playback {
+  if (frame.opcode === MediaOpcode.Audio)
+    return {
+      ...current,
+      level: audioLevel(frame.payload),
+      audioChunks: current.audioChunks + 1,
+      bytes: current.bytes + bytes,
+    };
+  return {
+    ...current,
+    picture: frame.payload,
+    videoFrames: current.videoFrames + 1,
+    keyframes: current.keyframes + (frame.opcode === MediaOpcode.Keyframe ? 1 : 0),
+    bytes: current.bytes + bytes,
+  };
+}
+
+function audioLevel(samples: Uint8Array): number {
+  const view = new DataView(samples.buffer, samples.byteOffset, samples.byteLength);
+  let sum = 0;
+  const count = samples.byteLength / 2;
+  for (let index = 0; index < count; index += 1) sum += view.getInt16(index * 2, true) ** 2;
+  return Math.min(1, Math.sqrt(sum / Math.max(1, count)) / 16384);
+}
+
+function LevelMeter({ level, styles }: { level: number; styles: ReturnType<typeof useStyles> }) {
+  const fill = useMemo(
+    () => [styles.meter, { width: `${Math.round(level * 100)}%` as const }],
+    [level, styles],
+  );
+  return (
+    <View style={styles.meterTrack}>
+      <View style={fill} />
+    </View>
+  );
+}
+
+function Picture({ pixels, cellSize }: { pixels: Uint8Array | null; cellSize: number }) {
+  const rows = useMemo(() => pictureRows(pixels, cellSize), [pixels, cellSize]);
+  return (
+    <View accessibilityLabel="Test pattern video">
+      {rows.map((row) => (
+        <View key={row.key} style={pictureStyles.row}>
+          {row.cells.map((cell) => (
+            <View key={cell.key} style={cell.style} />
+          ))}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+/** One style per pixel, row by row. */
+function pictureRows(pixels: Uint8Array | null, cellSize: number) {
+  const rows = [];
+  for (let y = 0; y < VIDEO.height; y += 1) {
+    const cells = [];
+    for (let x = 0; x < VIDEO.width; x += 1) {
+      const offset = (y * VIDEO.width + x) * 3;
+      const backgroundColor = pixels
+        ? `rgb(${pixels[offset]}, ${pixels[offset + 1]}, ${pixels[offset + 2]})`
+        : "transparent";
+      cells.push({ key: `${x}`, style: { width: cellSize, height: cellSize, backgroundColor } });
+    }
+    rows.push({ key: `${y}`, cells });
+  }
+  return rows;
+}
+
+const pictureStyles = StyleSheet.create({ row: { flexDirection: "row" } });
+
+function useStyles(theme: PluginWorkspacePanelProps["theme"], compact: boolean) {
+  return useMemo(
+    () =>
+      StyleSheet.create({
+        screen: {
+          flex: 1,
+          padding: compact ? 16 : 24,
+          gap: 12,
+          backgroundColor: theme.colors.surface0,
+        },
+        title: { color: theme.colors.foreground, fontSize: 18, fontWeight: "600" },
+        muted: { color: theme.colors.foregroundMuted },
+        meterTrack: {
+          height: 8,
+          borderRadius: 4,
+          overflow: "hidden",
+          backgroundColor: theme.colors.surface2,
+        },
+        meter: { height: 8, backgroundColor: theme.colors.accent },
+        upload: { gap: 8, alignItems: "flex-start" },
+        button: {
+          paddingVertical: 8,
+          paddingHorizontal: 14,
+          borderRadius: 8,
+          backgroundColor: theme.colors.accent,
+        },
+        buttonText: { color: theme.colors.accentForeground },
+      }),
+    [theme, compact],
+  );
+}
@@ -0,0 +1,22 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { MediaPanel } from "./client/media-panel";
+
+export default function contribute(client: PluginClientContext) {
+  client.addWorkspacePanel({
+    id: "media",
+    title: "Media stream",
+    icon: "MonitorPlay",
+    context: "workspace",
+    Component: MediaPanel,
+  });
+  client.addCommandCenterItem({
+    id: "open-media",
+    title: "Open media stream",
+    icon: "MonitorPlay",
+    context: "workspace",
+    onSelect({ openPanel }) {
+      openPanel("media");
+    },
+  });
+  return () => {};
+}
@@ -0,0 +1,27 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import { describeFrame } from "./server/frame-check";
+import { openTestPattern } from "./server/test-pattern";
+import { checkFrame } from "./shared/frame-check";
+import { encodeMediaFrame, MediaOpcode, mediaStream } from "./shared/media-frames";
+
+export default function contribute(server: PluginServerContext) {
+  // Two streams share one subscription; each frame's opcode says which one it belongs to.
+  server.handle(mediaStream, (_input, { push, signal }) => {
+    const source = openTestPattern({
+      video: (pixels, timestampMs, keyframe) =>
+        void push(
+          encodeMediaFrame({
+            opcode: keyframe ? MediaOpcode.Keyframe : MediaOpcode.Video,
+            timestampMs,
+            payload: pixels,
+          }),
+        ),
+      audio: (samples, timestampMs) =>
+        void push(encodeMediaFrame({ opcode: MediaOpcode.Audio, timestampMs, payload: samples })),
+    });
+    signal.addEventListener("abort", () => source.close(), { once: true });
+  });
+  // A Uint8Array input arrives as the bytes the panel sent.
+  server.handle(checkFrame, describeFrame);
+  return () => {};
+}
@@ -0,0 +1,6 @@
+{
+  "id": "media-stream",
+  "requirements": {
+    "paseo": ">=0.15.0-beta.2"
+  }
+}
@@ -0,0 +1,7 @@
+import { createHash } from "node:crypto";
+import type { RpcInput, RpcOutput } from "@getpaseo/plugin";
+import type { checkFrame } from "../shared/frame-check";
+
+export function describeFrame(frame: RpcInput<typeof checkFrame>): RpcOutput<typeof checkFrame> {
+  return { bytes: frame.byteLength, sha256: createHash("sha256").update(frame).digest("hex") };
+}
@@ -0,0 +1,44 @@
+import { AUDIO, VIDEO } from "../shared/media-frames";
+
+export interface MediaSourceHandlers {
+  video(pixels: Uint8Array, timestampMs: number, keyframe: boolean): void;
+  audio(samples: Uint8Array, timestampMs: number): void;
+}
+
+/** A synthetic source: a moving gradient and a tone that rises and falls. */
+export function openTestPattern(handlers: MediaSourceHandlers): { close(): void } {
+  const started = Date.now();
+  let frame = 0;
+  let sample = 0;
+  const video = setInterval(() => {
+    const pixels = new Uint8Array(VIDEO.width * VIDEO.height * 3);
+    for (let y = 0; y < VIDEO.height; y += 1)
+      for (let x = 0; x < VIDEO.width; x += 1) {
+        const offset = (y * VIDEO.width + x) * 3;
+        pixels[offset] = ((x + frame) * 16) % 256;
+        pixels[offset + 1] = (y * 28) % 256;
+        pixels[offset + 2] = ((x + y + frame) * 8) % 256;
+      }
+    handlers.video(pixels, Date.now() - started, frame % VIDEO.keyframeInterval === 0);
+    frame += 1;
+  }, 1000 / VIDEO.framesPerSecond);
+  const audio = setInterval(() => {
+    const count = (AUDIO.sampleRate * AUDIO.chunkMs) / 1000;
+    const samples = new Uint8Array(count * 2);
+    const view = new DataView(samples.buffer);
+    const amplitude = 8000 + 7000 * Math.sin((Date.now() - started) / 700);
+    for (let index = 0; index < count; index += 1, sample += 1)
+      view.setInt16(
+        index * 2,
+        amplitude * Math.sin((2 * Math.PI * 440 * sample) / AUDIO.sampleRate),
+        true,
+      );
+    handlers.audio(samples, Date.now() - started);
+  }, AUDIO.chunkMs);
+  return {
+    close() {
+      clearInterval(video);
+      clearInterval(audio);
+    },
+  };
+}
@@ -0,0 +1,9 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+/** Sends one frame back to the daemon, which reports what arrived. */
+export const checkFrame = defineRpc({
+  name: "media.frame.check",
+  input: z.instanceof(Uint8Array),
+  output: z.object({ bytes: z.number(), sha256: z.string() }),
+});
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
paseo-bot[bot]	a078dd9bc5	Merge remote-tracking branch 'origin/main' into fix/gitlab-fork-checkout-8159	2026-11-02 09:54:43 +00:00
paseo-bot[bot]andquickwind	eecac800b6	fix(gitlab): identify fork checkouts by their source project Merge request authors do not necessarily own the source fork. Resolve its namespace and repository URLs before naming the checkout and configuring its push remote, retaining the target MR ref when the source returns 404. Co-authored-by: quickwind <wallacewei@live.cn>	2026-11-02 09:54:18 +00:00
paseo-bot[bot]	835bc49487	fix(claude): retain final usage when a turn fails (#8519 ) Non-success SDK results computed final token counts and cost but emitted only failure. Publish the existing usage update before the terminal event so clients retain completed work accounting. Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>	2026-11-02 08:59:37 +00:00
Mohamed Boudra	63302287fe	Fix plugin RPCs with schema transforms (#8550 ) * fix(plugins): parse RPC values once at the receiver Sending parsed values caused transforms to run again on incompatible schema outputs. Keep the wire values in schema-input form and parse only where consumed. * fix(plugins): let omitted RPC inputs reach schema defaults * fix(plugins): accept omitted RPC outputs for client defaults	2026-11-02 15:42:39 +07:00
paseo-bot[bot]andhadan8977	3e3a707f5a	Keep moved file paths and diffs intact in commit history (#8509 ) * fix(server): keep commit file paths when a file moves up a directory * test(git): open moved commit files through their listed path Verify commit history and diff lookup agree for files moved up a directory, with and without content edits. Co-authored-by: hadan8977 <zc-huang23@mails.tsinghua.edu.cn> * refactor(git): clarify compact rename handling and test cases Co-authored-by: hadan8977 <zc-huang23@mails.tsinghua.edu.cn> --------- Co-authored-by: hadan8977 <zc-huang23@mails.tsinghua.edu.cn> Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>	2026-11-02 07:58:56 +00:00
Mohamed Boudra	d4ac64f335	Let plugins stream live events and binary data to the app (#8527 ) * feat(plugins): stream events and bytes between plugins and the app Plugins can declare a subscription with defineSubscription, handle it with server.handle(contract, (input, { push, signal })), and listen from a surface with useSubscription or client.subscribe. A top-level Uint8Array in an event, an RPC output, or an RPC input crosses the wire as a binary frame (opcodes 0x20-0x2f) without JSON or base64; a nested one fails validation on the sender. Each subscriber runs its own handler, owned by the session that subscribed, so release, disconnect, plugin stop and reload need no plugin code. The runtime buffers pushes until the subscribe response has gone out, so a client never sees an event for a subscription it does not know yet. Gated on server_info.features.pluginSubscriptions; binary outputs reach only clients that advertise plugin_binary_payloads. * fix(plugins): close subscription gaps found in review - Losing daemon.manage now releases the session's plugin subscriptions; binary events bypass the outbound permission check, so streams would otherwise outlive the revocation. - A subscribe that times out sends unsubscribe, since the plugin may still start the handler after the daemon gave up. - The byte limit leaves room for the largest frame header and routing, and lives in assertPluginWireValue so events, outputs and inputs share it. - A release right after the host accepted keeps `ready` resolved, so a handler that returns at once reports closed rather than an error. - Session trace logging tolerates loggers without isLevelEnabled. * fix(plugins): withhold binary plugin results after plugin access is revoked A binary RPC output or event skipped the outbound permission check its JSON form passes, so an RPC in flight when daemon.manage was revoked still delivered its bytes. Each frame now checks the permission of the JSON message it stands in for. * test(plugins): cover subscriptions in a real browser instead of JSDOM The app subscription tests mounted hooks in JSDOM, which docs/testing.md rules out. The adapter and contract behavior is now a plain unit test, and a Playwright spec drives the diff-watch and media-stream examples: JSON events following file changes, streamed bytes, and an upload. * test(plugins): add the plain subscription unit test and the browser spec * fix(plugins): apply subscription schema transforms once Both ends parsed each subscription value, and the sender sent its parse output, so the receiver parsed a schema's output as fresh input. An event schema like z.string().transform((s) => s.length) closed the stream as invalid. The sender now validates and sends the value as given; the receiver's parse produces what the handler or callback sees. * fix(plugins): parse a subscription's input once in the plugin process server.handle wrapped subscription handlers in a second input parse, so a transforming input schema rejected its own parsed output before the handler ran.	2026-11-02 14:10:15 +07:00
Mohamed Boudra	70cb34927a	fix(app): keep question choices open until explicit navigation (#8525 ) Allow description clicks to select options while users copy text. Removing automatic advance keeps that interaction reversible; links remain independent and submission stays explicit.	2026-11-02 14:08:07 +07:00
paseo-bot[bot]	b280ca5355	fix(relay): keep local E2E tests independent of production upstream (#8514 ) Wrangler local mode retains deployment vars, so relay readiness probes were forwarded to an unavailable upstream instead of the local Durable Object. Clear that binding only in the E2E launcher. Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>	2026-11-02 13:59:19 +07:00
paseo-bot[bot]luke RoundRedDot	da8d58bfee	fix(plugins): preserve agent message provenance in timeline transforms (#8492 ) Co-authored-by: luke <luopeihuan@gmail.com> Co-authored-by: RoundRedDot <roundreddot@gmail.com> Co-authored-by: paseo-bot[bot] <266920839+paseo-bot[bot]@users.noreply.github.com>	2026-11-02 05:04:23 +00:00
quickwind	ea3f2ccd4a	fix(gitlab): resolve headOwnerLogin and local branch name for fork merge requests	2026-10-29 12:03:10 +11:00