@rehearsal-db/core 0.1.0-rc.9 → 1.0.1

package/dist/src/cli/runtime_commands.mjs

@@ -14,6 +14,7 @@ import { RehearsalError, normalizeRehearsalError, redactDiagnosticValue, } from
 import { assertInstalledPackageFingerprint } from "../shared/operation_guard.mjs";
 import { getOperationCancellationSignal, throwIfOperationCancelled, } from "../shared/cancellation.mjs";
 import { runOwnedProcess } from "../shared/owned_process.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 import { getOwnedOperationProgressId, trackOperationStage, } from "../shared/operation_progress.mjs";
 import { buildRuntimeManagerArguments } from "../targets/target.mjs";
 import { parseRuntimeStatusSnapshot, renderRuntimeStatusSnapshot, } from "../runtime/status.mjs";
@@ -55,23 +56,7 @@ const parseCommand = (source) => {
         throw new Error("Application proof command is empty.");
     return values;
 };
-const projectCommandEnvironment = (additional = {}) => ({
-    ...Object.fromEntries([
-        "CI",
-        "COLORTERM",
-        "FORCE_COLOR",
-        "HOME",
-        "LANG",
-        "LC_ALL",
-        "NO_COLOR",
-        "PATH",
-        "SHELL",
-        "TERM",
-        "TMPDIR",
-        "USER",
-    ].flatMap((key) => process.env[key] === undefined ? [] : [[key, process.env[key]]])),
-    ...additional,
-});
+const projectCommandEnvironment = (additional = {}) => createCleanProcessEnvironment({ overrides: additional });
 const RUNTIME_STARTUP_FAILURE_PATTERN = /container\b.*\b(?:is not ready|starting|unhealthy)|health(?:check)?\b.*\b(?:failed|starting|unhealthy)|out of memory|\boom\b|no space left|resource temporarily unavailable/iu;
 export const classifyManagerFailure = ({ action, output, inferredCategory, }) => {
     if (RUNTIME_STARTUP_FAILURE_PATTERN.test(output) ||
@@ -473,6 +458,7 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
     };
     const startRuntimeApplication = async ({ flags, planOptions, session: commandSession, onRuntimeStarted = () => undefined, }) => {
         const topology = await loadRuntimeTopology(planOptions);
+        throwIfOperationCancelled();
         const application = topology.primary.config.application;
         const readiness = application.readiness;
         if (!readiness) {
@@ -516,6 +502,18 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
             mappings: application.environmentVariables,
             readiness,
         }));
