Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

27.6 KB
Raw Blame
import { describe, it, expect, vi } from "vitest";
import os from "node:os";
import path from "node:path";
import fs from "node:fs/promises";
import { createHash } from "node:crypto";
import {
  SandboxExecutor,
  augmentPath,
  buildSandboxEnv,
  buildShellInvocation,
  decodeProcessOutput,
  DEFAULT_SANDBOX_TIMEOUT_MS,
  defaultShellForPlatform,
  killProcessTree,
} from "../src/sandbox/executor.js";

const TEST_NODE = process.env.ORKAS_TEST_NODE || process.execPath;
const IS_WINDOWS = process.platform === "win32";
const NATIVE_SHELL_STARTUP_BUDGET_MS = IS_WINDOWS ? 15_000 : 5_000;
const NATIVE_SHELL_TEST_TIMEOUT_MS = IS_WINDOWS ? 25_000 : 10_000;

function shellQuote(value: string): string {
  return IS_WINDOWS
    ? `'${value.replace(/'/g, "''")}'`
    : `'${value.replace(/'/g, "'\\''")}'`;
}

function nodeEvalCommand(script: string): string {
  const invocation = `${shellQuote(TEST_NODE)} -e ${shellQuote(script)}`;
  return IS_WINDOWS ? `& ${invocation}` : invocation;
}

async function waitForProcessExit(pid: number, timeoutMs = 5_000): Promise<void> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    try { process.kill(pid, 0); }
    catch { return; }
    await new Promise((resolve) => setTimeout(resolve, 25));
  }
  throw new Error(`process ${pid} did not exit within ${timeoutMs}ms`);
}

