@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/host-platform.js

@@ -1,54 +1,13 @@
-/**
- * Host-lane PLATFORM seam (DESIGN-windows-native.md, FINAL r3) — the ONE place the host exec adapter's
- * POSIX/win32 differences live, so `remote-env-host.ts` stays a single code path with platform-gated leaves.
- *
- * 🔴 Iron invariant (design §4.1): the POSIX path is BYTE-IDENTICAL to the pre-Windows code — every helper is
- * `win32 ? new : exactly-what-the-inline-code-did` (same syscall, same throw behavior). Never "improve" POSIX
- * here; the existing full test suite is the regression net.
- *
- * win32 semantics (design D1-D4):
- *  - shell   = Git Bash via core 1.224 `getShellConfig` (WSL-launcher-filtered — the `System32\bash.exe`
- *              trap). Fail-LOUD when absent; never silently degrade to cmd (D1).
- *  - kill    = core 1.224 `signalProcessTree` (taskkill /T, /F for hard). Soft is a no-op for console trees
- *              (taskkill errors "can only be terminated forcefully") — the SIGTERM→grace→SIGKILL ladder is
- *              effectively delay→hard-kill on win32; accepted, CC-identical (D2).
- *  - spawn   = `detached:false` + `windowsHide:true` (no console window; no POSIX process group — the kill
- *              side uses the tree, not the group) (D3).
- *  - env     = case-insensitive key collapse before spawn (win32 env keys are case-insensitive; a `Path`+`PATH`
- *              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).
- *
- * ⚠️ 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.
- */
 import os from "node:os";
 import { getShellConfig, killProcessTree, signalProcessTree } from "@sema-agent/core";
 export const IS_WIN32 = process.platform === "win32";
-/** S1([1870] test AI 全归因,2026-07-27):POSIX 不再硬编码 `/bin/sh`——Debian/Ubuntu 的 /bin/sh 是
- *  dash,TB 实测三类病:`$'a\tb'` **静默错字节**(exit 0、输出字面 5 字节)、`[[ ]]` 127、进程替换
- *  语法错;CC 对照从不用 /bin/sh。改为与 win32 同源:core `getShellConfig()`(/bin/bash → PATH bash
- *  → `sh` 诚实兜底,core 六版逐字节稳定被 test AI 洗清)。旧「POSIX byte-identical」铁律就此**有意**
- *  打破——它防的是 Windows 改动误伤 POSIX,这次是带失分证据 + CC 对照的 POSIX 行为修正。
- *  极罕的无 bash 宿主(alpine 裸机)拿 core 的 `sh` 兜底,行为=修前。 */
 const POSIX_SH_FALLBACK = { shell: "/bin/sh", args: ["-c"] };
 let cachedWinShell;
 let cachedPosixShell;
