xbintsc 0.5.52 → 0.6.9

package/doc/zh-CN/implemented/modules.md

@@ -21,10 +21,14 @@
 
 ## 延迟求值
 
-- `gui` 的 `.html` 资产加载器用合成的 `__xt_deferred_module` 绑定标记相对的
-  `<script src>` import。bundler 会把该模块及其本地 import 图包装成返回各自
-  导出的函数，生成的脚本在 `loadHTML` 之后调用它们（`__xt_defer` 对每个模块
-  做记忆化）。这与浏览器的模块脚本一致：文档就绪后才求值 import 图。
+- `gui` 的 `.html` 资产加载器用合成的 `__xt_deferred_module` 绑定标记内联
+  `<script>` 主体与 `<script src>` 文件的相对 import。bundler 会把该模块及其
+  本地 import 图包装成返回各自导出的函数，生成的脚本在 `loadHTML` 之后调用它们
+  （`__xt_defer` 对每个模块做记忆化）。这与浏览器的模块脚本一致：文档就绪后才
+  求值 import 图。
+- 两种脚本写法使用同一套拆分逻辑：顶层 `import`/`export … from` 语句被提升进
+  生成模块，`export` 修饰符被去掉，因此裸说明符或 `node:` 说明符与普通模块
+  import 一样链接。
 - 同时被普通（非标记）import 引用的模块保持立即求值，并获得一个返回已初始化
   导出的薄包装。
 - 包装体是同步的：延迟脚本模块中的顶层 `await` 不受支持。

package/doc/zh-CN/implemented/node/child-process.md

@@ -5,16 +5,23 @@
 位置：`src/extensions/node/child_process/index.ts`、`runtime/ext_node/child_process/child_process.c`
 
 `spawnSync(command, args[, options])` 运行一个程序直到结束，返回
-`{ status, stdout, stderr }`。`options.cwd` 设置子进程工作目录；
-`options.stdio: "inherit"` 让子进程共用父进程的 stdout/stderr（`xbintsc run`
-用它把被编译程序的输出实时透传），否则 stdout/stderr 会作为 UTF-8 字符串捕获。
+`{ status, stdout, stderr }`。`options.cwd` 设置子进程工作目录，`options.env`
+替换子进程的环境变量，`options.stdio: "inherit"` 让子进程共用父进程的
+stdout/stderr（`xbintsc run` 用它把被编译程序的输出实时透传），否则
+stdout/stderr 会作为 UTF-8 字符串捕获。
 
 | 选项 | 说明 |
 | --- | --- |
 | `cwd` | 子进程的工作目录 |
+| `env` | 子进程的完整环境变量；不传则继承父进程，想扩展就展开 `process.env` |
 | `stdio: "inherit"` | 共用父进程的 stdout/stderr，而不是捕获 |
 | `encoding` | 接受但忽略（输出始终按 UTF-8 解码） |
 
+`env` 遵循 Node 的替换语义：传了对象，它就是子进程的完整环境，调用方没列出的
+变量在子进程里不存在。这正是调用方能把特定的 `SDKROOT`、`INCLUDE`、`LIB` 交给
+工具链、又不泄漏自身 shell 环境的原因；自举出来的编译器跑的就是这段代码，macOS
+的 SDK 修复也依赖它。
+
 Windows 上子进程通过 `CreateProcess` 启动，stdout/stderr 由读线程经匿名管道持续排空。
 不使用临时文件，因此受限的 `%TEMP%` 不会让 `spawnSync` 失败，输出超过管道缓冲区时
 也不会死锁。

package/doc/zh-CN/implemented/runtime-core.md

@@ -27,5 +27,5 @@
 - 运算符辅助：`xt_in`（`in`）、`xt_delete`（`delete`）、`xt_rest_args`（剩余参数 / `arguments`）。
 - Box：`box_new/get/set`（用于闭包捕获变量）。
 - 函数与闭包：`arg`、`closure_new/call/env/arity`。
