theokit 0.48.14 → 0.50.1

package/dist/{chunk-FTFN4MYN.js → chunk-7AEBH52I.js}

@@ -1,7 +1,13 @@
+import {
+  resolveTheoRootDir
+} from "./chunk-VQPHPQ5L.js";
 import {
   buildServicesProxyConfig,
   servicesConfigSchema
 } from "./chunk-SSYDEKWF.js";
+import {
+  dispatchControllerRequest
+} from "./chunk-RJJF457I.js";
 import {
   broadcastToDevtools
 } from "./chunk-OIGJOYX6.js";
@@ -9,38 +15,53 @@ import {
   RUN_ID_HEADER,
   SSE_BASE_HEADERS,
   SSE_DONE_FRAME,
-  dispatchControllerRequest,
+  admitAgentRequest,
+  agentAccessDenied,
+  cacheSchema,
+  closePauseSpan,
+  createObservabilityPluginFromConfig,
   encodeSse,
   formatSseFrame,
   getApprovalRegistry,
   getRunEventCache,
+  loggingSchema,
   makeThreadStartRun,
   mintRunId,
   mountAgent,
-  parseAgentRequestBody
-} from "./chunk-KTKTHIUF.js";
+  observabilitySchema,
+  parseAgentRequestBody,
+  rateLimitSchema,
+  readAgentPolicy,
+  securitySchema,
+  storageSchema,
+  uploadSchema
+} from "./chunk-KOS567NB.js";
+import {
+  loadEnv
+} from "./chunk-4X6H2BXP.js";
 import {
-  loadEnv,
   resolveTransformer
-} from "./chunk-XR74JD4M.js";
+} from "./chunk-OGLS76RN.js";
 import {
   BATCH_PATH,
-  TRACE_HEADER,
   createCorsHandler,
+  createServerContext,
+  createWebRequestSource,
   executeAction,
   executeRoute,
-  extractTraceId,
   handleBatchRequest,
   incomingMessageToHandlerRequest,
-  incomingMessageToWebRequest,
-  sendError
-} from "./chunk-XALU5LCU.js";
+  sendError,
+  writeWebResponseToServerResponse
+} from "./chunk-JKF25N73.js";
 import {
   findSuggestion
 } from "./chunk-NTDN54XO.js";
 import {
+  TRACE_HEADER,
+  extractTraceId,
   logRequest
-} from "./chunk-KD5G3YXI.js";
+} from "./chunk-DOI4G4X3.js";
 import {
   createPluginRunnerFromConfig
 } from "./chunk-VSLTKX5L.js";
@@ -49,24 +70,26 @@ import {
 } from "./chunk-TNI4MARH.js";
 import {
   createViteLoader
-} from "./chunk-7LVM22VG.js";
+} from "./chunk-OQCRCXCP.js";
 import {
   matchRoute,
-  scanAgents,
   scanServerActions,
   scanServerRoutes,
   scanWebSocketRoutes
-} from "./chunk-YGAXV5HR.js";
+} from "./chunk-6J4JWHDJ.js";
+import {
+  scanAgents
+} from "./chunk-L4VFNFDL.js";
 import {
   CSP_REPORT_PATH,
   CsrfReadinessStore,
   applySecurityHeaders,
   handleCspReport,
   handleCsrfReadiness
-} from "./chunk-MTEWLGVY.js";
+} from "./chunk-BPYMC7SU.js";
 import {
   validateCsrfRequest
-} from "./chunk-OLGPYOLO.js";
+} from "./chunk-P6OS7652.js";
 import {
   extractAppResources,
   handleMcpJsonRpc,
@@ -74,17 +97,20 @@ import {
 } from "./chunk-YOIVCCZT.js";
 import {
   resolveProvider
-} from "./chunk-AXKUA57G.js";
+} from "./chunk-3PBAN2YE.js";
 import {
   generateNonce
-} from "./chunk-JA2ZAT5Q.js";
+} from "./chunk-Z4PJMZLM.js";
 import {
   importUserModule
 } from "./chunk-52PDWL5S.js";
+import {
+  subjectFromContext
+} from "./chunk-YN4W7LCX.js";
 
 // src/vite-plugin/index.ts
-import { existsSync as existsSync9 } from "fs";
-import { resolve as resolve9, dirname as dirname4 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { resolve as resolve10, dirname as dirname4 } from "path";
 import { fileURLToPath } from "url";
 
 // src/vite-plugin/config-hook.ts
@@ -129,42 +155,56 @@ function runConfigHook(ctx) {
     },
     resolve: {
       alias: [
-        // Order matters: most-specific first so `theokit/X` doesn't
-        // get matched by the bare `theokit` alias.
-        { find: "theokit/server", replacement: resolve(ctx.theoSrcDir, `server/index${ext}`) },
-        { find: "theokit/client", replacement: resolve(ctx.theoSrcDir, `client/index${ext}`) },
+        // Order still matters — first match wins — but the entries below are
+        // EXACT (#377). A Vite alias whose `find` is a string matches by prefix,
+        // and every replacement here points at a FILE, so the old string form
+        // rewrote `theokit/client/core` into `…/client/index.ts/core` and the
+        // build died with ENOTDIR. It did that for every subpath nobody had
+        // listed, which made the failure open-ended rather than a typo.
+        { find: /^theokit\/server$/u, replacement: resolve(ctx.theoSrcDir, `server/index${ext}`) },
+        { find: /^theokit\/client$/u, replacement: resolve(ctx.theoSrcDir, `client/index${ext}`) },
         {
           // T2.1 (M5 lonely folders) moved the source from
           // `react-query/index.ts` into `client/react-query.ts` (sibling of
           // `client/index.ts`). The package.json export `./react-query`
           // still points at the build artifact `./dist/react-query/index.{js,d.ts}`,
           // but the dev-time source alias must follow the new location.
-          find: "theokit/react-query",
+          find: /^theokit\/react-query$/u,
           replacement: resolve(ctx.theoSrcDir, `client/react-query${ext}`)
         },
         {
-          find: "theokit/vite-plugin",
+          find: /^theokit\/vite-plugin$/u,
           replacement: resolve(ctx.theoSrcDir, `vite-plugin/index${ext}`)
         },
         {
-          find: "theokit/adapters/web-shim",
+          find: /^theokit\/adapters\/web-shim$/u,
           replacement: resolve(ctx.theoSrcDir, `adapters/web-shim${ext}`)
         },
         {
-          find: "theokit/adapters/ws-shim",
+          find: /^theokit\/adapters\/ws-shim$/u,
           replacement: resolve(ctx.theoSrcDir, `adapters/ws-shim${ext}`)
         },
         // T1.2 — devtools entry (DEV only; tree-shaken in build).
         // Source layout: src/devtools/dom/entry.tsx (has /dom/ segment)
         // Dist layout:   dist/devtools/entry.js    (tsup flattens /dom/)
         {
-          find: "theokit/devtools/entry",
+          find: /^theokit\/devtools\/entry$/u,
           replacement: resolve(
             ctx.theoSrcDir,
             ext === ".ts" ? "devtools/dom/entry.tsx" : "devtools/entry.js"
           )
         },
-        { find: "theokit", replacement: resolve(ctx.theoSrcDir, `index${ext}`) }
+        // Everything else under the package, by one rule rather than a list that
+        // has to grow with the exports map. The source layout mirrors the
+        // subpath, so `theokit/cache` is `<src>/cache` and Vite's own extension
+        // resolution finds the file. The two entries above that do NOT mirror it
+        // — react-query moved to a sibling, devtools' source carries a `/dom/`
+        // segment the dist flattens — are matched before this and keep their
+        // mapping.
+        { find: /^theokit\/(.+)$/u, replacement: resolve(ctx.theoSrcDir, "$1") },
+        // Exact, so a package merely NAMED like ours — `theokit-anything` — is
+        // left alone. The prefix form ate those too.
+        { find: /^theokit$/u, replacement: resolve(ctx.theoSrcDir, `index${ext}`) }
       ]
     }
   };
@@ -196,177 +236,13 @@ ${issueLines}
 };
 
 // src/config/schema.ts
-import { z as z8 } from "zod";
+import { z } from "zod";
 
 // src/core/contracts/theo-ui-theme.ts
 var THEME_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
 
