Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
40.9 KB
Raw Blame
// Ported from the CLI (omnirush-cli test/box-backends.test.js,
// feat/local-box-backends): the ranked choice per OS and each backend against
// its real CLI's output, mocked (no runtime on the test machine is touched):
// bubblewrap (boxrun's JSON), Apple `container` (1.x JSON), the OmniRush WSL
// distro (wsl.exe's UTF-16 output), WSL containers (wslc 3.0.1 JSON), and the
// overrides (the backend setting, the server's allowlist). Desktop additions:
// the service's status and setting, files-used through a non-container box.
import { afterEach, describe, expect, test } from "bun:test";
import { ChildProcess } from "node:child_process";
import { createHash } from "node:crypto";
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import { PassThrough } from "node:stream";

import { OPT_IN, BACKENDS, REQUIRED_FIRST, backendsFor, detectBackend, driverFor, normalizeBackend, ORDER } from "./backends/index.js";
import { apparmorProfile, boxEgress, boxdEnv, boxrunPath, bwrapCandidates, ENABLED_BWRAP, explainProbe, parseOut, probeBwrap, upArgs } from "./backends/bwrap.js";
import { createAppleArgs, findDigest, macosMajor, parseVersions, probeApple, snapshotInfo, SUPPORTED as APPLE, systemProductVersion } from "./backends/apple.js";
import { versionAtLeast } from "./backends/shared.js";
import { decodeWsl, download, ENABLE_HINT, inDistro, parseWslList, probeWslDistro, startKeeper } from "./backends/wsl.js";
import { createWslcArgs, labelsOf, parseJsonRows, parseWslcVersion, probeWslc, UPDATE_HINT } from "./backends/wslc.js";
import { Box, setToolsRoot } from "./box.js";
import { askedBackend, readBackend, rememberServerDefault, saveBackend, serverBackends } from "./launch.js";
import type { RunCommand, RunResult } from "./run.js";
import { BoxService, backendChoices, type BoxWorkspace } from "./service.js";
import { sandboxFilesUsed } from "../session-archive/files-used-sandbox.js";

const dirs: string[] = [];
const tmp = () => {
  const dir = mkdtempSync(path.join(os.tmpdir(), "box-be-"));
  dirs.push(dir);
  return dir;
};
afterEach(() => {
  setToolsRoot(null);
  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});

const set = (...files: Array<string | null>) => (file: string) => files.includes(file);
const ok = (stdout: unknown): RunResult => ({ code: 0, stdout: typeof stdout === "string" ? stdout : JSON.stringify(stdout), stderr: "" });
const fail = (stderr: string, code = 1): RunResult => ({ code, stdout: "", stderr });

/** A helpers folder with linux boxrun and boxd (empty stand-ins): the desktop finds helpers only where they are. */
function helperBin(): string {
  const dir = tmp();
  for (const arch of ["amd64", "arm64"]) {
    mkdirSync(path.join(dir, `linux-${arch}`), { recursive: true });
    for (const name of ["boxrun", "boxd"]) writeFileSync(path.join(dir, `linux-${arch}`, name), "");
  }
  return dir;
}

// --- ranking and overrides ---------------------------------------------------------------

describe("box backends: ranking and overrides", () => {
  test("the ranked order per OS", () => {
    expect(ORDER.linux).toEqual(["bwrap", "podman", "docker"]);
    expect(ORDER.darwin).toEqual(["orbstack", "colima", "docker-desktop", "rancher", "podman", "docker"]);
    expect(REQUIRED_FIRST.darwin).toEqual(["lima"]);
    expect(OPT_IN.darwin).toEqual(["apple"]);
    expect(ORDER.win32).toEqual(["wslc", "wsl", "docker-desktop", "podman", "docker", "wsl-engine"]);
    for (const list of Object.values(ORDER)) for (const id of list) expect(BACKENDS.some((b) => b === id)).toBe(true);
    expect(backendsFor("linux")).toEqual(ORDER.linux);
    expect(backendChoices("win32").map((c) => c.id)).toEqual(["auto", ...ORDER.win32, "native"]);
    expect(backendChoices("darwin").map((c) => c.id)).toEqual(["auto", "lima", ...ORDER.darwin, "apple", "native"]);
    expect(backendChoices("darwin").find((c) => c.id === "apple")?.label).toBe("Apple container (opt-in)");
  });

  test("setting values: ids, aliases, auto, native; anything else is refused", () => {
    expect(normalizeBackend("")).toBe("auto");
    expect(normalizeBackend("Bubblewrap")).toBe("bwrap");
    expect(normalizeBackend("container")).toBe("apple");
    expect(normalizeBackend("wsl-containers")).toBe("wslc");
    expect(normalizeBackend("desktop")).toBe("docker-desktop");
    expect(normalizeBackend("off")).toBe("native");
    expect(normalizeBackend("lxc")).toBeNull();
  });
});

// --- Linux: bubblewrap ------------------------------------------------------------------------

const BWRAP_OK = { ok: true, launcher: "bwrap", bwrap: "/usr/bin/bwrap", bwrap_version: "0.9.0", overlay: "kernel", idmap: "subuid", kernel: "6.8.0", apparmor_restrict_unprivileged_userns: 0, root: false, ms: 9 };
const BWRAP_AA = { ok: false, launcher: "bwrap", bwrap: "/usr/bin/bwrap", bwrap_version: "0.9.0", kernel: "6.8.0", apparmor_restrict_unprivileged_userns: 1, code: "apparmor", reason: "AppArmor blocks unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1, Ubuntu 23.10+)", detail: "bwrap: setting up uid map: Permission denied" };
const podmanInfo = { host: { arch: "amd64", os: "linux", security: { rootless: true } }, version: { Version: "4.9.3" } };