-- 异常：`xt_try_enter` / `xt_try_exception` / `xt_try_leave` 维护 `_setjmp` 帧栈；`xt_throw` 在存在帧时长跳到最近 `try`，否则打印 `Uncaught ...` 后退出。codegen 还会维护一条影子调用栈（函数名、源文件、行号）：`Error.stack` 用它生成堆栈（见[标准库](./stdlib.md)），原生崩溃时致命信号处理器也会打印同一组帧。`--debug` 还会生成 `!DICompileUnit` / `!DISubprogram` / `!DILocation` 元数据，并用 `-g -fno-omit-frame-pointer` 编译，因此 gdb/lldb/WinDbg 可以把指令映射回源码行。
+- 异常：`xt_try_enter` / `xt_try_exception` / `xt_try_leave` 维护 `_setjmp` 帧栈；`xt_throw` 在存在帧时长跳到最近 `try`，否则打印 `Uncaught ...` 后退出。无人观察的 promise rejection 同样是致命的：事件循环排空后 `xt_promise_report_unhandled` 会打印 `Unhandled promise rejection` 与原因，并以状态码 1 退出（见[异步](./async.md)）。codegen 还会维护一条影子调用栈（函数名、源文件、行号）：`Error.stack` 用它生成堆栈（见[标准库](./stdlib.md)），原生崩溃时致命信号处理器也会打印同一组帧。`--debug` 还会生成 `!DICompileUnit` / `!DISubprogram` / `!DILocation` 元数据，并用 `-g -fno-omit-frame-pointer` 编译，因此 gdb/lldb/WinDbg 可以把指令映射回源码行。
 - 对象 / 函数：`xt_object` 带原型链，`xt_function` 带属性包（静态成员与 `prototype`）；`xt_new`（实例化）、`xt_instance_of`（原型链）、`xt_object_freeze/is_frozen/from_entries`；`xt_constructors.c` 保存一等公民构造器缓存、构造器原型与静态值分派。

package/doc/zh-CN/npm-package.md

@@ -201,8 +201,24 @@ Hello from xbintsc
 （不一定是配置文件所在目录）；可以用 `xbintsc_CACHE_DIR` 改到别处。这种回退构建
 会明显比后续构建慢。
 
