jev-agent-tools 0.1.3 → 0.2.0

package/dist/adapters/private-storage.js

@@ -0,0 +1,98 @@
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import { PRIVATE_STORAGE_TIMEOUT_MS } from "../constants.js";
+const SYSTEM = "S-1-5-18";
+const ADMINISTRATORS = "S-1-5-32-544";
+const CREATOR_OWNER = "S-1-3-0";
+export const posixStorage = {
+    async isPrivate(entries) {
+        return entries.every(({ stat }) => (stat.mode & 0o077) === 0 &&
+            (!process.getuid || stat.uid === process.getuid()));
+    },
+    async restrictDirectory() {
+        // mkdir(..., { mode: 0o700 }) already creates POSIX directories privately.
+    },
+};
+// Paths arrive as JSON in an environment variable, never in the command text.
+const CHECK = `$ErrorActionPreference = 'Stop'
+$me = [System.Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$trusted = @($me, '${SYSTEM}', '${ADMINISTRATORS}')
+$sid = [System.Security.Principal.SecurityIdentifier]
+$results = foreach ($path in (ConvertFrom-Json $env:JEV_PRIVATE_PATHS)) {
+  try {
+    $acl = Get-Acl -LiteralPath $path
+    $owner = $acl.GetOwner($sid).Value
+    $private = ($owner -eq $me) -or ($owner -eq '${ADMINISTRATORS}')
+    foreach ($rule in $acl.GetAccessRules($true, $true, $sid)) {
+      if ($rule.AccessControlType -ne 'Allow') { continue }
+      $id = $rule.IdentityReference.Value
+      $inheritOnly = ($rule.PropagationFlags -band [System.Security.AccessControl.PropagationFlags]::InheritOnly) -ne 0
+      if ($id -eq '${CREATOR_OWNER}' -and $inheritOnly) { continue }
+      if ($trusted -notcontains $id) { $private = $false }
+    }
+    $private
+  } catch { $false }
+}
+ConvertTo-Json -Compress @($results)`;
+const RESTRICT = `$ErrorActionPreference = 'Stop'
+$path = $env:JEV_PRIVATE_PATH
+$me = [System.Security.Principal.WindowsIdentity]::GetCurrent().User
+$acl = Get-Acl -LiteralPath $path
+if ($acl.GetOwner([System.Security.Principal.SecurityIdentifier]).Value -ne $me.Value) { throw 'not owner' }
+$acl.SetAccessRuleProtection($true, $false)
+foreach ($rule in @($acl.Access)) { [void]$acl.RemoveAccessRuleAll($rule) }
+$inherit = [System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit'
+foreach ($id in @($me.Value, '${SYSTEM}', '${ADMINISTRATORS}')) {
+  $rule = New-Object System.Security.AccessControl.FileSystemAccessRule(
+    (New-Object System.Security.Principal.SecurityIdentifier($id)),
+    'FullControl', $inherit, 'None', 'Allow')
+  $acl.AddAccessRule($rule)
+}
+Set-Acl -LiteralPath $path -AclObject $acl`;
+function powershell(script, env) {
+    const root = process.env.SystemRoot ?? "C:\\Windows";
+    // A fixed system path, so a powershell.exe earlier on PATH is never used.
+    const executable = join(root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    // PowerShell 7 parents export PSModulePath, which stops Windows PowerShell
+    // 5.1 from loading its own Get-Acl module; 5.1 rebuilds it when unset.
+    const childEnv = { ...process.env, ...env };
+    for (const key of Object.keys(childEnv))
+        if (key.toLowerCase() === "psmodulepath")
+            delete childEnv[key];
+    const { promise, resolve, reject } = Promise.withResolvers();
+    execFile(executable, [
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        // UTF-16LE base64 runs the script as one unit; stdin runs line by line.
+        "-EncodedCommand",
+        Buffer.from(script, "utf16le").toString("base64"),
+    ], { env: childEnv, windowsHide: true, timeout: PRIVATE_STORAGE_TIMEOUT_MS }, (error, stdout) => (error ? reject(error) : resolve(stdout)));
+    return promise;
+}
+export const windowsStorage = {
+    async isPrivate(entries) {
+        if (!entries.length)
+            return true;
+        try {
+            const output = await powershell(CHECK, {
+                JEV_PRIVATE_PATHS: JSON.stringify(entries.map(({ path }) => path)),
+            });
+            const results = JSON.parse(output.trim());
+            return (Array.isArray(results) &&
+                results.length === entries.length &&
+                results.every((result) => result === true));
+        }
+        catch {
+            // An ACL that cannot be read is never treated as private.
+            return false;
+        }
+    },
+    async restrictDirectory(path) {
+        await powershell(RESTRICT, { JEV_PRIVATE_PATH: path });
+    },
+};
+export function privateStorage(platform = process.platform) {
+    return platform === "win32" ? windowsStorage : posixStorage;
+}

package/dist/adapters/risk-callers.js

@@ -0,0 +1,426 @@
+import { lstat } from "node:fs/promises";
+import { posix } from "node:path";
+import { CONCURRENCY, STATE_MAX_CHARS, TIMEOUT_MS } from "../constants.js";
+import { prepareRiskCallers, } from "../core/risk-callers.js";
+import { admitGitPath, checkFileAdmission, openRepoFile, resolveInsideRepo, } from "./files.js";
+import { loadSyntaxRootParser } from "./syntax.js";
+import { decodeUtf8, verifyGitUtf8 } from "./utf8.js";
+export async function loadCallerParser(sourceParser) {
+    const parser = sourceParser ?? (await loadSyntaxRootParser());
+    if (!parser)
+        return undefined;
+    const versions = new Map();
+    return {
+        supports: parser.supports,
+        parse(path, text) {
+            let entries = versions.get(path);
+            if (!entries) {
+                entries = new Map();
+                versions.set(path, entries);
+            }
+            if (entries.has(text))
+                return entries.get(text) ?? null;
+            const result = parser.parseRaw(path, text);
+            const root = result.ok ? result.root : null;
+            entries.set(text, root);
+            return root;
+        },
+    };
+}
+export async function collectRiskCallers(exec, options, units, changedFiles = [], sourceParser) {
+    if (!units.length)
+        return { proofs: [], limits: [] };
+    const parser = await loadCallerParser(sourceParser);
+    const local = prepareRiskCallers(units, changedFiles.map((file) => ({
+        path: file.path,
+        beforePath: file.oldPath,
+        before: file.before,
+        after: file.after,
+        limitation: file.limitation,
+    })), parser);
+    const eligibleIds = new Set([
+        ...local.proofs.map((proof) => proof.unitId),
+        ...local.limits.map((limit) => limit.unitId),
+    ]);
+    const nameFor = (unit) => {
+        const name = unit.name.split(".").at(-1) ?? unit.name;
+        if (!parser?.supports(unit.file))
+            return;
+        const probe = parser.parse(unit.file, unit.file.endsWith(".py")
+            ? `def ${name}():\n    pass`
+            : `function ${name}() {}`);
+        const declaration = probe
+            ?.children()
+            .find((node) => ["function_definition", "function_declaration"].includes(String(node.kind())));
+        return declaration?.field("name")?.text() === name ? name : undefined;
+    };
+    const eligible = units.filter((unit) => eligibleIds.has(unit.id) &&
+        ["function", "declaration", "slice"].includes(unit.kind) &&
+        nameFor(unit) !== undefined);
+    const retainedLimits = local.limits.filter((limit) => !eligible.some((unit) => unit.id === limit.unitId));
+    if (!eligible.length)
+        return local;
+    let cwd = options.cwd;
+    const git = async (args) => {
+        options.signal?.throwIfAborted();
+        const result = await exec("git", args, {
+            cwd,
+            timeout: TIMEOUT_MS,
+            signal: options.signal,
+        });
+        if (result.code !== 0 || result.killed)
+            throw new Error(result.stderr || "git interrupted");
+        return result.stdout;
+    };
+    try {
+        // The tool supplies the already resolved comparison reference, as for collectUnits.
+        cwd = (await git(["rev-parse", "--show-toplevel"])).trim();
+        const ref = (options.base ?? "HEAD").trim();
+        const sourceExtension = {
+            ".js": ".ts",
+            ".jsx": ".tsx",
+            ".mjs": ".mts",
+            ".cjs": ".cts",
+        };
+        const extensions = [
+            "ts",
+            "tsx",
+            "mts",
+            "cts",
+            "js",
+            "jsx",
+            "mjs",
+            "cjs",
+            "py",
+        ];
+        const tracked = await git([
+            "ls-files",
+            "-z",
+            `--with-tree=${ref}`,
+            "--",
+            ...extensions.map((extension) => `*.${extension}`),
+        ]);
+        const beforePaths = new Set(tracked.split("\0"));
+        const baseInventory = new Map();
+        for (const entry of (await git([
+            "ls-tree",
+            "-r",
+            "--long",
+            "-z",
+            "--full-tree",
+            "--end-of-options",
+            ref,
+        ])).split("\0")) {
+            const separator = entry.indexOf("\t");
+            if (separator !== -1)
+                baseInventory.set(entry.slice(separator + 1), entry);
+        }
+        const modifiedPaths = new Set((await git([
+            "diff",
+            "--name-only",
+            "-z",
+            "--no-renames",
+            "--no-ext-diff",
+            "--no-textconv",
+            ref,
+        ])).split("\0"));
+        const currentPaths = new Set((await git([
+            "ls-files",
+            "-z",
+            "--cached",
+            "--others",
+            "--exclude-standard",
+        ]))
+            .split("\0")
+            .filter(Boolean));
+        const names = [
+            ...new Set(eligible
+                .map((unit) => nameFor(unit))
+                .filter((name) => name !== undefined)),
+        ];
+        const matched = new Set();
+        const inventory = [...beforePaths].filter((path) => /\.(?:[cm]?[jt]sx?|py)$/.test(path));
+        const patternArgs = names.flatMap((name) => ["-e", name]);
+        const priorSearch = exec("git", [
+            "grep",
+            "-l",
+            "-z",
+            "-F",
+            "-w",
+            ...patternArgs,
+            ref,
+            "--",
+            ...extensions.map((extension) => `*.${extension}`),
+        ], { cwd, timeout: TIMEOUT_MS, signal: options.signal }).catch((error) => ({
+            stdout: "",
+            stderr: String(error),
+            code: 2,
+            killed: false,
+        }));
+        // Explicit tracked paths prevent rg from collecting ignored or untracked callers.
+        // Bound argument bytes as well as process concurrency, including long paths.
+        const batches = [];
+        let batch = [];
+        let bytes = 0;
+        for (const path of inventory) {
+            const size = Buffer.byteLength(path) + 1;
+            if (batch.length && bytes + size > 96_000) {
+                batches.push(batch);
+                batch = [];
+                bytes = 0;
+            }
+            batch.push(path);
+            bytes += size;
+        }
+        if (batch.length)
+            batches.push(batch);
+        for (let offset = 0; offset < batches.length; offset += CONCURRENCY) {
+            await Promise.all(batches.slice(offset, offset + CONCURRENCY).map(async (paths) => {
+                options.signal?.throwIfAborted();
+                const metadata = await Promise.all(paths.map(async (path) => {
+                    try {
+                        const admission = await checkFileAdmission(cwd, path, undefined, options.signal, currentPaths);
+                        if (!admission.ok)
+                            return undefined;
+                        const location = await resolveInsideRepo(cwd, path);
+                        if (!location.ok)
+                            return undefined;
+                        return (await lstat(location.abs)).isFile() ? path : undefined;
+                    }
+                    catch (error) {
+                        if (error.code === "ENOENT")
+                            return undefined;
+                        throw error;
+                    }
+                }));
+                const existing = metadata.filter((path) => path !== undefined);
+                if (!existing.length)
+                    return;
+                let current;
+                try {
+                    current = await exec("rg", ["-l", "-0", "-F", "-w", ...patternArgs, "--", ...existing], { cwd, timeout: TIMEOUT_MS, signal: options.signal });
+                }
+                catch {
+                    options.signal?.throwIfAborted();
+                }
+                if (!current || current.code > 1 || current.killed)
+                    current = await exec("git", [
+                        "grep",
+                        "-l",
+                        "-z",
+                        "-F",
+                        "-w",
+                        ...patternArgs,
+                        "--",
+                        ...existing,
+                    ], { cwd, timeout: TIMEOUT_MS, signal: options.signal });
+                if (current.code > 1 || current.killed)
+                    throw new Error(current.stderr || "tracked caller name search failed");
+                for (const path of current.stdout.split("\0"))
+                    if (path && beforePaths.has(path))
+                        matched.add(path);
+            }));
+        }
+        const prior = await priorSearch;
+        if (prior.code > 1 || prior.killed)
+            throw new Error(prior.stderr || "before caller name search failed");
+        for (const path of prior.stdout.split("\0"))
+            if (path.startsWith(`${ref}:`))
+                matched.add(path.slice(ref.length + 1));
+        for (const file of changedFiles)
+            matched.add(file.path);
+        const paths = [...matched];
+        const sources = [];
+        const readBefore = async (path) => {
+            if (!beforePaths.has(path))
+                return { text: null };
+            if (!(await admitGitPath(cwd, path, ref, exec, options.signal, baseInventory)).ok)
+                return { text: null, limitation: "before file not admitted" };
+            const entry = baseInventory.get(path);
+            const metadata = entry &&
+                /^(?:100644|100755|120000) blob ([0-9a-f]+)\s+(\d+)\t/.exec(entry);
+            if (!metadata)
+                return { text: null };
+            const object = metadata[1] ?? "";
+            const size = Number(metadata[2]);
+            if (!Number.isFinite(size) || size > STATE_MAX_CHARS)
+                return { text: null, limitation: "before file exceeds read budget" };
+            const text = await git([
+                "show",
+                "--no-ext-diff",
+                "--no-textconv",
+                "--end-of-options",
+                object,
+            ]);
+            const decoded = verifyGitUtf8(text, object, size);
+            if (!decoded.ok)
+                return { text: null, limitation: `${path}: ${decoded.error}` };
+            return text.length <= STATE_MAX_CHARS && !text.includes("\0")
+                ? { text }
+                : { text: null, limitation: "before binary or oversized" };
+        };
+        const readAfter = async (path) => {
+            let handle;
+            try {
+                options.signal?.throwIfAborted();
+                const location = await resolveInsideRepo(cwd, path);
+                if (!location.ok) {
+                    const metadata = await admitGitPath(cwd, path, ref, exec, options.signal, baseInventory);
+                    if (metadata.ok && location.error.includes("ENOENT"))
+                        return { text: null };
+                    return { text: null, limitation: "after file not admitted" };
+                }
+                const opened = await openRepoFile(cwd, path, {
+                    exec,
+                    signal: options.signal,
+                    inventory: currentPaths,
+                });
+                if (!opened.ok)
+                    return { text: null, limitation: "after file not admitted" };
+                handle = opened.handle;
+                const stat = { size: opened.size };
+                if (stat.size > STATE_MAX_CHARS)
+                    return { text: null, limitation: "after file exceeds read budget" };
+                const buffer = Buffer.alloc(STATE_MAX_CHARS + 1);
+                let offset = 0;
+                while (offset < buffer.length) {
+                    const read = await handle.read(buffer, offset, buffer.length - offset, null);
+                    if (!read.bytesRead)
+                        break;
+                    offset += read.bytesRead;
+                }
+                if (offset > STATE_MAX_CHARS || buffer.subarray(0, offset).includes(0))
+                    return { text: null, limitation: "after binary or oversized" };
+                const decoded = decodeUtf8(buffer.subarray(0, offset));
+                return decoded.ok
+                    ? { text: decoded.text }
+                    : { text: null, limitation: `${path}: ${decoded.error}` };
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    return { text: null };
+                return { text: null, limitation: "after unreadable" };
+            }
+            finally {
+                await handle?.close();
+            }
+        };
+        for (let offset = 0; offset < paths.length;) {
+            const selected = paths.slice(offset, offset + CONCURRENCY);
+            offset += selected.length;
+            const batch = await Promise.all(selected.map(async (path) => {
+                const changed = changedFiles.find((f) => f.path === path);
+                if (changed)
+                    return {
+                        path,
+                        beforePath: changed.oldPath,
+                        before: changed.before,
+                        after: changed.after,
+                        limitation: changed.limitation,
+                    };
+                if (!modifiedPaths.has(path)) {
+                    const after = await readAfter(path);
+                    if (after.text !== null)
+                        return {
+                            path,
+                            before: after.text,
+                            after: after.text,
+                            limitation: after.limitation,
+                        };
+                }
+                const [before, after] = await Promise.all([
+                    readBefore(path),
+                    readAfter(path),
+                ]);
+                return {
+                    path,
+                    before: before.text,
+                    after: after.text,
+                    limitation: before.limitation ?? after.limitation,
+                };
+            }));
+            sources.push(...batch);
+            // Follow static import AST nodes from candidate files so imported concrete providers remain visible.
+            for (const source of batch)
+                for (const side of ["before", "after"]) {
+                    if (side === "after" && source.before === source.after)
+                        continue;
+                    const text = source[side];
+                    if (!text || !parser?.supports(source.path))
+                        continue;
+                    const ast = parser.parse(source.path, text);
+                    if (!ast)
+                        continue;
+                    const visit = (node) => {
+                        if ([
+                            "import_statement",
+                            "import_from_statement",
+                            "export_statement",
+                        ].includes(String(node.kind()))) {
+                            const literal = node.field("source") ?? node.field("module_name");
+                            if (literal) {
+                                const specifier = literal.kind() === "string"
+                                    ? literal.text().slice(1, -1)
+                                    : literal.text();
+                                const sourcePath = side === "before" &&
+                                    "beforePath" in source &&
+                                    typeof source.beforePath === "string"
+                                    ? source.beforePath
+                                    : source.path;
+                                // Repository paths are always "/"-separated; the platform
+                                // resolve would yield "C:\\src\\..." on Windows.
+                                const basePath = specifier.startsWith(".")
+                                    ? posix.resolve("/", sourcePath, "..", specifier).slice(1)
+                                    : specifier.replaceAll(".", "/");
+                                const runtimeSource = basePath.replace(/\.(js|jsx|mjs|cjs)$/, (extension) => sourceExtension[extension] ?? extension);
+                                const candidates = new Set([
+                                    basePath,
+                                    runtimeSource,
+                                    ...extensions.map((extension) => `${basePath}.${extension}`),
+                                    `${basePath}/index.ts`,
+                                    `${basePath}/__init__.py`,
+                                ]);
+                                const matches = [...candidates].filter((path) => beforePaths.has(path));
+                                if (matches.length === 1 && !matched.has(matches[0] ?? "")) {
+                                    matched.add(matches[0] ?? "");
+                                    paths.push(matches[0] ?? "");
+                                }
+                            }
+                        }
+                        for (const child of node.children())
+                            visit(child);
+                    };
+                    if (source.path.endsWith(".py"))
+                        visit(ast);
+                    else
+                        for (const statement of ast.children()) {
+                            if (["import_statement", "export_statement"].includes(String(statement.kind())) &&
+                                statement.field("source"))
+                                visit(statement);
+                        }
+                }
+        }
+        const prepared = prepareRiskCallers(eligible, sources, parser);
+        prepared.limits.push(...retainedLimits);
+        prepared.limits.push(...eligible.map((unit) => ({
+            unitId: unit.id,
+            kind: "dynamic_access_uncovered",
+            reason: "callers found by name; dynamic access not covered",
+            paths: [unit.file],
+            missing: "dynamically named callers",
+        })));
+        return prepared;
+    }
+    catch (error) {
+        return {
+            proofs: [],
+            limits: eligible.map((unit) => ({
+                unitId: unit.id,
+                kind: "unreadable",
+                reason: `caller collection failed: ${String(error)}`,
+                paths: [unit.file],
+                missing: "bounded tracked caller/provider source",
+            })),
+        };
+    }
+}

package/dist/adapters/runner-version.js

@@ -0,0 +1,78 @@
+import { constants } from "node:fs";
+import { open, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { RUNNER_PACKAGE_MAX_BYTES } from "../constants.js";
+import { lockedRunnerVersion, runnerVersion, } from "../core/runner-version.js";
+/** Local-only ignored metadata exception: no contents enter Jev state. Closed runner names,
+ * bounded reads and realpath confinement allow pnpm links only inside the repository. */
+export async function installedRunnerVersion(root, cwd, runner) {
+    if (runner !== "vitest" && runner !== "jest" && runner !== "mocha")
+        return undefined;
+    if (isAbsolute(cwd) || cwd.split(/[\\/]/).includes(".."))
+        return undefined;
+    let handle;
+    try {
+        const base = await realpath(root);
+        const path = await realpath(resolve(base, cwd, "node_modules", runner, "package.json"));
+        const rel = relative(base, path);
+        if (isAbsolute(rel) || rel === ".." || rel.startsWith(`..${sep}`))
+            return undefined;
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > RUNNER_PACKAGE_MAX_BYTES)
+            return undefined;
+        const bytes = Buffer.alloc(RUNNER_PACKAGE_MAX_BYTES + 1);
+        const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+        if (bytesRead > RUNNER_PACKAGE_MAX_BYTES)
+            return undefined;
+        const value = JSON.parse(bytes.subarray(0, bytesRead).toString("utf8"));
+        return runnerVersion(value.version);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+export async function attachRunnerVersions(root, entries, read, known) {
+    const cache = new Map();
+    return Promise.all(entries.map(async (entry) => {
+        if (entry.framework !== "vitest" &&
+            entry.framework !== "jest" &&
+            entry.framework !== "mocha")
+            return entry;
+        const runner = entry.framework;
+        const key = `${entry.cwd}:${runner}`;
+        let pending = cache.get(key);
+        if (!pending) {
+            pending = (async () => {
+                const installed = await installedRunnerVersion(root, entry.cwd, runner);
+                if (installed)
+                    return installed;
+                const dirs = [entry.cwd];
+                for (const dir of dirs)
+                    for (const name of [
+                        "package-lock.json",
+                        "pnpm-lock.yaml",
+                        "yarn.lock",
+                        "bun.lock",
+                    ]) {
+                        const path = dir === "." ? name : `${dir}/${name}`;
+                        if (!known.has(path))
+                            continue;
+                        const source = await read(path);
+                        if (source) {
+                            const version = lockedRunnerVersion(runner, path, source.text);
+                            if (version)
+                                return version;
+                        }
+                    }
+                return undefined;
+            })();
+            cache.set(key, pending);
+        }
+        const version = await pending;
+        return { ...entry, ...(version ? { runnerVersion: version } : {}) };
+    }));
+}

package/dist/adapters/shell.js

@@ -0,0 +1,76 @@
+import { accessSync, constants } from "node:fs";
+// Candidates are Windows paths whatever the host OS, so the helpers use win32
+// semantics explicitly; the host-native `node:path` splits PATH on ":" on POSIX.
+import { win32 } from "node:path";
+function executable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Windows ships `bash.exe` launchers for WSL in System32 (and SysWOW64,
+ * Sysnative) and in WindowsApps. They run in a Linux VM that cannot see Windows
+ * temporary paths, so they are never used for command evidence, including
+ * when named explicitly in JEV_TOOLS_BASH.
+ */
+export function isWslLauncher(path) {
+    const lower = win32.normalize(path).toLowerCase();
+    return (/\\windows\\(system32|syswow64|sysnative)\\/.test(lower) ||
+        lower.includes("\\microsoft\\windowsapps\\"));
+}
+/** Permitted Git for Windows bash candidates, most specific first. */
+export function windowsBashCandidates(env) {
+    const candidates = [];
+    if (env.JEV_TOOLS_BASH?.trim())
+        candidates.push(env.JEV_TOOLS_BASH.trim());
+    const pathEntries = (env.PATH ?? env.Path ?? "")
+        .split(win32.delimiter)
+        .filter(Boolean);
+    for (const entry of pathEntries) {
+        candidates.push(win32.join(entry, "bash.exe"));
+        // Git\cmd\git.exe or Git\bin\git.exe on PATH implies Git\bin\bash.exe.
+        if (/[\\/](cmd|bin)$/i.test(entry))
+            candidates.push(win32.join(win32.dirname(entry), "bin", "bash.exe"));
+    }
+    for (const root of [
+        env.ProgramFiles,
+        env["ProgramFiles(x86)"],
+        env.LOCALAPPDATA && win32.join(env.LOCALAPPDATA, "Programs"),
+    ])
+        if (root)
+            candidates.push(win32.join(root, "Git", "bin", "bash.exe"));
+    // Filter every source, so no candidate can reintroduce a WSL launcher.
+    return [...new Set(candidates)].filter((candidate) => win32.isAbsolute(candidate) && !isWslLauncher(candidate));
+}
+const UNAVAILABLE = "No permitted bash found: install Git for Windows or set JEV_TOOLS_BASH to the full path of a bash that is not the WSL launcher.";
+let cached;
+/**
+ * POSIX hosts keep `env CI=1 bash -c`. Windows has no `env` and its default
+ * `bash` is the WSL launcher, so resolve Git for Windows bash (or
+ * JEV_TOOLS_BASH) to an absolute, permitted path and export CI inside the
+ * script. When none is found this fails closed: no bare name is returned,
+ * because spawning one would search PATH again without the WSL exclusion.
+ */
+export function resolveShell(platform = process.platform, env = process.env, isExecutable = executable) {
+    if (platform !== "win32")
+        return {
+            ok: true,
+            executable: "env",
+            prefix: ["CI=1", "bash"],
+            scriptPrefix: "",
+        };
+    const useCache = isExecutable === executable && env === process.env;
+    if (useCache && cached)
+        return cached;
+    const found = windowsBashCandidates(env).find((path) => isExecutable(path));
+    const resolved = found
+        ? { ok: true, executable: found, prefix: [], scriptPrefix: "export CI=1; " }
+        : { ok: false, error: UNAVAILABLE };
+    if (useCache && found)
+        cached = resolved;
+    return resolved;
+}