dsh-moli 1.1.1 → 1.1.2

package/README.md

@@ -119,7 +119,9 @@ moli_fetch url=https://example.com dump=markdown
 
 `moli_probe` reports whether the engine is present. If it is not, pick one of:
 
-**1. Let the plugin install it** — tries several download routes and reports a SHA256 of what it ran:
+**1. Let the plugin install it** — tries several download routes and reports a SHA256 of what it ran.
+   The whole run is asynchronous (the host keeps serving), and a configured `proxy` is passed to both
+   the download routes and the installer's own engine download:
 
 ```
 moli_probe action=install
@@ -266,7 +268,7 @@ Works on **Windows, Linux and macOS** (x64 / arm64).
 | Platform | Status |
 |---|---|
 | **Windows** | Verified by the maintainer |
-| **Linux** | Verified by the contributor on Ubuntu 24.04 LTS, Node v24.21.0, DSH 0.2.1-alpha.2, dsh-moli 1.1.0, Moli 1.1.17 |
+| **Linux** | Verified by the contributor, not the maintainer: Ubuntu 24.04 LTS, Node v24.21.0, Moli 1.1.17 — including the async install path, proxy injection, and a `strace`-recorded end-to-end fetch |
 | **macOS** | Implemented, not yet verified on a real host |
 
 - **Windows** — the engine is located at the official installer paths (`%LOCALAPPDATA%\Moli\bin\moli.exe`,
@@ -276,6 +278,19 @@ Works on **Windows, Linux and macOS** (x64 / arm64).
   `~/.local/share/moli/bin/moli`, `~/.local/share/moli/moli`, `~/.moli/bin/moli`) and on `$PATH`.
   `moli_probe action=install` runs the official `moli-installer.sh` via `sh`.
 
+**Installing never blocks the DSH host.** Both the installer download and the execution of the
+official installer spawn asynchronously with a timeout that escalates from SIGTERM to SIGKILL, and
+an interrupted turn aborts the child immediately — the host keeps serving while Moli's installer
+does its work. A `strace -e trace=connect` run against a real install recorded every connection
+going through the configured proxy port and none to the upstream host, and a fixture installer
+confirmed the proxy arrives in the child's environment.
+
+The configured `proxy` feeds **both** phases: the plugin's own download routes (`curl --proxy`, and
+`-Proxy` on PowerShell's `Invoke-WebRequest`), and the official installer's internal engine download
+— on Windows through a `DefaultWebProxy` prelude (PowerShell's `Invoke-WebRequest` ignores proxy
+environment variables), on POSIX through the standard `HTTPS_PROXY`/`HTTP_PROXY`/`ALL_PROXY`
+variables the installer's `curl` reads. A proxy carrying credentials sets them explicitly.
+
 On Linux, `moli_probe` discovered `~/.local/bin/moli` unaided, and `moli_fetch` rendered a
 region-gated storefront end to end — through a local forward proxy, with a Netscape `cookieFile` —
 returning a 500+ KB page whose final URL carried the cookie-driven query parameters. That run
@@ -293,7 +308,7 @@ Override any field under the plugin's `config` entry in the profile patch layer.
         exePath: 'C:\Users\me\AppData\Local\Moli\bin\moli.exe'  # default: auto-detect
         defaultTimeoutMs: 30000                                  # per-fetch readiness deadline
         maxChars: 200000                                         # inline text truncation
-        proxy: 'http://127.0.0.1:7890'                           # forward proxy for moli and downloads
+        proxy: 'http://127.0.0.1:7890'                           # forward proxy for moli, downloads, and the installer's engine download
         insecureTls: true                                        # see the TLS notes below
 ```
 
@@ -312,8 +327,10 @@ installation under a versioned subdirectory is still found.
 - **Moli itself is not bundled.** Install it separately or let `moli_probe action=install` fetch it.
 - **Only `fetch` is wrapped.** `moli serve` (CDP/WebDriver server) and `moli import` (session
   import) are not exposed as tools yet.
-- **No per-call cancellation.** The engine runs synchronously, so an interrupted turn cannot abort
-  a fetch mid-flight. A call already in progress finishes and its artifact is written.
+- **No per-call cancellation for fetches.** The engine runs synchronously for a fetch, so an
+  interrupted turn cannot abort it mid-flight; a call already in progress finishes and its artifact
+  is written. `moli_probe action=install` is the exception — it is asynchronous and aborts the child
+  immediately on an interrupted turn.
 - **HTTP error status is only visible for `dump: json`.** That is the only dump format carrying the
   status field. With `markdown` or `html` an error page is returned as content.
 - **`writeTo` calls are serialized.** They report as unsafe to parallelize, so two artifact writes
@@ -336,13 +353,20 @@ installation under a versioned subdirectory is still found.
 
 ## Verification
 
-Two suites live in [`verify/`](verify/), and both are runnable against a working tree:
+Four suites live in [`verify/`](verify/), and all are runnable against a working tree:
 
 - `schema-verify.mjs` checks the tool definitions with the registry's own validator, including
   controls that assert the two invalid schema shapes still fail.
 - `install-verify.mjs` drives the install pipeline against a loopback HTTP server: route ordering,
   the SHA256 of served bytes, refusal to execute on a checksum mismatch, actual execution when the
   digest matches, and the all-routes-failed diagnostic.
