Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

51.2 KB
Raw Blame
import { execFile, spawn } from "node:child_process";
import { createHash } from "node:crypto";
import {
  chmod,
  copyFile,
  mkdir,
  mkdtemp,
  readFile,
  readdir,
  rm,
  stat,
  writeFile,
} from "node:fs/promises";
import { createServer, type Server } from "node:http";
import type { AddressInfo } from "node:net";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { gzipSync } from "node:zlib";

import { afterEach, describe, expect, it } from "vitest";

const execFileAsync = promisify(execFile);
const repositoryRoot = path.resolve(
  fileURLToPath(new URL("../", import.meta.url)),
);
const installScriptPath = path.join(
  repositoryRoot,
  "scripts/install/install.sh",
);

const temporaryDirectories: string[] = [];
const cleanups: Array<() => Promise<void>> = [];

interface ScriptRunResult {
  code: number | null;
  stdout: string;
  stderr: string;
}

interface ComputerInvocation {
  argv: string[];
  path: string;
  piAgentDir: string;
}

interface FakeEngineScenario {
  acceptedStack?: boolean;
  lastRunState?: string;
  enforcePrivateRoot?: boolean;
  bootstrapError?: string;
  applyOutputLines?: string[];
  upFailsWithoutShareGpu?: boolean;
  preflightFail?: boolean;
  picks?: Array<{
    role: string;
    id: string;
    quant: string;
    quality: number;
    decodeTokS: number;
    decodeBasis: string;
    card: number;
    shared: boolean;
  }>;
  planPreflightWarn?: string;
  createGatewayPiOnApply?: boolean;
}

afterEach(async () => {
  await Promise.all(cleanups.splice(0).map((fn) => fn()));
  await Promise.all(
    temporaryDirectories
      .splice(0)
      .map((dir) => rm(dir, { recursive: true, force: true })),
  );
});

async function createTempRoot(): Promise<string> {
  const dir = await mkdtemp(path.join(os.tmpdir(), "linger-install-test-"));
  temporaryDirectories.push(dir);
  return dir;
}

async function resolvePythonExecutable(): Promise<string> {
  const { stdout } = await execFileAsync("sh", [
    "-c",
    "command -v python3 || command -v python",
  ]);
  const resolved = stdout.trim();
  if (!resolved) {
    throw new Error("python3 is required to run install.sh script tests");
  }
  return resolved;
}

async function createFakeStackScript(
  root: string,
  scenario: FakeEngineScenario,
): Promise<{
  scriptPath: string;
  logPath: string;
  kitHomeLogPath: string;
}> {
  const pythonBin = await resolvePythonExecutable();
  const scriptPath = path.join(root, "fake-stack.sh");
  const logPath = path.join(root, "stack-calls.log");
  const kitHomeLogPath = path.join(root, "kit-homes.log");
  const statusJsonPath = path.join(root, "fixture-status.json");
  const hardwareJsonPath = path.join(root, "fixture-hardware.json");
  const gatewayPiDir = path.join(
    root,
    "home",
    ".local/share/localmodels/tools/gateway-home/.pi/agent",
  );
  const piBinPath = path.join(root, "home", ".local/bin/pi");

  const statusPayload = scenario.acceptedStack
    ? {
        deployments: [{ name: "qwen3.8-27b", state: "active", ok: true }],
        last_run: {
          ok: true,
          plan_id: "plan-123456789abc",
          state: scenario.lastRunState ?? "completed",
          started_at: "2026-11-17T00:00:00Z",
          finished_at: "2026-11-17T00:05:00Z",
        },
      }
    : {
        deployments: [],
        last_run: null,
      };
  await writeFile(statusJsonPath, JSON.stringify(statusPayload));

  const picks = scenario.picks ?? [
    {
      role: "smartest",
      id: "qwen3.8-32b",
      quant: "UD-Q4_K_M",
      quality: 92,
      decodeTokS: 38,
      decodeBasis: "estimated",
      card: 0,
      shared: false,
    },
  ];
  const hardwarePayload = {
    system: "Linux",
    arch: "x86_64",
    ram_total_bytes: 128 * 1024 ** 3,
    ram_available_bytes: 96 * 1024 ** 3,
    disk_free_bytes: 400 * 1024 ** 3,
    cards: [
      {
        index: 0,
        name: "NVIDIA RTX PRO 6000",
        total_bytes: 96 * 1024 ** 3,
        free_bytes: 52 * 1024 ** 3,
        held_by: picks.some((p) => p.shared) ? ["vllm"] : [],
        auto: !picks.some((p) => p.shared),
      },
    ],
    picks: picks.map((p) => ({
      role: p.role,
      id: p.id,
      quant: p.quant,
      quality: p.quality,
      decode_tok_s: p.decodeTokS,
      decode_basis: p.decodeBasis,
      card: p.card,
      shared: p.shared,
    })),
  };
  await writeFile(hardwareJsonPath, JSON.stringify(hardwarePayload));

  const warnFinding: Array<{
    check: string;
    level: string;
    detail: string;
    fix?: string;
  }> = scenario.planPreflightWarn
    ? [
        {
          check: "preflight.gpu",
          level: "warn",
          detail: "2 compute process(es) outside the stack on its GPU",
          fix: "make sure they can share the card",
        },
        {
          check: "preflight.running",
          level: "warn",
          detail:
            "this tool still runs 1 other deployment(s): kokoro-82m-18380",
          fix: "use stack plan --update, or stop one with 'stack service local foo stop'",
        },
        {
          check: "preflight.note",
          level: "warn",
          detail: scenario.planPreflightWarn,
          fix: "Run stack up after reboot, or plan another --llm-port",
        },
      ]
    : [];
  if (scenario.preflightFail) {
    warnFinding.push({
      check: "preflight.disk",
      level: "fail",
      detail: "Not enough free disk space; see stack.sh docs",
      fix: "Free 20 GiB and retry stack plan",
    });
  }
  const planTemplate = {
    plan_id: "plan-abcdef123456",
    llm: {
      model: {
        id: "qwen3.8-27b",
        display_name: "Qwen 3.8 27B",
        quant: "UD-Q4_K_M",
      },
      placement: {
        label: "GPU 0",
      },
      launch: {
        window: 131072,
      },
    },
    decision: {
      model: {
        id: "qwen3-4b",
        display_name: "Qwen 3 4B",
      },
    },
    aux: [
      {
        name: "embed",
        endpoint: { contract: "embedding" },
        model: { id: "bge-m3", display_name: "BGE M3" },
      },
    ],
    budget: {
      download_bytes: 18 * 1024 ** 3,
      disk_needed_bytes: 20 * 1024 ** 3,
      ram_needed_bytes: 8 * 1024 ** 3,
      ram_available_bytes: 96 * 1024 ** 3,
    },
    preflight: {
      counts: {
        pass: 3,
        warn: warnFinding.filter((f) => f.level === "warn").length,
        fail: warnFinding.filter((f) => f.level === "fail").length,
      },
      findings: warnFinding,
    },
  };
  const planTemplatePath = path.join(root, "fixture-plan.json");
  await writeFile(planTemplatePath, JSON.stringify(planTemplate));

  const createPiOnApply = scenario.createGatewayPiOnApply !== false;
  const enforcePrivateRoot = scenario.enforcePrivateRoot ? "1" : "0";
  const applyLines = scenario.applyOutputLines
    ? scenario.applyOutputLines
        .map((line) => `    printf '%s\\n' ${JSON.stringify(line)}`)
        .join("\n")
    : `    printf 'Applied plan %s\\n' "\${4:-}"`;
  const bootstrapFailure = scenario.bootstrapError
    ? `  printf '%s\\n' ${JSON.stringify(scenario.bootstrapError)} >&2\n  exit 2\n`
    : "";
  const upShareGuard = scenario.upFailsWithoutShareGpu
    ? `    if [ "\${2:-}" != "--share-gpu" ]; then\n      printf 'stack: GPU busy; pass --share-gpu\\n' >&2\n      exit 3\n    fi\n`
    : "";
  const content = `#!/bin/sh
set -eu
printf '%s\n' "$*" >> ${JSON.stringify(logPath)}
if [ "${enforcePrivateRoot}" = "1" ] && [ "\${1:-}" = "--bootstrap-json" ]; then
  kit_root="\${LOCALMODELS_KIT_HOME:-\${XDG_CACHE_HOME:-\${HOME}/.cache}/simplex-localmodels/kits}"
  printf '%s\n' "$kit_root" >> ${JSON.stringify(kitHomeLogPath)}
  owner="$(id -u)"
  ancestor="$(dirname "$kit_root")"
  while :; do
    [ ! -L "$ancestor" ] || { printf 'stack.sh: cache root must be a private owned directory\n' >&2; exit 2; }
    if [ -e "$ancestor" ]; then
      bad_parent="$(find "$ancestor" -prune \\( \\( ! -user "$owner" ! -user 0 \\) -o \\( \\( -perm -0020 -o -perm -0002 \\) ! -perm -1000 \\) \\) -print || true)"
      [ -z "$bad_parent" ] || { printf 'stack.sh: cache root must be a private owned directory\n' >&2; exit 2; }
    fi
    [ "$ancestor" != / ] || break
    ancestor="$(dirname "$ancestor")"
  done
fi
case "\${1:-}" in
  --bootstrap-json)
${bootstrapFailure}    printf '{"schema":"localmodels.kit-location/v1","kitRoot":%s,"python":%s,"moduleDir":"modules"}\n' \
      ${JSON.stringify(JSON.stringify(root))} \
      ${JSON.stringify(JSON.stringify(pythonBin))}
    ;;
  status)
    if [ "\${2:-}" = "--json" ]; then
      cat ${JSON.stringify(statusJsonPath)}
    else
      printf 'qwen3.8-27b active\n'
      printf 'Services down after a reboot? python3 -m localmodels stack up starts them without reinstalling\n'
    fi
    ;;
  hardware)
    cat ${JSON.stringify(hardwareJsonPath)}
    ;;
  plan)
    out_file=""
    prev=""
    for arg in "$@"; do
      if [ "$prev" = "--out" ]; then
        out_file="$arg"
      fi
      prev="$arg"
    done
    cp ${JSON.stringify(planTemplatePath)} "$out_file"
    cat "$out_file"
    ;;
  apply)
${applyLines}
    if [ "${createPiOnApply ? "1" : "0"}" = "1" ]; then
      mkdir -p ${JSON.stringify(path.dirname(piBinPath))} ${JSON.stringify(gatewayPiDir)}
      cat <<'PIEOF' > ${JSON.stringify(piBinPath)}
#!/bin/sh
exit 0
PIEOF
      chmod 0755 ${JSON.stringify(piBinPath)}
      printf '{"providers":{}}\n' > ${JSON.stringify(path.join(gatewayPiDir, "models.json"))}
    fi
    ;;
  up)
${upShareGuard}    printf 'Local model stack is ready\n'
    ;;
  remove)
    case " $* " in
      *" --dry-run "*)
        printf 'Would delete cached weights via stack remove --purge\n'
        ;;
      *)
        printf 'Removed. Run stack remove --purge to free downloaded files.\n'
        ;;
    esac
    ;;
  *)
    printf 'stack.sh: unexpected subcommand %s\n' "\${1:-}" >&2
    exit 2
    ;;
esac
`;
  await writeFile(scriptPath, content, { mode: 0o755 });
  return { scriptPath, logPath, kitHomeLogPath };
}