function linuxRun(bwrapAnswer: unknown, { podman = true }: { podman?: boolean } = {}) {
  const calls: string[] = [];
  const run: RunCommand = async (bin, args) => {
    calls.push([path.basename(bin), ...args].join(" "));
    if (bin.endsWith("boxrun")) return ok(bwrapAnswer);
    if (bin.endsWith("podman")) return podman ? ok(podmanInfo) : fail("podman: not found", 127);
    return fail("Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?");
  };
  return { run, calls };
}

describe("box backends: Linux", () => {
  test("farm runs: only backends that keep the box offline; Podman/Docker are skipped, never a silent fallback", async () => {
    const home = tmp();
    const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin(), OMNIRUSH_FARM: "1", OMNIRUSH_FARM_RUN: "1" };
    const farm = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run: linuxRun(BWRAP_AA).run, fresh: true, all: true, wsl: false });
    expect(farm.ok).toBe(false);
    expect(farm.alternatives?.find((a) => a.backend === "podman")?.reason).toBe("cannot keep a farm session offline");
    const asked = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run: linuxRun(BWRAP_OK).run, fresh: true, asked: "podman", wsl: false });
    expect(asked.ok).toBe(false);
    const ok = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run: linuxRun(BWRAP_OK).run, fresh: true, wsl: false });
    expect(ok).toMatchObject({ ok: true, backend: "bwrap" });
    if (ok.ok) expect(ok.why).toMatch(/farm mode/);
    // boxsh's `wslc exec` fallback runs outside boxd's network: off in farm runs, kept otherwise.
    const runtime = { name: "wslc", backend: "wslc", bin: "wslc.exe" };
    const base = { key: "k", name: "omnirush-box-k", root: home, croot: home, runtime, home, runFolder: home, run: linuxRun(BWRAP_OK).run, log: () => {}, platform: "win32" as const };
    expect(new Box({ ...base, env: {} }).execFallback()).toBe(true);
    expect(new Box({ ...base, env: { OMNIRUSH_FARM: "1", OMNIRUSH_FARM_RUN: "1" } }).execFallback()).toBe(false);
    // A hackathon event's stock mode (no farm-run marker) keeps the fallback, as before.
    expect(new Box({ ...base, env: { OMNIRUSH_FARM: "1" } }).execFallback()).toBe(true);
  });

  test("bubblewrap first when its probe starts a namespace", async () => {
    const home = tmp();
    const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };
    const { run } = linuxRun(BWRAP_OK);
    const found = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, wsl: false });
    expect(found).toMatchObject({ ok: true, backend: "bwrap", flavor: "overlayfs", idmap: "subuid", version: "0.9.0" });
    if (found.ok) expect(found.why).toMatch(/bwrap > podman > docker/);
    expect(driverFor(found.ok ? found : null).kind).toBe("bwrap");
  });

  test("AppArmor's userns restriction: one-line reason with the admin fix, rootless Podman is used", async () => {
    const home = tmp();
    const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };
    const found = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run: linuxRun(BWRAP_AA).run, fresh: true, all: true, wsl: false });
    expect(found).toMatchObject({ ok: true, backend: "podman" });
    const bw = found.alternatives?.find((a) => a.backend === "bwrap");
    expect(bw?.ok).toBe(false);
    expect(bw?.reason).toMatch(/AppArmor .*sudo omnirush sandbox enable/);
    expect(bw?.reason).not.toMatch(/\n/);
    // Nothing else either: the project runs natively and says why in one line.
    const none = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env })), run: linuxRun(BWRAP_AA, { podman: false }).run, fresh: true, wsl: false });
    expect(none.ok).toBe(false);
    if (!none.ok) expect(none.reason).toMatch(/^bwrap: AppArmor/);
  });

  test("bwrap probe reasons: no bwrap, userns off, helper missing, garbage", async () => {
    expect(explainProbe({ code: "no_bwrap", reason: "bubblewrap (bwrap) is not installed" })).toMatch(/apt install bubblewrap/);
    expect(explainProbe({ code: "userns_off", reason: "x" })).toMatch(/Podman or Docker/);
    const home = tmp();
    const missing = await probeBwrap({ env: { OMNIRUSH_BOX_BIN_DIR: "/nope" }, boxHome: home, exists: () => false, platform: "linux" });
    expect(missing.ok ? "" : missing.reason).toMatch(/boxrun is missing/);
    const garbage = await probeBwrap({ env: { OMNIRUSH_BOX_BIN_DIR: helperBin() }, boxHome: home, exists: () => true, platform: "linux", run: async () => ({ code: 1, stdout: "", stderr: "segfault" }) });
    expect(garbage.ok).toBe(false);
    expect(parseOut('noise\n{"a":1}\n{"ok":true,"port":5}\n')).toEqual({ ok: true, port: 5 });
  });

  test("bwrap candidates: the enabled copy, the system's, then the bundled one; each probed until one starts a box", async () => {
    const bin = helperBin();
    const bundled = path.join(bin, "linux-amd64", "bwrap");
    writeFileSync(bundled, "");
    const present = new Set([ENABLED_BWRAP, "/usr/bin/bwrap", bundled, path.join(bin, "linux-amd64", "boxrun")]);
    const exists = (file: string) => present.has(file);
    expect(bwrapCandidates({ env: { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: bin }, arch: "x64", exists })).toEqual([
      { path: ENABLED_BWRAP, source: "enabled" }, { path: "/usr/bin/bwrap", source: "system" }, { path: bundled, source: "bundled" },
    ]);
    expect(bwrapCandidates({ env: { OMNIRUSH_BOX_BWRAP: "/x/bwrap" }, exists })).toEqual([{ path: "/x/bwrap", source: "env" }]);
    // The enabled copy fails, the system's is blocked by AppArmor, the bundled one works: it is used.
    const tried: string[] = [];
    const run: RunCommand = async (_bin, args) => {
      const bw = args[args.indexOf("--bwrap") + 1] ?? "";
      tried.push(bw);
      if (bw === bundled) return { code: 0, stdout: JSON.stringify({ ok: true, bwrap: bw, bwrap_version: "0.11.0" }), stderr: "" };
      return { code: 1, stdout: JSON.stringify({ ok: false, code: bw === "/usr/bin/bwrap" ? "apparmor" : "userns_off", reason: "blocked" }), stderr: "" };
    };
    const found = await probeBwrap({ env: { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: bin }, boxHome: tmp(), arch: "x64", exists, platform: "linux", run });
    expect(found).toMatchObject({ ok: true, bwrap: bundled, version: "0.11.0" });
    expect(tried).toEqual([ENABLED_BWRAP, "/usr/bin/bwrap", bundled]);
    // None works: AppArmor's reason (one admin step fixes it), naming the app's Allow.
    present.delete(bundled);
    const none = await probeBwrap({ env: { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: bin }, boxHome: tmp(), arch: "x64", exists, platform: "linux", run });
    expect(none).toMatchObject({ ok: false, code: "apparmor" });
    expect(none.ok ? "" : none.reason).toContain("Allow the sandbox");
  });

  test("the setting picks one backend; native turns the box off; the server's allowlist skips the rest", async () => {
    const home = tmp();
    const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };
    const { run, calls } = linuxRun(BWRAP_OK);
    const asked = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, asked: "podman", wsl: false });
    expect(asked).toMatchObject({ ok: true, backend: "podman" });
    if (asked.ok) expect(asked.why).toMatch(/chosen in Settings/);
    expect(calls.some((c) => c.startsWith("boxrun"))).toBe(false);
    const native = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: () => true, run, fresh: true, asked: "native" });
    expect(native).toMatchObject({ ok: false, native: true });
    const unknown = await detectBackend({ boxHome: home, platform: "linux", home, env, run, fresh: true, asked: "lxc" });
    expect(unknown.ok ? "" : unknown.reason).toMatch(/unknown sandbox backend "lxc"/);
    const allowed = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, all: true, allow: ["podman", "docker"], wsl: false });
    expect(allowed).toMatchObject({ ok: true, backend: "podman" });
    expect(allowed.alternatives?.find((a) => a.backend === "bwrap")?.reason).toBe("not allowed by the server");
  });

  test("the backend setting and the server's allowlist are remembered", () => {
    const state = tmp();
    expect(readBackend(state)).toBe("auto");
    expect(saveBackend(state, "Bubblewrap")).toBe("bwrap");
    expect(askedBackend({ env: {}, stateDir: state })).toEqual({ backend: "bwrap", source: "setting" });
    expect(askedBackend({ env: { OMNIRUSH_BOX_BACKEND: "docker" }, stateDir: state })).toEqual({ backend: "docker", source: "env" });
    expect(() => saveBackend(state, "nope")).toThrow();
    expect(JSON.parse(readFileSync(path.join(state, "box.json"), "utf8"))).toEqual({ backend: "bwrap" });
    expect(rememberServerDefault(state, { local_box: { default: "offer", backends: ["bwrap", "docker", 3] } })).toBe(true);
    expect(serverBackends(state)).toEqual(["bwrap", "docker"]);
    expect(rememberServerDefault(state, { local_box: { default: "offer", backends: ["bwrap", "docker"] } })).toBe(false);
    rememberServerDefault(state, { local_box: { default: "off" } });
    expect(serverBackends(state)).toBeNull();
  });

  test("farm egress: only farm runs give boxd BOXD_EGRESS (bwrap, WSL distro, wslc); other runs keep their exact args", () => {
    expect(boxEgress({})).toBeNull();
    expect(boxEgress({ OMNIRUSH_FARM: "0" })).toBeNull();
    expect(boxEgress({ OMNIRUSH_FARM: "1", OMNIRUSH_FARM_RUN: "1" })).toBe("farm");
    // A hackathon event's stock mode (OMNIRUSH_FARM without the farm-run marker): the network as is.
    expect(boxEgress({ OMNIRUSH_FARM: "1" })).toBeNull();
    expect(boxEgress({ OMNIRUSH_FARM_RUN: "1" })).toBeNull();
    const base = { box: "/b", store: "/s", image: "i", boxd: "/d", portFile: "/p", root: "/r", croot: "/r", runFolder: "/f", token: "t" };
    const plain = upArgs(base);
    expect(upArgs({ ...base, egress: null })).toEqual(plain);
    expect(plain.some((a) => a.startsWith("BOXD_EGRESS"))).toBe(false);
    expect(upArgs({ ...base, egress: "farm" })).toEqual([...plain, "--env", "BOXD_EGRESS=farm"]);
    const wbase = { name: "n", key: "k", root: "C:\\p", croot: "/c/p", image: "img", runFolder: "C:\\r", token: "t", port: 1, env: {} };
    const wplain = createWslcArgs(wbase);
    expect(createWslcArgs({ ...wbase, egress: null })).toEqual(wplain);
    const wfarm = createWslcArgs({ ...wbase, egress: "farm" });
    expect(wfarm).toContain("BOXD_EGRESS=farm");
    expect(wfarm).toContain("ai.omnirush.box.egress=farm");
    expect(wfarm.length).toBe(wplain.length + 4);
  });

  test("bwrap box start: the project at its path, the run folder, boxd on loopback with a port file, nothing of $HOME", () => {
    const args = upArgs({ box: "/h/.omnirush/box/bwrap/boxes/k", store: "/h/.omnirush/box/bwrap/store", image: "abc-amd64", boxd: "/pkg/boxd", portFile: "/h/.omnirush/box/projects/k/boxd.port", root: "/home/u/proj", croot: "/home/u/proj", runFolder: "/h/.omnirush/box/projects/k", pkglog: { root: "/h/.omnirush/pkglog" }, token: "t0k", idleMinutes: 90 });
    const binds = args.flatMap((a, i) => (a === "--bind" || a === "--ro-bind" ? [args[i + 1]] : []));
    expect(binds).toEqual(["/home/u/proj=/home/u/proj", "/h/.omnirush/box/projects/k=/run/omnirush", "/h/.omnirush/pkglog=/h/.omnirush/pkglog"]);
    const env = args.flatMap((a, i) => (a === "--env" ? [args[i + 1]] : []));
    expect(env).toContain("BOXD_LISTEN=127.0.0.1:0");
    expect(env).toContain("BOXD_PORT_FILE=/run/omnirush/boxd.port");
    expect(env).toContain("BOXD_IDLE_EXIT=90");
    expect(env).toContain("BOXD_TOKEN=t0k");
    expect(binds.some((b) => b?.startsWith("/h=") || b?.includes(".ssh"))).toBe(false);
    expect(boxdEnv({ token: "x", croot: "/c" }).filter((kv) => kv.startsWith("BOXD_UID") || kv.startsWith("BOXD_HOME"))).toEqual(["BOXD_UID=0", "BOXD_HOME=/root"]);
  });

  test("the AppArmor profile the CLI installs covers OmniRush's own bwrap only (userns), never the sysctl", () => {
    const profile = apparmorProfile("/usr/local/lib/omnirush/bwrap");
    expect(profile).toMatch(/profile omnirush-bwrap \/usr\/local\/lib\/omnirush\/bwrap flags=\(unconfined\) \{\n  userns,/);
    expect(/sysctl|apparmor_restrict/.test(profile.replace(/^#.*$/gm, ""))).toBe(false);
  });
});

// --- macOS: Apple container -----------------------------------------------------------------

const APPLE_BIN = "/usr/local/bin/container";
const appleVersions = [{ appName: "container", version: "1.5.0", buildType: "release", commit: "abc" }, { appName: "container-apiserver", version: "1.5.0", buildType: "release", commit: "abc" }];

describe("box backends: macOS", () => {
  test("Apple container: macOS 26 on Apple silicon, the 1.x line, its service running", async () => {
    expect(macosMajor("25.0.0", null)).toBe(26);
    expect(macosMajor("24.6.0", null)).toBe(15);
    expect(macosMajor("20.1.0", null)).toBe(11);
    expect(macosMajor("19.6.0", null)).toBe(null);
    // This Mac's own version wins over the kernel number (macOS 27.0.1 reports Darwin 27.0.0).
    expect(macosMajor("27.0.0", "27.0.1")).toBe(27);
    expect(systemProductVersion(() => "<dict><key>ProductVersion</key>\n\t<string>27.0.1</string></dict>")).toBe("27.0.1");
    expect(systemProductVersion(() => { throw new Error("ENOENT"); })).toBe(null);
    expect(parseVersions(JSON.stringify(appleVersions))).toEqual({ version: "1.5.0", server: "1.5.0" });
    expect(parseVersions("container CLI version 0.5.0 (build: release, commit: 1234)").version).toBe("0.5.0");
    const base = { platform: "darwin" as const, arch: "arm64", release: "25.1.0", env: { PATH: "/usr/bin" }, exists: set(APPLE_BIN) };
    const good: RunCommand = async (_bin, args) => (args[1] === "version" ? ok(appleVersions) : ok("apiserver is running"));
    expect(await probeApple({ ...base, run: good })).toMatchObject({ ok: true, version: "1.5.0", arch: "arm64", vm: true });
    const reason = async (run: RunCommand, extra: Record<string, unknown> = {}) => {
      const r = await probeApple({ ...base, ...extra, run });
      return r.ok ? "" : r.reason;
    };
    expect(await reason(good, { arch: "x64" })).toMatch(/Apple silicon/);
    expect(await reason(good, { release: "24.6.0" })).toMatch(/macOS 26 or later \(this is macOS 15\)/);
    expect(await reason(good, { exists: () => false })).toMatch(/not installed/);
    expect(await reason(async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "0.11.0" }]) : ok("")))).toMatch(/0\.11\.0 is outside the supported 1\.x line/);
    expect((await probeApple({ ...base, run: async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "2.0.0" }]) : ok("")) })).ok).toBe(false);
    expect(await reason(async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "1.4.1" }]) : fail("apiserver is not running and not registered with launchd")))).toMatch(/container system start/);
    expect(versionAtLeast("1.4.1", APPLE.min) && !versionAtLeast("1.4.1", APPLE.below)).toBe(true);
  });

  test("Apple container: create args, list/inspect JSON, image digest", () => {
    const args = createAppleArgs({ name: "omnirush-box-k", key: "k", root: "/Users/sam/proj", croot: "/Users/sam/proj", image: `ghcr.io/omnirush-ai/box-base@sha256:${"a".repeat(64)}`, runFolder: "/Users/sam/.omnirush/box/projects/k", token: "t", port: 50123, env: { OMNIRUSH_BOX_MEMORY: "6G" } });
    expect(args).toContain("type=bind,source=/Users/sam/proj,target=/Users/sam/proj");
    expect(args).toContain("type=bind,source=/Users/sam/.omnirush/box/projects/k/bin,target=/opt/omnirush/bin,readonly");
    expect(args.slice(args.indexOf("-p"), args.indexOf("-p") + 2)).toEqual(["-p", "127.0.0.1:50123:7777"]);
    expect(args[args.indexOf("--memory") + 1]).toBe("6G");
    expect(args[args.indexOf("--entrypoint") + 1]).toBe("/opt/omnirush/bin/boxd");
    expect(args).toContain("--init");
    expect(args).toContain("ai.omnirush.box.port=50123");
    const snap = { configuration: { id: "omnirush-box-k", image: { reference: "ghcr.io/omnirush-ai/box-base:1", descriptor: { digest: `sha256:${"b".repeat(64)}` } }, labels: { "ai.omnirush.box": "1", "ai.omnirush.box.key": "k" } }, status: "running", networks: [{ network: "default", hostname: "omnirush-box-k", ipv4Address: "192.168.64.7/24", ipv4Gateway: "192.168.64.1" }] };
    expect(snapshotInfo(snap)).toMatchObject({ running: true, address: "192.168.64.7", digest: `sha256:${"b".repeat(64)}` });
    expect(snapshotInfo({ ...snap, networks: [{ address: "192.168.64.9/24" }] }).address).toBe("192.168.64.9");
    expect(findDigest([{ name: "x", index: { digest: `sha256:${"c".repeat(64)}` } }])).toBe(`sha256:${"c".repeat(64)}`);
    expect(findDigest({ variants: [{ config: { digest: `sha256:${"d".repeat(64)}` } }] })).toBe(`sha256:${"d".repeat(64)}`);
  });

  test("ranking: OrbStack, colima, Docker Desktop through docker contexts; Apple container never probed unasked", async () => {
    const docker = "/usr/local/bin/docker";
    const infos: Record<string, unknown> = { orbstack: { OperatingSystem: "OrbStack", Name: "orbstack", ServerVersion: "27.0", OSType: "linux", Architecture: "aarch64" }, colima: { OperatingSystem: "Ubuntu 24.04", Name: "colima", ServerVersion: "27.1", OSType: "linux" }, "desktop-linux": { OperatingSystem: "Docker Desktop", ServerVersion: "28.0", OSType: "linux" } };
    const contexts = ["desktop-linux", "colima", "default"].map((Name) => JSON.stringify({ Name, DockerEndpoint: `unix:///x/${Name}.sock` })).join("\n");
    const run: RunCommand = async (bin, args) => {
      if (bin === APPLE_BIN) return fail("not installed", 127);
      if (args[0] === "context") return ok(contexts);
      if (args[0] === "--context") return infos[args[1] ?? ""] ? ok(infos[args[1] ?? ""]) : fail("Cannot connect to the Docker daemon");
      return fail("no");
    };
    const home = tmp();
    // (the OmniRush VM off: these are the runtimes it falls back to)
    const found = await detectBackend({ boxHome: home, platform: "darwin", arch: "arm64", release: "24.0.0", home: "/Users/sam", env: { PATH: "/usr/local/bin", OMNIRUSH_BOX_LIMA: "0" }, exists: set(docker), run, fresh: true, all: true });
    expect(found).toMatchObject({ ok: true, backend: "colima", prefix: ["--context", "colima"] });
    expect(found.alternatives?.find((a) => a.backend === "apple")?.reason).toMatch(/opt-in only/);
    expect(found.alternatives?.some((a) => a.backend === "docker-desktop" && a.ok)).toBe(true);
    const none = await detectBackend({ boxHome: home, platform: "darwin", home: "/Users/sam", env: { PATH: "/usr/bin", OMNIRUSH_BOX_LIMA: "0" }, exists: () => false, run, fresh: true });
    expect(none).toMatchObject({ ok: false, hint: "colima" });
  });

  test("Apple container: opt-in only, used when chosen, never started", async () => {
    const calls: string[][] = [];
    const run: RunCommand = async (bin, args) => {
      calls.push([bin, ...args]);
      if (bin === APPLE_BIN) return args[1] === "version" ? ok(appleVersions) : ok("apiserver is running");
      return fail("Cannot connect to the Docker daemon");
    };
    const base = { boxHome: tmp(), platform: "darwin" as const, arch: "arm64", release: "26.0.0", home: "/Users/sam", env: { PATH: "/usr/local/bin", OMNIRUSH_BOX_LIMA: "0" }, exists: set(APPLE_BIN), run, fresh: true };
    const auto = await detectBackend(base);
    expect(auto.ok).toBe(false);
    expect(calls.some(([bin]) => bin === APPLE_BIN)).toBe(false);
    const asked = await detectBackend({ ...base, asked: "apple-container" });
    expect(asked).toMatchObject({ ok: true, backend: "apple" });
    expect(calls.some((c) => c.slice(1).join(" ") === "system start")).toBe(false);
    const stopped = await probeApple({ ...base, run: async (_b, args) => (args[1] === "version" ? ok(appleVersions) : fail("apiserver is not running")) });
    expect(stopped.ok ? "" : stopped.reason).toMatch(/never starts it/);
  });
});

