fix(nitro): Emit Vercel deployment wiring

Move Junior's heartbeat cron and conversation work queue trigger into Nitro's Vercel Build Output config so Vercel deploys the routes Nitro actually emits.

Teach junior check to catch stale source-file queue mappings and missing juniorNitro() wiring before production deploys can silently miss inbound work.

Co-Authored-By: GPT-5 Codex <codex@openai.com>

Author: dcramer

apps/example/vercel.json

@@ -1,21 +1,4 @@
 {
   "framework": "nitro",
-  "buildCommand": "pnpm build",
-  "crons": [
-    {
-      "path": "/api/internal/heartbeat",
-      "schedule": "* * * * *"
-    }
-  ],
-  "functions": {
-    "api/internal/agent/continue.ts": {
-      "maxDuration": 300,
-      "experimentalTriggers": [
-        {
-          "type": "queue/v2beta",
-          "topic": "junior_conversation_work"
-        }
-      ]
-    }
-  }
+  "buildCommand": "pnpm build"
 }

packages/docs/src/content/docs/cli/check.md

@@ -1,6 +1,6 @@
 ---
 title: "junior check"
-description: "Validate Junior plugin manifests and skill files under app/ before build or deploy."
+description: "Validate Junior content and deployment config before build or deploy."
 type: reference
 prerequisites:
   - /start-here/quickstart/
@@ -11,7 +11,7 @@ related:
   - /cli/snapshot-create/
 ---
 
-`junior check` validates local app content and installed plugin package content before build or deploy. It ignores legacy top-level `plugins/` and `skills/` directories, and it only runs app-file checks when the target already looks like a Junior app.
+`junior check` validates local app content, installed plugin package content, and Junior deployment config before build or deploy. It ignores legacy top-level `plugins/` and `skills/` directories, and it only runs app-file checks when the target already looks like a Junior app.
 
 ## Usage
 
@@ -65,6 +65,10 @@ When the target already contains Junior app markers such as `app/SOUL.md`, `app/
 
 If a skill file has frontmatter but no instructions after it, the command emits a warning instead of failing.
 
+For Nitro/Vercel apps, the command checks deployment wiring when it sees Junior markers such as `@sentry/junior`, `juniorNitro()`, or app content files. It fails when `nitro.config.ts` omits `juniorNitro()`, because that module emits Junior's heartbeat cron and Vercel Queue trigger into the Nitro build output. It also fails when root `vercel.json` still targets `functions["api/internal/agent/continue.ts"]`; Nitro does not deploy that source file as a Vercel function.
+
+Root `vercel.json` heartbeat crons emit a warning. `juniorNitro()` now emits `/api/internal/heartbeat` into `.vercel/output/config.json`, so keeping the root cron can drift from the deployed Nitro config.
+
 ## Example output
 
 Successful validation:

packages/docs/src/content/docs/extend/scheduler-plugin.md

@@ -32,20 +32,19 @@ import { schedulerPlugin } from "@sentry/junior-scheduler";
 export const plugins = defineJuniorPlugins([schedulerPlugin()]);
 ```
 