+预编译归档由发布机的工具链生成，面向
+[使用前置要求](./requirements.md#支持的平台)中的下限（macOS 11.0、Windows 11、
+glibc 2.39）。如果它比本机的工具链新——例如更新的 Xcode Command Line
+Tools/SDK 或 Visual Studio C++ 生成工具——链接器可能拒绝该归档，报未定义符号
+（`LNK2038`、`LNK2019`、`Undefined symbols`、`undefined reference`）或
+`was built for newer macOS version` 警告。此时驱动会**自动**用包内自带的源码重新
+编译 `core`/`ext_node` 并重试链接，所以归档版本不匹配只会多花时间，不会让构建失败：
+
+```text
+xbintsc: the prebuilt runtime archive does not match this toolchain (…); compiling the C runtime from source
+```
+
+这个回退不会被记住：升级工具链之后，后续构建仍会重新尝试预编译归档。随包的
+`gui.a`/`media.a` 是例外——它们内含 SDL3/FFmpeg，npm 包里没有这些源码，无法这样
+重编。如果冲突的是它们，请使用与本机工具链匹配的发布包，或在源码检出中构建。
+
 如果确实想忽略平台包归档、改从主包自带的源码编译 C 运行时（例如修改了
-`runtime/`，或预编译归档与当前环境不匹配），可以设置：
+`runtime/`），可以设置：
 
 ```bash
 xbintsc_PREFER_PREBUILT=0 npx xbintsc build src/main.ts --out build
@@ -408,6 +424,7 @@ npm 包通过可选平台包获得同一套预编译运行时，只有在跳过
 | 第一次构建很慢 | 可选包 `@xbintsc/<os>-<arch>` 被跳过（或该宿主没有预编译包），正在编译并缓存运行时 C 源码。用 `npm ls @xbintsc/<os>-<arch>` 检查，并去掉 `--omit=optional` 重新安装；`--time` 可确认。 |
 | 写 `.xbintsc/` 权限错误 | 用 `xbintsc_CACHE_DIR` 指向可写目录，或在可写目录中运行。 |
 | `module 'fs' is provided by the 'node' extension` | 加 `--ext node`，或在配置里写 `"extensions": ["node"]`。 |
+| 链接报 `LNK2038`、`LNK2019`、`Undefined symbols` 或 `was built for newer macOS version` | 预编译归档由更新的 Xcode/Visual Studio 工具链构建。驱动会自动改用运行时的 C 源码重试链接；若仍然失败，冲突的是 `gui.a`/`media.a`，无法从 npm 包重编——请使用匹配的发布包或源码检出。 |
 | `GUI native library not found` / `media native library not found` | 携带 `gui.a`/`gui.lib` 或 `media.a`/`media.lib` 的可选平台包被跳过，或该宿主没有预编译的 GUI/media 归档（Windows arm64）。去掉 `--omit=optional` 重新安装，或使用 Linux/macOS/Windows x64 发布压缩包，或从源码检出构建。自动检测到的 `media` 特性缺归档只会 warning；`--feature media` 才会报错。 |
 | `require("xbintsc")` 失败 | 包只提供 ESM；使用 `import`（或动态 `import()`）。 |
 | Windows 链接时报缺少 MSVC 库 | 在 Native Tools 命令提示符中运行，安装 VS C++ 生成工具，并检查 `npx xbintsc doctor`。 |

package/doc/zh-CN/post/make-js-great-again.md

@@ -0,0 +1,32 @@
+# 这可能是今年最让JS开发者激动的事情了
+
+![3D鹈鹕骑自行车](../../../examples/gui/pelican-3d/preview.png)
+
+上面是我用JS+HTML+WebGL2做的鹈鹕3D骑自行车，FPS也非常不错。
+
+你可能会说“这不是用Ai有手就行了么？”
+
+但是，如果我说我把这上面用xbintsc编译成原生二进制，还不到10MB,还能在没有WebView环境上跑，还能支持Node.js和HTML混写，如下：
+
+```html
+<html>
+    <body>
+    <div id="out">loading...</div>
+    <script lang="ts">
+        import { readFileSync } from "fs";
+
+        const out = document.getElementById("out");
+        const world = readFileSync("data.txt", "utf8");
+        out.textContent = "hello " + world;
+    </script>
+    </body>
+</html>
+```
+
+要知道以前光chrome最少也得有100MB，用xbintsc编译产物10MB还不需要WebView环境，这可不仅仅代表桌面端开发体积极大减小和更加正确的实现路径的问题。
+
+更加具有划时代意义的是，JS开发者在嵌入式设备跑你想要做的应用成为了可能。
+
+[xbintsc开源地址](https://github.com/zy445566/xbintsc)
+
+

package/doc/zh-CN/requirements.md

@@ -14,6 +14,27 @@ xbintsc 不再自带编译器，因此每个平台都需要安装一个兼容 cl
 如果通过 npm 安装编译器而不是使用发布压缩包，Node.js 22+ 会直接运行编译器本身；
 见[通过 npm 包使用 xbintsc](./npm-package.md)。
 
+## 支持的平台
+
+发布二进制和预编译运行库归档面向 xbintsc 支持的最低平台版本。CI 使用**各宿主仍
+能产出发布包的最老工具链**构建它们，因此你机器上更新的 Xcode 或 Visual Studio 可以链接
+这些产物；反过来（旧工具链链接新产物）才会出现 `LNK2038`、`Undefined symbols` 或
+`was built for newer macOS version`。
+
+| 平台 | 生成的二进制可运行于 | 构建基线（CI） |
+| --- | --- | --- |
+| macOS x64 / arm64 | **macOS 11.0**（Big Sur）及以上 | 镜像中最老的 clang 16+ Xcode，`MACOSX_DEPLOYMENT_TARGET=11.0` |
+| Windows x64 | **Windows 11** 及以上 | `windows-2025` 镜像自带的工具链（当前为 VS 2026） |
+| Windows arm64 | **Windows 11** | `windows-11-arm` 镜像自带的工具链（当前为 VS 2026；没有更老的 arm64 镜像） |
+| Linux x64 / arm64 | **glibc 2.39**（Ubuntu 24.04）及以上 | `ubuntu-24.04` 上的 clang 16 + lld 16 |
+
+编译器工具链下限为：macOS 上的 Xcode 16（Apple clang 16）、Windows 上 `windows-2025`
+镜像自带的 Visual Studio（当前为 VS 2026）、Linux 上的 clang 16。因此构建机的要求比生成二进制的
+运行要求更高：Xcode 16 本身需要 macOS 14.5+，macOS 11–14 的构建机需要另外安装
+LLVM 16+（例如 Homebrew 的 `llvm`）。`xbintsc doctor` 会打印当前宿主的支持下限。如果归档是用比本机更新的工具链构建的，`build` 会自动改用随包 C 源码
+重试（见 [npm 包指南](./npm-package.md#首次构建与缓存)）；随包的 `gui.a`/`media.a`
+无法这样重编，因为 SDL3/FFmpeg 的源码不在包里。
+
 clang 15 及更旧版本会在任何程序的第一个字符串字面量处失败：
 
 ```
@@ -104,6 +125,10 @@ xcode-select -p            # 打印当前开发者目录
 xcrun --show-sdk-path      # 打印 SDK 路径
 ```
 
+xbintsc 会自己执行第二条命令，并把结果以 `-isysroot` 传给 clang，因此即使 clang
+是用绝对路径选中的（CI 的基线 Xcode，或 `xbintsc_CLANG`），也仍能找到 SDK 里的
+C 头文件与链接桩。自己设置 `SDKROOT` 优先，可用它固定某个 SDK。
+
 ## Linux —— 安装 clang 与 lld
 
 常规的 glibc 发行版加上 `clang`、`lld` 即可：
@@ -129,8 +154,11 @@ winget install -e --id Microsoft.VisualStudio.2022.BuildTools `
   --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --includeRecommended"
 ```
 
-Visual Studio 2022 自带的 LLVM（`VC\Tools\Llvm\x64\bin\clang.exe`，当前版本
-19.1.5）就是 `scripts/setup-vs-toolchain.ps1` 选择的工具链。独立安装的 LLVM
+Visual Studio 自带的 LLVM（`VC\Tools\Llvm\x64\bin\clang.exe`，当前 2022 安装中
+为 19.1.5）就是 `scripts/setup-vs-toolchain.ps1` 选择的工具链。`xbintsc` 会探测
+两种安装布局——按年份命名的旧布局（`2019`、`2022`）以及 Visual Studio 2026 及
+之后按主版本号命名的布局（`18\Community`、`18\Insiders` 等）——因此更新版本的
+安装无需设置 `xbintsc_CLANG` 也能被发现。独立安装的 LLVM
 （`winget install -e --id LLVM.LLVM`）对 `xbintsc` 本身也可用，但 GUI/媒体
 归档构建与 CI 都使用 Visual Studio 这一套，从而让运行时、预编译归档与最终
 二进制出自同一条工具链。无论哪种，编译器必须以 MSVC ABI 为目标

package/doc/zh-CN/unimplemented/deviations.md

@@ -16,6 +16,7 @@
 | 内存管理 | 非移动标记-清扫回收器（在 `xt_alloc` 之后）：显式根、子系统根提供者与保守 C 栈扫描。单线程、stop-the-world；无移动/压缩与分代 |
 | 函数 `arity` / 调用参数个数 | 对本地可见函数的直接调用由默认[语义检查](../implemented/checker.md)校验（`TS4004`）；通过属性、导入、展开实参或重新赋值后的绑定发起的调用不校验。`fn.length` 报告声明的 arity |
 | `async` / `await` | 已在栈式协程上真实挂起；`await` 总会排入一次微任务（非 Promise 与已 settle 的 Promise 也一样），因此与 pending `.then` 回调的交错顺序符合规范。顶层 `await` 会阻塞事件循环等待，而不是让出模块主体。`fs/promises` 与 `fetch` 把阻塞工作 offload 到 4 线程池并在 reactor 上 settle。异步生成器可在 `await` 与 `yield` 处挂起，`for await...of` 每次迭代等待一步 |
+| 未处理的 rejection | 在程序结束时才报告，而不是在当轮 tick 结束时：无人观察的 rejection 会在事件循环排空后打印并使进程以状态码 1 退出，因此长期运行的进程（如服务端）会一直运行到退出，稍后补挂的处理函数也仍会抑制该报告。Node 在微任务队列排空后立即抛出致命错误 |
 | 异步生成器清理 | `for await...of` 提前退出时不会调用迭代器的 `return()`。异步生成器中的 `yield*` 只委托同步可迭代对象。在挂起的 `yield` 处调用 `.return()` 会直接完成而不执行 `finally`（与同步生成器相同的限制） |
 | `super` | `super.x` / `super[x]` 从当前执行类的父级持有者读取（实例方法中是父原型，`static` 方法或静态块中是父构造函数），因此任意继承深度都正确 |
 | `Error.stack` | 仅函数级帧：每帧为 `at 名称 (文件:行)`，行号取自函数声明（最内层帧会更新为错误构造处）；没有列号，生成器 / `async` 函数体不产生帧（它们会切换栈） |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xbintsc",
-  "version": "0.5.52",
+  "version": "0.6.9",
   "description": "xbintsc - a TypeScript binary compiler (TypeScript -> LLVM IR -> native binary)",
   "type": "module",
   "license": "MIT",
@@ -72,12 +72,12 @@
     "vitest": "^2.1.8"
   },
   "optionalDependencies": {
-    "@xbintsc/linux-x64": "0.5.52",
-    "@xbintsc/linux-arm64": "0.5.52",
-    "@xbintsc/darwin-x64": "0.5.52",
-    "@xbintsc/darwin-arm64": "0.5.52",
-    "@xbintsc/win32-x64": "0.5.52",
-    "@xbintsc/win32-arm64": "0.5.52"
+    "@xbintsc/linux-x64": "0.6.9",
+    "@xbintsc/linux-arm64": "0.6.9",
+    "@xbintsc/darwin-x64": "0.6.9",
+    "@xbintsc/darwin-arm64": "0.6.9",
+    "@xbintsc/win32-x64": "0.6.9",
+    "@xbintsc/win32-arm64": "0.6.9"
   },
   "engines": {
     "node": ">=22"

package/runtime/ext_node/child_process/child_process.c

@@ -7,9 +7,10 @@
  *   const result = spawnSync("clang", ["--version"], { cwd, encoding: "utf8" });
  *   result.status / result.stdout / result.stderr
  *
- * `options.cwd` is honoured; stdout/stderr are always captured as UTF-8
- * strings. On Windows the process is run with `_spawnvp` and redirected
- * through temporary files (which also avoids pipe-buffer deadlocks).
+ * `options.cwd` and `options.env` are honoured (the latter with Node's replace
+ * semantics); stdout/stderr are always captured as UTF-8 strings. On Windows
+ * the child runs under `CreateProcess` with anonymous pipes drained by reader
+ * threads (which also avoids pipe-buffer deadlocks).
  */
 
 #include "rt.h"
@@ -60,6 +61,58 @@ static int option_stdio_inherit(xt_value options) {
   return stdio && XT_IS_STRING(stdio) && strcmp(xt_string_data(stdio), "inherit") == 0;
 }
 
+/*
+ * `options.env` replaces the child's environment, exactly like Node: an absent
+ * option inherits the parent's environment, while a present one is the complete
+ * environment (spread `process.env` into it to extend rather than replace).
+ *
+ * The runtime used to ignore this option, which made every `spawnSync` inherit:
+ * a caller passing `SDKROOT` or `INCLUDE` silently got nothing, and a
+ * self-hosted compiler could not hand the macOS SDK to clang.
+ */
+
+/** The `env` object, or `XT_UNDEFINED` when the child should inherit. */
+static xt_value option_env(xt_value options) {
+  if (!XT_IS_OBJECT(options)) return XT_UNDEFINED;
+  xt_value env = xt_object_get(options, xt_string_from_cstr("env"));
+  return XT_IS_OBJECT(env) ? env : XT_UNDEFINED;
+}
+
+/** The number of `KEY=VALUE` entries the environment object provides. */
+static int32_t env_size(xt_value env) {
+  xt_value keys = xt_object_keys(env);
+  return XT_IS_ARRAY(keys) ? xt_array_size(keys) : 0;
+}
+
+static void free_env_entries(char **entries, int32_t count) {
+  if (entries == NULL) return;
+  for (int32_t i = 0; i < count; i++) free(entries[i]);
+  free(entries);
+}
+
+/** `KEY=VALUE` entries for the environment object, in object key order. */
+static char **env_entries(xt_value env, int32_t count) {
+  char **entries = (char **)calloc((size_t)(count > 0 ? count : 1), sizeof(char *));
+  if (entries == NULL) return NULL;
+  xt_value keys = xt_object_keys(env);
+  xt_value *items = XT_IS_ARRAY(keys) ? xt_array_items(keys) : NULL;
+  for (int32_t i = 0; i < count; i++) {
+    xt_value key = items[i];
+    xt_value raw = xt_object_get(env, key);
+    /* Node ignores `undefined` values instead of passing "undefined". */
+    if (XT_IS_UNDEFINED(raw)) continue;
+    const char *name = xt_string_data(xt_to_string(key));
+    const char *value = xt_string_data(xt_to_string(raw));
+    if (name == NULL || value == NULL) continue;
+    size_t length = strlen(name) + strlen(value) + 2;
+    char *entry = (char *)malloc(length);
+    if (entry == NULL) continue;
+    snprintf(entry, length, "%s=%s", name, value);
+    entries[i] = entry;
+  }
+  return entries;
+}
+
 static xt_value make_result(double status, const char *out, const char *err) {
   xt_value result = xt_object_new();
   xt_set(result, xt_string_from_cstr("status"), xt_number(status));
@@ -181,18 +234,60 @@ static char *build_command_line(char **child_argv, int count) {
   return line;
 }
 
+/* `CreateProcessA` wants one ANSI block, entries sorted case-insensitively. */
+static int compare_env_entries(const void *left, const void *right) {
+  const char *a = *(const char *const *)left;
+  const char *b = *(const char *const *)right;
+  if (a == NULL) return b == NULL ? 0 : 1;
+  if (b == NULL) return -1;
+  return _stricmp(a, b);
+}
+
+/** The environment block for `CreateProcessA`, or NULL to inherit. */
+static char *build_env_block(xt_value env) {
+  if (!XT_IS_OBJECT(env)) return NULL;
+  int32_t count = env_size(env);
+  char **entries = env_entries(env, count);
+  if (entries == NULL) return NULL;
+  qsort(entries, (size_t)count, sizeof(char *), compare_env_entries);
+  size_t total = 1;
+  for (int32_t i = 0; i < count; i++) total += entries[i] != NULL ? strlen(entries[i]) + 1 : 0;
+  char *block = (char *)malloc(total + 1);
+  if (block == NULL) {
+    free_env_entries(entries, count);
+    return NULL;
+  }
+  char *cursor = block;
+  for (int32_t i = 0; i < count; i++) {
+    if (entries[i] == NULL) continue;
+    size_t length = strlen(entries[i]) + 1;
+    memcpy(cursor, entries[i], length);
+    cursor += length;
+  }
+  /* The block ends with an extra terminator; an empty environment is "\0\0". */
+  *cursor++ = 0;
+  *cursor = 0;
+  free_env_entries(entries, count);
+  return block;
+}
+
 xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   const char *command = argc > 0 ? xt_string_data(xt_to_string(argv[0])) : NULL;
   if (!command) command = "";
   xt_value args = argc > 1 ? argv[1] : XT_UNDEFINED;
   const char *cwd = argc > 2 ? option_cwd(argv[2]) : NULL;
+  char *env_block = build_env_block(option_env(argc > 2 ? argv[2] : XT_UNDEFINED));
 
   int count = 0;
   char **child_argv = (char **)build_argv(command, args, &count);
-  if (!child_argv) return make_result(-1, "", "out of memory");
+  if (!child_argv) {
+    free(env_block);
+    return make_result(-1, "", "out of memory");
+  }
   char *command_line = build_command_line(child_argv, count);
   if (!command_line) {
     free(child_argv);
+    free(env_block);
     return make_result(-1, "", "out of memory");
   }
 
@@ -204,9 +299,10 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
 
   if (option_stdio_inherit(argc > 2 ? argv[2] : XT_UNDEFINED)) {
     BOOL created = CreateProcessA(
-      NULL, command_line, NULL, NULL, TRUE, 0, NULL, cwd, &startup, &process);
+      NULL, command_line, NULL, NULL, TRUE, 0, env_block, cwd, &startup, &process);
     free(command_line);
     free(child_argv);
+    free(env_block);
     if (!created) return make_result(-1, "", "failed to start process");
     WaitForSingleObject(process.hProcess, INFINITE);
     DWORD exit_code = 0;
@@ -229,6 +325,7 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
     close_capture_pipe(&err_pipe);
     free(command_line);
     free(child_argv);
+    free(env_block);
     return make_result(-1, "", "could not create pipes");
   }
   startup.dwFlags = STARTF_USESTDHANDLES;
@@ -237,9 +334,10 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   startup.hStdError = err_write;
 
   BOOL created = CreateProcessA(
-    NULL, command_line, NULL, NULL, TRUE, 0, NULL, cwd, &startup, &process);
+    NULL, command_line, NULL, NULL, TRUE, 0, env_block, cwd, &startup, &process);
   free(command_line);
   free(child_argv);
+  free(env_block);
   CloseHandle(out_write);
   CloseHandle(err_write);
   if (!created) {
@@ -285,30 +383,68 @@ static void append_chunk(char **buffer, size_t *length, size_t *capacity, const
   (*buffer)[*length] = 0;
 }
 
+/** A NULL-terminated `envp` for `exec`, or NULL when the child inherits. */
+static char **build_envp(xt_value env) {
+  if (!XT_IS_OBJECT(env)) return NULL;
+  int32_t count = env_size(env);
+  char **entries = env_entries(env, count);
+  if (entries == NULL) return NULL;
+  char **envp = (char **)calloc((size_t)count + 1, sizeof(char *));
+  if (envp == NULL) {
+    free_env_entries(entries, count);
+    return NULL;
+  }
+  int32_t kept = 0;
+  for (int32_t i = 0; i < count; i++) {
+    if (entries[i] != NULL) envp[kept++] = entries[i];
+  }
+  envp[kept] = NULL;
+  /* The strings now belong to `envp`; only the index array is released here. */
+  free(entries);
+  return envp;
+}
+
+/** Release an `envp` built by {@link build_envp}. */
+static void free_envp(char **envp) {
+  if (envp == NULL) return;
+  for (char **entry = envp; *entry != NULL; entry++) free(*entry);
+  free(envp);
+}
+
 xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   const char *command = argc > 0 ? xt_string_data(xt_to_string(argv[0])) : NULL;
   if (!command) command = "";
   xt_value args = argc > 1 ? argv[1] : XT_UNDEFINED;
   const char *cwd = argc > 2 ? option_cwd(argv[2]) : NULL;
+  char **envp = build_envp(option_env(argc > 2 ? argv[2] : XT_UNDEFINED));
 
   int count = 0;
   char **child_argv = (char **)build_argv(command, args, &count);
-  if (!child_argv) return make_result(-1, "", "out of memory");
+  if (!child_argv) {
+    free_envp(envp);
+    return make_result(-1, "", "out of memory");
+  }
 
   if (option_stdio_inherit(argc > 2 ? argv[2] : XT_UNDEFINED)) {
     pid_t inherit_pid = fork();
     if (inherit_pid < 0) {
       free(child_argv);
+      free_envp(envp);
       return make_result(-1, "", "failed to fork");
     }
     if (inherit_pid == 0) {
       if (cwd) chdir(cwd);
+      if (envp != NULL) {
+        extern char **environ;
+        environ = envp;
+      }
       execvp(command, child_argv);
       _exit(127);
     }
     int inherit_status = 0;
     waitpid(inherit_pid, &inherit_status, 0);
     free(child_argv);
+    free_envp(envp);
     return make_result(
       WIFEXITED(inherit_status) ? (double)WEXITSTATUS(inherit_status) : -1.0, "", "");
   }
@@ -317,6 +453,7 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   int err_pipe[2];
   if (pipe(out_pipe) != 0 || pipe(err_pipe) != 0) {
     free(child_argv);
+    free_envp(envp);
     return make_result(-1, "", "could not create pipes");
   }
 
@@ -329,6 +466,10 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
     close(err_pipe[0]);
     close(err_pipe[1]);
     if (cwd) chdir(cwd);
+    if (envp != NULL) {
+      extern char **environ;
+      environ = envp;
+    }
     execvp(command, child_argv);
     _exit(127);
   }
@@ -371,6 +512,7 @@ xt_value xt_child_process_spawn_sync(int32_t argc, xt_value *argv) {
   free(buffers[0]);
   free(buffers[1]);
   free(child_argv);
+  free_envp(envp);
   return result;
 }
 

package/runtime/rt.h

@@ -334,6 +334,10 @@ xt_value xt_promise_static(xt_value name, int32_t argc, xt_value *argv);
 xt_value xt_await(xt_value value);
 /** Run queued promise reactions; called once the program body finishes. */
 void xt_drain_microtasks(void);
+/** Mark `value` (a promise) as observed, so its rejection is not reported. */
+void xt_promise_observe_value(xt_value value);
+/** Print rejected promises that no handler ever observed; returns how many. */
+int xt_promise_report_unhandled(void);
 
 /* -- host event loop ------------------------------------------------------ */
 /* A small select(2) reactor for host extensions (node's net/dgram/http). The

package/runtime/xt_async.c

@@ -122,6 +122,10 @@ void xt_async_wake(void *asyncPointer, xt_value value, int rejected) {
  * queues a microtask before resuming, so an await always interleaves with
  * pending `.then` callbacks exactly like the specification. */
 xt_value xt_await(xt_value value) {
+  /* The awaiting code observes the outcome, so a rejection here is handled by
+   * definition — it is rethrown inside the coroutine, and the promise of the
+   * enclosing `async` function is what gets reported if nobody catches it. */
+  xt_promise_observe_value(value);
   /* An `await` inside an async generator suspends that generator's coroutine
    * while leaving the current `.next()` promise pending. */
   xt_value generatorResult;

package/runtime/xt_generator.c

@@ -395,6 +395,8 @@ int xt_generator_await(xt_value value, xt_value *result) {
   /* A nested async function inside the generator runs on its own coroutine;
    * its awaits must not suspend the generator. */
   if (!xt_coroutine_is_current(gen->coroutine)) return 0;
+  /* The generator's body observes the outcome, so this rejection is handled. */
+  xt_promise_observe_value(value);
   int state = xt_promise_state_of(value);
   if (state == XT_PROMISE_PENDING) {
     gen->await_threw = 0;

package/runtime/xt_loop.c

@@ -449,11 +449,15 @@ void xt_run_event_loop(void) {
      responsible for calling `xt_loop_poll` while it runs. */
   if (xt_loop_main != NULL) {
     xt_loop_main();
-    return;
-  }
-  while (xt_loop_has_work()) {
-    if (xt_loop_poll(-1) < 0) break;
+  } else {
+    while (xt_loop_has_work()) {
+      if (xt_loop_poll(-1) < 0) break;
+    }
   }
+  /* A rejection that no handler ever observed is fatal, like Node's default
+   * `--unhandled-rejections=throw`. Without this an `async main()` that throws
+   * exits 0 with no output at all, which hides the failure completely. */
+  if (xt_promise_report_unhandled() > 0) exit(1);
 }
 
 int xt_loop_has_work(void) {