Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
91.1 KB
Raw Blame
// Install log (reproducible environments, phase 1): what the agent's own shell
// installed or fetched in each turn, at the exact version, so a turn's
// environment can be rebuilt with pinned installs.
//
//   wrappers   prepareInstallLog() writes the package-manager wrappers once
//              (install-log-assets.ts: a POSIX sh script linked as npm, uv,
//              cargo, apt-get, curl ...; on Windows a small exe copied as
//              npm.exe ...; plus a pip hook loaded through PYTHONPATH).
//              installLogEnv() puts their folder first on PATH in the
//              engine's environment only (the shells it starts for tool
//              calls), never the user's terminal or the system PATH. A
//              wrapper runs the real tool with the same arguments, streams
//              and exit code; for an install it notes the call in a folder
//              under the instance's raw folder (no tool is run then: copies
//              and listings only).
//   records    InstallLog reads those folders after the call, outside it:
//              it matches each to the session and shell call that ran it (by
//              time and folder), resolves the exact versions (pip's own
//              report, the hidden lockfile before and after, the package
//              folders), strips credentials from every argument and URL, and
//              hands one `context.install` line per call to the trace.
//   per turn   `context.env_turn`: OS, arch, runtime versions and version
//              managers (re-probed only when a cheap key changed) and the
//              files written outside the project during the turn (path,
//              size, sha256; never content).
//
// The server decides: GET /collect/capabilities `install_log: {enabled,
// sample_percent}`. Off (or an older server that does not say), nothing is
// noted and nothing is sent; the wrappers then only run the tool. Locally,
// OMNIRUSH_INSTALL_LOG=0 keeps the wrappers off PATH altogether.

import { createHash, randomBytes } from "node:crypto";
import { createReadStream, promises as fs } from "node:fs";
import { homedir, tmpdir } from "node:os";
import path from "node:path";

import { quietEnv, runCommand, type Runner } from "./exec.js";
import { POSIX_WRAPPER, PYTHON_HOOK, WINDOWS_WRAPPER_BASE64, WINDOWS_WRAPPER_SHA256 } from "./install-log-assets.js";
import { cleanUrl, isSecretFile, isSecretFolder, isSecretKey, tildeText, type PrivacyContext, type Scrubber } from "./privacy.js";
import { redactCredentials, redactionRaw } from "./redact-policy.js";

export const INSTALL_LOG_SCHEMA = "omnirush.install-log.v1";
export const ENV_TURN_SCHEMA = "omnirush.env-turn.v1";

/** The tools wrapped on Linux, macOS and WSL (pip itself is also seen by the hook, however it is started). */
export const POSIX_TOOLS = [
  "npm", "pnpm", "yarn", "bun", "npx", "pnpx", "bunx", "corepack",
  "pip", "pip3", "uv", "pipx", "poetry", "pipenv", "conda", "mamba", "micromamba",
  "cargo", "rustup", "go", "gem", "bundle", "bundler", "composer",
  "apt", "apt-get", "aptitude", "dnf", "yum", "microdnf", "apk", "pacman", "brew",
  "curl", "wget",
] as const;

/** The tools wrapped on Windows (PowerShell, cmd and Git Bash all find `<tool>.exe`). */
export const WINDOWS_TOOLS = [
  "npm", "pnpm", "yarn", "bun", "npx", "pnpx", "bunx", "corepack",
  "pip", "pip3", "uv", "pipx", "poetry", "pipenv", "conda", "mamba",
  "cargo", "rustup", "go", "gem", "bundle", "composer",
  "winget", "choco", "scoop", "curl", "wget",
] as const;

const MAX_ARGS = 128;
const MAX_ARG_BYTES = 2048;
const MAX_PACKAGES = 5000;
const MAX_DOWNLOAD_HASH_BYTES = 512 * 1024 * 1024;
/** A call still without its exit code after this long is reported as it is (killed, or still running in the background). */
const STALE_CALL_MS = 10 * 60_000;
/** Raw folders of instances that have ended are removed after this long. */
const STALE_INSTANCE_MS = 2 * 24 * 3600_000;
/** How much later than a shell call's end its wrapper may still be finishing its notes. */
const MATCH_SLACK_MS = 3_000;

// --- switches ------------------------------------------------------------------

/** OMNIRUSH_INSTALL_LOG=0 (or false/off/no) keeps the wrappers off the engine's PATH. On by default. */
export function installLogLocallyEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
  return !/^(?:0|false|off|no)$/i.test((env.OMNIRUSH_INSTALL_LOG ?? "").trim());
}

export type InstallLogGate = { enabled: boolean; samplePercent: number };
export const INSTALL_LOG_OFF: InstallLogGate = { enabled: false, samplePercent: 0 };

/** The server's switch from a GET /collect/capabilities answer; a missing key is off. */
export function installLogGate(capabilities: unknown): InstallLogGate {
  if (!capabilities || typeof capabilities !== "object") return INSTALL_LOG_OFF;
  const record = capabilities as Record<string, unknown>;
  const block = record.install_log;
  if (block && typeof block === "object" && !Array.isArray(block)) {
    const value = block as Record<string, unknown>;
    if (value.enabled !== true) return INSTALL_LOG_OFF;
    const percent = typeof value.sample_percent === "number" && Number.isFinite(value.sample_percent) ? Math.max(0, Math.min(100, Math.floor(value.sample_percent))) : 100;
    return { enabled: percent > 0, samplePercent: percent };
  }
  if (block === true) return { enabled: true, samplePercent: 100 };
  return INSTALL_LOG_OFF;
}

/** Whether a session is in the server's sample (a stable hash of its id). */
export function inInstallLogSample(sessionId: string, percent: number): boolean {
  if (percent >= 100) return true;
  if (percent <= 0) return false;
  return createHash("sha256").update(sessionId).digest().readUInt32BE(0) % 100 < percent;
}

// --- wrappers on disk ---------------------------------------------------------------

export type InstallLogPaths = {
  /** The wrapper folder (first on the engine's PATH). */
  bin: string;
  /** The folder holding the pip hook (first on the engine's PYTHONPATH). */
  py: string;
  /** This instance's raw folder: the wrappers note calls here; `on` in it switches noting on. */
  raw: string;
};

function digestOf(...parts: string[]): string {
  const hash = createHash("sha256");
  for (const part of parts) hash.update(part).update("\0");
  return hash.digest("hex").slice(0, 12);
}

async function isComplete(dir: string): Promise<boolean> {
  try {
    await fs.access(path.join(dir, ".complete"));
    return true;
  } catch {
    return false;
  }
}

/** Writes `dir` through a temporary folder renamed into place (several processes may race; the first one wins). */
async function materialize(dir: string, write: (tmp: string) => Promise<void>): Promise<void> {
  if (await isComplete(dir)) return;
  const tmp = `${dir}.tmp-${process.pid}-${randomBytes(4).toString("hex")}`;
  await fs.mkdir(tmp, { recursive: true });
  try {
    await write(tmp);
    await fs.writeFile(path.join(tmp, ".complete"), "");
    try {
      await fs.rename(tmp, dir);
    } catch {
      if (!(await isComplete(dir))) {
        await fs.rm(dir, { recursive: true, force: true });
        await fs.rename(tmp, dir);
      }
    }
  } finally {
    await fs.rm(tmp, { recursive: true, force: true }).catch(() => undefined);
  }
}

async function writePosixWrappers(dir: string): Promise<void> {
  const main = path.join(dir, "omnirush-pkg");
  await fs.writeFile(main, POSIX_WRAPPER, { mode: 0o755 });
  await fs.chmod(main, 0o755);
  for (const tool of POSIX_TOOLS) {
    const target = path.join(dir, tool);
    try {
      await fs.symlink("omnirush-pkg", target);
    } catch {
      await fs.copyFile(main, target);
      await fs.chmod(target, 0o755);
    }
  }
}

async function writeWindowsWrappers(dir: string): Promise<void> {
  const exe = Buffer.from(WINDOWS_WRAPPER_BASE64, "base64");
  if (createHash("sha256").update(exe).digest("hex") !== WINDOWS_WRAPPER_SHA256) throw new Error("install log: the Windows wrapper does not match its digest");
  const main = path.join(dir, "omnirush-pkg.exe");
  await fs.writeFile(main, exe);
  // The marker tells every wrapper (of any version) that this folder holds wrappers, never the real tool.
  await fs.writeFile(path.join(dir, "omnirush-pkg.marker"), "");
  for (const tool of WINDOWS_TOOLS) {
    const target = path.join(dir, `${tool}.exe`);
    try {
      await fs.link(main, target);
    } catch {
      await fs.copyFile(main, target);
    }
  }
}

/** Removes raw folders of instances that ended long ago (their process is gone). */
async function sweepRaw(rawRoot: string, keep: string): Promise<void> {
  let entries: string[] = [];
  try {
    entries = await fs.readdir(rawRoot);
  } catch {
    return;
  }
  const now = Date.now();
  for (const name of entries) {
    const full = path.join(rawRoot, name);
    if (full === keep) continue;
    try {
      const stat = await fs.stat(full);
      if (now - stat.mtimeMs > STALE_INSTANCE_MS) await fs.rm(full, { recursive: true, force: true });
    } catch {
      /* gone */
    }
  }
}

/**
 * Writes the wrappers and the pip hook under `<stateDir>/pkglog/` (once per
 * version) and makes this instance's raw folder. Null when the platform has
 * no wrappers or anything fails: the engine then starts without them.
 */
export async function prepareInstallLog(options: { stateDir: string; platform?: NodeJS.Platform }): Promise<InstallLogPaths | null> {
  const platform = options.platform ?? process.platform;
  try {
    const root = path.join(options.stateDir, "pkglog");
    const windows = platform === "win32";
    const bin = path.join(root, `bin-${digestOf(windows ? WINDOWS_WRAPPER_SHA256 : POSIX_WRAPPER, (windows ? WINDOWS_TOOLS : POSIX_TOOLS).join(","))}`);
    const py = path.join(root, `py-${digestOf(PYTHON_HOOK)}`);
    await fs.mkdir(root, { recursive: true });
    await materialize(bin, windows ? writeWindowsWrappers : writePosixWrappers);
    await materialize(py, (tmp) => fs.writeFile(path.join(tmp, "sitecustomize.py"), PYTHON_HOOK));
    const rawRoot = path.join(root, "raw");
    const raw = path.join(rawRoot, `${process.pid}-${randomBytes(4).toString("hex")}`);
    await fs.mkdir(raw, { recursive: true });
    void sweepRaw(rawRoot, raw);
    return { bin, py, raw };
  } catch {
    return null;
  }
}

/** The name an environment uses for `name` (Windows keys are case-insensitive: `Path`). */
export function envKey(env: Record<string, string | undefined>, name: string, platform: NodeJS.Platform = process.platform): string {
  if (platform !== "win32") return name;
  return Object.keys(env).find((key) => key.toUpperCase() === name.toUpperCase()) ?? name;
}

/**
 * The variables the engine's environment gets: the wrapper folder first on
 * PATH, the hook first on PYTHONPATH, and the raw folder. Keys keep the
 * spelling `base` uses (Windows `Path`), so a child never gets two PATHs.
 */
export function installLogEnv(paths: InstallLogPaths, base: Record<string, string | undefined> = process.env, platform: NodeJS.Platform = process.platform): Record<string, string> {
  const sep = platform === "win32" ? ";" : ":";
  const pathKey = envKey(base, "PATH", platform);
  const pyKey = envKey(base, "PYTHONPATH", platform);
  const current = base[pathKey] ?? "";
  const pythonPath = base[pyKey] ?? "";
  const without = (value: string, entry: string) => value.split(sep).filter((item) => item && item !== entry).join(sep);
  const restPath = without(current, paths.bin);
  const restPy = without(pythonPath, paths.py);
  return {
    [pathKey]: restPath ? `${paths.bin}${sep}${restPath}` : paths.bin,
    [pyKey]: restPy ? `${paths.py}${sep}${restPy}` : paths.py,
    OMNIRUSH_PKGLOG_DIR: paths.raw,
  };
}

