@junejs/server 1.0.0-dev.36 → 1.0.0-dev.45

package/src/agent-native.ts

@@ -13,6 +13,7 @@ import {
   withSystem,
   type ChannelPolicy,
   type EventSink,
+  type InputAnnouncement,
   type TurnEvent,
   type Model,
   type Msg,
@@ -92,7 +93,7 @@ class SqliteSessionStore implements SessionStore {
   // generation (audit trail — never deleted), clear the live rows, status → "new".
   // Archive tables + the generation counter are created lazily here, so existing
   // databases stay untouched until the first reset.
-  reset(): number {
+  reset(inTx?: () => void): number {
     return this.tx(() => {
       this.db.exec(`CREATE TABLE IF NOT EXISTS agent_messages_archive (session_id TEXT, generation INTEGER, seq INTEGER, body TEXT)`);
       this.db.exec(`CREATE TABLE IF NOT EXISTS agent_steps_archive (session_id TEXT, generation INTEGER, id TEXT, output TEXT)`);
@@ -105,6 +106,7 @@ class SqliteSessionStore implements SessionStore {
       this.db.query("DELETE FROM agent_steps WHERE session_id = ?").run(this.sid);
       this.db.query("INSERT INTO agent_sessions (session_id, status) VALUES (?, 'new') ON CONFLICT(session_id) DO UPDATE SET status = 'new'").run(this.sid);
       this.db.query("INSERT INTO agent_session_generations (session_id, generation) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET generation = ?").run(this.sid, generation + 1, generation + 1);
+      inTx?.(); // writes into the fresh generation, committed with the archive (#260)
       return generation;
     });
   }
@@ -120,7 +122,82 @@ class InProcEventSink implements EventSink {
 
 // `instructions` (the agent's system prompt) is injected into the model per turn
 // by the runtime (withSystem) — single-sourced on the def, not baked into `model`.
-export type AgentDef = { model: Model; tools: Tool[]; instructions?: string; channelInstructions?: Record<string, string | ChannelPolicy> };
+export type AgentDef = {
+  model: Model;
+  tools: Tool[];
+  instructions?: string;
+  channelInstructions?: Record<string, string | ChannelPolicy>;
+  // The app's receiver for input announcements (#260), installed on every session this
+  // runtime builds; undelivered announcements from an earlier process are flushed then.
+  onInputAnnouncement?: (a: InputAnnouncement) => void | Promise<void>;
+};
+
+// Retries a failed announcement delivery on a timer (#260): the engine keeps an undelivered
+// announcement and flushes again on the next announcement, settled turn or rebuild — but a
+// session that goes quiet would hold it until then. 5 s doubling to 5 min, per session;
+// unref'd, so a pending retry never holds the process open. Owned by the runtime, so the
+// backoff survives an evicted-and-rebuilt actor.
+class AnnouncementRetry {
+  // Explicit fields (not parameter properties) — keep the shipped source erasable.
+  private readonly flush: (agent: string, id: string) => void;
+  private readonly state = new Map<string, { failures: number; timer?: ReturnType<typeof setTimeout> }>();
+  private stopped = false;
+  constructor(flush: (agent: string, id: string) => void) {
+    this.flush = flush;
+  }
+  delivered(key: string) {
+    const s = this.state.get(key);
+    if (s?.timer) clearTimeout(s.timer);
+    this.state.delete(key);
+  }
+  failed(key: string, agent: string, id: string) {
+    if (this.stopped) return; // the runtime is closed: nothing retries into it
+    const s = this.state.get(key) ?? { failures: 0 };
+    this.state.set(key, s);
+    if (s.timer) return; // one retry pending at a time
+    const delay = Math.min(5_000 * 2 ** s.failures, 300_000);
+    s.failures++;
+    s.timer = setTimeout(() => { s.timer = undefined; this.flush(agent, id); }, delay);
+    (s.timer as { unref?: () => void }).unref?.();
+  }
+  // Cancel every pending retry, for good (#317): unref only keeps a timer from holding the
+  // process open — it still fires while the process lives, into a runtime (and a db) that
+  // is gone.
+  stop() {
+    this.stopped = true;
+    for (const s of this.state.values()) if (s.timer) clearTimeout(s.timer);
+    this.state.clear();
+  }
+}
+
+// SQLite handles a runtime opened itself (createNativeRuntime), so close() closes those and
+// never one a caller passed in.
+const ownedDbs = new WeakSet<SyncSqlite>();
+
+// Install the announcement hook on a freshly built session and deliver what an earlier life
+// of it recorded but never delivered (#260). The flush never rejects; it logs — and a
+// failure schedules a retry.
+function wireAnnouncements(session: AgentSession, def: AgentDef, retry: AnnouncementRetry): AgentSession {
+  const hook = def.onInputAnnouncement;
+  if (hook) {
+    const key = `${session.agent}:${session.id}`;
+    session.onAnnounce = async (a) => {
+      try {
+        await hook(a);
+      } catch (err) {
+        retry.failed(key, session.agent, session.id);
+        throw err; // the engine keeps the announcement and logs
+      }
+      retry.delivered(key);
+    };
+    void session.flushAnnouncements();
+  }
+  return session;
+}
+
+// The step the engine keeps its announcement outbox under (#260) — read by the native
+// runtime's startup scan. Mirrors ANNOUNCE_OUTBOX in @junejs/core/agent-runtime.
+const ANNOUNCE_OUTBOX_STEP = "announce-outbox";
 
 // The runtime-side def for an assembled AgentDefinition (#173): the tools (channel
 // capability tools and read_skill included), the system prompt (instructions + the
@@ -134,6 +211,7 @@ export function toAgentDef(agent: AgentDefinition, model: Model): AgentDef {
     tools: agent.tools,
     instructions: buildSystemPrompt(agent),
     ...(agent.channelInstructions ? { channelInstructions: agent.channelInstructions } : {}),
+    ...(agent.onInputAnnouncement ? { onInputAnnouncement: agent.onInputAnnouncement } : {}),
   };
 }
 
@@ -156,7 +234,10 @@ export class NativeRuntime implements Runtime {
   private actors = new Map<string, { session: AgentSession; sink: InProcEventSink }>();
   private readonly agents: Record<string, AgentDef>;
   private readonly db: SyncSqlite;
+  // Retries failed announcement deliveries (#260), across actor rebuilds.
+  private readonly announceRetry = new AnnouncementRetry((agent, id) => { void this.session(agent, id).flushAnnouncements(); });
   private readonly maxSessions: number;
+  private closing: Promise<void> | undefined; // set by close() (#317)
 
   constructor(agents: Record<string, AgentDef>, db: SyncSqlite, opts: NativeRuntimeOptions = {}) {
     assertCoreRuntimeVersion("NativeRuntime"); // #94: fail power-on, not mid-turn
@@ -178,6 +259,9 @@ export class NativeRuntime implements Runtime {
   session(agent: string, id: string): AgentSession {
     const key = `${agent}:${id}`;
     const hit = this.actors.get(key);
+    // A closing runtime still serves the actors it has (their turns are finishing), but
+    // builds no new one.
+    if (!hit && this.closing) throw new Error(`NativeRuntime is closed: cannot open session "${key}"`);
     if (hit) {
       // most recently used → the tail (Map iteration order is insertion order)
       this.actors.delete(key);
@@ -188,7 +272,7 @@ export class NativeRuntime implements Runtime {
     if (!def) throw new Error(`unknown agent: ${agent}`);
     const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
     const sink = new InProcEventSink();
-    const session = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions);
+    const session = wireAnnouncements(new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions), def, this.announceRetry);
     this.evictIdle();
     this.actors.set(key, { session, sink });
     return session;
@@ -197,6 +281,42 @@ export class NativeRuntime implements Runtime {
   // Number of memoized actors (observability / tests).
   get sessionCount(): number { return this.actors.size; }
 
+  // Deliver announcements an earlier process recorded but never delivered (#260), without
+  // waiting for their sessions to be used again: build every session whose outbox is not
+  // empty — building one flushes it. The agent and session come from the announcement
+  // itself, not from splitting the store key (an agent name may contain ":"). Called once
+  // by createNativeRuntime; safe to call again.
+  recoverAnnouncements(): void {
+    const rows = this.db.query("SELECT output FROM agent_steps WHERE id = ?").all(ANNOUNCE_OUTBOX_STEP) as { output: string }[];
+    for (const { output } of rows) {
+      const [first] = JSON.parse(output) as InputAnnouncement[];
+      if (first && this.agents[first.agent]?.onInputAnnouncement) this.session(first.agent, first.session);
+    }
+  }
+
+  // Shut the runtime down (#317). Pending announcement retries are cancelled and no new
+  // session opens at once; then it waits until every actor is idle — a running turn or an
+  // announcement delivery in flight still writes the store after its hook or model call
+  // returns — before dropping the actors and closing the SQLite handle createNativeRuntime
+  // opened (a db passed to the constructor stays the caller's). So it resolves only after
+  // in-flight work finishes. Call it before discarding a runtime in a process that keeps
+  // running (a test suite, a host that swaps runtimes), or a retry fires later against a
+  // closed or deleted database. Safe to call twice: both calls resolve together.
+  close(): Promise<void> {
+    this.closing ??= (async () => {
+      this.announceRetry.stop();
+      while ([...this.actors.values()].some((a) => !a.session.idle())) {
+        await new Promise((r) => setTimeout(r, 10));
+      }
+      this.actors.clear();
+      if (ownedDbs.has(this.db)) {
+        ownedDbs.delete(this.db);
+        this.db.close();
+      }
+    })();
+    return this.closing;
+  }
+
   // Drop least recently used idle actors until one more fits under the cap. Runs before
   // the new actor is inserted, so the actor being handed out is never a candidate.
   private evictIdle() {
@@ -216,7 +336,24 @@ export async function createNativeRuntime(
   path = ":memory:",
   opts: NativeRuntimeOptions = {},
 ): Promise<NativeRuntime> {
-  return new NativeRuntime(agents, await openLocalSqliteSync(path), opts);
+  const db = await openLocalSqliteSync(path);
+  ownedDbs.add(db);
+  let runtime: NativeRuntime | undefined;
+  try {
+    runtime = new NativeRuntime(agents, db, opts);
+    runtime.recoverAnnouncements(); // #260
+    return runtime;
+  } catch (err) {
+    // Nobody else holds this handle (a bad maxSessions, unreadable leftovers). A recovery
+    // that failed part-way may already have deliveries in flight, so go through close(),
+    // which waits for them before closing the db.
+    if (runtime) await runtime.close();
+    else {
+      ownedDbs.delete(db);
+      db.close();
+    }
+    throw err;
+  }
 }
 
 // ── memory backend — in-process, ephemeral (no DB, no disk) ───────────────────
@@ -242,12 +379,13 @@ class MemorySessionStore implements SessionStore {
   getStatus(): string { return this.status; }
   setStatus(s: string) { this.status = s; }
   tx<T>(fn: () => T): T { return fn(); } // no rollback: an in-memory store is not a durability tier
-  reset(): number {
+  reset(inTx?: () => void): number {
     const generation = this.generation++;
     this.archives.push({ generation, msgs: this.msgs, steps: this.steps });
     this.msgs = [];
     this.steps = new Map();
     this.status = "new";
+    inTx?.(); // writes into the fresh generation (#260)
     return generation;
   }
   unwrap<H = unknown>(): H { return undefined as unknown as H; }
@@ -257,6 +395,8 @@ export class MemoryRuntime implements Runtime {
   private actors = new Map<string, AgentSession>();
   private stores = new Map<string, MemorySessionStore>();
   private readonly agents: Record<string, AgentDef>;
+  private readonly announceRetry = new AnnouncementRetry((agent, id) => { void this.session(agent, id).flushAnnouncements(); }); // #260
+  private closed = false; // set by close() (#317)
   constructor(agents: Record<string, AgentDef>) {
     assertCoreRuntimeVersion("MemoryRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
@@ -266,17 +406,28 @@ export class MemoryRuntime implements Runtime {
     const key = `${agent}:${id}`;
     let a = this.actors.get(key);
     if (!a) {
+      if (this.closed) throw new Error(`MemoryRuntime is closed: cannot open session "${key}"`);
       const def = this.agents[agent];
       if (!def) throw new Error(`unknown agent: ${agent}`);
       const store = new MemorySessionStore();
       this.stores.set(key, store);
       // Same def handling as NativeRuntime: switching backend must not change behavior.
       const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-      a = new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions);
+      a = wireAnnouncements(new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions), def, this.announceRetry);
       this.actors.set(key, a);
     }
     return a;
   }
+  // Shut the runtime down (#317): cancel pending announcement retries and open no new
+  // session. The state is the actors themselves, so they are dropped too; with no store
+  // to close there is nothing to wait for — work still in flight finishes against its own
+  // in-memory store. Safe to call twice.
+  async close(): Promise<void> {
+    this.closed = true;
+    this.announceRetry.stop();
+    this.actors.clear();
+    this.stores.clear();
+  }
 }
 
 // The selectable agent-runtime backends. `native` (SQLite via june/host, durable
@@ -288,10 +439,13 @@ export type AgentBackend = "native" | "memory" | "durable";
 // Build an in-process runtime for the chosen backend. Throws for `durable` (that
 // target is the DO the worker constructs, not an in-process object) — so the
 // choice is explicit and a mis-selection fails loudly.
+// An in-process runtime: a Runtime the host owns, so it can shut it down (#317).
+export type InProcessRuntime = Runtime & { close(): Promise<void> };
+
 export async function createAgentRuntime(
   agents: Record<string, AgentDef>,
   opts: { backend?: AgentBackend; path?: string; maxSessions?: number } = {},
-): Promise<Runtime> {
+): Promise<InProcessRuntime> {
   const backend = opts.backend ?? "native";
   if (backend === "memory") return new MemoryRuntime(agents);
   if (backend === "native") return createNativeRuntime(agents, opts.path, { maxSessions: opts.maxSessions });

package/src/app.ts

@@ -27,9 +27,10 @@ import type { DocumentConfig } from "@junejs/core/document";
 import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
 
 import { findMiddlewareFile, isResourceFile, listRoutes, matchRouteTree, resolveNotFound, routeFiles, type SegmentMatch } from "./router";
+import { routeProblems, scanRoutes } from "./route-scan";
 import { createPipeline, type ExtraHandler, type LayoutComponent, type MiddlewareHandler, type Pipeline, type Resolved, type ResourceHandler } from "./pipeline";
 import { discoverAgent } from "./agent-discover";
-import { createAgentRuntime, mountAgent, toAgentDef } from "./agent-native";
+import { createAgentRuntime, mountAgent, toAgentDef, type InProcessRuntime } from "./agent-native";
 import { anthropic } from "@junejs/core/agent-models";
 import { resolveBoundary } from "./segment";
 import { memoizeResources } from "./resources";
@@ -65,6 +66,10 @@ export type JuneApp = {
   warmup(): Promise<void>;
   routePaths(): Promise<string[]>;
   earlyHints(): string[];
+  // Shut down what the app started (#317): the agent runtime built for an agent/
+  // directory — its pending announcement retries, its in-flight turns, its SQLite
+  // handle. Resolves once they finish. A no-op when no runtime was built.
+  close(): Promise<void>;
 };
 
 // Import a layout file's default export as a layout component (memoized), plus
@@ -226,6 +231,8 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
   // pipeline is built lazily on first fetch, memoized after.
   let pipelinePromise: Promise<Pipeline> | undefined;
   const getPipeline = (): Promise<Pipeline> => (pipelinePromise ??= buildPipeline());
+  // The agent runtime buildPipeline creates, kept so close() can shut it down (#317).
+  let agentRuntime: InProcessRuntime | undefined;
   async function buildPipeline(): Promise<Pipeline> {
     // Wire CSS Modules BEFORE any route import: the runtime interceptor must be
     // active so `import "x.module.css"` in a route resolves to the scoped map,
@@ -264,6 +271,7 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       // toAgentDef: tools, prompt AND the per-surface policies (#149) from the one
       // definition — channelInstructions was previously dropped on this path (#173).
       const rt = await createAgentRuntime({ [def.name]: toAgentDef(def, model) }, { backend });
+      agentRuntime = rt;
       const mounted = mountAgent(def, rt, { chatPath: agent.runtime.chat.path, channels: agent.runtime.channels });
       agentSurface = (req) => mounted.surface(req);
       await mounted.startAll();
@@ -443,6 +451,13 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
       return toPipeline();
     },
     async warmup() {
+      // What `june build` refuses (same-path files, a segment after an optional
+      // or catch-all), dev reports up front — it still serves what it can.
+      const problems = routeProblems(
+        [await scanRoutes(appDir), hasJuneRoutes ? await scanRoutes(juneRoutesDir) : []],
+        dirname(appDir),
+      );
+      if (problems) console.error(problems);
       const files = await routeFiles(appDir, { pageConvention: true });
       if (hasJuneRoutes) files.push(...(await routeFiles(juneRoutesDir, { pageConvention: true })));
       for (const file of files) {
@@ -453,5 +468,11 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
     },
     routePaths,
     earlyHints: () => config.earlyHints ?? [],
+    async close() {
+      // A pipeline still being built may be about to create the runtime: let it finish
+      // (its failure is the fetch's to report, not close()'s).
+      await pipelinePromise?.catch(() => {});
+      await agentRuntime?.close();
+    },
   };
 }

package/src/build.ts

@@ -300,6 +300,12 @@ export async function juneBuild(
   const resourceRoutesField = resources.length
     ? `\n  resourceRoutes: [\n${resources.join("\n")}\n  ],`
     : "";
+  // .june/routes/ patterns rank after every app/ route (dev falls back to them).
+  // Only emitted when there are some, so bundles without them stay byte-identical.
+  const generatedPaths = routes.filter((r) => r.generated).map((r) => r.path);
+  const generatedRoutesField = generatedPaths.length
+    ? `\n  generatedRoutes: ${JSON.stringify(generatedPaths)},`
+    : "";
   // Only emitted when some route declares a boundary, so boundary-less bundles
   // stay byte-identical (additive manifest field, like resources).
   const layoutBoundariesField = boundaries.length
@@ -417,6 +423,10 @@ export class JuneAgentDO extends DurableObject {
   fetch(req: Request): Promise<Response> {
     return this.#agent.fetch(req);
   }
+  // Delivers input announcements left undelivered — a failed hook's retry, or the watchdog (#260).
+  alarm(): Promise<void> {
+    return this.#agent.alarm();
+  }
 }
 `
     : "";
@@ -431,7 +441,7 @@ ${statics.join("\n")}
   },
   dynamicRoutes: [
 ${dynamics.join("\n")}
-  ],${resourceRoutesField}
+  ],${resourceRoutesField}${generatedRoutesField}
   layoutChains: {
 ${chains.join("\n")}
   },${layoutBoundariesField}

package/src/core-version.ts

@@ -15,7 +15,7 @@ import * as coreRuntime from "@junejs/core/agent-runtime";
 
 // The contract number this server tree is built against. Bump in lockstep with
 // core's RUNTIME_API_VERSION whenever the server↔core runtime contract changes.
-const EXPECTED_CORE_RUNTIME_API = 2;
+const EXPECTED_CORE_RUNTIME_API = 6;
 
 export function assertCoreRuntimeVersion(surface: string): void {
   checkCoreRuntimeVersion(surface, (coreRuntime as { RUNTIME_API_VERSION?: number }).RUNTIME_API_VERSION);

package/src/dev.ts

@@ -19,20 +19,41 @@ import { findGlobalCss, processCssCached, invalidateCss } from "./css";
 export type DevServerOptions = {
   appDir: string;
   port?: number;
+  // The address to bind. Default 127.0.0.1: the dev server is reachable from this
+  // machine only (MCP: "when running locally, servers SHOULD bind only to
+  // localhost"). "0.0.0.0" opens it to the LAN — `june dev --host`.
+  hostname?: string;
   host?: JuneHost;
 };
 
-export type DevServer = ServeHandle & { url: string };
+// The Host names a dev server answers /mcp and /api for (#308): localhost and its
+// subdomains, plus IP literals (always allowed — rebinding needs a domain name),
+// plus a named --host and whatever the config allows.
+// The URL to print and return: localhost for loopback or a wildcard bind (it
+// answers there too), else the one address bound — nothing listens on loopback then.
+export function devUrl(hostname: string, port: number): string {
+  if (["127.0.0.1", "0.0.0.0", "::", "localhost"].includes(hostname)) return `http://localhost:${port}`;
+  return `http://${hostname.includes(":") ? `[${hostname}]` : hostname}:${port}`;
+}
+
+export function devAllowedHosts(configured: readonly string[] | undefined, hostname: string): string[] {
+  const hosts = new Set(["localhost", ".localhost", ...(configured ?? [])]);
+  if (!/^[\d.]+$|:/.test(hostname)) hosts.add(hostname.toLowerCase()); // a name, not 0.0.0.0 / an IP
+  return [...hosts];
+}
+
+// stop() also shuts the app down (its agent runtime, #317); await it to know that's done.
+export type DevServer = Omit<ServeHandle, "stop"> & { url: string; stop(force?: boolean): Promise<void> };
 
 // A taken default port must not be a dead end in dev — walk forward until a
 // port binds (the Vite convention). Probed with node:net, which both hosts
 // implement, so the host interface stays untouched.
-async function findFreePort(start: number, tries = 20): Promise<number> {
+async function findFreePort(start: number, hostname: string, tries = 20): Promise<number> {
   for (let p = start; p < start + tries; p++) {
     const free = await new Promise<boolean>((resolve) => {
       const probe = createNetServer();
       probe.once("error", () => resolve(false));
-      probe.listen(p, () => probe.close(() => resolve(true)));
+      probe.listen(p, hostname, () => probe.close(() => resolve(true)));
     });
     if (free) return p;
   }
@@ -42,10 +63,13 @@ async function findFreePort(start: number, tries = 20): Promise<number> {
 export async function startDevServer({
   appDir,
   port = 3000,
+  hostname = "127.0.0.1",
   host = defaultHost,
 }: DevServerOptions): Promise<DevServer> {
   await installAsyncContext();
-  const config = await loadJuneConfig(appDir);
+  const loaded = await loadJuneConfig(appDir);
+  // The DNS-rebinding check (#308): a local server is exactly what rebinding targets.
+  const config = { ...loaded, agent: { ...loaded.agent, allowedHosts: devAllowedHosts(loaded.agent?.allowedHosts, hostname) } };
 
   // Apply pending migrations before serving — dev auto-applies the SAFE ones; a
   // destructive one is reported and skipped (the server still starts, but the
@@ -57,7 +81,7 @@ export async function startDevServer({
   const app = createApp({ appDir, config });
   await app.warmup();
 
-  const freePort = await findFreePort(port);
+  const freePort = await findFreePort(port, hostname);
   if (freePort !== port) console.log(`[june] port ${port} is taken → using ${freePort}`);
   port = freePort;
 
@@ -65,6 +89,7 @@ export async function startDevServer({
   // dev/built parity) never sees it. See dev-reload.ts.
   const handle = host.serve(withLiveReload((req) => app.fetch(req)), {
     port,
+    hostname,
     earlyHints: () => app.earlyHints(),
   });
 
@@ -87,7 +112,15 @@ export async function startDevServer({
     void processCssCached(appDir).catch(() => {});
   }
 
-  const url = `http://localhost:${handle.port}`;
-  console.log(`june dev → ${url}  (host: ${host.name})`);
-  return { ...handle, url };
+  const url = devUrl(hostname, handle.port);
+  const lan = hostname === "127.0.0.1" ? "" : `  · listening on ${hostname}`;
+  console.log(`june dev → ${url}  (host: ${host.name})${lan}`);
+  return {
+    ...handle,
+    url,
+    async stop(force?: boolean) {
+      handle.stop(force);
+      await app.close();
+    },
+  };
 }

package/src/host.ts

@@ -42,7 +42,8 @@ export interface JuneHost {
   readonly name: "bun" | "node";
   serve(
     handler: (req: Request) => Promise<Response>,
-    opts: { port: number; earlyHints?: () => string[] },
+    // hostname: the address to bind. Absent = all interfaces (production, containers).
+    opts: { port: number; hostname?: string; earlyHints?: () => string[] },
   ): ServeHandle;
   // Spawn a module in a child runtime (the react-server Flight renderer, which
   // must run under a different module-resolution condition). Phase 4 supersedes
@@ -63,7 +64,7 @@ function bunHost(): JuneHost {
       // idleTimeout 0: Bun's 10s default kills quiet long-lived responses —
       // the dev live-reload SSE most visibly (the browser then reconnects,
       // reads it as a server restart, and reloads the page every 10s).
-      const server = Bun.serve({ port: opts.port, fetch: handler, idleTimeout: 0 });
+      const server = Bun.serve({ port: opts.port, hostname: opts.hostname, fetch: handler, idleTimeout: 0 });
       return { port: server.port ?? opts.port, stop: (force) => void server.stop(force) };
     },
     spawnModule(entry, args, opts) {
@@ -125,7 +126,7 @@ function nodeHost(): JuneHost {
           res.end("Internal Server Error");
         }
       });
-      server.listen(opts.port);
+      server.listen(opts.port, opts.hostname);
       return {
         get port() {
           const addr = server.address();

package/src/manifest.ts

@@ -63,6 +63,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
   const routes: Record<string, BrandedRoute> = {};
   const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
   const resourceRoutes: Array<{ pattern: string; handler: ResourceHandler }> = [];
+  const generatedRoutes = scanned.filter((r) => r.generated).map((r) => r.path);
   const layoutChains: Record<string, LayoutComponent[]> = {};
   const layoutBoundaries: Record<string, { index: number; key: string }> = {};
   const loadings: Record<string, LoadingComponent> = {};
@@ -115,6 +116,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     routes,
     dynamicRoutes,
     resourceRoutes,
+    ...(generatedRoutes.length ? { generatedRoutes } : {}),
     layoutChains,
     layoutBoundaries,
     loadings,

package/src/pipeline.ts

@@ -48,9 +48,10 @@ import {
   siteSkill,
   sitemapXml,
 } from "@junejs/core/discovery";
-import { mcpHandler, mcpServerIdentity, mcpTools } from "@junejs/core/mcp";
+import { mcpForbidden, mcpHandler, mcpServerIdentity, mcpTools, originRejection } from "@junejs/core/mcp";
 import {
   apiActionId,
+  apiForbidden,
   apiHandler,
   apiNamespaceResponse,
   isApiNamespace,
@@ -854,6 +855,14 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     }
   }
 
+  // Which browsers may call /mcp and /api (#308) — the config's allowlists.
+  const originPolicy = { allowedOrigins: agent.allowedOrigins, allowedHosts: agent.allowedHosts };
+  // Only a POST runs an action on /mcp or /api; any other method is a CORS
+  // preflight or a 405. A preflight carries no credentials, so a cookie-reading
+  // resolver could throw on it — never resolve identity for one.
+  const callerIdentity = async (request: Request) =>
+    request.method === "POST" && cfg.identity ? await cfg.identity(request) : undefined;
+
   async function handleRequest(request: Request): Promise<Response> {
       const url = new URL(request.url);
 
@@ -864,11 +873,16 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         // ambient `db` is the SAME resource the UI uses, and — via cfg.identity —
         // the same principal: requiresPrincipal actions and per-call connection
         // auth are live on this surface. ctx carries identity only — not resources.
-        const identity = cfg.identity ? await cfg.identity(request) : undefined;
+        // The origin policy first: a refused browser call must not reach the
+        // identity resolver (its I/O, or a throw that would turn 403 into 500).
+        const refused = originRejection(request, originPolicy);
+        if (refused !== undefined) return mcpForbidden(refused);
+        const identity = await callerIdentity(request);
         return mcpHandler(
           request,
           { request, ...identity },
           mcpServerIdentity(url.origin, { site: docConfig.site, agent }),
+          originPolicy,
         );
       }
       // The REST projection of the same actions: POST /api/<id> dispatches through
@@ -887,8 +901,10 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         }
         const actionId = apiActionId(url.pathname);
         if (actionId) {
-          const identity = cfg.identity ? await cfg.identity(request) : undefined;
-          return apiHandler(request, actionId, { request, ...identity });
+          const refused = originRejection(request, originPolicy);
+          if (refused !== undefined) return apiForbidden(request, refused);
+          const identity = await callerIdentity(request);
+          return apiHandler(request, actionId, { request, ...identity }, originPolicy);
         }
       }
       // The server card is read cross-origin by browser-based MCP clients; its

package/src/route-rank.ts

@@ -0,0 +1,60 @@
+// Route precedence — the ONE ranking both resolvers use (#312). The dev matcher
+// (router.ts, matchRouteTree) walks the app tree trying each level's children in
+// this order; the built worker (worker.ts) cannot walk a tree, so it sorts its
+// flat route table with compareRoutePatterns and takes the first regex match.
+// For patterns that both match a URL, the depth-first walk and the sorted table
+// pick the same winner: the first segment where two patterns differ decides.
+//
+// Worker-safe: no node:* imports.
+
+export type SegmentKind = "static" | "param" | "optional" | "catchAll" | "optionalCatchAll";
+
+// The one segment grammar: a param name is an identifier ([A-Za-z_][A-Za-z0-9_]*).
+// Anything else in brackets (`[1]`, `[foo-bar]`, `[slug].png`) is a STATIC
+// segment named literally, in dev, in the ranking and in the worker's regex.
+const DYNAMIC = /^\[(\[)?(\.\.\.)?([A-Za-z_][A-Za-z0-9_]*)\](\])?$/;
+
+export function parseSegment(segment: string): { kind: SegmentKind; name?: string } {
+  const m = segment.match(DYNAMIC);
+  // Brackets must pair: `[[x]]` or `[x]`, never `[[x]` / `[x]]`.
+  if (!m || !!m[1] !== !!m[4]) return { kind: "static" };
+  const optional = !!m[1];
+  const catchAll = !!m[2];
+  const kind: SegmentKind = catchAll
+    ? optional ? "optionalCatchAll" : "catchAll"
+    : optional ? "optional" : "param";
+  return { kind, name: m[3] };
+}
+
+const RANK: Record<SegmentKind, number> = { static: 0, param: 1, optional: 2, catchAll: 3, optionalCatchAll: 4 };
+
+// Per-segment rank, most specific first: static, [param], [[param]], [...rest],
+// [[...rest]]. Optional sits after its required form, so `[slug]` answers
+// before `[[slug]]` when a segment is present.
+export function segmentRank(segment: string): number {
+  return RANK[parseSegment(segment).kind];
+}
+
+// Sibling order within one directory level: by rank, then by name so a tie
+// (two [param] dirs) resolves the same on every filesystem.
+export function compareSegments(a: string, b: string): number {
+  return segmentRank(a) - segmentRank(b) || (a < b ? -1 : a > b ? 1 : 0);
+}
+
+// Order two file-route patterns ("/docs/[[...path]]", "/feed.xml") by
+// precedence. The first differing segment decides; a pattern that ends there
+// beats one that continues, since only absent optional segments can follow a
+// match that already consumed the URL (dev checks a directory's own page before
+// descending into its optional children).
+export function compareRoutePatterns(a: string, b: string): number {
+  const as = a.split("/").filter(Boolean);
+  const bs = b.split("/").filter(Boolean);
+  for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+    const x = as[i];
+    const y = bs[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    if (x !== y) return compareSegments(x, y);
+  }
+  return 0;
+}