test(app): reproduce ignored bare folder links

Retain the failed UI reproduction from issue #7206 without changing production behavior.

docs/android.md

@@ -205,12 +205,12 @@ adb exec-out screencap -p > screenshot.png
 
 Stable tag pushes like `v0.1.0` trigger:
 
-- The EAS GitHub app on Expo servers (iOS + Android production builds + store submit). There is no workflow file in this repo for it.
+- The EAS GitHub app on Expo servers, using `packages/app/.eas/workflows/release-mobile.yml` (iOS + Android production builds and distribution).
 - `.github/workflows/android-apk-release.yml` on GitHub Actions (APK asset on GitHub Release).
 
-iOS auto-submits to App Store review via a Fastlane lane after EAS uploads to TestFlight. Android auto-submits to the Play Store via EAS-managed credentials.
+iOS distributes the same build to external TestFlight testers and App Store review; see [Mobile builds (EAS)](release.md#mobile-builds-eas) for the review paths. Android auto-submits to the Play Store via EAS-managed credentials.
 
-Beta tags like `v0.1.1-beta.1` only trigger the GitHub APK workflow. They publish a GitHub prerelease APK for testing and do not submit to the stores.
+Beta tags like `v0.1.1-beta.1` trigger the GitHub APK workflow and EAS `Release iOS Beta`. They publish a GitHub prerelease APK and distribute iOS through TestFlight without submitting to production stores.
 
 `android-v*` tags also trigger only the GitHub APK workflow — useful when you want to ship an APK without going through stores. The GitHub APK workflow supports `workflow_dispatch` with an existing `tag` input so you can rebuild without cutting a new tag.
 

docs/mobile-testing.md

@@ -300,16 +300,33 @@ done
 
 ### Android audio focus interruptions
 
-Voice mode uses the custom `expo-two-way-audio` Android module, so incoming calls and other system audio owners must be tested with emulator/system commands, not a JS-only test. To verify that voice resume handles denied audio focus without crashing:
+Use native instrumentation for audio interruptions. JS-only tests cannot prove Android focus,
+input silencing, or route recovery. The module's `android/src/androidTest` suite runs through
+Gradle's `connectedDebugAndroidTest` task and uses real `AudioManager` and `AudioRecord` instances.
+Run the microphone-privacy cases on Android 12 or newer.
+
+Verify these distinct outcomes:
+
+- Dictation continues when another media owner takes permanent, temporary, or ducking focus.
+- Disabling microphone access pauses audio delivery without discarding the dictation. Enabling
+  access resumes it. Starting dictation while access is disabled waits for the same recovery.
+- Returning from music controls resumes dictation without pausing music again. Cancelling a
+  backgrounded recording must prevent the lifecycle callback from restarting it.
+- Two-way voice still stops coherently on focus loss. Keep the incoming-call check below: it
+  exercises denied focus during lifecycle resume, beyond an ordinary media takeover.
 
 ```bash
-adb shell am start -n sh.paseo/.MainActivity
-# Start voice mode in an existing composer, then background Paseo with Home.
+# Start voice mode in an existing composer, then background Paseo.
 adb emu gsm call 5551234
-# Foreground Paseo while the call is still ringing.
+# Foreground Paseo while the call is still ringing, then end the simulated call.
+adb emu gsm cancel 5551234
 ```
 
-Expected result: Paseo does not throw `RuntimeException: Audio focus request failed`; native audio reports an interruption and voice mode stops or pauses coherently.
+Expected result: no `RuntimeException: Audio focus request failed`, and voice mode stops or pauses
+coherently. Repeat with dictation: it must retain captured audio and recover microphone access.
+Use browser/device automation to operate the app; the commands above only control emulator telephony.
+
+This fix requires a rebuilt native app. An OTA update on an older binary retains legacy capture.
 
 ### Releasing the audio session when idle
 

docs/release.md

@@ -305,12 +305,14 @@ macOS 13 maps to Darwin 22. The two values use different version domains; do not
 iOS and Android store builds are not in `.github/workflows`. They are triggered by the EAS GitHub app the moment the `v*` tag is pushed:
 
 - **Android (Play Store)** — EAS builds with profile `production` and auto-submits to the Play Store via `eas submit` (EAS-managed credentials, no Fastlane).
-- **iOS (TestFlight + App Store)** — EAS builds with profile `production`, uploads to TestFlight, and a Fastlane lane submits the build for App Store review.
+- **iOS (TestFlight + App Store)** — EAS builds with profile `production`, uploads once through a `testflight` job, distributes the build to the `Paseo Beta` external group with Beta App Review submission, and a Fastlane lane submits that same build for App Store review.
 - **Android APK (GitHub Release asset)** — separate, via `.github/workflows/android-apk-release.yml`. This is the only Android-related workflow that lives in this repo.
 
 EAS uses the local app version source. `packages/app/app.config.js` derives the native version from the package version. Android `versionCode` is `major * 1_000_000 + minor * 1_000 + patch`. iOS reserves 1,000 build slots per app version: beta `N` uses slot `N`, and stable uses slot `999`. For example, `0.2.6-beta.2` appears in App Store Connect as version `0.2.6` build `2006002`; stable uses build `2006999`. Rebuilding the same tag produces the same native build number; if a store has already accepted a binary and you need a different binary, cut the next beta or patch instead of relying on EAS remote auto-increment.
 
-Beta tags run `Release iOS Beta`. The workflow uploads the build to TestFlight, distributes it to the persistent `Paseo Beta` external group, and submits it for Beta App Review. Testers and the group are managed once in App Store Connect; releases require no dashboard action.
+Stable tags run `Release Mobile`; beta tags run `Release iOS Beta`. Both distribute to the persistent `Paseo Beta` external group and submit for Beta App Review, so testers receive stable releases as well as betas. Testers, the group, and required TestFlight test information are managed once in App Store Connect.
+
+Stable iOS releases use one binary for two Apple review paths: Beta App Review for external TestFlight distribution and App Store review. [Apple says](https://developer.apple.com/help/app-store-connect/test-a-beta-version/invite-external-testers) the first submitted build requires a full TestFlight review; later builds for the same version might not. Do not assume a stable patch skips review.
 
 There is no mobile-release workflow under `.github/workflows`. The EAS GitHub app reads the workflows under `packages/app/.eas/workflows` and handles tag triggering directly.
 
@@ -334,7 +336,7 @@ npx eas build:list --platform android --limit 5 --non-interactive --json
 # Inspect a specific build.
 npx eas build:view <build-id>
 
-# Inspect the full release workflow, including submit_ios, submit_android,
+# Inspect the full release workflow, including distribute_ios, submit_android,
 # and submit_ios_for_review.
 npx eas workflow:view <workflow-run-id> --json
 
@@ -347,17 +349,17 @@ npx eas build:view <build-id> --json | jq '.logFiles[]'
 
 A build's `gitCommitHash` must match the release tag commit. `status` walks through `NEW` → `IN_QUEUE` → `IN_PROGRESS` → `FINISHED` (or `ERRORED`/`CANCELED`). The EAS workflow run's `gitCommitHash` and `trigger` must also match the release tag.
 
-Once a build is `FINISHED`, EAS still has release-critical work to do: Android must submit to the Play Store, and iOS must upload to TestFlight **and** submit the build for App Store review. The release is not done until all platforms are on their way through the stores.
+Once a build is `FINISHED`, EAS still has release-critical work to do: Android must submit to the Play Store, and iOS must distribute to the external TestFlight group with Beta App Review submission **and** submit the same build for App Store review. The release is not done until all platforms are on their way through the stores.
 
 For the `Release Mobile` EAS workflow, these jobs must pass:
 
 - `build_ios` — iOS binary built
-- `submit_ios` — iOS binary uploaded to App Store Connect/TestFlight
+- `distribute_ios` — iOS binary uploaded once, added to `Paseo Beta`, and submitted for Beta App Review
 - `submit_ios_for_review` — iOS build submitted for App Store review via Fastlane
 - `build_android` — Android store binary built
 - `submit_android` — Android binary submitted to the Play Store
 
-Do not treat `build_ios: SUCCESS` or `submit_ios: SUCCESS` as a completed iOS release. `submit_ios_for_review: FAILURE` means the iOS release is blocked even if the build is visible in TestFlight.
+Do not treat `build_ios: SUCCESS` or `distribute_ios: SUCCESS` as a completed iOS release. `submit_ios_for_review: FAILURE` means the iOS release is blocked even if the build is visible in TestFlight.
 
 To confirm the submission landed, inspect the EAS workflow with `npx eas workflow:view <workflow-run-id> --json`. App Store Connect (review state for the matching version/build) and the Play Console track are the final ground truth.
 
@@ -380,8 +382,9 @@ Windows, and Android APK assets are present along with the channel manifests
 (`latest-mac.yml`, `latest-linux.yml`, and `latest.yml` for stable;
 `beta-mac.yml`, `beta-linux.yml`, and `beta.yml` for beta).
 
-For stable releases, also confirm every required mobile build, upload, store
-submission, and review-submission job for the release commit. For betas, confirm
+For stable releases, also confirm every required mobile build, external
+TestFlight distribution, Beta App Review submission, and store submission job
+for the release commit. For betas, confirm
 the beta EAS workflow completed its TestFlight distribution and Beta App Review
 path. Delete the heartbeat only after every applicable checklist item passes,
 then report the release as shipped.
@@ -396,7 +399,7 @@ Pattern:
   "timezone": "UTC",
   "maxRuns": 120,
   "expiresIn": "24h",
-  "prompt": "Resume the vX.Y.Z release babysit for commit <sha>. Check npm tags; every GitHub Actions run for the release branch and tag; the published GitHub Release body, expected desktop/APK assets, and channel manifests; the Docker image; and the matching EAS workflow. Completion requires every applicable checklist item. For stable, require build_ios, submit_ios, submit_ios_for_review, build_android, and submit_android to succeed. For beta, require the beta TestFlight distribution and Beta App Review path. If work is pending, wait for the next heartbeat. If a failure can be retried safely for the same version, follow the failed-release procedure; otherwise report the blocker. When every applicable completion-checklist item passes, delete THIS heartbeat, report shipped, and stop.",
+  "prompt": "Resume the vX.Y.Z release babysit for commit <sha>. Check npm tags; every GitHub Actions run for the release branch and tag; the published GitHub Release body, expected desktop/APK assets, and channel manifests; the Docker image; and the matching EAS workflow. Completion requires every applicable checklist item. For stable, require build_ios, distribute_ios (Paseo Beta external distribution and Beta App Review submission), submit_ios_for_review, build_android, and submit_android to succeed. For beta, require the beta TestFlight distribution and Beta App Review path. If work is pending, wait for the next heartbeat. If a failure can be retried safely for the same version, follow the failed-release procedure; otherwise report the blocker. When every applicable completion-checklist item passes, delete THIS heartbeat, report shipped, and stop.",
 }
 ```
 
@@ -680,7 +683,7 @@ Every entry covers `previous stable release → release source`: first beta, lat
 - [ ] GitHub `Release Notes Sync` is green and the release body matches the stable changelog entry
 - [ ] EAS `Release Mobile` workflow for the same tag is green
 - [ ] EAS iOS `build_ios` completes for the same tag
-- [ ] EAS iOS `submit_ios` succeeds, uploading the build to App Store Connect/TestFlight
+- [ ] EAS iOS `distribute_ios` succeeds, uploading the binary once, distributing it to `Paseo Beta`, and submitting it for Beta App Review
 - [ ] EAS iOS `submit_ios_for_review` succeeds, putting the build into App Store review
 - [ ] EAS Android `build_android` completes for the same tag
 - [ ] EAS Android `submit_android` succeeds, putting the build on its Play Store track

nix/npm-deps.hash

@@ -1 +1 @@
-sha256-Sw9WSOnvebpXgty0WACJrRq+pkKuynLMxJg6D/SnyRk=
+sha256-1WmrHvE68Lzyil4On7xtsPMQTODXZ3Jb3/juUg3nHi4=

packages/app/.eas/workflows/release-mobile.yml

@@ -23,13 +23,16 @@ jobs:
       platform: android
       profile: production
 
-  submit_ios:
-    name: Submit iOS
+  distribute_ios:
+    name: Distribute iOS to TestFlight
     needs: [build_ios]
-    type: submit
+    type: testflight
     params:
       build_id: ${{ needs.build_ios.outputs.build_id }}
       profile: production
+      external_groups:
+        - Paseo Beta
+      submit_beta_review: true
 
   submit_android:
     name: Submit Android
@@ -41,7 +44,7 @@ jobs:
 
   submit_ios_for_review:
     name: Submit iOS for App Store review
-    needs: [build_ios, submit_ios]
+    needs: [build_ios, distribute_ios]
     environment: production
     runs_on: macos-medium
     steps:

packages/app/e2e/browser/bare-folder-links.repro.spec.ts

@@ -0,0 +1,37 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { expect, test, type Page } from "../support/fixtures";
+import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+
+async function openFolderLink(page: Page) {
+  await page
+    .getByTestId("assistant-message")
+    .getByRole("link", { name: "Open folder", exact: true })
+    .click();
+}
+
+async function expectFolderContents(page: Page) {
+  await expect(page.getByTestId("file-explorer-tree-scroll")).toBeVisible();
+  await expect(
+    page.getByTestId("file-explorer-tree-scroll").getByText("guide.md", { exact: true }),
+  ).toBeVisible();
+}
+
+test("an explicit Markdown folder link without ./ opens its contents", async ({ page }) => {
+  const session = await seedMockAgentWorkspace({
+    repoPrefix: "bare-folder-link-repro-",
+    title: "Bare folder link reproduction",
+    initialPrompt: "Show the folder link",
+    featureValues: { mockAssistantResponse: "[Open folder](docs/guides)" },
+  });
+  try {
+    await mkdir(path.join(session.cwd, "docs/guides"), { recursive: true });
+    await writeFile(path.join(session.cwd, "docs/guides/guide.md"), "# Folder link destination\n");
+    await session.client.waitForFinish(session.agentId, 30_000);
+    await openAgentRoute(page, session);
+    await openFolderLink(page);
+    await expectFolderContents(page);
+  } finally {
+    await session.cleanup();
+  }
+});

packages/app/e2e/browser/open-project-scroll.spec.ts

@@ -0,0 +1,42 @@
+import { type Page } from "@playwright/test";
+import { test, expect } from "../support/fixtures";
+
+async function openProjectHome(page: Page) {
+  await page.goto("/open-project");
+  await expect(page.getByText("Add a project", { exact: true })).toBeVisible();
+}
+
+async function scrollToHomeFooter(page: Page) {
+  await page.mouse.move(160, 350);
+  await page.mouse.wheel(0, 1500);
+}
+
+async function expectHomeActionsReachable(page: Page) {
+  const providers = page.getByTestId("open-project-setup-providers");
+  const community = page.getByRole("button", { name: "Community", exact: true });
+  await expect(providers).toBeInViewport({ ratio: 1 });
+  await expect(community).toBeInViewport({ ratio: 1 });
+  const providerBounds = await providers.boundingBox();
+  const communityBounds = await community.boundingBox();
+  expect(providerBounds).not.toBeNull();
+  expect(communityBounds).not.toBeNull();
+  expect(communityBounds!.y).toBeGreaterThanOrEqual(providerBounds!.y + providerBounds!.height);
+}
+
+test("home actions remain reachable on a short phone screen", async ({ page }, testInfo) => {
+  await page.setViewportSize({ width: 320, height: 568 });
+  await openProjectHome(page);
+  await scrollToHomeFooter(page);
+  await expectHomeActionsReachable(page);
+  await page.screenshot({ path: testInfo.outputPath("home-scrolled.png") });
+});
+
+test("home actions fit on a desktop screen without overlap", async ({ page }) => {
+  await page.setViewportSize({ width: 1280, height: 900 });
+  await openProjectHome(page);
+  await expectHomeActionsReachable(page);
+  await expect(page.getByTestId("open-project-setup-providers")).toHaveCSS(
+    "-webkit-app-region",
+    "none",
+  );
+});

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

@@ -1,5 +1,16 @@
+import { fork } from "node:child_process";
+import path from "node:path";
+import { expect } from "@playwright/test";
+import { z } from "zod";
 import { test } from "../support/fixtures";
-import { openAgentRoute, seedMockAgentWorkspace } from "../support/helpers/mock-agent";
+import { expectVisibleAgentSurfacesIdle } from "../support/helpers/agent-stream";
+import { buildSeededHost } from "../support/helpers/daemon-registry";
+import { killProcessTree } from "../support/helpers/spawn-node";
+import {
+  buildAgentRoute,
+  openAgentRoute,
+  seedMockAgentWorkspace,
+} from "../support/helpers/mock-agent";
 import {
   chooseQuestionOption,
   continueToNextQuestion,
@@ -130,3 +141,204 @@ test.describe("Question prompt pagination", () => {
     }
   });
 });
+
+const questionDaemonMessage = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("ready"), port: z.number(), serverId: z.string() }),
+  z.object({
+    type: z.literal("attempt"),
+    requestId: z.string(),
+    response: z.unknown(),
+    sessionId: z.string(),
+  }),
+  z.object({
+    type: z.literal("resolved"),
+    requestId: z.string(),
+    response: z.unknown(),
+    sessionId: z.string(),
+    pendingRequestIds: z.array(z.string()),
+  }),
+  z.object({ type: z.literal("error"), error: z.string() }),
+]);
+
+type QuestionResponseAttempt = Extract<z.infer<typeof questionDaemonMessage>, { type: "attempt" }>;
+
+type QuestionResolution = Extract<z.infer<typeof questionDaemonMessage>, { type: "resolved" }>;
+
+interface QuestionRetryControl {
+  attempts: QuestionResponseAttempt[];
+  resolutions: QuestionResolution[];
+  releaseFirstResponse(): void;
+}
+
+const retryTest = test.extend<{
+  questionClient: QuestionRetryControl;
+}>({
+  questionClient: async ({ page }, provide, testInfo) => {
+    const serverDir = path.resolve(__dirname, "../../../server");
+    const child = fork(path.join(serverDir, "src/server/test-utils/question-response-daemon.ts"), {
+      cwd: serverDir,
+      execArgv: ["--import", "tsx"],
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+    const output: string[] = [];
+    child.stdout?.on("data", (data: Buffer) => output.push(data.toString()));
+    child.stderr?.on("data", (data: Buffer) => output.push(data.toString()));
+    const ready = Promise.withResolvers<{ port: number; serverId: string }>();
+    const attempts: QuestionResponseAttempt[] = [];
+    const resolutions: QuestionResolution[] = [];
+    child.on("message", (message: unknown) => {
+      const parsed = questionDaemonMessage.parse(message);
+      switch (parsed.type) {
+        case "ready":
+          ready.resolve(parsed);
+          break;
+        case "attempt":
+          attempts.push(parsed);
+          break;
+        case "resolved":
+          resolutions.push(parsed);
+          break;
+        case "error":
+          ready.reject(new Error(parsed.error));
+          break;
+      }
+    });
+    child.once("exit", (code) => ready.reject(new Error(`Question daemon exited with ${code}`)));
+    const timeout = setTimeout(
+      () => ready.reject(new Error("Question daemon startup timed out")),
+      20_000,
+    );
+    try {
+      const daemon = await ready.promise;
+      clearTimeout(timeout);
+      const session = await seedMockAgentWorkspace({
+        port: daemon.port,
+        repoPrefix: "question-retry-",
+        title: "Question response retry",
+        initialPrompt: "Emit synthetic questions.",
+      });
+      try {
+        await page.goto("/", { waitUntil: "commit" });
+        const serverId = daemon.serverId;
+        const host = buildSeededHost({
+          serverId,
+          endpoint: `127.0.0.1:${daemon.port}`,
+          label: "Question retry host",
+          nowIso: new Date().toISOString(),
+        });
+        await page.evaluate((extraHost) => {
+          localStorage.setItem("@paseo:e2e-extra-hosts", JSON.stringify([extraHost]));
+        }, host);
+        await page.goto(buildAgentRoute(session.workspaceId, session.agentId, serverId), {
+          waitUntil: "commit",
+        });
+        await waitForQuestionPrompt(page, 120_000);
+        await provide({ attempts, resolutions, releaseFirstResponse: () => child.send("release") });
+      } finally {
+        await session.cleanup();
+      }
+    } finally {
+      clearTimeout(timeout);
+      await killProcessTree(child);
+      if (testInfo.status !== testInfo.expectedStatus) {
+        await testInfo.attach("question-daemon", {
+          body: output.join(""),
+          contentType: "text/plain",
+        });
+      }
+    }
+  },
+});
+
+retryTest(
+  "failed question submission preserves answers and allows retry",
+  async ({ page, questionClient }, testInfo) => {
+    retryTest.setTimeout(180_000);
+    const card = page.getByTestId("question-form-card");
+    await chooseQuestionOption(page, "App");
+    await chooseQuestionOption(page, "Behind feature flag");
+    await fillQuestionAnswer(page, {
+      question: SUCCESS_QUESTION,
+      answer: "Preserve my answers after a failed submission.",
+    });
+    await card.getByRole("button", { name: "Submit" }).click();
+    await expect(card.getByRole("progressbar")).toBeVisible();
+    await expectQuestionPrimaryActionDisabled(page, "Submit");
+    await expect(card.getByRole("button", { name: "Dismiss" })).toBeDisabled();
+    await expect(card.getByRole("tab").first()).toBeDisabled();
+    await expect(card.getByRole("textbox")).not.toBeEditable();
+    questionClient.releaseFirstResponse();
+    await expectQuestionPrimaryActionEnabled(page, "Submit");
+    await card.screenshot({ path: testInfo.outputPath("submission-failed.png") });
+    await expect(card.getByRole("alert")).toHaveText("Could not send your response. Try again.");
+    await expect(card.getByRole("progressbar")).toHaveCount(0);
+    await expect(card.getByRole("button", { name: "Submit" })).toHaveText("Submit");
+    await expectQuestionDismissEnabled(page);
+    await openQuestion(page, { index: 1, total: TOTAL_QUESTIONS });
+    await expectQuestionOptionSelected(page, "App");
+    await openQuestion(page, { index: 2, total: TOTAL_QUESTIONS });
+    await expectQuestionOptionSelected(page, "Behind feature flag");
+    await openQuestion(page, { index: 3, total: TOTAL_QUESTIONS });
+    await expect(card.getByRole("textbox")).toHaveValue(
+      "Preserve my answers after a failed submission.",
+    );
+    await submitQuestionAnswers(page);
+    await expectVisibleAgentSurfacesIdle(page);
+    await expect.poll(() => questionClient.attempts.length).toBe(2);
+    expect(questionClient.attempts[1]).toEqual(questionClient.attempts[0]);
+    await expect
+      .poll(() => questionClient.resolutions)
+      .toEqual([{ ...questionClient.attempts[1], type: "resolved", pendingRequestIds: [] }]);
+    expect(questionClient.attempts[1].response).toMatchObject({
+      behavior: "allow",
+      updatedInput: {
+        answers: {
+          surface: "App",
+          rollout: "Behind feature flag",
+          success: "Preserve my answers after a failed submission.",
+        },
+      },
+    });
+    await page.screenshot({ path: testInfo.outputPath("submission-retried.png") });
+  },
+);
+
+retryTest(
+  "failed question dismissal allows an immediate retry",
+  async ({ page, questionClient }, testInfo) => {
+    retryTest.setTimeout(180_000);
+    const card = page.getByTestId("question-form-card");
+    questionClient.releaseFirstResponse();
+    await chooseQuestionOption(page, "App");
+    await chooseQuestionOption(page, "Behind feature flag");
+    await fillQuestionAnswer(page, {
+      question: SUCCESS_QUESTION,
+      answer: "Start with the internal team.",
+    });
+    await card.getByRole("button", { name: "Dismiss" }).click();
+    await expect(card.getByRole("alert")).toHaveText("Could not send your response. Try again.");
+    await expect(card.getByRole("progressbar")).toHaveCount(0);
+    await expect(card.getByRole("button", { name: "Dismiss" })).toHaveText("Dismiss");
+    await expectQuestionDismissEnabled(page);
+    await expectQuestionPrimaryActionEnabled(page, "Submit");
+    await card.screenshot({ path: testInfo.outputPath("dismissal-failed.png") });
+    await openQuestion(page, { index: 1, total: TOTAL_QUESTIONS });
+    await expectQuestionOptionSelected(page, "App");
+    await openQuestion(page, { index: 3, total: TOTAL_QUESTIONS });
+    await expect(card.getByRole("textbox")).toHaveValue("Start with the internal team.");
+    await expect(card.getByRole("alert")).toBeVisible();
+    await card.getByRole("button", { name: "Dismiss" }).click();
+    await expect(card).toHaveCount(0);
+    await expectVisibleAgentSurfacesIdle(page);
+    await expect.poll(() => questionClient.attempts.length).toBe(2);
+    expect(questionClient.attempts[1]).toEqual(questionClient.attempts[0]);
+    await expect
+      .poll(() => questionClient.resolutions)
+      .toEqual([{ ...questionClient.attempts[1], type: "resolved", pendingRequestIds: [] }]);
+    expect(questionClient.attempts[1].response).toEqual({
+      behavior: "deny",
+      message: "Dismissed by user",
+    });
+    await page.screenshot({ path: testInfo.outputPath("dismissal-retried.png") });
+  },
+);

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

@@ -1531,11 +1531,17 @@ function PermissionRequestCard({
   );
 
   if (request.kind === "question") {
+    const responseFailed =
+      permissionMutation.isError &&
+      permissionMutation.variables?.agentId === permission.agentId &&
+      permissionMutation.variables?.requestId === permission.request.id;
+    const responseError = responseFailed ? t("message.question.responseFailed") : null;
     return (
       <QuestionFormCard
         permission={permission}
         onRespond={handleResponse}
         isResponding={isResponding}
+        responseError={responseError}
       />
     );
   }

packages/app/src/audio/audio-engine-types.ts

@@ -2,6 +2,7 @@ export interface AudioEngineCallbacks {
   onCaptureData(pcm: Uint8Array): void;
   onVolumeLevel(level: number): void;
   onInterruption?(): void;
+  onCaptureAvailabilityChange?(available: boolean): void;
   onError?(error: Error): void;
 }
 
@@ -25,3 +26,8 @@ export interface AudioEngine {
   clearQueue(): void;
   isPlaying(): boolean;
 }
+
+export interface AudioEngineOptions {
+  traceLabel?: string;
+  captureMode?: "conversation" | "dictation";
+}

packages/app/src/audio/audio-engine.native.ts

@@ -1,4 +1,9 @@
-import type { AudioEngine, AudioEngineCallbacks, AudioPlaybackSource } from "./audio-engine-types";
+import type {
+  AudioEngine,
+  AudioEngineCallbacks,
+  AudioEngineOptions,
+  AudioPlaybackSource,
+} from "./audio-engine-types";
 
 import { createAudioPlayer, setAudioModeAsync } from "expo-audio";
 import { File, Paths } from "expo-file-system";
@@ -8,7 +13,7 @@ import { playPcm16 } from "./pcm";
 
 export function createAudioEngine(
   callbacks: AudioEngineCallbacks,
-  _options?: { traceLabel?: string },
+  options?: AudioEngineOptions,
 ): AudioEngine {
   const native = require("@getpaseo/expo-two-way-audio");
 
@@ -47,6 +52,12 @@ export function createAudioEngine(
   const interruptionSubscription = native.addExpoTwoWayAudioEventListener(
     "onAudioInterruption",
     (event: { data: string }) => {
+      if (event.data === "capture_paused" || event.data === "capture_resumed") {
+        if (refs.captureActive) {
+          callbacks.onCaptureAvailabilityChange?.(event.data === "capture_resumed");
+        }
+        return;
+      }
       if (event.data !== "blocked") {
         return;
       }
@@ -180,7 +191,10 @@ export function createAudioEngine(
       try {
         await ensureMicrophonePermission();
         await ensureInitialized();
-        const isRecording = native.toggleRecording(true);
+        const isRecording =
+          options?.captureMode === "dictation"
+            ? native.startDictation()
+            : native.toggleRecording(true);
         if (!isRecording) {
           throw new Error(
             "Microphone capture could not start because Android audio focus is unavailable.",
@@ -201,6 +215,7 @@ export function createAudioEngine(
       refs.captureActive = false;
       refs.muted = false;
       callbacks.onVolumeLevel(0);
+      callbacks.onCaptureAvailabilityChange?.(true);
       releaseSessionIfIdle();
     },
 

packages/app/src/audio/audio-engine.web.ts

@@ -1,6 +1,11 @@
 import { parsePcmSampleRate, resampleToPcm16 } from "./pcm";
 import { isElectronRuntime } from "@/desktop/host";
-import type { AudioEngine, AudioEngineCallbacks, AudioPlaybackSource } from "./audio-engine-types";
+import type {
+  AudioEngine,
+  AudioEngineCallbacks,
+  AudioEngineOptions,
+  AudioPlaybackSource,
+} from "./audio-engine-types";
 
 import { createPlaybackQueue } from "./playback";
 
@@ -46,7 +51,7 @@ async function decodeAudioData(context: AudioContext, buffer: ArrayBuffer): Prom
 
 export function createAudioEngine(
   callbacks: AudioEngineCallbacks,
-  _options?: { traceLabel?: string },
+  _options?: AudioEngineOptions,
 ): AudioEngine {
   const refs: {
     playbackContext: AudioContext | null;

packages/app/src/components/dictation-controls.tsx

@@ -87,7 +87,9 @@ export function DictationControls({
       <View style={styles.meterWrapper}>
         <VolumeMeter volume={volume} isMuted={false} isSpeaking={false} orientation="horizontal" />
       </View>
-      <Text style={timerTextStyle}>{formatDuration(duration)}</Text>
+      <Text style={timerTextStyle}>
+        {status === "paused" ? t("message.dictation.paused") : formatDuration(duration)}
+      </Text>
       <View style={styles.actionGroup}>
         <Pressable
           onPress={handleCancel}
@@ -210,6 +212,11 @@ export function DictationOverlay({
           />
           <Text style={overlayTimerTextStyle}>{formatDuration(duration)}</Text>
         </View>
+        {status === "paused" ? (
+          <Text numberOfLines={2} style={overlayTranscriptTextStyle}>
+            {t("message.dictation.paused")}
+          </Text>
+        ) : null}
         {isFailed ? (
           <Text numberOfLines={2} style={overlayTranscriptTextStyle}>
             {errorText

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

@@ -58,6 +58,7 @@ function mountCard(question: Record<string, unknown>) {
         permission={buildPermission(question)}
         onRespond={onRespond}
         isResponding={false}
+        responseError={null}
       />,
     ),
   );

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

@@ -1,3 +1,4 @@
+import { Alert } from "@/components/ui/alert";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import { useState, useCallback, useMemo, useRef, type RefObject } from "react";
 import { View, Text, Pressable, type PressableStateCallbackType } from "react-native";
@@ -27,6 +28,7 @@ interface QuestionFormCardProps {
   permission: PendingPermission;
   onRespond: (response: AgentPermissionResponse) => void;
   isResponding: boolean;
+  responseError: string | null;
 }
 
 const IS_WEB = isWeb;
@@ -339,7 +341,12 @@ function QuestionOtherInput({
   );
 }
 
-export function QuestionFormCard({ permission, onRespond, isResponding }: QuestionFormCardProps) {
+export function QuestionFormCard({
+  permission,
+  onRespond,
+  isResponding,
+  responseError,
+}: QuestionFormCardProps) {
   const { theme } = useUnistyles();
   const { t } = useTranslation();
   const isMobile = useIsCompactFormFactor();
@@ -438,7 +445,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
   ]);
 
   const handleDeny = useCallback(() => {
-    if (!questions) return;
+    if (!questions || isResponding) return;
     setRespondingAction("dismiss");
     if (shouldSubmitEmptyOnDismiss(questions)) {
       onRespond({
@@ -454,7 +461,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
       behavior: "deny",
       message: "Dismissed by user",
     });
-  }, [questions, onRespond, otherTexts, permission.request.input, selections]);
+  }, [questions, isResponding, onRespond, otherTexts, permission.request.input, selections]);
 
   const handleSelectQuestion = useCallback((index: number) => {
     setActiveQuestionIndex(index);
@@ -487,6 +494,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
     [theme.colors.surface2, theme.colors.surface1, theme.colors.borderAccent],
   );
 
+  const pendingAction = isResponding ? respondingAction : null;
   const primaryDisabled = isResponding || (isLastQuestion ? !allAnswered : !activeQuestionAnswered);
   const primaryActionLabel = isLastQuestion
     ? t("message.question.submit")
@@ -550,7 +558,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
   const dismissLabel = resolveDismissLabel(questions, t("common.actions.dismiss"));
   const selected = selections[resolvedActiveQuestionIndex] ?? new Set<number>();
   const otherText = otherTexts[resolvedActiveQuestionIndex] ?? "";
-  const showTextInput = activeQuestion ? questionShowsTextInput(activeQuestion) : false;
+  const showTextInput = questionShowsTextInput(questions[resolvedActiveQuestionIndex]);
 
   return (
     <View style={containerStyle} testID="question-form-card">
@@ -604,6 +612,8 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
         </View>
       ) : null}
 
+      {responseError ? <Alert variant="error" description={responseError} size="sm" /> : null}
+
       <View style={actionsContainerStyle}>
         <Pressable
           style={dismissButtonStyle}
@@ -613,7 +623,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
           accessibilityLabel={dismissLabel}
           testID="question-form-dismiss"
         >
-          {respondingAction === "dismiss" ? (
+          {pendingAction === "dismiss" ? (
             <LoadingSpinner size="small" color={theme.colors.foregroundMuted} />
           ) : (
             <View style={styles.actionContent}>
@@ -631,7 +641,7 @@ export function QuestionFormCard({ permission, onRespond, isResponding }: Questi
           accessibilityLabel={primaryActionLabel}
           testID="question-form-primary-action"
         >
-          {respondingAction === "submit" ? (
+          {pendingAction === "submit" ? (
             <LoadingSpinner size="small" color={theme.colors.accentForeground} />
           ) : (
             <View style={styles.actionContent}>

packages/app/src/hooks/use-dictation-audio-source.native.ts

@@ -14,6 +14,7 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
   const onErrorRef = useRef(config.onError);
   const onInterruptionRef = useRef(config.onInterruption);
   const [volume, setVolume] = useState(0);
+  const [isPaused, setIsPaused] = useState(false);
   const engineRef = useRef<ReturnType<typeof createAudioEngine> | null>(null);
 
   const getOrCreateEngine = useCallback(() => {
@@ -21,20 +22,24 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
       return engineRef.current;
     }
 
-    engineRef.current = createAudioEngine({
-      onCaptureData: (pcm) => {
-        onPcmSegmentRef.current(Buffer.from(pcm).toString("base64"));
+    engineRef.current = createAudioEngine(
+      {
+        onCaptureData: (pcm) => {
+          onPcmSegmentRef.current(Buffer.from(pcm).toString("base64"));
+        },
+        onVolumeLevel: (level) => {
+          setVolume(level);
+        },
+        onError: (error) => {
+          onErrorRef.current?.(error);
+        },
+        onInterruption: () => {
+          onInterruptionRef.current?.();
+        },
+        onCaptureAvailabilityChange: (available) => setIsPaused(!available),
       },
-      onVolumeLevel: (level) => {
-        setVolume(level);
-      },
-      onError: (error) => {
-        onErrorRef.current?.(error);
-      },
-      onInterruption: () => {
-        onInterruptionRef.current?.();
-      },
-    });
+      { captureMode: "dictation" },
+    );
     return engineRef.current;
   }, []);
 
@@ -67,5 +72,6 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
     start,
     stop,
     volume,
+    isPaused,
   };
 }

packages/app/src/hooks/use-dictation-audio-source.types.ts

@@ -8,4 +8,5 @@ export interface DictationAudioSource {
   start: () => Promise<void>;
   stop: () => Promise<void>;
   volume: number;
+  isPaused: boolean;
 }

packages/app/src/hooks/use-dictation-audio-source.web.ts

@@ -442,6 +442,7 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
       },
       stop,
       volume,
+      isPaused: false,
     }),
     [start, stop, volume],
   );

packages/app/src/hooks/use-dictation.shared.ts

@@ -1,6 +1,6 @@
 import { i18n } from "@/i18n/i18next";
 
-export type DictationStatus = "idle" | "recording" | "uploading" | "failed";
+export type DictationStatus = "idle" | "recording" | "paused" | "uploading" | "failed";
 
 export interface UseDictationOptions {
   client: import("@getpaseo/client/internal/daemon-client").DaemonClient | null;

packages/app/src/hooks/use-dictation.ts

@@ -461,7 +461,7 @@ export function useDictation(options: UseDictationOptions): UseDictationResult {
     volume: audio.volume,
     duration,
     error,
-    status,
+    status: status === "recording" && audio.isPaused ? "paused" : status,
     startDictation,
     cancelDictation,
     confirmDictation,

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

@@ -360,6 +360,7 @@ export const ar: TranslationResources = {
       details: "تفاصيل",
     },
     dictation: {
+      paused: "تمت مقاطعة الميكروفون. في انتظار الاستئناف…",
       start: "بدء الإملاء الصوتي",
       cancel: "إلغاء الإملاء",
       retry: "أعد محاولة الإملاء",
@@ -369,6 +370,7 @@ export const ar: TranslationResources = {
       failedRetry: "فشل الإملاء. اضغط على إعادة المحاولة.",
     },
     question: {
+      responseFailed: "تعذر إرسال ردك. حاول مرة أخرى.",
       submit: "يُقدِّم",
       next: "التالي",
       answerPlaceholder: "اكتب إجابتك...",

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

@@ -357,6 +357,7 @@ export const en = {
       details: "Details",
     },
     dictation: {
+      paused: "Microphone interrupted. Waiting to resume…",
       start: "Start voice dictation",
       cancel: "Cancel dictation",
       retry: "Retry dictation",
@@ -366,6 +367,7 @@ export const en = {
       failedRetry: "Dictation failed. Tap retry.",
     },
     question: {
+      responseFailed: "Could not send your response. Try again.",
       submit: "Submit",
       next: "Next",
       answerPlaceholder: "Type your answer...",

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

@@ -365,6 +365,7 @@ export const es: TranslationResources = {
       details: "Detalles",
     },
     dictation: {
+      paused: "Micrófono interrumpido. Esperando para reanudar…",
       start: "Iniciar dictado de voz",
       cancel: "Cancelar dictado",
       retry: "Reintentar el dictado",
@@ -374,6 +375,7 @@ export const es: TranslationResources = {
       failedRetry: "El dictado falló. Toca reintentar.",
     },
     question: {
+      responseFailed: "No se pudo enviar tu respuesta. Inténtalo de nuevo.",
       submit: "Entregar",
       next: "Siguiente",
       answerPlaceholder: "Escribe tu respuesta...",

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

@@ -365,6 +365,7 @@ export const fr: TranslationResources = {
       details: "Détails",
     },
     dictation: {
+      paused: "Microphone interrompu. En attente de reprise…",
       start: "Démarrer la dictée vocale",
       cancel: "Annuler la dictée",
       retry: "Relancer la dictée",
@@ -374,6 +375,7 @@ export const fr: TranslationResources = {
       failedRetry: "La dictée a échoué. Appuyez sur Réessayer.",
     },
     question: {
+      responseFailed: "Impossible d’envoyer votre réponse. Réessayez.",
       submit: "Envoyer",
       next: "Suivant",
       answerPlaceholder: "Saisissez votre réponse…",

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

@@ -365,6 +365,7 @@ export const ja: TranslationResources = {
       details: "詳細",
     },
     dictation: {
+      paused: "マイクが中断されました。再開を待っています…",
       start: "音声入力を開始",
       cancel: "音声入力をキャンセル",
       retry: "音声入力を再試行",
@@ -374,6 +375,7 @@ export const ja: TranslationResources = {
       failedRetry: "音声入力に失敗しました。再試行をタップしてください。",
     },
     question: {
+      responseFailed: "回答を送信できませんでした。もう一度お試しください。",
       submit: "送信",
       next: "次へ",
       answerPlaceholder: "回答を入力...",

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

@@ -361,6 +361,7 @@ export const ko: TranslationResources = {
       details: "세부 정보",
     },
     dictation: {
+      paused: "마이크가 중단되었습니다. 재개를 기다리는 중…",
       start: "음성 받아쓰기 시작",
       cancel: "받아쓰기 취소",
       retry: "받아쓰기 다시 시도",
@@ -370,6 +371,7 @@ export const ko: TranslationResources = {
       failedRetry: "받아쓰기에 실패했습니다. 다시 시도하려면 누르세요.",
     },
     question: {
+      responseFailed: "응답을 보내지 못했습니다. 다시 시도해 주세요.",
       submit: "제출",
       next: "다음",
       answerPlaceholder: "답변을 입력하세요...",

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

@@ -364,6 +364,7 @@ export const ptBR: TranslationResources = {
       details: "Detalhes",
     },
     dictation: {
+      paused: "Microfone interrompido. Aguardando para retomar…",
       start: "Iniciar ditado por voz",
       cancel: "Cancelar ditado",
       retry: "Tentar ditado novamente",
@@ -373,6 +374,7 @@ export const ptBR: TranslationResources = {
       failedRetry: "Falha no ditado. Toque para tentar novamente.",
     },
     question: {
+      responseFailed: "Não foi possível enviar sua resposta. Tente novamente.",
       submit: "Enviar",
       next: "Próximo",
       answerPlaceholder: "Digite sua resposta...",

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

@@ -364,6 +364,7 @@ export const ru: TranslationResources = {
       details: "Подробности",
     },
     dictation: {
+      paused: "Микрофон прерван. Ожидание возобновления…",
       start: "Начать диктовку голосом",
       cancel: "Отменить диктовку",
       retry: "Повторить диктовку",
@@ -373,6 +374,7 @@ export const ru: TranslationResources = {
       failedRetry: "Диктовка не удалась. Нажмите «Повторить».",
     },
     question: {
+      responseFailed: "Не удалось отправить ответ. Попробуйте ещё раз.",
       submit: "Отправить",
       next: "Далее",
       answerPlaceholder: "Введите ответ...",

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

@@ -360,6 +360,7 @@ export const zhCN: TranslationResources = {
       details: "详情",
     },
     dictation: {
+      paused: "麦克风已中断，正在等待恢复…",
       start: "开始语音听写",
       cancel: "取消听写",
       retry: "重试听写",
@@ -369,6 +370,7 @@ export const zhCN: TranslationResources = {
       failedRetry: "听写失败。点按重试。",
     },
     question: {
+      responseFailed: "未能发送你的回复，请重试。",
       submit: "提交",
       next: "下一步",
       answerPlaceholder: "输入你的回答...",

packages/app/src/screens/open-project-screen.tsx

@@ -1,7 +1,7 @@
 import { useHosts, useHostRuntimeLastError } from "@/runtime/host-runtime";
 import { useCallback, useEffect, useState, type ComponentType } from "react";
 import { useTranslation } from "react-i18next";
-import { View, Text, Pressable } from "react-native";
+import { View, Text, Pressable, ScrollView } from "react-native";
 import { StyleSheet, useUnistyles } from "react-native-unistyles";
 import { useRouter } from "expo-router";
 import { FolderOpen, Inbox, Plug, Smartphone } from "lucide-react-native";
@@ -18,11 +18,12 @@ import {
   HEADER_INNER_HEIGHT_MOBILE,
   HEADER_TOP_PADDING_MOBILE,
 } from "@/constants/layout";
-import { TitlebarDragRegion } from "@/components/desktop/titlebar-drag-region";
 import { useLocalDaemonServerId } from "@/hooks/use-is-local-daemon";
 import { PairDeviceModal } from "@/desktop/components/pair-device-modal";
 import { buildSettingsHostSectionRoute } from "@/utils/host-routes";
 
+const WINDOW_CONTENT_DATASET = { "window-content": "" };
+
 export function OpenProjectScreen() {
   const { t } = useTranslation();
   const hosts = useHosts();
@@ -61,51 +62,56 @@ export function OpenProjectScreen() {
   return (
     <View style={styles.container}>
       <MenuHeader borderless />
-      <View style={styles.content}>
-        <TitlebarDragRegion />
-        <View style={styles.logo}>
-          <PaseoLogo size={52} />
-        </View>
-        {hosts.map((host) => (
-          <HostError key={host.serverId} serverId={host.serverId} label={host.label} />
-        ))}
-        <View style={styles.tiles}>
-          <HomeTile
-            icon={FolderOpen}
-            title={t("openProject.tiles.addProject.title")}
-            description={t("openProject.tiles.addProject.description")}
-            onPress={handleOpenPicker}
-            testID="open-project-submit"
-            accent
-          />
-          <HomeTile
-            icon={Inbox}
-            title={t("openProject.tiles.importSession.title")}
-            description={t("openProject.tiles.importSession.description")}
-            onPress={importSession.open}
-            testID="open-project-import-session"
-          />
-          <HomeTile
-            icon={Plug}
-            title={t("openProject.tiles.setupProviders.title")}
-            description={t("openProject.tiles.setupProviders.description")}
-            onPress={handleOpenProviders}
-            testID="open-project-setup-providers"
-          />
-          {localServerId ? (
+      <ScrollView
+        style={styles.scroll}
+        contentContainerStyle={styles.scrollContent}
+        dataSet={WINDOW_CONTENT_DATASET}
+      >
+        <View style={styles.content}>
+          <View style={styles.logo}>
+            <PaseoLogo size={52} />
+          </View>
+          {hosts.map((host) => (
+            <HostError key={host.serverId} serverId={host.serverId} label={host.label} />
+          ))}
+          <View style={styles.tiles}>
             <HomeTile
-              icon={Smartphone}
-              title={t("openProject.tiles.pairDevice.title")}
-              description={t("openProject.tiles.pairDevice.description")}
-              onPress={handleOpenPairDevice}
-              testID="open-project-pair-device"
+              icon={FolderOpen}
+              title={t("openProject.tiles.addProject.title")}
+              description={t("openProject.tiles.addProject.description")}
+              onPress={handleOpenPicker}
+              testID="open-project-submit"
+              accent
             />
-          ) : null}
+            <HomeTile
+              icon={Inbox}
+              title={t("openProject.tiles.importSession.title")}
+              description={t("openProject.tiles.importSession.description")}
+              onPress={importSession.open}
+              testID="open-project-import-session"
+            />
+            <HomeTile
+              icon={Plug}
+              title={t("openProject.tiles.setupProviders.title")}
+              description={t("openProject.tiles.setupProviders.description")}
+              onPress={handleOpenProviders}
+              testID="open-project-setup-providers"
+            />
+            {localServerId ? (
+              <HomeTile
+                icon={Smartphone}
+                title={t("openProject.tiles.pairDevice.title")}
+                description={t("openProject.tiles.pairDevice.description")}
+                onPress={handleOpenPairDevice}
+                testID="open-project-pair-device"
+              />
+            ) : null}
+          </View>
         </View>
-      </View>
-      <View style={styles.communityRow}>
-        <CommunityLinks />
-      </View>
+        <View style={styles.communityRow}>
+          <CommunityLinks />
+        </View>
+      </ScrollView>
       <PairDeviceModal
         serverId={localServerId ?? ""}
         visible={isPairDeviceOpen}
@@ -176,18 +182,21 @@ const styles = StyleSheet.create((theme) => ({
     backgroundColor: theme.colors.surface0,
     userSelect: "none",
   },
+  scroll: {
+    flex: 1,
+  },
+  scrollContent: {
+    flexGrow: 1,
+  },
   content: {
     position: "relative",
-    flex: 1,
+    flexGrow: 1,
+    flexShrink: 0,
     justifyContent: { xs: "flex-start", md: "center" },
     alignItems: "center",
     gap: 0,
     padding: theme.spacing[6],
     paddingTop: { xs: theme.spacing[12], md: theme.spacing[6] },
-    paddingBottom: {
-      xs: HEADER_INNER_HEIGHT_MOBILE + HEADER_TOP_PADDING_MOBILE + theme.spacing[6],
-      md: HEADER_INNER_HEIGHT + theme.spacing[6],
-    },
   },
   logo: {
     marginBottom: theme.spacing[8],
@@ -238,10 +247,8 @@ const styles = StyleSheet.create((theme) => ({
     lineHeight: 18,
   },
   communityRow: {
-    position: "absolute",
-    left: 0,
-    right: 0,
-    bottom: {
+    flexShrink: 0,
+    paddingBottom: {
       xs: HEADER_INNER_HEIGHT_MOBILE + HEADER_TOP_PADDING_MOBILE + theme.spacing[2],
       md: HEADER_INNER_HEIGHT + theme.spacing[2],
     },

packages/expo-two-way-audio/android/build.gradle

@@ -36,8 +36,14 @@ android {
   defaultConfig {
     versionCode 1
     versionName "0.1.0"
+    testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
   }
   lintOptions {
     abortOnError false
   }
 }
+
+dependencies {
+  androidTestImplementation 'androidx.test:runner:1.6.2'
+  androidTestImplementation 'androidx.test.ext:junit:1.2.1'
+}

packages/expo-two-way-audio/android/src/androidTest/AndroidManifest.xml

@@ -0,0 +1,8 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+    <application>
+        <activity android:name="expo.modules.twowayaudio.AudioEngineTestActivity"
+            android:exported="true" />
+    </application>
+</manifest>

packages/expo-two-way-audio/android/src/androidTest/java/expo/modules/twowayaudio/AudioEngineTest.kt

@@ -0,0 +1,223 @@
+package expo.modules.twowayaudio
+
+import AudioEngine
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
+import android.media.AudioManager
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import androidx.test.filters.SdkSuppress
+import org.junit.After
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.atomic.AtomicInteger
+
+class AudioEngineTestActivity : Activity()
+
+/** Real AudioManager and AudioRecord: focus loss is delivered by Android, never injected. */
+@RunWith(AndroidJUnit4::class)
+class AudioEngineTest {
+    private val instrumentation = InstrumentationRegistry.getInstrumentation()
+    private lateinit var activity: Activity
+    private lateinit var engine: AudioEngine
+    private lateinit var audio: AudioManager
+    private val packets = AtomicInteger()
+    private val events = CopyOnWriteArrayList<String>()
+    private val requests = mutableListOf<AudioFocusRequest>()
+
+    @Before fun setUp() {
+        val context = instrumentation.context
+        shell("pm grant ${context.packageName} android.permission.RECORD_AUDIO")
+        activity = instrumentation.startActivitySync(
+            Intent(context, AudioEngineTestActivity::class.java).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        )
+        instrumentation.waitForIdleSync()
+        audio = activity.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+        main {
+            engine = AudioEngine(activity)
+            engine.onMicDataCallback = { packets.incrementAndGet() }
+            engine.onAudioInterruptionCallback = { events.add(it) }
+        }
+    }
+
+    @After fun tearDown() {
+        shell("cmd sensor_privacy disable 0 microphone")
+        main {
+            requests.forEach { audio.abandonAudioFocusRequest(it) }
+            engine.tearDown()
+            activity.finish()
+        }
+    }
+
+    @Test fun dictationContinuesWhenMusicTakesFocus() {
+        assertDictationSurvives(AudioManager.AUDIOFOCUS_GAIN)
+    }
+
+    @Test fun dictationContinuesWhenFocusIsTemporarilyLost() {
+        assertDictationSurvives(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT)
+    }
+
+    @Test fun dictationContinuesWhenAnotherAppRequestsDucking() {
+        assertDictationSurvives(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK)
+    }
+
+    @Test fun conversationStillStopsOnFocusLoss() {
+        main { assertTrue(engine.toggleRecording(true)) }
+        await("conversation microphone data") { packets.get() > 2 }
+        takeFocus(AudioManager.AUDIOFOCUS_GAIN)
+        await("terminal conversation interruption") { events.contains("blocked") }
+        assertFalse(engine.isRecording)
+    }
+
+    @Test fun dictationStartsWhileMusicOwnsFocusAndCanBeStartedAgain() {
+        takeFocus(AudioManager.AUDIOFOCUS_GAIN)
+        startDictation()
+        main { engine.toggleRecording(false); engine.releaseAudioSession() }
+        val stoppedAt = packets.get()
+        startDictation()
+        await("new recording data") { packets.get() > stoppedAt + 2 }
+        assertFalse(events.contains("blocked"))
+    }
+
+    @Test fun cancellingWhileBackgroundedDoesNotRestartOnResume() {
+        startDictation()
+        main {
+            engine.pauseRecordingAndPlayer()
+            engine.toggleRecording(false)
+            engine.releaseAudioSession()
+            engine.resumeRecordingAndPlayer()
+        }
+        assertFalse(engine.isRecording)
+    }
+
+    @Test fun dictationKeepsItsCaptureModeAfterBackgroundResume() {
+        startDictation()
+        main { engine.pauseRecordingAndPlayer(); engine.resumeRecordingAndPlayer() }
+        val resumedAt = packets.get()
+        takeFocus(AudioManager.AUDIOFOCUS_GAIN)
+        await("resumed dictation data after focus loss") { packets.get() > resumedAt + 3 }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+    }
+
+    @Test @SdkSuppress(minSdkVersion = 31)
+    fun microphonePrivacyInterruptionPreservesCaptureAndRecovers() {
+        startDictation()
+        shell("cmd sensor_privacy enable 0 microphone")
+        await("input paused") { events.contains("capture_paused") }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+        // Once Android reports silencing, do not enqueue artificial silence for transcription.
+        SystemClock.sleep(100)
+        val pausedAt = packets.get()
+        SystemClock.sleep(150)
+        assertEquals(pausedAt, packets.get())
+        shell("cmd sensor_privacy disable 0 microphone")
+        await("input resumed") { events.contains("capture_resumed") }
+        await("microphone data after recovery") { packets.get() > pausedAt + 3 }
+        assertTrue(engine.isRecording)
+        assertEquals(listOf("capture_paused", "capture_resumed"), events.toList())
+    }
+
+    @Test @SdkSuppress(minSdkVersion = 31)
+    fun startingWithMicrophonePrivacyEnabledWaitsAndRecovers() {
+        shell("cmd sensor_privacy enable 0 microphone")
+        main { assertTrue(engine.startDictation()) }
+        await("initial input paused") { events.contains("capture_paused") }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+        shell("cmd sensor_privacy disable 0 microphone")
+        await("initial input resumed") { events.contains("capture_resumed") }
+        await("microphone data") { packets.get() > 3 }
+    }
+
+    @Test fun resumingDictationDoesNotTakeFocusBackFromMusic() {
+        startDictation()
+        main { engine.pauseRecordingAndPlayer() }
+        val changes = CopyOnWriteArrayList<Int>()
+        val request = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
+            .setOnAudioFocusChangeListener({ changes.add(it) }, Handler(Looper.getMainLooper()))
+            .build()
+        requests.add(request)
+        main { assertEquals(AudioManager.AUDIOFOCUS_REQUEST_GRANTED, audio.requestAudioFocus(request)) }
+        val before = packets.get()
+        main { engine.resumeRecordingAndPlayer() }
+        await("resumed microphone data") { packets.get() > before + 3 }
+        assertTrue(engine.isRecording)
+        assertTrue("Music lost focus on dictation resume: $changes", changes.isEmpty())
+    }
+
+    @Test @SdkSuppress(minSdkVersion = 31)
+    fun stoppingDictationReleasesTheCommunicationRoute() {
+        startDictation()
+        await("selected communication route") { hasCommunicationRoute() }
+        main { engine.toggleRecording(false); engine.releaseAudioSession() }
+        await("normal audio mode") { audio.mode == AudioManager.MODE_NORMAL }
+        await("cleared communication route") { !hasCommunicationRoute() }
+        assertFalse(engine.isRecording)
+    }
+
+    private fun assertDictationSurvives(gain: Int) {
+        startDictation()
+        val before = packets.get()
+        val request = takeFocus(gain)
+        await("microphone data while focus is lost") { packets.get() > before + 3 }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+        val during = packets.get()
+        main { audio.abandonAudioFocusRequest(request) }
+        await("microphone data after focus release") { packets.get() > during + 3 }
+        assertTrue(engine.isRecording)
+        assertFalse(events.contains("blocked"))
+    }
+
+    private fun startDictation() {
+        val before = packets.get()
+        main { assertTrue(engine.startDictation()) }
+        await("initial microphone data") { packets.get() > before + 3 }
+    }
+
+    private fun takeFocus(gain: Int): AudioFocusRequest {
+        val request = AudioFocusRequest.Builder(gain)
+            .setAudioAttributes(AudioAttributes.Builder()
+                .setUsage(AudioAttributes.USAGE_MEDIA)
+                .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC).build())
+            .setOnAudioFocusChangeListener({}, Handler(Looper.getMainLooper()))
+            .build()
+        requests.add(request)
+        main { assertEquals(AudioManager.AUDIOFOCUS_REQUEST_GRANTED, audio.requestAudioFocus(request)) }
+        return request
+    }
+
+    private fun main(action: () -> Unit) = instrumentation.runOnMainSync(action)
+
+    private fun await(description: String, condition: () -> Boolean) {
+        val deadline = SystemClock.elapsedRealtime() + 5000
+        while (!condition() && SystemClock.elapsedRealtime() < deadline) SystemClock.sleep(20)
+        assertTrue("Timed out waiting for $description; events=$events packets=${packets.get()}", condition())
+    }
+
+    // communicationDevice reports the effective system device even after our selection is cleared.
+    // Inspect only current route clients, never the historical routing event log.
+    private fun hasCommunicationRoute(): Boolean {
+        val dump = shell("dumpsys audio")
+        assertTrue("Missing Android communication route diagnostics", dump.contains("Communication route clients:"))
+        return dump.lineSequence().any {
+            it.trimStart().startsWith("[CommunicationRouteClient: mUid: ${android.os.Process.myUid()} ")
+        }
+    }
+
+    private fun shell(command: String): String =
+        instrumentation.uiAutomation.executeShellCommand(command).use {
+            android.os.ParcelFileDescriptor.AutoCloseInputStream(it).readBytes().toString(Charsets.UTF_8)
+        }
+}

packages/expo-two-way-audio/android/src/main/java/expo/modules/twowayaudio/AudioEngine.kt

@@ -6,12 +6,14 @@ import android.media.AudioFocusRequest
 import android.media.AudioFormat
 import android.media.AudioManager
 import android.media.AudioRecord
+import android.media.AudioRecordingConfiguration
 import android.media.AudioTrack
 import android.media.MediaRecorder
 import android.media.audiofx.AcousticEchoCanceler
 import android.media.audiofx.NoiseSuppressor
 import android.os.Build
-import android.os.PowerManager
+import android.os.Handler
+import android.os.Looper
 import android.util.Log
 import androidx.annotation.RequiresApi
 import java.util.LinkedList
@@ -34,7 +36,26 @@ class AudioEngine (context: Context) {
     private var noiseSuppressor: NoiseSuppressor? = null
     private val executorServiceMicrophone = Executors.newFixedThreadPool(1)
     private val executorServicePlayback = Executors.newFixedThreadPool(1)
-    private var speakerDevice: AudioDeviceInfo? = null
+    private enum class CaptureMode { CONVERSATION, DICTATION }
+    private var captureMode = CaptureMode.CONVERSATION
+    private val mainHandler = Handler(Looper.getMainLooper())
+    @Volatile private var captureSilenced = false
+    private val recordingCallback = object : AudioManager.AudioRecordingCallback() {
+        override fun onRecordingConfigChanged(configs: MutableList<AudioRecordingConfiguration>) {
+            if (!isRecording || !::audioRecord.isInitialized) return
+            val config = configs.firstOrNull { it.clientAudioSessionId == audioRecord.audioSessionId }
+                ?: return
+            setCaptureSilenced(config.isClientSilenced)
+        }
+    }
+    private val deviceCallback = object : android.media.AudioDeviceCallback() {
+        override fun onAudioDevicesAdded(devices: Array<out AudioDeviceInfo>) {
+            if (communicationRouteActive) updateAudioRouting()
+        }
+        override fun onAudioDevicesRemoved(devices: Array<out AudioDeviceInfo>) {
+            if (communicationRouteActive) updateAudioRouting()
+        }
+    }
     private var communicationRouteActive = false
     private var bridgeWindowStartedAtMs = System.currentTimeMillis()
     private var micEvents = 0
@@ -44,7 +65,7 @@ class AudioEngine (context: Context) {
     private var playbackWrites = 0
     private var playbackWriteBytes = 0L
 
-    var isRecording = false
+    @Volatile var isRecording = false
     private var isRecordingBeforePause = false
     var isPlaying = false
 
@@ -83,28 +104,9 @@ class AudioEngine (context: Context) {
     @SuppressLint("NewApi")
     private fun initializeAudio(context:Context) {
         audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
-        activateCommunicationRoute()
-        if (!requestAudioFocus()) {
-            handleAudioFocusBlocked()
-        }
-
-        // Listen for changes in audio routing
-        audioManager.registerAudioDeviceCallback(object:android.media.AudioDeviceCallback(){
-            override fun onAudioDevicesAdded(addedDevices: Array<out AudioDeviceInfo>?) {
-                Log.d("AudioEngine", "onAudioDevicesAdded")
-                super.onAudioDevicesAdded(addedDevices)
-                if (communicationRouteActive) {
-                    updateAudioRouting()
-                }
-            }
-            override fun onAudioDevicesRemoved(removedDevices: Array<out AudioDeviceInfo>?) {
-                Log.d("AudioEngine", "onAudioDevicesRemoved")
-                super.onAudioDevicesRemoved(removedDevices)
-                if (communicationRouteActive) {
-                    updateAudioRouting()
-                }
-            }
-        }, null)
+        // Initialization must not interrupt music before a capture/playback operation owns a session.
+        audioManager.registerAudioDeviceCallback(deviceCallback, mainHandler)
+        audioManager.registerAudioRecordingCallback(recordingCallback, mainHandler)
 
         val bufferSize = AudioTrack.getMinBufferSize(
             SAMPLE_RATE,
@@ -125,49 +127,42 @@ class AudioEngine (context: Context) {
             bufferSize,
             AudioTrack.MODE_STREAM,
             audioManager.generateAudioSessionId()
-        ).apply {
-            play()
-        }
+        )
     }
 
+    @SuppressLint("NewApi")
     private fun updateAudioRouting() {
-        val devices = audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
-        var isExternalDeviceConnected = false
-        var selectedDevice: AudioDeviceInfo? = null
-
-        for (device in devices) {
-            if (device.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER) {
-                speakerDevice = device
-            }
-            if (device.type == AudioDeviceInfo.TYPE_WIRED_HEADPHONES ||
-                device.type == AudioDeviceInfo.TYPE_WIRED_HEADSET ||
-                device.type == AudioDeviceInfo.TYPE_BLUETOOTH_A2DP ||
-                device.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO) {
-                isExternalDeviceConnected = true
-                selectedDevice = device
-                break
-            } else if (device.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER) {
-                selectedDevice = device
-            }
-        }
-
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
-            // Use the modern API for Android S and above
-            try {
-                selectedDevice?.let {
-                    audioManager.setCommunicationDevice(it)
-                }
-            }catch (e:Exception){
-                Log.e("AudioEngine", "Error setting communication device. Using speaker")
-                speakerDevice?.let {
-                    audioManager.setCommunicationDevice(it)
-                }
+            val devices = audioManager.availableCommunicationDevices
+            // A2DP is a music output, not a microphone route. Android chooses the matching
+            // input for a valid communication sink (including SCO and BLE headsets).
+            val selected = devices.firstOrNull { it.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO ||
+                it.type == AudioDeviceInfo.TYPE_BLE_HEADSET }
+                ?: devices.firstOrNull { it.type == AudioDeviceInfo.TYPE_WIRED_HEADSET ||
+                    it.type == AudioDeviceInfo.TYPE_WIRED_HEADPHONES ||
+                    it.type == AudioDeviceInfo.TYPE_USB_HEADSET }
+                ?: devices.firstOrNull { it.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER }
+            val routed = try {
+                selected != null && audioManager.setCommunicationDevice(selected)
+            } catch (_: IllegalArgumentException) {
+                // The device disconnected between enumeration and selection.
+                false
             }
-
+            if (!routed) audioManager.clearCommunicationDevice()
         } else {
-            // Fall back to deprecated method for older Android versions
             @Suppress("DEPRECATION")
-            audioManager.isSpeakerphoneOn = !isExternalDeviceConnected
+            val devices = audioManager.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
+            // Before Android 12, A2DP signals a connected headset; start SCO to open its mic.
+            val bluetooth = devices.any { it.type == AudioDeviceInfo.TYPE_BLUETOOTH_SCO ||
+                it.type == AudioDeviceInfo.TYPE_BLUETOOTH_A2DP }
+            @Suppress("DEPRECATION")
+            if (bluetooth) audioManager.startBluetoothSco() else audioManager.stopBluetoothSco()
+            @Suppress("DEPRECATION")
+            audioManager.isSpeakerphoneOn = !bluetooth && !devices.any {
+                it.type == AudioDeviceInfo.TYPE_WIRED_HEADSET ||
+                    it.type == AudioDeviceInfo.TYPE_WIRED_HEADPHONES ||
+                    it.type == AudioDeviceInfo.TYPE_USB_HEADSET
+            }
         }
     }
 
@@ -186,6 +181,8 @@ class AudioEngine (context: Context) {
         } else {
             @Suppress("DEPRECATION")
             audioManager.isSpeakerphoneOn = false
+            @Suppress("DEPRECATION")
+            audioManager.stopBluetoothSco()
         }
         audioManager.mode = AudioManager.MODE_NORMAL
     }
@@ -245,8 +242,8 @@ class AudioEngine (context: Context) {
             audioFocusRequest = null
         }
 
-        val focusRequest =
-            AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
+        lateinit var focusRequest: AudioFocusRequest
+        focusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                 .setAudioAttributes(
                     AudioAttributes.Builder()
                         .setUsage(AudioAttributes.USAGE_VOICE_COMMUNICATION)
@@ -255,6 +252,7 @@ class AudioEngine (context: Context) {
                 )
                 .setAcceptsDelayedFocusGain(true)
                 .setOnAudioFocusChangeListener { focusChange ->
+                    if (audioFocusRequest !== focusRequest) return@setOnAudioFocusChangeListener
                     when (focusChange) {
                         AudioManager.AUDIOFOCUS_GAIN -> {
                             Log.d("AudioEngine", "Audio focus gained")
@@ -286,6 +284,14 @@ class AudioEngine (context: Context) {
     }
 
     private fun handleAudioFocusBlocked() {
+        // Focus governs playback. Dictation keeps its AudioRecord alive; Android's
+        // recording configuration reports real input silencing and restores it after calls.
+        if (captureMode == CaptureMode.DICTATION) {
+            stopPlayback()
+            audioFocusRequest?.let { audioManager.abandonAudioFocusRequest(it) }
+            audioFocusRequest = null
+            return
+        }
         if (isRecording) {
             stopRecording()
         }
@@ -306,11 +312,11 @@ class AudioEngine (context: Context) {
 
     @RequiresApi(Build.VERSION_CODES.Q)
     @SuppressLint("MissingPermission")
-    private fun startRecording(): Boolean {
+    private fun startRecording(requestFocus: Boolean = true): Boolean {
         activateCommunicationRoute()
-        if (!requestAudioFocus()) {
+        if (requestFocus && !requestAudioFocus()) {
             handleAudioFocusBlocked()
-            return false
+            if (captureMode == CaptureMode.CONVERSATION) return false
         }
 
         val bufferSize = AudioRecord.getMinBufferSize(SAMPLE_RATE, CHANNEL_CONFIG, AUDIO_FORMAT)
@@ -344,17 +350,27 @@ class AudioEngine (context: Context) {
 
         audioRecord.startRecording()
         isRecording = true
-        startMicSampleTap()
+        setCaptureSilenced(audioRecord.activeRecordingConfiguration?.isClientSilenced ?: false)
+        startMicSampleTap(audioRecord)
         return true
     }
 
-    private fun startMicSampleTap(){
+    private fun setCaptureSilenced(silenced: Boolean) {
+        if (captureSilenced == silenced) return
+        captureSilenced = silenced
+        if (silenced) onInputVolumeCallback?.invoke(0.0F)
+        onAudioInterruptionCallback?.invoke(if (silenced) "capture_paused" else "capture_resumed")
+    }
+
+    private fun startMicSampleTap(recorder: AudioRecord){
         executorServiceMicrophone.execute {
             val buffer = ByteArray(1024)
             try {
-                while (isRecording) {
-                    val read = audioRecord.read(buffer, 0, buffer.size)
-                    if (read > 0) {
+                while (isRecording && audioRecord === recorder) {
+                    val read = recorder.read(buffer, 0, buffer.size)
+                    if (!isRecording || audioRecord !== recorder) break
+                    if (read < 0) throw IllegalStateException("AudioRecord read failed: $read")
+                    if (read > 0 && !captureSilenced) {
                         val data = buffer.copyOf(read)
                         micEvents += 1
                         micBytes += data.size.toLong()
@@ -367,9 +383,13 @@ class AudioEngine (context: Context) {
                 Log.d("AudioEngine", "Mic sample tap stopped.")
             }catch (e: Exception){
                 Log.e("AudioEngine", "Error reading mic sample data", e)
-                isRecording = false
-                tearDown()
-                throw e
+                mainHandler.post {
+                    if (isRecording && audioRecord === recorder) {
+                        stopRecording()
+                        releaseAudioSession()
+                        onAudioInterruptionCallback?.invoke("blocked")
+                    }
+                }
             }
         }
     }
@@ -379,16 +399,31 @@ class AudioEngine (context: Context) {
         isRecording = false
         if (audioRecord.recordingState == AudioRecord.RECORDSTATE_RECORDING) {
             audioRecord.stop()
-            audioRecord.release()
         }
+        audioRecord.release()
+        echoCanceler?.release()
+        echoCanceler = null
+        noiseSuppressor?.release()
+        noiseSuppressor = null
+        setCaptureSilenced(false)
         onInputVolumeCallback?.invoke(0.0F)
     }
 
+    @RequiresApi(Build.VERSION_CODES.Q)
+    fun startDictation(): Boolean {
+        isRecordingBeforePause = false
+        if (isRecording) return true
+        captureMode = CaptureMode.DICTATION
+        return startRecording()
+    }
+
     @RequiresApi(Build.VERSION_CODES.Q)
     fun toggleRecording(value: Boolean): Boolean {
+        isRecordingBeforePause = false
         if (value == isRecording) return isRecording
 
         if (value) {
+            captureMode = CaptureMode.CONVERSATION
             return startRecording()
         } else {
             stopRecording()
@@ -401,6 +436,7 @@ class AudioEngine (context: Context) {
     @SuppressLint("NewApi")
     fun playPCMData(data: ByteArray) {
         acquireAudioSessionIfNeeded()
+        audioTrack.play()
         audioSampleQueue.add(data)
         playbackEvents += 1
         playbackQueuedBytes += data.size.toLong()
@@ -464,7 +500,7 @@ class AudioEngine (context: Context) {
     @RequiresApi(Build.VERSION_CODES.Q)
     fun pauseRecordingAndPlayer() {
         isRecordingBeforePause = isRecording
-        isRecording = toggleRecording(false)
+        stopRecording()
         audioTrack.pause()
     }
 
@@ -478,16 +514,18 @@ class AudioEngine (context: Context) {
         if (!wasRecordingBeforePause && !isPlaying) {
             return
         }
-        activateCommunicationRoute()
-        if (!requestAudioFocus()) {
-            handleAudioFocusBlocked()
-            return
+        isRecordingBeforePause = false
+        if (wasRecordingBeforePause) {
+            // Returning from music controls must not pause music the user explicitly resumed.
+            if (!startRecording(requestFocus = captureMode == CaptureMode.CONVERSATION)) return
+        } else {
+            activateCommunicationRoute()
+            if (!requestAudioFocus()) {
+                handleAudioFocusBlocked()
+                return
+            }
         }
-        isRecording = toggleRecording(wasRecordingBeforePause)
-        if (wasRecordingBeforePause && !isRecording) {
-            return
-        }
-        audioTrack.play()
+        if (captureMode == CaptureMode.CONVERSATION) audioTrack.play()
     }
 
     fun stopPlayback() {
@@ -520,7 +558,11 @@ class AudioEngine (context: Context) {
             audioManager.abandonAudioFocusRequest(request)
         }
         audioFocusRequest = null
+        audioManager.unregisterAudioDeviceCallback(deviceCallback)
+        audioManager.unregisterAudioRecordingCallback(recordingCallback)
+        audioTrack.release()
         executorServiceMicrophone.shutdownNow()
+        executorServicePlayback.shutdownNow()
     }
 
 

packages/expo-two-way-audio/android/src/main/java/expo/modules/twowayaudio/ExpoTwoWayAudioModule.kt

@@ -42,6 +42,12 @@ class ExpoTwoWayAudioModule : Module() {
              audioEngine?.isRecording ?: false
          }
 
+         Function("startDictation") {
+             val isRecording = audioEngine?.startDictation() ?: false
+             sendEvent(ON_RECORDING_CHANGE_EVENT, mapOf("data" to isRecording))
+             isRecording
+         }
+
          Function("toggleRecording") { value: Boolean ->
              audioEngine?.let { engine ->
                  val isRecording = engine.toggleRecording(value)

packages/expo-two-way-audio/ios/ExpoTwoWayAudioModule.swift

@@ -59,6 +59,12 @@ public class ExpoTwoWayAudioModule: Module {
             return audioEngine.isRecording
         }
 
+        Function("startDictation") { () -> Bool in
+            let isRecording = self.audioEngine?.toggleRecording(true) ?? false
+            self.sendEvent(ON_RECORDING_CHANGE_EVENT_NAME, ["data": isRecording])
+            return isRecording
+        }
+
         Function("toggleRecording") { (val: Bool) -> Bool in
             guard let audioEngine = self.audioEngine else {
                 print("AudioEngine not initialized")

packages/expo-two-way-audio/src/core.ts

@@ -17,6 +17,16 @@ export function toggleRecording(val: boolean): boolean {
   return ExpoTwoWayAudioModule.toggleRecording(val);
 }
 
+/** Capture speech without treating another app's playback focus as a microphone failure. */
+export function startDictation(): boolean {
+  // COMPAT(dictationCapture): added after v0.11.2, remove after 2027-01-16 once
+  // the native binary floor includes startDictation. Older OTA clients retain legacy capture.
+  if (typeof ExpoTwoWayAudioModule.startDictation !== "function") {
+    return ExpoTwoWayAudioModule.toggleRecording(true);
+  }
+  return ExpoTwoWayAudioModule.startDictation();
+}
+
 export function isRecording(): boolean {
   return ExpoTwoWayAudioModule.isRecording();
 }

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

@@ -12,6 +12,13 @@ import {
   toAgentPersistenceHandle,
 } from "../persistence-hooks.js";
 
+export class AgentNotFoundError extends Error {
+  constructor(agentId: string) {
+    super(`Agent not found: ${agentId}`);
+    this.name = "AgentNotFoundError";
+  }
+}
+
 interface PendingAgentInitialization {
   promise: Promise<ManagedAgent>;
   options: { broadcastTimeline: boolean };
@@ -94,7 +101,7 @@ export async function ensureAgentLoaded(
   const initPromise = (async () => {
     const record = await deps.agentStorage.get(agentId);
     if (!record) {
-      throw new Error(`Agent not found: ${agentId}`);
+      throw new AgentNotFoundError(agentId);
     }
 
     const validProviders = deps.validProviders ?? deps.agentManager.getRegisteredProviderIds();

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

@@ -10929,6 +10929,41 @@ test("authoritative timeline records a daemon-handled submitted prompt before it
   }
 });
 
+test("tryRunOutOfBand gives providers the command another agent sent, not its envelope", async () => {
+  const workdir = mkdtempSync(join(tmpdir(), "agent-manager-agent-out-of-band-"));
+  const seenPrompts: AgentPromptInput[] = [];
+
+  class SlashCommandSession extends TestAgentSession {
+    override tryHandleOutOfBand(prompt: AgentPromptInput) {
+      seenPrompts.push(prompt);
+      return prompt === "/handled" ? { run: async () => {} } : null;
+    }
+  }
+  const client = new (class extends TestAgentClient {
+    override async createSession(config: AgentSessionConfig) {
+      return new SlashCommandSession(config);
+    }
+  })();
+  const manager = new AgentManager({ clients: { codex: client }, logger });
+  const agent = await manager.createAgent({ provider: "codex", cwd: workdir }, undefined, {
+    workspaceId: undefined,
+  });
+
+  try {
+    const fromAgent = prepareAgentMessage("/handled", { kind: "agent-message", agentId: "sender" });
+    expect(manager.tryRunOutOfBand(agent.id, fromAgent.prompt)).toBe(true);
+    expect(seenPrompts).toEqual(["/handled"]);
+
+    // A human who pastes an envelope gets it quoted, and it stays a plain prompt.
+    const pasted = prepareAgentMessage(String(fromAgent.prompt));
+    expect(manager.tryRunOutOfBand(agent.id, pasted.prompt)).toBe(false);
+    expect(seenPrompts.at(-1)).toBe(pasted.prompt);
+  } finally {
+    await manager.closeAgent(agent.id);
+    rmSync(workdir, { recursive: true, force: true });
+  }
+});
+
 test("replaceAgentRun succeeds when foreground turn terminal event is never delivered", async () => {
   const workdir = mkdtempSync(join(tmpdir(), "agent-manager-stale-fg-"));
   const storagePath = join(workdir, "agents");

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

@@ -79,7 +79,7 @@ import {
   type PendingForegroundRun,
 } from "./agent-run-state.js";
 import { invokeRewindCapability, type RewindMode } from "./rewind/rewind.js";
-import { projectAgentMessage } from "./agent-messages/index.js";
+import { parseAgentMessage, projectAgentMessage } from "./agent-messages/index.js";
 import { isStaleProviderSessionError } from "./stale-provider-session-error.js";
 import { stripInternalPaseoMcpServer, withRuntimePaseoMcpServer } from "./runtime-mcp-config.js";
 import { resolveCreateAgentTitles } from "./create-agent-title.js";
@@ -2459,7 +2459,12 @@ export class AgentManager {
    */
   tryRunOutOfBand(agentId: string, prompt: AgentPromptInput, options?: AgentRunOptions): boolean {
     const agent = this.requireSessionAgent(agentId);
-    const handler = agent.session.tryHandleOutOfBand?.(prompt);
+    // Providers parse slash commands from the raw text, so a command another agent sent
+    // must reach them without its sender envelope.
+    const agentMessage = typeof prompt === "string" ? parseAgentMessage(prompt) : null;
+    const handler = agent.session.tryHandleOutOfBand?.(
+      agentMessage?.source ? agentMessage.text : prompt,
+    );
     if (!handler) {
       return false;
     }

packages/server/src/server/agent/mcp-server.test.ts

@@ -5,7 +5,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { describe, expect, it, vi } from "vitest";
 import { realpathSync } from "node:fs";
-import { access, mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { access, mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { join, resolve as resolvePath } from "node:path";
 import { tmpdir } from "node:os";
 import { z } from "zod";
@@ -15,6 +15,8 @@ import { createAgentMcpServer as createAgentMcpServerWithDependencies } from "./
 import { AgentManager, type ManagedAgent } from "./agent-manager.js";
 import { AgentStorage, type StoredAgentRecord } from "./agent-storage.js";
 import { createTestAgentClients } from "../test-utils/fake-agent-client.js";
+import { OmpAgentClient } from "./providers/omp/agent.js";
+import { FakeOmp } from "./providers/omp/test-utils/fake-omp.js";
 import type {
   AgentClient,
   AgentMode,
@@ -841,6 +843,49 @@ function createAgentMcpServer(options: Parameters<typeof createAgentMcpServerWit
   });
 }
 
+describe("bundled Paseo skill", () => {
+  it("documents only advertised create_workspace input names", async () => {
+    const server = await createAgentMcpServer({
+      agentManager: new BoundaryAgentManagerFake() as AgentManager,
+      agentStorage: new BoundaryAgentStorageFake() as AgentStorage,
+      providerSnapshotManager:
+        new BoundaryProviderSnapshotManagerFake() as unknown as ProviderSnapshotManager,
+      logger: createTestLogger(),
+    });
+    const client = await connectInMemoryMcpClient(server);
+
+    try {
+      const skill = await readFile(
+        new URL("../../../../../skills/paseo/SKILL.md", import.meta.url),
+        "utf8",
+      );
+      const paragraph = skill.split("\n").find((line) => line.startsWith("**`create_workspace`**"));
+      expect(paragraph).toBeTypeOf("string");
+      // The final sentence describes output, rather than tool inputs.
+      const inputGuidance = paragraph!.split("Returns ")[0]!;
+      const documentedInputs = [...inputGuidance.matchAll(/`([a-zA-Z][a-zA-Z0-9]*)`/g)].map(
+        (match) => match[1]!,
+      );
+      expect(documentedInputs.length).toBeGreaterThan(0);
+      const { tools } = await client.listTools();
+      const tool = tools.find((entry) => entry.name === "create_workspace")!;
+      const properties = tool.inputSchema.properties!;
+      const advertisedNamesAndValues = new Set([
+        ...Object.keys(properties),
+        ...Object.values(properties).flatMap((property) =>
+          typeof property === "object" && property !== null && Array.isArray(property.enum)
+            ? property.enum
+            : [],
+        ),
+      ]);
+      expect(documentedInputs.filter((name) => !advertisedNamesAndValues.has(name))).toEqual([]);
+    } finally {
+      await client.close();
+      await server.close();
+    }
+  });
+});
+
 describe("browser MCP tools", () => {
   const logger = createTestLogger();
 
@@ -3856,8 +3901,7 @@ class HeldTurnAgentSession implements AgentSession {
   }
 
   tryHandleOutOfBand(prompt: AgentPromptInput) {
-    const text = typeof prompt === "string" ? (parseAgentMessage(prompt)?.text ?? prompt) : null;
-    return text === "/side-command" ? { run: async () => {} } : null;
+    return prompt === "/side-command" ? { run: async () => {} } : null;
   }
 
   async startTurn(prompt: AgentPromptInput): Promise<{ turnId: string }> {
@@ -4557,6 +4601,180 @@ describe("send_agent_prompt MCP tool", () => {
   });
 });
 
+describe("send_agent_prompt MCP tool to an OMP child", () => {
+  const logger = createTestLogger();
+  const existingCwd = process.cwd();
+
+  async function setupOmpChild() {
+    const workdir = await mkdtemp(join(tmpdir(), "mcp-omp-child-"));
+    const storage = new AgentStorage(join(workdir, "agents"), logger);
+    const parentClient = new HeldTurnAgentClient("claude", false);
+    const omp = new FakeOmp();
+    const agentManager = new AgentManager({
+      clients: {
+        claude: parentClient,
+        omp: new OmpAgentClient({
+          logger,
+          runtime: omp,
+          noTurnScheduler: { waitForSettle: async () => {} },
+          runtimeSettings: { command: { mode: "replace", argv: [process.execPath] } },
+        }),
+      },
+      registry: storage,
+      logger,
+    });
+    const parent = await agentManager.createAgent(
+      { provider: "claude", cwd: existingCwd },
+      undefined,
+      { workspaceId: "wks_parent" },
+    );
+    const child = await agentManager.createAgent(
+      { provider: "omp", cwd: existingCwd, title: "OMP child" },
+      undefined,
+      { workspaceId: "wks_parent" },
+    );
+    const server = await createAgentMcpServer({
+      agentManager,
+      agentStorage: storage,
+      callerAgentId: parent.id,
+      providerSnapshotManager: createOpenCodeManager().manager,
+      logger,
+    });
+    return {
+      agentManager,
+      storage,
+      workdir,
+      parentClient,
+      ompSession: omp.latestSession(),
+      childId: child.id,
+      tool: registeredTool(server, "send_agent_prompt"),
+    };
+  }
+
+  async function expectOneFinishNotification(
+    agentManager: AgentManager,
+    parentClient: HeldTurnAgentClient,
+    childId: string,
+  ) {
+    await vi.waitFor(() => expect(agentManager.getAgent(childId)?.lifecycle).toBe("idle"));
+    await vi.waitFor(() => {
+      expect(parentClient.sessions[0]!.prompts).toHaveLength(1);
+      expect(parentClient.sessions[0]!.prompts[0]).toContain(
+        `Agent ${childId} (OMP child) finished.`,
+      );
+    });
+  }
+
+  it.each([
+    { command: "follow-up", streamingBehavior: "followUp" },
+    { command: "steer", streamingBehavior: "steer" },
+  ] as const)(
+    "delivers /$command into a turn OMP started on its own, without aborting it",
+    async ({ command, streamingBehavior }) => {
+      const { agentManager, storage, workdir, parentClient, ompSession, childId, tool } =
+        await setupOmpChild();
+      try {
+        ompSession.beginTurn();
+        ompSession.streamAssistantText("background job finished, working on it");
+        await vi.waitFor(() => {
+          expect(agentManager.getAgent(childId)?.activeTurnId).toMatch(/^autonomous-/);
+        });
+
+        const response = await invokeToolWithParsedInput(tool, {
+          agentId: childId,
+          prompt: `/${command} then summarize the logs`,
+        });
+
+        expect(response.structuredContent).toMatchObject({
+          success: true,
+          disposition: "out_of_band",
+          status: "running",
+        });
+        await vi.waitFor(() => {
+          expect(ompSession.prompts).toEqual([
+            { message: "then summarize the logs", imageCount: 0, streamingBehavior },
+          ]);
+        });
+        expect(ompSession.abortRequested).toBe(false);
+        expect(agentManager.getAgent(childId)?.lifecycle).toBe("running");
+
+        ompSession.finishTurn();
+        await expectOneFinishNotification(agentManager, parentClient, childId);
+      } finally {
+        await removeAgentStateDir(agentManager, storage, workdir);
+      }
+    },
+  );
+
+  it.each(["before ack", "after ack"])(
+    "reports an idle follow-up rejected %s and notifies its parent",
+    async (order) => {
+      const { agentManager, storage, workdir, parentClient, ompSession, childId, tool } =
+        await setupOmpChild();
+      try {
+        ompSession.promptAck = { requestId: "follow-up-rejected" };
+        const rejection = {
+          type: "prompt_result",
+          id: "follow-up-rejected",
+          agentInvoked: false,
+          status: "error",
+          sessionSettled: true,
+          error: { message: "Provider rejected the follow-up", retryable: false },
+        } as const;
+        const promptStarted = ompSession.nextPrompt();
+        const response = invokeToolWithParsedInput(tool, {
+          agentId: childId,
+          prompt: "/follow-up check the build",
+        });
+        await promptStarted;
+        if (order === "before ack") ompSession.emit(rejection);
+        await response;
+        if (order === "after ack") ompSession.emit(rejection);
+        await vi.waitFor(() => expect(agentManager.getAgent(childId)?.lifecycle).toBe("error"));
+        expect(agentManager.getAgent(childId)?.lastError).toContain(
+          "Provider rejected the follow-up",
+        );
+        await vi.waitFor(() => expect(parentClient.sessions[0]!.prompts).toHaveLength(1));
+        expect(parentClient.sessions[0]!.prompts[0]).toContain(
+          `Agent ${childId} (OMP child) errored.`,
+        );
+      } finally {
+        await removeAgentStateDir(agentManager, storage, workdir);
+      }
+    },
+  );
+
+  it("lets an idle child start a run with the follow-up", async () => {
+    const { agentManager, storage, workdir, parentClient, ompSession, childId, tool } =
+      await setupOmpChild();
+    try {
+      const response = await invokeToolWithParsedInput(tool, {
+        agentId: childId,
+        prompt: "/follow-up check the build",
+      });
+
+      expect(response.structuredContent).toMatchObject({
+        success: true,
+        disposition: "out_of_band",
+        status: "running",
+      });
+      await vi.waitFor(() => {
+        expect(ompSession.prompts).toEqual([
+          { message: "check the build", imageCount: 0, streamingBehavior: "followUp" },
+        ]);
+      });
+
+      ompSession.beginTurn();
+      ompSession.streamAssistantText("Build is green");
+      await vi.waitFor(() => expect(agentManager.getAgent(childId)?.lifecycle).toBe("running"));
+      ompSession.finishTurn();
+      await expectOneFinishNotification(agentManager, parentClient, childId);
+    } finally {
+      await removeAgentStateDir(agentManager, storage, workdir);
+    }
+  });
+});
+
 describe("update_agent MCP tool", () => {
   const logger = createTestLogger();
 

packages/server/src/server/agent/providers/claude/agent.background-subagent.test.ts

@@ -4,7 +4,7 @@ import path from "node:path";
 import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../../../test-utils/test-logger.js";
-import type { AgentStreamEvent } from "../../agent-sdk-types.js";
+import type { AgentSession, AgentStreamEvent } from "../../agent-sdk-types.js";
 import type { AgentTimelineRow } from "../../agent-manager.js";
 import { projectTimelineRows } from "../../timeline-projection.js";
 import { ClaudeAgentClient } from "./agent.js";
@@ -105,6 +105,39 @@ async function collectUntilTerminal(
   return events;
 }
 
+async function collectTimelineAcrossTurns(
+  session: AgentSession,
+  prompt: string,
+  turnCount: number,
+): Promise<AgentTimelineRow[]> {
+  const rows: AgentTimelineRow[] = [];
+  let currentTurnId: string | undefined;
+  let completedTurns = 0;
+  let unsubscribe = () => {};
+  const turnsCompleted = new Promise<void>((resolve) => {
+    unsubscribe = session.subscribe((event) => {
+      if (event.type === "turn_started") currentTurnId = event.turnId;
+      if (event.type === "timeline") {
+        rows.push({
+          seq: rows.length + 1,
+          timestamp: new Date(Date.UTC(2026, 9, 4, 0, 0, rows.length)).toISOString(),
+          item: event.item,
+          ...(currentTurnId ? { turnId: currentTurnId } : {}),
+        });
+      }
+      if (event.type === "turn_completed" && ++completedTurns === turnCount) resolve();
+    });
+  });
+  try {
+    await session.startTurn(prompt);
+    await turnsCompleted;
+    return rows;
+  } finally {
+    unsubscribe();
+    await session.close();
+  }
+}
+
 describe("background Claude subagents", () => {
   afterEach(() => {
     queryFactory.mockReset();
@@ -431,6 +464,124 @@ describe("background Claude subagents", () => {
         type: "sub_agent",
         subAgentType: "general-purpose",
         description: "Count files here",
+        log: "[Bash] ls -1",
+      },
+    });
+  });
+
+  test("keeps one logged Task card when the child streams on after the parent's turn ends", async () => {
+    // A child can stream across the main session's turn boundary. Claude opens the next
+    // main-session turn with system/init; bare child frames do not open a turn.
+    queryFactory.mockImplementation(() =>
+      buildQueryMock([
+        { type: "system", subtype: "init", session_id: "bg-session", permissionMode: "default" },
+        {
+          type: "assistant",
+          message: {
+            model: "claude-haiku-4-5",
+            content: [
+              {
+                type: "tool_use",
+                id: "toolu_background",
+                name: "Agent",
+                input: {
+                  subagent_type: "general-purpose",
+                  description: "Count files here",
+                  prompt: "Run ls and reply with the number of entries.",
+                  run_in_background: true,
+                },
+              },
+            ],
+          },
+        },
+        {
+          type: "system",
+          subtype: "task_started",
+          task_id: "bg-task",
+          tool_use_id: "toolu_background",
+          task_type: "local_agent",
+          subagent_type: "general-purpose",
+          description: "Count files here",
+          prompt: "Run ls and reply with the number of entries.",
+        },
+        {
+          type: "user",
+          message: {
+            role: "user",
+            content: [
+              {
+                type: "tool_result",
+                tool_use_id: "toolu_background",
+                content: "Async agent launched successfully.",
+              },
+            ],
+          },
+        },
+        {
+          type: "assistant",
+          parent_tool_use_id: "toolu_background",
+          message: {
+            model: "claude-haiku-4-5",
+            content: [
+              {
+                type: "tool_use",
+                id: "toolu_ls",
+                name: "Bash",
+                input: { command: "ls -1", description: "List files" },
+              },
+            ],
+          },
+        },
+        { type: "result", subtype: "success", usage: {}, total_cost_usd: 0 },
+        { type: "system", subtype: "init", session_id: "bg-session", permissionMode: "default" },
+        {
+          type: "user",
+          parent_tool_use_id: "toolu_background",
+          message: {
+            role: "user",
+            content: [{ type: "tool_result", tool_use_id: "toolu_ls", content: "a\nb\nc" }],
+          },
+        },
+        {
+          type: "assistant",
+          parent_tool_use_id: "toolu_background",
+          message: { model: "claude-haiku-4-5", content: [{ type: "text", text: "3" }] },
+        },
+        {
+          type: "system",
+          subtype: "task_updated",
+          task_id: "bg-task",
+          patch: { status: "completed" },
+        },
+        {
+          type: "system",
+          subtype: "task_notification",
+          task_id: "bg-task",
+          tool_use_id: "toolu_background",
+          status: "completed",
+        },
+        { type: "result", subtype: "success", usage: {}, total_cost_usd: 0 },
+      ]),
+    );
+    const session = await new ClaudeAgentClient({
+      logger: createTestLogger(),
+      queryFactory,
+      resolveBinary: async () => "/test/claude/bin",
+    }).createSession({ provider: "claude", cwd: process.cwd() });
+    const rows = await collectTimelineAcrossTurns(session, "delegate work", 2);
+
+    const cards = projectTimelineRows({ rows, mode: "projected" })
+      .map((entry) => entry.item)
+      .filter((item) => item.type === "tool_call" && item.callId === "toolu_background");
+
+    expect(cards).toHaveLength(1);
+    expect(cards[0]).toMatchObject({
+      status: "completed",
+      detail: {
+        type: "sub_agent",
+        subAgentType: "general-purpose",
+        description: "Count files here",
+        log: "[Bash] ls -1",
       },
     });
   });

packages/server/src/server/agent/providers/claude/agent.live-settings.test.ts

@@ -0,0 +1,157 @@
+import { expect, test } from "vitest";
+import type { Query, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import type { AgentStreamEvent } from "../../agent-sdk-types.js";
+import { ClaudeAgentClient } from "./agent.js";
+import type { ClaudeQueryInput } from "./query.js";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+
+// The injected SDK adapter consumes real session input and holds a command open
+// until the test releases it. Closing the query interrupts that command.
+class ForegroundQuery {
+  readonly work = deferred<void>();
+  readonly closed = deferred<void>();
+  private stopped = false;
+  private readonly output: AsyncGenerator<SDKMessage>;
+
+  constructor(input: ClaudeQueryInput) {
+    this.output = this.events(input);
+  }
+
+  private async *events(input: ClaudeQueryInput): AsyncGenerator<SDKMessage> {
+    if (typeof input.prompt === "string") throw new Error("Expected streaming input");
+    for await (const _prompt of input.prompt) {
+      yield {
+        type: "system",
+        subtype: "init",
+        session_id: "settings-session",
+        model: "claude-haiku-5-5",
+        permissionMode: "auto",
+      } as SDKMessage;
+      yield {
+        type: "assistant",
+        message: {
+          content: [
+            { type: "tool_use", id: "tool_sleep", name: "Bash", input: { command: "sleep 20" } },
+          ],
+        },
+      } as SDKMessage;
+      await this.work.promise;
+      if (this.stopped) return;
+      yield { type: "assistant", message: { content: "DONE" } } as SDKMessage;
+      yield {
+        type: "result",
+        subtype: "success",
+        usage: { input_tokens: 1, cache_read_input_tokens: 0, output_tokens: 1 },
+        total_cost_usd: 0,
+      } as SDKMessage;
+    }
+  }
+
+  next() {
+    return this.output.next();
+  }
+  return() {
+    this.close();
+    return this.output.return();
+  }
+  close() {
+    this.stopped = true;
+    this.closed.resolve();
+    this.work.resolve();
+  }
+  async interrupt() {
+    this.close();
+  }
+  async setPermissionMode() {}
+  async setModel() {}
+  async supportedCommands() {
+    return [];
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+}
+
+test.each(["mode", "model", "commands"] as const)(
+  "a pending thinking change preserves the current turn during a %s request",
+  async (control) => {
+    const queries: ForegroundQuery[] = [];
+    const efforts: ClaudeQueryInput["options"]["effort"][] = [];
+    const client = new ClaudeAgentClient({
+      logger: createTestLogger(),
+      resolveBinary: async () => "/test/claude",
+      queryFactory: (input) => {
+        const query = new ForegroundQuery(input);
+        queries.push(query);
+        efforts.push(input.options.effort);
+        return query as unknown as Query;
+      },
+    });
+    const session = await client.createSession({
+      provider: "claude",
+      cwd: process.cwd(),
+      model: "claude-haiku-5-5",
+      modeId: "auto",
+      thinkingOptionId: "low",
+    });
+    const running = deferred<void>();
+    let terminal = deferred<string>();
+    const events: AgentStreamEvent[] = [];
+    session.subscribe((event) => {
+      events.push(event);
+      if (
+        event.type === "timeline" &&
+        event.item.type === "tool_call" &&
+        event.item.status === "running"
+      )
+        running.resolve();
+      if (
+        event.type === "turn_completed" ||
+        event.type === "turn_failed" ||
+        event.type === "turn_canceled"
+      )
+        terminal.resolve(event.type);
+    });
+    try {
+      await session.startTurn("Run the foreground command");
+      await running.promise;
+      expect(await session.setThinkingOption?.("medium")).toMatchObject({
+        message: "Thinking level applies next turn",
+      });
+      if (control === "mode") await session.setMode("acceptEdits");
+      else if (control === "model") await session.setModel("claude-sonnet-5-6");
+      else await session.listCommands();
+      queries[0].work.resolve();
+      expect(
+        await Promise.race([
+          terminal.promise,
+          queries[0].closed.promise.then(() => "query closed before turn finished"),
+        ]),
+      ).toBe("turn_completed");
+      expect(
+        events.some(
+          (event) =>
+            event.type === "timeline" &&
+            event.item.type === "assistant_message" &&
+            event.item.text === "DONE",
+        ),
+      ).toBe(true);
+
+      terminal = deferred<string>();
+      await session.startTurn("Run another command with the new thinking level");
+      queries[1].work.resolve();
+      expect(await terminal.promise).toBe("turn_completed");
+      expect(efforts).toEqual(["low", "medium"]);
+    } finally {
+      await session.close();
+    }
+  },
+);

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

@@ -2228,18 +2228,37 @@ class ClaudeAgentSession implements AgentSession {
     getToolInput: (toolUseId) => this.toolUseCache.get(toolUseId)?.input ?? null,
     readWorkflowResult: readClaudeWorkflowResultFile,
   });
+  /**
+   * Subagent tool calls Claude has already answered while the child still runs, with the input
+   * they were launched with and the turn that answered them. A background child is answered at
+   * launch and streams its frames afterwards.
+   */
+  private readonly settledSubagentToolCalls = new Map<
+    string,
+    {
+      item: Extract<AgentTimelineItem, { type: "tool_call" }>;
+      input: AgentMetadata | null;
+      turnId: string | null;
+    }
+  >();
   private readonly sidechainTracker = new ClaudeSidechainTracker({
-    getToolInput: (toolUseId) => this.toolUseCache.get(toolUseId)?.input ?? null,
+    getToolInput: (toolUseId) =>
+      this.toolUseCache.get(toolUseId)?.input ??
+      this.settledSubagentToolCallInCurrentTurn(toolUseId)?.input ??
+      null,
     // Releases that predate the task protocol announce nothing, so the tracker keeps deriving
     // identity and status from frames for them. Detecting the capability beats comparing version
     // strings: it reacts to what this session actually does.
     isDescriptorOwnedElsewhere: () => this.taskProtocolSource.isActive,
-    // The parent's tool call owns its card once its result arrives. A background child streams
-    // its frames after Claude has already answered the call, and re-emitting the card from them
-    // would replace the settled card with an unlabeled, running one.
+    // A background child streams its frames after Claude has already answered the call, so its
+    // card is rebuilt from the settled call: a running one would replace the settled, labeled card.
+    // A card belongs to the turn that answered the call, so frames from a later turn leave it be.
     needsSyntheticParentToolCard: (toolUseId) =>
-      this.toolUseCache.has(toolUseId) &&
+      (this.toolUseCache.has(toolUseId) ||
+        this.settledSubagentToolCallInCurrentTurn(toolUseId) !== undefined) &&
       this.taskProtocolSource.needsSyntheticParentToolCard(toolUseId),
+    getSettledParentToolCall: (toolUseId) =>
+      this.settledSubagentToolCallInCurrentTurn(toolUseId)?.item,
   });
   private persistedHistory: PersistedTimelineEntry[] = [];
   private persistedProviderSubagentEvents: Extract<
@@ -2591,13 +2610,13 @@ class ClaudeAgentSession implements AgentSession {
     const normalized = isPermissionMode(modeId) ? modeId : "default";
     assertClaudeModeCanRun(normalized, this.harnessEnvironment);
     const previousMode = this.currentMode;
-    const launchesQuery = !this.query || this.queryRestartNeeded;
+    const previousQuery = this.query;
     const activeQuery = await this.ensureQuery(normalized);
     try {
       await activeQuery.setPermissionMode(normalized);
     } catch (error) {
       // The query was launched in the rejected mode; relaunch in the current mode next time.
-      if (launchesQuery) this.queryRestartNeeded = true;
+      if (activeQuery !== previousQuery) this.queryRestartNeeded = true;
       throw error;
     }
     if (normalized === "plan") {
@@ -2876,6 +2895,7 @@ class ClaudeAgentSession implements AgentSession {
     this.cancelCurrentTurn = null;
     this.turnState = "idle";
     this.sidechainTracker.clear();
+    this.settledSubagentToolCalls.clear();
     this.taskProtocolSource.reset();
     this.input?.end();
     this.query?.close?.();
@@ -3294,7 +3314,9 @@ class ClaudeAgentSession implements AgentSession {
   }
 
   private async ensureQuery(launchMode: PermissionMode = this.currentMode): Promise<Query> {
-    if (this.query && !this.queryRestartNeeded) {
+    // Controls use the running turn's query. Pending launch settings take effect
+    // after that turn finishes, when its active query handle has been cleared.
+    if (this.query && (!this.queryRestartNeeded || this.activeForegroundQuery === this.query)) {
       return this.query;
     }
 
@@ -4361,6 +4383,7 @@ class ClaudeAgentSession implements AgentSession {
     for (const event of foldSubagentObservations(subagentObservations)) {
       events.push({ type: "provider_subagent", provider: "claude", event });
     }
+    this.releaseFinishedSubagentToolCalls(subagentObservations);
     for (const observation of subagentObservations) {
       if (observation.kind !== "declared") continue;
       if (!this.taskProtocolSource.needsSyntheticParentToolCard(observation.id)) continue;
@@ -5548,28 +5571,22 @@ class ClaudeAgentSession implements AgentSession {
     const { images, text } = splitClaudeToolResultImages(block.content);
     const output = this.buildToolOutput(text, block, entry);
 
-    if (block.is_error) {
-      this.pushToolCall(
-        mapClaudeFailedToolCall({
+    const settledToolCall = block.is_error
+      ? mapClaudeFailedToolCall({
           name: toolName,
           callId,
           input: entry?.input ?? null,
           output: output ?? null,
           error: { ...block, content: text },
-        }),
-        items,
-      );
-    } else {
-      this.pushToolCall(
-        mapClaudeCompletedToolCall({
+        })
+      : mapClaudeCompletedToolCall({
           name: toolName,
           callId,
           input: entry?.input ?? null,
           output: output ?? null,
-        }),
-        items,
-      );
-    }
+        });
+    this.pushToolCall(settledToolCall, items);
+    this.rememberSettledSubagentToolCall(settledToolCall, entry);
 
     for (const image of images) {
       const imageItem = renderProviderImageOutputAsAssistantMarkdown(image, {
@@ -5585,6 +5602,34 @@ class ClaudeAgentSession implements AgentSession {
     }
   }
 
+  private rememberSettledSubagentToolCall(
+    item: Extract<AgentTimelineItem, { type: "tool_call" }> | null,
+    entry: ToolUseCacheEntry | undefined,
+  ): void {
+    const subagentId = item ? this.taskProtocolSource.resolveSubagentId(item.callId) : undefined;
+    if (!item || !subagentId) return;
+    this.settledSubagentToolCalls.set(subagentId, {
+      item,
+      input: entry?.input ?? null,
+      turnId: this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? null,
+    });
+  }
+
+  private settledSubagentToolCallInCurrentTurn(subagentId: string) {
+    const settled = this.settledSubagentToolCalls.get(subagentId);
+    const currentTurnId = this.activeForegroundTurnId ?? this.autonomousTurn?.id ?? null;
+    return settled && settled.turnId === currentTurnId ? settled : undefined;
+  }
+
+  /** A finished child streams no more frames, so its settled call has nothing left to update. */
+  private releaseFinishedSubagentToolCalls(observations: SubagentObservation[]): void {
+    for (const observation of observations) {
+      if (observation.kind === "status" && observation.status !== "running") {
+        this.settledSubagentToolCalls.delete(observation.id);
+      }
+    }
+  }
+
   private buildToolOutput(
     content: unknown,
     block: ClaudeContentChunk,

packages/server/src/server/agent/providers/claude/sidechain-tracker.ts

@@ -18,6 +18,8 @@ interface ClaudeContentChunk {
   [key: string]: unknown;
 }
 
+type ClaudeToolCallItem = Extract<AgentTimelineItem, { type: "tool_call" }>;
+
 interface SubAgentActionEntry {
   index: number;
   toolName: string;
@@ -64,6 +66,7 @@ export class ClaudeSidechainTracker {
   private readonly getToolInput: (toolUseId: string) => AgentMetadata | null | undefined;
   private readonly isDescriptorOwnedElsewhere: () => boolean;
   private readonly needsSyntheticParentToolCard: (toolUseId: string) => boolean;
+  private readonly getSettledParentToolCall: (toolUseId: string) => ClaudeToolCallItem | undefined;
 
   constructor(input: {
     getToolInput: (toolUseId: string) => AgentMetadata | null | undefined;
@@ -74,10 +77,17 @@ export class ClaudeSidechainTracker {
      */
     isDescriptorOwnedElsewhere?: () => boolean;
     needsSyntheticParentToolCard?: (toolUseId: string) => boolean;
+    /**
+     * The parent's tool call once Claude has answered it. A background child streams its frames
+     * after that answer, so its card keeps the settled status and output and gains the child's
+     * action log.
+     */
+    getSettledParentToolCall?: (toolUseId: string) => ClaudeToolCallItem | undefined;
   }) {
     this.getToolInput = input.getToolInput;
     this.isDescriptorOwnedElsewhere = input.isDescriptorOwnedElsewhere ?? (() => false);
     this.needsSyntheticParentToolCard = input.needsSyntheticParentToolCard ?? (() => true);
+    this.getSettledParentToolCall = input.getSettledParentToolCall ?? (() => undefined);
   }
 
   handleMessage(message: SDKMessage, parentToolUseId: string): AgentStreamEvent[] {
@@ -119,17 +129,19 @@ export class ClaudeSidechainTracker {
       return [];
     }
 
-    const toolCall = mapClaudeRunningToolCall({
-      name: "Task",
-      callId: parentToolUseId,
-      input: null,
-      output: null,
-    });
+    const toolCall =
+      this.getSettledParentToolCall(parentToolUseId) ??
+      mapClaudeRunningToolCall({
+        name: "Task",
+        callId: parentToolUseId,
+        input: null,
+        output: null,
+      });
     if (!toolCall) {
       return [];
     }
 
-    const detail: Extract<AgentTimelineItem, { type: "tool_call" }>["detail"] = {
+    const detail: ClaudeToolCallItem["detail"] = {
       type: "sub_agent",
       ...(state.subAgentType ? { subAgentType: state.subAgentType } : {}),
       ...(state.description ? { description: state.description } : {}),

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

@@ -39,6 +39,19 @@ const ABORTED_TERMINAL_RESPONSE: OmpAgentMessage = {
   errorMessage: "Interrupted by user",
 };
 
+test("an idle follow-up is submitted as a prompt so OMP can start a turn", async () => {
+  const runtime = new FakeOmp();
+  const client = new OmpAgentClient({ logger: createTestLogger(), runtime });
+  const session = await client.createSession({ provider: "omp", cwd: process.cwd() });
+  onTestFinished(() => session.close());
+  const handler = session.tryHandleOutOfBand?.("/follow-up check the build");
+  expect(handler).not.toBeNull();
+  await handler!.run({ emit: () => {} });
+  expect(runtime.latestSession().prompts).toEqual([
+    { message: "check the build", imageCount: 0, streamingBehavior: "followUp" },
+  ]);
+});
+
 test("OMP ready timeout defaults to 20 seconds and RPC timeout overrides both", () => {
   expect(resolveOmpProviderOptions({}).runtimeOptions).toMatchObject({
     readyTimeoutMs: 20_000,

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

@@ -705,6 +705,7 @@ export class OmpAgentSession implements AgentSession {
   private activeAssistantMessageId: string | null = null;
   private activeTurnTerminalAssistantMessage: OmpAgentMessage | null = null;
   private activeTurnStarted = false;
+  private outOfBandTurnStartAnnounced = false;
   private activeTurnHasUserMessage = false;
   private activeNoTurnPromptText: string | null = null;
   private readonly pendingNoTurnOutputs: Array<{ turnId: string; message: string }> = [];
@@ -849,6 +850,20 @@ export class OmpAgentSession implements AgentSession {
   }
 
   async startTurn(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<StartTurnResult> {
+    return this.startPrompt({ prompt, options });
+  }
+
+  private async startPrompt({
+    prompt,
+    options,
+    streamingBehavior,
+    announceTurn = false,
+  }: {
+    prompt: AgentPromptInput;
+    options?: AgentRunOptions;
+    streamingBehavior?: "steer" | "followUp";
+    announceTurn?: boolean;
+  }): Promise<StartTurnResult> {
     if (this.activeTurnId) {
       throw new Error("An OMP turn is already active");
     }
@@ -861,17 +876,26 @@ export class OmpAgentSession implements AgentSession {
     this.activeAssistantMessageId = null;
     this.activeTurnTerminalAssistantMessage = null;
     this.activeTurnStarted = false;
+    this.outOfBandTurnStartAnnounced = false;
     this.activeTurnHasUserMessage = false;
     this.activePromptRequestId = null;
     this.clearNoTurnBuffers();
     this.activeNoTurnPromptText = payload.text;
     this.usagePoller.startTurn();
+    if (announceTurn) {
+      this.outOfBandTurnStartAnnounced = true;
+      this.emit({ type: "turn_started", provider: this.provider, turnId });
+    }
 
     void (async () => {
       try {
         if (this.runtimeDead) await this.replaceRuntime(this.currentModeId ?? "full");
         if (this.closed) throw new Error("OMP session is closed");
-        const ack = await this.runtimeSession.prompt(payload.text, payload.images);
+        const ack = await this.runtimeSession.prompt({
+          message: payload.text,
+          images: payload.images,
+          streamingBehavior,
+        });
         this.activePromptRequestId = ack.requestId ?? null;
         const correlatedResult = ack.requestId
           ? this.pendingPromptResults.get(ack.requestId)
@@ -1191,6 +1215,7 @@ export class OmpAgentSession implements AgentSession {
     this.activeAssistantMessageId = null;
     this.activeTurnTerminalAssistantMessage = null;
     this.activeTurnStarted = false;
+    this.outOfBandTurnStartAnnounced = false;
     this.activeTurnHasUserMessage = false;
     this.pendingClientMessages.length = 0;
     this.clearNoTurnBuffers();
@@ -1235,12 +1260,13 @@ export class OmpAgentSession implements AgentSession {
       if (!message) {
         return null;
       }
+      const streamingBehavior = commandName === "steer" ? "steer" : "followUp";
       return {
         run: async () => {
-          if (commandName === "steer") {
-            this.runtimeSession.steer(message);
+          if (!this.activeTurnId && !this.activeTurnStarted) {
+            await this.startPrompt({ prompt: message, streamingBehavior, announceTurn: true });
           } else {
-            this.runtimeSession.followUp(message);
+            await this.runtimeSession.prompt({ message, streamingBehavior });
           }
         },
       };
@@ -1804,11 +1830,11 @@ export class OmpAgentSession implements AgentSession {
       case "turn_start":
         this.activeTurnStarted = true;
         this.clearNoTurnBuffers();
-        this.emit({
-          type: "turn_started",
-          provider: this.provider,
-          turnId,
-        });
+        if (this.outOfBandTurnStartAnnounced) {
+          this.outOfBandTurnStartAnnounced = false;
+        } else {
+          this.emit({ type: "turn_started", provider: this.provider, turnId });
+        }
         return;
       case "message_start":
         this.handleMessageStart(event);

packages/server/src/server/agent/providers/omp/cli-runtime.test.ts

@@ -143,6 +143,26 @@ describe("OMP CLI runtime", () => {
     await expect(result).rejects.toThrow("rejected");
     await session.close();
   });
+  test("sends the prompt streamingBehavior only when one is given", async () => {
+    const child = createOmpChild();
+    const session = await createRuntime(child, []).startSession({ cwd: "/workspace/project" });
+
+    for (const streamingBehavior of ["followUp", undefined] as const) {
+      const pending = capturePendingCommand(child, "prompt");
+      const result = session.prompt({ message: "after this, update the docs", streamingBehavior });
+      const command = await pending;
+      expect(withoutRequestId(command)).toEqual({
+        type: "prompt",
+        message: "after this, update the docs",
+        ...(streamingBehavior ? { streamingBehavior } : {}),
+      });
+      child.stdout.write(
+        `${JSON.stringify({ id: command.id, type: "response", command: "prompt", success: true })}\n`,
+      );
+      await result;
+    }
+    await session.close();
+  });
   test("uses the configured RPC timeout and attributes the pending phase", async () => {
     vi.useFakeTimers();
     const child = createOmpChild();
@@ -438,7 +458,7 @@ describe("OMP CLI runtime", () => {
     replyToCommands(child, () => undefined);
     const session = await createRuntime(child).startSession({ cwd: "/workspace/project" });
 
-    await expect(session.prompt("hello")).resolves.toEqual({ requestId: "req_1" });
+    await expect(session.prompt({ message: "hello" })).resolves.toEqual({ requestId: "req_1" });
   });
 
   test("reports OMP 18.3's late prompt rejection as a failed prompt result", async () => {
@@ -455,7 +475,7 @@ describe("OMP CLI runtime", () => {
     const events: unknown[] = [];
     session.onEvent((event) => events.push(event));
 
-    await expect(session.prompt("hello")).resolves.toEqual({ requestId: "req_1" });
+    await expect(session.prompt({ message: "hello" })).resolves.toEqual({ requestId: "req_1" });
 
     expect(events).toContainEqual({
       type: "prompt_result",

packages/server/src/server/agent/providers/omp/cli-runtime.ts

@@ -15,6 +15,7 @@ import {
   type OmpRuntime,
   type OmpRuntimeLaunch,
   type OmpRuntimeSession,
+  type OmpPromptInput,
   type OmpStartSessionInput,
 } from "./runtime.js";
 import {
@@ -142,14 +143,12 @@ class OmpCliRuntimeSession implements OmpRuntimeSession {
     };
   }
 
-  async prompt(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): Promise<OmpPromptAck> {
+  async prompt({ message, images, streamingBehavior }: OmpPromptInput): Promise<OmpPromptAck> {
     const { id: requestId, promise } = this.process.startRequest({
       type: "prompt",
       message,
       ...(images?.length ? { images } : {}),
+      ...(streamingBehavior ? { streamingBehavior: streamingBehavior } : {}),
     });
     const ack = OmpPromptAckSchema.parse(await promise) ?? {};
     return { requestId, ...ack };
@@ -282,13 +281,6 @@ class OmpCliRuntimeSession implements OmpRuntimeSession {
     await this.request({ type: "steer", message, ...(images?.length ? { images } : {}) });
   }
 
-  followUp(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): void {
-    this.process.send({ type: "follow_up", message, ...(images?.length ? { images } : {}) });
-  }
-
   async handoff(customInstructions?: string): Promise<void> {
     await this.request({
       type: "handoff",

packages/server/src/server/agent/providers/omp/rpc-types.ts

@@ -535,6 +535,7 @@ export const OmpRpcCommandSchema = z.discriminatedUnion("type", [
     type: z.literal("prompt"),
     message: z.string(),
     images: z.array(OmpImageContentSchema).optional(),
+    streamingBehavior: z.enum(["steer", "followUp"]).optional(),
   }),
   z.object({
     ...OmpCommandBase,

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

@@ -42,13 +42,18 @@ export interface OmpStartSessionInput {
   extraArgs?: string[];
 }
 
+export interface OmpPromptInput {
+  message: string;
+  images?: Array<{ type: "image"; data: string; mimeType: string }>;
+  streamingBehavior?: "steer" | "followUp";
+}
+
 export interface OmpRuntimeSession {
   readonly environment: Record<string, string>;
   onEvent(callback: (event: OmpRuntimeEvent) => void): () => void;
-  prompt(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): Promise<OmpPromptAck>;
+  // With streamingBehavior, a busy OMP queues the message instead of rejecting it, and an
+  // idle OMP starts a run with it.
+  prompt(input: OmpPromptInput): Promise<OmpPromptAck>;
   compact(customInstructions?: string): Promise<void>;
   setAutoCompaction(enabled: boolean): Promise<void>;
   abort(): Promise<void>;
@@ -71,10 +76,6 @@ export interface OmpRuntimeSession {
     message: string,
     images?: Array<{ type: "image"; data: string; mimeType: string }>,
   ): Promise<void>;
-  followUp(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): void;
   handoff(customInstructions?: string): Promise<void>;
   respondToExtensionUiRequest(
     id: string,

packages/server/src/server/agent/providers/omp/test-utils/fake-omp.ts

@@ -2,6 +2,7 @@ import type {
   OmpRuntime,
   OmpRuntimeLaunch,
   OmpRuntimeSession,
+  OmpPromptInput,
   OmpStartSessionInput,
 } from "../runtime.js";
 import type {
@@ -133,7 +134,11 @@ export class FakeOmpSession implements OmpRuntimeSession {
   readonly environment: Record<string, string>;
   fastModeResult = { enabled: false, active: false };
   readonly setFastModeRequests: boolean[] = [];
-  readonly prompts: Array<{ message: string; imageCount: number }> = [];
+  readonly prompts: Array<{
+    message: string;
+    imageCount: number;
+    streamingBehavior?: "steer" | "followUp";
+  }> = [];
   readonly compactRequests: Array<{ customInstructions?: string }> = [];
   readonly setAutoCompactionRequests: boolean[] = [];
   readonly subagentSubscriptionRequests: FakeOmpSubagentSubscriptionLevel[] = [];
@@ -143,7 +148,6 @@ export class FakeOmpSession implements OmpRuntimeSession {
   readonly handoffRequests: Array<{ customInstructions?: string }> = [];
   readonly steerRequests: Array<{ message: string; imageCount: number }> = [];
   steerError: Error | null = null;
-  readonly followUpRequests: Array<{ message: string; imageCount: number }> = [];
   readonly hostToolSetRequests: OmpRpcHostToolDefinition[][] = [];
   readonly hostToolResults: OmpRpcHostToolResult[] = [];
   readonly hostToolUpdates: OmpRpcHostToolUpdate[] = [];
@@ -216,14 +220,19 @@ export class FakeOmpSession implements OmpRuntimeSession {
     };
   }
 
-  async prompt(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): Promise<OmpPromptAck> {
-    if (this.state.isStreaming || this.state.isCompacting) {
+  async prompt({ message, images, streamingBehavior }: OmpPromptInput): Promise<OmpPromptAck> {
+    const busy = this.state.isStreaming || this.state.isCompacting;
+    if (busy && !streamingBehavior) {
       throw new Error("Agent is already processing");
     }
-    this.prompts.push({ message, imageCount: images?.length ?? 0 });
+    this.prompts.push({
+      message,
+      imageCount: images?.length ?? 0,
+      ...(streamingBehavior ? { streamingBehavior: streamingBehavior } : {}),
+    });
+    if (busy) {
+      return {};
+    }
     this.promptWaiters.shift()?.();
     const heldPrompt = this.nextHeldPrompt;
     if (heldPrompt) {
@@ -412,13 +421,6 @@ export class FakeOmpSession implements OmpRuntimeSession {
     if (this.steerError) throw this.steerError;
   }
 
-  followUp(
-    message: string,
-    images?: Array<{ type: "image"; data: string; mimeType: string }>,
-  ): void {
-    this.followUpRequests.push({ message, imageCount: images?.length ?? 0 });
-  }
-
   sendHostToolResult(result: OmpRpcHostToolResult): void {
     this.hostToolResults.push(result);
     this.hostToolResultWaiters.shift()?.(result);

packages/server/src/server/agent/providers/opencode/bridge-input-errors.test.ts

@@ -0,0 +1,202 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "vitest";
+import { createTestLogger } from "../../../../test-utils/test-logger.js";
+import { createPaseoToolCatalog } from "../../tools/paseo-tools.js";
+import { AgentManager } from "../../agent-manager.js";
+import { AgentStorage } from "../../agent-storage.js";
+import { ProviderSnapshotManager } from "../../provider-snapshot-manager.js";
+import { OpenCodeBridge } from "./bridge.js";
+import { ScheduleService } from "../../../schedule/service.js";
+import { createWorkspaceScriptsService } from "../../../session/workspace-scripts/workspace-scripts-service.js";
+import {
+  FileBackedProjectRegistry,
+  FileBackedWorkspaceRegistry,
+} from "../../../workspace-registry.js";
+import { createServiceProxySubsystem } from "../../../service-proxy.js";
+import { WorkspaceScriptRuntimeStore } from "../../../workspace-script-runtime-store.js";
+import { createTerminalManager } from "../../../../terminal/terminal-manager.js";
+
+test("bridge preserves tool failure messages and classifies invalid requests as client errors", async () => {
+  const paseoHome = await mkdtemp(path.join(tmpdir(), "paseo-7045-"));
+  const logger = createTestLogger();
+  const providerSnapshotManager = new ProviderSnapshotManager({ logger });
+  const agentManager = new AgentManager({ logger });
+  const agentStorage = new AgentStorage(paseoHome, logger);
+  const unused = async (): Promise<never> => {
+    throw new Error("Unexpected workspace or agent creation");
+  };
+  const scheduleService = new ScheduleService({
+    paseoHome,
+    logger,
+    agentManager,
+    agentStorage,
+    createAgent: unused,
+    createDirectoryWorkspace: unused,
+    createPaseoWorktreeWorkspace: unused,
+    archiveWorkspace: unused,
+    runner: async () => ({ agentId: null, output: "done" }),
+  });
+  const workspaceScripts = createWorkspaceScriptsService({
+    serviceProxy: createServiceProxySubsystem({ logger }),
+    scriptRuntimeStore: new WorkspaceScriptRuntimeStore(),
+    terminalManager: createTerminalManager(),
+    workspaceRegistry: new FileBackedWorkspaceRegistry(
+      path.join(paseoHome, "workspaces.json"),
+      logger,
+    ),
+    projectRegistry: new FileBackedProjectRegistry(path.join(paseoHome, "projects.json"), logger),
+    workspaceGitService: {
+      peekSnapshot: () => {
+        throw new Error("Unexpected git lookup");
+      },
+    },
+    getDaemonTcpPort: null,
+    getDaemonTcpHost: null,
+    serviceProxyPublicBaseUrl: null,
+    resolveScriptHealth: null,
+    logger,
+    emit: () => {},
+    publishStatusUpdate: () => {},
+    spawnWorkspaceScript: unused,
+    assertAutomationAllowed: unused,
+  });
+  const catalog = createPaseoToolCatalog({
+    workspaceScripts,
+    agentManager,
+    agentStorage,
+    scheduleService,
+    providerSnapshotManager,
+    logger,
+  });
+  const bridge = new OpenCodeBridge({ paseoHome, logger });
+  try {
+    await bridge.start();
+    bridge.setManifestCatalog(catalog);
+    bridge.bindSession({ sessionId: "diagnosis", env: {}, tools: catalog });
+    const config = JSON.parse(bridge.decorateServerEnv({}).OPENCODE_CONFIG_CONTENT);
+    const { baseUrl, token } = config.plugin[0][1];
+    const completed = await scheduleService.create({
+      prompt: "Run once",
+      name: "Daily check",
+      cadence: { type: "cron", expression: "0 0 * * *" },
+      target: { type: "new-agent", config: { provider: "codex", cwd: paseoHome } },
+      maxRuns: 1,
+      runOnCreate: true,
+    });
+    await scheduleService.tick();
+    expect((await scheduleService.inspect(completed.id)).status).toBe("completed");
+    const manifest = await fetch(`${baseUrl}/_internal/opencode/tools`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    const { tools } = await manifest.json();
+    expect(
+      tools.find((tool: { name: string }) => tool.name === "create_agent").inputSchema.properties,
+    ).not.toHaveProperty("background");
+    expect(
+      tools.find((tool: { name: string }) => tool.name === "update_schedule").inputSchema
+        .properties,
+    ).not.toHaveProperty("every");
+    await writeFile(
+      path.join(paseoHome, "schedules", "broken.json"),
+      JSON.stringify({ id: "broken", prompt: 17 }),
+    );
+    const observed = [];
+    for (const [tool, body, expected] of [
+      [
+        "create_agent",
+        JSON.stringify({ title: "Probe", provider: "opencode", initialPrompt: "Reply OK" }),
+        400,
+      ],
+      ["create_agent", "{", 400],
+      ["nonexistent_tool", "{}", 404],
+      ["inspect_schedule", JSON.stringify({ id: "missing" }), 400],
+      ...["pause_schedule", "resume_schedule", "run_schedule_once"].map(
+        (action) => [action, JSON.stringify({ id: completed.id }), 400] as const,
+      ),
+      [
+        "create_schedule",
+        JSON.stringify({ prompt: "Probe", provider: "codex", cron: "not-a-cron" }),
+        400,
+      ],
+      [
+        "create_schedule",
+        JSON.stringify({
+          prompt: "Probe",
+          provider: "codex",
+          cron: "0 0 * * *",
+          timezone: "Mars/Phobos",
+        }),
+        400,
+      ],
+      ["update_schedule", JSON.stringify({ id: completed.id, name: "" }), 200],
+      ["update_schedule", JSON.stringify({ id: completed.id, cron: "0 0 30 2 *" }), 400],
+      ["update_schedule", JSON.stringify({ id: completed.id, expiresIn: "not-a-duration" }), 400],
+      ["send_agent_prompt", JSON.stringify({ agentId: "missing", prompt: "Hello" }), 400],
+      ["inspect_schedule", JSON.stringify({ id: "broken" }), 500],
+      ["list_workspace_scripts", JSON.stringify({ workspaceId: "wks_typo" }), 500],
+      [
+        "start_workspace_script",
+        JSON.stringify({ workspaceId: "wks_typo", scriptName: "web" }),
+        500,
+      ],
+    ] as const) {
+      const response = await fetch(
+        `${baseUrl}/_internal/opencode/sessions/diagnosis/tools/${tool}`,
+        {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+          body,
+        },
+      );
+      observed.push({
+        tool,
+        body,
+        expected,
+        status: response.status,
+        payload: await response.json(),
+      });
+    }
+
+    for (const result of observed) expect.soft(result.status, result.body).toBe(result.expected);
+    expect((await scheduleService.inspect(completed.id)).name).toBeNull();
+    expect(
+      tools.find((tool: { name: string }) => tool.name === "update_schedule").inputSchema.properties
+        .name,
+    ).not.toHaveProperty("minLength");
+    for (const result of observed.slice(14)) {
+      expect.soft(result.payload).toEqual({ error: "Workspace not found: wks_typo" });
+    }
+    expect.soft(observed[12].payload).toEqual({ error: "Agent not found: missing" });
+    expect.soft(observed[13].payload).toEqual({ error: expect.stringContaining('"prompt"') });
+    expect.soft(observed[13].payload).not.toHaveProperty("issues");
+    expect(observed[3].payload).toEqual({ error: "Schedule not found: missing" });
+    for (const result of observed.slice(4, 7))
+      expect(result.payload).toEqual({ error: `Schedule ${completed.id} is already completed` });
+    for (const [index, field] of [
+      [7, "cron"],
+      [8, "timezone"],
+      [10, "cron"],
+      [11, "expiresIn"],
+    ] as const) {
+      expect(observed[index].payload).toMatchObject({
+        error: "Invalid tool input",
+        issues: expect.arrayContaining([expect.objectContaining({ path: [field] })]),
+      });
+    }
+    expect(observed[0].payload).toMatchObject({
+      error: "Invalid tool input",
+      issues: expect.arrayContaining([
+        expect.objectContaining({
+          path: ["provider"],
+          message: expect.stringContaining("provider/model"),
+        }),
+      ]),
+    });
+  } finally {
+    await bridge.close();
+    await providerSnapshotManager.shutdown();
+    await rm(paseoHome, { recursive: true, force: true });
+  }
+});

packages/server/src/server/agent/providers/opencode/bridge-plugin.mjs

@@ -13,8 +13,11 @@ export default async function paseoPlugin(input, options) {
     });
     const payload = await response.json().catch(() => ({}));
     if (!response.ok) {
-      const error = new Error(payload.error ?? `Paseo OpenCode bridge failed: ${response.status}`);
+      const detail = formatErrorDetail(payload.issues ?? payload.details);
+      const message = payload.error ?? `Paseo OpenCode bridge failed: ${response.status}`;
+      const error = new Error(detail ? `${message}: ${detail}` : message);
       error.status = response.status;
+      if (detail) error.details = detail;
       throw error;
     }
     return payload;
@@ -79,6 +82,17 @@ export default async function paseoPlugin(input, options) {
   };
 }
 
+function formatErrorDetail(details) {
+  if (!Array.isArray(details)) return typeof details === "string" ? details : "";
+  return details
+    .map((issue) => {
+      const path =
+        Array.isArray(issue?.path) && issue.path.length > 0 ? issue.path.join(".") : "input";
+      return `${path}: ${issue?.message ?? "Invalid value"}`;
+    })
+    .join("; ");
+}
+
 function logPluginError(stage, context, error) {
   console.error(`[paseo-opencode-plugin] ${stage} failed`, {
     ...context,

packages/server/src/server/agent/providers/opencode/bridge.test.ts

@@ -9,6 +9,7 @@ import { afterEach, describe, expect, test, vi } from "vitest";
 
 import { createTestLogger } from "../../../../test-utils/test-logger.js";
 import type { PaseoToolCatalog } from "../../tools/types.js";
+import { PaseoToolInputError } from "../../tools/types.js";
 import { createPaseoToolCatalog } from "../../tools/paseo-tools.js";
 import { AgentManager } from "../../agent-manager.js";
 import { AgentStorage } from "../../agent-storage.js";
@@ -36,8 +37,12 @@ function createCatalog(): PaseoToolCatalog {
     description: "Returns the supplied value.",
     inputSchema: { value: z.string() },
     async handler(input: unknown) {
-      const parsed = z.object({ value: z.string() }).parse(input);
-      return { content: [{ type: "text", text: parsed.value }] };
+      const parsed = z
+        .object({ value: z.string().min(2, "value must be at least 2 characters") })
+        .strict()
+        .safeParse(input);
+      if (!parsed.success) throw new PaseoToolInputError(parsed.error.message, parsed.error.issues);
+      return { content: [{ type: "text", text: parsed.data.value }] };
     },
   };
   const tools = new Map([[tool.name, tool]]);
@@ -193,6 +198,13 @@ describe("OpenCodeBridge", () => {
       expect(asked).toEqual([
         { permission: "paseo_echo_context", patterns: ["*"], always: ["*"], metadata: {} },
       ]);
+      asked.length = 0;
+      await expect(
+        hooks.tool.paseo_echo_context.execute(
+          { value: "x" },
+          { sessionID: "ses_one", ask: async () => undefined },
+        ),
+      ).rejects.toThrow("value: value must be at least 2 characters");
 
       executedInputs.length = 0;
       await expect(
@@ -357,12 +369,17 @@ describe("OpenCodeBridge", () => {
             body: JSON.stringify(input),
           },
         );
-        expect(response.status).toBe(500);
+        expect(response.status).toBe(400);
         const payload = await response.json();
-        expect(payload.error).toContain("provider must be provider/model");
+        expect(payload).toMatchObject({ error: "Invalid tool input", issues: expect.any(Array) });
         await expect(
           tools.get("paseo_create_agent")!.execute(input, { sessionID: "caller" }),
-        ).rejects.toMatchObject({ message: payload.error, status: 500 });
+        ).rejects.toMatchObject({
+          status: 400,
+          message: expect.stringContaining(
+            "Invalid tool input: provider: provider must be provider/model, for example codex/gpt-5.4",
+          ),
+        });
       } finally {
         await dispose();
       }
@@ -550,6 +567,104 @@ describe("OpenCodeBridge", () => {
     }
   });
 
+  test("returns actionable 4xx responses for invalid bridge requests", async () => {
+    const paseoHome = await mkdtemp(path.join(tmpdir(), "paseo-opencode-bridge-errors-"));
+    temporaryDirectories.push(paseoHome);
+    const bridge = new OpenCodeBridge({ paseoHome, logger: createTestLogger() });
+    await bridge.start();
+    const catalog = createCatalog();
+    bridge.bindSession({ sessionId: "ses_errors", env: {}, tools: catalog });
+    const expectedErrorCatalog: PaseoToolCatalog = {
+      tools: new Map([
+        [
+          "expected_error",
+          {
+            name: "expected_error",
+            description: "Throws an expected tool error.",
+            inputSchema: {},
+            async handler() {
+              throw new PaseoToolInputError("Agent not found: missing-agent");
+            },
+          },
+        ],
+        [
+          "internal_error",
+          {
+            name: "internal_error",
+            description: "Throws an internal error.",
+            inputSchema: {},
+            async handler() {
+              throw new Error("Provider unavailable");
+            },
+          },
+        ],
+      ]),
+      getTool(name) {
+        return this.tools.get(name);
+      },
+      async executeTool(name, input, context) {
+        const tool = this.tools.get(name);
+        if (!tool) throw new Error(`Unknown tool: ${name}`);
+        return tool.handler(input, context ?? {});
+      },
+    };
+    bridge.bindSession({ sessionId: "ses_expected_error", env: {}, tools: expectedErrorCatalog });
+
+    try {
+      const plugin = readPluginOptions(bridge.decorateServerEnv({}));
+      const headers = {
+        Authorization: `Bearer ${plugin.token}`,
+        "Content-Type": "application/json",
+      };
+      const invalidInput = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_errors/tools/echo_context`,
+        { method: "POST", headers, body: JSON.stringify({ value: "ok", extra: true }) },
+      );
+      expect(invalidInput.status).toBe(400);
+      expect(await invalidInput.json()).toEqual({
+        error: "Invalid tool input",
+        issues: [
+          {
+            code: "unrecognized_keys",
+            keys: ["extra"],
+            path: [],
+            message: 'Unrecognized key: "extra"',
+          },
+        ],
+      });
+
+      const unknownTool = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_errors/tools/missing`,
+        { method: "POST", headers, body: "{}" },
+      );
+      expect(unknownTool.status).toBe(404);
+      expect(await unknownTool.json()).toEqual({ error: "Paseo tool not found: missing" });
+
+      const malformedBody = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_errors/tools/echo_context`,
+        { method: "POST", headers, body: "{" },
+      );
+      expect(malformedBody.status).toBe(400);
+      expect(await malformedBody.json()).toEqual({ error: "Malformed JSON request body" });
+
+      const expectedError = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_expected_error/tools/expected_error`,
+        { method: "POST", headers, body: "{}" },
+      );
+      expect(expectedError.status).toBe(400);
+      expect(await expectedError.json()).toEqual({ error: "Agent not found: missing-agent" });
+
+      const internalError = await fetch(
+        `${plugin.baseUrl}/_internal/opencode/sessions/ses_expected_error/tools/internal_error`,
+        { method: "POST", headers, body: "{}" },
+      );
+      expect(internalError.status).toBe(500);
+      expect(await internalError.json()).toEqual({ error: "Provider unavailable" });
+    } finally {
+      await bridge.close();
+    }
+  });
+
   test("preserves user OpenCode config while installing one content-addressed plugin", async () => {
     const paseoHome = await mkdtemp(path.join(tmpdir(), "paseo-opencode-bridge-config-"));
     temporaryDirectories.push(paseoHome);

packages/server/src/server/agent/providers/opencode/bridge.ts

@@ -11,11 +11,22 @@ import {
   addModelVisibleStructuredContent,
   serializePaseoToolInputParameters,
 } from "../../tools/paseo-tool-serialization.js";
-import type { PaseoToolCatalog } from "../../tools/types.js";
+import { PaseoToolInputError, type PaseoToolCatalog } from "../../tools/types.js";
 
 const INTERNAL_PREFIX = "/_internal/opencode";
 const MAX_REQUEST_BYTES = 1024 * 1024;
 
+class OpenCodeBridgeClientError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = "OpenCodeBridgeClientError";
+  }
+}
+
 interface OpenCodeBridgeOptions {
   paseoHome: string;
   logger: Logger;
@@ -187,10 +198,26 @@ export class OpenCodeBridge {
       sendJson(response, 404, { error: "Not found" });
     } catch (error) {
       this.logger.warn({ err: error }, "OpenCode bridge request failed");
+      const failure = error instanceof Error ? error : new Error(String(error));
       if (!response.headersSent) {
-        sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        if (error instanceof OpenCodeBridgeClientError) {
+          sendJson(response, error.status, {
+            error: error.message,
+            ...(error.details === undefined ? {} : { details: error.details }),
+          });
+        } else if (error instanceof PaseoToolInputError) {
+          sendJson(
+            response,
+            error.status,
+            error.issues
+              ? { error: "Invalid tool input", issues: error.issues }
+              : { error: error.message },
+          );
+        } else {
+          sendJson(response, 500, { error: failure.message });
+        }
       } else {
-        response.destroy(error instanceof Error ? error : new Error(String(error)));
+        response.destroy(failure);
       }
     }
   }
@@ -224,6 +251,9 @@ export class OpenCodeBridge {
       sendJson(input.response, 403, { error: "Paseo tools are disabled for this session" });
       return;
     }
+    if (!binding.tools.getTool(input.toolName)) {
+      throw new OpenCodeBridgeClientError(404, `Paseo tool not found: ${input.toolName}`);
+    }
     const body = await readJsonBody(input.request);
     const controller = new AbortController();
     input.request.once("aborted", () =>
@@ -349,11 +379,17 @@ async function readJsonBody(request: IncomingMessage): Promise<unknown> {
   for await (const chunk of request) {
     const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
     size += buffer.byteLength;
-    if (size > MAX_REQUEST_BYTES) throw new Error("OpenCode bridge request body is too large");
+    if (size > MAX_REQUEST_BYTES) {
+      throw new OpenCodeBridgeClientError(413, "OpenCode bridge request body is too large");
+    }
     chunks.push(buffer);
   }
   if (chunks.length === 0) return {};
-  return JSON.parse(Buffer.concat(chunks).toString("utf8")) as unknown;
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8")) as unknown;
+  } catch {
+    throw new OpenCodeBridgeClientError(400, "Malformed JSON request body");
+  }
 }
 
 function sendJson(response: ServerResponse, status: number, body: unknown): void {

packages/server/src/server/agent/providers/opencode/v2/bridge-plugin.mjs

@@ -15,12 +15,14 @@ export default {
       if (allowMissing && response.status === 404) return null;
       if (!response.ok) {
         const payload = await response.json().catch(() => null);
+        const detail = formatErrorDetail(payload?.issues ?? payload?.details);
         const message =
           typeof payload?.error === "string" && payload.error
             ? payload.error
             : `Paseo tool bridge returned HTTP ${response.status}`;
-        const error = new Error(message);
+        const error = new Error(detail ? `${message}: ${detail}` : message);
         error.status = response.status;
+        if (detail) error.details = detail;
         throw error;
       }
       return response.json();
@@ -78,6 +80,17 @@ export default {
   },
 };
 
+function formatErrorDetail(details) {
+  if (!Array.isArray(details)) return typeof details === "string" ? details : "";
+  return details
+    .map((issue) => {
+      const path =
+        Array.isArray(issue?.path) && issue.path.length > 0 ? issue.path.join(".") : "input";
+      return `${path}: ${issue?.message ?? "Invalid value"}`;
+    })
+    .join("; ");
+}
+
 // OpenCode tool content is text or a file; MCP images arrive as base64 data.
 function toOpenCodeContent(part) {
   if (part.type === "image") {

packages/server/src/server/agent/tools/paseo-tools.ts

@@ -25,7 +25,7 @@ import {
 import { curateAgentActivity } from "../activity-curator.js";
 import { selectItemsByProjectedLimit } from "../timeline-projection.js";
 import type { AgentStorage } from "../agent-storage.js";
-import { ensureAgentLoaded } from "../agent-loading.js";
+import { AgentNotFoundError, ensureAgentLoaded } from "../agent-loading.js";
 import { isStoredAgentProviderAvailable } from "../../persistence-hooks.js";
 import {
   archiveByScope,
@@ -40,7 +40,12 @@ import { everyMsToFiveFieldCron } from "@getpaseo/protocol/schedule/cadence";
 import { expandUserPath, isSameOrDescendantPath, resolvePathFromBase } from "../../path-utils.js";
 import type { TerminalManager } from "../../../terminal/terminal-manager.js";
 import type { CreatePaseoWorktreeWorkflowFn } from "../../worktree-session.js";
-import type { ScheduleService } from "../../schedule/service.js";
+import { computeNextRunAt, validateScheduleCadence } from "../../schedule/cron.js";
+import {
+  ScheduleNotFoundError,
+  ScheduleStateConflictError,
+  type ScheduleService,
+} from "../../schedule/service.js";
 import {
   ScheduleRunSchema,
   ScheduleSummarySchema,
@@ -91,12 +96,13 @@ import {
 } from "../../worktree/commands.js";
 import { registerBrowserTools } from "../../browser-tools/tools.js";
 import type { BrowserToolsBroker } from "../../browser-tools/broker.js";
-import type {
-  PaseoToolCatalog,
-  PaseoToolConfig,
-  PaseoToolDefinition,
-  PaseoToolExecutionContext,
-  PaseoToolResult,
+import {
+  PaseoToolInputError,
+  type PaseoToolCatalog,
+  type PaseoToolConfig,
+  type PaseoToolDefinition,
+  type PaseoToolExecutionContext,
+  type PaseoToolResult,
 } from "./types.js";
 import type { ProviderPaseoToolsPolicy } from "@getpaseo/protocol/provider-config";
 import { isPaseoToolEnabled } from "../paseo-tool-policy.js";
@@ -229,7 +235,7 @@ function assertOptionsAbsent(
   message: string,
 ): void {
   if (options.some(([, value]) => value !== undefined)) {
-    throw new Error(message);
+    throw new PaseoToolInputError(message);
   }
 }
 
@@ -265,7 +271,7 @@ function resolveWorkspaceWorktreeTarget(input: WorkspaceWorktreeOptions): Worksp
       };
     case "checkout-branch":
       if (!input.branch) {
-        throw new Error("branch is required for checkout-branch mode");
+        throw new PaseoToolInputError("branch is required for checkout-branch mode");
       }
       assertOptionsAbsent(
         [
@@ -279,7 +285,7 @@ function resolveWorkspaceWorktreeTarget(input: WorkspaceWorktreeOptions): Worksp
       return { action: "checkout", refName: input.branch };
     case "checkout-pr":
       if (input.prNumber === undefined) {
-        throw new Error("prNumber is required for checkout-pr mode");
+        throw new PaseoToolInputError("prNumber is required for checkout-pr mode");
       }
       assertOptionsAbsent(
         [
@@ -355,7 +361,7 @@ function resolveScheduleProviderAndModel(params: {
   const provider = providerInput.slice(0, slashIndex).trim();
   const model = providerInput.slice(slashIndex + 1).trim();
   if (!provider || !model) {
-    throw new Error("provider must be <provider> or <provider>/<model>");
+    throw new PaseoToolInputError("provider must be <provider> or <provider>/<model>");
   }
 
   return {
@@ -372,7 +378,7 @@ function resolveScheduleUpdateProviderAndModel(params: {
   const modelInput = typeof params.model === "string" ? params.model.trim() : params.model;
 
   if (params.model !== undefined && modelInput === "") {
-    throw new Error("model cannot be empty");
+    throw new PaseoToolInputError("model cannot be empty");
   }
 
   if (!providerInput) {
@@ -390,13 +396,13 @@ function resolveScheduleUpdateProviderAndModel(params: {
   const provider = providerInput.slice(0, slashIndex).trim();
   const modelFromProvider = providerInput.slice(slashIndex + 1).trim();
   if (!provider || !modelFromProvider) {
-    throw new Error("provider must be <provider> or <provider>/<model>");
+    throw new PaseoToolInputError("provider must be <provider> or <provider>/<model>");
   }
   if (params.model === null) {
-    throw new Error("provider specifies a model but model is null");
+    throw new PaseoToolInputError("provider specifies a model but model is null");
   }
   if (typeof modelInput === "string" && modelInput !== modelFromProvider) {
-    throw new Error("Conflicting model values provided");
+    throw new PaseoToolInputError("Conflicting model values provided");
   }
 
   return {
@@ -438,26 +444,82 @@ function normalizeScheduleTimeZoneArg(value: string | undefined): string | undef
   return normalizeScheduleCadenceArg(value);
 }
 
+function addScheduleCadenceIssue(
+  input: { cron?: string; timezone?: string },
+  context: z.RefinementCtx,
+): void {
+  const expression = input.cron?.trim();
+  if (!expression) {
+    return;
+  }
+  const cadence: ScheduleCadence = {
+    type: "cron",
+    expression,
+    ...(input.timezone !== undefined ? { timezone: input.timezone.trim() } : {}),
+  };
+  try {
+    validateScheduleCadence(cadence);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    context.addIssue({
+      code: "custom",
+      path: [message.startsWith("Invalid cron time zone:") ? "timezone" : "cron"],
+      message,
+    });
+    return;
+  }
+  try {
+    computeNextRunAt(cadence, new Date());
+  } catch (error) {
+    context.addIssue({
+      code: "custom",
+      path: ["cron"],
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+function parseToolArguments<T>(schema: z.ZodType<T>, input: unknown): T {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    throw new PaseoToolInputError(result.error.message, result.error.issues);
+  }
+  return result.data;
+}
+
+function addScheduleDurationIssue(value: string, context: z.RefinementCtx): void {
+  try {
+    parseDurationString(value);
+  } catch (error) {
+    context.addIssue({
+      code: "custom",
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+const scheduleDurationInputSchema = z.string().superRefine(addScheduleDurationIssue);
+
 function resolveScheduleUpdateCadence(input: ScheduleUpdateToolInput): ScheduleCadence | undefined {
   const every = normalizeScheduleCadenceArg(input.every);
   const cron = normalizeScheduleCadenceArg(input.cron);
   const timeZone = normalizeScheduleTimeZoneArg(input.timezone);
 
   if (every !== undefined && cron !== undefined) {
-    throw new Error("Specify at most one of every or cron");
+    throw new PaseoToolInputError("Specify at most one of every or cron");
   }
   if (timeZone !== undefined && cron === undefined) {
-    throw new Error("timezone can only be used with cron");
+    throw new PaseoToolInputError("timezone can only be used with cron");
   }
   if (every !== undefined) {
     // COMPAT(scheduleEveryInput): accept the old hidden field and canonicalize it before write.
     // Added in v0.2.0; remove after 2027-01-17.
-    const everyMs = parseDurationString(every);
+    const everyMs = parseDurationString(parseToolArguments(scheduleDurationInputSchema, every));
     const expression = everyMsToFiveFieldCron(everyMs);
     if (expression) {
       return { type: "cron", expression };
     }
-    throw new Error(`${every} cannot be represented faithfully by five-field cron`);
+    throw new PaseoToolInputError(`${every} cannot be represented faithfully by five-field cron`);
   }
   if (cron !== undefined) {
     return {
@@ -471,7 +533,7 @@ function resolveScheduleUpdateCadence(input: ScheduleUpdateToolInput): ScheduleC
 
 function resolveScheduleUpdateExpiresAt(input: ScheduleUpdateToolInput): string | null | undefined {
   if (input.expiresIn !== undefined && input.clearExpires) {
-    throw new Error("Specify at most one of expiresIn or clearExpires");
+    throw new PaseoToolInputError("Specify at most one of expiresIn or clearExpires");
   }
   if (input.expiresIn !== undefined) {
     return new Date(Date.now() + parseDurationString(input.expiresIn)).toISOString();
@@ -593,7 +655,11 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       typeof (inputSchema as { safeParseAsync?: unknown }).safeParseAsync === "function"
         ? (inputSchema as z.ZodType)
         : z.object(inputSchema as z.ZodRawShape).passthrough();
-    return schema.parseAsync(input);
+    const result = await schema.safeParseAsync(input);
+    if (!result.success) {
+      throw new PaseoToolInputError(result.error.message, result.error.issues);
+    }
+    return result.data;
   };
 
   const tools = new Map<string, PaseoToolDefinition>();
@@ -627,7 +693,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     ): Promise<PaseoToolResult> {
       const tool = tools.get(name);
       if (!tool) {
-        throw new Error(`Paseo tool not found: ${name}`);
+        throw new PaseoToolInputError(`Paseo tool not found: ${name}`);
       }
       return tool.handler(await parseToolInput(tool, input), context);
     },
@@ -639,7 +705,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
   }): ScheduleCadence => {
     const expression = input.cron?.trim() ?? "";
     if (!expression) {
-      throw new Error("cron is required");
+      throw new PaseoToolInputError("cron is required");
     }
     const timezone = normalizeScheduleTimeZoneArg(input.timezone);
     return {
@@ -661,7 +727,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     }
     const parentAgent = agentManager.getAgent(callerAgentId);
     if (!parentAgent) {
-      throw new Error(`Parent agent ${callerAgentId} not found`);
+      throw new PaseoToolInputError(`Parent agent ${callerAgentId} not found`);
     }
     return parentAgent;
   };
@@ -690,9 +756,9 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     const trimmedCwd = requestedCwd?.trim();
     if (!trimmedCwd) {
       if (opts?.required) {
-        throw new Error("cwd is required");
+        throw new PaseoToolInputError("cwd is required");
       }
-      throw new Error("cwd is required outside an agent-scoped session");
+      throw new PaseoToolInputError("cwd is required outside an agent-scoped session");
     }
 
     return expandUserPath(trimmedCwd);
@@ -707,11 +773,12 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     }
 
     if (!options.ensureWorkspaceForCreate) {
-      throw new Error(
-        callerAgentId
-          ? `Caller agent ${callerAgentId} has no workspace and workspace minting is not configured`
-          : "workspaceId is required outside an agent-scoped session",
-      );
+      if (callerAgentId) {
+        throw new Error(
+          `Caller agent ${callerAgentId} has no workspace and workspace minting is not configured`,
+        );
+      }
+      throw new PaseoToolInputError("workspaceId is required outside an agent-scoped session");
     }
 
     return options.ensureWorkspaceForCreate(resolvedCwd);
@@ -726,11 +793,11 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     if (callerAgentId) {
       const callerAgent = resolveCallerAgent();
       if (!callerAgent?.workspaceId) {
-        throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+        throw new PaseoToolInputError(`Caller agent ${callerAgentId} has no current workspace`);
       }
       return callerAgent.workspaceId;
     }
-    throw new Error("workspaceId is required outside an agent-scoped session");
+    throw new PaseoToolInputError("workspaceId is required outside an agent-scoped session");
   }
 
   const buildCallerAgentScheduleConfigExtras = (
@@ -800,7 +867,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     }
 
     if (!params?.provider?.trim()) {
-      throw new Error("provider is required when target is new-agent");
+      throw new PaseoToolInputError("provider is required when target is new-agent");
     }
 
     const resolvedProviderModel = resolveScheduleProviderAndModel({
@@ -822,22 +889,41 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     if (!scheduleService) {
       throw new Error("Schedule service is not configured");
     }
-    const schedule = await scheduleService.inspect(id);
+    let schedule: Awaited<ReturnType<ScheduleService["inspect"]>>;
+    try {
+      schedule = await scheduleService.inspect(id);
+    } catch (error) {
+      if (error instanceof ScheduleNotFoundError) {
+        throw new PaseoToolInputError(error.message);
+      }
+      throw error;
+    }
     if (schedule.target.type !== type) {
-      throw new Error(
+      throw new PaseoToolInputError(
         type === "agent" ? `Heartbeat not found: ${id}` : `Schedule not found: ${id}`,
       );
     }
     return schedule;
   }
 
+  async function runScheduleAction<T>(action: () => Promise<T>): Promise<T> {
+    try {
+      return await action();
+    } catch (error) {
+      if (error instanceof ScheduleStateConflictError) {
+        throw new PaseoToolInputError(error.message);
+      }
+      throw error;
+    }
+  }
+
   async function requireCallerHeartbeat(id: string) {
     if (!callerAgentId) {
-      throw new Error("Heartbeat operations require an agent-scoped session");
+      throw new PaseoToolInputError("Heartbeat operations require an agent-scoped session");
     }
     const schedule = await requireScheduleTarget(id, "agent");
     if (schedule.target.type !== "agent" || schedule.target.agentId !== callerAgentId) {
-      throw new Error(`Heartbeat ${id} does not belong to caller ${callerAgentId}`);
+      throw new PaseoToolInputError(`Heartbeat ${id} does not belong to caller ${callerAgentId}`);
     }
     return schedule;
   }
@@ -847,6 +933,9 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     })
     .refine(
       (value) => {
+        if (!value.includes("/")) {
+          return true;
+        }
         try {
           resolveRequiredProviderModel(value);
           return true;
@@ -1184,11 +1273,13 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       },
       async (args, context) => {
         if (!callerAgentId) {
-          throw new Error("speak is only available to agent-scoped tool sessions");
+          throw new PaseoToolInputError("speak is only available to agent-scoped tool sessions");
         }
         const handler = resolveSpeakHandler?.(callerAgentId) ?? null;
         if (!handler) {
-          throw new Error(`No speak handler registered for your session '${callerAgentId}'`);
+          throw new PaseoToolInputError(
+            `No speak handler registered for your session '${callerAgentId}'`,
+          );
         }
         await handler({
           text: args.text,
@@ -1289,7 +1380,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       if (isolation === "local") {
         const cwd = resolveScopedCwd(path, { required: true });
         if (!(await isExistingDirectory(cwd))) {
-          throw new Error(`Directory not found: ${cwd}`);
+          throw new PaseoToolInputError(`Directory not found: ${cwd}`);
         }
         assertOptionsAbsent(
           [
@@ -1534,7 +1625,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       if (hasLegacyCreateAgentPlacement(args)) {
         // COMPAT(nestedCreateAgentPlacement): accept the old relationship/workspace shape without
         // advertising it to models. Added in v0.2.0; remove after 2027-01-17.
-        const parsed = legacyAgentToAgentCreateAgentArgsSchema.parse(args);
+        const parsed = parseToolArguments(legacyAgentToAgentCreateAgentArgsSchema, args);
         const { cwd, workspaceId, worktree } = await resolveCreateAgentWorkspace(parsed.workspace, {
           prompt: parsed.initialPrompt,
         });
@@ -1547,7 +1638,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
           worktree,
         };
       }
-      const parsed = agentToAgentCreateAgentArgsSchema.parse(args);
+      const parsed = parseToolArguments(agentToAgentCreateAgentArgsSchema, args);
       const { cwd, workspaceId } = await resolveCanonicalCreateAgentWorkspace(parsed.workspaceId, {
         prompt: parsed.initialPrompt,
       });
@@ -1563,13 +1654,15 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     if (hasLegacyCreateAgentPlacement(args)) {
       // COMPAT(nestedCreateAgentPlacement): see the agent-scoped branch above.
       const parsedArgs = normalizeTopLevelCreateAgentArgs(
-        legacyTopLevelCreateAgentArgsSchema.parse(args),
+        parseToolArguments(legacyTopLevelCreateAgentArgsSchema, args),
       );
       if (parsedArgs.relationship?.kind === "subagent") {
-        throw new Error("relationship subagent requires an agent-scoped tool session");
+        throw new PaseoToolInputError(
+          "relationship subagent requires an agent-scoped tool session",
+        );
       }
       if (!parsedArgs.workspace) {
-        throw new Error("Legacy create_agent placement could not be resolved");
+        throw new PaseoToolInputError("Legacy create_agent placement could not be resolved");
       }
       const { cwd, workspaceId, worktree } = await resolveCreateAgentWorkspace(
         parsedArgs.workspace,
@@ -1584,7 +1677,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         worktree,
       };
     }
-    const parsedArgs = canonicalTopLevelCreateAgentArgsSchema.parse(args);
+    const parsedArgs = parseToolArguments(canonicalTopLevelCreateAgentArgsSchema, args);
     const { cwd, workspaceId } = await resolveCanonicalCreateAgentWorkspace(
       parsedArgs.workspaceId,
       { prompt: parsedArgs.initialPrompt },
@@ -1644,7 +1737,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     }
     const caller = resolveCallerAgent();
     if (!caller?.workspaceId) {
-      throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+      throw new PaseoToolInputError(`Caller agent ${callerAgentId} has no current workspace`);
     }
     return { cwd: undefined, workspaceId: caller.workspaceId };
   }
@@ -1672,18 +1765,18 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     };
 
     if (canonicalCandidate.relationship && canonicalCandidate.workspace) {
-      return legacyTopLevelCreateAgentArgsSchema.parse({
+      return parseToolArguments(legacyTopLevelCreateAgentArgsSchema, {
         ...canonicalCandidate,
         ...(Object.keys(settings).length > 0 ? { settings } : {}),
       });
     }
 
     if (canonicalCandidate.relationship || canonicalCandidate.workspace) {
-      throw new Error("relationship and workspace must be provided together");
+      throw new PaseoToolInputError("relationship and workspace must be provided together");
     }
 
     if (!cwd?.trim()) {
-      throw new Error("cwd is required for legacy top-level create_agent calls");
+      throw new PaseoToolInputError("cwd is required for legacy top-level create_agent calls");
     }
 
     const legacyWorktreeTarget = resolveLegacyCreateAgentWorktreeTarget({
@@ -1710,7 +1803,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
           },
         };
 
-    return legacyTopLevelCreateAgentArgsSchema.parse({
+    return parseToolArguments(legacyTopLevelCreateAgentArgsSchema, {
       ...canonicalCandidate,
       relationship: { kind: "detached" },
       workspace,
@@ -1763,11 +1856,11 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
   }> {
     if (workspace.kind === "current") {
       if (!callerAgentId) {
-        throw new Error("workspace current requires an agent-scoped tool session");
+        throw new PaseoToolInputError("workspace current requires an agent-scoped tool session");
       }
       const callerAgent = resolveCallerAgent();
       if (!callerAgent?.workspaceId) {
-        throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+        throw new PaseoToolInputError(`Caller agent ${callerAgentId} has no current workspace`);
       }
       return {
         cwd: workspace.cwd,
@@ -1784,14 +1877,16 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         (candidate) => candidate.workspaceId === workspace.workspaceId,
       );
       if (!existingWorkspace) {
-        throw new Error(`Workspace ${workspace.workspaceId} not found`);
+        throw new PaseoToolInputError(`Workspace ${workspace.workspaceId} not found`);
       }
       const cwd = workspace.cwd
         ? resolveScopedCwd(workspace.cwd, { required: true })
         : existingWorkspace.cwd;
       const lockedCwd = callerContext?.lockedCwd?.trim();
       if (lockedCwd && !isSameOrDescendantPath(expandUserPath(lockedCwd), cwd)) {
-        throw new Error(`Workspace ${workspace.workspaceId} is outside the allowed cwd`);
+        throw new PaseoToolInputError(
+          `Workspace ${workspace.workspaceId} is outside the allowed cwd`,
+        );
       }
       return {
         cwd,
@@ -1893,6 +1988,9 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         logger: childLogger,
       }).catch((error) => {
         stopNotification?.();
+        if (error instanceof AgentNotFoundError) {
+          throw new PaseoToolInputError(error.message);
+        }
         throw error;
       });
 
@@ -1956,7 +2054,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
 
       const record = await agentStorage.get(agentId);
       if (!record || record.internal) {
-        throw new Error(`Agent ${agentId} not found`);
+        throw new PaseoToolInputError(`Agent ${agentId} not found`);
       }
 
       const structuredSnapshot = buildStoredAgentPayload(
@@ -2194,10 +2292,10 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       const workspaceId = resolveWorkspaceIdForRename(requestedWorkspaceId);
       const existing = await options.workspaceRegistry.get(workspaceId);
       if (!existing) {
-        throw new Error(`Workspace ${workspaceId} not found`);
+        throw new PaseoToolInputError(`Workspace ${workspaceId} not found`);
       }
       if (existing.archivedAt) {
-        throw new Error(`Workspace ${workspaceId} is archived`);
+        throw new PaseoToolInputError(`Workspace ${workspaceId} is archived`);
       }
 
       await options.workspaceRegistry.upsert({
@@ -2401,7 +2499,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
 
       const terminal = terminalManager.getTerminal(terminalId);
       if (!terminal) {
-        throw new Error(`Terminal ${terminalId} not found`);
+        throw new PaseoToolInputError(`Terminal ${terminalId} not found`);
       }
 
       terminal.kill();
@@ -2437,7 +2535,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       }
 
       if (!terminalManager.getTerminal(terminalId)) {
-        throw new Error(`Terminal ${terminalId} not found`);
+        throw new PaseoToolInputError(`Terminal ${terminalId} not found`);
       }
 
       const capture = await terminalManager.captureTerminal(terminalId, {
@@ -2478,7 +2576,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
 
       const terminal = terminalManager.getTerminal(terminalId);
       if (!terminal) {
-        throw new Error(`Terminal ${terminalId} not found`);
+        throw new PaseoToolInputError(`Terminal ${terminalId} not found`);
       }
 
       terminal.send({
@@ -2498,24 +2596,26 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     {
       title: "Create schedule",
       description: "Create a recurring schedule that starts a new agent on a cron cadence.",
-      inputSchema: {
-        prompt: z.string().trim().min(1, "prompt is required"),
-        cron: z.string().trim().min(1, "cron is required"),
-        timezone: z
-          .string()
-          .trim()
-          .min(1)
-          .optional()
-          .describe("IANA time zone for the cron cadence. For example: America/New_York."),
-        name: z.string().optional(),
-        provider: (callerAgentId ? AgentProviderEnum.optional() : AgentProviderEnum).describe(
-          "Provider, or provider/model (for example: codex or codex/gpt-5.4). Defaults to the caller's provider in an agent-scoped session.",
-        ),
-        cwd: z.string().optional(),
-        isolation: z.enum(["local", "worktree"]).optional(),
-        maxRuns: z.number().int().positive().optional(),
-        expiresIn: z.string().optional(),
-      },
+      inputSchema: z
+        .object({
+          prompt: z.string().trim().min(1, "prompt is required"),
+          cron: z.string().trim().min(1, "cron is required"),
+          timezone: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("IANA time zone for the cron cadence. For example: America/New_York."),
+          name: z.string().optional(),
+          provider: (callerAgentId ? AgentProviderEnum.optional() : AgentProviderEnum).describe(
+            "Provider, or provider/model (for example: codex or codex/gpt-5.4). Defaults to the caller's provider in an agent-scoped session.",
+          ),
+          cwd: z.string().optional(),
+          isolation: z.enum(["local", "worktree"]).optional(),
+          maxRuns: z.number().int().positive().optional(),
+          expiresIn: scheduleDurationInputSchema.optional(),
+        })
+        .superRefine(addScheduleCadenceIssue),
       outputSchema: ScheduleSummarySchema.shape,
     },
     async ({ prompt, cron, timezone, name, provider, cwd, isolation, maxRuns, expiresIn }) => {
@@ -2548,19 +2648,21 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
     {
       title: "Create heartbeat",
       description: "Create a recurring heartbeat that sends you a prompt on a cron cadence.",
-      inputSchema: {
-        prompt: z.string().trim().min(1, "prompt is required"),
-        cron: z.string().trim().min(1, "cron is required"),
-        timezone: z
-          .string()
-          .trim()
-          .min(1)
-          .optional()
-          .describe("IANA time zone for the cron cadence. For example: America/New_York."),
-        name: z.string().optional(),
-        maxRuns: z.number().int().positive().optional(),
-        expiresIn: z.string().optional(),
-      },
+      inputSchema: z
+        .object({
+          prompt: z.string().trim().min(1, "prompt is required"),
+          cron: z.string().trim().min(1, "cron is required"),
+          timezone: z
+            .string()
+            .trim()
+            .min(1)
+            .optional()
+            .describe("IANA time zone for the cron cadence. For example: America/New_York."),
+          name: z.string().optional(),
+          maxRuns: z.number().int().positive().optional(),
+          expiresIn: scheduleDurationInputSchema.optional(),
+        })
+        .superRefine(addScheduleCadenceIssue),
       outputSchema: ScheduleSummarySchema.shape,
     },
     async ({ prompt, cron, timezone, name, maxRuns, expiresIn }) => {
@@ -2568,7 +2670,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         throw new Error("Schedule service is not configured");
       }
       if (!callerAgentId) {
-        throw new Error("create_heartbeat requires an agent-scoped session");
+        throw new PaseoToolInputError("create_heartbeat requires an agent-scoped session");
       }
       resolveCallerAgent();
 
@@ -2679,7 +2781,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       }
 
       await requireScheduleTarget(id, "new-agent");
-      await scheduleService.pause(id);
+      await runScheduleAction(() => scheduleService.pause(id));
       return {
         content: [],
         structuredContent: ensureValidJson({ success: true }),
@@ -2705,7 +2807,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       }
 
       await requireScheduleTarget(id, "new-agent");
-      await scheduleService.resume(id);
+      await runScheduleAction(() => scheduleService.resume(id));
       return {
         content: [],
         structuredContent: ensureValidJson({ success: true }),
@@ -2787,13 +2889,13 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
             .optional()
             .describe("New mode for new-agent target (null to clear)."),
           cwd: z.string().trim().min(1).optional().describe("New cwd for new-agent target."),
-          expiresIn: z
-            .string()
+          expiresIn: scheduleDurationInputSchema
             .optional()
             .describe("New relative expiry duration (for example: 1h, 2d)."),
           clearExpires: z.boolean().optional().describe("Clear any schedule expiry."),
         })
-        .passthrough(),
+        .passthrough()
+        .superRefine(addScheduleCadenceIssue),
       outputSchema: StoredScheduleSchema.shape,
     },
     async (input) => {
@@ -2850,7 +2952,7 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
         throw new Error("Schedule service is not configured");
       }
       await requireScheduleTarget(id, "new-agent");
-      const schedule = await scheduleService.runOnce(id);
+      const schedule = await runScheduleAction(() => scheduleService.runOnce(id));
       return {
         content: [],
         structuredContent: ensureValidJson(schedule),
@@ -2963,10 +3065,10 @@ export function createPaseoToolCatalog(options: PaseoToolHostDependencies): Pase
       });
       const summary = toProviderSummary(entry);
       if (!entry.enabled) {
-        throw new Error(`Provider '${providerId}' is disabled`);
+        throw new PaseoToolInputError(`Provider '${providerId}' is disabled`);
       }
       if (entry.status !== "ready") {
-        throw new Error(entry.error ?? `Provider '${providerId}' is unavailable`);
+        throw new PaseoToolInputError(entry.error ?? `Provider '${providerId}' is unavailable`);
       }
       const selectedModel = settings?.model ?? resolvedProviderModel.model;
       const features = await agentManager.listDraftFeatures({

packages/server/src/server/agent/tools/types.ts

@@ -1,6 +1,18 @@
 import type { z } from "zod";
 import type { ProviderPaseoToolsPolicy } from "@getpaseo/protocol/provider-config";
 
+export class PaseoToolInputError extends Error {
+  readonly status = 400;
+
+  constructor(
+    message: string,
+    readonly issues?: z.ZodError["issues"],
+  ) {
+    super(message);
+    this.name = "PaseoToolInputError";
+  }
+}
+
 export interface PaseoToolExecutionContext {
   signal?: AbortSignal;
   sendUpdate?: (update: PaseoToolResult) => void;

packages/server/src/server/daemon-e2e/claude-settings-mid-turn.real.e2e.test.ts

@@ -0,0 +1,60 @@
+import { expect, test } from "vitest";
+import { mkdtemp, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import pino from "pino";
+import { ClaudeAgentClient } from "../agent/providers/claude/agent.js";
+import { createTestPaseoDaemon } from "../test-utils/paseo-daemon.js";
+import { DaemonClient } from "../test-utils/daemon-client.js";
+
+test("changing thinking then mode preserves a foreground Claude command", async () => {
+  const logger = pino({ level: "silent" });
+  const cwd = await mkdtemp(path.join(tmpdir(), "claude-settings-mid-turn-"));
+  const daemon = await createTestPaseoDaemon({
+    logger,
+    agentClients: { claude: new ClaudeAgentClient({ logger }) },
+  });
+  const client = new DaemonClient({ url: `ws://127.0.0.1:${daemon.port}/ws` });
+  try {
+    await client.connect();
+    await client.fetchAgents({ subscribe: {} });
+    const agent = await client.createAgent({
+      provider: "claude",
+      model: "claude-haiku-5-5",
+      modeId: "auto",
+      thinkingOptionId: "low",
+      cwd,
+    });
+    await client.subscribeAgentTimeline(agent.id, () => {}).ready;
+    await client.sendMessage(
+      agent.id,
+      "Run exactly these three Bash commands in the foreground, one per tool call, in order: python3 -c \"from pathlib import Path; import time; Path('started').write_text('started'); time.sleep(20); print(1)\", then the same with print(2), then print(3). Then reply DONE.",
+    );
+    // A tool-call row is emitted before Claude's permission check finishes.
+    // Wait for the command itself, so changing to acceptEdits cannot gate its start.
+    await expect.poll(() => existsSync(path.join(cwd, "started")), { timeout: 90_000 }).toBe(true);
+    const notice = await client.setAgentThinkingOption(agent.id, "medium");
+    expect(notice).toEqual({ type: "warning", message: "Thinking level applies next turn" });
+    await client.setAgentMode(agent.id, "acceptEdits");
+    await expect
+      .poll(
+        async () => {
+          const timeline = await client.fetchAgentTimeline(agent.id, { limit: 100 });
+          return timeline.entries.some(
+            ({ item }) =>
+              item.type === "tool_call" &&
+              item.detail.type === "shell" &&
+              item.detail.command.includes("print(1)") &&
+              item.status === "completed",
+          );
+        },
+        { timeout: 45_000, interval: 100 },
+      )
+      .toBe(true);
+  } finally {
+    await client.close();
+    await daemon.close();
+    await rm(cwd, { recursive: true, force: true });
+  }
+}, 180_000);

