From ec67bdb4ac500487a8a837e96916bbaf0721b117 Mon Sep 17 00:00:00 2001
From: Sawyer Hood <sawyerjhood@gmail.com>
Date: Wed, 19 Aug 2026 17:25:59 -0700
Subject: [PATCH 1/4] Prepare core, cloud, and test surfaces for the bb mobile
 app
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Small server/SDK/cloud/test changes the native client needs, with no mobile
code:

- Request-side `mobile` app surface (`x-bb-app-surface`): `@bb/config`
  `parseRequestAppSurface`, server request context + telemetry.
- `@bb/sdk`: `SdkResponseLike` transport/response contract,
  `projects.sidebarBootstrap()`.
- New `@bb/plugin-interaction-contracts` package with the ask-user-question
  and secrets pending-interaction schemas; both plugins re-export it.
- Fake provider `approve:<kind>` script step for approval fixtures.
- Integration harness `serverPort` / `bindHost` options, the long-lived
  mobile e2e backend and the TLS bb connect stub (`e2e:mobile-backend`,
  `e2e:mobile-connect-stub`).
- bb connect mobile pairing: `@bb/connect-client` machine-code pairing
  helpers, Settings → Remote access "Add mobile device" QR, the
  `bb connect machine-code` CLI command, guide/skill/docs updates.
- `/.well-known/apple-app-site-association` and `assetlinks.json` served by
  the connect gate worker and the apex web routes (`@bb/connect-db`
  `app-links`).

Co-Authored-By: Claude <noreply@anthropic.com>
---
 apps/connect/src/tunnel-do.ts                 |   6 +
 apps/connect/src/worker.test.ts               | 101 +++
 apps/connect/src/worker.ts                    |  16 +-
 apps/connect/wrangler.jsonc                   |   3 +
 apps/server/src/request-context.ts            |   8 +-
 .../skills/builtin-skills/bb-cli/SKILL.md     |  11 +-
 apps/server/src/services/system/telemetry.ts  |   6 +-
 apps/web/src/routeTree.gen.ts                 |  45 +
 ...]well-known.apple-app-site-association.tsx |  19 +
 .../[.]well-known.assetlinks[.]json.tsx       |  15 +
 apps/web/src/server/env.ts                    |   5 +
 docs/configuration.md                         |  20 +
 docs/multiple-devices.md                      |  25 +
 .../src/runtime.fake-approvals.test.ts        | 185 ++++
 .../agent-runtime/src/test/fake-adapter.ts    | 165 +++-
 .../src/test/fake-provider-script.ts          | 116 +++
 packages/config/src/app-surface.ts            |  25 +
 packages/config/test/app-surface.test.ts      |  19 +
 packages/connect-client/package.json          |   1 +
 packages/connect-client/src/credential.ts     |  27 -
 packages/connect-client/src/index.ts          |  12 +-
 packages/connect-client/src/list-servers.ts   |   7 +-
 packages/connect-client/src/mobile-pairing.ts | 104 +++
 packages/connect-client/src/urls.ts           |  30 +
 .../test/connect-client.test.ts               |  77 ++
 packages/connect-db/src/app-links.ts          | 116 +++
 packages/connect-db/src/index.ts              |   1 +
 packages/connect-db/test/app-links.test.ts    |  93 ++
 .../plugin-interaction-contracts/package.json |  28 +
 .../src/ask-user-question.ts                  |  76 ++
 .../plugin-interaction-contracts/src/index.ts |  33 +
 .../src/secret-request.ts                     |  44 +
 .../test/contracts.test.ts                    |  99 +++
 .../tsconfig.json                             |  10 +
 .../vitest.config.ts                          |  10 +
 packages/sdk/src/areas/projects.ts            |  22 +
 packages/sdk/src/response.ts                  |  22 +-
 packages/sdk/src/transport.ts                 |   7 +-
 packages/sdk/test/public-types.test.ts        |   7 +-
 .../src/templates/bb-guide-environments.md    |  16 +-
 plugins/ask-user-question/package.json        |   1 +
 plugins/ask-user-question/src/contracts.ts    |  93 +-
 plugins/connect/app.test.tsx                  | 102 +++
 plugins/connect/app.tsx                       | 255 +++++-
 plugins/connect/src/cli.ts                    |  73 +-
 plugins/connect/src/connect.test.ts           | 104 +++
 plugins/secrets/package.json                  |   1 +
 plugins/secrets/src/contracts.ts              |  43 +-
 pnpm-lock.yaml                                |  28 +
 tests/integration/helpers/harness.ts          |  15 +-
 tests/integration/mobile-e2e/backend.ts       | 296 +++++++
 tests/integration/mobile-e2e/connect-stub.ts  | 812 ++++++++++++++++++
 tests/integration/package.json                |   4 +-
 turbo.json                                    |  19 +
 54 files changed, 3296 insertions(+), 182 deletions(-)
 create mode 100644 apps/web/src/routes/[.]well-known.apple-app-site-association.tsx
 create mode 100644 apps/web/src/routes/[.]well-known.assetlinks[.]json.tsx
 create mode 100644 packages/agent-runtime/src/runtime.fake-approvals.test.ts
 create mode 100644 packages/config/test/app-surface.test.ts
 create mode 100644 packages/connect-client/src/mobile-pairing.ts
 create mode 100644 packages/connect-client/src/urls.ts
 create mode 100644 packages/connect-db/src/app-links.ts
 create mode 100644 packages/connect-db/test/app-links.test.ts
 create mode 100644 packages/plugin-interaction-contracts/package.json
 create mode 100644 packages/plugin-interaction-contracts/src/ask-user-question.ts
 create mode 100644 packages/plugin-interaction-contracts/src/index.ts
 create mode 100644 packages/plugin-interaction-contracts/src/secret-request.ts
 create mode 100644 packages/plugin-interaction-contracts/test/contracts.test.ts
 create mode 100644 packages/plugin-interaction-contracts/tsconfig.json
 create mode 100644 packages/plugin-interaction-contracts/vitest.config.ts
 create mode 100644 tests/integration/mobile-e2e/backend.ts
 create mode 100644 tests/integration/mobile-e2e/connect-stub.ts

diff --git a/apps/connect/src/tunnel-do.ts b/apps/connect/src/tunnel-do.ts
index 7eca8777af..895c329864 100644
--- a/apps/connect/src/tunnel-do.ts
+++ b/apps/connect/src/tunnel-do.ts
@@ -20,6 +20,12 @@ export interface Env {
   BETTER_AUTH_SECRET: string;
   ACCOUNT_APP_URL?: string;
   CLOUD_DEV?: string;
+  /**
+   * Android signing-cert SHA-256 fingerprints for `/.well-known/assetlinks.json`
+   * (comma-separated). Unset → the file serves an empty list (iOS universal
+   * links are unaffected).
+   */
+  ASSETLINKS_SHA256_FINGERPRINTS?: string;
 }
 
 const TUNNEL_TAG = "tunnel";
diff --git a/apps/connect/src/worker.test.ts b/apps/connect/src/worker.test.ts
index e6a9bdd078..c0f1974d05 100644
--- a/apps/connect/src/worker.test.ts
+++ b/apps/connect/src/worker.test.ts
@@ -685,6 +685,107 @@ describe("machine gate auth", () => {
   );
 });
 