async function removeTree(dir: string): Promise<void> {
  await fs.rm(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
}

describe("SandboxExecutor", () => {
  it("defaults command execution to the long bash timeout", () => {
    expect(DEFAULT_SANDBOX_TIMEOUT_MS).toBe(60 * 60_000);
  });

  it("executes a simple command", async () => {
    const sandbox = new SandboxExecutor({ workingDir: os.tmpdir() });
    const result = await sandbox.execute("echo hello");
    expect(result.stdout.trim()).toBe("hello");
    expect(result.exitCode).toBe(0);
    expect(result.startFailed).toBe(false);
    expect(result.timedOut).toBe(false);
  });

  it("contains synchronous shell start failures as a non-executed command result", async () => {
    const sandbox = new SandboxExecutor({
      workingDir: os.tmpdir(),
      shell: "invalid\0shell",
    });

    const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
    let result;
    try {
      result = await sandbox.execute("echo must-not-run");
      expect(warning).toHaveBeenCalledWith("[sandbox]", "Shell process failed to start", expect.objectContaining({
        command_hash: createHash("sha256").update("echo must-not-run").digest("hex").slice(0, 12),
        error_code: "ERR_INVALID_ARG_VALUE", phase: "spawn", platform: process.platform,
      }));
      expect(JSON.stringify(warning.mock.calls)).not.toContain("invalid");
      expect(JSON.stringify(warning.mock.calls)).not.toContain("echo must-not-run");
    } finally {
      warning.mockRestore();
    }

    expect(result).toMatchObject({
      stdout: "",
      exitCode: null,
      startFailed: true,
      timedOut: false,
      outputLimitExceeded: false,
      stdoutBytes: 0,
    });
    expect(result.stderr).toContain("Failed to start shell process");
    expect(result.stderrBytes).toBe(Buffer.byteLength(result.stderr));
  });

  it("contains asynchronous shell start failures without exposing the shell path", async () => {
    const missingShell = path.join(os.tmpdir(), `missing-shell-${process.pid}-${Date.now()}`);
    const sandbox = new SandboxExecutor({
      workingDir: os.tmpdir(),
      shell: missingShell,
    });

    const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
    let result;
    try {
      result = await sandbox.execute("echo must-not-run");
      expect(warning).toHaveBeenCalledWith("[sandbox]", "Shell process failed to start", expect.objectContaining({
        command_hash: createHash("sha256").update("echo must-not-run").digest("hex").slice(0, 12),
        error_code: "ENOENT", phase: "spawn", platform: process.platform,
      }));
      expect(JSON.stringify(warning.mock.calls)).not.toContain(missingShell);
    } finally {
      warning.mockRestore();
    }

    expect(result).toMatchObject({
      stdout: "",
      exitCode: null,
      startFailed: true,
      timedOut: false,
      outputLimitExceeded: false,
    });
    expect(result.stderr).toContain("Failed to start shell process (ENOENT)");
    expect(result.stderr).toContain("The command was not executed");
    expect(result.stderr).not.toContain(missingShell);
  });

  it("captures stderr", async () => {
    const sandbox = new SandboxExecutor({ workingDir: os.tmpdir() });
    const result = await sandbox.execute(nodeEvalCommand("process.stderr.write('error')"));
    expect(result.stderr.trim()).toBe("error");
  });

  it("returns non-zero exit code for failing commands", async () => {
    const sandbox = new SandboxExecutor({ workingDir: os.tmpdir() });
    const result = await sandbox.execute("exit 42");
    expect(result.exitCode).toBe(42);
  });

  it("enforces timeout", async () => {
    const sandbox = new SandboxExecutor({
      workingDir: os.tmpdir(),
      timeoutMs: 500,
    });
    const result = await sandbox.execute(nodeEvalCommand("setTimeout(() => {}, 10_000)"));
    expect(result.timedOut).toBe(true);
  }, 10000);

  it("times out commands whose background child keeps stdout open", async () => {
    const script = [
      "const { spawn } = require('node:child_process');",
      "spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'inherit' });",
      "console.log('parent done');",
    ].join("");
    const sandbox = new SandboxExecutor({
      workingDir: os.tmpdir(),
      timeoutMs: 500,
    });
    const started = Date.now();
    const result = await sandbox.execute(nodeEvalCommand(script));
    expect(result.timedOut).toBe(true);
    expect(Date.now() - started).toBeLessThan(5000);
  }, 10000);

  it.runIf(!IS_WINDOWS).each([false, true])("releases escaped-descendant pipes without losing captured output (spooled: %s)", async (spooled) => {
    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-escaped-pipes-"));
    const marker = path.join(dir, "owned-pid.json");
    const pipes = () => process.getActiveResourcesInfo().filter((kind) => kind === "PipeWrap").length;
    const baseline = pipes();
    const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
    let pid = 0;
    let stop: (() => void) | undefined;
    let output = "";
    const stdout = `READY${"x".repeat(256)}`;
    const stderr = "e".repeat(256);
    const descendant = `require('fs').writeFileSync(${JSON.stringify(marker)},JSON.stringify({pid:process.pid}));process.stderr.write(${JSON.stringify(stderr)});process.stdout.write(${JSON.stringify(stdout)});setTimeout(()=>process.exit(0),20000)`;
    const parent = `require('child_process').spawn(process.execPath,['-e',${JSON.stringify(descendant)}],{detached:true,stdio:'inherit'});`;
    try {
      const result = await new SandboxExecutor({
        workingDir: dir, timeoutMs: 15_000, maxOutputBytes: spooled ? 16 : 1024,
        ...(spooled ? { outputSpoolDir: path.join(dir, "spool") } : {}),
      })
        .execute(nodeEvalCommand(parent), {
          onStart(control) { stop = control.stop; },
          onOutput(bytes) {
            output += bytes.toString("utf8");
            if (output.includes("READY")) stop?.();
          },
        });
      pid = JSON.parse(await fs.readFile(marker, "utf8")).pid;
      expect(result.aborted).toBe(true);
      expect(result.stdout).toContain("READY");
      expect(result).toMatchObject({ stdoutBytes: Buffer.byteLength(stdout), stderrBytes: Buffer.byteLength(stderr) });
      if (spooled) {
        await expect(fs.readFile(result.stdoutStreamedOutput!.path, "utf8")).resolves.toBe(stdout);
        await expect(fs.readFile(result.stderrStreamedOutput!.path, "utf8")).resolves.toBe(stderr);
        expect(result.stdoutStreamedOutput?.sourceTruncated).toBeUndefined();
        expect(result.stderrStreamedOutput?.sourceTruncated).toBeUndefined();
      } else {
        expect(result.stdout).toBe(stdout);
        expect(result.stderr).toBe(stderr);
      }
      // Group cleanup cannot certify an escaped process's exit. Keep that
      // limitation visible while independently checking host handle release.
      expect(() => process.kill(pid, 0)).not.toThrow();
      await expect.poll(pipes, { timeout: 1_000 }).toBe(baseline);
      expect(warning).toHaveBeenCalledExactlyOnceWith("[sandbox]", "Shell process cleanup was not confirmed", {
        platform: process.platform, phase: "cleanup_deadline",
        root_exit_observed: true, stdout_open: true, stderr_open: true,
      });
    } finally {
      warning.mockRestore();
      if (!pid) {
        try { pid = JSON.parse(await fs.readFile(marker, "utf8")).pid; } catch { /* No child started. */ }
      }
      if (pid) {
        try { process.kill(pid, "SIGKILL"); } catch { /* Already exited. */ }
        await waitForProcessExit(pid);
      }
      await removeTree(dir);
    }
  }, 15_000);

  it("blocks dangerous commands", async () => {
    const sandbox = new SandboxExecutor({ workingDir: os.tmpdir() });
    const result = await sandbox.execute("rm -rf /");
    expect(result.exitCode).toBe(1);
    expect(result.stderr).toContain("blocked");
  });

  it.each([
    "printf '%s\\n' shutdown", "echo reboot", "rg shutdown README.md",
    "redis-cli -p 6379 shutdown nosave", "cat docs/shutdown.md",
    "printf '%s\\n' 'rm -rf /'", "echo init 0", "echo mkfs.ext4",
    "echo shutdown | cat", "cat < /dev/sda",
  ])("does not mistake literal arguments for blocked execution: %s", (command) => {
    const sandbox = new SandboxExecutor({ workingDir: os.tmpdir() });
    // Check admission without executing service mutations or destructive commands.
    expect((sandbox as any).checkBlockedCommand(command)).toBeNull();
  });

  it.each([
    "shutdown -h now", "/sbin/reboot", "halt", "mkfs.ext4 /dev/example",
    "rm -rf /", "rm -rf /*", "dd if=/dev/zero of=/dev/example",
    "chmod -R 777 /", "init 0", "init 6", "echo test > /dev/sda",
    "echo ready; shutdown -h now", "echo ready && reboot", "echo ready | halt",
    '"shut""down" -h now', "sudo shutdown -h now", "env X=1 reboot",
    "sh -c 'shutdown -h now'", 'echo "$(shutdown -h now)"',
    "python -c 'import os; os.system(\"shutdown -h now\")'",
    ":(){ :|:& };:", "! reboot", "su -c shutdown", "ssh host shutdown",
    "X=1 /sbin/shutdown", '"C:\\Windows\\System32\\shutdown.exe" /s',
  ])("retains dangerous and opaque command denial: %s", (command) => {
    const sandbox = new SandboxExecutor({ workingDir: os.tmpdir() });
    expect((sandbox as any).checkBlockedCommand(command)).not.toBeNull();
  });

  it("prints a blocked command name as data in foreground and detached execution", async () => {
    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-literal-"));
    const sandbox = new SandboxExecutor({ workingDir: dir });
    const command = "echo shutdown";
    try {
      const foreground = await sandbox.execute(command);
      expect(foreground.exitCode).toBe(0);
      expect(foreground.stdout.trim()).toBe("shutdown");
      const logPath = path.join(dir, "output.log");
      const background = sandbox.executeBackground(command, logPath);
      expect(background.error).toBeUndefined();
      expect(background.pid).toBeGreaterThan(0);
      await expect.poll(async () => (await fs.readFile(logPath, "utf8")).trim()).toBe("shutdown");
      await waitForProcessExit(background.pid!);
    } finally { await removeTree(dir); }
  }, NATIVE_SHELL_TEST_TIMEOUT_MS);

  it("blocks custom commands", async () => {
    const sandbox = new SandboxExecutor({
      workingDir: os.tmpdir(),
      blockedCommands: ["curl"],
    });
    const result = await sandbox.execute("curl http://example.com");
    expect(result.exitCode).toBe(1);
    expect(result.stderr).toContain("blocked");
  });

  it("enforces output size limit", async () => {
    const sandbox = new SandboxExecutor({
      workingDir: os.tmpdir(),
      maxOutputBytes: 100,
    });
    // Generate more than 100 bytes of output
    const result = await sandbox.execute(nodeEvalCommand("process.stdout.write('x'.repeat(1_000))"));
    expect(result.outputLimitExceeded).toBe(true);
    expect(result.stdout).toContain("[output truncated by sandbox]");
  });

  it("streams output beyond the memory limit to a complete spool file", async () => {
    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-spool-test-"));
    const output = "x".repeat(1_000);
    try {
      const sandbox = new SandboxExecutor({
        workingDir: tmpDir,
        maxOutputBytes: 100,
        outputSpoolDir: path.join(tmpDir, "results"),
        maxSpoolBytes: 5_000,
      });
      const script = `process.stdout.write('x'.repeat(${output.length}))`;
      const result = await sandbox.execute(nodeEvalCommand(script));

      expect(result.stderr).toBe("");
      expect(result.exitCode).toBe(0);
      expect(result.outputLimitExceeded).toBe(false);
      expect(result.stdoutBytes).toBe(Buffer.byteLength(output));
      expect(result.stdout).toContain("full output streamed to Result Store");
      expect(result.stdoutStreamedOutput).toMatchObject({
        size: Buffer.byteLength(output),
      });
      expect(result.stdoutStreamedOutput?.sourceTruncated).toBeUndefined();
      await expect(fs.readFile(result.stdoutStreamedOutput!.path, "utf8")).resolves.toBe(output);
    } finally {
      await removeTree(tmpDir);
    }
  });

  it("marks the stored prefix incomplete only at the hard spool limit", async () => {
    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-spool-cap-test-"));
    try {
      const sandbox = new SandboxExecutor({
        workingDir: tmpDir,
        maxOutputBytes: 100,
        outputSpoolDir: path.join(tmpDir, "results"),
        maxSpoolBytes: 500,
      });
      const script = "process.stdout.write('x'.repeat(1_000))";
      const result = await sandbox.execute(nodeEvalCommand(script));

      expect(result.stderr).toBe("");
      expect(result.outputLimitExceeded).toBe(true);
      expect(result.stdoutBytes).toBe(500);
      expect(result.stdout).toContain("stored prefix is incomplete");
      expect(result.stdoutStreamedOutput).toMatchObject({
        size: 500,
        sourceTruncated: true,
      });
      await expect(fs.stat(result.stdoutStreamedOutput!.path)).resolves.toMatchObject({ size: 500 });
    } finally {
      await removeTree(tmpDir);
    }
  });

  it("uses correct working directory", async () => {
    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-test-"));
    await fs.writeFile(path.join(tmpDir, "marker.txt"), "found");

    const sandbox = new SandboxExecutor({ workingDir: tmpDir });
    const result = await sandbox.execute(nodeEvalCommand("process.stdout.write(require('node:fs').readFileSync('marker.txt', 'utf8'))"));
    expect(result.stdout.trim()).toBe("found");

    await removeTree(tmpDir);
  });

  it("uses allowedDirs as a macOS write sandbox when sandbox-exec is available", async () => {
    if (process.platform !== "darwin") return;
    try { await fs.access("/usr/bin/sandbox-exec"); }
    catch { return; }

    const allowedDir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-allowed-"));
    const deniedDir = await fs.mkdtemp(path.join(process.cwd(), ".sandbox-denied-"));
    try {
      const allowedFile = path.join(allowedDir, "ok.txt");
      const deniedFile = path.join(deniedDir, "blocked.txt");
      const script = [
        "const fs = require('node:fs');",
        `fs.writeFileSync(${JSON.stringify(allowedFile)}, 'ok');`,
        `fs.writeFileSync(${JSON.stringify(deniedFile)}, 'blocked');`,
      ].join("");
      const sandbox = new SandboxExecutor({
        workingDir: allowedDir,
        allowedDirs: [allowedDir],
      });
      const result = await sandbox.execute(nodeEvalCommand(script));
      expect(result.exitCode).not.toBe(0);
      await expect(fs.readFile(allowedFile, "utf8")).resolves.toBe("ok");
      await expect(fs.access(deniedFile)).rejects.toThrow();
    } finally {
      await removeTree(allowedDir);
      await removeTree(deniedDir);
    }
  });

  it("passes custom environment variables", async () => {
    const sandbox = new SandboxExecutor({
      workingDir: os.tmpdir(),
      env: { MY_VAR: "test_value" },
    });
    const result = await sandbox.execute(nodeEvalCommand("process.stdout.write(process.env.MY_VAR || '')"));
    expect(result.stdout.trim()).toBe("test_value");
  });

  it("reports duration", async () => {
    const sandbox = new SandboxExecutor({ workingDir: os.tmpdir() });
    const result = await sandbox.execute("echo fast");
    expect(result.durationMs).toBeGreaterThanOrEqual(0);
    expect(result.durationMs).toBeLessThan(NATIVE_SHELL_STARTUP_BUDGET_MS);
  }, NATIVE_SHELL_TEST_TIMEOUT_MS);
});

describe("killProcessTree", () => {
  it("uses bounded native Windows tree cleanup and reports fallback failure", () => {
    const callbacks = new Map<string, (...args: any[]) => void>();
    const killer = {
      once: vi.fn((event: string, cb: (...args: any[]) => void) => {
        callbacks.set(event, cb);
        return killer;
      }),
      unref: vi.fn(),
    };
    const spawnFn = vi.fn(() => killer);
    const child = { pid: 1234, kill: vi.fn() };

    killProcessTree(child as any, "SIGTERM", {
      platform: "win32",
      spawnFn: spawnFn as any,
    });

    expect(String(spawnFn.mock.calls[0][0]).toLowerCase()).toMatch(/powershell\.exe$/);
    expect(spawnFn).toHaveBeenCalledWith(expect.any(String), expect.arrayContaining(["-NoProfile", "-EncodedCommand"]), {
      stdio: ["pipe", "pipe", "ignore"],
      windowsHide: true,
      timeout: 5_000,
    });
    expect(killer.unref).toHaveBeenCalled();
    expect(child.kill).not.toHaveBeenCalled();

    const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
    try {
      callbacks.get("close")?.(1);
      expect(child.kill).toHaveBeenCalledWith("SIGTERM");
      expect(warning).toHaveBeenCalledWith("[sandbox]", "Shell process tree termination failed", {
        platform: "win32", fallback: "direct_child_only",
      });
    } finally { warning.mockRestore(); }
  });

  it("kills POSIX process groups when a pid is available", () => {
    const child = { pid: 4321, kill: vi.fn() };
    const processKill = vi.fn();

    killProcessTree(child as any, "SIGKILL", {
      platform: "linux",
      processKill: processKill as any,
    });

    expect(processKill).toHaveBeenCalledWith(-4321, "SIGKILL");
    expect(child.kill).not.toHaveBeenCalled();
  });
});

describe("augmentPath", () => {
  it("prepends /opt/homebrew/bin when it's missing (Apple Silicon case)", () => {
    const out = augmentPath("/usr/bin:/bin", "darwin", {});
    expect(out.split(":")).toContain("/opt/homebrew/bin");
    expect(out.indexOf("/opt/homebrew/bin")).toBeLessThan(out.indexOf("/usr/bin"));
  });

  it("does not duplicate entries that are already present", () => {
    const input = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
    const out = augmentPath(input, "darwin", {});
    const homebrewCount = out.split(":").filter((p) => p === "/opt/homebrew/bin").length;
    expect(homebrewCount).toBe(1);
  });

  it("preserves user-supplied entries verbatim", () => {
    const input = "/Users/me/bin:/usr/bin";
    const out = augmentPath(input, "darwin", {});
    expect(out.split(":")).toContain("/Users/me/bin");
    expect(out.split(":")).toContain("/usr/bin");
  });

  it("falls back to canonical list when input is empty/undefined", () => {
    const out = augmentPath(undefined, "darwin", {});
    expect(out.split(":")).toContain("/opt/homebrew/bin");
    expect(out.split(":")).toContain("/usr/local/bin");
    expect(out.split(":")).toContain("/usr/bin");
  });

  it("adds common Google Cloud SDK install locations on POSIX", () => {
    const out = augmentPath("/usr/bin:/bin", "darwin", { HOME: "/Users/me" });
    const parts = out.split(":");
    expect(parts).toContain("/opt/homebrew/share/google-cloud-sdk/bin");
    expect(parts).toContain("/usr/local/share/google-cloud-sdk/bin");
    expect(parts).toContain("/Users/me/google-cloud-sdk/bin");
  });

  it("adds user-level CLI install locations on POSIX", () => {
    const out = augmentPath("/usr/bin:/bin", "darwin", { HOME: "/Users/me" });
    const parts = out.split(":");

    expect(parts).toContain("/Users/me/.local/bin");
    expect(parts).toContain("/Users/me/.npm-global/bin");
    expect(parts).toContain("/Users/me/bin");
    expect(parts.indexOf("/Users/me/.local/bin")).toBeLessThan(parts.indexOf("/opt/homebrew/bin"));
  });

  it("keeps user-supplied entries BEFORE canonical ones when the user put them first", () => {
    // /Users/me/tools/bin is user-custom; it must remain ahead of the
    // canonical /usr/bin entry that already existed in the input.
    const input = "/Users/me/tools/bin:/usr/bin";
    const out = augmentPath(input).split(":");
    expect(out.indexOf("/Users/me/tools/bin")).toBeLessThan(out.indexOf("/usr/bin"));
  });

  it("uses Windows PATH delimiters without splitting drive letters", () => {
    const input = "D:\\Tools\\bin;C:\\Windows\\System32";
    const out = augmentPath(input, "win32", { SystemRoot: "C:\\Windows" });
    const parts = out.split(";");
    expect(parts).toContain("D:\\Tools\\bin");
    expect(parts).toContain("C:\\Windows\\System32");
    expect(parts).not.toContain("D");
    expect(parts).not.toContain("\\Tools\\bin");
  });

  it("adds common Windows tool and shim locations", () => {
    const out = augmentPath("C:\\Windows\\System32", "win32", {
      SystemRoot: "C:\\Windows",
      ProgramFiles: "C:\\Program Files",
      "ProgramFiles(x86)": "C:\\Program Files (x86)",
      APPDATA: "C:\\Users\\me\\AppData\\Roaming",
      LOCALAPPDATA: "C:\\Users\\me\\AppData\\Local",
    });
    const parts = out.split(";");
    expect(parts).toContain("C:\\Program Files\\nodejs");
    expect(parts).toContain("C:\\Program Files (x86)\\nodejs");
    expect(parts).toContain("C:\\Users\\me\\AppData\\Roaming\\npm");
    expect(parts).toContain("C:\\Users\\me\\AppData\\Local\\npm");
    expect(parts).toContain("C:\\Users\\me\\AppData\\Local\\Programs\\nodejs");
    expect(parts).toContain("C:\\Program Files\\Git\\cmd");
    expect(parts).toContain("C:\\Program Files\\Git\\bin");
    expect(parts).toContain("C:\\Users\\me\\AppData\\Local\\Programs\\Git\\cmd");
    expect(parts).toContain("C:\\Users\\me\\AppData\\Local\\Programs\\OpenAI\\Codex\\bin");
  });

  it("defaults Windows Python subprocesses to UTF-8 stdio", () => {
    const env = buildSandboxEnv(undefined, "win32");
    expect(env.PYTHONIOENCODING).toBe("utf-8");
    expect(env.PYTHONUTF8).toBe("1");

    const overridden = buildSandboxEnv({ PYTHONIOENCODING: "gb18030", PYTHONUTF8: "0" }, "win32");
    expect(overridden.PYTHONIOENCODING).toBe("gb18030");
    expect(overridden.PYTHONUTF8).toBe("0");
  });

  describe("Windows shell selection", () => {
    it("defaults Windows to PowerShell instead of a POSIX-incompatible cmd -c path", () => {
      const previous = process.env.ORKAS_WINDOWS_SHELL;
      delete process.env.ORKAS_WINDOWS_SHELL;
      try {
        expect(defaultShellForPlatform("win32")).toBe("powershell.exe");
      } finally {
        if (previous === undefined) delete process.env.ORKAS_WINDOWS_SHELL;
        else process.env.ORKAS_WINDOWS_SHELL = previous;
      }
    });

    it("honors an explicit Windows shell override", () => {
      const previous = process.env.ORKAS_WINDOWS_SHELL;
      process.env.ORKAS_WINDOWS_SHELL = "pwsh.exe";
      try {
        expect(defaultShellForPlatform("win32")).toBe("pwsh.exe");
      } finally {
        if (previous === undefined) delete process.env.ORKAS_WINDOWS_SHELL;
        else process.env.ORKAS_WINDOWS_SHELL = previous;
      }
    });

    it("uses cmd.exe /d /s /c when cmd is explicitly selected", () => {
      const inv = buildShellInvocation("cmd.exe", "echo hi", "win32");
      expect(inv.kind).toBe("cmd");
      expect(inv.args).toEqual(["/d", "/s", "/c", "echo hi"]);
    });

    it("routes explicit cmd /c commands to cmd even when PowerShell is the default shell", () => {
      const command = 'cmd /c dir "%USERPROFILE%\\.orkas\\skills" 2>nul || echo missing';
      const inv = buildShellInvocation("powershell.exe", command, "win32");
      expect(inv.kind).toBe("cmd");
      expect(inv.command).toBe("cmd.exe");
      expect(inv.args).toEqual(["/d", "/s", "/c", command]);
    });

    it("passes PowerShell commands through without bash-syntax rewriting", () => {
      const command = '$ORKAS_NODE "$ORKAS_PC_DIR/bin/run-skill.cjs" calculator eval';
      const inv = buildShellInvocation("powershell.exe", command, "win32");
      expect(inv.kind).toBe("powershell");
      const wrappedCommand = [
        "& {",
        command,
        "$orkasCommandSucceeded = $?",
        "$orkasNativeExitCode = $LASTEXITCODE",
        "if ($null -ne $orkasNativeExitCode) { exit $orkasNativeExitCode }",
        "if (-not $orkasCommandSucceeded) { exit 1 }",
        "}",
      ].join("\n");
      expect(inv.args).toEqual([
        "-NoLogo",
        "-NoProfile",
        "-NonInteractive",
        "-ExecutionPolicy",
        "Bypass",
        "-Command",
        wrappedCommand,
      ]);
    });

    it("keeps explicit Git Bash-style shells POSIX-shaped on Windows", () => {
      const inv = buildShellInvocation("bash.exe", "echo $ORKAS_UID", "win32");
      expect(inv.kind).toBe("posix");
      expect(inv.args).toEqual(["-lc", "echo $ORKAS_UID"]);
    });
  });

  describe("executeBackground", () => {
    it("returns a pid immediately and writes output to the log file", async () => {
      const dir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-bg-"));
      const diagnostics = vi.spyOn(console, "info").mockImplementation(() => {});
      try {
        const logPath = path.join(dir, "run.log");
        const sandbox = new SandboxExecutor({ workingDir: dir });
        const { pid, error } = sandbox.executeBackground(
          nodeEvalCommand("process.stdout.write('done\\n')"),
          logPath,
        );
        expect(error).toBeUndefined();
        expect(typeof pid).toBe("number");
        const logged = JSON.stringify(diagnostics.mock.calls);
        expect(logged).toContain(`pid=${pid}`);
        expect(logged).not.toContain(dir);
        expect(logged).not.toContain("run.log");
        // PowerShell cold-start plus native scanner latency can exceed two
        // seconds on loaded Windows hosts. Background launch is deliberately
        // asynchronous, so allow a bounded platform-specific startup window.
        let body = "";
        const deadline = Date.now() + NATIVE_SHELL_STARTUP_BUDGET_MS;
        while (Date.now() < deadline && !body.includes("done")) {
          await new Promise((r) => setTimeout(r, 50));
          try { body = await fs.readFile(logPath, "utf8"); } catch { /* not yet */ }
        }
        expect(body).toContain("done");
        await waitForProcessExit(pid!);
      } finally {
        diagnostics.mockRestore();
        await removeTree(dir);
      }
    }, NATIVE_SHELL_TEST_TIMEOUT_MS);

    it("refuses blocked commands without spawning", async () => {
      const dir = await fs.mkdtemp(path.join(os.tmpdir(), "sandbox-bg-"));
      try {
        const sandbox = new SandboxExecutor({ workingDir: dir });
        const { pid, error } = sandbox.executeBackground("rm -rf /", path.join(dir, "x.log"));
        expect(pid).toBeNull();
        expect(error).toMatch(/blocked/i);
      } finally {
        await removeTree(dir);
      }
    });
  });
});

describe("decodeProcessOutput", () => {
  it("falls back to GB18030 for Chinese Windows console output", () => {
    const gbkVersion = Buffer.from([0xb0, 0xe6, 0xb1, 0xbe]);
    expect(decodeProcessOutput(gbkVersion, "win32", { ORKAS_UI_LANG: "zh" })).toBe("版本");
  });

  it("keeps valid UTF-8 output unchanged on Windows", () => {
    const utf8 = Buffer.from("版本", "utf8");
    expect(decodeProcessOutput(utf8, "win32", { ORKAS_UI_LANG: "zh" })).toBe("版本");
  });
});