-The scaffolded `vercel.json` includes the internal heartbeat route:
-
-```json title="vercel.json"
-{
-  "crons": [
-    {
-      "path": "/api/internal/heartbeat",
-      "schedule": "* * * * *"
-    }
-  ]
-}
+`juniorNitro()` emits the internal heartbeat route into Nitro's Vercel Build Output config:
+
+```ts title="nitro.config.ts"
+import { defineConfig } from "nitro";
+import { juniorNitro } from "@sentry/junior/nitro";
+
+export default defineConfig({
+  preset: "vercel",
+  modules: [juniorNitro()],
+});
 ```
 
-If you manage routes manually, call the heartbeat route on a one-minute cadence:
+If you deploy outside Vercel, call the heartbeat route on a one-minute cadence:
 
 | Route                     | Purpose                         |
 | ------------------------- | ------------------------------- |

packages/docs/src/content/docs/reference/api/functions/createApp.md

@@ -7,7 +7,7 @@ title: "createApp"
 
 > **createApp**(`options?`): `Promise`\<`Hono`\<`BlankEnv`, `BlankSchema`, `"/"`\>\>
 
-Defined in: [app.ts:252](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L252)
+Defined in: [app.ts:259](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L259)
 
 Create a Hono app with all Junior routes.
 

packages/docs/src/content/docs/reference/api/functions/juniorNitro.md

@@ -7,9 +7,9 @@ title: "juniorNitro"
 
 > **juniorNitro**(`options?`): `object`
 
-Defined in: [nitro.ts:183](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L183)
+Defined in: [nitro.ts:258](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L258)
 
-Nitro module that copies app and plugin content into the Vercel build output.
+Nitro module that configures deployment wiring and copies app/plugin content into the Vercel build output.
 
 ## Parameters
 

packages/docs/src/content/docs/reference/api/functions/juniorVercelConfig.md

@@ -9,7 +9,7 @@ title: "juniorVercelConfig"
 
 Defined in: [vercel.ts:6](https://github.com/getsentry/junior/blob/main/packages/junior/src/vercel.ts#L6)
 
-Return a minimal Vercel config for scaffolded Junior apps.
+Return the root Vercel project config for scaffolded Junior apps.
 
 ## Parameters
 

packages/docs/src/content/docs/reference/api/interfaces/JuniorAppOptions.md

@@ -5,32 +5,42 @@ prev: false
 title: "JuniorAppOptions"
 ---
 
-Defined in: [app.ts:48](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L48)
+Defined in: [app.ts:53](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L53)
 
 ## Properties
 
 ### configDefaults?
 
 > `optional` **configDefaults?**: `Record`\<`string`, `unknown`\>
 
-Defined in: [app.ts:50](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L50)
+Defined in: [app.ts:55](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L55)
 
 Install-wide provider defaults (`provider.key` format). Channel overrides take precedence.
 
-***
+---
+
+### conversationWork?
+
+> `optional` **conversationWork?**: `VercelConversationWorkCallbackOptions`
+
+Defined in: [app.ts:57](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L57)
+
+Queue consumer wiring for the durable conversation worker.
+
+---
 
 ### plugins?
 
 > `optional` **plugins?**: [`JuniorPluginSet`](/reference/api/interfaces/juniorpluginset/)
 
-Defined in: [app.ts:52](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L52)
+Defined in: [app.ts:59](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L59)
 
 Direct plugin set override. Usually omitted when `juniorNitro()` uses a plugin module.
 
-***
+---
 
 ### waitUntil?
 
 > `optional` **waitUntil?**: `WaitUntilFn`
 
-Defined in: [app.ts:53](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L53)
+Defined in: [app.ts:60](https://github.com/getsentry/junior/blob/main/packages/junior/src/app.ts#L60)

packages/docs/src/content/docs/reference/api/interfaces/JuniorNitroOptions.md

@@ -5,43 +5,53 @@ prev: false
 title: "JuniorNitroOptions"
 ---
 
-Defined in: [nitro.ts:33](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L33)
+Defined in: [nitro.ts:39](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L39)
 
 ## Properties
 
+### conversationWorkQueueTopic?
+
+> `optional` **conversationWorkQueueTopic?**: `string`
+
+Defined in: [nitro.ts:43](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L43)
+
+Vercel Queue topic for durable conversation work. Must match the runtime queue producer topic.
+
+---
+
 ### cwd?
 
 > `optional` **cwd?**: `string`
 
-Defined in: [nitro.ts:34](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L34)
+Defined in: [nitro.ts:40](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L40)
 
-***
+---
 
 ### includeFiles?
 
 > `optional` **includeFiles?**: `string`[]
 
-Defined in: [nitro.ts:44](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L44)
+Defined in: [nitro.ts:52](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L52)
 
 Extra file patterns to copy into the server output for files that the
 bundler cannot trace (e.g. dynamically imported providers).
 Each entry is `"<package-name>/<subpath-glob>"`, resolved via Node
 module resolution. Example: `"@earendil-works/pi-ai/dist/providers/*.js"`
 
-***
+---
 
 ### maxDuration?
 
 > `optional` **maxDuration?**: `number`
 
-Defined in: [nitro.ts:35](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L35)
+Defined in: [nitro.ts:41](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L41)
 
-***
+---
 
 ### plugins?
 
 > `optional` **plugins?**: `JuniorNitroPluginSource`
 
-Defined in: [nitro.ts:37](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L37)
+Defined in: [nitro.ts:45](https://github.com/getsentry/junior/blob/main/packages/junior/src/nitro.ts#L45)
 
 Plugin catalog set or runtime-safe plugin module. Direct sets must not include trusted hooks.

packages/docs/src/content/docs/start-here/deploy-to-vercel.md

@@ -12,7 +12,7 @@ related:
   - /start-here/verify-and-troubleshoot/
 ---
 
-The scaffolded app is already shaped for Vercel. Deployment mainly means linking the project, setting env vars, enabling the heartbeat cron, enabling snapshot warmup support, and pointing Slack at the production URL.
+The scaffolded app is already shaped for Vercel. Deployment mainly means linking the project, keeping `juniorNitro()` in Nitro config, setting env vars, enabling snapshot warmup support, and pointing Slack at the production URL.
 
 ## Link the project
 
@@ -41,35 +41,26 @@ The scaffolded `package.json` includes the production build script:
 
 Keep the Vercel build command as `pnpm build`. `junior snapshot create` prepares sandbox runtime dependencies declared by enabled plugins before request handling starts.
 
-## Keep Vercel runtime entries
+## Enable Junior's Nitro deployment module
 
-Junior uses a one-minute internal heartbeat to run trusted plugin heartbeats and recover stale agent dispatches. The scheduler plugin uses this heartbeat when scheduled tasks are enabled. The scaffolded `vercel.json` should include these runtime entries:
+Junior uses a one-minute internal heartbeat to run trusted plugin heartbeats and recover stale agent dispatches. Durable agent work is also resumed by a Vercel Queue consumer. Both pieces are emitted by `juniorNitro()` into Nitro's Vercel Build Output config, which is the config Vercel deploys for Nitro apps.
 
-```json title="vercel.json"
-{
-  "framework": "nitro",
-  "buildCommand": "pnpm build",
-  "crons": [
-    {
-      "path": "/api/internal/heartbeat",
-      "schedule": "* * * * *"
-    }
-  ],
-  "functions": {
-    "api/internal/agent/continue.ts": {
-      "maxDuration": 300,
-      "experimentalTriggers": [
-        {
-          "type": "queue/v2beta",
-          "topic": "junior_conversation_work"
-        }
-      ]
-    }
-  }
-}
+Keep `juniorNitro()` installed in `nitro.config.ts`:
+
+```ts title="nitro.config.ts"
+import { defineConfig } from "nitro";
+import { juniorNitro } from "@sentry/junior/nitro";
+
+export default defineConfig({
+  preset: "vercel",
+  modules: [juniorNitro()],
+  routes: {
+    "/**": { handler: "./server.ts" },
+  },
+});
 ```
 
