@sema-agent/server 7.127.0 → 7.127.1

package/MIGRATION.md

@@ -7,6 +7,10 @@
 > ⚠️ 完整清单在仓库根 `CHANGELOG.md`——它**不随 npm tarball 出包**(本文件随包)。看完整迁移窗的
 > 权威姿势是源码 tag diff:`git diff v<旧>..v<新>`(每版都推 `v<版本>` tag);npm 包页也镜像 CHANGELOG。
 
+## 7.127.1 —— Windows 宿主车道:策略链读 `cdPath` 不再因 shell 未落定而拒每条 Bash(行为修复,升级零动作)
+
+升级零动作:无 DDL、无配置变化、无 wire 变化。**谁受影响**:Windows 宿主部署里 server 进程环境找不到 Git Bash 的(PATH 无 Git、`ProgramFiles` 不对、经 ssh 起服白名单环境等)—— 7.127.0 及之前每条 Bash 都被策略链拒成「policy check threw / aborted」且真因被吞;本版起策略链读 `cdPath` 不再碰 shell,命令真要跑时才以真因拒(装 Git for Windows 或设 `HOST_SHELL_PATH`)。装了 Git Bash 的普通部署行为不变。回滚到 7.127.0 安全。
+
 ## 7.127.0 —— 引擎 7.50.2(精确钉)· 🔴 `tool_end.output` 带图:SSE 整块、账本只存描述符 · 新帧 `task_started`(SSE 与账本同在)· 🔴 e2b / k8s 车道不再挂 LSP · 记忆整理按人的路径规则判写(自动腿)· 附件请求键 400 · `~/…` 规则在无家目录车道上转问
 
 1. **`tool_end.output` 两形(BREAKING,消费方)**:`output` 可以是串,也可以是块数组;块里可有图像 / 文档 `{ type, data, mimeType }`。

package/dist/plugins/host-platform.d.ts

@@ -18,6 +18,9 @@
  *              pair from case-sensitive Object.assign reaches CreateProcess as ONE undefined-which
  *              entry). Canonical casing = the first-seen key (process.env's native casing wins since the
  *              inherit base is spread first).
+ *  - layering = env COMPOSITION is a pure function of config + process.env and never reads the resolved shell;
+ *              the shell belongs to the SPAWN layer only ({@link pinHostShell}, applied by the spawn sites after
+ *              `shellReady()`). A read surface (`cdPath`) therefore never depends on resolution having settled.
  *
  * ⚠️ The win32 branches are UNVERIFIED on a real machine until S5 (Windows CI runner) — design D5 discipline:
  * structural tests only on mac/Linux; behavior-level bite happens on the first Windows-runner green.