async function startMockLingerServer(
  root: string,
  authorized: boolean,
): Promise<{
  baseUrl: string;
  installerRequests: () => number;
  computerLogPath: string;
}> {
  const computerLogPath = path.join(root, "computer-calls.jsonl");
  const binDir = path.join(root, "bin");
  await mkdir(binDir, { recursive: true });
  let requestCount = 0;

  const installerScript = `#!/usr/bin/env bash
# linger-computer-launcher-v2
set -euo pipefail
web_origin="\${LINGER_WEB_URL:?LINGER_WEB_URL is required}"
rest="\${web_origin#*://}"
host="\${rest%%:*}"
port="\${rest#"$host"}"
port="\${port#:}"
env_name="local-\${port}"
bin_dir="\${LINGER_COMPUTER_BIN_DIR:-$HOME/.local/bin}"
mkdir -p "$bin_dir"
launcher="$bin_dir/linger-computer-$env_name"
cat <<'CLI_EOF' > "$launcher"
#!/usr/bin/env bash
# linger-computer-launcher-v2
set -euo pipefail
printf '{"argv":[' >> ${JSON.stringify(computerLogPath)}
first=1
for a in "$@"; do
  if [ "$first" -eq 0 ]; then printf ',' >> ${JSON.stringify(computerLogPath)}; fi
  printf '"%s"' "$(printf '%s' "$a" | sed 's/"/\\"/g')" >> ${JSON.stringify(computerLogPath)}
  first=0
done
printf '],"path":"%s","piAgentDir":"%s"}\n' \
  "$(printf '%s' "\${PATH:-}" | sed 's/"/\\"/g')" \
  "$(printf '%s' "\${PI_CODING_AGENT_DIR:-}" | sed 's/"/\\"/g')" >> ${JSON.stringify(computerLogPath)}

if [ "\${1:-}" = "auth" ] && [ "\${2:-}" = "status" ]; then
  printf '{"version":1,"authorized":${authorized ? "true" : "false"}}\n'
  exit 0
fi
if [ "\${1:-}" = "daemon" ] && [ "\${2:-}" = "status" ]; then
  printf 'Daemon: running\n'
  exit 0
fi
exit 0
CLI_EOF
chmod 0755 "$launcher"
`;

  const server: Server = createServer((req, res) => {
    if (req.url === "/install/linger-computer.sh") {
      requestCount += 1;
      res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
      res.end(installerScript);
      return;
    }
    res.writeHead(404);
    res.end("not found");
  });

  await new Promise<void>((resolve) => {
    server.listen(0, "127.0.0.1", () => resolve());
  });
  cleanups.push(
    () =>
      new Promise<void>((resolve, reject) => {
        server.close((err) => (err ? reject(err) : resolve()));
      }),
  );

  const address = server.address() as AddressInfo;
  return {
    baseUrl: `http://127.0.0.1:${address.port}`,
    installerRequests: () => requestCount,
    computerLogPath,
  };
}