+- `linux-verify.mjs` (POSIX hosts) asserts the proxy-helper functions, then against a real install
+  proves the two guarantees of the async rewrite: the installer child actually receives the proxy
+  through its environment (`HTTPS_PROXY` captured by a fixture installer), and the host event loop
+  stays live while a slow installer runs — the acceptance criterion for the async path.
+- `win-verify.mjs` (Windows hosts) runs the same pure assertions, then executes the `DefaultWebProxy`
+  prelude in a real `powershell.exe` and inspects the proxy object and credentials it set, exercises
+  the Windows download routes, and runs `installMoli` end to end.
 
 Beyond those, `lib/moli.js` and the tool layer were exercised end to end against Moli 1.1.16 on
 Windows: registration, probe, Markdown and JSON dumps, `eval` (including a tight-timeout regression

package/README.zh.md

@@ -110,7 +110,8 @@ moli_fetch url=https://example.com dump=markdown
 
 `moli_probe` 会报告引擎是否在场。如果不在，三种方式任选：
 
-**1. 让插件替你装**——多路径下载，并报告实际执行字节的 SHA256：
+**1. 让插件替你装**——多路径下载，并报告实际执行字节的 SHA256。整个过程异步（主机照常服务），配置的
+`proxy` 会同时传给下载路由与安装器内部的引擎下载：
 
 ```
 moli_probe action=install
@@ -247,7 +248,7 @@ Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmo
 | 平台 | 状态 |
 |---|---|
 | **Windows** | 由维护者验证 |
-| **Linux** | 由贡献者在 Ubuntu 24.04 LTS、Node v24.21.0、DSH 0.2.1-alpha.2、dsh-moli 1.1.0、Moli 1.1.17 上验证通过 |
+| **Linux** | **由贡献者验证，非维护者**：Ubuntu 24.04 LTS、Node v24.21.0、Moli 1.1.17——含异步安装路径、代理注入、以及 strace 记录的全链路抓取 |
 | **macOS** | 已实现，尚未在真机验证 |
 
 - **Windows** —— 引擎在官方安装位置查找（`%LOCALAPPDATA%\Moli\bin\moli.exe` 与 `%USERPROFILE%\.local\bin\moli.exe`），
@@ -255,6 +256,16 @@ Moli 仓库自带官方 agent skill：[`moli-webfetch`](https://github.com/lexmo
 - **Linux / macOS** —— 引擎在标准位置（`~/.local/bin/moli`、`~/.local/share/moli/bin/moli`、
   `~/.local/share/moli/moli`、`~/.moli/bin/moli`）与 `$PATH` 中查找；`moli_probe action=install` 通过 `sh` 执行官方 `moli-installer.sh`。
 
+**安装绝不阻塞 DSH 主机。** 安装器的下载与执行都以异步 spawn 进行，超时先 SIGTERM 再 SIGKILL，
+被中断的回合会立刻终止子进程——Moli 安装器干活期间主机照常服务。用 `strace -e trace=connect`
+对真实安装抓包，记录的每次连接都走配置的代理端口、没有任何直连上游主机；fixture 安装器也确认
+代理进入了子进程的环境。
+
+配置的 `proxy` **同时喂两个阶段**：插件自己的下载路由（`curl --proxy`，以及 PowerShell `Invoke-WebRequest`
+的 `-Proxy`），以及官方安装器内部的引擎下载——Windows 上通过 `DefaultWebProxy` prelude（PowerShell
+的 `Invoke-WebRequest` 不读代理环境变量），POSIX 上通过安装器 `curl` 会读取的标准 `HTTPS_PROXY`/
+`HTTP_PROXY`/`ALL_PROXY` 变量。带凭据的代理会显式设置凭据。
+
 在 Linux 上，`moli_probe` 无需干预就找到了 `~/.local/bin/moli`；`moli_fetch` 端到端渲染了一个地区限制的
 电商站——经由本地正向代理、并带上 Netscape 格式的 `cookieFile`——返回 500+ KB 的页面，最终 URL 带上了
 cookie 驱动的查询参数。那次实测同时覆盖了代理下载路由与引擎探测路径。
@@ -271,7 +282,7 @@ cookie 驱动的查询参数。那次实测同时覆盖了代理下载路由与
         exePath: 'C:\Users\me\AppData\Local\Moli\bin\moli.exe'  # 默认自动探测
         defaultTimeoutMs: 30000                                  # 单次抓取就绪超时
         maxChars: 200000                                         # 内联文本截断阈值
-        proxy: 'http://127.0.0.1:7890'                           # 转给本地正向代理
+        proxy: 'http://127.0.0.1:7890'                           # 转给本地正向代理（moli、下载、安装器内部引擎下载都走它）
         insecureTls: true                                        # 见下方 TLS 说明
 ```
 
@@ -287,8 +298,8 @@ cookie 驱动的查询参数。那次实测同时覆盖了代理下载路由与
   [issue](https://github.com/27painter/dsh-moli/issues)**——那是这些路径能被打通的唯一途径。
 - **不包含 Moli 本体。** 需自行安装，或让 `moli_probe action=install` 替你拉取。
 - **只封装了 `fetch`。** `moli serve`（CDP/WebDriver 服务器）与 `moli import`（会话导入）尚未做成工具。
-- **不支持单次取消。** 引擎是同步执行的，被中断的回合无法中途终止抓取；已在进行的调用会跑完并
-  写出产物。
+- **抓取不支持单次取消。** 引擎对抓取是同步执行的，被中断的回合无法中途终止；已在进行的调用会跑完并
+  写出产物。`moli_probe action=install` 是例外——它是异步的，被中断的回合会立刻终止子进程。
 - **HTTP 错误码只在 `dump: json` 下可见。** 那是唯一携带状态字段的格式；用 `markdown` 或 `html`
   时错误页会作为内容返回。
 - **`writeTo` 调用被串行化。** 它们声明为不可并行，因此两次产物写入不会交错。
@@ -306,11 +317,16 @@ cookie 驱动的查询参数。那次实测同时覆盖了代理下载路由与
 
 ## 验证情况
 
-[`verify/`](verify/) 下有两个可直接对工作区运行的测试：
+[`verify/`](verify/) 下有四个可直接对工作区运行的测试：
 
 - `schema-verify.mjs` 用注册表自己的校验器检查工具定义，并带有断言"两种非法 schema 形状仍会被拒"的对照组。
 - `install-verify.mjs` 用本地回环 HTTP 服务器驱动安装链路：路由顺序、被提供字节的 SHA256、校验不匹配时
   拒绝执行、匹配时真正执行、以及全部路径失败的诊断。
+- `linux-verify.mjs`（POSIX 主机）断言代理辅助函数，然后对真实安装验证异步改造的两个保证：安装器子进程
+  确实通过环境收到代理（fixture 安装器捕获 `HTTPS_PROXY`），以及慢安装器运行期间主机事件循环保持活跃——
+  这正是异步路径的验收标准。
+- `win-verify.mjs`（Windows 主机）跑同样的纯函数断言，然后在真实 `powershell.exe` 里执行 `DefaultWebProxy`
+  prelude 并检查它设置的代理对象与凭据，练习 Windows 下载路由，并端到端跑 `installMoli`。
 
 此外，`lib/moli.js` 与工具层在 Windows 上对 Moli 1.1.16 做了端到端验证：注册、probe、Markdown 与 JSON
 dump、`eval`（含针对 `-t` 参数位置的紧超时回归防护）、PNG 与 PDF 产物签名、截断、全部拒绝路径（二元 dump

package/index.js

@@ -300,7 +300,7 @@ export function apply(ctx, config) {
     output: { schema: PROBE_OUTPUT_SCHEMA, render: renderProbe },
     // Installation downloads and executes code, so it must never overlap itself.
     isConcurrencySafe: args => args.action !== 'install',
-    async execute(args) {
+    async execute(args, exec) {
       // An explicit install request is honoured even when an engine already
       // exists, so the action can also repair or upgrade an installation. Anything
       // else only inspects, because installing downloads and runs code.
@@ -309,14 +309,19 @@ export function apply(ctx, config) {
           exePath: options.exePath,
           expectedSha256: args.expectedSha256,
           timeoutMs: options.installTimeoutMs ?? 180000,
+          proxy: options.proxy,
           locate: findMoli,
           candidates: moliCandidates(options.exePath),
+          signal: exec?.signal,
         });
         if (outcome.ok === true) {
           cachedExe = outcome.exe;
           ctx.logger?.info?.(`dsh-moli: installed ${String(outcome.version)} at ${String(outcome.exe)}`);
         }
-        return outcome;
+        // The output schema declares `installed` as required, but installMoli's
+        // outcome carries `ok` instead. Surface both so the registry validator
+        // accepts the result and renderProbe still sees the shape it expects.
+        return { ...outcome, installed: outcome.ok === true };
       }
 
       const exe = engine();

package/lib/install.js

@@ -19,15 +19,28 @@
  * - Installation is never a side effect. It runs only when a tool call asks for
  *   it, because it downloads and executes third-party code.
  *
+ * Every long-running step runs through {@link runAsync}: a child process is
+ * spawned without blocking the event loop, the caller awaits its `close` event,
+ * and a timeout or abort signal kills it. The DSH host keeps serving requests
+ * while an install is in flight — including the official installer's own
+ * engine download, which can hang for a long time when the release host is
+ * unreachable without a proxy.
+ *
+ * Proxy handling is centralized at the head of this module (see the "Unified
+ * forward-proxy behaviour" section) and the platform decides how the official
+ * installer is fed that proxy: POSIX gets proxy environment variables (curl
+ * reads them), Windows gets a DefaultWebProxy prelude (Invoke-WebRequest reads
+ * that instead).
+ *
  * @module dsh-moli/lib/install
  */
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, rmSync, statSync } from 'node:fs';
 import { createConnection } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { findMoli, moliVersion } from './moli.js';
+import { findMoli } from './moli.js';
 
 /** Official installer for the latest release. */
 export const INSTALLER_URL = process.platform === 'win32'
@@ -45,6 +58,137 @@ export const MANUAL_INSTALL = {
 /** PowerShell prelude that makes older hosts negotiate TLS 1.2. */
 const TLS_PRELUDE = '[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;';
 
+/**
+ * Unified forward-proxy behaviour for this pipeline.
+ *
+ * Every proxy decision — parsing/validation, liveness probing, curl argv, the
+ * PowerShell DefaultWebProxy prelude, and the child-process environment for the
+ * official installer — lives here, so the download routes and (later) the
+ * installer execution always agree on one proxy configuration instead of
+ * re-deriving it in each spot.
+ *
+ * The platforms disagree about how a proxy is honoured, and that fact is
+ * encoded here:
+ *
+ * - Linux / macOS — `curl` (used inside moli-installer.sh) reads the standard
+ *   `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` environment variables, so
+ *   injecting them into the installer's child process is enough.
+ * - Windows — `Invoke-WebRequest` (used inside moli-installer.ps1) does NOT
+ *   read those variables; it honours the WinINET system proxy, i.e. .NET's
+ *   `DefaultWebProxy`, so the installer must be preceded by a prelude that
+ *   sets that object.
+ */
+
+/** Resolve a proxy URL into a structured configuration; undefined when unusable. */
+function resolveProxy(input) {
+  if (typeof input !== 'string' || input.length === 0) return undefined;
+  let parsed;
+  try {
+    parsed = new URL(input);
+  } catch {
+    return undefined;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return undefined;
+  const host = parsed.hostname === '' ? undefined : parsed.hostname;
+  // A proxy URL without an explicit port uses the scheme default (http 80,
+  // https 443); a bare `http://proxy` would otherwise parse as port 0 and be
+  // silently discarded while proxyListens probes port 80 for the same string.
+  const port = parsed.port === ''
+    ? (parsed.protocol === 'https:' ? 443 : 80)
+    : Number(parsed.port);
+  if (host === undefined || !Number.isInteger(port) || port <= 0 || port > 65535) return undefined;
+  return {
+    url: input,
+    scheme: parsed.protocol.slice(0, -1),
+    host,
+    port,
+    auth: parsed.username !== '' || parsed.password !== ''
+      ? { user: decodeURIComponent(parsed.username), pass: decodeURIComponent(parsed.password) }
+      : undefined,
+  };
+}
+
+/** Whether a URL targets loopback and must never be handed to a proxy. */
+function isLoopbackUrl(url) {
+  return /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])/iu.test(url);
+}
+
+/** curl argv that routes a download through the proxy. */
+function curlProxyArgs(proxy) {
+  const config = resolveProxy(proxy);
+  return config === undefined ? [] : ['--proxy', config.url];
+}
+
+/** curl argv that keeps a direct route off the proxy (loopback only). */
+function curlBypassArgs(url) {
+  return isLoopbackUrl(url) ? ['--noproxy', '*'] : [];
+}
+
+/**
+ * PowerShell prelude that clears the default web proxy for a loopback download.
+ *
+ * PowerShell 5.1's `Invoke-WebRequest` has no `-NoProxy`, and the system proxy
+ * is read from the registry, so the only portable way to bypass it is to clear
+ * the default proxy object for the process.
+ *
+ * @param loopback - whether the target URL is loopback.
+ * @returns the PowerShell statement, or an empty string when not needed.
+ */
+function powershellProxyBypass(loopback) {
+  return loopback
+    ? '[System.Net.WebRequest]::DefaultWebProxy = New-Object System.Net.WebProxy;'
+    : '';
+}
+
+/**
+ * PowerShell prelude that makes `Invoke-WebRequest` route through a proxy.
+ *
+ * `IWR` ignores `HTTPS_PROXY`/`HTTP_PROXY` environment variables; it honours
+ * the WinINET system proxy, i.e. .NET's `DefaultWebProxy`. Setting that object
+ * before running moli-installer.ps1 is what actually makes the Windows
+ * installer's internal engine download honour the configured proxy. When the
+ * proxy URL carries credentials, they are assigned explicitly as well: the
+ * `WebProxy` constructor does parse userinfo in the address, but an explicit
+ * `NetworkCredential` is the unambiguous form.
+ *
+ * @param proxy - proxy URL.
+ * @returns the PowerShell statement, or an empty string when absent.
+ */
+export function powershellProxyPrelude(proxy) {
+  const config = resolveProxy(proxy);
+  if (config === undefined) return '';
+  const esc = value => value.replace(/'/gu, "''");
+  let prelude = `$__dshMoliProxy = New-Object System.Net.WebProxy('${esc(config.url)}');`;
+  if (config.auth !== undefined) {
+    prelude += `$__dshMoliProxy.Credentials = New-Object System.Net.NetworkCredential('${esc(config.auth.user)}', '${esc(config.auth.pass)}');`;
+  }
+  prelude += `[System.Net.WebRequest]::DefaultWebProxy = $__dshMoliProxy;`;
+  return prelude;
+}
+
+/**
+ * Environment variables that make curl (inside moli-installer.sh) route
+ * through the proxy.
+ *
+ * Both cases are set because the tools disagree about which form they read:
+ * Windows builds of curl recognise the upper-case names, POSIX tools the
+ * lower-case ones.
+ *
+ * @param proxy - proxy URL.
+ * @returns an object to spread into the child's `env`; empty when absent.
+ */
+export function proxyEnv(proxy) {
+  const config = resolveProxy(proxy);  if (config === undefined) return {};
+  return {
+    HTTPS_PROXY: config.url,
+    HTTP_PROXY: config.url,
+    https_proxy: config.url,
+    http_proxy: config.url,
+    ALL_PROXY: config.url,
+    all_proxy: config.url,
+  };
+}
+
 /**
  * Check whether a forward proxy is actually accepting connections.
  *
@@ -59,18 +203,10 @@ const TLS_PRELUDE = '[Net.ServicePointManager]::SecurityProtocol = [Net.Security
  * @returns whether something is listening.
  */
 export function proxyListens(proxy, timeoutMs = 700) {
-  let host = '127.0.0.1';
-  let port = 0;
-  try {
-    const parsed = new URL(proxy);
-    host = parsed.hostname === '' ? host : parsed.hostname;
-    port = Number(parsed.port);
-  } catch {
-    return false;
-  }
-  if (!Number.isInteger(port) || port <= 0) return false;
+  const config = resolveProxy(proxy);
+  if (config === undefined) return Promise.resolve(false);
   return new Promise(resolve => {
-    const socket = createConnection({ host, port });
+    const socket = createConnection({ host: config.host, port: config.port });
     const settle = value => {
       socket.removeAllListeners();
       socket.destroy();
@@ -93,25 +229,230 @@ export function sha256File(path) {
   return createHash('sha256').update(readFileSync(path)).digest('hex');
 }
 
+/**
+ * Normalize stderr text into one readable line.
+ *
+ * Keep the leading meaningful lines and drop control bytes so the message
+ * survives a JSON round trip.
+ *
+ * @param text - raw stderr text.
+ * @returns the condensed message.
+ */
+function condenseStderr(text) {
+  return String(text)
+    .replace(/\u001b\[[0-9;]*m/gu, '')
+    .replace(/\r/gu, '')
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line.length > 0)
+    .slice(0, 6)
+    .join(' | ');
+}
+
+/**
+ * Kill a process and everything it spawned.
+ *
+ * The process that actually does the work — the installer's internal engine
+ * download — is a grandchild: POSIX spawns `sh`, which runs `moli-installer.sh`,
+ * which runs `curl`; Windows spawns `powershell.exe -Command "... & script.ps1"`
+ * and the `Invoke-WebRequest` inside the script does the download. Killing only
+ * the direct child would leak that download: the plugin would report a timeout
+ * or abort while the installer kept pulling the ~100 MB engine in the temp dir.
+ *
+ * - POSIX: spawn with `detached: true` makes the child a process-group leader,
+ *   so a negative pid signal reaches the whole group.
+ * - Windows: there is no process group to signal, so `taskkill /T` walks the
+ *   tree instead.
+ *
+ * @param child - the direct child process.
+ * @param signal - SIGTERM or SIGKILL (POSIX only; Windows always force-kills).
+ */
+function killTree(child, signal) {
+  if (child === undefined || child.pid === undefined) return;
+  if (process.platform === 'win32') {
+    try {
+      spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true, timeout: 10000 });
+    } catch { /* best effort */ }
+    return;
+  }
+  try { process.kill(-child.pid, signal); } catch { /* best effort */ }
+  // Fall back to the direct child in case the group kill did not reach it.
+  try { child.kill(signal); } catch { /* best effort */ }
+}
+
+/**
+ * Run one command asynchronously, never blocking the event loop.
+ *
+ * stdout and stderr go to real files (the plugin's existing sandbox discipline:
+ * a child under DSH's Windows sandbox cannot open inherited pipes, so pipe
+ * capture is unreliable), and the caller awaits the `close` event. A timeout
+ * sends SIGTERM then SIGKILL to the whole process group; an abort signal kills
+ * immediately. The caller's event loop keeps serving while the child runs —
+ * including the official installer's internal engine download, which can hang
+ * without a proxy.
+ *
+ * @param options - command, argv, env, timeout, optional stdout file, abort signal.
+ * @returns the settled outcome; never throws for a non-zero exit.
+ */
+function runAsync(options) {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-moli-run-'));
+  const outPath = options.stdoutFile ?? join(dir, 'stdout.bin');
+  const errPath = join(dir, 'stderr.txt');
+  let outFd;
+  let errFd;
+  let timer;
+  let child;
+  let settled = false;
+
+  const settle = value => {
+    if (settled) return;
+    settled = true;
+    if (timer !== undefined) clearTimeout(timer);
+    if (child !== undefined) child.removeAllListeners();
+    if (outFd !== undefined) closeSync(outFd);
+    if (errFd !== undefined) closeSync(errFd);
+    outFd = undefined;
+    errFd = undefined;
+    const stdout = existsSync(outPath) ? readFileSync(outPath) : Buffer.alloc(0);
+    const stderrText = existsSync(errPath) ? readFileSync(errPath, 'utf8') : '';
+    rmSync(dir, { recursive: true, force: true });
+    resolve({ status: value.status, spawnError: value.spawnError, stdout, stderr: stderrText });
+  };
+
+  // Promise executor cannot be async; the resolve is captured via closure.
+  let resolve;
+  const promise = new Promise(r => { resolve = r; });
+
+  try {
+    outFd = openSync(outPath, 'w');
+    errFd = openSync(errPath, 'w');
+  } catch (error) {
+    rmSync(dir, { recursive: true, force: true });
+    resolve({ status: null, stdout: Buffer.alloc(0), stderr: '', spawnError: `open failed: ${error.message}` });
+    return promise;
+  }
+
+  try {
+    child = spawn(options.command, options.args, {
+      stdio: ['ignore', outFd, errFd],
+      env: options.env ?? process.env,
+      windowsHide: true,
+      // POSIX: the child becomes a process-group leader so killTree can reach
+      // the whole tree (sh → moli-installer.sh → curl) with one negative-pid
+      // signal. Windows must NOT detach: a detached console child's stdio
+      // handles become invalid and powershell.exe exits 0 without running its
+      // command, so killTree force-kills there via taskkill /T /F, which needs
+      // no detach at all.
+      detached: process.platform !== 'win32',
+    });
+  } catch (error) {
+    settle({ status: null, stdout: Buffer.alloc(0), stderr: '', spawnError: `${error.code ?? 'spawn failed'}: ${error.message}` });
+    return promise;
+  }
+
+  child.once('error', error => settle({
+    status: null,
+    stdout: Buffer.alloc(0),
+    stderr: '',
+    spawnError: `${error.code ?? 'spawn failed'}: ${error.message}`,
+  }));
+  child.once('close', code => settle({
+    status: code ?? 0,
+    stdout: Buffer.alloc(0), // populated by settle from the file
+    stderr: '',
+  }));
+
+  const timeoutMs = options.timeoutMs;
+  if (timeoutMs !== undefined) {
+    timer = setTimeout(() => {
+      if (settled || child === undefined) return;
+      killTree(child, 'SIGTERM');
+      // Give the tree a short grace period, then force it.
+      const killer = setTimeout(() => {
+        if (!settled && child !== undefined) {
+          killTree(child, 'SIGKILL');
+        }
+      }, 2000);
+      killer.unref?.();
+    }, timeoutMs);
+  }
+
+  if (options.signal !== undefined && options.signal !== null) {
+    if (options.signal.aborted === true) {
+      killTree(child, 'SIGKILL');
+    } else {
+      options.signal.addEventListener('abort', () => {
+        if (!settled && child !== undefined) {
+          killTree(child, 'SIGKILL');
+        }
+      }, { once: true });
+    }
+  }
+
+  return promise;
+}
+
+/**
+ * Run one command synchronously, blocking until it exits.
+ *
+ * This is the Windows path's runner: Windows is deliberately not
+ * asynchronized (its installer has bounded `Invoke-WebRequest` timeouts and
+ * the platform was not part of the Linux hang investigation), so the whole
+ * install stays synchronous there. stdout and stderr still go to real files —
+ * under DSH's Windows sandbox a child cannot open inherited pipes — and the
+ * caller gets the file contents read back.
+ *
+ * @param options - command, argv, env, timeout, optional stdout file.
+ * @returns the settled outcome; never throws for a non-zero exit.
+ */
+function runSync(options) {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-moli-run-'));
+  const outPath = options.stdoutFile ?? join(dir, 'stdout.bin');
+  const errPath = join(dir, 'stderr.txt');
+  let outFd;
+  let errFd;
+  try {
+    outFd = openSync(outPath, 'w');
+    errFd = openSync(errPath, 'w');
+    const result = spawnSync(options.command, options.args, {
+      stdio: ['ignore', outFd, errFd],
+      env: options.env ?? process.env,
+      timeout: options.timeoutMs,
+      windowsHide: true,
+    });
+    const stdout = existsSync(outPath) ? readFileSync(outPath) : Buffer.alloc(0);
+    const stderrText = existsSync(errPath) ? readFileSync(errPath, 'utf8') : '';
+    const failed = result.error !== undefined && result.error !== null;
+    return {
+      status: failed ? null : (result.status ?? 0),
+      stdout,
+      stderr: condenseStderr(stderrText),
+      spawnError: failed ? `${result.error.code ?? 'spawn failed'}: ${result.error.message}` : undefined,
+    };
+  } finally {
+    if (outFd !== undefined) closeSync(outFd);
+    if (errFd !== undefined) closeSync(errFd);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 /**
  * Run one download attempt, treating a zero-byte file as failure.
  *
  * @param options - argv, environment, and the target path to check afterwards.
  * @returns the attempt outcome.
  */
-function attempt(options) {
-  const result = spawnSync(options.command, options.args, {
-    stdio: ['ignore', 'ignore', 'pipe'],
-    timeout: options.timeoutMs,
-    windowsHide: true,
-    env: options.env ?? process.env,
+async function attempt(options) {
+  const outcome = await runAsync({
+    command: options.command,
+    args: options.args,
+    env: options.env,
+    timeoutMs: options.timeoutMs,
   });
-  const failed = result.error !== undefined && result.error !== null;
-  const exit = failed ? null : (result.status ?? 0);
   const bytes = existsSync(options.target) ? statSync(options.target).size : 0;
+  const failed = outcome.spawnError !== undefined;
+  const exit = failed ? null : outcome.status;
   const ok = !failed && exit === 0 && bytes > 0;
-  // Keep the tail of stderr: a bare exit code cannot be acted on.
-  const stderr = typeof result.stderr === 'string' ? result.stderr.trim().split('\n').slice(-2).join(' ').slice(0, 240) : '';
   return {
     method: options.method,
     ok,
@@ -120,10 +461,44 @@ function attempt(options) {
     error: ok
       ? undefined
       : failed
-        ? `${result.error.code ?? 'spawn failed'}: ${result.error.message}`
+        ? outcome.spawnError
         : exit === 0
           ? 'the download produced an empty file'
-          : `exit ${String(exit)}${stderr === '' ? '' : `: ${stderr}`}`,
+          : `exit ${String(exit)}${outcome.stderr === '' ? '' : `: ${outcome.stderr}`}`,
+  };
+}
+
+/**
+ * Run a stdout-producing download route (the moli self-bootstrap) to the target.
+ *
+ * @param route - the route descriptor with `command` and `args`.
+ * @param target - the file the child's stdout is written to.
+ * @param timeoutMs - download deadline.
+ * @returns the attempt outcome.
+ */
+async function attemptStdout(route, target, timeoutMs) {
+  const outcome = await runAsync({
+    command: route.command,
+    args: route.args,
+    env: { ...process.env, MOLI_DL_TARGET: target },
+    timeoutMs,
+    stdoutFile: target,
+  });
+  const bytes = existsSync(target) ? statSync(target).size : 0;
+  const failed = outcome.spawnError !== undefined;
+  const ok = !failed && outcome.status === 0 && bytes > 0;
+  return {
+    method: route.method,
+    ok,
+    exit: failed ? null : outcome.status,
+    bytes,
+    error: ok
+      ? undefined
+      : failed
+        ? outcome.spawnError
+        : bytes === 0
+          ? 'empty output'
+          : `exit ${String(outcome.status)}`,
   };
 }
 
@@ -136,56 +511,54 @@ function attempt(options) {
 export async function downloadInstaller(options) {
   const target = options.target;
   const url = options.installerUrl ?? INSTALLER_URL;
-  const configured = typeof options.proxy === 'string' && options.proxy.length > 0 ? options.proxy : undefined;
   const timeoutMs = options.timeoutMs ?? 60000;
   const powershell = options.powershell ?? (process.platform === 'win32' ? 'powershell.exe' : 'powershell');
+  const onWindows = process.platform === 'win32';
+
+  // Head: one proxy decision, then every route below agrees on it.
+  const proxyConfig = resolveProxy(options.proxy);
+  const proxyAlive = proxyConfig === undefined ? false : await proxyListens(proxyConfig.url);
+  const proxy = proxyConfig === undefined ? undefined : proxyConfig.url;
 
   // Never hand a loopback URL to a proxy — with a stale system proxy setting the
   // request would go to a dead port and wait out the connect timeout. Windows
   // PowerShell 5.1 has no `-NoProxy` on Invoke-WebRequest, and the system proxy is
   // read from the registry, so the only portable way to bypass it is to clear the
   // default proxy object for the process.
-  const loopback = /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])/iu.test(url);
-  const bypass = loopback ? ' [System.Net.WebRequest]::DefaultWebProxy = New-Object System.Net.WebProxy;' : '';
-  const curlBypass = loopback ? ['--noproxy', '*'] : [];
+  const bypass = powershellProxyBypass(isLoopbackUrl(url));
 
   const iwr = extra => [
     '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command',
     `${TLS_PRELUDE}${bypass} Invoke-WebRequest -UseBasicParsing ${extra} -Uri '${url}' -OutFile $env:MOLI_DL_TARGET -TimeoutSec ${String(Math.ceil(timeoutMs / 1000))}`,
   ];
 
-  const routes = process.platform === 'win32'
-    ? [
-      {
-        method: 'Invoke-WebRequest (direct)',
-        command: powershell,
-        args: iwr(''),
-      },
-    ]
-    : [];
-
-  // Only attempt proxy routes when something is actually listening there.
-  let proxyAlive = false;
-  if (configured !== undefined) {
-    proxyAlive = await proxyListens(configured);
-  }
-  if (process.platform === 'win32' && configured !== undefined && proxyAlive) {
+  // Route order is platform-aware, in order of least surprise.
+  const routes = [];
+  if (onWindows) {
     routes.push({
-      method: `Invoke-WebRequest (proxy ${configured})`,
+      method: 'Invoke-WebRequest (direct)',
       command: powershell,
-      args: iwr(`-Proxy '${configured}'`),
+      args: iwr(''),
     });
+    // Only attempt proxy routes when something is actually listening there.
+    if (proxy !== undefined && proxyAlive) {
+      routes.push({
+        method: `Invoke-WebRequest (proxy ${proxy})`,
+        command: powershell,
+        args: iwr(`-Proxy '${proxy}'`),
+      });
+    }
   }
   routes.push({
     method: 'curl (direct)',
-    command: process.platform === 'win32' ? 'curl.exe' : 'curl',
-    args: ['-sSL', ...curlBypass, '--max-time', String(Math.ceil(timeoutMs / 1000)), '-o', target, url],
+    command: onWindows ? 'curl.exe' : 'curl',
+    args: ['-sSL', ...curlBypassArgs(url), '--max-time', String(Math.ceil(timeoutMs / 1000)), '-o', target, url],
   });
-  if (configured !== undefined && proxyAlive) {
+  if (proxy !== undefined && proxyAlive) {
     routes.push({
-      method: `curl (proxy ${configured})`,
-      command: process.platform === 'win32' ? 'curl.exe' : 'curl',
-      args: ['-sSL', ...curlBypass, '--max-time', String(Math.ceil(timeoutMs / 1000)), '--proxy', configured, '-o', target, url],
+      method: `curl (proxy ${proxy})`,
+      command: onWindows ? 'curl.exe' : 'curl',
+      args: ['-sSL', ...curlBypassArgs(url), '--max-time', String(Math.ceil(timeoutMs / 1000)), ...curlProxyArgs(proxy), '-o', target, url],
     });
   }
   // Moli can bootstrap itself: when it is present but broken, or when reinstalling,
@@ -195,40 +568,28 @@ export async function downloadInstaller(options) {
     routes.push({
       method: 'moli fetch (self-bootstrap)',
       command: exe,
-      args: ['fetch', url, '--insecure-disable-tls-host-verification', ...(configured === undefined || !proxyAlive ? [] : ['--http-proxy', configured])],
-      stdoutToFile: target,
+      args: ['fetch', url, '--insecure-disable-tls-host-verification', ...(proxy === undefined || !proxyAlive ? [] : ['--http-proxy', proxy])],
+      stdoutToFile: true,
     });
   }
 
   const log = [];
   for (const route of routes) {
     if (existsSync(target)) rmSync(target, { force: true });
-    let outcome;
-    if (route.stdoutToFile === undefined) {
-      outcome = attempt({
-        method: route.method,
-        command: route.command,
-        args: route.args,
-        target,
-        timeoutMs,
-        env: { ...process.env, MOLI_DL_TARGET: target },
-      });
-    } else {
-      // This route writes to stdout, so it needs the file descriptor treatment
-      // rather than an --out argument.
-      const fd = openSync(target, 'w');
-      const result = spawnSync(route.command, route.args, { stdio: ['ignore', fd, 'ignore'], timeout: timeoutMs, windowsHide: true });
-      closeSync(fd);
-      const bytes = existsSync(target) ? statSync(target).size : 0;
-      const failed = result.error !== undefined && result.error !== null;
-      outcome = {
-        method: route.method,
-        ok: !failed && (result.status ?? 0) === 0 && bytes > 0,
-        exit: failed ? null : (result.status ?? 0),
-        bytes,
-        error: failed ? `${result.error.code ?? 'spawn failed'}` : bytes === 0 ? 'empty output' : undefined,
-      };
-    }
+    // Every route runs asynchronously on every platform: the child process is
+    // spawned without blocking the DSH host's event loop, and the per-route
+    // timeout keeps a hung download from stalling the host. Windows and POSIX
+    // behave identically here.
+    const outcome = route.stdoutToFile === undefined
+      ? await attempt({
+          method: route.method,
+          command: route.command,
+          args: route.args,
+          target,
+          timeoutMs,
+          env: { ...process.env, MOLI_DL_TARGET: target },
+        })
+      : await attemptStdout(route, target, timeoutMs);
     log.push({ method: outcome.method, ok: outcome.ok, bytes: outcome.bytes, error: outcome.error });
     if (outcome.ok) {
       return { ok: true, path: target, bytes: outcome.bytes, sha256: sha256File(target), method: outcome.method, attempts: log };
@@ -237,10 +598,43 @@ export async function downloadInstaller(options) {
   return { ok: false, attempts: log, error: `every download route failed (${String(log.length)} tried)` };
 }
 
+/**
+ * Read the engine's version banner asynchronously.
+ *
+ * @param exe - absolute path to the moli binary.
+ * @param options - timeout and abort signal.
+ * @returns the version string, or undefined when the call failed.
+ */
+async function moliVersionAsync(exe, options = {}) {
+  const outcome = await runAsync({
+    command: exe,
+    args: ['--version'],
+    timeoutMs: options.timeoutMs ?? 15000,
+    signal: options.signal,
+  });
+  if (outcome.status !== 0 || outcome.spawnError !== undefined) return undefined;
+  const text = outcome.stdout.toString('utf8').trim();
+  return text === '' ? undefined : text;
+}
+
+/**
+ * Synchronous twin of {@link moliVersionAsync}, used on Windows.
+ *
+ * @param exe - absolute path to the moli binary.
+ * @param timeoutMs - version-call deadline.
+ * @returns the version string, or undefined when the call failed.
+ */
+function moliVersionSync(exe, timeoutMs = 15000) {
+  const outcome = runSync({ command: exe, args: ['--version'], timeoutMs });
+  if (outcome.status !== 0 || outcome.spawnError !== undefined) return undefined;
+  const text = outcome.stdout.toString('utf8').trim();
+  return text === '' ? undefined : text;
+}
+
 /**
  * Install Moli and confirm it answers.
  *
- * @param options - expected checksum, timeouts, proxy, and injection points for tests.
+ * @param options - expected checksum, timeouts, proxy, abort signal, and injection points for tests.
  * @returns the settled outcome value.
  */
 export async function installMoli(options = {}) {
@@ -248,10 +642,15 @@ export async function installMoli(options = {}) {
   const workDir = mkdtempSync(join(tmpdir(), 'dsh-moli-install-'));
   const target = join(workDir, process.platform === 'win32' ? 'moli-installer.ps1' : 'moli-installer.sh');
   try {
+    // Head: one proxy decision, shared by the download below and the run after it.
+    const proxyConfig = resolveProxy(options.proxy);
+    const proxyAlive = proxyConfig === undefined ? false : await proxyListens(proxyConfig.url);
+    const proxy = proxyConfig === undefined ? undefined : proxyConfig.url;
+
     const download = await downloadInstaller({
       target,
       installerUrl: options.installerUrl,
-      proxy: options.proxy,
+      proxy,
       timeoutMs: options.downloadTimeoutMs ?? 60000,
       locate: options.locate ?? findMoli,
       exePath: options.exePath,
@@ -283,23 +682,61 @@ export async function installMoli(options = {}) {
       }
     }
 
-    const run = process.platform === 'win32'
-      ? spawnSync(options.powershell ?? 'powershell.exe',
-          ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', target],
-          { stdio: ['ignore', 'ignore', 'ignore'], timeout: timeoutMs, windowsHide: true })
-      : spawnSync('sh', [target], { stdio: ['ignore', 'ignore', 'ignore'], timeout: timeoutMs });
-    const runFailed = run.error !== undefined && run.error !== null;
-    const runStatus = runFailed ? null : (run.status ?? 0);
+    // Run the official installer, routing its internal engine download through
+    // the proxy the way each platform honours it:
+    // - POSIX (Linux/macOS): moli-installer.sh uses curl, which reads the proxy
+    //   environment variables, so injecting them is enough.
+    // - Windows: moli-installer.ps1 uses Invoke-WebRequest, which ignores env
+    //   variables and honours .NET's DefaultWebProxy, so the script must be
+    //   preceded by a prelude that sets that object.
+    const env = { ...process.env, ...(proxyAlive ? proxyEnv(proxy) : {}) };
+    let args;
+    if (process.platform === 'win32') {
+      const prelude = `${TLS_PRELUDE}${proxyAlive ? powershellProxyPrelude(proxy) : ''}`;
+      const script = `& '${target.replace(/'/gu, "''")}'`;
+      args = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', `${prelude} ${script}`];
+    } else {
+      args = [target];
+    }
+    let run;
+    if (process.platform === 'win32') {
+      // Windows runs asynchronously too: spawn the installer without blocking
+      // the DSH host's event loop. The outer timeout sends SIGTERM then
+      // SIGKILL, and an abort signal kills it immediately, so the host keeps
+      // serving requests while PowerShell's Invoke-WebRequest does its work.
+      run = await runAsync({
+        command: options.powershell ?? 'powershell.exe',
+        args,
+        env,
+        timeoutMs,
+        signal: options.signal,
+      });
+    } else {
+      // Linux/macOS keeps its existing asynchronous behaviour.
+      run = await runAsync({
+        command: 'sh',
+        args,
+        env,
+        timeoutMs,
+        signal: options.signal,
+      });
+    }
+    const runFailed = run.spawnError !== undefined;
+    const runStatus = runFailed ? null : run.status;
 
     const locate = options.locate ?? findMoli;
     const exe = locate(options.exePath);
-    const version = exe === undefined ? undefined : moliVersion(exe);
+    const version = exe === undefined
+      ? undefined
+      : process.platform === 'win32'
+        ? moliVersionSync(exe)
+        : await moliVersionAsync(exe, { signal: options.signal });
 
     if (version === undefined) {
       return {
         ok: false,
         error: runFailed
-          ? `running the installer failed: ${run.error.message}`
+          ? `running the installer failed: ${run.spawnError}`
           : `the installer ${runStatus === 0 ? 'reported success' : `exited ${String(runStatus)}`}, but no working moli binary was found afterwards`,
         installerSha256: download.sha256,
         installerBytes: download.bytes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-moli",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "type": "module",
   "description": "DeepSeek Harness tools for the local Moli headless browser: rendered fetches, markdown, semantic trees, screenshots, and PDFs.",
   "license": "MIT",