/** Switches noting on or off for every wrapper of the instance (the `on` file; nothing restarts). */
export async function setInstallLogActive(raw: string, on: boolean): Promise<void> {
  const marker = path.join(raw, "on");
  try {
    if (on) await fs.writeFile(marker, "");
    else await fs.rm(marker, { force: true });
  } catch {
    /* best effort */
  }
}

// --- reading a noted call ---------------------------------------------------------

/** A Windows command-line tail split as the C runtime does (CommandLineToArgvW rules). */
export function splitWindowsArgs(tail: string): string[] {
  const out: string[] = [];
  let i = 0;
  while (i < tail.length) {
    while (tail[i] === " " || tail[i] === "\t") i++;
    if (i >= tail.length) break;
    let word = "";
    let quoted = false;
    while (i < tail.length) {
      const ch = tail[i]!;
      if (!quoted && (ch === " " || ch === "\t")) break;
      if (ch === "\\") {
        let j = i;
        while (tail[j] === "\\") j++;
        const slashes = j - i;
        if (tail[j] === '"') {
          word += "\\".repeat(Math.floor(slashes / 2));
          if (slashes % 2) {
            word += '"';
            i = j + 1;
          } else i = j;
        } else {
          word += "\\".repeat(slashes);
          i = j;
        }
        continue;
      }
      if (ch === '"') {
        if (quoted && tail[i + 1] === '"') {
          word += '"';
          i += 2;
          continue;
        }
        quoted = !quoted;
        i++;
        continue;
      }
      word += ch;
      i++;
    }
    out.push(word);
  }
  return out;
}

function parseMeta(text: string): Record<string, string> {
  const out: Record<string, string> = {};
  for (const line of text.split(/\r?\n/)) {
    const at = line.indexOf("=");
    if (at > 0) out[line.slice(0, at)] = line.slice(at + 1);
  }
  return out;
}

async function readText(file: string, max = 64 * 1024 * 1024): Promise<string | null> {
  try {
    const stat = await fs.stat(file);
    if (!stat.isFile() || stat.size > max) return null;
    return await fs.readFile(file, "utf8");
  } catch {
    return null;
  }
}

async function readJson(file: string): Promise<unknown> {
  const text = await readText(file);
  if (text === null) return null;
  try {
    return JSON.parse(text);
  } catch {
    return null;
  }
}

async function mtimeMs(file: string): Promise<number | null> {
  try {
    return (await fs.stat(file)).mtimeMs;
  } catch {
    return null;
  }
}

async function exists(file: string): Promise<boolean> {
  try {
    await fs.access(file);
    return true;
  } catch {
    return false;
  }
}

export async function sha256File(file: string, max = MAX_DOWNLOAD_HASH_BYTES): Promise<{ sha256: string; size: number } | null> {
  try {
    const stat = await fs.stat(file);
    if (!stat.isFile()) return null;
    if (stat.size > max) return { sha256: "", size: stat.size };
    const hash = createHash("sha256");
    await new Promise<void>((resolve, reject) => {
      createReadStream(file).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve()).on("error", reject);
    });
    return { sha256: hash.digest("hex"), size: stat.size };
  } catch {
    return null;
  }
}

/** One call as its wrapper (or the pip hook) noted it. */
export type RawCall = {
  dir: string;
  meta: Record<string, string>;
  /** The pip hook's notes inside the call (pip run by the wrapped tool, or the call itself). */
  hooks: Array<{ meta: Record<string, string>; argv: string[]; report: unknown; removed: string[] }>;
  argv: string[];
  exit: number | null;
  start: number;
  end: number | null;
  complete: boolean;
};

async function readArgv(dir: string, name: string): Promise<string[] | null> {
  try {
    const buffer = await fs.readFile(path.join(dir, name));
    const text = buffer.toString("utf8");
    return text.split("\0").filter((_, index, all) => index < all.length - 1 || all[index] !== "");
  } catch {
    return null;
  }
}

async function readRc(file: string): Promise<{ exit: number | null; at: number | null } | null> {
  const text = await readText(file, 4096);
  if (text === null) return null;
  const [code, at] = text.split(/\r?\n/);
  const exit = code !== undefined && /^-?\d+$/.test(code.trim()) ? Number(code.trim()) : null;
  const when = at !== undefined && /^\d+$/.test(at.trim()) ? Number(at.trim()) : await mtimeMs(file);
  // A Windows exit code is unsigned (0xC000013A after Ctrl+C): keep it as the signed 32-bit value tools print.
  return { exit: exit !== null && exit > 0x7fffffff ? exit - 0x100000000 : exit, at: when };
}

/** Reads one noted call folder (null when it is not one, or not readable yet). */
export async function readRawCall(dir: string, now = Date.now()): Promise<RawCall | null> {
  let names: string[];
  try {
    names = await fs.readdir(dir);
  } catch {
    return null;
  }
  const hooks: RawCall["hooks"] = [];
  for (const name of names.filter((item) => item === "hook" || item.startsWith("hook."))) {
    const tag = name === "hook" ? "" : name.slice(4);
    const metaText = await readText(path.join(dir, name), 64 * 1024);
    if (metaText === null) continue;
    const meta = parseMeta(metaText);
    const report = meta.report ? await readJson(path.join(dir, meta.report)) : null;
    const removedText = await readText(path.join(dir, `removed${tag}`), 1024 * 1024);
    const rc = await readRc(path.join(dir, `rc${tag}`));
    if (rc) meta.exit = rc.exit === null ? "" : String(rc.exit);
    if (rc?.at) meta.t1 = String(rc.at);
    hooks.push({ meta, argv: (await readArgv(dir, `argv${tag}`)) ?? [], report, removed: removedText ? removedText.split(/\r?\n/).filter(Boolean) : [] });
  }
  const metaText = await readText(path.join(dir, "meta"), 64 * 1024);
  let meta: Record<string, string>;
  let argv: string[];
  let rc: { exit: number | null; at: number | null } | null;
  let start: number | null;
  if (metaText !== null) {
    meta = parseMeta(metaText);
    const win = await readText(path.join(dir, "argv.win"), 1024 * 1024);
    argv = win !== null ? splitWindowsArgs(win) : (await readArgv(dir, "argv")) ?? [];
    rc = await readRc(path.join(dir, "rc"));
    start = meta.t0 && /^\d+$/.test(meta.t0) ? Number(meta.t0) : await mtimeMs(path.join(dir, "meta"));
  } else if (hooks.length > 0 && !hooks[0]!.meta.via?.startsWith("shim")) {
    // A pip the hook noted on its own (python -m pip, a venv's pip after `activate`).
    const hook = hooks[0]!;
    meta = { ...hook.meta, kind: "pip" };
    argv = hook.argv;
    rc = hook.meta.exit !== undefined ? { exit: hook.meta.exit === "" ? null : Number(hook.meta.exit), at: hook.meta.t1 ? Number(hook.meta.t1) : null } : null;
    start = hook.meta.t0 && /^\d+$/.test(hook.meta.t0) ? Number(hook.meta.t0) : await mtimeMs(path.join(dir, "hook"));
  } else {
    return null;
  }
  if (start === null) return null;
  const complete = rc !== null;
  if (!complete && now - start < STALE_CALL_MS) return { dir, meta, hooks, argv, exit: null, start, end: null, complete: false };
  return { dir, meta, hooks, argv, exit: rc?.exit ?? null, start, end: rc?.at ?? null, complete };
}

// --- what a call did ------------------------------------------------------------------

export type Ecosystem =
  | "pypi" | "npm" | "cargo" | "go" | "gem" | "composer" | "apt" | "rpm" | "apk" | "pacman" | "brew"
  | "winget" | "choco" | "scoop" | "conda" | "rustup" | "corepack" | "browsers" | "url" | "runtime" | "psgallery";
export type Scope = "project" | "global" | "user" | "target" | "system";

export type Package = { name: string; version: string; source?: string; sha256?: string; integrity?: string; path?: string };
export type Download = { url: string; path: string; path_rel?: string | null; sha256?: string; size?: number };

/** One `context.install` line (the ledger's v1 line, see the converter's ledger.py). */
export type InstallLine = {
  v: 1;
  schema: typeof INSTALL_LOG_SCHEMA;
  ts: string;
  end: string | null;
  dur_ms: number | null;
  turn: number | null;
  call: string | null;
  tool: string;
  via: "shim" | "python-hook" | "command";
  real: string | null;
  argv: string[];
  cwd: string;
  cwd_rel: string | null;
  exit: number | null;
  os: "linux" | "darwin" | "windows";
  scope: Scope;
  ecosystem: Ecosystem;
  target: string | null;
  target_rel: string | null;
  python: string | null;
  requested: string[];
  resolved: Package[];
  removed: Array<{ name: string; version?: string }>;
  downloads: Download[];
  lockfile: string | null;
  lockfile_rel: string | null;
  lockfile_sha256: string | null;
  truncated?: boolean;
};

/** Flags whose value is the next word, per tool family (so values never count as package names). */
const VALUE_FLAGS: Record<string, Set<string>> = {
  npm: new Set(["--prefix", "-C", "--cwd", "--dir", "--registry", "--cache", "--userconfig", "--tag", "-w", "--workspace", "--filter", "-F", "--save-prefix", "--omit", "--include", "--install-strategy", "--loglevel", "--network-concurrency", "--modules-folder", "--global-folder", "--cwd", "--config"]),
  pip: new Set(["-r", "--requirement", "-c", "--constraint", "-i", "--index-url", "--extra-index-url", "-f", "--find-links", "-t", "--target", "--prefix", "--root", "--platform", "--python-version", "--implementation", "--abi", "--src", "--upgrade-strategy", "--report", "--log", "--cache-dir", "--trusted-host", "--progress-bar", "--python", "-p", "--group", "--extra", "--index", "--default-index", "--project", "--directory", "--with", "--from", "--source", "--suffix", "--pip-args", "--spec", "--include-deps"]),
  cargo: new Set(["--version", "--vers", "--git", "--branch", "--tag", "--rev", "--path", "--root", "--features", "-F", "--bin", "--example", "--registry", "--index", "--target", "--profile", "-j", "--jobs", "--manifest-path", "--package", "-p", "--rename"]),
  go: new Set(["-tags", "-ldflags", "-gcflags", "-mod", "-modfile", "-o", "-C", "-pgo", "-overlay", "-p"]),
  gem: new Set(["-v", "--version", "-s", "--source", "-i", "--install-dir", "-n", "--bindir", "--platform", "-g", "--file", "--gemfile", "--path", "--group", "--without", "--with", "-j", "--jobs"]),
  composer: new Set(["--working-dir", "-d"]),
  apt: new Set(["-o", "--option", "-t", "--target-release", "-c", "--config-file"]),
  brew: new Set(["--formula-version"]),
  winget: new Set(["--id", "-q", "--query", "--name", "--moniker", "-v", "--version", "-s", "--source", "--scope", "-a", "--architecture", "-l", "--location", "--locale", "--log", "-o", "--override", "--custom", "--header", "--authentication-mode", "--installer-type"]),
  choco: new Set(["--version", "-s", "--source", "--params", "--package-parameters", "--install-arguments", "--ia", "-u", "--user", "-p", "--password"]),
  conda: new Set(["-n", "--name", "-p", "--prefix", "-c", "--channel", "--file"]),
  rustup: new Set(["--profile", "--target", "-t", "--component", "-c", "--toolchain"]),
  url: new Set(["-o", "--output", "-O", "--output-document", "-H", "--header", "-d", "--data", "--data-raw", "--data-binary", "-u", "--user", "-x", "--proxy", "-A", "--user-agent", "-e", "--referer", "-b", "--cookie", "-c", "--cookie-jar", "-X", "--request", "-T", "--upload-file", "-F", "--form", "-m", "--max-time", "--connect-timeout", "-w", "--write-out", "-P", "--directory-prefix", "--retry", "--resolve", "--cacert", "--cert", "--key", "-K", "--config"]),
};

function familyOf(tool: string): string {
  if (["npm", "pnpm", "yarn", "bun", "npx", "pnpx", "bunx", "corepack"].includes(tool)) return "npm";
  if (/^pip/.test(tool) || ["uv", "pipx", "poetry", "pipenv", "python", "python3", "py"].includes(tool)) return "pip";
  if (["conda", "mamba", "micromamba"].includes(tool)) return "conda";
  if (["apt", "apt-get", "aptitude", "dnf", "yum", "microdnf", "apk", "pacman"].includes(tool)) return "apt";
  if (["gem", "bundle", "bundler"].includes(tool)) return "gem";
  if (["curl", "wget"].includes(tool)) return "url";
  return tool;
}