// --- Windows: the OmniRush WSL distro --------------------------------------------------------

const WSL = "C:\\Windows\\System32\\wsl.exe";
const winEnv = { Path: "C:\\Windows\\System32", SystemRoot: "C:\\Windows", ProgramFiles: "C:\\Program Files", LOCALAPPDATA: "C:\\Users\\sam\\AppData\\Local" };
const utf16 = (text: string) => Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(text, "utf16le")]);

function wslRun({ status = ok("Default Version: 2\r\n"), list = ok("  NAME  STATE  VERSION\r\n"), version = ok("WSL version: 2.6.1.0\r\nKernel version: 6.6.87.2-1\r\n") }: { status?: RunResult; list?: RunResult; version?: RunResult } = {}): RunCommand {
  return async (_bin, args) => {
    if (args[0] === "--status") return status;
    if (args[0] === "--list") return list;
    if (args[0] === "--version") return version;
    return fail("unexpected");
  };
}

/** A child process with pipes and no process behind it (the WSL keeper's stand-in). */
class FakeChild extends ChildProcess {
  override stdout = new PassThrough();
  override stderr = new PassThrough();
  override stdin = new PassThrough();
}
const fakeChild = () => new FakeChild();

describe("box backends: Windows", () => {
  test("WSL rootfs download: through the app's fetch, https only, checked against its sha256", async () => {
    const dir = tmp();
    const body = Buffer.from("rootfs bytes");
    const sum = createHash("sha256").update(body).digest("hex");
    const asked: Array<[string, RequestInit | undefined]> = [];
    const fetcher = async (url: string, init?: RequestInit) => {
      asked.push([url, init]);
      return Object.defineProperty(new Response(body, { status: 200 }), "url", { value: url });
    };
    const dest = path.join(dir, "rootfs.tar.gz");
    expect(await download("https://example.invalid/r.tar.gz", dest, sum, { fetcher })).toBe(dest);
    expect(readFileSync(dest, "utf8")).toBe("rootfs bytes");
    expect(asked[0]?.[1]?.redirect).toBe("follow");
    await expect(download("https://example.invalid/r.tar.gz", path.join(dir, "bad"), "0".repeat(64), { fetcher })).rejects.toThrow(/sha256 mismatch/);
    await expect(download("http://example.invalid/r.tar.gz", path.join(dir, "plain"), null, { fetcher })).rejects.toThrow(/https only/);
    await expect(download("https://example.invalid/missing", path.join(dir, "m"), null, { fetcher: async () => new Response("no", { status: 404 }) })).rejects.toThrow(/HTTP 404/);
  });

  test("wsl.exe output: UTF-16LE with a BOM or UTF-8, the verbose list with its default marker", () => {
    const list = "  NAME            STATE           VERSION\r\n* Ubuntu-24.04    Running         2\r\n  OmniRushBox     Stopped         2\r\n  Legacy Distro   Stopped         1\r\n";
    expect(decodeWsl(utf16(list))).toBe(decodeWsl(Buffer.from(list)));
    expect(parseWslList(utf16(list))).toEqual([
      { name: "Ubuntu-24.04", state: "Running", version: "2", isDefault: true },
      { name: "OmniRushBox", state: "Stopped", version: "2", isDefault: false },
      { name: "Legacy Distro", state: "Stopped", version: "1", isDefault: false },
    ]);
    // What runCommand hands over when it read UTF-16 as UTF-8: NULs between letters.
    expect(decodeWsl("W\u0000S\u0000L\u0000")).toBe("WSL");
  });

  test("distro probe: not enabled is the one-time admin hint (never an install); WSL 1 and unpublished images say so", async () => {
    const reason = (r: Awaited<ReturnType<typeof probeWslDistro>>) => (r.ok ? "" : r.reason);
    const off = await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun({ status: fail(Buffer.from("Windows Subsystem for Linux is not installed. You can install by running 'wsl.exe --install'.", "utf16le").toString("utf8")) }) });
    expect(reason(off)).toBe(ENABLE_HINT);
    expect(ENABLE_HINT).toMatch(/administrator terminal: `wsl --install --no-distribution`, then restart/);
    expect(reason(await probeWslDistro({ platform: "win32", env: winEnv, exists: () => false, run: wslRun() }))).toBe(ENABLE_HINT);
    const v1 = await probeWslDistro({ platform: "win32", env: { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" }, exists: set(WSL), run: wslRun({ list: ok("  NAME STATE VERSION\r\n  OmniRushBox  Stopped  1\r\n") }) });
    expect(reason(v1)).toMatch(/WSL 1/);
    expect(reason(await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun(), pins: { version: "x", distro: "OmniRushBox", base: "x", assets: { amd64: { url: null, sha256: null, bytes: null } } } as never }))).toMatch(/not published yet/);
    // The shipped wsl.json pins a published image.
    expect((await probeWslDistro({ platform: "win32", arch: "x64", env: winEnv, exists: set(WSL), run: wslRun() })).ok).toBe(true);
    const ready = await probeWslDistro({ platform: "win32", env: { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" }, exists: set(WSL), run: wslRun() });
    expect(ready).toMatchObject({ ok: true, installed: false, distro: "OmniRushBox", version: "2.6.1.0" });
    const installed = await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun({ list: ok(utf16("  NAME  STATE  VERSION\r\n  OmniRushBox  Running  2\r\n").toString("latin1")) }) });
    expect(installed.ok).toBe(true);
  });

  test("distro box: Windows paths bound as /mnt/c into /c, commands as root without a shell", () => {
    expect(inDistro({ distro: "OmniRushBox" }, ["/opt/omnirush/boxrun", "status"])).toEqual(["-d", "OmniRushBox", "-u", "root", "--cd", "/", "--exec", "/opt/omnirush/boxrun", "status"]);
    const wslPath = (p: string) => `/mnt/${p[0]!.toLowerCase()}/${p.slice(3).replace(/\\/g, "/")}`;
    const args = upArgs({ box: "/var/lib/omnirush/boxes/k", store: "/var/lib/omnirush/store", image: "id", boxd: "/opt/omnirush/boxd", portFile: "/mnt/c/Users/Sam/.omnirush/box/projects/k/boxd.port", root: "C:\\Users\\Sam\\proj", croot: "/c/Users/Sam/proj", runFolder: "C:\\Users\\Sam\\.omnirush\\box\\projects\\k", token: "t", platform: "win32", mapPath: wslPath });
    expect(args).toContain("/mnt/c/Users/Sam/proj=/c/Users/Sam/proj");
    expect(args).toContain("/mnt/c/Users/Sam/.omnirush/box/projects/k=/run/omnirush");
  });

  test("keeper: the first JSON line (UTF-16 or not) gives the port; the keeper stays as a child", async () => {
    let spawnedArgs: string[] = [];
    const kept = await startKeeper({ bin: WSL, distro: "OmniRushBox" }, ["up", "--box", "/var/lib/omnirush/boxes/k"], {
      timeoutMs: 2_000,
      spawnImpl: (_bin, args) => {
        spawnedArgs = args;
        const child = fakeChild();
        setTimeout(() => child.stdout.emit("data", utf16('{"ok":true,"reused":false,"pid":41,"port":40123,"launcher":"unshare","overlay":"kernel"}\n')), 5);
        return child;
      },
    });
    expect(kept.ok).toBe(true);
    if (kept.ok) expect(kept.out.port).toBe(40123);
    expect(spawnedArgs.at(-1)).toBe("--foreground");
    const bad = await startKeeper({ bin: WSL, distro: "OmniRushBox" }, ["up"], {
      timeoutMs: 2_000,
      spawnImpl: () => {
        const child = fakeChild();
        setTimeout(() => child.emit("close", 1), 5);
        return child;
      },
    });
    expect(bad.ok).toBe(false);
  });

  const WSLC = "C:\\Program Files\\WSL\\wslc.exe";

  test("wslc: `wslc version` JSON or text; 3.0.1+ only; an older WSL gets the `wsl --update` hint, a missing one the enable hint", async () => {
    expect(parseWslcVersion('{"Client":{"Version":"3.0.1.0"}}')).toBe("3.0.1.0");
    expect(parseWslcVersion(utf16("wslc 3.0.2.0\r\n"))).toBe("3.0.2.0");
    const good = await probeWslc({ platform: "win32", env: winEnv, exists: set(WSLC), run: async () => ok('{"Client":{"Version":"3.0.1.0"}}') });
    expect(good).toMatchObject({ ok: true, version: "3.0.1.0", backend: "wslc", flavor: "wslc" });
    const reason = (r: Awaited<ReturnType<typeof probeWslc>>) => (r.ok ? "" : r.reason);
    expect(reason(await probeWslc({ platform: "win32", env: winEnv, exists: set(WSLC), run: async () => ok('{"Client":{"Version":"2.9.4.0"}}') }))).toMatch(/wsl --update/);
    const oldWsl = await probeWslc({ platform: "win32", env: winEnv, exists: set(WSL), run: async (_bin, args) => (args[0] === "--version" ? ok(utf16("WSL version: 2.6.1.0\r\n").toString("latin1")) : fail("x")) });
    expect(reason(oldWsl)).toBe(`${UPDATE_HINT}; this is WSL 2.6.1.0`);
    expect(reason(await probeWslc({ platform: "win32", env: winEnv, exists: () => false, run: async () => fail("x") }))).toBe(ENABLE_HINT);
  });

  test("wslc: create args take the Windows path as the bind source, publish boxd on loopback, upper-case memory, no --init", () => {
    const args = createWslcArgs({ name: "omnirush-box-k", key: "k", root: "C:\\Users\\Sam\\proj", croot: "/c/Users/Sam/proj", image: "ghcr.io/omnirush-ai/box-base:1", runFolder: "C:\\Users\\Sam\\.omnirush\\box\\projects\\k", token: "t", port: 50999, env: { OMNIRUSH_BOX_MEMORY: "4g" } });
    expect(args.slice(0, 2)).toEqual(["container", "create"]);
    expect(args).toContain("type=bind,source=C:\\Users\\Sam\\proj,target=/c/Users/Sam/proj");
    expect(args).toContain("type=bind,source=C:\\Users\\Sam\\.omnirush\\box\\projects\\k\\bin,target=/opt/omnirush/bin,readonly");
    expect(args).toContain("127.0.0.1:50999:7777");
    expect(args[args.indexOf("-m") + 1]).toBe("4G");
    expect(args).not.toContain("--init");
    expect(args.at(-1)).toBe("ghcr.io/omnirush-ai/box-base:1");
  });

  test("wslc: list JSON (an array or one object per line), labels as a map or docker's string", () => {
    const rows = [{ ID: "abc", Names: "omnirush-box-k", Image: "ghcr.io/omnirush-ai/box-base:1", State: "running", Labels: { "ai.omnirush.box": "1", "ai.omnirush.box.key": "k" }, Size: "57.2MB (virtual 1.1GB)" }];
    expect(parseJsonRows(JSON.stringify(rows))).toEqual(rows);
    expect(parseJsonRows(rows.map((r) => JSON.stringify(r)).join("\n"))).toEqual(rows);
    expect(labelsOf("a=1,b=x=y")).toEqual({ a: "1", b: "x=y" });
  });

  test("ranking: wslc, then the OmniRush distro, then Docker Desktop", async () => {
    const docker = "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe";
    const desktop = { ServerVersion: "27.3.1", OSType: "linux", OperatingSystem: "Docker Desktop" };
    const run: RunCommand = async (bin, args) => {
      if (bin === WSLC) return ok('{"Client":{"Version":"3.0.1.0"}}');
      if (bin === WSL) return wslRun()(bin, args);
      if (args[0] === "context") return ok("");
      return ok(desktop);
    };
    const env = { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" };
    expect(await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSLC, WSL, docker), run, fresh: true })).toMatchObject({ backend: "wslc" });
    const noWslc = await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSL, docker), run, fresh: true, all: true });
    expect(noWslc).toMatchObject({ ok: true, backend: "wsl" });
    expect(noWslc.alternatives?.find((a) => a.backend === "wslc")?.reason).toMatch(/wsl --update/);
    expect(await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSLC, WSL, docker), run, fresh: true, asked: "docker-desktop" })).toMatchObject({ backend: "docker-desktop" });
  });
});

