win-nice 0.1.0 → 0.2.0

package/bin/capt.ps1

@@ -0,0 +1,449 @@
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# win-nice: managed-file
+# Deliberately no param()/[CmdletBinding()]: a declared parameter name (even
+# without a [Parameter()] attribute) can still be ambiguously prefix-matched by
+# flags meant for the wrapped command (e.g. "-c" matching "-Count"). Reading
+# everything from $args sidesteps PowerShell's parameter binder entirely.
+$processorCount = [Environment]::ProcessorCount
+$maxCount = [Math]::Min($processorCount, 63)
+if ($args.Count -lt 2) {
+    Write-Error "usage: capt <thread-count 1-$maxCount> <command> [args...]"
+    exit 1
+}
+$countValue = 0
+if (-not [int]::TryParse($args[0], [ref]$countValue)) {
+    Write-Error "usage: capt <thread-count 1-$maxCount> <command> [args...]"
+    exit 1
+}
+
+# JOBOBJECT_BASIC_LIMIT_INFORMATION.Affinity is a UIntPtr (SIZE_T): it is
+# process-width, so a 32-bit PowerShell process can only express 32 affinity
+# bits. A <thread-count> of 33-63 on a many-core machine passes the machine
+# range check above, then dies inside Run()'s struct initializer with a raw
+# "Arithmetic operation resulted in an overflow." instead of an actionable
+# usage error. Reject it here, capm-style. Pure helper functions rather than
+# inline checks let the Pester suite drive the exact production validation with
+# an injected 32-bit pointer width from a 64-bit process.
+function Get-CaptAffinityBitLimit {
+    param([int]$UIntPtrSize = [UIntPtr]::Size)
+    return $UIntPtrSize * 8
+}
+
+function Get-CaptThreadCountValidation {
+    param(
+        [int]$Count,
+        [int]$MaxCount,
+        [int]$AffinityBitLimit,
+        [int]$ProcessBitWidth = ([UIntPtr]::Size * 8)
+    )
+
+    if ($Count -lt 1 -or $Count -gt $MaxCount) {
+        return [PSCustomObject]@{
+            IsValid = $false
+            ExitCode = 1
+            Message = "usage: capt <thread-count 1-$MaxCount> <command> [args...]"
+        }
+    }
+
+    if ($Count -gt $AffinityBitLimit) {
+        return [PSCustomObject]@{
+            IsValid = $false
+            ExitCode = 1
+            Message = ("capt: <thread-count> ($Count) exceeds the addressable limit " +
+                "for this PowerShell process ($AffinityBitLimit affinity bits, $ProcessBitWidth-bit) - " +
+                "use 64-bit PowerShell for counts above $AffinityBitLimit, or lower <thread-count>. " +
+                "usage: capt <thread-count 1-$MaxCount> <command> [args...]")
+        }
+    }
+
+    return [PSCustomObject]@{
+        IsValid = $true
+        ExitCode = 0
+        Message = $null
+    }
+}
+
+$validation = Get-CaptThreadCountValidation -Count $countValue -MaxCount $maxCount `
+    -AffinityBitLimit (Get-CaptAffinityBitLimit)
+if (-not $validation.IsValid) {
+    Write-Error $validation.Message
+    exit $validation.ExitCode
+}
+$Command = @($args[1..($args.Count - 1)])
+
+# Fallback command line for when the target isn't a directly-launchable .exe (see
+# CaptLauncher.Run below) - re-parsed by cmd.exe (via "cmd.exe /c"), so quoting must
+# neutralize its operators (&|<>^) and not just whitespace - see capc.ps1 for the
+# same logic and its documented "%" limitation.
+$commandLine = ($Command | ForEach-Object {
+    $escaped = $_ -replace '"', '\"'
+    if ($escaped -eq '' -or $escaped -match '[\s"&|<>^]') { '"' + $escaped + '"' } else { $escaped }
+}) -join ' '
+
+$source = @"
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+
+public static class CaptLauncher
+{
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+    struct STARTUPINFO
+    {
+        public int cb;
+        public string lpReserved;
+        public string lpDesktop;
+        public string lpTitle;
+        public int dwX;
+        public int dwY;
+        public int dwXSize;
+        public int dwYSize;
+        public int dwXCountChars;
+        public int dwYCountChars;
+        public int dwFillAttribute;
+        public int dwFlags;
+        public short wShowWindow;
+        public short cbReserved2;
+        public IntPtr lpReserved2;
+        public IntPtr hStdInput;
+        public IntPtr hStdOutput;
+        public IntPtr hStdError;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct PROCESS_INFORMATION
+    {
+        public IntPtr hProcess;
+        public IntPtr hThread;
+        public int dwProcessId;
+        public int dwThreadId;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct JOBOBJECT_BASIC_LIMIT_INFORMATION
+    {
+        public long PerProcessUserTimeLimit;
+        public long PerJobUserTimeLimit;
+        public uint LimitFlags;
+        public UIntPtr MinimumWorkingSetSize;
+        public UIntPtr MaximumWorkingSetSize;
+        public uint ActiveProcessLimit;
+        public UIntPtr Affinity;
+        public uint PriorityClass;
+        public uint SchedulingClass;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct IO_COUNTERS
+    {
+        public ulong ReadOperationCount;
+        public ulong WriteOperationCount;
+        public ulong OtherOperationCount;
+        public ulong ReadTransferCount;
+        public ulong WriteTransferCount;
+        public ulong OtherTransferCount;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    struct JOBOBJECT_EXTENDED_LIMIT_INFORMATION
+    {
+        public JOBOBJECT_BASIC_LIMIT_INFORMATION BasicLimitInformation;
+        public IO_COUNTERS IoInfo;
+        public UIntPtr ProcessMemoryLimit;
+        public UIntPtr JobMemoryLimit;
+        public UIntPtr PeakProcessMemoryUsed;
+        public UIntPtr PeakJobMemoryUsed;
+    }
+
+    [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
+    static extern bool CreateProcess(string lpApplicationName, StringBuilder lpCommandLine,
+        IntPtr lpProcessAttributes, IntPtr lpThreadAttributes, bool bInheritHandles,
+        uint dwCreationFlags, IntPtr lpEnvironment, string lpCurrentDirectory,
+        ref STARTUPINFO lpStartupInfo, out PROCESS_INFORMATION lpProcessInformation);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern IntPtr CreateJobObject(IntPtr lpJobAttributes, string lpName);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool SetInformationJobObject(IntPtr hJob, int JobObjectInfoClass, IntPtr lpJobObjectInfo, uint cbJobObjectInfoLength);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool AssignProcessToJobObject(IntPtr hJob, IntPtr hProcess);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern uint ResumeThread(IntPtr hThread);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern uint WaitForSingleObject(IntPtr hHandle, uint dwMilliseconds);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool GetExitCodeProcess(IntPtr hProcess, out uint lpExitCode);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool TerminateProcess(IntPtr hProcess, uint uExitCode);
+
+    [DllImport("kernel32.dll")]
+    static extern bool CloseHandle(IntPtr hObject);
+
+    const uint CREATE_SUSPENDED = 0x00000004;
+    const int JobObjectExtendedLimitInformation = 9;
+    const uint JOB_OBJECT_LIMIT_AFFINITY = 0x00000010;
+    const uint JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x00002000;
+
+    // Standard MSVCRT/CommandLineToArgvW quoting: safe for a directly-launched .exe's
+    // own argv parsing. No cmd.exe involved on this path, so none of its operator or
+    // "%" expansion semantics apply - this is the safe path, used whenever possible.
+    static string ArgvQuote(string arg)
+    {
+        if (arg.Length > 0 && arg.IndexOfAny(new char[] { ' ', '\t', '\n', '\v', '"' }) < 0)
+            return arg;
+
+        var result = new StringBuilder();
+        result.Append('"');
+        int backslashes = 0;
+        foreach (char c in arg)
+        {
+            if (c == '\\')
+            {
+                backslashes++;
+            }
+            else if (c == '"')
+            {
+                result.Append('\\', backslashes * 2 + 1);
+                result.Append('"');
+                backslashes = 0;
+            }
+            else
+            {
+                if (backslashes > 0) { result.Append('\\', backslashes); backslashes = 0; }
+                result.Append(c);
+            }
+        }
+        if (backslashes > 0) result.Append('\\', backslashes * 2);
+        result.Append('"');
+        return result.ToString();
+    }
+
+    static string BuildArgvCommandLine(string[] argv)
+    {
+        var parts = new string[argv.Length];
+        for (int i = 0; i < argv.Length; i++) parts[i] = ArgvQuote(argv[i]);
+        return string.Join(" ", parts);
+    }
+
+    public static int Run(ulong affinityMask, string[] argv, string cmdExeCommandLine)
+    {
+        IntPtr hJob = CreateJobObject(IntPtr.Zero, null);
+        if (hJob == IntPtr.Zero)
+            throw new InvalidOperationException("CreateJobObject failed: " + Marshal.GetLastWin32Error());
+
+        // Single owner for every handle this method acquires. The finally below closes
+        // hThread/hProcess/hJob - in that order - on EVERY way out: normal return, any
+        // of the InvalidOperationExceptions thrown here, and an unexpected managed
+        // exception (allocation/marshalling failure) between acquisition and use.
+        // hProcess/hThread stay IntPtr.Zero until CreateProcess has actually succeeded,
+        // so each handle is closed exactly once and only if it was really acquired.
+        IntPtr hProcess = IntPtr.Zero;
+        IntPtr hThread = IntPtr.Zero;
+        try
+        {
+            // KILL_ON_JOB_CLOSE: the cleanup in the finally below only runs if this
+            // launcher process survives to execute it. Killed from outside (taskkill
+            // without /T, a crash), nothing in-process ever runs - without this flag
+            // the last job handle dying with the process would leave every process
+            // still assigned to the job running on, untracked and unmanaged. With
+            // it, Windows itself terminates the whole job at that moment.
+            //
+            // A backstop only, never the normal exit mechanism: the last handle
+            // closing terminates every process still assigned to the job FOR ANY
+            // reason, including this wrapper's own orderly close in the finally -
+            // and the wait below only waits on the directly wrapped root process,
+            // so a daemon it spawned and left running can still be in the job at
+            // that point, the root long gone. Killing a daemon on a SUCCESSFUL
+            // exit would break the documented daemon-survival contract (README:
+            // the affinity limit sticks to any daemon the wrapped command leaves
+            // running, for that daemon's whole lifetime), so the success path
+            // below clears this flag first - see capc.ps1 for the full write-up.
+            // Set via the EXTENDED info class: JobObjectBasicLimitInformation
+            // rejects this flag with ERROR_INVALID_PARAMETER.
+            var extInfo = new JOBOBJECT_EXTENDED_LIMIT_INFORMATION
+            {
+                BasicLimitInformation = new JOBOBJECT_BASIC_LIMIT_INFORMATION
+                {
+                    LimitFlags = JOB_OBJECT_LIMIT_AFFINITY | JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE,
+                    Affinity = (UIntPtr)affinityMask
+                }
+            };
+            int size = Marshal.SizeOf(extInfo);
+            IntPtr ptr = Marshal.AllocHGlobal(size);
+            bool ok;
+            try
+            {
+                Marshal.StructureToPtr(extInfo, ptr, false);
+                ok = SetInformationJobObject(hJob, JobObjectExtendedLimitInformation, ptr, (uint)size);
+            }
+            finally
+            {
+                Marshal.FreeHGlobal(ptr);
+            }
+            if (!ok)
+                throw new InvalidOperationException("SetInformationJobObject failed: " + Marshal.GetLastWin32Error());
+
+            var si = new STARTUPINFO();
+            si.cb = Marshal.SizeOf(si);
+            PROCESS_INFORMATION pi = new PROCESS_INFORMATION();
+
+            // See capc.ps1 for why .bat/.cmd targets skip the direct attempt entirely:
+            // CreateProcess silently re-invokes them through cmd.exe on its own, using
+            // unescaped text, instead of failing the way a genuinely missing exe would.
+            bool isBatOrCmd = argv.Length > 0 && (
+                argv[0].EndsWith(".bat", StringComparison.OrdinalIgnoreCase) ||
+                argv[0].EndsWith(".cmd", StringComparison.OrdinalIgnoreCase));
+
+            bool created = false;
+            if (!isBatOrCmd)
+            {
+                var directCommandLine = new StringBuilder(BuildArgvCommandLine(argv));
+                created = CreateProcess(null, directCommandLine, IntPtr.Zero, IntPtr.Zero, true,
+                    CREATE_SUSPENDED, IntPtr.Zero, null, ref si, out pi);
+            }
+
+            if (!created)
+            {
+                // Falling back to cmd.exe /c: a literal "%" in any argument could now
+                // trigger environment-variable expansion (cmd.exe pairs up "%" characters
+                // across the whole command line, even across separate arguments) and
+                // change what actually runs. Fail loudly here instead of silently risking
+                // that - there's no reliable per-character escape for "%" at this level.
+                foreach (var a in argv)
+                {
+                    if (a.IndexOf('%') >= 0)
+                        throw new InvalidOperationException(
+                            "Refusing to run: argument contains '%' and the target needs the cmd.exe " +
+                            "fallback (not a directly-launchable .exe), where '%' can trigger unintended " +
+                            "environment-variable expansion. See README's Argument handling section.");
+                }
+
+                string cmdExe = Environment.SystemDirectory + "\\cmd.exe";
+                // /d: skip HKCU AutoRun (user-writable registry key). /v:off: disable delayed
+                // expansion so "!var!" in an argument can't be expanded. /s plus the extra outer
+                // quote pair: cmd's /S rule strips exactly that outer pair and leaves the rest of
+                // the string untouched - without /S, cmd strips the first and last quote of the
+                // whole line instead, which breaks quoting whenever the target path itself needs
+                // quotes AND another argument is also quoted.
+                var shellCommandLine = new StringBuilder("\"" + cmdExe + "\" /d /v:off /s /c \"" + cmdExeCommandLine + "\"");
+                created = CreateProcess(null, shellCommandLine, IntPtr.Zero, IntPtr.Zero, true,
+                    CREATE_SUSPENDED, IntPtr.Zero, null, ref si, out pi);
+                if (!created)
+                    throw new InvalidOperationException("CreateProcess failed: " + Marshal.GetLastWin32Error());
+            }
+
+            // Ownership of the child's handles transfers here, once CreateProcess has
+            // actually succeeded - from this point the finally below is what closes them.
+            hProcess = pi.hProcess;
+            hThread = pi.hThread;
+
+            if (!AssignProcessToJobObject(hJob, hProcess))
+            {
+                // Can't guarantee the pin - kill instead of letting it run unpinned and orphaned.
+                int err = Marshal.GetLastWin32Error();
+                string message = "AssignProcessToJobObject failed: " + err;
+                // Report if the best-effort kill itself also failed.
+                if (!TerminateProcess(hProcess, 1))
+                    message += "; TerminateProcess also failed: " + Marshal.GetLastWin32Error();
+                throw new InvalidOperationException(message);
+            }
+
+            if (ResumeThread(hThread) == 0xFFFFFFFF)
+            {
+                // Still suspended - an unbounded wait below would hang forever. Kill
+                // it instead of leaving an orphaned, permanently-suspended process.
+                int resumeErr = Marshal.GetLastWin32Error();
+                string message = "ResumeThread failed: " + resumeErr;
+                // Report if the best-effort kill itself also failed.
+                if (!TerminateProcess(hProcess, 1))
+                    message += "; TerminateProcess also failed: " + Marshal.GetLastWin32Error();
+                throw new InvalidOperationException(message);
+            }
+
+            if (WaitForSingleObject(hProcess, 0xFFFFFFFF) == 0xFFFFFFFF)
+            {
+                // The child's actual state is unknown here - don't just report
+                // failure and potentially leave it running unmanaged in the
+                // background. Best-effort kill before giving up.
+                int waitErr = Marshal.GetLastWin32Error();
+                string message = "WaitForSingleObject failed: " + waitErr;
+                // Report if the best-effort kill itself also failed.
+                if (!TerminateProcess(hProcess, 1))
+                    message += "; TerminateProcess also failed: " + Marshal.GetLastWin32Error();
+                throw new InvalidOperationException(message);
+            }
+
+            uint exitCode;
+            if (!GetExitCodeProcess(hProcess, out exitCode))
+                throw new InvalidOperationException("GetExitCodeProcess failed: " + Marshal.GetLastWin32Error());
+
+            // Normal success: the root process finished - release the
+            // kill-on-close backstop so the finally below closes hJob WITHOUT
+            // terminating anything still assigned to the job (the documented
+            // daemon-survival contract: the affinity cap keeps applying to
+            // whatever the command left running, it just outlives this
+            // wrapper's handle). Deliberately best-effort, not a throw: the
+            // wrapped command succeeded, and a failed cleanup syscall must not
+            // turn its real exit code below into a wrapper error - warn on
+            // stderr instead. Same struct and field values as the original
+            // set above, minus the kill-on-close bit, so the daemon keeps its
+            // affinity pin.
+            var releaseInfo = new JOBOBJECT_EXTENDED_LIMIT_INFORMATION
+            {
+                BasicLimitInformation = new JOBOBJECT_BASIC_LIMIT_INFORMATION
+                {
+                    LimitFlags = JOB_OBJECT_LIMIT_AFFINITY,
+                    Affinity = (UIntPtr)affinityMask
+                }
+            };
+            int releaseSize = Marshal.SizeOf(releaseInfo);
+            IntPtr releasePtr = Marshal.AllocHGlobal(releaseSize);
+            bool releaseOk;
+            int releaseErr = 0;
+            try
+            {
+                Marshal.StructureToPtr(releaseInfo, releasePtr, false);
+                releaseOk = SetInformationJobObject(hJob, JobObjectExtendedLimitInformation, releasePtr, (uint)releaseSize);
+                // Capture the Win32 error immediately, before any other call can
+                // overwrite it - every other native failure branch in this file
+                // reports the code for the same diagnosability reason.
+                if (!releaseOk)
+                    releaseErr = Marshal.GetLastWin32Error();
+            }
+            finally
+            {
+                Marshal.FreeHGlobal(releasePtr);
+            }
+            if (!releaseOk)
+                Console.Error.WriteLine("warning: could not release the job's kill-on-close guard (SetInformationJobObject failed with Win32 error " + releaseErr + ") - a still-running background process left by the wrapped command may be terminated when this wrapper exits");
+
+            return (int)exitCode;
+        }
+        finally
+        {
+            // Same order as the code this replaces: thread handle, process handle, job handle.
+            if (hThread != IntPtr.Zero) CloseHandle(hThread);
+            if (hProcess != IntPtr.Zero) CloseHandle(hProcess);
+            if (hJob != IntPtr.Zero) CloseHandle(hJob);
+        }
+    }
+}
+"@
+
+Add-Type -TypeDefinition $source -Language CSharp
+
+# First $countValue logical processors, i.e. threads - not physical cores. See
+# README. Bit-shift, not [Math]::Pow: doubles can't exactly represent 2^63.
+$affinityMask = ([uint64]1 -shl $countValue) - [uint64]1
+try {
+    exit ([CaptLauncher]::Run($affinityMask, [string[]]$Command, $commandLine))
+} catch {
+    Write-Error $_.Exception.InnerException.Message
+    exit 1
+}

package/bin/cx

@@ -1,11 +1,11 @@
-#!/bin/sh
-# SPDX-License-Identifier: MIT OR Apache-2.0
-# win-nice: managed-file
-# Git Bash ignores PATHEXT for bare-name resolution; this shim covers that shell.
-# MSYS2_ARG_CONV_EXCL='*' stops Git Bash/MSYS from rewriting user arguments
-# (e.g. /c, /d, C:\...) into Windows paths before the exec; the shim's own
-# .ps1 path is converted explicitly with cygpath -w so -File gets a Windows path.
-MSYS2_ARG_CONV_EXCL='*'
-export MSYS2_ARG_CONV_EXCL
-script=$(cygpath -w "$(dirname "$0")/cx.ps1" 2>/dev/null) || script="$(dirname "$0")/cx.ps1"
-exec powershell -NoProfile -ExecutionPolicy Bypass -File "$script" "$@"
+#!/bin/sh
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# win-nice: managed-file
+# Git Bash ignores PATHEXT for bare-name resolution; this shim covers that shell.
+# MSYS2_ARG_CONV_EXCL='*' stops Git Bash/MSYS from rewriting user arguments
+# (e.g. /c, /d, C:\...) into Windows paths before the exec; the shim's own
+# .ps1 path is converted explicitly with cygpath -w so -File gets a Windows path.
+MSYS2_ARG_CONV_EXCL='*'
+export MSYS2_ARG_CONV_EXCL
+script=$(cygpath -w "$(dirname "$0")/cx.ps1" 2>/dev/null) || script="$(dirname "$0")/cx.ps1"
+exec powershell -NoProfile -ExecutionPolicy Bypass -File "$script" "$@"

package/bin/cx.bat

@@ -1,7 +1,7 @@
 @echo off
 :: SPDX-License-Identifier: MIT OR Apache-2.0
 :: win-nice: managed-file
-:: A literal "%" in any argument gets corrupted here - see cap.bat for why (a
+:: A literal "%" in any argument gets corrupted here - see capc.bat for why (a
 :: cmd.exe batch-parameter quirk, not fixable from inside a .bat). Every other
 :: cmd.exe metacharacter (&|<>^) survives this hop untouched. Invoking "cx" bare
 :: from an actual PowerShell session skips this file (cx.ps1 preferred).

package/bin/cx.ps1

@@ -1,12 +1,12 @@
 # SPDX-License-Identifier: MIT OR Apache-2.0
 # win-nice: managed-file
 # No param(): $args sidesteps PowerShell's parameter binder entirely - see
-# cap.ps1 for why that matters (codex's own flags shouldn't get bound here).
+# capc.ps1 for why that matters (codex's own flags shouldn't get bound here).
 $Command = @('codex', '--dangerously-bypass-approvals-and-sandbox') + @($args)
 
 # Fallback command line for when codex isn't a directly-launchable .exe (it's
 # typically an npm-installed .cmd shim on Windows) - see CxLauncher.Run below and
-# cap.ps1 for the same logic and its documented "%" limitation. cx.bat has its own,
+# capc.ps1 for the same logic and its documented "%" limitation. cx.bat has its own,
 # more severe "%" caveat (see there) that applies before this script ever runs.
 $commandLine = ($Command | ForEach-Object {
     $escaped = $_ -replace '"', '\"'
@@ -64,6 +64,9 @@ public static class CxLauncher
     [DllImport("kernel32.dll", SetLastError = true)]
     static extern bool GetExitCodeProcess(IntPtr hProcess, out uint lpExitCode);
 
+    [DllImport("kernel32.dll", SetLastError = true)]
+    static extern bool TerminateProcess(IntPtr hProcess, uint uExitCode);
+
     [DllImport("kernel32.dll")]
     static extern bool CloseHandle(IntPtr hObject);
 
@@ -114,7 +117,7 @@ public static class CxLauncher
         si.cb = Marshal.SizeOf(si);
         PROCESS_INFORMATION pi = new PROCESS_INFORMATION();
 
-        // See cap.ps1 for why .bat/.cmd targets skip the direct attempt entirely:
+        // See capc.ps1 for why .bat/.cmd targets skip the direct attempt entirely:
         // CreateProcess silently re-invokes them through cmd.exe on its own, using
         // unescaped text, instead of failing the way a genuinely missing exe would.
         // A bare name like "codex" (typically an npm .cmd shim on Windows) isn't
@@ -139,6 +142,7 @@ public static class CxLauncher
             // across the whole command line, even across separate arguments) and
             // change what actually runs. Fail loudly here instead of silently risking
             // that - there's no reliable per-character escape for "%" at this level.
+            // No handle is held at this point, so this throw has nothing to clean up.
             foreach (var a in argv)
             {
                 if (a.IndexOf('%') >= 0)
@@ -162,15 +166,39 @@ public static class CxLauncher
                 throw new InvalidOperationException("CreateProcess failed: " + Marshal.GetLastWin32Error());
         }
 
-        WaitForSingleObject(pi.hProcess, 0xFFFFFFFF);
-
-        uint exitCode;
-        GetExitCodeProcess(pi.hProcess, out exitCode);
+        // Ownership of the child's handles starts here - CreateProcess has succeeded, so
+        // both are valid, and the finally below closes each of them exactly once on every
+        // way out: normal return, a thrown InvalidOperationException, or an unexpected
+        // managed exception.
+        IntPtr hProcess = pi.hProcess;
+        IntPtr hThread = pi.hThread;
+        try
+        {
+            if (WaitForSingleObject(hProcess, 0xFFFFFFFF) == 0xFFFFFFFF)
+            {
+                // The child's actual state is unknown here - don't just report
+                // failure and potentially leave it running unmanaged in the
+                // background. Best-effort kill before giving up.
+                int waitErr = Marshal.GetLastWin32Error();
+                string message = "WaitForSingleObject failed: " + waitErr;
+                // Report if the best-effort kill itself also failed.
+                if (!TerminateProcess(hProcess, 1))
+                    message += "; TerminateProcess also failed: " + Marshal.GetLastWin32Error();
+                throw new InvalidOperationException(message);
+            }
 
-        CloseHandle(pi.hThread);
-        CloseHandle(pi.hProcess);
+            uint exitCode;
+            if (!GetExitCodeProcess(hProcess, out exitCode))
+                throw new InvalidOperationException("GetExitCodeProcess failed: " + Marshal.GetLastWin32Error());
 
-        return (int)exitCode;
+            return (int)exitCode;
+        }
+        finally
+        {
+            // Same order as the code this replaces: thread handle, then process handle.
+            CloseHandle(hThread);
+            CloseHandle(hProcess);
+        }
     }
 }
 "@

package/bin/cy

@@ -1,11 +1,11 @@
-#!/bin/sh
-# SPDX-License-Identifier: MIT OR Apache-2.0
-# win-nice: managed-file
-# Git Bash ignores PATHEXT for bare-name resolution; this shim covers that shell.
-# MSYS2_ARG_CONV_EXCL='*' stops Git Bash/MSYS from rewriting user arguments
-# (e.g. /c, /d, C:\...) into Windows paths before the exec; the shim's own
-# .ps1 path is converted explicitly with cygpath -w so -File gets a Windows path.
-MSYS2_ARG_CONV_EXCL='*'
-export MSYS2_ARG_CONV_EXCL
-script=$(cygpath -w "$(dirname "$0")/cy.ps1" 2>/dev/null) || script="$(dirname "$0")/cy.ps1"
-exec powershell -NoProfile -ExecutionPolicy Bypass -File "$script" "$@"
+#!/bin/sh
+# SPDX-License-Identifier: MIT OR Apache-2.0
+# win-nice: managed-file
+# Git Bash ignores PATHEXT for bare-name resolution; this shim covers that shell.
+# MSYS2_ARG_CONV_EXCL='*' stops Git Bash/MSYS from rewriting user arguments
+# (e.g. /c, /d, C:\...) into Windows paths before the exec; the shim's own
+# .ps1 path is converted explicitly with cygpath -w so -File gets a Windows path.
+MSYS2_ARG_CONV_EXCL='*'
+export MSYS2_ARG_CONV_EXCL
+script=$(cygpath -w "$(dirname "$0")/cy.ps1" 2>/dev/null) || script="$(dirname "$0")/cy.ps1"
+exec powershell -NoProfile -ExecutionPolicy Bypass -File "$script" "$@"

package/bin/cy.bat

@@ -1,7 +1,7 @@
 @echo off
 :: SPDX-License-Identifier: MIT OR Apache-2.0
 :: win-nice: managed-file
-:: A literal "%" in any argument gets corrupted here - see cap.bat for why (a
+:: A literal "%" in any argument gets corrupted here - see capc.bat for why (a
 :: cmd.exe batch-parameter quirk, not fixable from inside a .bat). Every other
 :: cmd.exe metacharacter (&|<>^) survives this hop untouched. Invoking "cy" bare
 :: from an actual PowerShell session skips this file (cy.ps1 preferred).