u1s1-cli-cn 1.18.0 → 1.20.0

package/dist/agents/models-list.js

@@ -0,0 +1,297 @@
+/**
+ * `u1s1 agents models [--json] [--offline]`:给外部前端(Hearth 等)列出每个客户端能用的模型,
+ * 带显示名;`id` 就是该客户端 `--model` / `-m` 要的值。
+ *
+ * 契约(docs/custom-endpoints-all-clients-plan-2026-11-13.md §3):
+ *   { loggedIn, clients: { pi?: ClientModels, claude?: ClientModels, codex?: ClientModels } }
+ *   - 未登录:{ loggedIn: false, clients: {} },退出码 0;绝不发起设备登录、不开浏览器、不联网。
+ *   - 输出只含 id / name / source / endpoint / default / enabled,不带任何密钥、地址、token。
+ *   - claude / codex 没有本站的 agent-config 缓存时不出现在 clients 里(调用方按「不知道」处理)。
+ *
+ * 数据来源(都按当前站点隔离):
+ *   pi     官方模型:/v1/models(短超时)→ <agentDir>/models.json 里上次写的 u1s1 provider → 内置兜底列表;
+ *          自定义端点:/v1/endpoints(短超时,成功时刷新 endpoints.json,与启动 Pi 同一做法)→ endpoints.json。
+ *   claude / codex:只读 ~/.u1s1/agents/<agent>/agent-config.json(拉新配置要起签名代理、拿客户端证明,
+ *          不适合做成秒回的列表命令;启动对应客户端时会刷新缓存)。
+ * --offline:只读缓存,不联网、不写任何文件。
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { agentDir, apiEndpointToCustom, apiModelToDef, ENDPOINT_ID_RE, loadConfig, MODELS, PROVIDER_ID, readRawConfigFile, resolvePreferredModel, saveEndpointsCache, setCustomEndpoints, setModelsFromApi, u1s1Dir, VERSION, } from "../config.js";
+import { authorizedFetch, hasDeviceCredential } from "../device-auth.js";
+import { tr } from "../i18n.js";
+import { parseAgentConfig, readConfigCache } from "./agent-config.js";
+import { customModelId, routableEndpoint } from "./custom-models.js";
+import { chooseAgentModel, readAgentPrefs } from "./prefs.js";
+const GATEWAY_AGENT = {
+    claude: "claude-code",
+    codex: "codex",
+};
+// ---------------------------------------------------------------- pure builders
+/** Pi 的 --model 写法:provider/model(和 `u1s1 pi --list-models` 两列拼起来一致)。 */
+export function piModelId(provider, modelId) {
+    return `${provider}/${modelId}`;
+}
+/**
+ * 自定义端点的模型 → 列表条目。idFor 决定该客户端认的 id:Pi 是 provider/model;
+ * Claude Code / Codex 接上本地路由后(A2)按各自的写法传进来。
+ */
+export function customModelEntries(endpoints, idFor) {
+    const out = [];
+    for (const ep of endpoints) {
+        for (const m of ep.models) {
+            out.push({ id: idFor(ep, m), name: m.name || m.id, source: "custom", endpoint: ep.name });
+        }
+    }
+    return out;
+}
+export function piClientModels(official, endpoints, preferred) {
+    return {
+        default: piModelId(preferred.provider, preferred.id),
+        models: [
+            ...official.map((m) => ({ id: piModelId(PROVIDER_ID, m.id), name: m.name || m.id, source: "u1s1" })),
+            ...customModelEntries(endpoints, (ep, m) => piModelId(ep.id, m.id)),
+        ],
+    };
+}
+/**
+ * Claude Code / Codex:网关阵容(agent-config 缓存)+ 自定义端点的模型(只收本地路由转得了的
+ * openai-completions 端点,id = ep…/<模型>,见 custom-models.ts)。default 是启动时真正会用的模型:
+ * 用户在 u1s1 config 里选的(网关模型或自定义模型)还在就是它,否则网关默认——与 launch.ts 同一判断。
+ */
+export function gatewayClientModels(config, preferredModel, endpoints = []) {
+    const custom = customModelEntries(endpoints.filter(routableEndpoint), (ep, m) => customModelId(ep.id, m.id));
+    const lineup = { ...config, models: [...config.models, ...custom.map((m) => ({ id: m.id, name: m.name }))] };
+    return {
+        default: chooseAgentModel(lineup, preferredModel).model,
+        enabled: config.enabled,
+        models: [
+            ...config.models.map((m) => ({ id: m.id, name: m.name || m.id, source: "u1s1" })),
+            ...custom,
+        ],
+    };
+}
+// ---------------------------------------------------------------- caches (read-only)
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** 与 config.ts 的端点缓存同一个文件(这里只读) */
+function endpointsCacheFile() {
+    return join(u1s1Dir, "endpoints.json");
+}
+/** Pi 启动时把 u1s1 provider 的 baseUrl 写成本机签名代理(127.0.0.1 的随机端口)或站点地址。 */
+function sameSiteProviderBaseUrl(value, baseUrl) {
+    if (typeof value !== "string")
+        return false;
+    if (value === baseUrl)
+        return true;
+    try {
+        const host = new URL(value).hostname;
+        return host === "127.0.0.1" || host === "localhost" || host === "[::1]";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 上次启动 Pi 时写进 <agentDir>/models.json 的 u1s1 provider。那里的 baseUrl 通常是本机签名代理,
+ * 认不出站点;只排除明确指向别的站点的条目(换站后第一次启动 Pi 之前,离线时可能列出上一站的名字)。
+ * 那里的 name 拼了「 · 提示」(见 toProviderModels),这里去掉,只留显示名。
+ */
+export function officialModelsFromProviderFile(path, baseUrl) {
+    const root = readJson(path);
+    const providers = isRecord(root) ? root["providers"] : undefined;
+    const entry = isRecord(providers) ? providers[PROVIDER_ID] : undefined;
+    if (!isRecord(entry) || !sameSiteProviderBaseUrl(entry["baseUrl"], baseUrl) || !Array.isArray(entry["models"]))
+        return undefined;
+    const models = [];
+    for (const m of entry["models"]) {
+        if (!isRecord(m) || typeof m["id"] !== "string" || !m["id"])
+            continue;
+        const raw = typeof m["name"] === "string" ? m["name"] : "";
+        const sep = raw.indexOf(" · ");
+        const name = (sep > 0 ? raw.slice(0, sep) : raw).trim() || m["id"];
+        models.push({
+            id: m["id"],
+            name,
+            aliases: [],
+            reasoning: m["reasoning"] === true,
+            vision: false,
+            contextWindow: 0,
+            maxTokens: 0,
+            cost: null,
+            note: "",
+        });
+    }
+    return models.length ? models : undefined;
+}
+/** endpoints.json 只取列表要用的字段,形状不对的条目跳过。 */
+export function endpointsFromCache(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const e of raw) {
+        if (!isRecord(e) || typeof e["id"] !== "string" || !ENDPOINT_ID_RE.test(e["id"]) || !Array.isArray(e["models"]))
+            continue;
+        const models = [];
+        for (const m of e["models"]) {
+            if (!isRecord(m) || typeof m["id"] !== "string" || !m["id"])
+                continue;
+            models.push({
+                id: m["id"],
+                name: typeof m["name"] === "string" && m["name"] ? m["name"] : m["id"],
+                aliases: [],
+                reasoning: m["reasoning"] === true,
+                vision: m["vision"] === true,
+                contextWindow: 0,
+                maxTokens: 0,
+                cost: null,
+                note: "",
+            });
+        }
+        // api 不是密钥,留着让 Claude Code / Codex 的列表只收本地路由转得了的端点;baseUrl / apiKey 不读
+        const api = typeof e["api"] === "string" ? e["api"] : "";
+        out.push({ id: e["id"], name: typeof e["name"] === "string" ? e["name"] : e["id"], baseUrl: "", api, models });
+    }
+    return out;
+}
+export function cachedAgentConfig(cacheFile, site, agent) {
+    const cached = readConfigCache(cacheFile, site);
+    return cached ? parseAgentConfig(cached.body, agent) : undefined;
+}
+export const LIVE_REFRESH_TIMEOUT_MS = 2_500;
+/**
+ * 并行拉 /v1/models 与 /v1/endpoints,整体不超过 timeoutMs;到点一起中止,
+ * 任何失败(断网、401、5xx、格式不对)都只是让对应字段缺席,调用方退回缓存。
+ */
+export async function fetchLiveCatalog(get, timeoutMs = LIVE_REFRESH_TIMEOUT_MS) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    const json = async (path) => {
+        try {
+            const res = await get(path, ctrl.signal);
+            if (!res.ok)
+                return undefined;
+            const text = await res.text();
+            if (text.length > 2 * 1024 * 1024)
+                return undefined;
+            const body = JSON.parse(text);
+            return isRecord(body) ? body : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    try {
+        const [models, endpoints] = await Promise.all([json("/models"), json("/endpoints")]);
+        return {
+            ...(Array.isArray(models?.["data"]) && models["data"].length ? { models: models["data"] } : {}),
+            ...(Array.isArray(endpoints?.["endpoints"]) ? { endpoints: endpoints["endpoints"] } : {}),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        ctrl.abort();
+    }
+}
+export async function buildModelsListing(deps = {}) {
+    const cfg = loadConfig();
+    // 未登录:到此为止。不联网、不触发设备登录
+    if (!hasDeviceCredential(cfg))
+        return { loggedIn: false, clients: {} };
+    let live = {};
+    if (!deps.offline) {
+        const fetchLive = deps.fetchLive ?? (() => fetchLiveCatalog((path, signal) => authorizedFetch(cfg, `${cfg.baseUrl}${path}`, { headers: { "x-u1s1-version": VERSION }, signal })));
+        live = await fetchLive().catch(() => ({}));
+    }
+    // 官方模型
+    if (live.models) {
+        setModelsFromApi(live.models.map(apiModelToDef));
+    }
+    else {
+        const cached = officialModelsFromProviderFile(join(agentDir, "models.json"), cfg.baseUrl);
+        if (cached)
+            setModelsFromApi(cached);
+    }
+    // 自定义端点(成功拉到时刷新缓存,与启动 Pi 的 loadCustomEndpoints 同一做法;--offline 不写)
+    let endpoints;
+    if (live.endpoints) {
+        try {
+            endpoints = live.endpoints.map(apiEndpointToCustom);
+            if (!deps.offline) {
+                try {
+                    saveEndpointsCache(endpoints);
+                }
+                catch { /* 缓存写不进去不影响列表 */ }
+            }
+        }
+        catch {
+            endpoints = endpointsFromCache(readJson(endpointsCacheFile()));
+        }
+    }
+    else {
+        endpoints = endpointsFromCache(readJson(endpointsCacheFile()));
+    }
+    setCustomEndpoints(endpoints);
+    const clients = {
+        pi: piClientModels(MODELS, endpoints, resolvePreferredModel(cfg)),
+    };
+    const site = new URL(cfg.baseUrl).origin;
+    const raw = readRawConfigFile();
+    for (const client of ["claude", "codex"]) {
+        const config = cachedAgentConfig(join(u1s1Dir, "agents", client, "agent-config.json"), site, GATEWAY_AGENT[client]);
+        if (config)
+            clients[client] = gatewayClientModels(config, readAgentPrefs(client, raw).model, endpoints);
+    }
+    return { loggedIn: true, clients };
+}
+/** 人看的表。 */
+export function formatModelsTable(listing) {
+    if (!listing.loggedIn)
+        return [tr("还没有登录,先运行 u1s1 login。", "Not signed in yet. Run u1s1 login first.")];
+    const lines = [];
+    for (const client of ["pi", "claude", "codex"]) {
+        const c = listing.clients[client];
+        lines.push("");
+        if (!c) {
+            lines.push(`${client}  ${tr("(还没有模型列表,启动一次 u1s1 " + client + " 后可见)", "(no model list yet; start u1s1 " + client + " once to load it)")}`);
+            continue;
+        }
+        lines.push(c.enabled === false ? `${client}  ${tr("(暂未开放)", "(not available)")}` : client);
+        const width = Math.max(0, ...c.models.map((m) => m.id.length));
+        for (const m of c.models) {
+            const mark = m.id === c.default ? "●" : " ";
+            const tag = m.source === "custom" ? `  [${m.endpoint ?? tr("自定义", "custom")}]` : "";
+            lines.push(`  ${mark} ${m.id.padEnd(width)}  ${m.name}${tag}`);
+        }
+        if (c.models.length === 0)
+            lines.push(`    ${tr("(没有可用模型)", "(no models)")}`);
+    }
+    lines.push("");
+    lines.push(tr("● = 默认模型。启动时用 --model 传左列的 id。", "● = default model. Pass the left-hand id with --model."));
+    return lines;
+}
+export async function modelsCommand(args, deps = {}) {
+    const json = args.includes("--json");
+    const offline = deps.offline ?? args.includes("--offline");
+    const unknown = args.filter((a) => a !== "--json" && a !== "--offline");
+    if (unknown.length) {
+        console.error(tr("用法: u1s1 agents models [--json] [--offline]", "Usage: u1s1 agents models [--json] [--offline]"));
+        return 1;
+    }
+    const listing = await buildModelsListing({ ...deps, offline });
+    if (json)
+        process.stdout.write(JSON.stringify(listing) + "\n");
+    else
+        for (const line of formatModelsTable(listing))
+            console.log(line);
+    return 0;
+}

package/dist/agents/node-runtime.d.ts

@@ -0,0 +1,91 @@
+import type { SiteId } from "../site.js";
+export declare const DSH_MIN_NODE = "24.9.0";
+/** 钉死的 Node 24 LTS(2026-11-10 发布的安全更新)。 */
+export declare const NODE24_VERSION = "24.22.3";
+/** node-v24.22.3 官方 SHASUMS256.txt(https://nodejs.org/dist/v24.22.3/SHASUMS256.txt)里对应的条目。 */
+export declare const NODE24_SHA256: Readonly<Record<string, string>>;
+export declare const NODE_BIN_ENV = "U1S1_DSH_NODE";
+export interface NodeArchive {
+    /** nodejs.org 的平台名(darwin-arm64、win-x64…) */
+    target: string;
+    /** 压缩包文件名 */
+    file: string;
+    /** 解压后的顶层目录 */
+    dir: string;
+    /** node 可执行文件在顶层目录下的位置(posix 写法) */
+    binInDir: string;
+    format: "tar.gz" | "zip";
+    sha256: string;
+}
+export declare function nodeArchive(platform?: NodeJS.Platform, arch?: string, version?: string): NodeArchive | undefined;
+/** 国际站走官方 nodejs.org;中国站走 npmmirror 的 Node 镜像(同一份文件,按官方 SHA-256 校验)。U1S1_NODE_MIRROR 可覆盖。 */
+export declare function nodeDistBase(site: SiteId, env?: NodeJS.ProcessEnv): string;
+export declare function nodeDownloadUrl(site: SiteId, archive: NodeArchive, version?: string, env?: NodeJS.ProcessEnv): string;
+/** ~/.u1s1/agents/node/<版本>/ 下的 node(解压后只留可执行文件和 LICENSE)。 */
+export declare function managedNodeBin(agentsRoot: string, version?: string, platform?: NodeJS.Platform): string;
+/** `<node> --version` → 版本号;跑不起来返回 undefined。 */
+export declare function probeNodeVersion(bin: string): string | undefined;
+export declare function nodeVersionOk(version: string | undefined, min?: string): boolean;
+export type NodeSource = "env" | "self" | "path" | "managed" | "download";
+export interface FoundNode {
+    bin: string;
+    version: string;
+    source: NodeSource;
+}
+export declare class NodeRuntimeError extends Error {
+    readonly code: "env_unusable" | "declined" | "unsupported_platform" | "download_failed" | "verify_failed";
+    constructor(code: "env_unusable" | "declined" | "unsupported_platform" | "download_failed" | "verify_failed", message: string);
+}
+export interface FindNodeDeps {
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    selfVersion?: string;
+    platform?: NodeJS.Platform;
+    probe?: (bin: string) => string | undefined;
+    exists?: (p: string) => boolean;
+}
+/** 不下载:按 1-4 的顺序找够新的 node。U1S1_DSH_NODE 指定了但不能用时抛 env_unusable。 */
+export declare function findNode(agentsRoot: string, deps?: FindNodeDeps): FoundNode | undefined;
+export interface NodeDownloadInfo {
+    version: string;
+    url: string;
+    host: string;
+    downloadBytes?: number;
+}
+export interface EnsureNodeOptions {
+    agentsRoot: string;
+    site: SiteId;
+    /** 下载前征得同意;返回 false = 拒绝 */
+    consent: (info: NodeDownloadInfo) => Promise<boolean>;
+    log: (line: string) => void;
+    text: {
+        declined: () => string;
+        unsupported: () => string;
+        downloadFailed: (detail: string) => string;
+        verifyFailed: (detail: string) => string;
+        downloading: (version: string) => string;
+        installed: (version: string) => string;
+    };
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    /** 测试注入 */
+    find?: () => FoundNode | undefined;
+}
+/** 找到够新的 node;没有就征得同意后下载钉死的 Node 24 LTS。 */
+export declare function ensureNode(opts: EnsureNodeOptions): Promise<FoundNode>;
+/** 各平台压缩包约 30-55 MB;提示用。 */
+export declare const NODE24_APPROX_BYTES: number;
+/**
+ * 下载 → 按钉死的 SHA-256 校验 → 只解出 node 和 LICENSE → 确认能跑且版本对 → 改名成正式目录。
+ * 中途失败只留暂存目录的残渣(下次启动前清掉),不影响已有的东西。
+ */
+export declare function downloadNode(input: {
+    agentsRoot: string;
+    archive: NodeArchive;
+    url: string;
+    fetchImpl: typeof fetch;
+    text: EnsureNodeOptions["text"];
+    version?: string;
+}): Promise<string>;
+/** 暂存目录残渣(下载中途被打断)。 */
+export declare function cleanNodeStaging(agentsRoot: string): void;

package/dist/agents/node-runtime.js

@@ -0,0 +1,223 @@
+/**
+ * dsh(DeepSeek Harness)要的 Node(engines.node >=24.9.0)。便携包只带 Node 22,所以:
+ *
+ *   1. U1S1_DSH_NODE 指定的 node(排查/测试用;版本不够直接报错,不悄悄换别的)
+ *   2. 运行本 CLI 的 Node 就够新(用户自己 npm 装的 u1s1 跑在 Node 24+ 上)
+ *   3. PATH 里的 node 够新
+ *   4. 已下载到 ~/.u1s1/agents/node/<版本>/ 的官方 Node 24 LTS
+ *   5. 都没有:征得同意后从 nodejs.org(中国站走 npmmirror 的 Node 镜像)下载钉死的
+ *      Node 24 LTS 压缩包,按代码里的 SHA-256(抄自该版本官方 SHASUMS256.txt)校验后解出
+ *      node 可执行文件和 LICENSE。
+ *
+ * 只给 dsh 用:不改 PATH、不碰便携包自带的 Node,也不装 npm(npm 仍用 CLI 自带的那份,
+ * 只是改由这个 Node 运行,见 runtime.ts installRuntime)。
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { stripSecretEnv } from "../secret-env.js";
+import { compareVersions, findOnPath, normalizeVersion, versionFromOutput } from "./runtime.js";
+export const DSH_MIN_NODE = "24.9.0";
+/** 钉死的 Node 24 LTS(2026-11-10 发布的安全更新)。 */
+export const NODE24_VERSION = "24.22.3";
+/** node-v24.22.3 官方 SHASUMS256.txt(https://nodejs.org/dist/v24.22.3/SHASUMS256.txt)里对应的条目。 */
+export const NODE24_SHA256 = {
+    "darwin-arm64": "ff6e17d4874b76d272212b908cc020d6e815fba5a6c7eaaa06add725840307fd",
+    "darwin-x64": "977614af0504c81045e7fd85596dbca0e5f951b96681516dadafedcca8c447f7",
+    "linux-arm64": "261af2af250dfd7e9f25cf151d1b2713a0adf8f10a9ad116c4947f68627affe8",
+    "linux-x64": "061ec3e3062115705b56b51fa9cc330ab50d34b6969387d4e4b1a50c6809acc2",
+    "win-arm64": "b3cc74a295b39d4f273271e96f58c06dd2b35757ca12abec64c7d0598b434f14",
+    "win-x64": "e612af99f626ab415ea225af6bce5c971feb448cb5cae250bb1c3fa50c5f7d9f",
+};
+export const NODE_BIN_ENV = "U1S1_DSH_NODE";
+export function nodeArchive(platform = process.platform, arch = process.arch, version = NODE24_VERSION) {
+    const os = platform === "win32" ? "win" : platform === "darwin" ? "darwin" : platform === "linux" ? "linux" : undefined;
+    if (!os || (arch !== "x64" && arch !== "arm64"))
+        return undefined;
+    const target = `${os}-${arch}`;
+    const sha256 = version === NODE24_VERSION ? NODE24_SHA256[target] : undefined;
+    if (!sha256)
+        return undefined;
+    const dir = `node-v${version}-${target}`;
+    const format = os === "win" ? "zip" : "tar.gz";
+    return { target, file: `${dir}.${format}`, dir, binInDir: os === "win" ? "node.exe" : "bin/node", format, sha256 };
+}
+/** 国际站走官方 nodejs.org;中国站走 npmmirror 的 Node 镜像(同一份文件,按官方 SHA-256 校验)。U1S1_NODE_MIRROR 可覆盖。 */
+export function nodeDistBase(site, env = process.env) {
+    const override = env["U1S1_NODE_MIRROR"]?.trim();
+    if (override && /^https?:\/\//.test(override))
+        return override.replace(/\/+$/, "");
+    return site === "cn" ? "https://cdn.npmmirror.com/binaries/node" : "https://nodejs.org/dist";
+}
+export function nodeDownloadUrl(site, archive, version = NODE24_VERSION, env = process.env) {
+    return `${nodeDistBase(site, env)}/v${version}/${archive.file}`;
+}
+function join(...parts) {
+    return (process.platform === "win32" ? win32 : posix).join(...parts);
+}
+/** ~/.u1s1/agents/node/<版本>/ 下的 node(解压后只留可执行文件和 LICENSE)。 */
+export function managedNodeBin(agentsRoot, version = NODE24_VERSION, platform = process.platform) {
+    return join(agentsRoot, "node", version, platform === "win32" ? "node.exe" : "node");
+}
+/** `<node> --version` → 版本号;跑不起来返回 undefined。 */
+export function probeNodeVersion(bin) {
+    try {
+        const r = spawnSync(bin, ["--version"], { env: stripSecretEnv(process.env), encoding: "utf8", timeout: 15_000, windowsHide: true });
+        return r.status === 0 ? versionFromOutput(r.stdout ?? "") : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function nodeVersionOk(version, min = DSH_MIN_NODE) {
+    const v = normalizeVersion(version);
+    return !!v && compareVersions(v, min) >= 0;
+}
+export class NodeRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "NodeRuntimeError";
+    }
+}
+/** 不下载:按 1-4 的顺序找够新的 node。U1S1_DSH_NODE 指定了但不能用时抛 env_unusable。 */
+export function findNode(agentsRoot, deps = {}) {
+    const env = deps.env ?? process.env;
+    const probe = deps.probe ?? probeNodeVersion;
+    const exists = deps.exists ?? existsSync;
+    const pinned = env[NODE_BIN_ENV]?.trim();
+    if (pinned) {
+        const v = probe(pinned);
+        if (!v || !nodeVersionOk(v)) {
+            throw new NodeRuntimeError("env_unusable", `${NODE_BIN_ENV}=${pinned}: ${v ? `Node ${v} < ${DSH_MIN_NODE}` : "not runnable"}`);
+        }
+        return { bin: pinned, version: v, source: "env" };
+    }
+    const selfVersion = deps.selfVersion ?? process.versions.node;
+    if (nodeVersionOk(selfVersion))
+        return { bin: deps.execPath ?? process.execPath, version: normalizeVersion(selfVersion), source: "self" };
+    const onPath = findOnPath("node", { env, platform: deps.platform ?? process.platform, exists });
+    if (onPath) {
+        const v = probe(onPath);
+        if (v && nodeVersionOk(v))
+            return { bin: onPath, version: v, source: "path" };
+    }
+    const managed = managedNodeBin(agentsRoot, NODE24_VERSION, deps.platform ?? process.platform);
+    if (exists(managed)) {
+        const v = probe(managed);
+        if (v && nodeVersionOk(v))
+            return { bin: managed, version: v, source: "managed" };
+    }
+    return undefined;
+}
+/** 找到够新的 node;没有就征得同意后下载钉死的 Node 24 LTS。 */
+export async function ensureNode(opts) {
+    const found = (opts.find ?? (() => findNode(opts.agentsRoot, { env: opts.env })))();
+    if (found)
+        return found;
+    const archive = nodeArchive();
+    if (!archive)
+        throw new NodeRuntimeError("unsupported_platform", opts.text.unsupported());
+    const url = nodeDownloadUrl(opts.site, archive, NODE24_VERSION, opts.env);
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const ok = await opts.consent({ version: NODE24_VERSION, url, host: new URL(url).host, downloadBytes: NODE24_APPROX_BYTES });
+    if (!ok)
+        throw new NodeRuntimeError("declined", opts.text.declined());
+    opts.log(opts.text.downloading(NODE24_VERSION));
+    const bin = await downloadNode({ agentsRoot: opts.agentsRoot, archive, url, fetchImpl, text: opts.text });
+    opts.log(opts.text.installed(NODE24_VERSION));
+    return { bin, version: NODE24_VERSION, source: "download" };
+}
+/** 各平台压缩包约 30-55 MB;提示用。 */
+export const NODE24_APPROX_BYTES = 55 * 1024 * 1024;
+async function sha256File(file) {
+    const hash = createHash("sha256");
+    await pipeline(createReadStream(file), hash);
+    return hash.digest("hex");
+}
+function runTar(args, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn("tar", args, { cwd, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+        let output = "";
+        child.stdout?.on("data", (c) => { output += c.toString("utf8"); });
+        child.stderr?.on("data", (c) => { output += c.toString("utf8"); });
+        child.on("error", (e) => resolve({ code: 1, output: output + String(e) }));
+        child.on("exit", (code) => resolve({ code: code ?? 1, output }));
+    });
+}
+/**
+ * 下载 → 按钉死的 SHA-256 校验 → 只解出 node 和 LICENSE → 确认能跑且版本对 → 改名成正式目录。
+ * 中途失败只留暂存目录的残渣(下次启动前清掉),不影响已有的东西。
+ */
+export async function downloadNode(input) {
+    const version = input.version ?? NODE24_VERSION;
+    const root = join(input.agentsRoot, "node");
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const staging = join(root, `.staging-${version}-${randomBytes(4).toString("hex")}`);
+    mkdirSync(staging, { recursive: true });
+    try {
+        const archivePath = join(staging, input.archive.file);
+        let res;
+        try {
+            res = await input.fetchImpl(input.url, { signal: AbortSignal.timeout(10 * 60_000) });
+        }
+        catch (e) {
+            throw new NodeRuntimeError("download_failed", input.text.downloadFailed(e instanceof Error ? e.message : String(e)));
+        }
+        if (!res.ok || !res.body)
+            throw new NodeRuntimeError("download_failed", input.text.downloadFailed(`HTTP ${res.status}`));
+        await pipeline(Readable.fromWeb(res.body), createWriteStream(archivePath));
+        const got = await sha256File(archivePath);
+        if (got !== input.archive.sha256) {
+            throw new NodeRuntimeError("verify_failed", input.text.verifyFailed(`sha256 ${got} != ${input.archive.sha256}`));
+        }
+        const members = [`${input.archive.dir}/${input.archive.binInDir}`, `${input.archive.dir}/LICENSE`];
+        const extract = await runTar(["-xf", archivePath, ...members], staging);
+        if (extract.code !== 0)
+            throw new NodeRuntimeError("verify_failed", input.text.verifyFailed(`tar: ${extract.output.trim().slice(-300)}`));
+        const extracted = join(staging, input.archive.dir, ...input.archive.binInDir.split("/"));
+        const v = probeNodeVersion(extracted);
+        if (v !== version)
+            throw new NodeRuntimeError("verify_failed", input.text.verifyFailed(`node reports ${v ?? "nothing"}, expected ${version}`));
+        const target = join(root, version);
+        const finalDir = join(staging, "final");
+        mkdirSync(finalDir);
+        const binName = process.platform === "win32" ? "node.exe" : "node";
+        renameSync(extracted, join(finalDir, binName));
+        const license = join(staging, input.archive.dir, "LICENSE");
+        if (existsSync(license))
+            renameSync(license, join(finalDir, "LICENSE"));
+        rmSync(target, { recursive: true, force: true });
+        try {
+            renameSync(finalDir, target);
+        }
+        catch (e) {
+            // 另一个 u1s1 进程刚装好同一版本:用它的
+            if (!existsSync(join(target, binName)))
+                throw e;
+        }
+        return join(target, binName);
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+/** 暂存目录残渣(下载中途被打断)。 */
+export function cleanNodeStaging(agentsRoot) {
+    const root = join(agentsRoot, "node");
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (name.startsWith(".staging-"))
+            rmSync(join(root, name), { recursive: true, force: true });
+    }
+}