-// src/config/schemas/rate-limit.ts
-import { z } from "zod";
-var baseRateLimitSchema = z.object({
-  windowMs: z.number().min(1),
-  max: z.number().int().min(1)
-});
-var rateLimitSchema = z.union([
-  baseRateLimitSchema,
-  z.object({
-    default: baseRateLimitSchema.optional(),
-    routes: z.record(z.string(), baseRateLimitSchema).optional(),
-    keyBy: z.union([
-      z.enum(["ip", "session", "user"]),
-      z.function({ input: z.tuple([z.unknown()]), output: z.string() })
-    ]).optional(),
-    cookieName: z.string().min(1).optional(),
-    /**
-     * How many reverse proxies sit in front of the app, for `keyBy: 'ip'`. `false` (default)
-     * trusts none; `true` means one; a number names a longer chain.
-     *
-     * Required for correct limiting behind Caddy/nginx/a load balancer — without it every visitor
-     * keys on the proxy address and shares a single bucket. Off by default because
-     * `x-forwarded-for` is client-writable.
-     */
-    trustProxy: z.union([z.boolean(), z.number().int().min(0)]).optional()
-  })
-]);
-
-// src/config/schemas/upload.ts
-import { z as z2 } from "zod";
-var uploadSchema = z2.object({
-  maxFileSize: z2.number().min(1).default(10 * 1024 * 1024),
-  // 10MB
-  maxFiles: z2.number().int().min(1).default(10),
-  maxFieldSize: z2.number().min(1).default(1 * 1024 * 1024)
-  // 1MB
-});
-
-// src/config/schemas/logging.ts
-import { z as z3 } from "zod";
-var loggingSchema = z3.object({
-  level: z3.enum(["debug", "info", "warn", "error", "silent"]).default("info")
-});
-
-// src/config/schemas/cache.ts
-import { z as z4 } from "zod";
-var routeRuleSchema = z4.object({
-  maxAge: z4.number().nonnegative().optional(),
-  swr: z4.number().nonnegative().optional(),
-  tags: z4.array(z4.string()).optional()
-});
-var cacheSchema = z4.object({
-  enabled: z4.boolean().default(true),
-  /** 'memory' uses InMemoryCacheAdapter; otherwise pass a custom adapter instance. */
-  storage: z4.union([z4.literal("memory"), z4.custom()]).default("memory"),
-  maxEntries: z4.number().int().positive().default(1e3),
-  defaults: z4.object({
-    maxAge: z4.number().nonnegative().default(1),
-    swr: z4.number().nonnegative().optional(),
-    cacheErrors: z4.boolean().default(false)
-  }).default({ maxAge: 1, cacheErrors: false }),
-  keyDerivation: z4.object({
-    excludeQuery: z4.array(z4.string()).optional(),
-    sortQuery: z4.boolean().default(true),
-    lowercaseHost: z4.boolean().default(true)
-  }).default({ sortQuery: true, lowercaseHost: true }),
-  routeRules: z4.record(z4.string(), routeRuleSchema).optional()
-});
-
-// src/config/schemas/security.ts
-import { z as z6 } from "zod";
-
-// src/config/schemas/header-safe.ts
-import { z as z5 } from "zod";
-var headerSafeString = z5.string().refine((s) => !/[\r\n]/.test(s), { message: "Header value must not contain CR/LF" });
-
-// src/config/schemas/security.ts
-var securityHeadersSchema = z6.object({
-  csp: z6.union([headerSafeString, z6.literal(false)]).optional(),
-  // T6.1 — default flipped from 'report-only' to 'enforce' for 0.3.0.
-  // Users who want the old behaviour set `cspMode: 'report-only'`
-  // explicitly.
-  cspMode: z6.enum(["enforce", "report-only", "off"]).default("enforce"),
-  hsts: z6.union([headerSafeString, z6.literal(false)]).optional(),
-  frameOptions: z6.enum(["DENY", "SAMEORIGIN"]).default("DENY"),
-  contentTypeOptions: z6.literal("nosniff").default("nosniff"),
-  referrerPolicy: headerSafeString.default("strict-origin-when-cross-origin"),
-  /**
-   * T1.1 — Permissions-Policy directive string. EC-3-refined: rejects CR/LF.
-   * Pass `false` to suppress the header.
-   */
-  permissionsPolicy: z6.union([headerSafeString, z6.literal(false)]).optional()
-});
-var disallowedConfigSchema = z6.object({
-  routes: z6.array(z6.union([z6.string(), z6.instanceof(RegExp)])),
-  behavior: z6.enum(["warn", "raise"]).default("raise")
-});
-var corsSchema = z6.object({
-  origins: z6.union([
-    z6.literal("*"),
-    headerSafeString,
-    z6.instanceof(RegExp),
-    z6.array(z6.union([headerSafeString, z6.instanceof(RegExp)])),
-    z6.function({ input: z6.tuple([z6.string()]), output: z6.boolean() })
-  ]),
-  methods: z6.array(z6.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"])).optional(),
-  allowedHeaders: z6.array(headerSafeString).optional(),
-  exposedHeaders: z6.array(headerSafeString).optional(),
-  credentials: z6.boolean().default(false),
-  maxAge: z6.number().int().min(0).max(86400).default(600)
-}).refine((c) => !(c.origins === "*" && c.credentials), {
-  message: 'CORS spec forbids origins:"*" with credentials:true \u2014 browsers ignore the wildcard'
-});
-var securitySchema = z6.object({
-  // T6.1 — default flipped from 'warn' to 'strict' for 0.3.0. Apps that
-  // grep their warn-mode logs from 0.2.x already know which endpoints
-  // break; opt back into 'warn' globally OR use disallowedRoutes for
-  // surgical migration.
-  csrf: z6.enum(["off", "warn", "strict"]).default("strict"),
-  headers: securityHeadersSchema.optional(),
-  /** T5.1 — per-route escalation (Rails disallowed_warnings pattern). */
-  disallowed: disallowedConfigSchema.optional(),
-  /** T1.2 — Cross-Origin Resource Sharing. Single global config; runs first in pipeline. */
-  cors: corsSchema.optional()
-});
-
-// src/config/schemas/storage.ts
-import { z as z7 } from "zod";
-var tlsConfigSchema = z7.object({
-  rejectUnauthorized: z7.boolean().optional(),
-  caCert: z7.string().optional(),
-  clientCert: z7.string().optional(),
-  clientKey: z7.string().optional()
-});
-var serverConfigSchema = z7.object({
-  host: z7.string().min(1),
-  port: z7.number().int().positive().max(65535).optional(),
-  user: z7.string().min(1),
-  /** Password may be the empty string (some providers permit it). */
-  password: z7.string(),
-  tls: tlsConfigSchema.optional()
-});
-var postgresPoolConfigSchema = z7.object({
-  min: z7.number().int().nonnegative().optional(),
-  max: z7.number().int().positive().optional(),
-  connectionTimeoutMillis: z7.number().int().positive().optional(),
-  idleTimeoutMillis: z7.number().int().nonnegative().optional()
-});
-var postgresDatabaseConfigSchema = z7.object({
-  /** References a key in `storage.servers`. Resolved at `usePostgres()` call time. */
-  server: z7.string().min(1),
-  database: z7.string().min(1),
-  pool: postgresPoolConfigSchema.optional()
-});
-var redisServerConfigSchema = serverConfigSchema.extend({
-  db: z7.number().int().nonnegative().optional(),
-  maxRetriesPerRequest: z7.number().int().nonnegative().optional()
-});
-var storageSchema = z7.object({
-  servers: z7.record(z7.string(), serverConfigSchema).optional(),
-  databases: z7.record(z7.string(), postgresDatabaseConfigSchema).optional(),
-  redis: z7.record(z7.string(), redisServerConfigSchema).optional()
-});
-
 // src/config/schema.ts
-var theoConfigSchema = z8.object({
+var theoConfigSchema = z.object({
   /**
    * Plan v1.2 T2.1 — project identifier propagated into
    * `.theokit/services.json` v2 `project` field. DNS-1123 compatible (drives
@@ -374,27 +250,27 @@ var theoConfigSchema = z8.object({
    * emits services.json v1 with the legacy `services-bundle` fallback
    * (ADR D10) and logs a deprecation warning.
    */
-  name: z8.string().max(63).refine(
+  name: z.string().max(63).refine(
     // DNS-1123 equivalent expressed as explicit single-char anchors so
     // security/detect-unsafe-regex stays clean (no backtracking).
     (value) => value.length > 0 && /^[a-z0-9-]+$/u.test(value) && !value.startsWith("-") && !value.endsWith("-"),
     "name must match DNS-1123 (lowercase alphanumeric+hyphens, 1-63 chars, no leading/trailing hyphen)"
   ).optional(),
-  appDir: z8.string().default("app"),
-  serverDir: z8.string().default("server"),
+  appDir: z.string().default("app"),
+  serverDir: z.string().default("server"),
   /**
    * Directory (relative to the project root) holding `agents/<name>.ts` definitions, scanned by
    * dev/build/terminal/mcp. Defaults to `"agents"` — apps that keep the canonical layout are
    * unaffected. Set to e.g. `"core/agents"` to organize agents under a domain root (#95 follow-up).
    */
-  agentsDir: z8.string().default("agents"),
+  agentsDir: z.string().default("agents"),
   /**
    * T2.2 / EC-4 — Build output directory. Must be a relative path inside
    * the project root. Refused absolute or parent-relative paths to prevent
    * `cleanOutDir` from wiping arbitrary locations (defense-in-depth on
    * top of cleanOutDir's runtime EC-3 guard).
    */
-  distDir: z8.string().default(".theokit").refine(
+  distDir: z.string().default(".theokit").refine(
     (d) => !/^([A-Za-z]:)?[/\\]/.test(d) && !d.startsWith(".."),
     'distDir must be a relative path inside the project root (e.g., ".theokit")'
   ),
@@ -413,73 +289,79 @@ var theoConfigSchema = z8.object({
    *   * `idleTimeoutMs` — auto-evict idle agents (default 30 min). 0 disables
    *     idle eviction (LRU only).
    */
-  agents: z8.object({
-    maxRegistries: z8.number().int().positive().default(100),
-    registry: z8.object({
+  agents: z.object({
+    maxRegistries: z.number().int().positive().default(100),
+    registry: z.object({
       /** LRU cap — MUST be ≥ max-concurrent-active-conversations. */
-      maxAgents: z8.number().int().positive().max(1e4).default(100),
+      maxAgents: z.number().int().positive().max(1e4).default(100),
       /** Idle eviction window in ms. 0 disables idle eviction (LRU only). */
-      idleTimeoutMs: z8.number().int().nonnegative().default(30 * 6e4)
+      idleTimeoutMs: z.number().int().nonnegative().default(30 * 6e4)
     }).optional()
   }).optional(),
-  port: z8.number().int().min(1).max(65535).default(3e3),
+  port: z.number().int().min(1).max(65535).default(3e3),
   /** Listen on all addresses (0.0.0.0) for LAN/mobile testing. */
-  host: z8.union([z8.string(), z8.boolean()]).default("localhost"),
+  host: z.union([z.string(), z.boolean()]).default("localhost"),
   /** Automatically open browser on `theokit dev`. */
-  open: z8.union([z8.boolean(), z8.string()]).default(false),
+  open: z.union([z.boolean(), z.string()]).default(false),
   /** Exit if port is already in use instead of trying next available. */
-  strictPort: z8.boolean().default(false),
+  strictPort: z.boolean().default(false),
   /** Forward browser console/errors to terminal — useful for AI agent dev. */
-  forwardConsole: z8.union([
-    z8.boolean(),
-    z8.object({
-      unhandledErrors: z8.boolean().optional(),
-      logLevels: z8.array(z8.enum(["error", "warn", "info", "log", "debug"])).optional()
+  forwardConsole: z.union([
+    z.boolean(),
+    z.object({
+      unhandledErrors: z.boolean().optional(),
+      logLevels: z.array(z.enum(["error", "warn", "info", "log", "debug"])).optional()
     })
   ]).default(false),
   /** Pre-transform files on startup for faster first page load. */
-  warmup: z8.object({
-    clientFiles: z8.array(z8.string()).optional(),
-    ssrFiles: z8.array(z8.string()).optional()
+  warmup: z.object({
+    clientFiles: z.array(z.string()).optional(),
+    ssrFiles: z.array(z.string()).optional()
   }).optional(),
-  ssr: z8.boolean().default(false),
+  ssr: z.boolean().default(false),
   /** When true (and ssr === true), use renderToPipeableStream with progressive
    * shell flush instead of single-shot renderToString. Opt-in for streaming
    * SSR; default false preserves the current behavior. */
-  ssrStreaming: z8.boolean().default(false),
+  ssrStreaming: z.boolean().default(false),
   rateLimit: rateLimitSchema.optional(),
   upload: uploadSchema.optional(),
   logging: loggingSchema.optional(),
   security: securitySchema.optional(),
-  serialization: z8.enum(["json", "superjson"]).default("json"),
+  serialization: z.enum(["json", "superjson"]).default("json"),
   // Plugins are validated structurally at runtime by createPluginRunnerFromConfig.
   // Zod only checks the shape minimally (must be array). Type-level safety is
   // provided through defineConfig at the user surface.
-  plugins: z8.array(z8.unknown()).optional(),
+  //
+  // #425 — an entry MAY also be a module SPECIFIER (a string), resolved to that module's default
+  // export by `config/resolve-plugin-specifiers.ts`. A constructed plugin closes over state and
+  // therefore has no literal, so it is the string form — and only the string form — that a
+  // generated deploy entry can carry. Both shapes are accepted here for the same reason they are
+  // accepted at runtime: one declaration has to serve the local server and the deployed one.
+  plugins: z.array(z.unknown()).optional(),
   /** Enable client-side batching of theoFetch calls and the
    * /api/__theo_batch__ server endpoint. */
-  batching: z8.union([z8.boolean(), z8.object({ max: z8.number().int().positive().optional() })]).optional(),
+  batching: z.union([z.boolean(), z.object({ max: z.number().int().positive().optional() })]).optional(),
   /** T4.1 — Audit log. When `logger` is provided, framework events
    * (csrf.warn, rate-limit.exceeded, session.rotated, csp.violation) are
    * emitted to it. Default: noop. */
-  audit: z8.object({
-    logger: z8.unknown().optional()
+  audit: z.object({
+    logger: z.unknown().optional()
   }).optional(),
   /** TheoUI auto-wire (T2.1). `false` = opt-out; object = explicit theme/fonts;
    * undefined = enabled when @theokit/ui is detected in node_modules. */
-  ui: z8.union([
-    z8.literal(false),
-    z8.object({
+  ui: z.union([
+    z.literal(false),
+    z.object({
       // Any theme @theokit/ui knows — built-in or from `defineTheme()`. This was a closed
       // enum of `violet-forge | noir | paper`, two of which never existed in @theokit/ui, so
       // the only accepted value was the default and every real theme was rejected. The pattern
       // mirrors what @theokit/ui's ThemeProvider enforces, and it is load-bearing: the value is
       // interpolated into the generated entry and into a CSS selector.
-      theme: z8.string().regex(
+      theme: z.string().regex(
         THEME_NAME_PATTERN,
         "must start with a letter and contain only lowercase letters, digits and hyphens"
       ).optional(),
-      fonts: z8.enum(["bundled", "cdn"]).optional()
+      fonts: z.enum(["bundled", "cdn"]).optional()
     })
   ]).optional(),
   /**
@@ -488,6 +370,12 @@ var theoConfigSchema = z8.object({
    * Pass `cache: {}` to opt in with defaults.
    */
   cache: cacheSchema.optional(),
+  /**
+   * Observability (#353). Default `undefined` keeps telemetry off. Present and
+   * not `enabled: false` opts in; `provider` overrides the environment-derived
+   * adapter, which is the priority `adapter-registry.ts` has always documented.
+   */
+  observability: observabilitySchema.optional(),
   /**
    * Devtools overlay (Phase 0.4.0+ —
    *
@@ -498,11 +386,11 @@ var theoConfigSchema = z8.object({
    * Tree-shaken to noop in prod via the dual-export pattern in
    * `packages/theo/src/devtools/index.ts` (EC-17 positive prod check).
    */
-  devtools: z8.union([
-    z8.literal(false),
-    z8.object({
-      position: z8.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional(),
-      theme: z8.enum(["light", "dark", "system"]).optional()
+  devtools: z.union([
+    z.literal(false),
+    z.object({
+      position: z.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional(),
+      theme: z.enum(["light", "dark", "system"]).optional()
     })
   ]).optional(),
   /**
@@ -511,7 +399,7 @@ var theoConfigSchema = z8.object({
    * (EC-201 / ADR D2). If `config.adapters` includes a target NOT
    * matching `--target`, `theokit build` emits a cross-reference note.
    */
-  adapters: z8.array(z8.string()).optional(),
+  adapters: z.array(z.string()).optional(),
   /**
    * Extra package names to pre-bundle via Vite's `optimizeDeps.include`.
    *
@@ -526,14 +414,14 @@ var theoConfigSchema = z8.object({
    * Example:
    *   viteOptimizeDeps: ['mermaid']
    */
-  viteOptimizeDeps: z8.array(z8.string()).optional(),
+  viteOptimizeDeps: z.array(z.string()).optional(),
   /**
    * Jobs backend (ADR D3 + T2.1). When configured, every request gets
    * `ctx.queue.enqueue` auto-wired via the outbox lifecycle. Pass a
    * `JobBackend` instance (InMemoryJobBackend, PostgresJobBackend, etc.).
    */
-  jobs: z8.object({
-    backend: z8.custom((v) => typeof v === "object" && v !== null)
+  jobs: z.object({
+    backend: z.custom((v) => typeof v === "object" && v !== null)
   }).optional(),
   /**
    * StorageManager configuration (T1.1 / ADR-0007).
@@ -568,17 +456,17 @@ var theoConfigSchema = z8.object({
    * The env var `THEOKIT_OPENAPI_SERVERS` (CSV of URLs) overrides
    * `servers[].url` at emit time without rebuilding the config.
    */
-  openapi: z8.object({
-    servers: z8.array(
-      z8.object({
-        url: z8.url(),
-        description: z8.string().optional()
+  openapi: z.object({
+    servers: z.array(
+      z.object({
+        url: z.url(),
+        description: z.string().optional()
       })
     ).default([{ url: "http://localhost:3000", description: "Local development" }]),
-    specVersion: z8.enum(["3.1.0", "3.0.3"]).default("3.1.0"),
-    title: z8.string().default("TheoKit App"),
-    version: z8.string().default("0.0.0"),
-    outDir: z8.string().default(".theokit")
+    specVersion: z.enum(["3.1.0", "3.0.3"]).default("3.1.0"),
+    title: z.string().default("TheoKit App"),
+    version: z.string().default("0.0.0"),
+    outDir: z.string().default(".theokit")
   }).optional(),
   /**
    * G5 T1.3 — error envelope transformer hook (blueprint ADR D3).
@@ -595,7 +483,7 @@ var theoConfigSchema = z8.object({
    * with a function-typed runtime guard preserves the call-site type
    * without trading off Zod runtime validation.
    */
-  formatError: z8.custom((val) => typeof val === "function", {
+  formatError: z.custom((val) => typeof val === "function", {
     message: "formatError must be a function"
   }).optional()
 }).refine((cfg) => !Object.values(cfg.services).some((s) => s.port === cfg.port), {
@@ -674,6 +562,46 @@ async function loadConfig(dir) {
   return result.data;
 }
 
+// src/config/resolve-plugin-specifiers.ts
+import { isAbsolute, resolve as resolve3 } from "path";
+import { pathToFileURL } from "url";
+var UnresolvablePluginSpecifierError = class extends Error {
+  constructor(index, specifier, reason) {
+    super(`plugins[${index}] (${specifier}) could not be loaded: ${reason}`);
+    this.name = "UnresolvablePluginSpecifierError";
+  }
+};
+async function resolvePluginSpecifiers(plugins, cwd) {
+  const resolved = [];
+  for (const [index, entry] of plugins.entries()) {
+    resolved.push(typeof entry === "string" ? await importPlugin(entry, index, cwd) : entry);
+  }
+  return resolved;
+}
+async function importPlugin(specifier, index, cwd) {
+  const target = isAbsolute(specifier) ? specifier : resolve3(cwd, specifier);
+  let mod;
+  try {
+    mod = await import(
+      /* @vite-ignore */
+      pathToFileURL(target).href
+    );
+  } catch (err) {
+    throw new UnresolvablePluginSpecifierError(index, specifier, messageOf(err));
+  }
+  if (mod.default === void 0) {
+    throw new UnresolvablePluginSpecifierError(
+      index,
+      specifier,
+      "the module has no default export; a plugin module must `export default` its plugin"
+    );
+  }
+  return mod.default;
+}
+function messageOf(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/vite-plugin/theoui-detect.ts
 import { existsSync as existsSync3, readFileSync } from "fs";
 import { dirname, join } from "path";
@@ -773,7 +701,14 @@ var DEFAULT_RESOLVED = {
 async function resolvePluginConfig(projectRoot) {
   try {
     const userConfig = await loadConfig(projectRoot);
-    const pluginRunner = await createPluginRunnerFromConfig(userConfig.plugins);
+    const observabilityPlugin = createObservabilityPluginFromConfig(
+      userConfig.observability,
+      process.env
+    );
+    const declaredPlugins = await resolvePluginSpecifiers(userConfig.plugins ?? [], projectRoot);
+    const pluginRunner = await createPluginRunnerFromConfig(
+      observabilityPlugin === void 0 ? declaredPlugins : [observabilityPlugin, ...declaredPlugins]
+    );
     const transformer = resolveTransformer(userConfig.serialization);
     let resolvedBatching;
     if (userConfig.batching === true) {
@@ -807,7 +742,7 @@ async function resolvePluginConfig(projectRoot) {
 }
 
 // src/vite-plugin/configure-server-hook.ts
-import { resolve as resolve6, basename } from "path";
+import { resolve as resolve8, basename } from "path";
 
 // src/devtools/server-side/route-manifest.ts
 function buildPath(parents, segment) {
@@ -845,7 +780,7 @@ function broadcastRouteManifest(tree) {
 
 // src/router/scan.ts
 import { readdirSync, statSync, existsSync as existsSync4 } from "fs";
-import { join as join2, resolve as resolve3 } from "path";
+import { join as join2, resolve as resolve4 } from "path";
 
 // src/router/types.ts
 var ROUTE_FILE_NAMES = ["page", "layout", "error", "loading", "not-found"];
@@ -886,7 +821,7 @@ function attachRouteFiles(node, dir) {
     for (const ext of ROUTE_FILE_EXTENSIONS) {
       const filename = `${name}${ext}`;
       if (existsSync4(join2(dir, filename))) {
-        setRouteFile(node, key, resolve3(dir, filename));
+        setRouteFile(node, key, resolve4(dir, filename));
         break;
       }
     }
@@ -935,7 +870,13 @@ function scanChild(parentDir, dirName, routePath) {
 function scanDir(dir, segment, routePath) {
   const node = { segment, path: routePath, children: [] };
   attachRouteFiles(node, dir);
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  entries.sort((a, b) => {
+    if (a.name < b.name) return -1;
+    if (a.name > b.name) return 1;
+    return 0;
+  });
+  for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     if (entry.name.startsWith("_") || entry.name.startsWith(".")) continue;
     const child = scanChild(dir, entry.name, routePath);
@@ -1089,6 +1030,11 @@ function handleAgentCard(mod, name, route, baseUrl) {
 
 // src/server/agent/approve-agent.ts
 var APPROVE_SEGMENT = "/approve/";
+var APPROVE_PATH = /^\/api\/agents\/([^/]+)\/approve\/([^/]+)$/;
+function parseApprovalAgentName(urlPath) {
+  const match = APPROVE_PATH.exec(urlPath);
+  return match ? decodeURIComponent(match[1]) : null;
+}
 function parseApprovalId(urlPath) {
   const at = urlPath.indexOf(APPROVE_SEGMENT);
   if (at === -1) return null;
@@ -1121,7 +1067,17 @@ function parseApprovalBody(body) {
   }
   return decision;
 }
-async function handleAgentApproval(request, urlPath, registry, csrfMode = "strict") {
+async function refuseIfNotOwner(registry, approvalId, resolveSubject, params) {
+  const owner = registry.ownerOf(approvalId);
+  if (owner === void 0) return void 0;
+  const subject = resolveSubject === void 0 ? null : await resolveSubject();
+  if (subject?.id === owner) return void 0;
+  return agentAccessDenied(
+    { allowed: false, reason: "the approval belongs to another subject" },
+    params
+  );
+}
+async function handleAgentApproval(request, urlPath, registry, csrfMode = "strict", access = {}) {
   if (csrfMode !== "off") {
     const csrf = validateCsrfRequest(request);
     if (!csrf.valid && csrfMode === "strict") {
@@ -1132,6 +1088,15 @@ async function handleAgentApproval(request, urlPath, registry, csrfMode = "stric
   if (approvalId === null) {
     return jsonError(400, "BAD_REQUEST", "Approval path must be /api/agents/<name>/approve/<id>.");
   }
+  const params = {
+    agent: parseApprovalAgentName(urlPath) ?? "unknown",
+    endpoint: "approve",
+    approvalId
+  };
+  const decision = await admitAgentRequest(access.policy, access.resolveSubject, params);
+  if (!decision.allowed) return agentAccessDenied(decision, params);
+  const notOwner = await refuseIfNotOwner(registry, approvalId, access.resolveSubject, params);
+  if (notOwner !== void 0) return notOwner;
   let body = null;
   try {
     body = await request.json();
@@ -1145,25 +1110,13 @@ async function handleAgentApproval(request, urlPath, registry, csrfMode = "stric
   if (!resolved) {
     return jsonError(404, "NOT_PENDING", `No pending approval for id '${approvalId}'.`);
   }
+  closePauseSpan(approvalId, { resumeObserved: true });
   return new Response(JSON.stringify({ resolved: true }), {
     status: 200,
     headers: { "content-type": "application/json" }
   });
 }
 
-// src/server/agent/list-approvals-handler.ts
-var LIST_PATH = /^\/api\/agents\/([^/]+)\/approvals$/;
-function isListApprovalsPath(urlPath) {
-  const match = LIST_PATH.exec(urlPath);
-  return match ? decodeURIComponent(match[1]) : null;
-}
-function handleListApprovals(registry) {
-  return new Response(JSON.stringify({ approvals: registry.list() }), {
-    status: 200,
-    headers: { "content-type": "application/json; charset=utf-8" }
-  });
-}
-
 // src/server/agent/handle-agent-run-reconnect.ts
 var RUN_STREAM_PATH = /^\/api\/agents\/([^/]+)\/runs\/([^/]+)\/stream$/;
 function isAgentRunStreamPath(urlPath) {
@@ -1328,7 +1281,7 @@ function jsonError2(status, code, message) {
   });
 }
 async function handleThreadMessage(args) {
-  const { mod, apiKey, sessionId, request, source, csrfMode = "strict" } = args;
+  const { mod, apiKey, sessionId, request, source, agentName, csrfMode = "strict" } = args;
   if (csrfMode === "strict") {
     const csrf = validateCsrfRequest(request);
     if (!csrf.valid) return jsonError2(403, "CSRF_FAILED", `CSRF check failed: ${csrf.reason}`);
@@ -1346,7 +1299,9 @@ async function handleThreadMessage(args) {
     {
       registry: getThreadRunRegistry(),
       cache: getRunEventCache(),
-      startRun: makeThreadStartRun(mod, apiKey, source)
+      // usetheokit/theokit#381 — the request goes with it, so the run's spans join the trace of
+      // the caller that queued it instead of opening one of their own.
+      startRun: makeThreadStartRun(mod, apiKey, source, agentName, request)
     },
     sessionId,
     input.message
@@ -1424,6 +1379,19 @@ function waitThenAttachStream(sessionId, request, registry, cache, idleWaitMs) {
   return new Response(stream, { headers: { ...SSE_BASE_HEADERS } });
 }
 
+// src/server/agent/list-approvals-handler.ts
+var LIST_PATH = /^\/api\/agents\/([^/]+)\/approvals$/;
+function isListApprovalsPath(urlPath) {
+  const match = LIST_PATH.exec(urlPath);
+  return match ? decodeURIComponent(match[1]) : null;
+}
+function handleListApprovals(registry) {
+  return new Response(JSON.stringify({ approvals: registry.list() }), {
+    status: 200,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+
 // src/server/agent/serve-aux-routes.ts
 function jsonError3(status, code, message) {
   return new Response(JSON.stringify({ error: { code, message } }), {
@@ -1431,73 +1399,135 @@ function jsonError3(status, code, message) {
     headers: { "content-type": "application/json; charset=utf-8" }
   });
 }
-async function serveAgentAuxRoute(request, urlPath, deps) {
-  const method = request.method.toUpperCase();
-  const cardName = isAgentCardPath(urlPath);
-  if (cardName !== null) {
-    if (method !== "GET") return null;
-    const agent = deps.agents.find((a) => a.name === cardName);
-    if (!agent) return null;
-    const mod = await deps.loadModule(agent.filePath);
-    return handleAgentCard(mod, agent.name, agent.agentPath, deps.baseUrl);
-  }
-  if (isListApprovalsPath(urlPath)) {
-    if (method !== "GET") return null;
-    return handleListApprovals(getApprovalRegistry());
-  }
-  const runStream = isAgentRunStreamPath(urlPath);
-  if (runStream !== null) {
-    if (method !== "GET") return null;
-    if (!deps.agents.some((a) => a.name === runStream.name)) return null;
-    return handleAgentRunReconnect(runStream.runId, request, getRunEventCache());
-  }
-  const threadResponse = await serveThreadRoute(request, method, urlPath, deps);
-  if (threadResponse !== null) return threadResponse;
-  const mcpName = isMcpPath(urlPath);
-  if (mcpName !== null) {
-    return serveMcpRoute(request, method, mcpName, deps);
+function routeFor(deps, name, build) {
+  if (name === null) return null;
+  const agent = deps.agents.find((a) => a.name === name);
+  return agent === void 0 ? null : build(agent);
+}
+function matchGetAuxRoute(verb, urlPath, deps) {
+  if (verb !== "GET") return null;
+  const card = routeFor(
+    deps,
+    isAgentCardPath(urlPath),
+    (agent) => ({ kind: "card", agent })
+  );
+  if (card !== null) return card;
+  const approvals = routeFor(
+    deps,
+    isListApprovalsPath(urlPath),
+    (agent) => ({ kind: "approvals", agent })
+  );
+  if (approvals !== null) return approvals;
+  const run = isAgentRunStreamPath(urlPath);
+  if (run !== null) {
+    return routeFor(
+      deps,
+      run.name,
+      (agent) => ({ kind: "run-stream", agent, runId: run.runId })
+    );
   }
-  return null;
-}
-async function serveThreadRoute(request, method, urlPath, deps) {
   const stream = isThreadStreamPath(urlPath);
-  if (stream !== null) {
-    if (method !== "GET") return null;
-    if (!deps.agents.some((a) => a.name === stream.name)) return null;
-    return handleThreadStream(stream.sessionId, request);
-  }
+  if (stream === null) return null;
+  return routeFor(
+    deps,
+    stream.name,
+    (agent) => ({ kind: "thread-stream", agent, sessionId: stream.sessionId })
+  );
+}
+async function matchPostAuxRoute(verb, urlPath, deps) {
+  if (verb !== "POST") return null;
   const msg = isThreadMessagePath(urlPath);
   if (msg !== null) {
-    if (method !== "POST") return null;
-    const agent = deps.agents.find((a) => a.name === msg.name);
-    if (!agent) return null;
-    if (deps.resolveApiKey === void 0) {
-      return jsonError3(
-        501,
-        "NOT_CONFIGURED",
-        "Thread follow-up requires a provider API key (resolveApiKey was not provided to serveAgentAuxRoute)."
-      );
-    }
-    const mod = await deps.loadModule(agent.filePath);
-    return handleThreadMessage({
-      mod,
-      // Passed unresolved: `makeThreadStartRun` calls it once the module is compiled and the
-      // model is known (theokit#328).
-      apiKey: deps.resolveApiKey,
-      sessionId: msg.sessionId,
-      request,
-      source: `agent "${msg.name}"`,
-      csrfMode: deps.csrfMode ?? "strict"
+    return routeFor(
+      deps,
+      msg.name,
+      (agent2) => ({ kind: "thread-message", agent: agent2, sessionId: msg.sessionId })
+    );
+  }
+  const agent = routeFor(deps, isMcpPath(urlPath), (found) => found);
+  if (agent === null) return null;
+  const mod = await deps.loadModule(agent.filePath);
+  return isMcpExposed(mod) ? { kind: "mcp", agent, mod } : null;
+}
+async function matchAgentAuxRoute(method, urlPath, deps) {
+  const verb = method.toUpperCase();
+  return matchGetAuxRoute(verb, urlPath, deps) ?? await matchPostAuxRoute(verb, urlPath, deps);
+}
+async function admitAux(deps, agent, params, body) {
+  const mod = await deps.loadModule(agent.filePath);
+  const decision = await admitAgentRequest(
+    readAgentPolicy(mod, agent.filePath),
+    deps.resolveSubject,
+    params,
+    body
+  );
+  return decision.allowed ? null : agentAccessDenied(decision, params);
+}
+async function serveMatchedAuxRoute(route, request, deps) {
+  if (route.kind === "card") {
+    const mod = await deps.loadModule(route.agent.filePath);
+    return handleAgentCard(mod, route.agent.name, route.agent.agentPath, deps.baseUrl);
+  }
+  if (route.kind === "approvals") {
+    const refusal = await admitAux(deps, route.agent, {
+      agent: route.agent.name,
+      endpoint: "approvals"
     });
+    return refusal ?? handleListApprovals(getApprovalRegistry());
   }
-  return null;
+  if (route.kind === "run-stream") {
+    return handleAgentRunReconnect(route.runId, request, getRunEventCache());
+  }
+  if (route.kind === "mcp") return serveMcpRoute(route, request, deps);
+  return serveThreadRoute(route, request, deps);
 }
-async function serveMcpRoute(request, method, mcpName, deps) {
-  if (method !== "POST") return null;
-  const agent = deps.agents.find((a) => a.name === mcpName);
-  if (!agent) return null;
+async function serveThreadRoute(route, request, deps) {
+  const { agent, sessionId } = route;
+  if (route.kind === "thread-stream") {
+    const refusal2 = await admitAux(deps, agent, {
+      agent: agent.name,
+      endpoint: "thread-stream",
+      sessionId
+    });
+    return refusal2 ?? handleThreadStream(sessionId, request);
+  }
+  const refusal = await admitAux(deps, agent, {
+    agent: agent.name,
+    endpoint: "thread-message",
+    sessionId
+  });
+  if (refusal !== null) return refusal;
+  if (deps.resolveApiKey === void 0) {
+    return jsonError3(
+      501,
+      "NOT_CONFIGURED",
+      "Thread follow-up requires a provider API key (resolveApiKey was not provided to serveMatchedAuxRoute)."
+    );
+  }
   const mod = await deps.loadModule(agent.filePath);
-  if (!isMcpExposed(mod)) return null;
+  return handleThreadMessage({
+    mod,
+    // Passed unresolved: `makeThreadStartRun` calls it once the module is compiled and the
+    // model is known (theokit#328).
+    apiKey: deps.resolveApiKey,
+    sessionId,
+    request,
+    source: `agent "${agent.name}"`,
+    // usetheokit/theokit#406 — the label above reads well in an `AgentDefinitionError` and is not
+    // a name; the spans get the name, so the same agent is one series whichever route started it.
+    agentName: agent.name,
+    csrfMode: deps.csrfMode ?? "strict"
+  });
+}
+async function serveMcpRoute(route, request, deps) {
+  const { agent, mod } = route;
+  const mcpParams = { agent: agent.name, endpoint: "mcp" };
+  const mcpDecision = await admitAgentRequest(
+    readAgentPolicy(mod, agent.filePath),
+    deps.resolveSubject,
+    mcpParams
+  );
+  if (!mcpDecision.allowed) return agentAccessDenied(mcpDecision, mcpParams);
   const csrfMode = deps.csrfMode ?? "strict";
   if (csrfMode === "strict") {
     const csrf = validateCsrfRequest(request);
@@ -1514,38 +1544,53 @@ function isMcpExposed(mod) {
   return mod?.mcp === true;
 }
 
-// src/server/http/node-web-adapter.ts
-async function writeWebResponseToServerResponse(response, res) {
-  const setCookies = response.headers.getSetCookie();
-  if (setCookies.length > 0) {
-    res.setHeader("Set-Cookie", setCookies);
-  }
-  const otherHeaders = {};
-  for (const [key, value] of response.headers.entries()) {
-    if (key.toLowerCase() === "set-cookie") continue;
-    otherHeaders[key] = value;
-  }
-  res.writeHead(response.status, response.statusText, otherHeaders);
-  if (response.body === null) {
-    res.end();
+// src/server/http/plugin-lifecycle.ts
+function messageOf2(err, fallback) {
+  return err instanceof Error ? err.message : fallback;
+}
+async function serveThroughPluginLifecycle(target, serve) {
+  const { res, requestId, pluginRunner, failureMessage } = target;
+  let request;
+  try {
+    request = target.source.toRequest();
+  } catch (err) {
+    sendError(res, "INTERNAL", messageOf2(err, failureMessage), 500, void 0, requestId);
     return;
   }
-  const reader = response.body.getReader();
+  const pluginCtx = { request, response: res, ctx: {}, requestId };
+  if (pluginRunner) {
+    pluginRunner.applyDecorations(pluginCtx.ctx);
+    const onRequest = await pluginRunner.runOnRequest(pluginCtx);
+    if (onRequest.shortCircuited) return;
+  }
   try {
-    for (; ; ) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      res.write(value);
-    }
-    res.end();
-  } finally {
-    reader.releaseLock();
+    await serve(request, pluginCtx);
+  } catch (err) {
+    if (pluginRunner) await pluginRunner.runOnError(pluginCtx, err);
+    sendError(res, "INTERNAL", messageOf2(err, failureMessage), 500, void 0, requestId);
   }
+  if (pluginRunner) await pluginRunner.runOnResponse(pluginCtx);
+}
+
+// src/server/http/resolve-agent-subject.ts
+function createAgentSubjectResolver(sources) {
+  let pending;
+  return () => {
+    pending ??= resolve5(sources);
+    return pending;
+  };
+}
+async function resolve5(sources) {
+  const { req, res, loadModule, serverDir, pluginRunner } = sources;
+  const produced = serverDir === void 0 ? {} : await createServerContext(req, res, loadModule, serverDir);
+  const ctx = produced ?? {};
+  pluginRunner?.applyDecorations(ctx);
+  return subjectFromContext(ctx);
 }
 
 // src/vite-plugin/agent-middleware.ts
 var PREFIX2 = "/api/agents/";
-async function serveApprove(req, res, urlPath, csrfMode, log) {
+async function serveApprove(req, res, urlPath, deps, log) {
   const method = (req.method ?? "POST").toUpperCase();
   if (method !== "POST") {
     sendError(
@@ -1565,24 +1610,36 @@ async function serveApprove(req, res, urlPath, csrfMode, log) {
     });
     return;
   }
-  try {
-    const response = await handleAgentApproval(
-      incomingMessageToWebRequest(req),
-      urlPath,
-      getApprovalRegistry(),
-      csrfMode
-    );
-    await writeWebResponseToServerResponse(response, res);
-  } catch (err) {
-    sendError(
+  await serveThroughPluginLifecycle(
+    {
+      source: createWebRequestSource(req),
       res,
-      "INTERNAL",
-      err instanceof Error ? err.message : "Approve handler failed",
-      500,
-      void 0,
-      log.requestId
-    );
-  }
+      requestId: log.requestId,
+      pluginRunner: deps.pluginRunner,
+      failureMessage: "Approve handler failed"
+    },
+    async (request) => {
+      const agent = scanAgents(deps.projectRoot, deps.agentsDir).find(
+        (a) => a.name === parseApprovalAgentName(urlPath)
+      );
+      const resolveSubject = createAgentSubjectResolver({
+        req,
+        res,
+        loadModule: deps.loadModule,
+        serverDir: deps.serverDir,
+        pluginRunner: deps.pluginRunner
+      });
+      const policy = agent === void 0 ? void 0 : readAgentPolicy(await deps.loadModule(agent.filePath), agent.filePath);
+      const response = await handleAgentApproval(
+        request,
+        urlPath,
+        getApprovalRegistry(),
+        deps.csrfMode,
+        { policy, resolveSubject }
+      );
+      await writeWebResponseToServerResponse(response, res);
+    }
+  );
   logRequest({
     method,
     url: req.url ?? "",
@@ -1594,54 +1651,69 @@ async function serveApprove(req, res, urlPath, csrfMode, log) {
 async function serveAux(req, res, next, urlPath, deps) {
   const requestId = randomUUID2();
   const start = Date.now();
-  try {
-    const request = incomingMessageToWebRequest(req);
-    const response = await serveAgentAuxRoute(request, urlPath, {
-      agents: scanAgents(deps.projectRoot, deps.agentsDir),
-      loadModule: deps.loadModule,
-      baseUrl: `http://${req.headers.host ?? "localhost"}`,
-      csrfMode: deps.csrfMode,
-      // M39 — the thread follow-up route drives the agent; resolve the key on demand.
-      // theokit#328 — the thread route drives an agent, so its key follows the model too.
-      resolveApiKey: (model) => resolveProvider(model).apiKey
-    });
-    if (response === null) {
-      next();
-      return;
-    }
-    res.setHeader("x-request-id", requestId);
-    await writeWebResponseToServerResponse(response, res);
-  } catch (err) {
-    res.setHeader("x-request-id", requestId);
-    sendError(
+  const auxDeps = {
+    agents: scanAgents(deps.projectRoot, deps.agentsDir),
+    loadModule: deps.loadModule,
+    baseUrl: `http://${req.headers.host ?? "localhost"}`,
+    csrfMode: deps.csrfMode,
+    // M39 — the thread follow-up route drives the agent; resolve the key on demand.
+    // theokit#328 — the thread route drives an agent, so its key follows the model too.
+    resolveApiKey: (model) => resolveProvider(model).apiKey,
+    // usetheokit/theokit#365 — parity with `theokit start`; lazy for the same reason.
+    resolveSubject: createAgentSubjectResolver({
+      req,
       res,
-      "INTERNAL",
-      err instanceof Error ? err.message : "Agent aux handler failed",
-      500,
-      void 0,
-      requestId
-    );
+      loadModule: deps.loadModule,
+      serverDir: deps.serverDir,
+      pluginRunner: deps.pluginRunner
+    })
+  };
+  const method = (req.method ?? "GET").toUpperCase();
+  const route = await matchAgentAuxRoute(method, urlPath, auxDeps);
+  if (route === null) {
+    next();
+    return;
   }
+  res.setHeader("x-request-id", requestId);
+  await serveThroughPluginLifecycle(
+    {
+      source: createWebRequestSource(req),
+      res,
+      requestId,
+      pluginRunner: deps.pluginRunner,
+      failureMessage: "Agent aux handler failed"
+    },
+    async (request) => {
+      await writeWebResponseToServerResponse(
+        await serveMatchedAuxRoute(route, request, auxDeps),
+        res
+      );
+    }
+  );
   logRequest({
-    method: (req.method ?? "GET").toUpperCase(),
+    method,
     url: req.url ?? "",
     status: res.statusCode,
     duration: Date.now() - start,
     requestId
   });
 }
-function createAgentMiddleware(vite, projectRoot, csrfMode = "strict", agentsDir = "agents", pluginRunner) {
+function createAgentMiddleware(vite, projectRoot, csrfMode = "strict", agentsDir = "agents", deps = {}) {
+  const { pluginRunner, serverDir } = deps;
   const loadModule = createViteLoader(vite);
+  const cardDeps = () => ({
+    projectRoot,
+    loadModule,
+    agentsDir,
+    csrfMode,
+    serverDir,
+    pluginRunner
+  });
   return (req, res, next) => {
     void (async () => {
       const url = req.url ?? "";
       if (isAgentCardPath(url.split("?")[0]) !== null) {
-        await serveAux(req, res, next, url.split("?")[0], {
-          projectRoot,
-          loadModule,
-          agentsDir,
-          csrfMode
-        });
+        await serveAux(req, res, next, url.split("?")[0], cardDeps());
         return;
       }
       if (!url.startsWith(PREFIX2)) {
@@ -1653,16 +1725,12 @@ function createAgentMiddleware(vite, projectRoot, csrfMode = "strict", agentsDir
       res.setHeader("x-request-id", requestId);
       const urlPath = url.split("?")[0];
       if (isApprovalPath(urlPath)) {
-        await serveApprove(req, res, urlPath, csrfMode, { requestId, start });
-        return;
-      }
-      if (isListApprovalsPath(urlPath) !== null || isMcpPath(urlPath) !== null) {
-        await serveAux(req, res, next, urlPath, { projectRoot, loadModule, agentsDir, csrfMode });
+        await serveApprove(req, res, urlPath, cardDeps(), { requestId, start });
         return;
       }
       const agent = scanAgents(projectRoot, agentsDir).find((a) => a.agentPath === urlPath);
       if (!agent) {
-        next();
+        await serveAux(req, res, next, urlPath, cardDeps());
         return;
       }
       const method = (req.method ?? "POST").toUpperCase();
@@ -1689,7 +1757,8 @@ function createAgentMiddleware(vite, projectRoot, csrfMode = "strict", agentsDir
         loadModule,
         csrfMode,
         projectRoot,
-        pluginRunner
+        pluginRunner,
+        serverDir
       });
     })();
   };
@@ -1706,65 +1775,44 @@ async function serveAgentTurn(t) {
     loadModule,
     csrfMode,
     projectRoot,
-    pluginRunner
+    pluginRunner,
+    serverDir
   } = t;
-  let pluginCtx;
-  let request;
-  try {
-    request = incomingMessageToWebRequest(req);
-    pluginCtx = { request, response: res, ctx: {}, requestId };
-  } catch (err) {
-    sendError(
+  const resolveSubject = createAgentSubjectResolver({
+    req,
+    res,
+    loadModule,
+    serverDir,
+    pluginRunner
+  });
+  await serveThroughPluginLifecycle(
+    {
+      source: createWebRequestSource(req),
       res,
-      "INTERNAL",
-      err instanceof Error ? err.message : "Agent handler failed",
-      500,
-      void 0,
-      requestId
-    );
-    logRequest({ method, url, status: res.statusCode, duration: Date.now() - start, requestId });
-    return;
-  }
-  if (pluginRunner) {
-    pluginRunner.applyDecorations(pluginCtx.ctx);
-    const onRequest = await pluginRunner.runOnRequest(pluginCtx);
-    if (onRequest.shortCircuited) {
-      logRequest({
-        method,
-        url,
-        status: res.statusCode,
-        duration: Date.now() - start,
-        requestId
+      requestId,
+      pluginRunner,
+      failureMessage: "Agent handler failed"
+    },
+    async (request) => {
+      const mod = await loadModule(agent.filePath);
+      const apiKey = (model) => resolveProvider(model).apiKey;
+      const response = await mountAgent(mod, request, apiKey, {
+        source: agent.filePath,
+        csrfMode,
+        projectRoot,
+        // usetheokit/theokit#365 — the policy comes off `mod`; the caller owes the identity.
+        // usetheokit/theokit#406 — and the same name labels the run's spans.
+        agentName: agent.name,
+        resolveSubject
       });
-      return;
+      await writeWebResponseToServerResponse(response, res);
     }
-  }
-  try {
-    const mod = await loadModule(agent.filePath);
-    const apiKey = (model) => resolveProvider(model).apiKey;
-    const response = await mountAgent(mod, request, apiKey, {
-      source: agent.filePath,
-      csrfMode,
-      projectRoot
-    });
-    await writeWebResponseToServerResponse(response, res);
-  } catch (err) {
-    if (pluginRunner) await pluginRunner.runOnError(pluginCtx, err);
-    sendError(
-      res,
-      "INTERNAL",
-      err instanceof Error ? err.message : "Agent handler failed",
-      500,
-      void 0,
-      requestId
-    );
-  }
-  if (pluginRunner) await pluginRunner.runOnResponse(pluginCtx);
+  );
   logRequest({ method, url, status: res.statusCode, duration: Date.now() - start, requestId });
 }
 
 // src/vite-plugin/api-middleware.ts
-import { resolve as resolve4 } from "path";
+import { resolve as resolve6 } from "path";
 function shouldBypassApiMiddleware(url, prefixes) {
   if (!url.startsWith("/api/")) return true;
   if (prefixes.length === 0) return false;
@@ -1812,10 +1860,10 @@ async function handleBatchIfMatch(req, res, ctx) {
 async function handleBatchInline(req, res, batching, requestId) {
   try {
     const chunks = [];
-    await new Promise((resolve10, reject) => {
+    await new Promise((resolve11, reject) => {
       req.on("data", (c) => chunks.push(c));
       req.on("end", () => {
-        resolve10();
+        resolve11();
       });
       req.on("error", reject);
     });
@@ -1871,7 +1919,7 @@ async function runPluginsBeforeRouteMatch(pluginRunner, reqCtx) {
 }
 async function tryControllerFallthrough(ctx) {
   const handled = await dispatchControllerRequest({
-    controllersDir: resolve4(ctx.serverDir, "controllers"),
+    controllersDir: resolve6(ctx.serverDir, "controllers"),
     loadModule: ctx.loadModule,
     req: ctx.req,
     res: ctx.res,
@@ -1880,6 +1928,14 @@ async function tryControllerFallthrough(ctx) {
     requestId: ctx.requestId,
     // M47 — serve @Expose-bound agent routes via the ONE runtime (mountAgent). CSRF is already enforced
     // once at the controller-dispatch boundary (G5), so mountAgent runs with csrfMode 'off' (no double gate).
+    //
+    // usetheokit/theokit#365 gated the CONVENTION endpoints (`agents/<name>.ts`) and deliberately
+    // left this one to the decorator stack: an `@Expose` route is a controller method, so its
+    // access decision is the controller's `@Guard` chain, which the dispatcher already runs before
+    // it gets here. Passing a policy as well would give this one surface two authorization
+    // mechanisms and no rule for which wins. What is NOT solved by that: an `@Expose`d agent shares
+    // the conversation store with the convention endpoints, so a guard that admits a caller admits
+    // them to whatever `sessionId` the body names — see the advisory.
     serveAgent: (agent, request) => mountAgent(agent, request, (model) => resolveProvider(model).apiKey, {
       source: "expose",
       csrfMode: "off"
@@ -2007,7 +2063,7 @@ function createApiMiddleware(vite, serverDir, rateLimitConfigOrOptions) {
 
 // src/vite-plugin/ssr-dev-middleware.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { resolve as resolve5 } from "path";
+import { resolve as resolve7 } from "path";
 
 // src/core/contracts/find-root-div.ts
 function maskHtmlComments(html) {
@@ -2098,7 +2154,7 @@ function setupSsrDevMiddleware(server, opts) {
         return;
       }
       try {
-        const indexPath = resolve5(opts.projectRoot, "index.html");
+        const indexPath = resolve7(opts.projectRoot, "index.html");
         let template = readFileSync2(indexPath, "utf-8");
         const nonce = generateNonce();
         template = await server.transformIndexHtml(url, template);
@@ -2217,7 +2273,12 @@ async function runConfigureServer(server, ctx) {
     })
   );
   server.middlewares.use(
-    createAgentMiddleware(server, ctx.projectRoot, ctx.csrfMode, ctx.agentsDir, ctx.pluginRunner)
+    createAgentMiddleware(server, ctx.projectRoot, ctx.csrfMode, ctx.agentsDir, {
+      pluginRunner: ctx.pluginRunner,
+      // usetheokit/theokit#365 — the same backend root the route middleware scans, so an agent's
+      // declared policy is judged against the identity `server/context.ts` establishes.
+      serverDir
+    })
   );
   const servicesProxyPrefixes = ctx.services && Object.keys(ctx.services).length > 0 ? Object.values(ctx.services).map((s) => s.proxy) : [];
   const csrfReadinessStore = ctx.csrfReadinessStoreOverride ?? new CsrfReadinessStore();
@@ -2236,7 +2297,7 @@ async function runConfigureServer(server, ctx) {
       csrfReadinessStore
     })
   );
-  const configPath = resolve6(ctx.projectRoot, "theo.config.ts");
+  const configPath = resolve8(ctx.projectRoot, "theo.config.ts");
   server.watcher.on("change", (file) => {
     if (file === configPath) {
       console.warn(
@@ -2264,9 +2325,9 @@ async function runConfigureServer(server, ctx) {
   server.watcher.on("unlink", handleRouteChange);
   if (ctx.resolvedOpenApi !== void 0) {
     const openApiCfg = ctx.resolvedOpenApi;
-    const { reEmitOpenApi } = await import("./dev-emit-NBT6JD7R.js");
+    const { reEmitOpenApi } = await import("./dev-emit-MVAJAFGX.js");
     const openApiServerDir = ctx.serverDir;
-    const openApiDistDir = resolve6(ctx.projectRoot, ctx.resolvedDistDir);
+    const openApiDistDir = resolve8(ctx.projectRoot, ctx.resolvedDistDir);
     const isRouteFileForOpenApi = (file) => file.startsWith(openApiServerDir) && /\.(ts|tsx|js|mjs)$/.test(file);
     void reEmitOpenApi(openApiServerDir, openApiDistDir, openApiCfg);
     server.watcher.on("change", (file) => {
@@ -2316,7 +2377,7 @@ async function integrateStudio(importStudio = () => import(
 // src/vite-plugin/integrate-ui.ts
 import { existsSync as existsSync6, readFileSync as readFileSync4 } from "fs";
 import { dirname as dirname3, join as join4 } from "path";
-import { pathToFileURL } from "url";
+import { pathToFileURL as pathToFileURL2 } from "url";
 
 // src/vite-plugin/auto-detect.ts
 import { existsSync as existsSync5, readFileSync as readFileSync3 } from "fs";
@@ -2448,7 +2509,7 @@ function resolveConsumerImport(name, cwd) {
         entry ??= pkg.module ?? pkg.main;
         if (!entry) return null;
         const cleaned = entry.replace(/^\.\//, "");
-        return pathToFileURL(join4(pkgDir, cleaned)).href;
+        return pathToFileURL2(join4(pkgDir, cleaned)).href;
       } catch {
         return null;
       }
@@ -2521,7 +2582,7 @@ async function integrateUseTheoUI(cwd, opts) {
     return [];
   }
   try {
-    uiMod = await import(pathToFileURL(uiPluginPath).href);
+    uiMod = await import(pathToFileURL2(uiPluginPath).href);
   } catch (err) {
     console.warn(
       `[theokit] @theokit/ui/vite-plugin dynamic import failed (${err.message}). Skipping auto-config.`
@@ -2571,19 +2632,9 @@ async function integrateUseTheoUI(cwd, opts) {
   return [...tailwindPlugins, ...uiPlugins];
 }
 
-// src/vite-plugin/resolve-theo-root.ts
-import { existsSync as existsSync7 } from "fs";
-import { resolve as resolve7 } from "path";
-function resolveTheoRootDir(currentDir) {
-  if (existsSync7(resolve7(currentDir, "client"))) {
-    return currentDir;
-  }
-  return resolve7(currentDir, "..");
-}
-
 // src/vite-plugin/transform-html-hook.ts
-import { existsSync as existsSync8 } from "fs";
-import { resolve as resolve8 } from "path";
+import { existsSync as existsSync7 } from "fs";
+import { resolve as resolve9 } from "path";
 
 // src/vite-plugin/inject-devtools.ts
 var DEVTOOLS_VIRTUAL_ID = "/@theo/devtools/entry.js";
@@ -2683,7 +2734,7 @@ function runTransformIndexHtml(html, ctx) {
   next = devtools.html;
   const styles = injectStylesheets(next, {
     isDev: ctx.isDevMode.value,
-    hasPackage: (name) => existsSync8(resolve8(ctx.projectRoot, "node_modules", ...name.split("/")))
+    hasPackage: (name) => existsSync7(resolve9(ctx.projectRoot, "node_modules", ...name.split("/")))
   });
   next = styles.html;
   return next;
@@ -2786,6 +2837,46 @@ function generateSingleShotEntry(options) {
     `}`
   ].join("\n");
 }
+function streamingDocumentHelpers() {
+  return [
+    `function __theoHydrationScript(hydrationData, nonce) {`,
+    // `<` is escaped rather than the whole payload: loader data is developer
+    // data, and the only sequence that can break out of a script element is
+    // `</script`. Mirrors what the non-streaming path does in request-handler.ts.
+    `  const json = JSON.stringify(hydrationData).replace(/</g, '\\u003c')`,
+    `  const attr = nonce ? ' nonce="' + nonce + '"' : ''`,
+    `  return '<script' + attr + '>window.__staticRouterHydrationData=' + json + '<' + '/script>'`,
+    `}`,
+    ``,
+    `function __theoDocumentStream(appStream, hydrationData, options) {`,
+    `  const encoder = new TextEncoder()`,
+    `  const head = options.htmlHead ?? ''`,
+    `  const tail = options.htmlTail ?? ''`,
+    `  return new ReadableStream({`,
+    `    async start(controller) {`,
+    // Its own chunk: the reader gets <head> before React has rendered anything.
+    `      if (head) controller.enqueue(encoder.encode(head))`,
+    `      const reader = appStream.getReader()`,
+    `      try {`,
+    `        for (;;) {`,
+    `          const { done, value } = await reader.read()`,
+    `          if (done) break`,
+    `          controller.enqueue(value)`,
+    `        }`,
+    `      } finally {`,
+    `        reader.releaseLock()`,
+    `      }`,
+    // The hydration script trails the app markup and precedes the tail, so it
+    // still runs before the client entry the tail loads.
+    `      controller.enqueue(`,
+    `        encoder.encode(__theoHydrationScript(hydrationData, options.nonce) + tail),`,
+    `      )`,
+    `      controller.close()`,
+    `    },`,
+    `  })`,
+    `}`
+  ];
+}
 function streamingWebRenderer(appTree) {
   return [
     `// T2.3 \u2014 Web Standards streaming entry for edge runtimes (Cloudflare,`,
@@ -2805,13 +2896,16 @@ function streamingWebRenderer(appTree) {
     // Streaming still applies to genuine data-fetching Suspense, which is where it earns its keep.
     // A failed import is swallowed on purpose: React.lazy will retry and suspend as before, which
     // is strictly no worse than not having preloaded at all.
-    `  const __theoMatches = matchRoutes(routes, url.split('?')[0]) ?? []`,
+    // `url` is a URL here, not the string the other renderers receive as a parameter —
+    // so the match key is `.pathname`, never `.split('?')`. Hoisting the declaration
+    // without changing the accessor trades the TDZ for a TypeError (#344).
+    `  const url = new URL(request.url)`,
+    `  const __theoMatches = matchRoutes(routes, url.pathname) ?? []`,
     `  await Promise.all(`,
     `    __theoPreloadPathsFor(__theoMatches).map((p) => __theoPreloadMap[p]().catch(() => null)),`,
     `  )`,
     ``,
     `  const handler = createStaticHandler(routes)`,
-    `  const url = new URL(request.url)`,
     `  const context = await handler.query(request)`,
     ``,
     `  if (context instanceof Response) {`,
@@ -2821,12 +2915,14 @@ function streamingWebRenderer(appTree) {
     `  const router = createStaticRouter(handler.dataRoutes, context)`,
     `  const app = ${appTree}`,
     ``,
+    hydrationDataExtractSnippet(),
+    ``,
     `  const stream = await renderToReadableStream(app, {`,
     `    signal: request.signal,`,
     `    nonce: options.nonce,`,
     `    onError(err) { console.error('[SSR Web Stream Error]', err) },`,
     `  })`,
-    `  return new Response(stream, {`,
+    `  return new Response(__theoDocumentStream(stream, hydrationData, options), {`,
     `    status: 200,`,
     `    headers: {`,
     `      'Content-Type': 'text/html; charset=utf-8',`,
@@ -2870,15 +2966,29 @@ function streamingNodeRenderer(appTree) {
     `  const router = createStaticRouter(handler.dataRoutes, context)`,
     `  const app = ${appTree}`,
     ``,
+    hydrationDataExtractSnippet(),
+    ``,
+    `  const { PassThrough } = await import('node:stream')`,
     `  return new Promise((resolve, reject) => {`,
     `    let didError = false`,
+    // React's `pipe(dest)` ends `dest` when the source ends, which would close the
+    // response before the hydration script could be written. Piping into a
+    // PassThrough keeps the response open for the tail.
+    `    const passthrough = new PassThrough()`,
+    `    passthrough.on('data', (chunk) => { response.write(chunk) })`,
+    `    passthrough.on('end', () => {`,
+    `      response.end(__theoHydrationScript(hydrationData, options.nonce) + (options.htmlTail ?? ''))`,
+    `    })`,
+    `    passthrough.on('error', reject)`,
     `    const stream = renderToPipeableStream(app, {`,
     `      nonce: options.nonce,`,
     `      onShellReady() {`,
     `        response.statusCode = didError ? 500 : 200`,
     `        response.setHeader('Content-Type', 'text/html; charset=utf-8')`,
     `        response.setHeader('Transfer-Encoding', 'chunked')`,
-    `        stream.pipe(response)`,
+    // The head goes out on its own write, before any React byte.
+    `        if (options.htmlHead) response.write(options.htmlHead)`,
+    `        stream.pipe(passthrough)`,
     `        resolve({ streaming: true })`,
     `      },`,
     `      onShellError(err) { reject(err) },`,
@@ -2962,6 +3072,8 @@ function generateStreamingEntry(options) {
     `import { routes, __theoPreloadMap, __theoPreloadPathsFor } from '/@theo/route-manifest'`,
     theoUiImport,
     ``,
+    ...streamingDocumentHelpers(),
+    ``,
     ...streamingWebRenderer(appTree),
     ``,
     ...streamingNodeRenderer(appTree),
@@ -3071,7 +3183,6 @@ function walkRouteTree(node, parents, acc) {
       routePath
     });
   }
-  if (node.layout !== void 0) acc.layoutState.found = true;
   pushIf(acc.staticImports, node.layout, safeVarName(seg, "Layout"));
   pushIf(acc.staticImports, node.error, safeVarName(seg, "Error"));
   pushIf(acc.staticImports, node.loading, safeVarName(seg, "Loading"));
@@ -3086,18 +3197,20 @@ function generateRouteManifest(tree, options = {}) {
   const lazyPages_ = options.lazyPages !== false;
   const acc = {
     staticImports: [],
-    lazyPages: [],
-    layoutState: { found: false }
+    lazyPages: []
   };
   walkRouteTree(tree, [], acc);
   const staticImports = acc.staticImports;
   const lazyPages = acc.lazyPages;
-  const layoutState = acc.layoutState;
   const lines = [`import React, { Suspense } from 'react'`];
-  if (layoutState.found) {
-    lines.push(`import { Outlet } from 'react-router'`);
-  }
-  lines.push("");
+  lines.push(
+    `import { Outlet, ScrollRestoration } from 'react-router'`,
+    // #421 — react-router restores the DOCUMENT. The layout this framework scaffolds scrolls an
+    // inner element, so the restoration that was mounted and running restored nothing. Both are
+    // emitted: one owns the document, the other owns the elements the app marked.
+    `import { ElementScrollRestoration } from 'theokit/router/element-scroll-restoration'`,
+    ""
+  );
   for (const imp of staticImports) {
     lines.push(`import ${imp.varName} from '${imp.importPath}'`);
   }
@@ -3151,16 +3264,20 @@ function generateRouteManifest(tree, options = {}) {
   function genRouteConfig(node, isRoot) {
     const seg = node.segment || "root";
     const childrenArray = buildChildrenArray(node, seg);
+    const withScrollRestoration = (element) => `React.createElement(React.Fragment, null, React.createElement(ScrollRestoration), React.createElement(ElementScrollRestoration), ${element})`;
     if (node.layout) {
       const layoutVar = safeVarName(seg, "Layout");
       const pathPart = isRoot ? `path: '/'` : `path: '${segmentPath(node)}'`;
-      return `{ ${pathPart}, element: React.createElement(${layoutVar}, { children: React.createElement(Outlet) }), children: ${childrenArray} }`;
+      const layoutElement = `React.createElement(${layoutVar}, { children: React.createElement(Outlet) })`;
+      const element = isRoot ? withScrollRestoration(layoutElement) : layoutElement;
+      return `{ ${pathPart}, element: ${element}, children: ${childrenArray} }`;
     }
     if (isRoot) {
+      const rootElement = withScrollRestoration(`React.createElement(Outlet)`);
       if (node.children.length === 0 && !node.page && !node.notFound && !node.error) {
-        return `{ path: '/', children: [] }`;
+        return `{ path: '/', element: ${rootElement}, children: [] }`;
       }
-      return `{ path: '/', children: ${childrenArray} }`;
+      return `{ path: '/', element: ${rootElement}, children: ${childrenArray} }`;
     }
     if (node.page && node.children.length === 0 && !node.error && !node.notFound) {
       const pageVar = safeVarName(seg, "Page");
@@ -3328,8 +3445,8 @@ function findConsumerConfig(projectRoot, basename2) {
   let dir = projectRoot;
   for (let level = 0; level < 3; level++) {
     for (const ext of extensions) {
-      const candidate = resolve9(dir, `${basename2}${ext}`);
-      if (existsSync9(candidate)) return candidate;
+      const candidate = resolve10(dir, `${basename2}${ext}`);
+      if (existsSync8(candidate)) return candidate;
     }
     const parent = dirname4(dir);
     if (parent === dir) break;
@@ -3340,7 +3457,7 @@ function findConsumerConfig(projectRoot, basename2) {
 async function theoPluginAsync(rootOrOptions) {
   const options = typeof rootOrOptions === "string" ? { root: rootOrOptions } : rootOrOptions ?? {};
   const projectRoot = options.root ?? process.cwd();
-  const serverDirAbs = resolve9(projectRoot, options.serverDir ?? "server");
+  const serverDirAbs = resolve10(projectRoot, options.serverDir ?? "server");
   const agentsDirName = options.agentsDir ?? "agents";
   const consumerTailwindConfig = findConsumerConfig(projectRoot, "tailwind.config");
   const consumerPostcssConfig = findConsumerConfig(projectRoot, "postcss.config");
@@ -3359,23 +3476,23 @@ async function theoPluginAsync(rootOrOptions) {
       })
     );
   }
-  const { appTypedClientPlugin } = await import("./app-typed-client-HLP26EYM.js");
+  const { appTypedClientPlugin } = await import("./app-typed-client-XGDZKH73.js");
   const appClientPlugin = appTypedClientPlugin({
     cwd: projectRoot,
     serverDir: serverDirAbs,
-    distDir: resolve9(projectRoot, ".theokit")
+    distDir: resolve10(projectRoot, ".theokit")
   });
-  const { actionsVirtualModule } = await import("./actions-virtual-module-E4PISKMB.js");
+  const { actionsVirtualModule } = await import("./actions-virtual-module-RXL2RJTW.js");
   const actionsPlugin = actionsVirtualModule({
     serverDir: serverDirAbs,
-    distDir: resolve9(projectRoot, ".theokit")
+    distDir: resolve10(projectRoot, ".theokit")
   });
   const { agentsTypedClientPlugin } = await import("./agents-typed-client-INR2E7B3.js");
-  const { generateManifest } = await import("./internal-api-ZCJWJ5EC.js");
+  const { generateManifest } = await import("./internal-api-XQHU5JKY.js");
   const agentsClientPlugin = agentsTypedClientPlugin({
     projectRoot,
     agentsDir: agentsDirName,
-    distDir: resolve9(projectRoot, ".theokit"),
+    distDir: resolve10(projectRoot, ".theokit"),
     // Agents live at <projectRoot>/<agentsDir>; generateManifest scans them via the server dir's
     // parent (projectRoot for the canonical layout) + the agents dir name (#95 follow-up).
     scanManifest: () => generateManifest(serverDirAbs, projectRoot, agentsDirName)
@@ -3388,11 +3505,17 @@ async function theoPluginAsync(rootOrOptions) {
   const controllerTransformPlugin = controllerSwcTransformPlugin({
     serverDir: serverDirAbs
   });
+  const { serverOnlyImportBoundary } = await import("./server-boundary-2WFT546S.js");
+  const serverBoundaryPlugin = serverOnlyImportBoundary({
+    projectRoot,
+    serverDir: serverDirAbs
+  });
   return [
     theoPlugin(rootOrOptions),
     ...uiPlugins,
     ...studioPlugins,
     ...servicesPlugins,
+    serverBoundaryPlugin,
     // #122 — swc-compile controllers/** (enforce:'pre'; order-independent).
     controllerTransformPlugin,
     appClientPlugin,
@@ -3403,10 +3526,10 @@ async function theoPluginAsync(rootOrOptions) {
 }
 function buildOptimizeDepsInclude(projectRoot, viteOptimizeDeps) {
   const include = [];
-  if (existsSync9(resolve9(projectRoot, "node_modules", "@theokit", "ui"))) {
+  if (existsSync8(resolve10(projectRoot, "node_modules", "@theokit", "ui"))) {
     include.push("@theokit/ui");
   }
-  if (existsSync9(resolve9(projectRoot, "node_modules", "lucide-react"))) {
+  if (existsSync8(resolve10(projectRoot, "node_modules", "lucide-react"))) {
     include.push("lucide-react");
   }
   include.push("devalue");
@@ -3432,8 +3555,8 @@ var VIRTUAL_MODULE_IDS = {
 function theoPlugin(rootOrOptions) {
   const options = typeof rootOrOptions === "string" ? { root: rootOrOptions } : rootOrOptions ?? {};
   const projectRoot = options.root ?? process.cwd();
-  const appDir = resolve9(projectRoot, options.appDir ?? "app");
-  const serverDir = resolve9(projectRoot, options.serverDir ?? "server");
+  const appDir = resolve10(projectRoot, options.appDir ?? "app");
+  const serverDir = resolve10(projectRoot, options.serverDir ?? "server");
   const agentsDir = options.agentsDir ?? "agents";
   const ssrEnabled = options.ssr ?? false;
   const currentDir = dirname4(fileURLToPath(import.meta.url));
@@ -3565,4 +3688,4 @@ export {
   theoPluginAsync,
   theoPlugin
 };
-//# sourceMappingURL=chunk-FTFN4MYN.js.map
+//# sourceMappingURL=chunk-7AEBH52I.js.map