@@ -39,10 +42,22 @@ export interface HostShell {
  * read the cached value synchronously via {@link hostShell}.
  */
 export declare function resolveHostShell(): Promise<HostShell>;
-/** Synchronous read of the resolved shell — valid only AFTER {@link resolveHostShell} settled (the spawn sites
- *  are all behind `shellReady()`, which awaits it). POSIX never needs the async step. Throws on a mis-ordered
- *  call (a programming bug, not an operator condition — fail loud, not /bin/sh-on-windows). */
+/** Synchronous read of the resolved shell — a SPAWN-layer read, valid only AFTER {@link resolveHostShell} settled
+ *  (the spawn sites are all behind `shellReady()`, which awaits it). It is never an env-composition or read-surface
+ *  input (see {@link pinHostShell}). POSIX never needs the async step.
+ *  win32, not settled: a resolve that FAILED throws that failure (the real cause + the way out, memoised above);
+ *  only a resolve that never ran / is still in flight reaches the ordering sentence — on the spawn paths that arm
+ *  is unreachable (they await the resolve first), so it stays as the loud guard against a future mis-ordered caller
+ *  (a programming bug, not an operator condition — fail loud, not /bin/sh-on-windows). */
 export declare function hostShell(): HostShell;
+/**
+ * The SPAWN layer's one env edit: win32 pins `SHELL` to the resolved Git Bash (subshell scripts read `$SHELL`).
+ * Takes the {@link HostShell} the caller already read via {@link hostShell} — so a spawn site cannot reach the pin
+ * without a resolved shell (the type is the ordering guard), and env COMPOSITION never needs one. Mutates and
+ * returns `env` (call it BEFORE {@link collapseWin32EnvKeys} so an inherited case-variant `Shell` folds into one
+ * entry). POSIX: identity — `SHELL` is whatever the composed env already carried (byte-identical to pre-Windows).
+ */
+export declare function pinHostShell(env: NodeJS.ProcessEnv, sh: HostShell): NodeJS.ProcessEnv;
 /** test-only: reset the shell caches (each test can re-drive resolution). */
 export declare function resetHostShellCacheForTest(): void;
 /** Per-platform spawn options for a group-killable child (design D3).

package/dist/plugins/host-platform.js

@@ -4,6 +4,7 @@ export const IS_WIN32 = process.platform === "win32";
 const POSIX_SH_FALLBACK = { shell: "/bin/sh", args: ["-c"] };
 let cachedWinShell;
 let cachedPosixShell;
+let winShellFailure;
 export async function resolveHostShell() {
     if (!IS_WIN32) {
         if (cachedPosixShell)
@@ -15,26 +16,38 @@ export async function resolveHostShell() {
     if (cachedWinShell)
         return cachedWinShell;
     const custom = process.env.HOST_SHELL_PATH;
-    const cfg = await getShellConfig(custom || undefined);
-    if (!cfg.ok) {
-        throw new Error(`host lane needs a POSIX shell on Windows and none was found${custom ? ` (HOST_SHELL_PATH=${custom})` : ""}: ` +
-            `${cfg.error.message}. Install Git for Windows (https://gitforwindows.org) or set HOST_SHELL_PATH to a bash.exe. ` +
-            `Note: System32\\bash.exe is the WSL launcher, not a Windows bash — it is deliberately rejected.`);
+    try {
+        const cfg = await getShellConfig(custom || undefined);
+        if (!cfg.ok) {
+            throw new Error(`host lane needs a POSIX shell on Windows and none was found${custom ? ` (HOST_SHELL_PATH=${custom})` : ""}: ` +
+                `${cfg.error.message}. Install Git for Windows (https://gitforwindows.org) or set HOST_SHELL_PATH to a bash.exe. ` +
+                `Note: System32\\bash.exe is the WSL launcher, not a Windows bash — it is deliberately rejected.`);
+        }
+        cachedWinShell = { shell: cfg.value.shell, args: cfg.value.args };
+        return cachedWinShell;
+    }
+    catch (e) {
+        winShellFailure = e instanceof Error ? e : new Error(String(e));
+        throw winShellFailure;
     }
-    cachedWinShell = { shell: cfg.value.shell, args: cfg.value.args };
-    return cachedWinShell;
 }
 export function hostShell() {
     if (!IS_WIN32) {
         return cachedPosixShell ?? POSIX_SH_FALLBACK;
     }
-    if (!cachedWinShell)
-        throw new Error("host shell not resolved yet — resolveHostShell() must settle before any spawn (shellReady ordering bug)");
-    return cachedWinShell;
+    if (cachedWinShell)
+        return cachedWinShell;
+    throw winShellFailure ?? new Error("host shell not resolved yet — resolveHostShell() must settle before any spawn (shellReady ordering bug)");
+}
+export function pinHostShell(env, sh) {
+    if (IS_WIN32)
+        env.SHELL = sh.shell;
+    return env;
 }
 export function resetHostShellCacheForTest() {
     cachedWinShell = undefined;
     cachedPosixShell = undefined;
+    winShellFailure = undefined;
 }
 export function spawnGroupOptions() {
     return IS_WIN32 ? { detached: false, windowsHide: true } : { detached: true };

package/dist/plugins/remote-env-host.d.ts

@@ -96,8 +96,10 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
     readonly homeDir?: string | undefined;
     /**
      * core 7.49.0 #1554:shell 子进程**真拿到的** `CDPATH` 条目(`[]` = 没有)—— 删除守卫按它解裸 `cd <dir>`。本车道的命令就是本机子进程,
-     * env 是本类自己组合的(继承姿态 + `cfg.env`),所以说得出:读同一只组合({@link childEnv},不披露),切法与 core `NodeExecutionEnv` 同
-     * (缺席 / 空串 ⇒ `[]`,否则按 `:` 切)。逐命令的 `options.env` 由引擎自己交,它知道。
+     * env 是本类自己组合的(继承姿态 + `cfg.env`),所以说得出:读同一只组合({@link childEnv} 的**读面**,不披露、不钉 shell),切法与 core
+     * `NodeExecutionEnv` 同(缺席 / 空串 ⇒ `[]`,否则按 `:` 切)。逐命令的 `options.env` 由引擎自己交,它知道。
+     * 🔴 读面**不依赖 shell 落定**:core 判 Bash 的策略链在任何 exec 之前就读它(shell 解析在 exec 路径上才发生),所以这里不能碰
+     * {@link hostShell}(win32 上未落定同步抛 —— 修前每条 Bash 的策略链都因此被拒)。
      */
     get cdPath(): readonly string[];
     private readonly workspaceDir;
@@ -422,11 +424,16 @@ export declare class RemoteHostExecutionEnv implements RemoteExecutionEnv, Sched
      *  source of the shape rule) minus the config catalog's `secret`-typed names (`scrubServerSecrets`, 7.99.0 F7). `"all"` = full inherit (opt-out); a `string[]` = strict allowlist. Legacy `inheritProcessEnv`
      *  maps `true`→`"all"` / `false`→`[]`. */
     private inheritMode;