async function runInstallScript(
  args: string[],
  options: {
    env: NodeJS.ProcessEnv;
    input?: string;
    scriptPath?: string;
    cwd?: string;
  },
): Promise<ScriptRunResult> {
  return await new Promise<ScriptRunResult>((resolve, reject) => {
    const child = spawn(
      "bash",
      [options.scriptPath ?? installScriptPath, ...args],
      {
        cwd: options.cwd ?? repositoryRoot,
        env: options.env,
        stdio: ["pipe", "pipe", "pipe"],
      },
    );
    let stdout = "";
    let stderr = "";
    child.stdout.setEncoding("utf8");
    child.stderr.setEncoding("utf8");
    child.stdout.on("data", (chunk: string) => {
      stdout += chunk;
    });
    child.stderr.on("data", (chunk: string) => {
      stderr += chunk;
    });
    child.on("error", reject);
    child.on("close", (code) => {
      resolve({ code, stdout, stderr });
    });
    child.stdin.end(options.input ?? "");
  });
}

function buildTestEnv(root: string, stackScript: string): NodeJS.ProcessEnv {
  const homeDir = path.join(root, "home");
  const binDir = path.join(root, "bin");
  return {
    HOME: homeDir,
    PATH: `/usr/local/bin:/usr/bin:/bin`,
    LINGER_STACK_SCRIPT: stackScript,
    LINGER_COMPUTER_BIN_DIR: binDir,
  };
}

async function readComputerCalls(
  logPath: string,
): Promise<ComputerInvocation[]> {
  const raw = await readFile(logPath, "utf8");
  return raw
    .trim()
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line) as ComputerInvocation);
}