/** Positional words (flags and their values left out). */
export function positionals(tool: string, argv: string[]): string[] {
  const flags = VALUE_FLAGS[familyOf(tool)] ?? new Set<string>();
  const out: string[] = [];
  for (let i = 0; i < argv.length; i++) {
    const word = argv[i]!;
    if (word === "--") {
      out.push(...argv.slice(i + 1));
      break;
    }
    if (word.startsWith("-")) {
      if (!word.includes("=") && flags.has(word)) i++;
      continue;
    }
    if (/^\d*[<>]|^&>|^[<>|&;]$/.test(word)) continue; // a shell redirect that reached the tool's words (never a package)
    out.push(word);
  }
  return out;
}

function hasFlag(argv: string[], ...names: string[]): boolean {
  return argv.some((word) => names.includes(word) || names.some((name) => name.startsWith("--") && word.startsWith(`${name}=`)));
}

function flagValue(argv: string[], ...names: string[]): string | null {
  for (let i = 0; i < argv.length; i++) {
    const word = argv[i]!;
    for (const name of names) {
      if (word === name && i + 1 < argv.length) return argv[i + 1]!;
      if (name.startsWith("--") && word.startsWith(`${name}=`)) return word.slice(name.length + 1);
    }
  }
  return null;
}

export type Classified = { ecosystem: Ecosystem; scope: Scope; sub: string; requested: string[] };

