feat(core,tooling): Windows support — shell selection, install.ps1, win-x64 release package, Windows CI (#79)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

packages/cli/package.json

@@ -19,7 +19,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
     "build": "tsup",
-    "penguin": "PENGUIN_HOME=\"${PENGUIN_HOME:-$HOME/.penguin/dev-data}\" tsx src/index.ts"
+    "penguin": "node ../../scripts/run-with-env.mjs PENGUIN_HOME=~/.penguin/dev-data -- tsx src/index.ts"
   },
   "dependencies": {
     "@prismshadow/agenthub": "^0.4.1",

packages/cli/src/commands/config.ts

@@ -325,6 +325,13 @@ export function registerConfigCommand(program: Command, t: Messages): void {
         process.exitCode = 1;
         return;
       }
+      // Windows has no POSIX shell startup file to write and no /bin shell to restart into;
+      // refuse with a clear pointer instead of an ENOENT from spawning /bin/zsh.
+      if (process.platform === "win32") {
+        process.stderr.write(`${getMessages(lang).langWindowsUnsupported(lang)}\n`);
+        process.exitCode = 1;
+        return;
+      }
       const { rcPath } = await applyLanguageToRc(lang, {
         shell: process.env.SHELL,
         home: homedir(),

packages/cli/src/i18n.ts

@@ -176,6 +176,8 @@ export interface Messages {
   /** Example resume command shown when the REPL exits (dim print; only when this session has a resumable record). */
   resumeHint(command: string): string;
   langInvalid(value: string): string;
+  /** `config lang` persists via POSIX shell startup files; on Windows it refuses with a pointer to a user env var instead. */
+  langWindowsUnsupported(lang: string): string;
   langSet(lang: string, rcPath: string): string;
   langRestartConfirm(): string;
   langRestart(): string;
@@ -383,6 +385,9 @@ const en: Messages = {
     `[resumed] ${sessionId} · ${messageCount} message${messageCount === 1 ? "" : "s"} in the current context`,
   resumeHint: (command) => `To continue this conversation: ${command}`,
   langInvalid: (value) => `Invalid language "${value}". Use en or zh.`,
+  langWindowsUnsupported: (lang) =>
+    `penguin config lang persists via POSIX shell startup files, which Windows does not have.\n` +
+    `Set the user environment variable instead: setx PENGUIN_LANG ${lang} (new terminals pick it up).`,
   langSet: (lang, rcPath) => `Language set to ${lang}; wrote PENGUIN_LANG to ${rcPath}.`,
   langRestartConfirm: () => "Open a new shell now to apply? [y/N] ",
   langRestart: () => "Opening a new shell with the new language (type exit to return)…",
@@ -550,6 +555,9 @@ const zh: Messages = {
     `[已恢复] ${sessionId} · 当前上下文共 ${messageCount} 条消息`,
   resumeHint: (command) => `继续本次对话：${command}`,
   langInvalid: (value) => `无效的语言 "${value}"。请使用 en 或 zh。`,
+  langWindowsUnsupported: (lang) =>
+    `penguin config lang 通过 POSIX shell 启动文件持久化语言，Windows 上没有对应机制。\n` +
+    `请改为设置用户环境变量：setx PENGUIN_LANG ${lang}（新终端生效）。`,
   langSet: (lang, rcPath) => `语言已设为 ${lang}；已将 PENGUIN_LANG 写入 ${rcPath}。`,
   langRestartConfirm: () => "现在打开新 shell 使其生效？[y/N] ",
   langRestart: () => "正在打开使用新语言的新 shell（输入 exit 可返回）……",

packages/cli/test/config-model.test.ts

@@ -97,7 +97,10 @@ describe("penguin config model add/list (--root plus provider / model_id stored
 
     const file = projectConfigPath(tmpRoot, DEFAULT_PROJECT_ID);
     expect(path.basename(file)).toBe(".project_config.toml");
-    expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    // POSIX-only: Windows has no owner-only mode bits (chmod maps to the read-only attribute).
+    if (process.platform !== "win32") {
+      expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    }
     const parsed = parseToml(await fs.readFile(file, "utf8")) as {
       models: Array<Record<string, unknown>>;
     };

packages/cli/test/config-vault.test.ts

@@ -64,7 +64,10 @@ describe("penguin config vault", () => {
 
     const file = agentVaultPath(tmpRoot, DEFAULT_PROJECT_ID, "default_agent");
     expect(path.basename(file)).toBe(".vault.toml");
-    expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    // POSIX-only: Windows has no owner-only mode bits (chmod maps to the read-only attribute).
+    if (process.platform !== "win32") {
+      expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    }
     expect(await fs.readFile(file, "utf8")).toContain("vault-secret-9876");
 
     const list = await runVault(["list"]);

packages/cli/test/lang-config.test.ts

@@ -5,26 +5,29 @@ import { afterEach, describe, expect, it } from "vitest";
 import { applyLanguageToRc, resolveShellRc, upsertBlock } from "../src/lang-config.js";
 
 describe("resolveShellRc", () => {
+  // rcPath is built with path.join, so the expectations join too (backslashes on Windows —
+  // where the `config lang` command refuses before ever calling this, but the pure function
+  // stays coherent).
   it("maps zsh / bash / fish to their startup files and syntax", () => {
     const zsh = resolveShellRc("/bin/zsh", "/home/u");
     expect(zsh.kind).toBe("zsh");
-    expect(zsh.rcPath).toBe("/home/u/.zshrc");
+    expect(zsh.rcPath).toBe(join("/home/u", ".zshrc"));
     expect(zsh.body("zh")).toBe("export PENGUIN_LANG=zh");
 
     const bash = resolveShellRc("/usr/bin/bash", "/home/u");
     expect(bash.kind).toBe("bash");
-    expect(bash.rcPath).toBe("/home/u/.bashrc");
+    expect(bash.rcPath).toBe(join("/home/u", ".bashrc"));
 
     const fish = resolveShellRc("/usr/local/bin/fish", "/home/u");
     expect(fish.kind).toBe("fish");
-    expect(fish.rcPath).toBe("/home/u/.config/fish/config.fish");
+    expect(fish.rcPath).toBe(join("/home/u", ".config", "fish", "config.fish"));
     expect(fish.body("en")).toBe("set -gx PENGUIN_LANG en");
   });
 
   it("falls back to ~/.profile for an unknown shell", () => {
     const rc = resolveShellRc(undefined, "/home/u");
     expect(rc.kind).toBe("unknown");
-    expect(rc.rcPath).toBe("/home/u/.profile");
+    expect(rc.rcPath).toBe(join("/home/u", ".profile"));
   });
 });
 

packages/cli/test/update.test.ts

@@ -22,58 +22,64 @@ import {
 } from "../src/commands/update.js";
 import { getMessages } from "../src/i18n.js";
 
-describe("detectInstall (how this CLI was installed, from its own real path)", () => {
-  it("tarball: <installDir>/lib/dist/index.js, the layout install.sh unpacks", () => {
-    expect(detectInstall("/home/me/.penguin/lib/dist/index.js")).toEqual({
-      kind: "tarball",
-      installDir: "/home/me/.penguin",
+// POSIX-only: the fixtures are POSIX install layouts and detectInstall normalizes through
+// path.* (backslashes on Windows) — where in-place `penguin update` is refused anyway
+// (the documented Windows upgrade path is re-running install.ps1).
+describe.skipIf(process.platform === "win32")(
+  "detectInstall (how this CLI was installed, from its own real path)",
+  () => {
+    it("tarball: <installDir>/lib/dist/index.js, the layout install.sh unpacks", () => {
+      expect(detectInstall("/home/me/.penguin/lib/dist/index.js")).toEqual({
+        kind: "tarball",
+        installDir: "/home/me/.penguin",
+      });
     });
-  });
 
-  it("tarball: a non-default PENGUIN_INSTALL_DIR is read off the path, not the environment", () => {
-    expect(detectInstall("/opt/tools/penguin/lib/dist/index.js")).toEqual({
-      kind: "tarball",
-      installDir: "/opt/tools/penguin",
+    it("tarball: a non-default PENGUIN_INSTALL_DIR is read off the path, not the environment", () => {
+      expect(detectInstall("/opt/tools/penguin/lib/dist/index.js")).toEqual({
+        kind: "tarball",
+        installDir: "/opt/tools/penguin",
+      });
     });
-  });
 
-  it("npm global: npm's own prefix layout", () => {
-    expect(
-      detectInstall("/usr/local/lib/node_modules/@prismshadow/penguin-cli/dist/index.js"),
-    ).toEqual({ kind: "npm", globalRoot: "/usr/local/lib/node_modules" });
-  });
-
-  it("npm global: pnpm's global store, through the .pnpm virtual dir", () => {
-    const p =
-      "/home/me/.local/share/pnpm/global/5/node_modules/.pnpm/@prismshadow+penguin-cli@0.1.1/node_modules/@prismshadow/penguin-cli/dist/index.js";
-    const info = detectInstall(p);
-    expect(info.kind).toBe("npm");
-    expect(info.globalRoot).toContain(".pnpm");
-  });
-
-  it("source checkout: the built dist inside the monorepo", () => {
-    expect(detectInstall("/home/me/code/penguin-harness/packages/cli/dist/index.js")).toEqual({
-      kind: "source",
+    it("npm global: npm's own prefix layout", () => {
+      expect(
+        detectInstall("/usr/local/lib/node_modules/@prismshadow/penguin-cli/dist/index.js"),
+      ).toEqual({ kind: "npm", globalRoot: "/usr/local/lib/node_modules" });
     });
-  });
 
-  it("source checkout: tsx running src directly", () => {
-    expect(detectInstall("/home/me/code/penguin-harness/packages/cli/src/index.ts")).toEqual({
-      kind: "source",
+    it("npm global: pnpm's global store, through the .pnpm virtual dir", () => {
+      const p =
+        "/home/me/.local/share/pnpm/global/5/node_modules/.pnpm/@prismshadow+penguin-cli@0.1.1/node_modules/@prismshadow/penguin-cli/dist/index.js";
+      const info = detectInstall(p);
+      expect(info.kind).toBe("npm");
+      expect(info.globalRoot).toContain(".pnpm");
     });
-  });
 
-  it("a checkout wins over the tarball shape, so a repo under a lib/ dir is never mistaken for an install", () => {
-    expect(detectInstall("/srv/lib/penguin-harness/packages/cli/dist/index.js")).toEqual({
-      kind: "source",
+    it("source checkout: the built dist inside the monorepo", () => {
+      expect(detectInstall("/home/me/code/penguin-harness/packages/cli/dist/index.js")).toEqual({
+        kind: "source",
+      });
     });
-  });
 
-  it("anything else is unknown rather than guessed", () => {
-    expect(detectInstall("/random/place/index.js").kind).toBe("unknown");
-    expect(detectInstall("/home/me/.penguin/bin/penguin").kind).toBe("unknown");
-  });
-});
+    it("source checkout: tsx running src directly", () => {
+      expect(detectInstall("/home/me/code/penguin-harness/packages/cli/src/index.ts")).toEqual({
+        kind: "source",
+      });
+    });
+
+    it("a checkout wins over the tarball shape, so a repo under a lib/ dir is never mistaken for an install", () => {
+      expect(detectInstall("/srv/lib/penguin-harness/packages/cli/dist/index.js")).toEqual({
+        kind: "source",
+      });
+    });
+
+    it("anything else is unknown rather than guessed", () => {
+      expect(detectInstall("/random/place/index.js").kind).toBe("unknown");
+      expect(detectInstall("/home/me/.penguin/bin/penguin").kind).toBe("unknown");
+    });
+  },
+);
 
 describe("detectPackageManager (which manager owns a global node_modules root)", () => {
   it("pnpm: the global store or the .pnpm virtual dir", () => {

packages/core/package.json

@@ -36,7 +36,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
-    "test:e2e": "PENGUIN_E2E=1 vitest run test/llm.e2e.test.ts",
+    "test:e2e": "node ../../scripts/run-with-env.mjs PENGUIN_E2E=1 -- vitest run test/llm.e2e.test.ts",
     "build": "tsup"
   },
   "dependencies": {

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

@@ -4,6 +4,8 @@
 export { CommandSessionManager } from "./session-manager.js";
 export { ManagedSession, resultForExit } from "./session.js";
 export type { ProcessExit, SpawnOptions } from "./session.js";
+export { resolveShell, sessionShell } from "./shell.js";
+export type { ShellInvocation, ResolveShellOptions } from "./shell.js";
 export {
   DEFAULT_EXEC_YIELD_MS,
   DEFAULT_WRITE_YIELD_MS,

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

@@ -1,11 +1,14 @@
 /**
  * ManagedSession — runtime state and collection logic for a single command session.
  *
- * Spawns the process with `bash -lc <cmd>`, with stdout/stderr going through plain pipes (no
+ * Spawns the process with `bash -lc <cmd>` (on Windows, the shell picked by `sessionShell()`
+ * — see shell.ts), with stdout/stderr going through plain pipes (no
  * native dependency, clean output; an interactive program that detects no TTY falls back to
  * non-interactive mode, which parses more cleanly for the Agent anyway). `detached` makes the
  * child process the process-group leader, so both Ctrl-C and killing the whole group rely on
  * **process-group signals** (sending a signal to `-pid` also reaches background child processes).
+ * Windows has neither process groups nor real signals: every "signal" degrades to a hard
+ * TerminateProcess, and tree-wide cleanup goes through `taskkill /t` instead (see signalGroup).
  *
  * Key semantics:
  * - **Termination is determined by the foreground process exiting (the exit event, waitpid
@@ -22,9 +25,10 @@
  * - `kill()` sends SIGTERM to the process group, then SIGKILL after a grace period, reaping any
  *   leftover background child processes; idempotent.
  */
-import { spawn, type ChildProcess } from "node:child_process";
+import { spawn, spawnSync, type ChildProcess } from "node:child_process";
 import type { ToolResult } from "../types.js";
 import { CappedTextBuffer, WakeSignal } from "../background/index.js";
+import { sessionShell } from "./shell.js";
 
 /** Process-group semantics are available on POSIX; Windows falls back to signaling the child process directly. */
 const SUPPORTS_PROCESS_GROUP = process.platform !== "win32";
@@ -48,7 +52,7 @@ export interface ProcessExit {
 
 /** Arguments required to start a command. */
 export interface SpawnOptions {
-  /** Command string handed to `bash -lc`. */
+  /** Command string handed to the session shell (`bash -lc` on POSIX; see shell.ts for Windows). */
   cmd: string;
   /** Working directory (absolute path). */
   cwd: string;
@@ -71,11 +75,13 @@ export class ManagedSession {
   private readonly wakeSignal = new WakeSignal();
 
   constructor(opts: SpawnOptions) {
-    this.child = spawn("bash", ["-lc", opts.cmd], {
+    const shell = sessionShell();
+    this.child = spawn(shell.command, [...shell.args, opts.cmd], {
       cwd: opts.cwd,
       env: opts.env,
       detached: SUPPORTS_PROCESS_GROUP, // Become the process-group leader, so the whole group can be signaled
       stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true, // No flashing console window on Windows (ignored elsewhere)
     });
     this.child.stdout?.setEncoding("utf8");
     this.child.stderr?.setEncoding("utf8");
@@ -92,11 +98,26 @@ export class ManagedSession {
     this.child.on("error", (err) => this.handleError(err));
   }
 
-  /** Signals the process group; ignores the case where the process/group has already exited (ESRCH). */
-  private signalGroup(sig: NodeJS.Signals): void {
+  /**
+   * Signals the process group; ignores the case where the process/group has already exited (ESRCH).
+   *
+   * Windows has no signals: `child.kill()` is an unconditional TerminateProcess of the direct
+   * child only, which would orphan grandchildren (a `node server.js` started by the shell).
+   * Every signal therefore becomes a hard kill of the whole tree via `taskkill /t /f` — including
+   * SIGINT: without a shared console there is no way to deliver a real Ctrl-C to a piped child,
+   * so input_command's Ctrl-C degrades to this hard kill on Windows. `sync` uses spawnSync for
+   * the process-'exit' fallback, where the event loop is no longer running.
+   */
+  private signalGroup(sig: NodeJS.Signals, sync = false): void {
     try {
       if (SUPPORTS_PROCESS_GROUP && typeof this.child.pid === "number" && this.child.pid > 0) {
         process.kill(-this.child.pid, sig); // Negative pid = the whole process group
+      } else if (
+        process.platform === "win32" &&
+        typeof this.child.pid === "number" &&
+        this.child.pid > 0
+      ) {
+        this.killTreeWindows(this.child.pid, sync);
       } else {
         this.child.kill(sig);
       }
@@ -105,6 +126,26 @@ export class ManagedSession {
     }
   }
 
+  /** Hard-kills the whole process tree on Windows; falls back to child.kill() if taskkill itself fails. */
+  private killTreeWindows(pid: number, sync: boolean): void {
+    const args = ["/pid", String(pid), "/t", "/f"];
+    if (sync) {
+      const res = spawnSync("taskkill", args, { stdio: "ignore", windowsHide: true });
+      if (res.error || res.status !== 0) this.child.kill();
+      return;
+    }
+    try {
+      const killer = spawn("taskkill", args, { stdio: "ignore", windowsHide: true });
+      // taskkill missing or failing (e.g. restricted environment): still terminate the direct child.
+      killer.on("error", () => this.child.kill());
+      killer.on("exit", (code) => {
+        if (code !== 0 && !this.exited) this.child.kill();
+      });
+    } catch {
+      this.child.kill();
+    }
+  }
+
   private handleData(chunk: string): void {
     this.buffer.append(chunk);
     this.wakeSignal.notify();
@@ -191,6 +232,7 @@ export class ManagedSession {
       // stdin may already be closed, ignored.
     }
   }
+  /** Ctrl-C. POSIX: SIGINT to the process group; Windows: degrades to a hard tree kill (see signalGroup). */
   interrupt(): void {
     this.lastUsed = Date.now();
     this.signalGroup("SIGINT");
@@ -214,7 +256,7 @@ export class ManagedSession {
       clearTimeout(this.killTimer);
       this.killTimer = null;
     }
-    this.signalGroup("SIGKILL");
+    this.signalGroup("SIGKILL", true);
   }
 }
 

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

@@ -0,0 +1,121 @@
+/**
+ * Shell selection for command sessions.
+ *
+ * POSIX behavior is unchanged: commands run via `bash -lc <cmd>`. On Windows there is no
+ * bash by default, so the resolver picks the best available shell once per process:
+ *
+ * 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).
+ *
+ * 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)
+ *
+ * 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 path from "node:path";
+
+/** A resolved shell invocation: `spawn(command, [...args, cmd])` runs `cmd` in that shell. */
+export interface ShellInvocation {
+  /** Executable name or absolute path handed to spawn(). */
+  command: string;
+  /** Fixed argument prefix placed before the command string. */
+  args: string[];
+  /** Short lowercase name (basename without extension), shown to the model (e.g. "bash", "pwsh"). */
+  name: string;
+}
+
+/** Injection points for unit tests; production callers use the defaults. */
+export interface ResolveShellOptions {
+  platform?: NodeJS.Platform;
+  env?: NodeJS.ProcessEnv;
+  /** Returns the PATH resolutions of an executable name, best match first ([] when not found). */
+  whichAll?: (cmd: string) => string[];
+  /** The Windows system root (to recognize the WSL bash launcher); default `env.SystemRoot` or C:\Windows. */
+  systemRoot?: string;
+}
+
+/** Basename without a trailing .exe/.cmd/.bat/.ps1 extension, lowercased ("C:\...\pwsh.EXE" -> "pwsh"). */
+function shellBasename(command: string): string {
+  // path.win32 handles both separators, so PENGUIN_SHELL=/usr/bin/zsh still yields "zsh".
+  return path.win32
+    .basename(command)
+    .replace(/\.(exe|cmd|bat|ps1)$/i, "")
+    .toLowerCase();
+}
+
+/** Argument prefix for a shell, chosen by its basename (PowerShell-style vs cmd vs POSIX-style). */
+function argsForShell(name: string): string[] {
+  if (name === "pwsh" || name === "powershell") return ["-NoLogo", "-NoProfile", "-Command"];
+  if (name === "cmd") return ["/d", "/s", "/c"];
+  return ["-lc"];
+}
+
+/** Default PATH probe: `where` lists every match line by line, in PATH order (win32 only). */
+function defaultWhichAll(cmd: string): string[] {
+  try {
+    const res = spawnSync("where", [cmd], {
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    });
+    if (res.status !== 0 || !res.stdout) return [];
+    return res.stdout
+      .toString("utf8")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolves the shell for command sessions (pure given its options; see the module comment
+ * for the order). Exported for unit tests; runtime code uses the cached `sessionShell()`.
+ */
+export function resolveShell(opts: ResolveShellOptions = {}): ShellInvocation {
+  const platform = opts.platform ?? process.platform;
+  const env = opts.env ?? process.env;
+
+  const explicit = env.PENGUIN_SHELL?.trim();
+  if (explicit) {
+    const name = shellBasename(explicit);
+    return { command: explicit, args: argsForShell(name), name };
+  }
+
+  if (platform !== "win32") {
+    return { command: "bash", args: ["-lc"], name: "bash" };
+  }
+
+  const whichAll = opts.whichAll ?? defaultWhichAll;
+  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
+  // is the one spawn("bash") would run.
+  const bash = whichAll("bash")[0];
+  if (bash && !bash.toLowerCase().startsWith(systemRoot.toLowerCase() + path.win32.sep)) {
+    return { command: "bash", args: ["-lc"], name: "bash" };
+  }
+  if (whichAll("pwsh").length > 0) {
+    return { command: "pwsh", args: argsForShell("pwsh"), name: "pwsh" };
+  }
+  return { command: "powershell", args: argsForShell("powershell"), name: "powershell" };
+}
+
+let cached: ShellInvocation | null = null;
+
+/** The process-wide shell for command sessions; resolved once (probing PATH costs a subprocess on Windows). */
+export function sessionShell(): ShellInvocation {
+  if (!cached) cached = resolveShell();
+  return cached;
+}

packages/core/src/internal/session-support.ts

@@ -9,6 +9,7 @@ import path from "node:path";
 import { randomBytes, randomUUID } from "node:crypto";
 
 import { formatLocalDate } from "./dates.js";
+import { sessionShell } from "../environment/tools/command/shell.js";
 import type { SessionEnvironmentValues } from "../state/agent-state.js";
 import { workspacesDir } from "../state/index.js";
 import { userText } from "../omnimessage/index.js";
@@ -47,6 +48,9 @@ export function sessionEnvironment(
     modelId: ids.modelId,
     platform: process.platform,
     osVersion: getOsVersion(),
+    // The shell exec_command actually runs (bash on POSIX; resolved on Windows): the model
+    // must know whether to write bash or PowerShell syntax.
+    shell: sessionShell().name,
     date: formatLocalDate(date),
   };
 }

packages/core/src/state/agent-state.ts

@@ -36,6 +36,7 @@ import {
   PLATFORM_PLACEHOLDER,
   PROJECT_DIR_PLACEHOLDER,
   SESSION_ID_PLACEHOLDER,
+  SHELL_PLACEHOLDER,
   type SystemConfig,
 } from "./default-config.js";
 import { builtinProjectAgentPresets, type AgentPreset } from "./builtin-agents.js";
@@ -92,6 +93,8 @@ export interface SessionEnvironmentValues {
   modelId: string;
   platform: string;
   osVersion: string;
+  /** The shell command sessions run in (system Prompt placeholder {{SHELL}}; e.g. "bash", "pwsh") — tells the model which command syntax exec_command speaks. */
+  shell: string;
   date: string;
 }
 
@@ -383,6 +386,43 @@ export function skillMetadataSection(skills: SkillMetadata[]): string {
     .join("\n");
 }
 
+/**
+ * Windows compatibility fallback for pre-`{{SHELL}}` system prompt templates.
+ *
+ * `system_config.yaml` is baked at Agent creation and never auto-upgraded, so an Agent created
+ * before the `{{SHELL}}` placeholder existed never tells its model which shell `exec_command`
+ * speaks — and on Windows (where the shell may be PowerShell, not bash) the model then keeps
+ * emitting bash syntax into the wrong shell. When the platform is win32 and the template carries
+ * no `{{SHELL}}` placeholder, inject a `- Shell: <shell>` line into the assembled prompt at
+ * render time: right after the Environment section heading when one exists, else appended as a
+ * minimal final line. In-memory only — the stored template is never rewritten. On POSIX the
+ * assembled prompt stays byte-identical (bash was always implied there), and a prompt that
+ * already carries the exact line is left untouched (idempotent).
+ *
+ * Retirement condition: remove this fallback once pre-`{{SHELL}}` Agent configs (created before
+ * the placeholder shipped in PR #79) are no longer expected in the wild.
+ */
+function withShellLineFallback(
+  assembled: string,
+  template: string,
+  sessionEnvironment?: SessionEnvironmentValues,
+): string {
+  if (sessionEnvironment?.platform !== "win32") return assembled;
+  if (!sessionEnvironment.shell) return assembled;
+  if (template.includes(SHELL_PLACEHOLDER)) return assembled; // The template already renders the line itself.
+  // Any existing `- Shell:` line means the model is already told a shell — including a custom
+  // template hardcoding a different value on purpose; never add a second, contradicting line.
+  if (/^- Shell: /m.test(assembled)) return assembled;
+  const line = `- Shell: ${sessionEnvironment.shell}`;
+  // The default templates head the section with `# Environment`; accept any heading level.
+  const heading = /^#+ Environment[ \t]*$/m.exec(assembled);
+  if (heading) {
+    const insertAt = heading.index + heading[0].length;
+    return `${assembled.slice(0, insertAt)}\n${line}${assembled.slice(insertAt)}`;
+  }
+  return `${assembled}\n${line}`;
+}
+
 /**
  * Renders the complete runtime system Prompt: substitutes `AGENTS.md`, vault key names, Skill
  * metadata, and the concrete Session runtime environment placeholders into the system Prompt
@@ -390,7 +430,8 @@ export function skillMetadataSection(skills: SkillMetadata[]): string {
  * wrapper text such as `[developer_instructions]` and the # Vault / # Skills statements are
  * written directly into the system Prompt template itself (the Prompt is fully
  * transparent and editable via `system_config.yaml`). Other files in Agent State / Workspace are
- * never auto-injected.
+ * never auto-injected. Sole exception: on win32 a template without `{{SHELL}}` gets a `- Shell:`
+ * line injected at render time (see `withShellLineFallback`).
  *
  * `{{VAULT_KEYS}}` is replaced with the vault key-name list (an empty string if empty/not
  * provided): this lets the model know which APIs requiring a key it can call; values are never
@@ -406,7 +447,8 @@ export function assembleSystemPrompt(
   vaultKeys?: string[],
   skillMetadata?: SkillMetadata[],
 ): string {
-  return state.systemConfig.system_prompt
+  const template = state.systemConfig.system_prompt;
+  const assembled = template
     .split(AGENTS_MD_PLACEHOLDER)
     .join(state.agentsMd.trim())
     .split(VAULT_KEYS_PLACEHOLDER)
@@ -429,9 +471,12 @@ export function assembleSystemPrompt(
     .join(sessionEnvironment?.platform ?? "")
     .split(OS_VERSION_PLACEHOLDER)
     .join(sessionEnvironment?.osVersion ?? "")
+    .split(SHELL_PLACEHOLDER)
+    .join(sessionEnvironment?.shell ?? "")
     .split(DATE_PLACEHOLDER)
     .join(sessionEnvironment?.date ?? "")
     .trim();
+  return withShellLineFallback(assembled, template, sessionEnvironment);
 }
 
 /**

packages/core/src/state/default-config.ts

@@ -33,6 +33,8 @@ export const PROVIDER_PLACEHOLDER = "{{PROVIDER}}";
 export const MODEL_ID_PLACEHOLDER = "{{MODEL_ID}}";
 export const PLATFORM_PLACEHOLDER = "{{PLATFORM}}";
 export const OS_VERSION_PLACEHOLDER = "{{OS_VERSION}}";
+/** The shell exec_command runs (`bash` on POSIX; on Windows whatever shell.ts resolved), so the model knows which command syntax to write. */
+export const SHELL_PLACEHOLDER = "{{SHELL}}";
 export const DATE_PLACEHOLDER = "{{DATE}}";
 
 /**
@@ -147,6 +149,7 @@ Skills are reusable instruction packages stored under <app_data_dir>/agents/<age
 # Environment
 - Platform: {{PLATFORM}}
 - OS Version: {{OS_VERSION}}
+- Shell: {{SHELL}}
 - Date: {{DATE}}
 - App Data Dir: {{PROJECT_DIR}}
 - Agent ID: {{AGENT_ID}}

packages/core/test/builtin-agents.test.ts

@@ -126,6 +126,7 @@ describe("App Data Dir / Agent ID placeholders", () => {
       modelId: "deepseek-v4-pro",
       platform: "linux",
       osVersion: "test",
+      shell: "bash",
       date: "2026-07-08",
     });
     expect(prompt).toContain("Agent ID: env_agent");

packages/core/test/engine.test.ts

@@ -132,8 +132,10 @@ describe("ContextEngine ReAct loop (mock LLM, approve callback)", () => {
   });
 
   afterEach(async () => {
-    await rm(workspace, { recursive: true, force: true });
-    await rm(traces, { recursive: true, force: true });
+    // Retries (here and in the other cleanups below): on Windows a just-killed process tree
+    // releases its cwd locks asynchronously, so an immediate rm can hit EBUSY.
+    await rm(workspace, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+    await rm(traces, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
   });
 
   it("approves a tool call, writes the file, returns the final answer, traces it", async () => {
@@ -733,7 +735,7 @@ describe("ContextEngine async/incremental tool calls (overlapping execution)", (
     workspace = await mkdtemp(join(tmpdir(), "penguin-ws2-"));
   });
   afterEach(async () => {
-    await rm(workspace, { recursive: true, force: true });
+    await rm(workspace, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
   });
 
   it("emits both tool calls in one round; second is approved while the first executes; outputs come back in completion order", async () => {
@@ -809,7 +811,13 @@ describe("ContextEngine async/incremental tool calls (overlapping execution)", (
     // command has not finished yet) -- i.e., execution does not block the next approval.
     expect(approvedAt["t2"]!).toBeLessThan(firstCompleteAt["t1"] ?? Infinity);
     // The fast b.txt finishes first, the slow a.txt finishes later (outputs in completion order).
-    expect(firstCompleteAt["t2"]!).toBeLessThan(firstCompleteAt["t1"]!);
+    // POSIX only: on Windows a cold Git-Bash spawn costs 1-2s, which can swamp the 400ms sleep
+    // delta that makes t1 "the slow one" — CI has seen the two complete within 5ms — so the
+    // relative completion order is not controllable there. The overlap assertion above and the
+    // file contents below still run on Windows.
+    if (process.platform !== "win32") {
+      expect(firstCompleteAt["t2"]!).toBeLessThan(firstCompleteAt["t1"]!);
+    }
 
     expect(await readFile(join(workspace, "a.txt"), "utf8")).toBe("one");
     expect(await readFile(join(workspace, "b.txt"), "utf8")).toBe("two");
@@ -895,7 +903,7 @@ describe("ContextEngine tool execution resilience", () => {
     workspace = await mkdtemp(join(tmpdir(), "penguin-ws4-"));
   });
   afterEach(async () => {
-    await rm(workspace, { recursive: true, force: true });
+    await rm(workspace, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
   });
 
   it("feeds a failed tool output back and keeps tool_use/result paired (Environment converges errors, never throws)", async () => {
@@ -1105,7 +1113,7 @@ describe("ContextEngine abort during execution", () => {
     workspace = await mkdtemp(join(tmpdir(), "penguin-ws3-"));
   });
   afterEach(async () => {
-    await rm(workspace, { recursive: true, force: true });
+    await rm(workspace, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
   });
 
   it("aborting a long-running tool ends the turn, emits abort, and carries tool results over (model output completed)", async () => {
@@ -1255,7 +1263,7 @@ describe("ContextEngine LLM timeout / network interruption (PRN-012)", () => {
     workspace = await mkdtemp(join(tmpdir(), "penguin-ws4-"));
   });
   afterEach(async () => {
-    await rm(workspace, { recursive: true, force: true });
+    await rm(workspace, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
   });
 
   it("auto-retries on LLM timeout: original input + [turn_retried] carrying partial products", async () => {
@@ -1792,8 +1800,8 @@ describe("ContextEngine mid-run steering ([user_steering])", () => {
   });
 
   afterEach(async () => {
-    await rm(workspace, { recursive: true, force: true });
-    await rm(traces, { recursive: true, force: true });
+    await rm(workspace, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+    await rm(traces, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
   });
 
   /** Fake environment: streams a delta then closes with a fixed complete output (no real shell). */

packages/core/test/environment.test.ts

@@ -67,7 +67,9 @@ beforeEach(async () => {
 afterEach(async () => {
   if (originalHome === undefined) delete process.env.HOME;
   else process.env.HOME = originalHome;
-  await rm(tmp, { recursive: true, force: true });
+  // Retries: on Windows a just-killed process tree releases its cwd/file locks asynchronously,
+  // so an immediate recursive rm can hit EBUSY; fs.rm retries those with a linear backoff.
+  await rm(tmp, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
 });
 
 describe("Environment.listTools", () => {
@@ -485,9 +487,12 @@ describe("Environment.executeTool — relaxed tool contract", () => {
 
 describe("Environment.executeTool — timeoutMs (PRN-013)", () => {
   it("fails a tool exceeding timeoutMs, keeps prior output, and streams the timeout reason", async () => {
+    // The timeout must stay below MIN_YIELD_MS (250): for larger values exec_command yields to
+    // background (with a process_id) before the Environment timeout can ever fire.
+    const timeoutMs = 200;
     const env = new Environment({
       workspaceDir: tmp,
-      toolConfig: makeToolConfig(execTool({ timeoutMs: 200 })),
+      toolConfig: makeToolConfig(execTool({ timeoutMs })),
     });
     const startedAt = Date.now();
 
@@ -513,8 +518,13 @@ describe("Environment.executeTool — timeoutMs (PRN-013)", () => {
     };
     expect(last.type).toBe("tool_call_output");
     expect(last.stop_reason).toBe("failed");
-    expect(last.output).toContain("begin");
-    expect(last.output).toContain("[tool timeout: exceeded 200ms]");
+    // Kept-prior-output is asserted only where the shell can win the race: a Git-Bash login
+    // shell on Windows needs several hundred ms to start, so nothing is printed before a
+    // sub-250ms timeout there — the timeout mechanics above are still fully exercised.
+    if (process.platform !== "win32") {
+      expect(last.output).toContain("begin");
+    }
+    expect(last.output).toContain(`[tool timeout: exceeded ${timeoutMs}ms]`);
     // The timeout marker is also produced via streaming: concatenating the streamed deltas ==
     // the complete content.
     const streamed = messages
@@ -735,14 +745,14 @@ describe("Environment.executeTool — robustness", () => {
 describe("Environment.toolPermission", () => {
   it("returns the configured permission for a known tool", () => {
     const env = new Environment({
-      workspaceDir: "/tmp",
+      workspaceDir: tmpdir(),
       toolConfig: makeToolConfig(execTool({ permission: "rw" })),
     });
     expect(env.toolPermission("exec_command")).toBe("rw");
   });
 
   it("returns undefined for an unknown tool", () => {
-    const env = new Environment({ workspaceDir: "/tmp", toolConfig: makeToolConfig() });
+    const env = new Environment({ workspaceDir: tmpdir(), toolConfig: makeToolConfig() });
     expect(env.toolPermission("nope")).toBeUndefined();
   });
 });

packages/core/test/exec-session.test.ts

@@ -91,7 +91,9 @@ beforeEach(async () => {
 
 afterEach(async () => {
   env.dispose();
-  await rm(tmp, { recursive: true, force: true });
+  // Retries: on Windows a just-killed process tree releases its cwd/file locks asynchronously,
+  // so an immediate recursive rm can hit EBUSY; fs.rm retries those with a linear backoff.
+  await rm(tmp, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
 });
 
 describe("exec_command — long-running command sessions", () => {

packages/core/test/file-tools.test.ts

@@ -514,15 +514,19 @@ describe("edit_file — review follow-ups", () => {
 describe("write_file — review follow-ups", () => {
   const tool = () => createWriteFileTool(def(WRITE_FILE_NAME, "rw"));
 
-  it("preserves the permission bits of an overwritten file (atomic rename)", async () => {
-    const file = path.join(tmp, "mode.txt");
-    await writeFile(file, "old");
-    await chmod(file, 0o600);
-    const { result } = await run(tool(), { file_path: "mode.txt", content: "new" }, tmp);
-    expect(result?.stopReason).toBeUndefined();
-    expect((await stat(file)).mode & 0o777).toBe(0o600);
-    expect(await readFile(file, "utf8")).toBe("new");
-  });
+  // POSIX-only: Windows has no owner-only mode bits to preserve (chmod maps to the read-only attribute).
+  it.skipIf(process.platform === "win32")(
+    "preserves the permission bits of an overwritten file (atomic rename)",
+    async () => {
+      const file = path.join(tmp, "mode.txt");
+      await writeFile(file, "old");
+      await chmod(file, 0o600);
+      const { result } = await run(tool(), { file_path: "mode.txt", content: "new" }, tmp);
+      expect(result?.stopReason).toBeUndefined();
+      expect((await stat(file)).mode & 0o777).toBe(0o600);
+      expect(await readFile(file, "utf8")).toBe("new");
+    },
+  );
 
   it("writes atomically: no temp files are left behind", async () => {
     await run(tool(), { file_path: "fresh.txt", content: "x" }, tmp);

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

@@ -0,0 +1,112 @@
+/**
+ * Unit tests for the command-session shell resolver (pure function; platform, env and the
+ * PATH probe are injected — no real shells are spawned here).
+ */
+import { describe, expect, it } from "vitest";
+import { resolveShell } from "../src/environment/tools/command/shell.js";
+
+const POWERSHELL_ARGS = ["-NoLogo", "-NoProfile", "-Command"];
+
+/** A whichAll stub resolving only the given names (value = returned PATH matches). */
+function which(table: Record<string, string[]>): (cmd: string) => string[] {
+  return (cmd) => table[cmd] ?? [];
+}
+
+describe("resolveShell — POSIX", () => {
+  it("uses bash -lc on linux without probing (today's behavior, unchanged)", () => {
+    let probed = false;
+    const shell = resolveShell({
+      platform: "linux",
+      env: {},
+      whichAll: () => {
+        probed = true;
+        return [];
+      },
+    });
+    expect(shell).toEqual({ command: "bash", args: ["-lc"], name: "bash" });
+    expect(probed).toBe(false);
+  });
+
+  it("uses bash -lc on darwin", () => {
+    const shell = resolveShell({ platform: "darwin", env: {} });
+    expect(shell).toEqual({ command: "bash", args: ["-lc"], name: "bash" });
+  });
+});
+
+describe("resolveShell — win32 probing", () => {
+  it("prefers bash on PATH (Git for Windows)", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: {},
+      whichAll: which({
+        bash: ["C:\\Program Files\\Git\\bin\\bash.exe"],
+        pwsh: ["C:\\Program Files\\PowerShell\\7\\pwsh.exe"],
+      }),
+    });
+    expect(shell).toEqual({ command: "bash", args: ["-lc"], name: "bash" });
+  });
+
+  it("skips the WSL launcher bash under the system root and falls through to pwsh", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: { SystemRoot: "C:\\WINDOWS" },
+      whichAll: which({
+        bash: ["C:\\Windows\\System32\\bash.exe"],
+        pwsh: ["C:\\Program Files\\PowerShell\\7\\pwsh.exe"],
+      }),
+    });
+    expect(shell).toEqual({ command: "pwsh", args: POWERSHELL_ARGS, name: "pwsh" });
+  });
+
+  it("falls back to pwsh when bash is absent", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: {},
+      whichAll: which({ pwsh: ["C:\\Program Files\\PowerShell\\7\\pwsh.exe"] }),
+    });
+    expect(shell).toEqual({ command: "pwsh", args: POWERSHELL_ARGS, name: "pwsh" });
+  });
+
+  it("falls back to powershell when neither bash nor pwsh resolve", () => {
+    const shell = resolveShell({ platform: "win32", env: {}, whichAll: which({}) });
+    expect(shell).toEqual({ command: "powershell", args: POWERSHELL_ARGS, name: "powershell" });
+  });
+});
+
+describe("resolveShell — PENGUIN_SHELL override", () => {
+  it("wins on every platform and keeps POSIX-style args for a POSIX shell path", () => {
+    const shell = resolveShell({
+      platform: "linux",
+      env: { PENGUIN_SHELL: "/usr/bin/zsh" },
+    });
+    expect(shell).toEqual({ command: "/usr/bin/zsh", args: ["-lc"], name: "zsh" });
+  });
+
+  it("uses PowerShell-style args when the basename is pwsh (case/extension-insensitive)", () => {
+    const shell = resolveShell({
+      platform: "win32",
+      env: { PENGUIN_SHELL: "C:\\Program Files\\PowerShell\\7\\pwsh.EXE" },
+      whichAll: which({ bash: ["C:\\Program Files\\Git\\bin\\bash.exe"] }),
+    });
+    expect(shell).toEqual({
+      command: "C:\\Program Files\\PowerShell\\7\\pwsh.EXE",
+      args: POWERSHELL_ARGS,
+      name: "pwsh",
+    });
+  });
+
+  it("uses PowerShell-style args for a bare powershell name", () => {
+    const shell = resolveShell({ platform: "win32", env: { PENGUIN_SHELL: "powershell" } });
+    expect(shell).toEqual({ command: "powershell", args: POWERSHELL_ARGS, name: "powershell" });
+  });
+
+  it("uses cmd-style args when the basename is cmd", () => {
+    const shell = resolveShell({ platform: "win32", env: { PENGUIN_SHELL: "cmd" } });
+    expect(shell).toEqual({ command: "cmd", args: ["/d", "/s", "/c"], name: "cmd" });
+  });
+
+  it("ignores a blank PENGUIN_SHELL", () => {
+    const shell = resolveShell({ platform: "linux", env: { PENGUIN_SHELL: "  " } });
+    expect(shell).toEqual({ command: "bash", args: ["-lc"], name: "bash" });
+  });
+});

packages/core/test/state.test.ts

@@ -16,6 +16,7 @@ import {
   PLATFORM_PLACEHOLDER,
   PROJECT_DIR_PLACEHOLDER,
   SESSION_ID_PLACEHOLDER,
+  SHELL_PLACEHOLDER,
   addModel,
   setVisionModel,
   agentsMdPath,
@@ -64,7 +65,10 @@ afterEach(async () => {
   } else {
     process.env.PENGUIN_HOME = prevHome;
   }
-  await fs.rm(tmpRoot, { recursive: true, force: true });
+  // Retries: when a test times out, vitest runs this cleanup while the test's un-cancelled
+  // init may still be writing files, so an immediate recursive rm can hit ENOTEMPTY on
+  // Windows (fs.rm retries ENOTEMPTY/EBUSY/EPERM); a no-op when removal succeeds first try.
+  await fs.rm(tmpRoot, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
 });
 
 async function exists(p: string): Promise<boolean> {
@@ -83,87 +87,96 @@ describe("paths / resolveRoot", () => {
 });
 
 describe("loadOrInitAgentState", () => {
-  it("initializes an empty agent directory with the full state layout", async () => {
-    const state = await loadOrInitAgentState();
-    expect(state.root).toBe(tmpRoot);
-    expect(state.projectId).toBe(DEFAULT_PROJECT_ID);
-    expect(state.agentId).toBe(DEFAULT_AGENT_ID);
+  // Timeout: initialization writes the full layout — 15 library skills plus the example
+  // benchmark, dozens of small files — and this first init test also pays the cold-I/O cost
+  // (first-touch reads of the skills package, Defender scans) on Windows runners, where a
+  // slow-disk moment has pushed it past the 5s default. Purely a failure deadline: passing
+  // runs stay as fast as before on every platform.
+  it(
+    "initializes an empty agent directory with the full state layout",
+    { timeout: 20_000 },
+    async () => {
+      const state = await loadOrInitAgentState();
+      expect(state.root).toBe(tmpRoot);
+      expect(state.projectId).toBe(DEFAULT_PROJECT_ID);
+      expect(state.agentId).toBe(DEFAULT_AGENT_ID);
 
-    const root = tmpRoot;
-    expect(await exists(systemConfigPath(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
-    expect(await exists(agentsMdPath(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
-    expect(await exists(toolsDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
-    expect(await exists(memoryDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
-    expect(await exists(skillsDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
-    // The scratchpad/ directory alongside agent_state (model temp files get a subdirectory per Session id).
-    expect(await exists(scratchpadDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
+      const root = tmpRoot;
+      expect(await exists(systemConfigPath(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
+      expect(await exists(agentsMdPath(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
+      expect(await exists(toolsDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
+      expect(await exists(memoryDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
+      expect(await exists(skillsDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
+      // The scratchpad/ directory alongside agent_state (model temp files get a subdirectory per Session id).
+      expect(await exists(scratchpadDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID))).toBe(true);
 
-    expect(state.stateDir).toBe(agentStateDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID));
+      expect(state.stateDir).toBe(agentStateDir(root, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID));
 
-    // The default system Prompt states the Agent's identity, without repeating tool details
-    // already in the tool schema (Suggested workflows only points to the run_subagent
-    // delegation entry point).
-    expect(state.systemConfig.system_prompt).toContain("PenguinHarness");
-    expect(state.systemConfig.system_prompt).not.toContain("exec_command");
-    // Suggested workflows absorbs Subagent delegation and task conventions (self-reported
-    // identity as a soft convention, parallelism, file exchange).
-    expect(state.systemConfig.system_prompt).toContain("# Suggested workflows");
-    expect(state.systemConfig.system_prompt).toContain("run_subagent");
-    expect(state.systemConfig.system_prompt).toContain("Caller agent");
-    // The default AGENTS.md is empty: it carries no preset guidance.
-    expect(state.agentsMd).toBe("");
-    expect(state.systemConfig.system_prompt).toContain(AGENTS_MD_PLACEHOLDER);
-    expect(state.systemConfig.system_prompt).toContain(SESSION_ID_PLACEHOLDER);
-    expect(state.systemConfig.system_prompt).toContain(CWD_PLACEHOLDER);
-    expect(state.systemConfig.system_prompt).toContain(PLATFORM_PLACEHOLDER);
-    expect(state.systemConfig.system_prompt).toContain(OS_VERSION_PLACEHOLDER);
-    expect(state.systemConfig.system_prompt).toContain(DATE_PLACEHOLDER);
-    // AGENTS.md and the Environment injection sit at the end of the template, with AGENTS.md
-    // before Environment; the [developer_instructions] wrapper text is written directly into
-    // the template (the Prompt is transparent about the config).
-    expect(state.systemConfig.system_prompt).toContain("[developer_instructions]");
-    expect(state.systemConfig.system_prompt).toContain("[/developer_instructions]");
-    // The default template explains the semantics of system-synthesized markers to the model,
-    // and recommends preferring tool use.
-    expect(state.systemConfig.system_prompt).toContain("[turn_aborted]");
-    expect(state.systemConfig.system_prompt).toContain("[turn_retried]");
-    expect(state.systemConfig.system_prompt).toContain("[context_summary]");
-    expect(state.systemConfig.system_prompt).toContain("[user_steering]");
-    expect(state.systemConfig.system_prompt).toContain("# Tool use");
-    // Privacy hardening: explicitly forbids reading .project_config.toml (the sole config file,
-    // which holds API keys) and each Agent's .vault.toml, and states that config can only be
-    // changed via the CLI (penguin config ...).
-    expect(state.systemConfig.system_prompt).toContain("Never read");
-    expect(state.systemConfig.system_prompt).toContain(".project_config.toml");
-    expect(state.systemConfig.system_prompt).toContain("agent_state/.vault.toml");
-    expect(state.systemConfig.system_prompt).toContain("CLI-only");
-    expect(state.systemConfig.system_prompt).toContain("penguin config");
-    expect(state.systemConfig.system_prompt).not.toContain(".credentials.toml");
-    expect(state.systemConfig.system_prompt.indexOf(AGENTS_MD_PLACEHOLDER)).toBeLessThan(
-      state.systemConfig.system_prompt.indexOf("# Environment"),
-    );
-    // The # Vault and # Skills body sections plus their placeholders: the default template
-    // places them after [/developer_instructions] and before # Environment, in the order
-    // Vault -> Skills (the statement text is part of the template body, kept even with no
-    // keys/skills).
-    const tpl = state.systemConfig.system_prompt;
-    expect(tpl).toContain("# Vault");
-    expect(tpl).toContain(VAULT_KEYS_PLACEHOLDER);
-    expect(tpl).toContain("# Skills");
-    expect(tpl).toContain(SKILL_METADATA_PLACEHOLDER);
-    expect(tpl).toContain("[use_skills]");
-    expect(tpl.indexOf("[/developer_instructions]")).toBeLessThan(tpl.indexOf("# Vault"));
-    expect(tpl.indexOf("# Vault")).toBeLessThan(tpl.indexOf(VAULT_KEYS_PLACEHOLDER));
-    expect(tpl.indexOf(VAULT_KEYS_PLACEHOLDER)).toBeLessThan(tpl.indexOf("# Skills"));
-    expect(tpl.indexOf("# Skills")).toBeLessThan(tpl.indexOf(SKILL_METADATA_PLACEHOLDER));
-    expect(tpl.indexOf(SKILL_METADATA_PLACEHOLDER)).toBeLessThan(tpl.indexOf("# Environment"));
-    expect(state.systemConfig.model?.max_tokens).toBe(32000);
-    expect(state.systemConfig.model?.thinking_level).toBe("medium");
-    expect(state.systemConfig.model?.timeoutMs).toBe(120000);
-    expect(state.systemConfig.tools?.mcpServers).toEqual([]);
-    expect(Object.hasOwn(state.systemConfig, "description")).toBe(false);
-    expect(Object.hasOwn(state.systemConfig, "subagents")).toBe(false);
-  });
+      // The default system Prompt states the Agent's identity, without repeating tool details
+      // already in the tool schema (Suggested workflows only points to the run_subagent
+      // delegation entry point).
+      expect(state.systemConfig.system_prompt).toContain("PenguinHarness");
+      expect(state.systemConfig.system_prompt).not.toContain("exec_command");
+      // Suggested workflows absorbs Subagent delegation and task conventions (self-reported
+      // identity as a soft convention, parallelism, file exchange).
+      expect(state.systemConfig.system_prompt).toContain("# Suggested workflows");
+      expect(state.systemConfig.system_prompt).toContain("run_subagent");
+      expect(state.systemConfig.system_prompt).toContain("Caller agent");
+      // The default AGENTS.md is empty: it carries no preset guidance.
+      expect(state.agentsMd).toBe("");
+      expect(state.systemConfig.system_prompt).toContain(AGENTS_MD_PLACEHOLDER);
+      expect(state.systemConfig.system_prompt).toContain(SESSION_ID_PLACEHOLDER);
+      expect(state.systemConfig.system_prompt).toContain(CWD_PLACEHOLDER);
+      expect(state.systemConfig.system_prompt).toContain(PLATFORM_PLACEHOLDER);
+      expect(state.systemConfig.system_prompt).toContain(OS_VERSION_PLACEHOLDER);
+      expect(state.systemConfig.system_prompt).toContain(DATE_PLACEHOLDER);
+      // AGENTS.md and the Environment injection sit at the end of the template, with AGENTS.md
+      // before Environment; the [developer_instructions] wrapper text is written directly into
+      // the template (the Prompt is transparent about the config).
+      expect(state.systemConfig.system_prompt).toContain("[developer_instructions]");
+      expect(state.systemConfig.system_prompt).toContain("[/developer_instructions]");
+      // The default template explains the semantics of system-synthesized markers to the model,
+      // and recommends preferring tool use.
+      expect(state.systemConfig.system_prompt).toContain("[turn_aborted]");
+      expect(state.systemConfig.system_prompt).toContain("[turn_retried]");
+      expect(state.systemConfig.system_prompt).toContain("[context_summary]");
+      expect(state.systemConfig.system_prompt).toContain("[user_steering]");
+      expect(state.systemConfig.system_prompt).toContain("# Tool use");
+      // Privacy hardening: explicitly forbids reading .project_config.toml (the sole config file,
+      // which holds API keys) and each Agent's .vault.toml, and states that config can only be
+      // changed via the CLI (penguin config ...).
+      expect(state.systemConfig.system_prompt).toContain("Never read");
+      expect(state.systemConfig.system_prompt).toContain(".project_config.toml");
+      expect(state.systemConfig.system_prompt).toContain("agent_state/.vault.toml");
+      expect(state.systemConfig.system_prompt).toContain("CLI-only");
+      expect(state.systemConfig.system_prompt).toContain("penguin config");
+      expect(state.systemConfig.system_prompt).not.toContain(".credentials.toml");
+      expect(state.systemConfig.system_prompt.indexOf(AGENTS_MD_PLACEHOLDER)).toBeLessThan(
+        state.systemConfig.system_prompt.indexOf("# Environment"),
+      );
+      // The # Vault and # Skills body sections plus their placeholders: the default template
+      // places them after [/developer_instructions] and before # Environment, in the order
+      // Vault -> Skills (the statement text is part of the template body, kept even with no
+      // keys/skills).
+      const tpl = state.systemConfig.system_prompt;
+      expect(tpl).toContain("# Vault");
+      expect(tpl).toContain(VAULT_KEYS_PLACEHOLDER);
+      expect(tpl).toContain("# Skills");
+      expect(tpl).toContain(SKILL_METADATA_PLACEHOLDER);
+      expect(tpl).toContain("[use_skills]");
+      expect(tpl.indexOf("[/developer_instructions]")).toBeLessThan(tpl.indexOf("# Vault"));
+      expect(tpl.indexOf("# Vault")).toBeLessThan(tpl.indexOf(VAULT_KEYS_PLACEHOLDER));
+      expect(tpl.indexOf(VAULT_KEYS_PLACEHOLDER)).toBeLessThan(tpl.indexOf("# Skills"));
+      expect(tpl.indexOf("# Skills")).toBeLessThan(tpl.indexOf(SKILL_METADATA_PLACEHOLDER));
+      expect(tpl.indexOf(SKILL_METADATA_PLACEHOLDER)).toBeLessThan(tpl.indexOf("# Environment"));
+      expect(state.systemConfig.model?.max_tokens).toBe(32000);
+      expect(state.systemConfig.model?.thinking_level).toBe("medium");
+      expect(state.systemConfig.model?.timeoutMs).toBe(120000);
+      expect(state.systemConfig.tools?.mcpServers).toEqual([]);
+      expect(Object.hasOwn(state.systemConfig, "description")).toBe(false);
+      expect(Object.hasOwn(state.systemConfig, "subagents")).toBe(false);
+    },
+  );
 
   it("loads an existing agent directory and returns the same system prompt", async () => {
     const first = await loadOrInitAgentState();
@@ -500,6 +513,7 @@ describe("assembleSystemPrompt", () => {
           `pdir=${PROJECT_DIR_PLACEHOLDER}`,
           `platform=${PLATFORM_PLACEHOLDER}`,
           `os=${OS_VERSION_PLACEHOLDER}`,
+          `shell=${SHELL_PLACEHOLDER}`,
           `date=${DATE_PLACEHOLDER}`,
           "middle",
           AGENTS_MD_PLACEHOLDER,
@@ -518,6 +532,7 @@ describe("assembleSystemPrompt", () => {
       modelId: "deepseek-v4-pro",
       platform: "darwin",
       osVersion: "Darwin 25.0.0",
+      shell: "zsh",
       date: "2026-06-30",
     });
     expect(prompt).toBe(
@@ -529,6 +544,7 @@ describe("assembleSystemPrompt", () => {
         "pdir=/tmp/proj",
         "platform=darwin",
         "os=Darwin 25.0.0",
+        "shell=zsh",
         "date=2026-06-30",
         "middle",
         "# Agent Rules\nFollow local rules.",
@@ -572,6 +588,7 @@ describe("assembleSystemPrompt", () => {
       modelId: "deepseek-v4-pro",
       platform: "darwin",
       osVersion: "Darwin 25.0.0",
+      shell: "zsh",
       date: "2026-06-30",
     });
     expect(prompt).toBe("base prompt");
@@ -657,9 +674,11 @@ describe("assembleSystemPrompt", () => {
     expect(prompt).toContain("Model ID: gpt-5.5");
     expect(prompt).toContain("Platform:");
     expect(prompt).toContain("OS Version:");
+    expect(prompt).toContain("Shell:");
     expect(prompt).toContain("Date: 2026-06-30");
     expect(prompt.indexOf("Platform:")).toBeLessThan(prompt.indexOf("OS Version:"));
-    expect(prompt.indexOf("OS Version:")).toBeLessThan(prompt.indexOf("Date:"));
+    expect(prompt.indexOf("OS Version:")).toBeLessThan(prompt.indexOf("Shell:"));
+    expect(prompt.indexOf("Shell:")).toBeLessThan(prompt.indexOf("Date:"));
     expect(prompt.indexOf("Date:")).toBeLessThan(prompt.indexOf("App Data Dir:"));
     expect(prompt.indexOf("App Data Dir:")).toBeLessThan(prompt.indexOf("Agent ID:"));
     expect(prompt.indexOf("Agent ID:")).toBeLessThan(prompt.indexOf("CWD:"));
@@ -667,6 +686,114 @@ describe("assembleSystemPrompt", () => {
     expect(prompt.indexOf("Provider:")).toBeLessThan(prompt.indexOf("Model ID:"));
     expect(prompt.indexOf("Model ID:")).toBeLessThan(prompt.indexOf("Session ID:"));
   });
+
+  // The win32 Shell-line fallback for pre-{{SHELL}} templates (system_config.yaml is baked at
+  // Agent creation and never auto-upgraded). Removable together with `withShellLineFallback`
+  // once pre-{{SHELL}} Agent configs are no longer expected in the wild.
+  describe("Shell line fallback for templates without {{SHELL}}", () => {
+    const stateWithPrompt = (system_prompt: string) => ({
+      root: tmpRoot,
+      projectId: DEFAULT_PROJECT_ID,
+      agentId: DEFAULT_AGENT_ID,
+      stateDir: agentStateDir(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID),
+      systemConfig: { system_prompt },
+      agentsMd: "",
+    });
+    const envFor = (platform: string) => ({
+      sessionId: "session-1",
+      cwd: "C:\\ws",
+      agentId: "agent-x",
+      projectDir: "C:\\proj",
+      provider: "deepseek",
+      modelId: "deepseek-v4-pro",
+      platform,
+      osVersion: "Windows 11 Pro 10.0.26100",
+      shell: "pwsh",
+      date: "2026-07-27",
+    });
+    // A pre-{{SHELL}} default-template Environment section (Platform/OS Version/Date, no Shell).
+    const preShellTemplate = [
+      "intro",
+      "# Environment",
+      `- Platform: ${PLATFORM_PLACEHOLDER}`,
+      `- OS Version: ${OS_VERSION_PLACEHOLDER}`,
+      `- Date: ${DATE_PLACEHOLDER}`,
+      "",
+      "# Tail section",
+      "tail",
+    ].join("\n");
+
+    it("injects the line exactly once into the Environment section on win32", () => {
+      const prompt = assembleSystemPrompt(stateWithPrompt(preShellTemplate), envFor("win32"));
+      expect(prompt).toBe(
+        [
+          "intro",
+          "# Environment",
+          "- Shell: pwsh",
+          "- Platform: win32",
+          "- OS Version: Windows 11 Pro 10.0.26100",
+          "- Date: 2026-07-27",
+          "",
+          "# Tail section",
+          "tail",
+        ].join("\n"),
+      );
+      expect(prompt.split("- Shell: pwsh").length - 1).toBe(1);
+    });
+
+    it("keeps POSIX output byte-identical (no injected line)", () => {
+      for (const platform of ["linux", "darwin"]) {
+        const prompt = assembleSystemPrompt(stateWithPrompt(preShellTemplate), {
+          ...envFor(platform),
+          shell: "bash",
+          osVersion: "Linux 6.1.0",
+        });
+        expect(prompt).toBe(
+          [
+            "intro",
+            "# Environment",
+            `- Platform: ${platform}`,
+            "- OS Version: Linux 6.1.0",
+            "- Date: 2026-07-27",
+            "",
+            "# Tail section",
+            "tail",
+          ].join("\n"),
+        );
+        expect(prompt).not.toContain("Shell:");
+      }
+    });
+
+    it("does not duplicate the line when the template has {{SHELL}}", () => {
+      const template = [
+        "# Environment",
+        `- Platform: ${PLATFORM_PLACEHOLDER}`,
+        `- Shell: ${SHELL_PLACEHOLDER}`,
+      ].join("\n");
+      const prompt = assembleSystemPrompt(stateWithPrompt(template), envFor("win32"));
+      expect(prompt).toBe(["# Environment", "- Platform: win32", "- Shell: pwsh"].join("\n"));
+      expect(prompt.split("- Shell:").length - 1).toBe(1);
+    });
+
+    it("does not duplicate a hardcoded line and appends a minimal line without an Environment section", () => {
+      // A custom template that hardcodes the exact line: left untouched (idempotent).
+      const hardcoded = assembleSystemPrompt(
+        stateWithPrompt("base prompt\n- Shell: pwsh"),
+        envFor("win32"),
+      );
+      expect(hardcoded).toBe("base prompt\n- Shell: pwsh");
+      // A hardcoded line with a different value is a deliberate template choice:
+      // never add a second, contradicting Shell line.
+      const pinned = assembleSystemPrompt(
+        stateWithPrompt("base prompt\n- Shell: bash"),
+        envFor("win32"),
+      );
+      expect(pinned).toBe("base prompt\n- Shell: bash");
+      // No Environment section at all: the line is appended at the end.
+      const appended = assembleSystemPrompt(stateWithPrompt("base prompt"), envFor("win32"));
+      expect(appended).toBe("base prompt\n- Shell: pwsh");
+    });
+  });
 });
 
 describe("resetSystemConfigToDefaults", () => {
@@ -1174,28 +1301,35 @@ describe("single hidden config file (.project_config.toml, credentials inlined)"
     // The sole config file is hidden (not shown by ls by default) and has 0600 permission
     // (owner read/write only).
     expect(path.basename(file)).toBe(".project_config.toml");
-    expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    // POSIX-only: Windows has no owner-only mode bits (chmod maps to the read-only attribute).
+    if (process.platform !== "win32") {
+      expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    }
     expect(await fs.readFile(file, "utf8")).toContain("sk-split-1");
     // The old two-file layout is no longer produced.
     expect(await exists(path.join(tmpRoot, DEFAULT_PROJECT_ID, "project_config.toml"))).toBe(false);
     expect(await exists(path.join(tmpRoot, DEFAULT_PROJECT_ID, ".credentials.toml"))).toBe(false);
   });
 
-  it("chmod converges an existing file back to 0600 on save", async () => {
-    await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
-      provider: "custom",
-      model_id: "m-perm",
-      api_key: "sk-1",
-    });
-    const file = projectConfigPath(tmpRoot, DEFAULT_PROJECT_ID);
-    await fs.chmod(file, 0o644);
-    await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
-      provider: "custom",
-      model_id: "m-perm",
-      api_key: "sk-2",
-    });
-    expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
-  });
+  // POSIX-only: Windows has no owner-only mode bits to converge.
+  it.skipIf(process.platform === "win32")(
+    "chmod converges an existing file back to 0600 on save",
+    async () => {
+      await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
+        provider: "custom",
+        model_id: "m-perm",
+        api_key: "sk-1",
+      });
+      const file = projectConfigPath(tmpRoot, DEFAULT_PROJECT_ID);
+      await fs.chmod(file, 0o644);
+      await addModel(tmpRoot, DEFAULT_PROJECT_ID, {
+        provider: "custom",
+        model_id: "m-perm",
+        api_key: "sk-2",
+      });
+      expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    },
+  );
 
   it("writes provider and model_id as separate fields; refs are TOML inline tables", async () => {
     await addModel(
@@ -1238,7 +1372,10 @@ describe("agent vault (agent_state/.vault.toml)", () => {
     // with 0600 permission (owner read/write only).
     const file = agentVaultPath(tmpRoot, DEFAULT_PROJECT_ID, DEFAULT_AGENT_ID);
     expect(path.basename(file)).toBe(".vault.toml");
-    expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    // POSIX-only: Windows has no owner-only mode bits (chmod maps to the read-only attribute).
+    if (process.platform !== "win32") {
+      expect((await fs.stat(file)).mode & 0o777).toBe(0o600);
+    }
     const raw = await fs.readFile(file, "utf8");
     expect(raw).toContain("sk-secret-2");
     // The Project config no longer carries the vault.

packages/core/vitest.config.ts

@@ -0,0 +1,16 @@
+/**
+ * Vitest config for core. The one non-default setting is a platform-aware test timeout:
+ * many core tests spawn a real shell (Git-Bash on the Windows CI runners) or write the
+ * full Agent State layout, and Windows runner I/O variance (cold shell spawns, Defender
+ * first-touch scans, slow-disk moments) has pushed individually fast tests past vitest's
+ * 5s default — a different test on each run. A larger failure deadline changes nothing
+ * for passing tests; POSIX keeps the 5s default to fail fast during local development.
+ */
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    testTimeout: process.platform === "win32" ? 30_000 : 5_000,
+  },
+});

packages/docs/content/installation.en.md

@@ -6,6 +6,7 @@ description: Install PenguinHarness via the install script, npm, or from source.
 ## Requirements
 
 - Linux / macOS (x64 or arm64): the install script ships platform tarballs with an official Node.js runtime bundled — no local Node needed.
+- Windows 10 or later (x64) with PowerShell 5.1+: the Windows installer ships `penguin-win32-x64.zip` with the runtime bundled — no local Node needed.
 - Other platforms, or installing via npm / from source: system Node.js >= 24.
 
 ## Script install (recommended)
@@ -16,7 +17,19 @@ On Linux / macOS:
 curl -fsSL https://penguin.ooo/install.sh | sh
 ```
 
-The script downloads the matching `penguin-{linux,darwin}-{x64,arm64}.tar.gz`, which bundles an official Node.js runtime. Other platforms do **not** fall back automatically: the script exits and asks you to install Node.js >= 24 and re-run with `--universal`, which selects the runtime-less `penguin-universal.tar.gz`.
+The script downloads the matching `penguin-{linux,darwin}-{x64,arm64}.tar.gz`, which bundles an official Node.js runtime. Other POSIX platforms do **not** fall back automatically: the script exits and asks you to install Node.js >= 24 and re-run with `--universal`, which selects the runtime-less `penguin-universal.tar.gz` (Windows is served by its own installer below, not by `--universal`).
+
+On Windows (PowerShell):
+
+```powershell
+irm https://penguin.ooo/install.ps1 | iex
+```
+
+To pin a version, set the env var first:
+
+```powershell
+$env:PENGUIN_VERSION = "vX.Y.Z"; irm https://penguin.ooo/install.ps1 | iex
+```
 
 Verify the install:
 
@@ -36,9 +49,25 @@ penguin -v
 
 Script flags go after `sh -s --`, e.g. `curl -fsSL https://penguin.ooo/install.sh | sh -s -- --universal`.
 
+### Windows specifics
+
+| Item | Details |
+| --- | --- |
+| Install dir | `%USERPROFILE%\.penguin` by default; override with the `PENGUIN_INSTALL_DIR` env var |
+| Command entry | `bin\penguin.cmd` and `bin\penguin.ps1` launchers; the installer adds `%USERPROFILE%\.penguin\bin` to your **user** Path (restart the terminal once) |
+| Version pin | `$env:PENGUIN_VERSION = "vX.Y.Z"` before running the installer |
+| 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.
+- **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.
+- If PowerShell refuses to run `penguin` with "running scripts is disabled", your execution policy blocks the `penguin.ps1` shim: either call `penguin.cmd` explicitly, or allow local scripts with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.
+
 ### Data directory
 
-The data directory defaults to `~/.penguin/data` — under the install home `~/.penguin`, but never modified by install or upgrade — and is overridable with the `PENGUIN_HOME` env var. Model configuration, Session records, and other data are preserved across upgrades.
+The data directory defaults to `~/.penguin/data` (`%USERPROFILE%\.penguin\data` on Windows) — under the install home, but never modified by install or upgrade — and is overridable with the `PENGUIN_HOME` env var. Model configuration, Session records, and other data are preserved across upgrades.
 
 ## npm install
 
@@ -48,7 +77,7 @@ Requires system Node.js >= 24:
 npm install -g @prismshadow/penguin-cli
 ```
 
-The npm package is `@prismshadow/penguin-cli`; the installed command is `penguin`. Web UI assets ship inside the `@prismshadow/penguin-server` package, so this single install yields a working `penguin web`.
+The npm package is `@prismshadow/penguin-cli`; the installed command is `penguin`. Web UI assets ship inside the `@prismshadow/penguin-server` package, so this single install yields a working `penguin web`. This route works on every platform (including Windows) and is the alternative when the packaged zip/tarball is unsuitable.
 
 ## From source
 

packages/docs/content/installation.zh.md

@@ -6,6 +6,7 @@ description: 通过安装脚本、npm 或源码安装 PenguinHarness。
 ## 系统要求
 
 - Linux / macOS（x64 或 arm64）：安装脚本提供内置官方 Node.js 运行时的平台压缩包，解压即用，无需本机安装 Node。
+- Windows 10 及以上（x64），PowerShell 5.1+：Windows 安装器提供内置运行时的 `penguin-win32-x64.zip`，同样无需本机安装 Node。
 - 其他平台，或通过 npm / 源码安装：需要系统 Node.js >= 24。
 
 ## 脚本安装（推荐）
@@ -16,7 +17,19 @@ description: 通过安装脚本、npm 或源码安装 PenguinHarness。
 curl -fsSL https://penguin.ooo/install.sh | sh
 ```
 
-脚本按平台下载 `penguin-{linux,darwin}-{x64,arm64}.tar.gz`，其中捆绑了官方 Node.js 运行时。其他平台**不会自动回退**：脚本会退出并提示先安装 Node.js >= 24、再携带 `--universal` 重新执行，改用不含运行时的 `penguin-universal.tar.gz`。
+脚本按平台下载 `penguin-{linux,darwin}-{x64,arm64}.tar.gz`，其中捆绑了官方 Node.js 运行时。其他 POSIX 平台**不会自动回退**：脚本会退出并提示先安装 Node.js >= 24、再携带 `--universal` 重新执行，改用不含运行时的 `penguin-universal.tar.gz`（Windows 使用下方专属安装器，而不是 `--universal`）。
+
+在 Windows（PowerShell）上执行：
+
+```powershell
+irm https://penguin.ooo/install.ps1 | iex
+```
+
+如需固定版本，先设置环境变量：
+
+```powershell
+$env:PENGUIN_VERSION = "vX.Y.Z"; irm https://penguin.ooo/install.ps1 | iex
+```
 
 安装完成后验证：
 
@@ -36,9 +49,25 @@ penguin -v
 
 脚本参数写在 `sh -s --` 之后，例如 `curl -fsSL https://penguin.ooo/install.sh | sh -s -- --universal`。
 
+### Windows 细节
+
+| 项目 | 说明 |
+| --- | --- |
+| 安装目录 | 默认 `%USERPROFILE%\.penguin`，可用环境变量 `PENGUIN_INSTALL_DIR` 覆盖 |
+| 命令入口 | `bin\penguin.cmd` 与 `bin\penguin.ps1` 启动器；安装器会把 `%USERPROFILE%\.penguin\bin` 加入**用户** Path（重启终端后生效） |
+| 版本固定 | 运行安装器前设置 `$env:PENGUIN_VERSION = "vX.Y.Z"` |
+| 完整性校验 | 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。
+- **Ctrl-C 语义**：Windows 上向运行中的命令会话发送 Ctrl-C（`input_command` 传 `"\u0003"`）会终止整棵命令会话进程树，而不是中断前台命令——Windows 无法向管道子进程投递控制台 Ctrl-C，中断因此退化为整树强杀。
+- **就地更新**：`penguin update` 暂不支持 Windows——升级请重新运行上面的安装器。
+- **配置文件权限**：POSIX 上配置/凭据文件以 `0600`（仅属主可读写）写入；Windows 没有对应的权限位，文件遵循你用户目录的默认 NTFS ACL。
+- 如果 PowerShell 提示 "running scripts is disabled" 而无法运行 `penguin`，是执行策略拦住了 `penguin.ps1`：可以显式调用 `penguin.cmd`，或用 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` 允许本地脚本。
+
 ### 数据目录
 
-数据目录默认位于 `~/.penguin/data`（在安装主目录 `~/.penguin` 之下，但安装与升级都不会改动它），可用环境变量 `PENGUIN_HOME` 覆盖。模型配置、Session 记录等在升级后均会保留。
+数据目录默认位于 `~/.penguin/data`（Windows 为 `%USERPROFILE%\.penguin\data`），在安装主目录之下，但安装与升级都不会改动它，可用环境变量 `PENGUIN_HOME` 覆盖。模型配置、Session 记录等在升级后均会保留。
 
 ## npm 安装
 
@@ -48,7 +77,7 @@ penguin -v
 npm install -g @prismshadow/penguin-cli
 ```
 
-npm 包名为 `@prismshadow/penguin-cli`，安装后的命令是 `penguin`。Web UI 静态资源随 `@prismshadow/penguin-server` 包发布，因此仅执行上述命令即可直接使用 `penguin web`。
+npm 包名为 `@prismshadow/penguin-cli`，安装后的命令是 `penguin`。Web UI 静态资源随 `@prismshadow/penguin-server` 包发布，因此仅执行上述命令即可直接使用 `penguin web`。该方式在所有平台（含 Windows）可用，是压缩包不适用时的替代路径。
 
 ## 源码安装
 

packages/docs/content/tools.en.md

@@ -116,6 +116,8 @@ Both tools' arguments (explicit keys):
 }
 ```
 
+On POSIX, Ctrl-C sends `SIGINT` to the session's process group, interrupting the foreground command. On Windows there is no console signal delivery to a piped child process, so Ctrl-C degrades to a hard kill of the whole command session tree (`taskkill /t /f`) — the foreground command and every child it started terminate, instead of the foreground command being interrupted.
+
 ### File tools
 
 `read_file` / `edit_file` / `write_file` run with the user's full permissions, same as the shell tool; relative paths resolve against the Workspace and absolute paths are allowed. They are non-streaming (a single final output) and never throw — failures come back as explanatory text with `stop_reason: failed`.

packages/docs/content/tools.zh.md

@@ -115,6 +115,8 @@ exec_command(cmd)
 }
 ```
 
+POSIX 上 Ctrl-C 向会话进程组发送 `SIGINT`，中断前台命令。Windows 无法向管道子进程投递控制台信号，Ctrl-C 因此退化为整棵命令会话进程树的强杀（`taskkill /t /f`）——前台命令及其启动的所有子进程一并终止，而不是仅中断前台命令。
+
 ### 文件工具
 
 `read_file` / `edit_file` / `write_file` 与 Shell 工具一样以用户完整权限运行：相对路径按 Workspace 解析，也接受绝对路径。三者均为非流式（一次性输出最终结果），从不抛异常——失败以解释性文本收尾，`stop_reason` 为 `failed`。

packages/landing/public/install.ps1

@@ -0,0 +1,33 @@
+# https://penguin.ooo/install.ps1 - PenguinHarness installer entry point for Windows.
+#
+# GitHub Pages cannot serve HTTP redirects, so this thin forwarder IS the
+# stable install URL: it fetches the real installer attached to the latest
+# GitHub release and runs it, forwarding every argument it was given. Usage:
+#
+#   irm https://penguin.ooo/install.ps1 | iex
+#   & ([scriptblock]::Create((irm https://penguin.ooo/install.ps1))) -Version v0.2.0
+#
+$ErrorActionPreference = "Stop"
+$ProgressPreference = "SilentlyContinue"
+try {
+  [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+} catch {
+  # .NET builds where the enum is immutable already default to TLS 1.2+.
+}
+# Download fully first, then run: executing a piped stream directly would run a
+# truncated download line by line, and the real installer moves the old
+# bin/lib/web/node aside before moving the new ones in - a cut connection
+# mid-way must never leave a half-executed installer. The installer runs as an
+# in-memory script block (not a script file): script files are subject to the
+# execution policy, which is Restricted by default on client Windows - while the
+# user has already consented to remote code by piping this forwarder into iex.
+# Neither this forwarder nor the installer calls `exit`, which in iex/script-block
+# context would terminate the user's whole PowerShell session.
+$Tmp = Join-Path ([IO.Path]::GetTempPath()) "penguin-install-$PID.ps1"
+try {
+  Invoke-WebRequest -Uri "https://github.com/Prism-Shadow/penguin-harness/releases/latest/download/install.ps1" -OutFile $Tmp -UseBasicParsing
+  $Installer = [scriptblock]::Create((Get-Content -Path $Tmp -Raw))
+  & $Installer @args
+} finally {
+  Remove-Item -Force $Tmp -ErrorAction SilentlyContinue
+}

packages/landing/src/lib/links.ts

@@ -18,6 +18,12 @@ export const DOCS_URL = `${import.meta.env.BASE_URL}docs/`;
  */
 export const INSTALL_CMD = "curl -fsSL https://penguin.ooo/install.sh | sh";
 
+/**
+ * One-line installer for Windows (PowerShell 5.1+, x64, bundled Node runtime).
+ * penguin.ooo/install.ps1 is public/install.ps1 — the same thin-forwarder design.
+ */
+export const INSTALL_CMD_WINDOWS = "irm https://penguin.ooo/install.ps1 | iex";
+
 /**
  * Demo videos live in the sibling `penguin-harness-community` repo rather than in this
  * one: they are ~9 MB each, and this repo's whole history is ~17 MB, so committing them

packages/landing/src/lib/strings-en.ts

@@ -59,7 +59,9 @@ export const en: Strings = {
     ctaPrimary: "Get started",
     ctaGithub: "GitHub",
     installHint:
-      "One-line install (Linux / macOS, x64 / arm64, bundled Node runtime — unpack and run)",
+      "One-line install (Linux / macOS / Windows, bundled Node runtime — unpack and run)",
+    installLabelPosix: "Linux / macOS",
+    installLabelWindows: "Windows",
     stats: [
       { value: "1000+", label: "supported models" },
       { value: "1×CPU", label: "minimum footprint" },
@@ -155,7 +157,9 @@ export const en: Strings = {
       "Install with one command and let the Agent work from a desktop-grade interface — all data stays in your local ~/.penguin/data directory.",
     step1: "Install",
     step1Desc:
-      "Linux / macOS (x64 / arm64) with a bundled Node runtime — unpack and run; upgrades never touch your data.",
+      "Linux / macOS / Windows with a bundled Node runtime — unpack and run; upgrades never touch your data.",
+    installLabelPosix: "Linux / macOS",
+    installLabelWindows: "Windows (PowerShell)",
     tabWeb: "Web UI",
     tabCli: "CLI",
     webStep2: "Open the web interface",

packages/landing/src/lib/strings.ts

@@ -63,7 +63,9 @@ export const zh = {
     keywords: ["轻量", "高效", "开源"],
     ctaPrimary: "快速开始",
     ctaGithub: "GitHub",
-    installHint: "一行命令安装（Linux / macOS，x64 / arm64，内嵌 Node 运行时，解压即用）",
+    installHint: "一行命令安装（Linux / macOS / Windows，内嵌 Node 运行时，解压即用）",
+    installLabelPosix: "Linux / macOS",
+    installLabelWindows: "Windows",
     stats: [
       { value: "1000+", label: "支持模型数量" },
       { value: "1×CPU", label: "最低运行配置" },
@@ -156,8 +158,9 @@ export const zh = {
     subtitle:
       "一行命令安装，打开桌面级界面即可让 Agent 开始工作；数据全部保存在本地 ~/.penguin/data 目录。",
     step1: "安装",
-    step1Desc:
-      "Linux / macOS（x64 / arm64），产物内嵌 Node 运行时，解压即用；升级与重装不触碰数据。",
+    step1Desc: "Linux / macOS / Windows，产物内嵌 Node 运行时，解压即用；升级与重装不触碰数据。",
+    installLabelPosix: "Linux / macOS",
+    installLabelWindows: "Windows（PowerShell）",
     tabWeb: "Web 界面",
     tabCli: "命令行",
     webStep2: "启动 Web 界面",

packages/landing/src/sections/hero.tsx

@@ -7,7 +7,7 @@
 import { Fragment, useEffect, useState } from "react";
 import { Link } from "react-router";
 import { S } from "../lib/strings";
-import { INSTALL_CMD, REPO_URL } from "../lib/links";
+import { INSTALL_CMD, INSTALL_CMD_WINDOWS, REPO_URL } from "../lib/links";
 import { CopyButton } from "../components/copy-button";
 import { ArrowRightIcon, GitHubIcon } from "../components/icons";
 
@@ -115,12 +115,28 @@ export function Hero() {
           className="anim-rise mx-auto mt-10 w-fit max-w-full"
           style={{ animationDelay: "240ms" }}
         >
-          <div className="flex items-center gap-3 overflow-hidden rounded-xl border border-gray-200 bg-gray-50 py-2.5 pr-2.5 pl-4 text-left dark:border-gray-800 dark:bg-gray-900">
-            <code className="min-w-0 flex-1 overflow-x-auto font-mono text-[13px] whitespace-nowrap text-gray-800 dark:text-gray-200">
-              <span className="mr-2 text-gray-400 select-none dark:text-gray-500">$</span>
-              {INSTALL_CMD}
-            </code>
-            <CopyButton text={INSTALL_CMD} className="shrink-0" />
+          {/* One install row per OS (labels are language-neutral; prompt chars $ vs > match the shells). */}
+          <div className="overflow-hidden rounded-xl border border-gray-200 bg-gray-50 text-left dark:border-gray-800 dark:bg-gray-900">
+            <div className="flex items-center gap-3 py-2.5 pr-2.5 pl-4">
+              <span className="w-24 shrink-0 text-[11px] font-medium text-gray-400 dark:text-gray-500">
+                {S.hero.installLabelPosix}
+              </span>
+              <code className="min-w-0 flex-1 overflow-x-auto font-mono text-[13px] whitespace-nowrap text-gray-800 dark:text-gray-200">
+                <span className="mr-2 text-gray-400 select-none dark:text-gray-500">$</span>
+                {INSTALL_CMD}
+              </code>
+              <CopyButton text={INSTALL_CMD} className="shrink-0" />
+            </div>
+            <div className="flex items-center gap-3 border-t border-gray-200 py-2.5 pr-2.5 pl-4 dark:border-gray-800">
+              <span className="w-24 shrink-0 text-[11px] font-medium text-gray-400 dark:text-gray-500">
+                {S.hero.installLabelWindows}
+              </span>
+              <code className="min-w-0 flex-1 overflow-x-auto font-mono text-[13px] whitespace-nowrap text-gray-800 dark:text-gray-200">
+                <span className="mr-2 text-gray-400 select-none dark:text-gray-500">&gt;</span>
+                {INSTALL_CMD_WINDOWS}
+              </code>
+              <CopyButton text={INSTALL_CMD_WINDOWS} className="shrink-0" />
+            </div>
           </div>
           <p className="mt-2 text-xs text-gray-500 dark:text-gray-400">{S.hero.installHint}</p>
         </div>

packages/landing/src/sections/quickstart.tsx

@@ -7,7 +7,12 @@
 import { useState } from "react";
 import type { ReactNode } from "react";
 import { S } from "../lib/strings";
-import { DEEPSEEK_KEYS_URL, INSTALL_CMD, OPENROUTER_KEYS_URL } from "../lib/links";
+import {
+  DEEPSEEK_KEYS_URL,
+  INSTALL_CMD,
+  INSTALL_CMD_WINDOWS,
+  OPENROUTER_KEYS_URL,
+} from "../lib/links";
 import { Section } from "../components/section";
 import { CodeCard } from "../components/code-card";
 import {
@@ -125,7 +130,12 @@ export function Quickstart() {
             title={S.quickstart.step1}
             desc={S.quickstart.step1Desc}
           >
-            <CodeCard code={INSTALL_CMD} label="install" />
+            <CodeCard code={INSTALL_CMD} label={S.quickstart.installLabelPosix} />
+            <CodeCard
+              code={INSTALL_CMD_WINDOWS}
+              label={S.quickstart.installLabelWindows}
+              className="mt-2"
+            />
           </Step>
 
           {mode === "web" ? (

packages/server/package.json

@@ -25,7 +25,7 @@
     "node": ">=24"
   },
   "scripts": {
-    "dev": "node ../../scripts/dev-prebuild.mjs && PENGUIN_HOME=\"${PENGUIN_HOME:-$HOME/.penguin/dev-data}\" tsx watch src/index.ts",
+    "dev": "node ../../scripts/dev-prebuild.mjs && node ../../scripts/run-with-env.mjs PENGUIN_HOME=~/.penguin/dev-data -- tsx watch src/index.ts",
     "start": "node --disable-warning=ExperimentalWarning dist/index.js",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --passWithNoTests",

packages/server/src/services/workspace-files-service.ts

@@ -262,6 +262,15 @@ export class WorkspaceFilesService {
     }
     const { dir, name } = await this.resolveWriteParent(workspace, rel);
     const file = path.join(dir, name);
+    // Windows has no O_NOFOLLOW (the `?? 0` below erases it), so the atomic ELOOP guard never
+    // fires there — refuse a final-segment symlink via lstat instead. Best effort (a link
+    // created between this check and the open wins the race), but it closes the practical
+    // "preset a symlink, overwrite an outside file by upload" escape; POSIX keeps the atomic
+    // open-time guarantee.
+    if (process.platform === "win32") {
+      const st = await fs.lstat(file).catch(() => null);
+      if (st?.isSymbolicLink()) throw badRequest("path must not be a symlink.");
+    }
     // O_NOFOLLOW: open reports ELOOP if the final segment is a symlink, refusing to use it as leverage to overwrite a file outside the sandbox.
     const flags = fsc.O_WRONLY | fsc.O_CREAT | fsc.O_TRUNC | (fsc.O_NOFOLLOW ?? 0);
     let handle;

packages/server/test/models.test.ts

@@ -82,7 +82,10 @@ describe("models preset & catalog enrichment", () => {
     expect(cfgRaw).toContain('provider = "custom"');
     expect(cfgRaw).toContain('model_id = "m-inline"');
     expect(cfgRaw).not.toContain("custom/m-inline");
-    expect((await stat(cfgFile)).mode & 0o777).toBe(0o600);
+    // POSIX-only: Windows has no owner-only mode bits (chmod maps to the read-only attribute).
+    if (process.platform !== "win32") {
+      expect((await stat(cfgFile)).mode & 0o777).toBe(0o600);
+    }
     // No more separate .credentials.toml / project_config.toml files.
     await expect(readFile(path.join(projectDir, ".credentials.toml"), "utf8")).rejects.toThrow();
     await expect(readFile(path.join(projectDir, "project_config.toml"), "utf8")).rejects.toThrow();

packages/web/e2e/README.md

@@ -12,3 +12,8 @@ SKIP_BUILD=1 pnpm --filter @prismshadow/penguin-web test:e2e   # skip the build
 ```
 
 The first run requires `npx playwright install chromium`.
+
+The runner (`run.sh`) is POSIX-only and deliberately stays that way: `pnpm test` never
+invokes it (only the separate `test:e2e` script does), so a Windows checkout builds and
+tests fine without it. To run the browser e2e on Windows, use Git-Bash
+(`bash e2e/run.sh` from `packages/web`).