describe("root install.sh", () => {
  it("prints help without exposing internal stack.sh or PI_CODING_AGENT_DIR details", async () => {
    const root = await createTempRoot();
    const { scriptPath } = await createFakeStackScript(root, {});
    const result = await runInstallScript(["--help"], {
      env: buildTestEnv(root, scriptPath),
    });

    expect(result.code).toBe(0);
    expect(result.stdout).toContain("--web-url");
    expect(result.stdout).toContain("--connect");
    expect(result.stdout).toContain("--up");
    expect(result.stdout).toContain("--status");
    expect(result.stdout).toContain("--remove");
    const combined = `${result.stdout}\n${result.stderr}`;
    expect(combined).not.toContain("stack.sh");
    expect(combined).not.toContain("PI_CODING_AGENT_DIR");
    expect(combined).not.toContain("gateway-home");
  });

  it("guides through shared GPU selection, plan approval, and linger-computer login", async () => {
    const root = await createTempRoot();
    const homeDir = path.join(root, "home");
    await mkdir(homeDir, { recursive: true });
    const { scriptPath, logPath } = await createFakeStackScript(root, {
      picks: [
        {
          role: "smartest",
          id: "qwen3.8-32b",
          quant: "UD-Q4_K_M",
          quality: 92,
          decodeTokS: 38,
          decodeBasis: "estimated",
          card: 0,
          shared: true,
        },
        {
          role: "fastest",
          id: "qwen3.8-9b",
          quant: "Q4_K_M",
          quality: 78,
          decodeTokS: 72,
          decodeBasis: "measured-decode",
          card: 0,
          shared: true,
        },
      ],
      planPreflightWarn: "Shared card detected; check stack.sh settings",
    });
    const server = await startMockLingerServer(root, false);

    const result = await runInstallScript(["--web-url", server.baseUrl], {
      env: buildTestEnv(root, scriptPath),
      input: ["2", "y", "24G", "y", "y"].join("\n") + "\n",
    });

    expect(result.code).toBe(0);
    expect(result.stdout).toContain("[1/4] Checking Linger server");
    expect(result.stdout).toContain(
      "[2/4] Checking hardware and model options",
    );
    expect(result.stdout).toContain(
      "[3/4] Installing and verifying the local model",
    );
    expect(result.stdout).toContain("[4/4] Connecting this computer to Linger");

    const stackCalls = (await readFile(logPath, "utf8")).trim().split("\n");
    const planCall = stackCalls.find((line) => line.startsWith("plan "));
    expect(planCall).toBeDefined();
    expect(planCall).not.toContain("search");
    expect(planCall).toContain("--prefer fastest");
    expect(planCall).toContain("--gpu 0");
    expect(planCall).toContain("--share-gpu");
    expect(planCall).toContain("--gpu-memory 24G");
    expect(planCall).toContain("--decision auto");
    expect(planCall).toContain("--aux embedding,reranker");

    expect(result.stdout).not.toContain("2 compute process(es) outside");
    expect(result.stdout).toContain("kept untouched on separate ports");
    expect(result.stdout).not.toContain("stack service");
    expect(result.stdout).not.toContain("--llm-port");

    const applyCall = stackCalls.find((line) => line.startsWith("apply "));
    expect(applyCall).toContain("--approve plan-abcdef123456");

    expect(server.installerRequests()).toBe(2);
    const computerCalls = await readComputerCalls(server.computerLogPath);
    const expectedPiDir = path.join(
      homeDir,
      ".local/share/localmodels/tools/gateway-home/.pi/agent",
    );
    const expectedPiBin = path.join(homeDir, ".local/bin/pi");

    expect(computerCalls.map((c) => c.argv.slice(0, 2))).toEqual([
      ["auth", "status"],
      ["login", "--web-url"],
      ["runtime", "check"],
    ]);
    expect(computerCalls[1]?.argv).toEqual([
      "login",
      "--web-url",
      server.baseUrl,
      "--pi-path",
      expectedPiBin,
    ]);
    expect(computerCalls[1]?.piAgentDir).toBe(expectedPiDir);
    expect(computerCalls[1]?.path).toContain(path.join(homeDir, ".local/bin"));
    expect(computerCalls[2]?.argv).toEqual([
      "runtime",
      "check",
      "pi",
      "--live",
      "--pi-path",
      expectedPiBin,
    ]);
    expect(computerCalls[2]?.piAgentDir).toBe(expectedPiDir);

    const combined = `${result.stdout}\n${result.stderr}`;
    expect(combined).not.toContain("stack.sh");
    expect(combined).not.toContain("PI_CODING_AGENT_DIR");
    expect(combined).not.toContain("gateway-home");
  });

  it("exits cleanly when plan approval is declined without downloading or connecting", async () => {
    const root = await createTempRoot();
    await mkdir(path.join(root, "home"), { recursive: true });
    const { scriptPath, logPath } = await createFakeStackScript(root, {});
    const server = await startMockLingerServer(root, false);

    const result = await runInstallScript(["--web-url", server.baseUrl], {
      env: buildTestEnv(root, scriptPath),
      input: ["n", "n"].join("\n") + "\n",
    });

    expect(result.code).toBe(0);
    expect(result.stdout).toContain("Nothing was downloaded or changed");
    const stackCalls = await readFile(logPath, "utf8");
    expect(stackCalls).not.toContain("apply ");
    expect(server.installerRequests()).toBe(1);
    expect(`${result.stdout}\n${result.stderr}`).not.toContain("stack.sh");
  });

  it("reuses an accepted local model stack and restarts an authorized computer daemon", async () => {
    const root = await createTempRoot();
    const homeDir = path.join(root, "home");
    const piDir = path.join(
      homeDir,
      ".local/share/localmodels/tools/gateway-home/.pi/agent",
    );
    const piBin = path.join(homeDir, ".local/bin/pi");
    await mkdir(piDir, { recursive: true });
    await mkdir(path.dirname(piBin), { recursive: true });
    await writeFile(path.join(piDir, "models.json"), "{}");
    await writeFile(piBin, "#!/bin/sh\nexit 0\n");
    await chmod(piBin, 0o755);

    const { scriptPath, logPath } = await createFakeStackScript(root, {
      acceptedStack: true,
    });
    const server = await startMockLingerServer(root, true);

    const result = await runInstallScript(["--web-url", server.baseUrl], {
      env: buildTestEnv(root, scriptPath),
      input: "\n",
    });

    expect(result.code).toBe(0);
    const stackCalls = (await readFile(logPath, "utf8")).trim().split("\n");
    expect(stackCalls).toContain("up");
    expect(stackCalls.some((line) => line.startsWith("hardware"))).toBe(false);
    expect(stackCalls.some((line) => line.startsWith("plan"))).toBe(false);
    expect(stackCalls.some((line) => line.startsWith("apply"))).toBe(false);

    const computerCalls = await readComputerCalls(server.computerLogPath);
    expect(computerCalls.map((c) => c.argv.slice(0, 2))).toEqual([
      ["auth", "status"],
      ["daemon", "restart"],
      ["runtime", "check"],
    ]);
    expect(computerCalls[1]?.piAgentDir).toBe(piDir);
  });

  it("sanitizes day-2 --status and --remove output without exposing stack commands", async () => {
    const root = await createTempRoot();
    await mkdir(path.join(root, "home"), { recursive: true });
    const { scriptPath, logPath } = await createFakeStackScript(root, {
      acceptedStack: true,
    });

    const statusResult = await runInstallScript(["--status"], {
      env: buildTestEnv(root, scriptPath),
    });
    expect(statusResult.code).toBe(0);
    expect(statusResult.stdout).toContain("./scripts/install/install.sh --up");
    expect(statusResult.stdout).not.toContain("stack up");
    expect(statusResult.stdout).not.toContain("localmodels");

    const removeResult = await runInstallScript(
      ["--remove", "--purge", "--yes"],
      {
        env: buildTestEnv(root, scriptPath),
      },
    );
    expect(removeResult.code).toBe(0);
    expect(removeResult.stdout).toContain(
      "./scripts/install/install.sh --remove --purge",
    );
    expect(removeResult.stdout).not.toContain("stack remove");

    const stackCalls = (await readFile(logPath, "utf8")).trim().split("\n");
    expect(stackCalls).toContain("status");
    expect(stackCalls).toContain("remove --purge --yes");
  });

  it("falls back from group-writable XDG cache to a private kit root and temp fallback", async () => {
    const root = await createTempRoot();
    const homeDir = path.join(root, "home");
    const xdgCache = path.join(root, "shared-cache");
    const privateTmp = path.join(root, "private-tmp");
    await mkdir(homeDir, { recursive: true });
    await mkdir(xdgCache, { recursive: true });
    await mkdir(privateTmp, { recursive: true });
    await chmod(root, 0o755);
    await chmod(homeDir, 0o700);
    await chmod(xdgCache, 0o775);
    await chmod(privateTmp, 0o700);

    const { scriptPath, kitHomeLogPath } = await createFakeStackScript(root, {
      enforcePrivateRoot: true,
    });

    const first = await runInstallScript(["--status"], {
      env: {
        ...buildTestEnv(root, scriptPath),
        XDG_CACHE_HOME: xdgCache,
        TMPDIR: privateTmp,
      },
    });
    expect(first.code).toBe(0);
    const firstLogged = (await readFile(kitHomeLogPath, "utf8"))
      .trim()
      .split("\n");
    expect(firstLogged[0]).toBe(path.join(homeDir, ".linger/localmodels/kits"));
    const homeKitStat = await stat(firstLogged[0] ?? "");
    expect(homeKitStat.mode & 0o777).toBe(0o700);

    await chmod(homeDir, 0o775);
    const second = await runInstallScript(["--status"], {
      env: {
        ...buildTestEnv(root, scriptPath),
        XDG_CACHE_HOME: xdgCache,
        TMPDIR: privateTmp,
      },
    });
    expect(second.code).toBe(0);
    const secondLogged = (await readFile(kitHomeLogPath, "utf8"))
      .trim()
      .split("\n");
    expect(
      secondLogged[1]?.startsWith(path.join(privateTmp, "linger-kit.")),
    ).toBe(true);
    expect(await readdir(privateTmp)).toEqual([]);
  });

  it("reassigns colliding Compose ports and preserves LiveKit RTC ports on rerun", async () => {
    const root = await createTempRoot();
    const fakeRepo = path.join(root, "fake-repo");
    const fakeBin = path.join(root, "fake-bin");
    const homeDir = path.join(root, "home");
    const xdgCache = path.join(root, "cache");
    const dockerLogPath = path.join(root, "docker-calls.log");
    const serverStartedPath = path.join(root, "server-started");
    await mkdir(path.join(fakeRepo, "scripts/install"), { recursive: true });
    await mkdir(path.join(fakeRepo, "scripts/installs"), { recursive: true });
    await mkdir(path.join(fakeRepo, ".linger-runtime"), { recursive: true });
    await chmod(path.join(fakeRepo, ".linger-runtime"), 0o555);
    cleanups.push(async () => {
      await chmod(path.join(fakeRepo, ".linger-runtime"), 0o755);
    });
    await mkdir(fakeBin, { recursive: true });
    await mkdir(homeDir, { recursive: true });
    await mkdir(xdgCache, { recursive: true });
    await chmod(homeDir, 0o700);
    await chmod(xdgCache, 0o700);

    const copiedInstallPath = path.join(fakeRepo, "scripts/install/install.sh");
    await copyFile(installScriptPath, copiedInstallPath);
    await chmod(copiedInstallPath, 0o755);

    const { scriptPath: fakeStackPath } = await createFakeStackScript(root, {});
    await copyFile(
      fakeStackPath,
      path.join(fakeRepo, "scripts/installs/stack.sh"),
    );
    await chmod(path.join(fakeRepo, "scripts/installs/stack.sh"), 0o755);

    await writeFile(fakeRepo + "/docker-compose.yml", "services:\n  web:\n");
    await writeFile(
      path.join(fakeRepo, ".env.example"),
      [
        "WEB_PUBLIC_ORIGIN=http://localhost:3000",
        "AGENT_RUNNER_PUBLIC_GATEWAY_URL=ws://127.0.0.1:4319/v1/runner-gateway",
        "LIVEKIT_URL=ws://127.0.0.1:17880",
        "# POSTGRES_PORT=5432",
        "# TEAMHUB_HTTP_PORT=8080",
        "# WEB_HTTP_PORT=3000",
      ].join("\n") + "\n",
    );

    await writeFile(
      path.join(fakeBin, "docker"),
      `#!/bin/sh
set -eu
printf '%s\n' "$*" >> ${JSON.stringify(dockerLogPath)}
if [ "\${1:-}" = "compose" ] && [ "\${2:-}" = "version" ]; then
  printf '2.24.4\n'
  exit 0
fi
if [ "\${1:-}" = "compose" ] && [ "\${2:-}" = "ps" ]; then
  printf '127.0.0.1:5432->5432/tcp\n'
  exit 0
fi
if [ "\${1:-}" = "compose" ] && [ "\${2:-}" = "up" ]; then
  touch ${JSON.stringify(serverStartedPath)}
fi
exit 0
`,
      { mode: 0o755 },
    );

    await writeFile(
      path.join(fakeBin, "curl"),
      `#!/bin/sh
set -eu
out=""
url=""
prev=""
for a in "$@"; do
  case "$prev" in
    -o|--output) out="$a" ;;
  esac
  case "$a" in
    http://*|https://*) url="$a" ;;
  esac
  prev="$a"
done
case "$url" in
  "http://localhost:3001/install/linger-computer.sh")
    if [ ! -f ${JSON.stringify(serverStartedPath)} ]; then exit 22; fi
    body="# linger-computer-launcher-v2"
    if [ -n "$out" ]; then printf '%s\n' "$body" > "$out"; else printf '%s\n' "$body"; fi
    exit 0
    ;;
  *)
    exit 22
    ;;
esac
`,
      { mode: 0o755 },
    );

    const result = await runInstallScript([], {
      scriptPath: copiedInstallPath,
      cwd: fakeRepo,
      env: {
        HOME: homeDir,
        XDG_CACHE_HOME: xdgCache,
        PATH: `${fakeBin}:/usr/local/bin:/usr/bin:/bin`,
        LINGER_INSTALL_BUSY_PORTS: "3000,17880,7881,7882",
      },
      input: ["1", "y", "n", "n", "n"].join("\n") + "\n",
    });

    expect(result.code).toBe(0);
    expect(result.stdout).toContain(
      "Port(s) already in use: 3000, 17880, 7881, 7882",
    );
    expect(result.stdout).toContain("Nothing was downloaded or changed.");

    const updatedEnv = await readFile(path.join(fakeRepo, ".env"), "utf8");
    expect(updatedEnv).toContain("WEB_HTTP_PORT=3001");
    expect(updatedEnv).toContain("WEB_PUBLIC_ORIGIN=http://localhost:3001");
    expect(updatedEnv).toContain("LIVEKIT_URL=ws://127.0.0.1:17881");
    expect(updatedEnv).not.toMatch(
      /^LIVEKIT_(HTTP_PORT|RTC_TCP_PORT|RTC_UDP_PORT)=/m,
    );
    expect(updatedEnv).toContain(
      "COMPOSE_FILE=docker-compose.yml:.local/compose.ports.yml",
    );
    expect(updatedEnv).not.toContain("POSTGRES_PORT=5433");
    const overridePath = path.join(fakeRepo, ".local/compose.ports.yml");
    const override = await readFile(overridePath, "utf8");
    expect(override).toContain(
      "entrypoint: /livekit-server --rtc.tcp_port 7883 --udp-port 7884",
    );
    expect(override).not.toContain("command:");
    expect(override).toContain("ports: !override");
    expect(override).toContain('"127.0.0.1:17881:7880"');
    expect(override).toContain(
      '"${LIVEKIT_RTC_BIND_ADDRESS:-127.0.0.1}:7883:7883"',
    );
    expect(override).toContain(
      '"${LIVEKIT_RTC_BIND_ADDRESS:-127.0.0.1}:7884:7884/udp"',
    );

    const dockerCalls = await readFile(dockerLogPath, "utf8");
    expect(dockerCalls).toContain("compose up --build --detach --wait");

    await rm(serverStartedPath);
    const repeated = await runInstallScript([], {
      scriptPath: copiedInstallPath,
      cwd: fakeRepo,
      env: {
        HOME: homeDir,
        XDG_CACHE_HOME: xdgCache,
        PATH: `${fakeBin}:/usr/local/bin:/usr/bin:/bin`,
        LINGER_INSTALL_BUSY_PORTS: "3000,17880,7881,7882",
      },
      input: ["1", "n", "n", "n"].join("\n") + "\n",
    });
    expect(repeated.code).toBe(0);
    expect(repeated.stdout).toContain("Starting Linger with Docker Compose...");
    expect(repeated.stdout).not.toContain("Port(s) already in use:");
    expect(await readFile(path.join(fakeRepo, ".env"), "utf8")).toBe(
      updatedEnv,
    );
    expect(await readFile(overridePath, "utf8")).toBe(override);

    const dockerPath = path.join(fakeBin, "docker");
    await writeFile(
      dockerPath,
      (await readFile(dockerPath, "utf8")).replace("2.24.4", "2.24.3"),
    );
    await rm(serverStartedPath);
    const unsupported = await runInstallScript([], {
      scriptPath: copiedInstallPath,
      cwd: fakeRepo,
      env: {
        HOME: homeDir,
        XDG_CACHE_HOME: xdgCache,
        PATH: `${fakeBin}:/usr/local/bin:/usr/bin:/bin`,
        LINGER_INSTALL_BUSY_PORTS: "3001,17881,7883",
      },
      input: ["1", "y"].join("\n") + "\n",
    });
    expect(unsupported.code).toBe(1);
    expect(unsupported.stderr).toContain(
      "requires Docker Compose 2.24.4 or later",
    );
    expect(await readFile(path.join(fakeRepo, ".env"), "utf8")).toBe(
      updatedEnv,
    );
    expect(await readFile(overridePath, "utf8")).toBe(override);
  });

  it("validates CLI flags, conflicting modes, and standalone menu outside repo", async () => {
    const root = await createTempRoot();
    const { scriptPath } = await createFakeStackScript(root, {});
    const env = buildTestEnv(root, scriptPath);

    const shortHelp = await runInstallScript(["-h"], { env });
    expect(shortHelp.code).toBe(0);
    expect(shortHelp.stdout).toContain("--web-url");

    const unknown = await runInstallScript(["--bogus"], { env });
    expect(unknown.code).toBe(1);
    expect(unknown.stderr).toContain("Unknown option: --bogus");

    const conflict = await runInstallScript(["--connect", "--up"], { env });
    expect(conflict.code).toBe(1);
    expect(conflict.stderr).toContain(
      "Options --connect and --up cannot be combined",
    );

    const missingUrl = await runInstallScript(["--web-url"], { env });
    expect(missingUrl.code).toBe(1);
    expect(missingUrl.stderr).toContain("--web-url requires an origin URL");

    const invalidUrl = await runInstallScript(["--web-url", "not-a-url"], {
      env,
    });
    expect(invalidUrl.code).toBe(1);
    expect(invalidUrl.stderr).toContain("Invalid Linger server URL");

    const standaloneDir = path.join(root, "standalone");
    await mkdir(standaloneDir, { recursive: true });
    const standalonePath = path.join(standaloneDir, "install.sh");
    await copyFile(installScriptPath, standalonePath);
    await chmod(standalonePath, 0o755);

    const saHelp = await runInstallScript(["--help"], {
      scriptPath: standalonePath,
      cwd: standaloneDir,
      env,
    });
    expect(saHelp.code).toBe(0);
    expect(saHelp.stdout).toContain("Usage: ./install.sh");

    const saMenu = await runInstallScript(["--web-url", "http://127.0.0.1:9"], {
      scriptPath: standalonePath,
      cwd: standaloneDir,
      env,
      input: "9\n",
    });
    expect(saMenu.code).toBe(1);
    expect(saMenu.stdout).not.toContain("Docker Compose");
    expect(saMenu.stderr).toContain("Invalid choice: 9");
  });

  it("supports custom URL retry/force/skip and local-models-only flows", async () => {
    const root = await createTempRoot();
    await mkdir(path.join(root, "home"), { recursive: true });
    const { scriptPath } = await createFakeStackScript(root, {});
    const server = await startMockLingerServer(root, false);
    const standaloneDir = path.join(root, "standalone");
    await mkdir(standaloneDir, { recursive: true });
    const standalonePath = path.join(standaloneDir, "install.sh");
    await copyFile(installScriptPath, standalonePath);
    await chmod(standalonePath, 0o755);

    const customRetry = await runInstallScript(
      ["--web-url", "http://127.0.0.1:9"],
      {
        scriptPath: standalonePath,
        cwd: standaloneDir,
        env: buildTestEnv(root, scriptPath),
        input:
          [
            "1",
            "bad-url",
            "http://127.0.0.1:9",
            "n",
            server.baseUrl,
            "n",
            "n",
          ].join("\n") + "\n",
      },
    );
    expect(customRetry.code).toBe(0);
    expect(customRetry.stdout).toContain("Invalid URL");
    expect(customRetry.stdout).toContain(
      `Found Linger server at ${server.baseUrl}`,
    );

    const skipResult = await runInstallScript(
      ["--web-url", "http://127.0.0.1:9"],
      {
        scriptPath: standalonePath,
        cwd: standaloneDir,
        env: buildTestEnv(root, scriptPath),
        input: ["2", "n", "y"].join("\n") + "\n",
      },
    );
    expect(skipResult.code).toBe(0);
    expect(skipResult.stdout).toContain("Continuing with local models only");
    expect(skipResult.stdout).toContain("./install.sh --connect --web-url");
  });

  it("handles Compose port decline, owner retry, and explicit URL reset", async () => {
    const root = await createTempRoot();
    const fakeRepo = path.join(root, "fake-repo");
    const fakeBin = path.join(root, "fake-bin");
    const homeDir = path.join(root, "home");
    const xdgCache = path.join(root, "cache");
    const teamhubLog = path.join(root, "teamhub.log");
    await mkdir(path.join(fakeRepo, "scripts/install"), { recursive: true });
    await mkdir(path.join(fakeRepo, "scripts/installs"), { recursive: true });
    await mkdir(fakeBin, { recursive: true });
    await mkdir(homeDir, { recursive: true });
    await mkdir(xdgCache, { recursive: true });
    await chmod(homeDir, 0o700);
    await chmod(xdgCache, 0o700);

    const copiedInstallPath = path.join(fakeRepo, "scripts/install/install.sh");
    await copyFile(installScriptPath, copiedInstallPath);
    await chmod(copiedInstallPath, 0o755);

    const { scriptPath: fakeStackPath } = await createFakeStackScript(root, {});
    await copyFile(
      fakeStackPath,
      path.join(fakeRepo, "scripts/installs/stack.sh"),
    );
    await chmod(path.join(fakeRepo, "scripts/installs/stack.sh"), 0o755);

    await writeFile(fakeRepo + "/docker-compose.yml", "services:\n  web:\n");
    await writeFile(
      path.join(fakeRepo, ".env.example"),
      "WEB_PUBLIC_ORIGIN=http://localhost:3000\n# WEB_HTTP_PORT=3000\n",
    );

    const server = await startMockLingerServer(root, false);
    const serverPort = new URL(server.baseUrl).port;

    await writeFile(
      path.join(fakeBin, "docker"),
      `#!/bin/sh
set -eu
if [ "\${1:-}" = "compose" ] && [ "\${2:-}" = "version" ]; then
  printf 'Docker Compose version v2.40.2\n'
  exit 0
fi
if [ "\${1:-}" = "compose" ] && [ "\${2:-}" = "exec" ]; then
  cat > ${JSON.stringify(teamhubLog)}
  exit 0
fi
exit 0
`,
      { mode: 0o755 },
    );

    await writeFile(
      path.join(fakeBin, "curl"),
      `#!/bin/sh
set -eu
out=""
url=""
prev=""
for a in "$@"; do
  case "$prev" in -o|--output) out="$a" ;; esac
  case "$a" in http://*|https://*) url="$a" ;; esac
  prev="$a"
done
case "$url" in
  "${server.baseUrl}/install/linger-computer.sh")
    body="# linger-computer-launcher-v2"
    if [ -n "$out" ]; then printf '%s\n' "$body" > "$out"; else printf '%s\n' "$body"; fi
    exit 0
    ;;
  *)
    exit 22
    ;;
esac
`,
      { mode: 0o755 },
    );

    const env: NodeJS.ProcessEnv = {
      HOME: homeDir,
      XDG_CACHE_HOME: xdgCache,
      PATH: `${fakeBin}:/usr/local/bin:/usr/bin:/bin`,
      LINGER_INSTALL_BUSY_PORTS: "3000",
    };

    const declinedPorts = await runInstallScript([], {
      scriptPath: copiedInstallPath,
      cwd: fakeRepo,
      env,
      input: ["1", "n"].join("\n") + "\n",
    });
    expect(declinedPorts.code).toBe(1);
    expect(declinedPorts.stderr).toContain("Free those ports");

    await writeFile(
      path.join(fakeRepo, ".env"),
      `WEB_PUBLIC_ORIGIN=${server.baseUrl}\nWEB_HTTP_PORT=${serverPort}\n`,
    );

    const resetExplicit = await runInstallScript(
      ["--web-url", "http://127.0.0.1:9"],
      {
        scriptPath: copiedInstallPath,
        cwd: fakeRepo,
        env: { ...env, LINGER_INSTALL_BUSY_PORTS: "" },
        input: ["1", "y", "", "short", "", "n", "n"].join("\n") + "\n",
      },
    );
    expect(resetExplicit.code).toBe(0);
    expect(resetExplicit.stdout).toContain(
      "Password must be at least 8 characters",
    );
    expect(resetExplicit.stdout).toContain(
      `Linger server is ready at ${server.baseUrl}`,
    );
    expect((await readFile(teamhubLog, "utf8")).trim()).toBe("test1234");
  });

  it("handles GPU cancel, memory cap retry, preflight failures, and stack sanitization", async () => {
    const root = await createTempRoot();
    await mkdir(path.join(root, "home"), { recursive: true });
    const server = await startMockLingerServer(root, false);

    const bootErr = await createFakeStackScript(root, {
      bootstrapError: "stack: GPU service owners unknown",
    });
    const bootRes = await runInstallScript(["--status"], {
      env: buildTestEnv(root, bootErr.scriptPath),
    });
    expect(bootRes.code).toBe(1);
    expect(bootRes.stderr).toContain("install.sh: GPU service owners unknown");
    expect(bootRes.stderr).not.toContain("stack:");

    const sharedScenario = await createFakeStackScript(root, {
      picks: [
        {
          role: "smartest",
          id: "qwen3.8-27b",
          quant: "UD-Q4_K_M",
          quality: 54,
          decodeTokS: 109,
          decodeBasis: "estimated",
          card: 0,
          shared: true,
        },
      ],
      preflightFail: true,
      applyOutputLines: [
        "stack.sh: internal note",
        "Applied plan plan-abcdef123456",
      ],
    });

    const gpuDecline = await runInstallScript(["--web-url", server.baseUrl], {
      env: buildTestEnv(root, sharedScenario.scriptPath),
      input: "n\n",
    });
    expect(gpuDecline.code).toBe(0);
    expect(gpuDecline.stdout).toContain("Installation cancelled.");

    const preflightAbort = await runInstallScript(
      ["--web-url", server.baseUrl],
      {
        env: buildTestEnv(root, sharedScenario.scriptPath),
        input: ["y", "badcap", "16384M", "n"].join("\n") + "\n",
      },
    );
    expect(preflightAbort.code).toBe(1);
    expect(preflightAbort.stdout).toContain(
      "Please enter a size like 24G or 16384M",
    );
    expect(preflightAbort.stderr).toContain("Preflight checks failed");
    expect(preflightAbort.stdout).not.toContain("stack.sh");

    const liveSanitize = await createFakeStackScript(root, {
      applyOutputLines: [
        "stack: starting service via stack.sh",
        "Applied plan plan-abcdef123456",
      ],
    });
    const applyRes = await runInstallScript(["--web-url", server.baseUrl], {
      env: buildTestEnv(root, liveSanitize.scriptPath),
      input: ["n", "y"].join("\n") + "\n",
    });
    expect(applyRes.code).toBe(0);
    expect(applyRes.stdout).not.toContain("stack.sh");
    expect(applyRes.stdout).not.toContain("stack:");
  });

  it("handles up --share-gpu retry, --update replan, --connect, --up, and interactive purge", async () => {
    const root = await createTempRoot();
    const homeDir = path.join(root, "home");
    const piDir = path.join(
      homeDir,
      ".local/share/localmodels/tools/gateway-home/.pi/agent",
    );
    await mkdir(piDir, { recursive: true });
    await writeFile(path.join(piDir, "models.json"), "{}");

    const { scriptPath, logPath } = await createFakeStackScript(root, {
      acceptedStack: true,
      upFailsWithoutShareGpu: true,
    });
    const server = await startMockLingerServer(root, true);
    const env = buildTestEnv(root, scriptPath);

    const shareRetry = await runInstallScript(["--web-url", server.baseUrl], {
      env,
      input: ["1", "y"].join("\n") + "\n",
    });
    expect(shareRetry.code).toBe(0);
    expect(shareRetry.stdout).toContain(
      "Retry starting while sharing GPU with other running processes?",
    );

    const replan = await runInstallScript(["--web-url", server.baseUrl], {
      env,
      input: ["2", "n", "n"].join("\n") + "\n",
    });
    expect(replan.code).toBe(0);

    const connectOnly = await runInstallScript(
      ["--connect", "--web-url", server.baseUrl],
      { env },
    );
    expect(connectOnly.code).toBe(0);

    const upMode = await runInstallScript(
      ["--up", "--web-url", server.baseUrl],
      {
        env: buildTestEnv(
          root,
          (await createFakeStackScript(root, { acceptedStack: true }))
            .scriptPath,
        ),
      },
    );
    expect(upMode.code).toBe(0);

    const purgeCancel = await runInstallScript(["--remove", "--purge"], {
      env,
      input: "n\n",
    });
    expect(purgeCancel.code).toBe(0);
    expect(purgeCancel.stdout).toContain("Nothing deleted.");

    const purgeConfirm = await runInstallScript(["--remove", "--purge"], {
      env,
      input: "y\n",
    });
    expect(purgeConfirm.code).toBe(0);
    expect(purgeConfirm.stdout).toContain(
      "./scripts/install/install.sh --remove --purge",
    );

    const calls = (await readFile(logPath, "utf8")).trim().split("\n");
    expect(calls).toContain("up --share-gpu");
    expect(
      calls.some((c) => c.startsWith("plan ") && c.includes("--update")),
    ).toBe(true);
    expect(calls).toContain("remove --purge --dry-run");
    expect(calls).toContain("remove --purge --yes");
  });
});

