fix(scheduler): Harden optional plugin state access

Keep legacy scheduler state access scoped to the scheduler plugin namespace so the migration path does not expose arbitrary raw state prefixes.

Clarify heartbeat docs now that scheduled tasks are enabled by registering the scheduler plugin explicitly.

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

Author: dcramer

apps/example/README.md

@@ -28,12 +28,12 @@ Copy `.env.example` and set:
 - `AI_VISION_MODEL` (optional, enables image-understanding; unset disables vision features)
 - `AI_WEB_SEARCH_MODEL` (optional, overrides the `webSearch` tool model; defaults to a search-tuned model)
 - `JUNIOR_SECRET` (required outside `pnpm dev`; the local wrapper supplies a dev-only secret when unset)
-- `JUNIOR_SCHEDULER_SECRET` or `CRON_SECRET` (optional for `pnpm dev`; the local wrapper supplies a dev-only secret when both are unset)
+- `JUNIOR_SCHEDULER_SECRET` or `CRON_SECRET` (optional for `pnpm dev`; the local wrapper supplies a dev-only heartbeat secret when both are unset)
 - `NOTION_TOKEN` (optional, enables the bundled Notion plugin)
 
 ## Wiring
 
 - `plugin-packages.ts` is the single source of truth for installed plugin packages in this app
 - `nitro.config.ts` passes that list to `juniorNitro()` so plugin content is copied into the build output
 - `server.ts` passes the same list to `createApp()` so local dev does not depend on Nitro's virtual config path for plugin discovery
-- root `pnpm dev` starts a local heartbeat loop that calls `/api/internal/heartbeat` every minute, matching the production cron pulse used by the built-in scheduler plugin; it also defaults `JUNIOR_BASE_URL` to the local server when unset so signed internal callbacks can recover scheduled dispatches
+- root `pnpm dev` starts a local heartbeat loop that calls `/api/internal/heartbeat` every minute, matching the production cron pulse used for trusted plugin heartbeats and stale dispatch recovery; it also defaults `JUNIOR_BASE_URL` to the local server when unset so signed internal callbacks can recover dispatched runs

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

@@ -66,14 +66,14 @@ If you manage routes manually, call the heartbeat route on a one-minute cadence:
 
 ## Configure environment variables
 
-Set one scheduler route secret:
+Set one heartbeat route secret:
 
-| Variable                                   | Required   | Purpose                                                                                       |
-| ------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------- |
-| `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET` | Production | Bearer token for internal scheduler and heartbeat routes. Use `CRON_SECRET` with Vercel Cron. |
-| `JUNIOR_TIMEZONE`                          | No         | Default IANA timezone for schedule authoring. Defaults to `America/Los_Angeles`.              |
+| Variable                                   | Required   | Purpose                                                                            |
+| ------------------------------------------ | ---------- | ---------------------------------------------------------------------------------- |
+| `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET` | Production | Bearer token for the internal heartbeat route. Use `CRON_SECRET` with Vercel Cron. |
+| `JUNIOR_TIMEZONE`                          | No         | Default IANA timezone for schedule authoring. Defaults to `America/Los_Angeles`.   |
 
-Local development can run without a scheduler route secret when you call the dev server directly. Production deployments should set `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET`.
+Local development can run without a heartbeat route secret when you call the dev server directly. Production deployments should set `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET`.
 
 ## Verify
 

packages/docs/src/content/docs/reference/config-and-env.md

@@ -25,8 +25,8 @@ related:
 | `AI_WEB_SEARCH_MODEL`                       | No          | Override for the `webSearch` tool model. Defaults to a search-tuned model; does not fall through to `AI_MODEL`.                                       |
 | `JUNIOR_BASE_URL`                           | No          | Canonical base URL for callback/auth URL generation.                                                                                                  |
 | `JUNIOR_STATE_KEY_PREFIX`                   | No          | Optional namespace prepended to all state-adapter keys, locks, and queues. Use separate prefixes when sharing one Redis database across environments. |