-    /** 每次 spawn 交给子进程的 env(组合 + 剥除披露)。 */
+    /** 每次 spawn 交给子进程的 env(组合 + 剥除披露 + win32 的 SHELL 钉)。`sh` = 调用点刚从 {@link hostShell} 读到的那只(spawn 路径
+     *  都在 `shellReady()` 之后):没有已落定的 shell 就到不了这条腿 —— 类型即次序守卫。 */
     private mergeEnv;
     /**
-     * 子进程 env 的**唯一组合**。`disclose` = 这一次是不是真要交给子进程(是 ⇒ scrub 腿经 `hostSubprocessEnv` 记剥除;否 ⇒ 只读组合,
-     * 不计数 —— {@link cdPath} 这类「子进程会拿到什么」的读者走这一臂,一次没发生的 spawn 不进剥除账)。
+     * 子进程 env 的**唯一组合**,分两层(一条律:**env 组合是纯函数,shell 只属于 spawn**):
+     *  · **组合层**(恒有)—— 继承姿态 + `cfg.env` + perCommand + win32 大小写折叠。**不碰 shell**,所以读面(如 {@link cdPath})任何时候
+     *    都能读,不依赖 shell 是否已落定。
+     *  · **spawn 层**(`spawnShell` 在场)—— 这一次是真要交给子进程:scrub 腿经 `hostSubprocessEnv` 记剥除(`spawnShell` 缺席 ⇒ 只读组合,
+     *    不计数:一次没发生的 spawn 不进剥除账),win32 上把 `SHELL` 钉到已解析的 Git Bash({@link pinHostShell},在大小写折叠**之前**)。
+     * 披露与钉同一个开关(`spawnShell`)—— 「真 spawn」只有一种说法,不再有 `disclose` 与钉各自一个布尔。
      */
     private childEnv;
     private fileError;

package/dist/plugins/remote-env-host.js