+        try {
+            throwIfOperationCancelled();
+        }
+        catch (error) {
+            try {
+                await applicationSession.stop();
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "Application handoff was cancelled and its owned process could not be stopped.");
+            }
+            throw error;
+        }
         return {
             started: started.runtime,
             verified: verified.runtime,
@@ -527,6 +525,7 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
     };
     const openRuntimeApplication = async ({ flags, planOptions, session: commandSession, onReady = () => undefined, }) => {
         const topology = await loadRuntimeTopology(planOptions);
+        throwIfOperationCancelled();
         let runtimeStarted = false;
         const { result, lifecycle } = await applyRuntimePersistence({
             mode: topology.primary.config.lifecycle.open,

package/dist/src/cli/runtime_planning.mjs

@@ -1,6 +1,7 @@
 import { buildRehearsalPlan, runRehearsalDoctor } from "../runtime/plan.mjs";
 import { inspectRuntimeTopologyCandidates, loadRuntimeTopology, } from "../runtime/topology.mjs";
 import { redactDiagnosticValue } from "../shared/diagnostics.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 export const buildRuntimeStackPlan = async (planOptions) => {
     const topology = await loadRuntimeTopology(planOptions);
@@ -52,6 +53,11 @@ export const buildRuntimeStackPlan = async (planOptions) => {
     };
 };
 export const runRuntimeStackDoctor = async (planOptions) => {
+    const host = await inspectHostPlatform({
+        projectRoot: planOptions.projectRoot ?? process.cwd(),
+    });
+    if (!host.supported)
+        return runRehearsalDoctor(planOptions);
     let topology;
     try {
         topology = await loadRuntimeTopology(planOptions);

package/dist/src/cli/terminal.mjs

@@ -1,6 +1,8 @@
 /** Terminal presentation and prompt primitives shared by guided CLI workflows. */
 import { createInterface } from "node:readline/promises";
 import * as prompts from "@clack/prompts";
+import { hasTerminalInputLease, reassertTerminalInputLease, } from "../shared/terminal_input.mjs";
+import { getOperationCancellationSignal } from "../shared/cancellation.mjs";
 const useColor = (flags) => !flags.plain &&
     process.stdout.isTTY &&
     process.env.NO_COLOR === undefined &&
@@ -54,22 +56,39 @@ export const promptForChoice = async ({ message, options, flags = {}, optionsAlr
     }
 };
 export async function promptForConfirmation(message, flags = {}, { cancelValue = false } = {}) {
+    const signal = getOperationCancellationSignal();
+    if (signal?.aborted)
+        throw signal.reason;
     if (useStyledPrompts(flags)) {
-        const accepted = await prompts.confirm({ message, initialValue: false });
-        return prompts.isCancel(accepted) ? cancelValue : accepted;
+        try {
+            const accepted = await prompts.confirm({
+                message,
+                initialValue: false,
+                ...(signal ? { signal } : {}),
+            });
+            return prompts.isCancel(accepted) ? cancelValue : accepted;
+        }
+        finally {
+            reassertTerminalInputLease(process.stdin);
+        }
     }
     const prompt = createInterface({
         input: process.stdin,
         output: process.stdout,
     });
     try {
-        const answer = (await prompt.question(`${message} (y/N) `))
+        const answer = (await prompt.question(`${message} (y/N) `, { signal }))
             .trim()
             .toLowerCase();
         return answer === "y" || answer === "yes";
     }
     finally {
-        prompt.close();
+        try {
+            prompt.close();
+        }
+        finally {
+            reassertTerminalInputLease(process.stdin);
+        }
     }
 }
 export const promptForPath = async ({ message, defaultValue, optional = false, flags = {}, validate, }) => {
@@ -203,7 +222,7 @@ export const promptForMultipleChoice = async ({ message, options, initialValues
 export const installGuidedExitShortcut = (flags, { beforeExit } = {}) => {
     let exiting = false;
     const exit = () => {
-        if (exiting)
+        if (exiting || hasTerminalInputLease(process.stdin))
             return;
         exiting = true;
         if (process.stdin.isTTY && process.stdin.isRaw)

package/dist/src/project/install_scaffold.mjs

@@ -6,6 +6,7 @@ import { access, readFile, readdir, stat } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { applyRehearsalSetup, planRehearsalSetup } from "./setup.mjs";
 import { findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, } from "./configuration.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
 const PACKAGE_NAME = "@rehearsal-db/core";
 const DEPENDENCY_GROUPS = Object.freeze([
     "dependencies",
@@ -224,6 +225,12 @@ export const createInstalledRehearsalScaffold = async ({ packageRoot, environmen
     });
     if (resolution.status !== "resolved")
         return resolution;
+    const host = await inspectHostPlatform({
+        projectRoot: resolution.projectRoot,
+    });
+    if (!host.supported) {
+        return skip(`${host.detail} ${host.remediation}`.replace(/\.$/u, ""));
+    }
     const detected = await inspectDetectedProject({
         projectRoot: resolution.projectRoot,
     });

package/dist/src/project/project_discovery_metadata.mjs

@@ -7,6 +7,7 @@ import { lstat, readFile, readdir } from "node:fs/promises";
 import { basename, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { CONFIG_FILENAMES } from "./configuration_discovery.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 const MAX_METADATA_BYTES = 1024 * 1024;
 const execFileAsync = promisify(execFile);
 const inside = (root, path) => {
@@ -112,17 +113,14 @@ export const probeContainerEngineWithoutStarting = async () => {
         await execFileAsync("docker", ["info", "--format", "{{.ServerVersion}}"], {
             timeout: 2_000,
             maxBuffer: 64 * 1024,
-            env: Object.fromEntries([
-                "COLIMA_HOME",
-                "DOCKER_CONFIG",
-                "DOCKER_CONTEXT",
-                "DOCKER_HOST",
-                "HOME",
-                "PATH",
-                "USER",
-            ]
-                .map((key) => [key, process.env[key]])
-                .filter((entry) => Boolean(entry[1]))),
+            env: createCleanProcessEnvironment({
+                passthroughKeys: [
+                    "COLIMA_HOME",
+                    "DOCKER_CONFIG",
+                    "DOCKER_CONTEXT",
+                    "DOCKER_HOST",
+                ],
+            }),
         });
         return "running";
     }

package/dist/src/runtime/persistence.mjs

@@ -1,5 +1,5 @@
 /** Explicit, non-destructive persistence policy for project-owned runtimes. */
-import { withOperationCancellationShield } from "../shared/cancellation.mjs";
+import { getOperationCancellationSignal, withOperationCancellationShield, } from "../shared/cancellation.mjs";
 export const shouldStopRuntime = (mode) => mode === "stop-after-run" || mode === "stop-on-application-exit";
 export const applyRuntimePersistence = async ({ mode, operation, stop, canStop = () => true, }) => {
     let result;
@@ -20,8 +20,11 @@ export const applyRuntimePersistence = async ({ mode, operation, stop, canStop =
             stopped = true;
         }
         catch (stopError) {
-            if (operationFailed) {
-                throw new AggregateError([operationError, stopError], "The Rehearsal operation failed and its owned runtime could not be stopped automatically.");
+            // The shield has unwound here. A later interruption must not let the
+            // outer cancellation owner replace a real cleanup fault with clean130.
+            const cancellation = getOperationCancellationSignal();
+            if (operationFailed || cancellation?.aborted) {
+                throw new AggregateError([operationFailed ? operationError : cancellation.reason, stopError], "The Rehearsal operation failed and its owned runtime could not be stopped automatically.");
             }
             throw stopError;
         }

package/dist/src/runtime/plan.mjs

@@ -21,6 +21,8 @@ import { readRehearsalServiceEnvironment } from "./service_environment.mjs";
 import { readBoundRuntimeSanitizationPolicy, validateRuntimeSanitizationPolicy, } from "../baseline/sanitization_policy.mjs";
 import { buildAuthenticationReview, buildBaselineScopeReview, } from "./project_review.mjs";
 import { readVerifiedBaselineShapeEvidence } from "../source/shape_files.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const hasErrorCode = (error, code) => typeof error === "object" &&
     error !== null &&
@@ -29,7 +31,7 @@ const hasErrorCode = (error, code) => typeof error === "object" &&
 const commandAvailable = (command, args = ["--version"]) => {
     const result = spawnSync(command, args, {
         encoding: "utf8",
-        env: Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined ? [] : [[key, process.env[key]]])),
+        env: createCleanProcessEnvironment(),
         stdio: ["ignore", "pipe", "pipe"],
     });
     return {
@@ -378,6 +380,23 @@ export const inspectRehearsalMigrations = async (options = {}) => {
     };
 };
 export const runRehearsalDoctor = async (options = {}) => {
+    const host = await inspectHostPlatform({
+        projectRoot: options.projectRoot ?? process.cwd(),
+    });
+    if (!host.supported) {
+        return {
+            state: "NOT READY",
+            checks: [
+                {
+                    id: "operating-system",
+                    label: "Operating-system support",
+                    status: "fail",
+                    detail: host.detail,
+                    remediation: host.remediation,
+                },
+            ],
+        };
+    }
     let loaded;
     try {
         loaded = await loadRehearsalConfig(options);
@@ -426,12 +445,9 @@ export const runRehearsalDoctor = async (options = {}) => {
             id: "operating-system",
             label: "Operating-system support",
             run: async () => {
-                if (!["darwin", "linux"].includes(process.platform)) {
-                    throw new Error(`${process.platform} is not supported by the version-1 contract.`);
-                }
-                return `${process.platform} is in the supported matrix`;
+                return host.detail;
             },
-            remediation: "Use macOS or Linux; WSL and native Windows require separate proof before support.",
+            remediation: host.remediation,
         },
         {
             id: "package-manager",
@@ -594,9 +610,7 @@ export const runRehearsalDoctor = async (options = {}) => {
                         ], {
                             cwd: projectRoot,
                             encoding: "utf8",
-                            env: Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined
-                                ? []
-                                : [[key, process.env[key]]])),
+                            env: createCleanProcessEnvironment(),
                             stdio: ["ignore", "pipe", "pipe"],
                         });
                         if (status.status !== 0 ||
@@ -614,12 +628,9 @@ export const runRehearsalDoctor = async (options = {}) => {
                     const status = spawnSync("supabase", ["status", "-o", "env", "--workdir", paths.runtimeWorkdir], {
                         cwd: projectRoot,
                         encoding: "utf8",
-                        env: {
-                            ...Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined
-                                ? []
-                                : [[key, process.env[key]]])),
-                            ...serviceEnvironment,
-                        },
+                        env: createCleanProcessEnvironment({
+                            overrides: serviceEnvironment,
+                        }),
                         stdio: ["ignore", "pipe", "pipe"],
                     });
                     if (status.status !== 0 ||

package/dist/src/shared/cancellation.d.mts

@@ -1,6 +1,7 @@
 /** Cooperative cancellation state for one mutating CLI operation. */
 import type { EventEmitter } from "node:events";
 import { RehearsalError } from "./diagnostics.mjs";
+import { type TerminalInput } from "./terminal_input.mjs";
 export declare const OPERATION_CANCELLATION_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGHUP", "SIGTSTP"];
 export type OperationCancellationSignal = (typeof OPERATION_CANCELLATION_SIGNALS)[number];
 type SignalTarget = Pick<EventEmitter, "prependListener" | "removeListener">;
@@ -11,8 +12,9 @@ export declare const getOperationCancellationSignal: () => AbortSignal | undefin
 export declare const throwIfOperationCancelled: () => void;
 export declare const reachOperationCancellationCheckpoint: () => Promise<void>;
 export declare const withOperationCancellationShield: <Value>(task: () => Promise<Value>) => Promise<Value>;
-export declare const runWithOperationCancellation: <Value>({ task, signalTarget, }: {
+export declare const runWithOperationCancellation: <Value>({ task, signalTarget, input, }: {
     task: (signal: AbortSignal) => Promise<Value>;
     signalTarget?: SignalTarget;
+    input?: TerminalInput | null;
 }) => Promise<Value>;
 export {};

package/dist/src/shared/cancellation.mjs

@@ -1,5 +1,6 @@
 /** Cooperative cancellation state for one mutating CLI operation. */
 import { RehearsalError } from "./diagnostics.mjs";
+import { acquireTerminalInput, } from "./terminal_input.mjs";
 export const OPERATION_CANCELLATION_SIGNALS = [
     "SIGINT",
     "SIGTERM",
@@ -8,6 +9,7 @@ export const OPERATION_CANCELLATION_SIGNALS = [
 ];
 const CANCELLABLE_COMMANDS = new Set([
     "migrate",
+    "open",
     "refresh",
     "reset",
     "run",
@@ -48,24 +50,29 @@ export const withOperationCancellationShield = async (task) => {
         shieldDepth -= 1;
     }
 };
-export const runWithOperationCancellation = async ({ task, signalTarget = process, }) => {
+export const runWithOperationCancellation = async ({ task, signalTarget = process, input = process.stdin, }) => {
     if (activeSignal) {
         throw new Error("A cancellable Rehearsal operation is already active.");
     }
     const controller = new AbortController();
     activeSignal = controller.signal;
+    let releaseInput = null;
+    const interrupt = (signal) => {
+        if (!controller.signal.aborted)
+            controller.abort(createOperationCancelledError(signal));
+    };
     const handlers = new Map(OPERATION_CANCELLATION_SIGNALS.map((signal) => [
         signal,
         () => {
-            if (!controller.signal.aborted) {
-                controller.abort(createOperationCancelledError(signal));
-            }
+            if (!releaseInput || releaseInput.isCurrentOwner())
+                interrupt(signal);
         },
     ]));
     for (const [signal, handler] of handlers) {
         signalTarget.prependListener(signal, handler);
     }
     try {
+        releaseInput = acquireTerminalInput(input, interrupt);
         const result = await task(controller.signal);
         throwIfOperationCancelled();
         return result;
@@ -82,5 +89,6 @@ export const runWithOperationCancellation = async ({ task, signalTarget = proces
         }
         activeSignal = undefined;
         shieldDepth = 0;
+        releaseInput?.();
     }
 };

package/dist/src/shared/host_platform.d.mts

@@ -0,0 +1,16 @@
+export declare const NATIVE_WINDOWS_REMEDIATION = "Use WSL2, not a native Windows terminal: run wsl --install -d Ubuntu in PowerShell and confirm version 2 with wsl --list --verbose (upgrade with wsl --set-version Ubuntu 2 if needed). Enable Docker Desktop Settings > Resources > WSL integration for that distribution. Keep the project in its Linux home filesystem (for example ~/projects, not /mnt/c), install a supported Linux Node.js version and project tools there, open it with VS Code Remote - WSL, then rerun rehearsal doctor inside WSL2.";
+export interface HostPlatformInspection {
+    readonly kind: "macos" | "linux" | "wsl2" | "wsl-unverified" | "windows" | "other";
+    readonly supported: boolean;
+    readonly detail: string;
+    readonly remediation: string;
+}
+export interface HostPlatformOptions {
+    readonly projectRoot?: string;
+    readonly platform?: NodeJS.Platform;
+    readonly kernelRelease?: string;
+    readonly readKernelRelease?: () => Promise<string>;
+    readonly inspectFilesystem?: (path: string) => Promise<number>;
+}
+export declare const inspectHostPlatform: ({ projectRoot, platform, kernelRelease, readKernelRelease, inspectFilesystem, }?: HostPlatformOptions) => Promise<HostPlatformInspection>;
+export declare const assertSupportedHostPlatform: (options?: HostPlatformOptions) => Promise<void>;

package/dist/src/shared/host_platform.mjs

@@ -0,0 +1,109 @@
+/** Read-only host capability checks; never substitute environment hints for proof. */
+import { open, statfs } from "node:fs/promises";
+import { release } from "node:os";
+import { RehearsalError } from "./diagnostics.mjs";
+export const NATIVE_WINDOWS_REMEDIATION = "Use WSL2, not a native Windows terminal: run wsl --install -d Ubuntu in PowerShell and confirm version 2 with wsl --list --verbose (upgrade with wsl --set-version Ubuntu 2 if needed). Enable Docker Desktop Settings > Resources > WSL integration for that distribution. Keep the project in its Linux home filesystem (for example ~/projects, not /mnt/c), install a supported Linux Node.js version and project tools there, open it with VS Code Remote - WSL, then rerun rehearsal doctor inside WSL2.";
+const readProcKernelRelease = async () => {
+    const file = await open("/proc/sys/kernel/osrelease", "r");
+    try {
+        const buffer = Buffer.alloc(512);
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await file.close();
+    }
+};
+// WSL's Windows drive mounts do not provide the private modes and atomic symlink
+// contract used by baselines. Accept proven Linux filesystem types, not paths.
+const WSL_POSIX_FILESYSTEM_TYPES = new Set([
+    0xef53, // ext2/ext3/ext4 (WSL2 distribution filesystem)
+    0x58465342, // XFS
+    0x9123683e, // Btrfs
+]);
+export const inspectHostPlatform = async ({ projectRoot = process.cwd(), platform = process.platform, kernelRelease = release(), readKernelRelease = readProcKernelRelease, inspectFilesystem = async (path) => (await statfs(path)).type, } = {}) => {
+    if (platform === "darwin") {
+        return {
+            kind: "macos",
+            supported: true,
+            detail: "macOS is in the supported host matrix; project readiness checks still apply.",
+            remediation: "Resolve the remaining project readiness checks on macOS.",
+        };
+    }
+    if (platform === "win32") {
+        return {
+            kind: "windows",
+            supported: false,
+            detail: "Native Windows runtime and preparation operations are unsupported: POSIX private-file, process-group, and atomic baseline-pointer guarantees have not been established.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    if (platform !== "linux") {
+        return {
+            kind: "other",
+            supported: false,
+            detail: "This operating system is outside the verified macOS/Linux runtime contract.",
+            remediation: "Use a supported macOS or Linux environment. Windows users should use WSL2 with the project on its Linux home filesystem and Docker Desktop WSL integration.",
+        };
+    }
+    let procRelease = "";
+    try {
+        procRelease = (await readKernelRelease()).slice(0, 512);
+    }
+    catch {
+        // os.release() is independent kernel evidence when procfs is unavailable.
+    }
+    const evidence = `${kernelRelease.slice(0, 512)}\n${procRelease}`;
+    if (!/microsoft|\bwsl2?\b/iu.test(evidence)) {
+        return {
+            kind: "linux",
+            supported: true,
+            detail: "Linux is in the supported host matrix; project readiness checks still apply.",
+            remediation: "Resolve the remaining project readiness checks on Linux.",
+        };
+    }
+    if (!/microsoft-standard|\bwsl2\b/iu.test(evidence)) {
+        return {
+            kind: "wsl-unverified",
+            supported: false,
+            detail: "A WSL kernel was detected, but WSL2 kernel capabilities were not proven. WSL1 is unsupported.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    let filesystemType = null;
+    try {
+        filesystemType = await inspectFilesystem(projectRoot);
+    }
+    catch {
+        // Unknown filesystem evidence must not be interpreted as POSIX capability.
+    }
+    if (filesystemType === null ||
+        !WSL_POSIX_FILESYSTEM_TYPES.has(filesystemType)) {
+        return {
+            kind: "wsl2",
+            supported: false,
+            detail: "WSL2 was detected, but this project is not on a proven Linux filesystem. Windows drive mounts and unknown filesystem types are unsupported for private baseline data.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    return {
+        kind: "wsl2",
+        supported: true,
+        detail: "WSL2 kernel and a Linux project filesystem were detected. Run in VS Code Remote - WSL with Linux tools and Docker Desktop WSL integration; the remaining readiness and private-file checks still apply.",
+        remediation: NATIVE_WINDOWS_REMEDIATION,
+    };
+};
+export const assertSupportedHostPlatform = async (options = {}) => {
+    const inspection = await inspectHostPlatform(options);
+    if (inspection.supported)
+        return;
+    throw new RehearsalError({
+        category: "unsafe_environment",
+        code: "HOST_PLATFORM_UNSUPPORTED",
+        message: inspection.detail,
+        expected: "A supported macOS/Linux runtime with its existing safety guarantees.",
+        actual: inspection.kind,
+        refused: "No project configuration, child process, or runtime operation was started.",
+        suggestions: [inspection.remediation],
+    });
+};

package/dist/src/shared/process_environment.d.mts

@@ -8,8 +8,9 @@ export interface CleanProcessEnvironmentOptions {
     inheritedEnvironment?: ProcessEnvironment;
     overrides?: ProcessEnvironment;
     passthroughKeys?: readonly string[];
+    platform?: NodeJS.Platform;
 }
 export declare const isLoopbackUrl: (value: string) => boolean;
 export declare const assertLoopbackUrl: (label: string, value: string) => void;
 export declare const pickEnvironmentVariables: (source: ProcessEnvironment, keys: readonly string[]) => Record<string, string>;
-export declare const createCleanProcessEnvironment: ({ inheritedEnvironment, overrides, passthroughKeys, }?: CleanProcessEnvironmentOptions) => Record<string, string>;
+export declare const createCleanProcessEnvironment: ({ inheritedEnvironment, overrides, passthroughKeys, platform, }?: CleanProcessEnvironmentOptions) => Record<string, string>;

package/dist/src/shared/process_environment.mjs

@@ -21,6 +21,17 @@ const SAFE_SYSTEM_ENVIRONMENT_KEYS = Object.freeze([
     "TEMP",
     "USER",
 ]);
+// Windows resolves environment names case-insensitively. Keep only infrastructure
+// needed to locate executables and user configuration, never ambient credentials.
+const SAFE_WINDOWS_ENVIRONMENT_KEYS = Object.freeze([
+    "SystemRoot",
+    "WINDIR",
+    "ComSpec",
+    "PATHEXT",
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+]);
 const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "::1", "[::1]", "localhost"]);
 export const isLoopbackUrl = (value) => {
     try {
@@ -41,10 +52,41 @@ export const pickEnvironmentVariables = (source, keys) => Object.fromEntries(key
     const value = source[key];
     return value === undefined ? [] : [[key, value]];
 }));
-export const createCleanProcessEnvironment = ({ inheritedEnvironment = process.env, overrides = {}, passthroughKeys = [], } = {}) => ({
-    ...pickEnvironmentVariables(inheritedEnvironment, [
+const pickWindowsEnvironmentVariables = (source, keys) => {
+    const selected = {};
+    const seen = new Set();
+    for (const key of keys) {
+        const normalized = key.toUpperCase();
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        const sourceKey = source[key] !== undefined
+            ? key
+            : Object.keys(source).find((candidate) => candidate.toUpperCase() === normalized &&
+                source[candidate] !== undefined);
+        if (sourceKey !== undefined)
+            selected[key] = source[sourceKey];
+    }
+    return selected;
+};
+export const createCleanProcessEnvironment = ({ inheritedEnvironment = process.env, overrides = {}, passthroughKeys = [], platform = process.platform, } = {}) => {
+    const keys = [
         ...SAFE_SYSTEM_ENVIRONMENT_KEYS,
+        ...(platform === "win32" ? SAFE_WINDOWS_ENVIRONMENT_KEYS : []),
         ...passthroughKeys,
-    ]),
-    ...pickEnvironmentVariables(overrides, Object.keys(overrides)),
-});
+    ];
+    if (platform !== "win32") {
+        return {
+            ...pickEnvironmentVariables(inheritedEnvironment, keys),
+            ...pickEnvironmentVariables(overrides, Object.keys(overrides)),
+        };
+    }
+    const environment = pickWindowsEnvironmentVariables(inheritedEnvironment, keys);
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined)
+            continue;
+        const existing = Object.keys(environment).find((candidate) => candidate.toUpperCase() === key.toUpperCase());
+        environment[existing ?? key] = value;
+    }
+    return environment;
+};

package/dist/src/shared/terminal_input.d.mts

@@ -0,0 +1,25 @@
+/** Own terminal control bytes without suspending the invoking shell's npm job. */
+export interface TerminalInput {
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    readonly readableFlowing?: boolean | null;
+    setRawMode?(enabled: boolean): unknown;
+    resume?(): unknown;
+    pause?(): unknown;
+    prependListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    removeListener(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+}
+export interface TerminalInputLease {
+    (): void;
+    isCurrentOwner(): boolean;
+}
+export declare const hasTerminalInputLease: (input: TerminalInput | null | undefined) => boolean;
+/** Prompt libraries may restore cooked mode; resume only a still-owned lease. */
+export declare const reassertTerminalInputLease: (input: TerminalInput | null | undefined) => void;
+/**
+ * Raw input turns Ctrl+C/Ctrl+Z into bytes instead of kernel signals to the
+ * entire foreground npm/shell job. Signal handlers remain responsible for
+ * externally delivered signals. The final overlapping lease restores only the
+ * mode/flow state this owner acquired; a pre-existing raw terminal stays raw.
+ */
+export declare const acquireTerminalInput: (input: TerminalInput | null | undefined, onInterrupt: (signal: "SIGINT" | "SIGTSTP") => void) => TerminalInputLease;