-| `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET`  | Conditional | Bearer token for internal scheduler and heartbeat routes; use `CRON_SECRET` with Vercel Cron, or `JUNIOR_SCHEDULER_SECRET` for an external scheduler. |
-| `JUNIOR_TIMEZONE`                           | No          | Default IANA timezone for scheduler authoring and other timezone-sensitive behavior. Defaults to `America/Los_Angeles`.                               |
+| `CRON_SECRET` or `JUNIOR_SCHEDULER_SECRET`  | Conditional | Bearer token for the internal heartbeat route; use `CRON_SECRET` with Vercel Cron, or `JUNIOR_SCHEDULER_SECRET` for a non-Vercel heartbeat caller.    |
+| `JUNIOR_TIMEZONE`                           | No          | Default IANA timezone for scheduler authoring when the scheduler plugin is enabled. Defaults to `America/Los_Angeles`.                                |
 | `AI_GATEWAY_API_KEY`                        | No          | AI gateway auth if used in your setup.                                                                                                                |
 
 Generate `JUNIOR_SECRET` with Node, then store the generated value in every environment that runs the same app:

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

@@ -43,7 +43,7 @@ Keep the Vercel build command as `pnpm build`. `junior snapshot create` prepares
 
 ## Enable the heartbeat cron
 
-Junior uses a one-minute internal heartbeat to run scheduled tasks and recover stale agent dispatches. The scaffolded `vercel.json` should include this cron:
+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 this cron:
 
 ```json title="vercel.json"
 {

packages/junior/src/chat/plugins/agent-hooks.ts

@@ -41,6 +41,33 @@ let agentPlugins: JuniorPlugin[] = [];
 const AGENT_PLUGIN_NAME_RE = /^[a-z][a-z0-9-]*$/;
 const AGENT_PLUGIN_TOOL_NAME_RE = /^[a-z][A-Za-z0-9]*$/;
 
+function validateLegacyStatePrefixes(plugin: JuniorPlugin): void {
+  const prefixes = plugin.pluginConfig?.legacyStatePrefixes;
+  if (prefixes === undefined) {
+    return;
+  }
+  if (!Array.isArray(prefixes)) {
+    throw new Error(
+      `Trusted plugin "${plugin.name}" legacyStatePrefixes must be an array`,
+    );
+  }
+
+  const allowedPrefix = `junior:${plugin.name}`;
+  for (const rawPrefix of prefixes) {
+    const prefix = typeof rawPrefix === "string" ? rawPrefix.trim() : "";
+    if (!prefix) {
+      throw new Error(
+        `Trusted plugin "${plugin.name}" legacy state prefixes must be non-empty strings`,
+      );
+    }
+    if (prefix !== allowedPrefix && !prefix.startsWith(`${allowedPrefix}:`)) {
+      throw new Error(
+        `Trusted plugin "${plugin.name}" legacy state prefix "${prefix}" must stay under "${allowedPrefix}"`,
+      );
+    }
+  }
+}
+
 /** Validate trusted plugin identity before it can affect process-wide hooks. */
 export function validateAgentPlugins(plugins: JuniorPlugin[]): void {
   const seen = new Set<string>();
@@ -54,6 +81,7 @@ export function validateAgentPlugins(plugins: JuniorPlugin[]): void {
       throw new Error(`Duplicate trusted plugin name "${plugin.name}"`);
     }
     seen.add(plugin.name);
+    validateLegacyStatePrefixes(plugin);
   }
 }
 

packages/junior/tests/unit/app-config.test.ts

@@ -250,4 +250,26 @@ describe("createApp plugin config", () => {
     expect(getAgentPlugins().map((plugin) => plugin.name)).toEqual([]);
     expect(getPluginProviders()).toEqual([]);
   });
+
+  it("rejects legacy state prefixes outside the trusted plugin namespace", async () => {
+    await createApp({
+      plugins: [],
+    });
+
+    await expect(
+      createApp({
+        plugins: [
+          defineJuniorPlugin({
+            name: "trusted",
+            pluginConfig: { legacyStatePrefixes: ["junior:scheduler"] },
+          }),
+        ],
+      }),
+    ).rejects.toThrow(
+      'Trusted plugin "trusted" legacy state prefix "junior:scheduler" must stay under "junior:trusted"',
+    );
+
+    expect(getAgentPlugins().map((plugin) => plugin.name)).toEqual([]);
+    expect(getPluginProviders()).toEqual([]);
+  });
 });