-/**
- * Resolve the host shell ONCE per process (cached). POSIX resolves synchronously to `/bin/sh` — zero behavior
- * change. win32 defers to core's `getShellConfig` (explicit `HOST_SHELL_PATH` override → Git-for-Windows
- * install dirs → PATH `bash.exe` with the WSL-launcher filter) and THROWS a self-explaining error when no
- * usable bash exists (design D1 fail-loud: "install Git for Windows", never a silent cmd fallback).
- *
- * Call sites: `shellReady()` awaits this once (all exec/bg/stream spawns are behind it), then the spawn sites
- * read the cached value synchronously via {@link hostShell}.
- */
 export async function resolveHostShell() {
     if (!IS_WIN32) {
         if (cachedPosixShell)
             return cachedPosixShell;
-        // S1:POSIX 与 win32 同源(core getShellConfig:/bin/bash → PATH bash → sh 兜底;POSIX 分支
-        // 恒 ok——sh 兜底也是 ok 形,故这里不需要 win32 的 fail-loud 臂)。HOST_SHELL_PATH 同一覆写口。
         const posixCfg = await getShellConfig(process.env.HOST_SHELL_PATH || undefined);
         cachedPosixShell = posixCfg.ok ? { shell: posixCfg.value.shell, args: posixCfg.value.args } : POSIX_SH_FALLBACK;
         return cachedPosixShell;
@@ -65,38 +24,21 @@ export async function resolveHostShell() {
     cachedWinShell = { shell: cfg.value.shell, args: cfg.value.args };
     return cachedWinShell;
 }
-/** 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). */
 export function hostShell() {
     if (!IS_WIN32) {
-        // S1 后 POSIX 也走异步解析;未解析先到的同步读拿 sh 兜底(修前字节形)而非 throw——POSIX 的
-        // 病是 dash 语义不是缺 shell,这里降级无害且绝不把既有调用序变成崩溃。解析后即恒 bash。
         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;
 }
-/** test-only: reset the shell caches (each test can re-drive resolution). */
 export function resetHostShellCacheForTest() {
     cachedWinShell = undefined;
     cachedPosixShell = undefined;
 }
-/** Per-platform spawn options for a group-killable child (design D3).
- *  POSIX: `detached:true` — child becomes its own process-group leader (pgid === pid) so `kill(-pid)` reaps the
- *  whole group. BYTE-IDENTICAL to the previous inline `detached: true`.
- *  win32: `detached:false` (a detached child opens a console; there is no killable POSIX group either way —
- *  the kill side uses taskkill's tree) + `windowsHide:true` (no flashing console window). */
 export function spawnGroupOptions() {
     return IS_WIN32 ? { detached: false, windowsHide: true } : { detached: true };
 }
-/**
- * HARD kill of the child's whole tree (design D2). POSIX = `process.kill(-pid, "SIGKILL")` — byte-identical,
- * INCLUDING the throw on a dead group (ESRCH): every call site already wraps in its own try/catch with its own
- * fallback (e.g. `child.kill("SIGKILL")`), and that structure must not change.
- * win32 = core `signalProcessTree(pid,"SIGKILL")` → `taskkill /F /T` (never throws — fire-and-forget spawn).
- */
 export function killTreeHard(pid) {
     if (IS_WIN32) {
         signalProcessTree(pid, "SIGKILL");
@@ -104,14 +46,6 @@ export function killTreeHard(pid) {
     }
     process.kill(-pid, "SIGKILL");
 }
-/**
- * SOFT kill (design D2 — the bg KillShell/timeout-wall first rung; the caller owns the grace→hard escalation
- * timer, unchanged). POSIX = `process.kill(-pid, "SIGTERM")` byte-identical (throws on dead group — the caller
- * treats that as "already dead, skip escalation"). win32 = `taskkill /T` without /F — which for a typical
- * all-console tree ERRORS AND KILLS NOTHING: the ladder degrades to delay→hard-kill there;
- * accepted + documented (CC-identical). It never throws, so the caller's "already dead → return" branch never
- * fires on win32 — the escalation timer always arms, which is exactly what we want given soft is a no-op.
- */
 export function killTreeSoft(pid) {
     if (IS_WIN32) {
         signalProcessTree(pid, "SIGTERM");
@@ -119,40 +53,17 @@ export function killTreeSoft(pid) {
     }
     process.kill(-pid, "SIGTERM");
 }
-/** Graceful tree kill where the CALLER has no escalation timer of its own (currently unused by the host lane —
- *  exported for parity with core's surface; the bg driver keeps its own HOST_BG_KILL_GRACE_MS ladder). */
 export { killProcessTree };
-/**
- * win32 env-key case collapse (design D1). Windows env keys are case-insensitive; Node hands the
- * object to CreateProcess as-is, so a case-sensitive merge that produced BOTH `Path` (inherited) and `PATH`
- * (caller override) yields one-of-them-undefined-which in the child. Collapse case-duplicate keys LAST-WRITE-WINS
- * in iteration order — matching what `Object.assign` semantics promised the caller (per-command overrides beat
- * config env beats inherited base) — while keeping the FIRST-SEEN casing (the inherited base is assigned first,
- * so `Path=…` inherited + `PATH=x` override collapses to `Path=x`: native casing, override value).
- * POSIX: returns the input UNTOUCHED (case-sensitive env is real there — `Path` and `PATH` are distinct).
- */
 export function collapseWin32EnvKeys(env) {
     if (!IS_WIN32)
         return env;
     return collapseEnvKeysCaseInsensitive(env);
 }
-/**
- * Conventional exit-code mapping for a process killed by a signal (128 + signal number). Single pattern-home
- * construction point for every exec adapter that must turn a `close` event's external-kill case
- * (`code===null`, `signal` set) into an exit code instead of silently reporting a fake success 0 — the host
- * lane, ssh, adb, and local-docker all consume THIS function; none of them may hand-write their own signal
- * table. Uses Node's authoritative platform table (`os.constants.signals`) rather than a hand-written list —
- * a hand-written table has previously missed `SIGABRT`/`SIGPIPE` (`kill -ABRT` reported 137, impersonating
- * `SIGKILL`). Callers keep a `?? 9` fallback for a name the platform table doesn't define, matching core's
- * `SIGNUM[signal] ?? 9`.
- */
 export function signalNumber(signal) {
     return os.constants.signals[signal];
 }
-/** The platform-free collapse algorithm (exported so the mac/Linux suite can pin the win32 behavior — design
- *  D5: structural verification everywhere, behavioral bite on the Windows runner). */
 export function collapseEnvKeysCaseInsensitive(env) {
-    const canonical = new Map(); // lowercased key → first-seen casing
+    const canonical = new Map();
     const out = {};
     for (const [k, v] of Object.entries(env)) {
         if (v === undefined)
@@ -164,7 +75,7 @@ export function collapseEnvKeysCaseInsensitive(env) {
             out[k] = v;
         }
         else {
-            out[keep] = v; // later (higher-precedence) value under the first-seen casing
+            out[keep] = v;
         }
     }
     return out;