+describe("bb mobile app-link association files", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // No cookie, no machine header: these must never reach the session gate.
+    mockParseCookie.mockReturnValue(null);
+    mockResolveLabel.mockResolvedValue(resolvedServer());
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it.each([
+    "/.well-known/apple-app-site-association",
+    "/.well-known/assetlinks.json",
+  ])(
+    "serves %s on a bare label without a session and without proxying",
+    async (path) => {
+      const { env, ctx, captured } = makeEnv(() => new Response("origin"));
+      const response = await worker.fetch(
+        visitorRequest("sawyer.getbb.app", path),
+        env as never,
+        ctx,
+      );
+      expect(response.status).toBe(200);
+      expect(response.headers.get("content-type")).toBe("application/json");
+      expect(captured).toHaveLength(0);
+      expect(mockResolveLabel).not.toHaveBeenCalled();
+      expect(mockVerifySession).not.toHaveBeenCalled();
+    },
+  );
+
+  it("serves the AASA on share hosts and labels that do not resolve (Apple fetches anonymously)", async () => {
+    mockResolveLabel.mockResolvedValue(null);
+    const { env, ctx, captured } = makeEnv(() => new Response("origin"));
+    const share = await worker.fetch(
+      visitorRequest(
+        "sawyer--8000.getbb.app",
+        "/.well-known/apple-app-site-association",
+      ),
+      env as never,
+      ctx,
+    );
+    expect(share.status).toBe(200);
+    const body = (await share.json()) as {
+      applinks: { details: { appIDs: string[] }[] };
+    };
+    expect(body.applinks.details[0]?.appIDs).toEqual([
+      "9QCU24SXK5.app.getbb.mobile",
+    ]);
+    const unknown = await worker.fetch(
+      visitorRequest(
+        "nobody-here.getbb.app",
+        "/.well-known/apple-app-site-association",
+      ),
+      env as never,
+      ctx,
+    );
+    expect(unknown.status).toBe(200);
+    expect(captured).toHaveLength(0);
+  });
+
+  it("reads Android fingerprints from the env and serves an empty list otherwise", async () => {
+    const { env, ctx } = makeEnv(() => new Response("origin"));
+    const empty = await worker.fetch(
+      visitorRequest("sawyer.getbb.app", "/.well-known/assetlinks.json"),
+      env as never,
+      ctx,
+    );
+    const emptyBody = (await empty.json()) as {
+      target: { sha256_cert_fingerprints: string[] };
+    }[];
+    expect(emptyBody[0]?.target.sha256_cert_fingerprints).toEqual([]);
+
+    const withEnv = await worker.fetch(
+      visitorRequest("sawyer.getbb.app", "/.well-known/assetlinks.json"),
+      { ...env, ASSETLINKS_SHA256_FINGERPRINTS: "aa:bb,cc:dd" } as never,
+      ctx,
+    );
+    const withEnvBody = (await withEnv.json()) as {
+      target: { package_name: string; sha256_cert_fingerprints: string[] };
+    }[];
+    expect(withEnvBody[0]?.target.package_name).toBe("app.getbb.mobile");
+    expect(withEnvBody[0]?.target.sha256_cert_fingerprints).toEqual([
+      "AA:BB",
+      "CC:DD",
+    ]);
+  });
+
+  it("leaves other .well-known paths to the session gate", async () => {
+    const { env, ctx, captured } = makeEnv(() => new Response("origin"));
+    const response = await worker.fetch(
+      visitorRequest("sawyer.getbb.app", "/.well-known/openid-configuration"),
+      env as never,
+      ctx,
+    );
+    expect(response.status).toBe(401);
+    expect(captured).toHaveLength(0);
+  });
+});
+
 describe("gate worker share hosts", () => {
   beforeEach(() => {
     vi.clearAllMocks();
diff --git a/apps/connect/src/worker.ts b/apps/connect/src/worker.ts
index 9935622663..6065a683ee 100644
--- a/apps/connect/src/worker.ts
+++ b/apps/connect/src/worker.ts
@@ -1,5 +1,10 @@
 import { drizzle } from "drizzle-orm/d1";
-import { RESERVED_HANDLES, parseVisitorHost, schema } from "@bb/connect-db";
+import {
+  RESERVED_HANDLES,
+  handleAppLinkAssociationRequest,
+  parseVisitorHost,
+  schema,
+} from "@bb/connect-db";
 import { TUNNEL_OFFLINE_HEADER, TunnelDO, type Env } from "./tunnel-do.js";
 import {
   parseCookie,
@@ -290,6 +295,15 @@ export default {
     if (url.pathname === "/api/connect/machine-label") {
       return handleAssignMachineLabel(request, env);
     }
+    // bb mobile universal / app links: Apple's CDN and Android fetch the
+    // association files anonymously from `https://<label>.getbb.app`, so
+    // they are answered here for every host — before label resolution and
+    // the session gate, never proxied to the tunnel, never redirected.
+    const appLinks = handleAppLinkAssociationRequest(
+      { method: request.method, url: url.toString() },
+      env,
+    );
+    if (appLinks) return appLinks;
 
     const host = resolveConnectRequestHost(request.headers, runtime);
     const parsed = parseVisitorHost(host, env.BASE_DOMAIN);
diff --git a/apps/connect/wrangler.jsonc b/apps/connect/wrangler.jsonc
index 6227e7338d..3b92eb1176 100644
--- a/apps/connect/wrangler.jsonc
+++ b/apps/connect/wrangler.jsonc
@@ -10,6 +10,9 @@
 // Secret: wrangler secret put BETTER_AUTH_SECRET [--env staging]
 //         (must equal bb-web's BETTER_AUTH_SECRET — the gate verifies the
 //         session cookie's HMAC with it)
+// Optional var: ASSETLINKS_SHA256_FINGERPRINTS — comma-separated Android
+//         signing-cert fingerprints for /.well-known/assetlinks.json (bb
+//         mobile app links). Unset until the Android app is signed.
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "bb-connect",
diff --git a/apps/server/src/request-context.ts b/apps/server/src/request-context.ts
index 3c48ee470d..1cb4fd30ee 100644
--- a/apps/server/src/request-context.ts
+++ b/apps/server/src/request-context.ts
@@ -1,8 +1,9 @@
 import { getConnInfo } from "@hono/node-server/conninfo";
 import {
   APP_SURFACE_HEADER_NAME,
-  parseAppSurface,
+  parseRequestAppSurface,
   type AppSurface,
+  type RequestAppSurface,
 } from "@bb/config/app-surface";
 import type { Context } from "hono";
 
@@ -57,8 +58,9 @@ export function getGateMachineId(context: GateAuthHeaderReader): string | null {
 export function resolveRequestAppSurface(
   context: Context,
   fallback: AppSurface,
-): AppSurface {
+): RequestAppSurface {
   return (
-    parseAppSurface(context.req.header(APP_SURFACE_HEADER_NAME)) ?? fallback
+    parseRequestAppSurface(context.req.header(APP_SURFACE_HEADER_NAME)) ??
+    fallback
   );
 }
diff --git a/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md b/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
index dc25154fed..57ebfd2668 100644
--- a/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
+++ b/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
@@ -223,11 +223,18 @@ isolated|reuse`, or anchor with `--source-seq-end`. Permission mode inherits
   `bb connect servers` lists every bb on the paired account (handle,
   name, url, live) so callers can discover siblings; `--json` includes
   `selfHandle` for deduping this server. When you start a local server the user
-  should open remotely, expose the port and give them the share URL. Remote
+  should open remotely, expose the port and give them the share URL.
+  `bb connect machine-code` mints a one-time code (10 minutes, single use)
+  that pairs the bb mobile app with this bb: it prints the code, server URL,
+  connect apex, and expiry; `--json` returns `{code, serverUrl, apex,
+  expiresAt}`. The phone enrolls as a connect machine with its own revocable
+  credential (visible in the getbb.app dashboard). Settings → Remote access →
+  Add mobile device shows the same code as a QR. A machine-limit failure names
+  the dashboard so the user can revoke an unused device. Remote
   access is owned by the builtin `connect` plugin: `bb plugin disable connect`
   cuts it off entirely; with bb connect still enabled, `bb plugin enable
   connect` restores the command. Plugins → Connect shows the current URL, QR
-  code, shared ports, re-pair form, and disconnect control.
+  code, mobile pairing, shared ports, re-pair form, and disconnect control.
 - Add remote execution machines from Settings → Machines. Its one-line
   installer stores the bb connect machine credential locally and configures
   both the daemon protocol and agent-launched `bb` CLI to traverse the account
diff --git a/apps/server/src/services/system/telemetry.ts b/apps/server/src/services/system/telemetry.ts
index 70e3783fcd..9706caa6c1 100644
--- a/apps/server/src/services/system/telemetry.ts
+++ b/apps/server/src/services/system/telemetry.ts
@@ -1,7 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { DEFAULTS } from "@bb/config/defaults";
 import { readOrCreateSecretFile } from "@bb/secret-storage";
-import type { AppSurface } from "@bb/config/app-surface";
+import type { AppSurface, RequestAppSurface } from "@bb/config/app-surface";
 import type { ServerLogger } from "../../types.js";
 
 /**
@@ -28,7 +28,7 @@ import type { ServerLogger } from "../../types.js";
 const POSTHOG_INGESTION_URL = "https://us.i.posthog.com/capture/";
 const TELEMETRY_ID_FILE_NAME = "telemetry-id";
 
-const telemetryAppSurfaceStorage = new AsyncLocalStorage<AppSurface>();
+const telemetryAppSurfaceStorage = new AsyncLocalStorage<RequestAppSurface>();
 
 /**
  * Which coding agents the machine had when onboarding opened. Answers "how many
@@ -125,7 +125,7 @@ export function createNoopTelemetryService(): TelemetryService {
 }
 
 export function runWithTelemetryAppSurface<T>(
-  appSurface: AppSurface,
+  appSurface: RequestAppSurface,
   callback: () => T,
 ): T {
   return telemetryAppSurfaceStorage.run(appSurface, callback);
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index 22b4ff930a..24a3c4f476 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -16,6 +16,8 @@ import { Route as IndexRouteImport } from './routes/index'
 import { Route as DownloadMacosRouteImport } from './routes/download.macos'
 import { Route as BlogSlugRouteImport } from './routes/blog_.$slug'
 import { Route as ApiSubscribeRouteImport } from './routes/api.subscribe'
+import { Route as DotwellKnownAssetlinksDotjsonRouteImport } from './routes/[.]well-known.assetlinks[.]json'
+import { Route as DotwellKnownAppleAppSiteAssociationRouteImport } from './routes/[.]well-known.apple-app-site-association'
 import { Route as MarketplaceV1SplatRouteImport } from './routes/marketplace.v1.$'
 import { Route as ApiConnectRevokeMachineRouteImport } from './routes/api.connect.revoke-machine'
 import { Route as ApiConnectRedeemMachineRouteImport } from './routes/api.connect.redeem-machine'
@@ -58,6 +60,18 @@ const ApiSubscribeRoute = ApiSubscribeRouteImport.update({
   path: '/api/subscribe',
   getParentRoute: () => rootRouteImport,
 } as any)
+const DotwellKnownAssetlinksDotjsonRoute =
+  DotwellKnownAssetlinksDotjsonRouteImport.update({
+    id: '/.well-known/assetlinks.json',
+    path: '/.well-known/assetlinks.json',
+    getParentRoute: () => rootRouteImport,
+  } as any)
+const DotwellKnownAppleAppSiteAssociationRoute =
+  DotwellKnownAppleAppSiteAssociationRouteImport.update({
+    id: '/.well-known/apple-app-site-association',
+    path: '/.well-known/apple-app-site-association',
+    getParentRoute: () => rootRouteImport,
+  } as any)
 const MarketplaceV1SplatRoute = MarketplaceV1SplatRouteImport.update({
   id: '/marketplace/v1/$',
   path: '/marketplace/v1/$',
@@ -94,6 +108,8 @@ export interface FileRoutesByFullPath {
   '/blog': typeof BlogRoute
   '/changelog': typeof ChangelogRoute
   '/dashboard': typeof DashboardRoute
+  '/.well-known/apple-app-site-association': typeof DotwellKnownAppleAppSiteAssociationRoute
+  '/.well-known/assetlinks.json': typeof DotwellKnownAssetlinksDotjsonRoute
   '/api/subscribe': typeof ApiSubscribeRoute
   '/blog/$slug': typeof BlogSlugRoute
   '/download/macos': typeof DownloadMacosRoute
@@ -109,6 +125,8 @@ export interface FileRoutesByTo {
   '/blog': typeof BlogRoute
   '/changelog': typeof ChangelogRoute
   '/dashboard': typeof DashboardRoute
+  '/.well-known/apple-app-site-association': typeof DotwellKnownAppleAppSiteAssociationRoute
+  '/.well-known/assetlinks.json': typeof DotwellKnownAssetlinksDotjsonRoute
   '/api/subscribe': typeof ApiSubscribeRoute
   '/blog/$slug': typeof BlogSlugRoute
   '/download/macos': typeof DownloadMacosRoute
@@ -125,6 +143,8 @@ export interface FileRoutesById {
   '/blog': typeof BlogRoute
   '/changelog': typeof ChangelogRoute
   '/dashboard': typeof DashboardRoute
+  '/.well-known/apple-app-site-association': typeof DotwellKnownAppleAppSiteAssociationRoute
+  '/.well-known/assetlinks.json': typeof DotwellKnownAssetlinksDotjsonRoute
   '/api/subscribe': typeof ApiSubscribeRoute
   '/blog_/$slug': typeof BlogSlugRoute
   '/download/macos': typeof DownloadMacosRoute
@@ -142,6 +162,8 @@ export interface FileRouteTypes {
     | '/blog'
     | '/changelog'
     | '/dashboard'
+    | '/.well-known/apple-app-site-association'
+    | '/.well-known/assetlinks.json'
     | '/api/subscribe'
     | '/blog/$slug'
     | '/download/macos'
@@ -157,6 +179,8 @@ export interface FileRouteTypes {
     | '/blog'
     | '/changelog'
     | '/dashboard'
+    | '/.well-known/apple-app-site-association'
+    | '/.well-known/assetlinks.json'
     | '/api/subscribe'
     | '/blog/$slug'
     | '/download/macos'
@@ -172,6 +196,8 @@ export interface FileRouteTypes {
     | '/blog'
     | '/changelog'
     | '/dashboard'
+    | '/.well-known/apple-app-site-association'
+    | '/.well-known/assetlinks.json'
     | '/api/subscribe'
     | '/blog_/$slug'
     | '/download/macos'
@@ -188,6 +214,8 @@ export interface RootRouteChildren {
   BlogRoute: typeof BlogRoute
   ChangelogRoute: typeof ChangelogRoute
   DashboardRoute: typeof DashboardRoute
+  DotwellKnownAppleAppSiteAssociationRoute: typeof DotwellKnownAppleAppSiteAssociationRoute
+  DotwellKnownAssetlinksDotjsonRoute: typeof DotwellKnownAssetlinksDotjsonRoute
   ApiSubscribeRoute: typeof ApiSubscribeRoute
   BlogSlugRoute: typeof BlogSlugRoute
   DownloadMacosRoute: typeof DownloadMacosRoute
@@ -250,6 +278,20 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ApiSubscribeRouteImport
       parentRoute: typeof rootRouteImport
     }
+    '/.well-known/assetlinks.json': {
+      id: '/.well-known/assetlinks.json'
+      path: '/.well-known/assetlinks.json'
+      fullPath: '/.well-known/assetlinks.json'
+      preLoaderRoute: typeof DotwellKnownAssetlinksDotjsonRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/.well-known/apple-app-site-association': {
+      id: '/.well-known/apple-app-site-association'
+      path: '/.well-known/apple-app-site-association'
+      fullPath: '/.well-known/apple-app-site-association'
+      preLoaderRoute: typeof DotwellKnownAppleAppSiteAssociationRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/marketplace/v1/$': {
       id: '/marketplace/v1/$'
       path: '/marketplace/v1/$'
@@ -300,6 +342,9 @@ const rootRouteChildren: RootRouteChildren = {
   BlogRoute: BlogRoute,
   ChangelogRoute: ChangelogRoute,
   DashboardRoute: DashboardRoute,
+  DotwellKnownAppleAppSiteAssociationRoute:
+    DotwellKnownAppleAppSiteAssociationRoute,
+  DotwellKnownAssetlinksDotjsonRoute: DotwellKnownAssetlinksDotjsonRoute,
   ApiSubscribeRoute: ApiSubscribeRoute,
   BlogSlugRoute: BlogSlugRoute,
   DownloadMacosRoute: DownloadMacosRoute,
diff --git a/apps/web/src/routes/[.]well-known.apple-app-site-association.tsx b/apps/web/src/routes/[.]well-known.apple-app-site-association.tsx
new file mode 100644
index 0000000000..ba0285f004
--- /dev/null
+++ b/apps/web/src/routes/[.]well-known.apple-app-site-association.tsx
@@ -0,0 +1,19 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { handleAppLinkAssociationRequest } from "@bb/connect-db";
+import { getEnv } from "@/server/env";
+
+// iOS universal links for bb mobile (`applinks:getbb.app` +
+// `applinks:*.getbb.app`): the apex serves the same association file the
+// connect gate serves on every `<label>.getbb.app` (@bb/connect-db
+// `app-links.ts` is the single source of truth). Anonymous, JSON, no redirect.
+export const Route = createFileRoute("/.well-known/apple-app-site-association")(
+  {
+    server: {
+      handlers: {
+        GET: ({ request }) =>
+          handleAppLinkAssociationRequest(request, getEnv()) ??
+          new Response("not found\n", { status: 404 }),
+      },
+    },
+  },
+);
diff --git a/apps/web/src/routes/[.]well-known.assetlinks[.]json.tsx b/apps/web/src/routes/[.]well-known.assetlinks[.]json.tsx
new file mode 100644
index 0000000000..06ccf3ec02
--- /dev/null
+++ b/apps/web/src/routes/[.]well-known.assetlinks[.]json.tsx
@@ -0,0 +1,15 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { handleAppLinkAssociationRequest } from "@bb/connect-db";
+import { getEnv } from "@/server/env";
+
+// Android app links for bb mobile: fingerprints come from the
+// ASSETLINKS_SHA256_FINGERPRINTS var (empty list until the app is signed).
+export const Route = createFileRoute("/.well-known/assetlinks.json")({
+  server: {
+    handlers: {
+      GET: ({ request }) =>
+        handleAppLinkAssociationRequest(request, getEnv()) ??
+        new Response("not found\n", { status: 404 }),
+    },
+  },
+});
diff --git a/apps/web/src/server/env.ts b/apps/web/src/server/env.ts
index 10f188a915..545efc9e51 100644
--- a/apps/web/src/server/env.ts
+++ b/apps/web/src/server/env.ts
@@ -24,6 +24,11 @@ export interface Env {
    * answers 404 until it exists.
    */
   MARKETPLACE?: R2Bucket;
+  /**
+   * Android signing-cert SHA-256 fingerprints for `/.well-known/assetlinks.json`
+   * (bb mobile app links; comma-separated). Unset → empty list.
+   */
+  ASSETLINKS_SHA256_FINGERPRINTS?: string;
 }
 
 export function getEnv(): Env {
diff --git a/docs/configuration.md b/docs/configuration.md
index 446d148128..c611d5786d 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -605,6 +605,26 @@ The tunnel client lives in `plugins/connect/`; the CLI command is proxied to
 the plugin, and Settings → Connect drives the plugin's rpc (including shared
 ports).
 
+### Pairing the bb mobile app
+
+The bb mobile app reaches a paired bb through the same connect route. It
+enrolls as a connect **machine** — its own credential on the getbb.app account,
+separate from the server's pairing secret and individually revocable — so
+pairing starts from the bb, not from the phone:
+
+- Settings → Remote access → **Add mobile device** mints a one-time code and
+  shows it as a QR code plus copyable text with a countdown.
+- `bb connect machine-code` prints the same code, server URL, connect apex,
+  and expiry; `bb connect machine-code --json` returns
+  `{code, serverUrl, apex, expiresAt}` (the QR encodes that JSON).
+
+Scan or type the code in the mobile app. The code lasts 10 minutes and works
+once. The phone then appears in the getbb.app dashboard machine list, where you
+can revoke it; every enrollment takes one of the account's machine slots
+(desktop apps, remote execution machines, and phones all count), so a
+machine-limit error asks you to revoke an unused device first. Both surfaces
+need the bb to be paired (`bb connect --code …`) and the connect plugin enabled.
+
 ## Experiments
 
 Experimental surfaces are changed in Settings → Experiments or with
diff --git a/docs/multiple-devices.md b/docs/multiple-devices.md
index b4a42524fa..b36e1af8c0 100644
--- a/docs/multiple-devices.md
+++ b/docs/multiple-devices.md
@@ -75,6 +75,31 @@ If Settings reports that it cannot connect to the helper:
 
 Phones and tablets need no helper; editor-launch actions are simply unavailable.
 
+## Use the bb mobile app
+
+The bb mobile app is a client for a bb server; it runs nothing itself. Over
+bb connect it pairs the same way the desktop app does: the phone enrolls as a
+connect machine with its own credential, which the getbb.app dashboard lists
+and can revoke.
+
+1. Pair the bb server with bb connect first (Settings → Remote access, or
+   `bb connect --code … --server …`).
+2. Mint a pairing code for the phone: Settings → Remote access → **Add mobile
+   device** (QR code plus the code as text, with a countdown), or run
+   `bb connect machine-code` (`--json` prints
+   `{code, serverUrl, apex, expiresAt}`).
+3. In the mobile app, add a server over bb connect and scan the QR code or type
+   the code. Codes last 10 minutes and work once.
+
+The phone keeps its credential in the device keychain and mints short-lived
+sessions from it; it never holds the server's pairing secret. To cut a phone
+off, revoke it in the getbb.app dashboard machine list. Every phone takes one of
+the account's machine slots, so a machine-limit error means an unused device
+should be revoked first. On a trusted network the app can also use a direct
+server URL (Tailscale Serve or `--server-bind-host 0.0.0.0`) with the same
+caveats as a browser. Platforms (iOS first) and what the phone cannot do are
+listed in [platform-support.md](platform-support.md#mobile-app).
+
 ## Point the desktop app at another bb
 
 The desktop app's Server menu lists "This Mac", every bb connect server on the
diff --git a/packages/agent-runtime/src/runtime.fake-approvals.test.ts b/packages/agent-runtime/src/runtime.fake-approvals.test.ts
new file mode 100644
index 0000000000..3d393824ee
--- /dev/null
+++ b/packages/agent-runtime/src/runtime.fake-approvals.test.ts
@@ -0,0 +1,185 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type {
+  PendingInteractionCreate,
+  PendingInteractionResolution,
+  ThreadEvent,
+} from "@bb/domain";
+import { promptTextInput } from "./test/prompt-input.js";
+import { createAgentRuntimeWithAdapters } from "./runtime.js";
+import { createFakeAdapter } from "./test/fake-adapter.js";
+import {
+  fullRuntimeOptions,
+  waitForThreadAgentMessageText,
+  waitForThreadTurnCompleted,
+} from "./test/runtime-test-harness.js";
+
+// The `approve:<kind>` control token is the deterministic approval path the
+// mobile e2e flows drive against the fake provider. These tests pin the
+// request the runtime hands to `onInteractiveRequest` and the two ways the
+// fake turn resumes afterwards.
+describe("fake provider approve:<kind> control token", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "bb-runtime-fake-approval-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  async function runApprovalTurn(args: {
+    prompt: string;
+    resolve: (
+      request: PendingInteractionCreate,
+    ) => PendingInteractionResolution;
+  }): Promise<{
+    events: ThreadEvent[];
+    requests: PendingInteractionCreate[];
+    shutdown: () => Promise<void>;
+  }> {
+    const events: ThreadEvent[] = [];
+    const requests: PendingInteractionCreate[] = [];
+    const runtime = createAgentRuntimeWithAdapters({
+      workspacePath: tmpDir,
+      onEvent: (event) => events.push(event),
+      onToolCall: async () => ({
+        contentItems: [{ type: "inputText", text: "ok" }],
+        success: true,
+      }),
+      onInteractiveRequest: async (request) => {
+        requests.push(request);
+        return args.resolve(request);
+      },
+      adapterFactory: () => createFakeAdapter(),
+    });
+
+    await runtime.startThread({
+      environmentId: "env-1",
+      threadId: "t1",
+      projectId: "p1",
+      providerId: "fake",
+      options: fullRuntimeOptions,
+    });
+    await runtime.runTurn({
+      clientRequestId: "creq_fakeapprv2",
+      threadId: "t1",
+      input: [promptTextInput({ text: args.prompt })],
+      options: fullRuntimeOptions,
+    });
+    await waitForThreadTurnCompleted({
+      events,
+      providerId: "fake",
+      runtime,
+      threadId: "t1",
+    });
+
+    return { events, requests, shutdown: () => runtime.shutdown() };
+  }
+
+  it("emits a command approval and echoes the response after allow_once", async () => {
+    const { events, requests, shutdown } = await runApprovalTurn({
+      prompt: "approve:command hello",
+      resolve: () => ({ decision: "allow_once", grantedPermissions: null }),
+    });
+
+    expect(requests).toHaveLength(1);
+    expect(requests[0]).toMatchObject({
+      threadId: "t1",
+      turnId: "turn-1",
+      providerId: "fake",
+      providerThreadId: "prov-1",
+      payload: {
+        kind: "approval",
+        subject: {
+          kind: "command",
+          command: "echo hi",
+          cwd: null,
+          actions: [],
+          sessionGrant: null,
+        },
+        reason: null,
+        availableDecisions: ["allow_once", "allow_for_session", "deny"],
+      },
+    });
+    await waitForThreadAgentMessageText({
+      events,
+      providerId: "fake",
+      text: "Response to: approve:command hello",
+      threadId: "t1",
+    });
+    expect(events).not.toContainEqual(
+      expect.objectContaining({
+        type: "item/completed",
+        item: expect.objectContaining({ type: "agentMessage", text: "Denied" }),
+      }),
+    );
+    await shutdown();
+  });
+
+  it("completes the turn with Denied when the approval is denied", async () => {
+    const { events, requests, shutdown } = await runApprovalTurn({
+      prompt: "approve:command hello",
+      resolve: () => ({ decision: "deny" }),
+    });
+
+    expect(requests).toHaveLength(1);
+    await waitForThreadAgentMessageText({
+      events,
+      providerId: "fake",
+      text: "Denied",
+      threadId: "t1",
+    });
+    expect(events).not.toContainEqual(
+      expect.objectContaining({
+        type: "item/completed",
+        item: expect.objectContaining({
+          type: "agentMessage",
+          text: "Response to: approve:command hello",
+        }),
+      }),
+    );
+    await shutdown();
+  });
+
+  it.each([
+    {
+      kind: "file_change",
+      subject: { kind: "file_change", writeScope: null, sessionGrant: null },
+      reason: "Write src/example.ts",
+    },
+    {
+      kind: "permission_grant",
+      subject: {
+        kind: "permission_grant",
+        toolName: "Edit",
+        permissions: {
+          network: null,
+          fileSystem: { read: [], write: ["src/example.ts"] },
+        },
+      },
+      reason: null,
+    },
+    {
+      kind: "plan",
+      subject: { kind: "plan", planFilePath: null },
+      reason: null,
+    },
+  ])("decodes approve:$kind into a $kind approval subject", async (fixture) => {
+    const { requests, shutdown } = await runApprovalTurn({
+      prompt: `approve:${fixture.kind}`,
+      resolve: () => ({ decision: "deny" }),
+    });
+
+    expect(requests).toHaveLength(1);
+    expect(requests[0]?.payload).toMatchObject({
+      kind: "approval",
+      subject: fixture.subject,
+      reason: fixture.reason,
+    });
+    await shutdown();
+  });
+});
diff --git a/packages/agent-runtime/src/test/fake-adapter.ts b/packages/agent-runtime/src/test/fake-adapter.ts
index 767439aec4..4ef6a0c473 100644
--- a/packages/agent-runtime/src/test/fake-adapter.ts
+++ b/packages/agent-runtime/src/test/fake-adapter.ts
@@ -1,11 +1,14 @@
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import {
+  isApprovalPendingInteractionPayload,
+  isApprovalPendingInteractionResolution,
   isUserQuestionPendingInteractionPayload,
   isUserQuestionPendingInteractionResolution,
   threadScope,
   threadEventItemSchema,
   turnScope,
+  type ApprovalPendingInteractionPayload,
   type AvailableModel,
   type PendingInteractionUserQuestionOption,
   type ProviderCapabilities,
@@ -31,7 +34,8 @@ import {
 } from "../provider-adapter.js";
 import { parseAvailableModelList } from "../shared/available-models.js";
 import { classifySessionExecutionSettingsChange } from "../execution-options.js";
-type FakeUserQuestionCapability = ProviderCapabilities["supportsNativeUserQuestion"];
+type FakeUserQuestionCapability =
+  ProviderCapabilities["supportsNativeUserQuestion"];
 
 export interface CreateFakeProviderExecutionContext {
   displayName?: string;
@@ -48,6 +52,7 @@ interface FakeEventMessage {
 const DEFAULT_ADAPTER_ID = "fake";
 const DEFAULT_DISPLAY_NAME = "Fake Provider";
 const FAKE_USER_QUESTION_REQUEST_METHOD = "interaction/user_question";
+const FAKE_APPROVAL_REQUEST_METHOD = "interaction/approval";
 
 function resolveTsxLoaderSpecifier(): string {
   return import.meta.resolve("tsx");
@@ -402,7 +407,7 @@ function decodeToolCallRequest(
   );
 }
 
-function decodeInteractiveRequest(
+function decodeUserQuestionRequest(
   request: ProviderInboundRequest,
 ): DecodedInteractiveRequest | null {
   if (
@@ -443,13 +448,143 @@ function decodeInteractiveRequest(
   };
 }
 
+// Maps the fake script's `interaction/approval` params (`approvalKind` plus a
+// few kind-specific fixture fields) onto bb's approval payload. The subject
+// shape is spelled out here so a domain schema change fails typecheck instead
+// of silently dropping the request at runtime.
+function buildFakeApprovalPayload(
+  params: Record<string, unknown>,
+  itemId: string,
+): ApprovalPendingInteractionPayload | null {
+  const approvalKind = stringParam(params, "approvalKind");
+  switch (approvalKind) {
+    case "command": {
+      const command = stringParam(params, "command");
+      if (!command) {
+        return null;
+      }
+      return {
+        kind: "approval",
+        subject: {
+          kind: "command",
+          itemId,
+          command,
+          cwd: stringParam(params, "cwd"),
+          actions: [],
+          sessionGrant: null,
+        },
+        reason: null,
+        availableDecisions: ["allow_once", "allow_for_session", "deny"],
+      };
+    }
+    case "file_change": {
+      const path = stringParam(params, "path");
+      if (!path) {
+        return null;
+      }
+      return {
+        kind: "approval",
+        subject: {
+          kind: "file_change",
+          itemId,
+          writeScope: null,
+          sessionGrant: null,
+        },
+        reason: `Write ${path}`,
+        availableDecisions: ["allow_once", "allow_for_session", "deny"],
+      };
+    }
+    case "permission_grant": {
+      const path = stringParam(params, "path");
+      if (!path) {
+        return null;
+      }
+      return {
+        kind: "approval",
+        subject: {
+          kind: "permission_grant",
+          itemId,
+          toolName: stringParam(params, "toolName"),
+          permissions: {
+            network: null,
+            fileSystem: { read: [], write: [path] },
+          },
+        },
+        reason: null,
+        availableDecisions: ["allow_once", "allow_for_session", "deny"],
+      };
+    }
+    case "plan": {
+      const plan = stringParam(params, "plan");
+      if (!plan) {
+        return null;
+      }
+      return {
+        kind: "approval",
+        subject: {
+          kind: "plan",
+          itemId,
+          plan,
+          planFilePath: null,
+        },
+        reason: null,
+        availableDecisions: ["allow_once", "deny"],
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+function decodeApprovalRequest(
+  request: ProviderInboundRequest,
+): DecodedInteractiveRequest | null {
+  if (
+    request.method !== FAKE_APPROVAL_REQUEST_METHOD ||
+    (typeof request.id !== "string" && typeof request.id !== "number") ||
+    !isRecord(request.params)
+  ) {
+    return null;
+  }
+
+  const providerThreadId = stringParam(request.params, "providerThreadId");
+  const turnId = turnIdParam(request.params);
+  const itemId = stringParam(request.params, "itemId");
+  if (!providerThreadId || turnId === undefined || !itemId) {
+    return null;
+  }
+  const payload = buildFakeApprovalPayload(request.params, itemId);
+  if (!payload) {
+    return null;
+  }
+
+  return {
+    requestId: request.id,
+    method: request.method,
+    providerThreadId,
+    turnId,
+    threadId: optionalStringParam(request.params, "threadId"),
+    payload,
+  };
+}
+
+function createDecodeInteractiveRequest(
+  supportsNativeUserQuestion: FakeUserQuestionCapability,
+): (request: ProviderInboundRequest) => DecodedInteractiveRequest | null {
+  return (request) =>
+    decodeApprovalRequest(request) ??
+    (supportsNativeUserQuestion ? decodeUserQuestionRequest(request) : null);
+}
+
 function buildInteractiveResponse(
   args: BuildInteractiveResponseArgs,
 ): ProviderInteractiveResponse {
-  if (
-    !isUserQuestionPendingInteractionPayload(args.request.payload) ||
-    !isUserQuestionPendingInteractionResolution(args.resolution)
-  ) {
+  const matchesPayload =
+    (isApprovalPendingInteractionPayload(args.request.payload) &&
+      isApprovalPendingInteractionResolution(args.resolution)) ||
+    (isUserQuestionPendingInteractionPayload(args.request.payload) &&
+      isUserQuestionPendingInteractionResolution(args.resolution));
+  if (!matchesPayload) {
     throw new ProviderResponseEncodeError(
       "Fake provider interactive response kind does not match the request payload",
     );
@@ -478,9 +613,15 @@ export function createFakeAdapter(
    *   cannot resolve the BB turn id.
    * - `ask_user` emits a provider-scoped user-question interactive request
    *   when the adapter is configured with `supportsNativeUserQuestion: true`.
+   * - `approve:<kind>` (kind: `command` | `file_change` | `permission_grant`
+   *   | `plan`) emits a provider-scoped approval interactive request with
+   *   fixed fixture fields (`echo hi`, `src/example.ts`, ...). The turn
+   *   resumes once the approval resolves: allow_once/allow_for_session echo
+   *   `Response to: ...`, deny completes with `Denied`.
    * - remaining text is echoed back as `Response to: ...`.
    */
-  const supportsNativeUserQuestion = options.supportsNativeUserQuestion ?? false;
+  const supportsNativeUserQuestion =
+    options.supportsNativeUserQuestion ?? false;
 
   return {
     approvalEnforcedBy: "runtime",
@@ -496,9 +637,9 @@ export function createFakeAdapter(
     },
     classifyExecutionSettingsChange: classifySessionExecutionSettingsChange,
     decodeToolCallRequest,
-    decodeInteractiveRequest: supportsNativeUserQuestion
-      ? decodeInteractiveRequest
-      : undefined,
+    decodeInteractiveRequest: createDecodeInteractiveRequest(
+      supportsNativeUserQuestion,
+    ),
     displayName: options.displayName ?? DEFAULT_DISPLAY_NAME,
     id: options.id ?? DEFAULT_ADAPTER_ID,
     parseModelListResult,
@@ -513,8 +654,6 @@ export function createFakeAdapter(
     translateAcceptedCommand() {
       return [];
     },
-    buildInteractiveResponse: supportsNativeUserQuestion
-      ? buildInteractiveResponse
-      : undefined,
+    buildInteractiveResponse,
   };
 }
diff --git a/packages/agent-runtime/src/test/fake-provider-script.ts b/packages/agent-runtime/src/test/fake-provider-script.ts
index 2e7b102f2a..7e85a2dd44 100644
--- a/packages/agent-runtime/src/test/fake-provider-script.ts
+++ b/packages/agent-runtime/src/test/fake-provider-script.ts
@@ -19,6 +19,14 @@ interface PendingUserQuestion {
   threadId: string;
 }
 
+type ApprovalKind = "command" | "file_change" | "permission_grant" | "plan";
+
+interface PendingApproval {
+  delayMs: number;
+  responseText: string;
+  threadId: string;
+}
+
 type ToolTurnIdMode = "active" | "unresolved";
 
 interface ThreadState {
@@ -29,6 +37,7 @@ interface ThreadState {
 }
 
 interface TurnPlan {
+  approvalKind: ApprovalKind | null;
   delayMs: number;
   questionRequested: boolean;
   responseText: string;
@@ -41,11 +50,20 @@ const rl = createInterface({ input: process.stdin });
 const threads = new Map<string, ThreadState>();
 const pendingToolCalls = new Map<JsonRpcId, PendingToolCall>();
 const pendingUserQuestions = new Map<JsonRpcId, PendingUserQuestion>();
+const pendingApprovals = new Map<JsonRpcId, PendingApproval>();
 
 let nextProviderThreadId = 1;
 let nextToolCallId = 1;
 let nextUserQuestionId = 10_000;
+let nextApprovalId = 20_000;
 const USER_QUESTION_METHOD = "interaction/user_question";
+const APPROVAL_METHOD = "interaction/approval";
+const APPROVAL_KINDS: readonly ApprovalKind[] = [
+  "command",
+  "file_change",
+  "permission_grant",
+  "plan",
+];
 const defaultModelList = {
   models: [
     {
@@ -186,9 +204,14 @@ function parseUserContent(input: unknown): JsonRecord[] {
   return content;
 }
 
+function parseApprovalKind(value: string | undefined): ApprovalKind | null {
+  return APPROVAL_KINDS.find((kind) => kind === value) ?? null;
+}
+
 function parseTurnPlan(inputText: string): TurnPlan {
   const delayMatch = /(?:^|\s)delay:(\d+)(?:\s|$)/.exec(inputText);
   const userQuestionMatch = /(?:^|\s)ask_user(?:\s|$)/.exec(inputText);
+  const approvalMatch = /(?:^|\s)approve:([^\s]+)(?:\s|$)/.exec(inputText);
   const unresolvedToolMatch =
     /(?:^|\s)call_tool_unresolved:([^\s]+)(?:\s|$)/.exec(inputText);
   const toolMatch =
@@ -204,6 +227,7 @@ function parseTurnPlan(inputText: string): TurnPlan {
   }
 
   return {
+    approvalKind: parseApprovalKind(approvalMatch?.[1]),
     delayMs,
     questionRequested: Boolean(userQuestionMatch),
     responseText: inputText ? `Response to: ${inputText}` : "Response complete",
@@ -369,6 +393,54 @@ function requestUserQuestion(
   });
 }
 
+// Kind-specific fixture fields the fake adapter maps onto the approval
+// subject. Deterministic so UI e2e flows can assert on them.
+function buildApprovalParams(kind: ApprovalKind): JsonRecord {
+  switch (kind) {
+    case "command":
+      return { command: "echo hi", cwd: null };
+    case "file_change":
+      return { path: "src/example.ts" };
+    case "permission_grant":
+      return { toolName: "Edit", path: "src/example.ts" };
+    case "plan":
+      return { plan: "# Fake plan\n\n1. Say hi\n2. Report back" };
+  }
+}
+
+function requestApproval(
+  threadId: string,
+  turnId: string,
+  kind: ApprovalKind,
+  responseText: string,
+  delayMs: number,
+): void {
+  const thread = getThreadState(threadId);
+  if (!thread || !thread.activeTurn) {
+    return;
+  }
+
+  const requestId = nextApprovalId++;
+  pendingApprovals.set(requestId, {
+    delayMs,
+    responseText,
+    threadId,
+  });
+  send({
+    jsonrpc: "2.0",
+    id: requestId,
+    method: APPROVAL_METHOD,
+    params: {
+      threadId,
+      turnId,
+      providerThreadId: thread.providerThreadId,
+      itemId: `approval-${requestId}`,
+      approvalKind: kind,
+      ...buildApprovalParams(kind),
+    },
+  });
+}
+
 function beginTurn(threadId: string, input: unknown): void {
   const thread = getThreadState(threadId);
   if (!thread) {
@@ -398,6 +470,17 @@ function beginTurn(threadId: string, input: unknown): void {
   });
   emitUserMessage(threadId, turnId, input);
 
+  if (plan.approvalKind) {
+    requestApproval(
+      threadId,
+      turnId,
+      plan.approvalKind,
+      plan.responseText,
+      plan.delayMs,
+    );
+    return;
+  }
+
   if (plan.questionRequested) {
     requestUserQuestion(threadId, turnId, plan.delayMs);
     return;
@@ -552,6 +635,36 @@ function handleUserQuestionResult(message: JsonRecord): boolean {
   return true;
 }
 
+function isAllowedApprovalResult(result: unknown): boolean {
+  return (
+    isJsonRecord(result) &&
+    (result.decision === "allow_once" ||
+      result.decision === "allow_for_session")
+  );
+}
+
+function handleApprovalResult(message: JsonRecord): boolean {
+  const messageId = getJsonRpcId(message.id);
+  if (messageId === undefined || typeof message.method === "string") {
+    return false;
+  }
+
+  const pendingApproval = pendingApprovals.get(messageId);
+  if (!pendingApproval) {
+    return false;
+  }
+
+  pendingApprovals.delete(messageId);
+  scheduleTurnCompletion(
+    pendingApproval.threadId,
+    isAllowedApprovalResult(message.result)
+      ? pendingApproval.responseText
+      : "Denied",
+    pendingApproval.delayMs,
+  );
+  return true;
+}
+
 function handleMessage(message: JsonRecord): void {
   if (handleToolResult(message)) {
     return;
@@ -559,6 +672,9 @@ function handleMessage(message: JsonRecord): void {
   if (handleUserQuestionResult(message)) {
     return;
   }
+  if (handleApprovalResult(message)) {
+    return;
+  }
 
   const method = getString(message.method);
   if (!method) {
diff --git a/packages/config/src/app-surface.ts b/packages/config/src/app-surface.ts
index 17620fa8a2..435ca8c34f 100644
--- a/packages/config/src/app-surface.ts
+++ b/packages/config/src/app-surface.ts
@@ -1,11 +1,26 @@
 export const APP_SURFACE_HEADER_NAME = "x-bb-app-surface";
 export const APP_SURFACE_ENV_NAME = "BB_APP_SURFACE";
 
+/**
+ * Surfaces a bb server can be configured as (`BB_APP_SURFACE`): the packaged
+ * desktop app or the plain web app.
+ */
 export const APP_SURFACE_VALUES = ["desktop", "web"] as const;
 export type AppSurface = (typeof APP_SURFACE_VALUES)[number];
 
+/**
+ * Surfaces a client may declare on a request (`x-bb-app-surface`). Includes
+ * the native mobile app, which is never a server-side surface.
+ */
+export const REQUEST_APP_SURFACE_VALUES = [
+  ...APP_SURFACE_VALUES,
+  "mobile",
+] as const;
+export type RequestAppSurface = (typeof REQUEST_APP_SURFACE_VALUES)[number];
+
 export const APP_SURFACE_DESKTOP: AppSurface = "desktop";
 export const APP_SURFACE_WEB: AppSurface = "web";
+export const APP_SURFACE_MOBILE: RequestAppSurface = "mobile";
 export const DEFAULT_APP_SURFACE: AppSurface = APP_SURFACE_WEB;
 
 export function parseAppSurface(
@@ -18,6 +33,16 @@ export function parseAppSurface(
   return APP_SURFACE_VALUES.find((surface) => surface === trimmedValue);
 }
 
+export function parseRequestAppSurface(
+  value: string | null | undefined,
+): RequestAppSurface | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  const trimmedValue = value.trim();
+  return REQUEST_APP_SURFACE_VALUES.find((surface) => surface === trimmedValue);
+}
+
 export function formatAppSurfaceValues(): string {
   return APP_SURFACE_VALUES.join(", ");
 }
diff --git a/packages/config/test/app-surface.test.ts b/packages/config/test/app-surface.test.ts
new file mode 100644
index 0000000000..75549f8842
--- /dev/null
+++ b/packages/config/test/app-surface.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { parseAppSurface, parseRequestAppSurface } from "../src/app-surface.js";
+
+describe("app surface parsing", () => {
+  it("accepts mobile only as a request surface", () => {
+    // `mobile` is a client declaration (x-bb-app-surface); a bb server can
+    // never be configured as the mobile surface (BB_APP_SURFACE).
+    expect(parseRequestAppSurface("mobile")).toBe("mobile");
+    expect(parseRequestAppSurface(" web ")).toBe("web");
+    expect(parseAppSurface("mobile")).toBeUndefined();
+    expect(parseAppSurface("desktop")).toBe("desktop");
+  });
+
+  it("rejects unknown and empty values on both parsers", () => {
+    expect(parseRequestAppSurface("tv")).toBeUndefined();
+    expect(parseRequestAppSurface(null)).toBeUndefined();
+    expect(parseAppSurface("")).toBeUndefined();
+  });
+});
diff --git a/packages/connect-client/package.json b/packages/connect-client/package.json
index 7dd9c55731..02f9b34b36 100644
--- a/packages/connect-client/package.json
+++ b/packages/connect-client/package.json
@@ -2,6 +2,7 @@
   "name": "@bb/connect-client",
   "version": "0.0.1",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "source": "./src/index.ts",
diff --git a/packages/connect-client/src/credential.ts b/packages/connect-client/src/credential.ts
index a155917749..c2e8b2618f 100644
--- a/packages/connect-client/src/credential.ts
+++ b/packages/connect-client/src/credential.ts
@@ -12,30 +12,3 @@ export const connectCredentialSchema = z.object({
 });
 
 export type ConnectCredential = z.infer<typeof connectCredentialSchema>;
-
-export type ConnectPublicProtocol = "http:" | "https:";
-
-/** Local Cloud is HTTP-only; every non-local Connect gate is HTTPS-only. */
-export function connectPublicProtocol(
-  baseDomain: string,
-): ConnectPublicProtocol {
-  const hostname = new URL(`https://${baseDomain}`).hostname;
-  return hostname.endsWith(".localhost") ? "http:" : "https:";
-}
-
-/**
- * Derive the connect cloud apex (`https://getbb.app`) from a server URL
- * (`https://<handle>.getbb.app`) by dropping the handle label.
- */
-export function deriveConnectBaseUrl(serverUrl: string): string {
-  return new URL(serverUrl).origin.replace(/\/\/[^.]+\./, "//");
-}
-
-/**
- * `https://getbb.app` + routing label → `https://<label>.getbb.app`.
- * `handle` is the redeemed server's subdomain (primary or additional).
- */
-export function serverUrlForHandle(baseUrl: string, handle: string): string {
-  const url = new URL(baseUrl);
-  return `${url.protocol}//${handle}.${url.host}`;
-}
diff --git a/packages/connect-client/src/index.ts b/packages/connect-client/src/index.ts
index e093662c0e..bca5b21f54 100644
--- a/packages/connect-client/src/index.ts
+++ b/packages/connect-client/src/index.ts
@@ -1,11 +1,13 @@
 export {
   connectCredentialSchema,
+  type ConnectCredential,
+} from "./credential.js";
+export {
   connectPublicProtocol,
   deriveConnectBaseUrl,
   serverUrlForHandle,
-  type ConnectCredential,
   type ConnectPublicProtocol,
-} from "./credential.js";
+} from "./urls.js";
 export {
   ConnectListError,
   isRevokedCredentialError,
@@ -27,3 +29,9 @@ export {
   redeemMachineCredential,
   type ConnectMachineRedeemErrorCode,
 } from "./redeem-machine.js";
+export {
+  encodeMobilePairingPayload,
+  mobilePairingPayload,
+  parseMobilePairingPayload,
+  type MobilePairingPayload,
+} from "./mobile-pairing.js";
diff --git a/packages/connect-client/src/list-servers.ts b/packages/connect-client/src/list-servers.ts
index 7730086080..675bf6e7dc 100644
--- a/packages/connect-client/src/list-servers.ts
+++ b/packages/connect-client/src/list-servers.ts
@@ -1,9 +1,6 @@
 import { z } from "zod";
-import {
-  deriveConnectBaseUrl,
-  serverUrlForHandle,
-  type ConnectCredential,
-} from "./credential.js";
+import type { ConnectCredential } from "./credential.js";
+import { deriveConnectBaseUrl, serverUrlForHandle } from "./urls.js";
 import { ConnectListError } from "./errors.js";
 
 /** One server row from `GET /api/connect/servers` (worker boundary). */
diff --git a/packages/connect-client/src/mobile-pairing.ts b/packages/connect-client/src/mobile-pairing.ts
new file mode 100644
index 0000000000..35991a8e70
--- /dev/null
+++ b/packages/connect-client/src/mobile-pairing.ts
@@ -0,0 +1,104 @@
+import { deriveConnectBaseUrl } from "./urls.js";
+
+// What a paired bb shows (as a QR code and as text) so the bb mobile app can
+// enroll itself as a connect machine. The producer side is the connect
+// plugin ("Add mobile device" in Settings → Remote access and
+// `bb connect machine-code`); the consumer is the phone's scanner / manual
+// entry, which redeems `code` at `apex` and then talks to `serverUrl`.
+//
+// `apex` rides along even though it is derivable from `serverUrl`: the phone
+// must not guess which cloud minted the code (self-hosted apexes, local Cloud
+// during development), and the producer already knows it.
+//
+// Deliberately zod-free: the connect plugin's browser bundle encodes this and
+// must not carry the validation stack for one object.
+export interface MobilePairingPayload {
+  /** One-time machine-pair code (`XXXX-XXXX`). */
+  code: string;
+  /** The bb this code targets, e.g. `https://<handle>.getbb.app`. */
+  serverUrl: string;
+  /** The connect apex that redeems the code, e.g. `https://getbb.app`. */
+  apex: string;
+  /** Epoch ms after which the apex refuses the code. */
+  expiresAt: number;
+}
+
+/**
+ * Build the pairing payload from a minted machine code. `apex` is derived
+ * from the server URL the apex echoed, so both always name the same cloud.
+ */
+export function mobilePairingPayload(machineCode: {
+  code: string;
+  serverUrl: string;
+  expiresAt: number;
+}): MobilePairingPayload {
+  return {
+    code: machineCode.code,
+    serverUrl: machineCode.serverUrl,
+    apex: deriveConnectBaseUrl(machineCode.serverUrl),
+    expiresAt: machineCode.expiresAt,
+  };
+}
+
+/** The QR code contents: compact JSON with a fixed key order. */
+export function encodeMobilePairingPayload(
+  payload: MobilePairingPayload,
+): string {
+  return JSON.stringify({
+    code: payload.code,
+    serverUrl: payload.serverUrl,
+    apex: payload.apex,
+    expiresAt: payload.expiresAt,
+  });
+}
+
+function isHttpUrl(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse scanned QR text back into a payload, or null when it is not one
+ * (another QR code, a bare URL, truncated JSON, wrong field types). Unknown
+ * extra fields are ignored so an older phone can still read a newer payload.
+ */
+export function parseMobilePairingPayload(
+  text: string,
+): MobilePairingPayload | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return null;
+  }
+  const record = raw as {
+    code?: unknown;
+    serverUrl?: unknown;
+    apex?: unknown;
+    expiresAt?: unknown;
+  };
+  if (
+    typeof record.code !== "string" ||
+    record.code.length === 0 ||
+    !isHttpUrl(record.serverUrl) ||
+    !isHttpUrl(record.apex) ||
+    typeof record.expiresAt !== "number" ||
+    !Number.isInteger(record.expiresAt)
+  ) {
+    return null;
+  }
+  return {
+    code: record.code,
+    serverUrl: record.serverUrl,
+    apex: record.apex,
+    expiresAt: record.expiresAt,
+  };
+}
diff --git a/packages/connect-client/src/urls.ts b/packages/connect-client/src/urls.ts
new file mode 100644
index 0000000000..84107583d4
--- /dev/null
+++ b/packages/connect-client/src/urls.ts
@@ -0,0 +1,30 @@
+// Pure URL helpers for the connect cloud: no zod, no fetch. Kept apart from the
+// credential schema so browser bundles that only need URL math (the connect
+// plugin's settings section) do not pull the validation stack in.
+
+export type ConnectPublicProtocol = "http:" | "https:";
+
+/** Local Cloud is HTTP-only; every non-local Connect gate is HTTPS-only. */
+export function connectPublicProtocol(
+  baseDomain: string,
+): ConnectPublicProtocol {
+  const hostname = new URL(`https://${baseDomain}`).hostname;
+  return hostname.endsWith(".localhost") ? "http:" : "https:";
+}
+
+/**
+ * Derive the connect cloud apex (`https://getbb.app`) from a server URL
+ * (`https://<handle>.getbb.app`) by dropping the handle label.
+ */
+export function deriveConnectBaseUrl(serverUrl: string): string {
+  return new URL(serverUrl).origin.replace(/\/\/[^.]+\./, "//");
+}
+
+/**
+ * `https://getbb.app` + routing label → `https://<label>.getbb.app`.
+ * `handle` is the redeemed server's subdomain (primary or additional).
+ */
+export function serverUrlForHandle(baseUrl: string, handle: string): string {
+  const url = new URL(baseUrl);
+  return `${url.protocol}//${handle}.${url.host}`;
+}
diff --git a/packages/connect-client/test/connect-client.test.ts b/packages/connect-client/test/connect-client.test.ts
index 7ca278dd57..8d12309e54 100644
--- a/packages/connect-client/test/connect-client.test.ts
+++ b/packages/connect-client/test/connect-client.test.ts
@@ -3,8 +3,11 @@ import {
   ConnectListError,
   ConnectMachineRedeemError,
   connectPublicProtocol,
+  encodeMobilePairingPayload,
   deriveConnectBaseUrl,
   listAccountServers,
+  mobilePairingPayload,
+  parseMobilePairingPayload,
   redeemMachineCredential,
   serverUrlForHandle,
 } from "../src/index.js";
@@ -186,3 +189,77 @@ describe("redeemMachineCredential", () => {
     ).resolves.toMatchObject({ handle: "laptop" });
   });
 });
+
+describe("mobile pairing payload", () => {
+  it("derives the apex from the server URL and round-trips through QR text", () => {
+    const payload = mobilePairingPayload({
+      code: "K7QP-2M4X",
+      serverUrl: "https://laptop.getbb.app",
+      expiresAt: 1_700_000_600_000,
+    });
+    expect(payload).toEqual({
+      code: "K7QP-2M4X",
+      serverUrl: "https://laptop.getbb.app",
+      apex: "https://getbb.app",
+      expiresAt: 1_700_000_600_000,
+    });
+    const text = encodeMobilePairingPayload(payload);
+    expect(JSON.parse(text)).toEqual(payload);
+    expect(parseMobilePairingPayload(text)).toEqual(payload);
+  });
+
+  it("keeps a local Cloud apex's scheme and port", () => {
+    expect(
+      mobilePairingPayload({
+        code: "AAAA-BBBB",
+        serverUrl: "http://laptop.bb.localhost:42745",
+        expiresAt: 1,
+      }).apex,
+    ).toBe("http://bb.localhost:42745");
+  });
+
+  it("rejects text that is not a pairing payload", () => {
+    expect(parseMobilePairingPayload("https://laptop.getbb.app")).toBeNull();
+    expect(parseMobilePairingPayload("{not json")).toBeNull();
+    expect(parseMobilePairingPayload('{"code":"K7QP-2M4X"}')).toBeNull();
+    expect(
+      parseMobilePairingPayload(
+        JSON.stringify({
+          code: "K7QP-2M4X",
+          serverUrl: "laptop.getbb.app",
+          apex: "https://getbb.app",
+          expiresAt: 1,
+        }),
+      ),
+    ).toBeNull();
+    expect(
+      parseMobilePairingPayload(
+        JSON.stringify({
+          code: "K7QP-2M4X",
+          serverUrl: "https://laptop.getbb.app",
+          apex: "https://getbb.app",
+          expiresAt: "soon",
+        }),
+      ),
+    ).toBeNull();
+  });
+
+  it("ignores extra fields from a newer producer", () => {
+    expect(
+      parseMobilePairingPayload(
+        JSON.stringify({
+          code: "K7QP-2M4X",
+          serverUrl: "https://laptop.getbb.app",
+          apex: "https://getbb.app",
+          expiresAt: 1,
+          label: "Sawyer's Mac",
+        }),
+      ),
+    ).toEqual({
+      code: "K7QP-2M4X",
+      serverUrl: "https://laptop.getbb.app",
+      apex: "https://getbb.app",
+      expiresAt: 1,
+    });
+  });
+});
diff --git a/packages/connect-db/src/app-links.ts b/packages/connect-db/src/app-links.ts
new file mode 100644
index 0000000000..5d492d3e17
--- /dev/null
+++ b/packages/connect-db/src/app-links.ts
@@ -0,0 +1,116 @@
+// bb mobile app-link association files (iOS universal links, Android app
+// links). Served unauthenticated from every `<label>.getbb.app` by the connect
+// gate (before the session check) and from the apex by bb-web, so a
+// `https://<handle>.getbb.app/threads/<id>` link opens the app when it is
+// installed. Single source of truth for the app ids and the path allowlist.
+
+/** Apple team id + iOS bundle id of the bb mobile app. */
+export const BB_MOBILE_IOS_APP_ID = "9QCU24SXK5.app.getbb.mobile";
+/** Android application id of the bb mobile app. */
+export const BB_MOBILE_ANDROID_PACKAGE = "app.getbb.mobile";
+
+/**
+ * Web paths the app claims (mirrors `apps/mobile/app.json`: iOS
+ * `associatedDomains`, Android `intentFilters`). Everything else stays in
+ * the browser.
+ */
+export const BB_MOBILE_APP_LINK_PATHS: readonly string[] = [
+  "/threads/*",
+  "/projects/*",
+  "/settings/*",
+];
+
+export const APPLE_APP_SITE_ASSOCIATION_PATH =
+  "/.well-known/apple-app-site-association";
+export const ANDROID_ASSET_LINKS_PATH = "/.well-known/assetlinks.json";
+
+/**
+ * `https://developer.apple.com/documentation/xcode/supporting-associated-domains`
+ * — the modern `components` form plus the legacy `paths` array for older
+ * iOS versions. Served as `application/json` with no redirects.
+ */
+export function buildAppleAppSiteAssociation(): Record<string, unknown> {
+  return {
+    applinks: {
+      apps: [],
+      details: [
+        {
+          appIDs: [BB_MOBILE_IOS_APP_ID],
+          appID: BB_MOBILE_IOS_APP_ID,
+          paths: [...BB_MOBILE_APP_LINK_PATHS],
+          components: BB_MOBILE_APP_LINK_PATHS.map((path) => ({
+            "/": path,
+          })),
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Parse the `ASSETLINKS_SHA256_FINGERPRINTS` env var (comma / whitespace
+ * separated `AA:BB:…` signing-cert fingerprints). Empty → no fingerprints →
+ * Android cannot verify the app (the file still serves so the allowlist is
+ * discoverable and the deploy does not depend on the signing key).
+ */
+export function parseAssetLinksFingerprints(
+  value: string | undefined | null,
+): string[] {
+  if (!value) return [];
+  return value
+    .split(/[\s,]+/u)
+    .map((entry) => entry.trim().toUpperCase())
+    .filter((entry) => entry.length > 0);
+}
+
+/** `https://developers.google.com/digital-asset-links/v1/getting-started` */
+export function buildAndroidAssetLinks(
+  sha256CertFingerprints: readonly string[],
+): unknown[] {
+  return [
+    {
+      relation: ["delegate_permission/common.handle_all_urls"],
+      target: {
+        namespace: "android_app",
+        package_name: BB_MOBILE_ANDROID_PACKAGE,
+        sha256_cert_fingerprints: [...sha256CertFingerprints],
+      },
+    },
+  ];
+}
+
+/**
+ * Answer a `GET`/`HEAD` for either association file, or `null` when the
+ * request is for something else. Shared by the gate worker and bb-web so the
+ * two never drift. Cacheable for an hour (Apple's CDN refetches on its own
+ * schedule; a redeploy with new ids does not need an instant flip).
+ */
+export function handleAppLinkAssociationRequest(
+  request: { method: string; url: string },
+  env: { ASSETLINKS_SHA256_FINGERPRINTS?: string },
+): Response | null {
+  const { pathname } = new URL(request.url);
+  let body: unknown;
+  if (pathname === APPLE_APP_SITE_ASSOCIATION_PATH) {
+    body = buildAppleAppSiteAssociation();
+  } else if (pathname === ANDROID_ASSET_LINKS_PATH) {
+    body = buildAndroidAssetLinks(
+      parseAssetLinksFingerprints(env.ASSETLINKS_SHA256_FINGERPRINTS),
+    );
+  } else {
+    return null;
+  }
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    return new Response("method not allowed\n", {
+      status: 405,
+      headers: { allow: "GET, HEAD" },
+    });
+  }
+  return new Response(request.method === "HEAD" ? null : JSON.stringify(body), {
+    status: 200,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "public, max-age=3600",
+    },
+  });
+}
diff --git a/packages/connect-db/src/index.ts b/packages/connect-db/src/index.ts
index 0b4a98bb4b..88465da320 100644
--- a/packages/connect-db/src/index.ts
+++ b/packages/connect-db/src/index.ts
@@ -1,3 +1,4 @@
 export * from "./schema.js";
 export * from "./constants.js";
 export * from "./availability.js";
+export * from "./app-links.js";
diff --git a/packages/connect-db/test/app-links.test.ts b/packages/connect-db/test/app-links.test.ts
new file mode 100644
index 0000000000..a2cd88b903
--- /dev/null
+++ b/packages/connect-db/test/app-links.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import {
+  ANDROID_ASSET_LINKS_PATH,
+  APPLE_APP_SITE_ASSOCIATION_PATH,
+  BB_MOBILE_ANDROID_PACKAGE,
+  BB_MOBILE_IOS_APP_ID,
+  handleAppLinkAssociationRequest,
+  parseAssetLinksFingerprints,
+} from "../src/app-links.js";
+
+describe("app link association files", () => {
+  it("serves the AASA as application/json with the app id and path allowlist", async () => {
+    const response = handleAppLinkAssociationRequest(
+      {
+        method: "GET",
+        url: `https://sawyer.getbb.app${APPLE_APP_SITE_ASSOCIATION_PATH}`,
+      },
+      {},
+    );
+    expect(response?.status).toBe(200);
+    expect(response?.headers.get("content-type")).toBe("application/json");
+    const body = (await response?.json()) as {
+      applinks: {
+        details: { appIDs: string[]; paths: string[]; components: unknown[] }[];
+      };
+    };
+    expect(body.applinks.details[0]?.appIDs).toEqual([BB_MOBILE_IOS_APP_ID]);
+    expect(body.applinks.details[0]?.paths).toEqual([
+      "/threads/*",
+      "/projects/*",
+      "/settings/*",
+    ]);
+    expect(body.applinks.details[0]?.components).toHaveLength(3);
+  });
+
+  it("serves assetlinks.json with the fingerprints from the env (empty when unset)", async () => {
+    const unset = handleAppLinkAssociationRequest(
+      { method: "GET", url: `https://getbb.app${ANDROID_ASSET_LINKS_PATH}` },
+      {},
+    );
+    const unsetBody = (await unset?.json()) as {
+      target: { package_name: string; sha256_cert_fingerprints: string[] };
+    }[];
+    expect(unsetBody[0]?.target.package_name).toBe(BB_MOBILE_ANDROID_PACKAGE);
+    expect(unsetBody[0]?.target.sha256_cert_fingerprints).toEqual([]);
+
+    const set = handleAppLinkAssociationRequest(
+      { method: "GET", url: `https://getbb.app${ANDROID_ASSET_LINKS_PATH}` },
+      { ASSETLINKS_SHA256_FINGERPRINTS: "aa:bb:cc, dd:ee:ff\n11:22" },
+    );
+    const setBody = (await set?.json()) as {
+      target: { sha256_cert_fingerprints: string[] };
+    }[];
+    expect(setBody[0]?.target.sha256_cert_fingerprints).toEqual([
+      "AA:BB:CC",
+      "DD:EE:FF",
+      "11:22",
+    ]);
+    expect(parseAssetLinksFingerprints(undefined)).toEqual([]);
+  });
+
+  it("ignores other paths and refuses non-GET methods", () => {
+    expect(
+      handleAppLinkAssociationRequest(
+        { method: "GET", url: "https://getbb.app/.well-known/other" },
+        {},
+      ),
+    ).toBeNull();
+    expect(
+      handleAppLinkAssociationRequest(
+        { method: "GET", url: "https://getbb.app/threads/x" },
+        {},
+      ),
+    ).toBeNull();
+    const post = handleAppLinkAssociationRequest(
+      {
+        method: "POST",
+        url: `https://getbb.app${APPLE_APP_SITE_ASSOCIATION_PATH}`,
+      },
+      {},
+    );
+    expect(post?.status).toBe(405);
+    const head = handleAppLinkAssociationRequest(
+      {
+        method: "HEAD",
+        url: `https://getbb.app${APPLE_APP_SITE_ASSOCIATION_PATH}`,
+      },
+      {},
+    );
+    expect(head?.status).toBe(200);
+    expect(head?.body).toBeNull();
+  });
+});
diff --git a/packages/plugin-interaction-contracts/package.json b/packages/plugin-interaction-contracts/package.json
new file mode 100644
index 0000000000..09ad14ceb4
--- /dev/null
+++ b/packages/plugin-interaction-contracts/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@bb/plugin-interaction-contracts",
+  "version": "0.0.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "types": "./src/index.ts",
+  "scripts": {
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@bb/tsconfig": "workspace:*",
+    "@types/node": "^22.0.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "typescript-7": "npm:typescript@^7.0.2",
+    "vitest": "^4.1.1"
+  }
+}
diff --git a/packages/plugin-interaction-contracts/src/ask-user-question.ts b/packages/plugin-interaction-contracts/src/ask-user-question.ts
new file mode 100644
index 0000000000..c927f08e46
--- /dev/null
+++ b/packages/plugin-interaction-contracts/src/ask-user-question.ts
@@ -0,0 +1,76 @@
+import { z } from "zod";
+
+/**
+ * Pending-interaction contract of the bundled `ask-user-question` plugin
+ * (`plugins/ask-user-question`): the payload the plugin's server puts on
+ * `bb.ui.requestInput({ rendererId: "ask-user-question", payload })` and the
+ * response value its form submits back. Shared between the plugin and the
+ * native app (which renders the form without the plugin's React DOM bundle).
+ *
+ * Limits mirror Claude Code's own `AskUserQuestion` tool so a model that has
+ * learned the native tool hits the same walls here. `header` has no hard cap
+ * on either side — Claude's schema documents "max 12 chars" in prose without
+ * enforcing it, and rejecting a 13-character chip label would be a worse
+ * failure than rendering it.
+ */
+export const ASK_USER_QUESTION_RENDERER_ID = "ask-user-question";
+
+export const MAX_QUESTIONS = 4;
+export const MAX_OPTIONS = 4;
+export const MAX_SELECTED = MAX_OPTIONS;
+export const MAX_FREE_TEXT_LENGTH = 4096;
+/**
+ * Per-option preview cap. Previews are freeform (mockups, diffs, snippets) and
+ * every one of them rides the 64 KiB `bb.ui.requestInput` payload, so the cap
+ * keeps a single question from exhausting that budget on its own.
+ */
+export const MAX_OPTION_PREVIEW_LENGTH = 4096;
+
+const nonBlank = (value: string) => value.trim().length > 0;
+
+// ---------------------------------------------------------------------------
+// Interaction payload — server → the form.
+// ---------------------------------------------------------------------------
+
+export const interactionOptionSchema = z.object({
+  value: z.string().min(1),
+  label: z.string().min(1),
+  description: z.string().min(1).optional(),
+  preview: z.string().min(1).optional(),
+});
+export type InteractionOption = z.infer<typeof interactionOptionSchema>;
+
+export const interactionQuestionSchema = z.object({
+  id: z.string().min(1),
+  prompt: z.string().min(1),
+  shortLabel: z.string().min(1),
+  multiSelect: z.boolean(),
+  options: z.array(interactionOptionSchema).max(MAX_OPTIONS),
+  allowFreeText: z.boolean(),
+});
+export type InteractionQuestion = z.infer<typeof interactionQuestionSchema>;
+
+export const interactionPayloadSchema = z.object({
+  questions: z.array(interactionQuestionSchema).min(1).max(MAX_QUESTIONS),
+});
+export type InteractionPayload = z.infer<typeof interactionPayloadSchema>;
+
+// ---------------------------------------------------------------------------
+// Interaction response — the form → server.
+// ---------------------------------------------------------------------------
+
+export const interactionAnswerSchema = z.object({
+  selected: z.array(z.string().min(1)).max(MAX_SELECTED),
+  freeText: z
+    .string()
+    .min(1)
+    .max(MAX_FREE_TEXT_LENGTH)
+    .refine(nonBlank, "Free text cannot be blank")
+    .optional(),
+});
+export type InteractionAnswer = z.infer<typeof interactionAnswerSchema>;
+
+export const interactionResponseSchema = z.object({
+  answers: z.record(z.string().min(1), interactionAnswerSchema),
+});
+export type InteractionResponse = z.infer<typeof interactionResponseSchema>;
diff --git a/packages/plugin-interaction-contracts/src/index.ts b/packages/plugin-interaction-contracts/src/index.ts
new file mode 100644
index 0000000000..ff1e26bc78
--- /dev/null
+++ b/packages/plugin-interaction-contracts/src/index.ts
@@ -0,0 +1,33 @@
+// @bb/plugin-interaction-contracts: the payload/response zod schemas of the
+// bundled plugins' pending interactions (`ask-user-question`,
+// `secret-request`). A real cross-package contract: the plugins produce and
+// consume these on the server, and clients that cannot run the plugins' React
+// DOM bundles (the native app) render the same forms natively from them.
+export {
+  ASK_USER_QUESTION_RENDERER_ID,
+  MAX_FREE_TEXT_LENGTH,
+  MAX_OPTION_PREVIEW_LENGTH,
+  MAX_OPTIONS,
+  MAX_QUESTIONS,
+  MAX_SELECTED,
+  interactionAnswerSchema,
+  interactionOptionSchema,
+  interactionPayloadSchema,
+  interactionQuestionSchema,
+  interactionResponseSchema,
+  type InteractionAnswer,
+  type InteractionOption,
+  type InteractionPayload,
+  type InteractionQuestion,
+  type InteractionResponse,
+} from "./ask-user-question.js";
+export {
+  SECRET_REQUEST_RENDERER_ID,
+  SECRET_VALUE_MAX_LENGTH,
+  secretNameSchema,
+  secretRequestPayloadSchema,
+  secretRequestResponseSchema,
+  secretValueSchema,
+  type SecretRequestPayload,
+  type SecretRequestResponse,
+} from "./secret-request.js";
diff --git a/packages/plugin-interaction-contracts/src/secret-request.ts b/packages/plugin-interaction-contracts/src/secret-request.ts
new file mode 100644
index 0000000000..681778efa4
--- /dev/null
+++ b/packages/plugin-interaction-contracts/src/secret-request.ts
@@ -0,0 +1,44 @@
+import { z } from "zod";
+
+/**
+ * Pending-interaction contract of the bundled `secrets` plugin
+ * (`plugins/secrets`): the payload its `bb secret request` CLI puts on
+ * `bb.ui.requestInput({ rendererId: "secret-request", payload })` and the
+ * `{ values }` response the form submits back (one single-line value per
+ * requested variable; the plugin writes them to the dotenv destination).
+ */
+export const SECRET_REQUEST_RENDERER_ID = "secret-request";
+
+export const SECRET_VALUE_MAX_LENGTH = 16 * 1024;
+
+export const secretNameSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
+
+export const secretRequestPayloadSchema = z.object({
+  purpose: z.string().min(1).nullable(),
+  destination: z.object({ kind: z.literal("dotenv"), path: z.string().min(1) }),
+  fields: z
+    .array(
+      z.object({
+        name: secretNameSchema,
+        description: z.string().min(1).nullable(),
+      }),
+    )
+    .min(1),
+});
+export type SecretRequestPayload = z.infer<typeof secretRequestPayloadSchema>;
+
+export const secretValueSchema = z
+  .string()
+  .min(1)
+  .max(SECRET_VALUE_MAX_LENGTH)
+  .refine((value) => !value.includes("\n") && !value.includes("\r"), {
+    message: "Secret values must be single-line strings",
+  })
+  .refine((value) => !value.includes("\0"), {
+    message: "Secret values must not contain NUL",
+  });
+
+export const secretRequestResponseSchema = z.object({
+  values: z.record(secretNameSchema, secretValueSchema),
+});
+export type SecretRequestResponse = z.infer<typeof secretRequestResponseSchema>;
diff --git a/packages/plugin-interaction-contracts/test/contracts.test.ts b/packages/plugin-interaction-contracts/test/contracts.test.ts
new file mode 100644
index 0000000000..16f9e9eeb3
--- /dev/null
+++ b/packages/plugin-interaction-contracts/test/contracts.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import {
+  interactionPayloadSchema,
+  interactionResponseSchema,
+  MAX_OPTIONS,
+  secretRequestPayloadSchema,
+  secretRequestResponseSchema,
+} from "../src/index.js";
+
+describe("ask-user-question contracts", () => {
+  it("accepts a payload with options, previews, and free text", () => {
+    const parsed = interactionPayloadSchema.safeParse({
+      questions: [
+        {
+          id: "q1",
+          prompt: "Pick a color",
+          shortLabel: "Color",
+          multiSelect: false,
+          allowFreeText: true,
+          options: [
+            {
+              value: "red",
+              label: "Red",
+              description: "Warm",
+              preview: "#f00",
+            },
+            { value: "blue", label: "Blue" },
+          ],
+        },
+      ],
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  it("rejects more than the option cap and blank free text answers", () => {
+    const options = Array.from({ length: MAX_OPTIONS + 1 }, (_, index) => ({
+      value: `v${index}`,
+      label: `Option ${index}`,
+    }));
+    expect(
+      interactionPayloadSchema.safeParse({
+        questions: [
+          {
+            id: "q1",
+            prompt: "Too many",
+            shortLabel: "Many",
+            multiSelect: true,
+            allowFreeText: false,
+            options,
+          },
+        ],
+      }).success,
+    ).toBe(false);
+    expect(
+      interactionResponseSchema.safeParse({
+        answers: { q1: { selected: [], freeText: "   " } },
+      }).success,
+    ).toBe(false);
+    expect(
+      interactionResponseSchema.safeParse({
+        answers: { q1: { selected: ["v1"] } },
+      }).success,
+    ).toBe(true);
+  });
+});
+
+describe("secret-request contracts", () => {
+  it("requires a dotenv destination and identifier-like names", () => {
+    expect(
+      secretRequestPayloadSchema.safeParse({
+        purpose: null,
+        destination: { kind: "dotenv", path: "/repo/.env" },
+        fields: [{ name: "API_KEY", description: null }],
+      }).success,
+    ).toBe(true);
+    expect(
+      secretRequestPayloadSchema.safeParse({
+        purpose: "x",
+        destination: { kind: "dotenv", path: "/repo/.env" },
+        fields: [{ name: "1BAD", description: null }],
+      }).success,
+    ).toBe(false);
+  });
+
+  it("rejects multi-line or empty values", () => {
+    expect(
+      secretRequestResponseSchema.safeParse({ values: { API_KEY: "abc" } })
+        .success,
+    ).toBe(true);
+    expect(
+      secretRequestResponseSchema.safeParse({ values: { API_KEY: "a\nb" } })
+        .success,
+    ).toBe(false);
+    expect(
+      secretRequestResponseSchema.safeParse({ values: { API_KEY: "" } })
+        .success,
+    ).toBe(false);
+  });
+});
diff --git a/packages/plugin-interaction-contracts/tsconfig.json b/packages/plugin-interaction-contracts/tsconfig.json
new file mode 100644
index 0000000000..12e131cc20
--- /dev/null
+++ b/packages/plugin-interaction-contracts/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": [
+    "@bb/tsconfig/base.json",
+    "@bb/tsconfig/typecheck-overrides.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["src", "test"]
+}
diff --git a/packages/plugin-interaction-contracts/vitest.config.ts b/packages/plugin-interaction-contracts/vitest.config.ts
new file mode 100644
index 0000000000..89432760a4
--- /dev/null
+++ b/packages/plugin-interaction-contracts/vitest.config.ts
@@ -0,0 +1,10 @@
+import { defineWorkspaceTestConfig } from "../../vitest.shared.js";
+
+export default defineWorkspaceTestConfig({
+  test: {
+    silent: "passed-only",
+    name: "@bb/plugin-interaction-contracts",
+    include: ["test/**/*.test.ts"],
+    exclude: ["dist/**", "node_modules/**"],
+  },
+});
diff --git a/packages/sdk/src/areas/projects.ts b/packages/sdk/src/areas/projects.ts
index 95593e443a..54a609cd55 100644
--- a/packages/sdk/src/areas/projects.ts
+++ b/packages/sdk/src/areas/projects.ts
@@ -15,6 +15,7 @@ import type {
   PromptHistoryResponse,
   PromptHistoryQuery,
   ReorderProjectRequest,
+  SidebarBootstrapResponse,
   UpdateProjectRequest,
   UpdateProjectSourceRequest,
   UploadedPromptAttachment,
@@ -96,6 +97,10 @@ export interface ProjectDefaultExecutionOptionsArgs {
   signal?: AbortSignal;
 }
 
+export interface ProjectSidebarBootstrapArgs {
+  signal?: AbortSignal;
+}
+
 export interface ProjectAttachmentFileLike {
   arrayBuffer(): Promise<ArrayBuffer>;
   readonly name: string;
@@ -181,6 +186,7 @@ export type ProjectListResult =
 export type ProjectPathsResult = WorkspacePathListResponse;
 export type ProjectPromptHistoryResult = PromptHistoryResponse;
 export type ProjectReorderResult = ProjectResponse[];
+export type ProjectSidebarBootstrapResult = SidebarBootstrapResponse;
 export type ProjectSourceAddResult = ProjectSource;
 export type ProjectSourceDeleteResult = { ok: true };
 export type ProjectSourceUpdateResult = ProjectSource;
@@ -218,6 +224,14 @@ export interface ProjectsArea {
     args: ProjectPromptHistoryArgs,
   ): Promise<ProjectPromptHistoryResult>;
   reorder(args: ProjectReorderArgs): Promise<ProjectReorderResult>;
+  /**
+   * One round-trip navigation snapshot: thread sections, every project with
+   * its live threads and resolved thread-creation defaults, and the personal
+   * project. Backs the sidebar of the web and native apps.
+   */
+  sidebarBootstrap(
+    args?: ProjectSidebarBootstrapArgs,
+  ): Promise<ProjectSidebarBootstrapResult>;
   sources: ProjectSourcesArea;
   update(args: ProjectUpdateArgs): Promise<ProjectUpdateResult>;
 }
@@ -559,6 +573,14 @@ export function createProjectsArea(args: CreateSdkAreaArgs): ProjectsArea {
         }),
       );
     },
+    async sidebarBootstrap(input = {}) {
+      return transport.readJson(
+        transport.api.v1["sidebar-bootstrap"].$get(
+          {},
+          ...signalRequestArgs(input.signal),
+        ),
+      );
+    },
     sources,
     async update(input) {
       return transport.readJson(
diff --git a/packages/sdk/src/response.ts b/packages/sdk/src/response.ts
index 8d77ea9cff..b09f31eeba 100644
--- a/packages/sdk/src/response.ts
+++ b/packages/sdk/src/response.ts
@@ -31,6 +31,18 @@ interface WrapRequestTimeoutBodyArgs {
   stream: ReadableStream<Uint8Array>;
 }
 
+/**
+ * The subset of `Response` the SDK reads. Constraining on this instead of the
+ * global `Response` keeps typed Hono client responses assignable in every
+ * runtime whose global `Response`/`FormData` declarations differ from lib.dom
+ * (React Native declares its own `FormData` with `getParts()`, which makes
+ * `Response.formData()` incompatible even though the SDK never calls it).
+ */
+export type SdkResponseLike = Pick<
+  Response,
+  "arrayBuffer" | "headers" | "json" | "ok" | "status" | "statusText" | "text"
+>;
+
 export type JsonBodyOf<TResponse> = TResponse extends {
   json(): Promise<infer TBody>;
 }
@@ -124,20 +136,20 @@ export function createRequestTimeoutFetch(
   };
 }
 
-export async function readJsonResponse<TResponse extends Response>(
+export async function readJsonResponse<TResponse extends SdkResponseLike>(
   response: Promise<TResponse>,
 ): Promise<JsonBodyOf<TResponse>> {
   const resolved = await resolveResponse(response);
   return resolved.json();
 }
 
-export async function readVoidResponse<TResponse extends Response>(
+export async function readVoidResponse<TResponse extends SdkResponseLike>(
   response: Promise<TResponse>,
 ): Promise<void> {
   await resolveResponse(response);
 }
 
-export async function resolveResponse<TResponse extends Response>(
+export async function resolveResponse<TResponse extends SdkResponseLike>(
   responsePromise: Promise<TResponse>,
 ): Promise<TResponse> {
   let response: TResponse;
@@ -305,7 +317,9 @@ function readHttpErrorCode(parsed: unknown): string | null {
   return typeof code === "string" ? code : null;
 }
 
-async function readHttpErrorInfo(response: Response): Promise<HttpErrorInfo> {
+async function readHttpErrorInfo(
+  response: SdkResponseLike,
+): Promise<HttpErrorInfo> {
   let rawBody: string;
   try {
     rawBody = await response.text();
diff --git a/packages/sdk/src/transport.ts b/packages/sdk/src/transport.ts
index 24df4cc923..a4c780ee5b 100644
--- a/packages/sdk/src/transport.ts
+++ b/packages/sdk/src/transport.ts
@@ -2,6 +2,7 @@ import type { ApiClient } from "@bb/server-contract";
 import type {
   FetchImplementation,
   JsonBodyOf,
+  SdkResponseLike,
 } from "./response.js";
 
 export type BbSdkRuntime = "node" | "browser";
@@ -12,13 +13,13 @@ export interface BbSdkTransport {
   fetch: FetchImplementation;
   realtimeUrl?: string;
   runtime: BbSdkRuntime;
-  readJson<TResponse extends Response>(
+  readJson<TResponse extends SdkResponseLike>(
     response: Promise<TResponse>,
   ): Promise<JsonBodyOf<TResponse>>;
-  readVoid<TResponse extends Response>(
+  readVoid<TResponse extends SdkResponseLike>(
     response: Promise<TResponse>,
   ): Promise<void>;
-  resolve<TResponse extends Response>(
+  resolve<TResponse extends SdkResponseLike>(
     response: Promise<TResponse>,
   ): Promise<TResponse>;
   websocket?: BbRealtimeSocketFactory;
diff --git a/packages/sdk/test/public-types.test.ts b/packages/sdk/test/public-types.test.ts
index 17d3747079..cd1ee49cca 100644
--- a/packages/sdk/test/public-types.test.ts
+++ b/packages/sdk/test/public-types.test.ts
@@ -301,11 +301,7 @@ type ExpectedPluginsKey =
   | "token"
   | "updateSettings";
 
-type ExpectedPluginCatalogKey =
-  | "install"
-  | "installPlan"
-  | "search"
-  | "status";
+type ExpectedPluginCatalogKey = "install" | "installPlan" | "search" | "status";
 
 type ExpectedPluginMarketplacesKey = "add" | "list" | "refresh" | "remove";
 
@@ -323,6 +319,7 @@ type ExpectedProjectsKey =
   | "paths"
   | "promptHistory"
   | "reorder"
+  | "sidebarBootstrap"
   | "sources"
   | "update";
 
diff --git a/packages/templates/src/templates/bb-guide-environments.md b/packages/templates/src/templates/bb-guide-environments.md
index 718cfbc549..ae22f38b32 100644
--- a/packages/templates/src/templates/bb-guide-environments.md
+++ b/packages/templates/src/templates/bb-guide-environments.md
@@ -155,6 +155,7 @@ Remote access (bb connect):
   bb connect unexpose <port> [--host <name-or-id>]  Stop sharing on that host
   bb connect shares [--host <name-or-id>]           List that host's shares
   bb connect servers                      List every bb on this account (handle, url, live)
+  bb connect machine-code                 Mint a one-time code that pairs the bb mobile app
 
   Port sharing works from threads on any enrolled host. In a thread,
   `bb connect expose <port>` resolves the thread environment's host; outside a
@@ -169,7 +170,16 @@ Remote access (bb connect):
   `bb connect status` shows all shares with host + URL. `shares --json` returns
   the resolved `host` and rows with `hostId`, `hostName`, `port`, and `url`.
 
+  The bb mobile app pairs with a paired bb through bb connect. Settings →
+  Remote access → Add mobile device shows a QR code plus the code as text;
+  `bb connect machine-code` prints the same code, server URL, apex, and expiry
+  (`--json` for `{code, serverUrl, apex, expiresAt}`). The phone scans or
+  types the code and enrolls as a connect machine on the account with its own
+  revocable credential (it appears in the getbb.app dashboard machine list).
+  Codes last 10 minutes and work once; an account-machine-limit failure says
+  so and points at the dashboard to revoke an unused device.
+
   Remote access is owned by the builtin "connect" plugin (Plugins → connect
-  shows the URL, QR code, and shared ports). Disabling the plugin
-  (`bb plugin disable connect`) cuts off all remote access; re-enable with
-  `bb plugin enable connect`.
+  shows the URL, QR code, mobile pairing, and shared ports). Disabling the
+  plugin (`bb plugin disable connect`) cuts off all remote access; re-enable
+  with `bb plugin enable connect`.
diff --git a/plugins/ask-user-question/package.json b/plugins/ask-user-question/package.json
index c775368d02..fe1cef3432 100644
--- a/plugins/ask-user-question/package.json
+++ b/plugins/ask-user-question/package.json
@@ -24,6 +24,7 @@
     "test": "vitest run --config vitest.config.ts"
   },
   "dependencies": {
+    "@bb/plugin-interaction-contracts": "workspace:*",
     "@bb/shared-ui": "workspace:*",
     "zod": "^4.3.6"
   },
diff --git a/plugins/ask-user-question/src/contracts.ts b/plugins/ask-user-question/src/contracts.ts
index f5ffb923ff..12216b24b5 100644
--- a/plugins/ask-user-question/src/contracts.ts
+++ b/plugins/ask-user-question/src/contracts.ts
@@ -1,22 +1,32 @@
 import { z } from "zod";
-
-/**
- * Limits mirrored from Claude Code's own `AskUserQuestion` tool so a model
- * that has learned the native tool hits the same walls here. `header` has no
- * hard cap on either side — Claude's schema documents "max 12 chars" in prose
- * without enforcing it, and rejecting a 13-character chip label would be a
- * worse failure than rendering it.
- */
-export const MAX_QUESTIONS = 4;
-export const MAX_OPTIONS = 4;
-export const MAX_SELECTED = MAX_OPTIONS;
-export const MAX_FREE_TEXT_LENGTH = 4096;
-/**
- * Per-option preview cap. Previews are freeform (mockups, diffs, snippets) and
- * every one of them rides the 64 KiB `bb.ui.requestInput` payload, so the cap
- * keeps a single question from exhausting that budget on its own.
- */
-export const MAX_OPTION_PREVIEW_LENGTH = 4096;
+import {
+  MAX_OPTION_PREVIEW_LENGTH,
+  MAX_OPTIONS,
+  MAX_QUESTIONS,
+} from "@bb/plugin-interaction-contracts";
+
+// The interaction payload/response contract (what the server hands the form
+// and what the form submits back) lives in @bb/plugin-interaction-contracts so
+// clients that cannot run this plugin's React DOM bundle (the native app) can
+// render the same form. Re-exported here so the plugin's own modules keep one
+// import path; the tool input/result shapes below stay plugin-private.
+export {
+  MAX_FREE_TEXT_LENGTH,
+  MAX_OPTION_PREVIEW_LENGTH,
+  MAX_OPTIONS,
+  MAX_QUESTIONS,
+  MAX_SELECTED,
+  interactionAnswerSchema,
+  interactionOptionSchema,
+  interactionPayloadSchema,
+  interactionQuestionSchema,
+  interactionResponseSchema,
+  type InteractionAnswer,
+  type InteractionOption,
+  type InteractionPayload,
+  type InteractionQuestion,
+  type InteractionResponse,
+} from "@bb/plugin-interaction-contracts";
 
 const nonBlank = (value: string) => value.trim().length > 0;
 
@@ -54,53 +64,6 @@ export const toolInputSchema = z.object({
 });
 export type ToolInput = z.infer<typeof toolInputSchema>;
 
-// ---------------------------------------------------------------------------
-// Interaction payload — server → the plugin's composer form.
-// ---------------------------------------------------------------------------
-
-export const interactionOptionSchema = z.object({
-  value: z.string().min(1),
-  label: z.string().min(1),
-  description: z.string().min(1).optional(),
-  preview: z.string().min(1).optional(),
-});
-export type InteractionOption = z.infer<typeof interactionOptionSchema>;
-
-export const interactionQuestionSchema = z.object({
-  id: z.string().min(1),
-  prompt: z.string().min(1),
-  shortLabel: z.string().min(1),
-  multiSelect: z.boolean(),
-  options: z.array(interactionOptionSchema).max(MAX_OPTIONS),
-  allowFreeText: z.boolean(),
-});
-export type InteractionQuestion = z.infer<typeof interactionQuestionSchema>;
-
-export const interactionPayloadSchema = z.object({
-  questions: z.array(interactionQuestionSchema).min(1).max(MAX_QUESTIONS),
-});
-export type InteractionPayload = z.infer<typeof interactionPayloadSchema>;
-
-// ---------------------------------------------------------------------------
-// Interaction response — the form → server.
-// ---------------------------------------------------------------------------
-
-export const interactionAnswerSchema = z.object({
-  selected: z.array(z.string().min(1)).max(MAX_SELECTED),
-  freeText: z
-    .string()
-    .min(1)
-    .max(MAX_FREE_TEXT_LENGTH)
-    .refine(nonBlank, "Free text cannot be blank")
-    .optional(),
-});
-export type InteractionAnswer = z.infer<typeof interactionAnswerSchema>;
-
-export const interactionResponseSchema = z.object({
-  answers: z.record(z.string().min(1), interactionAnswerSchema),
-});
-export type InteractionResponse = z.infer<typeof interactionResponseSchema>;
-
 // ---------------------------------------------------------------------------
 // Tool result — what the model reads back.
 // ---------------------------------------------------------------------------
diff --git a/plugins/connect/app.test.tsx b/plugins/connect/app.test.tsx
index f1c182cf99..af67ebee00 100644
--- a/plugins/connect/app.test.tsx
+++ b/plugins/connect/app.test.tsx
@@ -358,6 +358,108 @@ describe("connect settings section", () => {
     await slot.findByText(/this bb is not connected to getbb.app/);
   });
 
+  it("add mobile device mints a machine code and shows the QR payload, the code, and a countdown", async () => {
+    const expiresAt = Date.now() + 600_000;
+    const slot = renderSlot(
+      app.settingsSections[0]!,
+      {},
+      {
+        rpc: {
+          status: () => connected(),
+          createMachineCode: () => ({
+            code: "K7QP-2M4X",
+            expiresAt,
+            serverUrl: "https://workstation.getbb.app",
+          }),
+        },
+      },
+    );
+
+    await slot.findByText("Connected");
+    expect(slot.queryByText("K7QP-2M4X")).toBeNull();
+    fireEvent.click(slot.getByRole("button", { name: "Add mobile device" }));
+
+    await waitFor(() =>
+      expect(slot.rpcCalls).toContainEqual({
+        method: "createMachineCode",
+        input: null,
+      }),
+    );
+    // The code is shown as copyable text…
+    await slot.findByText("K7QP-2M4X");
+    slot.getByRole("button", { name: "Copy pairing code" });
+    slot.getByText(/Code expires in 9:5\d/);
+    // …and the QR carries the full pairing payload (code + server + apex).
+    const qr = (await slot.findByRole("img", {
+      name: "QR code to pair the bb mobile app",
+    })) as HTMLImageElement;
+    expect(qr.src.startsWith("data:image/png")).toBe(true);
+    slot.getByText(/bb connect machine-code/);
+  });
+
+  it("an expired mobile pairing code offers a fresh one", async () => {
+    let minted = 0;
+    const slot = renderSlot(
+      app.settingsSections[0]!,
+      {},
+      {
+        rpc: {
+          status: () => connected(),
+          createMachineCode: () => {
+            minted += 1;
+            return {
+              code: minted === 1 ? "AAAA-1111" : "BBBB-2222",
+              // The first code dies almost immediately; the renewal lasts.
+              expiresAt: Date.now() + (minted === 1 ? 1_200 : 600_000),
+              serverUrl: "https://workstation.getbb.app",
+            };
+          },
+        },
+      },
+    );
+
+    await slot.findByText("Connected");
+    fireEvent.click(slot.getByRole("button", { name: "Add mobile device" }));
+    await slot.findByText("AAAA-1111");
+
+    await slot.findByText("Code expired", undefined, { timeout: 4_000 });
+    expect(
+      slot.queryByRole("button", { name: "Copy pairing code" }),
+    ).toBeNull();
+    fireEvent.click(slot.getByRole("button", { name: "Generate a new code" }));
+
+    await slot.findByText("BBBB-2222");
+    expect(slot.queryByText("AAAA-1111")).toBeNull();
+    slot.getByText(/Code expires in/);
+  });
+
+  it("explains the account machine limit with a dashboard link", async () => {
+    const slot = renderSlot(
+      app.settingsSections[0]!,
+      {},
+      {
+        rpc: {
+          status: () => connected(),
+          createMachineCode: () => {
+            throw new Error("machine_limit");
+          },
+        },
+      },
+    );
+
+    await slot.findByText("Connected");
+    fireEvent.click(slot.getByRole("button", { name: "Add mobile device" }));
+
+    await slot.findByText(/reached its machine limit/);
+    const link = slot.getByRole("link", {
+      name: "Revoke a device you no longer use",
+    }) as HTMLAnchorElement;
+    expect(link.href).toBe("https://getbb.app/dashboard");
+    // No wire text, no stale code card; the action is available to retry.
+    expect(slot.queryByText("machine_limit")).toBeNull();
+    slot.getByRole("button", { name: "Add mobile device" });
+  });
+
   it("disconnect confirms, then lands on the unpaired card with a receipt", async () => {
     let currentStatus = connected();
     const slot = renderSlot(
diff --git a/plugins/connect/app.tsx b/plugins/connect/app.tsx
index 460e9fdd7c..867d561044 100644
--- a/plugins/connect/app.tsx
+++ b/plugins/connect/app.tsx
@@ -4,11 +4,16 @@
 // `connect` realtime pushes. Four states, each matched to the redesign mock:
 // not paired (promise + two numbered steps + auto-submitting code field),
 // pairing (inline typed-code errors), connected (URL hero chip + QR toggle +
-// shared ports + isolated disconnect), reconnecting (amber wash + dimmed
-// body). Disconnect confirms in a dialog, then lands on the unpaired card
-// with a transient receipt.
+// mobile-app pairing + shared ports + isolated disconnect), reconnecting
+// (amber wash + dimmed body). Disconnect confirms in a dialog, then lands on
+// the unpaired card with a transient receipt.
 import { useCallback, useEffect, useRef, useState } from "react";
 import { definePluginApp, useRealtime, useRpc } from "@get-bb/plugin-sdk/app";
+import {
+  encodeMobilePairingPayload,
+  mobilePairingPayload,
+  type MobilePairingPayload,
+} from "@bb/connect-client";
 import type { connectRpcContract } from "./src/rpc.js";
 import QRCode from "qrcode";
 import { Button } from "@bb/shared-ui/button";
@@ -248,7 +253,15 @@ function StepNumber({ value }: { value: number }) {
   );
 }
 
-function QrCodeImage({ value }: { value: string }) {
+function QrCodeImage({
+  value,
+  alt,
+  className,
+}: {
+  value: string;
+  alt?: string;
+  className?: string;
+}) {
   const [dataUrl, setDataUrl] = useState<string | null>(null);
   useEffect(() => {
     let cancelled = false;
@@ -268,8 +281,11 @@ function QrCodeImage({ value }: { value: string }) {
   return (
     <img
       src={dataUrl}
-      alt={`QR code for ${value}`}
-      className="size-32 rounded-md border border-border bg-white p-1.5"
+      alt={alt ?? `QR code for ${value}`}
+      className={cn(
+        "size-32 rounded-md border border-border bg-white p-1.5",
+        className,
+      )}
     />
   );
 }
@@ -358,7 +374,7 @@ function UrlHero({ url, showOpen }: { url: string; showOpen: boolean }) {
   );
 }
 
-function QuietCopyButton({ url, label }: { url: string; label: string }) {
+function QuietCopyButton({ text, label }: { text: string; label: string }) {
   const [copied, setCopied] = useState(false);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   useEffect(
@@ -368,7 +384,7 @@ function QuietCopyButton({ url, label }: { url: string; label: string }) {
     [],
   );
   const copy = useCallback(() => {
-    navigator.clipboard.writeText(url).then(
+    navigator.clipboard.writeText(text).then(
       () => {
         setCopied(true);
         if (timerRef.current !== null) clearTimeout(timerRef.current);
@@ -378,7 +394,7 @@ function QuietCopyButton({ url, label }: { url: string; label: string }) {
         // Quiet copy has no inline hint; leave the label unchanged.
       },
     );
-  }, [url]);
+  }, [text]);
   return (
     <Button
       type="button"
@@ -500,6 +516,223 @@ function PairForm({
   );
 }
 
+// ---------------------------------------------------------------------------
+// Add mobile device: mint a one-time machine code for the bb mobile app.
+//
+// The phone enrolls as a connect *machine* (its own revocable credential, the
+// desktop-app model), so this reuses the `createMachineCode` rpc. The QR
+// carries the pairing payload (code + server + apex + expiry) and the code is
+// shown as copyable text for manual entry. Mirrors `bb connect machine-code`.
+// ---------------------------------------------------------------------------
+
+type MachineCodeErrorCode = "machine_limit" | "network" | "not_paired";
+
+function toMachineCodeErrorCode(error: unknown): MachineCodeErrorCode {
+  const message = errorText(error);
+  if (message === "machine_limit" || message === "not_paired") return message;
+  // Unknown failures read as transient; the user can retry.
+  return "network";
+}
+
+/** "9:58" — minutes:seconds left on a code, clamped at 0:00. */
+function formatCountdown(remainingMs: number): string {
+  const totalSeconds = Math.max(0, Math.floor(remainingMs / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${minutes}:${seconds.toString().padStart(2, "0")}`;
+}
+
+/** Ticks once a second while a deadline is set; returns ms left (or null). */
+function useCountdown(expiresAt: number | null): number | null {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (expiresAt === null) return;
+    const interval = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(interval);
+  }, [expiresAt]);
+  return expiresAt === null ? null : expiresAt - now;
+}
+
+function MobilePairingCard({
+  payload,
+  dashboardHost,
+  minting,
+  onRenew,
+}: {
+  payload: MobilePairingPayload;
+  dashboardHost: string;
+  minting: boolean;
+  onRenew: () => void;
+}) {
+  const remainingMs = useCountdown(payload.expiresAt);
+  const expired = remainingMs !== null && remainingMs <= 0;
+  const qrText = encodeMobilePairingPayload(payload);
+  return (
+    <div className="flex flex-col gap-3 rounded-md border border-border bg-surface-recessed/50 px-3 py-3 sm:flex-row sm:items-start">
+      <div className={cn("shrink-0", expired && "opacity-40 saturate-0")}>
+        <QrCodeImage
+          value={qrText}
+          alt="QR code to pair the bb mobile app"
+          className="size-40"
+        />
+      </div>
+      <div className="min-w-0 flex-1 space-y-2">
+        <p className="text-sm">
+          Scan this with the bb mobile app, or enter the code by hand.
+        </p>
+        <div className="flex max-w-xs items-center gap-1 rounded-lg border border-border bg-surface-recessed py-1 pl-3.5 pr-1">
+          <span
+            className={cn(
+              "min-w-0 flex-1 truncate font-mono text-sm font-medium tracking-widest",
+              expired
+                ? "text-muted-foreground line-through"
+                : "text-foreground",
+            )}
+            aria-label="Mobile pairing code"
+          >
+            {payload.code}
+          </span>
+          {expired ? null : (
+            <QuietCopyButton text={payload.code} label="Copy pairing code" />
+          )}
+        </div>
+        <div className="flex items-center gap-2 text-xs text-subtle-foreground">
+          {expired ? (
+            <>
+              <span>Code expired</span>
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                className="text-muted-foreground"
+                disabled={minting}
+                onClick={onRenew}
+              >
+                {minting ? (
+                  <Icon name="Spinner" className="size-4 animate-spin" />
+                ) : null}
+                Generate a new code
+              </Button>
+            </>
+          ) : remainingMs !== null ? (
+            <span className="tabular-nums">
+              Code expires in {formatCountdown(remainingMs)}
+            </span>
+          ) : null}
+        </div>
+        <p className="text-xs text-subtle-foreground/75">
+          The code works once. Your phone gets its own credential on your{" "}
+          {dashboardHost} account — it shows up in the dashboard&apos;s machine
+          list, where you can revoke it. Same thing from a terminal:{" "}
+          <span className="font-mono">bb connect machine-code</span>.
+        </p>
+      </div>
+    </div>
+  );
+}
+
+function AddMobileDeviceSection({ dashboardUrl }: { dashboardUrl: string }) {
+  const rpc = useRpc<typeof connectRpcContract>();
+  const [payload, setPayload] = useState<MobilePairingPayload | null>(null);
+  const [minting, setMinting] = useState(false);
+  const [errorCode, setErrorCode] = useState<MachineCodeErrorCode | null>(null);
+  const dashboardHost = hostOf(dashboardUrl);
+
+  const mint = useCallback(() => {
+    if (minting) return;
+    setMinting(true);
+    setErrorCode(null);
+    rpc.call("createMachineCode").then(
+      (result) => {
+        setMinting(false);
+        setPayload(mobilePairingPayload(result));
+      },
+      (rpcError: unknown) => {
+        setMinting(false);
+        setErrorCode(toMachineCodeErrorCode(rpcError));
+      },
+    );
+  }, [minting, rpc]);
+
+  return (
+    <div className="space-y-2.5 border-t border-border-seam pt-4">
+      <div className="flex items-center">
+        <h3 className="text-[11px] font-semibold uppercase tracking-wide text-subtle-foreground">
+          Mobile app
+        </h3>
+        <span className="flex-1" />
+        {payload === null ? (
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="text-muted-foreground"
+            disabled={minting}
+            onClick={mint}
+          >
+            {minting ? (
+              <Icon name="Spinner" className="size-3.5 animate-spin" />
+            ) : (
+              <Icon name="Plus" className="size-3.5" />
+            )}
+            Add mobile device
+          </Button>
+        ) : (
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="text-muted-foreground"
+            onClick={() => {
+              setPayload(null);
+              setErrorCode(null);
+            }}
+          >
+            Done
+          </Button>
+        )}
+      </div>
+
+      {payload !== null ? (
+        <MobilePairingCard
+          // A renewed code is a fresh card: restart its clock from now.
+          key={payload.code}
+          payload={payload}
+          dashboardHost={dashboardHost}
+          minting={minting}
+          onRenew={mint}
+        />
+      ) : (
+        <p className="text-xs text-subtle-foreground/75">
+          Pair the bb mobile app with this bb. It gets a one-time code to scan
+          or type; the phone then reaches this bb through {dashboardHost}.
+        </p>
+      )}
+
+      {errorCode === "machine_limit" ? (
+        <div className="max-w-md rounded-md border border-surface-destructive-border bg-surface-destructive px-3 py-2 text-xs text-destructive-text">
+          Your {dashboardHost} account has reached its machine limit.{" "}
+          <a
+            href={dashboardUrl}
+            target="_blank"
+            rel="noreferrer"
+            className="font-semibold underline underline-offset-2"
+          >
+            Revoke a device you no longer use
+          </a>{" "}
+          in the dashboard, then try again.
+        </div>
+      ) : errorCode !== null ? (
+        <p className="text-xs text-destructive-text">
+          {errorCode === "not_paired"
+            ? "This bb is no longer paired — re-pair, then try again."
+            : "Couldn't reach the Connect service to create a code — check your connection, then try again."}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Shared ports subsection (restyled into the section grammar).
 // ---------------------------------------------------------------------------
@@ -653,7 +886,7 @@ function SharedPortsSection({
                             {hostOf(share.url)}
                           </a>
                           <QuietCopyButton
-                            url={share.url}
+                            text={share.url}
                             label={`Copy share URL for port ${share.port}`}
                           />
                         </>
@@ -949,6 +1182,8 @@ function ConnectedContent({
         </div>
       ) : null}
 
+      <AddMobileDeviceSection dashboardUrl={status.dashboardUrl} />
+
       <SharedPortsSection shares={status.shares} dimmed={false} />
 
       <div className="-mx-4 mt-4 flex items-center gap-3 border-t border-border-seam px-4 pt-3">
diff --git a/plugins/connect/src/cli.ts b/plugins/connect/src/cli.ts
index 47db848892..4061002e9d 100644
--- a/plugins/connect/src/cli.ts
+++ b/plugins/connect/src/cli.ts
@@ -1,5 +1,10 @@
 import type { BbPluginApi, PluginCliResult } from "@get-bb/plugin-sdk";
+import {
+  mobilePairingPayload,
+  type MobilePairingPayload,
+} from "@bb/connect-client";
 import type { ShareHostResolver } from "./hosts.js";
+import { MachineCodeError } from "./machine-code.js";
 import { parseSharePort } from "./shares.js";
 import type { ConnectTunnel } from "./tunnel.js";
 import type { ConnectStatus } from "./types.js";
@@ -7,7 +12,8 @@ import type { ConnectStatus } from "./types.js";
 // `bb connect` — resolved through the plugin CLI proxy. The dashboard-issued
 // command `npx -p bb-app@latest bb connect --code <code> --server <url>` must
 // keep working verbatim, so the root command takes the pairing flags and
-// `status` / `off` / `expose` / `unexpose` / `shares` / `servers` are subcommands.
+// `status` / `off` / `expose` / `unexpose` / `shares` / `servers` /
+// `machine-code` are subcommands.
 
 interface ParsedFlags {
   flags: Map<string, string | true>;
@@ -76,6 +82,8 @@ function helpText(): string {
     "  bb connect unexpose <port> [--host <name-or-id>]  Stop sharing a port on that host",
     "  bb connect shares [--host <name-or-id>]           List shares for the thread's host",
     "  bb connect servers             List every bb on this account (from getbb.app)",
+    "  bb connect machine-code        Mint a one-time code that enrolls the bb mobile app (or another",
+    "                                 device) as a connect machine for this bb",
     "",
     "The server holds the tunnel; it stays up while bb is running.",
   ].join("\n");
@@ -108,6 +116,43 @@ function notPairedError(): string {
   return "this bb is not connected to getbb.app — run `bb connect` for how to pair";
 }
 
+/**
+ * Human copy for a failed `machine-code`. The typed code is stable (the panel
+ * maps the same codes); the dashboard host is named so the limit message tells
+ * the user where to free a slot.
+ */
+function machineCodeErrorText(
+  error: MachineCodeError,
+  dashboardUrl: string,
+): string {
+  switch (error.code) {
+    case "not_paired":
+      return notPairedError();
+    case "machine_limit":
+      return `this account has reached its connect machine limit — revoke a device you no longer use at ${dashboardUrl}, then try again`;
+    case "network":
+      return "could not reach the connect service to mint a machine code — check the connection and try again";
+  }
+}
+
+function formatMachineCode(payload: MobilePairingPayload): string {
+  const minutes = Math.max(
+    0,
+    Math.round((payload.expiresAt - Date.now()) / 60_000),
+  );
+  return [
+    `Code:       ${payload.code}`,
+    `Server:     ${payload.serverUrl}`,
+    `Apex:       ${payload.apex}`,
+    `Expires:    ${new Date(payload.expiresAt).toISOString()} (in about ${minutes} min)`,
+    "",
+    "Enter the code in the bb mobile app when it asks to pair over bb connect (or",
+    "scan the QR code from Settings → Remote access → Add mobile device). The phone",
+    "enrolls as a connect machine on this account — it appears in the getbb.app",
+    "dashboard's machine list, where you can revoke it. The code works once.",
+  ].join("\n");
+}
+
 export function registerConnectCli(args: {
   bb: Pick<BbPluginApi, "cli">;
   tunnel: ConnectTunnel;
@@ -149,6 +194,12 @@ export function registerConnectCli(args: {
         summary: "List every bb server on this account",
         usage: "bb connect servers [--json]",
       },
+      {
+        name: "machine-code",
+        summary:
+          "Mint a one-time code that enrolls the bb mobile app as a connect machine",
+        usage: "bb connect machine-code [--json]",
+      },
     ],
     async run(argv, ctx): Promise<PluginCliResult> {
       try {
@@ -294,6 +345,26 @@ export function registerConnectCli(args: {
           ];
           return { exitCode: 0, stdout: `${lines.join("\n")}\n` };
         }
+        if (first === "machine-code") {
+          const parsed = parseFlags(argv.slice(1));
+          validateFlags(parsed, { boolean: ["json"] });
+          let payload: MobilePairingPayload;
+          try {
+            payload = mobilePairingPayload(await tunnel.createMachineCode());
+          } catch (error) {
+            if (error instanceof MachineCodeError) {
+              return {
+                exitCode: 1,
+                stderr: `${machineCodeErrorText(error, tunnel.status().dashboardUrl)}\n`,
+              };
+            }
+            throw error;
+          }
+          if (parsed.flags.has("json")) {
+            return { exitCode: 0, stdout: asJson(payload) };
+          }
+          return { exitCode: 0, stdout: `${formatMachineCode(payload)}\n` };
+        }
         if (first !== undefined && !first.startsWith("--")) {
           return {
             exitCode: 1,
diff --git a/plugins/connect/src/connect.test.ts b/plugins/connect/src/connect.test.ts
index 94bdd51fb2..4cddc49eb6 100644
--- a/plugins/connect/src/connect.test.ts
+++ b/plugins/connect/src/connect.test.ts
@@ -2534,6 +2534,110 @@ describe("connect CLI", () => {
     );
   });
 
+  it("machine-code when unpaired errors clearly", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const { harness } = await loadCli();
+    const result = await harness.runCli(["machine-code"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("not connected to getbb.app");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("machine-code prints the pairing payload as text or json", async () => {
+    const fetchMock = vi.fn(
+      async (input: RequestInfo | URL, _init?: RequestInit) => {
+        const url = String(input);
+        if (url.includes("/api/connect/redeem")) {
+          return new Response(
+            JSON.stringify({ credential: "bbcred_live", handle: "sawyer" }),
+            { status: 200 },
+          );
+        }
+        if (url === "https://getbb.app/api/connect/machine-code") {
+          return new Response(
+            JSON.stringify({
+              code: "K7QP-2M4X",
+              expiresInMs: 600_000,
+              serverUrl: "https://sawyer.getbb.app",
+            }),
+          );
+        }
+        return new Response("not found", { status: 404 });
+      },
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    const { harness } = await loadCli();
+    await harness.runCli([
+      "--code",
+      "ABCD",
+      "--server",
+      "https://sawyer.getbb.app",
+    ]);
+
+    const before = Date.now();
+    const text = await harness.runCli(["machine-code"]);
+    expect(text.exitCode).toBe(0);
+    expect(text.stdout).toContain("Code:       K7QP-2M4X");
+    expect(text.stdout).toContain("Server:     https://sawyer.getbb.app");
+    expect(text.stdout).toContain("Apex:       https://getbb.app");
+    expect(text.stdout).toContain("in about 10 min");
+    expect(text.stdout).toContain("Add mobile device");
+
+    const json = await harness.runCli(["machine-code", "--json"]);
+    expect(json.exitCode).toBe(0);
+    const parsed = JSON.parse(json.stdout ?? "") as Record<string, unknown>;
+    expect(parsed).toEqual({
+      code: "K7QP-2M4X",
+      serverUrl: "https://sawyer.getbb.app",
+      apex: "https://getbb.app",
+      expiresAt: expect.any(Number),
+    });
+    expect(parsed.expiresAt as number).toBeGreaterThanOrEqual(before + 600_000);
+    // Minted through the apex with the server's own pairing credential.
+    const call = fetchMock.mock.calls.find(
+      ([input]) =>
+        String(input) === "https://getbb.app/api/connect/machine-code",
+    );
+    expect(call?.[1]).toEqual({
+      method: "POST",
+      headers: { "x-bb-connect-machine": "bbcred_live" },
+    });
+  });
+
+  it("machine-code explains the account machine limit and names the dashboard", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: RequestInfo | URL) => {
+        const url = String(input);
+        if (url.includes("/api/connect/redeem")) {
+          return new Response(
+            JSON.stringify({ credential: "bbcred_live", handle: "sawyer" }),
+            { status: 200 },
+          );
+        }
+        if (url.endsWith("/api/connect/machine-code")) {
+          return new Response(JSON.stringify({ error: "machine-limit" }), {
+            status: 409,
+          });
+        }
+        return new Response("not found", { status: 404 });
+      }),
+    );
+    const { harness } = await loadCli();
+    await harness.runCli([
+      "--code",
+      "ABCD",
+      "--server",
+      "https://sawyer.getbb.app",
+    ]);
+    const result = await harness.runCli(["machine-code"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain("machine limit");
+    expect(result.stderr).toContain("https://getbb.app/dashboard");
+    expect(result.stderr).not.toContain("machine_limit");
+  });
+
   it("expose / shares / unexpose happy path", async () => {
     vi.stubGlobal(
       "fetch",
diff --git a/plugins/secrets/package.json b/plugins/secrets/package.json
index 84e95928d8..a2f18ea5b3 100644
--- a/plugins/secrets/package.json
+++ b/plugins/secrets/package.json
@@ -24,6 +24,7 @@
     "test": "vitest run --config vitest.config.ts"
   },
   "dependencies": {
+    "@bb/plugin-interaction-contracts": "workspace:*",
     "@bb/shared-ui": "workspace:*",
     "@hugeicons/core-free-icons": "^4.1.3",
     "@hugeicons/react": "^1.1.6",
diff --git a/plugins/secrets/src/contracts.ts b/plugins/secrets/src/contracts.ts
index 718c24116d..9b876560d0 100644
--- a/plugins/secrets/src/contracts.ts
+++ b/plugins/secrets/src/contracts.ts
@@ -1,32 +1,11 @@
-import { z } from "zod";
-
-export const secretNameSchema = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/u);
-
-export const secretRequestPayloadSchema = z.object({
-  purpose: z.string().min(1).nullable(),
-  destination: z.object({ kind: z.literal("dotenv"), path: z.string().min(1) }),
-  fields: z
-    .array(
-      z.object({
-        name: secretNameSchema,
-        description: z.string().min(1).nullable(),
-      }),
-    )
-    .min(1),
-});
-export type SecretRequestPayload = z.infer<typeof secretRequestPayloadSchema>;
-
-const secretValueSchema = z
-  .string()
-  .min(1)
-  .max(16 * 1024)
-  .refine((value) => !value.includes("\n") && !value.includes("\r"), {
-    message: "Secret values must be single-line strings",
-  })
-  .refine((value) => !value.includes("\0"), {
-    message: "Secret values must not contain NUL",
-  });
-
-export const secretRequestResponseSchema = z.object({
-  values: z.record(secretNameSchema, secretValueSchema),
-});
+// The secret-request payload/response contract lives in
+// @bb/plugin-interaction-contracts so clients that cannot run this plugin's
+// React DOM bundle (the native app) can render the same secure form.
+// Re-exported here so the plugin's own modules keep one import path.
+export {
+  secretNameSchema,
+  secretRequestPayloadSchema,
+  secretRequestResponseSchema,
+  type SecretRequestPayload,
+  type SecretRequestResponse,
+} from "@bb/plugin-interaction-contracts";
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 302eb7ed4d..1ea0205a83 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1783,6 +1783,28 @@ importers:
         specifier: ^4.1.1
         version: 4.1.1(@opentelemetry/api@1.9.1)(@types/node@22.19.10)(jsdom@29.0.1(@noble/hashes@2.0.1))(msw@2.12.14(@types/node@22.19.10)(@typescript/typescript6@6.0.2))(vite@8.0.12(@types/node@22.19.10)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))
 
+  packages/plugin-interaction-contracts:
+    dependencies:
+      zod:
+        specifier: 4.3.6
+        version: 4.3.6
+    devDependencies:
+      '@bb/tsconfig':
+        specifier: workspace:*
+        version: link:../tsconfig
+      '@types/node':
+        specifier: ^22.0.0
+        version: 22.19.10
+      typescript:
+        specifier: npm:@typescript/typescript6@^6.0.2
+        version: '@typescript/typescript6@6.0.2'
+      typescript-7:
+        specifier: npm:typescript@^7.0.2
+        version: typescript@7.0.2
+      vitest:
+        specifier: ^4.1.1
+        version: 4.1.1(@opentelemetry/api@1.9.1)(@types/node@22.19.10)(jsdom@29.0.1(@noble/hashes@2.0.1))(msw@2.12.14(@types/node@22.19.10)(@typescript/typescript6@6.0.2))(vite@8.0.12(@types/node@22.19.10)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.23.1)(yaml@2.9.0))
+
   packages/plugin-registry:
     devDependencies:
       '@bb/plugin-build':
@@ -2461,6 +2483,9 @@ importers:
 
   plugins/ask-user-question:
     dependencies:
+      '@bb/plugin-interaction-contracts':
+        specifier: workspace:*
+        version: link:../../packages/plugin-interaction-contracts
       '@bb/shared-ui':
         specifier: workspace:*
         version: link:../../packages/shared-ui
@@ -3131,6 +3156,9 @@ importers:
 
   plugins/secrets:
     dependencies:
+      '@bb/plugin-interaction-contracts':
+        specifier: workspace:*
+        version: link:../../packages/plugin-interaction-contracts
       '@bb/shared-ui':
         specifier: workspace:*
         version: link:../../packages/shared-ui
diff --git a/tests/integration/helpers/harness.ts b/tests/integration/helpers/harness.ts
index 786645c573..3ce31baad0 100644
--- a/tests/integration/helpers/harness.ts
+++ b/tests/integration/helpers/harness.ts
@@ -107,6 +107,17 @@ export interface IntegrationHarness {
 
 export interface CreateHarnessOptions {
   adapterFactory?: ProviderAdapterFactory;
+  /**
+   * Bind the server to a fixed port instead of an ephemeral one. Long-lived
+   * harness backends (mobile e2e) need a stable URL for the app under test.
+   */
+  serverPort?: number;
+  /**
+   * Bind host. Defaults to loopback. `0.0.0.0` lets a physical phone on the
+   * same network reach the harness server; the client base URL stays on
+   * 127.0.0.1 either way.
+   */
+  bindHost?: "127.0.0.1" | "0.0.0.0";
 }
 
 export type WithHarnessCallback<T> = (
@@ -344,8 +355,8 @@ async function startIntegrationServer(
       // 127.0.0.1 too. If we leave the host unspecified, this server can end
       // up on ::1 while another local process owns 127.0.0.1 on the same
       // port, and the client will hit that other process instead.
-      hostname: TEST_SERVER_HOST,
-      port: 0,
+      hostname: options.bindHost ?? TEST_SERVER_HOST,
+      port: options.serverPort ?? 0,
       fetch: app.fetch,
     },
     (info) => {
diff --git a/tests/integration/mobile-e2e/backend.ts b/tests/integration/mobile-e2e/backend.ts
new file mode 100644
index 0000000000..a6713fe9fc
--- /dev/null
+++ b/tests/integration/mobile-e2e/backend.ts
@@ -0,0 +1,296 @@
+// Long-lived harness backend for the mobile app's Maestro flows.
+//
+// Starts the in-process integration server + host daemon with the fake
+// provider adapter (user questions enabled) on a fixed port, seeds a project
+// with a few threads, prints the connection details as JSON on stdout, and
+// keeps running until SIGINT/SIGTERM.
+//
+// Usage (from the repo root):
+//   pnpm --filter @bb/integration-tests e2e:mobile-backend
+//   BB_MOBILE_E2E_PORT=41999 BB_MOBILE_E2E_BIND_HOST=0.0.0.0 pnpm ... (physical phone)
+//
+// The iOS Simulator shares the Mac loopback, so the app can use
+// http://127.0.0.1:<port> directly. The Android emulator uses 10.0.2.2.
+import { createFakeAdapter } from "@bb/agent-runtime/test";
+import type { PendingInteraction } from "@bb/domain";
+import { createIntegrationHarness } from "../helpers/harness.js";
+import type { IntegrationHarness } from "../helpers/harness.js";
+import {
+  createProjectFixture,
+  createReadyHostThread,
+} from "../helpers/fixtures.js";
+import {
+  listThreadInteractions,
+  resolveThreadInteraction,
+  sendTextMessage,
+} from "../helpers/api.js";
+import { waitForThreadStatus } from "../helpers/assertions.js";
+
+const DEFAULT_PORT = 41999;
+
+function readPort(): number {
+  const raw = process.env.BB_MOBILE_E2E_PORT;
+  if (!raw) return DEFAULT_PORT;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new Error(`Invalid BB_MOBILE_E2E_PORT: ${raw}`);
+  }
+  return parsed;
+}
+
+function readBindHost(): "127.0.0.1" | "0.0.0.0" {
+  const raw = process.env.BB_MOBILE_E2E_BIND_HOST;
+  if (raw === undefined || raw === "127.0.0.1") return "127.0.0.1";
+  if (raw === "0.0.0.0") return "0.0.0.0";
+  throw new Error(`Invalid BB_MOBILE_E2E_BIND_HOST: ${raw}`);
+}
+
+const TURN_TIMEOUT_MS = 15_000;
+const INTERACTION_POLL_INTERVAL_MS = 100;
+
+/** First pending interaction of `threadId`, polling until one appears. */
+async function waitForPendingInteraction(
+  harness: IntegrationHarness,
+  threadId: string,
+  timeoutMs = TURN_TIMEOUT_MS,
+): Promise<PendingInteraction> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const interactions = await listThreadInteractions(harness.api, threadId);
+    const pending = interactions.find(
+      (interaction) => interaction.status === "pending",
+    );
+    if (pending) return pending;
+    if (Date.now() >= deadline) {
+      throw new Error(
+        `Timed out waiting for a pending interaction on thread ${threadId}`,
+      );
+    }
+    await new Promise((resolve) =>
+      setTimeout(resolve, INTERACTION_POLL_INTERVAL_MS),
+    );
+  }
+}
+
+/** Sends one message and waits for the turn to finish. */
+async function runTurn(
+  harness: IntegrationHarness,
+  threadId: string,
+  text: string,
+): Promise<void> {
+  await sendTextMessage(harness.api, threadId, { text });
+  await waitForThreadStatus(harness.api, threadId, "idle", TURN_TIMEOUT_MS);
+}
+
+// ≥60 lines of markdown with a heading, a code block, a table, a list, and a
+// link so every Phase 4a renderer has content to show. Must not contain the
+// fake provider's control tokens (`approve:`, `call_tool:`, `ask_user`,
+// `delay:`) anywhere as whitespace-delimited words.
+const LONG_MARKDOWN_MESSAGE = [
+  "# Release checklist overview",
+  "",
+  "This message exercises the markdown renderer end to end. It is long on",
+  "purpose so the timeline has to scroll, and it mixes every block type the",
+  "mobile renderer supports.",
+  "",
+  "## Goals",
+  "",
+  "- Ship the native timeline with parity for common rows.",
+  "- Keep the delta merge cheap while a turn streams.",
+  "- Verify paging, the unread divider, and the table of contents.",
+  "",
+  "## Steps",
+  "",
+  "1. Build the dev client once.",
+  "2. Start Metro against the harness backend.",
+  "3. Run the Maestro flows.",
+  "",
+  "## Commands",
+  "",
+  "```bash",
+  "pnpm exec turbo run typecheck lint test --filter=@bb/mobile",
+  "cd apps/mobile && pnpm e2e:ios",
+  "xcrun simctl io booted screenshot /tmp/timeline.png",
+  "```",
+  "",
+  "## Rows covered",
+  "",
+  "| Row kind | Source | Notes |",
+  "| --- | --- | --- |",
+  "| conversation | user + assistant | markdown bodies |",
+  "| command | tool-call token | tool call with args |",
+  "| approval | approval token | allowed once |",
+  "| question | question token | left pending |",
+  "",
+  "## Reference",
+  "",
+  "See the [bb docs](https://docs.getbb.app) for the server contract and the",
+  "plan in `plans/bb-mobile-expo.md` for the phase breakdown.",
+  "",
+  "## Notes",
+  "",
+  "Paragraph one of the notes section. It has enough words to wrap on a",
+  "phone so line breaking inside paragraphs gets exercised as well.",
+  "",
+  "Paragraph two mentions `inline code`, **bold text**, and _emphasis_ so",
+  "the inline renderers get a look too.",
+  "",
+  "> A blockquote with a single line of advice: keep the rows flat.",
+  "",
+  "### Sub-heading one",
+  "",
+  "- nested list level one",
+  "  - nested list level two",
+  "  - another level-two item",
+  "- back to level one",
+  "",
+  "### Sub-heading two",
+  "",
+  "Final paragraph. If you can read this on the device, the long message",
+  "scrolled into view correctly.",
+  "",
+  "Trailing line one.",
+  "Trailing line two.",
+  "Trailing line three.",
+  "Trailing line four.",
+].join("\n");
+
+async function main(): Promise<void> {
+  const harness = await createIntegrationHarness({
+    adapterFactory: () =>
+      createFakeAdapter({ supportsNativeUserQuestion: true }),
+    bindHost: readBindHost(),
+    serverPort: readPort(),
+  });
+
+  const shutdown = async (signal: string) => {
+    process.stderr.write(`mobile-e2e backend: ${signal}, shutting down\n`);
+    await harness.cleanup();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+
+  const project = await createProjectFixture(harness, {
+    name: "Mobile E2E Project",
+  });
+
+  // Thread 1: a completed exchange the app can render read-only.
+  const completed = await createReadyHostThread(harness, {
+    projectId: project.id,
+    title: "Completed thread",
+    workspace: { type: "unmanaged", path: null },
+  });
+  await sendTextMessage(harness.api, completed.thread.id, {
+    text: "Hello from the seed",
+  });
+  await waitForThreadStatus(harness.api, completed.thread.id, "idle", 15_000);
+
+  // Thread 2: idle, for the app to send into (fake adapter echoes
+  // `Response to: ...`, honors `delay:<ms>` and `ask_user`).
+  const idle = await createReadyHostThread(harness, {
+    projectId: project.id,
+    title: "Idle thread",
+    workspace: { type: "unmanaged", path: null },
+  });
+
+  // Thread 3: several turns so the timeline has content for every Phase 4a
+  // row renderer. The `ask_user` turn goes last and is left pending on
+  // purpose (the thread stays "needs input").
+  const rich = await createReadyHostThread(harness, {
+    projectId: project.id,
+    title: "Rich thread",
+    workspace: { type: "unmanaged", path: null },
+  });
+  const richId = rich.thread.id;
+  await runTurn(harness, richId, "Hello rich thread, first message");
+  await runTurn(harness, richId, "delay:300 second message");
+  await runTurn(harness, richId, "call_tool:my_test_tool");
+  // Approval: the fake adapter blocks until the command approval resolves.
+  await sendTextMessage(harness.api, richId, {
+    text: "approve:command echo hi",
+  });
+  const approval = await waitForPendingInteraction(harness, richId);
+  await resolveThreadInteraction({
+    api: harness.api,
+    threadId: richId,
+    interactionId: approval.id,
+    resolution: { decision: "allow_once", grantedPermissions: null },
+  });
+  await waitForThreadStatus(harness.api, richId, "idle", TURN_TIMEOUT_MS);
+  await runTurn(harness, richId, LONG_MARKDOWN_MESSAGE);
+  // Left pending: the question row + "Needs input" state.
+  await sendTextMessage(harness.api, richId, { text: "ask_user" });
+  await waitForPendingInteraction(harness, richId);
+  // Sending through the API marks the thread read as the sender; the
+  // timeline flow expects to open this thread unread (divider at the top).
+  const unreadResponse = await harness.api.threads[":id"].unread.$post({
+    param: { id: richId },
+  });
+  if (unreadResponse.status !== 200) {
+    throw new Error(
+      `mark rich thread unread failed: ${unreadResponse.status} ${await unreadResponse.text()}`,
+    );
+  }
+
+  // Thread 4: started on behalf of the idle thread (a fork seed anchor), so
+  // the first row is the generated "Forked from Idle thread" conversation row
+  // rather than a user bubble; one follow-up turn keeps it idle.
+  const rowsThreadResponse = await harness.api.threads.$post({
+    json: {
+      environment: { type: "reuse", environmentId: completed.environment.id },
+      input: [
+        {
+          type: "text",
+          text: "Worker finished: all checks pass.\nThe summary is in the next message.",
+          mentions: [],
+        },
+      ],
+      origin: "app",
+      model: "fake-model",
+      parentThreadId: idle.thread.id,
+      projectId: project.id,
+      providerId: "fake",
+      title: "Rows thread",
+      startedOnBehalfOf: { initiator: "agent", senderThreadId: idle.thread.id },
+      originKind: "fork",
+    },
+  });
+  if (rowsThreadResponse.status !== 201) {
+    throw new Error(
+      `create rows thread failed: ${rowsThreadResponse.status} ${await rowsThreadResponse.text()}`,
+    );
+  }
+  const rowsThread = (await rowsThreadResponse.json()) as { id: string };
+  await waitForThreadStatus(
+    harness.api,
+    rowsThread.id,
+    "idle",
+    TURN_TIMEOUT_MS,
+  );
+  await runTurn(harness, rowsThread.id, "Thanks, proceed.");
+
+  const details = {
+    hostId: harness.hostId,
+    projectId: project.id,
+    serverUrl: harness.serverUrl,
+    threads: {
+      completed: completed.thread.id,
+      idle: idle.thread.id,
+      rich: richId,
+      rows: rowsThread.id,
+    },
+  };
+  process.stdout.write(`${JSON.stringify(details)}\n`);
+  process.stderr.write(
+    `mobile-e2e backend ready at ${harness.serverUrl} (Ctrl-C to stop)\n`,
+  );
+
+  // Keep the process alive.
+  await new Promise<never>(() => {});
+}
+
+main().catch((error) => {
+  process.stderr.write(`mobile-e2e backend failed: ${String(error)}\n`);
+  process.exit(1);
+});
diff --git a/tests/integration/mobile-e2e/connect-stub.ts b/tests/integration/mobile-e2e/connect-stub.ts
new file mode 100644
index 0000000000..8e144af5a0
--- /dev/null
+++ b/tests/integration/mobile-e2e/connect-stub.ts
@@ -0,0 +1,812 @@
+// Stub bb connect apex + gate for the mobile app's Maestro flows.
+//
+// The real topology is `https://getbb.app` (apex: redeems pairing codes) and
+// `https://<handle>.getbb.app` (gate: mints the desktop-session cookie, lists
+// the account's servers, and proxies everything else to the bb server behind
+// the tunnel only when a session cookie is present). This stub plays both on
+// one TLS port in front of the harness backend (`e2e:mobile-backend`):
+//
+//   apex   https://localhost:<port>           POST /api/connect/redeem-machine
+//   gate   https://<handle>.localhost:<port>  POST /api/connect/desktop-session
+//                                             GET  /api/connect/servers
+//                                             everything else → upstream bb
+//                                             (HTTP + WebSocket), 401 HTML
+//                                             sign-in page without a session
+//
+// TLS is required: iOS App Transport Security refuses plain http to a
+// qualified hostname and `@bb/connect-client` insists that the server lives
+// under the apex (`<label>.<apex-host>`), which rules out bare IPs. The stub
+// generates a local CA + leaf certificate with the `openssl` CLI under
+// `~/.bb-mobile-e2e/connect-stub-certs` (once) and prints the `xcrun simctl
+// keychain … add-root-cert` command that makes a simulator trust it; set
+// `BB_MOBILE_E2E_SIMULATOR=<udid|booted>` to run that command on start.
+// macOS and the iOS Simulator resolve `*.localhost` to loopback.
+//
+// Control endpoints (no auth, for flows; also served over plain HTTP on
+// 127.0.0.1:<control port> so curl / Maestro `runScript` need no CA):
+//   GET  /__stub/state            counters + live sessions/machines
+//   POST /__stub/expire-session   every session cookie stops working and live
+//                                 sockets are closed; the credential still
+//                                 mints new sessions (the app self-heals)
+//   POST /__stub/revoke-machine   credentials + sessions are revoked and
+//                                 sockets closed; re-minting fails with 401
+//                                 (the app shows "needs to be paired again")
+//   POST /__stub/reset            back to the initial state
+//
+// Pairing codes: `BB_MOBILE_E2E_CONNECT_CODE` (default STUB-PAIR) can be
+// redeemed any number of times (each redeem mints a fresh credential), so a
+// flow can re-pair after a revoke. Sentinel codes reproduce the apex's error
+// answers: EXPIRED-CODE (410), USED-CODE (409 already-used), LIMIT-CODE
+// (409 machine-limit); anything else is 404 invalid-code.
+//
+// Env: BB_MOBILE_E2E_GATE_PORT (42998), BB_MOBILE_E2E_STUB_CONTROL_PORT
+// (42997), BB_MOBILE_E2E_STUB_LOG=1 (one line per gate request), BB_MOBILE_E2E_UPSTREAM_URL
+// (http://127.0.0.1:${BB_MOBILE_E2E_PORT ?? 41999}), BB_MOBILE_E2E_STUB_HANDLE
+// (stub), BB_MOBILE_E2E_CONNECT_CODE (STUB-PAIR), BB_MOBILE_E2E_SESSION_TTL_MS
+// (3600000), BB_MOBILE_E2E_STUB_CERT_DIR, BB_MOBILE_E2E_SIMULATOR.
+//
+// Usage (from the repo root):
+//   pnpm --filter @bb/integration-tests e2e:mobile-backend
+//   pnpm --filter @bb/integration-tests e2e:mobile-connect-stub
+import { execFileSync } from "node:child_process";
+import { randomBytes, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import type { Duplex } from "node:stream";
+
+const DEFAULT_GATE_PORT = 42998;
+const DEFAULT_CONTROL_PORT = 42997;
+const DEFAULT_UPSTREAM_PORT = 41999;
+const DEFAULT_CODE = "STUB-PAIR";
+const DEFAULT_HANDLE = "stub";
+const OTHER_HANDLE = "other";
+const DEFAULT_SESSION_TTL_MS = 60 * 60 * 1000;
+// Same names as the real gate (apps/connect/src/cloud-dev.ts). `__Secure-`
+// requires the Secure flag, which the stub can honor because it speaks TLS.
+const DESKTOP_SESSION_COOKIE = "__Secure-bb-connect.desktop_session";
+const MACHINE_CREDENTIAL_HEADER = "x-bb-connect-machine";
+const GATE_AUTH_HEADER = "x-bb-gate-auth";
+const GATE_MACHINE_ID_HEADER = "x-bb-gate-machine-id";
+
+function readPort(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new Error(`Invalid ${name}: ${raw}`);
+  }
+  return parsed;
+}
+
+function readPositiveInt(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${name}: ${raw}`);
+  }
+  return parsed;
+}
+
+const gatePort = readPort("BB_MOBILE_E2E_GATE_PORT", DEFAULT_GATE_PORT);
+const controlPort = readPort(
+  "BB_MOBILE_E2E_STUB_CONTROL_PORT",
+  DEFAULT_CONTROL_PORT,
+);
+const upstreamUrl = new URL(
+  process.env.BB_MOBILE_E2E_UPSTREAM_URL ??
+    `http://127.0.0.1:${readPort("BB_MOBILE_E2E_PORT", DEFAULT_UPSTREAM_PORT)}`,
+);
+if (upstreamUrl.protocol !== "http:") {
+  throw new Error("BB_MOBILE_E2E_UPSTREAM_URL must be http://");
+}
+const upstreamHost = upstreamUrl.hostname;
+const upstreamPort = Number.parseInt(upstreamUrl.port, 10) || 80;
+const handle = (process.env.BB_MOBILE_E2E_STUB_HANDLE ?? DEFAULT_HANDLE)
+  .trim()
+  .toLowerCase();
+if (!/^[a-z0-9-]+$/u.test(handle)) {
+  throw new Error(`Invalid BB_MOBILE_E2E_STUB_HANDLE: ${handle}`);
+}
+const pairingCode = (process.env.BB_MOBILE_E2E_CONNECT_CODE ?? DEFAULT_CODE)
+  .trim()
+  .toUpperCase();
+const sessionTtlMs = readPositiveInt(
+  "BB_MOBILE_E2E_SESSION_TTL_MS",
+  DEFAULT_SESSION_TTL_MS,
+);
+const certDir =
+  process.env.BB_MOBILE_E2E_STUB_CERT_DIR ??
+  path.join(os.homedir(), ".bb-mobile-e2e", "connect-stub-certs");
+
+const apexUrl = `https://localhost:${gatePort}`;
+const serverUrl = `https://${handle}.localhost:${gatePort}`;
+const otherServerUrl = `https://${OTHER_HANDLE}.localhost:${gatePort}`;
+const cookieDomain = process.env.BB_MOBILE_E2E_COOKIE_DOMAIN ?? ".localhost";
+
+// ---------------------------------------------------------------------------
+// Certificates
+// ---------------------------------------------------------------------------
+
+interface TlsMaterial {
+  key: Buffer;
+  cert: Buffer;
+  caPath: string;
+}
+
+function ensureCertificates(): TlsMaterial {
+  mkdirSync(certDir, { recursive: true });
+  const caKey = path.join(certDir, "ca.key");
+  const caPem = path.join(certDir, "ca.pem");
+  const leafKey = path.join(certDir, "leaf.key");
+  const leafPem = path.join(certDir, "leaf.pem");
+  const sanFile = path.join(certDir, "leaf.san");
+  const sans = [
+    "DNS:localhost",
+    `DNS:${handle}.localhost`,
+    `DNS:${OTHER_HANDLE}.localhost`,
+    "DNS:*.localhost",
+    "IP:127.0.0.1",
+    "IP:::1",
+  ].join(",");
+
+  const openssl = (args: string[]): void => {
+    execFileSync("openssl", args, { stdio: ["ignore", "ignore", "pipe"] });
+  };
+
+  if (!existsSync(caKey) || !existsSync(caPem)) {
+    process.stderr.write(`connect-stub: generating CA in ${certDir}\n`);
+    openssl([
+      "req",
+      "-x509",
+      "-newkey",
+      "rsa:2048",
+      "-nodes",
+      "-keyout",
+      caKey,
+      "-out",
+      caPem,
+      "-days",
+      "3650",
+      "-subj",
+      "/CN=bb mobile e2e connect stub CA",
+      "-addext",
+      "basicConstraints=critical,CA:TRUE",
+      "-addext",
+      "keyUsage=critical,keyCertSign,cRLSign",
+    ]);
+  }
+  const sanStale =
+    !existsSync(sanFile) || readFileSync(sanFile, "utf8") !== sans;
+  if (!existsSync(leafKey) || !existsSync(leafPem) || sanStale) {
+    process.stderr.write(
+      `connect-stub: issuing leaf certificate for ${sans}\n`,
+    );
+    const csr = path.join(certDir, "leaf.csr");
+    const ext = path.join(certDir, "leaf.ext");
+    writeFileSync(
+      ext,
+      [
+        `subjectAltName=${sans}`,
+        "basicConstraints=CA:FALSE",
+        "keyUsage=digitalSignature,keyEncipherment",
+        "extendedKeyUsage=serverAuth",
+        "",
+      ].join("\n"),
+    );
+    openssl([
+      "req",
+      "-newkey",
+      "rsa:2048",
+      "-nodes",
+      "-keyout",
+      leafKey,
+      "-out",
+      csr,
+      "-subj",
+      "/CN=localhost",
+    ]);
+    openssl([
+      "x509",
+      "-req",
+      "-in",
+      csr,
+      "-CA",
+      caPem,
+      "-CAkey",
+      caKey,
+      "-CAcreateserial",
+      "-out",
+      leafPem,
+      "-days",
+      "825",
+      "-extfile",
+      ext,
+    ]);
+    writeFileSync(sanFile, sans);
+  }
+  return {
+    key: readFileSync(leafKey),
+    cert: readFileSync(leafPem),
+    caPath: caPem,
+  };
+}
+
+function installRootCertificate(simulator: string, caPath: string): void {
+  try {
+    execFileSync(
+      "xcrun",
+      ["simctl", "keychain", simulator, "add-root-cert", caPath],
+      { stdio: ["ignore", "ignore", "pipe"] },
+    );
+    process.stderr.write(
+      `connect-stub: root certificate installed in simulator ${simulator}\n`,
+    );
+  } catch (error) {
+    process.stderr.write(
+      `connect-stub: could not install the root certificate in ${simulator}: ${String(error)}\n`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+interface Machine {
+  id: string;
+  credential: string;
+  createdAt: number;
+  revokedAt: number | null;
+}
+
+interface Session {
+  value: string;
+  machineId: string;
+  expiresAt: number;
+  invalidatedAt: number | null;
+}
+
+const machines = new Map<string, Machine>(); // by credential
+const sessions = new Map<string, Session>(); // by cookie value
+const liveSockets = new Set<Duplex>();
+const counters = {
+  redeems: 0,
+  desktopSessions: 0,
+  listServers: 0,
+  proxiedRequests: 0,
+  proxiedUpgrades: 0,
+  unauthenticatedRequests: 0,
+  unauthenticatedUpgrades: 0,
+};
+
+function now(): number {
+  return Date.now();
+}
+
+const verbose = process.env.BB_MOBILE_E2E_STUB_LOG === "1";
+
+/** One line per request/upgrade when BB_MOBILE_E2E_STUB_LOG=1. */
+function trace(line: string): void {
+  if (verbose) process.stderr.write(`connect-stub: ${line}\n`);
+}
+
+function describeCookies(header: string | undefined): string {
+  if (!header) return "no cookie";
+  const names = header
+    .split(";")
+    .map((part) => part.trim().split("=")[0] ?? "")
+    .filter((name) => name.length > 0);
+  return `cookies ${names.join(",")}`;
+}
+
+function activeMachine(credential: string | null): Machine | null {
+  if (!credential) return null;
+  const machine = machines.get(credential);
+  return machine && machine.revokedAt === null ? machine : null;
+}
+
+function activeSession(value: string | null): Session | null {
+  if (!value) return null;
+  const session = sessions.get(value);
+  if (!session || session.invalidatedAt !== null) return null;
+  if (session.expiresAt <= now()) return null;
+  const machine = Array.from(machines.values()).find(
+    (candidate) => candidate.id === session.machineId,
+  );
+  return machine && machine.revokedAt === null ? session : null;
+}
+
+function closeLiveSockets(): number {
+  const count = liveSockets.size;
+  for (const socket of liveSockets) socket.destroy();
+  liveSockets.clear();
+  return count;
+}
+
+function expireSessions(): number {
+  let count = 0;
+  for (const session of sessions.values()) {
+    if (session.invalidatedAt === null) {
+      session.invalidatedAt = now();
+      count += 1;
+    }
+  }
+  return count;
+}
+
+function revokeMachines(): number {
+  let count = 0;
+  for (const machine of machines.values()) {
+    if (machine.revokedAt === null) {
+      machine.revokedAt = now();
+      count += 1;
+    }
+  }
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function parseCookie(header: string | undefined, name: string): string | null {
+  if (!header) return null;
+  for (const part of header.split(";")) {
+    const [rawName, ...rest] = part.trim().split("=");
+    if (rawName === name) return rest.join("=");
+  }
+  return null;
+}
+
+function json(res: http.ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(body));
+}
+
+function signInPage(label: string, url: string): string {
+  // Shape of apps/connect/src/worker.ts `signInPage`: HTML, regardless of
+  // Accept, linking to the account app.
+  return `<!doctype html><html><head><meta charset="utf-8"><title>Sign in · ${label}</title></head><body><h1>Sign in to bb connect</h1><p>You need a session to reach <code>${label}</code>.</p><p><a href="${apexUrl}/dashboard?returnTo=${encodeURIComponent(url)}">Sign in</a></p></body></html>`;
+}
+
+function readBody(req: http.IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+function isMachinePath(pathname: string): boolean {
+  return (
+    pathname.startsWith("/internal") ||
+    pathname === "/api/v1" ||
+    pathname.startsWith("/api/v1/")
+  );
+}
+
+function headerValue(value: string | string[] | undefined): string | null {
+  if (Array.isArray(value)) return value[0] ?? null;
+  return value ?? null;
+}
+
+/**
+ * Headers forwarded upstream: visitor-supplied gate headers are stripped, and
+ * like the tunnel client (`@bb/tunnel-client` `headersForLoopbackRequest`)
+ * an `Origin` equal to the public gate origin is rewritten to the loopback
+ * origin so the bb server's browser-origin guard accepts the request (React
+ * Native's WebSocket sends `Origin: https://<gate host>`).
+ */
+function upstreamHeaders(
+  req: http.IncomingMessage,
+  auth: "session" | "machine",
+  machineId: string | null,
+): http.OutgoingHttpHeaders {
+  const headers: http.OutgoingHttpHeaders = {};
+  const publicOrigin = `https://${headerValue(req.headers.host) ?? ""}`;
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    const lower = name.toLowerCase();
+    if (
+      lower === "host" ||
+      lower === MACHINE_CREDENTIAL_HEADER ||
+      lower === GATE_AUTH_HEADER ||
+      lower === GATE_MACHINE_ID_HEADER
+    ) {
+      continue;
+    }
+    headers[name] =
+      lower === "origin" && value === publicOrigin ? upstreamUrl.origin : value;
+  }
+  headers.host = `${upstreamHost}:${upstreamPort}`;
+  headers[GATE_AUTH_HEADER] = auth;
+  if (machineId) headers[GATE_MACHINE_ID_HEADER] = machineId;
+  return headers;
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+async function handleRedeemMachine(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+): Promise<void> {
+  if (req.method !== "POST")
+    return json(res, 405, { error: "method_not_allowed" });
+  let code = "";
+  try {
+    const body: unknown = JSON.parse((await readBody(req)) || "{}");
+    if (typeof body === "object" && body !== null && "code" in body) {
+      const raw = (body as { code?: unknown }).code;
+      code = typeof raw === "string" ? raw.trim().toUpperCase() : "";
+    }
+  } catch {
+    return json(res, 400, { error: "invalid-json" });
+  }
+  counters.redeems += 1;
+  if (!code) return json(res, 400, { error: "missing-code" });
+  if (code === "EXPIRED-CODE") return json(res, 410, { error: "expired" });
+  if (code === "USED-CODE") return json(res, 409, { error: "already-used" });
+  if (code === "LIMIT-CODE") return json(res, 409, { error: "machine-limit" });
+  if (code !== pairingCode) return json(res, 404, { error: "invalid-code" });
+  const machine: Machine = {
+    id: randomUUID(),
+    credential: `bbcm_${randomBytes(24).toString("base64url")}`,
+    createdAt: now(),
+    revokedAt: null,
+  };
+  machines.set(machine.credential, machine);
+  process.stderr.write(
+    `connect-stub: redeemed ${code} → machine ${machine.id}\n`,
+  );
+  // Same shape as the apex (`handle` is the account's primary handle).
+  return json(res, 200, {
+    credential: machine.credential,
+    machineId: machine.id,
+    handle,
+    serverUrl,
+  });
+}
+
+function handleDesktopSession(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+): void {
+  if (req.method !== "POST")
+    return json(res, 405, { error: "method_not_allowed" });
+  counters.desktopSessions += 1;
+  const machine = activeMachine(
+    headerValue(req.headers[MACHINE_CREDENTIAL_HEADER]),
+  );
+  if (!machine) return json(res, 401, { error: "unauthorized" });
+  const session: Session = {
+    value: `${randomBytes(18).toString("base64url")}.${randomBytes(16).toString("base64url")}`,
+    machineId: machine.id,
+    expiresAt: now() + sessionTtlMs,
+    invalidatedAt: null,
+  };
+  sessions.set(session.value, session);
+  process.stderr.write(
+    `connect-stub: desktop session minted for machine ${machine.id} (expires in ${sessionTtlMs}ms)\n`,
+  );
+  return json(res, 200, {
+    cookie: {
+      domain: cookieDomain,
+      expiresAt: session.expiresAt,
+      name: DESKTOP_SESSION_COOKIE,
+      value: session.value,
+    },
+  });
+}
+
+function handleListServers(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+): void {
+  if (req.method !== "GET")
+    return json(res, 405, { error: "method_not_allowed" });
+  counters.listServers += 1;
+  const machine = activeMachine(
+    headerValue(req.headers[MACHINE_CREDENTIAL_HEADER]),
+  );
+  if (!machine) return json(res, 401, { error: "unauthorized" });
+  return json(res, 200, {
+    servers: [
+      { handle, name: "Stub server", live: true },
+      { handle: OTHER_HANDLE, name: "Other stub server", live: false },
+    ],
+  });
+}
+
+function handleControl(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+): void {
+  if (pathname === "/__stub/state" && req.method === "GET") {
+    return json(res, 200, {
+      apexUrl,
+      serverUrl,
+      otherServerUrl,
+      upstreamUrl: upstreamUrl.origin,
+      pairingCode,
+      machines: Array.from(machines.values()).map((machine) => ({
+        id: machine.id,
+        createdAt: machine.createdAt,
+        revokedAt: machine.revokedAt,
+      })),
+      sessions: Array.from(sessions.values()).map((session) => ({
+        machineId: session.machineId,
+        expiresAt: session.expiresAt,
+        invalidatedAt: session.invalidatedAt,
+      })),
+      liveSockets: liveSockets.size,
+      counters,
+    });
+  }
+  if (req.method !== "POST")
+    return json(res, 405, { error: "method_not_allowed" });
+  if (pathname === "/__stub/expire-session") {
+    const expired = expireSessions();
+    const closed = closeLiveSockets();
+    process.stderr.write(
+      `connect-stub: expired ${expired} session(s), closed ${closed} socket(s)\n`,
+    );
+    return json(res, 200, { ok: true, expired, closed });
+  }
+  if (pathname === "/__stub/revoke-machine") {
+    const revoked = revokeMachines();
+    const expired = expireSessions();
+    const closed = closeLiveSockets();
+    process.stderr.write(
+      `connect-stub: revoked ${revoked} machine(s), expired ${expired} session(s), closed ${closed} socket(s)\n`,
+    );
+    return json(res, 200, { ok: true, revoked, expired, closed });
+  }
+  if (pathname === "/__stub/reset") {
+    const closed = closeLiveSockets();
+    machines.clear();
+    sessions.clear();
+    process.stderr.write(`connect-stub: reset (closed ${closed} socket(s))\n`);
+    return json(res, 200, { ok: true, closed });
+  }
+  return json(res, 404, { error: "not_found" });
+}
+
+function proxyRequest(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  auth: "session" | "machine",
+  machineId: string | null,
+): void {
+  counters.proxiedRequests += 1;
+  const upstream = http.request(
+    {
+      host: upstreamHost,
+      port: upstreamPort,
+      method: req.method,
+      path: req.url,
+      headers: upstreamHeaders(req, auth, machineId),
+    },
+    (upstreamRes) => {
+      res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+      upstreamRes.pipe(res);
+    },
+  );
+  upstream.on("error", (error) => {
+    process.stderr.write(`connect-stub: upstream error ${String(error)}\n`);
+    if (!res.headersSent) {
+      res.writeHead(503, { "content-type": "text/plain" });
+    }
+    res.end("bb connect: server offline\n");
+  });
+  req.pipe(upstream);
+}
+
+async function handleRequest(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+): Promise<void> {
+  const url = new URL(
+    req.url ?? "/",
+    `https://${req.headers.host ?? "localhost"}`,
+  );
+  const pathname = url.pathname;
+  if (pathname === "/api/connect/redeem-machine") {
+    return handleRedeemMachine(req, res);
+  }
+  if (pathname === "/api/connect/desktop-session") {
+    return handleDesktopSession(req, res);
+  }
+  if (pathname === "/api/connect/servers") return handleListServers(req, res);
+  if (pathname.startsWith("/__stub/")) return handleControl(req, res, pathname);
+  if (pathname.startsWith("/__")) {
+    res.writeHead(404, { "content-type": "text/plain" });
+    return void res.end("bb connect: not found\n");
+  }
+
+  // Daemon / machine CLI traffic: the machine credential on /api/v1*.
+  const presented = headerValue(req.headers[MACHINE_CREDENTIAL_HEADER]);
+  if (isMachinePath(pathname) && presented !== null) {
+    const machine = activeMachine(presented);
+    if (!machine) {
+      res.writeHead(403, { "content-type": "text/plain" });
+      return void res.end("bb connect: machine not authorized\n");
+    }
+    return proxyRequest(req, res, "machine", machine.id);
+  }
+  if (pathname.startsWith("/internal")) {
+    res.writeHead(403, { "content-type": "text/plain" });
+    return void res.end("bb connect: machine not authorized\n");
+  }
+
+  // Visitor request: session cookie or the HTML sign-in page.
+  const cookieHeader = headerValue(req.headers.cookie) ?? undefined;
+  const session = activeSession(
+    parseCookie(cookieHeader, DESKTOP_SESSION_COOKIE),
+  );
+  trace(
+    `${req.method ?? "GET"} ${url.host}${pathname} (${describeCookies(cookieHeader)}) → ${session ? "proxy" : "401 sign-in"}`,
+  );
+  if (!session) {
+    counters.unauthenticatedRequests += 1;
+    res.writeHead(401, { "content-type": "text/html; charset=utf-8" });
+    return void res.end(signInPage(url.host, url.toString()));
+  }
+  return proxyRequest(req, res, "session", null);
+}
+
+function handleUpgrade(
+  req: http.IncomingMessage,
+  socket: Duplex,
+  head: Buffer,
+): void {
+  const url = new URL(
+    req.url ?? "/",
+    `https://${req.headers.host ?? "localhost"}`,
+  );
+  const cookieHeader = headerValue(req.headers.cookie) ?? undefined;
+  const session = activeSession(
+    parseCookie(cookieHeader, DESKTOP_SESSION_COOKIE),
+  );
+  trace(
+    `UPGRADE ${url.host}${url.pathname} (${describeCookies(cookieHeader)}) → ${session ? "proxy" : "401 sign-in"}`,
+  );
+  if (!session) {
+    counters.unauthenticatedUpgrades += 1;
+    const body = signInPage(url.host, url.toString());
+    // Flush the full response before the FIN: SocketRocket must read the
+    // status line ("Received bad response code from server: 401.") rather
+    // than see a reset, which would look like a plain network failure.
+    socket.end(
+      [
+        "HTTP/1.1 401 Unauthorized",
+        "content-type: text/html; charset=utf-8",
+        `content-length: ${Buffer.byteLength(body)}`,
+        "connection: close",
+        "",
+        body,
+      ].join("\r\n"),
+    );
+    return;
+  }
+  counters.proxiedUpgrades += 1;
+  const upstream = net.connect(upstreamPort, upstreamHost, () => {
+    const headers = upstreamHeaders(req, "session", null);
+    const lines = [`${req.method ?? "GET"} ${req.url ?? "/"} HTTP/1.1`];
+    for (const [name, value] of Object.entries(headers)) {
+      if (value === undefined) continue;
+      for (const entry of Array.isArray(value) ? value : [String(value)]) {
+        lines.push(`${name}: ${entry}`);
+      }
+    }
+    upstream.write(`${lines.join("\r\n")}\r\n\r\n`);
+    if (head.length > 0) upstream.write(head);
+    upstream.once("data", (chunk: Buffer) => {
+      trace(
+        `UPGRADE ${url.pathname} upstream answered: ${chunk.toString("latin1").split("\r\n", 1)[0] ?? ""}`,
+      );
+    });
+    upstream.pipe(socket);
+    socket.pipe(upstream);
+  });
+  liveSockets.add(socket);
+  const cleanup = (): void => {
+    liveSockets.delete(socket);
+    upstream.destroy();
+    socket.destroy();
+  };
+  upstream.on("error", cleanup);
+  upstream.on("close", cleanup);
+  socket.on("error", cleanup);
+  socket.on("close", cleanup);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main(): void {
+  const tls = ensureCertificates();
+  const simulator = process.env.BB_MOBILE_E2E_SIMULATOR;
+  if (simulator) installRootCertificate(simulator, tls.caPath);
+
+  const listeners: https.Server[] = [];
+  // Bind v4 and v6 loopback explicitly: iOS may pick either for `*.localhost`.
+  for (const host of ["127.0.0.1", "::1"]) {
+    const server = https.createServer(
+      { key: tls.key, cert: tls.cert },
+      (req, res) => {
+        handleRequest(req, res).catch((error: unknown) => {
+          process.stderr.write(
+            `connect-stub: handler error ${String(error)}\n`,
+          );
+          if (!res.headersSent) json(res, 500, { error: "internal" });
+          else res.end();
+        });
+      },
+    );
+    server.on("upgrade", handleUpgrade);
+    server.on("error", (error) => {
+      process.stderr.write(
+        `connect-stub: listen error on ${host}: ${String(error)}\n`,
+      );
+      process.exit(1);
+    });
+    server.listen(gatePort, host);
+    listeners.push(server);
+  }
+
+  // Plain-HTTP control listener so flows (Maestro `runScript`, curl) can
+  // drive the stub without trusting its certificate. Only `/__stub/*`.
+  const control = http.createServer((req, res) => {
+    const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    if (pathname.startsWith("/__stub/"))
+      return handleControl(req, res, pathname);
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end("bb connect stub: control port only answers /__stub/*\n");
+  });
+  control.on("error", (error) => {
+    process.stderr.write(
+      `connect-stub: control listen error on ${controlPort}: ${String(error)}\n`,
+    );
+    process.exit(1);
+  });
+  control.listen(controlPort, "127.0.0.1");
+
+  const shutdown = (signal: string): void => {
+    process.stderr.write(`connect-stub: ${signal}, shutting down\n`);
+    closeLiveSockets();
+    for (const server of listeners) server.close();
+    control.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+  const details = {
+    apexUrl,
+    serverUrl,
+    otherServerUrl,
+    handle,
+    pairingCode,
+    upstreamUrl: upstreamUrl.origin,
+    controlUrl: `http://127.0.0.1:${controlPort}`,
+    caPath: tls.caPath,
+    installRootCert: `xcrun simctl keychain booted add-root-cert ${tls.caPath}`,
+  };
+  process.stdout.write(`${JSON.stringify(details)}\n`);
+  process.stderr.write(
+    `mobile-e2e connect stub ready: apex ${apexUrl}, gate ${serverUrl} → ${upstreamUrl.origin} (code ${pairingCode}; control http://127.0.0.1:${controlPort}/__stub/*; Ctrl-C to stop)\n` +
+      `  trust the CA in a simulator once: ${details.installRootCert}\n`,
+  );
+}
+
+main();
diff --git a/tests/integration/package.json b/tests/integration/package.json
index d6655a1c69..029c58109b 100644
--- a/tests/integration/package.json
+++ b/tests/integration/package.json
@@ -7,7 +7,9 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --config vitest.config.ts",
     "test:smoke": "vitest run --config vitest.config.ts fake/smoke",
-    "test:integration": "vitest run --config vitest.real-provider.config.ts"
+    "test:integration": "vitest run --config vitest.real-provider.config.ts",
+    "e2e:mobile-backend": "cross-env NODE_ENV=test node --conditions=source --import tsx mobile-e2e/backend.ts",
+    "e2e:mobile-connect-stub": "node --import tsx mobile-e2e/connect-stub.ts"
   },
   "dependencies": {
     "@bb/agent-runtime": "workspace:*",
diff --git a/turbo.json b/turbo.json
index cd06fd2632..20d9039ca2 100644
--- a/turbo.json
+++ b/turbo.json
@@ -573,6 +573,25 @@
         "$TURBO_ROOT$/vitest.shared.ts"
       ]
     },
+    "@bb/integration-tests#e2e:mobile-backend": {
+      "cache": false,
+      "persistent": true,
+      "passThroughEnv": [
+        "*"
+      ],
+      "dependsOn": [
+        "//#ensure-native-modules",
+        "@get-bb/plugin-sdk#build",
+        "topo"
+      ]
+    },
+    "@bb/integration-tests#e2e:mobile-connect-stub": {
+      "cache": false,
+      "persistent": true,
+      "passThroughEnv": [
+        "*"
+      ]
+    },
     "@bb/integration-tests#test:smoke": {
       "dependsOn": [
         "//#ensure-native-modules",

From 850d3dbd246f4cdc54975fd0468cff024fc2f05a Mon Sep 17 00:00:00 2001
From: Sawyer Hood <sawyerjhood@gmail.com>
Date: Wed, 19 Aug 2026 18:26:25 -0700
Subject: [PATCH 2/4] Gate mobile pairing behind the mobileApp experiment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bb mobile app is not generally available yet, but the connect panel
rendered "Add mobile device" for every paired install and `bb connect
machine-code` was live. Add a `mobileApp` experiment (off by default) in
@bb/domain with a toggle in Settings → Experiments, and have the connect
plugin read it through its loopback SDK binding (`bb.sdk.system.config()`)
on every call — no new plugin API:

- new `mobilePairing` rpc tells the panel whether to render the section
- `createMachineCode` rpc and `bb connect machine-code` refuse with a
  pointer to the toggle (`bb settings experiment mobileApp true`)
- docs, the bb-cli skill, and the guide template mention the experiment

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../AppLayout.plugin-panel-header.test.tsx    |  1 +
 .../AppLayout.root-compose-project.test.tsx   |  1 +
 apps/app/src/lib/system-config-atoms.ts       |  1 +
 .../views/SettingsView.experiments.test.tsx   | 10 ++++
 apps/app/src/views/SettingsView.stories.tsx   |  7 +++
 apps/app/src/views/SettingsView.tsx           | 24 ++++++++
 apps/desktop/scripts/smoke-packaged-app.mjs   |  1 +
 apps/desktop/test/preload-build.test.ts       |  1 +
 .../skills/builtin-skills/bb-cli/SKILL.md     |  3 +-
 .../bb-cli/references/app-settings.md         |  8 +++
 apps/server/test/system/experiments.test.ts   | 11 +++-
 .../threads/thread-runtime-config.test.ts     |  1 +
 docs/configuration.md                         | 15 ++++-
 docs/multiple-devices.md                      |  7 ++-
 packages/db/test/experiments.test.ts          |  1 +
 packages/domain/src/experiments.ts            |  2 +
 .../src/templates/bb-guide-environments.md    |  7 ++-
 plugins/connect/app.test.tsx                  | 30 ++++++++++
 plugins/connect/app.tsx                       | 55 ++++++++++++++++++-
 plugins/connect/src/cli.ts                    | 19 ++++++-
 plugins/connect/src/connect.test.ts           | 25 ++++++++-
 plugins/connect/src/rpc.ts                    | 27 +++++++++
 plugins/connect/src/server.ts                 | 19 ++++++-
 23 files changed, 255 insertions(+), 21 deletions(-)

diff --git a/apps/app/src/components/layout/AppLayout.plugin-panel-header.test.tsx b/apps/app/src/components/layout/AppLayout.plugin-panel-header.test.tsx
index a20dbbf4a2..2653357c53 100644
--- a/apps/app/src/components/layout/AppLayout.plugin-panel-header.test.tsx
+++ b/apps/app/src/components/layout/AppLayout.plugin-panel-header.test.tsx
@@ -29,6 +29,7 @@ vi.mock("@/hooks/queries/system-queries", () => ({
       experiments: {
         claudeCodeMockCliTraffic: false,
         editMessages: false,
+        mobileApp: false,
         newOnboarding: false,
         providerSessionReaping: false,
       },
diff --git a/apps/app/src/components/layout/AppLayout.root-compose-project.test.tsx b/apps/app/src/components/layout/AppLayout.root-compose-project.test.tsx
index 7ce87d84dc..1cf4144a9f 100644
--- a/apps/app/src/components/layout/AppLayout.root-compose-project.test.tsx
+++ b/apps/app/src/components/layout/AppLayout.root-compose-project.test.tsx
@@ -34,6 +34,7 @@ vi.mock("@/hooks/queries/system-queries", () => ({
       experiments: {
         claudeCodeMockCliTraffic: false,
         editMessages: false,
+        mobileApp: false,
         newOnboarding: false,
         providerSessionReaping: false,
       },
diff --git a/apps/app/src/lib/system-config-atoms.ts b/apps/app/src/lib/system-config-atoms.ts
index 6ac9577d64..ddb09b3c26 100644
--- a/apps/app/src/lib/system-config-atoms.ts
+++ b/apps/app/src/lib/system-config-atoms.ts
@@ -23,6 +23,7 @@ const unavailableSystemConfig: SystemConfigResponse = {
   experiments: {
     claudeCodeMockCliTraffic: false,
     editMessages: false,
+    mobileApp: false,
     newOnboarding: false,
     providerSessionReaping: false,
   },
diff --git a/apps/app/src/views/SettingsView.experiments.test.tsx b/apps/app/src/views/SettingsView.experiments.test.tsx
index c1443fabaa..fa62487062 100644
--- a/apps/app/src/views/SettingsView.experiments.test.tsx
+++ b/apps/app/src/views/SettingsView.experiments.test.tsx
@@ -6,6 +6,7 @@ import { ExperimentsSettingsSection } from "./SettingsView";
 afterEach(cleanup);
 
 function renderSection(overrides?: {
+  onMobileAppEnabledChange?: (enabled: boolean) => void;
   onNewOnboardingEnabledChange?: (enabled: boolean) => void;
   onProviderSessionReapingEnabledChange?: (enabled: boolean) => void;
 }) {
@@ -14,10 +15,12 @@ function renderSection(overrides?: {
       claudeCodeMockCliTrafficEnabled={false}
       disabled={false}
       editMessagesEnabled={false}
+      mobileAppEnabled={false}
       newOnboardingEnabled={false}
       providerSessionReapingEnabled={false}
       onClaudeCodeMockCliTrafficEnabledChange={vi.fn()}
       onEditMessagesEnabledChange={vi.fn()}
+      onMobileAppEnabledChange={overrides?.onMobileAppEnabledChange ?? vi.fn()}
       onNewOnboardingEnabledChange={
         overrides?.onNewOnboardingEnabledChange ?? vi.fn()
       }
@@ -36,6 +39,13 @@ describe("ExperimentsSettingsSection", () => {
     expect(onChange).toHaveBeenCalledWith(true);
   });
 
+  it("reports mobile app changes", () => {
+    const onChange = vi.fn();
+    renderSection({ onMobileAppEnabledChange: onChange });
+    fireEvent.click(screen.getByLabelText("Mobile app"));
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+
   it("reports idle provider session release changes", () => {
     const onChange = vi.fn();
     renderSection({ onProviderSessionReapingEnabledChange: onChange });
diff --git a/apps/app/src/views/SettingsView.stories.tsx b/apps/app/src/views/SettingsView.stories.tsx
index 8220393503..050cf6ef1d 100644
--- a/apps/app/src/views/SettingsView.stories.tsx
+++ b/apps/app/src/views/SettingsView.stories.tsx
@@ -335,6 +335,7 @@ function ExperimentsStory() {
       }
       disabled={false}
       editMessagesEnabled={state.experiments.editMessages}
+      mobileAppEnabled={state.experiments.mobileApp}
       newOnboardingEnabled={state.experiments.newOnboarding}
       providerSessionReapingEnabled={state.experiments.providerSessionReaping}
       onClaudeCodeMockCliTrafficEnabledChange={(enabled) =>
@@ -349,6 +350,12 @@ function ExperimentsStory() {
           editMessages: enabled,
         }))
       }
+      onMobileAppEnabledChange={(enabled) =>
+        state.setExperiments((current) => ({
+          ...current,
+          mobileApp: enabled,
+        }))
+      }
       onNewOnboardingEnabledChange={(enabled) =>
         state.setExperiments((current) => ({
           ...current,
diff --git a/apps/app/src/views/SettingsView.tsx b/apps/app/src/views/SettingsView.tsx
index fb85521079..06c14b741f 100644
--- a/apps/app/src/views/SettingsView.tsx
+++ b/apps/app/src/views/SettingsView.tsx
@@ -212,10 +212,12 @@ export interface ExperimentsSettingsSectionProps {
   disabled: boolean;
   claudeCodeMockCliTrafficEnabled: boolean;
   editMessagesEnabled: boolean;
+  mobileAppEnabled: boolean;
   newOnboardingEnabled: boolean;
   providerSessionReapingEnabled: boolean;
   onClaudeCodeMockCliTrafficEnabledChange: (enabled: boolean) => void;
   onEditMessagesEnabledChange: (enabled: boolean) => void;
+  onMobileAppEnabledChange: (enabled: boolean) => void;
   onNewOnboardingEnabledChange: (enabled: boolean) => void;
   onProviderSessionReapingEnabledChange: (enabled: boolean) => void;
 }
@@ -996,6 +998,7 @@ export function ProviderSettingsSection({
 
 const CLAUDE_CODE_MOCK_CLI_TRAFFIC_EXPERIMENT_LABEL = "Mock CLI Traffic";
 const EDIT_MESSAGES_EXPERIMENT_LABEL = "Edit messages";
+const MOBILE_APP_EXPERIMENT_LABEL = "Mobile app";
 const NEW_ONBOARDING_EXPERIMENT_LABEL = "New onboarding";
 const PROVIDER_SESSION_REAPING_EXPERIMENT_LABEL =
   "Idle provider session release";
@@ -1003,10 +1006,12 @@ export function ExperimentsSettingsSection({
   claudeCodeMockCliTrafficEnabled,
   disabled,
   editMessagesEnabled,
+  mobileAppEnabled,
   newOnboardingEnabled,
   providerSessionReapingEnabled,
   onClaudeCodeMockCliTrafficEnabledChange,
   onEditMessagesEnabledChange,
+  onMobileAppEnabledChange,
   onNewOnboardingEnabledChange,
   onProviderSessionReapingEnabledChange,
 }: ExperimentsSettingsSectionProps) {
@@ -1041,6 +1046,18 @@ export function ExperimentsSettingsSection({
           />
         </SettingsWithControl>
 
+        <SettingsWithControl
+          label={MOBILE_APP_EXPERIMENT_LABEL}
+          description="Pair the bb mobile app over bb connect: shows Add mobile device under Remote access and enables bb connect machine-code."
+        >
+          <Switch
+            checked={mobileAppEnabled}
+            disabled={disabled}
+            onCheckedChange={onMobileAppEnabledChange}
+            aria-label={MOBILE_APP_EXPERIMENT_LABEL}
+          />
+        </SettingsWithControl>
+
         <SettingsWithControl
           label={NEW_ONBOARDING_EXPERIMENT_LABEL}
           description="Enable the new first-run guide for agent setup and project selection."
@@ -1232,6 +1249,13 @@ export function SettingsView() {
             editMessages: enabled,
           })
         }
+        mobileAppEnabled={experiments.mobileApp}
+        onMobileAppEnabledChange={(enabled) =>
+          updateExperimentsMutation.mutate({
+            ...experiments,
+            mobileApp: enabled,
+          })
+        }
         newOnboardingEnabled={experiments.newOnboarding}
         onNewOnboardingEnabledChange={(enabled) =>
           updateExperimentsMutation.mutate({
diff --git a/apps/desktop/scripts/smoke-packaged-app.mjs b/apps/desktop/scripts/smoke-packaged-app.mjs
index 2026275c83..7fcb982f82 100644
--- a/apps/desktop/scripts/smoke-packaged-app.mjs
+++ b/apps/desktop/scripts/smoke-packaged-app.mjs
@@ -145,6 +145,7 @@ async function startSmokeServer({
         dataDir,
         experiments: {
           claudeCodeMockCliTraffic: false,
+          mobileApp: false,
           newOnboarding: false,
           providerSessionReaping: false,
         },
diff --git a/apps/desktop/test/preload-build.test.ts b/apps/desktop/test/preload-build.test.ts
index 1b00d5a924..9c0c1dda18 100644
--- a/apps/desktop/test/preload-build.test.ts
+++ b/apps/desktop/test/preload-build.test.ts
@@ -129,6 +129,7 @@ async function startDesktopSmokeServer(
           experiments: {
             claudeCodeMockCliTraffic: false,
             editMessages: false,
+            mobileApp: false,
             newOnboarding: false,
             providerSessionReaping: false,
           },
diff --git a/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md b/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
index 57ebfd2668..5585174706 100644
--- a/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
+++ b/apps/server/src/services/skills/builtin-skills/bb-cli/SKILL.md
@@ -225,7 +225,8 @@ isolated|reuse`, or anchor with `--source-seq-end`. Permission mode inherits
   `selfHandle` for deduping this server. When you start a local server the user
   should open remotely, expose the port and give them the share URL.
   `bb connect machine-code` mints a one-time code (10 minutes, single use)
-  that pairs the bb mobile app with this bb: it prints the code, server URL,
+  that pairs the bb mobile app with this bb (it needs the `mobileApp`
+  experiment: `bb settings experiment mobileApp true`): it prints the code, server URL,
   connect apex, and expiry; `--json` returns `{code, serverUrl, apex,
   expiresAt}`. The phone enrolls as a connect machine with its own revocable
   credential (visible in the getbb.app dashboard). Settings → Remote access →
diff --git a/apps/server/src/services/skills/builtin-skills/bb-cli/references/app-settings.md b/apps/server/src/services/skills/builtin-skills/bb-cli/references/app-settings.md
index ab8221397d..4b168a311e 100644
--- a/apps/server/src/services/skills/builtin-skills/bb-cli/references/app-settings.md
+++ b/apps/server/src/services/skills/builtin-skills/bb-cli/references/app-settings.md
@@ -57,3 +57,11 @@ every window and client sees the same value.
 - Enable it with `bb settings experiment newOnboarding true`.
 - Use `bb settings replay-onboarding` to enable the experiment and show the
   agent and project setup guide again.
+
+## Mobile app
+
+- The `mobileApp` experiment defaults to false while the bb mobile app is in
+  early access.
+- Enable it with `bb settings experiment mobileApp true`. It shows the
+  **Add mobile device** card under Settings → Remote access and enables
+  `bb connect machine-code`.
diff --git a/apps/server/test/system/experiments.test.ts b/apps/server/test/system/experiments.test.ts
index 58004771a0..5d9e139f83 100644
--- a/apps/server/test/system/experiments.test.ts
+++ b/apps/server/test/system/experiments.test.ts
@@ -16,6 +16,7 @@ describe("experiments settings", () => {
       expect(body.experiments).toEqual({
         claudeCodeMockCliTraffic: false,
         editMessages: true,
+        mobileApp: false,
         newOnboarding: false,
         providerSessionReaping: false,
       });
@@ -30,20 +31,23 @@ describe("experiments settings", () => {
         body: JSON.stringify({
           claudeCodeMockCliTraffic: true,
           editMessages: true,
+          mobileApp: true,
           newOnboarding: true,
-            providerSessionReaping: true,
+          providerSessionReaping: true,
         }),
       });
       expect(put.status).toBe(200);
       expect(experimentsSchema.parse(await readJson(put))).toEqual({
         claudeCodeMockCliTraffic: true,
         editMessages: true,
+        mobileApp: true,
         newOnboarding: true,
         providerSessionReaping: true,
       });
       expect(getExperiments(harness.db)).toEqual({
         claudeCodeMockCliTraffic: true,
         editMessages: true,
+        mobileApp: true,
         newOnboarding: true,
         providerSessionReaping: true,
       });
@@ -54,6 +58,7 @@ describe("experiments settings", () => {
       ).toEqual({
         claudeCodeMockCliTraffic: true,
         editMessages: true,
+        mobileApp: true,
         newOnboarding: true,
         providerSessionReaping: true,
       });
@@ -80,8 +85,9 @@ describe("experiments settings", () => {
         body: JSON.stringify({
           claudeCodeMockCliTraffic: false,
           editMessages: true,
+          mobileApp: false,
           newOnboarding: false,
-            providerSessionReaping: true,
+          providerSessionReaping: true,
         }),
       });
       const updated = await harness.app.request("/internal/runtime-policy", {
@@ -104,6 +110,7 @@ describe("experiments settings", () => {
         body: JSON.stringify({
           claudeCodeMockCliTraffic: false,
           editMessages: false,
+          mobileApp: false,
           newOnboarding: false,
           providerSessionReaping: false,
         }),
diff --git a/apps/server/test/threads/thread-runtime-config.test.ts b/apps/server/test/threads/thread-runtime-config.test.ts
index 5336d6aad7..1f7d6764f1 100644
--- a/apps/server/test/threads/thread-runtime-config.test.ts
+++ b/apps/server/test/threads/thread-runtime-config.test.ts
@@ -863,6 +863,7 @@ describe("thread runtime config", () => {
       setExperiments(harness.db, {
         claudeCodeMockCliTraffic: true,
         editMessages: false,
+        mobileApp: false,
         newOnboarding: false,
         providerSessionReaping: false,
       });
diff --git a/docs/configuration.md b/docs/configuration.md
index c611d5786d..0754ea4f77 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -610,7 +610,11 @@ ports).
 The bb mobile app reaches a paired bb through the same connect route. It
 enrolls as a connect **machine** — its own credential on the getbb.app account,
 separate from the server's pairing secret and individually revocable — so
-pairing starts from the bb, not from the phone:
+pairing starts from the bb, not from the phone. Both pairing surfaces sit
+behind the `mobileApp` experiment (Settings → Experiments → **Mobile app**, or
+`bb settings experiment mobileApp true`) until the app is generally available;
+the connect plugin reads the experiment from `/system/config` on every call,
+so a toggle applies without a plugin reload:
 
 - Settings → Remote access → **Add mobile device** mints a one-time code and
   shows it as a QR code plus copyable text with a countdown.
@@ -623,7 +627,9 @@ once. The phone then appears in the getbb.app dashboard machine list, where you
 can revoke it; every enrollment takes one of the account's machine slots
 (desktop apps, remote execution machines, and phones all count), so a
 machine-limit error asks you to revoke an unused device first. Both surfaces
-need the bb to be paired (`bb connect --code …`) and the connect plugin enabled.
+need the experiment on, the bb paired (`bb connect --code …`), and the connect
+plugin enabled; with the experiment off the panel hides the section and
+`bb connect machine-code` exits 1 with a pointer to the toggle.
 
 ## Experiments
 
@@ -639,6 +645,11 @@ history; if the thread is running, submission stops the current turn and waits
 for it to settle before atomically replacing that message and every later turn
 while keeping workspace changes.
 
+The `mobileApp` experiment turns on pairing for the bb mobile app: the
+**Add mobile device** card under Settings → Remote access and the
+`bb connect machine-code` command (see "Pairing the bb mobile app" above). It
+is off by default while the app is in early access.
+
 The `providerSessionReaping` experiment extends idle session release to every
 restorable provider. BB releases those sessions after 30 idle minutes. The
 daemon reads the setting before each five-minute maintenance pass. Active
diff --git a/docs/multiple-devices.md b/docs/multiple-devices.md
index b36e1af8c0..1dd48f977a 100644
--- a/docs/multiple-devices.md
+++ b/docs/multiple-devices.md
@@ -84,11 +84,14 @@ and can revoke.
 
 1. Pair the bb server with bb connect first (Settings → Remote access, or
    `bb connect --code … --server …`).
-2. Mint a pairing code for the phone: Settings → Remote access → **Add mobile
+2. Turn on the **Mobile app** experiment (Settings → Experiments, or
+   `bb settings experiment mobileApp true`). Mobile pairing stays hidden
+   without it while the app is in early access.
+3. Mint a pairing code for the phone: Settings → Remote access → **Add mobile
    device** (QR code plus the code as text, with a countdown), or run
    `bb connect machine-code` (`--json` prints
    `{code, serverUrl, apex, expiresAt}`).
-3. In the mobile app, add a server over bb connect and scan the QR code or type
+4. In the mobile app, add a server over bb connect and scan the QR code or type
    the code. Codes last 10 minutes and work once.
 
 The phone keeps its credential in the device keychain and mints short-lived
diff --git a/packages/db/test/experiments.test.ts b/packages/db/test/experiments.test.ts
index 0ee1b541b1..e617d89720 100644
--- a/packages/db/test/experiments.test.ts
+++ b/packages/db/test/experiments.test.ts
@@ -38,6 +38,7 @@ describe("experiments", () => {
         "claudeCodeMockCliTraffic",
         "editMessages",
         "futureExperiment",
+        "mobileApp",
         "newOnboarding",
         "providerSessionReaping",
       ]);
diff --git a/packages/domain/src/experiments.ts b/packages/domain/src/experiments.ts
index b45c6ceb50..91fdd55081 100644
--- a/packages/domain/src/experiments.ts
+++ b/packages/domain/src/experiments.ts
@@ -13,6 +13,7 @@ import { z } from "zod";
 export const experimentKeys = [
   "claudeCodeMockCliTraffic",
   "editMessages",
+  "mobileApp",
   "newOnboarding",
   "providerSessionReaping",
 ] as const;
@@ -29,6 +30,7 @@ export type Experiments = z.infer<typeof experimentsSchema>;
 export const defaultExperiments: Experiments = {
   claudeCodeMockCliTraffic: false,
   editMessages: true,
+  mobileApp: false,
   newOnboarding: false,
   providerSessionReaping: false,
 };
diff --git a/packages/templates/src/templates/bb-guide-environments.md b/packages/templates/src/templates/bb-guide-environments.md
index ae22f38b32..0bccfca842 100644
--- a/packages/templates/src/templates/bb-guide-environments.md
+++ b/packages/templates/src/templates/bb-guide-environments.md
@@ -156,6 +156,7 @@ Remote access (bb connect):
   bb connect shares [--host <name-or-id>]           List that host's shares
   bb connect servers                      List every bb on this account (handle, url, live)
   bb connect machine-code                 Mint a one-time code that pairs the bb mobile app
+                                          (needs the mobileApp experiment)
 
   Port sharing works from threads on any enrolled host. In a thread,
   `bb connect expose <port>` resolves the thread environment's host; outside a
@@ -170,8 +171,10 @@ Remote access (bb connect):
   `bb connect status` shows all shares with host + URL. `shares --json` returns
   the resolved `host` and rows with `hostId`, `hostName`, `port`, and `url`.
 
-  The bb mobile app pairs with a paired bb through bb connect. Settings →
-  Remote access → Add mobile device shows a QR code plus the code as text;
+  The bb mobile app pairs with a paired bb through bb connect. Turn on the
+  `mobileApp` experiment first (`bb settings experiment mobileApp true`, or
+  Settings → Experiments → Mobile app); the surfaces below stay hidden without
+  it. Settings → Remote access → Add mobile device shows a QR code plus the code as text;
   `bb connect machine-code` prints the same code, server URL, apex, and expiry
   (`--json` for `{code, serverUrl, apex, expiresAt}`). The phone scans or
   types the code and enrolls as a connect machine on the account with its own
diff --git a/plugins/connect/app.test.tsx b/plugins/connect/app.test.tsx
index af67ebee00..5a5366b19d 100644
--- a/plugins/connect/app.test.tsx
+++ b/plugins/connect/app.test.tsx
@@ -358,6 +358,33 @@ describe("connect settings section", () => {
     await slot.findByText(/this bb is not connected to getbb.app/);
   });
 
+  it("hides mobile pairing unless the mobileApp experiment is on", async () => {
+    const slot = renderSlot(
+      app.settingsSections[0]!,
+      {},
+      {
+        rpc: {
+          status: () => connected(),
+          mobilePairing: () => ({ enabled: false }),
+        },
+      },
+    );
+
+    await slot.findByText("Connected");
+    await waitFor(() =>
+      expect(slot.rpcCalls).toContainEqual({
+        method: "mobilePairing",
+        input: null,
+      }),
+    );
+    expect(slot.queryByText("Mobile app")).toBeNull();
+    expect(
+      slot.queryByRole("button", { name: "Add mobile device" }),
+    ).toBeNull();
+    // The rest of the paired card is unaffected.
+    slot.getByRole("button", { name: "Show QR for phone" });
+  });
+
   it("add mobile device mints a machine code and shows the QR payload, the code, and a countdown", async () => {
     const expiresAt = Date.now() + 600_000;
     const slot = renderSlot(
@@ -366,6 +393,7 @@ describe("connect settings section", () => {
       {
         rpc: {
           status: () => connected(),
+          mobilePairing: () => ({ enabled: true }),
           createMachineCode: () => ({
             code: "K7QP-2M4X",
             expiresAt,
@@ -405,6 +433,7 @@ describe("connect settings section", () => {
       {
         rpc: {
           status: () => connected(),
+          mobilePairing: () => ({ enabled: true }),
           createMachineCode: () => {
             minted += 1;
             return {
@@ -440,6 +469,7 @@ describe("connect settings section", () => {
       {
         rpc: {
           status: () => connected(),
+          mobilePairing: () => ({ enabled: true }),
           createMachineCode: () => {
             throw new Error("machine_limit");
           },
diff --git a/plugins/connect/app.tsx b/plugins/connect/app.tsx
index 867d561044..c374aa3a89 100644
--- a/plugins/connect/app.tsx
+++ b/plugins/connect/app.tsx
@@ -525,11 +525,21 @@ function PairForm({
 // shown as copyable text for manual entry. Mirrors `bb connect machine-code`.
 // ---------------------------------------------------------------------------
 
-type MachineCodeErrorCode = "machine_limit" | "network" | "not_paired";
+type MachineCodeErrorCode =
+  | "experiment_off"
+  | "machine_limit"
+  | "network"
+  | "not_paired";
 
 function toMachineCodeErrorCode(error: unknown): MachineCodeErrorCode {
   const message = errorText(error);
-  if (message === "machine_limit" || message === "not_paired") return message;
+  if (
+    message === "experiment_off" ||
+    message === "machine_limit" ||
+    message === "not_paired"
+  ) {
+    return message;
+  }
   // Unknown failures read as transient; the user can retry.
   return "network";
 }
@@ -631,7 +641,44 @@ function MobilePairingCard({
   );
 }
 
+/**
+ * Mobile pairing ships behind the `mobileApp` experiment (Settings →
+ * Experiments) until the app is generally available. The backend owns the
+ * gate (it also refuses `createMachineCode`); this hook only decides whether
+ * to render the section. False while the answer is unknown or on error, so
+ * the panel never flashes the section for an install that has it off.
+ */
+function useMobilePairingEnabled(): boolean {
+  const rpc = useRpc<typeof connectRpcContract>();
+  const [enabled, setEnabled] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    rpc.call("mobilePairing").then(
+      (result) => {
+        if (!cancelled) setEnabled(result.enabled);
+      },
+      () => {
+        if (!cancelled) setEnabled(false);
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [rpc]);
+  return enabled;
+}
+
 function AddMobileDeviceSection({ dashboardUrl }: { dashboardUrl: string }) {
+  const enabled = useMobilePairingEnabled();
+  if (!enabled) return null;
+  return <AddMobileDeviceSectionContent dashboardUrl={dashboardUrl} />;
+}
+
+function AddMobileDeviceSectionContent({
+  dashboardUrl,
+}: {
+  dashboardUrl: string;
+}) {
   const rpc = useRpc<typeof connectRpcContract>();
   const [payload, setPayload] = useState<MobilePairingPayload | null>(null);
   const [minting, setMinting] = useState(false);
@@ -726,7 +773,9 @@ function AddMobileDeviceSection({ dashboardUrl }: { dashboardUrl: string }) {
         <p className="text-xs text-destructive-text">
           {errorCode === "not_paired"
             ? "This bb is no longer paired — re-pair, then try again."
-            : "Couldn't reach the Connect service to create a code — check your connection, then try again."}
+            : errorCode === "experiment_off"
+              ? "Mobile pairing was turned off in Settings → Experiments."
+              : "Couldn't reach the Connect service to create a code — check your connection, then try again."}
         </p>
       ) : null}
     </div>
diff --git a/plugins/connect/src/cli.ts b/plugins/connect/src/cli.ts
index 4061002e9d..2313a396ca 100644
--- a/plugins/connect/src/cli.ts
+++ b/plugins/connect/src/cli.ts
@@ -5,6 +5,7 @@ import {
 } from "@bb/connect-client";
 import type { ShareHostResolver } from "./hosts.js";
 import { MachineCodeError } from "./machine-code.js";
+import type { MobilePairingGate } from "./rpc.js";
 import { parseSharePort } from "./shares.js";
 import type { ConnectTunnel } from "./tunnel.js";
 import type { ConnectStatus } from "./types.js";
@@ -83,7 +84,8 @@ function helpText(): string {
     "  bb connect shares [--host <name-or-id>]           List shares for the thread's host",
     "  bb connect servers             List every bb on this account (from getbb.app)",
     "  bb connect machine-code        Mint a one-time code that enrolls the bb mobile app (or another",
-    "                                 device) as a connect machine for this bb",
+    "                                 device) as a connect machine for this bb (needs the",
+    '                                 "Mobile app" experiment in Settings → Experiments)',
     "",
     "The server holds the tunnel; it stays up while bb is running.",
   ].join("\n");
@@ -135,6 +137,10 @@ function machineCodeErrorText(
   }
 }
 
+function mobilePairingDisabledError(): string {
+  return 'mobile pairing is off — turn on the "Mobile app" experiment in Settings → Experiments (or `bb settings experiment mobileApp true`), then run this again';
+}
+
 function formatMachineCode(payload: MobilePairingPayload): string {
   const minutes = Math.max(
     0,
@@ -157,8 +163,9 @@ export function registerConnectCli(args: {
   bb: Pick<BbPluginApi, "cli">;
   tunnel: ConnectTunnel;
   hostResolver: ShareHostResolver;
+  mobilePairing: MobilePairingGate;
 }): void {
-  const { bb, tunnel, hostResolver } = args;
+  const { bb, tunnel, hostResolver, mobilePairing } = args;
   bb.cli.register({
     name: "connect",
     summary:
@@ -197,7 +204,7 @@ export function registerConnectCli(args: {
       {
         name: "machine-code",
         summary:
-          "Mint a one-time code that enrolls the bb mobile app as a connect machine",
+          'Mint a one-time code that enrolls the bb mobile app as a connect machine (needs the "Mobile app" experiment)',
         usage: "bb connect machine-code [--json]",
       },
     ],
@@ -348,6 +355,12 @@ export function registerConnectCli(args: {
         if (first === "machine-code") {
           const parsed = parseFlags(argv.slice(1));
           validateFlags(parsed, { boolean: ["json"] });
+          if (!(await mobilePairing.enabled())) {
+            return {
+              exitCode: 1,
+              stderr: `${mobilePairingDisabledError()}\n`,
+            };
+          }
           let payload: MobilePairingPayload;
           try {
             payload = mobilePairingPayload(await tunnel.createMachineCode());
diff --git a/plugins/connect/src/connect.test.ts b/plugins/connect/src/connect.test.ts
index 4cddc49eb6..03295d0664 100644
--- a/plugins/connect/src/connect.test.ts
+++ b/plugins/connect/src/connect.test.ts
@@ -39,12 +39,18 @@ const REMOTE_HOST_NAME = "Sawyer Air";
 
 function createConnectFakeHost(options?: {
   remoteIdentity?: { label: string; baseDomain: string };
+  /** The `mobileApp` experiment (defaults on so pairing paths are exercised). */
+  mobileApp?: boolean;
 }): FakePluginHost {
   return createFakePluginHost({
     pluginId: "connect",
     sdk: {
       system: {
-        config: async () => ({ primaryHostId: SERVER_HOST_ID }) as never,
+        config: async () =>
+          ({
+            primaryHostId: SERVER_HOST_ID,
+            experiments: { mobileApp: options?.mobileApp ?? true },
+          }) as never,
       },
       hosts: {
         get: async ({ hostId }: { hostId: string }) => {
@@ -2389,8 +2395,10 @@ describe("connect CLI", () => {
     vi.unstubAllGlobals();
   });
 
-  async function loadCli(): Promise<FakePluginHost> {
-    host = createConnectFakeHost();
+  async function loadCli(options?: {
+    mobileApp?: boolean;
+  }): Promise<FakePluginHost> {
+    host = createConnectFakeHost(options);
     await plugin(host.bb as unknown as Parameters<typeof plugin>[0]);
     return host;
   }
@@ -2534,6 +2542,17 @@ describe("connect CLI", () => {
     );
   });
 
+  it("machine-code is off until the mobileApp experiment is on", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    const { harness } = await loadCli({ mobileApp: false });
+    const result = await harness.runCli(["machine-code"]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain('"Mobile app" experiment');
+    expect(result.stderr).toContain("bb settings experiment mobileApp true");
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
   it("machine-code when unpaired errors clearly", async () => {
     const fetchMock = vi.fn();
     vi.stubGlobal("fetch", fetchMock);
diff --git a/plugins/connect/src/rpc.ts b/plugins/connect/src/rpc.ts
index 2ef1f0934d..7d247129a0 100644
--- a/plugins/connect/src/rpc.ts
+++ b/plugins/connect/src/rpc.ts
@@ -98,6 +98,13 @@ const desktopSessionSchema: z.ZodType<DesktopSession> = z
   })
   .strict();
 
+const mobilePairingSchema = z
+  .object({
+    /** True when the `mobileApp` experiment is on (Settings → Experiments). */
+    enabled: z.boolean(),
+  })
+  .strict();
+
 const machineCodeSchema: z.ZodType<MachineCode> = z
   .object({
     code: z.string(),
@@ -128,6 +135,7 @@ export const connectRpcContract = defineRpcContract({
     output: listAccountServersResultSchema,
   },
   createDesktopSession: { input: z.null(), output: desktopSessionSchema },
+  mobilePairing: { input: z.null(), output: mobilePairingSchema },
   createMachineCode: { input: z.null(), output: machineCodeSchema },
   revokeMachine: {
     input: revokeMachineInputSchema,
@@ -137,9 +145,22 @@ export const connectRpcContract = defineRpcContract({
 
 export type ConnectRpcHandlers = PluginRpcHandlers<typeof connectRpcContract>;
 
+/**
+ * Mobile pairing (the "Add mobile device" card and `bb connect machine-code`)
+ * ships behind the user-toggled `mobileApp` experiment until the app is
+ * generally available. The gate is read at call time so a toggle applies
+ * without a plugin reload.
+ */
+export interface MobilePairingGate {
+  enabled(): Promise<boolean>;
+}
+
+export const MOBILE_PAIRING_DISABLED_ERROR = "experiment_off";
+
 export function createRpcHandlers(
   tunnel: ConnectTunnel,
   hostResolver: ShareHostResolver,
+  mobilePairing: MobilePairingGate,
 ): ConnectRpcHandlers {
   return {
     async pair(args) {
@@ -202,7 +223,13 @@ export function createRpcHandlers(
         throw error;
       }
     },
+    async mobilePairing() {
+      return { enabled: await mobilePairing.enabled() };
+    },
     async createMachineCode() {
+      if (!(await mobilePairing.enabled())) {
+        throw new Error(MOBILE_PAIRING_DISABLED_ERROR);
+      }
       try {
         return await tunnel.createMachineCode();
       } catch (error) {
diff --git a/plugins/connect/src/server.ts b/plugins/connect/src/server.ts
index 4d1c4f324f..bdaf95bffb 100644
--- a/plugins/connect/src/server.ts
+++ b/plugins/connect/src/server.ts
@@ -1,7 +1,11 @@
 import type { BbPluginApi } from "@get-bb/plugin-sdk";
 import { registerConnectCli } from "./cli.js";
 import { createKvCredentialStore } from "./credential.js";
-import { connectRpcContract, createRpcHandlers } from "./rpc.js";
+import {
+  connectRpcContract,
+  createRpcHandlers,
+  type MobilePairingGate,
+} from "./rpc.js";
 import { ShareRegistry } from "./shares.js";
 import { ConnectTunnel } from "./tunnel.js";
 import { ShareHostResolver } from "./hosts.js";
@@ -45,8 +49,17 @@ export default async function plugin(bb: BbPluginApi) {
       bb.realtime.publish(CONNECT_REALTIME_CHANNEL, status),
   });
 
-  bb.rpc.register(connectRpcContract, createRpcHandlers(tunnel, hostResolver));
-  registerConnectCli({ bb, tunnel, hostResolver });
+  // Experiments are server-owned settings; the plugin reads them through its
+  // loopback SDK binding rather than through a dedicated plugin API.
+  const mobilePairing: MobilePairingGate = {
+    enabled: async () => (await bb.sdk.system.config()).experiments.mobileApp,
+  };
+
+  bb.rpc.register(
+    connectRpcContract,
+    createRpcHandlers(tunnel, hostResolver, mobilePairing),
+  );
+  registerConnectCli({ bb, tunnel, hostResolver, mobilePairing });
 
   bb.agents.contributeInstructions(() => {
     const status = tunnel.status();

From 3c224ae714f3465af40a546e2a02fca06f8acfdb Mon Sep 17 00:00:00 2001
From: Sawyer Hood <sawyerjhood@gmail.com>
Date: Wed, 19 Aug 2026 19:12:11 -0700
Subject: [PATCH 3/4] Keep the createMachineCode rpc open; gate only the mobile
 surfaces

The desktop app's own connect enrollment and the web "Add machine" dialog
mint machine codes through the same `createMachineCode` rpc, so the
mobileApp experiment gate added in 00fc462 broke both by default. The gate
now covers only the mobile-specific surfaces: the panel card (through the
`mobilePairing` rpc) and `bb connect machine-code`.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 plugins/connect/app.tsx    | 26 ++++++++------------------
 plugins/connect/src/rpc.ts |  9 +++------
 2 files changed, 11 insertions(+), 24 deletions(-)

diff --git a/plugins/connect/app.tsx b/plugins/connect/app.tsx
index c374aa3a89..875d82fd1c 100644
--- a/plugins/connect/app.tsx
+++ b/plugins/connect/app.tsx
@@ -525,21 +525,11 @@ function PairForm({
 // shown as copyable text for manual entry. Mirrors `bb connect machine-code`.
 // ---------------------------------------------------------------------------
 
-type MachineCodeErrorCode =
-  | "experiment_off"
-  | "machine_limit"
-  | "network"
-  | "not_paired";
+type MachineCodeErrorCode = "machine_limit" | "network" | "not_paired";
 
 function toMachineCodeErrorCode(error: unknown): MachineCodeErrorCode {
   const message = errorText(error);
-  if (
-    message === "experiment_off" ||
-    message === "machine_limit" ||
-    message === "not_paired"
-  ) {
-    return message;
-  }
+  if (message === "machine_limit" || message === "not_paired") return message;
   // Unknown failures read as transient; the user can retry.
   return "network";
 }
@@ -644,9 +634,11 @@ function MobilePairingCard({
 /**
  * Mobile pairing ships behind the `mobileApp` experiment (Settings →
  * Experiments) until the app is generally available. The backend owns the
- * gate (it also refuses `createMachineCode`); this hook only decides whether
- * to render the section. False while the answer is unknown or on error, so
- * the panel never flashes the section for an install that has it off.
+ * gate (the `mobilePairing` rpc, also honoured by `bb connect machine-code`);
+ * this hook only decides whether to render the section. False while the
+ * answer is unknown or on error, so the panel never flashes the section for
+ * an install that has it off. `createMachineCode` itself is not gated: the
+ * desktop app and the "Add machine" dialog mint machine codes through it.
  */
 function useMobilePairingEnabled(): boolean {
   const rpc = useRpc<typeof connectRpcContract>();
@@ -773,9 +765,7 @@ function AddMobileDeviceSectionContent({
         <p className="text-xs text-destructive-text">
           {errorCode === "not_paired"
             ? "This bb is no longer paired — re-pair, then try again."
-            : errorCode === "experiment_off"
-              ? "Mobile pairing was turned off in Settings → Experiments."
-              : "Couldn't reach the Connect service to create a code — check your connection, then try again."}
+            : "Couldn't reach the Connect service to create a code — check your connection, then try again."}
         </p>
       ) : null}
     </div>
diff --git a/plugins/connect/src/rpc.ts b/plugins/connect/src/rpc.ts
index 7d247129a0..2f7312bb6b 100644
--- a/plugins/connect/src/rpc.ts
+++ b/plugins/connect/src/rpc.ts
@@ -149,14 +149,14 @@ export type ConnectRpcHandlers = PluginRpcHandlers<typeof connectRpcContract>;
  * Mobile pairing (the "Add mobile device" card and `bb connect machine-code`)
  * ships behind the user-toggled `mobileApp` experiment until the app is
  * generally available. The gate is read at call time so a toggle applies
- * without a plugin reload.
+ * without a plugin reload. It covers only those two mobile surfaces: the
+ * `createMachineCode` rpc itself stays open because the desktop app's own
+ * enrollment and the web "Add machine" dialog mint machine codes through it.
  */
 export interface MobilePairingGate {
   enabled(): Promise<boolean>;
 }
 
-export const MOBILE_PAIRING_DISABLED_ERROR = "experiment_off";
-
 export function createRpcHandlers(
   tunnel: ConnectTunnel,
   hostResolver: ShareHostResolver,
@@ -227,9 +227,6 @@ export function createRpcHandlers(
       return { enabled: await mobilePairing.enabled() };
     },
     async createMachineCode() {
-      if (!(await mobilePairing.enabled())) {
-        throw new Error(MOBILE_PAIRING_DISABLED_ERROR);
-      }
       try {
         return await tunnel.createMachineCode();
       } catch (error) {

From c0794d7530c8fca45ab69e862b41600fbc58afc4 Mon Sep 17 00:00:00 2001
From: Sawyer Hood <sawyerjhood@gmail.com>
Date: Wed, 19 Aug 2026 19:33:33 -0700
Subject: [PATCH 4/4] Review fixes for the mobile core-prep layer

- connect worker: answer the Apple/Android app-link association files only
  for bare labels; share hosts (`<label>--<port>`) front arbitrary local
  apps and must not claim /threads, /projects, /settings for the mobile app
- AASA: emit only the modern `appIDs` + `components` form (Apple TN3155
  warns against mixing it with the legacy `appID` + `paths` keys)
- mobile-e2e backend: print a security warning (and the LAN URL hint) when
  BB_MOBILE_E2E_BIND_HOST=0.0.0.0 exposes the unauthenticated harness
- ask-user-question / secrets plugins: import the shared renderer-ID
  constants instead of repeating the literals
- docs: drop a forward-referencing anchor

Co-Authored-By: Claude <noreply@anthropic.com>
---
 apps/connect/src/worker.test.ts            | 39 ++++++++++++--------
 apps/connect/src/worker.ts                 | 25 +++++++------
 docs/multiple-devices.md                   |  2 +-
 packages/connect-db/src/app-links.ts       | 17 ++++-----
 packages/connect-db/test/app-links.test.ts | 22 +++++++-----
 plugins/ask-user-question/app.tsx          |  3 +-
 plugins/ask-user-question/src/contracts.ts |  1 +
 plugins/ask-user-question/src/server.ts    |  9 +++--
 plugins/secrets/app.tsx                    |  3 +-
 plugins/secrets/src/contracts.ts           |  1 +
 plugins/secrets/src/server.ts              |  8 +++--
 tests/integration/mobile-e2e/backend.ts    | 42 ++++++++++++++++++++--
 12 files changed, 122 insertions(+), 50 deletions(-)

diff --git a/apps/connect/src/worker.test.ts b/apps/connect/src/worker.test.ts
index c0f1974d05..ca536b6ce0 100644
--- a/apps/connect/src/worker.test.ts
+++ b/apps/connect/src/worker.test.ts
@@ -717,36 +717,47 @@ describe("bb mobile app-link association files", () => {
     },
   );
 
-  it("serves the AASA on share hosts and labels that do not resolve (Apple fetches anonymously)", async () => {
+  it("serves the AASA on bare labels that do not resolve yet (Apple fetches anonymously before a claim)", async () => {
     mockResolveLabel.mockResolvedValue(null);
     const { env, ctx, captured } = makeEnv(() => new Response("origin"));
-    const share = await worker.fetch(
+    const unknown = await worker.fetch(
       visitorRequest(
-        "sawyer--8000.getbb.app",
+        "nobody-here.getbb.app",
         "/.well-known/apple-app-site-association",
       ),
       env as never,
       ctx,
     );
-    expect(share.status).toBe(200);
-    const body = (await share.json()) as {
+    expect(unknown.status).toBe(200);
+    const body = (await unknown.json()) as {
       applinks: { details: { appIDs: string[] }[] };
     };
     expect(body.applinks.details[0]?.appIDs).toEqual([
       "9QCU24SXK5.app.getbb.mobile",
     ]);
-    const unknown = await worker.fetch(
-      visitorRequest(
-        "nobody-here.getbb.app",
-        "/.well-known/apple-app-site-association",
-      ),
-      env as never,
-      ctx,
-    );
-    expect(unknown.status).toBe(200);
     expect(captured).toHaveLength(0);
   });
 
+  it.each([
+    "/.well-known/apple-app-site-association",
+    "/.well-known/assetlinks.json",
+  ])(
+    "does not claim %s on share hosts — they front arbitrary local apps, so the file falls through to the session gate",
+    async (path) => {
+      const { env, ctx, captured } = makeEnv(() => new Response("origin"));
+      const share = await worker.fetch(
+        visitorRequest("sawyer--8000.getbb.app", path),
+        env as never,
+        ctx,
+      );
+      // Anonymous (Apple CDN / Android) fetch → 401 sign-in page, i.e. no
+      // association for `<label>--<port>` hosts; never proxied without a session.
+      expect(share.status).toBe(401);
+      expect(share.headers.get("content-type")).not.toBe("application/json");
+      expect(captured).toHaveLength(0);
+    },
+  );
+
   it("reads Android fingerprints from the env and serves an empty list otherwise", async () => {
     const { env, ctx } = makeEnv(() => new Response("origin"));
     const empty = await worker.fetch(
diff --git a/apps/connect/src/worker.ts b/apps/connect/src/worker.ts
index 6065a683ee..25accdbfcf 100644
--- a/apps/connect/src/worker.ts
+++ b/apps/connect/src/worker.ts
@@ -295,19 +295,24 @@ export default {
     if (url.pathname === "/api/connect/machine-label") {
       return handleAssignMachineLabel(request, env);
     }
-    // bb mobile universal / app links: Apple's CDN and Android fetch the
-    // association files anonymously from `https://<label>.getbb.app`, so
-    // they are answered here for every host — before label resolution and
-    // the session gate, never proxied to the tunnel, never redirected.
-    const appLinks = handleAppLinkAssociationRequest(
-      { method: request.method, url: url.toString() },
-      env,
-    );
-    if (appLinks) return appLinks;
-
     const host = resolveConnectRequestHost(request.headers, runtime);
     const parsed = parseVisitorHost(host, env.BASE_DOMAIN);
     if (!parsed) return text("bb connect: unknown host\n", 404);
+    // bb mobile universal / app links: Apple's CDN and Android fetch the
+    // association files anonymously from `https://<label>.getbb.app`, so
+    // bare labels answer here — before label resolution (Apple may fetch
+    // before the label is claimed) and the session gate, never proxied to
+    // the tunnel, never redirected. Share hosts (`<label>--<port>`) front
+    // arbitrary local apps, not a bb server, so they must not claim
+    // `/threads/*` & co for the app: they fall through to the normal gate
+    // like any other path (401 for Apple's anonymous fetch → no association).
+    if (parsed.target === null) {
+      const appLinks = handleAppLinkAssociationRequest(
+        { method: request.method, url: url.toString() },
+        env,
+      );
+      if (appLinks) return appLinks;
+    }
     // The base label is now ANY server's subdomain (the account handle names the
     // primary bb; additional bbs claim their own labels), not just a profile
     // handle. `target` (a port) rides along for share hosts, nested per-bb.
diff --git a/docs/multiple-devices.md b/docs/multiple-devices.md
index 1dd48f977a..e0c028d216 100644
--- a/docs/multiple-devices.md
+++ b/docs/multiple-devices.md
@@ -101,7 +101,7 @@ the account's machine slots, so a machine-limit error means an unused device
 should be revoked first. On a trusted network the app can also use a direct
 server URL (Tailscale Serve or `--server-bind-host 0.0.0.0`) with the same
 caveats as a browser. Platforms (iOS first) and what the phone cannot do are
-listed in [platform-support.md](platform-support.md#mobile-app).
+listed in [platform-support.md](platform-support.md).
 
 ## Point the desktop app at another bb
 
diff --git a/packages/connect-db/src/app-links.ts b/packages/connect-db/src/app-links.ts
index 5d492d3e17..ba905a3bf8 100644
--- a/packages/connect-db/src/app-links.ts
+++ b/packages/connect-db/src/app-links.ts
@@ -1,8 +1,10 @@
 // bb mobile app-link association files (iOS universal links, Android app
-// links). Served unauthenticated from every `<label>.getbb.app` by the connect
-// gate (before the session check) and from the apex by bb-web, so a
+// links). Served unauthenticated from every bare `<label>.getbb.app` by the
+// connect gate (before the session check) and from the apex by bb-web, so a
 // `https://<handle>.getbb.app/threads/<id>` link opens the app when it is
-// installed. Single source of truth for the app ids and the path allowlist.
+// installed. Share hosts (`<label>--<port>.getbb.app`) front arbitrary local
+// apps, not a bb server, so the gate does not answer there. Single source of
+// truth for the app ids and the path allowlist.
 
 /** Apple team id + iOS bundle id of the bb mobile app. */
 export const BB_MOBILE_IOS_APP_ID = "9QCU24SXK5.app.getbb.mobile";
@@ -26,18 +28,17 @@ export const ANDROID_ASSET_LINKS_PATH = "/.well-known/assetlinks.json";
 
 /**
  * `https://developer.apple.com/documentation/xcode/supporting-associated-domains`
- * — the modern `components` form plus the legacy `paths` array for older
- * iOS versions. Served as `application/json` with no redirects.
+ * — the modern `appIDs` + `components` form only. Apple TN3155 says not to
+ * mix it with the legacy `appID` + `paths` keys (unexpected universal-link
+ * behaviour), and the app's minimum iOS is well past 13.5 where the legacy
+ * keys mattered. Served as `application/json` with no redirects.
  */
 export function buildAppleAppSiteAssociation(): Record<string, unknown> {
   return {
     applinks: {
-      apps: [],
       details: [
         {
           appIDs: [BB_MOBILE_IOS_APP_ID],
-          appID: BB_MOBILE_IOS_APP_ID,
-          paths: [...BB_MOBILE_APP_LINK_PATHS],
           components: BB_MOBILE_APP_LINK_PATHS.map((path) => ({
             "/": path,
           })),
diff --git a/packages/connect-db/test/app-links.test.ts b/packages/connect-db/test/app-links.test.ts
index a2cd88b903..5a563944c9 100644
--- a/packages/connect-db/test/app-links.test.ts
+++ b/packages/connect-db/test/app-links.test.ts
@@ -20,17 +20,23 @@ describe("app link association files", () => {
     expect(response?.status).toBe(200);
     expect(response?.headers.get("content-type")).toBe("application/json");
     const body = (await response?.json()) as {
-      applinks: {
-        details: { appIDs: string[]; paths: string[]; components: unknown[] }[];
+      applinks: Record<string, unknown> & {
+        details: Record<string, unknown>[];
       };
     };
-    expect(body.applinks.details[0]?.appIDs).toEqual([BB_MOBILE_IOS_APP_ID]);
-    expect(body.applinks.details[0]?.paths).toEqual([
-      "/threads/*",
-      "/projects/*",
-      "/settings/*",
+    // Modern form only: Apple TN3155 warns against mixing `appIDs`/`components`
+    // with the legacy `appID`/`paths` keys.
+    expect(body.applinks.details).toEqual([
+      {
+        appIDs: [BB_MOBILE_IOS_APP_ID],
+        components: [
+          { "/": "/threads/*" },
+          { "/": "/projects/*" },
+          { "/": "/settings/*" },
+        ],
+      },
     ]);
-    expect(body.applinks.details[0]?.components).toHaveLength(3);
+    expect(Object.keys(body.applinks)).toEqual(["details"]);
   });
 
   it("serves assetlinks.json with the fingerprints from the env (empty when unset)", async () => {
diff --git a/plugins/ask-user-question/app.tsx b/plugins/ask-user-question/app.tsx
index de07b0fdc2..5d5923fafe 100644
--- a/plugins/ask-user-question/app.tsx
+++ b/plugins/ask-user-question/app.tsx
@@ -17,6 +17,7 @@ import { Icon } from "@bb/shared-ui/icon";
 import { usePointerCoarse } from "@bb/shared-ui/hooks/use-pointer-coarse";
 import { cn } from "@bb/shared-ui/lib/utils";
 import {
+  ASK_USER_QUESTION_RENDERER_ID,
   interactionPayloadSchema,
   type InteractionOption,
   type InteractionQuestion,
@@ -560,7 +561,7 @@ function AskUserQuestionInteraction({
 
 export default definePluginApp((app) => {
   app.slots.pendingInteraction({
-    id: "ask-user-question",
+    id: ASK_USER_QUESTION_RENDERER_ID,
     component: AskUserQuestionInteraction,
   });
 });
diff --git a/plugins/ask-user-question/src/contracts.ts b/plugins/ask-user-question/src/contracts.ts
index 12216b24b5..3f0a27e44c 100644
--- a/plugins/ask-user-question/src/contracts.ts
+++ b/plugins/ask-user-question/src/contracts.ts
@@ -11,6 +11,7 @@ import {
 // render the same form. Re-exported here so the plugin's own modules keep one
 // import path; the tool input/result shapes below stay plugin-private.
 export {
+  ASK_USER_QUESTION_RENDERER_ID,
   MAX_FREE_TEXT_LENGTH,
   MAX_OPTION_PREVIEW_LENGTH,
   MAX_OPTIONS,
diff --git a/plugins/ask-user-question/src/server.ts b/plugins/ask-user-question/src/server.ts
index 3b19c30226..8767fb793d 100644
--- a/plugins/ask-user-question/src/server.ts
+++ b/plugins/ask-user-question/src/server.ts
@@ -1,5 +1,9 @@
 import type { BbPluginApi, PluginAgentToolResult } from "@get-bb/plugin-sdk";
-import { interactionResponseSchema, toolInputSchema } from "./contracts.js";
+import {
+  ASK_USER_QUESTION_RENDERER_ID,
+  interactionResponseSchema,
+  toolInputSchema,
+} from "./contracts.js";
 import {
   TOOL_DESCRIPTION,
   TOOL_INPUT_JSON_SCHEMA,
@@ -14,8 +18,7 @@ import {
 } from "./translate.js";
 
 export const TOOL_NAME = "AskUserQuestion";
-export const RENDERER_ID = "ask-user-question";
-
+export const RENDERER_ID = ASK_USER_QUESTION_RENDERER_ID;
 
 function errorResult(message: string): PluginAgentToolResult {
   return { content: [{ type: "text", text: message }], isError: true };
diff --git a/plugins/secrets/app.tsx b/plugins/secrets/app.tsx
index 9442bab0f6..b282f567c3 100644
--- a/plugins/secrets/app.tsx
+++ b/plugins/secrets/app.tsx
@@ -13,6 +13,7 @@ import {
 } from "@hugeicons/core-free-icons";
 import { HugeiconsIcon } from "@hugeicons/react";
 import {
+  SECRET_REQUEST_RENDERER_ID,
   secretRequestPayloadSchema,
   secretRequestResponseSchema,
 } from "./src/contracts.js";
@@ -216,7 +217,7 @@ function SecretRequestInteraction({
 
 export default definePluginApp((app) => {
   app.slots.pendingInteraction({
-    id: "secret-request",
+    id: SECRET_REQUEST_RENDERER_ID,
     component: SecretRequestInteraction,
   });
 });
diff --git a/plugins/secrets/src/contracts.ts b/plugins/secrets/src/contracts.ts
index 9b876560d0..b215440808 100644
--- a/plugins/secrets/src/contracts.ts
+++ b/plugins/secrets/src/contracts.ts
@@ -3,6 +3,7 @@
 // React DOM bundle (the native app) can render the same secure form.
 // Re-exported here so the plugin's own modules keep one import path.
 export {
+  SECRET_REQUEST_RENDERER_ID,
   secretNameSchema,
   secretRequestPayloadSchema,
   secretRequestResponseSchema,
diff --git a/plugins/secrets/src/server.ts b/plugins/secrets/src/server.ts
index 84ce296067..b284f5ba31 100644
--- a/plugins/secrets/src/server.ts
+++ b/plugins/secrets/src/server.ts
@@ -5,7 +5,11 @@ import type {
   PluginCliResult,
 } from "@get-bb/plugin-sdk";
 import { z } from "zod";
-import { secretNameSchema, secretRequestResponseSchema } from "./contracts.js";
+import {
+  SECRET_REQUEST_RENDERER_ID,
+  secretNameSchema,
+  secretRequestResponseSchema,
+} from "./contracts.js";
 import { assertNoDuplicateAssignments, reconcileDotenv } from "./dotenv.js";
 
 interface ParsedRequest {
@@ -176,7 +180,7 @@ async function runRequest(
   const result = await bb.ui.requestInput(
     {
       threadId: ctx.threadId,
-      rendererId: "secret-request",
+      rendererId: SECRET_REQUEST_RENDERER_ID,
       title: `Add secrets to ${destinationPath}`,
       payload: {
         purpose: parsed.purpose,
diff --git a/tests/integration/mobile-e2e/backend.ts b/tests/integration/mobile-e2e/backend.ts
index a6713fe9fc..dbd9ba4672 100644
--- a/tests/integration/mobile-e2e/backend.ts
+++ b/tests/integration/mobile-e2e/backend.ts
@@ -11,6 +11,13 @@
 //
 // The iOS Simulator shares the Mac loopback, so the app can use
 // http://127.0.0.1:<port> directly. The Android emulator uses 10.0.2.2.
+//
+// SECURITY: BB_MOBILE_E2E_BIND_HOST=0.0.0.0 exposes the unauthenticated
+// harness server and a real host daemon (terminal sessions and file reads as
+// your user) to everyone on the network, the same exposure as
+// `bb --server-bind-host 0.0.0.0`. Use it only on a trusted network and stop
+// the backend when you are done.
+import { networkInterfaces } from "node:os";
 import { createFakeAdapter } from "@bb/agent-runtime/test";
 import type { PendingInteraction } from "@bb/domain";
 import { createIntegrationHarness } from "../helpers/harness.js";
@@ -45,6 +52,34 @@ function readBindHost(): "127.0.0.1" | "0.0.0.0" {
   throw new Error(`Invalid BB_MOBILE_E2E_BIND_HOST: ${raw}`);
 }
 
+/** Non-internal IPv4 addresses a phone on the same network could reach. */
+function listLanIpv4Addresses(): string[] {
+  return Object.values(networkInterfaces())
+    .flatMap((entries) => entries ?? [])
+    .filter((entry) => entry.family === "IPv4" && !entry.internal)
+    .map((entry) => entry.address);
+}
+
+/** Mirrors the server's wildcard-bind warning (apps/server start-server). */
+function warnWildcardBind(port: number): void {
+  const lanUrls = listLanIpv4Addresses().map(
+    (address) => `http://${address}:${port}`,
+  );
+  process.stderr.write(
+    [
+      "mobile-e2e backend: SECURITY WARNING: binding on 0.0.0.0. The harness",
+      "server is unauthenticated and runs a real host daemon that permits",
+      "command execution (terminal sessions) and file reads as your user.",
+      "Use BB_MOBILE_E2E_BIND_HOST=0.0.0.0 only behind a trusted network",
+      "boundary and stop the backend when you are done.",
+    ].join(" ") +
+      "\n" +
+      (lanUrls.length > 0
+        ? `mobile-e2e backend: point the phone at ${lanUrls.join(" or ")}\n`
+        : ""),
+  );
+}
+
 const TURN_TIMEOUT_MS = 15_000;
 const INTERACTION_POLL_INTERVAL_MS = 100;
 
@@ -156,11 +191,14 @@ const LONG_MARKDOWN_MESSAGE = [
 ].join("\n");
 
 async function main(): Promise<void> {
+  const bindHost = readBindHost();
+  const serverPort = readPort();
+  if (bindHost === "0.0.0.0") warnWildcardBind(serverPort);
   const harness = await createIntegrationHarness({
     adapterFactory: () =>
       createFakeAdapter({ supportsNativeUserQuestion: true }),
-    bindHost: readBindHost(),
-    serverPort: readPort(),
+    bindHost,
+    serverPort,
   });
 
   const shutdown = async (signal: string) => {