/** What kind of install a call is (null: not an install). The wrappers' own check is a looser superset of this one. */
export function classifyCall(tool: string, argv: string[]): Classified | null {
  tool = tool.toLowerCase().replace(/\.exe$/, "");
  const words = positionals(tool, argv);
  const [s1 = "", s2 = ""] = words;
  const after = (n: number) => words.slice(n);
  const npmLike = (pm: string, list: string[], offset: number): Classified | null => {
    const sub = list[offset] ?? "";
    const verbs: Record<string, string[]> = {
      npm: ["install", "i", "in", "ins", "inst", "insta", "instal", "isnt", "isnta", "isntal", "isntall", "add", "ci", "clean-install", "install-clean", "ic", "uninstall", "un", "unlink", "remove", "rm", "r", "update", "up", "upgrade", "udpate", "link", "ln"],
      pnpm: ["add", "install", "i", "remove", "rm", "un", "uninstall", "update", "up", "upgrade"],
      yarn: ["", "install", "add", "remove", "upgrade", "up", "global"],
      bun: ["add", "a", "install", "i", "remove", "rm", "update", "link"],
    };
    if (!(verbs[pm] ?? []).includes(sub)) return null;
    const global = hasFlag(argv, "-g", "--global", "--location=global") || (pm === "yarn" && sub === "global");
    const requested = list.slice(offset + (pm === "yarn" && sub === "global" ? 2 : 1));
    return { ecosystem: "npm", scope: global ? "global" : "project", sub, requested };
  };
  switch (tool) {
    case "npm":
    case "pnpm":
    case "yarn":
    case "bun":
      return npmLike(tool, words, 0);
    case "corepack":
      if (["npm", "pnpm", "yarn"].includes(s1)) return npmLike(s1, words, 1);
      if (["enable", "prepare", "install", "use", "up"].includes(s1)) return { ecosystem: "corepack", scope: "global", sub: s1, requested: after(1) };
      return null;
    case "npx":
    case "pnpx":
    case "bunx": {
      const at = words.findIndex((word) => /^(?:@playwright\/test|playwright(?:-core)?)(?:@.*)?$/.test(word));
      if (at >= 0 && words[at + 1] === "install") return { ecosystem: "browsers", scope: "global", sub: "install", requested: words.slice(at + 2).length ? words.slice(at + 2) : ["(default browsers)"] };
      return null;
    }
    case "pip":
    case "python":
    case "python3":
    case "py":
      if (s1 === "install" || s1 === "uninstall") {
        const scope: Scope = hasFlag(argv, "--user") ? "user" : hasFlag(argv, "--target", "-t", "--prefix", "--root") ? "target" : "project";
        const requested = after(1);
        const reqFiles = [flagValue(argv, "-r", "--requirement")].filter((item): item is string => Boolean(item)).map((file) => `-r ${file}`);
        return { ecosystem: "pypi", scope, sub: s1, requested: [...requested, ...reqFiles] };
      }
      return null;
    case "uv":
      if (s1 === "pip" && ["install", "uninstall", "sync"].includes(s2)) return { ecosystem: "pypi", scope: hasFlag(argv, "--system") ? "global" : "project", sub: `pip ${s2}`, requested: after(2) };
      if (["add", "remove", "sync", "lock"].includes(s1)) return { ecosystem: "pypi", scope: "project", sub: s1, requested: after(1) };
      if (s1 === "tool" && ["install", "uninstall", "upgrade"].includes(s2)) return { ecosystem: "pypi", scope: "global", sub: `tool ${s2}`, requested: after(2) };
      if (s1 === "python" && s2 === "install") return { ecosystem: "runtime", scope: "global", sub: "python install", requested: after(2).map((v) => `python@${v}`) };
      return null;
    case "pipx":
      if (["install", "uninstall", "inject", "upgrade", "reinstall"].includes(s1)) return { ecosystem: "pypi", scope: "global", sub: s1, requested: after(1) };
      return null;
    case "poetry":
      if (["add", "install", "remove", "update", "sync", "lock"].includes(s1)) return { ecosystem: "pypi", scope: "project", sub: s1, requested: after(1) };
      return null;
    case "pipenv":
      if (["install", "uninstall", "sync", "update", "lock"].includes(s1)) return { ecosystem: "pypi", scope: "project", sub: s1, requested: after(1) };
      return null;
    case "conda":
    case "mamba":
    case "micromamba":
      if (["install", "create", "remove", "uninstall", "update", "upgrade"].includes(s1)) return { ecosystem: "conda", scope: "global", sub: s1, requested: after(1) };
      return null;
    case "cargo":
      if (["install", "uninstall", "binstall"].includes(s1)) {
        const version = flagValue(argv, "--version", "--vers");
        const names = after(1).map((name) => (version && !name.includes("@") ? `${name}@${version}` : name));
        return { ecosystem: "cargo", scope: "global", sub: s1, requested: names };
      }
      if (["add", "remove", "fetch", "update"].includes(s1)) return { ecosystem: "cargo", scope: "project", sub: s1, requested: after(1) };
      return null;
    case "rustup":
      if (["install", "default", "toolchain", "target", "component", "update"].includes(s1)) return { ecosystem: "rustup", scope: "global", sub: s1, requested: s1 === "toolchain" || s1 === "target" || s1 === "component" ? after(2) : after(1) };
      return null;
    case "go":
      if (s1 === "install") return { ecosystem: "go", scope: "global", sub: s1, requested: after(1) };
      if (s1 === "get") return { ecosystem: "go", scope: "project", sub: s1, requested: after(1) };
      if (s1 === "mod" && ["download", "tidy", "vendor"].includes(s2)) return { ecosystem: "go", scope: "project", sub: `mod ${s2}`, requested: after(2) };
      return null;
    case "gem":
      if (["install", "i", "uninstall", "update"].includes(s1)) {
        const version = flagValue(argv, "-v", "--version");
        return { ecosystem: "gem", scope: hasFlag(argv, "--user-install") ? "user" : "global", sub: s1, requested: after(1).map((name) => (version ? `${name}@${version}` : name)) };
      }
      return null;
    case "bundle":
    case "bundler":
      if (["", "install", "add", "update"].includes(s1)) return { ecosystem: "gem", scope: "project", sub: s1 || "install", requested: after(1) };
      return null;
    case "composer":
      if (s1 === "global" && ["require", "install", "update", "remove"].includes(s2)) return { ecosystem: "composer", scope: "global", sub: s2, requested: after(2) };
      if (["require", "install", "update", "remove"].includes(s1)) return { ecosystem: "composer", scope: "project", sub: s1, requested: after(1) };
      return null;
    case "apt":
    case "apt-get":
    case "aptitude":
      if (["install", "remove", "purge", "reinstall", "upgrade", "dist-upgrade", "full-upgrade", "autoremove"].includes(s1)) return { ecosystem: "apt", scope: "system", sub: s1, requested: after(1) };
      return null;
    case "dnf":
    case "yum":
    case "microdnf":
      if (["install", "remove", "erase", "upgrade", "update", "reinstall", "downgrade"].includes(s1)) return { ecosystem: "rpm", scope: "system", sub: s1, requested: after(1) };
      return null;
    case "apk":
      if (s1 === "add" || s1 === "del") return { ecosystem: "apk", scope: "system", sub: s1, requested: after(1) };
      return null;
    case "pacman": {
      const op = argv.find((word) => /^-[SRU]/.test(word));
      return op ? { ecosystem: "pacman", scope: "system", sub: op, requested: words } : null;
    }
    case "brew":
      if (["install", "uninstall", "reinstall", "upgrade", "remove", "rm", "tap"].includes(s1)) return { ecosystem: "brew", scope: "system", sub: s1, requested: after(1).map((name) => (hasFlag(argv, "--cask") ? `cask:${name}` : name)) };
      return null;
    case "winget": {
      if (!["install", "add", "uninstall", "remove", "rm", "upgrade", "update", "import"].includes(s1)) return null;
      const id = flagValue(argv, "--id", "-q", "--query", "--name", "--moniker");
      const version = flagValue(argv, "-v", "--version");
      const names = [...new Set([...(id ? [id] : []), ...after(1)])].filter((name) => !/^--?/.test(name));
      return { ecosystem: "winget", scope: "system", sub: s1, requested: names.map((name) => (version ? `${name}@${version}` : name)) };
    }
    case "choco":
      if (["install", "uninstall", "upgrade", "update"].includes(s1)) {
        const version = flagValue(argv, "--version");
        return { ecosystem: "choco", scope: "system", sub: s1, requested: after(1).map((name) => (version ? `${name}@${version}` : name)) };
      }
      return null;
    case "scoop":
      if (["install", "uninstall", "update"].includes(s1)) return { ecosystem: "scoop", scope: "user", sub: s1, requested: after(1) };
      return null;
    case "curl":
    case "wget":
      return argv.some((word) => /^(?:https?|ftp):\/\//i.test(word)) ? { ecosystem: "url", scope: "project", sub: "", requested: [] } : null;
    default:
      return null;
  }
}

// --- privacy ------------------------------------------------------------------------

const SECRET_FLAG = /^--?(?:token|password|passwd|pass|pwd|secret|api[-_]?key|auth|auth[-_]?token|access[-_]?token|otp|client[-_]?secret|private[-_]?key|key)$/i;
const SECRET_HEADER = /^\s*(?:authorization|proxy-authorization|cookie|set-cookie|x-[a-z0-9-]*(?:token|key|secret|auth)[a-z0-9-]*|private-token|job-token)\s*:/i;

/** One argument without credentials: URL userinfo and secret query values, `key=secret`, header values. */
function cleanArg(word: string): string {
  let out = word;
  // A whole-word URL: userinfo and secret query values (the rest of the query stays).
  if (/^[a-z][a-z0-9+.-]*:\/\/\S*$/i.test(out)) return cleanUrl(out);
  // URLs inside a word (--index-url=https://u:p@host/simple): the same, in place.
  if (/[a-z][a-z0-9+.-]*:\/\//i.test(out)) out = out.replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@"']+@/gi, "$1").replace(/((?:https?|ftp):\/\/\S+)/gi, (url) => cleanUrl(url));
  const flag = /^(--header=|-H)(?=\S)/.exec(out)?.[0] ?? "";
  const header = SECRET_HEADER.exec(out.slice(flag.length));
  if (header) return `${out.slice(0, flag.length + header[0].length)} [REDACTED]`;
  // name=value (npm config set //registry/:_authToken=..., NPM_TOKEN=..., --password=...)
  const assign = /^(-{0,2})([^=\s]+)=(.+)$/.exec(out);
  if (assign && /:\/\//.test(assign[3]!)) return out; // --index-url=<url>: cleaned above
  if (assign && (isSecretKey(assign[2]!.split(/[:/]/).at(-1) ?? "") || SECRET_FLAG.test(`--${assign[2]}`) || /_auth(?:token)?$/i.test(assign[2]!))) return `${assign[1]}${assign[2]}=[REDACTED]`;
  return out;
}

/** The call's arguments without credentials (a secret flag's value is replaced; capped). */
export function sanitizeArgs(argv: string[]): { args: string[]; truncated: boolean } {
  // client-raw: the arguments as run (the cap stays).
  if (redactionRaw()) return { args: argv.slice(0, MAX_ARGS), truncated: argv.length > MAX_ARGS };
  const out: string[] = [];
  let truncated = argv.length > MAX_ARGS;
  for (let i = 0; i < Math.min(argv.length, MAX_ARGS); i++) {
    const word = argv[i]!;
    const prev = i > 0 ? argv[i - 1]! : "";
    let clean: string;
    if (SECRET_FLAG.test(prev) || /^-(?:u|-user|-proxy-user|U)$/.test(prev) && word.includes(":")) {
      clean = SECRET_FLAG.test(prev) ? "[REDACTED]" : `${word.split(":")[0]}:[REDACTED]`;
    } else if (/^-(?:H|-header)$/.test(prev) && SECRET_HEADER.test(word)) {
      clean = cleanArg(word);
    } else if (/^npm_config_|^NPM_TOKEN$|^NODE_AUTH_TOKEN$/i.test(prev)) {
      clean = "[REDACTED]";
    } else {
      clean = cleanArg(word);
    }
    // The client redaction policy over each argument (credential shapes the rules above do not name).
    clean = redactCredentials(clean, { mode: "config" }).text;
    if (Buffer.byteLength(clean) > MAX_ARG_BYTES) {
      clean = Buffer.from(clean).subarray(0, MAX_ARG_BYTES).toString("utf8");
      truncated = true;
    }
    out.push(clean);
  }
  return { args: out, truncated };
}

// --- resolving versions -----------------------------------------------------------

function normPy(name: string): string {
  return name.toLowerCase().replace(/[-_.]+/g, "-");
}

/** `requests-2.32.3.dist-info` → requests / 2.32.3. */
export function parseDistInfo(name: string): { name: string; version: string } | null {
  const match = /^(.+)-([^-]+)\.dist-info$/.exec(name.trim());
  return match ? { name: normPy(match[1]!), version: match[2]! } : null;
}

function distDiff(before: string | null, after: string | null): { resolved: Package[]; removed: Array<{ name: string; version?: string }> } {
  const parse = (text: string | null) => new Map((text ?? "").split(/\r?\n/).map(parseDistInfo).filter((item): item is { name: string; version: string } => item !== null).map((item) => [item.name, item.version]));
  const b = parse(before);
  const a = parse(after);
  const resolved: Package[] = [];
  for (const [name, version] of a) if (b.get(name) !== version) resolved.push({ name, version });
  const removed = [...b].filter(([name]) => !a.has(name)).map(([name, version]) => ({ name, version }));
  return { resolved, removed };
}

/** pip's installation report → packages (exact version, URL, sha256). */
export function pipReport(report: unknown): Package[] {
  if (!report || typeof report !== "object") return [];
  const install = (report as { install?: unknown }).install;
  if (!Array.isArray(install)) return [];
  const out: Package[] = [];
  for (const item of install) {
    if (!item || typeof item !== "object") continue;
    const metadata = (item as { metadata?: { name?: unknown; version?: unknown } }).metadata ?? {};
    const info = (item as { download_info?: { url?: unknown; archive_info?: { hashes?: Record<string, unknown>; hash?: unknown } } }).download_info ?? {};
    if (typeof metadata.name !== "string" || typeof metadata.version !== "string") continue;
    const pkg: Package = { name: normPy(metadata.name), version: metadata.version };
    if (typeof info.url === "string" && !info.url.startsWith("file:")) pkg.source = info.url;
    const sha = info.archive_info?.hashes?.sha256 ?? (typeof info.archive_info?.hash === "string" && info.archive_info.hash.startsWith("sha256=") ? info.archive_info.hash.slice(7) : undefined);
    if (typeof sha === "string" && /^[0-9a-f]{64}$/.test(sha)) pkg.sha256 = sha;
    out.push(pkg);
  }
  return out;
}

type NpmEntry = { name: string; version: string; resolved?: string; integrity?: string };

function npmTree(text: string | null): Map<string, NpmEntry> {
  const out = new Map<string, NpmEntry>();
  if (!text) return out;
  try {
    const lock = JSON.parse(text) as { packages?: Record<string, { name?: string; version?: string; resolved?: string; integrity?: string; link?: boolean }> };
    for (const [key, value] of Object.entries(lock.packages ?? {})) {
      if (!key || !value || value.link) continue;
      const name = value.name ?? key.replace(/^.*node_modules\//, "");
      out.set(key, { name, version: value.version ?? "", ...(value.resolved ? { resolved: value.resolved } : {}), ...(value.integrity ? { integrity: value.integrity } : {}) });
    }
  } catch {
    /* not JSON */
  }
  return out;
}

/** The hidden lockfile before and after an npm install → what it added or changed, and what it removed. */
export function npmDiff(before: string | null, after: string | null): { resolved: Package[]; removed: Array<{ name: string; version?: string }> } {
  const b = npmTree(before);
  const a = npmTree(after);
  const resolved: Package[] = [];
  for (const [key, entry] of a) {
    const old = b.get(key);
    if (old && old.version === entry.version) continue;
    resolved.push({ name: entry.name, version: entry.version, ...(entry.resolved ? { source: entry.resolved } : {}), ...(entry.integrity ? { integrity: entry.integrity } : {}), path: key });
  }
  const removed = [...b].filter(([key]) => !a.has(key)).map(([, entry]) => ({ name: entry.name, version: entry.version }));
  return { resolved, removed };
}

/** `lodash@^4` → lodash; `@types/node@20` → @types/node; `pkg==1.2` → pkg. */
export function packageName(spec: string): string {
  let s = spec.trim();
  if (s.startsWith("cask:")) s = s.slice(5);
  if (/^(?:git\+|https?:|file:|\.{0,2}\/|[A-Za-z]:\\|-r )/.test(s)) return "";
  if (s.startsWith("@")) {
    const at = s.indexOf("@", 1);
    return at > 0 ? s.slice(0, at) : s;
  }
  return s.split(/[@=<>!~;\[ ]/)[0] ?? "";
}

async function readPackageVersion(dir: string): Promise<{ version: string } | null> {
  const json = (await readJson(path.join(dir, "package.json"))) as { version?: unknown } | null;
  return json && typeof json.version === "string" ? { version: json.version } : null;
}

const LOCKFILES: Record<string, string[]> = {
  npm: ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"],
  pypi: ["uv.lock", "poetry.lock", "Pipfile.lock", "pdm.lock"],
  cargo: ["Cargo.lock"],
  go: ["go.sum"],
  gem: ["Gemfile.lock"],
  composer: ["composer.lock"],
};

async function findUp(start: string, names: string[], stop: string | null): Promise<string | null> {
  let dir = path.resolve(start);
  for (let i = 0; i < 40; i++) {
    for (const name of names) if (await exists(path.join(dir, name))) return path.join(dir, name);
    if (stop && path.resolve(dir) === path.resolve(stop)) return null;
    const up = path.dirname(dir);
    if (up === dir) return null;
    dir = up;
  }
  return null;
}

export type ResolveContext = {
  platform: NodeJS.Platform;
  home: string | null;
  env: NodeJS.ProcessEnv;
  run: Runner;
  root: string;
};

async function globalNpmRoots(tool: string, real: string | null, ctx: ResolveContext): Promise<string[]> {
  const roots: string[] = [];
  const prefix = ctx.env.npm_config_prefix ?? ctx.env.NPM_CONFIG_PREFIX;
  if (prefix) roots.push(ctx.platform === "win32" ? path.join(prefix, "node_modules") : path.join(prefix, "lib", "node_modules"));
  if (real) {
    const bin = path.dirname(real);
    roots.push(ctx.platform === "win32" ? path.join(bin, "node_modules") : path.join(path.dirname(bin), "lib", "node_modules"));
    try {
      const resolved = await fs.realpath(real);
      if (ctx.platform !== "win32") {
        const at = resolved.indexOf(`${path.sep}lib${path.sep}node_modules${path.sep}`);
        if (at > 0) roots.push(resolved.slice(0, at + `${path.sep}lib${path.sep}node_modules`.length));
      }
    } catch {
      /* not a link */
    }
  }
  if (ctx.home) {
    if (ctx.platform === "win32") roots.push(path.join(ctx.env.APPDATA ?? path.join(ctx.home, "AppData", "Roaming"), "npm", "node_modules"));
    roots.push(path.join(ctx.home, ".npm-global", "lib", "node_modules"), path.join(ctx.home, ".bun", "install", "global", "node_modules"), path.join(ctx.home, ".config", "yarn", "global", "node_modules"));
    if (tool === "pnpm") roots.push(path.join(ctx.home, ".local", "share", "pnpm", "global", "5", "node_modules"));
  }
  return [...new Set(roots)];
}

function pythonSitePackages(prefix: string, platform: NodeJS.Platform): Promise<string[]> {
  return (async () => {
    if (platform === "win32") return [path.join(prefix, "Lib", "site-packages")];
    try {
      const libs = await fs.readdir(path.join(prefix, "lib"));
      return libs.filter((name) => /^python\d/.test(name)).map((name) => path.join(prefix, "lib", name, "site-packages"));
    } catch {
      return [];
    }
  })();
}

async function distVersion(sitePackages: string[], name: string): Promise<string | null> {
  const wanted = normPy(name);
  for (const dir of sitePackages) {
    let entries: string[] = [];
    try {
      entries = await fs.readdir(dir);
    } catch {
      continue;
    }
    for (const entry of entries) {
      const info = parseDistInfo(entry);
      if (info && info.name === wanted) return info.version;
    }
  }
  return null;
}

/** Exact versions of what a call installed (best effort; never throws). */
async function resolveCall(call: RawCall, cls: Classified, tool: string, ctx: ResolveContext): Promise<{
  resolved: Package[]; removed: Array<{ name: string; version?: string }>; downloads: Download[]; target: string | null; python: string | null; lockfile: string | null;
}> {
  const read = (name: string) => readText(path.join(call.dir, name));
  let resolved: Package[] = [];
  let removed: Array<{ name: string; version?: string }> = [];
  const downloads: Download[] = [];
  let target: string | null = null;
  let python: string | null = null;
  let lockfile: string | null = null;
  const names = cls.requested.map(packageName).filter(Boolean);
  const cwd = call.meta.cwd || ctx.root;
  const real = call.meta.real || null;
  try {
    switch (cls.ecosystem) {
      case "pypi": {
        const reports = call.hooks.flatMap((hook) => pipReport(hook.report));
        if (reports.length) resolved = reports;
        for (const hook of call.hooks) {
          for (const line of hook.removed) {
            const [name, version] = line.split("\t");
            if (name) removed.push({ name: normPy(name), ...(version ? { version } : {}) });
          }
        }
        const hook = call.hooks[0];
        if (hook) {
          target = hook.meta.prefix || null;
          python = hook.meta.version || null;
        }
        const venv = call.meta.venv_dir || null;
        if (venv) target ??= venv;
        if (!reports.length) {
          const diff = distDiff(await read("b.dist"), await read("a.dist"));
          if (diff.resolved.length || diff.removed.length) {
            resolved = diff.resolved;
            removed = diff.removed.length ? diff.removed : removed;
          }
        }
        // pipx / uv tool: the tool's own environment.
        if (!resolved.length && cls.scope === "global" && ctx.home && (tool === "pipx" || tool === "uv")) {
          for (const name of names) {
            const base = tool === "pipx"
              ? [path.join(ctx.env.PIPX_HOME ?? path.join(ctx.home, ".local", "share", "pipx"), "venvs", normPy(name)), path.join(ctx.home, "pipx", "venvs", normPy(name))]
              : [path.join(ctx.env.UV_TOOL_DIR ?? (ctx.platform === "win32" ? path.join(ctx.env.APPDATA ?? ctx.home, "uv", "tools") : path.join(ctx.home, ".local", "share", "uv", "tools")), normPy(name))];
            for (const env of base) {
              const version = await distVersion(await pythonSitePackages(env, ctx.platform), name);
              if (version) {
                resolved.push({ name: normPy(name), version });
                target ??= env;
                break;
              }
            }
          }
        }
        if (cls.scope === "project") {
          const lock = await findUp(cwd, LOCKFILES.pypi!, ctx.root);
          if (lock && (tool === "uv" || tool === "poetry" || tool === "pipenv")) lockfile = lock;
        }
        break;
      }
      case "npm": {
        if (cls.scope === "global") {
          target = "global";
          const roots = await globalNpmRoots(tool, real, ctx);
          for (const name of names) {
            for (const root of roots) {
              const found = await readPackageVersion(path.join(root, name));
              if (found) {
                resolved.push({ name, version: found.version, path: `node_modules/${name}` });
                break;
              }
            }
          }
          break;
        }
        const root = call.meta.root || (await findUp(call.meta.prefix_arg || cwd, ["package.json"], null).then((file) => (file ? path.dirname(file) : null)));
        target = root ?? cwd;
        const after = await read("a.npm");
        if (after !== null) ({ resolved, removed } = npmDiff(await read("b.npm"), after));
        if (!resolved.length && root) {
          for (const name of names) {
            const found = await readPackageVersion(path.join(root, "node_modules", name));
            if (found) resolved.push({ name, version: found.version, path: `node_modules/${name}` });
          }
        }
        if (root) {
          for (const name of LOCKFILES.npm!) {
            if (await exists(path.join(root, name))) {
              lockfile = path.join(root, name);
              break;
            }
          }
        }
        break;
      }
      case "cargo": {
        if (cls.scope === "global" && ctx.home) {
          const crates = (await readJson(path.join(ctx.env.CARGO_HOME ?? path.join(ctx.home, ".cargo"), ".crates2.json"))) as { installs?: Record<string, unknown> } | null;
          const keys = Object.keys(crates?.installs ?? {});
          for (const name of names) {
            const key = keys.find((item) => item.split(" ")[0] === name);
            if (!key) continue;
            const [, version, source] = /^\S+ (\S+) \((.*)\)$/.exec(key) ?? [];
            if (version) resolved.push({ name, version, ...(source ? { source } : {}) });
          }
        } else lockfile = await findUp(cwd, LOCKFILES.cargo!, ctx.root);
        break;
      }
      case "go": {
        if (cls.scope === "global") {
          const envOut = await ctx.run(real ?? "go", ["env", "GOBIN", "GOPATH"], { timeoutMs: 5_000, env: quietEnv({ ...ctx.env, OMNIRUSH_PKGLOG_OFF: "1" }) });
          const [gobin = "", gopath = ""] = (envOut?.stdout ?? "").split(/\r?\n/);
          const bin = gobin.trim() || (gopath.trim() ? path.join(gopath.trim().split(path.delimiter)[0]!, "bin") : "");
          for (const spec of cls.requested) {
            const [pkg = "", version = ""] = spec.split("@");
            if (!pkg) continue;
            const parts = pkg.split("/").filter((part) => !/^v\d+$/.test(part));
            const exe = parts.at(-1) ?? "";
            if (/^v\d+\.\d+\.\d+/.test(version)) {
              resolved.push({ name: pkg, version });
              continue;
            }
            if (!bin || !exe) continue;
            const info = await ctx.run(real ?? "go", ["version", "-m", path.join(bin, ctx.platform === "win32" ? `${exe}.exe` : exe)], { timeoutMs: 5_000, env: quietEnv({ ...ctx.env, OMNIRUSH_PKGLOG_OFF: "1" }) });
            const mod = /^\s*mod\s+(\S+)\s+(\S+)(?:\s+(\S+))?/m.exec(info?.stdout ?? "");
            if (mod) resolved.push({ name: pkg, version: mod[2]!, ...(mod[3] ? { integrity: mod[3] } : {}) });
          }
        } else lockfile = await findUp(cwd, LOCKFILES.go!, ctx.root);
        break;
      }
      case "gem": {
        if (cls.scope === "project") {
          lockfile = await findUp(cwd, LOCKFILES.gem!, ctx.root);
          break;
        }
        for (const spec of cls.requested.slice(0, 10)) {
          const [name = "", wanted = ""] = spec.split("@");
          if (!name) continue;
          const listed = await ctx.run(real ?? "gem", ["list", "--local", "--exact", name], { timeoutMs: 10_000, env: quietEnv({ ...ctx.env, OMNIRUSH_PKGLOG_OFF: "1" }) });
          const versions = /\(([^)]*)\)/.exec(listed?.stdout ?? "")?.[1]?.split(",").map((item) => item.trim().replace(/^default:\s*/, "").split(" ")[0]!) ?? [];
          const version = wanted && versions.includes(wanted) ? wanted : versions[0];
          if (version) resolved.push({ name, version });
        }
        break;
      }
      case "composer":
        if (cls.scope === "project") lockfile = await findUp(cwd, LOCKFILES.composer!, ctx.root);
        break;
      case "apt": {
        const parse = (text: string | null) => {
          const out = new Map<string, string>();
          for (const block of (text ?? "").split(/\n\n+/)) {
            const name = /^Package: (.+)$/m.exec(block)?.[1];
            const version = /^Version: (.+)$/m.exec(block)?.[1];
            const status = /^Status: (.+)$/m.exec(block)?.[1] ?? "";
            const arch = /^Architecture: (.+)$/m.exec(block)?.[1];
            if (name && version && status.includes("installed") && !status.includes("not-installed") && !status.includes("config-files")) out.set(arch && arch !== "all" ? `${name}:${arch}` : name, version);
          }
          return out;
        };
        const before = parse(await read("b.dpkg"));
        const after = parse(await read("a.dpkg"));
        for (const [name, version] of after) if (before.get(name) !== version) resolved.push({ name: name.replace(/:(?:amd64|arm64|i386|armhf)$/, ""), version });
        for (const [name, version] of before) if (!after.has(name)) removed.push({ name: name.replace(/:(?:amd64|arm64|i386|armhf)$/, ""), version });
        break;
      }
      case "apk": {
        const parse = (text: string | null) => {
          const out = new Map<string, string>();
          for (const block of (text ?? "").split(/\n\n+/)) {
            const name = /^P:(.+)$/m.exec(block)?.[1];
            const version = /^V:(.+)$/m.exec(block)?.[1];
            if (name && version) out.set(name, version);
          }
          return out;
        };
        const before = parse(await read("b.apk"));
        const after = parse(await read("a.apk"));
        for (const [name, version] of after) if (before.get(name) !== version) resolved.push({ name, version });
        for (const [name, version] of before) if (!after.has(name)) removed.push({ name, version });
        break;
      }
      case "rpm":
      case "pacman": {
        if (!names.length) break;
        const probe = cls.ecosystem === "rpm" ? ["rpm", ["-q", "--qf", "%{NAME}\t%{VERSION}-%{RELEASE}\n", ...names.slice(0, 50)]] as const : ["pacman", ["-Q", ...names.slice(0, 50)]] as const;
        const out = await ctx.run(probe[0], [...probe[1]], { timeoutMs: 10_000 });
        for (const line of (out?.stdout ?? "").split(/\r?\n/)) {
          const [name, version] = line.split(/[\t ]+/);
          if (name && version && !/not installed|was not found/.test(line)) resolved.push({ name, version });
        }
        break;
      }
      case "brew": {
        if (!real) break;
        let prefix: string;
        try {
          prefix = path.dirname(path.dirname(await fs.realpath(real)));
        } catch {
          prefix = path.dirname(path.dirname(real));
        }
        for (const spec of cls.requested) {
          const cask = spec.startsWith("cask:");
          const name = packageName(spec).split("/").at(-1) ?? "";
          if (!name) continue;
          const dir = path.join(prefix, cask ? "Caskroom" : "Cellar", name);
          let versions: string[] = [];
          try {
            versions = await fs.readdir(dir);
          } catch {
            continue;
          }
          let newest: { version: string; at: number } | null = null;
          for (const version of versions) {
            const at = (await mtimeMs(path.join(dir, version))) ?? 0;
            if (!newest || at > newest.at) newest = { version, at };
          }
          if (newest) resolved.push({ name: cask ? `cask:${name}` : name, version: newest.version });
        }
        break;
      }
      case "winget": {
        if (ctx.platform !== "win32") break;
        for (const spec of cls.requested.slice(0, 3)) {
          const id = spec.split("@")[0]!;
          const out = await ctx.run("winget", ["list", "--id", id, "--exact", "--accept-source-agreements", "--disable-interactivity"], { timeoutMs: 20_000 });
          const row = (out?.stdout ?? "").split(/\r?\n/).find((line) => line.includes(id));
          const version = row?.slice(row.indexOf(id) + id.length).trim().split(/\s+/)[0];
          if (version && /\d/.test(version)) resolved.push({ name: id, version });
        }
        break;
      }
      case "choco": {
        const base = ctx.env.ChocolateyInstall ?? "C:\\ProgramData\\chocolatey";
        for (const name of names) {
          const nuspec = await readText(path.join(base, "lib", name, `${name}.nuspec`), 1024 * 1024);
          const version = nuspec ? /<version>([^<]+)<\/version>/.exec(nuspec)?.[1] : undefined;
          if (version) resolved.push({ name, version });
        }
        break;
      }
      case "scoop": {
        if (!ctx.home) break;
        const base = ctx.env.SCOOP ?? path.join(ctx.home, "scoop");
        for (const name of names) {
          const manifest = (await readJson(path.join(base, "apps", name.split("/").at(-1)!, "current", "manifest.json"))) as { version?: unknown } | null;
          if (manifest && typeof manifest.version === "string") resolved.push({ name, version: manifest.version });
        }
        break;
      }
      case "browsers": {
        if (!ctx.home) break;
        const dir = ctx.env.PLAYWRIGHT_BROWSERS_PATH && ctx.env.PLAYWRIGHT_BROWSERS_PATH !== "0" ? ctx.env.PLAYWRIGHT_BROWSERS_PATH
          : ctx.platform === "darwin" ? path.join(ctx.home, "Library", "Caches", "ms-playwright")
            : ctx.platform === "win32" ? path.join(ctx.env.LOCALAPPDATA ?? path.join(ctx.home, "AppData", "Local"), "ms-playwright")
              : path.join(ctx.home, ".cache", "ms-playwright");
        let entries: string[] = [];
        try {
          entries = await fs.readdir(dir);
        } catch {
          entries = [];
        }
        for (const entry of entries) {
          const match = /^(.+)-(\d+)$/.exec(entry);
          const at = await mtimeMs(path.join(dir, entry));
          if (match && at !== null && at >= call.start - 5_000) resolved.push({ name: match[1]!, version: match[2]! });
        }
        target = tildeText(dir, { home: ctx.home, user: null });
        break;
      }
      case "corepack": {
        for (const spec of cls.requested) {
          const [name = "", version = ""] = spec.startsWith("@") ? [spec] : spec.split("@");
          if (name && version) resolved.push({ name, version });
        }
        break;
      }
      case "runtime":
      case "rustup":
      case "conda":
        break;
      case "url": {
        const url = call.argv.find((word) => /^(?:https?|ftp):\/\//i.test(word));
        if (!url) break;
        let out: string | null;
        if (tool === "curl") {
          out = flagValue(call.argv, "-o", "--output");
          if (out === null) {
            const combined = call.argv.findIndex((word) => /^-[^-]*o$/.test(word));
            if (combined >= 0) out = call.argv[combined + 1] ?? null;
          }
          if (out === null && (hasFlag(call.argv, "-O", "--remote-name", "--remote-name-all") || call.argv.some((word) => /^-[^-]*O$/.test(word)))) out = "@remote";
        } else {
          out = flagValue(call.argv, "-O", "--output-document") ?? "@remote";
        }
        if (out === "-") out = null;
        if (out !== null) {
          let file = out;
          if (out === "@remote") {
            let base = "index.html";
            try {
              base = decodeURIComponent(new URL(url).pathname.split("/").filter(Boolean).at(-1) ?? "") || "index.html";
            } catch {
              /* keep */
            }
            const dir = tool === "wget" ? flagValue(call.argv, "-P", "--directory-prefix") ?? "" : "";
            file = path.join(dir, base);
          }
          const absolute = path.resolve(cwd, file);
          const hashed = await sha256File(absolute);
          downloads.push({ url, path: absolute, ...(hashed?.sha256 ? { sha256: hashed.sha256 } : {}), ...(hashed ? { size: hashed.size } : {}) });
        } else {
          downloads.push({ url, path: "(stdout)" });
        }
        break;
      }
    }
  } catch {
    /* what was found so far */
  }
  return { resolved: resolved.slice(0, MAX_PACKAGES), removed: removed.slice(0, MAX_PACKAGES), downloads, target, python, lockfile };
}

function osName(platform: NodeJS.Platform): InstallLine["os"] {
  return platform === "win32" ? "windows" : platform === "darwin" ? "darwin" : "linux";
}

/** `child` relative to `root` with `/`, "" for the root itself, null when outside it. */
export function relativeTo(root: string, child: string | null, platform: NodeJS.Platform = process.platform): string | null {
  if (!child || !root) return null;
  const mod = platform === "win32" ? path.win32 : path.posix;
  const rel = mod.relative(mod.resolve(root), mod.resolve(child));
  if (rel === "") return "";
  if (rel.startsWith("..") || mod.isAbsolute(rel)) return null;
  return rel.split(mod.sep).join("/");
}

/** The calls the wrappers noted, as ledger lines (credentials stripped, the home as `~`). */
export async function lineOf(call: RawCall, options: { root: string; turn: number | null; callId: string | null; command: string | null; privacy: PrivacyContext; scrub: Scrubber; platform: NodeJS.Platform; env: NodeJS.ProcessEnv; run: Runner }): Promise<InstallLine | null> {
  const tool = (call.meta.tool || "pip").toLowerCase();
  const cls = classifyCall(tool, call.argv);
  if (!cls) return null;
  const ctx: ResolveContext = { platform: options.platform, home: options.privacy.home, env: options.env, run: options.run, root: options.root };
  const found = await resolveCall(call, cls, tool, ctx);
  if (cls.ecosystem === "url") {
    const download = found.downloads[0];
    if (!download) return null;
    if (download.path === "(stdout)") {
      // Only a script piped into an interpreter is an install; a plain request is not.
      const piped = options.command && /\b(?:curl|wget)\b[^|;&]*\|\s*(?:sudo\s+(?:-\S+\s+)*)?(?:ba|z|da|k)?sh\b|\b(?:curl|wget)\b[^|;&]*\|\s*(?:sudo\s+)?(?:python3?|node|perl|ruby|iex|bash)\b/.test(options.command);
      if (!piped) return null;
      download.path = "(piped)";
    }
  }
  const tilde = (text: string | null) => (text === null ? null : options.scrub.text(tildeText(text, options.privacy)));
  const { args, truncated } = sanitizeArgs(call.argv);
  const cwd = call.meta.cwd || options.root;
  const hook = call.hooks[0];
  const exit = call.exit ?? (hook?.meta.exit ? Number(hook.meta.exit) : null);
  const end = call.end ?? (hook?.meta.t1 ? Number(hook.meta.t1) : null);
  const lockSha = found.lockfile ? (await sha256File(found.lockfile, 64 * 1024 * 1024))?.sha256 || null : null;
  const line: InstallLine = {
    v: 1,
    schema: INSTALL_LOG_SCHEMA,
    ts: new Date(call.start).toISOString(),
    end: end ? new Date(end).toISOString() : null,
    dur_ms: end ? Math.max(0, Math.round(end - call.start)) : null,
    turn: options.turn,
    call: options.callId,
    tool,
    via: call.meta.via === "python-hook" ? "python-hook" : "shim",
    real: tilde(call.meta.real || hook?.meta.python || null),
    argv: args.map((arg) => options.scrub.text(tildeText(arg, options.privacy))),
    cwd: tilde(cwd)!,
    cwd_rel: relativeTo(options.root, cwd, options.platform),
    exit: Number.isFinite(exit) ? exit : null,
    os: osName(options.platform),
    scope: hook && cls.ecosystem === "pypi" && cls.scope === "project" && hook.meta.prefix && hook.meta.base_prefix && hook.meta.prefix === hook.meta.base_prefix ? "global" : cls.scope,
    ecosystem: cls.ecosystem,
    target: found.target === "global" ? "global" : tilde(found.target),
    target_rel: found.target && found.target !== "global" ? relativeTo(options.root, found.target, options.platform) : null,
    python: found.python,
    requested: cls.requested.slice(0, 500).map((spec) => options.scrub.text(tildeText(redactionRaw() ? spec : cleanArg(spec), options.privacy))),
    resolved: found.resolved.map((pkg) => ({ ...pkg, ...(pkg.source && !redactionRaw() ? { source: cleanUrl(pkg.source) } : {}) })),
    removed: found.removed,
    downloads: found.downloads.map((download) => ({
      url: redactionRaw() ? download.url : cleanUrl(download.url),
      path: download.path.startsWith("(") ? download.path : tilde(download.path)!,
      path_rel: download.path.startsWith("(") ? null : relativeTo(options.root, download.path, options.platform),
      ...(download.sha256 ? { sha256: download.sha256 } : {}),
      ...(download.size !== undefined ? { size: download.size } : {}),
    })),
    lockfile: found.lockfile ? path.basename(found.lockfile) : null,
    lockfile_rel: found.lockfile ? relativeTo(options.root, found.lockfile, options.platform) : null,
    lockfile_sha256: lockSha,
    ...(truncated || found.resolved.length >= MAX_PACKAGES ? { truncated: true } : {}),
  };
  return line;
}

// --- PowerShell downloads (cmdlets no PATH wrapper sees) ----------------------------

// PowerShell's download and install cmdlets and their aliases. No PATH wrapper sees a cmdlet,
// and the engine starts PowerShell with -NoProfile (no function wrapper can be loaded only for
// the agent's shells without changing the engine or the execution policy), so they are read from
// the call's command text. The names are put together here so that the package scanner
// (scripts/scan-package.mjs), which looks for download-and-run code in what ships, never takes
// this reader of the agent's commands for such code.
const PS_WEB = ["Invoke-" + "WebRequest", "iwr", "Invoke-" + "RestMethod", "irm", "Start-" + "BitsTransfer", "wget", "curl"];
const PS_DOWNLOAD = new RegExp(`(?:^|[\\s(&|{])(${PS_WEB.join("|")})(?=\\s|$)(.*)$`, "i");
const PS_RUN = new RegExp(`\\|\\s*(?:iex|Invoke-${"Expression"})\\b|^\\s*(?:iex|Invoke-${"Expression"})\\b|[;&]\\s*(?:iex|Invoke-${"Expression"})\\b`, "i");
const PS_CLIENT = new RegExp(`(?:New-Object\\s+(?:-TypeName\\s+)?["']?(?:System\\.)?Net\\.${"WebClient"}["']?\\)?|\\[(?:System\\.)?Net\\.${"WebClient"}\\]::new\\(\\)\\)?)[^.]*\\.(Download${"String"}|Download${"File"})\\(\\s*([^)]*)\\)`, "i");
const PS_MODULE = /\b(Install-Module|Install-Package|Install-Script|Install-PSResource|Update-Module)\b(.*)$/i;

/** `$name = "value"` assignments of a PowerShell command (so `-Uri $url` can be read). */
function psVariables(command: string): Map<string, string> {
  const vars = new Map<string, string>();
  for (const match of command.matchAll(/\$([A-Za-z_][\w]*)\s*=\s*(["'])([^"'\r\n]*)\2/g)) vars.set(match[1]!.toLowerCase(), match[3]!);
  return vars;
}

/** A word of a PowerShell segment: quotes removed, `$var` from the command's own assignments. */
function psWord(raw: string | undefined, vars: Map<string, string>): string | null {
  if (!raw) return null;
  let word = raw.trim().replace(/^["']|["']$/g, "");
  word = word.replace(/\$\{?([A-Za-z_]\w*)\}?/g, (all, name: string) => vars.get(name.toLowerCase()) ?? all);
  return word || null;
}

function psFlag(rest: string, names: string[]): string | undefined {
  const re = new RegExp(`-(?:${names.join("|")})(?::|\\s+)("[^"]*"|'[^']*'|[^\\s;|)]+)`, "i");
  return re.exec(rest)?.[1];
}

/** Downloads a PowerShell command makes (cmdlets, their aliases, the .NET web client): url + file, or piped into a run. */
export function powershellDownloads(command: string): Array<{ url: string; out: string | null; piped: boolean; unresolved?: boolean }> {
  const out: Array<{ url: string; out: string | null; piped: boolean; unresolved?: boolean }> = [];
  const vars = psVariables(command);
  const isUrl = (word: string | null): word is string => Boolean(word && /^(?:https?|ftp):\/\/\S+$/i.test(word));
  for (const segment of command.split(/;|\r?\n|&&|\|\|/)) {
    const client = PS_CLIENT.exec(segment);
    if (client) {
      const args = client[2]!.split(",").map((part) => psWord(part, vars));
      if (isUrl(args[0] ?? null)) {
        const file = client[1]!.toLowerCase().endsWith("file") ? args[1] ?? null : null;
        if (file || PS_RUN.test(segment)) out.push({ url: args[0]!, out: file, piped: !file });
      }
      continue;
    }
    const match = PS_DOWNLOAD.exec(segment);
    if (!match) continue;
    const cmdlet = match[1]!;
    const rest = match[2]!;
    // curl/wget without PowerShell's own parameters are the real programs: their wrapper saw them.
    if (/^(?:curl|wget)$/i.test(cmdlet) && !/-(?:Uri|OutFile|UseBasicParsing|Method|Headers)\b/i.test(rest)) continue;
    let url = psWord(psFlag(rest, ["Uri", "Source"]), vars);
    if (!isUrl(url)) {
      const positional = /^\s+("[^"]*"|'[^']*'|[^\s;|)-][^\s;|)]*)/.exec(rest)?.[1];
      url = psWord(positional, vars);
    }
    // A URL given after other parameters (iwr -UseBasicParsing https://...).
    if (!isUrl(url)) url = psWord(/(?:^|\s)(["']?(?:https?|ftp):\/\/[^\s"'|;)]+["']?)/i.exec(rest)?.[1], vars);
    const file = psWord(psFlag(rest, ["OutFile", "Destination"]), vars);
    const piped = PS_RUN.test(rest) || PS_RUN.test(segment.slice(0, match.index));
    if (!file && !piped) continue;
    if (isUrl(url)) {
      out.push({ url, out: file, piped: piped && !file });
      continue;
    }
    // The URL is a loop variable or built at run time: the command's literal URLs, the file unknown.
    for (const found of command.matchAll(/["'\s(=,@]((?:https?|ftp):\/\/[^\s"'|;)$,]+)/gi)) {
      if (!out.some((item) => item.url === found[1])) out.push({ url: found[1]!, out: null, piped: false, unresolved: true });
    }
  }
  return out;
}

/** PowerShell Gallery installs a command makes: module or script names, the version asked for, and the scope. */
export function powershellModules(command: string): Array<{ cmdlet: string; names: string[]; version: string | null; scope: "user" | "system" }> {
  const out: Array<{ cmdlet: string; names: string[]; version: string | null; scope: "user" | "system" }> = [];
  const vars = psVariables(command);
  for (const segment of command.split(/;|\r?\n|&&|\|\|/)) {
    const match = PS_MODULE.exec(segment);
    if (!match) continue;
    const rest = match[2]!;
    let names = psWord(psFlag(rest, ["Name"]), vars);
    if (!names) names = psWord(/^\s+("[^"]*"|'[^']*'|[^\s;|)-][^\s;|)]*)/.exec(rest)?.[1], vars);
    const list = (names ?? "").split(",").map((name) => name.trim().replace(/^["']|["']$/g, "")).filter((name) => /^[\w.-]+$/.test(name));
    if (!list.length) continue;
    const version = psWord(psFlag(rest, ["RequiredVersion", "Version", "MinimumVersion"]), vars);
    const scope = /-Scope(?::|\s+)["']?AllUsers/i.test(rest) ? "system" : "user";
    out.push({ cmdlet: match[1]!, names: list, version: version && /^[\w.-]+$/.test(version) ? version : null, scope });
  }
  return out;
}

/** The installed versions of a PowerShell module (newest first): the user's and the machine's module folders. */
export async function powershellModuleVersions(name: string, env: NodeJS.ProcessEnv, home: string | null): Promise<string[]> {
  const docs = [env.OneDrive ? path.join(env.OneDrive, "Documents") : null, home ? path.join(home, "Documents") : null].filter((dir): dir is string => Boolean(dir));
  const programFiles = env.ProgramFiles ?? "C:\\Program Files";
  const roots = [
    ...docs.flatMap((dir) => [path.join(dir, "WindowsPowerShell", "Modules"), path.join(dir, "PowerShell", "Modules")]),
    path.join(programFiles, "WindowsPowerShell", "Modules"),
    path.join(programFiles, "PowerShell", "Modules"),
  ];
  for (const root of roots) {
    let entries: string[] = [];
    try {
      entries = await fs.readdir(path.join(root, name));
    } catch {
      continue;
    }
    const versions: Array<{ version: string; at: number }> = [];
    for (const entry of entries) if (/^\d+(?:\.\d+)+/.test(entry)) versions.push({ version: entry, at: (await mtimeMs(path.join(root, name, entry))) ?? 0 });
    if (versions.length) return versions.sort((a, b) => b.at - a.at).map((item) => item.version);
  }
  return [];
}

/** A PowerShell path word on this machine: $env:NAME, $HOME and ~ expanded. */
export function powershellPath(word: string, env: NodeJS.ProcessEnv, home: string | null): string {
  let out = word.replace(/\$env:([A-Za-z_]\w*)/gi, (all, name: string) => {
    const key = Object.keys(env).find((item) => item.toLowerCase() === name.toLowerCase());
    return key ? env[key] ?? all : all;
  });
  if (home) out = out.replace(/^(?:\$HOME|~)(?=$|[\\/])/i, home);
  return out;
}

// --- per-turn environment ---------------------------------------------------------

const RUNTIMES: Array<{ name: string; commands: string[]; args: string[]; pattern: RegExp }> = [
  { name: "node", commands: ["node"], args: ["--version"], pattern: /v?(\d+\.\d+\.\d+)/ },
  { name: "python", commands: ["python3", "python"], args: ["--version"], pattern: /Python (\d+\.\d+\.\d+)/ },
  { name: "go", commands: ["go"], args: ["version"], pattern: /go(\d+\.\d+(?:\.\d+)?)/ },
  { name: "rustc", commands: ["rustc"], args: ["--version"], pattern: /rustc (\d+\.\d+\.\d+)/ },
  { name: "java", commands: ["java"], args: ["-version"], pattern: /version "?(\d+(?:\.\d+)*)/ },
  { name: "ruby", commands: ["ruby"], args: ["--version"], pattern: /ruby (\d+\.\d+\.\d+)/ },
];
const PIN_FILES = [".nvmrc", ".node-version", ".python-version", ".tool-versions", "mise.toml", ".mise.toml", "rust-toolchain", "rust-toolchain.toml", ".ruby-version", ".java-version", ".sdkmanrc"];
const MANAGER_ENV: Array<[string, string]> = [
  ["NVM_DIR", "nvm"], ["PYENV_ROOT", "pyenv"], ["PYENV_SHELL", "pyenv"], ["MISE_SHELL", "mise"], ["ASDF_DIR", "asdf"], ["ASDF_DATA_DIR", "asdf"],
  ["VOLTA_HOME", "volta"], ["FNM_DIR", "fnm"], ["FNM_MULTISHELL_PATH", "fnm"], ["RBENV_ROOT", "rbenv"], ["SDKMAN_DIR", "sdkman"], ["CONDA_PREFIX", "conda"], ["NVM_HOME", "nvm-windows"],
];
const MANAGER_PATH: Array<[RegExp, string]> = [
  [/[\\/]\.nvm[\\/]/, "nvm"], [/[\\/]\.pyenv[\\/]|[\\/]pyenv-win[\\/]/, "pyenv"], [/[\\/]mise[\\/](?:installs|shims)[\\/]/, "mise"], [/[\\/]\.asdf[\\/]/, "asdf"],
  [/[\\/]\.volta[\\/]/, "volta"], [/fnm/, "fnm"], [/[\\/]\.rbenv[\\/]/, "rbenv"], [/[\\/]\.sdkman[\\/]/, "sdkman"], [/conda|miniforge|mambaforge/i, "conda"], [/[\\/]\.local[\\/]share[\\/]uv[\\/]python[\\/]/, "uv"],
];

async function which(command: string, pathValue: string, platform: NodeJS.Platform, skip: string | null): Promise<string | null> {
  const sep = platform === "win32" ? ";" : ":";
  const exts = platform === "win32" ? [".exe", ".cmd", ".bat"] : [""];
  for (const dir of pathValue.split(sep)) {
    if (!dir || (skip && path.resolve(dir) === path.resolve(skip))) continue;
    for (const ext of exts) {
      const file = path.join(dir, `${command}${ext}`);
      try {
        const stat = await fs.stat(file);
        if (stat.isFile()) return file;
      } catch {
        /* next */
      }
    }
  }
  return null;
}

export type EnvTurn = {
  schema: typeof ENV_TURN_SCHEMA;
  turn: number;
  at: string;
  os: InstallLine["os"];
  arch: string;
  os_version: string | null;
  runtimes: Record<string, string>;
  paths: Record<string, string>;
  managers: string[];
  pins: Record<string, string>;
  changed: boolean;
  installs: number;
  outside_writes: Array<{ path: string; size: number; sha256: string | null; mtime: string }>;
  outside_truncated: boolean;
  timings_ms: Record<string, number>;
};

/** Runtime versions are probed again only when this key (binaries on PATH, their mtime, the version pins) changes. */
const fingerprintCache = new Map<string, { key: string; runtimes: Record<string, string> }>();

type EnvFingerprint = Omit<EnvTurn, "schema" | "turn" | "at" | "installs" | "outside_writes" | "outside_truncated" | "timings_ms">;

/** The box's machine, kernel and the runtimes on its PATH (`<command> <path>` lines). */
// PATH is walked by hand so the install log's wrappers (~/.omnirush/pkglog/bin-*, the box's
// /opt/omnirush/pkglog) are skipped, as `skipDir` does on this machine. It always exits 0: a
// loop whose last command is missing would end 127, which reads as "no box".
const BOX_WHICH = `uname -m; uname -r; IFS=:; for c in ${[...new Set(["mise", ...RUNTIMES.flatMap((runtime) => runtime.commands)])].join(" ")}; do for d in $PATH; do case "$d" in */pkglog|*/pkglog/*) continue;; esac; if [ -f "$d/$c" ] && [ -x "$d/$c" ]; then echo "$c $d/$c"; break; fi; done; done; true`;

/**
 * The fingerprint of a session whose shell tool runs in its box (src/box):
 * the runtimes the agent's commands run with are the box's, so they are
 * found and probed there (`run`: a runner for commands inside it); the
 * version pins are the project's files, the same in and out of the box.
 */
async function boxEnvFingerprint(options: { root: string; privacy: PrivacyContext; run: Runner }): Promise<EnvFingerprint> {
  const result = await options.run("sh", ["-c", BOX_WHICH], { timeoutMs: 5_000, cwd: options.root, maxBytes: 64 * 1024 });
  const lines = (result && result.code === 0 ? result.stdout : "").split("\n").map((line) => line.trim());
  const machine = lines[0] ?? "";
  const found = new Map<string, string>();
  for (const line of lines.slice(2)) {
    const match = /^(\S+) (\/\S+)$/.exec(line);
    if (match) found.set(match[1]!, match[2]!);
  }
  const paths: Record<string, string> = {};
  for (const runtime of RUNTIMES) {
    const command = runtime.commands.find((name) => found.has(name));
    if (command) paths[runtime.name] = found.get(command)!;
  }
  const pins: Record<string, string> = {};
  for (const name of PIN_FILES) {
    const text = await readText(path.join(options.root, name), 4096);
    if (text !== null) pins[name] = text.trim().slice(0, 512);
  }
  const managers = new Set<string>();
  for (const file of Object.values(paths)) for (const [pattern, manager] of MANAGER_PATH) if (pattern.test(file)) managers.add(manager);
  if (found.has("mise")) managers.add("mise");
  const key = `${JSON.stringify(paths)}|${JSON.stringify(pins)}`;
  const cacheKey = `box\0${options.root}`;
  const cached = fingerprintCache.get(cacheKey);
  let runtimes: Record<string, string>;
  let changed = true;
  if (cached && cached.key === key) {
    runtimes = cached.runtimes;
    changed = false;
  } else {
    runtimes = {};
    await Promise.all(RUNTIMES.map(async (runtime) => {
      const file = paths[runtime.name];
      if (!file) return;
      const probe = await options.run(file, runtime.args, { timeoutMs: 5_000, cwd: options.root, maxBytes: 64 * 1024 });
      const match = runtime.pattern.exec(`${probe?.stdout ?? ""}\n${probe?.stderr ?? ""}`);
      if (match) runtimes[runtime.name] = match[1]!;
    }));
    fingerprintCache.set(cacheKey, { key, runtimes });
    changed = !cached || JSON.stringify(cached.runtimes) !== JSON.stringify(runtimes);
  }
  return {
    os: "linux",
    arch: machine === "x86_64" ? "x64" : machine === "aarch64" ? "arm64" : machine || "unknown",
    os_version: lines[1] || null,
    runtimes,
    paths: Object.fromEntries(Object.entries(paths).map(([name, file]) => [name, tildeText(file, options.privacy)])),
    managers: [...managers].sort(),
    pins,
    changed,
  };
}

export async function envFingerprint(options: { root: string; pathValue: string; skipDir: string | null; env: NodeJS.ProcessEnv; platform: NodeJS.Platform; arch: string; osVersion: string | null; privacy: PrivacyContext; run: Runner; box?: Runner | null }): Promise<EnvFingerprint> {
  if (options.box) return boxEnvFingerprint({ root: options.root, privacy: options.privacy, run: options.box });
  const paths: Record<string, string> = {};
  const keyParts: string[] = [];
  for (const runtime of RUNTIMES) {
    for (const command of runtime.commands) {
      const found = await which(command, options.pathValue, options.platform, options.skipDir);
      if (!found) continue;
      let real = found;
      let stamp = "";
      try {
        real = await fs.realpath(found);
        const stat = await fs.stat(real);
        stamp = `${stat.size}:${Math.round(stat.mtimeMs)}`;
      } catch {
        /* keep */
      }
      paths[runtime.name] = found;
      keyParts.push(`${runtime.name}=${real}@${stamp}`);
      break;
    }
  }
  const pins: Record<string, string> = {};
  for (const name of PIN_FILES) {
    const text = await readText(path.join(options.root, name), 4096);
    if (text !== null) pins[name] = text.trim().slice(0, 512);
  }
  keyParts.push(JSON.stringify(pins));
  const managers = new Set<string>();
  for (const [name, manager] of MANAGER_ENV) if (options.env[name]) managers.add(manager);
  for (const found of Object.values(paths)) for (const [pattern, manager] of MANAGER_PATH) if (pattern.test(found)) managers.add(manager);
  if (await which("mise", options.pathValue, options.platform, options.skipDir)) managers.add("mise");
  const key = keyParts.join("|");
  const cacheKey = `${options.root}\0${options.pathValue}`;
  const cached = fingerprintCache.get(cacheKey);
  let runtimes: Record<string, string>;
  let changed = true;
  if (cached && cached.key === key) {
    runtimes = cached.runtimes;
    changed = false;
  } else {
    runtimes = {};
    await Promise.all(RUNTIMES.map(async (runtime) => {
      const file = paths[runtime.name];
      if (!file) return;
      const result = await options.run(file, runtime.args, { timeoutMs: 5_000, cwd: options.root, env: quietEnv({ ...options.env, OMNIRUSH_PKGLOG_OFF: "1" }), maxBytes: 64 * 1024 });
      const match = runtime.pattern.exec(`${result?.stdout ?? ""}\n${result?.stderr ?? ""}`);
      if (match) runtimes[runtime.name] = match[1]!;
    }));
    fingerprintCache.set(cacheKey, { key, runtimes });
    changed = !cached || JSON.stringify(cached.runtimes) !== JSON.stringify(runtimes);
  }
  return {
    os: osName(options.platform),
    arch: options.arch,
    os_version: options.osVersion,
    runtimes,
    paths: Object.fromEntries(Object.entries(paths).map(([name, file]) => [name, tildeText(file, options.privacy)])),
    managers: [...managers].sort(),
    pins,
    changed,
  };
}

// Folders whose churn is caches, package trees, app or editor state: never part of the outside manifest.
const SKIP_NAMES = new Set([
  "node_modules", "site-packages", "dist-packages", "__pycache__", ".cache", ".npm", ".pnpm-store", ".yarn", ".bun", "registry", ".rustup", "pkg", ".gradle", ".m2",
  "Library", "ms-playwright", ".git", ".venv", "venv", ".tox", ".vscode", ".vscode-server", ".cursor", ".cursor-server", "Code", "google-chrome", "chromium", "mozilla", ".mozilla",
  "Trash", "systemd", "pulse", "dconf", "omnirush", "OmniRush.ai", "opencode", "pip", "uv", "pypoetry", "go-build", "JetBrains", "Cache", "CachedData", "logs", "Temp", "snap",
  ".ssh", ".gnupg", ".aws", ".kube", ".docker", "keyrings", "Microsoft", "Packages", "fontconfig", "gvfs-metadata", "recently-used.xbel", "tracker3", "nvim", ".local/state",
]);

/** One file or symlink scanOutside found written in a turn's window. */
export type OutsideEntry = {
  /** Absolute. */
  absolute: string;
  kind: "file" | "symlink";
  size: number;
  /** The newer of the content change and the inode change (an extracted or copied file keeps an old mtime). */
  changedMs: number;
  mtimeMs: number;
};

export type OutsideScanOptions = {
  root: string;
  since: number;
  until: number;
  home: string | null;
  platform: NodeJS.Platform;
  env: NodeJS.ProcessEnv;
  exclude: string[];
  /** More folders to look in (a turn's command targets), each with its depth; scanned before the temp folders. */
  extraRoots?: Array<[string, number]>;
  /** Also symlinks (`ln -s`), and files changed by inode time (`unzip`, `tar -x`, `cp -p` keep old mtimes). */
  inodeTimes?: boolean;
  maxEntries?: number;
  maxFiles?: number;
  budgetMs?: number;
};

/**
 * Files written outside the project during a turn, within a time and entry
 * budget: the home's dotfiles and config, ~/.local and ~/bin, /usr/local and
 * /opt, the temp folders (and `extraRoots`). Caches, package trees, app and
 * editor state, and credential files and folders are never listed.
 */
export async function scanOutside(options: OutsideScanOptions): Promise<{ entries: OutsideEntry[]; truncated: boolean; scanned: number }> {
  const started = Date.now();
  const maxEntries = options.maxEntries ?? 4000;
  const maxFiles = options.maxFiles ?? 200;
  const budget = options.budgetMs ?? 250;
  const home = options.home;
  const roots: Array<[string, number]> = [];
  if (home) {
    roots.push([home, 1], [path.join(home, ".config"), 3], [path.join(home, ".local", "bin"), 1], [path.join(home, "bin"), 1]);
    if (options.platform === "win32") {
      if (options.env.APPDATA) roots.push([options.env.APPDATA, 2]);
      if (options.env.LOCALAPPDATA) roots.push([path.join(options.env.LOCALAPPDATA, "Programs"), 2]);
    } else roots.push([path.join(home, ".local", "share"), 2]);
  }
  if (options.platform !== "win32") roots.push(["/usr/local/bin", 1], ["/usr/local/lib", 2], ["/opt", 2]);
  for (const extra of options.extraRoots ?? []) roots.push(extra);
  // Temp folders last: they are the busiest, and each root has its own share of the entry budget.
  const tmp = tmpdir();
  roots.push([tmp, 2]);
  if (options.platform !== "win32" && tmp !== "/tmp") roots.push(["/tmp", 2]);
  const excluded = [path.resolve(options.root), ...options.exclude.map((dir) => path.resolve(dir))];
  const isExcluded = (file: string) => excluded.some((dir) => file === dir || file.startsWith(dir + path.sep));
  const entries: OutsideEntry[] = [];
  const seen = new Set<string>();
  let scanned = 0;
  let truncated = false;
  // Each root gets its own share of the entry budget: a crowded temp folder never hides the home's config files.
  const perRoot = Math.max(200, Math.floor(maxEntries / 4));
  let rootScanned = 0;
  let rootDone = false;
  const inWindow = (ms: number) => ms >= options.since - 1_000 && ms <= options.until + 1_000;
  let freshOnly = false;
  const changedSince = async (dir: string) => {
    try {
      const info = await fs.stat(dir);
      return Math.max(info.mtimeMs, info.ctimeMs) >= options.since - 1_000;
    } catch {
      return false;
    }
  };
  const walk = async (dir: string, depth: number): Promise<void> => {
    if (rootDone) return;
    let listed: import("node:fs").Dirent[];
    try {
      listed = await fs.readdir(dir, { withFileTypes: true });
    } catch {
      return;
    }
    for (const entry of listed) {
      scanned += 1;
      if (++rootScanned > perRoot || scanned > maxEntries || Date.now() - started > budget || entries.length >= maxFiles) {
        truncated = true;
        rootDone = true;
        return;
      }
      const full = path.join(dir, entry.name);
      if (seen.has(full) || isExcluded(full) || SKIP_NAMES.has(entry.name) || entry.name.startsWith("omnirush")) continue;
      seen.add(full);
      if (entry.isDirectory()) {
        // A busy temp folder: only folders that changed in the window are looked into (with inode times).
        if (depth > 1 && !isSecretFolder(full) && (!freshOnly || (await changedSince(full)))) await walk(full, depth - 1);
        if (rootDone) return;
        continue;
      }
      const link = entry.isSymbolicLink();
      if ((!entry.isFile() && !(link && options.inodeTimes)) || isSecretFile(full)) continue;
      let stat: import("node:fs").Stats;
      try {
        stat = link ? await fs.lstat(full) : await fs.stat(full);
      } catch {
        continue;
      }
      const changedMs = options.inodeTimes ? Math.max(stat.mtimeMs, stat.ctimeMs) : stat.mtimeMs;
      if (!inWindow(changedMs)) continue;
      entries.push({ absolute: full, kind: link ? "symlink" : "file", size: stat.size, changedMs, mtimeMs: stat.mtimeMs });
    }
  };
  const temps = new Set([path.resolve(tmp), "/tmp"]);
  for (const [root, depth] of roots) {
    rootScanned = 0;
    rootDone = false;
    freshOnly = Boolean(options.inodeTimes) && temps.has(path.resolve(root));
    await walk(root, depth);
    if (scanned > maxEntries || Date.now() - started > budget || entries.length >= maxFiles) break;
  }
  return { entries, truncated, scanned };
}

/** Files written outside the project during a turn (path, size, sha256; never content), within a time and entry budget. */
export async function outsideWrites(options: { root: string; since: number; until: number; home: string | null; platform: NodeJS.Platform; env: NodeJS.ProcessEnv; privacy: PrivacyContext; scrub: Scrubber; exclude: string[]; maxEntries?: number; maxFiles?: number; budgetMs?: number }): Promise<{ files: EnvTurn["outside_writes"]; truncated: boolean; scanned: number }> {
  const scan = await scanOutside(options);
  const files: EnvTurn["outside_writes"] = [];
  for (const entry of scan.entries) {
    const hashed = entry.size <= 4 * 1024 * 1024 ? await sha256File(entry.absolute, 4 * 1024 * 1024) : null;
    files.push({ path: options.scrub.text(tildeText(entry.absolute, options.privacy)), size: entry.size, sha256: hashed?.sha256 || null, mtime: new Date(entry.mtimeMs).toISOString() });
  }
  return { files, truncated: scan.truncated, scanned: scan.scanned };
}

// --- the per-instance reader -------------------------------------------------------

export type InstallLogHost = {
  /** The instance's raw folder (prepareInstallLog().raw); the engine's PATH has the wrappers. */
  raw: string;
  /** The wrapper folder, left out of PATH lookups for the fingerprint. */
  bin?: string | null;
  /** The server's switch (the host caches GET /collect/capabilities). */
  gate: () => Promise<InstallLogGate>;
  /** Folders of the app itself, never part of the outside manifest. */
  appDirs?: string[];
};

/** A shell call a session's engine ran (its tool events): the window a noted call must fall in. */
export type CallWindow = { sessionId: string; callId: string | null; start: number; end: number | null; cwd: string | null; command: string | null; turn: number };

export class InstallLogReader {
  private draining: Promise<unknown> = Promise.resolve();

  constructor(private readonly raw: string) {}

  /** Complete noted calls, oldest first (folders still being written are left for later). */
  async pending(now = Date.now()): Promise<RawCall[]> {
    let names: string[] = [];
    try {
      names = await fs.readdir(this.raw);
    } catch {
      return [];
    }
    const out: RawCall[] = [];
    for (const name of names) {
      if (name === "on") continue;
      const call = await readRawCall(path.join(this.raw, name), now);
      if (call && (call.complete || now - call.start >= STALE_CALL_MS)) out.push(call);
    }
    return out.sort((a, b) => a.start - b.start);
  }

  /** Runs `work` after the previous drain (one at a time). */
  serial<T>(work: () => Promise<T>): Promise<T> {
    const next = this.draining.then(work, work);
    this.draining = next.catch(() => undefined);
    return next;
  }

  async remove(call: RawCall): Promise<void> {
    await fs.rm(call.dir, { recursive: true, force: true }).catch(() => undefined);
  }
}

/** The engine's shell call a noted call ran under, as the wrapper read it from its environment (OMNIRUSH_CALL; the engine's shell.env hook), or null. */
export function notedCallId(call: RawCall): string | null {
  const id = call.meta.call ?? call.hooks[0]?.meta.call;
  return typeof id === "string" && /^[A-Za-z0-9_.:-]{1,200}$/.test(id) ? id : null;
}

/**
 * Which session and shell call a noted call belongs to: the call its wrapper
 * names (OMNIRUSH_CALL: parallel calls, a sub-agent's, a background command
 * a call started), else its start inside one call window (strictly first,
 * then with slack; folder breaks ties).
 */
export function matchCall(call: RawCall, windows: CallWindow[], now = Date.now()): CallWindow | null {
  const named = notedCallId(call);
  if (named) {
    const exact = windows.find((window) => window.callId === named);
    if (exact) return exact;
  }
  const pick = (inside: CallWindow[]): CallWindow | null | undefined => {
    if (inside.length === 1) return inside[0]!;
    if (inside.length === 0) return undefined;
    const cwd = call.meta.cwd ? path.resolve(call.meta.cwd) : null;
    const byFolder = cwd ? inside.filter((window) => window.cwd && (cwd === path.resolve(window.cwd) || cwd.startsWith(path.resolve(window.cwd) + path.sep))) : [];
    if (byFolder.length === 1) return byFolder[0]!;
    const sessions = new Set(inside.map((window) => window.sessionId));
    if (sessions.size === 1) return { ...inside[0]!, callId: null };
    return null;
  };
  // The engine's own start and end of each call (the same clock): a wrapper starts inside its call.
  const strict = pick(windows.filter((window) => call.start >= window.start - 20 && call.start <= (window.end ?? now) + 20));
  if (strict !== undefined) return strict;
  // Late or early event times: the call that started last before it, within the slack.
  const near = windows.filter((window) => call.start >= window.start - 1_000 && call.start <= (window.end ?? now) + MATCH_SLACK_MS);
  if (near.length === 0) return null;
  const latest = Math.max(...near.map((window) => window.start));
  return pick(near.filter((window) => window.start === latest)) ?? null;
}

export const DEFAULT_RUNNER: Runner = runCommand;
export { homedir as installLogHome };