@nowcrew/daemon 0.6.88-beta.27 → 0.6.88-beta.29

package/dist/machine-info.js

@@ -1,4 +1,5 @@
 import { retryHarnessProbe } from "./runtimes/harness-probe-retry.js";
+import { MARKETPLACE_CAPABILITY } from "./marketplace-protocol.js";
 /**
  * 采集本机信息上报给控制面 (machine:hello):hostname / os / daemon 版本 / 已装 runtimes。
  * runtimes 探测靠 `which <bin>`(win32 用 `where`),只报真实可执行的 CLI(用于展示 Detected Runtimes)。
@@ -31,17 +32,20 @@ export const TRAINING_PROJECT_DEPENDENCIES_CAPABILITY = "training_project_depend
 export const SELF_TRAINING_EXECUTION_CAPABILITY = "self_training_execution_v1";
 export const EXECUTION_LARGE_ATTACHMENTS_CAPABILITY = "execution_attachments_300m_v1";
 export const PROJECT_SKILL_PROJECTION_CAPABILITY = "project_skill_projection_v2";
+export const MACHINE_ENVIRONMENT_CAPABILITY = "machine_environment_v1";
 export const NATIVE_PROJECT_WORKSPACE_READINESS = Object.freeze({
     resolverReady: true,
     nativeRuntimeAdaptersReady: true,
 });
 export const DAEMON_CAPABILITIES = Object.freeze([
+    MARKETPLACE_CAPABILITY,
     "scheduled_job_v1",
     "reply_origin_v1",
     "origin_decision_v1",
     "execution_telemetry_ack_v1",
     "execution_external_output_v1",
     "execution_attachments_v1",
+    "message_file_preview_v1",
     EXECUTION_LARGE_ATTACHMENTS_CAPABILITY,
     "execution_answer_stream_v1",
     "execution_machine_queue_v1",
@@ -56,6 +60,8 @@ export const DAEMON_CAPABILITIES = Object.freeze([
     "agent_ability_release_v1",
     "agent_ability_workspace_v1",
     "agent_ability_runtime_assets_v1",
+    "agent_environments_v1",
+    MACHINE_ENVIRONMENT_CAPABILITY,
 ]);
 /** 能力只按平台过滤,进程存活期间静态(CLAUDE.md 红线)。Windows 在 junction/copy 真机 smoke 通过前不宣告 Project Skills。 */
 export const daemonCapabilities = (runtimePlatform = process.platform, readiness = NATIVE_PROJECT_WORKSPACE_READINESS) => {
@@ -64,7 +70,9 @@ export const daemonCapabilities = (runtimePlatform = process.platform, readiness
     const nativeWorkspaceReady = nativeWorkspacePlatform
         && readiness.resolverReady
         && readiness.nativeRuntimeAdaptersReady;
-    return Object.freeze(DAEMON_CAPABILITIES.filter((capability) => ((capability !== PROJECT_WORKSPACES_CAPABILITY || nativeWorkspaceReady)
+    return Object.freeze(DAEMON_CAPABILITIES.filter((capability) => ((capability !== MARKETPLACE_CAPABILITY || nativeWorkspacePlatform)
+        && (capability !== PROJECT_WORKSPACES_CAPABILITY || nativeWorkspaceReady)
+        && (capability !== "message_file_preview_v1" || nativeWorkspacePlatform)
         && (nativeWorkspacePlatform
             || (capability !== "project_skills_v1"
                 && capability !== "project_skill_projection_v2"
@@ -98,10 +106,10 @@ const RUNTIME_BINS = [
     ["kimi", "kimi"],
     ["pi", "pi"],
 ];
-async function isInstalled(bin) {
+async function isInstalled(bin, env) {
     try {
         // 用增强 PATH 探测:daemon 继承的 PATH 可能缺 ~/.local/bin 等用户级目录(Claude 原生安装器落点)。
-        await execFileP(lookupCmd(), [bin], { env: { ...process.env, PATH: augmentedPath() } });
+        await execFileP(lookupCmd(), [bin], { env });
         return true;
     }
     catch {
@@ -109,10 +117,10 @@ async function isInstalled(bin) {
     }
 }
 /** 并发探测所有候选 runtime,返回已安装的展示名列表。 */
-export async function detectRuntimes() {
+export async function detectRuntimes(env = { ...process.env, PATH: augmentedPath() }) {
     const checks = await Promise.all(RUNTIME_BINS.map(async ([name, bin]) => {
         try {
-            return await isInstalled(name === "deepseek-harness" ? deepSeekHarnessLauncher().bin : bin) ? name : null;
+            return await isInstalled(name === "deepseek-harness" ? deepSeekHarnessLauncher(env).bin : bin, env) ? name : null;
         }
         catch {
             return null;
@@ -120,18 +128,18 @@ export async function detectRuntimes() {
     }));
     return checks.filter((x) => x !== null);
 }
-async function supportsKimiAcp(signal, probeId) {
-    return probeKimiAcp({ bin: "kimi", ...(probeId ? { probeId } : {}), ...(signal ? { signal } : {}) });
+async function supportsKimiAcp(signal, probeId, env) {
+    return probeKimiAcp({ bin: "kimi", ...(probeId ? { probeId } : {}), ...(signal ? { signal } : {}), ...(env ? { env } : {}) });
 }
-async function supportsHermesAcp(signal, probeId) {
-    return probeHermesAcp({ bin: "hermes", ...(probeId ? { probeId } : {}), ...(signal ? { signal } : {}) });
+async function supportsHermesAcp(signal, probeId, env) {
+    return probeHermesAcp({ bin: "hermes", ...(probeId ? { probeId } : {}), ...(signal ? { signal } : {}), ...(env ? { env } : {}) });
 }
-async function supportsOpenCodeRun(signal) {
-    return probeOpenCodeRun(signal);
+async function supportsOpenCodeRun(signal, _probeId, env) {
+    return probeOpenCodeRun(signal, env);
 }
-async function supportsDeepSeekHarnessAcp(signal, probeId) {
+async function supportsDeepSeekHarnessAcp(signal, probeId, env) {
     try {
-        return await probeDeepSeekHarnessAcp({ bin: deepSeekHarnessLauncher().bin, ...(probeId ? { probeId } : {}), ...(signal ? { signal } : {}) });
+        return await probeDeepSeekHarnessAcp({ bin: deepSeekHarnessLauncher(env).bin, ...(probeId ? { probeId } : {}), ...(signal ? { signal } : {}), ...(env ? { env } : {}) });
     }
     catch (error) {
         if (error instanceof AcpProbeCleanupError)
@@ -175,7 +183,7 @@ export async function detectExecutionRuntimes(installed = detectRuntimes(), kimi
                 : runtime === "deepseek-harness" ? deepSeekHarnessReady
                     : true));
 }
-export const detectExecutionRuntimesWithSignal = (installed, signal, probeId) => detectExecutionRuntimes(installed, supportsKimiAcp, supportsHermesAcp, supportsOpenCodeRun, supportsDeepSeekHarnessAcp, signal, probeId);
+export const detectExecutionRuntimesWithSignal = (installed, signal, probeId, env) => detectExecutionRuntimes(installed, (probeSignal, id) => supportsKimiAcp(probeSignal, id, env), (probeSignal, id) => supportsHermesAcp(probeSignal, id, env), (probeSignal, id) => supportsOpenCodeRun(probeSignal, id, env), (probeSignal, id) => supportsDeepSeekHarnessAcp(probeSignal, id, env), signal, probeId);
 export function daemonVersion() {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
@@ -212,13 +220,13 @@ async function listAgentHandles(agentsRoot) {
 }
 export async function collectMachineHello(agentsRoot, executionLimits, runtimePlatform = process.platform, dependencies = {}) {
     const [runtimes, agentHandles, additionalCapabilities] = await Promise.all([
-        (dependencies.detectInstalled ?? detectRuntimes)(),
+        (dependencies.detectInstalled ?? (() => detectRuntimes(dependencies.env)))(),
         listAgentHandles(agentsRoot),
         dependencies.additionalCapabilities?.() ?? Promise.resolve([]),
     ]);
     const backend = executionBackendCapability(runtimePlatform, dependencies.jobObjectProbe);
     const executionRuntimes = backend.supported
-        ? await (dependencies.detectExecutable ?? detectExecutionRuntimes)(runtimes)
+        ? await (dependencies.detectExecutable ?? ((installed) => detectExecutionRuntimesWithSignal(installed, undefined, undefined, dependencies.env)))(runtimes)
         : [];
     const baseCapabilities = dependencies.capabilities ?? daemonCapabilities(runtimePlatform);
     const capabilities = additionalCapabilities.length === 0 && Object.isFrozen(baseCapabilities)

package/dist/machine-runtime-environment.js

@@ -0,0 +1,189 @@
+import { WebSocket } from "ws";
+import { createMachineEnvironmentProvider, createStaticMachineEnvironmentProvider } from "./machine-environment-cache.js";
+import { copyMachineEnvironment } from "./machine-environment-policy.js";
+import { collectMachineHello, detectRuntimes, detectExecutionRuntimesWithSignal } from "./machine-info.js";
+import { conservativeExecutionRuntimes, createRuntimeProbeCoordinator } from "./runtime-probe.js";
+import { augmentedPath } from "./runtime-path.js";
+import { mergeRuntimeEnvironments, runtimeEnvironmentValue } from "./runtime-environment-merge.js";
+import { listRuntimeModels } from "./list-models.js";
+import { handleRuntimeProbeFrame, probeRuntimeHealth } from "./runtime-health.js";
+import { dslog } from "./slog.js";
+const version = (snapshot) => `${snapshot.status.bootId}:${snapshot.status.generation}`;
+/** 启动 hello 不等待 shell；每次成功环境代次以独立探测和连接围栏更新运行能力。 */
+export function createMachineRuntimeEnvironment(options) {
+    const startupEnv = copyMachineEnvironment(options.startupEnv ?? process.env);
+    let stopped = false;
+    let connection;
+    let cycle;
+    let accepted;
+    let latest;
+    let stopPromise;
+    let warmed = false;
+    const retiredBoots = new Set();
+    const preparedEnvironments = new WeakMap();
+    const prepare = (snapshot) => {
+        const existing = preparedEnvironments.get(snapshot.env);
+        if (existing)
+            return existing;
+        const source = { ...snapshot.env, PATH: runtimeEnvironmentValue(snapshot.env, "PATH") ?? "" };
+        const env = Object.freeze(mergeRuntimeEnvironments([snapshot.env, { PATH: augmentedPath(source, {}, process.platform, "append") }]));
+        preparedEnvironments.set(snapshot.env, env);
+        return env;
+    };
+    const current = (candidate) => !stopped && cycle === candidate
+        && connection === candidate.connection && connection.socket.readyState === WebSocket.OPEN
+        && version(latest) === version(candidate.snapshot);
+    const inactiveReason = (candidate) => connection !== candidate.connection
+        ? "stale_connection" : candidate.connection.socket.readyState !== WebSocket.OPEN
+        ? "socket_not_open" : "stale_environment";
+    const refreshRuntimes = () => {
+        if (stopped || !connection || connection.socket.readyState !== WebSocket.OPEN)
+            return;
+        cycle?.probe.stop();
+        const next = { connection, snapshot: latest, probe: createRuntimeProbeCoordinator(), facts: Promise.resolve([]), runtimes: [], known: false };
+        cycle = next;
+        const env = prepare(next.snapshot);
+        const collect = options.machineInfo?.collect ?? collectMachineHello;
+        const helloPromise = collect(options.config.agentsRoot, options.config.executionLimits, process.platform, {
+            env,
+            detectInstalled: () => (options.machineInfo?.detectInstalled ?? detectRuntimes)(env),
+            detectExecutable: async (installed) => conservativeExecutionRuntimes(installed),
+            additionalCapabilities: options.additionalCapabilities,
+            capabilities: next.connection.capabilities,
+            ...(options.profileName === undefined ? {} : { profileName: options.profileName }),
+        });
+        next.facts = helloPromise.then(async (hello) => {
+            if (!current(next))
+                return [];
+            next.runtimes = hello.executionRuntimes;
+            const initialPublished = next.connection.beforePublish.then(() => {
+                if (current(next))
+                    options.publish(hello, next.connection.socket);
+            });
+            const logDecision = (reason, runtimes) => dslog("runtime_probe.hello_refresh", "runtime hello 刷新决策", {
+                connection_id: next.connection.connectionId, reason, current_socket: connection === next.connection,
+                socket_open: next.connection.socket.readyState === WebSocket.OPEN, socket_ready_state: next.connection.socket.readyState,
+                installed_runtimes: JSON.stringify(hello.runtimes), initial_execution_runtimes: JSON.stringify(hello.executionRuntimes),
+                execution_runtimes: JSON.stringify(runtimes), environment_boot_id: next.snapshot.status.bootId, environment_generation: next.snapshot.status.generation,
+            });
+            if (hello.executionProtocol === undefined) {
+                next.known = true;
+                logDecision("protocol_unavailable", []);
+                await initialPublished;
+                return [];
+            }
+            const detector = options.machineInfo?.detectExecutable ?? detectExecutionRuntimesWithSignal;
+            const detected = await next.probe.detect(hello.runtimes, (installed, signal, probeId) => detector(installed, signal, probeId, env), next.connection.connectionId, version(next.snapshot));
+            if (!current(next)) {
+                logDecision(inactiveReason(next), detected);
+                return [];
+            }
+            next.runtimes = detected;
+            next.known = true;
+            await initialPublished;
+            const changed = JSON.stringify(detected) !== JSON.stringify(hello.executionRuntimes);
+            logDecision(!current(next) ? inactiveReason(next) : changed ? "publish" : "unchanged", detected);
+            if (current(next) && changed)
+                options.publish({ ...hello, executionRuntimes: [...detected] }, next.connection.socket);
+            return detected;
+        }).catch(() => {
+            if (current(next)) {
+                next.known = true;
+                options.onError("runtime_detection_failed", {
+                    reason: "detection_threw", ...(next.connection.connectionId === undefined ? {} : { connection_id: next.connection.connectionId }),
+                    current_socket: connection === next.connection, socket_open: next.connection.socket.readyState === WebSocket.OPEN,
+                });
+            }
+            return [];
+        });
+    };
+    const observe = (snapshot) => {
+        if (stopped)
+            return;
+        if (snapshot.status.state !== "ready") {
+            // 预热可先给出账号归属已恢复的基线；loading/disabled 本身不触发重新探测。
+            if (!accepted && !connection)
+                latest = snapshot;
+            return;
+        }
+        if (accepted) {
+            if (retiredBoots.has(snapshot.status.bootId))
+                return;
+            if (snapshot.status.bootId === accepted.status.bootId && snapshot.status.generation <= accepted.status.generation)
+                return;
+            if (snapshot.status.bootId !== accepted.status.bootId)
+                retiredBoots.add(accepted.status.bootId);
+        }
+        accepted = snapshot;
+        latest = snapshot;
+        refreshRuntimes();
+    };
+    const source = options.provider ?? (options.config.machineEnvironmentMode === undefined || options.config.machineEnvironmentMode === "off"
+        ? createStaticMachineEnvironmentProvider(startupEnv)
+        : createMachineEnvironmentProvider({ startupEnv, mode: options.config.machineEnvironmentMode, onChange: observe }));
+    latest = Object.freeze({ env: startupEnv, status: source.status() });
+    const stop = () => {
+        if (stopPromise)
+            return stopPromise;
+        stopped = true;
+        cycle?.probe.stop();
+        connection = undefined;
+        stopPromise = Promise.resolve().then(() => source.stop()).catch(() => { throw new Error("machine_environment_stop_failed"); });
+        return stopPromise;
+    };
+    const provider = {
+        async acquire(input) { if (stopped)
+            return latest; const snapshot = await source.acquire(input); observe(snapshot); return snapshot; },
+        status: () => source.status(), stop,
+    };
+    return {
+        provider,
+        prewarm: () => {
+            if (stopped || warmed)
+                return;
+            warmed = true;
+            void provider.acquire().catch(() => { if (!stopped)
+                options.onError("machine_environment_capture_failed"); });
+        },
+        open: (socket, input) => { connection = { socket, ...input }; refreshRuntimes(); },
+        close: (socket) => { if (connection?.socket === socket) {
+            connection = undefined;
+            cycle?.probe.stop();
+            cycle = undefined;
+        } },
+        async availableRuntimes(runtime) {
+            while (!stopped && cycle) {
+                const active = cycle;
+                if (active.runtimes.includes(runtime))
+                    return active.runtimes;
+                await active.facts;
+                if (cycle === active)
+                    return active.runtimes;
+            }
+            return [];
+        },
+        async models(runtime) {
+            const snapshot = await provider.acquire();
+            if (stopped || version(latest) !== version(snapshot))
+                throw new Error("runtime_environment_changed");
+            const models = await (options.models ?? listRuntimeModels)(runtime, { env: prepare(snapshot), environmentGeneration: version(snapshot) });
+            if (stopped || version(latest) !== version(snapshot))
+                throw new Error("runtime_environment_changed");
+            return models;
+        },
+        async health(decoded, probe = probeRuntimeHealth) {
+            return handleRuntimeProbeFrame(decoded, async (request) => {
+                const snapshot = await provider.acquire();
+                if (stopped || version(latest) !== version(snapshot))
+                    throw new Error("runtime_environment_changed");
+                const active = cycle;
+                const known = active?.known === true && version(active.snapshot) === version(snapshot);
+                const result = await probe(request, { env: prepare(snapshot), ...(known ? { availableRuntimes: active.runtimes } : {}) });
+                if (stopped || version(latest) !== version(snapshot))
+                    throw new Error("runtime_environment_changed");
+                return result;
+            });
+        },
+        stop,
+    };
+}

package/dist/machine-shell-environment-capture.js

@@ -0,0 +1,135 @@
+import { access, lstat, realpath, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { MachineEnvironmentCaptureError } from "./machine-environment-contract.js";
+import { isMachineTransientKey, machineCaptureStartupEnvironment, validateMachineEnvironment } from "./machine-environment-policy.js";
+import { runMachineEnvironmentProcess } from "./machine-environment-process.js";
+const quote = (value) => `'${value.replace(/'/gu, `'"'"'`)}'`;
+const ENV_PROGRAM = 'require("node:fs").writeFileSync(3,JSON.stringify(process.env))';
+/** stderr 只在私有有界管道中短暂保留；返回实际入口路径，不返回 trace 或错误文本。 */
+async function tracedZshEntrypoints(bytes, accountHome) {
+    if (!bytes)
+        throw new MachineEnvironmentCaptureError("shell_capture_failed");
+    const entries = new Set();
+    for (const line of bytes.toString("utf8").split("\n")) {
+        if (!line.endsWith("<sourcetrace>"))
+            continue;
+        const match = /^(.*):\d+> <sourcetrace>$/u.exec(line);
+        // 自定义 PS4 隐藏了来源时无法证明入口，不能把未检查的半份环境发布为 ready。
+        if (!match?.[1] || match[1].includes("\0"))
+            throw new MachineEnvironmentCaptureError("shell_capture_failed");
+        // printf >&2 可不换行。只接受原生 +path:line> 尾部中唯一真实入口，
+        // 不能把前缀噪声（可能含秘密）拼进 sourceLocations。
+        const starts = [...match[1].matchAll(/\+/gu)].map((part) => part.index + 1);
+        if (starts.length === 0 || starts.length > 32)
+            throw new MachineEnvironmentCaptureError("shell_capture_failed");
+        const paths = [...new Set(starts.map((start) => resolve(accountHome, match[1].slice(start))))]
+            .filter((path) => /\/(?:\.zshenv|\.zshrc)$/u.test(path)
+            || ["/etc/zshenv", "/etc/zsh/zshenv", "/etc/zshrc", "/etc/zsh/zshrc"].includes(path));
+        if (paths.length === 0)
+            continue;
+        const existing = (await Promise.all(paths.map(async (path) => {
+            try {
+                return (await stat(path)).isFile() ? path : null;
+            }
+            catch {
+                return null;
+            }
+        }))).filter((path) => path !== null);
+        if (existing.length !== 1)
+            throw new MachineEnvironmentCaptureError("shell_files_changed");
+        entries.add(existing[0]);
+    }
+    return [...entries];
+}
+export function machineShellSourceLocations(request, effectiveDirectory) {
+    if (request.source === "bash")
+        return [join(request.account.home, ".bashrc")];
+    if (request.source !== "zsh")
+        return [];
+    const initial = resolve(request.account.home, request.startupEnv.ZDOTDIR ?? request.account.home);
+    const effective = effectiveDirectory ?? initial;
+    return [...new Set(["/etc/zshenv", "/etc/zsh/zshenv", "/etc/zshrc", "/etc/zsh/zshrc", join(initial, ".zshenv"), join(initial, ".zshrc"), join(effective, ".zshrc")])].slice(0, 8);
+}
+export async function machineEnvironmentSourceFingerprint(locations) {
+    return JSON.stringify(await Promise.all(locations.map(async (path) => {
+        try {
+            const link = await lstat(path);
+            const target = await stat(path);
+            return [path, link.dev, link.ino, link.mtimeMs, link.ctimeMs, link.size, await realpath(path), target.dev, target.ino, target.mtimeMs, target.ctimeMs, target.size];
+        }
+        catch (error) {
+            if (["ENOENT", "ENOTDIR"].includes(error.code ?? ""))
+                return [path, "missing"];
+            throw new MachineEnvironmentCaptureError("shell_capture_failed");
+        }
+    })));
+}
+export const captureShellMachineEnvironment = async (request) => {
+    if (request.source !== "bash" && request.source !== "zsh")
+        throw new MachineEnvironmentCaptureError("shell_unavailable");
+    const file = request.shellPath;
+    if (!file || !isAbsolute(file))
+        throw new MachineEnvironmentCaptureError("shell_unavailable");
+    try {
+        await access(file, constants.X_OK);
+    }
+    catch {
+        throw new MachineEnvironmentCaptureError("shell_unavailable");
+    }
+    const env = machineCaptureStartupEnvironment(request.startupEnv, request.account, process.platform);
+    const processOptions = { file, env, cwd: request.account.home, signal: request.signal, deadline: request.deadline };
+    const syntaxCheck = async (path) => {
+        try {
+            await access(path, constants.R_OK);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw new MachineEnvironmentCaptureError("shell_capture_failed");
+        }
+        await runMachineEnvironmentProcess({ ...processOptions, args: request.source === "bash" ? ["--noprofile", "--norc", "-n", path] : ["-f", "-n", path], exitErrorCode: "shell_syntax_invalid" });
+    };
+    let locations = machineShellSourceLocations(request);
+    if (request.source === "bash")
+        await syntaxCheck(join(request.account.home, ".bashrc"));
+    const command = `${request.source === "zsh" ? "[[ -o sourcetrace ]] || exit 73; " : ""}exec ${quote(process.execPath)} -e ${quote(ENV_PROGRAM)}`;
+    const args = request.source === "zsh" ? ["-o", "SOURCE_TRACE", "-ic", command] : ["--noprofile", "--rcfile", join(request.account.home, ".bashrc"), "-ic", command];
+    for (let discovery = 0; discovery < 2; discovery++) {
+        const before = await machineEnvironmentSourceFingerprint(locations);
+        let sourceTraceBytes;
+        const bytes = await runMachineEnvironmentProcess({ ...processOptions, args, collectFd: 3, ...(request.source === "zsh" ? { metadataFd: 2, onMetadata: (value) => { sourceTraceBytes = value; } } : {}) });
+        if (before !== await machineEnvironmentSourceFingerprint(locations))
+            throw new MachineEnvironmentCaptureError("shell_files_changed");
+        if (request.source === "zsh") {
+            const actualEntrypoints = await tracedZshEntrypoints(sourceTraceBytes, request.account.home);
+            sourceTraceBytes = undefined;
+            const discovered = actualEntrypoints.some((path) => !locations.includes(path));
+            const nextLocations = [...new Set([...locations, ...actualEntrypoints])];
+            if (nextLocations.length > 8)
+                throw new MachineEnvironmentCaptureError("shell_capture_failed");
+            const actualBefore = await machineEnvironmentSourceFingerprint(nextLocations);
+            for (const path of actualEntrypoints)
+                await syntaxCheck(path);
+            if (actualBefore !== await machineEnvironmentSourceFingerprint(nextLocations))
+                throw new MachineEnvironmentCaptureError("shell_files_changed");
+            if (discovered) {
+                if (discovery > 0)
+                    throw new MachineEnvironmentCaptureError("shell_files_changed");
+                // 新发现的入口在本次执行前没有指纹；丢弃发现轮，按原截止时间重采一次。
+                locations = nextLocations;
+                continue;
+            }
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(bytes.toString("utf8"));
+        }
+        catch {
+            throw new MachineEnvironmentCaptureError("shell_capture_failed");
+        }
+        const exported = validateMachineEnvironment(parsed, bytes.length);
+        return { env: Object.freeze(Object.fromEntries(Object.entries(exported).filter(([key]) => !isMachineTransientKey(key)))), sourceLocations: locations };
+    }
+    throw new MachineEnvironmentCaptureError("shell_files_changed");
+};

package/dist/machine-windows-environment-capture.js

@@ -0,0 +1,215 @@
+import { spawn } from "node:child_process";
+import { win32 } from "node:path";
+import { MACHINE_ENVIRONMENT_MAX_BYTES, MACHINE_ENVIRONMENT_MAX_ENTRIES, MachineEnvironmentCaptureError, } from "./machine-environment-contract.js";
+import { WINDOWS_DAEMON_SID_SCRIPT, WINDOWS_ENVIRONMENT_CAPTURE_SCRIPT } from "./machine-windows-environment-script.js";
+const CAPTURE_TIMEOUT_MS = 8_000;
+const CLEANUP_TIMEOUT_MS = 2_000;
+const validSid = (value) => typeof value === "string" && value.length <= 184 && /^S-1-(?:\d+-)+\d+$/.test(value);
+const unavailable = () => new MachineEnvironmentCaptureError("windows_environment_unavailable");
+const validKey = (key) => key.length > 0 && !/[=\0]/.test(key);
+function systemExecutable(startupEnv, relative) {
+    const roots = Object.entries(startupEnv).filter(([key]) => key.toUpperCase() === "SYSTEMROOT");
+    const root = roots[0]?.[1];
+    if (roots.length !== 1 || !root || !/^[A-Za-z]:[\\/]/.test(root) || /[\0\r\n]/.test(root)
+        || root.slice(2).includes(":") || root.split(/[\\/]/).some((part) => part === "." || part === ".."))
+        throw unavailable();
+    return win32.join(root, "System32", relative);
+}
+/** 仅终止本调用仍持有的活 helper PID；根进程已退出时不按旧 PID 杀进程。 */
+export const runWindowsEnvironmentProcess = (request) => new Promise((resolve, reject) => {
+    if (request.signal?.aborted || request.deadline <= Date.now()) {
+        reject(new MachineEnvironmentCaptureError("shell_capture_timeout"));
+        return;
+    }
+    let child;
+    try {
+        child = spawn(request.file, [...request.args], {
+            env: { ...request.env }, stdio: ["ignore", "pipe", "pipe"], shell: false, windowsHide: true,
+        });
+    }
+    catch {
+        reject(unavailable());
+        return;
+    }
+    let settled = false;
+    let failure;
+    let cleanupTimer;
+    let killer;
+    let killerClosed = true;
+    let helperClosed = false;
+    const chunks = [];
+    let bytes = 0;
+    function finish(error) {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(captureTimer);
+        if (cleanupTimer !== undefined)
+            clearTimeout(cleanupTimer);
+        request.signal?.removeEventListener("abort", abort);
+        if (error) {
+            chunks.length = 0;
+            reject(new MachineEnvironmentCaptureError(error));
+        }
+        else
+            resolve(Buffer.concat(chunks));
+    }
+    function finishCleanup() {
+        if (helperClosed && killerClosed)
+            finish(failure);
+    }
+    function stop(code) {
+        if (failure || settled)
+            return;
+        failure = code;
+        chunks.length = 0;
+        clearTimeout(captureTimer);
+        cleanupTimer = setTimeout(() => {
+            // Node 的 kill 使用本 ChildProcess 的句柄；这里不使用已退出 helper 的陈旧 PID。
+            if (killer && killer.exitCode === null && killer.signalCode === null)
+                killer.kill();
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill();
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            child.unref();
+            finish("shell_cleanup_failed");
+        }, CLEANUP_TIMEOUT_MS);
+        if (child.pid && child.exitCode === null && child.signalCode === null) {
+            try {
+                killerClosed = false;
+                killer = spawn(systemExecutable(request.env, "taskkill.exe"), ["/PID", String(child.pid), "/T", "/F"], {
+                    env: { ...request.env }, stdio: "ignore", shell: false, windowsHide: true,
+                });
+                killer.once("error", () => { killerClosed = true; failure = "shell_cleanup_failed"; child.kill(); finishCleanup(); });
+                killer.once("close", (exitCode) => {
+                    killerClosed = true;
+                    if (exitCode !== 0)
+                        failure = "shell_cleanup_failed";
+                    finishCleanup();
+                });
+            }
+            catch {
+                killerClosed = true;
+                failure = "shell_cleanup_failed";
+                child.kill();
+            }
+        }
+        finishCleanup();
+    }
+    const abort = () => stop("shell_capture_timeout");
+    const captureTimer = setTimeout(abort, Math.max(1, request.deadline - Date.now()));
+    request.signal?.addEventListener("abort", abort, { once: true });
+    child.stdout?.on("data", (data) => {
+        if (settled || failure)
+            return;
+        bytes += data.length;
+        if (bytes > request.maxBytes)
+            stop("shell_capture_too_large");
+        else
+            chunks.push(Buffer.from(data));
+    });
+    child.stderr?.on("data", (data) => {
+        if (settled || failure)
+            return;
+        bytes += data.length;
+        if (bytes > request.maxBytes)
+            stop("shell_capture_too_large");
+    });
+    child.once("error", () => {
+        if (failure)
+            return;
+        finish("windows_environment_unavailable");
+    });
+    child.once("close", (code) => {
+        helperClosed = true;
+        if (failure)
+            finishCleanup();
+        else if (code === 0)
+            finish();
+        else
+            finish(code === 12 ? "shell_capture_too_large" : "windows_environment_unavailable");
+    });
+    if (request.signal?.aborted)
+        abort();
+});
+async function runScript(options, script) {
+    const deadline = Math.min(options.deadline ?? Date.now() + CAPTURE_TIMEOUT_MS, Date.now() + CAPTURE_TIMEOUT_MS);
+    if (options.signal?.aborted || deadline <= Date.now())
+        throw new MachineEnvironmentCaptureError("shell_capture_timeout");
+    const maxBytes = Math.min(options.maxBytes ?? MACHINE_ENVIRONMENT_MAX_BYTES, MACHINE_ENVIRONMENT_MAX_BYTES);
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        throw unavailable();
+    const file = systemExecutable(options.startupEnv, "WindowsPowerShell\\v1.0\\powershell.exe");
+    let output;
+    try {
+        output = await (options.runner ?? runWindowsEnvironmentProcess)({
+            file, args: ["-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")],
+            env: options.startupEnv, deadline, maxBytes, ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof MachineEnvironmentCaptureError)
+            throw new MachineEnvironmentCaptureError(error.code);
+        throw unavailable();
+    }
+    if (output.length > maxBytes)
+        throw new MachineEnvironmentCaptureError("shell_capture_too_large");
+    try {
+        const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(output));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw unavailable();
+        return parsed;
+    }
+    catch {
+        throw unavailable();
+    }
+}
+export async function captureWindowsEnvironment(options) {
+    if (!validSid(options.expectedSid))
+        throw unavailable();
+    const payload = await runScript(options, WINDOWS_ENVIRONMENT_CAPTURE_SCRIPT);
+    if (!validSid(payload.accountSid))
+        throw unavailable();
+    if (payload.accountSid !== options.expectedSid)
+        throw new MachineEnvironmentCaptureError("windows_environment_identity_mismatch");
+    if (!payload.env || typeof payload.env !== "object" || Array.isArray(payload.env) || !Array.isArray(payload.sourceOwnedKeys))
+        throw unavailable();
+    const entries = Object.entries(payload.env);
+    if (entries.length > MACHINE_ENVIRONMENT_MAX_ENTRIES || payload.sourceOwnedKeys.length > MACHINE_ENVIRONMENT_MAX_ENTRIES) {
+        throw new MachineEnvironmentCaptureError("shell_capture_too_large");
+    }
+    const env = Object.create(null);
+    const seen = new Set();
+    for (const [key, value] of entries) {
+        const folded = key.toUpperCase();
+        if (!validKey(key) || seen.has(folded) || typeof value !== "string" || value.includes("\0"))
+            throw unavailable();
+        seen.add(folded);
+        env[key] = value;
+    }
+    seen.clear();
+    const sourceOwnedKeys = [];
+    for (const key of payload.sourceOwnedKeys) {
+        if (typeof key !== "string" || !validKey(key) || seen.has(key.toUpperCase()))
+            throw unavailable();
+        seen.add(key.toUpperCase());
+        sourceOwnedKeys.push(key);
+    }
+    return Object.freeze({ env: Object.freeze(env), sourceOwnedKeys: Object.freeze(sourceOwnedKeys), accountSid: payload.accountSid });
+}
+export async function resolveWindowsDaemonSid(options) {
+    const payload = await runScript(options, WINDOWS_DAEMON_SID_SCRIPT);
+    if (!validSid(payload.accountSid))
+        throw unavailable();
+    return payload.accountSid;
+}
+export const captureWindowsMachineEnvironment = async (request) => {
+    const options = { startupEnv: request.startupEnv, signal: request.signal, deadline: request.deadline };
+    const expectedSid = request.account.sid ?? await resolveWindowsDaemonSid(options);
+    const result = await captureWindowsEnvironment({ ...options, expectedSid });
+    return {
+        ...result,
+        sourceLocations: ["HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment", "HKCU\\Environment"],
+    };
+};