feat(core,tooling): bundle MinGit in the Windows package so exec_command always has bash (#95)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

.github/workflows/release.yml

@@ -39,6 +39,12 @@ on:
 env:
   # Bundled Node runtime version (official nodejs.org dist, aligned with engines >=24).
   NODE_RUNTIME_VERSION: v24.18.0
+  # Bundled POSIX shell for the Windows package: Git for Windows' MinGit, whose usr/bin/sh.exe
+  # IS GNU bash (installed under the name `sh`), plus ~60 coreutils and git.exe. Pinned to an
+  # exact release so the shipped bytes are reproducible and the GPLv2 source offer in
+  # THIRD-PARTY-NOTICES.md names one version. Bump deliberately, not automatically.
+  MINGIT_VERSION: 2.55.0.3
+  MINGIT_TAG: v2.55.0.windows.3
 
 jobs:
   # Skip the build/upload when the tag's Release already exists (immutable releases forbid
@@ -161,6 +167,13 @@ jobs:
       # to the sibling web\, prefer the bundled node\node.exe, fall back to system node).
       # install.ps1 verifies and unpacks this zip; in PowerShell the .ps1 shim wins over .cmd,
       # in cmd.exe only the .cmd is found — both forward all args and the exit code.
+      #
+      # It also bundles MinGit under git\, so exec_command has a POSIX shell even on a machine
+      # with no Git for Windows: the shims advertise git\usr\bin\sh.exe as PENGUIN_BUNDLED_SHELL
+      # and the resolver (core's shell.ts) uses it only when the user has no bash of their own.
+      # MinGit is unpacked with its tree intact — MSYS binaries locate /etc relative to the
+      # directory holding msys-2.0.dll, so `sh -lc` finds git\etc\profile and gets the usual
+      # /mingw64/bin:/usr/bin:<inherited Windows PATH>, keeping System32's curl/tar reachable.
       - name: Package win-x64 zip
         run: |
           name="node-$NODE_RUNTIME_VERSION-win-x64"
@@ -169,12 +182,22 @@ jobs:
           mkdir -p /tmp/node-runtime
           unzip -q "/tmp/$name.zip" -d /tmp/node-runtime
           mv "/tmp/node-runtime/$name" out/penguin/node
+          # MinGit unzips flat (no top-level directory), so give it its own destination.
+          mingit="MinGit-$MINGIT_VERSION-64-bit.zip"
+          curl -fsSL "https://github.com/git-for-windows/git/releases/download/$MINGIT_TAG/$mingit" -o "/tmp/$mingit"
+          rm -rf out/penguin/git
+          mkdir -p out/penguin/git
+          unzip -q "/tmp/$mingit" -d out/penguin/git
+          # Fail loudly here rather than shipping a package whose shell silently does not exist.
+          test -f out/penguin/git/usr/bin/sh.exe
+          test -f out/penguin/git/etc/profile
           rm -f out/penguin/bin/penguin
           cat > out/penguin/bin/penguin.cmd <<'EOF'
           @echo off
           setlocal
           set "DIR=%~dp0.."
           if not defined PENGUIN_WEB_DIST set "PENGUIN_WEB_DIST=%DIR%\web"
+          if exist "%DIR%\git\usr\bin\sh.exe" set "PENGUIN_BUNDLED_SHELL=%DIR%\git\usr\bin\sh.exe"
           if exist "%DIR%\node\node.exe" (
             "%DIR%\node\node.exe" "%DIR%\lib\dist\index.js" %*
           ) else (
@@ -187,6 +210,8 @@ jobs:
           cat > out/penguin/bin/penguin.ps1 <<'EOF'
           $dir = Split-Path -Parent $PSScriptRoot
           if (-not $env:PENGUIN_WEB_DIST) { $env:PENGUIN_WEB_DIST = Join-Path $dir "web" }
+          $sh = Join-Path $dir "git\usr\bin\sh.exe"
+          if (Test-Path $sh) { $env:PENGUIN_BUNDLED_SHELL = $sh }
           $node = Join-Path $dir "node\node.exe"
           if (-not (Test-Path $node)) { $node = "node" }
           & $node (Join-Path $dir "lib\dist\index.js") @args

THIRD-PARTY-NOTICES.md

@@ -0,0 +1,47 @@
+# Third-party notices
+
+PenguinHarness itself is licensed under Apache-2.0 (see [LICENSE](LICENSE)). Some **distributed
+release artifacts** additionally bundle third-party programs, which keep their own licenses. This
+file records those, and how to obtain their source.
+
+Nothing listed here is part of this repository — the components are downloaded by the release
+workflow (`.github/workflows/release.yml`) and placed alongside the application inside the
+release archives. Installing from npm (`@prismshadow/penguin-cli`) bundles none of them.
+
+## Node.js runtime — `node/`
+
+Present in every archive except `penguin-universal.tar.gz`. Downloaded unmodified from the
+official distribution at <https://nodejs.org/dist/>. Node.js is MIT-licensed with additional
+notices for its dependencies; the full text ships inside the bundle
+(`node/LICENSE`, and on Windows `node/LICENSE`).
+
+Source: <https://github.com/nodejs/node> — the tag matching the bundled version, which is pinned
+as `NODE_RUNTIME_VERSION` in the release workflow.
+
+## MinGit (Git for Windows) — `git/`
+
+Present in `penguin-win32-x64.zip` only.
+
+The Windows package bundles **MinGit**, the minimal redistributable build of Git for Windows,
+unmodified, as published by the Git for Windows project. It supplies the POSIX shell that the
+agent's `exec_command` runs (`git/usr/bin/sh.exe`, which is GNU bash), roughly sixty core
+utilities, and `git.exe`. It is used only when the machine has no Git for Windows installation of
+its own; a user-installed one always takes precedence.
+
+**License: GNU General Public License version 2** (with the additional per-component licenses
+that Git for Windows ships). The complete license texts are included inside the bundle at
+`git/LICENSE.txt` and `git/mingw64/share/licenses/`.
+
+Version bundled: the release attached to the Git for Windows tag pinned as `MINGIT_TAG` in the
+release workflow.
+
+**Written offer / source availability.** The complete corresponding source code for the bundled
+MinGit is published by the Git for Windows project at:
+
+- <https://github.com/git-for-windows/git> — repository, tagged per release
+- <https://github.com/git-for-windows/git/releases> — release assets, including the source
+  archives for each tag
+
+The bundled binaries are byte-identical to the `MinGit-<version>-64-bit.zip` asset of that tag;
+no patches are applied. If you need the corresponding source and cannot obtain it from the URLs
+above, open an issue on this repository and we will provide it.

install.ps1

@@ -10,7 +10,7 @@
 # `npm install -g @prismshadow/penguin-cli` instead.
 #
 # The data dir (%USERPROFILE%\.penguin\data) sits under the install home but is never touched by
-# reinstall/upgrade (which only replace bin/lib/web/node). Upgrading = re-running this installer.
+# reinstall/upgrade (which only replace bin/lib/web/node/git). Upgrading = re-running this installer.
 #
 # Docs: https://penguin.ooo/docs/installation
 param(
@@ -112,7 +112,7 @@ try {
   if (-not (Test-Path $NewRoot)) { Fail "unexpected archive layout: top-level penguin\ missing." }
   if (-not (Test-Path (Join-Path $NewRoot "bin"))) { Fail "unexpected archive layout: penguin\bin missing." }
 
-  $Dirs = @("bin", "lib", "web", "node")
+  $Dirs = @("bin", "lib", "web", "node", "git")
   $Moved = @()
   New-Item -ItemType Directory -Path $OldDir | Out-Null
   try {
@@ -153,6 +153,7 @@ if (-not (Test-Path $CmdShim)) {
     'setlocal'
     'set "DIR=%~dp0.."'
     'if not defined PENGUIN_WEB_DIST set "PENGUIN_WEB_DIST=%DIR%\web"'
+    'if exist "%DIR%\git\usr\bin\sh.exe" set "PENGUIN_BUNDLED_SHELL=%DIR%\git\usr\bin\sh.exe"'
     'if exist "%DIR%\node\node.exe" ('
     '  "%DIR%\node\node.exe" "%DIR%\lib\dist\index.js" %*'
     ') else ('
@@ -166,6 +167,8 @@ if (-not (Test-Path $Ps1Shim)) {
   @(
     '$dir = Split-Path -Parent $PSScriptRoot'
     'if (-not $env:PENGUIN_WEB_DIST) { $env:PENGUIN_WEB_DIST = Join-Path $dir "web" }'
+    '$sh = Join-Path $dir "git\usr\bin\sh.exe"'
+    'if (Test-Path $sh) { $env:PENGUIN_BUNDLED_SHELL = $sh }'
     '$node = Join-Path $dir "node\node.exe"'
     'if (-not (Test-Path $node)) { $node = "node" }'
     '& $node (Join-Path $dir "lib\dist\index.js") @args'

packages/core/src/environment/tools/command/shell.ts

@@ -7,22 +7,37 @@
  * 1. `PENGUIN_SHELL` (explicit executable name or path) always wins, on every platform;
  *    the argument shape is inferred from its basename (see below).
  * 2. Otherwise, non-Windows uses `bash -lc` (today's behavior, bit for bit).
- * 3. On Windows, probe PATH for `bash` (Git for Windows — best compatibility with the
- *    skill/prompt ecosystem, which is written for a POSIX shell), then `pwsh`
- *    (PowerShell 7+), then fall back to `powershell` (Windows PowerShell 5.1, always
- *    present). A `bash` that resolves into the Windows system directory is ignored: that
- *    is the WSL launcher, which runs commands inside a Linux distro with a different
- *    filesystem view (and fails outright when no distro is configured).
+ * 3. On Windows, probe PATH for `bash` (a full Git for Windows install — best compatibility
+ *    with the skill/prompt ecosystem, which is written for a POSIX shell). A `bash` that
+ *    resolves into the Windows system directory is ignored: that is the WSL launcher, which
+ *    runs commands inside a Linux distro with a different filesystem view (and fails outright
+ *    when no distro is configured).
+ * 4. Then `PENGUIN_BUNDLED_SHELL` — the MinGit bash the Windows package ships (see the
+ *    release workflow), advertised by the launcher shims as an absolute path. It comes
+ *    *after* the PATH probe on purpose: a user's own Git for Windows carries the full MSYS
+ *    userland (curl, tar, less, perl …), while MinGit carries ~60 core tools, so when both
+ *    exist theirs is the better shell. This step is what makes the shell deterministic —
+ *    without it, the same Agent and the same Skill behave differently on two Windows
+ *    machines depending on what happens to be installed.
+ * 5. Only then `pwsh` (PowerShell 7+), and finally `powershell` (Windows PowerShell 5.1,
+ *    always present). These remain reachable for npm installs, which ship no bundle.
  *
  * Argument shapes by basename (also applied to `PENGUIN_SHELL` values):
  * - `pwsh` / `powershell` -> `-NoLogo -NoProfile -Command <cmd>`
  * - `cmd`                 -> `/d /s /c <cmd>`
  * - anything else         -> `-lc <cmd>` (bash/zsh/sh-style login shell)
  *
+ * `-lc` matters for the bundled shell: as a login shell it sources MinGit's `etc/profile`,
+ * which defaults to `MSYS2_PATH_TYPE=inherit` and yields
+ * `/mingw64/bin:/usr/local/bin:/usr/bin:/bin:<inherited Windows PATH>` — the bundled coreutils
+ * and git first, the inherited Windows PATH still behind them, so System32's `curl.exe` and
+ * `tar.exe` (which MinGit does not carry) keep resolving. Nothing has to plumb PATH by hand.
+ *
  * The resolved shell's name is surfaced to the model via the session environment (the
  * `Shell:` line in the system prompt), so it knows which syntax the exec tool speaks.
  */
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import path from "node:path";
 
 /** A resolved shell invocation: `spawn(command, [...args, cmd])` runs `cmd` in that shell. */
@@ -43,6 +58,8 @@ export interface ResolveShellOptions {
   whichAll?: (cmd: string) => string[];
   /** The Windows system root (to recognize the WSL bash launcher); default `env.SystemRoot` or C:\Windows. */
   systemRoot?: string;
+  /** Existence probe for the bundled shell path (injected in tests); default `fs.existsSync`. */
+  exists?: (filePath: string) => boolean;
 }
 
 /** Basename without a trailing .exe/.cmd/.bat/.ps1 extension, lowercased ("C:\...\pwsh.EXE" -> "pwsh"). */
@@ -98,6 +115,7 @@ export function resolveShell(opts: ResolveShellOptions = {}): ShellInvocation {
   }
 
   const whichAll = opts.whichAll ?? defaultWhichAll;
+  const exists = opts.exists ?? existsSync;
   const systemRoot = opts.systemRoot ?? env.SystemRoot ?? "C:\\Windows";
   // The WSL launcher lives in <SystemRoot>\System32 (or Sysnative under WOW64); a Git for
   // Windows bash lives under the Git install dir. Only the first PATH match counts — that
@@ -106,6 +124,13 @@ export function resolveShell(opts: ResolveShellOptions = {}): ShellInvocation {
   if (bash && !bash.toLowerCase().startsWith(systemRoot.toLowerCase() + path.win32.sep)) {
     return { command: "bash", args: ["-lc"], name: "bash" };
   }
+  // The bundled MinGit bash (installed-package layout only; absent for npm installs). Reported
+  // to the model as "bash" rather than its filename: MinGit installs GNU bash under the name
+  // `sh`, and the Skill ecosystem targets bash, so "sh" would understate what it can run.
+  const bundled = env.PENGUIN_BUNDLED_SHELL?.trim();
+  if (bundled && exists(bundled)) {
+    return { command: bundled, args: ["-lc"], name: "bash" };
+  }
   if (whichAll("pwsh").length > 0) {
     return { command: "pwsh", args: argsForShell("pwsh"), name: "pwsh" };
   }

packages/core/test/shell-resolver.test.ts

@@ -110,3 +110,79 @@ describe("resolveShell — PENGUIN_SHELL override", () => {
     expect(shell).toEqual({ command: "bash", args: ["-lc"], name: "bash" });
   });
 });
+
+describe("resolveShell — the bundled MinGit bash (PENGUIN_BUNDLED_SHELL)", () => {
+  const BUNDLED = "C:\\Users\\u\\.penguin\\git\\usr\\bin\\sh.exe";
+  /** An exists() stub answering true only for the bundled path. */
+  const bundledExists = (p: string) => p === BUNDLED;
+
+  it("is used when the machine has no bash of its own, and reports itself as bash", () => {
+    // MinGit installs GNU bash under the name `sh`; the model is told "bash" because that is
+    // what it is and what the Skill ecosystem targets — "sh" would understate it.
+    const shell = resolveShell({
+      platform: "win32",
+      env: { PENGUIN_BUNDLED_SHELL: BUNDLED },
+      whichAll: which({ pwsh: ["C:\\pwsh.exe"] }),
+      exists: bundledExists,
+    });
+    expect(shell).toEqual({ command: BUNDLED, args: ["-lc"], name: "bash" });
+  });
+
+  it("yields to a real Git for Windows on PATH (its MSYS userland is the fuller one)", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: { PENGUIN_BUNDLED_SHELL: BUNDLED },
+      whichAll: which({ bash: ["C:\\Program Files\\Git\\bin\\bash.exe"] }),
+      exists: bundledExists,
+    });
+    expect(shell).toEqual({ command: "bash", args: ["-lc"], name: "bash" });
+  });
+
+  it("beats pwsh and powershell — the point of bundling is that neither is reached", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: { PENGUIN_BUNDLED_SHELL: BUNDLED },
+      whichAll: which({ pwsh: ["C:\\pwsh.exe"], powershell: ["C:\\powershell.exe"] }),
+      exists: bundledExists,
+    });
+    expect(shell.command).toBe(BUNDLED);
+  });
+
+  it("still loses to an explicit PENGUIN_SHELL", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: { PENGUIN_SHELL: "pwsh", PENGUIN_BUNDLED_SHELL: BUNDLED },
+      exists: bundledExists,
+    });
+    expect(shell).toEqual({ command: "pwsh", args: POWERSHELL_ARGS, name: "pwsh" });
+  });
+
+  it("a stale path (dir deleted) falls through to pwsh rather than spawning a missing exe", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: { PENGUIN_BUNDLED_SHELL: BUNDLED },
+      whichAll: which({ pwsh: ["C:\\pwsh.exe"] }),
+      exists: () => false,
+    });
+    expect(shell).toEqual({ command: "pwsh", args: POWERSHELL_ARGS, name: "pwsh" });
+  });
+
+  it("is ignored on POSIX (npm installs and source checkouts never set it anyway)", () => {
+    const shell = resolveShell({
+      platform: "linux",
+      env: { PENGUIN_BUNDLED_SHELL: BUNDLED },
+      exists: bundledExists,
+    });
+    expect(shell).toEqual({ command: "bash", args: ["-lc"], name: "bash" });
+  });
+
+  it("a blank value is ignored (unset-but-defined shims must not win)", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: { PENGUIN_BUNDLED_SHELL: "  " },
+      whichAll: which({ powershell: ["C:\\powershell.exe"] }),
+      exists: () => true,
+    });
+    expect(shell.name).toBe("powershell");
+  });
+});

