helloloop 0.9.1 → 0.10.0

package/src/supervisor_state.mjs

@@ -0,0 +1,64 @@
+import { nowIso, readJson, writeJson } from "./common.mjs";
+
+export const ACTIVE_SUPERVISOR_STATUSES = new Set(["launching", "running"]);
+export const FINAL_SUPERVISOR_STATUSES = new Set(["completed", "failed", "stopped"]);
+
+export function readJsonIfExists(filePath) {
+  try {
+    return filePath ? readJson(filePath) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isTrackedPidAlive(pid) {
+  const numberPid = Number(pid || 0);
+  if (!Number.isFinite(numberPid) || numberPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(numberPid, 0);
+    return true;
+  } catch (error) {
+    return String(error?.code || "") === "EPERM";
+  }
+}
+
+function buildSupervisorState(context, patch = {}) {
+  const current = readSupervisorState(context) || {};
+  return {
+    ...current,
+    ...patch,
+    updatedAt: nowIso(),
+  };
+}
+
+export function readSupervisorState(context) {
+  return readJsonIfExists(context.supervisorStateFile);
+}
+
+export function hasActiveSupervisor(context) {
+  const state = readSupervisorState(context);
+  const activePid = Number(state?.guardianPid || state?.pid || 0);
+  return Boolean(
+    state?.status
+    && ACTIVE_SUPERVISOR_STATUSES.has(String(state.status))
+    && isTrackedPidAlive(activePid),
+  );
+}
+
+export function writeSupervisorState(context, patch) {
+  writeJson(context.supervisorStateFile, buildSupervisorState(context, patch));
+}
+
+export function writeActiveSupervisorState(context, patch = {}) {
+  const nextPatch = {
+    ...patch,
+    exitCode: null,
+    completedAt: "",
+  };
+  if (!Object.hasOwn(nextPatch, "message")) {
+    nextPatch.message = "";
+  }
+  writeSupervisorState(context, nextPatch);
+}

package/src/supervisor_watch.mjs

@@ -1,22 +1,16 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { fileExists, readJson, sleep } from "./common.mjs";
+import {
+  readJsonIfExists,
+  selectLatestActivityFile,
+  selectLatestRuntimeFile,
+} from "./activity_projection.mjs";
+import { fileExists, sleep } from "./common.mjs";
 import { renderHostLeaseLabel } from "./host_lease.mjs";
-
-const FINAL_STATUSES = new Set(["completed", "failed", "stopped"]);
-
-function readJsonIfExists(filePath) {
-  if (!filePath || !fileExists(filePath)) {
-    return null;
-  }
-
-  try {
-    return readJson(filePath);
-  } catch {
-    return null;
-  }
-}
+import { loadRuntimeSettings } from "./runtime_settings_loader.mjs";
+import { hasRetryBudget, pickRetryDelaySeconds } from "./runtime_settings.mjs";
+import { FINAL_SUPERVISOR_STATUSES } from "./supervisor_state.mjs";
 
 function writeLine(stream, message) {
   stream.write(`${message}\n`);
@@ -65,37 +59,6 @@ function formatTaskStatus(status) {
   return lines.join("\n");
 }
 
-function selectRuntimeFile(runDir) {
-  if (!runDir || !fileExists(runDir)) {
-    return "";
-  }
-
-  const candidates = [];
-  for (const entry of fs.readdirSync(runDir, { withFileTypes: true })) {
-    if (entry.isFile() && entry.name.endsWith("-runtime.json")) {
-      candidates.push(path.join(runDir, entry.name));
-      continue;
-    }
-    if (!entry.isDirectory()) {
-      continue;
-    }
-    const nestedDir = path.join(runDir, entry.name);
-    for (const nestedName of fs.readdirSync(nestedDir)) {
-      if (nestedName.endsWith("-runtime.json")) {
-        candidates.push(path.join(nestedDir, nestedName));
-      }
-    }
-  }
-
-  candidates.sort((left, right) => {
-    const rightTime = fs.statSync(right).mtimeMs;
-    const leftTime = fs.statSync(left).mtimeMs;
-    return rightTime - leftTime;
-  });
-
-  return candidates[0] || "";
-}
-
 function formatRuntimeState(runtime, previousRuntime) {
   if (!runtime?.status) {
     return "";
@@ -161,6 +124,44 @@ function formatRuntimeState(runtime, previousRuntime) {
   return `[HelloLoop watch] ${label}${details ? ` | ${details}` : ""}`;
 }
 
+function formatActivityState(activity, previousActivity) {
+  if (!activity?.current?.label && !activity?.todo?.total) {
+    return "";
+  }
+
+  const activeCommandLabel = Array.isArray(activity?.activeCommands) ? activity.activeCommands[0]?.label || "" : "";
+  const signature = [
+    activity.current?.status || "",
+    activity.current?.label || "",
+    activity.todo?.completed || 0,
+    activity.todo?.total || 0,
+    activeCommandLabel,
+  ].join("|");
+  const previousSignature = previousActivity
+    ? [
+      previousActivity.current?.status || "",
+      previousActivity.current?.label || "",
+      previousActivity.todo?.completed || 0,
+      previousActivity.todo?.total || 0,
+      Array.isArray(previousActivity?.activeCommands) ? previousActivity.activeCommands[0]?.label || "" : "",
+    ].join("|")
+    : "";
+
+  if (signature === previousSignature) {
+    return "";
+  }
+
+  const details = [];
+  if (activity.todo?.total) {
+    details.push(`todo=${activity.todo.completed}/${activity.todo.total}`);
+  }
+  if (activeCommandLabel) {
+    details.push(`cmd=${activeCommandLabel}`);
+  }
+
+  return `[HelloLoop watch] 当前动作：${activity.current?.label || "等待事件"}${details.length ? ` | ${details.join(" | ")}` : ""}`;
+}
+
 function readTextDelta(filePath, offset) {
   if (!filePath || !fileExists(filePath)) {
     return { nextOffset: 0, text: "" };
@@ -244,6 +245,7 @@ export async function watchSupervisorSession(context, options = {}) {
   let lastSupervisorSignature = "";
   let lastTaskSignature = "";
   let previousRuntime = null;
+  let previousActivity = null;
   let missingPolls = 0;
 
   while (true) {
@@ -251,8 +253,12 @@ export async function watchSupervisorSession(context, options = {}) {
     const result = readJsonIfExists(context.supervisorResultFile);
     const activeSessionId = expectedSessionId || supervisor?.sessionId || result?.sessionId || "";
     const taskStatus = resolveStatusForSession(readJsonIfExists(context.statusFile), activeSessionId);
-    const runtimeFile = taskStatus?.runDir ? selectRuntimeFile(taskStatus.runDir) : "";
+    const runtimeFile = taskStatus?.runDir ? selectLatestRuntimeFile(taskStatus.runDir) : "";
     const runtime = readJsonIfExists(runtimeFile);
+    const activityFile = runtime?.activityFile && fileExists(runtime.activityFile)
+      ? runtime.activityFile
+      : (taskStatus?.runDir ? selectLatestActivityFile(taskStatus.runDir, runtime?.attemptPrefix || "") : "");
+    const activity = readJsonIfExists(activityFile);
 
     if (!supervisor && !result) {
       missingPolls += 1;
@@ -296,6 +302,11 @@ export async function watchSupervisorSession(context, options = {}) {
       writeLine(stdoutStream, runtimeMessage);
     }
     previousRuntime = runtime || previousRuntime;
+    const activityMessage = formatActivityState(activity, previousActivity);
+    if (activityMessage) {
+      writeLine(stdoutStream, activityMessage);
+    }
+    previousActivity = activity || previousActivity;
 
     const activePrefix = runtime?.attemptPrefix || "";
     const runtimeDir = runtimeFile ? path.dirname(runtimeFile) : "";
@@ -309,7 +320,7 @@ export async function watchSupervisorSession(context, options = {}) {
     readAndWriteDelta(stdoutCursor, stdoutFile, stdoutStream);
     readAndWriteDelta(stderrCursor, stderrFile, stderrStream);
 
-    if (supervisor?.status && FINAL_STATUSES.has(String(supervisor.status))) {
+    if (supervisor?.status && FINAL_SUPERVISOR_STATUSES.has(String(supervisor.status))) {
       readAndWriteDelta(stdoutCursor, stdoutFile, stdoutStream);
       readAndWriteDelta(stderrCursor, stderrFile, stderrStream);
       return buildWatchResult(supervisor, result);
@@ -318,3 +329,36 @@ export async function watchSupervisorSession(context, options = {}) {
     await sleep(pollMs);
   }
 }
+
+function formatRetryAttachMessage(options, attemptNumber, delaySeconds) {
+  const sessionLabel = String(options.sessionId || "").trim();
+  const targetLabel = sessionLabel
+    ? `后台会话 ${sessionLabel}`
+    : "后台会话";
+  return `[HelloLoop watch] 暂未检测到可附着的${targetLabel}，将在 ${delaySeconds} 秒后自动重试（第 ${attemptNumber} 次）。`;
+}
+
+export async function watchSupervisorSessionWithRecovery(context, options = {}) {
+  const observerRetry = loadRuntimeSettings({
+    globalConfigFile: options.globalConfigFile,
+  }).observerRetry;
+  const stdoutStream = options.stdoutStream || process.stdout;
+  let retryCount = 0;
+
+  while (true) {
+    const result = await watchSupervisorSession(context, options);
+    if (!result.empty) {
+      return result;
+    }
+
+    const nextAttempt = retryCount + 1;
+    if (!observerRetry.enabled || !hasRetryBudget(observerRetry.maxRetryCount, nextAttempt)) {
+      return result;
+    }
+
+    const delaySeconds = pickRetryDelaySeconds(observerRetry.retryDelaysSeconds, nextAttempt);
+    writeLine(stdoutStream, formatRetryAttachMessage(options, nextAttempt, delaySeconds));
+    retryCount = nextAttempt;
+    await sleep(delaySeconds * 1000);
+  }
+}

package/src/terminal_session_limits.mjs

@@ -3,6 +3,7 @@ import path from "node:path";
 
 import { ensureDir, fileExists, nowIso, readJson, timestampForFile, writeJson } from "./common.mjs";
 import { loadGlobalConfig } from "./global_config.mjs";
+import { normalizeTerminalConcurrencySettings } from "./runtime_settings.mjs";
 
 const SESSION_DIR_NAME = "terminal-sessions";
 const RUNTIME_DIR_NAME = "runtime";
@@ -33,27 +34,6 @@ function isPidAlive(pid) {
   }
 }
 
-function normalizeNonNegativeInteger(value, fallbackValue) {
-  if (value === null || value === undefined || value === "") {
-    return fallbackValue;
-  }
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed < 0) {
-    return fallbackValue;
-  }
-  return Math.floor(parsed);
-}
-
-export function normalizeTerminalConcurrencySettings(settings = {}) {
-  const source = settings && typeof settings === "object" ? settings : {};
-  return {
-    enabled: source.enabled !== false,
-    visibleMax: normalizeNonNegativeInteger(source.visibleMax, 8),
-    backgroundMax: normalizeNonNegativeInteger(source.backgroundMax, 8),
-    totalMax: normalizeNonNegativeInteger(source.totalMax, 8),
-  };
-}
-
 function resolveTerminalRuntimeConfig(options = {}) {
   const globalConfig = loadGlobalConfig({
     globalConfigFile: options.globalConfigFile,

package/src/windows_hidden_shell_proxy.mjs

@@ -0,0 +1,405 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { ensureDir, fileExists, readText, writeJson } from "./common.mjs";
+
+const REAL_PWSH_ENV = "HELLOLOOP_REAL_PWSH";
+const REAL_POWERSHELL_ENV = "HELLOLOOP_REAL_POWERSHELL";
+const ORIGINAL_PATH_ENV = "HELLOLOOP_ORIGINAL_PATH";
+const PROXY_ENABLED_ENV = "HELLOLOOP_HIDDEN_SHELL_PROXY_ENABLED";
+export const HIDDEN_PROCESS_PROXY_TARGET_ENV = "HELLOLOOP_PROXY_TARGET_EXE";
+const PROXY_METADATA_FILE = "metadata.json";
+const PROXY_ALIASES = ["pwsh.exe", "powershell.exe"];
+const PROXY_EXECUTABLE = "HelloLoopHiddenShellProxy.exe";
+const WINDOWS_SYSTEM_ROOT = process.env.SystemRoot || "C:\\Windows";
+const WHERE_EXE = path.join(WINDOWS_SYSTEM_ROOT, "System32", "where.exe");
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const toolRoot = path.resolve(__dirname, "..");
+const proxySourceRoot = path.join(toolRoot, "native", "windows-hidden-shell-proxy");
+const proxyProjectFile = path.join(proxySourceRoot, "HelloLoopHiddenShellProxy.csproj");
+const proxyProgramFile = path.join(proxySourceRoot, "Program.cs");
+
+function trimOuterQuotes(value) {
+  return String(value || "").trim().replace(/^"(.*)"$/u, "$1");
+}
+
+function splitWindowsPath(value) {
+  return String(value || "")
+    .split(";")
+    .map((item) => trimOuterQuotes(item))
+    .filter(Boolean);
+}
+
+function uniqueNonEmpty(values) {
+  return [...new Set(values.map((item) => trimOuterQuotes(item)).filter(Boolean))];
+}
+
+function buildWindowsPath(frontDirs, basePath) {
+  return uniqueNonEmpty([
+    ...frontDirs,
+    ...splitWindowsPath(basePath),
+  ]).join(";");
+}
+
+function parseWhereOutput(output) {
+  return String(output || "")
+    .split(/\r?\n/)
+    .map((line) => trimOuterQuotes(line))
+    .filter(Boolean);
+}
+
+function sleepSync(ms) {
+  const shared = new SharedArrayBuffer(4);
+  const view = new Int32Array(shared);
+  Atomics.wait(view, 0, 0, Math.max(0, ms));
+}
+
+function isManagedProxyPath(candidate) {
+  return String(candidate || "")
+    .replaceAll("/", "\\")
+    .toLowerCase()
+    .includes("\\.helloloop\\runtime\\windows-hidden-shell\\");
+}
+
+function resolveShellFallbacks() {
+  const programFiles = process.env.ProgramW6432 || process.env.ProgramFiles || "";
+  const systemRoot = process.env.SystemRoot || "C:\\Windows";
+  return {
+    pwsh: [
+      path.join(programFiles, "PowerShell", "7", "pwsh.exe"),
+      path.join(programFiles, "PowerShell", "7-preview", "pwsh.exe"),
+    ],
+    powershell: [
+      path.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"),
+    ],
+  };
+}
+
+function findExecutableInWindowsPath(executableName, lookupPath) {
+  const result = spawnSync(WHERE_EXE, [executableName], {
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+    env: {
+      ...process.env,
+      PATH: lookupPath || process.env.PATH || "",
+    },
+  });
+  if (result.status !== 0) {
+    return "";
+  }
+  return parseWhereOutput(result.stdout).find((candidate) => !isManagedProxyPath(candidate) && fs.existsSync(candidate)) || "";
+}
+
+function resolveDotnetExecutable() {
+  const candidates = uniqueNonEmpty([
+    process.env.HELLOLOOP_DOTNET_EXECUTABLE,
+    process.env.DOTNET_ROOT ? path.join(process.env.DOTNET_ROOT, "dotnet.exe") : "",
+    process.env.ProgramFiles ? path.join(process.env.ProgramFiles, "dotnet", "dotnet.exe") : "",
+    process.env["ProgramFiles(x86)"] ? path.join(process.env["ProgramFiles(x86)"], "dotnet", "dotnet.exe") : "",
+    findExecutableInWindowsPath("dotnet.exe", process.env.PATH || ""),
+  ]);
+  return candidates.find((candidate) => fileExists(candidate)) || "";
+}
+
+function resolveRealWindowsShells(lookupPath) {
+  const fallbacks = resolveShellFallbacks();
+  const pwsh = findExecutableInWindowsPath("pwsh.exe", lookupPath)
+    || fallbacks.pwsh.find((candidate) => fileExists(candidate))
+    || "";
+  const powershell = findExecutableInWindowsPath("powershell.exe", lookupPath)
+    || fallbacks.powershell.find((candidate) => fileExists(candidate))
+    || "";
+
+  return {
+    pwsh,
+    powershell,
+  };
+}
+
+function resolveSourceHash() {
+  const hash = crypto.createHash("sha256");
+  hash.update(readText(path.join(toolRoot, "package.json")));
+  hash.update(readText(proxyProjectFile));
+  hash.update(readText(proxyProgramFile));
+  hash.update(process.arch);
+  return hash.digest("hex").slice(0, 16);
+}
+
+function resolveRuntimeRoot() {
+  return path.join(
+    os.homedir(),
+    ".helloloop",
+    "runtime",
+    "windows-hidden-shell",
+    `${process.arch}-${resolveSourceHash()}`,
+  );
+}
+
+function resolveProxyBinDir(runtimeRoot) {
+  return path.join(runtimeRoot, "bin");
+}
+
+function resolveProxyMetadataFile(runtimeRoot) {
+  return path.join(runtimeRoot, PROXY_METADATA_FILE);
+}
+
+function isProxyReady(runtimeRoot) {
+  const metadataFile = resolveProxyMetadataFile(runtimeRoot);
+  if (!fileExists(metadataFile)) {
+    return false;
+  }
+
+  try {
+    const metadata = JSON.parse(readText(metadataFile));
+    if (metadata.sourceHash !== resolveSourceHash()) {
+      return false;
+    }
+  } catch {
+    return false;
+  }
+
+  const binDir = resolveProxyBinDir(runtimeRoot);
+  return PROXY_ALIASES.every((fileName) => fileExists(path.join(binDir, fileName)));
+}
+
+function writeProxyMetadata(runtimeRoot, realShells, buildTool) {
+  writeJson(resolveProxyMetadataFile(runtimeRoot), {
+    schemaVersion: 1,
+    sourceHash: resolveSourceHash(),
+    builtAt: new Date().toISOString(),
+    buildTool,
+    realShells,
+  });
+}
+
+function finalizeBuiltProxy(runtimeRoot, realShells, buildTool) {
+  const binDir = resolveProxyBinDir(runtimeRoot);
+  const baseExe = path.join(binDir, PROXY_EXECUTABLE);
+  if (!fileExists(baseExe)) {
+    throw new Error(`未生成隐藏 shell 代理可执行文件：${baseExe}`);
+  }
+
+  for (const alias of PROXY_ALIASES) {
+    fs.copyFileSync(baseExe, path.join(binDir, alias));
+  }
+
+  writeProxyMetadata(runtimeRoot, realShells, buildTool);
+}
+
+function resolveDotnetSdkExecutable() {
+  const dotnetExecutable = resolveDotnetExecutable();
+  if (!dotnetExecutable) {
+    return "";
+  }
+  const result = spawnSync(dotnetExecutable, ["--list-sdks"], {
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+  });
+  if (result.status !== 0 || !String(result.stdout || "").trim()) {
+    return "";
+  }
+  return dotnetExecutable;
+}
+
+function buildProxyWithDotnet(runtimeRoot, realShells, dotnetExecutable) {
+  ensureDir(runtimeRoot);
+
+  const binDir = resolveProxyBinDir(runtimeRoot);
+  ensureDir(binDir);
+
+  const publish = spawnSync(dotnetExecutable, [
+    "publish",
+    proxyProjectFile,
+    "-nologo",
+    "-c",
+    "Release",
+    "-o",
+    binDir,
+  ], {
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+    cwd: proxySourceRoot,
+  });
+
+  if (publish.status !== 0) {
+    throw new Error([
+      "dotnet publish 执行失败。",
+      String(publish.stdout || "").trim(),
+      String(publish.stderr || "").trim(),
+    ].filter(Boolean).join("\n"));
+  }
+
+  finalizeBuiltProxy(runtimeRoot, realShells, "dotnet");
+}
+
+function buildProxyWithPowerShell(runtimeRoot, realShells) {
+  const compilerShell = realShells.powershell || realShells.pwsh;
+  if (!compilerShell) {
+    throw new Error("未找到可用于编译隐藏 shell 代理的 PowerShell。");
+  }
+
+  ensureDir(runtimeRoot);
+  const binDir = resolveProxyBinDir(runtimeRoot);
+  ensureDir(binDir);
+
+  const buildScriptFile = path.join(runtimeRoot, "build-hidden-shell-proxy.ps1");
+  const outputAssembly = path.join(binDir, "HelloLoopHiddenShellProxy.exe");
+  const scriptContent = [
+    "param(",
+    "  [string]$SourcePath,",
+    "  [string]$OutputAssembly",
+    ")",
+    "$ErrorActionPreference = 'Stop'",
+    "Add-Type -Path $SourcePath -OutputAssembly $OutputAssembly -OutputType WindowsApplication",
+  ].join("\n");
+  fs.writeFileSync(buildScriptFile, scriptContent, "utf8");
+
+  const compile = spawnSync(compilerShell, [
+    "-NoLogo",
+    "-NoProfile",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-File",
+    buildScriptFile,
+    "-SourcePath",
+    proxyProgramFile,
+    "-OutputAssembly",
+    outputAssembly,
+  ], {
+    encoding: "utf8",
+    shell: false,
+    windowsHide: true,
+    cwd: runtimeRoot,
+  });
+
+  if (compile.status !== 0) {
+    throw new Error([
+      "PowerShell Add-Type 编译隐藏 shell 代理失败。",
+      String(compile.stdout || "").trim(),
+      String(compile.stderr || "").trim(),
+    ].filter(Boolean).join("\n"));
+  }
+
+  finalizeBuiltProxy(runtimeRoot, realShells, "powershell-add-type");
+}
+
+function buildProxy(runtimeRoot, realShells) {
+  const dotnetExecutable = resolveDotnetSdkExecutable();
+  if (dotnetExecutable) {
+    buildProxyWithDotnet(runtimeRoot, realShells, dotnetExecutable);
+    return;
+  }
+  buildProxyWithPowerShell(runtimeRoot, realShells);
+}
+
+function acquireBuildLock(runtimeRoot) {
+  const lockDir = path.join(runtimeRoot, ".build-lock");
+  ensureDir(runtimeRoot);
+  try {
+    fs.mkdirSync(lockDir);
+    return {
+      acquired: true,
+      lockDir,
+    };
+  } catch (error) {
+    if (String(error?.code || "") !== "EEXIST") {
+      throw error;
+    }
+    return {
+      acquired: false,
+      lockDir,
+    };
+  }
+}
+
+function waitForExistingBuild(runtimeRoot) {
+  const deadline = Date.now() + 180000;
+  while (Date.now() < deadline) {
+    if (isProxyReady(runtimeRoot)) {
+      return;
+    }
+    sleepSync(500);
+  }
+  throw new Error("等待已有 Windows 隐藏 shell 代理构建完成超时。");
+}
+
+function ensureProxyBuilt(realShells) {
+  const runtimeRoot = resolveRuntimeRoot();
+  if (isProxyReady(runtimeRoot)) {
+    return runtimeRoot;
+  }
+
+  const lock = acquireBuildLock(runtimeRoot);
+  if (!lock.acquired) {
+    waitForExistingBuild(runtimeRoot);
+    return runtimeRoot;
+  }
+
+  try {
+    if (!isProxyReady(runtimeRoot)) {
+      buildProxy(runtimeRoot, realShells);
+    }
+    return runtimeRoot;
+  } finally {
+    fs.rmSync(lock.lockDir, { recursive: true, force: true });
+  }
+}
+
+function ensureProxyRuntime(options = {}) {
+  const basePath = String(options.basePath || process.env.PATH || "").trim();
+  const realShells = resolveRealWindowsShells(basePath);
+  if (!realShells.pwsh && !realShells.powershell) {
+    throw new Error("未找到真实的 pwsh.exe 或 powershell.exe，无法建立隐藏 shell 代理。");
+  }
+
+  const runtimeRoot = ensureProxyBuilt(realShells);
+  const proxyBinDir = resolveProxyBinDir(runtimeRoot);
+  const proxyExecutable = path.join(proxyBinDir, PROXY_EXECUTABLE);
+  if (!fileExists(proxyExecutable)) {
+    throw new Error(`未找到隐藏 shell 代理可执行文件：${proxyExecutable}`);
+  }
+
+  return {
+    basePath,
+    runtimeRoot,
+    proxyBinDir,
+    proxyExecutable,
+    realShells,
+  };
+}
+
+export function resolveWindowsHiddenProcessProxyExecutable(options = {}) {
+  if ((options.platform || process.platform) !== "win32") {
+    return "";
+  }
+  return ensureProxyRuntime(options).proxyExecutable;
+}
+
+/**
+ * Resolve the Windows hidden-shell proxy environment patch used to suppress
+ * background pwsh/powershell console windows for Codex child processes.
+ */
+export function resolveWindowsHiddenShellEnvPatch(options = {}) {
+  if ((options.platform || process.platform) !== "win32") {
+    return {};
+  }
+
+  const runtime = ensureProxyRuntime(options);
+
+  return {
+    [REAL_PWSH_ENV]: runtime.realShells.pwsh,
+    [REAL_POWERSHELL_ENV]: runtime.realShells.powershell,
+    [ORIGINAL_PATH_ENV]: runtime.basePath,
+    [PROXY_ENABLED_ENV]: "1",
+    PATH: buildWindowsPath([runtime.proxyBinDir], runtime.basePath),
+  };
+}