@loucompanion/forge-bridge 0.1.3-dev.9bc5014a2270 → 0.1.3-dev.a58d7cd1092f

package/dist/shared/process/dotnet-toolchain.js

@@ -0,0 +1,179 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const skippedDirectories = new Set([".git", "bin", "node_modules", "obj"]);
+export async function configureDotNetToolchain(repoRoots, options = {}) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const requiredMajor = await requiredDotNetMajor(repoRoots);
+    if (requiredMajor === null)
+        return null;
+    const explicit = environmentValue(environment, "FORGE_DOTNET_PATH");
+    if (explicit && !path.isAbsolute(explicit)) {
+        throw new Error("dotnet_toolchain_invalid: FORGE_DOTNET_PATH must be an absolute executable path.");
+    }
+    const candidates = dotNetCandidates(environment, platform, options.homeDirectory ?? os.homedir(), requiredMajor);
+    const fileExists = options.fileExists ?? isFile;
+    const listSdks = options.listSdks ?? probeSdks;
+    const probed = [];
+    for (const candidate of candidates) {
+        if (!await fileExists(candidate))
+            continue;
+        try {
+            const output = await listSdks(candidate);
+            const sdkVersion = sdkVersions(output).find((version) => majorVersion(version) === requiredMajor);
+            probed.push(`${candidate} (${sdkVersions(output).join(", ") || "no SDKs"})`);
+            if (!sdkVersion)
+                continue;
+            const rootPath = path.dirname(candidate);
+            prependPath(environment, rootPath, platform);
+            setEnvironmentValue(environment, "DOTNET_ROOT", rootPath);
+            if (platform === "win32")
+                setEnvironmentValue(environment, "DOTNET_ROOT_X64", rootPath);
+            setEnvironmentValue(environment, "FORGE_DOTNET_PATH", candidate);
+            return { executablePath: candidate, rootPath, sdkVersion, requiredMajor };
+        }
+        catch (error) {
+            probed.push(`${candidate} (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    const detail = probed.length > 0 ? ` Probed: ${probed.join("; ")}.` : "";
+    throw new Error(`dotnet_toolchain_unavailable: repositories require .NET SDK ${requiredMajor}.x, but no compatible dotnet executable was found.`
+        + ` Set FORGE_DOTNET_PATH to the absolute executable path.${detail}`);
+}
+async function requiredDotNetMajor(repoRoots) {
+    const majors = [];
+    for (const root of [...new Set(repoRoots.map((candidate) => path.resolve(candidate)))]) {
+        const globalMajor = await readGlobalJsonMajor(root);
+        if (globalMajor !== null) {
+            majors.push(globalMajor);
+            continue;
+        }
+        majors.push(...await readProjectTargetMajors(root));
+    }
+    return majors.length > 0 ? Math.max(...majors) : null;
+}
+async function readGlobalJsonMajor(root) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(path.join(root, "global.json"), "utf8"));
+        return typeof parsed.sdk?.version === "string" ? majorVersion(parsed.sdk.version) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readProjectTargetMajors(root) {
+    const projects = await findProjectFiles(root, 4, 256);
+    const majors = [];
+    for (const project of projects) {
+        let source;
+        try {
+            source = await fs.readFile(project, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const match of source.matchAll(/<TargetFrameworks?>\s*([^<]+)\s*<\/TargetFrameworks?>/giu)) {
+            for (const framework of match[1]?.split(";") ?? []) {
+                const target = /^net(\d+)\./iu.exec(framework.trim());
+                if (target?.[1])
+                    majors.push(Number.parseInt(target[1], 10));
+            }
+        }
+    }
+    return majors;
+}
+async function findProjectFiles(root, maximumDepth, maximumFiles) {
+    const projects = [];
+    async function visit(directory, depth) {
+        if (depth > maximumDepth || projects.length >= maximumFiles)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (projects.length >= maximumFiles)
+                return;
+            if (entry.isDirectory() && !skippedDirectories.has(entry.name)) {
+                await visit(path.join(directory, entry.name), depth + 1);
+            }
+            else if (entry.isFile() && entry.name.toLowerCase().endsWith(".csproj")) {
+                projects.push(path.join(directory, entry.name));
+            }
+        }
+    }
+    await visit(root, 0);
+    return projects;
+}
+function dotNetCandidates(environment, platform, homeDirectory, requiredMajor) {
+    const executable = platform === "win32" ? "dotnet.exe" : "dotnet";
+    const explicit = environmentValue(environment, "FORGE_DOTNET_PATH");
+    if (explicit)
+        return [explicit];
+    const dotNetRoot = environmentValue(environment, "DOTNET_ROOT");
+    const pathValue = environmentValue(environment, "PATH") ?? "";
+    const programFiles = environmentValue(environment, "ProgramFiles");
+    const candidates = [
+        dotNetRoot ? path.join(dotNetRoot, executable) : null,
+        path.join(homeDirectory, ".dotnet", executable),
+        path.join(homeDirectory, `.dotnet${requiredMajor}`, executable),
+        ...(platform === "win32" && programFiles ? [path.join(programFiles, "dotnet", executable)] : []),
+        ...pathValue.split(path.delimiter).filter(Boolean).map((directory) => path.join(directory, executable)),
+    ].filter((candidate) => Boolean(candidate));
+    return [...new Map(candidates.map((candidate) => [canonicalPath(candidate, platform), path.resolve(candidate)])).values()];
+}
+async function probeSdks(candidate) {
+    const { stdout } = await execFileAsync(candidate, ["--list-sdks"], {
+        encoding: "utf8",
+        timeout: 10_000,
+        windowsHide: true,
+    });
+    return stdout;
+}
+function sdkVersions(output) {
+    return output.split(/\r?\n/gu)
+        .map((line) => /^(\d+\.\d+\.\d+(?:[-+][^\s]+)?)/u.exec(line.trim())?.[1] ?? null)
+        .filter((version) => version !== null);
+}
+function majorVersion(version) {
+    const match = /^(\d+)\./u.exec(version.trim());
+    return match?.[1] ? Number.parseInt(match[1], 10) : null;
+}
+async function isFile(candidate) {
+    try {
+        return (await fs.stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function prependPath(environment, directory, platform) {
+    const current = environmentValue(environment, "PATH") ?? "";
+    const normalizedDirectory = canonicalPath(directory, platform);
+    const remaining = current.split(path.delimiter)
+        .filter(Boolean)
+        .filter((entry) => canonicalPath(entry, platform) !== normalizedDirectory);
+    setEnvironmentValue(environment, "PATH", [directory, ...remaining].join(path.delimiter));
+}
+function environmentValue(environment, name) {
+    const key = Object.keys(environment).find((candidate) => candidate.toLowerCase() === name.toLowerCase());
+    return key ? environment[key] : undefined;
+}
+function setEnvironmentValue(environment, name, value) {
+    const keys = Object.keys(environment).filter((candidate) => candidate.toLowerCase() === name.toLowerCase());
+    const target = keys[0] ?? name;
+    for (const duplicate of keys.slice(1))
+        delete environment[duplicate];
+    environment[target] = value;
+}
+function canonicalPath(candidate, platform) {
+    const normalized = path.normalize(candidate);
+    return platform === "win32" ? normalized.toLowerCase() : normalized;
+}

package/dist/shared/process/host-process-recovery.d.ts

@@ -0,0 +1,12 @@
+import type { HostProcessSupervisorMetadata } from "./host-process-supervisor.js";
+export type HostProcessRecoveryOutcome = "absent" | "terminated" | "pid_reused" | "unverifiable";
+export interface HostProcessRecovery {
+    recover(metadata: HostProcessSupervisorMetadata): Promise<HostProcessRecoveryOutcome>;
+}
+/** Exact, birth-marker-fenced recovery for a process tree left by an old bridge. */
+export declare class ExactHostProcessRecovery implements HostProcessRecovery {
+    private readonly platform;
+    private readonly graceMs;
+    constructor(platform?: NodeJS.Platform, graceMs?: number);
+    recover(metadata: HostProcessSupervisorMetadata): Promise<HostProcessRecoveryOutcome>;
+}

package/dist/shared/process/host-process-recovery.js

@@ -0,0 +1,78 @@
+import { captureHostProcessIdentity } from "./host-process-supervisor.js";
+/** Exact, birth-marker-fenced recovery for a process tree left by an old bridge. */
+export class ExactHostProcessRecovery {
+    platform;
+    graceMs;
+    constructor(platform = process.platform, graceMs = 2_000) {
+        this.platform = platform;
+        this.graceMs = graceMs;
+    }
+    async recover(metadata) {
+        if (!processExists(metadata.rootPid))
+            return "absent";
+        if (!metadata.rootIdentity)
+            return "unverifiable";
+        const currentIdentity = captureHostProcessIdentity(metadata.rootPid, this.platform);
+        if (!currentIdentity)
+            return processExists(metadata.rootPid) ? "unverifiable" : "absent";
+        if (currentIdentity !== metadata.rootIdentity)
+            return "pid_reused";
+        if (this.platform === "win32") {
+            signalExactProcess(metadata.rootPid, "SIGTERM");
+        }
+        else {
+            signalExactProcessGroup(metadata.rootPid, "SIGTERM");
+        }
+        await waitForExit(metadata.rootPid, this.graceMs);
+        if (processExists(metadata.rootPid)) {
+            if (captureHostProcessIdentity(metadata.rootPid, this.platform) !== metadata.rootIdentity) {
+                return "pid_reused";
+            }
+            if (this.platform === "win32") {
+                signalExactProcess(metadata.rootPid, "SIGKILL");
+            }
+            else {
+                signalExactProcessGroup(metadata.rootPid, "SIGKILL");
+            }
+            await waitForExit(metadata.rootPid, this.graceMs);
+        }
+        if (processExists(metadata.rootPid)
+            && captureHostProcessIdentity(metadata.rootPid, this.platform) === metadata.rootIdentity) {
+            throw new Error("host_process_recovery_degraded: exact supervised process tree did not stop.");
+        }
+        return "terminated";
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function signalExactProcess(pid, signal) {
+    try {
+        process.kill(pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+function signalExactProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+async function waitForExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && processExists(pid)) {
+        await new Promise(resolve => setTimeout(resolve, 25));
+    }
+}

package/dist/shared/process/host-process-supervisor.d.ts

@@ -0,0 +1,59 @@
+import type { ChildProcess } from "node:child_process";
+export type HostProcessSupervisorStrategy = "windows_job_object" | "unix_process_group";
+export interface HostProcessSupervisionRequest {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string>>;
+}
+export interface HostProcessSupervisedLaunch {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly detached: boolean;
+    readonly supervisorId: string;
+    readonly strategy: HostProcessSupervisorStrategy;
+    readonly metadataPath: string;
+    readonly memoryTelemetryPath?: string;
+    readonly payloadPath?: string;
+    readonly payloadSha256?: string;
+    readonly readyPath?: string;
+    readonly startGrantPath?: string;
+    readonly commandDigest: string;
+}
+export interface HostProcessProviderReady {
+    readonly schemaVersion: 1;
+    readonly supervisorId: string;
+    readonly rootPid?: number;
+    readonly rootIdentity?: string | null;
+    readonly providerPid: number;
+    readonly providerCreatedAt: string;
+    readonly providerIdentity?: string | null;
+    readonly startAttempt: number;
+}
+export interface HostProcessSupervisorMetadata {
+    readonly schemaVersion: 1;
+    readonly supervisorId: string;
+    readonly strategy: HostProcessSupervisorStrategy;
+    readonly rootPid: number;
+    readonly rootCreatedAt: string;
+    readonly rootIdentity?: string | null;
+    readonly commandDigest: string;
+    readonly worktreePath: string;
+    readonly runtimeLeaseId: string;
+    readonly dispatchAttemptId: string;
+    readonly fencingToken: string;
+    readonly bridgePid: number;
+    readonly providerPid?: number;
+    readonly providerCreatedAt?: string;
+    readonly providerIdentity?: string | null;
+    readonly providerStartAttempt?: number;
+}
+export declare function resolveHostProcessSupervisedLaunch(request: HostProcessSupervisionRequest, resolvedCommand: string, resolvedArgs: readonly string[], platform?: NodeJS.Platform): HostProcessSupervisedLaunch | null;
+export declare function persistHostProcessSupervisorMetadata(launch: HostProcessSupervisedLaunch, request: HostProcessSupervisionRequest, rootPid: number, rootCreatedAt: string, providerReady?: HostProcessProviderReady): HostProcessSupervisorMetadata;
+/**
+ * Captures an OS-issued process birth marker. Recovery compares this marker
+ * before signalling a persisted PID so PID reuse can never redirect cleanup
+ * at an unrelated process.
+ */
+export declare function captureHostProcessIdentity(pid: number, platform?: NodeJS.Platform): string | null;
+export declare function terminateHostProcessTree(child: ChildProcess, launch: HostProcessSupervisedLaunch | null, graceMs?: number): Promise<void>;

package/dist/shared/process/host-process-supervisor.js

@@ -0,0 +1,330 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const windowsJobSupervisorPath = fileURLToPath(new URL("../../../runtime/windows-job-supervisor.ps1", import.meta.url));
+export function resolveHostProcessSupervisedLaunch(request, resolvedCommand, resolvedArgs, platform = process.platform) {
+    const env = request.env;
+    if (env?.FORGE_RUNTIME_MODE !== "host")
+        return null;
+    const supervisorId = requiredEnvironment(env, "FORGE_PROCESS_SUPERVISOR_ID");
+    const metadataPath = requiredEnvironment(env, "FORGE_PROCESS_SUPERVISOR_METADATA_PATH");
+    const logDirectory = requiredEnvironment(env, "FORGE_LOG_DIR");
+    assertMetadataPath(logDirectory, metadataPath);
+    const commandDigest = createHash("sha256")
+        .update(JSON.stringify([resolvedCommand, ...resolvedArgs]))
+        .digest("hex");
+    if (platform === "win32") {
+        if (!fs.existsSync(windowsJobSupervisorPath)) {
+            throw new Error(`host_process_supervisor_missing: ${windowsJobSupervisorPath}`);
+        }
+        const payloadPath = `${metadataPath}.launch.json`;
+        const readyPath = `${metadataPath}.provider-ready.json`;
+        const startGrantPath = `${metadataPath}.provider-start-granted`;
+        const memoryTelemetryPath = `${metadataPath}.memory.json`;
+        const serializedPayload = `${JSON.stringify({
+            command: resolvedCommand,
+            args: resolvedArgs,
+            cwd: request.cwd,
+            parentPid: process.pid,
+            supervisorId,
+            readyPath,
+            startGrantPath,
+            memoryTelemetryPath,
+        })}\n`;
+        const payloadSha256 = createHash("sha256").update(serializedPayload).digest("hex");
+        fs.writeFileSync(payloadPath, serializedPayload, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        });
+        return {
+            command: windowsPowerShellPath(),
+            args: [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                windowsJobSupervisorPath,
+                "-Mode",
+                "Outer",
+                "-PayloadPath",
+                payloadPath,
+                "-PayloadSha256",
+                payloadSha256,
+            ],
+            detached: false,
+            supervisorId,
+            strategy: "windows_job_object",
+            metadataPath,
+            memoryTelemetryPath,
+            payloadPath,
+            payloadSha256,
+            readyPath,
+            startGrantPath,
+            commandDigest,
+        };
+    }
+    return {
+        command: resolvedCommand,
+        args: resolvedArgs,
+        detached: true,
+        supervisorId,
+        strategy: "unix_process_group",
+        metadataPath,
+        commandDigest,
+    };
+}
+export function persistHostProcessSupervisorMetadata(launch, request, rootPid, rootCreatedAt, providerReady) {
+    if (!Number.isSafeInteger(rootPid) || rootPid <= 0) {
+        throw new Error("host_process_supervisor_invalid: supervised root PID was not assigned.");
+    }
+    const env = request.env ?? {};
+    const metadata = {
+        schemaVersion: 1,
+        supervisorId: launch.supervisorId,
+        strategy: launch.strategy,
+        rootPid,
+        rootCreatedAt,
+        rootIdentity: providerReady?.rootPid === rootPid
+            ? providerReady.rootIdentity ?? null
+            : captureHostProcessIdentity(rootPid),
+        commandDigest: launch.commandDigest,
+        worktreePath: request.cwd,
+        runtimeLeaseId: requiredEnvironment(env, "FORGE_RESOURCE_LEASE_ID"),
+        dispatchAttemptId: requiredEnvironment(env, "FORGE_DISPATCH_ATTEMPT_ID"),
+        fencingToken: requiredEnvironment(env, "FORGE_FENCING_TOKEN"),
+        bridgePid: process.pid,
+        providerPid: providerReady?.providerPid,
+        providerCreatedAt: providerReady?.providerCreatedAt,
+        providerIdentity: providerReady?.providerIdentity
+            ?? (providerReady ? captureHostProcessIdentity(providerReady.providerPid) : undefined),
+        providerStartAttempt: providerReady?.startAttempt,
+    };
+    fs.writeFileSync(launch.metadataPath, `${JSON.stringify(metadata)}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+    return metadata;
+}
+/**
+ * Captures an OS-issued process birth marker. Recovery compares this marker
+ * before signalling a persisted PID so PID reuse can never redirect cleanup
+ * at an unrelated process.
+ */
+export function captureHostProcessIdentity(pid, platform = process.platform) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (platform === "linux") {
+            const bootId = fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+            const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+            const close = stat.lastIndexOf(")");
+            const fields = close >= 0 ? stat.slice(close + 2).trim().split(/\s+/u) : [];
+            const startTicks = fields[19];
+            return bootId && startTicks && /^\d+$/u.test(startTicks)
+                ? `linux:${bootId}:${startTicks}`
+                : null;
+        }
+        if (platform === "win32") {
+            const output = execFileSync(windowsPowerShellPath(), [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`,
+            ], {
+                encoding: "utf8",
+                windowsHide: true,
+                timeout: 10_000,
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim();
+            return /^\d+$/u.test(output) ? `win32:${output}` : null;
+        }
+        // Other Unix variants do not expose a sufficiently strong birth marker
+        // through Node. Fail closed rather than trust a second-resolution ps time.
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function terminateHostProcessTree(child, launch, graceMs = 2_000) {
+    if (!launch) {
+        await terminateUnsupervisedProcessTree(child, graceMs);
+        return;
+    }
+    if (launch.strategy === "windows_job_object") {
+        const rootPid = child.pid ?? 0;
+        const metadata = readSupervisorMetadata(launch.metadataPath);
+        const rootIdentity = metadata?.rootPid === rootPid
+            ? metadata.rootIdentity ?? null
+            : captureHostProcessIdentity(rootPid, "win32");
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // Closing the launcher is best effort when the Job Object already settled.
+        }
+        await waitForExactProcessExit(rootPid, rootIdentity, graceMs, "win32");
+        if (exactProcessExists(rootPid, rootIdentity, "win32")) {
+            forceWindowsProcessTree(rootPid);
+            await waitForExactProcessExit(rootPid, rootIdentity, graceMs, "win32");
+        }
+        if (exactProcessExists(rootPid, rootIdentity, "win32")) {
+            throw new Error("host_process_supervisor_termination_failed: supervised Windows root did not stop.");
+        }
+        const providerPid = metadata?.providerPid ?? 0;
+        const providerIdentity = metadata?.providerIdentity ?? null;
+        if (exactProcessExists(providerPid, providerIdentity, "win32")) {
+            forceWindowsProcessTree(providerPid);
+            await waitForExactProcessExit(providerPid, providerIdentity, graceMs, "win32");
+        }
+        if (exactProcessExists(providerPid, providerIdentity, "win32")) {
+            throw new Error("host_process_supervisor_termination_failed: supervised Windows provider tree did not stop.");
+        }
+        return;
+    }
+    const processGroupId = child.pid;
+    if (!processGroupId || !signalUnixProcessGroup(processGroupId, "SIGTERM"))
+        return;
+    await waitForUnixProcessGroupExit(processGroupId, graceMs);
+    if (unixProcessGroupExists(processGroupId)) {
+        signalUnixProcessGroup(processGroupId, "SIGKILL");
+        await waitForUnixProcessGroupExit(processGroupId, graceMs);
+    }
+    if (unixProcessGroupExists(processGroupId)) {
+        throw new Error("host_process_supervisor_termination_failed: supervised Unix process group did not stop.");
+    }
+}
+async function terminateUnsupervisedProcessTree(child, graceMs) {
+    const rootPid = child.pid ?? 0;
+    if (!Number.isSafeInteger(rootPid) || rootPid <= 0) {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // The process already settled before a PID was assigned.
+        }
+        return;
+    }
+    if (process.platform === "win32") {
+        // Without a Job Object there is no trustworthy ancestry record after the
+        // root has already exited. Never target a potentially reused Windows PID.
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        const rootIdentity = captureHostProcessIdentity(rootPid, "win32");
+        forceWindowsProcessTree(rootPid);
+        await waitForExactProcessExit(rootPid, rootIdentity, graceMs, "win32");
+        if (exactProcessExists(rootPid, rootIdentity, "win32")) {
+            throw new Error("host_process_supervisor_termination_failed: unsupervised Windows provider tree did not stop.");
+        }
+        return;
+    }
+    if (!signalUnixProcessGroup(rootPid, "SIGTERM"))
+        return;
+    await waitForUnixProcessGroupExit(rootPid, graceMs);
+    if (unixProcessGroupExists(rootPid)) {
+        signalUnixProcessGroup(rootPid, "SIGKILL");
+        await waitForUnixProcessGroupExit(rootPid, graceMs);
+    }
+    if (unixProcessGroupExists(rootPid)) {
+        throw new Error("host_process_supervisor_termination_failed: unsupervised Unix provider tree did not stop.");
+    }
+}
+function requiredEnvironment(env, name) {
+    const value = env[name]?.trim();
+    if (!value)
+        throw new Error(`host_process_supervisor_invalid: ${name} is required.`);
+    return value;
+}
+function assertMetadataPath(logDirectory, metadataPath) {
+    const root = path.resolve(logDirectory);
+    const target = path.resolve(metadataPath);
+    if (target !== root && !target.startsWith(`${root}${path.sep}`)) {
+        throw new Error("host_process_supervisor_invalid: metadata path must be inside FORGE_LOG_DIR.");
+    }
+}
+function windowsPowerShellPath() {
+    const systemRoot = process.env.SystemRoot?.trim() || "C:\\Windows";
+    const candidate = path.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    return fs.existsSync(candidate) ? candidate : "powershell.exe";
+}
+function signalUnixProcessGroup(processGroupId, signal) {
+    try {
+        process.kill(-processGroupId, signal);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        throw error;
+    }
+}
+function unixProcessGroupExists(processGroupId) {
+    try {
+        process.kill(-processGroupId, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        throw error;
+    }
+}
+async function waitForUnixProcessGroupExit(processGroupId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && unixProcessGroupExists(processGroupId)) {
+        await new Promise(resolve => setTimeout(resolve, 25));
+    }
+}
+function readSupervisorMetadata(metadataPath) {
+    try {
+        return JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function exactProcessExists(pid, identity, platform) {
+    if (!identity || !processExists(pid))
+        return false;
+    return captureHostProcessIdentity(pid, platform) === identity;
+}
+function processExists(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function waitForExactProcessExit(pid, identity, timeoutMs, platform) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && exactProcessExists(pid, identity, platform)) {
+        await new Promise(resolve => setTimeout(resolve, 25));
+    }
+}
+function forceWindowsProcessTree(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return;
+    const systemRoot = process.env.SystemRoot?.trim() || "C:\\Windows";
+    const taskkill = path.win32.join(systemRoot, "System32", "taskkill.exe");
+    try {
+        execFileSync(taskkill, ["/PID", String(pid), "/T", "/F"], {
+            windowsHide: true,
+            timeout: 5_000,
+            stdio: "ignore",
+        });
+    }
+    catch {
+        // A racing process exit is verified by the caller before it returns.
+    }
+}

package/dist/shared/process/process.d.ts

@@ -2,6 +2,7 @@ export interface ProcessRunRequest {
     readonly command: string;
     readonly args: readonly string[];
     readonly cwd: string;
+    readonly env?: NodeJS.ProcessEnv;
 }
 export interface ProcessRunResult {
     readonly exitCode: number;

package/dist/shared/process/process.js

@@ -5,6 +5,7 @@ export class NodeProcessRunner {
         return await new Promise((resolve, reject) => {
             const child = spawn(request.command, request.args, {
                 cwd: request.cwd,
+                env: request.env,
                 stdio: ["ignore", "pipe", "pipe"]
             });
             let stdout = "";

package/dist/shared/process/windows-launch.d.ts

@@ -2,7 +2,7 @@ export interface LaunchCommand {
     readonly command: string;
     readonly args: readonly string[];
 }
-export declare function buildWindowsCmdLaunch(command: string, args: readonly string[]): LaunchCommand;
+export declare function buildWindowsCmdLaunch(command: string, args: readonly string[], comSpec?: string | undefined): LaunchCommand;
 export declare function buildWindowsLaunchCommand(commandPath: string, args: readonly string[]): LaunchCommand;
 export declare function windowsCommandLine(command: string, args: readonly string[]): string;
 export declare function quoteWindowsCommandLineArg(value: string): string;