// --- the record, the upload label, the desktop status ----------------------------------------

describe("box backends: record, label, status", () => {
  test("record and label: the backend is named; boxsh gets no exec fallback where there is no exec", () => {
    const home = tmp();
    const runFolder = path.join(home, "projects", "k");
    mkdirSync(runFolder, { recursive: true });
    const run: RunCommand = async () => ok("");
    const box = new Box({ key: "k", name: "omnirush-box-k", root: "/p", croot: "/p", runtime: { name: "bwrap", backend: "bwrap", bin: "/pkg/boxrun", version: "0.9.0", flavor: "overlayfs", rootless: true, arch: "amd64" }, home, runFolder, run, log: () => {}, platform: "linux", env: {} });
    box.connect({ port: 5, token: "t", uid: 0, gid: 0, containerId: "bwrap_k_1", imageId: `sha256:${"e".repeat(64)}` });
    box.writeRecord();
    const rec = JSON.parse(readFileSync(path.join(home, "boxes", "k.json"), "utf8"));
    expect({ backend: rec.backend, runtime: rec.runtime, args: rec.runtime_args }).toEqual({ backend: "bwrap", runtime: "", args: [] });
    mkdirSync(path.join(home, "chains", "k"), { recursive: true });
    writeFileSync(path.join(home, "chains", "k", "image.json"), JSON.stringify({ ref: "ghcr.io/omnirush-ai/box-base:2026.10.1", digest: `sha256:${"f".repeat(64)}`, stack: "base" }));
    const label = box.label();
    expect(label.backend).toBe("bwrap");
    expect(label.image.digest).toBe(`sha256:${"f".repeat(64)}`);
    const docker = new Box({ key: "d", name: "omnirush-box-d", root: "/p", croot: "/p", runtime: { name: "docker", backend: "docker-desktop", bin: "/usr/bin/docker", prefix: ["--context", "desktop-linux"] }, home, runFolder, run, log: () => {}, platform: "linux", env: {} });
    docker.connect({ port: 6, token: "t", uid: 0, gid: 0, containerId: "c", imageId: "i" });
    docker.writeRecord();
    const drec = JSON.parse(readFileSync(path.join(home, "boxes", "d.json"), "utf8"));
    expect({ backend: drec.backend, runtime: drec.runtime, args: drec.runtime_args }).toEqual({ backend: "docker-desktop", runtime: "/usr/bin/docker", args: ["--context", "desktop-linux"] });
  });

  test("files used read a non-container box through its exec (boxsh), not `docker exec`", async () => {
    if (process.platform === "win32") return;
    const dir = tmp();
    const file = path.join(dir, "note.txt");
    writeFileSync(file, "hello");
    const view = sandboxFilesUsed({ container: "omnirush-box-k", manifest: { home: "/root", workspaces: [] }, cwd: dir, hostHome: null, docker: "/nonexistent/docker", exec: { bin: "/bin/sh", args: ["-c", 'exec "$0" "$@"'], env: { OMNIRUSH_BOX_KEY: "k" } } });
    const facts = await view?.view.inspect([file], 1024);
    expect(facts?.get(file)).toMatchObject({ kind: "file", size: 5 });
  });

  test("the settings card's status: the backend, its version and why, the others, the setting and its choices", async () => {
    const stateDir = tmp();
    const home = tmp();
    const root = tmp();
    const workspace: BoxWorkspace = { id: "ws_1", path: root, workspaceType: "local" };
    const settings = new Map<string, { mode: "on" | "off" | null; offered: boolean }>([["ws_1", { mode: "on", offered: true }]]);
    const env = { OMNIRUSH_BOX_HOME: home, OMNIRUSH_BOX_BIN_DIR: tmp(), PATH: "", OMNIRUSH_BOX_RUNTIME: "/nonexistent/docker" };
    const boxes = new BoxService({
      stateDir,
      readSettings: async (id) => settings.get(id) ?? { mode: null, offered: false },
      writeSettings: async () => {},
      workspaces: () => [workspace],
      pluginPath: () => "/plugins/omnirush-box.js",
      env,
    });
    const status = await boxes.status(workspace, { fresh: true });
    expect(status.backendSetting).toMatchObject({ value: "auto", source: "auto" });
    expect(status.backendSetting.choices[0]).toEqual({ id: "auto", label: "Automatic" });
    expect(status.backendSetting.choices.at(-1)?.id).toBe("native");
    expect(status.backend).toMatchObject({ id: null, allowed: null });
    expect(status.backend?.why).toBeTruthy();
    expect(status.backend?.alternatives.every((alt) => typeof alt.id === "string" && typeof alt.ok === "boolean")).toBe(true);
    expect(await boxes.setBackend("native")).toBe("native");
    const native = await boxes.status(workspace, { fresh: true });
    expect(native.backendSetting).toMatchObject({ value: "native", source: "setting" });
    expect(native.state).toBe("unavailable");
    await expect(boxes.setBackend("lxc")).rejects.toThrow(/unknown sandbox backend/);
    rememberServerDefault(stateDir, { local_box: { default: "off", backends: ["podman"] } });
    await boxes.setBackend("auto");
    expect((await boxes.status(workspace, { fresh: true })).backend?.allowed).toEqual(["podman"]);
  });
});