@@ -7,7 +7,7 @@ import { openSync, closeSync, readSync, statSync, truncateSync, unlinkSync, mkdi
 import { StringDecoder } from "node:string_decoder";
 import { armPipeDestroyGrace, numEnvOr, SYMLINK_CHAIN_MAX_HOPS } from "./remote-shell.js";
 import { hostBackgroundShellEnabled, hostExecSpoolEnabled } from "../config.js";
-import { resolveHostShell, hostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
+import { resolveHostShell, hostShell, pinHostShell, spawnGroupOptions, killTreeHard, killTreeSoft, hardKillGroupNow, collapseWin32EnvKeys, adoptHostForegroundChild } from "./host-platform.js";
 import { BackgroundShellManager, seedMemStream, feedMemStream, drainMemStream } from "./background-shell-support.js";
 import { FileError, NodeExecutionEnv, ExecutionError, RemoteExecutionError, RollingTailBuffer, markTruncated, SchedulerError, BackgroundShellError, } from "@sema-agent/core";
 import { allowlistedEnv, composeHostSubprocessEnv, hostSubprocessEnv } from "../server-secret-env.js";
@@ -58,7 +58,7 @@ export class RemoteHostExecutionEnv {
     cwd;
     homeDir;
     get cdPath() {
-        const value = this.childEnv(undefined, false).CDPATH;
+        const value = this.childEnv(undefined, undefined).CDPATH;
         return value === undefined || value === "" ? [] : value.split(":");
     }
     workspaceDir;
@@ -233,7 +233,7 @@ export class RemoteHostExecutionEnv {
                         const sh = hostShell();
                         child = spawn(sh.shell, [...sh.args, command], {
                             cwd: self.resolve(options?.cwd ?? self.cwd),
-                            env: self.mergeEnv(options?.env),
+                            env: self.mergeEnv(options?.env, sh),
                             ...spawnGroupOptions(),
                             stdio: ["ignore", outFh.fd, errFh.fd],
                         });
@@ -412,7 +412,7 @@ export class RemoteHostExecutionEnv {
             const sh = hostShell();
             const child = spawn(sh.shell, [...sh.args, command], {
                 cwd,
-                env: this.mergeEnv(options?.env),
+                env: this.mergeEnv(options?.env, sh),
                 ...spawnGroupOptions(),
             });
             const ticket = adoptHostForegroundChild(child);
@@ -672,7 +672,7 @@ export class RemoteHostExecutionEnv {
             try {
                 child = spawn(sh.shell, [...sh.args, command], {
                     cwd,
-                    env: this.mergeEnv(options?.env),
+                    env: this.mergeEnv(options?.env, sh),
                     ...spawnGroupOptions(),
                     stdio: ["ignore", spool.fds[0], spool.fds[1]],
                 });
@@ -814,7 +814,7 @@ export class RemoteHostExecutionEnv {
         let wake;
         const signalReady = () => { const w = wake; wake = undefined; w?.(); };
         const sh = hostShell();
-        const child = spawn(sh.shell, [...sh.args, command], { cwd, env: this.mergeEnv(options?.env), ...spawnGroupOptions() });
+        const child = spawn(sh.shell, [...sh.args, command], { cwd, env: this.mergeEnv(options?.env, sh), ...spawnGroupOptions() });
         const ticket = adoptHostForegroundChild(child);
         let pipeDestroyTimer;
         const kill = () => {
@@ -1319,10 +1319,11 @@ export class RemoteHostExecutionEnv {
             return "all";
         return "scrub";
     }
-    mergeEnv(perCommand) {
-        return this.childEnv(perCommand, true);
+    mergeEnv(perCommand, sh) {
+        return this.childEnv(perCommand, sh);
     }
-    childEnv(perCommand, disclose) {
+    childEnv(perCommand, spawnShell) {
+        const disclose = spawnShell !== undefined;
         const mode = this.inheritMode();
         let base;
         if (mode === "all")
@@ -1340,8 +1341,8 @@ export class RemoteHostExecutionEnv {
             Object.assign(base, this.cfg.env);
         if (perCommand)
             Object.assign(base, perCommand);
-        if (process.platform === "win32")
-            base.SHELL = hostShell().shell;
+        if (spawnShell)
+            pinHostShell(base, spawnShell);
         return collapseWin32EnvKeys(base);
     }
     fileError(e, p, abortSignal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.127.0",
+  "version": "7.127.1",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",