packages/docs/content/installation.en.md

@@ -59,7 +59,7 @@ Script flags go after `sh -s --`, e.g. `curl -fsSL https://penguin.ooo/install.s
 | Integrity check | Downloads are sha256-verified when the Release ships checksum assets |
 | Upgrade | Re-run the installer; it swaps `bin`/`lib`/`web`/`node` and never touches `data` |
 
-- **Agent shell**: on Windows, the agent's `exec_command` prefers Git-Bash (`bash` on PATH, e.g. from [Git for Windows](https://gitforwindows.org/)) for the best compatibility with skills written for a POSIX shell, and falls back to PowerShell (`pwsh`, then `powershell`) when bash is absent. The `PENGUIN_SHELL` env var overrides the pick; the session's system prompt tells the model which shell is active.
+- **Agent shell**: on Windows, the agent's `exec_command` runs in a POSIX shell, for compatibility with skills written for one. It picks, in order: `bash` on PATH (your own [Git for Windows](https://gitforwindows.org/), preferred because it carries the full MSYS userland); then the **bundled bash** — the Windows zip ships MinGit under `git\`, so a machine with no Git for Windows still gets a POSIX shell, about sixty core utilities and `git.exe`; then PowerShell (`pwsh`, then `powershell`). The PowerShell fallback is only reached by npm installs, which bundle nothing. The `PENGUIN_SHELL` env var overrides the pick; the session's system prompt tells the model which shell is active. The bundled shell's licensing is recorded in [THIRD-PARTY-NOTICES.md](https://github.com/Prism-Shadow/penguin-harness/blob/main/THIRD-PARTY-NOTICES.md).
 - **Ctrl-C semantics**: on Windows, sending Ctrl-C to a running command session (`input_command` with `"\u0003"`) terminates the whole command session tree instead of interrupting the foreground command — Windows cannot deliver a console Ctrl-C to a piped child process, so the interrupt degrades to a hard tree kill.
 - **In-place update**: `penguin update` is not yet supported on Windows — upgrade by re-running the installer above.
 - **Config file permissions**: on POSIX, config/credential files are written with `0600` (owner-only) permissions; Windows has no such mode bits, so files fall under your profile's default NTFS ACLs.

packages/docs/content/installation.zh.md

@@ -59,7 +59,7 @@ penguin -v
 | 完整性校验 | Release 提供 checksum 资产时自动进行 sha256 校验 |
 | 升级 | 重新运行安装器；只替换 `bin`/`lib`/`web`/`node`，绝不触碰 `data` |
 
-- **Agent shell**：Windows 上 `exec_command` 优先使用 Git-Bash（PATH 上的 `bash`，如 [Git for Windows](https://gitforwindows.org/)），与面向 POSIX shell 编写的技能生态兼容性最好；没有 bash 时回退到 PowerShell（先 `pwsh` 后 `powershell`）。环境变量 `PENGUIN_SHELL` 可强制指定；会话的系统提示词会告知模型当前 shell。
+- **Agent shell**：Windows 上 `exec_command` 在 POSIX shell 中执行，以兼容面向 POSIX 编写的技能生态。选择顺序为：PATH 上的 `bash`（你自己安装的 [Git for Windows](https://gitforwindows.org/)，优先，因为它带完整的 MSYS 工具集）；其次是**内置 bash**——Windows zip 在 `git\` 下自带 MinGit，因此未安装 Git for Windows 的机器同样有 POSIX shell、约六十个核心工具和 `git.exe`；最后才是 PowerShell（先 `pwsh` 后 `powershell`）。只有经 npm 安装（不含内置包）才会走到 PowerShell。环境变量 `PENGUIN_SHELL` 可强制指定；会话的系统提示词会告知模型当前 shell。内置 shell 的许可信息见 [THIRD-PARTY-NOTICES.md](https://github.com/Prism-Shadow/penguin-harness/blob/main/THIRD-PARTY-NOTICES.md)。
 - **Ctrl-C 语义**：Windows 上向运行中的命令会话发送 Ctrl-C（`input_command` 传 `"\u0003"`）会终止整棵命令会话进程树，而不是中断前台命令——Windows 无法向管道子进程投递控制台 Ctrl-C，中断因此退化为整树强杀。
 - **就地更新**：`penguin update` 暂不支持 Windows——升级请重新运行上面的安装器。
 - **配置文件权限**：POSIX 上配置/凭据文件以 `0600`（仅属主可读写）写入；Windows 没有对应的权限位，文件遵循你用户目录的默认 NTFS ACL。