-If you maintain `vercel.json` manually, keep the `/api/internal/heartbeat` cron entry and the queue trigger for `api/internal/agent/continue.ts`. The scaffolded `api/internal/agent/continue.ts` file delegates queue delivery to `server.ts`, and Vercel requires the `functions` key to match a concrete source file.
+Do not configure `functions["api/internal/agent/continue.ts"]` in root `vercel.json`; Nitro does not deploy that source file as a Vercel function. `juniorNitro()` attaches the queue trigger to `/api/internal/agent/continue` with Nitro `vercel.functionRules`, and emits the `/api/internal/heartbeat` cron into `.vercel/output/config.json`.
 
 The heartbeat endpoint returns `401` unless the incoming Vercel Cron request has a bearer token that matches `CRON_SECRET`.
 
@@ -125,11 +116,13 @@ Reinstall the Slack app if scopes changed.
 Run these checks after deployment:
 
 1. `GET https://<your-domain>/health` returns `status: "ok"`.
-2. The Vercel deployment has a cron entry for `/api/internal/heartbeat`.
-3. A Slack mention produces a thread reply in the expected workspace.
-4. App Home opens without an error.
-5. Queue callback and turn logs show successful processing.
-6. One enabled plugin workflow succeeds end to end.
+2. `junior check` passes without deployment config errors.
+3. The Vercel deployment has a cron entry for `/api/internal/heartbeat`.
+4. The Vercel deployment has a Queue trigger for `/api/internal/agent/continue`.
+5. A Slack mention produces a thread reply in the expected workspace.
+6. App Home opens without an error.
+7. Queue callback and turn logs show successful processing.
+8. One enabled plugin workflow succeeds end to end.
 
 ## Next step