describe("scripts/install/install.ps1 and release pin parity", () => {
  it("keeps scripts/install/install.ps1 free of CJK and aligned with CLI flags and helpers", async () => {
    const ps1 = await readFile(
      path.join(repositoryRoot, "scripts", "install", "install.ps1"),
      "utf8",
    );
    expect(ps1.startsWith("#requires -Version 5.1")).toBe(true);
    expect(/[\u3400-\u9fff\uf900-\ufaff]/.test(ps1)).toBe(false);

    for (const flag of [
      "--web-url",
      "--update",
      "--connect",
      "--up",
      "--status",
      "--remove",
      "--purge",
      "-y",
      "--yes",
      "-h",
      "--help",
    ]) {
      expect(ps1).toContain(flag);
    }

    expect(ps1).toContain("SetAccessRuleProtection($true, $false)");
    expect(ps1).toContain("[IO.Path]::PathSeparator");
    expect(ps1).toContain(
      "Set-DotEnvKey $EnvPath 'COMPOSE_FILE' \"docker-compose.yml$sep$overrideRel\"",
    );
    expect(ps1).toContain("--rtc.tcp_port");
    expect(ps1).toContain("Docker Compose 2.24.4 or later");
    expect(ps1).toContain(
      "Reminder: change the default password in Settings -> Security.",
    );
    expect(ps1).toContain("Test-IsElevated");
    expect(ps1).toContain("PI_CODING_AGENT_DIR");
    expect(ps1).toContain("SystemRoot");
    expect(ps1).toContain("PATHEXT");
    expect(ps1).toContain("pi.cmd");
    expect(ps1).toContain(
      "Invoke-Stack @('apply', $planFile, '--approve', $planId)",
    );
    expect(ps1).not.toContain("@('apply', '--plan'");
    expect(ps1).not.toContain("LINGER_STACK_SCRIPT_URL");
    expect(ps1).not.toContain("Test-IsAclBootstrapFailure");
    expect(ps1).toContain("@('auth', 'status', '--json')");
    expect(ps1).toContain("Get-StackInvokePath");
    expect(ps1).toContain("Format-SanitizedLine");
    expect(ps1).toContain("gateway-home");
    expect(ps1).toContain("localmodels");
  });

  // Linux CI has no PowerShell runtime; scripts/install/install.tests.ps1 runs
  // natively on Windows (PS 5.1 & PS 7) and via this Windows-gated case.
  it.runIf(process.platform === "win32")(
    "runs the PowerShell behavioral branch suite for scripts/install/install.ps1",
    async () => {
      const ps1 = path.join(
        repositoryRoot,
        "scripts",
        "install",
        "install.ps1",
      );
      const suite = path.join(
        repositoryRoot,
        "scripts",
        "install",
        "install.tests.ps1",
      );
      const { stdout } = await execFileAsync(
        "powershell.exe",
        [
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-File",
          suite,
          "-InstallScriptPath",
          ps1,
        ],
        { cwd: repositoryRoot, encoding: "utf8", timeout: 120_000 },
      );
      expect(stdout).toContain("ASSERTIONS PASSED");
    },
    // Longer than the suite's own 120 s limit, so vitest does not end it first.
    180_000,
  );

  it("documents the Windows guided installer command in README.md", async () => {
    const readme = await readFile(
      path.join(repositoryRoot, "README.md"),
      "utf8",
    );
    expect(readme).toContain(
      "powershell -ExecutionPolicy Bypass -File .\\scripts\\install\\install.ps1",
    );
  });

  it("keeps stack.ps1 release pins aligned with stack.sh", async () => {
    const [stackSh, stackPs1] = await Promise.all([
      readFile(
        path.join(repositoryRoot, "scripts", "installs", "stack.sh"),
        "utf8",
      ),
      readFile(
        path.join(repositoryRoot, "scripts", "installs", "stack.ps1"),
        "utf8",
      ),
    ]);
    const shVersion = stackSh.match(/^STACK_VERSION='([^']+)'/m)?.[1];
    const shCommit = stackSh.match(/^STACK_SOURCE_COMMIT='([^']+)'/m)?.[1];
    const shNpm = stackSh.match(/^STACK_NPM_VERSION='([^']+)'/m)?.[1];
    expect(shVersion).toBeTruthy();
    expect(shCommit).toBeTruthy();
    expect(shNpm).toBeTruthy();
    expect(stackPs1).toContain(`$StackVersion = '${shVersion}'`);
    expect(stackPs1).toContain(`$StackSourceCommit = '${shCommit}'`);
    expect(stackPs1).toContain(`$StackNpmVersion = '${shNpm}'`);
  });

  it("keeps standalone install script stack pins synchronized and free of floating domain URLs", async () => {
    const syncScript = path.join(
      repositoryRoot,
      "scripts",
      "sync-install-stack-pin.mjs",
    );
    const { stdout } = await execFileAsync(
      process.execPath,
      [syncScript, "--check"],
      { cwd: repositoryRoot, encoding: "utf8" },
    );
    expect(stdout).toContain("Verified install stack pins");

    const [shBody, ps1Body] = await Promise.all([
      readFile(installScriptPath, "utf8"),
      readFile(
        path.join(repositoryRoot, "scripts", "install", "install.ps1"),
        "utf8",
      ),
    ]);
    expect(shBody).not.toContain("simplexai.com/stack");
    expect(ps1Body).not.toContain("simplexai.com/stack");
  });

  it("downloads, SHA-256 verifies, and rejects tampered @simplexai/localmodels tarballs when run standalone", async () => {
    const buildSingleFileTgz = (entryName: string, content: Buffer): Buffer => {
      const header = Buffer.alloc(512);
      header.write(entryName, 0, "ascii");
      header.write("0000755\0", 100, "ascii");
      header.write("0000000\0", 108, "ascii");
      header.write("0000000\0", 116, "ascii");
      header.write(
        `${content.length.toString(8).padStart(11, "0")}\0`,
        124,
        "ascii",
      );
      header.write("00000000000\0", 136, "ascii");
      header.write("        ", 148, "ascii");
      header.write("0", 156, "ascii");
      header.write("ustar\0", 257, "ascii");
      header.write("00", 263, "ascii");
      let sum = 0;
      for (const byte of header) {
        sum += byte;
      }
      header.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148, "ascii");
      const pad = (512 - (content.length % 512)) % 512;
      const tar = Buffer.concat([
        header,
        content,
        Buffer.alloc(pad),
        Buffer.alloc(1024),
      ]);
      return gzipSync(tar);
    };

    const startMockNpm = async (expectedUrlPath: string, tgzBytes: Buffer) => {
      const srv = createServer((req, res) => {
        if (req.url === expectedUrlPath) {
          res.writeHead(200, { "content-type": "application/gzip" });
          res.end(tgzBytes);
          return;
        }
        res.writeHead(404);
        res.end("not found");
      });
      await new Promise<void>((resolve) => srv.listen(0, "127.0.0.1", resolve));
      cleanups.push(
        () =>
          new Promise<void>((resolve, reject) =>
            srv.close((err) => (err ? reject(err) : resolve())),
          ),
      );
      const addr = srv.address() as AddressInfo;
      return `http://127.0.0.1:${addr.port}`;
    };

    const root = await createTempRoot();
    await mkdir(path.join(root, "home"), { recursive: true });
    await chmod(path.join(root, "home"), 0o700);
    const standaloneDir = path.join(root, "standalone");
    await mkdir(standaloneDir, { recursive: true });
    const standaloneSh = path.join(standaloneDir, "install.sh");
    await copyFile(installScriptPath, standaloneSh);
    await chmod(standaloneSh, 0o755);

    const shRaw = await readFile(standaloneSh, "utf8");
    const npmVer = shRaw.match(/^STACK_PIN_NPM_VERSION='([^']+)'/m)?.[1];
    expect(npmVer).toBeTruthy();
    const tarUrlPath = `/@simplexai/localmodels/-/localmodels-${npmVer}.tgz`;

    // 1. Unmodified install.sh rejects a tampered package/stack.sh immediately.
    const tamperedUrl = await startMockNpm(
      tarUrlPath,
      buildSingleFileTgz(
        "package/stack.sh",
        Buffer.from("#!/bin/sh\necho bad\n"),
      ),
    );
    const envBase = buildTestEnv(root, "");
    delete envBase.LINGER_STACK_SCRIPT;
    delete envBase.LINGER_STACK_URL;
    const tamperedRes = await runInstallScript(["--status"], {
      scriptPath: standaloneSh,
      cwd: standaloneDir,
      env: { ...envBase, SIMPLEX_NPM_REGISTRY: tamperedUrl },
    });
    expect(tamperedRes.code).toBe(1);
    expect(tamperedRes.stderr).toContain(
      "Local model runtime bootstrap checksum mismatch.",
    );

    // 1b. Bounded streaming caps uncompressed package/stack.sh at 16 MiB.
    const oversizedUrl = await startMockNpm(
      tarUrlPath,
      buildSingleFileTgz(
        "package/stack.sh",
        Buffer.alloc(16 * 1024 * 1024 + 64),
      ),
    );
    const oversizedRes = await runInstallScript(["--status"], {
      scriptPath: standaloneSh,
      cwd: standaloneDir,
      env: { ...envBase, SIMPLEX_NPM_REGISTRY: oversizedUrl },
    });
    expect(oversizedRes.code).toBe(1);
    expect(oversizedRes.stderr).toContain(
      "Local model runtime bootstrap exceeds maximum size.",
    );

    // 2. Standalone install.sh extracts and runs verified package/stack.sh when SHA-256 matches.
    const fakeBody = Buffer.from(
      `#!/bin/sh
if [ "\${1:-}" = "--bootstrap-json" ]; then
  printf '{"schema":"localmodels.kit-location/v1","python":"/bin/sh"}\\n'
  exit 0
fi
if [ "\${1:-}" = "status" ]; then
  printf 'qwen3.8-27b active\\n'
  exit 0
fi
exit 0
`,
      "utf8",
    );
    const fakeSha = createHash("sha256").update(fakeBody).digest("hex");
    const pinnedSh = path.join(standaloneDir, "install-pinned.sh");
    await writeFile(
      pinnedSh,
      shRaw.replace(
        /STACK_PIN_SHA256='[a-f0-9]+'/,
        `STACK_PIN_SHA256='${fakeSha}'`,
      ),
      { mode: 0o755 },
    );
    const goodUrl = await startMockNpm(
      tarUrlPath,
      buildSingleFileTgz("package/stack.sh", fakeBody),
    );
    const goodRes = await runInstallScript(["--status"], {
      scriptPath: pinnedSh,
      cwd: standaloneDir,
      env: { ...envBase, SIMPLEX_NPM_REGISTRY: goodUrl },
    });
    expect(goodRes.code).toBe(0);
    expect(goodRes.stdout).toContain("qwen3.8-27b active");
  });
});