packages/server/src/server/daemon-e2e/omp.real.e2e.test.ts

@@ -5,6 +5,8 @@ import path from "node:path";
 import { promisify } from "node:util";
 
 import pino from "pino";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { afterEach, beforeAll, describe, expect, test } from "vitest";
 
 import type { AgentTimelineItem } from "../agent/agent-sdk-types.js";
@@ -131,6 +133,14 @@ async function timeline(client: DaemonClient, agentId: string): Promise<AgentTim
   return result.entries.map((entry) => entry.item);
 }
 
+async function readAssistantText(harness: Harness, agentId: string): Promise<string> {
+  const items = await timeline(harness.client, agentId);
+  return items
+    .filter((item) => item.type === "assistant_message")
+    .map((item) => item.text)
+    .join("");
+}
+
 function compactionFiller(records = 1200): string {
   const teas = ["assam", "darjeeling", "sencha", "oolong"];
   return Array.from(
@@ -257,8 +267,80 @@ async function contextWindowUsedTokens(client: DaemonClient, agentId: string) {
 
 describe("daemon E2E (real OMP)", () => {
   test(
-    "a prompt OMP rejects before its agent runs fails the turn with OMP's error",
+    "an idle out-of-band follow-up starts a turn",
     async () => {
+      const harness = await createHarness();
+      try {
+        const agent = await createAgent(harness, "idle-follow-up");
+        await harness.client.sendMessage(agent.id, "/follow-up Reply exactly IDLE_FOLLOWUP_OK");
+        await expect
+          .poll(() => readAssistantText(harness, agent.id), { timeout: 30_000 })
+          .toContain("IDLE_FOLLOWUP_OK");
+        const finish = await harness.client.waitForFinish(agent.id, TIMEOUT_MS);
+        expect(finish.status).toBe("idle");
+      } finally {
+        await closeHarness(harness);
+      }
+    },
+    TIMEOUT_MS,
+  );
+
+  test(
+    "an agent-sent idle follow-up starts a turn and notifies its parent",
+    async () => {
+      const harness = await createHarness();
+      const mcp = new Client({ name: "idle-follow-up-test", version: "1.0.0" });
+      try {
+        const parent = await createAgent(harness, "follow-up-parent");
+        const child = await createAgent(harness, "follow-up-child");
+        await mcp.connect(
+          new StreamableHTTPClientTransport(
+            new URL(
+              `http://127.0.0.1:${harness.daemon.port}/mcp/agents?callerAgentId=${parent.id}`,
+            ),
+          ),
+        );
+        const response = await mcp.callTool({
+          name: "send_agent_prompt",
+          arguments: { agentId: child.id, prompt: "/follow-up Reply exactly MCP_IDLE_FOLLOWUP_OK" },
+        });
+        expect(response.isError).not.toBe(true);
+        expect(response.structuredContent).toMatchObject({
+          success: true,
+          disposition: "out_of_band",
+        });
+        await expect
+          .poll(() => readAssistantText(harness, child.id), { timeout: 30_000 })
+          .toContain("MCP_IDLE_FOLLOWUP_OK");
+        await expect
+          .poll(
+            async () => {
+              const items = await timeline(harness.client, parent.id);
+              let notifications = 0;
+              for (const item of items) {
+                if (
+                  item.type === "tool_call" &&
+                  item.agentMessage?.sender.id === child.id &&
+                  item.agentMessage.event === "finished"
+                )
+                  notifications++;
+              }
+              return notifications;
+            },
+            { timeout: 15_000 },
+          )
+          .toBe(1);
+      } finally {
+        await mcp.close();
+        await closeHarness(harness);
+      }
+    },
+    TIMEOUT_MS,
+  );
+
+  test.each(["Reply with ok.", "/follow-up Reply with ok."])(
+    "a rejected %s fails the turn with OMP's error",
+    async (prompt) => {
       const harness = await createHarness({ ompHome: createOfflineOmpHome() });
       try {
         const agent = await harness.client.createAgent({
@@ -268,7 +350,7 @@ describe("daemon E2E (real OMP)", () => {
           model: "anthropic/claude-haiku-4-5",
           modeId: "full",
         });
-        await harness.client.sendMessage(agent.id, "Reply with ok.");
+        await harness.client.sendMessage(agent.id, prompt);
         const finish = await harness.client.waitForFinish(agent.id, 60_000);
         expect(finish.status).toBe("error");
         expect(finish.error).toContain("No API key found for anthropic");

packages/server/src/server/schedule/service.ts

@@ -38,6 +38,20 @@ export class ScheduleTargetGoneError extends Error {
   }
 }
 
+export class ScheduleNotFoundError extends Error {
+  constructor(id: string) {
+    super(`Schedule not found: ${id}`);
+    this.name = "ScheduleNotFoundError";
+  }
+}
+
+export class ScheduleStateConflictError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ScheduleStateConflictError";
+  }
+}
+
 function advanceNextRunAtPast(
   cadence: StoredSchedule["cadence"],
   nextRunAt: Date,
@@ -158,7 +172,7 @@ function shouldCompleteSchedule(schedule: StoredSchedule, now: Date): boolean {
 
 function requireSchedule(schedule: StoredSchedule | null, id: string): StoredSchedule {
   if (!schedule) {
-    throw new Error(`Schedule not found: ${id}`);
+    throw new ScheduleNotFoundError(id);
   }
   return schedule;
 }
@@ -392,10 +406,7 @@ export class ScheduleService {
 
   async inspect(id: string): Promise<StoredSchedule> {
     const schedule = await this.store.get(id);
-    if (!schedule) {
-      throw new Error(`Schedule not found: ${id}`);
-    }
-    return schedule;
+    return requireSchedule(schedule, id);
   }
 
   async logs(id: string): Promise<ScheduleRun[]> {
@@ -406,7 +417,7 @@ export class ScheduleService {
   async pause(id: string): Promise<StoredSchedule> {
     const paused = await this.store.update(id, (schedule) => {
       if (schedule.status === "completed") {
-        throw new Error(`Schedule ${id} is already completed`);
+        throw new ScheduleStateConflictError(`Schedule ${id} is already completed`);
       }
       if (schedule.status === "paused") {
         return schedule;
@@ -426,7 +437,7 @@ export class ScheduleService {
   async resume(id: string): Promise<StoredSchedule> {
     const resumed = await this.store.update(id, (schedule) => {
       if (schedule.status === "completed") {
-        throw new Error(`Schedule ${id} is already completed`);
+        throw new ScheduleStateConflictError(`Schedule ${id} is already completed`);
       }
       if (schedule.status === "active") {
         return schedule;
@@ -546,10 +557,10 @@ export class ScheduleService {
   async runOnce(id: string): Promise<StoredSchedule> {
     const schedule = await this.inspect(id);
     if (schedule.status === "completed") {
-      throw new Error(`Schedule ${id} is already completed`);
+      throw new ScheduleStateConflictError(`Schedule ${id} is already completed`);
     }
     if (this.runningScheduleIds.has(id)) {
-      throw new Error(`Schedule ${id} is already running`);
+      throw new ScheduleStateConflictError(`Schedule ${id} is already running`);
     }
     await this.runSchedule(schedule, this.now(), { manual: true });
     return this.inspect(id);

packages/server/src/server/test-utils/question-response-daemon.ts

@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+import {
+  MockLoadTestAgentClient,
+  MockLoadTestAgentSession,
+} from "../agent/providers/mock-load-test-agent.js";
+import { createTestPaseoDaemon } from "./paseo-daemon.js";
+
+const firstResponse = Promise.withResolvers<void>();
+
+class RetryQuestionSession extends MockLoadTestAgentSession {
+  private attempts = 0;
+
+  override async respondToPermission(
+    requestId: string,
+    response: Parameters<MockLoadTestAgentSession["respondToPermission"]>[1],
+  ) {
+    this.attempts += 1;
+    process.send?.({ type: "attempt", requestId, response, sessionId: this.id });
+    if (this.attempts === 1) {
+      await firstResponse.promise;
+      throw new Error("Synthetic question response failure");
+    }
+    return super.respondToPermission(requestId, response);
+  }
+}
+
+class RetryQuestionClient extends MockLoadTestAgentClient {
+  override async createSession(config: Parameters<MockLoadTestAgentClient["createSession"]>[0]) {
+    const session = new RetryQuestionSession({ config, sessionId: randomUUID() });
+    session.subscribe((event) => {
+      if (event.type === "permission_resolved") {
+        process.send?.({
+          type: "resolved",
+          requestId: event.requestId,
+          response: event.resolution,
+          sessionId: session.id,
+          pendingRequestIds: session.getPendingPermissions().map((request) => request.id),
+        });
+      }
+    });
+    return session;
+  }
+}
+
+async function main(): Promise<void> {
+  const daemon = await createTestPaseoDaemon({
+    agentClients: { mock: new RetryQuestionClient() },
+    isDev: true,
+    mcpEnabled: false,
+    corsAllowedOrigins: [`http://localhost:${process.env.E2E_METRO_PORT}`],
+  });
+  process.on("message", (message: unknown) => {
+    if (message === "release") firstResponse.resolve();
+  });
+  const shutdown = async () => {
+    firstResponse.resolve();
+    await daemon.close();
+    process.exit(0);
+  };
+  process.once("SIGINT", () => void shutdown());
+  process.once("SIGTERM", () => void shutdown());
+  process.once("disconnect", () => void shutdown());
+  process.send?.({ type: "ready", port: daemon.port, serverId: daemon.daemon.getServerId() });
+}
+
+void main().catch((error: unknown) => {
+  process.send?.({ type: "error", error: error instanceof Error ? error.message : String(error) });
+  process.exit(1);
+});

scripts/ci-workflow.test.mjs

@@ -37,7 +37,7 @@ function jobBlocks(source) {
   let currentJob;
 
   for (const line of source.split("\n")) {
-    const jobMatch = /^  ([a-z0-9-]+):\s*$/.exec(line);
+    const jobMatch = /^  ([a-z0-9_-]+):\s*$/.exec(line);
     if (jobMatch) {
       currentJob = jobMatch[1];
       jobs.set(currentJob, []);
@@ -303,3 +303,31 @@ test("desktop packaging smokes main pushes and only the pull requests that touch
     assert.match(source, new RegExp(`${action}@[0-9a-f]{40} # v\\d+\\.\\d+\\.\\d+`));
   }
 });
+
+test("stable iOS releases upload once and distribute to external testers before App Store review", () => {
+  const source = readFileSync(
+    new URL("packages/app/.eas/workflows/release-mobile.yml", repoRoot),
+    "utf8",
+  );
+  const jobs = jobBlocks(source);
+  const uploads = [...jobs.entries()].filter(
+    ([, lines]) =>
+      lines.some((line) => /^    type: (submit|testflight)$/.test(line)) &&
+      lines.some((line) => line.includes("needs.build_ios.outputs.build_id")),
+  );
+  assert.equal(uploads.length, 1, "the iOS binary must be uploaded exactly once");
+  const [distributionId, distributionLines] = uploads[0];
+  const distribution = distributionLines.join("\n");
+  assert.match(distribution, /^    type: testflight$/m);
+  assert.match(distribution, /external_groups:\s*\n\s+- Paseo Beta/);
+  assert.match(distribution, /^      submit_beta_review: true$/m);
+
+  const review = jobs.get("submit_ios_for_review").join("\n");
+  assert.match(review, new RegExp(`needs: \\[build_ios, ${distributionId}\\]`));
+  assert.match(review, /APP_VERSION="\$\{\{ needs\.build_ios\.outputs\.app_version \}\}"/);
+  assert.match(
+    review,
+    /APP_BUILD_VERSION="\$\{\{ needs\.build_ios\.outputs\.app_build_version \}\}"/,
+  );
+  assert.match(review, /bundle exec fastlane ios submit_review/);
+});

skills/paseo/SKILL.md

@@ -21,7 +21,7 @@ For a local daemon, `project create` defaults to the current directory and resol
 
 ## Workspaces
 
-**`create_workspace`** — create a workspace independently of any agent. Required: `isolation` (`local` or `worktree`). Worktree isolation supports `mode: "branch-off" | "checkout-branch" | "checkout-pr"`: use `branchName`/`baseBranch` for a new branch, `branch` for an existing branch, or `prNumber` plus optional `forge`/`projectPath` for a change request. `worktreeSlug` controls the managed path. Returns the workspace descriptor centered on `workspaceId`.
+**`create_workspace`** — create a workspace independently of any agent. Required: `isolation` (`local` or `worktree`). Worktree isolation supports `mode: "branch-off" | "checkout-branch" | "checkout-pr"`: use `branchName`/`baseBranch` for a new branch, `branch` for an existing branch, or `prNumber` plus optional `forge` for a change request. Use `path` for a local directory or source checkout and `projectId` for the owning project; when no path is supplied, a worktree may resolve its source from `projectId`. `worktreeSlug` controls the managed path. Returns the workspace descriptor centered on `workspaceId`.
 
 `background: true` hides a workspace from default lists and the sidebar while its contents remain durable and accessible; omit `background` to inherit your current workspace’s value (false without a caller), and override it only when the user explicitly asks.